1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2 @c 2000, 2001, 2002 Free Software Foundation, Inc.
3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi.
8 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997,
9 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
11 Permission is granted to copy, distribute and/or modify this document
12 under the terms of the GNU Free Documentation License, Version 1.1 or
13 any later version published by the Free Software Foundation; with the
14 Invariant Sections being ``GNU General Public License'' and ``Funding
15 Free Software'', the Front-Cover texts being (a) (see below), and with
16 the Back-Cover Texts being (b) (see below). A copy of the license is
17 included in the gfdl(7) man page.
19 (a) The FSF's Front-Cover Text is:
23 (b) The FSF's Back-Cover Text is:
25 You have freedom to copy and modify this GNU Manual, like GNU
26 software. Copies published by the Free Software Foundation raise
27 funds for GNU development.
29 @c Set file name and title for the man page.
31 @settitle GNU project C and C++ compiler
33 gcc [@option{-c}|@option{-S}|@option{-E}] [@option{-std=}@var{standard}]
34 [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
35 [@option{-W}@var{warn}@dots{}] [@option{-pedantic}]
36 [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
37 [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
38 [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
39 [@option{-o} @var{outfile}] @var{infile}@dots{}
41 Only the most useful options are listed here; see below for the
42 remainder. @samp{g++} accepts mostly the same options as @samp{gcc}.
45 gpl(7), gfdl(7), fsf-funding(7),
46 cpp(1), gcov(1), g77(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1)
47 and the Info entries for @file{gcc}, @file{cpp}, @file{g77}, @file{as},
48 @file{ld}, @file{binutils} and @file{gdb}.
51 For instructions on reporting bugs, see
52 @w{@uref{http://gcc.gnu.org/bugs.html}}. Use of the @command{gccbug}
53 script to report bugs is recommended.
56 See the Info entry for @command{gcc}, or
57 @w{@uref{http://gcc.gnu.org/onlinedocs/gcc/Contributors.html}},
58 for contributors to GCC@.
63 @chapter GCC Command Options
64 @cindex GCC command options
65 @cindex command options
66 @cindex options, GCC command
68 @c man begin DESCRIPTION
70 When you invoke GCC, it normally does preprocessing, compilation,
71 assembly and linking. The ``overall options'' allow you to stop this
72 process at an intermediate stage. For example, the @option{-c} option
73 says not to run the linker. Then the output consists of object files
74 output by the assembler.
76 Other options are passed on to one stage of processing. Some options
77 control the preprocessor and others the compiler itself. Yet other
78 options control the assembler and linker; most of these are not
79 documented here, since you rarely need to use any of them.
81 @cindex C compilation options
82 Most of the command line options that you can use with GCC are useful
83 for C programs; when an option is only useful with another language
84 (usually C++), the explanation says so explicitly. If the description
85 for a particular option does not mention a source language, you can use
86 that option with all supported languages.
88 @cindex C++ compilation options
89 @xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
90 options for compiling C++ programs.
92 @cindex grouping options
93 @cindex options, grouping
94 The @command{gcc} program accepts options and file names as operands. Many
95 options have multi-letter names; therefore multiple single-letter options
96 may @emph{not} be grouped: @option{-dr} is very different from @w{@samp{-d
99 @cindex order of options
100 @cindex options, order
101 You can mix options and other arguments. For the most part, the order
102 you use doesn't matter. Order does matter when you use several options
103 of the same kind; for example, if you specify @option{-L} more than once,
104 the directories are searched in the order specified.
106 Many options have long names starting with @samp{-f} or with
107 @samp{-W}---for example, @option{-fforce-mem},
108 @option{-fstrength-reduce}, @option{-Wformat} and so on. Most of
109 these have both positive and negative forms; the negative form of
110 @option{-ffoo} would be @option{-fno-foo}. This manual documents
111 only one of these two forms, whichever one is not the default.
115 @xref{Option Index}, for an index to GCC's options.
118 * Option Summary:: Brief list of all options, without explanations.
119 * Overall Options:: Controlling the kind of output:
120 an executable, object files, assembler files,
121 or preprocessed source.
122 * Invoking G++:: Compiling C++ programs.
123 * C Dialect Options:: Controlling the variant of C language compiled.
124 * C++ Dialect Options:: Variations on C++.
125 * Objective-C Dialect Options:: Variations on Objective-C.
126 * Language Independent Options:: Controlling how diagnostics should be
128 * Warning Options:: How picky should the compiler be?
129 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
130 * Optimize Options:: How much optimization?
131 * Preprocessor Options:: Controlling header files and macro definitions.
132 Also, getting dependency information for Make.
133 * Assembler Options:: Passing options to the assembler.
134 * Link Options:: Specifying libraries and so on.
135 * Directory Options:: Where to find header files and libraries.
136 Where to find the compiler executable files.
137 * Spec Files:: How to pass switches to sub-processes.
138 * Target Options:: Running a cross-compiler, or an old version of GCC.
139 * Submodel Options:: Specifying minor hardware or convention variations,
140 such as 68010 vs 68020.
141 * Code Gen Options:: Specifying conventions for function calls, data layout
143 * Environment Variables:: Env vars that affect GCC.
144 * Running Protoize:: Automatically adding or removing function prototypes.
150 @section Option Summary
152 Here is a summary of all the options, grouped by type. Explanations are
153 in the following sections.
156 @item Overall Options
157 @xref{Overall Options,,Options Controlling the Kind of Output}.
159 -c -S -E -o @var{file} -pipe -pass-exit-codes -x @var{language} @gol
160 -v --target-help --help}
162 @item C Language Options
163 @xref{C Dialect Options,,Options Controlling C Dialect}.
165 -ansi -std=@var{standard} -aux-info @var{filename} @gol
166 -fno-asm -fno-builtin -fno-builtin-@var{function} @gol
167 -fhosted -ffreestanding @gol
168 -trigraphs -traditional -traditional-cpp @gol
169 -fallow-single-precision -fcond-mismatch @gol
170 -fsigned-bitfields -fsigned-char @gol
171 -funsigned-bitfields -funsigned-char @gol
172 -fwritable-strings -fshort-wchar}
174 @item C++ Language Options
175 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
177 -fno-access-control -fcheck-new -fconserve-space @gol
178 -fno-const-strings -fdollars-in-identifiers @gol
179 -fno-elide-constructors @gol
180 -fno-enforce-eh-specs -fexternal-templates @gol
181 -falt-external-templates @gol
182 -ffor-scope -fno-for-scope -fno-gnu-keywords @gol
183 -fno-implicit-templates @gol
184 -fno-implicit-inline-templates @gol
185 -fno-implement-inlines -fms-extensions @gol
186 -fno-nonansi-builtins -fno-operator-names @gol
187 -fno-optional-diags -fpermissive @gol
188 -frepo -fno-rtti -fstats -ftemplate-depth-@var{n} @gol
189 -fuse-cxa-atexit -fvtable-gc -fno-weak -nostdinc++ @gol
190 -fno-default-inline -Wctor-dtor-privacy @gol
191 -Wnon-virtual-dtor -Wreorder @gol
192 -Weffc++ -Wno-deprecated @gol
193 -Wno-non-template-friend -Wold-style-cast @gol
194 -Woverloaded-virtual -Wno-pmf-conversions @gol
195 -Wsign-promo -Wsynth}
197 @item Objective-C Language Options
198 @xref{Objective-C Dialect Options,,Options Controlling Objective-C Dialect}.
200 -fconstant-string-class=@var{class-name} @gol
201 -fgnu-runtime -fnext-runtime -gen-decls @gol
202 -Wno-protocol -Wselector}
204 @item Language Independent Options
205 @xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}.
207 -fmessage-length=@var{n} @gol
208 -fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]}}
210 @item Warning Options
211 @xref{Warning Options,,Options to Request or Suppress Warnings}.
213 -fsyntax-only -pedantic -pedantic-errors @gol
214 -w -W -Wall -Waggregate-return @gol
215 -Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment @gol
216 -Wconversion -Wno-deprecated-declarations @gol
217 -Wdisabled-optimization -Wno-div-by-zero -Werror @gol
218 -Wfloat-equal -Wformat -Wformat=2 @gol
219 -Wformat-nonliteral -Wformat-security @gol
220 -Wimplicit -Wimplicit-int @gol
221 -Wimplicit-function-declaration @gol
222 -Werror-implicit-function-declaration @gol
223 -Wimport -Winline @gol
224 -Wlarger-than-@var{len} -Wlong-long @gol
225 -Wmain -Wmissing-braces -Wmissing-declarations @gol
226 -Wmissing-format-attribute -Wmissing-noreturn @gol
227 -Wno-multichar -Wno-format-extra-args -Wno-format-y2k @gol
228 -Wno-import -Wpacked -Wpadded @gol
229 -Wparentheses -Wpointer-arith -Wredundant-decls @gol
230 -Wreturn-type -Wsequence-point -Wshadow @gol
231 -Wsign-compare -Wswitch -Wsystem-headers @gol
232 -Wtrigraphs -Wundef -Wuninitialized @gol
233 -Wunknown-pragmas -Wunreachable-code @gol
234 -Wunused -Wunused-function -Wunused-label -Wunused-parameter @gol
235 -Wunused-value -Wunused-variable -Wwrite-strings}
237 @item C-only Warning Options
239 -Wbad-function-cast -Wmissing-prototypes -Wnested-externs @gol
240 -Wstrict-prototypes -Wtraditional}
242 @item Debugging Options
243 @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
245 -d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
246 -fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} @gol
247 -fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
248 -fdump-tree-original@r{[}-@var{n}@r{]} -fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
249 -fdump-tree-inlined@r{[}-@var{n}@r{]} @gol
251 -fprofile-arcs -ftest-coverage -ftime-report @gol
252 -g -g@var{level} -gcoff -gdwarf -gdwarf-1 -gdwarf-1+ -gdwarf-2 @gol
253 -ggdb -gstabs -gstabs+ -gvms -gxcoff -gxcoff+ @gol
254 -p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol
255 -print-multi-directory -print-multi-lib @gol
256 -print-prog-name=@var{program} -print-search-dirs -Q @gol
259 @item Optimization Options
260 @xref{Optimize Options,,Options that Control Optimization}.
262 -falign-functions=@var{n} -falign-jumps=@var{n} @gol
263 -falign-labels=@var{n} -falign-loops=@var{n} @gol
264 -fbranch-probabilities -fcaller-saves -fcprop-registers @gol
265 -fcse-follow-jumps -fcse-skip-blocks -fdata-sections @gol
266 -fdelayed-branch -fdelete-null-pointer-checks @gol
267 -fexpensive-optimizations -ffast-math -ffloat-store @gol
268 -fforce-addr -fforce-mem -ffunction-sections @gol
269 -fgcse -fgcse-lm -fgcse-sm @gol
270 -finline-functions -finline-limit=@var{n} -fkeep-inline-functions @gol
271 -fkeep-static-consts -fmerge-constants -fmerge-all-constants @gol
272 -fmove-all-movables -fno-default-inline -fno-defer-pop @gol
273 -fno-function-cse -fno-guess-branch-probability @gol
274 -fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol
275 -funsafe-math-optimizations -fno-trapping-math @gol
276 -fno-zero-initialized-in-bss @gol
277 -fomit-frame-pointer -foptimize-register-move @gol
278 -foptimize-sibling-calls -fprefetch-loop-arrays @gol
279 -freduce-all-givs -fregmove -frename-registers @gol
280 -frerun-cse-after-loop -frerun-loop-opt @gol
281 -fschedule-insns -fschedule-insns2 @gol
282 -fsingle-precision-constant -fssa -fssa-ccp -fssa-dce @gol
283 -fstrength-reduce -fstrict-aliasing -fthread-jumps -ftrapv @gol
284 -funroll-all-loops -funroll-loops @gol
285 --param @var{name}=@var{value}
286 -O -O0 -O1 -O2 -O3 -Os}
288 @item Preprocessor Options
289 @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
291 -$ -A@var{question}=@var{answer} -A-@var{question}@r{[}=@var{answer}@r{]} @gol
292 -C -dD -dI -dM -dN @gol
293 -D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol
294 -idirafter @var{dir} @gol
295 -include @var{file} -imacros @var{file} @gol
296 -iprefix @var{file} -iwithprefix @var{dir} @gol
297 -iwithprefixbefore @var{dir} -isystem @var{dir} @gol
298 -M -MM -MF -MG -MP -MQ -MT -nostdinc -P -remap @gol
299 -trigraphs -undef -U@var{macro} -Wp,@var{option}}
301 @item Assembler Option
302 @xref{Assembler Options,,Passing Options to the Assembler}.
307 @xref{Link Options,,Options for Linking}.
309 @var{object-file-name} -l@var{library} @gol
310 -nostartfiles -nodefaultlibs -nostdlib @gol
311 -s -static -static-libgcc -shared -shared-libgcc -symbolic @gol
312 -Wl,@var{option} -Xlinker @var{option} @gol
315 @item Directory Options
316 @xref{Directory Options,,Options for Directory Search}.
318 -B@var{prefix} -I@var{dir} -I- -L@var{dir} -specs=@var{file}}
321 @c I wrote this xref this way to avoid overfull hbox. -- rms
322 @xref{Target Options}.
324 -b @var{machine} -V @var{version}}
326 @item Machine Dependent Options
327 @xref{Submodel Options,,Hardware Models and Configurations}.
329 @emph{M680x0 Options}
331 -m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol
332 -m68060 -mcpu32 -m5200 -m68881 -mbitfield -mc68000 -mc68020 @gol
333 -mfpa -mnobitfield -mrtd -mshort -msoft-float -mpcrel @gol
334 -malign-int -mstrict-align}
336 @emph{M68hc1x Options}
338 -m6811 -m6812 -m68hc11 -m68hc12 @gol
339 -mauto-incdec -mshort -msoft-reg-count=@var{count}}
347 -mcpu=@var{cpu-type} @gol
348 -mtune=@var{cpu-type} @gol
349 -mcmodel=@var{code-model} @gol
351 -mapp-regs -mbroken-saverestore -mcypress @gol
352 -mepilogue -mfaster-structs -mflat @gol
353 -mfpu -mhard-float -mhard-quad-float @gol
354 -mimpure-text -mlive-g0 -mno-app-regs @gol
355 -mno-epilogue -mno-faster-structs -mno-flat -mno-fpu @gol
356 -mno-impure-text -mno-stack-bias -mno-unaligned-doubles @gol
357 -msoft-float -msoft-quad-float -msparclite -mstack-bias @gol
358 -msupersparc -munaligned-doubles -mv8}
360 @emph{Convex Options}
362 -mc1 -mc2 -mc32 -mc34 -mc38 @gol
363 -margcount -mnoargcount @gol
364 -mlong32 -mlong64 @gol
365 -mvolatile-cache -mvolatile-nocache}
367 @emph{AMD29K Options}
369 -m29000 -m29050 -mbw -mnbw -mdw -mndw @gol
370 -mlarge -mnormal -msmall @gol
371 -mkernel-registers -mno-reuse-arg-regs @gol
372 -mno-stack-check -mno-storem-bug @gol
373 -mreuse-arg-regs -msoft-float -mstack-check @gol
374 -mstorem-bug -muser-registers}
378 -mapcs-frame -mno-apcs-frame @gol
379 -mapcs-26 -mapcs-32 @gol
380 -mapcs-stack-check -mno-apcs-stack-check @gol
381 -mapcs-float -mno-apcs-float @gol
382 -mapcs-reentrant -mno-apcs-reentrant @gol
383 -msched-prolog -mno-sched-prolog @gol
384 -mlittle-endian -mbig-endian -mwords-little-endian @gol
385 -malignment-traps -mno-alignment-traps @gol
386 -msoft-float -mhard-float -mfpe @gol
387 -mthumb-interwork -mno-thumb-interwork @gol
388 -mcpu=@var{name} -march=@var{name} -mfpe=@var{name} @gol
389 -mstructure-size-boundary=@var{n} @gol
390 -mbsd -mxopen -mno-symrename @gol
391 -mabort-on-noreturn @gol
392 -mlong-calls -mno-long-calls @gol
393 -msingle-pic-base -mno-single-pic-base @gol
394 -mpic-register=@var{reg} @gol
395 -mnop-fun-dllimport @gol
396 -mpoke-function-name @gol
398 -mtpcs-frame -mtpcs-leaf-frame @gol
399 -mcaller-super-interworking -mcallee-super-interworking }
401 @emph{MN10200 Options}
405 @emph{MN10300 Options}
407 -mmult-bug -mno-mult-bug @gol
408 -mam33 -mno-am33 @gol
411 @emph{M32R/D Options}
413 -m32rx -m32r -mcode-model=@var{model-type} -msdata=@var{sdata-type} @gol
418 -m88000 -m88100 -m88110 -mbig-pic @gol
419 -mcheck-zero-division -mhandle-large-shift @gol
420 -midentify-revision -mno-check-zero-division @gol
421 -mno-ocs-debug-info -mno-ocs-frame-position @gol
422 -mno-optimize-arg-area -mno-serialize-volatile @gol
423 -mno-underscores -mocs-debug-info @gol
424 -mocs-frame-position -moptimize-arg-area @gol
425 -mserialize-volatile -mshort-data-@var{num} -msvr3 @gol
426 -msvr4 -mtrap-large-shift -muse-div-instruction @gol
427 -mversion-03.00 -mwarn-passed-structs}
429 @emph{RS/6000 and PowerPC Options}
431 -mcpu=@var{cpu-type} @gol
432 -mtune=@var{cpu-type} @gol
433 -mpower -mno-power -mpower2 -mno-power2 @gol
434 -mpowerpc -mpowerpc64 -mno-powerpc @gol
435 -maltivec -mno-altivec @gol
436 -mpowerpc-gpopt -mno-powerpc-gpopt @gol
437 -mpowerpc-gfxopt -mno-powerpc-gfxopt @gol
438 -mnew-mnemonics -mold-mnemonics @gol
439 -mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc @gol
440 -m64 -m32 -mxl-call -mno-xl-call -mpe @gol
441 -msoft-float -mhard-float -mmultiple -mno-multiple @gol
442 -mstring -mno-string -mupdate -mno-update @gol
443 -mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol
444 -mstrict-align -mno-strict-align -mrelocatable @gol
445 -mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol
446 -mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol
447 -mcall-aix -mcall-sysv -mcall-netbsd @gol
448 -maix-struct-return -msvr4-struct-return
450 -mprototype -mno-prototype @gol
451 -msim -mmvme -mads -myellowknife -memb -msdata @gol
452 -msdata=@var{opt} -mvxworks -G @var{num} -pthread}
456 -mcall-lib-mul -mfp-arg-in-fpregs -mfp-arg-in-gregs @gol
457 -mfull-fp-blocks -mhc-struct-return -min-line-mul @gol
458 -mminimum-fp-blocks -mnohc-struct-return}
462 -mabicalls -march=@var{cpu-type} -mtune=@var{cpu=type} @gol
463 -mcpu=@var{cpu-type} -membedded-data -muninit-const-in-rodata @gol
464 -membedded-pic -mfp32 -mfp64 -mfused-madd -mno-fused-madd @gol
465 -mgas -mgp32 -mgp64 @gol
466 -mgpopt -mhalf-pic -mhard-float -mint64 -mips1 @gol
467 -mips2 -mips3 -mips4 -mlong64 -mlong32 -mlong-calls -mmemcpy @gol
468 -mmips-as -mmips-tfile -mno-abicalls @gol
469 -mno-embedded-data -mno-uninit-const-in-rodata @gol
470 -mno-embedded-pic -mno-gpopt -mno-long-calls @gol
471 -mno-memcpy -mno-mips-tfile -mno-rnames -mno-stats @gol
472 -mrnames -msoft-float @gol
473 -m4650 -msingle-float -mmad @gol
474 -mstats -EL -EB -G @var{num} -nocpp @gol
475 -mabi=32 -mabi=n32 -mabi=64 -mabi=eabi @gol
476 -mfix7000 -mno-crt0 -mflush-func=@var{func} -mno-flush-func}
478 @emph{i386 and x86-64 Options}
480 -mcpu=@var{cpu-type} -march=@var{cpu-type} -mfpmath=@var{unit} @gol
481 -masm=@var{dialect} -mno-fancy-math-387 @gol
482 -mno-fp-ret-in-387 -msoft-float -msvr3-shlib @gol
483 -mno-wide-multiply -mrtd -malign-double @gol
484 -mpreferred-stack-boundary=@var{num} @gol
485 -mmmx -msse -msse2 -msse-math -m3dnow @gol
486 -mthreads -mno-align-stringops -minline-all-stringops @gol
487 -mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol
488 -m96bit-long-double -mregparm=@var{num} -momit-leaf-frame-pointer @gol
494 -march=@var{architecture-type} @gol
495 -mbig-switch -mdisable-fpregs -mdisable-indexing @gol
496 -mfast-indirect-calls -mgas -mjump-in-delay @gol
497 -mlong-load-store -mno-big-switch -mno-disable-fpregs @gol
498 -mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol
499 -mno-jump-in-delay -mno-long-load-store @gol
500 -mno-portable-runtime -mno-soft-float @gol
501 -mno-space-regs -msoft-float -mpa-risc-1-0 @gol
502 -mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime @gol
503 -mschedule=@var{cpu-type} -mspace-regs}
505 @emph{Intel 960 Options}
507 -m@var{cpu-type} -masm-compat -mclean-linkage @gol
508 -mcode-align -mcomplex-addr -mleaf-procedures @gol
509 -mic-compat -mic2.0-compat -mic3.0-compat @gol
510 -mintel-asm -mno-clean-linkage -mno-code-align @gol
511 -mno-complex-addr -mno-leaf-procedures @gol
512 -mno-old-align -mno-strict-align -mno-tail-call @gol
513 -mnumerics -mold-align -msoft-float -mstrict-align @gol
516 @emph{DEC Alpha Options}
518 -mno-fp-regs -msoft-float -malpha-as -mgas @gol
519 -mieee -mieee-with-inexact -mieee-conformant @gol
520 -mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} @gol
521 -mtrap-precision=@var{mode} -mbuild-constants @gol
522 -mcpu=@var{cpu-type} -mtune=@var{cpu-type} @gol
523 -mbwx -mmax -mfix -mcix @gol
524 -mfloat-vax -mfloat-ieee @gol
525 -mexplicit-relocs -msmall-data -mlarge-data @gol
526 -mmemory-latency=@var{time}}
528 @emph{DEC Alpha/VMS Options}
532 @emph{Clipper Options}
536 @emph{H8/300 Options}
538 -mrelax -mh -ms -mint32 -malign-300}
542 -m1 -m2 -m3 -m3e @gol
543 -m4-nofpu -m4-single-only -m4-single -m4 @gol
544 -m5-64media -m5-64media-nofpu @gol
545 -m5-32media -m5-32media-nofpu @gol
546 -m5-compact -m5-compact-nofpu @gol
547 -mb -ml -mdalign -mrelax @gol
548 -mbigtable -mfmovd -mhitachi -mnomacsave @gol
549 -mieee -misize -mpadstruct -mspace @gol
550 -mprefergot -musermode}
552 @emph{System V Options}
554 -Qy -Qn -YP,@var{paths} -Ym,@var{dir}}
559 -mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text-section} @gol
560 -mdata=@var{data-section} -mrodata=@var{readonly-data-section}}
562 @emph{TMS320C3x/C4x Options}
564 -mcpu=@var{cpu} -mbig -msmall -mregparm -mmemparm @gol
565 -mfast-fix -mmpyi -mbk -mti -mdp-isr-reload @gol
566 -mrpts=@var{count} -mrptb -mdb -mloop-unsigned @gol
567 -mparallel-insns -mparallel-mpy -mpreserve-float}
571 -mlong-calls -mno-long-calls -mep -mno-ep @gol
572 -mprolog-function -mno-prolog-function -mspace @gol
573 -mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol
578 -m32032 -m32332 -m32532 -m32081 -m32381 @gol
579 -mmult-add -mnomult-add -msoft-float -mrtd -mnortd @gol
580 -mregparam -mnoregparam -msb -mnosb @gol
581 -mbitfield -mnobitfield -mhimem -mnohimem}
585 -mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts @gol
586 -mcall-prologues -mno-tablejump -mtiny-stack}
590 -mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol
591 -mno-relax-immediates -mwide-bitfields -mno-wide-bitfields @gol
592 -m4byte-functions -mno-4byte-functions -mcallgraph-data @gol
593 -mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim @gol
594 -mlittle-endian -mbig-endian -m210 -m340 -mstack-increment}
598 -mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol
599 -mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol
600 -melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol
605 -mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol
606 -mvolatile-asm-stop -mb-step -mregister-names -mno-sdata @gol
607 -mconstant-gp -mauto-pic -minline-divide-min-latency @gol
608 -minline-divide-max-throughput -mno-dwarf2-asm @gol
609 -mfixed-range=@var{register-range}}
613 -mextmem -mextmemory -monchip -mno-asm-optimize -masm-optimize @gol
614 -mbranch-cost=@var{n} -mcond-exec=@var{n}}
616 @emph{S/390 and zSeries Options}
618 -mhard-float -msoft-float -mbackchain -mno-backchain @gol
619 -msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol
620 -m64 -m31 -mdebug -mno-debug}
624 -mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol
625 -mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol
626 -metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol
627 -mstack-align -mdata-align -mconst-align @gol
628 -m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol
629 -melf -maout -melinux -mlinux -sim -sim2}
631 @emph{PDP-11 Options}
633 -mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol
634 -mbcopy -mbcopy-builtin -mint32 -mno-int16 @gol
635 -mint16 -mno-int32 -mfloat32 -mno-float64 @gol
636 -mfloat64 -mno-float32 -mabshi -mno-abshi @gol
637 -mbranch-expensive -mbranch-cheap @gol
638 -msplit -mno-split -munix-asm -mdec-asm}
640 @emph{Xstormy16 Options}
644 @emph{Xtensa Options}
646 -mbig-endian -mlittle-endian @gol
647 -mdensity -mno-density @gol
648 -mmac16 -mno-mac16 @gol
649 -mmul16 -mno-mul16 @gol
650 -mmul32 -mno-mul32 @gol
652 -mminmax -mno-minmax @gol
653 -msext -mno-sext @gol
654 -mbooleans -mno-booleans @gol
655 -mhard-float -msoft-float @gol
656 -mfused-madd -mno-fused-madd @gol
657 -mserialize-volatile -mno-serialize-volatile @gol
658 -mtext-section-literals -mno-text-section-literals @gol
659 -mtarget-align -mno-target-align @gol
660 -mlongcalls -mno-longcalls}
662 @item Code Generation Options
663 @xref{Code Gen Options,,Options for Code Generation Conventions}.
665 -fcall-saved-@var{reg} -fcall-used-@var{reg} @gol
666 -ffixed-@var{reg} -fexceptions @gol
667 -fnon-call-exceptions -funwind-tables @gol
668 -fasynchronous-unwind-tables @gol
669 -finhibit-size-directive -finstrument-functions @gol
670 -fno-common -fno-ident -fno-gnu-linker @gol
671 -fpcc-struct-return -fpic -fPIC @gol
672 -freg-struct-return -fshared-data -fshort-enums @gol
673 -fshort-double -fvolatile @gol
674 -fvolatile-global -fvolatile-static @gol
675 -fverbose-asm -fpack-struct -fstack-check @gol
676 -fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
677 -fargument-alias -fargument-noalias @gol
678 -fargument-noalias-global -fleading-underscore}
682 * Overall Options:: Controlling the kind of output:
683 an executable, object files, assembler files,
684 or preprocessed source.
685 * C Dialect Options:: Controlling the variant of C language compiled.
686 * C++ Dialect Options:: Variations on C++.
687 * Objective-C Dialect Options:: Variations on Objective-C.
688 * Language Independent Options:: Controlling how diagnostics should be
690 * Warning Options:: How picky should the compiler be?
691 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
692 * Optimize Options:: How much optimization?
693 * Preprocessor Options:: Controlling header files and macro definitions.
694 Also, getting dependency information for Make.
695 * Assembler Options:: Passing options to the assembler.
696 * Link Options:: Specifying libraries and so on.
697 * Directory Options:: Where to find header files and libraries.
698 Where to find the compiler executable files.
699 * Spec Files:: How to pass switches to sub-processes.
700 * Target Options:: Running a cross-compiler, or an old version of GCC.
703 @node Overall Options
704 @section Options Controlling the Kind of Output
706 Compilation can involve up to four stages: preprocessing, compilation
707 proper, assembly and linking, always in that order. The first three
708 stages apply to an individual source file, and end by producing an
709 object file; linking combines all the object files (those newly
710 compiled, and those specified as input) into an executable file.
712 @cindex file name suffix
713 For any given input file, the file name suffix determines what kind of
718 C source code which must be preprocessed.
721 C source code which should not be preprocessed.
724 C++ source code which should not be preprocessed.
727 Objective-C source code. Note that you must link with the library
728 @file{libobjc.a} to make an Objective-C program work.
731 Objective-C source code which should not be preprocessed.
734 C header file (not to be compiled or linked).
738 @itemx @var{file}.cxx
739 @itemx @var{file}.cpp
740 @itemx @var{file}.c++
742 C++ source code which must be preprocessed. Note that in @samp{.cxx},
743 the last two letters must both be literally @samp{x}. Likewise,
744 @samp{.C} refers to a literal capital C@.
747 @itemx @var{file}.for
748 @itemx @var{file}.FOR
749 Fortran source code which should not be preprocessed.
752 @itemx @var{file}.fpp
753 @itemx @var{file}.FPP
754 Fortran source code which must be preprocessed (with the traditional
758 Fortran source code which must be preprocessed with a RATFOR
759 preprocessor (not included with GCC)@.
761 @xref{Overall Options,,Options Controlling the Kind of Output, g77,
762 Using and Porting GNU Fortran}, for more details of the handling of
765 @c FIXME: Descriptions of Java file types.
772 Ada source code file which contains a library unit declaration (a
773 declaration of a package, subprogram, or generic, or a generic
774 instantiation), or a library unit renaming declaration (a package,
775 generic, or subprogram renaming declaration). Such files are also
778 @itemx @var{file}.adb
779 Ada source code file containing a library unit body (a subprogram or
780 package body). Such files are also called @dfn{bodies}.
782 @c GCC also knows about some suffixes for languages not yet included:
788 @itemx @var{file}.chi
789 CHILL source code (preprocessed with the traditional preprocessor).
795 Assembler code which must be preprocessed.
798 An object file to be fed straight into linking.
799 Any file name with no recognized suffix is treated this way.
803 You can specify the input language explicitly with the @option{-x} option:
806 @item -x @var{language}
807 Specify explicitly the @var{language} for the following input files
808 (rather than letting the compiler choose a default based on the file
809 name suffix). This option applies to all following input files until
810 the next @option{-x} option. Possible values for @var{language} are:
812 c c-header cpp-output
814 objective-c objc-cpp-output
815 assembler assembler-with-cpp
818 f77 f77-cpp-input ratfor
823 Turn off any specification of a language, so that subsequent files are
824 handled according to their file name suffixes (as they are if @option{-x}
825 has not been used at all).
827 @item -pass-exit-codes
828 @opindex pass-exit-codes
829 Normally the @command{gcc} program will exit with the code of 1 if any
830 phase of the compiler returns a non-success return code. If you specify
831 @option{-pass-exit-codes}, the @command{gcc} program will instead return with
832 numerically highest error produced by any phase that returned an error
836 If you only want some of the stages of compilation, you can use
837 @option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
838 one of the options @option{-c}, @option{-S}, or @option{-E} to say where
839 @command{gcc} is to stop. Note that some combinations (for example,
840 @samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
845 Compile or assemble the source files, but do not link. The linking
846 stage simply is not done. The ultimate output is in the form of an
847 object file for each source file.
849 By default, the object file name for a source file is made by replacing
850 the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
852 Unrecognized input files, not requiring compilation or assembly, are
857 Stop after the stage of compilation proper; do not assemble. The output
858 is in the form of an assembler code file for each non-assembler input
861 By default, the assembler file name for a source file is made by
862 replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
864 Input files that don't require compilation are ignored.
868 Stop after the preprocessing stage; do not run the compiler proper. The
869 output is in the form of preprocessed source code, which is sent to the
872 Input files which don't require preprocessing are ignored.
874 @cindex output file option
877 Place output in file @var{file}. This applies regardless to whatever
878 sort of output is being produced, whether it be an executable file,
879 an object file, an assembler file or preprocessed C code.
881 Since only one output file can be specified, it does not make sense to
882 use @option{-o} when compiling more than one input file, unless you are
883 producing an executable file as output.
885 If @option{-o} is not specified, the default is to put an executable file
886 in @file{a.out}, the object file for @file{@var{source}.@var{suffix}} in
887 @file{@var{source}.o}, its assembler file in @file{@var{source}.s}, and
888 all preprocessed C source on standard output.
892 Print (on standard error output) the commands executed to run the stages
893 of compilation. Also print the version number of the compiler driver
894 program and of the preprocessor and the compiler proper.
898 Use pipes rather than temporary files for communication between the
899 various stages of compilation. This fails to work on some systems where
900 the assembler is unable to read from a pipe; but the GNU assembler has
905 Print (on the standard output) a description of the command line options
906 understood by @command{gcc}. If the @option{-v} option is also specified
907 then @option{--help} will also be passed on to the various processes
908 invoked by @command{gcc}, so that they can display the command line options
909 they accept. If the @option{-W} option is also specified then command
910 line options which have no documentation associated with them will also
915 Print (on the standard output) a description of target specific command
916 line options for each tool.
920 @section Compiling C++ Programs
922 @cindex suffixes for C++ source
923 @cindex C++ source file suffixes
924 C++ source files conventionally use one of the suffixes @samp{.C},
925 @samp{.cc}, @samp{.cpp}, @samp{.c++}, @samp{.cp}, or @samp{.cxx};
926 preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes
927 files with these names and compiles them as C++ programs even if you
928 call the compiler the same way as for compiling C programs (usually with
929 the name @command{gcc}).
933 However, C++ programs often require class libraries as well as a
934 compiler that understands the C++ language---and under some
935 circumstances, you might want to compile programs from standard input,
936 or otherwise without a suffix that flags them as C++ programs.
937 @command{g++} is a program that calls GCC with the default language
938 set to C++, and automatically specifies linking against the C++
939 library. On many systems, @command{g++} is also
940 installed with the name @command{c++}.
942 @cindex invoking @command{g++}
943 When you compile C++ programs, you may specify many of the same
944 command-line options that you use for compiling programs in any
945 language; or command-line options meaningful for C and related
946 languages; or options that are meaningful only for C++ programs.
947 @xref{C Dialect Options,,Options Controlling C Dialect}, for
948 explanations of options for languages related to C@.
949 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
950 explanations of options that are meaningful only for C++ programs.
952 @node C Dialect Options
953 @section Options Controlling C Dialect
954 @cindex dialect options
955 @cindex language dialect options
956 @cindex options, dialect
958 The following options control the dialect of C (or languages derived
959 from C, such as C++ and Objective-C) that the compiler accepts:
966 In C mode, support all ISO C89 programs. In C++ mode,
967 remove GNU extensions that conflict with ISO C++.
969 This turns off certain features of GCC that are incompatible with ISO
970 C89 (when compiling C code), or of standard C++ (when compiling C++ code),
971 such as the @code{asm} and @code{typeof} keywords, and
972 predefined macros such as @code{unix} and @code{vax} that identify the
973 type of system you are using. It also enables the undesirable and
974 rarely used ISO trigraph feature. For the C compiler,
975 it disables recognition of C++ style @samp{//} comments as well as
976 the @code{inline} keyword.
978 The alternate keywords @code{__asm__}, @code{__extension__},
979 @code{__inline__} and @code{__typeof__} continue to work despite
980 @option{-ansi}. You would not want to use them in an ISO C program, of
981 course, but it is useful to put them in header files that might be included
982 in compilations done with @option{-ansi}. Alternate predefined macros
983 such as @code{__unix__} and @code{__vax__} are also available, with or
984 without @option{-ansi}.
986 The @option{-ansi} option does not cause non-ISO programs to be
987 rejected gratuitously. For that, @option{-pedantic} is required in
988 addition to @option{-ansi}. @xref{Warning Options}.
990 The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
991 option is used. Some header files may notice this macro and refrain
992 from declaring certain functions or defining certain macros that the
993 ISO standard doesn't call for; this is to avoid interfering with any
994 programs that might use these names for other things.
996 Functions which would normally be built in but do not have semantics
997 defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
998 functions with @option{-ansi} is used. @xref{Other Builtins,,Other
999 built-in functions provided by GCC}, for details of the functions
1004 Determine the language standard. This option is currently only
1005 supported when compiling C@. A value for this option must be provided;
1011 ISO C89 (same as @option{-ansi}).
1013 @item iso9899:199409
1014 ISO C89 as modified in amendment 1.
1020 ISO C99. Note that this standard is not yet fully supported; see
1021 @w{@uref{http://gcc.gnu.org/c99status.html}} for more information. The
1022 names @samp{c9x} and @samp{iso9899:199x} are deprecated.
1025 Default, ISO C89 plus GNU extensions (including some C99 features).
1029 ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC,
1030 this will become the default. The name @samp{gnu9x} is deprecated.
1034 Even when this option is not specified, you can still use some of the
1035 features of newer standards in so far as they do not conflict with
1036 previous C standards. For example, you may use @code{__restrict__} even
1037 when @option{-std=c99} is not specified.
1039 The @option{-std} options specifying some version of ISO C have the same
1040 effects as @option{-ansi}, except that features that were not in ISO C89
1041 but are in the specified version (for example, @samp{//} comments and
1042 the @code{inline} keyword in ISO C99) are not disabled.
1044 @xref{Standards,,Language Standards Supported by GCC}, for details of
1045 these standard versions.
1047 @item -aux-info @var{filename}
1049 Output to the given filename prototyped declarations for all functions
1050 declared and/or defined in a translation unit, including those in header
1051 files. This option is silently ignored in any language other than C@.
1053 Besides declarations, the file indicates, in comments, the origin of
1054 each declaration (source file and line), whether the declaration was
1055 implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
1056 @samp{O} for old, respectively, in the first character after the line
1057 number and the colon), and whether it came from a declaration or a
1058 definition (@samp{C} or @samp{F}, respectively, in the following
1059 character). In the case of function definitions, a K&R-style list of
1060 arguments followed by their declarations is also provided, inside
1061 comments, after the declaration.
1065 Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1066 keyword, so that code can use these words as identifiers. You can use
1067 the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
1068 instead. @option{-ansi} implies @option{-fno-asm}.
1070 In C++, this switch only affects the @code{typeof} keyword, since
1071 @code{asm} and @code{inline} are standard keywords. You may want to
1072 use the @option{-fno-gnu-keywords} flag instead, which has the same
1073 effect. In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
1074 switch only affects the @code{asm} and @code{typeof} keywords, since
1075 @code{inline} is a standard keyword in ISO C99.
1078 @itemx -fno-builtin-@var{function} @r{(C and Objective-C only)}
1079 @opindex fno-builtin
1080 @cindex built-in functions
1081 Don't recognize built-in functions that do not begin with
1082 @samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in
1083 functions provided by GCC}, for details of the functions affected,
1084 including those which are not built-in functions when @option{-ansi} or
1085 @option{-std} options for strict ISO C conformance are used because they
1086 do not have an ISO standard meaning.
1088 GCC normally generates special code to handle certain built-in functions
1089 more efficiently; for instance, calls to @code{alloca} may become single
1090 instructions that adjust the stack directly, and calls to @code{memcpy}
1091 may become inline copy loops. The resulting code is often both smaller
1092 and faster, but since the function calls no longer appear as such, you
1093 cannot set a breakpoint on those calls, nor can you change the behavior
1094 of the functions by linking with a different library.
1096 In C++, @option{-fno-builtin} is always in effect. The @option{-fbuiltin}
1097 option has no effect. Therefore, in C++, the only way to get the
1098 optimization benefits of built-in functions is to call the function
1099 using the @samp{__builtin_} prefix. The GNU C++ Standard Library uses
1100 built-in functions to implement many functions (like
1101 @code{std::strchr}), so that you automatically get efficient code.
1103 With the @option{-fno-builtin-@var{function}} option, not available
1104 when compiling C++, only the built-in function @var{function} is
1105 disabled. @var{function} must not begin with @samp{__builtin_}. If a
1106 function is named this is not built-in in this version of GCC, this
1107 option is ignored. There is no corresponding
1108 @option{-fbuiltin-@var{function}} option; if you wish to enable
1109 built-in functions selectively when using @option{-fno-builtin} or
1110 @option{-ffreestanding}, you may define macros such as:
1113 #define abs(n) __builtin_abs ((n))
1114 #define strcpy(d, s) __builtin_strcpy ((d), (s))
1119 @cindex hosted environment
1121 Assert that compilation takes place in a hosted environment. This implies
1122 @option{-fbuiltin}. A hosted environment is one in which the
1123 entire standard library is available, and in which @code{main} has a return
1124 type of @code{int}. Examples are nearly everything except a kernel.
1125 This is equivalent to @option{-fno-freestanding}.
1127 @item -ffreestanding
1128 @opindex ffreestanding
1129 @cindex hosted environment
1131 Assert that compilation takes place in a freestanding environment. This
1132 implies @option{-fno-builtin}. A freestanding environment
1133 is one in which the standard library may not exist, and program startup may
1134 not necessarily be at @code{main}. The most obvious example is an OS kernel.
1135 This is equivalent to @option{-fno-hosted}.
1137 @xref{Standards,,Language Standards Supported by GCC}, for details of
1138 freestanding and hosted environments.
1142 Support ISO C trigraphs. The @option{-ansi} option (and @option{-std}
1143 options for strict ISO C conformance) implies @option{-trigraphs}.
1145 @cindex traditional C language
1146 @cindex C language, traditional
1148 @itemx -traditional-cpp
1149 @opindex traditional-cpp
1150 @opindex traditional
1151 Formerly, these options caused GCC to attempt to emulate a pre-standard
1152 C compiler. They are now only supported with the @option{-E} switch.
1153 The preprocessor continues to support a pre-standard mode. See the GNU
1154 CPP manual for details.
1156 @item -fcond-mismatch
1157 @opindex fcond-mismatch
1158 Allow conditional expressions with mismatched types in the second and
1159 third arguments. The value of such an expression is void. This option
1160 is not supported for C++.
1162 @item -funsigned-char
1163 @opindex funsigned-char
1164 Let the type @code{char} be unsigned, like @code{unsigned char}.
1166 Each kind of machine has a default for what @code{char} should
1167 be. It is either like @code{unsigned char} by default or like
1168 @code{signed char} by default.
1170 Ideally, a portable program should always use @code{signed char} or
1171 @code{unsigned char} when it depends on the signedness of an object.
1172 But many programs have been written to use plain @code{char} and
1173 expect it to be signed, or expect it to be unsigned, depending on the
1174 machines they were written for. This option, and its inverse, let you
1175 make such a program work with the opposite default.
1177 The type @code{char} is always a distinct type from each of
1178 @code{signed char} or @code{unsigned char}, even though its behavior
1179 is always just like one of those two.
1182 @opindex fsigned-char
1183 Let the type @code{char} be signed, like @code{signed char}.
1185 Note that this is equivalent to @option{-fno-unsigned-char}, which is
1186 the negative form of @option{-funsigned-char}. Likewise, the option
1187 @option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
1189 @item -fsigned-bitfields
1190 @itemx -funsigned-bitfields
1191 @itemx -fno-signed-bitfields
1192 @itemx -fno-unsigned-bitfields
1193 @opindex fsigned-bitfields
1194 @opindex funsigned-bitfields
1195 @opindex fno-signed-bitfields
1196 @opindex fno-unsigned-bitfields
1197 These options control whether a bit-field is signed or unsigned, when the
1198 declaration does not use either @code{signed} or @code{unsigned}. By
1199 default, such a bit-field is signed, because this is consistent: the
1200 basic integer types such as @code{int} are signed types.
1202 @item -fwritable-strings
1203 @opindex fwritable-strings
1204 Store string constants in the writable data segment and don't uniquize
1205 them. This is for compatibility with old programs which assume they can
1206 write into string constants.
1208 Writing into string constants is a very bad idea; ``constants'' should
1212 @opindex fshort-wchar
1213 Override the underlying type for @samp{wchar_t} to be @samp{short
1214 unsigned int} instead of the default for the target. This option is
1215 useful for building programs to run under WINE@.
1218 @node C++ Dialect Options
1219 @section Options Controlling C++ Dialect
1221 @cindex compiler options, C++
1222 @cindex C++ options, command line
1223 @cindex options, C++
1224 This section describes the command-line options that are only meaningful
1225 for C++ programs; but you can also use most of the GNU compiler options
1226 regardless of what language your program is in. For example, you
1227 might compile a file @code{firstClass.C} like this:
1230 g++ -g -frepo -O -c firstClass.C
1234 In this example, only @option{-frepo} is an option meant
1235 only for C++ programs; you can use the other options with any
1236 language supported by GCC@.
1238 Here is a list of options that are @emph{only} for compiling C++ programs:
1241 @item -fno-access-control
1242 @opindex fno-access-control
1243 Turn off all access checking. This switch is mainly useful for working
1244 around bugs in the access control code.
1248 Check that the pointer returned by @code{operator new} is non-null
1249 before attempting to modify the storage allocated. The current Working
1250 Paper requires that @code{operator new} never return a null pointer, so
1251 this check is normally unnecessary.
1253 An alternative to using this option is to specify that your
1254 @code{operator new} does not throw any exceptions; if you declare it
1255 @samp{throw()}, G++ will check the return value. See also @samp{new
1258 @item -fconserve-space
1259 @opindex fconserve-space
1260 Put uninitialized or runtime-initialized global variables into the
1261 common segment, as C does. This saves space in the executable at the
1262 cost of not diagnosing duplicate definitions. If you compile with this
1263 flag and your program mysteriously crashes after @code{main()} has
1264 completed, you may have an object that is being destroyed twice because
1265 two definitions were merged.
1267 This option is no longer useful on most targets, now that support has
1268 been added for putting variables into BSS without making them common.
1270 @item -fno-const-strings
1271 @opindex fno-const-strings
1272 Give string constants type @code{char *} instead of type @code{const
1273 char *}. By default, G++ uses type @code{const char *} as required by
1274 the standard. Even if you use @option{-fno-const-strings}, you cannot
1275 actually modify the value of a string constant, unless you also use
1276 @option{-fwritable-strings}.
1278 This option might be removed in a future release of G++. For maximum
1279 portability, you should structure your code so that it works with
1280 string constants that have type @code{const char *}.
1282 @item -fdollars-in-identifiers
1283 @opindex fdollars-in-identifiers
1284 Accept @samp{$} in identifiers. You can also explicitly prohibit use of
1285 @samp{$} with the option @option{-fno-dollars-in-identifiers}. (GNU C allows
1286 @samp{$} by default on most target systems, but there are a few exceptions.)
1287 Traditional C allowed the character @samp{$} to form part of
1288 identifiers. However, ISO C and C++ forbid @samp{$} in identifiers.
1290 @item -fno-elide-constructors
1291 @opindex fno-elide-constructors
1292 The C++ standard allows an implementation to omit creating a temporary
1293 which is only used to initialize another object of the same type.
1294 Specifying this option disables that optimization, and forces G++ to
1295 call the copy constructor in all cases.
1297 @item -fno-enforce-eh-specs
1298 @opindex fno-enforce-eh-specs
1299 Don't check for violation of exception specifications at runtime. This
1300 option violates the C++ standard, but may be useful for reducing code
1301 size in production builds, much like defining @samp{NDEBUG}. The compiler
1302 will still optimize based on the exception specifications.
1304 @item -fexternal-templates
1305 @opindex fexternal-templates
1307 Cause @samp{#pragma interface} and @samp{implementation} to apply to
1308 template instantiation; template instances are emitted or not according
1309 to the location of the template definition. @xref{Template
1310 Instantiation}, for more information.
1312 This option is deprecated.
1314 @item -falt-external-templates
1315 @opindex falt-external-templates
1316 Similar to @option{-fexternal-templates}, but template instances are
1317 emitted or not according to the place where they are first instantiated.
1318 @xref{Template Instantiation}, for more information.
1320 This option is deprecated.
1323 @itemx -fno-for-scope
1325 @opindex fno-for-scope
1326 If @option{-ffor-scope} is specified, the scope of variables declared in
1327 a @i{for-init-statement} is limited to the @samp{for} loop itself,
1328 as specified by the C++ standard.
1329 If @option{-fno-for-scope} is specified, the scope of variables declared in
1330 a @i{for-init-statement} extends to the end of the enclosing scope,
1331 as was the case in old versions of G++, and other (traditional)
1332 implementations of C++.
1334 The default if neither flag is given to follow the standard,
1335 but to allow and give a warning for old-style code that would
1336 otherwise be invalid, or have different behavior.
1338 @item -fno-gnu-keywords
1339 @opindex fno-gnu-keywords
1340 Do not recognize @code{typeof} as a keyword, so that code can use this
1341 word as an identifier. You can use the keyword @code{__typeof__} instead.
1342 @option{-ansi} implies @option{-fno-gnu-keywords}.
1344 @item -fno-implicit-templates
1345 @opindex fno-implicit-templates
1346 Never emit code for non-inline templates which are instantiated
1347 implicitly (i.e.@: by use); only emit code for explicit instantiations.
1348 @xref{Template Instantiation}, for more information.
1350 @item -fno-implicit-inline-templates
1351 @opindex fno-implicit-inline-templates
1352 Don't emit code for implicit instantiations of inline templates, either.
1353 The default is to handle inlines differently so that compiles with and
1354 without optimization will need the same set of explicit instantiations.
1356 @item -fno-implement-inlines
1357 @opindex fno-implement-inlines
1358 To save space, do not emit out-of-line copies of inline functions
1359 controlled by @samp{#pragma implementation}. This will cause linker
1360 errors if these functions are not inlined everywhere they are called.
1362 @item -fms-extensions
1363 @opindex fms-extensions
1364 Disable pedantic warnings about constructs used in MFC, such as implicit
1365 int and getting a pointer to member function via non-standard syntax.
1367 @item -fno-nonansi-builtins
1368 @opindex fno-nonansi-builtins
1369 Disable built-in declarations of functions that are not mandated by
1370 ANSI/ISO C@. These include @code{ffs}, @code{alloca}, @code{_exit},
1371 @code{index}, @code{bzero}, @code{conjf}, and other related functions.
1373 @item -fno-operator-names
1374 @opindex fno-operator-names
1375 Do not treat the operator name keywords @code{and}, @code{bitand},
1376 @code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1377 synonyms as keywords.
1379 @item -fno-optional-diags
1380 @opindex fno-optional-diags
1381 Disable diagnostics that the standard says a compiler does not need to
1382 issue. Currently, the only such diagnostic issued by G++ is the one for
1383 a name having multiple meanings within a class.
1386 @opindex fpermissive
1387 Downgrade messages about nonconformant code from errors to warnings. By
1388 default, G++ effectively sets @option{-pedantic-errors} without
1389 @option{-pedantic}; this option reverses that. This behavior and this
1390 option are superseded by @option{-pedantic}, which works as it does for GNU C@.
1394 Enable automatic template instantiation at link time. This option also
1395 implies @option{-fno-implicit-templates}. @xref{Template
1396 Instantiation}, for more information.
1400 Disable generation of information about every class with virtual
1401 functions for use by the C++ runtime type identification features
1402 (@samp{dynamic_cast} and @samp{typeid}). If you don't use those parts
1403 of the language, you can save some space by using this flag. Note that
1404 exception handling uses the same information, but it will generate it as
1409 Emit statistics about front-end processing at the end of the compilation.
1410 This information is generally only useful to the G++ development team.
1412 @item -ftemplate-depth-@var{n}
1413 @opindex ftemplate-depth
1414 Set the maximum instantiation depth for template classes to @var{n}.
1415 A limit on the template instantiation depth is needed to detect
1416 endless recursions during template class instantiation. ANSI/ISO C++
1417 conforming programs must not rely on a maximum depth greater than 17.
1419 @item -fuse-cxa-atexit
1420 @opindex fuse-cxa-atexit
1421 Register destructors for objects with static storage duration with the
1422 @code{__cxa_atexit} function rather than the @code{atexit} function.
1423 This option is required for fully standards-compliant handling of static
1424 destructors, but will only work if your C library supports
1425 @code{__cxa_atexit}.
1429 Emit special relocations for vtables and virtual function references
1430 so that the linker can identify unused virtual functions and zero out
1431 vtable slots that refer to them. This is most useful with
1432 @option{-ffunction-sections} and @option{-Wl,--gc-sections}, in order to
1433 also discard the functions themselves.
1435 This optimization requires GNU as and GNU ld. Not all systems support
1436 this option. @option{-Wl,--gc-sections} is ignored without @option{-static}.
1440 Do not use weak symbol support, even if it is provided by the linker.
1441 By default, G++ will use weak symbols if they are available. This
1442 option exists only for testing, and should not be used by end-users;
1443 it will result in inferior code and has no benefits. This option may
1444 be removed in a future release of G++.
1448 Do not search for header files in the standard directories specific to
1449 C++, but do still search the other standard directories. (This option
1450 is used when building the C++ library.)
1453 In addition, these optimization, warning, and code generation options
1454 have meanings only for C++ programs:
1457 @item -fno-default-inline
1458 @opindex fno-default-inline
1459 Do not assume @samp{inline} for functions defined inside a class scope.
1460 @xref{Optimize Options,,Options That Control Optimization}. Note that these
1461 functions will have linkage like inline functions; they just won't be
1464 @item -Wctor-dtor-privacy @r{(C++ only)}
1465 @opindex Wctor-dtor-privacy
1466 Warn when a class seems unusable, because all the constructors or
1467 destructors in a class are private and the class has no friends or
1468 public static member functions.
1470 @item -Wnon-virtual-dtor @r{(C++ only)}
1471 @opindex Wnon-virtual-dtor
1472 Warn when a class declares a non-virtual destructor that should probably
1473 be virtual, because it looks like the class will be used polymorphically.
1475 @item -Wreorder @r{(C++ only)}
1477 @cindex reordering, warning
1478 @cindex warning for reordering of member initializers
1479 Warn when the order of member initializers given in the code does not
1480 match the order in which they must be executed. For instance:
1486 A(): j (0), i (1) @{ @}
1490 Here the compiler will warn that the member initializers for @samp{i}
1491 and @samp{j} will be rearranged to match the declaration order of the
1495 The following @option{-W@dots{}} options are not affected by @option{-Wall}.
1498 @item -Weffc++ @r{(C++ only)}
1500 Warn about violations of the following style guidelines from Scott Meyers'
1501 @cite{Effective C++} book:
1505 Item 11: Define a copy constructor and an assignment operator for classes
1506 with dynamically allocated memory.
1509 Item 12: Prefer initialization to assignment in constructors.
1512 Item 14: Make destructors virtual in base classes.
1515 Item 15: Have @code{operator=} return a reference to @code{*this}.
1518 Item 23: Don't try to return a reference when you must return an object.
1522 and about violations of the following style guidelines from Scott Meyers'
1523 @cite{More Effective C++} book:
1527 Item 6: Distinguish between prefix and postfix forms of increment and
1528 decrement operators.
1531 Item 7: Never overload @code{&&}, @code{||}, or @code{,}.
1535 If you use this option, you should be aware that the standard library
1536 headers do not obey all of these guidelines; you can use @samp{grep -v}
1537 to filter out those warnings.
1539 @item -Wno-deprecated @r{(C++ only)}
1540 @opindex Wno-deprecated
1541 Do not warn about usage of deprecated features. @xref{Deprecated Features}.
1543 @item -Wno-non-template-friend @r{(C++ only)}
1544 @opindex Wno-non-template-friend
1545 Disable warnings when non-templatized friend functions are declared
1546 within a template. With the advent of explicit template specification
1547 support in G++, if the name of the friend is an unqualified-id (i.e.,
1548 @samp{friend foo(int)}), the C++ language specification demands that the
1549 friend declare or define an ordinary, nontemplate function. (Section
1550 14.5.3). Before G++ implemented explicit specification, unqualified-ids
1551 could be interpreted as a particular specialization of a templatized
1552 function. Because this non-conforming behavior is no longer the default
1553 behavior for G++, @option{-Wnon-template-friend} allows the compiler to
1554 check existing code for potential trouble spots, and is on by default.
1555 This new compiler behavior can be turned off with
1556 @option{-Wno-non-template-friend} which keeps the conformant compiler code
1557 but disables the helpful warning.
1559 @item -Wold-style-cast @r{(C++ only)}
1560 @opindex Wold-style-cast
1561 Warn if an old-style (C-style) cast to a non-void type is used within
1562 a C++ program. The new-style casts (@samp{static_cast},
1563 @samp{reinterpret_cast}, and @samp{const_cast}) are less vulnerable to
1564 unintended effects, and much easier to grep for.
1566 @item -Woverloaded-virtual @r{(C++ only)}
1567 @opindex Woverloaded-virtual
1568 @cindex overloaded virtual fn, warning
1569 @cindex warning for overloaded virtual fn
1570 Warn when a function declaration hides virtual functions from a
1571 base class. For example, in:
1578 struct B: public A @{
1583 the @code{A} class version of @code{f} is hidden in @code{B}, and code
1591 will fail to compile.
1593 @item -Wno-pmf-conversions @r{(C++ only)}
1594 @opindex Wno-pmf-conversions
1595 Disable the diagnostic for converting a bound pointer to member function
1598 @item -Wsign-promo @r{(C++ only)}
1599 @opindex Wsign-promo
1600 Warn when overload resolution chooses a promotion from unsigned or
1601 enumeral type to a signed type over a conversion to an unsigned type of
1602 the same size. Previous versions of G++ would try to preserve
1603 unsignedness, but the standard mandates the current behavior.
1605 @item -Wsynth @r{(C++ only)}
1607 @cindex warning for synthesized methods
1608 @cindex synthesized methods, warning
1609 Warn when G++'s synthesis behavior does not match that of cfront. For
1615 A& operator = (int);
1625 In this example, G++ will synthesize a default @samp{A& operator =
1626 (const A&);}, while cfront will use the user-defined @samp{operator =}.
1629 @node Objective-C Dialect Options
1630 @section Options Controlling Objective-C Dialect
1632 @cindex compiler options, Objective-C
1633 @cindex Objective-C options, command line
1634 @cindex options, Objective-C
1635 This section describes the command-line options that are only meaningful
1636 for Objective-C programs; but you can also use most of the GNU compiler
1637 options regardless of what language your program is in. For example,
1638 you might compile a file @code{some_class.m} like this:
1641 gcc -g -fgnu-runtime -O -c some_class.m
1645 In this example, only @option{-fgnu-runtime} is an option meant only for
1646 Objective-C programs; you can use the other options with any language
1649 Here is a list of options that are @emph{only} for compiling Objective-C
1653 @item -fconstant-string-class=@var{class-name}
1654 @opindex fconstant-string-class
1655 Use @var{class-name} as the name of the class to instantiate for each
1656 literal string specified with the syntax @code{@@"@dots{}"}. The default
1657 class name is @code{NXConstantString}.
1660 @opindex fgnu-runtime
1661 Generate object code compatible with the standard GNU Objective-C
1662 runtime. This is the default for most types of systems.
1664 @item -fnext-runtime
1665 @opindex fnext-runtime
1666 Generate output compatible with the NeXT runtime. This is the default
1667 for NeXT-based systems, including Darwin and Mac OS X@.
1671 Dump interface declarations for all classes seen in the source file to a
1672 file named @file{@var{sourcename}.decl}.
1675 @opindex Wno-protocol
1676 Do not warn if methods required by a protocol are not implemented
1677 in the class adopting it.
1681 Warn if a selector has multiple methods of different types defined.
1683 @c not documented because only avail via -Wp
1684 @c @item -print-objc-runtime-info
1688 @node Language Independent Options
1689 @section Options to Control Diagnostic Messages Formatting
1690 @cindex options to control diagnostics formatting
1691 @cindex diagnostic messages
1692 @cindex message formatting
1694 Traditionally, diagnostic messages have been formatted irrespective of
1695 the output device's aspect (e.g.@: its width, @dots{}). The options described
1696 below can be used to control the diagnostic messages formatting
1697 algorithm, e.g.@: how many characters per line, how often source location
1698 information should be reported. Right now, only the C++ front end can
1699 honor these options. However it is expected, in the near future, that
1700 the remaining front ends would be able to digest them correctly.
1703 @item -fmessage-length=@var{n}
1704 @opindex fmessage-length
1705 Try to format error messages so that they fit on lines of about @var{n}
1706 characters. The default is 72 characters for @command{g++} and 0 for the rest of
1707 the front ends supported by GCC@. If @var{n} is zero, then no
1708 line-wrapping will be done; each error message will appear on a single
1711 @opindex fdiagnostics-show-location
1712 @item -fdiagnostics-show-location=once
1713 Only meaningful in line-wrapping mode. Instructs the diagnostic messages
1714 reporter to emit @emph{once} source location information; that is, in
1715 case the message is too long to fit on a single physical line and has to
1716 be wrapped, the source location won't be emitted (as prefix) again,
1717 over and over, in subsequent continuation lines. This is the default
1720 @item -fdiagnostics-show-location=every-line
1721 Only meaningful in line-wrapping mode. Instructs the diagnostic
1722 messages reporter to emit the same source location information (as
1723 prefix) for physical lines that result from the process of breaking
1724 a message which is too long to fit on a single line.
1728 @node Warning Options
1729 @section Options to Request or Suppress Warnings
1730 @cindex options to control warnings
1731 @cindex warning messages
1732 @cindex messages, warning
1733 @cindex suppressing warnings
1735 Warnings are diagnostic messages that report constructions which
1736 are not inherently erroneous but which are risky or suggest there
1737 may have been an error.
1739 You can request many specific warnings with options beginning @samp{-W},
1740 for example @option{-Wimplicit} to request warnings on implicit
1741 declarations. Each of these specific warning options also has a
1742 negative form beginning @samp{-Wno-} to turn off warnings;
1743 for example, @option{-Wno-implicit}. This manual lists only one of the
1744 two forms, whichever is not the default.
1746 These options control the amount and kinds of warnings produced by GCC:
1749 @cindex syntax checking
1751 @opindex fsyntax-only
1752 Check the code for syntax errors, but don't do anything beyond that.
1756 Issue all the warnings demanded by strict ISO C and ISO C++;
1757 reject all programs that use forbidden extensions, and some other
1758 programs that do not follow ISO C and ISO C++. For ISO C, follows the
1759 version of the ISO C standard specified by any @option{-std} option used.
1761 Valid ISO C and ISO C++ programs should compile properly with or without
1762 this option (though a rare few will require @option{-ansi} or a
1763 @option{-std} option specifying the required version of ISO C)@. However,
1764 without this option, certain GNU extensions and traditional C and C++
1765 features are supported as well. With this option, they are rejected.
1767 @option{-pedantic} does not cause warning messages for use of the
1768 alternate keywords whose names begin and end with @samp{__}. Pedantic
1769 warnings are also disabled in the expression that follows
1770 @code{__extension__}. However, only system header files should use
1771 these escape routes; application programs should avoid them.
1772 @xref{Alternate Keywords}.
1774 Some users try to use @option{-pedantic} to check programs for strict ISO
1775 C conformance. They soon find that it does not do quite what they want:
1776 it finds some non-ISO practices, but not all---only those for which
1777 ISO C @emph{requires} a diagnostic, and some others for which
1778 diagnostics have been added.
1780 A feature to report any failure to conform to ISO C might be useful in
1781 some instances, but would require considerable additional work and would
1782 be quite different from @option{-pedantic}. We don't have plans to
1783 support such a feature in the near future.
1785 Where the standard specified with @option{-std} represents a GNU
1786 extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
1787 corresponding @dfn{base standard}, the version of ISO C on which the GNU
1788 extended dialect is based. Warnings from @option{-pedantic} are given
1789 where they are required by the base standard. (It would not make sense
1790 for such warnings to be given only for features not in the specified GNU
1791 C dialect, since by definition the GNU dialects of C include all
1792 features the compiler supports with the given option, and there would be
1793 nothing to warn about.)
1795 @item -pedantic-errors
1796 @opindex pedantic-errors
1797 Like @option{-pedantic}, except that errors are produced rather than
1802 Inhibit all warning messages.
1806 Inhibit warning messages about the use of @samp{#import}.
1808 @item -Wchar-subscripts
1809 @opindex Wchar-subscripts
1810 Warn if an array subscript has type @code{char}. This is a common cause
1811 of error, as programmers often forget that this type is signed on some
1816 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
1817 comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
1821 Check calls to @code{printf} and @code{scanf}, etc., to make sure that
1822 the arguments supplied have types appropriate to the format string
1823 specified, and that the conversions specified in the format string make
1824 sense. This includes standard functions, and others specified by format
1825 attributes (@pxref{Function Attributes}), in the @code{printf},
1826 @code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
1827 not in the C standard) families.
1829 The formats are checked against the format features supported by GNU
1830 libc version 2.2. These include all ISO C89 and C99 features, as well
1831 as features from the Single Unix Specification and some BSD and GNU
1832 extensions. Other library implementations may not support all these
1833 features; GCC does not support warning about features that go beyond a
1834 particular library's limitations. However, if @option{-pedantic} is used
1835 with @option{-Wformat}, warnings will be given about format features not
1836 in the selected standard version (but not for @code{strfmon} formats,
1837 since those are not in any version of the C standard). @xref{C Dialect
1838 Options,,Options Controlling C Dialect}.
1840 @option{-Wformat} is included in @option{-Wall}. For more control over some
1841 aspects of format checking, the options @option{-Wno-format-y2k},
1842 @option{-Wno-format-extra-args}, @option{-Wformat-nonliteral},
1843 @option{-Wformat-security} and @option{-Wformat=2} are available, but are
1844 not included in @option{-Wall}.
1846 @item -Wno-format-y2k
1847 @opindex Wno-format-y2k
1848 If @option{-Wformat} is specified, do not warn about @code{strftime}
1849 formats which may yield only a two-digit year.
1851 @item -Wno-format-extra-args
1852 @opindex Wno-format-extra-args
1853 If @option{-Wformat} is specified, do not warn about excess arguments to a
1854 @code{printf} or @code{scanf} format function. The C standard specifies
1855 that such arguments are ignored.
1857 Where the unused arguments lie between used arguments that are
1858 specified with @samp{$} operand number specifications, normally
1859 warnings are still given, since the implementation could not know what
1860 type to pass to @code{va_arg} to skip the unused arguments. However,
1861 in the case of @code{scanf} formats, this option will suppress the
1862 warning if the unused arguments are all pointers, since the Single
1863 Unix Specification says that such unused arguments are allowed.
1865 @item -Wformat-nonliteral
1866 @opindex Wformat-nonliteral
1867 If @option{-Wformat} is specified, also warn if the format string is not a
1868 string literal and so cannot be checked, unless the format function
1869 takes its format arguments as a @code{va_list}.
1871 @item -Wformat-security
1872 @opindex Wformat-security
1873 If @option{-Wformat} is specified, also warn about uses of format
1874 functions that represent possible security problems. At present, this
1875 warns about calls to @code{printf} and @code{scanf} functions where the
1876 format string is not a string literal and there are no format arguments,
1877 as in @code{printf (foo);}. This may be a security hole if the format
1878 string came from untrusted input and contains @samp{%n}. (This is
1879 currently a subset of what @option{-Wformat-nonliteral} warns about, but
1880 in future warnings may be added to @option{-Wformat-security} that are not
1881 included in @option{-Wformat-nonliteral}.)
1885 Enable @option{-Wformat} plus format checks not included in
1886 @option{-Wformat}. Currently equivalent to @samp{-Wformat
1887 -Wformat-nonliteral -Wformat-security}.
1889 @item -Wimplicit-int
1890 @opindex Wimplicit-int
1891 Warn when a declaration does not specify a type.
1893 @item -Wimplicit-function-declaration
1894 @itemx -Werror-implicit-function-declaration
1895 @opindex Wimplicit-function-declaration
1896 @opindex Werror-implicit-function-declaration
1897 Give a warning (or error) whenever a function is used before being
1902 Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
1906 Warn if the type of @samp{main} is suspicious. @samp{main} should be a
1907 function with external linkage, returning int, taking either zero
1908 arguments, two, or three arguments of appropriate types.
1910 @item -Wmissing-braces
1911 @opindex Wmissing-braces
1912 Warn if an aggregate or union initializer is not fully bracketed. In
1913 the following example, the initializer for @samp{a} is not fully
1914 bracketed, but that for @samp{b} is fully bracketed.
1917 int a[2][2] = @{ 0, 1, 2, 3 @};
1918 int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
1922 @opindex Wparentheses
1923 Warn if parentheses are omitted in certain contexts, such
1924 as when there is an assignment in a context where a truth value
1925 is expected, or when operators are nested whose precedence people
1926 often get confused about.
1928 Also warn about constructions where there may be confusion to which
1929 @code{if} statement an @code{else} branch belongs. Here is an example of
1944 In C, every @code{else} branch belongs to the innermost possible @code{if}
1945 statement, which in this example is @code{if (b)}. This is often not
1946 what the programmer expected, as illustrated in the above example by
1947 indentation the programmer chose. When there is the potential for this
1948 confusion, GCC will issue a warning when this flag is specified.
1949 To eliminate the warning, add explicit braces around the innermost
1950 @code{if} statement so there is no way the @code{else} could belong to
1951 the enclosing @code{if}. The resulting code would look like this:
1967 @item -Wsequence-point
1968 @opindex Wsequence-point
1969 Warn about code that may have undefined semantics because of violations
1970 of sequence point rules in the C standard.
1972 The C standard defines the order in which expressions in a C program are
1973 evaluated in terms of @dfn{sequence points}, which represent a partial
1974 ordering between the execution of parts of the program: those executed
1975 before the sequence point, and those executed after it. These occur
1976 after the evaluation of a full expression (one which is not part of a
1977 larger expression), after the evaluation of the first operand of a
1978 @code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
1979 function is called (but after the evaluation of its arguments and the
1980 expression denoting the called function), and in certain other places.
1981 Other than as expressed by the sequence point rules, the order of
1982 evaluation of subexpressions of an expression is not specified. All
1983 these rules describe only a partial order rather than a total order,
1984 since, for example, if two functions are called within one expression
1985 with no sequence point between them, the order in which the functions
1986 are called is not specified. However, the standards committee have
1987 ruled that function calls do not overlap.
1989 It is not specified when between sequence points modifications to the
1990 values of objects take effect. Programs whose behavior depends on this
1991 have undefined behavior; the C standard specifies that ``Between the
1992 previous and next sequence point an object shall have its stored value
1993 modified at most once by the evaluation of an expression. Furthermore,
1994 the prior value shall be read only to determine the value to be
1995 stored.''. If a program breaks these rules, the results on any
1996 particular implementation are entirely unpredictable.
1998 Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
1999 = b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
2000 diagnosed by this option, and it may give an occasional false positive
2001 result, but in general it has been found fairly effective at detecting
2002 this sort of problem in programs.
2004 The present implementation of this option only works for C programs. A
2005 future implementation may also work for C++ programs.
2007 The C standard is worded confusingly, therefore there is some debate
2008 over the precise meaning of the sequence point rules in subtle cases.
2009 Links to discussions of the problem, including proposed formal
2010 definitions, may be found on our readings page, at
2011 @w{@uref{http://gcc.gnu.org/readings.html}}.
2014 @opindex Wreturn-type
2015 Warn whenever a function is defined with a return-type that defaults to
2016 @code{int}. Also warn about any @code{return} statement with no
2017 return-value in a function whose return-type is not @code{void}.
2019 For C++, a function without return type always produces a diagnostic
2020 message, even when @option{-Wno-return-type} is specified. The only
2021 exceptions are @samp{main} and functions defined in system headers.
2025 Warn whenever a @code{switch} statement has an index of enumeral type
2026 and lacks a @code{case} for one or more of the named codes of that
2027 enumeration. (The presence of a @code{default} label prevents this
2028 warning.) @code{case} labels outside the enumeration range also
2029 provoke warnings when this option is used.
2033 Warn if any trigraphs are encountered that might change the meaning of
2034 the program (trigraphs within comments are not warned about).
2036 @item -Wunused-function
2037 @opindex Wunused-function
2038 Warn whenever a static function is declared but not defined or a
2039 non\-inline static function is unused.
2041 @item -Wunused-label
2042 @opindex Wunused-label
2043 Warn whenever a label is declared but not used.
2045 To suppress this warning use the @samp{unused} attribute
2046 (@pxref{Variable Attributes}).
2048 @item -Wunused-parameter
2049 @opindex Wunused-parameter
2050 Warn whenever a function parameter is unused aside from its declaration.
2052 To suppress this warning use the @samp{unused} attribute
2053 (@pxref{Variable Attributes}).
2055 @item -Wunused-variable
2056 @opindex Wunused-variable
2057 Warn whenever a local variable or non-constant static variable is unused
2058 aside from its declaration
2060 To suppress this warning use the @samp{unused} attribute
2061 (@pxref{Variable Attributes}).
2063 @item -Wunused-value
2064 @opindex Wunused-value
2065 Warn whenever a statement computes a result that is explicitly not used.
2067 To suppress this warning cast the expression to @samp{void}.
2071 All all the above @option{-Wunused} options combined.
2073 In order to get a warning about an unused function parameter, you must
2074 either specify @samp{-W -Wunused} or separately specify
2075 @option{-Wunused-parameter}.
2077 @item -Wuninitialized
2078 @opindex Wuninitialized
2079 Warn if an automatic variable is used without first being initialized or
2080 if a variable may be clobbered by a @code{setjmp} call.
2082 These warnings are possible only in optimizing compilation,
2083 because they require data flow information that is computed only
2084 when optimizing. If you don't specify @option{-O}, you simply won't
2087 These warnings occur only for variables that are candidates for
2088 register allocation. Therefore, they do not occur for a variable that
2089 is declared @code{volatile}, or whose address is taken, or whose size
2090 is other than 1, 2, 4 or 8 bytes. Also, they do not occur for
2091 structures, unions or arrays, even when they are in registers.
2093 Note that there may be no warning about a variable that is used only
2094 to compute a value that itself is never used, because such
2095 computations may be deleted by data flow analysis before the warnings
2098 These warnings are made optional because GCC is not smart
2099 enough to see all the reasons why the code might be correct
2100 despite appearing to have an error. Here is one example of how
2121 If the value of @code{y} is always 1, 2 or 3, then @code{x} is
2122 always initialized, but GCC doesn't know this. Here is
2123 another common case:
2128 if (change_y) save_y = y, y = new_y;
2130 if (change_y) y = save_y;
2135 This has no bug because @code{save_y} is used only if it is set.
2137 @cindex @code{longjmp} warnings
2138 This option also warns when a non-volatile automatic variable might be
2139 changed by a call to @code{longjmp}. These warnings as well are possible
2140 only in optimizing compilation.
2142 The compiler sees only the calls to @code{setjmp}. It cannot know
2143 where @code{longjmp} will be called; in fact, a signal handler could
2144 call it at any point in the code. As a result, you may get a warning
2145 even when there is in fact no problem because @code{longjmp} cannot
2146 in fact be called at the place which would cause a problem.
2148 Some spurious warnings can be avoided if you declare all the functions
2149 you use that never return as @code{noreturn}. @xref{Function
2152 @item -Wreorder @r{(C++ only)}
2154 @cindex reordering, warning
2155 @cindex warning for reordering of member initializers
2156 Warn when the order of member initializers given in the code does not
2157 match the order in which they must be executed. For instance:
2159 @item -Wunknown-pragmas
2160 @opindex Wunknown-pragmas
2161 @cindex warning for unknown pragmas
2162 @cindex unknown pragmas, warning
2163 @cindex pragmas, warning of unknown
2164 Warn when a #pragma directive is encountered which is not understood by
2165 GCC@. If this command line option is used, warnings will even be issued
2166 for unknown pragmas in system header files. This is not the case if
2167 the warnings were only enabled by the @option{-Wall} command line option.
2171 All of the above @samp{-W} options combined. This enables all the
2172 warnings about constructions that some users consider questionable, and
2173 that are easy to avoid (or modify to prevent the warning), even in
2174 conjunction with macros.
2177 The following @option{-W@dots{}} options are not implied by @option{-Wall}.
2178 Some of them warn about constructions that users generally do not
2179 consider questionable, but which occasionally you might wish to check
2180 for; others warn about constructions that are necessary or hard to avoid
2181 in some cases, and there is no simple way to modify the code to suppress
2187 Print extra warning messages for these events:
2191 A function can return either with or without a value. (Falling
2192 off the end of the function body is considered returning without
2193 a value.) For example, this function would evoke such a
2207 An expression-statement or the left-hand side of a comma expression
2208 contains no side effects.
2209 To suppress the warning, cast the unused expression to void.
2210 For example, an expression such as @samp{x[i,j]} will cause a warning,
2211 but @samp{x[(void)i,j]} will not.
2214 An unsigned value is compared against zero with @samp{<} or @samp{<=}.
2217 A comparison like @samp{x<=y<=z} appears; this is equivalent to
2218 @samp{(x<=y ? 1 : 0) <= z}, which is a different interpretation from
2219 that of ordinary mathematical notation.
2222 Storage-class specifiers like @code{static} are not the first things in
2223 a declaration. According to the C Standard, this usage is obsolescent.
2226 The return type of a function has a type qualifier such as @code{const}.
2227 Such a type qualifier has no effect, since the value returned by a
2228 function is not an lvalue. (But don't warn about the GNU extension of
2229 @code{volatile void} return types. That extension will be warned about
2230 if @option{-pedantic} is specified.)
2233 If @option{-Wall} or @option{-Wunused} is also specified, warn about unused
2237 A comparison between signed and unsigned values could produce an
2238 incorrect result when the signed value is converted to unsigned.
2239 (But don't warn if @option{-Wno-sign-compare} is also specified.)
2242 An aggregate has a partly bracketed initializer.
2243 For example, the following code would evoke such a warning,
2244 because braces are missing around the initializer for @code{x.h}:
2247 struct s @{ int f, g; @};
2248 struct t @{ struct s h; int i; @};
2249 struct t x = @{ 1, 2, 3 @};
2253 An aggregate has an initializer which does not initialize all members.
2254 For example, the following code would cause such a warning, because
2255 @code{x.h} would be implicitly initialized to zero:
2258 struct s @{ int f, g, h; @};
2259 struct s x = @{ 3, 4 @};
2263 @item -Wno-div-by-zero
2264 @opindex Wno-div-by-zero
2265 @opindex Wdiv-by-zero
2266 Do not warn about compile-time integer division by zero. Floating point
2267 division by zero is not warned about, as it can be a legitimate way of
2268 obtaining infinities and NaNs.
2270 @item -Wsystem-headers
2271 @opindex Wsystem-headers
2272 @cindex warnings from system headers
2273 @cindex system headers, warnings from
2274 Print warning messages for constructs found in system header files.
2275 Warnings from system headers are normally suppressed, on the assumption
2276 that they usually do not indicate real problems and would only make the
2277 compiler output harder to read. Using this command line option tells
2278 GCC to emit warnings from system headers as if they occurred in user
2279 code. However, note that using @option{-Wall} in conjunction with this
2280 option will @emph{not} warn about unknown pragmas in system
2281 headers---for that, @option{-Wunknown-pragmas} must also be used.
2284 @opindex Wfloat-equal
2285 Warn if floating point values are used in equality comparisons.
2287 The idea behind this is that sometimes it is convenient (for the
2288 programmer) to consider floating-point values as approximations to
2289 infinitely precise real numbers. If you are doing this, then you need
2290 to compute (by analysing the code, or in some other way) the maximum or
2291 likely maximum error that the computation introduces, and allow for it
2292 when performing comparisons (and when producing output, but that's a
2293 different problem). In particular, instead of testing for equality, you
2294 would check to see whether the two values have ranges that overlap; and
2295 this is done with the relational operators, so equality comparisons are
2298 @item -Wtraditional @r{(C only)}
2299 @opindex Wtraditional
2300 Warn about certain constructs that behave differently in traditional and
2301 ISO C@. Also warn about ISO C constructs that have no traditional C
2302 equivalent, and/or problematic constructs which should be avoided.
2306 Macro parameters that appear within string literals in the macro body.
2307 In traditional C macro replacement takes place within string literals,
2308 but does not in ISO C@.
2311 In traditional C, some preprocessor directives did not exist.
2312 Traditional preprocessors would only consider a line to be a directive
2313 if the @samp{#} appeared in column 1 on the line. Therefore
2314 @option{-Wtraditional} warns about directives that traditional C
2315 understands but would ignore because the @samp{#} does not appear as the
2316 first character on the line. It also suggests you hide directives like
2317 @samp{#pragma} not understood by traditional C by indenting them. Some
2318 traditional implementations would not recognize @samp{#elif}, so it
2319 suggests avoiding it altogether.
2322 A function-like macro that appears without arguments.
2325 The unary plus operator.
2328 The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
2329 constant suffixes. (Traditional C does support the @samp{L} suffix on integer
2330 constants.) Note, these suffixes appear in macros defined in the system
2331 headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
2332 Use of these macros in user code might normally lead to spurious
2333 warnings, however gcc's integrated preprocessor has enough context to
2334 avoid warning in these cases.
2337 A function declared external in one block and then used after the end of
2341 A @code{switch} statement has an operand of type @code{long}.
2344 A non-@code{static} function declaration follows a @code{static} one.
2345 This construct is not accepted by some traditional C compilers.
2348 The ISO type of an integer constant has a different width or
2349 signedness from its traditional type. This warning is only issued if
2350 the base of the constant is ten. I.e.@: hexadecimal or octal values, which
2351 typically represent bit patterns, are not warned about.
2354 Usage of ISO string concatenation is detected.
2357 Initialization of automatic aggregates.
2360 Identifier conflicts with labels. Traditional C lacks a separate
2361 namespace for labels.
2364 Initialization of unions. If the initializer is zero, the warning is
2365 omitted. This is done under the assumption that the zero initializer in
2366 user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
2367 initializer warnings and relies on default initialization to zero in the
2371 Conversions by prototypes between fixed/floating point values and vice
2372 versa. The absence of these prototypes when compiling with traditional
2373 C would cause serious problems. This is a subset of the possible
2374 conversion warnings, for the full set use @option{-Wconversion}.
2379 Warn if an undefined identifier is evaluated in an @samp{#if} directive.
2383 Warn whenever a local variable shadows another local variable, parameter or
2384 global variable or whenever a built-in function is shadowed.
2386 @item -Wlarger-than-@var{len}
2387 @opindex Wlarger-than
2388 Warn whenever an object of larger than @var{len} bytes is defined.
2390 @item -Wpointer-arith
2391 @opindex Wpointer-arith
2392 Warn about anything that depends on the ``size of'' a function type or
2393 of @code{void}. GNU C assigns these types a size of 1, for
2394 convenience in calculations with @code{void *} pointers and pointers
2397 @item -Wbad-function-cast @r{(C only)}
2398 @opindex Wbad-function-cast
2399 Warn whenever a function call is cast to a non-matching type.
2400 For example, warn if @code{int malloc()} is cast to @code{anything *}.
2404 Warn whenever a pointer is cast so as to remove a type qualifier from
2405 the target type. For example, warn if a @code{const char *} is cast
2406 to an ordinary @code{char *}.
2409 @opindex Wcast-align
2410 Warn whenever a pointer is cast such that the required alignment of the
2411 target is increased. For example, warn if a @code{char *} is cast to
2412 an @code{int *} on machines where integers can only be accessed at
2413 two- or four-byte boundaries.
2415 @item -Wwrite-strings
2416 @opindex Wwrite-strings
2417 When compiling C, give string constants the type @code{const
2418 char[@var{length}]} so that
2419 copying the address of one into a non-@code{const} @code{char *}
2420 pointer will get a warning; when compiling C++, warn about the
2421 deprecated conversion from string constants to @code{char *}.
2422 These warnings will help you find at
2423 compile time code that can try to write into a string constant, but
2424 only if you have been very careful about using @code{const} in
2425 declarations and prototypes. Otherwise, it will just be a nuisance;
2426 this is why we did not make @option{-Wall} request these warnings.
2429 @opindex Wconversion
2430 Warn if a prototype causes a type conversion that is different from what
2431 would happen to the same argument in the absence of a prototype. This
2432 includes conversions of fixed point to floating and vice versa, and
2433 conversions changing the width or signedness of a fixed point argument
2434 except when the same as the default promotion.
2436 Also, warn if a negative integer constant expression is implicitly
2437 converted to an unsigned type. For example, warn about the assignment
2438 @code{x = -1} if @code{x} is unsigned. But do not warn about explicit
2439 casts like @code{(unsigned) -1}.
2441 @item -Wsign-compare
2442 @opindex Wsign-compare
2443 @cindex warning for comparison of signed and unsigned values
2444 @cindex comparison of signed and unsigned values, warning
2445 @cindex signed and unsigned values, comparison warning
2446 Warn when a comparison between signed and unsigned values could produce
2447 an incorrect result when the signed value is converted to unsigned.
2448 This warning is also enabled by @option{-W}; to get the other warnings
2449 of @option{-W} without this warning, use @samp{-W -Wno-sign-compare}.
2451 @item -Waggregate-return
2452 @opindex Waggregate-return
2453 Warn if any functions that return structures or unions are defined or
2454 called. (In languages where you can return an array, this also elicits
2457 @item -Wstrict-prototypes @r{(C only)}
2458 @opindex Wstrict-prototypes
2459 Warn if a function is declared or defined without specifying the
2460 argument types. (An old-style function definition is permitted without
2461 a warning if preceded by a declaration which specifies the argument
2464 @item -Wmissing-prototypes @r{(C only)}
2465 @opindex Wmissing-prototypes
2466 Warn if a global function is defined without a previous prototype
2467 declaration. This warning is issued even if the definition itself
2468 provides a prototype. The aim is to detect global functions that fail
2469 to be declared in header files.
2471 @item -Wmissing-declarations
2472 @opindex Wmissing-declarations
2473 Warn if a global function is defined without a previous declaration.
2474 Do so even if the definition itself provides a prototype.
2475 Use this option to detect global functions that are not declared in
2478 @item -Wmissing-noreturn
2479 @opindex Wmissing-noreturn
2480 Warn about functions which might be candidates for attribute @code{noreturn}.
2481 Note these are only possible candidates, not absolute ones. Care should
2482 be taken to manually verify functions actually do not ever return before
2483 adding the @code{noreturn} attribute, otherwise subtle code generation
2484 bugs could be introduced. You will not get a warning for @code{main} in
2485 hosted C environments.
2487 @item -Wmissing-format-attribute
2488 @opindex Wmissing-format-attribute
2490 If @option{-Wformat} is enabled, also warn about functions which might be
2491 candidates for @code{format} attributes. Note these are only possible
2492 candidates, not absolute ones. GCC will guess that @code{format}
2493 attributes might be appropriate for any function that calls a function
2494 like @code{vprintf} or @code{vscanf}, but this might not always be the
2495 case, and some functions for which @code{format} attributes are
2496 appropriate may not be detected. This option has no effect unless
2497 @option{-Wformat} is enabled (possibly by @option{-Wall}).
2499 @item -Wno-multichar
2500 @opindex Wno-multichar
2502 Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
2503 Usually they indicate a typo in the user's code, as they have
2504 implementation-defined values, and should not be used in portable code.
2506 @item -Wno-deprecated-declarations
2507 @opindex Wno-deprecated-declarations
2508 Do not warn about uses of functions, variables, and types marked as
2509 deprecated by using the @code{deprecated} attribute.
2510 (@pxref{Function Attributes}, @pxref{Variable Attributes},
2511 @pxref{Type Attributes}.)
2515 Warn if a structure is given the packed attribute, but the packed
2516 attribute has no effect on the layout or size of the structure.
2517 Such structures may be mis-aligned for little benefit. For
2518 instance, in this code, the variable @code{f.x} in @code{struct bar}
2519 will be misaligned even though @code{struct bar} does not itself
2520 have the packed attribute:
2527 @} __attribute__((packed));
2537 Warn if padding is included in a structure, either to align an element
2538 of the structure or to align the whole structure. Sometimes when this
2539 happens it is possible to rearrange the fields of the structure to
2540 reduce the padding and so make the structure smaller.
2542 @item -Wredundant-decls
2543 @opindex Wredundant-decls
2544 Warn if anything is declared more than once in the same scope, even in
2545 cases where multiple declaration is valid and changes nothing.
2547 @item -Wnested-externs @r{(C only)}
2548 @opindex Wnested-externs
2549 Warn if an @code{extern} declaration is encountered within a function.
2551 @item -Wunreachable-code
2552 @opindex Wunreachable-code
2553 Warn if the compiler detects that code will never be executed.
2555 This option is intended to warn when the compiler detects that at
2556 least a whole line of source code will never be executed, because
2557 some condition is never satisfied or because it is after a
2558 procedure that never returns.
2560 It is possible for this option to produce a warning even though there
2561 are circumstances under which part of the affected line can be executed,
2562 so care should be taken when removing apparently-unreachable code.
2564 For instance, when a function is inlined, a warning may mean that the
2565 line is unreachable in only one inlined copy of the function.
2567 This option is not made part of @option{-Wall} because in a debugging
2568 version of a program there is often substantial code which checks
2569 correct functioning of the program and is, hopefully, unreachable
2570 because the program does work. Another common use of unreachable
2571 code is to provide behavior which is selectable at compile-time.
2575 Warn if a function can not be inlined and it was declared as inline.
2579 @opindex Wno-long-long
2580 Warn if @samp{long long} type is used. This is default. To inhibit
2581 the warning messages, use @option{-Wno-long-long}. Flags
2582 @option{-Wlong-long} and @option{-Wno-long-long} are taken into account
2583 only when @option{-pedantic} flag is used.
2585 @item -Wdisabled-optimization
2586 @opindex Wdisabled-optimization
2587 Warn if a requested optimization pass is disabled. This warning does
2588 not generally indicate that there is anything wrong with your code; it
2589 merely indicates that GCC's optimizers were unable to handle the code
2590 effectively. Often, the problem is that your code is too big or too
2591 complex; GCC will refuse to optimize programs when the optimization
2592 itself is likely to take inordinate amounts of time.
2596 Make all warnings into errors.
2599 @node Debugging Options
2600 @section Options for Debugging Your Program or GCC
2601 @cindex options, debugging
2602 @cindex debugging information options
2604 GCC has various special options that are used for debugging
2605 either your program or GCC:
2610 Produce debugging information in the operating system's native format
2611 (stabs, COFF, XCOFF, or DWARF)@. GDB can work with this debugging
2614 On most systems that use stabs format, @option{-g} enables use of extra
2615 debugging information that only GDB can use; this extra information
2616 makes debugging work better in GDB but will probably make other debuggers
2618 refuse to read the program. If you want to control for certain whether
2619 to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
2620 @option{-gxcoff+}, @option{-gxcoff}, @option{-gdwarf-1+}, @option{-gdwarf-1},
2621 or @option{-gvms} (see below).
2623 Unlike most other C compilers, GCC allows you to use @option{-g} with
2624 @option{-O}. The shortcuts taken by optimized code may occasionally
2625 produce surprising results: some variables you declared may not exist
2626 at all; flow of control may briefly move where you did not expect it;
2627 some statements may not be executed because they compute constant
2628 results or their values were already at hand; some statements may
2629 execute in different places because they were moved out of loops.
2631 Nevertheless it proves possible to debug optimized output. This makes
2632 it reasonable to use the optimizer for programs that might have bugs.
2634 The following options are useful when GCC is generated with the
2635 capability for more than one debugging format.
2639 Produce debugging information for use by GDB@. This means to use the
2640 most expressive format available (DWARF 2, stabs, or the native format
2641 if neither of those are supported), including GDB extensions if at all
2646 Produce debugging information in stabs format (if that is supported),
2647 without GDB extensions. This is the format used by DBX on most BSD
2648 systems. On MIPS, Alpha and System V Release 4 systems this option
2649 produces stabs debugging output which is not understood by DBX or SDB@.
2650 On System V Release 4 systems this option requires the GNU assembler.
2654 Produce debugging information in stabs format (if that is supported),
2655 using GNU extensions understood only by the GNU debugger (GDB)@. The
2656 use of these extensions is likely to make other debuggers crash or
2657 refuse to read the program.
2661 Produce debugging information in COFF format (if that is supported).
2662 This is the format used by SDB on most System V systems prior to
2667 Produce debugging information in XCOFF format (if that is supported).
2668 This is the format used by the DBX debugger on IBM RS/6000 systems.
2672 Produce debugging information in XCOFF format (if that is supported),
2673 using GNU extensions understood only by the GNU debugger (GDB)@. The
2674 use of these extensions is likely to make other debuggers crash or
2675 refuse to read the program, and may cause assemblers other than the GNU
2676 assembler (GAS) to fail with an error.
2680 Produce debugging information in DWARF version 1 format (if that is
2681 supported). This is the format used by SDB on most System V Release 4
2686 Produce debugging information in DWARF version 1 format (if that is
2687 supported), using GNU extensions understood only by the GNU debugger
2688 (GDB)@. The use of these extensions is likely to make other debuggers
2689 crash or refuse to read the program.
2693 Produce debugging information in DWARF version 2 format (if that is
2694 supported). This is the format used by DBX on IRIX 6.
2698 Produce debugging information in VMS debug format (if that is
2699 supported). This is the format used by DEBUG on VMS systems.
2702 @itemx -ggdb@var{level}
2703 @itemx -gstabs@var{level}
2704 @itemx -gcoff@var{level}
2705 @itemx -gxcoff@var{level}
2706 @itemx -gdwarf@var{level}
2707 @itemx -gdwarf-2@var{level}
2708 @itemx -gvms@var{level}
2709 Request debugging information and also use @var{level} to specify how
2710 much information. The default level is 2.
2712 Level 1 produces minimal information, enough for making backtraces in
2713 parts of the program that you don't plan to debug. This includes
2714 descriptions of functions and external variables, but no information
2715 about local variables and no line numbers.
2717 Level 3 includes extra information, such as all the macro definitions
2718 present in the program. Some debuggers support macro expansion when
2719 you use @option{-g3}.
2724 Generate extra code to write profile information suitable for the
2725 analysis program @code{prof}. You must use this option when compiling
2726 the source files you want data about, and you must also use it when
2729 @cindex @code{gprof}
2732 Generate extra code to write profile information suitable for the
2733 analysis program @code{gprof}. You must use this option when compiling
2734 the source files you want data about, and you must also use it when
2740 Generate extra code to write profile information for basic blocks, which will
2741 record the number of times each basic block is executed, the basic block start
2742 address, and the function name containing the basic block. If @option{-g} is
2743 used, the line number and filename of the start of the basic block will also be
2744 recorded. If not overridden by the machine description, the default action is
2745 to append to the text file @file{bb.out}.
2747 This data could be analyzed by a program like @code{tcov}. Note,
2748 however, that the format of the data is not what @code{tcov} expects.
2749 Eventually GNU @code{gprof} should be extended to process this data.
2753 Makes the compiler print out each function name as it is compiled, and
2754 print some statistics about each pass when it finishes.
2757 @opindex ftime-report
2758 Makes the compiler print some statistics about the time consumed by each
2759 pass when it finishes.
2762 @opindex fmem-report
2763 Makes the compiler print some statistics about permanent memory
2764 allocation when it finishes.
2766 @item -fprofile-arcs
2767 @opindex fprofile-arcs
2768 Instrument @dfn{arcs} during compilation to generate coverage data
2769 or for profile-directed block ordering. During execution the program
2770 records how many times each branch is executed and how many times it is
2771 taken. When the compiled program exits it saves this data to a file
2772 called @file{@var{sourcename}.da} for each source file.
2774 For profile-directed block ordering, compile the program with
2775 @option{-fprofile-arcs} plus optimization and code generation options,
2776 generate the arc profile information by running the program on a
2777 selected workload, and then compile the program again with the same
2778 optimization and code generation options plus
2779 @option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
2780 Control Optimization}).
2782 The other use of @option{-fprofile-arcs} is for use with @code{gcov},
2783 when it is used with the @option{-ftest-coverage} option. GCC
2784 supports two methods of determining code coverage: the options that
2785 support @code{gcov}, and options @option{-a} and @option{-ax}, which
2786 write information to text files. The options that support @code{gcov}
2787 do not need to instrument every arc in the program, so a program compiled
2788 with them runs faster than a program compiled with @option{-a}, which
2789 adds instrumentation code to every basic block in the program. The
2790 tradeoff: since @code{gcov} does not have execution counts for all
2791 branches, it must start with the execution counts for the instrumented
2792 branches, and then iterate over the program flow graph until the entire
2793 graph has been solved. Hence, @code{gcov} runs a little more slowly than
2794 a program which uses information from @option{-a} and @option{-ax}.
2796 With @option{-fprofile-arcs}, for each function of your program GCC
2797 creates a program flow graph, then finds a spanning tree for the graph.
2798 Only arcs that are not on the spanning tree have to be instrumented: the
2799 compiler adds code to count the number of times that these arcs are
2800 executed. When an arc is the only exit or only entrance to a block, the
2801 instrumentation code can be added to the block; otherwise, a new basic
2802 block must be created to hold the instrumentation code.
2804 This option makes it possible to estimate branch probabilities and to
2805 calculate basic block execution counts. In general, basic block
2806 execution counts as provided by @option{-a} do not give enough
2807 information to estimate all branch probabilities.
2810 @item -ftest-coverage
2811 @opindex ftest-coverage
2812 Create data files for the @code{gcov} code-coverage utility
2813 (@pxref{Gcov,, @code{gcov}: a GCC Test Coverage Program}).
2814 The data file names begin with the name of your source file:
2817 @item @var{sourcename}.bb
2818 A mapping from basic blocks to line numbers, which @code{gcov} uses to
2819 associate basic block execution counts with line numbers.
2821 @item @var{sourcename}.bbg
2822 A list of all arcs in the program flow graph. This allows @code{gcov}
2823 to reconstruct the program flow graph, so that it can compute all basic
2824 block and arc execution counts from the information in the
2825 @code{@var{sourcename}.da} file.
2828 Use @option{-ftest-coverage} with @option{-fprofile-arcs}; the latter
2829 option adds instrumentation to the program, which then writes
2830 execution counts to another data file:
2833 @item @var{sourcename}.da
2834 Runtime arc execution counts, used in conjunction with the arc
2835 information in the file @code{@var{sourcename}.bbg}.
2838 Coverage data will map better to the source files if
2839 @option{-ftest-coverage} is used without optimization.
2841 @item -d@var{letters}
2843 Says to make debugging dumps during compilation at times specified by
2844 @var{letters}. This is used for debugging the compiler. The file names
2845 for most of the dumps are made by appending a pass number and a word to
2846 the source file name (e.g. @file{foo.c.00.rtl} or @file{foo.c.01.sibling}).
2847 Here are the possible letters for use in @var{letters}, and their meanings:
2852 Annotate the assembler output with miscellaneous debugging information.
2855 Dump after computing branch probabilities, to @file{@var{file}.15.bp}.
2858 Dump after block reordering, to @file{@var{file}.30.bbro}.
2861 Dump after instruction combination, to the file @file{@var{file}.17.combine}.
2864 Dump after the first if conversion, to the file @file{@var{file}.18.ce}.
2867 Dump after delayed branch scheduling, to @file{@var{file}.32.dbr}.
2870 Dump all macro definitions, at the end of preprocessing, in addition to
2874 Dump after SSA optimizations, to @file{@var{file}.04.ssa} and
2875 @file{@var{file}.07.ussa}.
2878 Dump after the second if conversion, to @file{@var{file}.27.ce2}.
2881 Dump after life analysis, to @file{@var{file}.16.life}.
2884 Dump after purging @code{ADDRESSOF} codes, to @file{@var{file}.10.addressof}.
2887 Dump after global register allocation, to @file{@var{file}.22.greg}.
2890 Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
2893 Dump after reg-to-stack conversion, to @file{@var{file}.29.stack}.
2896 Dump after post-reload optimizations, to @file{@var{file}.23.postreload}.
2899 Dump after GCSE, to @file{@var{file}.11.gcse}.
2902 Dump after sibling call optimizations, to @file{@var{file}.01.sibling}.
2905 Dump after the first jump optimization, to @file{@var{file}.03.jump}.
2908 Dump after conversion from registers to stack, to @file{@var{file}.33.stack}.
2911 Dump after local register allocation, to @file{@var{file}.21.lreg}.
2914 Dump after loop optimization, to @file{@var{file}.12.loop}.
2917 Dump after performing the machine dependent reorganisation pass, to
2918 @file{@var{file}.31.mach}.
2921 Dump after register renumbering, to @file{@var{file}.26.rnreg}.
2924 Dump after the register move pass, to @file{@var{file}.19.regmove}.
2927 Dump after RTL generation, to @file{@var{file}.00.rtl}.
2930 Dump after the second scheduling pass, to @file{@var{file}.28.sched2}.
2933 Dump after CSE (including the jump optimization that sometimes follows
2934 CSE), to @file{@var{file}.09.cse}.
2937 Dump after the first scheduling pass, to @file{@var{file}.20.sched}.
2940 Dump after the second CSE pass (including the jump optimization that
2941 sometimes follows CSE), to @file{@var{file}.13.cse2}.
2944 Dump after null pointer ellimination pass ti @file{@var{file}.08.null}.
2947 Dump after the second flow pass, to @file{@var{file}.24.flow2}.
2950 Dump after SSA dead code elimination, to @file{@var{file}.06.ssadce}.
2953 Dump after the peephole pass, to @file{@var{file}.25.peephole2}.
2956 Produce all the dumps listed above.
2959 Print statistics on memory usage, at the end of the run, to
2963 Annotate the assembler output with a comment indicating which
2964 pattern and alternative was used. The length of each instruction is
2968 Dump the RTL in the assembler output as a comment before each instruction.
2969 Also turns on @option{-dp} annotation.
2972 For each of the other indicated dump files (except for
2973 @file{@var{file}.00.rtl}), dump a representation of the control flow graph
2974 suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
2977 Just generate RTL for a function instead of compiling it. Usually used
2981 Dump debugging information during parsing, to standard error.
2984 @item -fdump-unnumbered
2985 @opindex fdump-unnumbered
2986 When doing debugging dumps (see @option{-d} option above), suppress instruction
2987 numbers and line number note output. This makes it more feasible to
2988 use diff on debugging dumps for compiler invocations with different
2989 options, in particular with and without @option{-g}.
2991 @item -fdump-translation-unit @r{(C and C++ only)}
2992 @itemx -fdump-translation-unit-@var{options} @r{(C and C++ only)}
2993 @opindex fdump-translation-unit
2994 Dump a representation of the tree structure for the entire translation
2995 unit to a file. The file name is made by appending @file{.tu} to the
2996 source file name. If the @samp{-@var{options}} form is used, @var{options}
2997 controls the details of the dump as described for the
2998 @option{-fdump-tree} options.
3000 @item -fdump-class-hierarchy @r{(C++ only)}
3001 @itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
3002 @opindex fdump-class-hierarchy
3003 Dump a representation of each class's hierarchy and virtual function
3004 table layout to a file. The file name is made by appending @file{.class}
3005 to the source file name. If the @samp{-@var{options}} form is used,
3006 @var{options} controls the details of the dump as described for the
3007 @option{-fdump-tree} options.
3009 @item -fdump-tree-@var{switch} @r{(C++ only)}
3010 @itemx -fdump-tree-@var{switch}-@var{options} @r{(C++ only)}
3012 Control the dumping at various stages of processing the intermediate
3013 language tree to a file. The file name is generated by appending a switch
3014 specific suffix to the source file name. If the @samp{-@var{options}}
3015 form is used, @var{options} is a list of @samp{-} separated options that
3016 control the details of the dump. Not all options are applicable to all
3017 dumps, those which are not meaningful will be ignored. The following
3018 options are available
3022 Print the address of each node. Usually this is not meaningful as it
3023 changes according to the environment and source file. Its primary use
3024 is for tying up a dump file with a debug environment.
3026 Inhibit dumping of members of a scope or body of a function merely
3027 because that scope has been reached. Only dump such items when they
3028 are directly reachable by some other path.
3030 Turn on all options.
3033 The following tree dumps are possible:
3036 Dump before any tree based optimization, to @file{@var{file}.original}.
3038 Dump after all tree based optimization, to @file{@var{file}.optimized}.
3040 Dump after function inlining, to @file{@var{file}.inlined}.
3045 Store the usual ``temporary'' intermediate files permanently; place them
3046 in the current directory and name them based on the source file. Thus,
3047 compiling @file{foo.c} with @samp{-c -save-temps} would produce files
3048 @file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
3049 preprocessed @file{foo.i} output file even though the compiler now
3050 normally uses an integrated preprocessor.
3054 Report the CPU time taken by each subprocess in the compilation
3055 sequence. For C source files, this is the compiler proper and assembler
3056 (plus the linker if linking is done). The output looks like this:
3063 The first number on each line is the ``user time,'' that is time spent
3064 executing the program itself. The second number is ``system time,''
3065 time spent executing operating system routines on behalf of the program.
3066 Both numbers are in seconds.
3068 @item -print-file-name=@var{library}
3069 @opindex print-file-name
3070 Print the full absolute name of the library file @var{library} that
3071 would be used when linking---and don't do anything else. With this
3072 option, GCC does not compile or link anything; it just prints the
3075 @item -print-multi-directory
3076 @opindex print-multi-directory
3077 Print the directory name corresponding to the multilib selected by any
3078 other switches present in the command line. This directory is supposed
3079 to exist in @env{GCC_EXEC_PREFIX}.
3081 @item -print-multi-lib
3082 @opindex print-multi-lib
3083 Print the mapping from multilib directory names to compiler switches
3084 that enable them. The directory name is separated from the switches by
3085 @samp{;}, and each switch starts with an @samp{@@} instead of the
3086 @samp{-}, without spaces between multiple switches. This is supposed to
3087 ease shell-processing.
3089 @item -print-prog-name=@var{program}
3090 @opindex print-prog-name
3091 Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
3093 @item -print-libgcc-file-name
3094 @opindex print-libgcc-file-name
3095 Same as @option{-print-file-name=libgcc.a}.
3097 This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
3098 but you do want to link with @file{libgcc.a}. You can do
3101 gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
3104 @item -print-search-dirs
3105 @opindex print-search-dirs
3106 Print the name of the configured installation directory and a list of
3107 program and library directories gcc will search---and don't do anything else.
3109 This is useful when gcc prints the error message
3110 @samp{installation problem, cannot exec cpp0: No such file or directory}.
3111 To resolve this you either need to put @file{cpp0} and the other compiler
3112 components where gcc expects to find them, or you can set the environment
3113 variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
3114 Don't forget the trailing '/'.
3115 @xref{Environment Variables}.
3118 @opindex dumpmachine
3119 Print the compiler's target machine (for example,
3120 @samp{i686-pc-linux-gnu})---and don't do anything else.
3123 @opindex dumpversion
3124 Print the compiler version (for example, @samp{3.0})---and don't do
3129 Print the compiler's built-in specs---and don't do anything else. (This
3130 is used when GCC itself is being built.) @xref{Spec Files}.
3133 @node Optimize Options
3134 @section Options That Control Optimization
3135 @cindex optimize options
3136 @cindex options, optimization
3138 These options control various sorts of optimizations:
3145 Optimize. Optimizing compilation takes somewhat more time, and a lot
3146 more memory for a large function.
3148 Without @option{-O}, the compiler's goal is to reduce the cost of
3149 compilation and to make debugging produce the expected results.
3150 Statements are independent: if you stop the program with a breakpoint
3151 between statements, you can then assign a new value to any variable or
3152 change the program counter to any other statement in the function and
3153 get exactly the results you would expect from the source code.
3155 With @option{-O}, the compiler tries to reduce code size and execution
3156 time, without performing any optimizations that take a great deal of
3161 Optimize even more. GCC performs nearly all supported optimizations
3162 that do not involve a space-speed tradeoff. The compiler does not
3163 perform loop unrolling or function inlining when you specify @option{-O2}.
3164 As compared to @option{-O}, this option increases both compilation time
3165 and the performance of the generated code.
3167 @option{-O2} turns on all optional optimizations except for loop unrolling,
3168 function inlining, and register renaming. It also turns on the
3169 @option{-fforce-mem} option on all machines and frame pointer elimination
3170 on machines where doing so does not interfere with debugging.
3172 Please note the warning under @option{-fgcse} about
3173 invoking @option{-O2} on programs that use computed gotos.
3177 Optimize yet more. @option{-O3} turns on all optimizations specified by
3178 @option{-O2} and also turns on the @option{-finline-functions} and
3179 @option{-frename-registers} options.
3187 Optimize for size. @option{-Os} enables all @option{-O2} optimizations that
3188 do not typically increase code size. It also performs further
3189 optimizations designed to reduce code size.
3191 If you use multiple @option{-O} options, with or without level numbers,
3192 the last such option is the one that is effective.
3195 Options of the form @option{-f@var{flag}} specify machine-independent
3196 flags. Most flags have both positive and negative forms; the negative
3197 form of @option{-ffoo} would be @option{-fno-foo}. In the table below,
3198 only one of the forms is listed---the one which is not the default.
3199 You can figure out the other form by either removing @samp{no-} or
3204 @opindex ffloat-store
3205 Do not store floating point variables in registers, and inhibit other
3206 options that might change whether a floating point value is taken from a
3209 @cindex floating point precision
3210 This option prevents undesirable excess precision on machines such as
3211 the 68000 where the floating registers (of the 68881) keep more
3212 precision than a @code{double} is supposed to have. Similarly for the
3213 x86 architecture. For most programs, the excess precision does only
3214 good, but a few programs rely on the precise definition of IEEE floating
3215 point. Use @option{-ffloat-store} for such programs, after modifying
3216 them to store all pertinent intermediate computations into variables.
3218 @item -fno-default-inline
3219 @opindex fno-default-inline
3220 Do not make member functions inline by default merely because they are
3221 defined inside the class scope (C++ only). Otherwise, when you specify
3222 @w{@option{-O}}, member functions defined inside class scope are compiled
3223 inline by default; i.e., you don't need to add @samp{inline} in front of
3224 the member function name.
3226 @item -fno-defer-pop
3227 @opindex fno-defer-pop
3228 Always pop the arguments to each function call as soon as that function
3229 returns. For machines which must pop arguments after a function call,
3230 the compiler normally lets arguments accumulate on the stack for several
3231 function calls and pops them all at once.
3235 Force memory operands to be copied into registers before doing
3236 arithmetic on them. This produces better code by making all memory
3237 references potential common subexpressions. When they are not common
3238 subexpressions, instruction combination should eliminate the separate
3239 register-load. The @option{-O2} option turns on this option.
3242 @opindex fforce-addr
3243 Force memory address constants to be copied into registers before
3244 doing arithmetic on them. This may produce better code just as
3245 @option{-fforce-mem} may.
3247 @item -fomit-frame-pointer
3248 @opindex fomit-frame-pointer
3249 Don't keep the frame pointer in a register for functions that
3250 don't need one. This avoids the instructions to save, set up and
3251 restore frame pointers; it also makes an extra register available
3252 in many functions. @strong{It also makes debugging impossible on
3255 On some machines, such as the VAX, this flag has no effect, because
3256 the standard calling sequence automatically handles the frame pointer
3257 and nothing is saved by pretending it doesn't exist. The
3258 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
3259 whether a target machine supports this flag. @xref{Registers,,Register
3260 Usage, gccint, GNU Compiler Collection (GCC) Internals}.
3262 @item -foptimize-sibling-calls
3263 @opindex foptimize-sibling-calls
3264 Optimize sibling and tail recursive calls.
3268 This option generates traps for signed overflow on addition, subtraction,
3269 multiplication operations.
3273 Don't pay attention to the @code{inline} keyword. Normally this option
3274 is used to keep the compiler from expanding any functions inline.
3275 Note that if you are not optimizing, no functions can be expanded inline.
3277 @item -finline-functions
3278 @opindex finline-functions
3279 Integrate all simple functions into their callers. The compiler
3280 heuristically decides which functions are simple enough to be worth
3281 integrating in this way.
3283 If all calls to a given function are integrated, and the function is
3284 declared @code{static}, then the function is normally not output as
3285 assembler code in its own right.
3287 @item -finline-limit=@var{n}
3288 @opindex finline-limit
3289 By default, gcc limits the size of functions that can be inlined. This flag
3290 allows the control of this limit for functions that are explicitly marked as
3291 inline (ie marked with the inline keyword or defined within the class
3292 definition in c++). @var{n} is the size of functions that can be inlined in
3293 number of pseudo instructions (not counting parameter handling). The default
3294 value of @var{n} is 600.
3295 Increasing this value can result in more inlined code at
3296 the cost of compilation time and memory consumption. Decreasing usually makes
3297 the compilation faster and less code will be inlined (which presumably
3298 means slower programs). This option is particularly useful for programs that
3299 use inlining heavily such as those based on recursive templates with C++.
3301 @emph{Note:} pseudo instruction represents, in this particular context, an
3302 abstract measurement of function's size. In no way, it represents a count
3303 of assembly instructions and as such its exact meaning might change from one
3304 release to an another.
3306 @item -fkeep-inline-functions
3307 @opindex fkeep-inline-functions
3308 Even if all calls to a given function are integrated, and the function
3309 is declared @code{static}, nevertheless output a separate run-time
3310 callable version of the function. This switch does not affect
3311 @code{extern inline} functions.
3313 @item -fkeep-static-consts
3314 @opindex fkeep-static-consts
3315 Emit variables declared @code{static const} when optimization isn't turned
3316 on, even if the variables aren't referenced.
3318 GCC enables this option by default. If you want to force the compiler to
3319 check if the variable was referenced, regardless of whether or not
3320 optimization is turned on, use the @option{-fno-keep-static-consts} option.
3322 @item -fmerge-constants
3323 Attempt to merge identical constants (string constants and floating point
3324 constants) accross compilation units.
3326 This option is default for optimized compilation if assembler and linker
3327 support it. Use @option{-fno-merge-constants} to inhibit this behavior.
3329 @item -fmerge-all-constants
3330 Attempt to merge identical constants and identical variables.
3332 This option implies @option{-fmerge-constants}. In addition to
3333 @option{-fmerge-constants} this considers e.g. even constant initialized
3334 arrays or initialized constant variables with integral or floating point
3335 types. Languages like C or C++ require each non-automatic variable to
3336 have distinct location, so using this option will result in non-conforming
3339 @item -fno-function-cse
3340 @opindex fno-function-cse
3341 Do not put function addresses in registers; make each instruction that
3342 calls a constant function contain the function's address explicitly.
3344 This option results in less efficient code, but some strange hacks
3345 that alter the assembler output may be confused by the optimizations
3346 performed when this option is not used.
3350 Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, and @*
3351 @option{-fno-trapping-math}.
3353 This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
3355 This option should never be turned on by any @option{-O} option since
3356 it can result in incorrect output for programs which depend on
3357 an exact implementation of IEEE or ISO rules/specifications for
3360 @item -fno-math-errno
3361 @opindex fno-math-errno
3362 Do not set ERRNO after calling math functions that are executed
3363 with a single instruction, e.g., sqrt. A program that relies on
3364 IEEE exceptions for math error handling may want to use this flag
3365 for speed while maintaining IEEE arithmetic compatibility.
3367 This option should never be turned on by any @option{-O} option since
3368 it can result in incorrect output for programs which depend on
3369 an exact implementation of IEEE or ISO rules/specifications for
3372 The default is @option{-fmath-errno}.
3374 @item -funsafe-math-optimizations
3375 @opindex funsafe-math-optimizations
3376 Allow optimizations for floating-point arithmetic that (a) assume
3377 that arguments and results are valid and (b) may violate IEEE or
3378 ANSI standards. When used at link-time, it may include libraries
3379 or startup files that change the default FPU control word or other
3380 similar optimizations.
3382 This option should never be turned on by any @option{-O} option since
3383 it can result in incorrect output for programs which depend on
3384 an exact implementation of IEEE or ISO rules/specifications for
3387 The default is @option{-fno-unsafe-math-optimizations}.
3389 @item -fno-trapping-math
3390 @opindex fno-trapping-math
3391 Compile code assuming that floating-point operations cannot generate
3392 user-visible traps. Setting this option may allow faster code
3393 if one relies on ``non-stop'' IEEE arithmetic, for example.
3395 This option should never be turned on by any @option{-O} option since
3396 it can result in incorrect output for programs which depend on
3397 an exact implementation of IEEE or ISO rules/specifications for
3400 The default is @option{-ftrapping-math}.
3402 @item -fno-zero-initialized-in-bss
3403 @opindex fno-zero-initialized-in-bss
3404 If the target supports a BSS section, GCC by default puts variables that
3405 are initialized to zero into BSS@. This can save space in the resulting
3408 This option turns off this behavior because some programs explicitly
3409 rely on variables going to the data section. E.g., so that the
3410 resulting executable can find the beginning of that section and/or make
3411 assumptions based on that.
3413 The default is @option{-fzero-initialized-in-bss}.
3416 The following options control specific optimizations. The @option{-O2}
3417 option turns on all of these optimizations except @option{-funroll-loops}
3418 and @option{-funroll-all-loops}. On most machines, the @option{-O} option
3419 turns on the @option{-fthread-jumps} and @option{-fdelayed-branch} options,
3420 but specific machines may handle it differently.
3422 You can use the following flags in the rare cases when ``fine-tuning''
3423 of optimizations to be performed is desired.
3425 Not all of the optimizations performed by GCC have @option{-f} options
3429 @item -fstrength-reduce
3430 @opindex fstrength-reduce
3431 Perform the optimizations of loop strength reduction and
3432 elimination of iteration variables.
3434 @item -fthread-jumps
3435 @opindex fthread-jumps
3436 Perform optimizations where we check to see if a jump branches to a
3437 location where another comparison subsumed by the first is found. If
3438 so, the first branch is redirected to either the destination of the
3439 second branch or a point immediately following it, depending on whether
3440 the condition is known to be true or false.
3442 @item -fcse-follow-jumps
3443 @opindex fcse-follow-jumps
3444 In common subexpression elimination, scan through jump instructions
3445 when the target of the jump is not reached by any other path. For
3446 example, when CSE encounters an @code{if} statement with an
3447 @code{else} clause, CSE will follow the jump when the condition
3450 @item -fcse-skip-blocks
3451 @opindex fcse-skip-blocks
3452 This is similar to @option{-fcse-follow-jumps}, but causes CSE to
3453 follow jumps which conditionally skip over blocks. When CSE
3454 encounters a simple @code{if} statement with no else clause,
3455 @option{-fcse-skip-blocks} causes CSE to follow the jump around the
3456 body of the @code{if}.
3458 @item -frerun-cse-after-loop
3459 @opindex frerun-cse-after-loop
3460 Re-run common subexpression elimination after loop optimizations has been
3463 @item -frerun-loop-opt
3464 @opindex frerun-loop-opt
3465 Run the loop optimizer twice.
3469 Perform a global common subexpression elimination pass.
3470 This pass also performs global constant and copy propagation.
3472 @emph{Note:} When compiling a program using computed gotos, a GCC
3473 extension, you may get better runtime performance if you disable
3474 the global common subexpression elmination pass by adding
3475 @option{-fno-gcse} to the command line.
3479 When @option{-fgcse-lm} is enabled, global common subexpression elimination will
3480 attempt to move loads which are only killed by stores into themselves. This
3481 allows a loop containing a load/store sequence to be changed to a load outside
3482 the loop, and a copy/store within the loop.
3486 When @option{-fgcse-sm} is enabled, A store motion pass is run after global common
3487 subexpression elimination. This pass will attempt to move stores out of loops.
3488 When used in conjunction with @option{-fgcse-lm}, loops containing a load/store sequence
3489 can be changed to a load before the loop and a store after the loop.
3491 @item -fdelete-null-pointer-checks
3492 @opindex fdelete-null-pointer-checks
3493 Use global dataflow analysis to identify and eliminate useless checks
3494 for null pointers. The compiler assumes that dereferencing a null
3495 pointer would have halted the program. If a pointer is checked after
3496 it has already been dereferenced, it cannot be null.
3498 In some environments, this assumption is not true, and programs can
3499 safely dereference null pointers. Use
3500 @option{-fno-delete-null-pointer-checks} to disable this optimization
3501 for programs which depend on that behavior.
3503 @item -fexpensive-optimizations
3504 @opindex fexpensive-optimizations
3505 Perform a number of minor optimizations that are relatively expensive.
3507 @item -foptimize-register-move
3509 @opindex foptimize-register-move
3511 Attempt to reassign register numbers in move instructions and as
3512 operands of other simple instructions in order to maximize the amount of
3513 register tying. This is especially helpful on machines with two-operand
3514 instructions. GCC enables this optimization by default with @option{-O2}
3517 Note @option{-fregmove} and @option{-foptimize-register-move} are the same
3520 @item -fdelayed-branch
3521 @opindex fdelayed-branch
3522 If supported for the target machine, attempt to reorder instructions
3523 to exploit instruction slots available after delayed branch
3526 @item -fschedule-insns
3527 @opindex fschedule-insns
3528 If supported for the target machine, attempt to reorder instructions to
3529 eliminate execution stalls due to required data being unavailable. This
3530 helps machines that have slow floating point or memory load instructions
3531 by allowing other instructions to be issued until the result of the load
3532 or floating point instruction is required.
3534 @item -fschedule-insns2
3535 @opindex fschedule-insns2
3536 Similar to @option{-fschedule-insns}, but requests an additional pass of
3537 instruction scheduling after register allocation has been done. This is
3538 especially useful on machines with a relatively small number of
3539 registers and where memory load instructions take more than one cycle.
3541 @item -ffunction-sections
3542 @itemx -fdata-sections
3543 @opindex ffunction-sections
3544 @opindex fdata-sections
3545 Place each function or data item into its own section in the output
3546 file if the target supports arbitrary sections. The name of the
3547 function or the name of the data item determines the section's name
3550 Use these options on systems where the linker can perform optimizations
3551 to improve locality of reference in the instruction space. HPPA
3552 processors running HP-UX and Sparc processors running Solaris 2 have
3553 linkers with such optimizations. Other systems using the ELF object format
3554 as well as AIX may have these optimizations in the future.
3556 Only use these options when there are significant benefits from doing
3557 so. When you specify these options, the assembler and linker will
3558 create larger object and executable files and will also be slower.
3559 You will not be able to use @code{gprof} on all systems if you
3560 specify this option and you may have problems with debugging if
3561 you specify both this option and @option{-g}.
3563 @item -fcaller-saves
3564 @opindex fcaller-saves
3565 Enable values to be allocated in registers that will be clobbered by
3566 function calls, by emitting extra instructions to save and restore the
3567 registers around such calls. Such allocation is done only when it
3568 seems to result in better code than would otherwise be produced.
3570 This option is always enabled by default on certain machines, usually
3571 those which have no call-preserved registers to use instead.
3573 For all machines, optimization level 2 and higher enables this flag by
3576 @item -funroll-loops
3577 @opindex funroll-loops
3578 Unroll loops whose number of iterations can be determined at compile
3579 time or upon entry to the loop. @option{-funroll-loops} implies both
3580 @option{-fstrength-reduce} and @option{-frerun-cse-after-loop}. This
3581 option makes code larger, and may or may not make it run faster.
3583 @item -funroll-all-loops
3584 @opindex funroll-all-loops
3585 Unroll all loops, even if their number of iterations is uncertain when
3586 the loop is entered. This usually makes programs run more slowly.
3587 @option{-funroll-all-loops} implies the same options as
3588 @option{-funroll-loops},
3590 @item -fprefetch-loop-arrays
3591 @opindex fprefetch-loop-arrays
3592 If supported by the target machine, generate instructions to prefetch
3593 memory to improve the performance of loops that access large arrays.
3595 @item -fmove-all-movables
3596 @opindex fmove-all-movables
3597 Forces all invariant computations in loops to be moved
3600 @item -freduce-all-givs
3601 @opindex freduce-all-givs
3602 Forces all general-induction variables in loops to be
3605 @emph{Note:} When compiling programs written in Fortran,
3606 @option{-fmove-all-movables} and @option{-freduce-all-givs} are enabled
3607 by default when you use the optimizer.
3609 These options may generate better or worse code; results are highly
3610 dependent on the structure of loops within the source code.
3612 These two options are intended to be removed someday, once
3613 they have helped determine the efficacy of various
3614 approaches to improving loop optimizations.
3616 Please let us (@w{@email{gcc@@gcc.gnu.org}} and @w{@email{fortran@@gnu.org}})
3617 know how use of these options affects
3618 the performance of your production code.
3619 We're very interested in code that runs @emph{slower}
3620 when these options are @emph{enabled}.
3623 @itemx -fno-peephole2
3624 @opindex fno-peephole
3625 @opindex fno-peephole2
3626 Disable any machine-specific peephole optimizations. The difference
3627 between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
3628 are implemented in the compiler; some targets use one, some use the
3629 other, a few use both.
3631 @item -fbranch-probabilities
3632 @opindex fbranch-probabilities
3633 After running a program compiled with @option{-fprofile-arcs}
3634 (@pxref{Debugging Options,, Options for Debugging Your Program or
3635 @command{gcc}}), you can compile it a second time using
3636 @option{-fbranch-probabilities}, to improve optimizations based on
3637 the number of times each branch was taken. When the program
3638 compiled with @option{-fprofile-arcs} exits it saves arc execution
3639 counts to a file called @file{@var{sourcename}.da} for each source
3640 file The information in this data file is very dependent on the
3641 structure of the generated code, so you must use the same source code
3642 and the same optimization options for both compilations.
3644 With @option{-fbranch-probabilities}, GCC puts a @samp{REG_EXEC_COUNT}
3645 note on the first instruction of each basic block, and a
3646 @samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
3647 These can be used to improve optimization. Currently, they are only
3648 used in one place: in @file{reorg.c}, instead of guessing which path a
3649 branch is mostly to take, the @samp{REG_BR_PROB} values are used to
3650 exactly determine which path is taken more often.
3652 @item -fno-guess-branch-probability
3653 @opindex fno-guess-branch-probability
3654 Do not guess branch probabilities using a randomized model.
3656 Sometimes gcc will opt to use a randomized model to guess branch
3657 probabilities, when none are available from either profiling feedback
3658 (@option{-fprofile-arcs}) or @samp{__builtin_expect}. This means that
3659 different runs of the compiler on the same program may produce different
3662 In a hard real-time system, people don't want different runs of the
3663 compiler to produce code that has different behavior; minimizing
3664 non-determinism is of paramount import. This switch allows users to
3665 reduce non-determinism, possibly at the expense of inferior
3668 @item -fstrict-aliasing
3669 @opindex fstrict-aliasing
3670 Allows the compiler to assume the strictest aliasing rules applicable to
3671 the language being compiled. For C (and C++), this activates
3672 optimizations based on the type of expressions. In particular, an
3673 object of one type is assumed never to reside at the same address as an
3674 object of a different type, unless the types are almost the same. For
3675 example, an @code{unsigned int} can alias an @code{int}, but not a
3676 @code{void*} or a @code{double}. A character type may alias any other
3679 Pay special attention to code like this:
3692 The practice of reading from a different union member than the one most
3693 recently written to (called ``type-punning'') is common. Even with
3694 @option{-fstrict-aliasing}, type-punning is allowed, provided the memory
3695 is accessed through the union type. So, the code above will work as
3696 expected. However, this code might not:
3707 Every language that wishes to perform language-specific alias analysis
3708 should define a function that computes, given an @code{tree}
3709 node, an alias set for the node. Nodes in different alias sets are not
3710 allowed to alias. For an example, see the C front-end function
3711 @code{c_get_alias_set}.
3713 @item -falign-functions
3714 @itemx -falign-functions=@var{n}
3715 @opindex falign-functions
3716 Align the start of functions to the next power-of-two greater than
3717 @var{n}, skipping up to @var{n} bytes. For instance,
3718 @option{-falign-functions=32} aligns functions to the next 32-byte
3719 boundary, but @option{-falign-functions=24} would align to the next
3720 32-byte boundary only if this can be done by skipping 23 bytes or less.
3722 @option{-fno-align-functions} and @option{-falign-functions=1} are
3723 equivalent and mean that functions will not be aligned.
3725 Some assemblers only support this flag when @var{n} is a power of two;
3726 in that case, it is rounded up.
3728 If @var{n} is not specified, use a machine-dependent default.
3730 @item -falign-labels
3731 @itemx -falign-labels=@var{n}
3732 @opindex falign-labels
3733 Align all branch targets to a power-of-two boundary, skipping up to
3734 @var{n} bytes like @option{-falign-functions}. This option can easily
3735 make code slower, because it must insert dummy operations for when the
3736 branch target is reached in the usual flow of the code.
3738 If @option{-falign-loops} or @option{-falign-jumps} are applicable and
3739 are greater than this value, then their values are used instead.
3741 If @var{n} is not specified, use a machine-dependent default which is
3742 very likely to be @samp{1}, meaning no alignment.
3745 @itemx -falign-loops=@var{n}
3746 @opindex falign-loops
3747 Align loops to a power-of-two boundary, skipping up to @var{n} bytes
3748 like @option{-falign-functions}. The hope is that the loop will be
3749 executed many times, which will make up for any execution of the dummy
3752 If @var{n} is not specified, use a machine-dependent default.
3755 @itemx -falign-jumps=@var{n}
3756 @opindex falign-jumps
3757 Align branch targets to a power-of-two boundary, for branch targets
3758 where the targets can only be reached by jumping, skipping up to @var{n}
3759 bytes like @option{-falign-functions}. In this case, no dummy operations
3762 If @var{n} is not specified, use a machine-dependent default.
3766 Perform optimizations in static single assignment form. Each function's
3767 flow graph is translated into SSA form, optimizations are performed, and
3768 the flow graph is translated back from SSA form. Users should not
3769 specify this option, since it is not yet ready for production use.
3773 Perform Sparse Conditional Constant Propagation in SSA form. Requires
3774 @option{-fssa}. Like @option{-fssa}, this is an experimental feature.
3778 Perform aggressive dead-code elimination in SSA form. Requires @option{-fssa}.
3779 Like @option{-fssa}, this is an experimental feature.
3781 @item -fsingle-precision-constant
3782 @opindex fsingle-precision-constant
3783 Treat floating point constant as single precision constant instead of
3784 implicitly converting it to double precision constant.
3786 @item -frename-registers
3787 @opindex frename-registers
3788 Attempt to avoid false dependencies in scheduled code by making use
3789 of registers left over after register allocation. This optimization
3790 will most benefit processors with lots of registers. It can, however,
3791 make debugging impossible, since variables will no longer stay in
3792 a ``home register''.
3794 @item -fno-cprop-registers
3795 @opindex fno-cprop-registers
3796 After register allocation and post-register allocation instruction splitting,
3797 we perform a copy-propagation pass to try to reduce scheduling dependencies
3798 and occasionally eliminate the copy.
3800 @item --param @var{name}=@var{value}
3802 In some places, GCC uses various constants to control the amount of
3803 optimization that is done. For example, GCC will not inline functions
3804 that contain more that a certain number of instructions. You can
3805 control some of these constants on the command-line using the
3806 @option{--param} option.
3808 In each case, the @var{value} is an integer. The allowable choices for
3809 @var{name} are given in the following table:
3812 @item max-delay-slot-insn-search
3813 The maximum number of instructions to consider when looking for an
3814 instruction to fill a delay slot. If more than this arbitrary number of
3815 instructions is searched, the time savings from filling the delay slot
3816 will be minimal so stop searching. Increasing values mean more
3817 aggressive optimization, making the compile time increase with probably
3818 small improvement in executable run time.
3820 @item max-delay-slot-live-search
3821 When trying to fill delay slots, the maximum number of instructions to
3822 consider when searching for a block with valid live register
3823 information. Increasing this arbitrarily chosen value means more
3824 aggressive optimization, increasing the compile time. This parameter
3825 should be removed when the delay slot code is rewritten to maintain the
3828 @item max-gcse-memory
3829 The approximate maximum amount of memory that will be allocated in
3830 order to perform the global common subexpression elimination
3831 optimization. If more memory than specified is required, the
3832 optimization will not be done.
3834 @item max-gcse-passes
3835 The maximum number of passes of GCSE to run.
3837 @item max-pending-list-length
3838 The maximum number of pending dependencies scheduling will allow
3839 before flushing the current state and starting over. Large functions
3840 with few branches or calls can create excessively large lists which
3841 needlessly consume memory and resources.
3843 @item max-inline-insns
3844 If an function contains more than this many instructions, it
3845 will not be inlined. This option is precisely equivalent to
3846 @option{-finline-limit}.
3851 @node Preprocessor Options
3852 @section Options Controlling the Preprocessor
3853 @cindex preprocessor options
3854 @cindex options, preprocessor
3856 These options control the C preprocessor, which is run on each C source
3857 file before actual compilation.
3859 If you use the @option{-E} option, nothing is done except preprocessing.
3860 Some of these options make sense only together with @option{-E} because
3861 they cause the preprocessor output to be unsuitable for actual
3865 @item -include @var{file}
3867 Process @var{file} as input before processing the regular input file.
3868 In effect, the contents of @var{file} are compiled first. Any @option{-D}
3869 and @option{-U} options on the command line are always processed before
3870 @option{-include @var{file}}, regardless of the order in which they are
3871 written. All the @option{-include} and @option{-imacros} options are
3872 processed in the order in which they are written.
3874 @item -imacros @var{file}
3876 Process @var{file} as input, discarding the resulting output, before
3877 processing the regular input file. Because the output generated from
3878 @var{file} is discarded, the only effect of @option{-imacros @var{file}}
3879 is to make the macros defined in @var{file} available for use in the
3880 main input. All the @option{-include} and @option{-imacros} options are
3881 processed in the order in which they are written.
3883 @item -idirafter @var{dir}
3885 @cindex second include path
3886 Add the directory @var{dir} to the second include path. The directories
3887 on the second include path are searched when a header file is not found
3888 in any of the directories in the main include path (the one that
3889 @option{-I} adds to).
3891 @item -iprefix @var{prefix}
3893 Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix}
3896 @item -iwithprefix @var{dir}
3897 @opindex iwithprefix
3898 Add a directory to the second include path. The directory's name is
3899 made by concatenating @var{prefix} and @var{dir}, where @var{prefix} was
3900 specified previously with @option{-iprefix}. If you have not specified a
3901 prefix yet, the directory containing the installed passes of the
3902 compiler is used as the default.
3904 @item -iwithprefixbefore @var{dir}
3905 @opindex iwithprefixbefore
3906 Add a directory to the main include path. The directory's name is made
3907 by concatenating @var{prefix} and @var{dir}, as in the case of
3908 @option{-iwithprefix}.
3910 @item -isystem @var{dir}
3912 Add a directory to the beginning of the second include path, marking it
3913 as a system directory, so that it gets the same special treatment as
3914 is applied to the standard system directories.
3918 Do not search the standard system directories for header files. Only
3919 the directories you have specified with @option{-I} options (and the
3920 current directory, if appropriate) are searched. @xref{Directory
3921 Options}, for information on @option{-I}.
3923 By using both @option{-nostdinc} and @option{-I-}, you can limit the include-file
3924 search path to only those directories you specify explicitly.
3928 When searching for a header file in a directory, remap file names if a
3929 file named @file{header.gcc} exists in that directory. This can be used
3930 to work around limitations of file systems with file name restrictions.
3931 The @file{header.gcc} file should contain a series of lines with two
3932 tokens on each line: the first token is the name to map, and the second
3933 token is the actual name to use.
3937 Do not predefine any nonstandard macros. (Including architecture flags).
3941 Run only the C preprocessor. Preprocess all the C source files
3942 specified and output the results to standard output or to the
3943 specified output file.
3947 Tell the preprocessor not to discard comments. Used with the
3952 Tell the preprocessor not to generate @samp{#line} directives.
3953 Used with the @option{-E} option.
3956 @cindex dependencies, make
3959 Instead of outputting the result of preprocessing, output a rule
3960 suitable for @command{make} describing the dependencies of the main
3961 source file. The preprocessor outputs one @command{make} rule containing
3962 the object file name for that source file, a colon, and the names of all
3963 the included files, including those coming from @option{-include} or
3964 @option{-imacros} command line options.
3966 Unless specified explicitly (with @option{-MT} or @option{-MQ}), the
3967 object file name consists of the basename of the source file with any
3968 suffix replaced with object file suffix. If there are many included
3969 files then the rule is split into several lines using @samp{\}-newline.
3970 The rule has no commands.
3972 Passing @option{-M} to the driver implies @option{-E}.
3976 Like @option{-M} but do not mention header files that are found in
3977 system header directories, nor header files that are included,
3978 directly or indirectly, from such a header.
3980 This implies that the choice of angle brackets or double quotes in an
3981 @samp{#include} directive does not in itself determine whether that
3982 header will appear in @option{-MM} dependency output. This is a
3983 slight change in semantics from GCC versions 3.0 and earlier.
3987 @option{-MD} is equivalent to @option{-M -MF @var{file}}, except that
3988 @option{-E} is not implied. The driver determines @var{file} based on
3989 whether an @option{-o} option is given. If it is, the driver uses its
3990 argument but with a suffix of @file{.d}, otherwise it take the
3991 basename of the input file and applies a @file{.d} suffix.
3993 If @option{-MD} is used in conjunction with @option{-E}, any
3994 @option{-o} switch is understood to specify the dependency output file
3995 (but @pxref{-MF}), but if used without @option{-E}, each @option{-o}
3996 is understood to specify a target object file.
3998 Since @option{-E} is not implied, @option{-MD} can be used to generate
3999 a dependency output file as a side-effect of the compilation process.
4001 With Mach, you can use the utility @code{md} to merge multiple
4002 dependency files into a single dependency file suitable for using with
4003 the @samp{make} command.
4007 Like @option{-MD} except mention only user header files, not system
4010 @item -MF @var{file}
4013 When used with @option{-M} or @option{-MM}, specifies a
4014 file to write the dependencies to. If no @option{-MF} switch is given
4015 the preprocessor sends the rules to the same place it would have sent
4016 preprocessed output.
4018 When used with the driver options @option{-MD} or @option{-MMD},
4019 @option{-MF} overrides the default dependency output file.
4021 Another way to specify output of a @code{make} rule is by setting
4022 the environment variable @env{DEPENDENCIES_OUTPUT} (@pxref{Environment
4027 When used with @option{-M} or @option{-MM}, @option{-MG} says to treat missing
4028 header files as generated files and assume they live in the same
4029 directory as the source file. It suppresses preprocessed output, as a
4030 missing header file is ordinarily an error.
4032 This feature is used in automatic updating of makefiles.
4036 This option instructs CPP to add a phony target for each dependency
4037 other than the main file, causing each to depend on nothing. These
4038 dummy rules work around errors @code{make} gives if you remove header
4039 files without updating the @code{Makefile} to match.
4041 This is typical output:-
4044 /tmp/test.o: /tmp/test.c /tmp/test.h
4049 @item -MQ @var{target}
4050 @item -MT @var{target}
4053 By default CPP uses the main file name, including any path, and appends
4054 the object suffix, normally ``.o'', to it to obtain the name of the
4055 target for dependency generation. With @option{-MT} you can specify a
4056 target yourself, overriding the default one.
4058 If you want multiple targets, you can specify them as a single argument
4059 to @option{-MT}, or use multiple @option{-MT} options.
4061 The targets you specify are output in the order they appear on the
4062 command line. @option{-MQ} is identical to @option{-MT}, except that the
4063 target name is quoted for Make, but with @option{-MT} it isn't. For
4064 example, @option{-MT '$(objpfx)foo.o'} gives
4067 $(objpfx)foo.o: /tmp/foo.c
4070 but @option{-MQ '$(objpfx)foo.o'} gives
4073 $$(objpfx)foo.o: /tmp/foo.c
4076 The default target is automatically quoted, as if it were given with
4081 Print the name of each header file used, in addition to other normal
4084 @item -A@var{question}(@var{answer})
4086 Assert the answer @var{answer} for @var{question}, in case it is tested
4087 with a preprocessing conditional such as @samp{#if
4088 #@var{question}(@var{answer})}. @option{-A-} disables the standard
4089 assertions that normally describe the target machine.
4093 Define macro @var{macro} with the string @samp{1} as its definition.
4095 @item -D@var{macro}=@var{defn}
4096 Define macro @var{macro} as @var{defn}. All instances of @option{-D} on
4097 the command line are processed before any @option{-U} options.
4099 Any @option{-D} and @option{-U} options on the command line are processed in
4100 order, and always before @option{-imacros @var{file}}, regardless of the
4101 order in which they are written.
4105 Undefine macro @var{macro}. @option{-U} options are evaluated after all
4106 @option{-D} options, but before any @option{-include} and @option{-imacros}
4109 Any @option{-D} and @option{-U} options on the command line are processed in
4110 order, and always before @option{-imacros @var{file}}, regardless of the
4111 order in which they are written.
4115 Tell the preprocessor to output only a list of the macro definitions
4116 that are in effect at the end of preprocessing. Used with the @option{-E}
4121 Tell the preprocessing to pass all macro definitions into the output, in
4122 their proper sequence in the rest of the output.
4126 Like @option{-dD} except that the macro arguments and contents are omitted.
4127 Only @samp{#define @var{name}} is included in the output.
4131 Output @samp{#include} directives in addition to the result of
4134 @item -fpreprocessed
4135 @opindex fpreprocessed
4136 Indicate to the preprocessor that the input file has already been
4137 preprocessed. This suppresses things like macro expansion, trigraph
4138 conversion, escaped newline splicing, and processing of most directives.
4139 The preprocessor still recognizes and removes comments, so that you can
4140 pass a file preprocessed with @option{-C} to the compiler without
4141 problems. In this mode the integrated preprocessor is little more than
4142 a tokenizer for the front ends.
4144 @option{-fpreprocessed} is implicit if the input file has one of the
4145 extensions @samp{i}, @samp{ii} or @samp{mi}. These are the extensions
4146 that GCC uses for preprocessed files created by @option{-save-temps}.
4150 Process ISO standard trigraph sequences. These are three-character
4151 sequences, all starting with @samp{??}, that are defined by ISO C to
4152 stand for single characters. For example, @samp{??/} stands for
4153 @samp{\}, so @samp{'??/n'} is a character constant for a newline. By
4154 default, GCC ignores trigraphs, but in standard-conforming modes it
4155 converts them. See the @option{-std} and @option{-ansi} options.
4157 The nine trigraph sequences are
4160 @expansion{} @samp{[}
4163 @expansion{} @samp{]}
4166 @expansion{} @samp{@{}
4169 @expansion{} @samp{@}}
4172 @expansion{} @samp{#}
4175 @expansion{} @samp{\}
4178 @expansion{} @samp{^}
4181 @expansion{} @samp{|}
4184 @expansion{} @samp{~}
4188 Trigraph support is not popular, so many compilers do not implement it
4189 properly. Portable code should not rely on trigraphs being either
4190 converted or ignored.
4192 @item -Wp,@var{option}
4194 Pass @var{option} as an option to the preprocessor. If @var{option}
4195 contains commas, it is split into multiple options at the commas.
4198 @node Assembler Options
4199 @section Passing Options to the Assembler
4201 @c prevent bad page break with this line
4202 You can pass options to the assembler.
4205 @item -Wa,@var{option}
4207 Pass @var{option} as an option to the assembler. If @var{option}
4208 contains commas, it is split into multiple options at the commas.
4212 @section Options for Linking
4213 @cindex link options
4214 @cindex options, linking
4216 These options come into play when the compiler links object files into
4217 an executable output file. They are meaningless if the compiler is
4218 not doing a link step.
4222 @item @var{object-file-name}
4223 A file name that does not end in a special recognized suffix is
4224 considered to name an object file or library. (Object files are
4225 distinguished from libraries by the linker according to the file
4226 contents.) If linking is done, these object files are used as input
4235 If any of these options is used, then the linker is not run, and
4236 object file names should not be used as arguments. @xref{Overall
4240 @item -l@var{library}
4241 @itemx -l @var{library}
4243 Search the library named @var{library} when linking. (The second
4244 alternative with the library as a separate argument is only for
4245 POSIX compliance and is not recommended.)
4247 It makes a difference where in the command you write this option; the
4248 linker searches and processes libraries and object files in the order they
4249 are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
4250 after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
4251 to functions in @samp{z}, those functions may not be loaded.
4253 The linker searches a standard list of directories for the library,
4254 which is actually a file named @file{lib@var{library}.a}. The linker
4255 then uses this file as if it had been specified precisely by name.
4257 The directories searched include several standard system directories
4258 plus any that you specify with @option{-L}.
4260 Normally the files found this way are library files---archive files
4261 whose members are object files. The linker handles an archive file by
4262 scanning through it for members which define symbols that have so far
4263 been referenced but not defined. But if the file that is found is an
4264 ordinary object file, it is linked in the usual fashion. The only
4265 difference between using an @option{-l} option and specifying a file name
4266 is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
4267 and searches several directories.
4271 You need this special case of the @option{-l} option in order to
4272 link an Objective-C program.
4275 @opindex nostartfiles
4276 Do not use the standard system startup files when linking.
4277 The standard system libraries are used normally, unless @option{-nostdlib}
4278 or @option{-nodefaultlibs} is used.
4280 @item -nodefaultlibs
4281 @opindex nodefaultlibs
4282 Do not use the standard system libraries when linking.
4283 Only the libraries you specify will be passed to the linker.
4284 The standard startup files are used normally, unless @option{-nostartfiles}
4285 is used. The compiler may generate calls to memcmp, memset, and memcpy
4286 for System V (and ISO C) environments or to bcopy and bzero for
4287 BSD environments. These entries are usually resolved by entries in
4288 libc. These entry points should be supplied through some other
4289 mechanism when this option is specified.
4293 Do not use the standard system startup files or libraries when linking.
4294 No startup files and only the libraries you specify will be passed to
4295 the linker. The compiler may generate calls to memcmp, memset, and memcpy
4296 for System V (and ISO C) environments or to bcopy and bzero for
4297 BSD environments. These entries are usually resolved by entries in
4298 libc. These entry points should be supplied through some other
4299 mechanism when this option is specified.
4301 @cindex @option{-lgcc}, use with @option{-nostdlib}
4302 @cindex @option{-nostdlib} and unresolved references
4303 @cindex unresolved references and @option{-nostdlib}
4304 @cindex @option{-lgcc}, use with @option{-nodefaultlibs}
4305 @cindex @option{-nodefaultlibs} and unresolved references
4306 @cindex unresolved references and @option{-nodefaultlibs}
4307 One of the standard libraries bypassed by @option{-nostdlib} and
4308 @option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
4309 that GCC uses to overcome shortcomings of particular machines, or special
4310 needs for some languages.
4311 (@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
4312 Collection (GCC) Internals},
4313 for more discussion of @file{libgcc.a}.)
4314 In most cases, you need @file{libgcc.a} even when you want to avoid
4315 other standard libraries. In other words, when you specify @option{-nostdlib}
4316 or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
4317 This ensures that you have no unresolved references to internal GCC
4318 library subroutines. (For example, @samp{__main}, used to ensure C++
4319 constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
4320 GNU Compiler Collection (GCC) Internals}.)
4324 Remove all symbol table and relocation information from the executable.
4328 On systems that support dynamic linking, this prevents linking with the shared
4329 libraries. On other systems, this option has no effect.
4333 Produce a shared object which can then be linked with other objects to
4334 form an executable. Not all systems support this option. For predictable
4335 results, you must also specify the same set of options that were used to
4336 generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
4337 when you specify this option.@footnote{On some systems, @samp{gcc -shared}
4338 needs to build supplementary stub code for constructors to work. On
4339 multi-libbed systems, @samp{gcc -shared} must select the correct support
4340 libraries to link against. Failing to supply the correct flags may lead
4341 to subtle defects. Supplying them in cases where they are not necessary
4344 @item -shared-libgcc
4345 @itemx -static-libgcc
4346 @opindex shared-libgcc
4347 @opindex static-libgcc
4348 On systems that provide @file{libgcc} as a shared library, these options
4349 force the use of either the shared or static version respectively.
4350 If no shared version of @file{libgcc} was built when the compiler was
4351 configured, these options have no effect.
4353 There are several situations in which an application should use the
4354 shared @file{libgcc} instead of the static version. The most common
4355 of these is when the application wishes to throw and catch exceptions
4356 across different shared libraries. In that case, each of the libraries
4357 as well as the application itself should use the shared @file{libgcc}.
4359 Therefore, the G++ and GCJ drivers automatically add
4360 @option{-shared-libgcc} whenever you build a shared library or a main
4361 executable, because C++ and Java programs typically use exceptions, so
4362 this is the right thing to do.
4364 If, instead, you use the GCC driver to create shared libraries, you may
4365 find that they will not always be linked with the shared @file{libgcc}.
4366 If GCC finds, at its configuration time, that you have a GNU linker that
4367 does not support option @option{--eh-frame-hdr}, it will link the shared
4368 version of @file{libgcc} into shared libraries by default. Otherwise,
4369 it will take advantage of the linker and optimize away the linking with
4370 the shared version of @file{libgcc}, linking with the static version of
4371 libgcc by default. This allows exceptions to propagate through such
4372 shared libraries, without incurring relocation costs at library load
4375 However, if a library or main executable is supposed to throw or catch
4376 exceptions, you must link it using the G++ or GCJ driver, as appropriate
4377 for the languages used in the program, or using the option
4378 @option{-shared-libgcc}, such that it is linked with the shared
4383 Bind references to global symbols when building a shared object. Warn
4384 about any unresolved references (unless overridden by the link editor
4385 option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
4388 @item -Xlinker @var{option}
4390 Pass @var{option} as an option to the linker. You can use this to
4391 supply system-specific linker options which GCC does not know how to
4394 If you want to pass an option that takes an argument, you must use
4395 @option{-Xlinker} twice, once for the option and once for the argument.
4396 For example, to pass @option{-assert definitions}, you must write
4397 @samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
4398 @option{-Xlinker "-assert definitions"}, because this passes the entire
4399 string as a single argument, which is not what the linker expects.
4401 @item -Wl,@var{option}
4403 Pass @var{option} as an option to the linker. If @var{option} contains
4404 commas, it is split into multiple options at the commas.
4406 @item -u @var{symbol}
4408 Pretend the symbol @var{symbol} is undefined, to force linking of
4409 library modules to define it. You can use @option{-u} multiple times with
4410 different symbols to force loading of additional library modules.
4413 @node Directory Options
4414 @section Options for Directory Search
4415 @cindex directory options
4416 @cindex options, directory search
4419 These options specify directories to search for header files, for
4420 libraries and for parts of the compiler:
4425 Add the directory @var{dir} to the head of the list of directories to be
4426 searched for header files. This can be used to override a system header
4427 file, substituting your own version, since these directories are
4428 searched before the system header file directories. However, you should
4429 not use this option to add directories that contain vendor-supplied
4430 system header files (use @option{-isystem} for that). If you use more than
4431 one @option{-I} option, the directories are scanned in left-to-right
4432 order; the standard system directories come after.
4434 If a standard system include directory, or a directory specified with
4435 @option{-isystem}, is also specified with @option{-I}, it will be
4436 searched only in the position requested by @option{-I}. Also, it will
4437 not be considered a system include directory. If that directory really
4438 does contain system headers, there is a good chance that they will
4439 break. For instance, if GCC's installation procedure edited the headers
4440 in @file{/usr/include} to fix bugs, @samp{-I/usr/include} will cause the
4441 original, buggy headers to be found instead of the corrected ones. GCC
4442 will issue a warning when a system include directory is hidden in this
4447 Any directories you specify with @option{-I} options before the @option{-I-}
4448 option are searched only for the case of @samp{#include "@var{file}"};
4449 they are not searched for @samp{#include <@var{file}>}.
4451 If additional directories are specified with @option{-I} options after
4452 the @option{-I-}, these directories are searched for all @samp{#include}
4453 directives. (Ordinarily @emph{all} @option{-I} directories are used
4456 In addition, the @option{-I-} option inhibits the use of the current
4457 directory (where the current input file came from) as the first search
4458 directory for @samp{#include "@var{file}"}. There is no way to
4459 override this effect of @option{-I-}. With @option{-I.} you can specify
4460 searching the directory which was current when the compiler was
4461 invoked. That is not exactly the same as what the preprocessor does
4462 by default, but it is often satisfactory.
4464 @option{-I-} does not inhibit the use of the standard system directories
4465 for header files. Thus, @option{-I-} and @option{-nostdinc} are
4470 Add directory @var{dir} to the list of directories to be searched
4473 @item -B@var{prefix}
4475 This option specifies where to find the executables, libraries,
4476 include files, and data files of the compiler itself.
4478 The compiler driver program runs one or more of the subprograms
4479 @file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
4480 @var{prefix} as a prefix for each program it tries to run, both with and
4481 without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
4483 For each subprogram to be run, the compiler driver first tries the
4484 @option{-B} prefix, if any. If that name is not found, or if @option{-B}
4485 was not specified, the driver tries two standard prefixes, which are
4486 @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc-lib/}. If neither of
4487 those results in a file name that is found, the unmodified program
4488 name is searched for using the directories specified in your
4489 @env{PATH} environment variable.
4491 The compiler will check to see if the path provided by the @option{-B}
4492 refers to a directory, and if necessary it will add a directory
4493 separator character at the end of the path.
4495 @option{-B} prefixes that effectively specify directory names also apply
4496 to libraries in the linker, because the compiler translates these
4497 options into @option{-L} options for the linker. They also apply to
4498 includes files in the preprocessor, because the compiler translates these
4499 options into @option{-isystem} options for the preprocessor. In this case,
4500 the compiler appends @samp{include} to the prefix.
4502 The run-time support file @file{libgcc.a} can also be searched for using
4503 the @option{-B} prefix, if needed. If it is not found there, the two
4504 standard prefixes above are tried, and that is all. The file is left
4505 out of the link if it is not found by those means.
4507 Another way to specify a prefix much like the @option{-B} prefix is to use
4508 the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
4511 As a special kludge, if the path provided by @option{-B} is
4512 @file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
4513 9, then it will be replaced by @file{[dir/]include}. This is to help
4514 with boot-strapping the compiler.
4516 @item -specs=@var{file}
4518 Process @var{file} after the compiler reads in the standard @file{specs}
4519 file, in order to override the defaults that the @file{gcc} driver
4520 program uses when determining what switches to pass to @file{cc1},
4521 @file{cc1plus}, @file{as}, @file{ld}, etc. More than one
4522 @option{-specs=@var{file}} can be specified on the command line, and they
4523 are processed in order, from left to right.
4529 @section Specifying subprocesses and the switches to pass to them
4531 @command{gcc} is a driver program. It performs its job by invoking a
4532 sequence of other programs to do the work of compiling, assembling and
4533 linking. GCC interprets its command-line parameters and uses these to
4534 deduce which programs it should invoke, and which command-line options
4535 it ought to place on their command lines. This behavior is controlled
4536 by @dfn{spec strings}. In most cases there is one spec string for each
4537 program that GCC can invoke, but a few programs have multiple spec
4538 strings to control their behavior. The spec strings built into GCC can
4539 be overridden by using the @option{-specs=} command-line switch to specify
4542 @dfn{Spec files} are plaintext files that are used to construct spec
4543 strings. They consist of a sequence of directives separated by blank
4544 lines. The type of directive is determined by the first non-whitespace
4545 character on the line and it can be one of the following:
4548 @item %@var{command}
4549 Issues a @var{command} to the spec file processor. The commands that can
4553 @item %include <@var{file}>
4555 Search for @var{file} and insert its text at the current point in the
4558 @item %include_noerr <@var{file}>
4559 @cindex %include_noerr
4560 Just like @samp{%include}, but do not generate an error message if the include
4561 file cannot be found.
4563 @item %rename @var{old_name} @var{new_name}
4565 Rename the spec string @var{old_name} to @var{new_name}.
4569 @item *[@var{spec_name}]:
4570 This tells the compiler to create, override or delete the named spec
4571 string. All lines after this directive up to the next directive or
4572 blank line are considered to be the text for the spec string. If this
4573 results in an empty string then the spec will be deleted. (Or, if the
4574 spec did not exist, then nothing will happened.) Otherwise, if the spec
4575 does not currently exist a new spec will be created. If the spec does
4576 exist then its contents will be overridden by the text of this
4577 directive, unless the first character of that text is the @samp{+}
4578 character, in which case the text will be appended to the spec.
4580 @item [@var{suffix}]:
4581 Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
4582 and up to the next directive or blank line are considered to make up the
4583 spec string for the indicated suffix. When the compiler encounters an
4584 input file with the named suffix, it will processes the spec string in
4585 order to work out how to compile that file. For example:
4592 This says that any input file whose name ends in @samp{.ZZ} should be
4593 passed to the program @samp{z-compile}, which should be invoked with the
4594 command-line switch @option{-input} and with the result of performing the
4595 @samp{%i} substitution. (See below.)
4597 As an alternative to providing a spec string, the text that follows a
4598 suffix directive can be one of the following:
4601 @item @@@var{language}
4602 This says that the suffix is an alias for a known @var{language}. This is
4603 similar to using the @option{-x} command-line switch to GCC to specify a
4604 language explicitly. For example:
4611 Says that .ZZ files are, in fact, C++ source files.
4614 This causes an error messages saying:
4617 @var{name} compiler not installed on this system.
4621 GCC already has an extensive list of suffixes built into it.
4622 This directive will add an entry to the end of the list of suffixes, but
4623 since the list is searched from the end backwards, it is effectively
4624 possible to override earlier entries using this technique.
4628 GCC has the following spec strings built into it. Spec files can
4629 override these strings or create their own. Note that individual
4630 targets can also add their own spec strings to this list.
4633 asm Options to pass to the assembler
4634 asm_final Options to pass to the assembler post-processor
4635 cpp Options to pass to the C preprocessor
4636 cc1 Options to pass to the C compiler
4637 cc1plus Options to pass to the C++ compiler
4638 endfile Object files to include at the end of the link
4639 link Options to pass to the linker
4640 lib Libraries to include on the command line to the linker
4641 libgcc Decides which GCC support library to pass to the linker
4642 linker Sets the name of the linker
4643 predefines Defines to be passed to the C preprocessor
4644 signed_char Defines to pass to CPP to say whether @code{char} is signed
4646 startfile Object files to include at the start of the link
4649 Here is a small example of a spec file:
4655 --start-group -lgcc -lc -leval1 --end-group %(old_lib)
4658 This example renames the spec called @samp{lib} to @samp{old_lib} and
4659 then overrides the previous definition of @samp{lib} with a new one.
4660 The new definition adds in some extra command-line options before
4661 including the text of the old definition.
4663 @dfn{Spec strings} are a list of command-line options to be passed to their
4664 corresponding program. In addition, the spec strings can contain
4665 @samp{%}-prefixed sequences to substitute variable text or to
4666 conditionally insert text into the command line. Using these constructs
4667 it is possible to generate quite complex command lines.
4669 Here is a table of all defined @samp{%}-sequences for spec
4670 strings. Note that spaces are not generated automatically around the
4671 results of expanding these sequences. Therefore you can concatenate them
4672 together or combine them with constant text in a single argument.
4676 Substitute one @samp{%} into the program name or argument.
4679 Substitute the name of the input file being processed.
4682 Substitute the basename of the input file being processed.
4683 This is the substring up to (and not including) the last period
4684 and not including the directory.
4687 This is the same as @samp{%b}, but include the file suffix (text after
4691 Marks the argument containing or following the @samp{%d} as a
4692 temporary file name, so that that file will be deleted if GCC exits
4693 successfully. Unlike @samp{%g}, this contributes no text to the
4696 @item %g@var{suffix}
4697 Substitute a file name that has suffix @var{suffix} and is chosen
4698 once per compilation, and mark the argument in the same way as
4699 @samp{%d}. To reduce exposure to denial-of-service attacks, the file
4700 name is now chosen in a way that is hard to predict even when previously
4701 chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
4702 might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
4703 the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
4704 treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
4705 was simply substituted with a file name chosen once per compilation,
4706 without regard to any appended suffix (which was therefore treated
4707 just like ordinary text), making such attacks more likely to succeed.
4709 @item %u@var{suffix}
4710 Like @samp{%g}, but generates a new temporary file name even if
4711 @samp{%u@var{suffix}} was already seen.
4713 @item %U@var{suffix}
4714 Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
4715 new one if there is no such last file name. In the absence of any
4716 @samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
4717 the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
4718 would involve the generation of two distinct file names, one
4719 for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
4720 simply substituted with a file name chosen for the previous @samp{%u},
4721 without regard to any appended suffix.
4723 @item %j@var{SUFFIX}
4724 Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
4725 writable, and if save-temps is off; otherwise, substitute the name
4726 of a temporary file, just like @samp{%u}. This temporary file is not
4727 meant for communication between processes, but rather as a junk
4730 @item %.@var{SUFFIX}
4731 Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
4732 when it is subsequently output with @samp{%*}. @var{SUFFIX} is
4733 terminated by the next space or %.
4736 Marks the argument containing or following the @samp{%w} as the
4737 designated output file of this compilation. This puts the argument
4738 into the sequence of arguments that @samp{%o} will substitute later.
4741 Substitutes the names of all the output files, with spaces
4742 automatically placed around them. You should write spaces
4743 around the @samp{%o} as well or the results are undefined.
4744 @samp{%o} is for use in the specs for running the linker.
4745 Input files whose names have no recognized suffix are not compiled
4746 at all, but they are included among the output files, so they will
4750 Substitutes the suffix for object files. Note that this is
4751 handled specially when it immediately follows @samp{%g, %u, or %U},
4752 because of the need for those to form complete file names. The
4753 handling is such that @samp{%O} is treated exactly as if it had already
4754 been substituted, except that @samp{%g, %u, and %U} do not currently
4755 support additional @var{suffix} characters following @samp{%O} as they would
4756 following, for example, @samp{.o}.
4759 Substitutes the standard macro predefinitions for the
4760 current target machine. Use this when running @code{cpp}.
4763 Like @samp{%p}, but puts @samp{__} before and after the name of each
4764 predefined macro, except for macros that start with @samp{__} or with
4765 @samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
4769 Substitute a @option{-iprefix} option made from @env{GCC_EXEC_PREFIX}.
4772 Current argument is the name of a library or startup file of some sort.
4773 Search for that file in a standard list of directories and substitute
4774 the full name found.
4777 Print @var{str} as an error message. @var{str} is terminated by a newline.
4778 Use this when inconsistent options are detected.
4781 Output @samp{-} if the input for the current command is coming from a pipe.
4784 Substitute the contents of spec string @var{name} at this point.
4787 Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
4789 @item %x@{@var{option}@}
4790 Accumulate an option for @samp{%X}.
4793 Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
4797 Output the accumulated assembler options specified by @option{-Wa}.
4800 Output the accumulated preprocessor options specified by @option{-Wp}.
4803 Substitute the major version number of GCC@.
4804 (For version 2.9.5, this is 2.)
4807 Substitute the minor version number of GCC@.
4808 (For version 2.9.5, this is 9.)
4811 Substitute the patch level number of GCC@.
4812 (For version 2.9.5, this is 5.)
4815 Process the @code{asm} spec. This is used to compute the
4816 switches to be passed to the assembler.
4819 Process the @code{asm_final} spec. This is a spec string for
4820 passing switches to an assembler post-processor, if such a program is
4824 Process the @code{link} spec. This is the spec for computing the
4825 command line passed to the linker. Typically it will make use of the
4826 @samp{%L %G %S %D and %E} sequences.
4829 Dump out a @option{-L} option for each directory that GCC believes might
4830 contain startup files. If the target supports multilibs then the
4831 current multilib directory will be prepended to each of these paths.
4834 Output the multilib directory with directory separators replaced with
4835 @samp{_}. If multilib directories are not set, or the multilib directory is
4836 @file{.} then this option emits nothing.
4839 Process the @code{lib} spec. This is a spec string for deciding which
4840 libraries should be included on the command line to the linker.
4843 Process the @code{libgcc} spec. This is a spec string for deciding
4844 which GCC support library should be included on the command line to the linker.
4847 Process the @code{startfile} spec. This is a spec for deciding which
4848 object files should be the first ones passed to the linker. Typically
4849 this might be a file named @file{crt0.o}.
4852 Process the @code{endfile} spec. This is a spec string that specifies
4853 the last object files that will be passed to the linker.
4856 Process the @code{cpp} spec. This is used to construct the arguments
4857 to be passed to the C preprocessor.
4860 Process the @code{signed_char} spec. This is intended to be used
4861 to tell cpp whether a char is signed. It typically has the definition:
4863 %@{funsigned-char:-D__CHAR_UNSIGNED__@}
4867 Process the @code{cc1} spec. This is used to construct the options to be
4868 passed to the actual C compiler (@samp{cc1}).
4871 Process the @code{cc1plus} spec. This is used to construct the options to be
4872 passed to the actual C++ compiler (@samp{cc1plus}).
4875 Substitute the variable part of a matched option. See below.
4876 Note that each comma in the substituted string is replaced by
4880 Substitutes the @code{-S} switch, if that switch was given to GCC@.
4881 If that switch was not specified, this substitutes nothing. Note that
4882 the leading dash is omitted when specifying this option, and it is
4883 automatically inserted if the substitution is performed. Thus the spec
4884 string @samp{%@{foo@}} would match the command-line option @option{-foo}
4885 and would output the command line option @option{-foo}.
4887 @item %W@{@code{S}@}
4888 Like %@{@code{S}@} but mark last argument supplied within as a file to be
4891 @item %@{@code{S}*@}
4892 Substitutes all the switches specified to GCC whose names start
4893 with @code{-S}, but which also take an argument. This is used for
4894 switches like @option{-o}, @option{-D}, @option{-I}, etc.
4895 GCC considers @option{-o foo} as being
4896 one switch whose names starts with @samp{o}. %@{o*@} would substitute this
4897 text, including the space. Thus two arguments would be generated.
4899 @item %@{^@code{S}*@}
4900 Like %@{@code{S}*@}, but don't put a blank between a switch and its
4901 argument. Thus %@{^o*@} would only generate one argument, not two.
4903 @item %@{@code{S}*&@code{T}*@}
4904 Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
4905 (the order of @code{S} and @code{T} in the spec is not significant).
4906 There can be any number of ampersand-separated variables; for each the
4907 wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
4909 @item %@{<@code{S}@}
4910 Remove all occurrences of @code{-S} from the command line. Note---this
4911 command is position dependent. @samp{%} commands in the spec string
4912 before this option will see @code{-S}, @samp{%} commands in the spec
4913 string after this option will not.
4915 @item %@{@code{S}*:@code{X}@}
4916 Substitutes @code{X} if one or more switches whose names start with
4917 @code{-S} are specified to GCC@. Note that the tail part of the
4918 @code{-S} option (i.e.@: the part matched by the @samp{*}) will be substituted
4919 for each occurrence of @samp{%*} within @code{X}.
4921 @item %@{@code{S}:@code{X}@}
4922 Substitutes @code{X}, but only if the @samp{-S} switch was given to GCC@.
4924 @item %@{!@code{S}:@code{X}@}
4925 Substitutes @code{X}, but only if the @samp{-S} switch was @emph{not} given to GCC@.
4927 @item %@{|@code{S}:@code{X}@}
4928 Like %@{@code{S}:@code{X}@}, but if no @code{S} switch, substitute @samp{-}.
4930 @item %@{|!@code{S}:@code{X}@}
4931 Like %@{!@code{S}:@code{X}@}, but if there is an @code{S} switch, substitute @samp{-}.
4933 @item %@{.@code{S}:@code{X}@}
4934 Substitutes @code{X}, but only if processing a file with suffix @code{S}.
4936 @item %@{!.@code{S}:@code{X}@}
4937 Substitutes @code{X}, but only if @emph{not} processing a file with suffix @code{S}.
4939 @item %@{@code{S}|@code{P}:@code{X}@}
4940 Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@. This may be
4941 combined with @samp{!} and @samp{.} sequences as well, although they
4942 have a stronger binding than the @samp{|}. For example a spec string
4946 %@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
4949 will output the following command-line options from the following input
4950 command-line options:
4955 -d fred.c -foo -baz -boggle
4956 -d jim.d -bar -baz -boggle
4961 The conditional text @code{X} in a %@{@code{S}:@code{X}@} or
4962 %@{!@code{S}:@code{X}@} construct may contain other nested @samp{%} constructs
4963 or spaces, or even newlines. They are processed as usual, as described
4966 The @option{-O}, @option{-f}, @option{-m}, and @option{-W}
4967 switches are handled specifically in these
4968 constructs. If another value of @option{-O} or the negated form of a @option{-f}, @option{-m}, or
4969 @option{-W} switch is found later in the command line, the earlier switch
4970 value is ignored, except with @{@code{S}*@} where @code{S} is just one
4971 letter, which passes all matching options.
4973 The character @samp{|} at the beginning of the predicate text is used to indicate
4974 that a command should be piped to the following command, but only if @option{-pipe}
4977 It is built into GCC which switches take arguments and which do not.
4978 (You might think it would be useful to generalize this to allow each
4979 compiler's spec to say which switches take arguments. But this cannot
4980 be done in a consistent fashion. GCC cannot even decide which input
4981 files have been specified without knowing which switches take arguments,
4982 and it must know which input files to compile in order to tell which
4985 GCC also knows implicitly that arguments starting in @option{-l} are to be
4986 treated as compiler output files, and passed to the linker in their
4987 proper position among the other output files.
4989 @c man begin OPTIONS
4991 @node Target Options
4992 @section Specifying Target Machine and Compiler Version
4993 @cindex target options
4994 @cindex cross compiling
4995 @cindex specifying machine version
4996 @cindex specifying compiler version and target machine
4997 @cindex compiler version, specifying
4998 @cindex target machine, specifying
5000 By default, GCC compiles code for the same type of machine that you
5001 are using. However, it can also be installed as a cross-compiler, to
5002 compile for some other type of machine. In fact, several different
5003 configurations of GCC, for different target machines, can be
5004 installed side by side. Then you specify which one to use with the
5007 In addition, older and newer versions of GCC can be installed side
5008 by side. One of them (probably the newest) will be the default, but
5009 you may sometimes wish to use another.
5012 @item -b @var{machine}
5014 The argument @var{machine} specifies the target machine for compilation.
5015 This is useful when you have installed GCC as a cross-compiler.
5017 The value to use for @var{machine} is the same as was specified as the
5018 machine type when configuring GCC as a cross-compiler. For
5019 example, if a cross-compiler was configured with @samp{configure
5020 i386v}, meaning to compile for an 80386 running System V, then you
5021 would specify @option{-b i386v} to run that cross compiler.
5023 When you do not specify @option{-b}, it normally means to compile for
5024 the same type of machine that you are using.
5026 @item -V @var{version}
5028 The argument @var{version} specifies which version of GCC to run.
5029 This is useful when multiple versions are installed. For example,
5030 @var{version} might be @samp{2.0}, meaning to run GCC version 2.0.
5032 The default version, when you do not specify @option{-V}, is the last
5033 version of GCC that you installed.
5036 The @option{-b} and @option{-V} options actually work by controlling part of
5037 the file name used for the executable files and libraries used for
5038 compilation. A given version of GCC, for a given target machine, is
5039 normally kept in the directory @file{/usr/local/lib/gcc-lib/@var{machine}/@var{version}}.
5041 Thus, sites can customize the effect of @option{-b} or @option{-V} either by
5042 changing the names of these directories or adding alternate names (or
5043 symbolic links). If in directory @file{/usr/local/lib/gcc-lib/} the
5044 file @file{80386} is a link to the file @file{i386v}, then @option{-b
5045 80386} becomes an alias for @option{-b i386v}.
5047 In one respect, the @option{-b} or @option{-V} do not completely change
5048 to a different compiler: the top-level driver program @command{gcc}
5049 that you originally invoked continues to run and invoke the other
5050 executables (preprocessor, compiler per se, assembler and linker)
5051 that do the real work. However, since no real work is done in the
5052 driver program, it usually does not matter that the driver program
5053 in use is not the one for the specified target. It is common for the
5054 interface to the other executables to change incompatibly between
5055 compiler versions, so unless the version specified is very close to that
5056 of the driver (for example, @option{-V 3.0} with a driver program from GCC
5057 version 3.0.1), use of @option{-V} may not work; for example, using
5058 @option{-V 2.95.2} will not work with a driver program from GCC 3.0.
5060 The only way that the driver program depends on the target machine is
5061 in the parsing and handling of special machine-specific options.
5062 However, this is controlled by a file which is found, along with the
5063 other executables, in the directory for the specified version and
5064 target machine. As a result, a single installed driver program adapts
5065 to any specified target machine, and sufficiently similar compiler
5068 The driver program executable does control one significant thing,
5069 however: the default version and target machine. Therefore, you can
5070 install different instances of the driver program, compiled for
5071 different targets or versions, under different names.
5073 For example, if the driver for version 2.0 is installed as @command{ogcc}
5074 and that for version 2.1 is installed as @command{gcc}, then the command
5075 @command{gcc} will use version 2.1 by default, while @command{ogcc} will use
5076 2.0 by default. However, you can choose either version with either
5077 command with the @option{-V} option.
5079 @node Submodel Options
5080 @section Hardware Models and Configurations
5081 @cindex submodel options
5082 @cindex specifying hardware config
5083 @cindex hardware models and configurations, specifying
5084 @cindex machine dependent options
5086 Earlier we discussed the standard option @option{-b} which chooses among
5087 different installed compilers for completely different target
5088 machines, such as VAX vs.@: 68000 vs.@: 80386.
5090 In addition, each of these target machine types can have its own
5091 special options, starting with @samp{-m}, to choose among various
5092 hardware models or configurations---for example, 68010 vs 68020,
5093 floating coprocessor or none. A single installed version of the
5094 compiler can compile for any model or configuration, according to the
5097 Some configurations of the compiler also support additional special
5098 options, usually for compatibility with other compilers on the same
5101 These options are defined by the macro @code{TARGET_SWITCHES} in the
5102 machine description. The default for the options is also defined by
5103 that macro, which enables you to change the defaults.
5117 * RS/6000 and PowerPC Options::
5120 * i386 and x86-64 Options::
5122 * Intel 960 Options::
5123 * DEC Alpha Options::
5124 * DEC Alpha/VMS Options::
5128 * System V Options::
5129 * TMS320C3x/C4x Options::
5137 * S/390 and zSeries Options::
5141 * Xstormy16 Options::
5145 @node M680x0 Options
5146 @subsection M680x0 Options
5147 @cindex M680x0 options
5149 These are the @samp{-m} options defined for the 68000 series. The default
5150 values for these options depends on which style of 68000 was selected when
5151 the compiler was configured; the defaults for the most common choices are
5159 Generate output for a 68000. This is the default
5160 when the compiler is configured for 68000-based systems.
5162 Use this option for microcontrollers with a 68000 or EC000 core,
5163 including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
5169 Generate output for a 68020. This is the default
5170 when the compiler is configured for 68020-based systems.
5174 Generate output containing 68881 instructions for floating point.
5175 This is the default for most 68020 systems unless @option{--nfp} was
5176 specified when the compiler was configured.
5180 Generate output for a 68030. This is the default when the compiler is
5181 configured for 68030-based systems.
5185 Generate output for a 68040. This is the default when the compiler is
5186 configured for 68040-based systems.
5188 This option inhibits the use of 68881/68882 instructions that have to be
5189 emulated by software on the 68040. Use this option if your 68040 does not
5190 have code to emulate those instructions.
5194 Generate output for a 68060. This is the default when the compiler is
5195 configured for 68060-based systems.
5197 This option inhibits the use of 68020 and 68881/68882 instructions that
5198 have to be emulated by software on the 68060. Use this option if your 68060
5199 does not have code to emulate those instructions.
5203 Generate output for a CPU32. This is the default
5204 when the compiler is configured for CPU32-based systems.
5206 Use this option for microcontrollers with a
5207 CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
5208 68336, 68340, 68341, 68349 and 68360.
5212 Generate output for a 520X ``coldfire'' family cpu. This is the default
5213 when the compiler is configured for 520X-based systems.
5215 Use this option for microcontroller with a 5200 core, including
5216 the MCF5202, MCF5203, MCF5204 and MCF5202.
5221 Generate output for a 68040, without using any of the new instructions.
5222 This results in code which can run relatively efficiently on either a
5223 68020/68881 or a 68030 or a 68040. The generated code does use the
5224 68881 instructions that are emulated on the 68040.
5228 Generate output for a 68060, without using any of the new instructions.
5229 This results in code which can run relatively efficiently on either a
5230 68020/68881 or a 68030 or a 68040. The generated code does use the
5231 68881 instructions that are emulated on the 68060.
5235 Generate output containing Sun FPA instructions for floating point.
5238 @opindex msoft-float
5239 Generate output containing library calls for floating point.
5240 @strong{Warning:} the requisite libraries are not available for all m68k
5241 targets. Normally the facilities of the machine's usual C compiler are
5242 used, but this can't be done directly in cross-compilation. You must
5243 make your own arrangements to provide suitable library functions for
5244 cross-compilation. The embedded targets @samp{m68k-*-aout} and
5245 @samp{m68k-*-coff} do provide software floating point support.
5249 Consider type @code{int} to be 16 bits wide, like @code{short int}.
5252 @opindex mnobitfield
5253 Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
5254 and @option{-m5200} options imply @w{@option{-mnobitfield}}.
5258 Do use the bit-field instructions. The @option{-m68020} option implies
5259 @option{-mbitfield}. This is the default if you use a configuration
5260 designed for a 68020.
5264 Use a different function-calling convention, in which functions
5265 that take a fixed number of arguments return with the @code{rtd}
5266 instruction, which pops their arguments while returning. This
5267 saves one instruction in the caller since there is no need to pop
5268 the arguments there.
5270 This calling convention is incompatible with the one normally
5271 used on Unix, so you cannot use it if you need to call libraries
5272 compiled with the Unix compiler.
5274 Also, you must provide function prototypes for all functions that
5275 take variable numbers of arguments (including @code{printf});
5276 otherwise incorrect code will be generated for calls to those
5279 In addition, seriously incorrect code will result if you call a
5280 function with too many arguments. (Normally, extra arguments are
5281 harmlessly ignored.)
5283 The @code{rtd} instruction is supported by the 68010, 68020, 68030,
5284 68040, 68060 and CPU32 processors, but not by the 68000 or 5200.
5287 @itemx -mno-align-int
5289 @opindex mno-align-int
5290 Control whether GCC aligns @code{int}, @code{long}, @code{long long},
5291 @code{float}, @code{double}, and @code{long double} variables on a 32-bit
5292 boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
5293 Aligning variables on 32-bit boundaries produces code that runs somewhat
5294 faster on processors with 32-bit busses at the expense of more memory.
5296 @strong{Warning:} if you use the @option{-malign-int} switch, GCC will
5297 align structures containing the above types differently than
5298 most published application binary interface specifications for the m68k.
5302 Use the pc-relative addressing mode of the 68000 directly, instead of
5303 using a global offset table. At present, this option implies @option{-fpic},
5304 allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
5305 not presently supported with @option{-mpcrel}, though this could be supported for
5306 68020 and higher processors.
5308 @item -mno-strict-align
5309 @itemx -mstrict-align
5310 @opindex mno-strict-align
5311 @opindex mstrict-align
5312 Do not (do) assume that unaligned memory references will be handled by
5317 @node M68hc1x Options
5318 @subsection M68hc1x Options
5319 @cindex M68hc1x options
5321 These are the @samp{-m} options defined for the 68hc11 and 68hc12
5322 microcontrollers. The default values for these options depends on
5323 which style of microcontroller was selected when the compiler was configured;
5324 the defaults for the most common choices are given below.
5331 Generate output for a 68HC11. This is the default
5332 when the compiler is configured for 68HC11-based systems.
5338 Generate output for a 68HC12. This is the default
5339 when the compiler is configured for 68HC12-based systems.
5342 @opindex mauto-incdec
5343 Enable the use of 68HC12 pre and post auto-increment and auto-decrement
5348 Consider type @code{int} to be 16 bits wide, like @code{short int}.
5350 @item -msoft-reg-count=@var{count}
5351 @opindex msoft-reg-count
5352 Specify the number of pseudo-soft registers which are used for the
5353 code generation. The maximum number is 32. Using more pseudo-soft
5354 register may or may not result in better code depending on the program.
5355 The default is 4 for 68HC11 and 2 for 68HC12.
5360 @subsection VAX Options
5363 These @samp{-m} options are defined for the VAX:
5368 Do not output certain jump instructions (@code{aobleq} and so on)
5369 that the Unix assembler for the VAX cannot handle across long
5374 Do output those jump instructions, on the assumption that you
5375 will assemble with the GNU assembler.
5379 Output code for g-format floating point numbers instead of d-format.
5383 @subsection SPARC Options
5384 @cindex SPARC options
5386 These @samp{-m} switches are supported on the SPARC:
5391 @opindex mno-app-regs
5393 Specify @option{-mapp-regs} to generate output using the global registers
5394 2 through 4, which the SPARC SVR4 ABI reserves for applications. This
5397 To be fully SVR4 ABI compliant at the cost of some performance loss,
5398 specify @option{-mno-app-regs}. You should compile libraries and system
5399 software with this option.
5404 @opindex mhard-float
5405 Generate output containing floating point instructions. This is the
5411 @opindex msoft-float
5412 Generate output containing library calls for floating point.
5413 @strong{Warning:} the requisite libraries are not available for all SPARC
5414 targets. Normally the facilities of the machine's usual C compiler are
5415 used, but this cannot be done directly in cross-compilation. You must make
5416 your own arrangements to provide suitable library functions for
5417 cross-compilation. The embedded targets @samp{sparc-*-aout} and
5418 @samp{sparclite-*-*} do provide software floating point support.
5420 @option{-msoft-float} changes the calling convention in the output file;
5421 therefore, it is only useful if you compile @emph{all} of a program with
5422 this option. In particular, you need to compile @file{libgcc.a}, the
5423 library that comes with GCC, with @option{-msoft-float} in order for
5426 @item -mhard-quad-float
5427 @opindex mhard-quad-float
5428 Generate output containing quad-word (long double) floating point
5431 @item -msoft-quad-float
5432 @opindex msoft-quad-float
5433 Generate output containing library calls for quad-word (long double)
5434 floating point instructions. The functions called are those specified
5435 in the SPARC ABI@. This is the default.
5437 As of this writing, there are no sparc implementations that have hardware
5438 support for the quad-word floating point instructions. They all invoke
5439 a trap handler for one of these instructions, and then the trap handler
5440 emulates the effect of the instruction. Because of the trap handler overhead,
5441 this is much slower than calling the ABI library routines. Thus the
5442 @option{-msoft-quad-float} option is the default.
5446 @opindex mno-epilogue
5448 With @option{-mepilogue} (the default), the compiler always emits code for
5449 function exit at the end of each function. Any function exit in
5450 the middle of the function (such as a return statement in C) will
5451 generate a jump to the exit code at the end of the function.
5453 With @option{-mno-epilogue}, the compiler tries to emit exit code inline
5454 at every function exit.
5460 With @option{-mflat}, the compiler does not generate save/restore instructions
5461 and will use a ``flat'' or single register window calling convention.
5462 This model uses %i7 as the frame pointer and is compatible with the normal
5463 register window model. Code from either may be intermixed.
5464 The local registers and the input registers (0--5) are still treated as
5465 ``call saved'' registers and will be saved on the stack as necessary.
5467 With @option{-mno-flat} (the default), the compiler emits save/restore
5468 instructions (except for leaf functions) and is the normal mode of operation.
5470 @item -mno-unaligned-doubles
5471 @itemx -munaligned-doubles
5472 @opindex mno-unaligned-doubles
5473 @opindex munaligned-doubles
5474 Assume that doubles have 8 byte alignment. This is the default.
5476 With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
5477 alignment only if they are contained in another type, or if they have an
5478 absolute address. Otherwise, it assumes they have 4 byte alignment.
5479 Specifying this option avoids some rare compatibility problems with code
5480 generated by other compilers. It is not the default because it results
5481 in a performance loss, especially for floating point code.
5483 @item -mno-faster-structs
5484 @itemx -mfaster-structs
5485 @opindex mno-faster-structs
5486 @opindex mfaster-structs
5487 With @option{-mfaster-structs}, the compiler assumes that structures
5488 should have 8 byte alignment. This enables the use of pairs of
5489 @code{ldd} and @code{std} instructions for copies in structure
5490 assignment, in place of twice as many @code{ld} and @code{st} pairs.
5491 However, the use of this changed alignment directly violates the Sparc
5492 ABI@. Thus, it's intended only for use on targets where the developer
5493 acknowledges that their resulting code will not be directly in line with
5494 the rules of the ABI@.
5500 These two options select variations on the SPARC architecture.
5502 By default (unless specifically configured for the Fujitsu SPARClite),
5503 GCC generates code for the v7 variant of the SPARC architecture.
5505 @option{-mv8} will give you SPARC v8 code. The only difference from v7
5506 code is that the compiler emits the integer multiply and integer
5507 divide instructions which exist in SPARC v8 but not in SPARC v7.
5509 @option{-msparclite} will give you SPARClite code. This adds the integer
5510 multiply, integer divide step and scan (@code{ffs}) instructions which
5511 exist in SPARClite but not in SPARC v7.
5513 These options are deprecated and will be deleted in a future GCC release.
5514 They have been replaced with @option{-mcpu=xxx}.
5519 @opindex msupersparc
5520 These two options select the processor for which the code is optimized.
5522 With @option{-mcypress} (the default), the compiler optimizes code for the
5523 Cypress CY7C602 chip, as used in the SparcStation/SparcServer 3xx series.
5524 This is also appropriate for the older SparcStation 1, 2, IPX etc.
5526 With @option{-msupersparc} the compiler optimizes code for the SuperSparc cpu, as
5527 used in the SparcStation 10, 1000 and 2000 series. This flag also enables use
5528 of the full SPARC v8 instruction set.
5530 These options are deprecated and will be deleted in a future GCC release.
5531 They have been replaced with @option{-mcpu=xxx}.
5533 @item -mcpu=@var{cpu_type}
5535 Set the instruction set, register set, and instruction scheduling parameters
5536 for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
5537 @samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
5538 @samp{hypersparc}, @samp{sparclite86x}, @samp{f930}, @samp{f934},
5539 @samp{sparclet}, @samp{tsc701}, @samp{v9}, and @samp{ultrasparc}.
5541 Default instruction scheduling parameters are used for values that select
5542 an architecture and not an implementation. These are @samp{v7}, @samp{v8},
5543 @samp{sparclite}, @samp{sparclet}, @samp{v9}.
5545 Here is a list of each supported architecture and their supported
5550 v8: supersparc, hypersparc
5551 sparclite: f930, f934, sparclite86x
5556 @item -mtune=@var{cpu_type}
5558 Set the instruction scheduling parameters for machine type
5559 @var{cpu_type}, but do not set the instruction set or register set that the
5560 option @option{-mcpu=@var{cpu_type}} would.
5562 The same values for @option{-mcpu=@var{cpu_type}} can be used for
5563 @option{-mtune=@var{cpu_type}}, but the only useful values are those
5564 that select a particular cpu implementation. Those are @samp{cypress},
5565 @samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
5566 @samp{sparclite86x}, @samp{tsc701}, and @samp{ultrasparc}.
5570 These @samp{-m} switches are supported in addition to the above
5571 on the SPARCLET processor.
5574 @item -mlittle-endian
5575 @opindex mlittle-endian
5576 Generate code for a processor running in little-endian mode.
5580 Treat register @code{%g0} as a normal register.
5581 GCC will continue to clobber it as necessary but will not assume
5582 it always reads as 0.
5584 @item -mbroken-saverestore
5585 @opindex mbroken-saverestore
5586 Generate code that does not use non-trivial forms of the @code{save} and
5587 @code{restore} instructions. Early versions of the SPARCLET processor do
5588 not correctly handle @code{save} and @code{restore} instructions used with
5589 arguments. They correctly handle them used without arguments. A @code{save}
5590 instruction used without arguments increments the current window pointer
5591 but does not allocate a new stack frame. It is assumed that the window
5592 overflow trap handler will properly handle this case as will interrupt
5596 These @samp{-m} switches are supported in addition to the above
5597 on SPARC V9 processors in 64-bit environments.
5600 @item -mlittle-endian
5601 @opindex mlittle-endian
5602 Generate code for a processor running in little-endian mode.
5608 Generate code for a 32-bit or 64-bit environment.
5609 The 32-bit environment sets int, long and pointer to 32 bits.
5610 The 64-bit environment sets int to 32 bits and long and pointer
5613 @item -mcmodel=medlow
5614 @opindex mcmodel=medlow
5615 Generate code for the Medium/Low code model: the program must be linked
5616 in the low 32 bits of the address space. Pointers are 64 bits.
5617 Programs can be statically or dynamically linked.
5619 @item -mcmodel=medmid
5620 @opindex mcmodel=medmid
5621 Generate code for the Medium/Middle code model: the program must be linked
5622 in the low 44 bits of the address space, the text segment must be less than
5623 2G bytes, and data segment must be within 2G of the text segment.
5624 Pointers are 64 bits.
5626 @item -mcmodel=medany
5627 @opindex mcmodel=medany
5628 Generate code for the Medium/Anywhere code model: the program may be linked
5629 anywhere in the address space, the text segment must be less than
5630 2G bytes, and data segment must be within 2G of the text segment.
5631 Pointers are 64 bits.
5633 @item -mcmodel=embmedany
5634 @opindex mcmodel=embmedany
5635 Generate code for the Medium/Anywhere code model for embedded systems:
5636 assume a 32-bit text and a 32-bit data segment, both starting anywhere
5637 (determined at link time). Register %g4 points to the base of the
5638 data segment. Pointers are still 64 bits.
5639 Programs are statically linked, PIC is not supported.
5642 @itemx -mno-stack-bias
5643 @opindex mstack-bias
5644 @opindex mno-stack-bias
5645 With @option{-mstack-bias}, GCC assumes that the stack pointer, and
5646 frame pointer if present, are offset by @minus{}2047 which must be added back
5647 when making stack frame references.
5648 Otherwise, assume no such offset is present.
5651 @node Convex Options
5652 @subsection Convex Options
5653 @cindex Convex options
5655 These @samp{-m} options are defined for Convex:
5660 Generate output for C1. The code will run on any Convex machine.
5661 The preprocessor symbol @code{__convex__c1__} is defined.
5665 Generate output for C2. Uses instructions not available on C1.
5666 Scheduling and other optimizations are chosen for max performance on C2.
5667 The preprocessor symbol @code{__convex_c2__} is defined.
5671 Generate output for C32xx. Uses instructions not available on C1.
5672 Scheduling and other optimizations are chosen for max performance on C32.
5673 The preprocessor symbol @code{__convex_c32__} is defined.
5677 Generate output for C34xx. Uses instructions not available on C1.
5678 Scheduling and other optimizations are chosen for max performance on C34.
5679 The preprocessor symbol @code{__convex_c34__} is defined.
5683 Generate output for C38xx. Uses instructions not available on C1.
5684 Scheduling and other optimizations are chosen for max performance on C38.
5685 The preprocessor symbol @code{__convex_c38__} is defined.
5689 Generate code which puts an argument count in the word preceding each
5690 argument list. This is compatible with regular CC, and a few programs
5691 may need the argument count word. GDB and other source-level debuggers
5692 do not need it; this info is in the symbol table.
5695 @opindex mnoargcount
5696 Omit the argument count word. This is the default.
5698 @item -mvolatile-cache
5699 @opindex mvolatile-cache
5700 Allow volatile references to be cached. This is the default.
5702 @item -mvolatile-nocache
5703 @opindex mvolatile-nocache
5704 Volatile references bypass the data cache, going all the way to memory.
5705 This is only needed for multi-processor code that does not use standard
5706 synchronization instructions. Making non-volatile references to volatile
5707 locations will not necessarily work.
5711 Type long is 32 bits, the same as type int. This is the default.
5715 Type long is 64 bits, the same as type long long. This option is useless,
5716 because no library support exists for it.
5719 @node AMD29K Options
5720 @subsection AMD29K Options
5721 @cindex AMD29K options
5723 These @samp{-m} options are defined for the AMD Am29000:
5728 @cindex DW bit (29k)
5729 Generate code that assumes the @code{DW} bit is set, i.e., that byte and
5730 halfword operations are directly supported by the hardware. This is the
5735 Generate code that assumes the @code{DW} bit is not set.
5739 @cindex byte writes (29k)
5740 Generate code that assumes the system supports byte and halfword write
5741 operations. This is the default.
5745 Generate code that assumes the systems does not support byte and
5746 halfword write operations. @option{-mnbw} implies @option{-mndw}.
5750 @cindex memory model (29k)
5751 Use a small memory model that assumes that all function addresses are
5752 either within a single 256 KB segment or at an absolute address of less
5753 than 256k. This allows the @code{call} instruction to be used instead
5754 of a @code{const}, @code{consth}, @code{calli} sequence.
5758 Use the normal memory model: Generate @code{call} instructions only when
5759 calling functions in the same file and @code{calli} instructions
5760 otherwise. This works if each file occupies less than 256 KB but allows
5761 the entire executable to be larger than 256 KB@. This is the default.
5765 Always use @code{calli} instructions. Specify this option if you expect
5766 a single file to compile into more than 256 KB of code.
5770 @cindex processor selection (29k)
5771 Generate code for the Am29050.
5775 Generate code for the Am29000. This is the default.
5777 @item -mkernel-registers
5778 @opindex mkernel-registers
5779 @cindex kernel and user registers (29k)
5780 Generate references to registers @code{gr64-gr95} instead of to
5781 registers @code{gr96-gr127}. This option can be used when compiling
5782 kernel code that wants a set of global registers disjoint from that used
5785 Note that when this option is used, register names in @samp{-f} flags
5786 must use the normal, user-mode, names.
5788 @item -muser-registers
5789 @opindex muser-registers
5790 Use the normal set of global registers, @code{gr96-gr127}. This is the
5794 @itemx -mno-stack-check
5795 @opindex mstack-check
5796 @opindex mno-stack-check
5797 @cindex stack checks (29k)
5798 Insert (or do not insert) a call to @code{__msp_check} after each stack
5799 adjustment. This is often used for kernel code.
5802 @itemx -mno-storem-bug
5803 @opindex mstorem-bug
5804 @opindex mno-storem-bug
5805 @cindex storem bug (29k)
5806 @option{-mstorem-bug} handles 29k processors which cannot handle the
5807 separation of a mtsrim insn and a storem instruction (most 29000 chips
5808 to date, but not the 29050).
5810 @item -mno-reuse-arg-regs
5811 @itemx -mreuse-arg-regs
5812 @opindex mno-reuse-arg-regs
5813 @opindex mreuse-arg-regs
5814 @option{-mno-reuse-arg-regs} tells the compiler to only use incoming argument
5815 registers for copying out arguments. This helps detect calling a function
5816 with fewer arguments than it was declared with.
5818 @item -mno-impure-text
5819 @itemx -mimpure-text
5820 @opindex mno-impure-text
5821 @opindex mimpure-text
5822 @option{-mimpure-text}, used in addition to @option{-shared}, tells the compiler to
5823 not pass @option{-assert pure-text} to the linker when linking a shared object.
5826 @opindex msoft-float
5827 Generate output containing library calls for floating point.
5828 @strong{Warning:} the requisite libraries are not part of GCC@.
5829 Normally the facilities of the machine's usual C compiler are used, but
5830 this can't be done directly in cross-compilation. You must make your
5831 own arrangements to provide suitable library functions for
5836 Do not generate multm or multmu instructions. This is useful for some embedded
5837 systems which do not have trap handlers for these instructions.
5841 @subsection ARM Options
5844 These @samp{-m} options are defined for Advanced RISC Machines (ARM)
5849 @opindex mapcs-frame
5850 Generate a stack frame that is compliant with the ARM Procedure Call
5851 Standard for all functions, even if this is not strictly necessary for
5852 correct execution of the code. Specifying @option{-fomit-frame-pointer}
5853 with this option will cause the stack frames not to be generated for
5854 leaf functions. The default is @option{-mno-apcs-frame}.
5858 This is a synonym for @option{-mapcs-frame}.
5862 Generate code for a processor running with a 26-bit program counter,
5863 and conforming to the function calling standards for the APCS 26-bit
5864 option. This option replaces the @option{-m2} and @option{-m3} options
5865 of previous releases of the compiler.
5869 Generate code for a processor running with a 32-bit program counter,
5870 and conforming to the function calling standards for the APCS 32-bit
5871 option. This option replaces the @option{-m6} option of previous releases
5875 @c not currently implemented
5876 @item -mapcs-stack-check
5877 @opindex mapcs-stack-check
5878 Generate code to check the amount of stack space available upon entry to
5879 every function (that actually uses some stack space). If there is
5880 insufficient space available then either the function
5881 @samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
5882 called, depending upon the amount of stack space required. The run time
5883 system is required to provide these functions. The default is
5884 @option{-mno-apcs-stack-check}, since this produces smaller code.
5886 @c not currently implemented
5888 @opindex mapcs-float
5889 Pass floating point arguments using the float point registers. This is
5890 one of the variants of the APCS@. This option is recommended if the
5891 target hardware has a floating point unit or if a lot of floating point
5892 arithmetic is going to be performed by the code. The default is
5893 @option{-mno-apcs-float}, since integer only code is slightly increased in
5894 size if @option{-mapcs-float} is used.
5896 @c not currently implemented
5897 @item -mapcs-reentrant
5898 @opindex mapcs-reentrant
5899 Generate reentrant, position independent code. The default is
5900 @option{-mno-apcs-reentrant}.
5903 @item -mthumb-interwork
5904 @opindex mthumb-interwork
5905 Generate code which supports calling between the ARM and Thumb
5906 instruction sets. Without this option the two instruction sets cannot
5907 be reliably used inside one program. The default is
5908 @option{-mno-thumb-interwork}, since slightly larger code is generated
5909 when @option{-mthumb-interwork} is specified.
5911 @item -mno-sched-prolog
5912 @opindex mno-sched-prolog
5913 Prevent the reordering of instructions in the function prolog, or the
5914 merging of those instruction with the instructions in the function's
5915 body. This means that all functions will start with a recognizable set
5916 of instructions (or in fact one of a choice from a small set of
5917 different function prologues), and this information can be used to
5918 locate the start if functions inside an executable piece of code. The
5919 default is @option{-msched-prolog}.
5922 @opindex mhard-float
5923 Generate output containing floating point instructions. This is the
5927 @opindex msoft-float
5928 Generate output containing library calls for floating point.
5929 @strong{Warning:} the requisite libraries are not available for all ARM
5930 targets. Normally the facilities of the machine's usual C compiler are
5931 used, but this cannot be done directly in cross-compilation. You must make
5932 your own arrangements to provide suitable library functions for
5935 @option{-msoft-float} changes the calling convention in the output file;
5936 therefore, it is only useful if you compile @emph{all} of a program with
5937 this option. In particular, you need to compile @file{libgcc.a}, the
5938 library that comes with GCC, with @option{-msoft-float} in order for
5941 @item -mlittle-endian
5942 @opindex mlittle-endian
5943 Generate code for a processor running in little-endian mode. This is
5944 the default for all standard configurations.
5947 @opindex mbig-endian
5948 Generate code for a processor running in big-endian mode; the default is
5949 to compile code for a little-endian processor.
5951 @item -mwords-little-endian
5952 @opindex mwords-little-endian
5953 This option only applies when generating code for big-endian processors.
5954 Generate code for a little-endian word order but a big-endian byte
5955 order. That is, a byte order of the form @samp{32107654}. Note: this
5956 option should only be used if you require compatibility with code for
5957 big-endian ARM processors generated by versions of the compiler prior to
5960 @item -malignment-traps
5961 @opindex malignment-traps
5962 Generate code that will not trap if the MMU has alignment traps enabled.
5963 On ARM architectures prior to ARMv4, there were no instructions to
5964 access half-word objects stored in memory. However, when reading from
5965 memory a feature of the ARM architecture allows a word load to be used,
5966 even if the address is unaligned, and the processor core will rotate the
5967 data as it is being loaded. This option tells the compiler that such
5968 misaligned accesses will cause a MMU trap and that it should instead
5969 synthesise the access as a series of byte accesses. The compiler can
5970 still use word accesses to load half-word data if it knows that the
5971 address is aligned to a word boundary.
5973 This option is ignored when compiling for ARM architecture 4 or later,
5974 since these processors have instructions to directly access half-word
5977 @item -mno-alignment-traps
5978 @opindex mno-alignment-traps
5979 Generate code that assumes that the MMU will not trap unaligned
5980 accesses. This produces better code when the target instruction set
5981 does not have half-word memory operations (i.e.@: implementations prior to
5984 Note that you cannot use this option to access unaligned word objects,
5985 since the processor will only fetch one 32-bit aligned object from
5988 The default setting for most targets is @option{-mno-alignment-traps}, since
5989 this produces better code when there are no half-word memory
5990 instructions available.
5992 @item -mshort-load-bytes
5993 @itemx -mno-short-load-words
5994 @opindex mshort-load-bytes
5995 @opindex mno-short-load-words
5996 These are deprecated aliases for @option{-malignment-traps}.
5998 @item -mno-short-load-bytes
5999 @itemx -mshort-load-words
6000 @opindex mno-short-load-bytes
6001 @opindex mshort-load-words
6002 This are deprecated aliases for @option{-mno-alignment-traps}.
6006 This option only applies to RISC iX@. Emulate the native BSD-mode
6007 compiler. This is the default if @option{-ansi} is not specified.
6011 This option only applies to RISC iX@. Emulate the native X/Open-mode
6014 @item -mno-symrename
6015 @opindex mno-symrename
6016 This option only applies to RISC iX@. Do not run the assembler
6017 post-processor, @samp{symrename}, after code has been assembled.
6018 Normally it is necessary to modify some of the standard symbols in
6019 preparation for linking with the RISC iX C library; this option
6020 suppresses this pass. The post-processor is never run when the
6021 compiler is built for cross-compilation.
6023 @item -mcpu=@var{name}
6025 This specifies the name of the target ARM processor. GCC uses this name
6026 to determine what kind of instructions it can emit when generating
6027 assembly code. Permissible names are: @samp{arm2}, @samp{arm250},
6028 @samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
6029 @samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
6030 @samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
6031 @samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
6032 @samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm8},
6033 @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
6034 @samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
6035 @samp{arm920t}, @samp{arm940t}, @samp{arm9tdmi}, @samp{arm10tdmi},
6036 @samp{arm1020t}, @samp{xscale}.
6038 @itemx -mtune=@var{name}
6040 This option is very similar to the @option{-mcpu=} option, except that
6041 instead of specifying the actual target processor type, and hence
6042 restricting which instructions can be used, it specifies that GCC should
6043 tune the performance of the code as if the target were of the type
6044 specified in this option, but still choosing the instructions that it
6045 will generate based on the cpu specified by a @option{-mcpu=} option.
6046 For some ARM implementations better performance can be obtained by using
6049 @item -march=@var{name}
6051 This specifies the name of the target ARM architecture. GCC uses this
6052 name to determine what kind of instructions it can emit when generating
6053 assembly code. This option can be used in conjunction with or instead
6054 of the @option{-mcpu=} option. Permissible names are: @samp{armv2},
6055 @samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
6056 @samp{armv5}, @samp{armv5t}, @samp{armv5te}.
6058 @item -mfpe=@var{number}
6059 @itemx -mfp=@var{number}
6062 This specifies the version of the floating point emulation available on
6063 the target. Permissible values are 2 and 3. @option{-mfp=} is a synonym
6064 for @option{-mfpe=}, for compatibility with older versions of GCC@.
6066 @item -mstructure-size-boundary=@var{n}
6067 @opindex mstructure-size-boundary
6068 The size of all structures and unions will be rounded up to a multiple
6069 of the number of bits set by this option. Permissible values are 8 and
6070 32. The default value varies for different toolchains. For the COFF
6071 targeted toolchain the default value is 8. Specifying the larger number
6072 can produce faster, more efficient code, but can also increase the size
6073 of the program. The two values are potentially incompatible. Code
6074 compiled with one value cannot necessarily expect to work with code or
6075 libraries compiled with the other value, if they exchange information
6076 using structures or unions.
6078 @item -mabort-on-noreturn
6079 @opindex mabort-on-noreturn
6080 Generate a call to the function @code{abort} at the end of a
6081 @code{noreturn} function. It will be executed if the function tries to
6085 @itemx -mno-long-calls
6086 @opindex mlong-calls
6087 @opindex mno-long-calls
6088 Tells the compiler to perform function calls by first loading the
6089 address of the function into a register and then performing a subroutine
6090 call on this register. This switch is needed if the target function
6091 will lie outside of the 64 megabyte addressing range of the offset based
6092 version of subroutine call instruction.
6094 Even if this switch is enabled, not all function calls will be turned
6095 into long calls. The heuristic is that static functions, functions
6096 which have the @samp{short-call} attribute, functions that are inside
6097 the scope of a @samp{#pragma no_long_calls} directive and functions whose
6098 definitions have already been compiled within the current compilation
6099 unit, will not be turned into long calls. The exception to this rule is
6100 that weak function definitions, functions with the @samp{long-call}
6101 attribute or the @samp{section} attribute, and functions that are within
6102 the scope of a @samp{#pragma long_calls} directive, will always be
6103 turned into long calls.
6105 This feature is not enabled by default. Specifying
6106 @option{-mno-long-calls} will restore the default behavior, as will
6107 placing the function calls within the scope of a @samp{#pragma
6108 long_calls_off} directive. Note these switches have no effect on how
6109 the compiler generates code to handle function calls via function
6112 @item -mnop-fun-dllimport
6113 @opindex mnop-fun-dllimport
6114 Disable support for the @code{dllimport} attribute.
6116 @item -msingle-pic-base
6117 @opindex msingle-pic-base
6118 Treat the register used for PIC addressing as read-only, rather than
6119 loading it in the prologue for each function. The run-time system is
6120 responsible for initializing this register with an appropriate value
6121 before execution begins.
6123 @item -mpic-register=@var{reg}
6124 @opindex mpic-register
6125 Specify the register to be used for PIC addressing. The default is R10
6126 unless stack-checking is enabled, when R9 is used.
6128 @item -mpoke-function-name
6129 @opindex mpoke-function-name
6130 Write the name of each function into the text section, directly
6131 preceding the function prologue. The generated code is similar to this:
6135 .ascii "arm_poke_function_name", 0
6138 .word 0xff000000 + (t1 - t0)
6139 arm_poke_function_name
6141 stmfd sp!, @{fp, ip, lr, pc@}
6145 When performing a stack backtrace, code can inspect the value of
6146 @code{pc} stored at @code{fp + 0}. If the trace function then looks at
6147 location @code{pc - 12} and the top 8 bits are set, then we know that
6148 there is a function name embedded immediately preceding this location
6149 and has length @code{((pc[-3]) & 0xff000000)}.
6153 Generate code for the 16-bit Thumb instruction set. The default is to
6154 use the 32-bit ARM instruction set.
6157 @opindex mtpcs-frame
6158 Generate a stack frame that is compliant with the Thumb Procedure Call
6159 Standard for all non-leaf functions. (A leaf function is one that does
6160 not call any other functions.) The default is @option{-mno-tpcs-frame}.
6162 @item -mtpcs-leaf-frame
6163 @opindex mtpcs-leaf-frame
6164 Generate a stack frame that is compliant with the Thumb Procedure Call
6165 Standard for all leaf functions. (A leaf function is one that does
6166 not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
6168 @item -mcallee-super-interworking
6169 @opindex mcallee-super-interworking
6170 Gives all externally visible functions in the file being compiled an ARM
6171 instruction set header which switches to Thumb mode before executing the
6172 rest of the function. This allows these functions to be called from
6173 non-interworking code.
6175 @item -mcaller-super-interworking
6176 @opindex mcaller-super-interworking
6177 Allows calls via function pointers (including virtual functions) to
6178 execute correctly regardless of whether the target code has been
6179 compiled for interworking or not. There is a small overhead in the cost
6180 of executing a function pointer if this option is enabled.
6184 @node MN10200 Options
6185 @subsection MN10200 Options
6186 @cindex MN10200 options
6187 These @option{-m} options are defined for Matsushita MN10200 architectures:
6192 Indicate to the linker that it should perform a relaxation optimization pass
6193 to shorten branches, calls and absolute memory addresses. This option only
6194 has an effect when used on the command line for the final link step.
6196 This option makes symbolic debugging impossible.
6199 @node MN10300 Options
6200 @subsection MN10300 Options
6201 @cindex MN10300 options
6202 These @option{-m} options are defined for Matsushita MN10300 architectures:
6207 Generate code to avoid bugs in the multiply instructions for the MN10300
6208 processors. This is the default.
6211 @opindex mno-mult-bug
6212 Do not generate code to avoid bugs in the multiply instructions for the
6217 Generate code which uses features specific to the AM33 processor.
6221 Do not generate code which uses features specific to the AM33 processor. This
6226 Do not link in the C run-time initialization object file.
6230 Indicate to the linker that it should perform a relaxation optimization pass
6231 to shorten branches, calls and absolute memory addresses. This option only
6232 has an effect when used on the command line for the final link step.
6234 This option makes symbolic debugging impossible.
6238 @node M32R/D Options
6239 @subsection M32R/D Options
6240 @cindex M32R/D options
6242 These @option{-m} options are defined for Mitsubishi M32R/D architectures:
6247 Generate code for the M32R/X@.
6251 Generate code for the M32R@. This is the default.
6253 @item -mcode-model=small
6254 @opindex mcode-model=small
6255 Assume all objects live in the lower 16MB of memory (so that their addresses
6256 can be loaded with the @code{ld24} instruction), and assume all subroutines
6257 are reachable with the @code{bl} instruction.
6258 This is the default.
6260 The addressability of a particular object can be set with the
6261 @code{model} attribute.
6263 @item -mcode-model=medium
6264 @opindex mcode-model=medium
6265 Assume objects may be anywhere in the 32-bit address space (the compiler
6266 will generate @code{seth/add3} instructions to load their addresses), and
6267 assume all subroutines are reachable with the @code{bl} instruction.
6269 @item -mcode-model=large
6270 @opindex mcode-model=large
6271 Assume objects may be anywhere in the 32-bit address space (the compiler
6272 will generate @code{seth/add3} instructions to load their addresses), and
6273 assume subroutines may not be reachable with the @code{bl} instruction
6274 (the compiler will generate the much slower @code{seth/add3/jl}
6275 instruction sequence).
6278 @opindex msdata=none
6279 Disable use of the small data area. Variables will be put into
6280 one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
6281 @code{section} attribute has been specified).
6282 This is the default.
6284 The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
6285 Objects may be explicitly put in the small data area with the
6286 @code{section} attribute using one of these sections.
6289 @opindex msdata=sdata
6290 Put small global and static data in the small data area, but do not
6291 generate special code to reference them.
6295 Put small global and static data in the small data area, and generate
6296 special instructions to reference them.
6300 @cindex smaller data references
6301 Put global and static objects less than or equal to @var{num} bytes
6302 into the small data or bss sections instead of the normal data or bss
6303 sections. The default value of @var{num} is 8.
6304 The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
6305 for this option to have any effect.
6307 All modules should be compiled with the same @option{-G @var{num}} value.
6308 Compiling with different values of @var{num} may or may not work; if it
6309 doesn't the linker will give an error message---incorrect code will not be
6315 @subsection M88K Options
6316 @cindex M88k options
6318 These @samp{-m} options are defined for Motorola 88k architectures:
6323 Generate code that works well on both the m88100 and the
6328 Generate code that works best for the m88100, but that also
6333 Generate code that works best for the m88110, and may not run
6338 Obsolete option to be removed from the next revision.
6341 @item -midentify-revision
6342 @opindex midentify-revision
6343 @cindex identifying source, compiler (88k)
6344 Include an @code{ident} directive in the assembler output recording the
6345 source file name, compiler name and version, timestamp, and compilation
6348 @item -mno-underscores
6349 @opindex mno-underscores
6350 @cindex underscores, avoiding (88k)
6351 In assembler output, emit symbol names without adding an underscore
6352 character at the beginning of each name. The default is to use an
6353 underscore as prefix on each name.
6355 @item -mocs-debug-info
6356 @itemx -mno-ocs-debug-info
6357 @opindex mocs-debug-info
6358 @opindex mno-ocs-debug-info
6360 @cindex debugging, 88k OCS
6361 Include (or omit) additional debugging information (about registers used
6362 in each stack frame) as specified in the 88open Object Compatibility
6363 Standard, ``OCS''@. This extra information allows debugging of code that
6364 has had the frame pointer eliminated. The default for DG/UX, SVr4, and
6365 Delta 88 SVr3.2 is to include this information; other 88k configurations
6366 omit this information by default.
6368 @item -mocs-frame-position
6369 @opindex mocs-frame-position
6370 @cindex register positions in frame (88k)
6371 When emitting COFF debugging information for automatic variables and
6372 parameters stored on the stack, use the offset from the canonical frame
6373 address, which is the stack pointer (register 31) on entry to the
6374 function. The DG/UX, SVr4, Delta88 SVr3.2, and BCS configurations use
6375 @option{-mocs-frame-position}; other 88k configurations have the default
6376 @option{-mno-ocs-frame-position}.
6378 @item -mno-ocs-frame-position
6379 @opindex mno-ocs-frame-position
6380 @cindex register positions in frame (88k)
6381 When emitting COFF debugging information for automatic variables and
6382 parameters stored on the stack, use the offset from the frame pointer
6383 register (register 30). When this option is in effect, the frame
6384 pointer is not eliminated when debugging information is selected by the
6387 @item -moptimize-arg-area
6388 @opindex moptimize-arg-area
6389 @cindex arguments in frame (88k)
6390 Save space by reorganizing the stack frame. This option generates code
6391 that does not agree with the 88open specifications, but uses less
6394 @itemx -mno-optimize-arg-area
6395 @opindex mno-optimize-arg-area
6396 Do not reorganize the stack frame to save space. This is the default.
6397 The generated conforms to the specification, but uses more memory.
6399 @item -mshort-data-@var{num}
6400 @opindex mshort-data
6401 @cindex smaller data references (88k)
6402 @cindex r0-relative references (88k)
6403 Generate smaller data references by making them relative to @code{r0},
6404 which allows loading a value using a single instruction (rather than the
6405 usual two). You control which data references are affected by
6406 specifying @var{num} with this option. For example, if you specify
6407 @option{-mshort-data-512}, then the data references affected are those
6408 involving displacements of less than 512 bytes.
6409 @option{-mshort-data-@var{num}} is not effective for @var{num} greater
6412 @item -mserialize-volatile
6413 @opindex mserialize-volatile
6414 @itemx -mno-serialize-volatile
6415 @opindex mno-serialize-volatile
6416 @cindex sequential consistency on 88k
6417 Do, or don't, generate code to guarantee sequential consistency
6418 of volatile memory references. By default, consistency is
6421 The order of memory references made by the MC88110 processor does
6422 not always match the order of the instructions requesting those
6423 references. In particular, a load instruction may execute before
6424 a preceding store instruction. Such reordering violates
6425 sequential consistency of volatile memory references, when there
6426 are multiple processors. When consistency must be guaranteed,
6427 GCC generates special instructions, as needed, to force
6428 execution in the proper order.
6430 The MC88100 processor does not reorder memory references and so
6431 always provides sequential consistency. However, by default, GCC
6432 generates the special instructions to guarantee consistency
6433 even when you use @option{-m88100}, so that the code may be run on an
6434 MC88110 processor. If you intend to run your code only on the
6435 MC88100 processor, you may use @option{-mno-serialize-volatile}.
6437 The extra code generated to guarantee consistency may affect the
6438 performance of your application. If you know that you can safely
6439 forgo this guarantee, you may use @option{-mno-serialize-volatile}.
6445 @cindex assembler syntax, 88k
6447 Turn on (@option{-msvr4}) or off (@option{-msvr3}) compiler extensions
6448 related to System V release 4 (SVr4). This controls the following:
6452 Which variant of the assembler syntax to emit.
6454 @option{-msvr4} makes the C preprocessor recognize @samp{#pragma weak}
6455 that is used on System V release 4.
6457 @option{-msvr4} makes GCC issue additional declaration directives used in
6461 @option{-msvr4} is the default for the m88k-motorola-sysv4 and
6462 m88k-dg-dgux m88k configurations. @option{-msvr3} is the default for all
6463 other m88k configurations.
6465 @item -mversion-03.00
6466 @opindex mversion-03.00
6467 This option is obsolete, and is ignored.
6468 @c ??? which asm syntax better for GAS? option there too?
6470 @item -mno-check-zero-division
6471 @itemx -mcheck-zero-division
6472 @opindex mno-check-zero-division
6473 @opindex mcheck-zero-division
6474 @cindex zero division on 88k
6475 Do, or don't, generate code to guarantee that integer division by
6476 zero will be detected. By default, detection is guaranteed.
6478 Some models of the MC88100 processor fail to trap upon integer
6479 division by zero under certain conditions. By default, when
6480 compiling code that might be run on such a processor, GCC
6481 generates code that explicitly checks for zero-valued divisors
6482 and traps with exception number 503 when one is detected. Use of
6483 @option{-mno-check-zero-division} suppresses such checking for code
6484 generated to run on an MC88100 processor.
6486 GCC assumes that the MC88110 processor correctly detects all instances
6487 of integer division by zero. When @option{-m88110} is specified, no
6488 explicit checks for zero-valued divisors are generated, and both
6489 @option{-mcheck-zero-division} and @option{-mno-check-zero-division} are
6492 @item -muse-div-instruction
6493 @opindex muse-div-instruction
6494 @cindex divide instruction, 88k
6495 Use the div instruction for signed integer division on the
6496 MC88100 processor. By default, the div instruction is not used.
6498 On the MC88100 processor the signed integer division instruction
6499 div) traps to the operating system on a negative operand. The
6500 operating system transparently completes the operation, but at a
6501 large cost in execution time. By default, when compiling code
6502 that might be run on an MC88100 processor, GCC emulates signed
6503 integer division using the unsigned integer division instruction
6504 divu), thereby avoiding the large penalty of a trap to the
6505 operating system. Such emulation has its own, smaller, execution
6506 cost in both time and space. To the extent that your code's
6507 important signed integer division operations are performed on two
6508 nonnegative operands, it may be desirable to use the div
6509 instruction directly.
6511 On the MC88110 processor the div instruction (also known as the
6512 divs instruction) processes negative operands without trapping to
6513 the operating system. When @option{-m88110} is specified,
6514 @option{-muse-div-instruction} is ignored, and the div instruction is used
6515 for signed integer division.
6517 Note that the result of dividing @code{INT_MIN} by @minus{}1 is undefined. In
6518 particular, the behavior of such a division with and without
6519 @option{-muse-div-instruction} may differ.
6521 @item -mtrap-large-shift
6522 @itemx -mhandle-large-shift
6523 @opindex mtrap-large-shift
6524 @opindex mhandle-large-shift
6525 @cindex bit shift overflow (88k)
6526 @cindex large bit shifts (88k)
6527 Include code to detect bit-shifts of more than 31 bits; respectively,
6528 trap such shifts or emit code to handle them properly. By default GCC
6529 makes no special provision for large bit shifts.
6531 @item -mwarn-passed-structs
6532 @opindex mwarn-passed-structs
6533 @cindex structure passing (88k)
6534 Warn when a function passes a struct as an argument or result.
6535 Structure-passing conventions have changed during the evolution of the C
6536 language, and are often the source of portability problems. By default,
6537 GCC issues no such warning.
6540 @c break page here to avoid unsightly interparagraph stretch.
6544 @node RS/6000 and PowerPC Options
6545 @subsection IBM RS/6000 and PowerPC Options
6546 @cindex RS/6000 and PowerPC Options
6547 @cindex IBM RS/6000 and PowerPC Options
6549 These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
6557 @itemx -mpowerpc-gpopt
6558 @itemx -mno-powerpc-gpopt
6559 @itemx -mpowerpc-gfxopt
6560 @itemx -mno-powerpc-gfxopt
6562 @itemx -mno-powerpc64
6568 @opindex mno-powerpc
6569 @opindex mpowerpc-gpopt
6570 @opindex mno-powerpc-gpopt
6571 @opindex mpowerpc-gfxopt
6572 @opindex mno-powerpc-gfxopt
6574 @opindex mno-powerpc64
6575 GCC supports two related instruction set architectures for the
6576 RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those
6577 instructions supported by the @samp{rios} chip set used in the original
6578 RS/6000 systems and the @dfn{PowerPC} instruction set is the
6579 architecture of the Motorola MPC5xx, MPC6xx, MPC8xx microprocessors, and
6580 the IBM 4xx microprocessors.
6582 Neither architecture is a subset of the other. However there is a
6583 large common subset of instructions supported by both. An MQ
6584 register is included in processors supporting the POWER architecture.
6586 You use these options to specify which instructions are available on the
6587 processor you are using. The default value of these options is
6588 determined when configuring GCC@. Specifying the
6589 @option{-mcpu=@var{cpu_type}} overrides the specification of these
6590 options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
6591 rather than the options listed above.
6593 The @option{-mpower} option allows GCC to generate instructions that
6594 are found only in the POWER architecture and to use the MQ register.
6595 Specifying @option{-mpower2} implies @option{-power} and also allows GCC
6596 to generate instructions that are present in the POWER2 architecture but
6597 not the original POWER architecture.
6599 The @option{-mpowerpc} option allows GCC to generate instructions that
6600 are found only in the 32-bit subset of the PowerPC architecture.
6601 Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
6602 GCC to use the optional PowerPC architecture instructions in the
6603 General Purpose group, including floating-point square root. Specifying
6604 @option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
6605 use the optional PowerPC architecture instructions in the Graphics
6606 group, including floating-point select.
6608 The @option{-mpowerpc64} option allows GCC to generate the additional
6609 64-bit instructions that are found in the full PowerPC64 architecture
6610 and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
6611 @option{-mno-powerpc64}.
6613 If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
6614 will use only the instructions in the common subset of both
6615 architectures plus some special AIX common-mode calls, and will not use
6616 the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
6617 permits GCC to use any instruction from either architecture and to
6618 allow use of the MQ register; specify this for the Motorola MPC601.
6620 @item -mnew-mnemonics
6621 @itemx -mold-mnemonics
6622 @opindex mnew-mnemonics
6623 @opindex mold-mnemonics
6624 Select which mnemonics to use in the generated assembler code. With
6625 @option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
6626 the PowerPC architecture. With @option{-mold-mnemonics} it uses the
6627 assembler mnemonics defined for the POWER architecture. Instructions
6628 defined in only one architecture have only one mnemonic; GCC uses that
6629 mnemonic irrespective of which of these options is specified.
6631 GCC defaults to the mnemonics appropriate for the architecture in
6632 use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
6633 value of these option. Unless you are building a cross-compiler, you
6634 should normally not specify either @option{-mnew-mnemonics} or
6635 @option{-mold-mnemonics}, but should instead accept the default.
6637 @item -mcpu=@var{cpu_type}
6639 Set architecture type, register usage, choice of mnemonics, and
6640 instruction scheduling parameters for machine type @var{cpu_type}.
6641 Supported values for @var{cpu_type} are @samp{rios}, @samp{rios1},
6642 @samp{rsc}, @samp{rios2}, @samp{rs64a}, @samp{601}, @samp{602},
6643 @samp{603}, @samp{603e}, @samp{604}, @samp{604e}, @samp{620},
6644 @samp{630}, @samp{740}, @samp{7400}, @samp{7450}, @samp{750},
6645 @samp{power}, @samp{power2}, @samp{powerpc}, @samp{403}, @samp{505},
6646 @samp{801}, @samp{821}, @samp{823}, and @samp{860} and @samp{common}.
6648 @option{-mcpu=common} selects a completely generic processor. Code
6649 generated under this option will run on any POWER or PowerPC processor.
6650 GCC will use only the instructions in the common subset of both
6651 architectures, and will not use the MQ register. GCC assumes a generic
6652 processor model for scheduling purposes.
6654 @option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
6655 @option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
6656 PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
6657 types, with an appropriate, generic processor model assumed for
6658 scheduling purposes.
6660 The other options specify a specific processor. Code generated under
6661 those options will run best on that processor, and may not run at all on
6664 The @option{-mcpu} options automatically enable or disable other
6665 @option{-m} options as follows:
6669 @option{-mno-power}, @option{-mno-powerc}
6676 @option{-mpower}, @option{-mno-powerpc}, @option{-mno-new-mnemonics}
6691 @option{-mno-power}, @option{-mpowerpc}, @option{-mnew-mnemonics}
6694 @option{-mpower}, @option{-mpowerpc}, @option{-mnew-mnemonics}
6699 @option{-mno-power}, @option{-mpowerpc}, @option{-mnew-mnemonics}, @option{-msoft-float}
6702 @item -mtune=@var{cpu_type}
6704 Set the instruction scheduling parameters for machine type
6705 @var{cpu_type}, but do not set the architecture type, register usage, or
6706 choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
6707 values for @var{cpu_type} are used for @option{-mtune} as for
6708 @option{-mcpu}. If both are specified, the code generated will use the
6709 architecture, registers, and mnemonics set by @option{-mcpu}, but the
6710 scheduling parameters set by @option{-mtune}.
6715 @opindex mno-altivec
6716 These switches enable or disable the use of built-in functions that
6717 allow access to the AltiVec instruction set. You may also need to set
6718 @option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
6722 @itemx -mno-fp-in-toc
6723 @itemx -mno-sum-in-toc
6724 @itemx -mminimal-toc
6726 @opindex mno-fp-in-toc
6727 @opindex mno-sum-in-toc
6728 @opindex mminimal-toc
6729 Modify generation of the TOC (Table Of Contents), which is created for
6730 every executable file. The @option{-mfull-toc} option is selected by
6731 default. In that case, GCC will allocate at least one TOC entry for
6732 each unique non-automatic variable reference in your program. GCC
6733 will also place floating-point constants in the TOC@. However, only
6734 16,384 entries are available in the TOC@.
6736 If you receive a linker error message that saying you have overflowed
6737 the available TOC space, you can reduce the amount of TOC space used
6738 with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
6739 @option{-mno-fp-in-toc} prevents GCC from putting floating-point
6740 constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
6741 generate code to calculate the sum of an address and a constant at
6742 run-time instead of putting that sum into the TOC@. You may specify one
6743 or both of these options. Each causes GCC to produce very slightly
6744 slower and larger code at the expense of conserving TOC space.
6746 If you still run out of space in the TOC even when you specify both of
6747 these options, specify @option{-mminimal-toc} instead. This option causes
6748 GCC to make only one TOC entry for every file. When you specify this
6749 option, GCC will produce code that is slower and larger but which
6750 uses extremely little TOC space. You may wish to use this option
6751 only on files that contain less frequently executed code.
6757 Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
6758 @code{long} type, and the infrastructure needed to support them.
6759 Specifying @option{-maix64} implies @option{-mpowerpc64} and
6760 @option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
6761 implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
6766 @opindex mno-xl-call
6767 On AIX, pass floating-point arguments to prototyped functions beyond the
6768 register save area (RSA) on the stack in addition to argument FPRs. The
6769 AIX calling convention was extended but not initially documented to
6770 handle an obscure K&R C case of calling a function that takes the
6771 address of its arguments with fewer arguments than declared. AIX XL
6772 compilers access floating point arguments which do not fit in the
6773 RSA from the stack when a subroutine is compiled without
6774 optimization. Because always storing floating-point arguments on the
6775 stack is inefficient and rarely needed, this option is not enabled by
6776 default and only is necessary when calling subroutines compiled by AIX
6777 XL compilers without optimization.
6781 Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
6782 application written to use message passing with special startup code to
6783 enable the application to run. The system must have PE installed in the
6784 standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
6785 must be overridden with the @option{-specs=} option to specify the
6786 appropriate directory location. The Parallel Environment does not
6787 support threads, so the @option{-mpe} option and the @option{-pthread}
6788 option are incompatible.
6792 @opindex msoft-float
6793 @opindex mhard-float
6794 Generate code that does not use (uses) the floating-point register set.
6795 Software floating point emulation is provided if you use the
6796 @option{-msoft-float} option, and pass the option to GCC when linking.
6799 @itemx -mno-multiple
6801 @opindex mno-multiple
6802 Generate code that uses (does not use) the load multiple word
6803 instructions and the store multiple word instructions. These
6804 instructions are generated by default on POWER systems, and not
6805 generated on PowerPC systems. Do not use @option{-mmultiple} on little
6806 endian PowerPC systems, since those instructions do not work when the
6807 processor is in little endian mode. The exceptions are PPC740 and
6808 PPC750 which permit the instructions usage in little endian mode.
6814 Generate code that uses (does not use) the load string instructions
6815 and the store string word instructions to save multiple registers and
6816 do small block moves. These instructions are generated by default on
6817 POWER systems, and not generated on PowerPC systems. Do not use
6818 @option{-mstring} on little endian PowerPC systems, since those
6819 instructions do not work when the processor is in little endian mode.
6820 The exceptions are PPC740 and PPC750 which permit the instructions
6821 usage in little endian mode.
6827 Generate code that uses (does not use) the load or store instructions
6828 that update the base register to the address of the calculated memory
6829 location. These instructions are generated by default. If you use
6830 @option{-mno-update}, there is a small window between the time that the
6831 stack pointer is updated and the address of the previous frame is
6832 stored, which means code that walks the stack frame across interrupts or
6833 signals may get corrupted data.
6836 @itemx -mno-fused-madd
6837 @opindex mfused-madd
6838 @opindex mno-fused-madd
6839 Generate code that uses (does not use) the floating point multiply and
6840 accumulate instructions. These instructions are generated by default if
6841 hardware floating is used.
6843 @item -mno-bit-align
6845 @opindex mno-bit-align
6847 On System V.4 and embedded PowerPC systems do not (do) force structures
6848 and unions that contain bit-fields to be aligned to the base type of the
6851 For example, by default a structure containing nothing but 8
6852 @code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
6853 boundary and have a size of 4 bytes. By using @option{-mno-bit-align},
6854 the structure would be aligned to a 1 byte boundary and be one byte in
6857 @item -mno-strict-align
6858 @itemx -mstrict-align
6859 @opindex mno-strict-align
6860 @opindex mstrict-align
6861 On System V.4 and embedded PowerPC systems do not (do) assume that
6862 unaligned memory references will be handled by the system.
6865 @itemx -mno-relocatable
6866 @opindex mrelocatable
6867 @opindex mno-relocatable
6868 On embedded PowerPC systems generate code that allows (does not allow)
6869 the program to be relocated to a different address at runtime. If you
6870 use @option{-mrelocatable} on any module, all objects linked together must
6871 be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
6873 @item -mrelocatable-lib
6874 @itemx -mno-relocatable-lib
6875 @opindex mrelocatable-lib
6876 @opindex mno-relocatable-lib
6877 On embedded PowerPC systems generate code that allows (does not allow)
6878 the program to be relocated to a different address at runtime. Modules
6879 compiled with @option{-mrelocatable-lib} can be linked with either modules
6880 compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
6881 with modules compiled with the @option{-mrelocatable} options.
6887 On System V.4 and embedded PowerPC systems do not (do) assume that
6888 register 2 contains a pointer to a global area pointing to the addresses
6889 used in the program.
6892 @itemx -mlittle-endian
6894 @opindex mlittle-endian
6895 On System V.4 and embedded PowerPC systems compile code for the
6896 processor in little endian mode. The @option{-mlittle-endian} option is
6897 the same as @option{-mlittle}.
6902 @opindex mbig-endian
6903 On System V.4 and embedded PowerPC systems compile code for the
6904 processor in big endian mode. The @option{-mbig-endian} option is
6905 the same as @option{-mbig}.
6909 On System V.4 and embedded PowerPC systems compile code using calling
6910 conventions that adheres to the March 1995 draft of the System V
6911 Application Binary Interface, PowerPC processor supplement. This is the
6912 default unless you configured GCC using @samp{powerpc-*-eabiaix}.
6914 @item -mcall-sysv-eabi
6915 @opindex mcall-sysv-eabi
6916 Specify both @option{-mcall-sysv} and @option{-meabi} options.
6918 @item -mcall-sysv-noeabi
6919 @opindex mcall-sysv-noeabi
6920 Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
6924 On System V.4 and embedded PowerPC systems compile code using calling
6925 conventions that are similar to those used on AIX@. This is the
6926 default if you configured GCC using @samp{powerpc-*-eabiaix}.
6928 @item -mcall-solaris
6929 @opindex mcall-solaris
6930 On System V.4 and embedded PowerPC systems compile code for the Solaris
6934 @opindex mcall-linux
6935 On System V.4 and embedded PowerPC systems compile code for the
6936 Linux-based GNU system.
6940 On System V.4 and embedded PowerPC systems compile code for the
6941 Hurd-based GNU system.
6944 @opindex mcall-netbsd
6945 On System V.4 and embedded PowerPC systems compile code for the
6946 NetBSD operating system.
6948 @item -maix-struct-return
6949 @opindex maix-struct-return
6950 Return all structures in memory (as specified by the AIX ABI)@.
6952 @item -msvr4-struct-return
6953 @opindex msvr4-struct-return
6954 Return structures smaller than 8 bytes in registers (as specified by the
6958 @opindex mabi=altivec
6959 Extend the current ABI with AltiVec ABI extensions. This does not
6960 change the default ABI, instead it adds the AltiVec ABI extensions to
6964 @itemx -mno-prototype
6966 @opindex mno-prototype
6967 On System V.4 and embedded PowerPC systems assume that all calls to
6968 variable argument functions are properly prototyped. Otherwise, the
6969 compiler must insert an instruction before every non prototyped call to
6970 set or clear bit 6 of the condition code register (@var{CR}) to
6971 indicate whether floating point values were passed in the floating point
6972 registers in case the function takes a variable arguments. With
6973 @option{-mprototype}, only calls to prototyped variable argument functions
6974 will set or clear the bit.
6978 On embedded PowerPC systems, assume that the startup module is called
6979 @file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
6980 @file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
6985 On embedded PowerPC systems, assume that the startup module is called
6986 @file{crt0.o} and the standard C libraries are @file{libmvme.a} and
6991 On embedded PowerPC systems, assume that the startup module is called
6992 @file{crt0.o} and the standard C libraries are @file{libads.a} and
6996 @opindex myellowknife
6997 On embedded PowerPC systems, assume that the startup module is called
6998 @file{crt0.o} and the standard C libraries are @file{libyk.a} and
7003 On System V.4 and embedded PowerPC systems, specify that you are
7004 compiling for a VxWorks system.
7008 On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
7009 header to indicate that @samp{eabi} extended relocations are used.
7015 On System V.4 and embedded PowerPC systems do (do not) adhere to the
7016 Embedded Applications Binary Interface (eabi) which is a set of
7017 modifications to the System V.4 specifications. Selecting @option{-meabi}
7018 means that the stack is aligned to an 8 byte boundary, a function
7019 @code{__eabi} is called to from @code{main} to set up the eabi
7020 environment, and the @option{-msdata} option can use both @code{r2} and
7021 @code{r13} to point to two separate small data areas. Selecting
7022 @option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
7023 do not call an initialization function from @code{main}, and the
7024 @option{-msdata} option will only use @code{r13} to point to a single
7025 small data area. The @option{-meabi} option is on by default if you
7026 configured GCC using one of the @samp{powerpc*-*-eabi*} options.
7029 @opindex msdata=eabi
7030 On System V.4 and embedded PowerPC systems, put small initialized
7031 @code{const} global and static data in the @samp{.sdata2} section, which
7032 is pointed to by register @code{r2}. Put small initialized
7033 non-@code{const} global and static data in the @samp{.sdata} section,
7034 which is pointed to by register @code{r13}. Put small uninitialized
7035 global and static data in the @samp{.sbss} section, which is adjacent to
7036 the @samp{.sdata} section. The @option{-msdata=eabi} option is
7037 incompatible with the @option{-mrelocatable} option. The
7038 @option{-msdata=eabi} option also sets the @option{-memb} option.
7041 @opindex msdata=sysv
7042 On System V.4 and embedded PowerPC systems, put small global and static
7043 data in the @samp{.sdata} section, which is pointed to by register
7044 @code{r13}. Put small uninitialized global and static data in the
7045 @samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
7046 The @option{-msdata=sysv} option is incompatible with the
7047 @option{-mrelocatable} option.
7049 @item -msdata=default
7051 @opindex msdata=default
7053 On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
7054 compile code the same as @option{-msdata=eabi}, otherwise compile code the
7055 same as @option{-msdata=sysv}.
7058 @opindex msdata-data
7059 On System V.4 and embedded PowerPC systems, put small global and static
7060 data in the @samp{.sdata} section. Put small uninitialized global and
7061 static data in the @samp{.sbss} section. Do not use register @code{r13}
7062 to address small data however. This is the default behavior unless
7063 other @option{-msdata} options are used.
7067 @opindex msdata=none
7069 On embedded PowerPC systems, put all initialized global and static data
7070 in the @samp{.data} section, and all uninitialized data in the
7071 @samp{.bss} section.
7075 @cindex smaller data references (PowerPC)
7076 @cindex .sdata/.sdata2 references (PowerPC)
7077 On embedded PowerPC systems, put global and static items less than or
7078 equal to @var{num} bytes into the small data or bss sections instead of
7079 the normal data or bss section. By default, @var{num} is 8. The
7080 @option{-G @var{num}} switch is also passed to the linker.
7081 All modules should be compiled with the same @option{-G @var{num}} value.
7084 @itemx -mno-regnames
7086 @opindex mno-regnames
7087 On System V.4 and embedded PowerPC systems do (do not) emit register
7088 names in the assembly language output using symbolic forms.
7092 Adds support for multithreading with the @dfn{pthreads} library.
7093 This option sets flags for both the preprocessor and linker.
7098 @subsection IBM RT Options
7100 @cindex IBM RT options
7102 These @samp{-m} options are defined for the IBM RT PC:
7106 @opindex min-line-mul
7107 Use an in-line code sequence for integer multiplies. This is the
7110 @item -mcall-lib-mul
7111 @opindex mcall-lib-mul
7112 Call @code{lmul$$} for integer multiples.
7114 @item -mfull-fp-blocks
7115 @opindex mfull-fp-blocks
7116 Generate full-size floating point data blocks, including the minimum
7117 amount of scratch space recommended by IBM@. This is the default.
7119 @item -mminimum-fp-blocks
7120 @opindex mminimum-fp-blocks
7121 Do not include extra scratch space in floating point data blocks. This
7122 results in smaller code, but slower execution, since scratch space must
7123 be allocated dynamically.
7125 @cindex @file{varargs.h} and RT PC
7126 @cindex @file{stdarg.h} and RT PC
7127 @item -mfp-arg-in-fpregs
7128 @opindex mfp-arg-in-fpregs
7129 Use a calling sequence incompatible with the IBM calling convention in
7130 which floating point arguments are passed in floating point registers.
7131 Note that @code{varargs.h} and @code{stdarg.h} will not work with
7132 floating point operands if this option is specified.
7134 @item -mfp-arg-in-gregs
7135 @opindex mfp-arg-in-gregs
7136 Use the normal calling convention for floating point arguments. This is
7139 @item -mhc-struct-return
7140 @opindex mhc-struct-return
7141 Return structures of more than one word in memory, rather than in a
7142 register. This provides compatibility with the MetaWare HighC (hc)
7143 compiler. Use the option @option{-fpcc-struct-return} for compatibility
7144 with the Portable C Compiler (pcc).
7146 @item -mnohc-struct-return
7147 @opindex mnohc-struct-return
7148 Return some structures of more than one word in registers, when
7149 convenient. This is the default. For compatibility with the
7150 IBM-supplied compilers, use the option @option{-fpcc-struct-return} or the
7151 option @option{-mhc-struct-return}.
7155 @subsection MIPS Options
7156 @cindex MIPS options
7158 These @samp{-m} options are defined for the MIPS family of computers:
7162 @item -march=@var{cpu-type}
7164 Assume the defaults for the machine type @var{cpu-type} when generating
7165 instructions. The choices for @var{cpu-type} are @samp{r2000}, @samp{r3000},
7166 @samp{r3900}, @samp{r4000}, @samp{r4100}, @samp{r4300}, @samp{r4400},
7167 @samp{r4600}, @samp{r4650}, @samp{r5000}, @samp{r6000}, @samp{r8000},
7168 and @samp{orion}. Additionally, the @samp{r2000}, @samp{r3000},
7169 @samp{r4000}, @samp{r5000}, and @samp{r6000} can be abbreviated as
7170 @samp{r2k} (or @samp{r2K}), @samp{r3k}, etc.
7172 @item -mtune=@var{cpu-type}
7174 Assume the defaults for the machine type @var{cpu-type} when scheduling
7175 instructions. The choices for @var{cpu-type} are @samp{r2000}, @samp{r3000},
7176 @samp{r3900}, @samp{r4000}, @samp{r4100}, @samp{r4300}, @samp{r4400},
7177 @samp{r4600}, @samp{r4650}, @samp{r5000}, @samp{r6000}, @samp{r8000},
7178 and @samp{orion}. Additionally, the @samp{r2000}, @samp{r3000},
7179 @samp{r4000}, @samp{r5000}, and @samp{r6000} can be abbreviated as
7180 @samp{r2k} (or @samp{r2K}), @samp{r3k}, etc. While picking a specific
7181 @var{cpu-type} will schedule things appropriately for that particular
7182 chip, the compiler will not generate any code that does not meet level 1
7183 of the MIPS ISA (instruction set architecture) without a @option{-mipsX}
7184 or @option{-mabi} switch being used.
7186 @item -mcpu=@var{cpu-type}
7188 This is identical to specifying both @option{-march} and @option{-mtune}.
7192 Issue instructions from level 1 of the MIPS ISA@. This is the default.
7193 @samp{r3000} is the default @var{cpu-type} at this ISA level.
7197 Issue instructions from level 2 of the MIPS ISA (branch likely, square
7198 root instructions). @samp{r6000} is the default @var{cpu-type} at this
7203 Issue instructions from level 3 of the MIPS ISA (64-bit instructions).
7204 @samp{r4000} is the default @var{cpu-type} at this ISA level.
7208 Issue instructions from level 4 of the MIPS ISA (conditional move,
7209 prefetch, enhanced FPU instructions). @samp{r8000} is the default
7210 @var{cpu-type} at this ISA level.
7214 Assume that 32 32-bit floating point registers are available. This is
7219 Assume that 32 64-bit floating point registers are available. This is
7220 the default when the @option{-mips3} option is used.
7223 @itemx -mno-fused-madd
7224 @opindex mfused-madd
7225 @opindex mno-fused-madd
7226 Generate code that uses (does not use) the floating point multiply and
7227 accumulate instructions, when they are available. These instructions
7228 are generated by default if they are available, but this may be
7229 undesirable if the extra precision causes problems or on certain chips
7230 in the mode where denormals are rounded to zero where denormals
7231 generated by multiply and accumulate instructions cause exceptions
7236 Assume that 32 32-bit general purpose registers are available. This is
7241 Assume that 32 64-bit general purpose registers are available. This is
7242 the default when the @option{-mips3} option is used.
7246 Force int and long types to be 64 bits wide. See @option{-mlong32} for an
7247 explanation of the default, and the width of pointers.
7251 Force long types to be 64 bits wide. See @option{-mlong32} for an
7252 explanation of the default, and the width of pointers.
7256 Force long, int, and pointer types to be 32 bits wide.
7258 If none of @option{-mlong32}, @option{-mlong64}, or @option{-mint64} are set,
7259 the size of ints, longs, and pointers depends on the ABI and ISA chosen.
7260 For @option{-mabi=32}, and @option{-mabi=n32}, ints and longs are 32 bits
7261 wide. For @option{-mabi=64}, ints are 32 bits, and longs are 64 bits wide.
7262 For @option{-mabi=eabi} and either @option{-mips1} or @option{-mips2}, ints
7263 and longs are 32 bits wide. For @option{-mabi=eabi} and higher ISAs, ints
7264 are 32 bits, and longs are 64 bits wide. The width of pointer types is
7265 the smaller of the width of longs or the width of general purpose
7266 registers (which in turn depends on the ISA)@.
7278 Generate code for the indicated ABI@. The default instruction level is
7279 @option{-mips1} for @samp{32}, @option{-mips3} for @samp{n32}, and
7280 @option{-mips4} otherwise. Conversely, with @option{-mips1} or
7281 @option{-mips2}, the default ABI is @samp{32}; otherwise, the default ABI
7286 Generate code for the MIPS assembler, and invoke @file{mips-tfile} to
7287 add normal debug information. This is the default for all
7288 platforms except for the OSF/1 reference platform, using the OSF/rose
7289 object format. If the either of the @option{-gstabs} or @option{-gstabs+}
7290 switches are used, the @file{mips-tfile} program will encapsulate the
7291 stabs within MIPS ECOFF@.
7295 Generate code for the GNU assembler. This is the default on the OSF/1
7296 reference platform, using the OSF/rose object format. Also, this is
7297 the default if the configure option @option{--with-gnu-as} is used.
7299 @item -msplit-addresses
7300 @itemx -mno-split-addresses
7301 @opindex msplit-addresses
7302 @opindex mno-split-addresses
7303 Generate code to load the high and low parts of address constants separately.
7304 This allows GCC to optimize away redundant loads of the high order
7305 bits of addresses. This optimization requires GNU as and GNU ld.
7306 This optimization is enabled by default for some embedded targets where
7307 GNU as and GNU ld are standard.
7313 The @option{-mrnames} switch says to output code using the MIPS software
7314 names for the registers, instead of the hardware names (ie, @var{a0}
7315 instead of @var{$4}). The only known assembler that supports this option
7316 is the Algorithmics assembler.
7322 The @option{-mgpopt} switch says to write all of the data declarations
7323 before the instructions in the text section, this allows the MIPS
7324 assembler to generate one word memory references instead of using two
7325 words for short global or static data items. This is on by default if
7326 optimization is selected.
7332 For each non-inline function processed, the @option{-mstats} switch
7333 causes the compiler to emit one line to the standard error file to
7334 print statistics about the program (number of registers saved, stack
7341 The @option{-mmemcpy} switch makes all block moves call the appropriate
7342 string function (@samp{memcpy} or @samp{bcopy}) instead of possibly
7343 generating inline code.
7346 @itemx -mno-mips-tfile
7347 @opindex mmips-tfile
7348 @opindex mno-mips-tfile
7349 The @option{-mno-mips-tfile} switch causes the compiler not
7350 postprocess the object file with the @file{mips-tfile} program,
7351 after the MIPS assembler has generated it to add debug support. If
7352 @file{mips-tfile} is not run, then no local variables will be
7353 available to the debugger. In addition, @file{stage2} and
7354 @file{stage3} objects will have the temporary file names passed to the
7355 assembler embedded in the object file, which means the objects will
7356 not compare the same. The @option{-mno-mips-tfile} switch should only
7357 be used when there are bugs in the @file{mips-tfile} program that
7358 prevents compilation.
7361 @opindex msoft-float
7362 Generate output containing library calls for floating point.
7363 @strong{Warning:} the requisite libraries are not part of GCC@.
7364 Normally the facilities of the machine's usual C compiler are used, but
7365 this can't be done directly in cross-compilation. You must make your
7366 own arrangements to provide suitable library functions for
7370 @opindex mhard-float
7371 Generate output containing floating point instructions. This is the
7372 default if you use the unmodified sources.
7375 @itemx -mno-abicalls
7377 @opindex mno-abicalls
7378 Emit (or do not emit) the pseudo operations @samp{.abicalls},
7379 @samp{.cpload}, and @samp{.cprestore} that some System V.4 ports use for
7380 position independent code.
7383 @itemx -mno-long-calls
7384 @opindex mlong-calls
7385 @opindex mno-long-calls
7386 Do all calls with the @samp{JALR} instruction, which requires
7387 loading up a function's address into a register before the call.
7388 You need to use this switch, if you call outside of the current
7389 512 megabyte segment to functions that are not through pointers.
7392 @itemx -mno-half-pic
7394 @opindex mno-half-pic
7395 Put pointers to extern references into the data section and load them
7396 up, rather than put the references in the text section.
7398 @item -membedded-pic
7399 @itemx -mno-embedded-pic
7400 @opindex membedded-pic
7401 @opindex mno-embedded-pic
7402 Generate PIC code suitable for some embedded systems. All calls are
7403 made using PC relative address, and all data is addressed using the $gp
7404 register. No more than 65536 bytes of global data may be used. This
7405 requires GNU as and GNU ld which do most of the work. This currently
7406 only works on targets which use ECOFF; it does not work with ELF@.
7408 @item -membedded-data
7409 @itemx -mno-embedded-data
7410 @opindex membedded-data
7411 @opindex mno-embedded-data
7412 Allocate variables to the read-only data section first if possible, then
7413 next in the small data section if possible, otherwise in data. This gives
7414 slightly slower code than the default, but reduces the amount of RAM required
7415 when executing, and thus may be preferred for some embedded systems.
7417 @item -muninit-const-in-rodata
7418 @itemx -mno-uninit-const-in-rodata
7419 @opindex muninit-const-in-rodata
7420 @opindex mno-uninit-const-in-rodata
7421 When used together with @option{-membedded-data}, it will always store uninitialized
7422 const variables in the read-only data section.
7424 @item -msingle-float
7425 @itemx -mdouble-float
7426 @opindex msingle-float
7427 @opindex mdouble-float
7428 The @option{-msingle-float} switch tells gcc to assume that the floating
7429 point coprocessor only supports single precision operations, as on the
7430 @samp{r4650} chip. The @option{-mdouble-float} switch permits gcc to use
7431 double precision operations. This is the default.
7437 Permit use of the @samp{mad}, @samp{madu} and @samp{mul} instructions,
7438 as on the @samp{r4650} chip.
7442 Turns on @option{-msingle-float}, @option{-mmad}, and, at least for now,
7443 @option{-mcpu=r4650}.
7449 Enable 16-bit instructions.
7453 Use the entry and exit pseudo ops. This option can only be used with
7458 Compile code for the processor in little endian mode.
7459 The requisite libraries are assumed to exist.
7463 Compile code for the processor in big endian mode.
7464 The requisite libraries are assumed to exist.
7468 @cindex smaller data references (MIPS)
7469 @cindex gp-relative references (MIPS)
7470 Put global and static items less than or equal to @var{num} bytes into
7471 the small data or bss sections instead of the normal data or bss
7472 section. This allows the assembler to emit one word memory reference
7473 instructions based on the global pointer (@var{gp} or @var{$28}),
7474 instead of the normal two words used. By default, @var{num} is 8 when
7475 the MIPS assembler is used, and 0 when the GNU assembler is used. The
7476 @option{-G @var{num}} switch is also passed to the assembler and linker.
7477 All modules should be compiled with the same @option{-G @var{num}}
7482 Tell the MIPS assembler to not run its preprocessor over user
7483 assembler files (with a @samp{.s} suffix) when assembling them.
7487 Pass an option to gas which will cause nops to be inserted if
7488 the read of the destination register of an mfhi or mflo instruction
7489 occurs in the following two instructions.
7493 Do not include the default crt0.
7495 @item -mflush-func=@var{func}
7496 @itemx -mno-flush-func
7497 @opindex mflush-func
7498 Specifies the function to call to flush the I and D caches, or to not
7499 call any such function. If called, the function must take the same
7500 arguments as the common @code{_flush_func()}, that is, the address of the
7501 memory range for which the cache is being flushed, the size of the
7502 memory range, and the number 3 (to flush both caches). The default
7503 depends on the target gcc was configured for, but commonly is either
7504 @samp{_flush_func} or @samp{__cpu_flush}.
7507 These options are defined by the macro
7508 @code{TARGET_SWITCHES} in the machine description. The default for the
7509 options is also defined by that macro, which enables you to change the
7512 @node i386 and x86-64 Options
7513 @subsection Intel 386 and AMD x86-64 Options
7514 @cindex i386 Options
7515 @cindex x86-64 Options
7516 @cindex Intel 386 Options
7517 @cindex AMD x86-64 Options
7519 These @samp{-m} options are defined for the i386 and x86-64 family of
7523 @item -mcpu=@var{cpu-type}
7525 Tune to @var{cpu-type} everything applicable about the generated code, except
7526 for the ABI and the set of available instructions. The choices for
7527 @var{cpu-type} are @samp{i386}, @samp{i486}, @samp{i586}, @samp{i686},
7528 @samp{pentium}, @samp{pentium-mmx}, @samp{pentiumpro}, @samp{pentium2},
7529 @samp{pentium3}, @samp{pentium4}, @samp{k6}, @samp{k6-2}, @samp{k6-3},
7530 @samp{athlon}, @samp{athlon-tbird}, @samp{athlon-4}, @samp{athlon-xp}
7531 and @samp{athlon-mp}.
7533 While picking a specific @var{cpu-type} will schedule things appropriately
7534 for that particular chip, the compiler will not generate any code that
7535 does not run on the i386 without the @option{-march=@var{cpu-type}} option
7536 being used. @samp{i586} is equivalent to @samp{pentium} and @samp{i686}
7537 is equivalent to @samp{pentiumpro}. @samp{k6} and @samp{athlon} are the
7538 AMD chips as opposed to the Intel ones.
7540 @item -march=@var{cpu-type}
7542 Generate instructions for the machine type @var{cpu-type}. The choices
7543 for @var{cpu-type} are the same as for @option{-mcpu}. Moreover,
7544 specifying @option{-march=@var{cpu-type}} implies @option{-mcpu=@var{cpu-type}}.
7553 @opindex mpentiumpro
7554 These options are synonyms for @option{-mcpu=i386}, @option{-mcpu=i486},
7555 @option{-mcpu=pentium}, and @option{-mcpu=pentiumpro} respectively.
7556 These synonyms are deprecated.
7558 @item -mfpmath=@var{unit}
7560 generate floating point arithmetics for selected unit @var{unit}. the choices
7565 Use the standard 387 floating point coprocessor present majority of chips and
7566 emulated otherwise. Code compiled with this option will run almost everywhere.
7567 The temporary results are computed in 80bit precesion instead of precision
7568 specified by the type resulting in slightly different results compared to most
7569 of other chips. See @option{-ffloat-store} for more detailed description.
7571 This is the default choice for i386 compiler.
7574 Use scalar floating point instructions present in the SSE instruction set.
7575 This instruction set is supported by Pentium3 and newer chips, in the AMD line
7576 by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE
7577 instruction set supports only single precision arithmetics, thus the double and
7578 extended precision arithmetics is still done using 387. Later version, present
7579 only in Pentium4 and the future AMD x86-64 chips supports double precision
7582 For i387 you need to use @option{-march=@var{cpu-type}}, @option{-msse} or
7583 @option{-msse2} switches to enable SSE extensions and make this option
7584 effective. For x86-64 compiler, these extensions are enabled by default.
7586 The resulting code should be considerably faster in majority of cases and avoid
7587 the numerical instability problems of 387 code, but may break some existing
7588 code that expects temporaries to be 80bit.
7590 This is the default choice for x86-64 compiler.
7593 Attempt to utilize both instruction sets at once. This effectivly double the
7594 amount of available registers and on chips with separate execution units for
7595 387 and SSE the execution resources too. Use this option with care, as it is
7596 still experimental, because gcc register allocator does not model separate
7597 functional units well resulting in instable performance.
7600 @item -masm=@var{dialect}
7601 @opindex masm=@var{dialect}
7602 Output asm instructions using selected @var{dialect}. Supported choices are
7603 @samp{intel} or @samp{att} (the default one).
7608 @opindex mno-ieee-fp
7609 Control whether or not the compiler uses IEEE floating point
7610 comparisons. These handle correctly the case where the result of a
7611 comparison is unordered.
7614 @opindex msoft-float
7615 Generate output containing library calls for floating point.
7616 @strong{Warning:} the requisite libraries are not part of GCC@.
7617 Normally the facilities of the machine's usual C compiler are used, but
7618 this can't be done directly in cross-compilation. You must make your
7619 own arrangements to provide suitable library functions for
7622 On machines where a function returns floating point results in the 80387
7623 register stack, some floating point opcodes may be emitted even if
7624 @option{-msoft-float} is used.
7626 @item -mno-fp-ret-in-387
7627 @opindex mno-fp-ret-in-387
7628 Do not use the FPU registers for return values of functions.
7630 The usual calling convention has functions return values of types
7631 @code{float} and @code{double} in an FPU register, even if there
7632 is no FPU@. The idea is that the operating system should emulate
7635 The option @option{-mno-fp-ret-in-387} causes such values to be returned
7636 in ordinary CPU registers instead.
7638 @item -mno-fancy-math-387
7639 @opindex mno-fancy-math-387
7640 Some 387 emulators do not support the @code{sin}, @code{cos} and
7641 @code{sqrt} instructions for the 387. Specify this option to avoid
7642 generating those instructions. This option is the default on FreeBSD@.
7643 As of revision 2.6.1, these instructions are not generated unless you
7644 also use the @option{-funsafe-math-optimizations} switch.
7646 @item -malign-double
7647 @itemx -mno-align-double
7648 @opindex malign-double
7649 @opindex mno-align-double
7650 Control whether GCC aligns @code{double}, @code{long double}, and
7651 @code{long long} variables on a two word boundary or a one word
7652 boundary. Aligning @code{double} variables on a two word boundary will
7653 produce code that runs somewhat faster on a @samp{Pentium} at the
7654 expense of more memory.
7656 @item -m128bit-long-double
7657 @opindex m128bit-long-double
7658 Control the size of @code{long double} type. i386 application binary interface
7659 specify the size to be 12 bytes, while modern architectures (Pentium and newer)
7660 prefer @code{long double} aligned to 8 or 16 byte boundary. This is
7661 impossible to reach with 12 byte long doubles in the array accesses.
7663 @strong{Warning:} if you use the @option{-m128bit-long-double} switch, the
7664 structures and arrays containing @code{long double} will change their size as
7665 well as function calling convention for function taking @code{long double}
7668 @item -m96bit-long-double
7669 @opindex m96bit-long-double
7670 Set the size of @code{long double} to 96 bits as required by the i386
7671 application binary interface. This is the default.
7674 @itemx -mno-svr3-shlib
7675 @opindex msvr3-shlib
7676 @opindex mno-svr3-shlib
7677 Control whether GCC places uninitialized local variables into the
7678 @code{bss} or @code{data} segments. @option{-msvr3-shlib} places them
7679 into @code{bss}. These options are meaningful only on System V Release 3.
7683 Use a different function-calling convention, in which functions that
7684 take a fixed number of arguments return with the @code{ret} @var{num}
7685 instruction, which pops their arguments while returning. This saves one
7686 instruction in the caller since there is no need to pop the arguments
7689 You can specify that an individual function is called with this calling
7690 sequence with the function attribute @samp{stdcall}. You can also
7691 override the @option{-mrtd} option by using the function attribute
7692 @samp{cdecl}. @xref{Function Attributes}.
7694 @strong{Warning:} this calling convention is incompatible with the one
7695 normally used on Unix, so you cannot use it if you need to call
7696 libraries compiled with the Unix compiler.
7698 Also, you must provide function prototypes for all functions that
7699 take variable numbers of arguments (including @code{printf});
7700 otherwise incorrect code will be generated for calls to those
7703 In addition, seriously incorrect code will result if you call a
7704 function with too many arguments. (Normally, extra arguments are
7705 harmlessly ignored.)
7707 @item -mregparm=@var{num}
7709 Control how many registers are used to pass integer arguments. By
7710 default, no registers are used to pass arguments, and at most 3
7711 registers can be used. You can control this behavior for a specific
7712 function by using the function attribute @samp{regparm}.
7713 @xref{Function Attributes}.
7715 @strong{Warning:} if you use this switch, and
7716 @var{num} is nonzero, then you must build all modules with the same
7717 value, including any libraries. This includes the system libraries and
7720 @item -mpreferred-stack-boundary=@var{num}
7721 @opindex mpreferred-stack-boundary
7722 Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
7723 byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
7724 the default is 4 (16 bytes or 128 bits), except when optimizing for code
7725 size (@option{-Os}), in which case the default is the minimum correct
7726 alignment (4 bytes for x86, and 8 bytes for x86-64).
7728 On Pentium and PentiumPro, @code{double} and @code{long double} values
7729 should be aligned to an 8 byte boundary (see @option{-malign-double}) or
7730 suffer significant run time performance penalties. On Pentium III, the
7731 Streaming SIMD Extension (SSE) data type @code{__m128} suffers similar
7732 penalties if it is not 16 byte aligned.
7734 To ensure proper alignment of this values on the stack, the stack boundary
7735 must be as aligned as that required by any value stored on the stack.
7736 Further, every function must be generated such that it keeps the stack
7737 aligned. Thus calling a function compiled with a higher preferred
7738 stack boundary from a function compiled with a lower preferred stack
7739 boundary will most likely misalign the stack. It is recommended that
7740 libraries that use callbacks always use the default setting.
7742 This extra alignment does consume extra stack space, and generally
7743 increases code size. Code that is sensitive to stack space usage, such
7744 as embedded systems and operating system kernels, may want to reduce the
7745 preferred alignment to @option{-mpreferred-stack-boundary=2}.
7761 These switches enable or disable the use of built-in functions that allow
7762 direct access to the MMX, SSE and 3Dnow extensions of the instruction set.
7764 @xref{X86 Built-in Functions}, for details of the functions enabled
7765 and disabled by these switches.
7768 @itemx -mno-push-args
7770 @opindex mno-push-args
7771 Use PUSH operations to store outgoing parameters. This method is shorter
7772 and usually equally fast as method using SUB/MOV operations and is enabled
7773 by default. In some cases disabling it may improve performance because of
7774 improved scheduling and reduced dependencies.
7776 @item -maccumulate-outgoing-args
7777 @opindex maccumulate-outgoing-args
7778 If enabled, the maximum amount of space required for outgoing arguments will be
7779 computed in the function prologue. This is faster on most modern CPUs
7780 because of reduced dependencies, improved scheduling and reduced stack usage
7781 when preferred stack boundary is not equal to 2. The drawback is a notable
7782 increase in code size. This switch implies @option{-mno-push-args}.
7786 Support thread-safe exception handling on @samp{Mingw32}. Code that relies
7787 on thread-safe exception handling must compile and link all code with the
7788 @option{-mthreads} option. When compiling, @option{-mthreads} defines
7789 @option{-D_MT}; when linking, it links in a special thread helper library
7790 @option{-lmingwthrd} which cleans up per thread exception handling data.
7792 @item -mno-align-stringops
7793 @opindex mno-align-stringops
7794 Do not align destination of inlined string operations. This switch reduces
7795 code size and improves performance in case the destination is already aligned,
7796 but gcc don't know about it.
7798 @item -minline-all-stringops
7799 @opindex minline-all-stringops
7800 By default GCC inlines string operations only when destination is known to be
7801 aligned at least to 4 byte boundary. This enables more inlining, increase code
7802 size, but may improve performance of code that depends on fast memcpy, strlen
7803 and memset for short lengths.
7805 @item -momit-leaf-frame-pointer
7806 @opindex momit-leaf-frame-pointer
7807 Don't keep the frame pointer in a register for leaf functions. This
7808 avoids the instructions to save, set up and restore frame pointers and
7809 makes an extra register available in leaf functions. The option
7810 @option{-fomit-frame-pointer} removes the frame pointer for all functions
7811 which might make debugging harder.
7814 These @samp{-m} switches are supported in addition to the above
7815 on AMD x86-64 processors in 64-bit environments.
7822 Generate code for a 32-bit or 64-bit environment.
7823 The 32-bit environment sets int, long and pointer to 32 bits and
7824 generates code that runs on any i386 system.
7825 The 64-bit environment sets int to 32 bits and long and pointer
7826 to 64 bits and generates code for AMD's x86-64 architecture.
7829 @opindex no-red-zone
7830 Do not use a so called red zone for x86-64 code. The red zone is mandated
7831 by the x86-64 ABI, it is a 128-byte area beyond the location of the
7832 stack pointer that will not be modified by signal or interrupt handlers
7833 and therefore can be used for temporary data without adjusting the stack
7834 pointer. The flag @option{-mno-red-zone} disables this red zone.
7838 @subsection HPPA Options
7839 @cindex HPPA Options
7841 These @samp{-m} options are defined for the HPPA family of computers:
7844 @item -march=@var{architecture-type}
7846 Generate code for the specified architecture. The choices for
7847 @var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
7848 1.1, and @samp{2.0} for PA 2.0 processors. Refer to
7849 @file{/usr/lib/sched.models} on an HP-UX system to determine the proper
7850 architecture option for your machine. Code compiled for lower numbered
7851 architectures will run on higher numbered architectures, but not the
7854 PA 2.0 support currently requires gas snapshot 19990413 or later. The
7855 next release of binutils (current is 2.9.1) will probably contain PA 2.0
7859 @itemx -mpa-risc-1-1
7860 @itemx -mpa-risc-2-0
7861 @opindex mpa-risc-1-0
7862 @opindex mpa-risc-1-1
7863 @opindex mpa-risc-2-0
7864 Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
7867 @opindex mbig-switch
7868 Generate code suitable for big switch tables. Use this option only if
7869 the assembler/linker complain about out of range branches within a switch
7872 @item -mjump-in-delay
7873 @opindex mjump-in-delay
7874 Fill delay slots of function calls with unconditional jump instructions
7875 by modifying the return pointer for the function call to be the target
7876 of the conditional jump.
7878 @item -mdisable-fpregs
7879 @opindex mdisable-fpregs
7880 Prevent floating point registers from being used in any manner. This is
7881 necessary for compiling kernels which perform lazy context switching of
7882 floating point registers. If you use this option and attempt to perform
7883 floating point operations, the compiler will abort.
7885 @item -mdisable-indexing
7886 @opindex mdisable-indexing
7887 Prevent the compiler from using indexing address modes. This avoids some
7888 rather obscure problems when compiling MIG generated code under MACH@.
7890 @item -mno-space-regs
7891 @opindex mno-space-regs
7892 Generate code that assumes the target has no space registers. This allows
7893 GCC to generate faster indirect calls and use unscaled index address modes.
7895 Such code is suitable for level 0 PA systems and kernels.
7897 @item -mfast-indirect-calls
7898 @opindex mfast-indirect-calls
7899 Generate code that assumes calls never cross space boundaries. This
7900 allows GCC to emit code which performs faster indirect calls.
7902 This option will not work in the presence of shared libraries or nested
7905 @item -mlong-load-store
7906 @opindex mlong-load-store
7907 Generate 3-instruction load and store sequences as sometimes required by
7908 the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
7911 @item -mportable-runtime
7912 @opindex mportable-runtime
7913 Use the portable calling conventions proposed by HP for ELF systems.
7917 Enable the use of assembler directives only GAS understands.
7919 @item -mschedule=@var{cpu-type}
7921 Schedule code according to the constraints for the machine type
7922 @var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
7923 @samp{7100}, @samp{7100LC}, @samp{7200}, and @samp{8000}. Refer to
7924 @file{/usr/lib/sched.models} on an HP-UX system to determine the
7925 proper scheduling option for your machine.
7928 @opindex mlinker-opt
7929 Enable the optimization pass in the HPUX linker. Note this makes symbolic
7930 debugging impossible. It also triggers a bug in the HPUX 8 and HPUX 9 linkers
7931 in which they give bogus error messages when linking some programs.
7934 @opindex msoft-float
7935 Generate output containing library calls for floating point.
7936 @strong{Warning:} the requisite libraries are not available for all HPPA
7937 targets. Normally the facilities of the machine's usual C compiler are
7938 used, but this cannot be done directly in cross-compilation. You must make
7939 your own arrangements to provide suitable library functions for
7940 cross-compilation. The embedded target @samp{hppa1.1-*-pro}
7941 does provide software floating point support.
7943 @option{-msoft-float} changes the calling convention in the output file;
7944 therefore, it is only useful if you compile @emph{all} of a program with
7945 this option. In particular, you need to compile @file{libgcc.a}, the
7946 library that comes with GCC, with @option{-msoft-float} in order for
7950 @node Intel 960 Options
7951 @subsection Intel 960 Options
7953 These @samp{-m} options are defined for the Intel 960 implementations:
7956 @item -m@var{cpu-type}
7964 Assume the defaults for the machine type @var{cpu-type} for some of
7965 the other options, including instruction scheduling, floating point
7966 support, and addressing modes. The choices for @var{cpu-type} are
7967 @samp{ka}, @samp{kb}, @samp{mc}, @samp{ca}, @samp{cf},
7968 @samp{sa}, and @samp{sb}.
7975 @opindex msoft-float
7976 The @option{-mnumerics} option indicates that the processor does support
7977 floating-point instructions. The @option{-msoft-float} option indicates
7978 that floating-point support should not be assumed.
7980 @item -mleaf-procedures
7981 @itemx -mno-leaf-procedures
7982 @opindex mleaf-procedures
7983 @opindex mno-leaf-procedures
7984 Do (or do not) attempt to alter leaf procedures to be callable with the
7985 @code{bal} instruction as well as @code{call}. This will result in more
7986 efficient code for explicit calls when the @code{bal} instruction can be
7987 substituted by the assembler or linker, but less efficient code in other
7988 cases, such as calls via function pointers, or using a linker that doesn't
7989 support this optimization.
7992 @itemx -mno-tail-call
7994 @opindex mno-tail-call
7995 Do (or do not) make additional attempts (beyond those of the
7996 machine-independent portions of the compiler) to optimize tail-recursive
7997 calls into branches. You may not want to do this because the detection of
7998 cases where this is not valid is not totally complete. The default is
7999 @option{-mno-tail-call}.
8001 @item -mcomplex-addr
8002 @itemx -mno-complex-addr
8003 @opindex mcomplex-addr
8004 @opindex mno-complex-addr
8005 Assume (or do not assume) that the use of a complex addressing mode is a
8006 win on this implementation of the i960. Complex addressing modes may not
8007 be worthwhile on the K-series, but they definitely are on the C-series.
8008 The default is currently @option{-mcomplex-addr} for all processors except
8012 @itemx -mno-code-align
8013 @opindex mcode-align
8014 @opindex mno-code-align
8015 Align code to 8-byte boundaries for faster fetching (or don't bother).
8016 Currently turned on by default for C-series implementations only.
8019 @item -mclean-linkage
8020 @itemx -mno-clean-linkage
8021 @opindex mclean-linkage
8022 @opindex mno-clean-linkage
8023 These options are not fully implemented.
8027 @itemx -mic2.0-compat
8028 @itemx -mic3.0-compat
8030 @opindex mic2.0-compat
8031 @opindex mic3.0-compat
8032 Enable compatibility with iC960 v2.0 or v3.0.
8036 @opindex masm-compat
8038 Enable compatibility with the iC960 assembler.
8040 @item -mstrict-align
8041 @itemx -mno-strict-align
8042 @opindex mstrict-align
8043 @opindex mno-strict-align
8044 Do not permit (do permit) unaligned accesses.
8048 Enable structure-alignment compatibility with Intel's gcc release version
8049 1.3 (based on gcc 1.37). This option implies @option{-mstrict-align}.
8051 @item -mlong-double-64
8052 @opindex mlong-double-64
8053 Implement type @samp{long double} as 64-bit floating point numbers.
8054 Without the option @samp{long double} is implemented by 80-bit
8055 floating point numbers. The only reason we have it because there is
8056 no 128-bit @samp{long double} support in @samp{fp-bit.c} yet. So it
8057 is only useful for people using soft-float targets. Otherwise, we
8058 should recommend against use of it.
8062 @node DEC Alpha Options
8063 @subsection DEC Alpha Options
8065 These @samp{-m} options are defined for the DEC Alpha implementations:
8068 @item -mno-soft-float
8070 @opindex mno-soft-float
8071 @opindex msoft-float
8072 Use (do not use) the hardware floating-point instructions for
8073 floating-point operations. When @option{-msoft-float} is specified,
8074 functions in @file{libgcc.a} will be used to perform floating-point
8075 operations. Unless they are replaced by routines that emulate the
8076 floating-point operations, or compiled in such a way as to call such
8077 emulations routines, these routines will issue floating-point
8078 operations. If you are compiling for an Alpha without floating-point
8079 operations, you must ensure that the library is built so as not to call
8082 Note that Alpha implementations without floating-point operations are
8083 required to have floating-point registers.
8088 @opindex mno-fp-regs
8089 Generate code that uses (does not use) the floating-point register set.
8090 @option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
8091 register set is not used, floating point operands are passed in integer
8092 registers as if they were integers and floating-point results are passed
8093 in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
8094 so any function with a floating-point argument or return value called by code
8095 compiled with @option{-mno-fp-regs} must also be compiled with that
8098 A typical use of this option is building a kernel that does not use,
8099 and hence need not save and restore, any floating-point registers.
8103 The Alpha architecture implements floating-point hardware optimized for
8104 maximum performance. It is mostly compliant with the IEEE floating
8105 point standard. However, for full compliance, software assistance is
8106 required. This option generates code fully IEEE compliant code
8107 @emph{except} that the @var{inexact-flag} is not maintained (see below).
8108 If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
8109 defined during compilation. The resulting code is less efficient but is
8110 able to correctly support denormalized numbers and exceptional IEEE
8111 values such as not-a-number and plus/minus infinity. Other Alpha
8112 compilers call this option @option{-ieee_with_no_inexact}.
8114 @item -mieee-with-inexact
8115 @opindex mieee-with-inexact
8116 This is like @option{-mieee} except the generated code also maintains
8117 the IEEE @var{inexact-flag}. Turning on this option causes the
8118 generated code to implement fully-compliant IEEE math. In addition to
8119 @code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
8120 macro. On some Alpha implementations the resulting code may execute
8121 significantly slower than the code generated by default. Since there is
8122 very little code that depends on the @var{inexact-flag}, you should
8123 normally not specify this option. Other Alpha compilers call this
8124 option @option{-ieee_with_inexact}.
8126 @item -mfp-trap-mode=@var{trap-mode}
8127 @opindex mfp-trap-mode
8128 This option controls what floating-point related traps are enabled.
8129 Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
8130 The trap mode can be set to one of four values:
8134 This is the default (normal) setting. The only traps that are enabled
8135 are the ones that cannot be disabled in software (e.g., division by zero
8139 In addition to the traps enabled by @samp{n}, underflow traps are enabled
8143 Like @samp{su}, but the instructions are marked to be safe for software
8144 completion (see Alpha architecture manual for details).
8147 Like @samp{su}, but inexact traps are enabled as well.
8150 @item -mfp-rounding-mode=@var{rounding-mode}
8151 @opindex mfp-rounding-mode
8152 Selects the IEEE rounding mode. Other Alpha compilers call this option
8153 @option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
8158 Normal IEEE rounding mode. Floating point numbers are rounded towards
8159 the nearest machine number or towards the even machine number in case
8163 Round towards minus infinity.
8166 Chopped rounding mode. Floating point numbers are rounded towards zero.
8169 Dynamic rounding mode. A field in the floating point control register
8170 (@var{fpcr}, see Alpha architecture reference manual) controls the
8171 rounding mode in effect. The C library initializes this register for
8172 rounding towards plus infinity. Thus, unless your program modifies the
8173 @var{fpcr}, @samp{d} corresponds to round towards plus infinity.
8176 @item -mtrap-precision=@var{trap-precision}
8177 @opindex mtrap-precision
8178 In the Alpha architecture, floating point traps are imprecise. This
8179 means without software assistance it is impossible to recover from a
8180 floating trap and program execution normally needs to be terminated.
8181 GCC can generate code that can assist operating system trap handlers
8182 in determining the exact location that caused a floating point trap.
8183 Depending on the requirements of an application, different levels of
8184 precisions can be selected:
8188 Program precision. This option is the default and means a trap handler
8189 can only identify which program caused a floating point exception.
8192 Function precision. The trap handler can determine the function that
8193 caused a floating point exception.
8196 Instruction precision. The trap handler can determine the exact
8197 instruction that caused a floating point exception.
8200 Other Alpha compilers provide the equivalent options called
8201 @option{-scope_safe} and @option{-resumption_safe}.
8203 @item -mieee-conformant
8204 @opindex mieee-conformant
8205 This option marks the generated code as IEEE conformant. You must not
8206 use this option unless you also specify @option{-mtrap-precision=i} and either
8207 @option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
8208 is to emit the line @samp{.eflag 48} in the function prologue of the
8209 generated assembly file. Under DEC Unix, this has the effect that
8210 IEEE-conformant math library routines will be linked in.
8212 @item -mbuild-constants
8213 @opindex mbuild-constants
8214 Normally GCC examines a 32- or 64-bit integer constant to
8215 see if it can construct it from smaller constants in two or three
8216 instructions. If it cannot, it will output the constant as a literal and
8217 generate code to load it from the data segment at runtime.
8219 Use this option to require GCC to construct @emph{all} integer constants
8220 using code, even if it takes more instructions (the maximum is six).
8222 You would typically use this option to build a shared library dynamic
8223 loader. Itself a shared library, it must relocate itself in memory
8224 before it can find the variables and constants in its own data segment.
8230 Select whether to generate code to be assembled by the vendor-supplied
8231 assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
8249 Indicate whether GCC should generate code to use the optional BWX,
8250 CIX, FIX and MAX instruction sets. The default is to use the instruction
8251 sets supported by the CPU type specified via @option{-mcpu=} option or that
8252 of the CPU on which GCC was built if none was specified.
8257 @opindex mfloat-ieee
8258 Generate code that uses (does not use) VAX F and G floating point
8259 arithmetic instead of IEEE single and double precision.
8261 @item -mexplicit-relocs
8262 @itemx -mno-explicit-relocs
8263 @opindex mexplicit-relocs
8264 @opindex mno-explicit-relocs
8265 Older Alpha assemblers provided no way to generate symbol relocations
8266 except via assembler macros. Use of these macros does not allow
8267 optimial instruction scheduling. GNU binutils as of version 2.12
8268 supports a new syntax that allows the compiler to explicitly mark
8269 which relocations should apply to which instructions. This option
8270 is mostly useful for debugging, as GCC detects the capabilities of
8271 the assembler when it is built and sets the default accordingly.
8275 @opindex msmall-data
8276 @opindex mlarge-data
8277 When @option{-mexplicit-relocs} is in effect, static data is
8278 accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
8279 is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
8280 (the @code{.sdata} and @code{.sbss} sections) and are accessed via
8281 16-bit relocations off of the @code{$gp} register. This limits the
8282 size of the small data area to 64KB, but allows the variables to be
8283 directly accessed via a single instruction.
8285 The default is @option{-mlarge-data}. With this option the data area
8286 is limited to just below 2GB. Programs that require more than 2GB of
8287 data must use @code{malloc} or @code{mmap} to allocate the data in the
8288 heap instead of in the program's data segment.
8290 When generating code for shared libraries, @option{-fpic} implies
8291 @option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
8293 @item -mcpu=@var{cpu_type}
8295 Set the instruction set and instruction scheduling parameters for
8296 machine type @var{cpu_type}. You can specify either the @samp{EV}
8297 style name or the corresponding chip number. GCC supports scheduling
8298 parameters for the EV4, EV5 and EV6 family of processors and will
8299 choose the default values for the instruction set from the processor
8300 you specify. If you do not specify a processor type, GCC will default
8301 to the processor on which the compiler was built.
8303 Supported values for @var{cpu_type} are
8309 Schedules as an EV4 and has no instruction set extensions.
8313 Schedules as an EV5 and has no instruction set extensions.
8317 Schedules as an EV5 and supports the BWX extension.
8322 Schedules as an EV5 and supports the BWX and MAX extensions.
8326 Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
8330 Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
8333 @item -mtune=@var{cpu_type}
8335 Set only the instruction scheduling parameters for machine type
8336 @var{cpu_type}. The instruction set is not changed.
8338 @item -mmemory-latency=@var{time}
8339 @opindex mmemory-latency
8340 Sets the latency the scheduler should assume for typical memory
8341 references as seen by the application. This number is highly
8342 dependent on the memory access patterns used by the application
8343 and the size of the external cache on the machine.
8345 Valid options for @var{time} are
8349 A decimal number representing clock cycles.
8355 The compiler contains estimates of the number of clock cycles for
8356 ``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
8357 (also called Dcache, Scache, and Bcache), as well as to main memory.
8358 Note that L3 is only valid for EV5.
8363 @node DEC Alpha/VMS Options
8364 @subsection DEC Alpha/VMS Options
8366 These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
8369 @item -mvms-return-codes
8370 @opindex mvms-return-codes
8371 Return VMS condition codes from main. The default is to return POSIX
8372 style condition (e.g.@ error) codes.
8375 @node Clipper Options
8376 @subsection Clipper Options
8378 These @samp{-m} options are defined for the Clipper implementations:
8383 Produce code for a C300 Clipper processor. This is the default.
8387 Produce code for a C400 Clipper processor, i.e.@: use floating point
8391 @node H8/300 Options
8392 @subsection H8/300 Options
8394 These @samp{-m} options are defined for the H8/300 implementations:
8399 Shorten some address references at link time, when possible; uses the
8400 linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
8401 ld.info, Using ld}, for a fuller description.
8405 Generate code for the H8/300H@.
8409 Generate code for the H8/S@.
8413 Generate code for the H8/S2600. This switch must be used with @option{-ms}.
8417 Make @code{int} data 32 bits by default.
8421 On the H8/300H and H8/S, use the same alignment rules as for the H8/300.
8422 The default for the H8/300H and H8/S is to align longs and floats on 4
8424 @option{-malign-300} causes them to be aligned on 2 byte boundaries.
8425 This option has no effect on the H8/300.
8429 @subsection SH Options
8431 These @samp{-m} options are defined for the SH implementations:
8436 Generate code for the SH1.
8440 Generate code for the SH2.
8444 Generate code for the SH3.
8448 Generate code for the SH3e.
8452 Generate code for the SH4 without a floating-point unit.
8454 @item -m4-single-only
8455 @opindex m4-single-only
8456 Generate code for the SH4 with a floating-point unit that only
8457 supports single-precision arithmetic.
8461 Generate code for the SH4 assuming the floating-point unit is in
8462 single-precision mode by default.
8466 Generate code for the SH4.
8470 Compile code for the processor in big endian mode.
8474 Compile code for the processor in little endian mode.
8478 Align doubles at 64-bit boundaries. Note that this changes the calling
8479 conventions, and thus some functions from the standard C library will
8480 not work unless you recompile it first with @option{-mdalign}.
8484 Shorten some address references at link time, when possible; uses the
8485 linker option @option{-relax}.
8489 Use 32-bit offsets in @code{switch} tables. The default is to use
8494 Enable the use of the instruction @code{fmovd}.
8498 Comply with the calling conventions defined by Hitachi.
8502 Mark the @code{MAC} register as call-clobbered, even if
8503 @option{-mhitachi} is given.
8507 Increase IEEE-compliance of floating-point code.
8511 Dump instruction size and location in the assembly code.
8515 This option is deprecated. It pads structures to multiple of 4 bytes,
8516 which is incompatible with the SH ABI@.
8520 Optimize for space instead of speed. Implied by @option{-Os}.
8524 When generating position-independent code, emit function calls using
8525 the Global Offset Table instead of the Procedure Linkage Table.
8529 Generate a library function call to invalidate instruction cache
8530 entries, after fixing up a trampoline. This library function call
8531 doesn't assume it can write to the whole memory address space. This
8532 is the default when the target is @code{sh-*-linux*}.
8535 @node System V Options
8536 @subsection Options for System V
8538 These additional options are available on System V Release 4 for
8539 compatibility with other compilers on those systems:
8544 Create a shared object.
8545 It is recommended that @option{-symbolic} or @option{-shared} be used instead.
8549 Identify the versions of each tool used by the compiler, in a
8550 @code{.ident} assembler directive in the output.
8554 Refrain from adding @code{.ident} directives to the output file (this is
8557 @item -YP,@var{dirs}
8559 Search the directories @var{dirs}, and no others, for libraries
8560 specified with @option{-l}.
8564 Look in the directory @var{dir} to find the M4 preprocessor.
8565 The assembler uses this option.
8566 @c This is supposed to go with a -Yd for predefined M4 macro files, but
8567 @c the generic assembler that comes with Solaris takes just -Ym.
8570 @node TMS320C3x/C4x Options
8571 @subsection TMS320C3x/C4x Options
8572 @cindex TMS320C3x/C4x Options
8574 These @samp{-m} options are defined for TMS320C3x/C4x implementations:
8578 @item -mcpu=@var{cpu_type}
8580 Set the instruction set, register set, and instruction scheduling
8581 parameters for machine type @var{cpu_type}. Supported values for
8582 @var{cpu_type} are @samp{c30}, @samp{c31}, @samp{c32}, @samp{c40}, and
8583 @samp{c44}. The default is @samp{c40} to generate code for the
8588 @itemx -msmall-memory
8590 @opindex mbig-memory
8592 @opindex msmall-memory
8594 Generates code for the big or small memory model. The small memory
8595 model assumed that all data fits into one 64K word page. At run-time
8596 the data page (DP) register must be set to point to the 64K page
8597 containing the .bss and .data program sections. The big memory model is
8598 the default and requires reloading of the DP register for every direct
8605 Allow (disallow) allocation of general integer operands into the block
8612 Enable (disable) generation of code using decrement and branch,
8613 DBcond(D), instructions. This is enabled by default for the C4x. To be
8614 on the safe side, this is disabled for the C3x, since the maximum
8615 iteration count on the C3x is @math{2^{23} + 1} (but who iterates loops more than
8616 @math{2^{23}} times on the C3x?). Note that GCC will try to reverse a loop so
8617 that it can utilise the decrement and branch instruction, but will give
8618 up if there is more than one memory reference in the loop. Thus a loop
8619 where the loop counter is decremented can generate slightly more
8620 efficient code, in cases where the RPTB instruction cannot be utilised.
8622 @item -mdp-isr-reload
8624 @opindex mdp-isr-reload
8626 Force the DP register to be saved on entry to an interrupt service
8627 routine (ISR), reloaded to point to the data section, and restored on
8628 exit from the ISR@. This should not be required unless someone has
8629 violated the small memory model by modifying the DP register, say within
8636 For the C3x use the 24-bit MPYI instruction for integer multiplies
8637 instead of a library call to guarantee 32-bit results. Note that if one
8638 of the operands is a constant, then the multiplication will be performed
8639 using shifts and adds. If the @option{-mmpyi} option is not specified for the C3x,
8640 then squaring operations are performed inline instead of a library call.
8643 @itemx -mno-fast-fix
8645 @opindex mno-fast-fix
8646 The C3x/C4x FIX instruction to convert a floating point value to an
8647 integer value chooses the nearest integer less than or equal to the
8648 floating point value rather than to the nearest integer. Thus if the
8649 floating point number is negative, the result will be incorrectly
8650 truncated an additional code is necessary to detect and correct this
8651 case. This option can be used to disable generation of the additional
8652 code required to correct the result.
8658 Enable (disable) generation of repeat block sequences using the RPTB
8659 instruction for zero overhead looping. The RPTB construct is only used
8660 for innermost loops that do not call functions or jump across the loop
8661 boundaries. There is no advantage having nested RPTB loops due to the
8662 overhead required to save and restore the RC, RS, and RE registers.
8663 This is enabled by default with @option{-O2}.
8665 @item -mrpts=@var{count}
8669 Enable (disable) the use of the single instruction repeat instruction
8670 RPTS@. If a repeat block contains a single instruction, and the loop
8671 count can be guaranteed to be less than the value @var{count}, GCC will
8672 emit a RPTS instruction instead of a RPTB@. If no value is specified,
8673 then a RPTS will be emitted even if the loop count cannot be determined
8674 at compile time. Note that the repeated instruction following RPTS does
8675 not have to be reloaded from memory each iteration, thus freeing up the
8676 CPU buses for operands. However, since interrupts are blocked by this
8677 instruction, it is disabled by default.
8679 @item -mloop-unsigned
8680 @itemx -mno-loop-unsigned
8681 @opindex mloop-unsigned
8682 @opindex mno-loop-unsigned
8683 The maximum iteration count when using RPTS and RPTB (and DB on the C40)
8684 is @math{2^{31} + 1} since these instructions test if the iteration count is
8685 negative to terminate the loop. If the iteration count is unsigned
8686 there is a possibility than the @math{2^{31} + 1} maximum iteration count may be
8687 exceeded. This switch allows an unsigned iteration count.
8691 Try to emit an assembler syntax that the TI assembler (asm30) is happy
8692 with. This also enforces compatibility with the API employed by the TI
8693 C3x C compiler. For example, long doubles are passed as structures
8694 rather than in floating point registers.
8700 Generate code that uses registers (stack) for passing arguments to functions.
8701 By default, arguments are passed in registers where possible rather
8702 than by pushing arguments on to the stack.
8704 @item -mparallel-insns
8705 @itemx -mno-parallel-insns
8706 @opindex mparallel-insns
8707 @opindex mno-parallel-insns
8708 Allow the generation of parallel instructions. This is enabled by
8709 default with @option{-O2}.
8711 @item -mparallel-mpy
8712 @itemx -mno-parallel-mpy
8713 @opindex mparallel-mpy
8714 @opindex mno-parallel-mpy
8715 Allow the generation of MPY||ADD and MPY||SUB parallel instructions,
8716 provided @option{-mparallel-insns} is also specified. These instructions have
8717 tight register constraints which can pessimize the code generation
8723 @subsection V850 Options
8724 @cindex V850 Options
8726 These @samp{-m} options are defined for V850 implementations:
8730 @itemx -mno-long-calls
8731 @opindex mlong-calls
8732 @opindex mno-long-calls
8733 Treat all calls as being far away (near). If calls are assumed to be
8734 far away, the compiler will always load the functions address up into a
8735 register, and call indirect through the pointer.
8741 Do not optimize (do optimize) basic blocks that use the same index
8742 pointer 4 or more times to copy pointer into the @code{ep} register, and
8743 use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
8744 option is on by default if you optimize.
8746 @item -mno-prolog-function
8747 @itemx -mprolog-function
8748 @opindex mno-prolog-function
8749 @opindex mprolog-function
8750 Do not use (do use) external functions to save and restore registers at
8751 the prolog and epilog of a function. The external functions are slower,
8752 but use less code space if more than one function saves the same number
8753 of registers. The @option{-mprolog-function} option is on by default if
8758 Try to make the code as small as possible. At present, this just turns
8759 on the @option{-mep} and @option{-mprolog-function} options.
8763 Put static or global variables whose size is @var{n} bytes or less into
8764 the tiny data area that register @code{ep} points to. The tiny data
8765 area can hold up to 256 bytes in total (128 bytes for byte references).
8769 Put static or global variables whose size is @var{n} bytes or less into
8770 the small data area that register @code{gp} points to. The small data
8771 area can hold up to 64 kilobytes.
8775 Put static or global variables whose size is @var{n} bytes or less into
8776 the first 32 kilobytes of memory.
8780 Specify that the target processor is the V850.
8783 @opindex mbig-switch
8784 Generate code suitable for big switch tables. Use this option only if
8785 the assembler/linker complain about out of range branches within a switch
8790 @subsection ARC Options
8793 These options are defined for ARC implementations:
8798 Compile code for little endian mode. This is the default.
8802 Compile code for big endian mode.
8805 @opindex mmangle-cpu
8806 Prepend the name of the cpu to all public symbol names.
8807 In multiple-processor systems, there are many ARC variants with different
8808 instruction and register set characteristics. This flag prevents code
8809 compiled for one cpu to be linked with code compiled for another.
8810 No facility exists for handling variants that are ``almost identical''.
8811 This is an all or nothing option.
8813 @item -mcpu=@var{cpu}
8815 Compile code for ARC variant @var{cpu}.
8816 Which variants are supported depend on the configuration.
8817 All variants support @option{-mcpu=base}, this is the default.
8819 @item -mtext=@var{text-section}
8820 @itemx -mdata=@var{data-section}
8821 @itemx -mrodata=@var{readonly-data-section}
8825 Put functions, data, and readonly data in @var{text-section},
8826 @var{data-section}, and @var{readonly-data-section} respectively
8827 by default. This can be overridden with the @code{section} attribute.
8828 @xref{Variable Attributes}.
8833 @subsection NS32K Options
8834 @cindex NS32K options
8836 These are the @samp{-m} options defined for the 32000 series. The default
8837 values for these options depends on which style of 32000 was selected when
8838 the compiler was configured; the defaults for the most common choices are
8846 Generate output for a 32032. This is the default
8847 when the compiler is configured for 32032 and 32016 based systems.
8853 Generate output for a 32332. This is the default
8854 when the compiler is configured for 32332-based systems.
8860 Generate output for a 32532. This is the default
8861 when the compiler is configured for 32532-based systems.
8865 Generate output containing 32081 instructions for floating point.
8866 This is the default for all systems.
8870 Generate output containing 32381 instructions for floating point. This
8871 also implies @option{-m32081}. The 32381 is only compatible with the 32332
8872 and 32532 cpus. This is the default for the pc532-netbsd configuration.
8876 Try and generate multiply-add floating point instructions @code{polyF}
8877 and @code{dotF}. This option is only available if the @option{-m32381}
8878 option is in effect. Using these instructions requires changes to
8879 register allocation which generally has a negative impact on
8880 performance. This option should only be enabled when compiling code
8881 particularly likely to make heavy use of multiply-add instructions.
8884 @opindex mnomulti-add
8885 Do not try and generate multiply-add floating point instructions
8886 @code{polyF} and @code{dotF}. This is the default on all platforms.
8889 @opindex msoft-float
8890 Generate output containing library calls for floating point.
8891 @strong{Warning:} the requisite libraries may not be available.
8894 @opindex mnobitfield
8895 Do not use the bit-field instructions. On some machines it is faster to
8896 use shifting and masking operations. This is the default for the pc532.
8900 Do use the bit-field instructions. This is the default for all platforms
8905 Use a different function-calling convention, in which functions
8906 that take a fixed number of arguments return pop their
8907 arguments on return with the @code{ret} instruction.
8909 This calling convention is incompatible with the one normally
8910 used on Unix, so you cannot use it if you need to call libraries
8911 compiled with the Unix compiler.
8913 Also, you must provide function prototypes for all functions that
8914 take variable numbers of arguments (including @code{printf});
8915 otherwise incorrect code will be generated for calls to those
8918 In addition, seriously incorrect code will result if you call a
8919 function with too many arguments. (Normally, extra arguments are
8920 harmlessly ignored.)
8922 This option takes its name from the 680x0 @code{rtd} instruction.
8927 Use a different function-calling convention where the first two arguments
8928 are passed in registers.
8930 This calling convention is incompatible with the one normally
8931 used on Unix, so you cannot use it if you need to call libraries
8932 compiled with the Unix compiler.
8935 @opindex mnoregparam
8936 Do not pass any arguments in registers. This is the default for all
8941 It is OK to use the sb as an index register which is always loaded with
8942 zero. This is the default for the pc532-netbsd target.
8946 The sb register is not available for use or has not been initialized to
8947 zero by the run time system. This is the default for all targets except
8948 the pc532-netbsd. It is also implied whenever @option{-mhimem} or
8949 @option{-fpic} is set.
8953 Many ns32000 series addressing modes use displacements of up to 512MB@.
8954 If an address is above 512MB then displacements from zero can not be used.
8955 This option causes code to be generated which can be loaded above 512MB@.
8956 This may be useful for operating systems or ROM code.
8960 Assume code will be loaded in the first 512MB of virtual address space.
8961 This is the default for all platforms.
8967 @subsection AVR Options
8970 These options are defined for AVR implementations:
8973 @item -mmcu=@var{mcu}
8975 Specify ATMEL AVR instruction set or MCU type.
8977 Instruction set avr1 is for the minimal AVR core, not supported by the C
8978 compiler, only for assembler programs (MCU types: at90s1200, attiny10,
8979 attiny11, attiny12, attiny15, attiny28).
8981 Instruction set avr2 (default) is for the classic AVR core with up to
8982 8K program memory space (MCU types: at90s2313, at90s2323, attiny22,
8983 at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
8984 at90c8534, at90s8535).
8986 Instruction set avr3 is for the classic AVR core with up to 128K program
8987 memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
8989 Instruction set avr4 is for the enhanced AVR core with up to 8K program
8990 memory space (MCU types: atmega8, atmega83, atmega85).
8992 Instruction set avr5 is for the enhanced AVR core with up to 128K program
8993 memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
8994 atmega64, atmega128, at43usb355, at94k).
8998 Output instruction sizes to the asm file.
9000 @item -minit-stack=@var{N}
9001 @opindex minit-stack
9002 Specify the initial stack address, which may be a symbol or numeric value,
9003 @samp{__stack} is the default.
9005 @item -mno-interrupts
9006 @opindex mno-interrupts
9007 Generated code is not compatible with hardware interrupts.
9008 Code size will be smaller.
9010 @item -mcall-prologues
9011 @opindex mcall-prologues
9012 Functions prologues/epilogues expanded as call to appropriate
9013 subroutines. Code size will be smaller.
9015 @item -mno-tablejump
9016 @opindex mno-tablejump
9017 Do not generate tablejump insns which sometimes increase code size.
9020 @opindex mtiny-stack
9021 Change only the low 8 bits of the stack pointer.
9025 @subsection MCore Options
9026 @cindex MCore options
9028 These are the @samp{-m} options defined for the Motorola M*Core
9038 @opindex mno-hardlit
9039 Inline constants into the code stream if it can be done in two
9040 instructions or less.
9048 Use the divide instruction. (Enabled by default).
9050 @item -mrelax-immediate
9051 @itemx -mrelax-immediate
9052 @itemx -mno-relax-immediate
9053 @opindex mrelax-immediate
9054 @opindex mrelax-immediate
9055 @opindex mno-relax-immediate
9056 Allow arbitrary sized immediates in bit operations.
9058 @item -mwide-bitfields
9059 @itemx -mwide-bitfields
9060 @itemx -mno-wide-bitfields
9061 @opindex mwide-bitfields
9062 @opindex mwide-bitfields
9063 @opindex mno-wide-bitfields
9064 Always treat bit-fields as int-sized.
9066 @item -m4byte-functions
9067 @itemx -m4byte-functions
9068 @itemx -mno-4byte-functions
9069 @opindex m4byte-functions
9070 @opindex m4byte-functions
9071 @opindex mno-4byte-functions
9072 Force all functions to be aligned to a four byte boundary.
9074 @item -mcallgraph-data
9075 @itemx -mcallgraph-data
9076 @itemx -mno-callgraph-data
9077 @opindex mcallgraph-data
9078 @opindex mcallgraph-data
9079 @opindex mno-callgraph-data
9080 Emit callgraph information.
9084 @itemx -mno-slow-bytes
9085 @opindex mslow-bytes
9086 @opindex mslow-bytes
9087 @opindex mno-slow-bytes
9088 Prefer word access when reading byte quantities.
9090 @item -mlittle-endian
9091 @itemx -mlittle-endian
9093 @opindex mlittle-endian
9094 @opindex mlittle-endian
9095 @opindex mbig-endian
9096 Generate code for a little endian target.
9104 Generate code for the 210 processor.
9108 @subsection IA-64 Options
9109 @cindex IA-64 Options
9111 These are the @samp{-m} options defined for the Intel IA-64 architecture.
9115 @opindex mbig-endian
9116 Generate code for a big endian target. This is the default for HPUX@.
9118 @item -mlittle-endian
9119 @opindex mlittle-endian
9120 Generate code for a little endian target. This is the default for AIX5
9127 Generate (or don't) code for the GNU assembler. This is the default.
9128 @c Also, this is the default if the configure option @option{--with-gnu-as}
9135 Generate (or don't) code for the GNU linker. This is the default.
9136 @c Also, this is the default if the configure option @option{--with-gnu-ld}
9141 Generate code that does not use a global pointer register. The result
9142 is not position independent code, and violates the IA-64 ABI@.
9144 @item -mvolatile-asm-stop
9145 @itemx -mno-volatile-asm-stop
9146 @opindex mvolatile-asm-stop
9147 @opindex mno-volatile-asm-stop
9148 Generate (or don't) a stop bit immediately before and after volatile asm
9153 Generate code that works around Itanium B step errata.
9155 @item -mregister-names
9156 @itemx -mno-register-names
9157 @opindex mregister-names
9158 @opindex mno-register-names
9159 Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
9160 the stacked registers. This may make assembler output more readable.
9166 Disable (or enable) optimizations that use the small data section. This may
9167 be useful for working around optimizer bugs.
9170 @opindex mconstant-gp
9171 Generate code that uses a single constant global pointer value. This is
9172 useful when compiling kernel code.
9176 Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
9177 This is useful when compiling firmware code.
9179 @item -minline-divide-min-latency
9180 @opindex minline-divide-min-latency
9181 Generate code for inline divides using the minimum latency algorithm.
9183 @item -minline-divide-max-throughput
9184 @opindex minline-divide-max-throughput
9185 Generate code for inline divides using the maximum throughput algorithm.
9187 @item -mno-dwarf2-asm
9189 @opindex mno-dwarf2-asm
9190 @opindex mdwarf2-asm
9191 Don't (or do) generate assembler code for the DWARF2 line number debugging
9192 info. This may be useful when not using the GNU assembler.
9194 @item -mfixed-range=@var{register-range}
9195 @opindex mfixed-range
9196 Generate code treating the given register range as fixed registers.
9197 A fixed register is one that the register allocator can not use. This is
9198 useful when compiling kernel code. A register range is specified as
9199 two registers separated by a dash. Multiple register ranges can be
9200 specified separated by a comma.
9204 @subsection D30V Options
9205 @cindex D30V Options
9207 These @samp{-m} options are defined for D30V implementations:
9212 Link the @samp{.text}, @samp{.data}, @samp{.bss}, @samp{.strings},
9213 @samp{.rodata}, @samp{.rodata1}, @samp{.data1} sections into external
9214 memory, which starts at location @code{0x80000000}.
9218 Same as the @option{-mextmem} switch.
9222 Link the @samp{.text} section into onchip text memory, which starts at
9223 location @code{0x0}. Also link @samp{.data}, @samp{.bss},
9224 @samp{.strings}, @samp{.rodata}, @samp{.rodata1}, @samp{.data1} sections
9225 into onchip data memory, which starts at location @code{0x20000000}.
9227 @item -mno-asm-optimize
9228 @itemx -masm-optimize
9229 @opindex mno-asm-optimize
9230 @opindex masm-optimize
9231 Disable (enable) passing @option{-O} to the assembler when optimizing.
9232 The assembler uses the @option{-O} option to automatically parallelize
9233 adjacent short instructions where possible.
9235 @item -mbranch-cost=@var{n}
9236 @opindex mbranch-cost
9237 Increase the internal costs of branches to @var{n}. Higher costs means
9238 that the compiler will issue more instructions to avoid doing a branch.
9241 @item -mcond-exec=@var{n}
9243 Specify the maximum number of conditionally executed instructions that
9244 replace a branch. The default is 4.
9247 @node S/390 and zSeries Options
9248 @subsection S/390 and zSeries Options
9249 @cindex S/390 and zSeries Options
9251 These are the @samp{-m} options defined for the S/390 and zSeries architecture.
9256 @opindex mhard-float
9257 @opindex msoft-float
9258 Use (do not use) the hardware floating-point instructions and registers
9259 for floating-point operations. When @option{-msoft-float} is specified,
9260 functions in @file{libgcc.a} will be used to perform floating-point
9261 operations. When @option{-mhard-float} is specified, the compiler
9262 generates IEEE floating-point instructions. This is the default.
9265 @itemx -mno-backchain
9267 @opindex mno-backchain
9268 Generate (or do not generate) code which maintains an explicit
9269 backchain within the stack frame that points to the caller's frame.
9270 This is currently needed to allow debugging. The default is to
9271 generate the backchain.
9274 @itemx -mno-small-exec
9275 @opindex msmall-exec
9276 @opindex mno-small-exec
9277 Generate (or do not generate) code using the @code{bras} instruction
9278 to do subroutine calls.
9279 This only works reliably if the total executable size does not
9280 exceed 64k. The default is to use the @code{basr} instruction instead,
9281 which does not have this limitation.
9287 When @option{-m31} is specified, generate code compliant to the
9288 Linux for S/390 ABI@. When @option{-m64} is specified, generate
9289 code compliant to the Linux for zSeries ABI@. This allows GCC in
9290 particular to generate 64-bit instructions. For the @samp{s390}
9291 targets, the default is @option{-m31}, while the @samp{s390x}
9292 targets default to @option{-m64}.
9298 Generate (or do not generate) code using the @code{mvcle} instruction
9299 to perform block moves. When @option{-mno-mvcle} is specifed,
9300 use a @code{mvc} loop instead. This is the default.
9306 Print (or do not print) additional debug information when compiling.
9307 The default is to not print debug information.
9312 @subsection CRIS Options
9313 @cindex CRIS Options
9315 These options are defined specifically for the CRIS ports.
9318 @item -march=@var{architecture-type}
9319 @itemx -mcpu=@var{architecture-type}
9322 Generate code for the specified architecture. The choices for
9323 @var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
9324 respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX.
9325 Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
9328 @item -mtune=@var{architecture-type}
9330 Tune to @var{architecture-type} everything applicable about the generated
9331 code, except for the ABI and the set of available instructions. The
9332 choices for @var{architecture-type} are the same as for
9333 @option{-march=@var{architecture-type}}.
9335 @item -mmax-stack-frame=@var{n}
9336 @opindex mmax-stack-frame
9337 Warn when the stack frame of a function exceeds @var{n} bytes.
9339 @item -melinux-stacksize=@var{n}
9340 @opindex melinux-stacksize
9341 Only available with the @samp{cris-axis-aout} target. Arranges for
9342 indications in the program to the kernel loader that the stack of the
9343 program should be set to @var{n} bytes.
9349 The options @option{-metrax4} and @option{-metrax100} are synonyms for
9350 @option{-march=v3} and @option{-march=v8} respectively.
9354 Enable CRIS-specific verbose debug-related information in the assembly
9355 code. This option also has the effect to turn off the @samp{#NO_APP}
9356 formatted-code indicator to the assembler at the beginning of the
9361 Do not use condition-code results from previous instruction; always emit
9362 compare and test instructions before use of condition codes.
9364 @item -mno-side-effects
9365 @opindex mno-side-effects
9366 Do not emit instructions with side-effects in addressing modes other than
9370 @itemx -mno-stack-align
9372 @itemx -mno-data-align
9373 @itemx -mconst-align
9374 @itemx -mno-const-align
9375 @opindex mstack-align
9376 @opindex mno-stack-align
9377 @opindex mdata-align
9378 @opindex mno-data-align
9379 @opindex mconst-align
9380 @opindex mno-const-align
9381 These options (no-options) arranges (eliminate arrangements) for the
9382 stack-frame, individual data and constants to be aligned for the maximum
9383 single data access size for the chosen CPU model. The default is to
9384 arrange for 32-bit alignment. ABI details such as structure layout are
9385 not affected by these options.
9393 Similar to the stack- data- and const-align options above, these options
9394 arrange for stack-frame, writable data and constants to all be 32-bit,
9395 16-bit or 8-bit aligned. The default is 32-bit alignment.
9397 @item -mno-prologue-epilogue
9398 @itemx -mprologue-epilogue
9399 @opindex mno-prologue-epilogue
9400 @opindex mprologue-epilogue
9401 With @option{-mno-prologue-epilogue}, the normal function prologue and
9402 epilogue that sets up the stack-frame are omitted and no return
9403 instructions or return sequences are generated in the code. Use this
9404 option only together with visual inspection of the compiled code: no
9405 warnings or errors are generated when call-saved registers must be saved,
9406 or storage for local variable needs to be allocated.
9412 With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
9413 instruction sequences that load addresses for functions from the PLT part
9414 of the GOT rather than (traditional on other architectures) calls to the
9415 PLT. The default is @option{-mgotplt}.
9419 Legacy no-op option only recognized with the cris-axis-aout target.
9423 Legacy no-op option only recognized with the cris-axis-elf and
9424 cris-axis-linux-gnu targets.
9428 Only recognized with the cris-axis-aout target, where it selects a
9429 GNU/linux-like multilib, include files and instruction set for
9434 Legacy no-op option only recognized with the cris-axis-linux-gnu target.
9438 This option, recognized for the cris-axis-aout and cris-axis-elf arranges
9439 to link with input-output functions from a simulator library. Code,
9440 initialized data and zero-initialized data are allocated consecutively.
9444 Like @option{-sim}, but pass linker options to locate initialized data at
9445 0x40000000 and zero-initialized data at 0x80000000.
9449 @subsection MMIX Options
9450 @cindex MMIX Options
9452 These options are defined for the MMIX:
9456 @itemx -mno-libfuncs
9458 @opindex mno-libfuncs
9459 Specify that intrinsic library functions are being compiled, passing all
9460 values in registers, no matter the size.
9465 @opindex mno-epsilon
9466 Generate floating-point comparison instructions that compare with respect
9467 to the @code{rE} epsilon register.
9469 @item -mabi=mmixware
9471 @opindex mabi-mmixware
9473 Generate code that passes function parameters and return values that (in
9474 the called function) are seen as registers @code{$0} and up, as opposed to
9475 the GNU ABI which uses global registers @code{$231} and up.
9478 @itemx -mno-zero-extend
9479 @opindex mzero-extend
9480 @opindex mno-zero-extend
9481 When reading data from memory in sizes shorter than 64 bits, use (do not
9482 use) zero-extending load instructions by default, rather than
9483 sign-extending ones.
9486 @itemx -mno-knuthdiv
9488 @opindex mno-knuthdiv
9489 Make the result of a division yielding a remainder have the same sign as
9490 the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
9491 remainder follows the sign of the dividend. Both methods are
9492 arithmetically valid, the latter being almost exclusively used.
9494 @item -mtoplevel-symbols
9495 @itemx -mno-toplevel-symbols
9496 @opindex mtoplevel-symbols
9497 @opindex mno-toplevel-symbols
9498 Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
9499 code can be used with the @code{PREFIX} assembly directive.
9503 Generate an executable in the ELF format, rather than the default
9504 @samp{mmo} format used by the @command{mmix} simulator.
9506 @item -mbranch-predict
9507 @itemx -mno-branch-predict
9508 @opindex mbranch-predict
9509 @opindex mno-branch-predict
9510 Use (do not use) the probable-branch instructions, when static branch
9511 prediction indicates a probable branch.
9513 @item -mbase-addresses
9514 @itemx -mno-base-addresses
9515 @opindex mbase-addresses
9516 @opindex mno-base-addresses
9517 Generate (do not generate) code that uses @emph{base addresses}. Using a
9518 base address automatically generates a request (handled by the assembler
9519 and the linker) for a constant to be set up in a global register. The
9520 register is used for one or more base address requests within the range 0
9521 to 255 from the value held in the register. The generally leads to short
9522 and fast code, but the number of different data items that can be
9523 addressed is limited. This means that a program that uses lots of static
9524 data may require @option{-mno-base-addresses}.
9527 @node PDP-11 Options
9528 @subsection PDP-11 Options
9529 @cindex PDP-11 Options
9531 These options are defined for the PDP-11:
9536 Use hardware FPP floating point. This is the default. (FIS floating
9537 point on the PDP-11/40 is not supported.)
9540 @opindex msoft-float
9541 Do not use hardware floating point.
9545 Return floating-point results in ac0 (fr0 in Unix assembler syntax).
9549 Return floating-point results in memory. This is the default.
9553 Generate code for a PDP-11/40.
9557 Generate code for a PDP-11/45. This is the default.
9561 Generate code for a PDP-11/10.
9563 @item -mbcopy-builtin
9564 @opindex bcopy-builtin
9565 Use inline @code{movstrhi} patterns for copying memory. This is the
9570 Do not use inline @code{movstrhi} patterns for copying memory.
9576 Use 16-bit @code{int}. This is the default.
9582 Use 32-bit @code{int}.
9587 @opindex mno-float32
9588 Use 64-bit @code{float}. This is the default.
9593 @opindex mno-float64
9594 Use 32-bit @code{float}.
9598 Use @code{abshi2} pattern. This is the default.
9602 Do not use @code{abshi2} pattern.
9604 @item -mbranch-expensive
9605 @opindex mbranch-expensive
9606 Pretend that branches are expensive. This is for experimenting with
9607 code generation only.
9609 @item -mbranch-cheap
9610 @opindex mbranch-cheap
9611 Do not pretend that branches are expensive. This is the default.
9615 Generate code for a system with split I&D.
9619 Generate code for a system without split I&D. This is the default.
9623 Use Unix assembler syntax. This is the default when configured for
9628 Use DEC assembler syntax. This is the default when configured for any
9629 PDP-11 target other than @samp{pdp11-*-bsd}.
9632 @node Xstormy16 Options
9633 @subsection Xstormy16 Options
9634 @cindex Xstormy16 Options
9636 These options are defined for Xstormy16:
9641 Choose startup files and linker script suitable for the simulator.
9644 @node Xtensa Options
9645 @subsection Xtensa Options
9646 @cindex Xtensa Options
9648 The Xtensa architecture is designed to support many different
9649 configurations. The compiler's default options can be set to match a
9650 particular Xtensa configuration by copying a configuration file into the
9651 GCC sources when building GCC@. The options below may be used to
9652 override the default options.
9656 @itemx -mlittle-endian
9657 @opindex mbig-endian
9658 @opindex mlittle-endian
9659 Specify big-endian or little-endian byte ordering for the target Xtensa
9665 @opindex mno-density
9666 Enable or disable use of the optional Xtensa code density instructions.
9672 Enable or disable use of the Xtensa MAC16 option. When enabled, GCC
9673 will generate MAC16 instructions from standard C code, with the
9674 limitation that it will use neither the MR register file nor any
9675 instruction that operates on the MR registers. When this option is
9676 disabled, GCC will translate 16-bit multiply/accumulate operations to a
9677 combination of core instructions and library calls, depending on whether
9678 any other multiplier options are enabled.
9684 Enable or disable use of the 16-bit integer multiplier option. When
9685 enabled, the compiler will generate 16-bit multiply instructions for
9686 multiplications of 16 bits or smaller in standard C code. When this
9687 option is disabled, the compiler will either use 32-bit multiply or
9688 MAC16 instructions if they are available or generate library calls to
9689 perform the multiply operations using shifts and adds.
9695 Enable or disable use of the 32-bit integer multiplier option. When
9696 enabled, the compiler will generate 32-bit multiply instructions for
9697 multiplications of 32 bits or smaller in standard C code. When this
9698 option is disabled, the compiler will generate library calls to perform
9699 the multiply operations using either shifts and adds or 16-bit multiply
9700 instructions if they are available.
9706 Enable or disable use of the optional normalization shift amount
9707 (@code{NSA}) instructions to implement the built-in @code{ffs} function.
9713 Enable or disable use of the optional minimum and maximum value
9720 Enable or disable use of the optional sign extend (@code{SEXT})
9724 @itemx -mno-booleans
9726 @opindex mno-booleans
9727 Enable or disable support for the boolean register file used by Xtensa
9728 coprocessors. This is not typically useful by itself but may be
9729 required for other options that make use of the boolean registers (e.g.,
9730 the floating-point option).
9734 @opindex mhard-float
9735 @opindex msoft-float
9736 Enable or disable use of the floating-point option. When enabled, GCC
9737 generates floating-point instructions for 32-bit @code{float}
9738 operations. When this option is disabled, GCC generates library calls
9739 to emulate 32-bit floating-point operations using integer instructions.
9740 Regardless of this option, 64-bit @code{double} operations are always
9741 emulated with calls to library functions.
9744 @itemx -mno-fused-madd
9745 @opindex mfused-madd
9746 @opindex mno-fused-madd
9747 Enable or disable use of fused multiply/add and multiply/subtract
9748 instructions in the floating-point option. This has no effect if the
9749 floating-point option is not also enabled. Disabling fused multiply/add
9750 and multiply/subtract instructions forces the compiler to use separate
9751 instructions for the multiply and add/subtract operations. This may be
9752 desirable in some cases where strict IEEE 754-compliant results are
9753 required: the fused multiply add/subtract instructions do not round the
9754 intermediate result, thereby producing results with @emph{more} bits of
9755 precision than specified by the IEEE standard. Disabling fused multiply
9756 add/subtract instructions also ensures that the program output is not
9757 sensitive to the compiler's ability to combine multiply and add/subtract
9760 @item -mserialize-volatile
9761 @itemx -mno-serialize-volatile
9762 @opindex mserialize-volatile
9763 @opindex mno-serialize-volatile
9764 When this option is enabled, GCC inserts @code{MEMW} instructions before
9765 @code{volatile} memory references to guarantee sequential consistency.
9766 The default is @option{-mserialize-volatile}. Use
9767 @option{-mno-serialize-volatile} to omit the @code{MEMW} instructions.
9769 @item -mtext-section-literals
9770 @itemx -mno-text-section-literals
9771 @opindex mtext-section-literals
9772 @opindex mno-text-section-literals
9773 Control the treatment of literal pools. The default is
9774 @option{-mno-text-section-literals}, which places literals in a separate
9775 section in the output file. This allows the literal pool to be placed
9776 in a data RAM/ROM, and it also allows the linker to combine literal
9777 pools from separate object files to remove redundant literals and
9778 improve code size. With @option{-mtext-section-literals}, the literals
9779 are interspersed in the text section in order to keep them as close as
9780 possible to their references. This may be necessary for large assembly
9783 @item -mtarget-align
9784 @itemx -mno-target-align
9785 @opindex mtarget-align
9786 @opindex mno-target-align
9787 When this option is enabled, GCC instructs the assembler to
9788 automatically align instructions to reduce branch penalties at the
9789 expense of some code density. The assembler attempts to widen density
9790 instructions to align branch targets and the instructions following call
9791 instructions. If there are not enough preceding safe density
9792 instructions to align a target, no widening will be performed. The
9793 default is @option{-mtarget-align}. These options do not affect the
9794 treatment of auto-aligned instructions like @code{LOOP}, which the
9795 assembler will always align, either by widening density instructions or
9796 by inserting no-op instructions.
9799 @itemx -mno-longcalls
9801 @opindex mno-longcalls
9802 When this option is enabled, GCC instructs the assembler to translate
9803 direct calls to indirect calls unless it can determine that the target
9804 of a direct call is in the range allowed by the call instruction. This
9805 translation typically occurs for calls to functions in other source
9806 files. Specifically, the assembler translates a direct @code{CALL}
9807 instruction into an @code{L32R} followed by a @code{CALLX} instruction.
9808 The default is @option{-mno-longcalls}. This option should be used in
9809 programs where the call target can potentially be out of range. This
9810 option is implemented in the assembler, not the compiler, so the
9811 assembly code generated by GCC will still show direct call
9812 instructions---look at the disassembled object code to see the actual
9813 instructions. Note that the assembler will use an indirect call for
9814 every cross-file call, not just those that really will be out of range.
9817 @node Code Gen Options
9818 @section Options for Code Generation Conventions
9819 @cindex code generation conventions
9820 @cindex options, code generation
9821 @cindex run-time options
9823 These machine-independent options control the interface conventions
9824 used in code generation.
9826 Most of them have both positive and negative forms; the negative form
9827 of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
9828 one of the forms is listed---the one which is not the default. You
9829 can figure out the other form by either removing @samp{no-} or adding
9834 @opindex fexceptions
9835 Enable exception handling. Generates extra code needed to propagate
9836 exceptions. For some targets, this implies GCC will generate frame
9837 unwind information for all functions, which can produce significant data
9838 size overhead, although it does not affect execution. If you do not
9839 specify this option, GCC will enable it by default for languages like
9840 C++ which normally require exception handling, and disable it for
9841 languages like C that do not normally require it. However, you may need
9842 to enable this option when compiling C code that needs to interoperate
9843 properly with exception handlers written in C++. You may also wish to
9844 disable this option if you are compiling older C++ programs that don't
9845 use exception handling.
9847 @item -fnon-call-exceptions
9848 @opindex fnon-call-exceptions
9849 Generate code that allows trapping instructions to throw exceptions.
9850 Note that this requires platform-specific runtime support that does
9851 not exist everywhere. Moreover, it only allows @emph{trapping}
9852 instructions to throw exceptions, i.e.@: memory references or floating
9853 point instructions. It does not allow exceptions to be thrown from
9854 arbitrary signal handlers such as @code{SIGALRM}.
9856 @item -funwind-tables
9857 @opindex funwind-tables
9858 Similar to @option{-fexceptions}, except that it will just generate any needed
9859 static data, but will not affect the generated code in any other way.
9860 You will normally not enable this option; instead, a language processor
9861 that needs this handling would enable it on your behalf.
9863 @item -fasynchronous-unwind-tables
9864 @opindex funwind-tables
9865 Generate unwind table in dwarf2 format, if supported by target machine. The
9866 table is exact at each instruction boundary, so it can be used for stack
9867 unwinding from asynchronous events (such as debugger or garbage collector).
9869 @item -fpcc-struct-return
9870 @opindex fpcc-struct-return
9871 Return ``short'' @code{struct} and @code{union} values in memory like
9872 longer ones, rather than in registers. This convention is less
9873 efficient, but it has the advantage of allowing intercallability between
9874 GCC-compiled files and files compiled with other compilers.
9876 The precise convention for returning structures in memory depends
9877 on the target configuration macros.
9879 Short structures and unions are those whose size and alignment match
9880 that of some integer type.
9882 @item -freg-struct-return
9883 @opindex freg-struct-return
9884 Return @code{struct} and @code{union} values in registers when possible.
9885 This is more efficient for small structures than
9886 @option{-fpcc-struct-return}.
9888 If you specify neither @option{-fpcc-struct-return} nor
9889 @option{-freg-struct-return}, GCC defaults to whichever convention is
9890 standard for the target. If there is no standard convention, GCC
9891 defaults to @option{-fpcc-struct-return}, except on targets where GCC is
9892 the principal compiler. In those cases, we can choose the standard, and
9893 we chose the more efficient register return alternative.
9896 @opindex fshort-enums
9897 Allocate to an @code{enum} type only as many bytes as it needs for the
9898 declared range of possible values. Specifically, the @code{enum} type
9899 will be equivalent to the smallest integer type which has enough room.
9901 @item -fshort-double
9902 @opindex fshort-double
9903 Use the same size for @code{double} as for @code{float}.
9906 @opindex fshared-data
9907 Requests that the data and non-@code{const} variables of this
9908 compilation be shared data rather than private data. The distinction
9909 makes sense only on certain operating systems, where shared data is
9910 shared between processes running the same program, while private data
9911 exists in one copy per process.
9915 In C, allocate even uninitialized global variables in the data section of the
9916 object file, rather than generating them as common blocks. This has the
9917 effect that if the same variable is declared (without @code{extern}) in
9918 two different compilations, you will get an error when you link them.
9919 The only reason this might be useful is if you wish to verify that the
9920 program will work on other systems which always work this way.
9924 Ignore the @samp{#ident} directive.
9926 @item -fno-gnu-linker
9927 @opindex fno-gnu-linker
9928 Do not output global initializations (such as C++ constructors and
9929 destructors) in the form used by the GNU linker (on systems where the GNU
9930 linker is the standard method of handling them). Use this option when
9931 you want to use a non-GNU linker, which also requires using the
9932 @command{collect2} program to make sure the system linker includes
9933 constructors and destructors. (@command{collect2} is included in the GCC
9934 distribution.) For systems which @emph{must} use @command{collect2}, the
9935 compiler driver @command{gcc} is configured to do this automatically.
9937 @item -finhibit-size-directive
9938 @opindex finhibit-size-directive
9939 Don't output a @code{.size} assembler directive, or anything else that
9940 would cause trouble if the function is split in the middle, and the
9941 two halves are placed at locations far apart in memory. This option is
9942 used when compiling @file{crtstuff.c}; you should not need to use it
9946 @opindex fverbose-asm
9947 Put extra commentary information in the generated assembly code to
9948 make it more readable. This option is generally only of use to those
9949 who actually need to read the generated assembly code (perhaps while
9950 debugging the compiler itself).
9952 @option{-fno-verbose-asm}, the default, causes the
9953 extra information to be omitted and is useful when comparing two assembler
9958 Consider all memory references through pointers to be volatile.
9960 @item -fvolatile-global
9961 @opindex fvolatile-global
9962 Consider all memory references to extern and global data items to
9963 be volatile. GCC does not consider static data items to be volatile
9964 because of this switch.
9966 @item -fvolatile-static
9967 @opindex fvolatile-static
9968 Consider all memory references to static data to be volatile.
9972 @cindex global offset table
9974 Generate position-independent code (PIC) suitable for use in a shared
9975 library, if supported for the target machine. Such code accesses all
9976 constant addresses through a global offset table (GOT)@. The dynamic
9977 loader resolves the GOT entries when the program starts (the dynamic
9978 loader is not part of GCC; it is part of the operating system). If
9979 the GOT size for the linked executable exceeds a machine-specific
9980 maximum size, you get an error message from the linker indicating that
9981 @option{-fpic} does not work; in that case, recompile with @option{-fPIC}
9982 instead. (These maximums are 16k on the m88k, 8k on the Sparc, and 32k
9983 on the m68k and RS/6000. The 386 has no such limit.)
9985 Position-independent code requires special support, and therefore works
9986 only on certain machines. For the 386, GCC supports PIC for System V
9987 but not for the Sun 386i. Code generated for the IBM RS/6000 is always
9988 position-independent.
9992 If supported for the target machine, emit position-independent code,
9993 suitable for dynamic linking and avoiding any limit on the size of the
9994 global offset table. This option makes a difference on the m68k, m88k,
9997 Position-independent code requires special support, and therefore works
9998 only on certain machines.
10000 @item -ffixed-@var{reg}
10002 Treat the register named @var{reg} as a fixed register; generated code
10003 should never refer to it (except perhaps as a stack pointer, frame
10004 pointer or in some other fixed role).
10006 @var{reg} must be the name of a register. The register names accepted
10007 are machine-specific and are defined in the @code{REGISTER_NAMES}
10008 macro in the machine description macro file.
10010 This flag does not have a negative form, because it specifies a
10013 @item -fcall-used-@var{reg}
10014 @opindex fcall-used
10015 Treat the register named @var{reg} as an allocable register that is
10016 clobbered by function calls. It may be allocated for temporaries or
10017 variables that do not live across a call. Functions compiled this way
10018 will not save and restore the register @var{reg}.
10020 It is an error to used this flag with the frame pointer or stack pointer.
10021 Use of this flag for other registers that have fixed pervasive roles in
10022 the machine's execution model will produce disastrous results.
10024 This flag does not have a negative form, because it specifies a
10027 @item -fcall-saved-@var{reg}
10028 @opindex fcall-saved
10029 Treat the register named @var{reg} as an allocable register saved by
10030 functions. It may be allocated even for temporaries or variables that
10031 live across a call. Functions compiled this way will save and restore
10032 the register @var{reg} if they use it.
10034 It is an error to used this flag with the frame pointer or stack pointer.
10035 Use of this flag for other registers that have fixed pervasive roles in
10036 the machine's execution model will produce disastrous results.
10038 A different sort of disaster will result from the use of this flag for
10039 a register in which function values may be returned.
10041 This flag does not have a negative form, because it specifies a
10044 @item -fpack-struct
10045 @opindex fpack-struct
10046 Pack all structure members together without holes. Usually you would
10047 not want to use this option, since it makes the code suboptimal, and
10048 the offsets of structure members won't agree with system libraries.
10050 @item -finstrument-functions
10051 @opindex finstrument-functions
10052 Generate instrumentation calls for entry and exit to functions. Just
10053 after function entry and just before function exit, the following
10054 profiling functions will be called with the address of the current
10055 function and its call site. (On some platforms,
10056 @code{__builtin_return_address} does not work beyond the current
10057 function, so the call site information may not be available to the
10058 profiling functions otherwise.)
10061 void __cyg_profile_func_enter (void *this_fn,
10063 void __cyg_profile_func_exit (void *this_fn,
10067 The first argument is the address of the start of the current function,
10068 which may be looked up exactly in the symbol table.
10070 This instrumentation is also done for functions expanded inline in other
10071 functions. The profiling calls will indicate where, conceptually, the
10072 inline function is entered and exited. This means that addressable
10073 versions of such functions must be available. If all your uses of a
10074 function are expanded inline, this may mean an additional expansion of
10075 code size. If you use @samp{extern inline} in your C code, an
10076 addressable version of such functions must be provided. (This is
10077 normally the case anyways, but if you get lucky and the optimizer always
10078 expands the functions inline, you might have gotten away without
10079 providing static copies.)
10081 A function may be given the attribute @code{no_instrument_function}, in
10082 which case this instrumentation will not be done. This can be used, for
10083 example, for the profiling functions listed above, high-priority
10084 interrupt routines, and any functions from which the profiling functions
10085 cannot safely be called (perhaps signal handlers, if the profiling
10086 routines generate output or allocate memory).
10088 @item -fstack-check
10089 @opindex fstack-check
10090 Generate code to verify that you do not go beyond the boundary of the
10091 stack. You should specify this flag if you are running in an
10092 environment with multiple threads, but only rarely need to specify it in
10093 a single-threaded environment since stack overflow is automatically
10094 detected on nearly all systems if there is only one stack.
10096 Note that this switch does not actually cause checking to be done; the
10097 operating system must do that. The switch causes generation of code
10098 to ensure that the operating system sees the stack being extended.
10100 @item -fstack-limit-register=@var{reg}
10101 @itemx -fstack-limit-symbol=@var{sym}
10102 @itemx -fno-stack-limit
10103 @opindex fstack-limit-register
10104 @opindex fstack-limit-symbol
10105 @opindex fno-stack-limit
10106 Generate code to ensure that the stack does not grow beyond a certain value,
10107 either the value of a register or the address of a symbol. If the stack
10108 would grow beyond the value, a signal is raised. For most targets,
10109 the signal is raised before the stack overruns the boundary, so
10110 it is possible to catch the signal without taking special precautions.
10112 For instance, if the stack starts at absolute address @samp{0x80000000}
10113 and grows downwards, you can use the flags
10114 @option{-fstack-limit-symbol=__stack_limit} and
10115 @option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
10116 of 128KB@. Note that this may only work with the GNU linker.
10118 @cindex aliasing of parameters
10119 @cindex parameters, aliased
10120 @item -fargument-alias
10121 @itemx -fargument-noalias
10122 @itemx -fargument-noalias-global
10123 @opindex fargument-alias
10124 @opindex fargument-noalias
10125 @opindex fargument-noalias-global
10126 Specify the possible relationships among parameters and between
10127 parameters and global data.
10129 @option{-fargument-alias} specifies that arguments (parameters) may
10130 alias each other and may alias global storage.@*
10131 @option{-fargument-noalias} specifies that arguments do not alias
10132 each other, but may alias global storage.@*
10133 @option{-fargument-noalias-global} specifies that arguments do not
10134 alias each other and do not alias global storage.
10136 Each language will automatically use whatever option is required by
10137 the language standard. You should not need to use these options yourself.
10139 @item -fleading-underscore
10140 @opindex fleading-underscore
10141 This option and its counterpart, @option{-fno-leading-underscore}, forcibly
10142 change the way C symbols are represented in the object file. One use
10143 is to help link with legacy assembly code.
10145 Be warned that you should know what you are doing when invoking this
10146 option, and that not all targets provide complete support for it.
10151 @node Environment Variables
10152 @section Environment Variables Affecting GCC
10153 @cindex environment variables
10155 @c man begin ENVIRONMENT
10157 This section describes several environment variables that affect how GCC
10158 operates. Some of them work by specifying directories or prefixes to use
10159 when searching for various kinds of files. Some are used to specify other
10160 aspects of the compilation environment.
10162 Note that you can also specify places to search using options such as
10163 @option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
10164 take precedence over places specified using environment variables, which
10165 in turn take precedence over those specified by the configuration of GCC@.
10166 @xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
10167 GNU Compiler Collection (GCC) Internals}.
10172 @c @itemx LC_COLLATE
10174 @c @itemx LC_MONETARY
10175 @c @itemx LC_NUMERIC
10180 @c @findex LC_COLLATE
10181 @findex LC_MESSAGES
10182 @c @findex LC_MONETARY
10183 @c @findex LC_NUMERIC
10187 These environment variables control the way that GCC uses
10188 localization information that allow GCC to work with different
10189 national conventions. GCC inspects the locale categories
10190 @env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
10191 so. These locale categories can be set to any value supported by your
10192 installation. A typical value is @samp{en_UK} for English in the United
10195 The @env{LC_CTYPE} environment variable specifies character
10196 classification. GCC uses it to determine the character boundaries in
10197 a string; this is needed for some multibyte encodings that contain quote
10198 and escape characters that would otherwise be interpreted as a string
10201 The @env{LC_MESSAGES} environment variable specifies the language to
10202 use in diagnostic messages.
10204 If the @env{LC_ALL} environment variable is set, it overrides the value
10205 of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
10206 and @env{LC_MESSAGES} default to the value of the @env{LANG}
10207 environment variable. If none of these variables are set, GCC
10208 defaults to traditional C English behavior.
10212 If @env{TMPDIR} is set, it specifies the directory to use for temporary
10213 files. GCC uses temporary files to hold the output of one stage of
10214 compilation which is to be used as input to the next stage: for example,
10215 the output of the preprocessor, which is the input to the compiler
10218 @item GCC_EXEC_PREFIX
10219 @findex GCC_EXEC_PREFIX
10220 If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
10221 names of the subprograms executed by the compiler. No slash is added
10222 when this prefix is combined with the name of a subprogram, but you can
10223 specify a prefix that ends with a slash if you wish.
10225 If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
10226 an appropriate prefix to use based on the pathname it was invoked with.
10228 If GCC cannot find the subprogram using the specified prefix, it
10229 tries looking in the usual places for the subprogram.
10231 The default value of @env{GCC_EXEC_PREFIX} is
10232 @file{@var{prefix}/lib/gcc-lib/} where @var{prefix} is the value
10233 of @code{prefix} when you ran the @file{configure} script.
10235 Other prefixes specified with @option{-B} take precedence over this prefix.
10237 This prefix is also used for finding files such as @file{crt0.o} that are
10240 In addition, the prefix is used in an unusual way in finding the
10241 directories to search for header files. For each of the standard
10242 directories whose name normally begins with @samp{/usr/local/lib/gcc-lib}
10243 (more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
10244 replacing that beginning with the specified prefix to produce an
10245 alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
10246 @file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
10247 These alternate directories are searched first; the standard directories
10250 @item COMPILER_PATH
10251 @findex COMPILER_PATH
10252 The value of @env{COMPILER_PATH} is a colon-separated list of
10253 directories, much like @env{PATH}. GCC tries the directories thus
10254 specified when searching for subprograms, if it can't find the
10255 subprograms using @env{GCC_EXEC_PREFIX}.
10258 @findex LIBRARY_PATH
10259 The value of @env{LIBRARY_PATH} is a colon-separated list of
10260 directories, much like @env{PATH}. When configured as a native compiler,
10261 GCC tries the directories thus specified when searching for special
10262 linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking
10263 using GCC also uses these directories when searching for ordinary
10264 libraries for the @option{-l} option (but directories specified with
10265 @option{-L} come first).
10267 @item C_INCLUDE_PATH
10268 @itemx CPLUS_INCLUDE_PATH
10269 @itemx OBJC_INCLUDE_PATH
10270 @findex C_INCLUDE_PATH
10271 @findex CPLUS_INCLUDE_PATH
10272 @findex OBJC_INCLUDE_PATH
10273 @c @itemx OBJCPLUS_INCLUDE_PATH
10274 These environment variables pertain to particular languages. Each
10275 variable's value is a colon-separated list of directories, much like
10276 @env{PATH}. When GCC searches for header files, it tries the
10277 directories listed in the variable for the language you are using, after
10278 the directories specified with @option{-I} but before the standard header
10281 @item DEPENDENCIES_OUTPUT
10282 @findex DEPENDENCIES_OUTPUT
10283 @cindex dependencies for make as output
10284 If this variable is set, its value specifies how to output dependencies
10285 for Make based on the header files processed by the compiler. This
10286 output looks much like the output from the @option{-M} option
10287 (@pxref{Preprocessor Options}), but it goes to a separate file, and is
10288 in addition to the usual results of compilation.
10290 The value of @env{DEPENDENCIES_OUTPUT} can be just a file name, in
10291 which case the Make rules are written to that file, guessing the target
10292 name from the source file name. Or the value can have the form
10293 @samp{@var{file} @var{target}}, in which case the rules are written to
10294 file @var{file} using @var{target} as the target name.
10298 @cindex locale definition
10299 This variable is used to pass locale information to the compiler. One way in
10300 which this information is used is to determine the character set to be used
10301 when character literals, string literals and comments are parsed in C and C++.
10302 When the compiler is configured to allow multibyte characters,
10303 the following values for @env{LANG} are recognized:
10307 Recognize JIS characters.
10309 Recognize SJIS characters.
10311 Recognize EUCJP characters.
10314 If @env{LANG} is not defined, or if it has some other value, then the
10315 compiler will use mblen and mbtowc as defined by the default locale to
10316 recognize and translate multibyte characters.
10321 @node Running Protoize
10322 @section Running Protoize
10324 The program @code{protoize} is an optional part of GCC@. You can use
10325 it to add prototypes to a program, thus converting the program to ISO
10326 C in one respect. The companion program @code{unprotoize} does the
10327 reverse: it removes argument types from any prototypes that are found.
10329 When you run these programs, you must specify a set of source files as
10330 command line arguments. The conversion programs start out by compiling
10331 these files to see what functions they define. The information gathered
10332 about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
10334 After scanning comes actual conversion. The specified files are all
10335 eligible to be converted; any files they include (whether sources or
10336 just headers) are eligible as well.
10338 But not all the eligible files are converted. By default,
10339 @code{protoize} and @code{unprotoize} convert only source and header
10340 files in the current directory. You can specify additional directories
10341 whose files should be converted with the @option{-d @var{directory}}
10342 option. You can also specify particular files to exclude with the
10343 @option{-x @var{file}} option. A file is converted if it is eligible, its
10344 directory name matches one of the specified directory names, and its
10345 name within the directory has not been excluded.
10347 Basic conversion with @code{protoize} consists of rewriting most
10348 function definitions and function declarations to specify the types of
10349 the arguments. The only ones not rewritten are those for varargs
10352 @code{protoize} optionally inserts prototype declarations at the
10353 beginning of the source file, to make them available for any calls that
10354 precede the function's definition. Or it can insert prototype
10355 declarations with block scope in the blocks where undeclared functions
10358 Basic conversion with @code{unprotoize} consists of rewriting most
10359 function declarations to remove any argument types, and rewriting
10360 function definitions to the old-style pre-ISO form.
10362 Both conversion programs print a warning for any function declaration or
10363 definition that they can't convert. You can suppress these warnings
10366 The output from @code{protoize} or @code{unprotoize} replaces the
10367 original source file. The original file is renamed to a name ending
10368 with @samp{.save} (for DOS, the saved filename ends in @samp{.sav}
10369 without the original @samp{.c} suffix). If the @samp{.save} (@samp{.sav}
10370 for DOS) file already exists, then the source file is simply discarded.
10372 @code{protoize} and @code{unprotoize} both depend on GCC itself to
10373 scan the program and collect information about the functions it uses.
10374 So neither of these programs will work until GCC is installed.
10376 Here is a table of the options you can use with @code{protoize} and
10377 @code{unprotoize}. Each option works with both programs unless
10381 @item -B @var{directory}
10382 Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
10383 usual directory (normally @file{/usr/local/lib}). This file contains
10384 prototype information about standard system functions. This option
10385 applies only to @code{protoize}.
10387 @item -c @var{compilation-options}
10388 Use @var{compilation-options} as the options when running @code{gcc} to
10389 produce the @samp{.X} files. The special option @option{-aux-info} is
10390 always passed in addition, to tell @code{gcc} to write a @samp{.X} file.
10392 Note that the compilation options must be given as a single argument to
10393 @code{protoize} or @code{unprotoize}. If you want to specify several
10394 @code{gcc} options, you must quote the entire set of compilation options
10395 to make them a single word in the shell.
10397 There are certain @code{gcc} arguments that you cannot use, because they
10398 would produce the wrong kind of output. These include @option{-g},
10399 @option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in
10400 the @var{compilation-options}, they are ignored.
10403 Rename files to end in @samp{.C} (@samp{.cc} for DOS-based file
10404 systems) instead of @samp{.c}. This is convenient if you are converting
10405 a C program to C++. This option applies only to @code{protoize}.
10408 Add explicit global declarations. This means inserting explicit
10409 declarations at the beginning of each source file for each function
10410 that is called in the file and was not declared. These declarations
10411 precede the first function definition that contains a call to an
10412 undeclared function. This option applies only to @code{protoize}.
10414 @item -i @var{string}
10415 Indent old-style parameter declarations with the string @var{string}.
10416 This option applies only to @code{protoize}.
10418 @code{unprotoize} converts prototyped function definitions to old-style
10419 function definitions, where the arguments are declared between the
10420 argument list and the initial @samp{@{}. By default, @code{unprotoize}
10421 uses five spaces as the indentation. If you want to indent with just
10422 one space instead, use @option{-i " "}.
10425 Keep the @samp{.X} files. Normally, they are deleted after conversion
10429 Add explicit local declarations. @code{protoize} with @option{-l} inserts
10430 a prototype declaration for each function in each block which calls the
10431 function without any declaration. This option applies only to
10435 Make no real changes. This mode just prints information about the conversions
10436 that would have been done without @option{-n}.
10439 Make no @samp{.save} files. The original files are simply deleted.
10440 Use this option with caution.
10442 @item -p @var{program}
10443 Use the program @var{program} as the compiler. Normally, the name
10444 @file{gcc} is used.
10447 Work quietly. Most warnings are suppressed.
10450 Print the version number, just like @option{-v} for @code{gcc}.
10453 If you need special compiler options to compile one of your program's
10454 source files, then you should generate that file's @samp{.X} file
10455 specially, by running @code{gcc} on that source file with the
10456 appropriate options and the option @option{-aux-info}. Then run
10457 @code{protoize} on the entire set of files. @code{protoize} will use
10458 the existing @samp{.X} file because it is newer than the source file.
10462 gcc -Dfoo=bar file1.c -aux-info file1.X
10467 You need to include the special files along with the rest in the
10468 @code{protoize} command, even though their @samp{.X} files already
10469 exist, because otherwise they won't get converted.
10471 @xref{Protoize Caveats}, for more information on how to use
10472 @code{protoize} successfully.