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 -fms-extensions @gol
168 -trigraphs -traditional -traditional-cpp @gol
169 -fallow-single-precision -fcond-mismatch @gol
170 -fsigned-bitfields -fsigned-char @gol
171 -funsigned-bitfields -funsigned-char @gol
172 -fwritable-strings -fshort-wchar}
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 -Wno-endif-labels @gol
224 -Wlarger-than-@var{len} -Wlong-long @gol
225 -Wmain -Wmissing-braces -Wmissing-declarations @gol
226 -Wmissing-format-attribute -Wmissing-noreturn @gol
227 -Wno-multichar -Wno-format-extra-args -Wno-format-y2k @gol
228 -Wno-import -Wnonnull -Wpacked -Wpadded @gol
229 -Wparentheses -Wpointer-arith -Wredundant-decls @gol
230 -Wreturn-type -Wsequence-point -Wshadow @gol
231 -Wsign-compare -Wswitch -Wswitch-default -Wswitch-enum @gol
232 -Wsystem-headers -Wtrigraphs -Wundef -Wuninitialized @gol
233 -Wunknown-pragmas -Wunreachable-code @gol
234 -Wunused -Wunused-function -Wunused-label -Wunused-parameter @gol
235 -Wunused-value -Wunused-variable -Wwrite-strings}
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 -floop-optimize -fcrossjumping @gol
270 -fif-conversion -fif-conversion2 @gol
271 -finline-functions -finline-limit=@var{n} -fkeep-inline-functions @gol
272 -fkeep-static-consts -fmerge-constants -fmerge-all-constants @gol
273 -fmove-all-movables -fno-default-inline -fno-defer-pop @gol
274 -fno-function-cse -fno-guess-branch-probability @gol
275 -fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol
276 -funsafe-math-optimizations -fno-trapping-math @gol
277 -fno-zero-initialized-in-bss @gol
278 -fomit-frame-pointer -foptimize-register-move @gol
279 -foptimize-sibling-calls -fprefetch-loop-arrays @gol
280 -freduce-all-givs -fregmove -frename-registers @gol
281 -freorder-blocks -freorder-functions @gol
282 -frerun-cse-after-loop -frerun-loop-opt @gol
283 -fschedule-insns -fschedule-insns2 @gol
284 -fsingle-precision-constant -fssa -fssa-ccp -fssa-dce @gol
285 -fstrength-reduce -fstrict-aliasing -ftracer -fthread-jumps -ftrapv @gol
286 -funroll-all-loops -funroll-loops @gol
287 --param @var{name}=@var{value}
288 -O -O0 -O1 -O2 -O3 -Os}
290 @item Preprocessor Options
291 @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
293 -$ -A@var{question}=@var{answer} -A-@var{question}@r{[}=@var{answer}@r{]} @gol
294 -C -dD -dI -dM -dN @gol
295 -D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol
296 -idirafter @var{dir} @gol
297 -include @var{file} -imacros @var{file} @gol
298 -iprefix @var{file} -iwithprefix @var{dir} @gol
299 -iwithprefixbefore @var{dir} -isystem @var{dir} @gol
300 -M -MM -MF -MG -MP -MQ -MT -nostdinc -P -remap @gol
301 -trigraphs -undef -U@var{macro} -Wp,@var{option}}
303 @item Assembler Option
304 @xref{Assembler Options,,Passing Options to the Assembler}.
309 @xref{Link Options,,Options for Linking}.
311 @var{object-file-name} -l@var{library} @gol
312 -nostartfiles -nodefaultlibs -nostdlib @gol
313 -s -static -static-libgcc -shared -shared-libgcc -symbolic @gol
314 -Wl,@var{option} -Xlinker @var{option} @gol
317 @item Directory Options
318 @xref{Directory Options,,Options for Directory Search}.
320 -B@var{prefix} -I@var{dir} -I- -L@var{dir} -specs=@var{file}}
323 @c I wrote this xref this way to avoid overfull hbox. -- rms
324 @xref{Target Options}.
326 -V @var{version} -b @var{machine}}
328 @item Machine Dependent Options
329 @xref{Submodel Options,,Hardware Models and Configurations}.
331 @emph{M680x0 Options}
333 -m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol
334 -m68060 -mcpu32 -m5200 -m68881 -mbitfield -mc68000 -mc68020 @gol
335 -mfpa -mnobitfield -mrtd -mshort -msoft-float -mpcrel @gol
336 -malign-int -mstrict-align}
338 @emph{M68hc1x Options}
340 -m6811 -m6812 -m68hc11 -m68hc12 @gol
341 -mauto-incdec -mshort -msoft-reg-count=@var{count}}
349 -mcpu=@var{cpu-type} @gol
350 -mtune=@var{cpu-type} @gol
351 -mcmodel=@var{code-model} @gol
353 -mapp-regs -mbroken-saverestore -mcypress @gol
354 -mfaster-structs -mflat @gol
355 -mfpu -mhard-float -mhard-quad-float @gol
356 -mimpure-text -mlive-g0 -mno-app-regs @gol
357 -mno-faster-structs -mno-flat -mno-fpu @gol
358 -mno-impure-text -mno-stack-bias -mno-unaligned-doubles @gol
359 -msoft-float -msoft-quad-float -msparclite -mstack-bias @gol
360 -msupersparc -munaligned-doubles -mv8}
362 @emph{Convex Options}
364 -mc1 -mc2 -mc32 -mc34 -mc38 @gol
365 -margcount -mnoargcount @gol
366 -mlong32 -mlong64 @gol
367 -mvolatile-cache -mvolatile-nocache}
369 @emph{AMD29K Options}
371 -m29000 -m29050 -mbw -mnbw -mdw -mndw @gol
372 -mlarge -mnormal -msmall @gol
373 -mkernel-registers -mno-reuse-arg-regs @gol
374 -mno-stack-check -mno-storem-bug @gol
375 -mreuse-arg-regs -msoft-float -mstack-check @gol
376 -mstorem-bug -muser-registers}
380 -mapcs-frame -mno-apcs-frame @gol
381 -mapcs-26 -mapcs-32 @gol
382 -mapcs-stack-check -mno-apcs-stack-check @gol
383 -mapcs-float -mno-apcs-float @gol
384 -mapcs-reentrant -mno-apcs-reentrant @gol
385 -msched-prolog -mno-sched-prolog @gol
386 -mlittle-endian -mbig-endian -mwords-little-endian @gol
387 -malignment-traps -mno-alignment-traps @gol
388 -msoft-float -mhard-float -mfpe @gol
389 -mthumb-interwork -mno-thumb-interwork @gol
390 -mcpu=@var{name} -march=@var{name} -mfpe=@var{name} @gol
391 -mstructure-size-boundary=@var{n} @gol
392 -mbsd -mxopen -mno-symrename @gol
393 -mabort-on-noreturn @gol
394 -mlong-calls -mno-long-calls @gol
395 -msingle-pic-base -mno-single-pic-base @gol
396 -mpic-register=@var{reg} @gol
397 -mnop-fun-dllimport @gol
398 -mpoke-function-name @gol
400 -mtpcs-frame -mtpcs-leaf-frame @gol
401 -mcaller-super-interworking -mcallee-super-interworking }
403 @emph{MN10200 Options}
407 @emph{MN10300 Options}
409 -mmult-bug -mno-mult-bug @gol
410 -mam33 -mno-am33 @gol
413 @emph{M32R/D Options}
415 -m32rx -m32r -mcode-model=@var{model-type} -msdata=@var{sdata-type} @gol
420 -m88000 -m88100 -m88110 -mbig-pic @gol
421 -mcheck-zero-division -mhandle-large-shift @gol
422 -midentify-revision -mno-check-zero-division @gol
423 -mno-ocs-debug-info -mno-ocs-frame-position @gol
424 -mno-optimize-arg-area -mno-serialize-volatile @gol
425 -mno-underscores -mocs-debug-info @gol
426 -mocs-frame-position -moptimize-arg-area @gol
427 -mserialize-volatile -mshort-data-@var{num} -msvr3 @gol
428 -msvr4 -mtrap-large-shift -muse-div-instruction @gol
429 -mversion-03.00 -mwarn-passed-structs}
431 @emph{RS/6000 and PowerPC Options}
433 -mcpu=@var{cpu-type} @gol
434 -mtune=@var{cpu-type} @gol
435 -mpower -mno-power -mpower2 -mno-power2 @gol
436 -mpowerpc -mpowerpc64 -mno-powerpc @gol
437 -maltivec -mno-altivec @gol
438 -mpowerpc-gpopt -mno-powerpc-gpopt @gol
439 -mpowerpc-gfxopt -mno-powerpc-gfxopt @gol
440 -mnew-mnemonics -mold-mnemonics @gol
441 -mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc @gol
442 -m64 -m32 -mxl-call -mno-xl-call -mpe @gol
443 -msoft-float -mhard-float -mmultiple -mno-multiple @gol
444 -mstring -mno-string -mupdate -mno-update @gol
445 -mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol
446 -mstrict-align -mno-strict-align -mrelocatable @gol
447 -mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol
448 -mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol
449 -mcall-aix -mcall-sysv -mcall-netbsd @gol
450 -maix-struct-return -msvr4-struct-return
451 -mabi=altivec -mabi=no-altivec @gol
452 -mprototype -mno-prototype @gol
453 -msim -mmvme -mads -myellowknife -memb -msdata @gol
454 -msdata=@var{opt} -mvxworks -mwindiss -G @var{num} -pthread}
458 -mcall-lib-mul -mfp-arg-in-fpregs -mfp-arg-in-gregs @gol
459 -mfull-fp-blocks -mhc-struct-return -min-line-mul @gol
460 -mminimum-fp-blocks -mnohc-struct-return}
464 -mabicalls -march=@var{cpu-type} -mtune=@var{cpu=type} @gol
465 -mcpu=@var{cpu-type} -membedded-data -muninit-const-in-rodata @gol
466 -membedded-pic -mfp32 -mfp64 -mfused-madd -mno-fused-madd @gol
467 -mgas -mgp32 -mgp64 @gol
468 -mgpopt -mhalf-pic -mhard-float -mint64 -mips1 @gol
469 -mips2 -mips3 -mips4 -mlong64 -mlong32 -mlong-calls -mmemcpy @gol
470 -mmips-as -mmips-tfile -mno-abicalls @gol
471 -mno-embedded-data -mno-uninit-const-in-rodata @gol
472 -mno-embedded-pic -mno-gpopt -mno-long-calls @gol
473 -mno-memcpy -mno-mips-tfile -mno-rnames -mno-stats @gol
474 -mrnames -msoft-float @gol
475 -m4650 -msingle-float -mmad @gol
476 -mstats -EL -EB -G @var{num} -nocpp @gol
477 -mabi=32 -mabi=n32 -mabi=64 -mabi=eabi @gol
478 -mfix7000 -mno-crt0 -mflush-func=@var{func} -mno-flush-func}
480 @emph{i386 and x86-64 Options}
482 -mcpu=@var{cpu-type} -march=@var{cpu-type} -mfpmath=@var{unit} @gol
483 -masm=@var{dialect} -mno-fancy-math-387 @gol
484 -mno-fp-ret-in-387 -msoft-float -msvr3-shlib @gol
485 -mno-wide-multiply -mrtd -malign-double @gol
486 -mpreferred-stack-boundary=@var{num} @gol
487 -mmmx -msse -msse2 -msse-math -m3dnow @gol
488 -mthreads -mno-align-stringops -minline-all-stringops @gol
489 -mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol
490 -m96bit-long-double -mregparm=@var{num} -momit-leaf-frame-pointer @gol
496 -march=@var{architecture-type} @gol
497 -mbig-switch -mdisable-fpregs -mdisable-indexing @gol
498 -mfast-indirect-calls -mgas -mjump-in-delay @gol
499 -mlong-load-store -mno-big-switch -mno-disable-fpregs @gol
500 -mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol
501 -mno-jump-in-delay -mno-long-load-store @gol
502 -mno-portable-runtime -mno-soft-float @gol
503 -mno-space-regs -msoft-float -mpa-risc-1-0 @gol
504 -mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime @gol
505 -mschedule=@var{cpu-type} -mspace-regs}
507 @emph{Intel 960 Options}
509 -m@var{cpu-type} -masm-compat -mclean-linkage @gol
510 -mcode-align -mcomplex-addr -mleaf-procedures @gol
511 -mic-compat -mic2.0-compat -mic3.0-compat @gol
512 -mintel-asm -mno-clean-linkage -mno-code-align @gol
513 -mno-complex-addr -mno-leaf-procedures @gol
514 -mno-old-align -mno-strict-align -mno-tail-call @gol
515 -mnumerics -mold-align -msoft-float -mstrict-align @gol
518 @emph{DEC Alpha Options}
520 -mno-fp-regs -msoft-float -malpha-as -mgas @gol
521 -mieee -mieee-with-inexact -mieee-conformant @gol
522 -mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} @gol
523 -mtrap-precision=@var{mode} -mbuild-constants @gol
524 -mcpu=@var{cpu-type} -mtune=@var{cpu-type} @gol
525 -mbwx -mmax -mfix -mcix @gol
526 -mfloat-vax -mfloat-ieee @gol
527 -mexplicit-relocs -msmall-data -mlarge-data @gol
528 -mmemory-latency=@var{time}}
530 @emph{DEC Alpha/VMS Options}
534 @emph{Clipper Options}
538 @emph{H8/300 Options}
540 -mrelax -mh -ms -mint32 -malign-300}
544 -m1 -m2 -m3 -m3e @gol
545 -m4-nofpu -m4-single-only -m4-single -m4 @gol
546 -m5-64media -m5-64media-nofpu @gol
547 -m5-32media -m5-32media-nofpu @gol
548 -m5-compact -m5-compact-nofpu @gol
549 -mb -ml -mdalign -mrelax @gol
550 -mbigtable -mfmovd -mhitachi -mnomacsave @gol
551 -mieee -misize -mpadstruct -mspace @gol
552 -mprefergot -musermode}
554 @emph{System V Options}
556 -Qy -Qn -YP,@var{paths} -Ym,@var{dir}}
561 -mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text-section} @gol
562 -mdata=@var{data-section} -mrodata=@var{readonly-data-section}}
564 @emph{TMS320C3x/C4x Options}
566 -mcpu=@var{cpu} -mbig -msmall -mregparm -mmemparm @gol
567 -mfast-fix -mmpyi -mbk -mti -mdp-isr-reload @gol
568 -mrpts=@var{count} -mrptb -mdb -mloop-unsigned @gol
569 -mparallel-insns -mparallel-mpy -mpreserve-float}
573 -mlong-calls -mno-long-calls -mep -mno-ep @gol
574 -mprolog-function -mno-prolog-function -mspace @gol
575 -mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol
580 -m32032 -m32332 -m32532 -m32081 -m32381 @gol
581 -mmult-add -mnomult-add -msoft-float -mrtd -mnortd @gol
582 -mregparam -mnoregparam -msb -mnosb @gol
583 -mbitfield -mnobitfield -mhimem -mnohimem}
587 -mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts @gol
588 -mcall-prologues -mno-tablejump -mtiny-stack}
592 -mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol
593 -mno-relax-immediates -mwide-bitfields -mno-wide-bitfields @gol
594 -m4byte-functions -mno-4byte-functions -mcallgraph-data @gol
595 -mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim @gol
596 -mlittle-endian -mbig-endian -m210 -m340 -mstack-increment}
600 -mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol
601 -mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol
602 -melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol
603 -mno-base-addresses -msingle-exit -mno-single-exit}
607 -mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol
608 -mvolatile-asm-stop -mb-step -mregister-names -mno-sdata @gol
609 -mconstant-gp -mauto-pic -minline-divide-min-latency @gol
610 -minline-divide-max-throughput -mno-dwarf2-asm @gol
611 -mfixed-range=@var{register-range}}
615 -mextmem -mextmemory -monchip -mno-asm-optimize -masm-optimize @gol
616 -mbranch-cost=@var{n} -mcond-exec=@var{n}}
618 @emph{S/390 and zSeries Options}
620 -mhard-float -msoft-float -mbackchain -mno-backchain @gol
621 -msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol
622 -m64 -m31 -mdebug -mno-debug}
626 -mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol
627 -mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol
628 -metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol
629 -mstack-align -mdata-align -mconst-align @gol
630 -m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol
631 -melf -maout -melinux -mlinux -sim -sim2}
633 @emph{PDP-11 Options}
635 -mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol
636 -mbcopy -mbcopy-builtin -mint32 -mno-int16 @gol
637 -mint16 -mno-int32 -mfloat32 -mno-float64 @gol
638 -mfloat64 -mno-float32 -mabshi -mno-abshi @gol
639 -mbranch-expensive -mbranch-cheap @gol
640 -msplit -mno-split -munix-asm -mdec-asm}
642 @emph{Xstormy16 Options}
646 @emph{Xtensa Options}
648 -mbig-endian -mlittle-endian @gol
649 -mdensity -mno-density @gol
650 -mmac16 -mno-mac16 @gol
651 -mmul16 -mno-mul16 @gol
652 -mmul32 -mno-mul32 @gol
654 -mminmax -mno-minmax @gol
655 -msext -mno-sext @gol
656 -mbooleans -mno-booleans @gol
657 -mhard-float -msoft-float @gol
658 -mfused-madd -mno-fused-madd @gol
659 -mserialize-volatile -mno-serialize-volatile @gol
660 -mtext-section-literals -mno-text-section-literals @gol
661 -mtarget-align -mno-target-align @gol
662 -mlongcalls -mno-longcalls}
664 @item Code Generation Options
665 @xref{Code Gen Options,,Options for Code Generation Conventions}.
667 -fcall-saved-@var{reg} -fcall-used-@var{reg} @gol
668 -ffixed-@var{reg} -fexceptions @gol
669 -fnon-call-exceptions -funwind-tables @gol
670 -fasynchronous-unwind-tables @gol
671 -finhibit-size-directive -finstrument-functions @gol
672 -fno-common -fno-ident -fno-gnu-linker @gol
673 -fpcc-struct-return -fpic -fPIC @gol
674 -freg-struct-return -fshared-data -fshort-enums @gol
675 -fshort-double -fvolatile @gol
676 -fvolatile-global -fvolatile-static @gol
677 -fverbose-asm -fpack-struct -fstack-check @gol
678 -fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
679 -fargument-alias -fargument-noalias @gol
680 -fargument-noalias-global -fleading-underscore -ftls-model=@var{model}}
684 * Overall Options:: Controlling the kind of output:
685 an executable, object files, assembler files,
686 or preprocessed source.
687 * C Dialect Options:: Controlling the variant of C language compiled.
688 * C++ Dialect Options:: Variations on C++.
689 * Objective-C Dialect Options:: Variations on Objective-C.
690 * Language Independent Options:: Controlling how diagnostics should be
692 * Warning Options:: How picky should the compiler be?
693 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
694 * Optimize Options:: How much optimization?
695 * Preprocessor Options:: Controlling header files and macro definitions.
696 Also, getting dependency information for Make.
697 * Assembler Options:: Passing options to the assembler.
698 * Link Options:: Specifying libraries and so on.
699 * Directory Options:: Where to find header files and libraries.
700 Where to find the compiler executable files.
701 * Spec Files:: How to pass switches to sub-processes.
702 * Target Options:: Running a cross-compiler, or an old version of GCC.
705 @node Overall Options
706 @section Options Controlling the Kind of Output
708 Compilation can involve up to four stages: preprocessing, compilation
709 proper, assembly and linking, always in that order. The first three
710 stages apply to an individual source file, and end by producing an
711 object file; linking combines all the object files (those newly
712 compiled, and those specified as input) into an executable file.
714 @cindex file name suffix
715 For any given input file, the file name suffix determines what kind of
720 C source code which must be preprocessed.
723 C source code which should not be preprocessed.
726 C++ source code which should not be preprocessed.
729 Objective-C source code. Note that you must link with the library
730 @file{libobjc.a} to make an Objective-C program work.
733 Objective-C source code which should not be preprocessed.
736 C header file (not to be compiled or linked).
740 @itemx @var{file}.cxx
741 @itemx @var{file}.cpp
742 @itemx @var{file}.c++
744 C++ source code which must be preprocessed. Note that in @samp{.cxx},
745 the last two letters must both be literally @samp{x}. Likewise,
746 @samp{.C} refers to a literal capital C@.
749 @itemx @var{file}.for
750 @itemx @var{file}.FOR
751 Fortran source code which should not be preprocessed.
754 @itemx @var{file}.fpp
755 @itemx @var{file}.FPP
756 Fortran source code which must be preprocessed (with the traditional
760 Fortran source code which must be preprocessed with a RATFOR
761 preprocessor (not included with GCC)@.
763 @xref{Overall Options,,Options Controlling the Kind of Output, g77,
764 Using and Porting GNU Fortran}, for more details of the handling of
767 @c FIXME: Descriptions of Java file types.
774 Ada source code file which contains a library unit declaration (a
775 declaration of a package, subprogram, or generic, or a generic
776 instantiation), or a library unit renaming declaration (a package,
777 generic, or subprogram renaming declaration). Such files are also
780 @itemx @var{file}.adb
781 Ada source code file containing a library unit body (a subprogram or
782 package body). Such files are also called @dfn{bodies}.
784 @c GCC also knows about some suffixes for languages not yet included:
793 Assembler code which must be preprocessed.
796 An object file to be fed straight into linking.
797 Any file name with no recognized suffix is treated this way.
801 You can specify the input language explicitly with the @option{-x} option:
804 @item -x @var{language}
805 Specify explicitly the @var{language} for the following input files
806 (rather than letting the compiler choose a default based on the file
807 name suffix). This option applies to all following input files until
808 the next @option{-x} option. Possible values for @var{language} are:
810 c c-header cpp-output
812 objective-c objc-cpp-output
813 assembler assembler-with-cpp
815 f77 f77-cpp-input ratfor
821 Turn off any specification of a language, so that subsequent files are
822 handled according to their file name suffixes (as they are if @option{-x}
823 has not been used at all).
825 @item -pass-exit-codes
826 @opindex pass-exit-codes
827 Normally the @command{gcc} program will exit with the code of 1 if any
828 phase of the compiler returns a non-success return code. If you specify
829 @option{-pass-exit-codes}, the @command{gcc} program will instead return with
830 numerically highest error produced by any phase that returned an error
834 If you only want some of the stages of compilation, you can use
835 @option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
836 one of the options @option{-c}, @option{-S}, or @option{-E} to say where
837 @command{gcc} is to stop. Note that some combinations (for example,
838 @samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
843 Compile or assemble the source files, but do not link. The linking
844 stage simply is not done. The ultimate output is in the form of an
845 object file for each source file.
847 By default, the object file name for a source file is made by replacing
848 the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
850 Unrecognized input files, not requiring compilation or assembly, are
855 Stop after the stage of compilation proper; do not assemble. The output
856 is in the form of an assembler code file for each non-assembler input
859 By default, the assembler file name for a source file is made by
860 replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
862 Input files that don't require compilation are ignored.
866 Stop after the preprocessing stage; do not run the compiler proper. The
867 output is in the form of preprocessed source code, which is sent to the
870 Input files which don't require preprocessing are ignored.
872 @cindex output file option
875 Place output in file @var{file}. This applies regardless to whatever
876 sort of output is being produced, whether it be an executable file,
877 an object file, an assembler file or preprocessed C code.
879 Since only one output file can be specified, it does not make sense to
880 use @option{-o} when compiling more than one input file, unless you are
881 producing an executable file as output.
883 If @option{-o} is not specified, the default is to put an executable file
884 in @file{a.out}, the object file for @file{@var{source}.@var{suffix}} in
885 @file{@var{source}.o}, its assembler file in @file{@var{source}.s}, and
886 all preprocessed C source on standard output.
890 Print (on standard error output) the commands executed to run the stages
891 of compilation. Also print the version number of the compiler driver
892 program and of the preprocessor and the compiler proper.
896 Like @option{-v} except the commands are not executed and all command
897 arguments are quoted. This is useful for shell scripts to capture the
898 driver-generated command lines.
902 Use pipes rather than temporary files for communication between the
903 various stages of compilation. This fails to work on some systems where
904 the assembler is unable to read from a pipe; but the GNU assembler has
909 Print (on the standard output) a description of the command line options
910 understood by @command{gcc}. If the @option{-v} option is also specified
911 then @option{--help} will also be passed on to the various processes
912 invoked by @command{gcc}, so that they can display the command line options
913 they accept. If the @option{-W} option is also specified then command
914 line options which have no documentation associated with them will also
919 Print (on the standard output) a description of target specific command
920 line options for each tool.
924 @section Compiling C++ Programs
926 @cindex suffixes for C++ source
927 @cindex C++ source file suffixes
928 C++ source files conventionally use one of the suffixes @samp{.C},
929 @samp{.cc}, @samp{.cpp}, @samp{.c++}, @samp{.cp}, or @samp{.cxx};
930 preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes
931 files with these names and compiles them as C++ programs even if you
932 call the compiler the same way as for compiling C programs (usually with
933 the name @command{gcc}).
937 However, C++ programs often require class libraries as well as a
938 compiler that understands the C++ language---and under some
939 circumstances, you might want to compile programs from standard input,
940 or otherwise without a suffix that flags them as C++ programs.
941 @command{g++} is a program that calls GCC with the default language
942 set to C++, and automatically specifies linking against the C++
943 library. On many systems, @command{g++} is also
944 installed with the name @command{c++}.
946 @cindex invoking @command{g++}
947 When you compile C++ programs, you may specify many of the same
948 command-line options that you use for compiling programs in any
949 language; or command-line options meaningful for C and related
950 languages; or options that are meaningful only for C++ programs.
951 @xref{C Dialect Options,,Options Controlling C Dialect}, for
952 explanations of options for languages related to C@.
953 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
954 explanations of options that are meaningful only for C++ programs.
956 @node C Dialect Options
957 @section Options Controlling C Dialect
958 @cindex dialect options
959 @cindex language dialect options
960 @cindex options, dialect
962 The following options control the dialect of C (or languages derived
963 from C, such as C++ and Objective-C) that the compiler accepts:
970 In C mode, support all ISO C89 programs. In C++ mode,
971 remove GNU extensions that conflict with ISO C++.
973 This turns off certain features of GCC that are incompatible with ISO
974 C89 (when compiling C code), or of standard C++ (when compiling C++ code),
975 such as the @code{asm} and @code{typeof} keywords, and
976 predefined macros such as @code{unix} and @code{vax} that identify the
977 type of system you are using. It also enables the undesirable and
978 rarely used ISO trigraph feature. For the C compiler,
979 it disables recognition of C++ style @samp{//} comments as well as
980 the @code{inline} keyword.
982 The alternate keywords @code{__asm__}, @code{__extension__},
983 @code{__inline__} and @code{__typeof__} continue to work despite
984 @option{-ansi}. You would not want to use them in an ISO C program, of
985 course, but it is useful to put them in header files that might be included
986 in compilations done with @option{-ansi}. Alternate predefined macros
987 such as @code{__unix__} and @code{__vax__} are also available, with or
988 without @option{-ansi}.
990 The @option{-ansi} option does not cause non-ISO programs to be
991 rejected gratuitously. For that, @option{-pedantic} is required in
992 addition to @option{-ansi}. @xref{Warning Options}.
994 The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
995 option is used. Some header files may notice this macro and refrain
996 from declaring certain functions or defining certain macros that the
997 ISO standard doesn't call for; this is to avoid interfering with any
998 programs that might use these names for other things.
1000 Functions which would normally be built in but do not have semantics
1001 defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
1002 functions with @option{-ansi} is used. @xref{Other Builtins,,Other
1003 built-in functions provided by GCC}, for details of the functions
1008 Determine the language standard. This option is currently only
1009 supported when compiling C@. A value for this option must be provided;
1015 ISO C89 (same as @option{-ansi}).
1017 @item iso9899:199409
1018 ISO C89 as modified in amendment 1.
1024 ISO C99. Note that this standard is not yet fully supported; see
1025 @w{@uref{http://gcc.gnu.org/c99status.html}} for more information. The
1026 names @samp{c9x} and @samp{iso9899:199x} are deprecated.
1029 Default, ISO C89 plus GNU extensions (including some C99 features).
1033 ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC,
1034 this will become the default. The name @samp{gnu9x} is deprecated.
1038 Even when this option is not specified, you can still use some of the
1039 features of newer standards in so far as they do not conflict with
1040 previous C standards. For example, you may use @code{__restrict__} even
1041 when @option{-std=c99} is not specified.
1043 The @option{-std} options specifying some version of ISO C have the same
1044 effects as @option{-ansi}, except that features that were not in ISO C89
1045 but are in the specified version (for example, @samp{//} comments and
1046 the @code{inline} keyword in ISO C99) are not disabled.
1048 @xref{Standards,,Language Standards Supported by GCC}, for details of
1049 these standard versions.
1051 @item -aux-info @var{filename}
1053 Output to the given filename prototyped declarations for all functions
1054 declared and/or defined in a translation unit, including those in header
1055 files. This option is silently ignored in any language other than C@.
1057 Besides declarations, the file indicates, in comments, the origin of
1058 each declaration (source file and line), whether the declaration was
1059 implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
1060 @samp{O} for old, respectively, in the first character after the line
1061 number and the colon), and whether it came from a declaration or a
1062 definition (@samp{C} or @samp{F}, respectively, in the following
1063 character). In the case of function definitions, a K&R-style list of
1064 arguments followed by their declarations is also provided, inside
1065 comments, after the declaration.
1069 Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1070 keyword, so that code can use these words as identifiers. You can use
1071 the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
1072 instead. @option{-ansi} implies @option{-fno-asm}.
1074 In C++, this switch only affects the @code{typeof} keyword, since
1075 @code{asm} and @code{inline} are standard keywords. You may want to
1076 use the @option{-fno-gnu-keywords} flag instead, which has the same
1077 effect. In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
1078 switch only affects the @code{asm} and @code{typeof} keywords, since
1079 @code{inline} is a standard keyword in ISO C99.
1082 @itemx -fno-builtin-@var{function} @r{(C and Objective-C only)}
1083 @opindex fno-builtin
1084 @cindex built-in functions
1085 Don't recognize built-in functions that do not begin with
1086 @samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in
1087 functions provided by GCC}, for details of the functions affected,
1088 including those which are not built-in functions when @option{-ansi} or
1089 @option{-std} options for strict ISO C conformance are used because they
1090 do not have an ISO standard meaning.
1092 GCC normally generates special code to handle certain built-in functions
1093 more efficiently; for instance, calls to @code{alloca} may become single
1094 instructions that adjust the stack directly, and calls to @code{memcpy}
1095 may become inline copy loops. The resulting code is often both smaller
1096 and faster, but since the function calls no longer appear as such, you
1097 cannot set a breakpoint on those calls, nor can you change the behavior
1098 of the functions by linking with a different library.
1100 In C++, @option{-fno-builtin} is always in effect. The @option{-fbuiltin}
1101 option has no effect. Therefore, in C++, the only way to get the
1102 optimization benefits of built-in functions is to call the function
1103 using the @samp{__builtin_} prefix. The GNU C++ Standard Library uses
1104 built-in functions to implement many functions (like
1105 @code{std::strchr}), so that you automatically get efficient code.
1107 With the @option{-fno-builtin-@var{function}} option, not available
1108 when compiling C++, only the built-in function @var{function} is
1109 disabled. @var{function} must not begin with @samp{__builtin_}. If a
1110 function is named this is not built-in in this version of GCC, this
1111 option is ignored. There is no corresponding
1112 @option{-fbuiltin-@var{function}} option; if you wish to enable
1113 built-in functions selectively when using @option{-fno-builtin} or
1114 @option{-ffreestanding}, you may define macros such as:
1117 #define abs(n) __builtin_abs ((n))
1118 #define strcpy(d, s) __builtin_strcpy ((d), (s))
1123 @cindex hosted environment
1125 Assert that compilation takes place in a hosted environment. This implies
1126 @option{-fbuiltin}. A hosted environment is one in which the
1127 entire standard library is available, and in which @code{main} has a return
1128 type of @code{int}. Examples are nearly everything except a kernel.
1129 This is equivalent to @option{-fno-freestanding}.
1131 @item -ffreestanding
1132 @opindex ffreestanding
1133 @cindex hosted environment
1135 Assert that compilation takes place in a freestanding environment. This
1136 implies @option{-fno-builtin}. A freestanding environment
1137 is one in which the standard library may not exist, and program startup may
1138 not necessarily be at @code{main}. The most obvious example is an OS kernel.
1139 This is equivalent to @option{-fno-hosted}.
1141 @xref{Standards,,Language Standards Supported by GCC}, for details of
1142 freestanding and hosted environments.
1144 @item -fms-extensions
1145 @opindex fms-extensions
1146 Accept some non-standard constructs used in Microsoft header files.
1150 Support ISO C trigraphs. The @option{-ansi} option (and @option{-std}
1151 options for strict ISO C conformance) implies @option{-trigraphs}.
1153 @cindex traditional C language
1154 @cindex C language, traditional
1156 @itemx -traditional-cpp
1157 @opindex traditional-cpp
1158 @opindex traditional
1159 Formerly, these options caused GCC to attempt to emulate a pre-standard
1160 C compiler. They are now only supported with the @option{-E} switch.
1161 The preprocessor continues to support a pre-standard mode. See the GNU
1162 CPP manual for details.
1164 @item -fcond-mismatch
1165 @opindex fcond-mismatch
1166 Allow conditional expressions with mismatched types in the second and
1167 third arguments. The value of such an expression is void. This option
1168 is not supported for C++.
1170 @item -funsigned-char
1171 @opindex funsigned-char
1172 Let the type @code{char} be unsigned, like @code{unsigned char}.
1174 Each kind of machine has a default for what @code{char} should
1175 be. It is either like @code{unsigned char} by default or like
1176 @code{signed char} by default.
1178 Ideally, a portable program should always use @code{signed char} or
1179 @code{unsigned char} when it depends on the signedness of an object.
1180 But many programs have been written to use plain @code{char} and
1181 expect it to be signed, or expect it to be unsigned, depending on the
1182 machines they were written for. This option, and its inverse, let you
1183 make such a program work with the opposite default.
1185 The type @code{char} is always a distinct type from each of
1186 @code{signed char} or @code{unsigned char}, even though its behavior
1187 is always just like one of those two.
1190 @opindex fsigned-char
1191 Let the type @code{char} be signed, like @code{signed char}.
1193 Note that this is equivalent to @option{-fno-unsigned-char}, which is
1194 the negative form of @option{-funsigned-char}. Likewise, the option
1195 @option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
1197 @item -fsigned-bitfields
1198 @itemx -funsigned-bitfields
1199 @itemx -fno-signed-bitfields
1200 @itemx -fno-unsigned-bitfields
1201 @opindex fsigned-bitfields
1202 @opindex funsigned-bitfields
1203 @opindex fno-signed-bitfields
1204 @opindex fno-unsigned-bitfields
1205 These options control whether a bit-field is signed or unsigned, when the
1206 declaration does not use either @code{signed} or @code{unsigned}. By
1207 default, such a bit-field is signed, because this is consistent: the
1208 basic integer types such as @code{int} are signed types.
1210 @item -fwritable-strings
1211 @opindex fwritable-strings
1212 Store string constants in the writable data segment and don't uniquize
1213 them. This is for compatibility with old programs which assume they can
1214 write into string constants.
1216 Writing into string constants is a very bad idea; ``constants'' should
1220 @opindex fshort-wchar
1221 Override the underlying type for @samp{wchar_t} to be @samp{short
1222 unsigned int} instead of the default for the target. This option is
1223 useful for building programs to run under WINE@.
1226 @node C++ Dialect Options
1227 @section Options Controlling C++ Dialect
1229 @cindex compiler options, C++
1230 @cindex C++ options, command line
1231 @cindex options, C++
1232 This section describes the command-line options that are only meaningful
1233 for C++ programs; but you can also use most of the GNU compiler options
1234 regardless of what language your program is in. For example, you
1235 might compile a file @code{firstClass.C} like this:
1238 g++ -g -frepo -O -c firstClass.C
1242 In this example, only @option{-frepo} is an option meant
1243 only for C++ programs; you can use the other options with any
1244 language supported by GCC@.
1246 Here is a list of options that are @emph{only} for compiling C++ programs:
1249 @item -fno-access-control
1250 @opindex fno-access-control
1251 Turn off all access checking. This switch is mainly useful for working
1252 around bugs in the access control code.
1256 Check that the pointer returned by @code{operator new} is non-null
1257 before attempting to modify the storage allocated. The current Working
1258 Paper requires that @code{operator new} never return a null pointer, so
1259 this check is normally unnecessary.
1261 An alternative to using this option is to specify that your
1262 @code{operator new} does not throw any exceptions; if you declare it
1263 @samp{throw()}, G++ will check the return value. See also @samp{new
1266 @item -fconserve-space
1267 @opindex fconserve-space
1268 Put uninitialized or runtime-initialized global variables into the
1269 common segment, as C does. This saves space in the executable at the
1270 cost of not diagnosing duplicate definitions. If you compile with this
1271 flag and your program mysteriously crashes after @code{main()} has
1272 completed, you may have an object that is being destroyed twice because
1273 two definitions were merged.
1275 This option is no longer useful on most targets, now that support has
1276 been added for putting variables into BSS without making them common.
1278 @item -fno-const-strings
1279 @opindex fno-const-strings
1280 Give string constants type @code{char *} instead of type @code{const
1281 char *}. By default, G++ uses type @code{const char *} as required by
1282 the standard. Even if you use @option{-fno-const-strings}, you cannot
1283 actually modify the value of a string constant, unless you also use
1284 @option{-fwritable-strings}.
1286 This option might be removed in a future release of G++. For maximum
1287 portability, you should structure your code so that it works with
1288 string constants that have type @code{const char *}.
1290 @item -fdollars-in-identifiers
1291 @opindex fdollars-in-identifiers
1292 Accept @samp{$} in identifiers. You can also explicitly prohibit use of
1293 @samp{$} with the option @option{-fno-dollars-in-identifiers}. (GNU C allows
1294 @samp{$} by default on most target systems, but there are a few exceptions.)
1295 Traditional C allowed the character @samp{$} to form part of
1296 identifiers. However, ISO C and C++ forbid @samp{$} in identifiers.
1298 @item -fno-elide-constructors
1299 @opindex fno-elide-constructors
1300 The C++ standard allows an implementation to omit creating a temporary
1301 which is only used to initialize another object of the same type.
1302 Specifying this option disables that optimization, and forces G++ to
1303 call the copy constructor in all cases.
1305 @item -fno-enforce-eh-specs
1306 @opindex fno-enforce-eh-specs
1307 Don't check for violation of exception specifications at runtime. This
1308 option violates the C++ standard, but may be useful for reducing code
1309 size in production builds, much like defining @samp{NDEBUG}. The compiler
1310 will still optimize based on the exception specifications.
1312 @item -fexternal-templates
1313 @opindex fexternal-templates
1315 Cause @samp{#pragma interface} and @samp{implementation} to apply to
1316 template instantiation; template instances are emitted or not according
1317 to the location of the template definition. @xref{Template
1318 Instantiation}, for more information.
1320 This option is deprecated.
1322 @item -falt-external-templates
1323 @opindex falt-external-templates
1324 Similar to @option{-fexternal-templates}, but template instances are
1325 emitted or not according to the place where they are first instantiated.
1326 @xref{Template Instantiation}, for more information.
1328 This option is deprecated.
1331 @itemx -fno-for-scope
1333 @opindex fno-for-scope
1334 If @option{-ffor-scope} is specified, the scope of variables declared in
1335 a @i{for-init-statement} is limited to the @samp{for} loop itself,
1336 as specified by the C++ standard.
1337 If @option{-fno-for-scope} is specified, the scope of variables declared in
1338 a @i{for-init-statement} extends to the end of the enclosing scope,
1339 as was the case in old versions of G++, and other (traditional)
1340 implementations of C++.
1342 The default if neither flag is given to follow the standard,
1343 but to allow and give a warning for old-style code that would
1344 otherwise be invalid, or have different behavior.
1346 @item -fno-gnu-keywords
1347 @opindex fno-gnu-keywords
1348 Do not recognize @code{typeof} as a keyword, so that code can use this
1349 word as an identifier. You can use the keyword @code{__typeof__} instead.
1350 @option{-ansi} implies @option{-fno-gnu-keywords}.
1352 @item -fno-implicit-templates
1353 @opindex fno-implicit-templates
1354 Never emit code for non-inline templates which are instantiated
1355 implicitly (i.e.@: by use); only emit code for explicit instantiations.
1356 @xref{Template Instantiation}, for more information.
1358 @item -fno-implicit-inline-templates
1359 @opindex fno-implicit-inline-templates
1360 Don't emit code for implicit instantiations of inline templates, either.
1361 The default is to handle inlines differently so that compiles with and
1362 without optimization will need the same set of explicit instantiations.
1364 @item -fno-implement-inlines
1365 @opindex fno-implement-inlines
1366 To save space, do not emit out-of-line copies of inline functions
1367 controlled by @samp{#pragma implementation}. This will cause linker
1368 errors if these functions are not inlined everywhere they are called.
1370 @item -fms-extensions
1371 @opindex fms-extensions
1372 Disable pedantic warnings about constructs used in MFC, such as implicit
1373 int and getting a pointer to member function via non-standard syntax.
1375 @item -fno-nonansi-builtins
1376 @opindex fno-nonansi-builtins
1377 Disable built-in declarations of functions that are not mandated by
1378 ANSI/ISO C@. These include @code{ffs}, @code{alloca}, @code{_exit},
1379 @code{index}, @code{bzero}, @code{conjf}, and other related functions.
1381 @item -fno-operator-names
1382 @opindex fno-operator-names
1383 Do not treat the operator name keywords @code{and}, @code{bitand},
1384 @code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1385 synonyms as keywords.
1387 @item -fno-optional-diags
1388 @opindex fno-optional-diags
1389 Disable diagnostics that the standard says a compiler does not need to
1390 issue. Currently, the only such diagnostic issued by G++ is the one for
1391 a name having multiple meanings within a class.
1394 @opindex fpermissive
1395 Downgrade messages about nonconformant code from errors to warnings. By
1396 default, G++ effectively sets @option{-pedantic-errors} without
1397 @option{-pedantic}; this option reverses that. This behavior and this
1398 option are superseded by @option{-pedantic}, which works as it does for GNU C@.
1402 Enable automatic template instantiation at link time. This option also
1403 implies @option{-fno-implicit-templates}. @xref{Template
1404 Instantiation}, for more information.
1408 Disable generation of information about every class with virtual
1409 functions for use by the C++ runtime type identification features
1410 (@samp{dynamic_cast} and @samp{typeid}). If you don't use those parts
1411 of the language, you can save some space by using this flag. Note that
1412 exception handling uses the same information, but it will generate it as
1417 Emit statistics about front-end processing at the end of the compilation.
1418 This information is generally only useful to the G++ development team.
1420 @item -ftemplate-depth-@var{n}
1421 @opindex ftemplate-depth
1422 Set the maximum instantiation depth for template classes to @var{n}.
1423 A limit on the template instantiation depth is needed to detect
1424 endless recursions during template class instantiation. ANSI/ISO C++
1425 conforming programs must not rely on a maximum depth greater than 17.
1427 @item -fuse-cxa-atexit
1428 @opindex fuse-cxa-atexit
1429 Register destructors for objects with static storage duration with the
1430 @code{__cxa_atexit} function rather than the @code{atexit} function.
1431 This option is required for fully standards-compliant handling of static
1432 destructors, but will only work if your C library supports
1433 @code{__cxa_atexit}.
1437 Emit special relocations for vtables and virtual function references
1438 so that the linker can identify unused virtual functions and zero out
1439 vtable slots that refer to them. This is most useful with
1440 @option{-ffunction-sections} and @option{-Wl,--gc-sections}, in order to
1441 also discard the functions themselves.
1443 This optimization requires GNU as and GNU ld. Not all systems support
1444 this option. @option{-Wl,--gc-sections} is ignored without @option{-static}.
1448 Do not use weak symbol support, even if it is provided by the linker.
1449 By default, G++ will use weak symbols if they are available. This
1450 option exists only for testing, and should not be used by end-users;
1451 it will result in inferior code and has no benefits. This option may
1452 be removed in a future release of G++.
1456 Do not search for header files in the standard directories specific to
1457 C++, but do still search the other standard directories. (This option
1458 is used when building the C++ library.)
1461 In addition, these optimization, warning, and code generation options
1462 have meanings only for C++ programs:
1465 @item -fno-default-inline
1466 @opindex fno-default-inline
1467 Do not assume @samp{inline} for functions defined inside a class scope.
1468 @xref{Optimize Options,,Options That Control Optimization}. Note that these
1469 functions will have linkage like inline functions; they just won't be
1472 @item -Wctor-dtor-privacy @r{(C++ only)}
1473 @opindex Wctor-dtor-privacy
1474 Warn when a class seems unusable, because all the constructors or
1475 destructors in a class are private and the class has no friends or
1476 public static member functions.
1478 @item -Wnon-virtual-dtor @r{(C++ only)}
1479 @opindex Wnon-virtual-dtor
1480 Warn when a class declares a non-virtual destructor that should probably
1481 be virtual, because it looks like the class will be used polymorphically.
1483 @item -Wreorder @r{(C++ only)}
1485 @cindex reordering, warning
1486 @cindex warning for reordering of member initializers
1487 Warn when the order of member initializers given in the code does not
1488 match the order in which they must be executed. For instance:
1494 A(): j (0), i (1) @{ @}
1498 Here the compiler will warn that the member initializers for @samp{i}
1499 and @samp{j} will be rearranged to match the declaration order of the
1503 The following @option{-W@dots{}} options are not affected by @option{-Wall}.
1506 @item -Weffc++ @r{(C++ only)}
1508 Warn about violations of the following style guidelines from Scott Meyers'
1509 @cite{Effective C++} book:
1513 Item 11: Define a copy constructor and an assignment operator for classes
1514 with dynamically allocated memory.
1517 Item 12: Prefer initialization to assignment in constructors.
1520 Item 14: Make destructors virtual in base classes.
1523 Item 15: Have @code{operator=} return a reference to @code{*this}.
1526 Item 23: Don't try to return a reference when you must return an object.
1530 and about violations of the following style guidelines from Scott Meyers'
1531 @cite{More Effective C++} book:
1535 Item 6: Distinguish between prefix and postfix forms of increment and
1536 decrement operators.
1539 Item 7: Never overload @code{&&}, @code{||}, or @code{,}.
1543 If you use this option, you should be aware that the standard library
1544 headers do not obey all of these guidelines; you can use @samp{grep -v}
1545 to filter out those warnings.
1547 @item -Wno-deprecated @r{(C++ only)}
1548 @opindex Wno-deprecated
1549 Do not warn about usage of deprecated features. @xref{Deprecated Features}.
1551 @item -Wno-non-template-friend @r{(C++ only)}
1552 @opindex Wno-non-template-friend
1553 Disable warnings when non-templatized friend functions are declared
1554 within a template. With the advent of explicit template specification
1555 support in G++, if the name of the friend is an unqualified-id (i.e.,
1556 @samp{friend foo(int)}), the C++ language specification demands that the
1557 friend declare or define an ordinary, nontemplate function. (Section
1558 14.5.3). Before G++ implemented explicit specification, unqualified-ids
1559 could be interpreted as a particular specialization of a templatized
1560 function. Because this non-conforming behavior is no longer the default
1561 behavior for G++, @option{-Wnon-template-friend} allows the compiler to
1562 check existing code for potential trouble spots, and is on by default.
1563 This new compiler behavior can be turned off with
1564 @option{-Wno-non-template-friend} which keeps the conformant compiler code
1565 but disables the helpful warning.
1567 @item -Wold-style-cast @r{(C++ only)}
1568 @opindex Wold-style-cast
1569 Warn if an old-style (C-style) cast to a non-void type is used within
1570 a C++ program. The new-style casts (@samp{static_cast},
1571 @samp{reinterpret_cast}, and @samp{const_cast}) are less vulnerable to
1572 unintended effects, and much easier to grep for.
1574 @item -Woverloaded-virtual @r{(C++ only)}
1575 @opindex Woverloaded-virtual
1576 @cindex overloaded virtual fn, warning
1577 @cindex warning for overloaded virtual fn
1578 Warn when a function declaration hides virtual functions from a
1579 base class. For example, in:
1586 struct B: public A @{
1591 the @code{A} class version of @code{f} is hidden in @code{B}, and code
1599 will fail to compile.
1601 @item -Wno-pmf-conversions @r{(C++ only)}
1602 @opindex Wno-pmf-conversions
1603 Disable the diagnostic for converting a bound pointer to member function
1606 @item -Wsign-promo @r{(C++ only)}
1607 @opindex Wsign-promo
1608 Warn when overload resolution chooses a promotion from unsigned or
1609 enumeral type to a signed type over a conversion to an unsigned type of
1610 the same size. Previous versions of G++ would try to preserve
1611 unsignedness, but the standard mandates the current behavior.
1613 @item -Wsynth @r{(C++ only)}
1615 @cindex warning for synthesized methods
1616 @cindex synthesized methods, warning
1617 Warn when G++'s synthesis behavior does not match that of cfront. For
1623 A& operator = (int);
1633 In this example, G++ will synthesize a default @samp{A& operator =
1634 (const A&);}, while cfront will use the user-defined @samp{operator =}.
1637 @node Objective-C Dialect Options
1638 @section Options Controlling Objective-C Dialect
1640 @cindex compiler options, Objective-C
1641 @cindex Objective-C options, command line
1642 @cindex options, Objective-C
1643 This section describes the command-line options that are only meaningful
1644 for Objective-C programs; but you can also use most of the GNU compiler
1645 options regardless of what language your program is in. For example,
1646 you might compile a file @code{some_class.m} like this:
1649 gcc -g -fgnu-runtime -O -c some_class.m
1653 In this example, only @option{-fgnu-runtime} is an option meant only for
1654 Objective-C programs; you can use the other options with any language
1657 Here is a list of options that are @emph{only} for compiling Objective-C
1661 @item -fconstant-string-class=@var{class-name}
1662 @opindex fconstant-string-class
1663 Use @var{class-name} as the name of the class to instantiate for each
1664 literal string specified with the syntax @code{@@"@dots{}"}. The default
1665 class name is @code{NXConstantString}.
1668 @opindex fgnu-runtime
1669 Generate object code compatible with the standard GNU Objective-C
1670 runtime. This is the default for most types of systems.
1672 @item -fnext-runtime
1673 @opindex fnext-runtime
1674 Generate output compatible with the NeXT runtime. This is the default
1675 for NeXT-based systems, including Darwin and Mac OS X@.
1679 Dump interface declarations for all classes seen in the source file to a
1680 file named @file{@var{sourcename}.decl}.
1683 @opindex Wno-protocol
1684 Do not warn if methods required by a protocol are not implemented
1685 in the class adopting it.
1689 Warn if a selector has multiple methods of different types defined.
1691 @c not documented because only avail via -Wp
1692 @c @item -print-objc-runtime-info
1696 @node Language Independent Options
1697 @section Options to Control Diagnostic Messages Formatting
1698 @cindex options to control diagnostics formatting
1699 @cindex diagnostic messages
1700 @cindex message formatting
1702 Traditionally, diagnostic messages have been formatted irrespective of
1703 the output device's aspect (e.g.@: its width, @dots{}). The options described
1704 below can be used to control the diagnostic messages formatting
1705 algorithm, e.g.@: how many characters per line, how often source location
1706 information should be reported. Right now, only the C++ front end can
1707 honor these options. However it is expected, in the near future, that
1708 the remaining front ends would be able to digest them correctly.
1711 @item -fmessage-length=@var{n}
1712 @opindex fmessage-length
1713 Try to format error messages so that they fit on lines of about @var{n}
1714 characters. The default is 72 characters for @command{g++} and 0 for the rest of
1715 the front ends supported by GCC@. If @var{n} is zero, then no
1716 line-wrapping will be done; each error message will appear on a single
1719 @opindex fdiagnostics-show-location
1720 @item -fdiagnostics-show-location=once
1721 Only meaningful in line-wrapping mode. Instructs the diagnostic messages
1722 reporter to emit @emph{once} source location information; that is, in
1723 case the message is too long to fit on a single physical line and has to
1724 be wrapped, the source location won't be emitted (as prefix) again,
1725 over and over, in subsequent continuation lines. This is the default
1728 @item -fdiagnostics-show-location=every-line
1729 Only meaningful in line-wrapping mode. Instructs the diagnostic
1730 messages reporter to emit the same source location information (as
1731 prefix) for physical lines that result from the process of breaking
1732 a message which is too long to fit on a single line.
1736 @node Warning Options
1737 @section Options to Request or Suppress Warnings
1738 @cindex options to control warnings
1739 @cindex warning messages
1740 @cindex messages, warning
1741 @cindex suppressing warnings
1743 Warnings are diagnostic messages that report constructions which
1744 are not inherently erroneous but which are risky or suggest there
1745 may have been an error.
1747 You can request many specific warnings with options beginning @samp{-W},
1748 for example @option{-Wimplicit} to request warnings on implicit
1749 declarations. Each of these specific warning options also has a
1750 negative form beginning @samp{-Wno-} to turn off warnings;
1751 for example, @option{-Wno-implicit}. This manual lists only one of the
1752 two forms, whichever is not the default.
1754 The following options control the amount and kinds of warnings produced
1755 by GCC; for further, language-specific options also refer to
1756 @ref{C++ Dialect Options} and @ref{Objective-C Dialect Options}.
1759 @cindex syntax checking
1761 @opindex fsyntax-only
1762 Check the code for syntax errors, but don't do anything beyond that.
1766 Issue all the warnings demanded by strict ISO C and ISO C++;
1767 reject all programs that use forbidden extensions, and some other
1768 programs that do not follow ISO C and ISO C++. For ISO C, follows the
1769 version of the ISO C standard specified by any @option{-std} option used.
1771 Valid ISO C and ISO C++ programs should compile properly with or without
1772 this option (though a rare few will require @option{-ansi} or a
1773 @option{-std} option specifying the required version of ISO C)@. However,
1774 without this option, certain GNU extensions and traditional C and C++
1775 features are supported as well. With this option, they are rejected.
1777 @option{-pedantic} does not cause warning messages for use of the
1778 alternate keywords whose names begin and end with @samp{__}. Pedantic
1779 warnings are also disabled in the expression that follows
1780 @code{__extension__}. However, only system header files should use
1781 these escape routes; application programs should avoid them.
1782 @xref{Alternate Keywords}.
1784 Some users try to use @option{-pedantic} to check programs for strict ISO
1785 C conformance. They soon find that it does not do quite what they want:
1786 it finds some non-ISO practices, but not all---only those for which
1787 ISO C @emph{requires} a diagnostic, and some others for which
1788 diagnostics have been added.
1790 A feature to report any failure to conform to ISO C might be useful in
1791 some instances, but would require considerable additional work and would
1792 be quite different from @option{-pedantic}. We don't have plans to
1793 support such a feature in the near future.
1795 Where the standard specified with @option{-std} represents a GNU
1796 extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
1797 corresponding @dfn{base standard}, the version of ISO C on which the GNU
1798 extended dialect is based. Warnings from @option{-pedantic} are given
1799 where they are required by the base standard. (It would not make sense
1800 for such warnings to be given only for features not in the specified GNU
1801 C dialect, since by definition the GNU dialects of C include all
1802 features the compiler supports with the given option, and there would be
1803 nothing to warn about.)
1805 @item -pedantic-errors
1806 @opindex pedantic-errors
1807 Like @option{-pedantic}, except that errors are produced rather than
1812 Inhibit all warning messages.
1816 Inhibit warning messages about the use of @samp{#import}.
1818 @item -Wchar-subscripts
1819 @opindex Wchar-subscripts
1820 Warn if an array subscript has type @code{char}. This is a common cause
1821 of error, as programmers often forget that this type is signed on some
1826 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
1827 comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
1831 Check calls to @code{printf} and @code{scanf}, etc., to make sure that
1832 the arguments supplied have types appropriate to the format string
1833 specified, and that the conversions specified in the format string make
1834 sense. This includes standard functions, and others specified by format
1835 attributes (@pxref{Function Attributes}), in the @code{printf},
1836 @code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
1837 not in the C standard) families.
1839 The formats are checked against the format features supported by GNU
1840 libc version 2.2. These include all ISO C89 and C99 features, as well
1841 as features from the Single Unix Specification and some BSD and GNU
1842 extensions. Other library implementations may not support all these
1843 features; GCC does not support warning about features that go beyond a
1844 particular library's limitations. However, if @option{-pedantic} is used
1845 with @option{-Wformat}, warnings will be given about format features not
1846 in the selected standard version (but not for @code{strfmon} formats,
1847 since those are not in any version of the C standard). @xref{C Dialect
1848 Options,,Options Controlling C Dialect}.
1850 Since @option{-Wformat} also checks for null format arguments for
1851 several functions, @option{-Wformat} also implies @option{-Wnonnull}.
1853 @option{-Wformat} is included in @option{-Wall}. For more control over some
1854 aspects of format checking, the options @option{-Wno-format-y2k},
1855 @option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
1856 @option{-Wformat-nonliteral}, @option{-Wformat-security}, and
1857 @option{-Wformat=2} are available, but are not included in @option{-Wall}.
1859 @item -Wno-format-y2k
1860 @opindex Wno-format-y2k
1861 If @option{-Wformat} is specified, do not warn about @code{strftime}
1862 formats which may yield only a two-digit year.
1864 @item -Wno-format-extra-args
1865 @opindex Wno-format-extra-args
1866 If @option{-Wformat} is specified, do not warn about excess arguments to a
1867 @code{printf} or @code{scanf} format function. The C standard specifies
1868 that such arguments are ignored.
1870 Where the unused arguments lie between used arguments that are
1871 specified with @samp{$} operand number specifications, normally
1872 warnings are still given, since the implementation could not know what
1873 type to pass to @code{va_arg} to skip the unused arguments. However,
1874 in the case of @code{scanf} formats, this option will suppress the
1875 warning if the unused arguments are all pointers, since the Single
1876 Unix Specification says that such unused arguments are allowed.
1878 @item -Wno-format-zero-length
1879 @opindex Wno-format-zero-length
1880 If @option{-Wformat} is specified, do not warn about zero-length formats.
1881 The C standard specifies that zero-length formats are allowed.
1883 @item -Wformat-nonliteral
1884 @opindex Wformat-nonliteral
1885 If @option{-Wformat} is specified, also warn if the format string is not a
1886 string literal and so cannot be checked, unless the format function
1887 takes its format arguments as a @code{va_list}.
1889 @item -Wformat-security
1890 @opindex Wformat-security
1891 If @option{-Wformat} is specified, also warn about uses of format
1892 functions that represent possible security problems. At present, this
1893 warns about calls to @code{printf} and @code{scanf} functions where the
1894 format string is not a string literal and there are no format arguments,
1895 as in @code{printf (foo);}. This may be a security hole if the format
1896 string came from untrusted input and contains @samp{%n}. (This is
1897 currently a subset of what @option{-Wformat-nonliteral} warns about, but
1898 in future warnings may be added to @option{-Wformat-security} that are not
1899 included in @option{-Wformat-nonliteral}.)
1903 Enable @option{-Wformat} plus format checks not included in
1904 @option{-Wformat}. Currently equivalent to @samp{-Wformat
1905 -Wformat-nonliteral -Wformat-security}.
1909 Enable warning about passing a null pointer for arguments marked as
1910 requiring a non-null value by the @code{nonnull} function attribute.
1912 @option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It
1913 can be disabled with the @option{-Wno-nonnull} option.
1915 @item -Wimplicit-int
1916 @opindex Wimplicit-int
1917 Warn when a declaration does not specify a type.
1919 @item -Wimplicit-function-declaration
1920 @itemx -Werror-implicit-function-declaration
1921 @opindex Wimplicit-function-declaration
1922 @opindex Werror-implicit-function-declaration
1923 Give a warning (or error) whenever a function is used before being
1928 Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
1932 Warn if the type of @samp{main} is suspicious. @samp{main} should be a
1933 function with external linkage, returning int, taking either zero
1934 arguments, two, or three arguments of appropriate types.
1936 @item -Wmissing-braces
1937 @opindex Wmissing-braces
1938 Warn if an aggregate or union initializer is not fully bracketed. In
1939 the following example, the initializer for @samp{a} is not fully
1940 bracketed, but that for @samp{b} is fully bracketed.
1943 int a[2][2] = @{ 0, 1, 2, 3 @};
1944 int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
1948 @opindex Wparentheses
1949 Warn if parentheses are omitted in certain contexts, such
1950 as when there is an assignment in a context where a truth value
1951 is expected, or when operators are nested whose precedence people
1952 often get confused about.
1954 Also warn about constructions where there may be confusion to which
1955 @code{if} statement an @code{else} branch belongs. Here is an example of
1970 In C, every @code{else} branch belongs to the innermost possible @code{if}
1971 statement, which in this example is @code{if (b)}. This is often not
1972 what the programmer expected, as illustrated in the above example by
1973 indentation the programmer chose. When there is the potential for this
1974 confusion, GCC will issue a warning when this flag is specified.
1975 To eliminate the warning, add explicit braces around the innermost
1976 @code{if} statement so there is no way the @code{else} could belong to
1977 the enclosing @code{if}. The resulting code would look like this:
1993 @item -Wsequence-point
1994 @opindex Wsequence-point
1995 Warn about code that may have undefined semantics because of violations
1996 of sequence point rules in the C standard.
1998 The C standard defines the order in which expressions in a C program are
1999 evaluated in terms of @dfn{sequence points}, which represent a partial
2000 ordering between the execution of parts of the program: those executed
2001 before the sequence point, and those executed after it. These occur
2002 after the evaluation of a full expression (one which is not part of a
2003 larger expression), after the evaluation of the first operand of a
2004 @code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
2005 function is called (but after the evaluation of its arguments and the
2006 expression denoting the called function), and in certain other places.
2007 Other than as expressed by the sequence point rules, the order of
2008 evaluation of subexpressions of an expression is not specified. All
2009 these rules describe only a partial order rather than a total order,
2010 since, for example, if two functions are called within one expression
2011 with no sequence point between them, the order in which the functions
2012 are called is not specified. However, the standards committee have
2013 ruled that function calls do not overlap.
2015 It is not specified when between sequence points modifications to the
2016 values of objects take effect. Programs whose behavior depends on this
2017 have undefined behavior; the C standard specifies that ``Between the
2018 previous and next sequence point an object shall have its stored value
2019 modified at most once by the evaluation of an expression. Furthermore,
2020 the prior value shall be read only to determine the value to be
2021 stored.''. If a program breaks these rules, the results on any
2022 particular implementation are entirely unpredictable.
2024 Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
2025 = b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
2026 diagnosed by this option, and it may give an occasional false positive
2027 result, but in general it has been found fairly effective at detecting
2028 this sort of problem in programs.
2030 The present implementation of this option only works for C programs. A
2031 future implementation may also work for C++ programs.
2033 The C standard is worded confusingly, therefore there is some debate
2034 over the precise meaning of the sequence point rules in subtle cases.
2035 Links to discussions of the problem, including proposed formal
2036 definitions, may be found on our readings page, at
2037 @w{@uref{http://gcc.gnu.org/readings.html}}.
2040 @opindex Wreturn-type
2041 Warn whenever a function is defined with a return-type that defaults to
2042 @code{int}. Also warn about any @code{return} statement with no
2043 return-value in a function whose return-type is not @code{void}.
2045 For C++, a function without return type always produces a diagnostic
2046 message, even when @option{-Wno-return-type} is specified. The only
2047 exceptions are @samp{main} and functions defined in system headers.
2051 Warn whenever a @code{switch} statement has an index of enumeral type
2052 and lacks a @code{case} for one or more of the named codes of that
2053 enumeration. (The presence of a @code{default} label prevents this
2054 warning.) @code{case} labels outside the enumeration range also
2055 provoke warnings when this option is used.
2057 @item -Wswitch-default
2058 @opindex Wswitch-switch
2059 Warn whenever a @code{switch} statement does not have a @code{default}
2063 @opindex Wswitch-enum
2064 Warn whenever a @code{switch} statement has an index of enumeral type
2065 and lacks a @code{case} for one or more of the named codes of that
2066 enumeration. @code{case} labels outside the enumeration range also
2067 provoke warnings when this option is used.
2071 Warn if any trigraphs are encountered that might change the meaning of
2072 the program (trigraphs within comments are not warned about).
2074 @item -Wunused-function
2075 @opindex Wunused-function
2076 Warn whenever a static function is declared but not defined or a
2077 non\-inline static function is unused.
2079 @item -Wunused-label
2080 @opindex Wunused-label
2081 Warn whenever a label is declared but not used.
2083 To suppress this warning use the @samp{unused} attribute
2084 (@pxref{Variable Attributes}).
2086 @item -Wunused-parameter
2087 @opindex Wunused-parameter
2088 Warn whenever a function parameter is unused aside from its declaration.
2090 To suppress this warning use the @samp{unused} attribute
2091 (@pxref{Variable Attributes}).
2093 @item -Wunused-variable
2094 @opindex Wunused-variable
2095 Warn whenever a local variable or non-constant static variable is unused
2096 aside from its declaration
2098 To suppress this warning use the @samp{unused} attribute
2099 (@pxref{Variable Attributes}).
2101 @item -Wunused-value
2102 @opindex Wunused-value
2103 Warn whenever a statement computes a result that is explicitly not used.
2105 To suppress this warning cast the expression to @samp{void}.
2109 All all the above @option{-Wunused} options combined.
2111 In order to get a warning about an unused function parameter, you must
2112 either specify @samp{-W -Wunused} or separately specify
2113 @option{-Wunused-parameter}.
2115 @item -Wuninitialized
2116 @opindex Wuninitialized
2117 Warn if an automatic variable is used without first being initialized or
2118 if a variable may be clobbered by a @code{setjmp} call.
2120 These warnings are possible only in optimizing compilation,
2121 because they require data flow information that is computed only
2122 when optimizing. If you don't specify @option{-O}, you simply won't
2125 These warnings occur only for variables that are candidates for
2126 register allocation. Therefore, they do not occur for a variable that
2127 is declared @code{volatile}, or whose address is taken, or whose size
2128 is other than 1, 2, 4 or 8 bytes. Also, they do not occur for
2129 structures, unions or arrays, even when they are in registers.
2131 Note that there may be no warning about a variable that is used only
2132 to compute a value that itself is never used, because such
2133 computations may be deleted by data flow analysis before the warnings
2136 These warnings are made optional because GCC is not smart
2137 enough to see all the reasons why the code might be correct
2138 despite appearing to have an error. Here is one example of how
2159 If the value of @code{y} is always 1, 2 or 3, then @code{x} is
2160 always initialized, but GCC doesn't know this. Here is
2161 another common case:
2166 if (change_y) save_y = y, y = new_y;
2168 if (change_y) y = save_y;
2173 This has no bug because @code{save_y} is used only if it is set.
2175 @cindex @code{longjmp} warnings
2176 This option also warns when a non-volatile automatic variable might be
2177 changed by a call to @code{longjmp}. These warnings as well are possible
2178 only in optimizing compilation.
2180 The compiler sees only the calls to @code{setjmp}. It cannot know
2181 where @code{longjmp} will be called; in fact, a signal handler could
2182 call it at any point in the code. As a result, you may get a warning
2183 even when there is in fact no problem because @code{longjmp} cannot
2184 in fact be called at the place which would cause a problem.
2186 Some spurious warnings can be avoided if you declare all the functions
2187 you use that never return as @code{noreturn}. @xref{Function
2190 @item -Wreorder @r{(C++ only)}
2192 @cindex reordering, warning
2193 @cindex warning for reordering of member initializers
2194 Warn when the order of member initializers given in the code does not
2195 match the order in which they must be executed. For instance:
2197 @item -Wunknown-pragmas
2198 @opindex Wunknown-pragmas
2199 @cindex warning for unknown pragmas
2200 @cindex unknown pragmas, warning
2201 @cindex pragmas, warning of unknown
2202 Warn when a #pragma directive is encountered which is not understood by
2203 GCC@. If this command line option is used, warnings will even be issued
2204 for unknown pragmas in system header files. This is not the case if
2205 the warnings were only enabled by the @option{-Wall} command line option.
2209 All of the above @samp{-W} options combined. This enables all the
2210 warnings about constructions that some users consider questionable, and
2211 that are easy to avoid (or modify to prevent the warning), even in
2212 conjunction with macros.
2215 The following @option{-W@dots{}} options are not implied by @option{-Wall}.
2216 Some of them warn about constructions that users generally do not
2217 consider questionable, but which occasionally you might wish to check
2218 for; others warn about constructions that are necessary or hard to avoid
2219 in some cases, and there is no simple way to modify the code to suppress
2225 Print extra warning messages for these events:
2229 A function can return either with or without a value. (Falling
2230 off the end of the function body is considered returning without
2231 a value.) For example, this function would evoke such a
2245 An expression-statement or the left-hand side of a comma expression
2246 contains no side effects.
2247 To suppress the warning, cast the unused expression to void.
2248 For example, an expression such as @samp{x[i,j]} will cause a warning,
2249 but @samp{x[(void)i,j]} will not.
2252 An unsigned value is compared against zero with @samp{<} or @samp{<=}.
2255 A comparison like @samp{x<=y<=z} appears; this is equivalent to
2256 @samp{(x<=y ? 1 : 0) <= z}, which is a different interpretation from
2257 that of ordinary mathematical notation.
2260 Storage-class specifiers like @code{static} are not the first things in
2261 a declaration. According to the C Standard, this usage is obsolescent.
2264 The return type of a function has a type qualifier such as @code{const}.
2265 Such a type qualifier has no effect, since the value returned by a
2266 function is not an lvalue. (But don't warn about the GNU extension of
2267 @code{volatile void} return types. That extension will be warned about
2268 if @option{-pedantic} is specified.)
2271 If @option{-Wall} or @option{-Wunused} is also specified, warn about unused
2275 A comparison between signed and unsigned values could produce an
2276 incorrect result when the signed value is converted to unsigned.
2277 (But don't warn if @option{-Wno-sign-compare} is also specified.)
2280 An aggregate has a partly bracketed initializer.
2281 For example, the following code would evoke such a warning,
2282 because braces are missing around the initializer for @code{x.h}:
2285 struct s @{ int f, g; @};
2286 struct t @{ struct s h; int i; @};
2287 struct t x = @{ 1, 2, 3 @};
2291 An aggregate has an initializer which does not initialize all members.
2292 For example, the following code would cause such a warning, because
2293 @code{x.h} would be implicitly initialized to zero:
2296 struct s @{ int f, g, h; @};
2297 struct s x = @{ 3, 4 @};
2301 @item -Wno-div-by-zero
2302 @opindex Wno-div-by-zero
2303 @opindex Wdiv-by-zero
2304 Do not warn about compile-time integer division by zero. Floating point
2305 division by zero is not warned about, as it can be a legitimate way of
2306 obtaining infinities and NaNs.
2308 @item -Wsystem-headers
2309 @opindex Wsystem-headers
2310 @cindex warnings from system headers
2311 @cindex system headers, warnings from
2312 Print warning messages for constructs found in system header files.
2313 Warnings from system headers are normally suppressed, on the assumption
2314 that they usually do not indicate real problems and would only make the
2315 compiler output harder to read. Using this command line option tells
2316 GCC to emit warnings from system headers as if they occurred in user
2317 code. However, note that using @option{-Wall} in conjunction with this
2318 option will @emph{not} warn about unknown pragmas in system
2319 headers---for that, @option{-Wunknown-pragmas} must also be used.
2322 @opindex Wfloat-equal
2323 Warn if floating point values are used in equality comparisons.
2325 The idea behind this is that sometimes it is convenient (for the
2326 programmer) to consider floating-point values as approximations to
2327 infinitely precise real numbers. If you are doing this, then you need
2328 to compute (by analysing the code, or in some other way) the maximum or
2329 likely maximum error that the computation introduces, and allow for it
2330 when performing comparisons (and when producing output, but that's a
2331 different problem). In particular, instead of testing for equality, you
2332 would check to see whether the two values have ranges that overlap; and
2333 this is done with the relational operators, so equality comparisons are
2336 @item -Wtraditional @r{(C only)}
2337 @opindex Wtraditional
2338 Warn about certain constructs that behave differently in traditional and
2339 ISO C@. Also warn about ISO C constructs that have no traditional C
2340 equivalent, and/or problematic constructs which should be avoided.
2344 Macro parameters that appear within string literals in the macro body.
2345 In traditional C macro replacement takes place within string literals,
2346 but does not in ISO C@.
2349 In traditional C, some preprocessor directives did not exist.
2350 Traditional preprocessors would only consider a line to be a directive
2351 if the @samp{#} appeared in column 1 on the line. Therefore
2352 @option{-Wtraditional} warns about directives that traditional C
2353 understands but would ignore because the @samp{#} does not appear as the
2354 first character on the line. It also suggests you hide directives like
2355 @samp{#pragma} not understood by traditional C by indenting them. Some
2356 traditional implementations would not recognize @samp{#elif}, so it
2357 suggests avoiding it altogether.
2360 A function-like macro that appears without arguments.
2363 The unary plus operator.
2366 The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
2367 constant suffixes. (Traditional C does support the @samp{L} suffix on integer
2368 constants.) Note, these suffixes appear in macros defined in the system
2369 headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
2370 Use of these macros in user code might normally lead to spurious
2371 warnings, however gcc's integrated preprocessor has enough context to
2372 avoid warning in these cases.
2375 A function declared external in one block and then used after the end of
2379 A @code{switch} statement has an operand of type @code{long}.
2382 A non-@code{static} function declaration follows a @code{static} one.
2383 This construct is not accepted by some traditional C compilers.
2386 The ISO type of an integer constant has a different width or
2387 signedness from its traditional type. This warning is only issued if
2388 the base of the constant is ten. I.e.@: hexadecimal or octal values, which
2389 typically represent bit patterns, are not warned about.
2392 Usage of ISO string concatenation is detected.
2395 Initialization of automatic aggregates.
2398 Identifier conflicts with labels. Traditional C lacks a separate
2399 namespace for labels.
2402 Initialization of unions. If the initializer is zero, the warning is
2403 omitted. This is done under the assumption that the zero initializer in
2404 user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
2405 initializer warnings and relies on default initialization to zero in the
2409 Conversions by prototypes between fixed/floating point values and vice
2410 versa. The absence of these prototypes when compiling with traditional
2411 C would cause serious problems. This is a subset of the possible
2412 conversion warnings, for the full set use @option{-Wconversion}.
2415 Use of ISO C style function definitions. This warning intentionally is
2416 @emph{not} issued for prototype declarations or variadic functions
2417 because these ISO C features will appear in your code when using
2418 libiberty's traditional C compatibility macros, @code{PARAMS} and
2419 @code{VPARAMS}. This warning is also bypassed for nested functions
2420 because that feature is already a gcc extension and thus not relevant to
2421 traditional C compatibility.
2426 Warn if an undefined identifier is evaluated in an @samp{#if} directive.
2428 @item -Wendif-labels
2429 @opindex Wendif-labels
2430 Warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
2434 Warn whenever a local variable shadows another local variable, parameter or
2435 global variable or whenever a built-in function is shadowed.
2437 @item -Wlarger-than-@var{len}
2438 @opindex Wlarger-than
2439 Warn whenever an object of larger than @var{len} bytes is defined.
2441 @item -Wpointer-arith
2442 @opindex Wpointer-arith
2443 Warn about anything that depends on the ``size of'' a function type or
2444 of @code{void}. GNU C assigns these types a size of 1, for
2445 convenience in calculations with @code{void *} pointers and pointers
2448 @item -Wbad-function-cast @r{(C only)}
2449 @opindex Wbad-function-cast
2450 Warn whenever a function call is cast to a non-matching type.
2451 For example, warn if @code{int malloc()} is cast to @code{anything *}.
2455 Warn whenever a pointer is cast so as to remove a type qualifier from
2456 the target type. For example, warn if a @code{const char *} is cast
2457 to an ordinary @code{char *}.
2460 @opindex Wcast-align
2461 Warn whenever a pointer is cast such that the required alignment of the
2462 target is increased. For example, warn if a @code{char *} is cast to
2463 an @code{int *} on machines where integers can only be accessed at
2464 two- or four-byte boundaries.
2466 @item -Wwrite-strings
2467 @opindex Wwrite-strings
2468 When compiling C, give string constants the type @code{const
2469 char[@var{length}]} so that
2470 copying the address of one into a non-@code{const} @code{char *}
2471 pointer will get a warning; when compiling C++, warn about the
2472 deprecated conversion from string constants to @code{char *}.
2473 These warnings will help you find at
2474 compile time code that can try to write into a string constant, but
2475 only if you have been very careful about using @code{const} in
2476 declarations and prototypes. Otherwise, it will just be a nuisance;
2477 this is why we did not make @option{-Wall} request these warnings.
2480 @opindex Wconversion
2481 Warn if a prototype causes a type conversion that is different from what
2482 would happen to the same argument in the absence of a prototype. This
2483 includes conversions of fixed point to floating and vice versa, and
2484 conversions changing the width or signedness of a fixed point argument
2485 except when the same as the default promotion.
2487 Also, warn if a negative integer constant expression is implicitly
2488 converted to an unsigned type. For example, warn about the assignment
2489 @code{x = -1} if @code{x} is unsigned. But do not warn about explicit
2490 casts like @code{(unsigned) -1}.
2492 @item -Wsign-compare
2493 @opindex Wsign-compare
2494 @cindex warning for comparison of signed and unsigned values
2495 @cindex comparison of signed and unsigned values, warning
2496 @cindex signed and unsigned values, comparison warning
2497 Warn when a comparison between signed and unsigned values could produce
2498 an incorrect result when the signed value is converted to unsigned.
2499 This warning is also enabled by @option{-W}; to get the other warnings
2500 of @option{-W} without this warning, use @samp{-W -Wno-sign-compare}.
2502 @item -Waggregate-return
2503 @opindex Waggregate-return
2504 Warn if any functions that return structures or unions are defined or
2505 called. (In languages where you can return an array, this also elicits
2508 @item -Wstrict-prototypes @r{(C only)}
2509 @opindex Wstrict-prototypes
2510 Warn if a function is declared or defined without specifying the
2511 argument types. (An old-style function definition is permitted without
2512 a warning if preceded by a declaration which specifies the argument
2515 @item -Wmissing-prototypes @r{(C only)}
2516 @opindex Wmissing-prototypes
2517 Warn if a global function is defined without a previous prototype
2518 declaration. This warning is issued even if the definition itself
2519 provides a prototype. The aim is to detect global functions that fail
2520 to be declared in header files.
2522 @item -Wmissing-declarations
2523 @opindex Wmissing-declarations
2524 Warn if a global function is defined without a previous declaration.
2525 Do so even if the definition itself provides a prototype.
2526 Use this option to detect global functions that are not declared in
2529 @item -Wmissing-noreturn
2530 @opindex Wmissing-noreturn
2531 Warn about functions which might be candidates for attribute @code{noreturn}.
2532 Note these are only possible candidates, not absolute ones. Care should
2533 be taken to manually verify functions actually do not ever return before
2534 adding the @code{noreturn} attribute, otherwise subtle code generation
2535 bugs could be introduced. You will not get a warning for @code{main} in
2536 hosted C environments.
2538 @item -Wmissing-format-attribute
2539 @opindex Wmissing-format-attribute
2541 If @option{-Wformat} is enabled, also warn about functions which might be
2542 candidates for @code{format} attributes. Note these are only possible
2543 candidates, not absolute ones. GCC will guess that @code{format}
2544 attributes might be appropriate for any function that calls a function
2545 like @code{vprintf} or @code{vscanf}, but this might not always be the
2546 case, and some functions for which @code{format} attributes are
2547 appropriate may not be detected. This option has no effect unless
2548 @option{-Wformat} is enabled (possibly by @option{-Wall}).
2550 @item -Wno-multichar
2551 @opindex Wno-multichar
2553 Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
2554 Usually they indicate a typo in the user's code, as they have
2555 implementation-defined values, and should not be used in portable code.
2557 @item -Wno-deprecated-declarations
2558 @opindex Wno-deprecated-declarations
2559 Do not warn about uses of functions, variables, and types marked as
2560 deprecated by using the @code{deprecated} attribute.
2561 (@pxref{Function Attributes}, @pxref{Variable Attributes},
2562 @pxref{Type Attributes}.)
2566 Warn if a structure is given the packed attribute, but the packed
2567 attribute has no effect on the layout or size of the structure.
2568 Such structures may be mis-aligned for little benefit. For
2569 instance, in this code, the variable @code{f.x} in @code{struct bar}
2570 will be misaligned even though @code{struct bar} does not itself
2571 have the packed attribute:
2578 @} __attribute__((packed));
2588 Warn if padding is included in a structure, either to align an element
2589 of the structure or to align the whole structure. Sometimes when this
2590 happens it is possible to rearrange the fields of the structure to
2591 reduce the padding and so make the structure smaller.
2593 @item -Wredundant-decls
2594 @opindex Wredundant-decls
2595 Warn if anything is declared more than once in the same scope, even in
2596 cases where multiple declaration is valid and changes nothing.
2598 @item -Wnested-externs @r{(C only)}
2599 @opindex Wnested-externs
2600 Warn if an @code{extern} declaration is encountered within a function.
2602 @item -Wunreachable-code
2603 @opindex Wunreachable-code
2604 Warn if the compiler detects that code will never be executed.
2606 This option is intended to warn when the compiler detects that at
2607 least a whole line of source code will never be executed, because
2608 some condition is never satisfied or because it is after a
2609 procedure that never returns.
2611 It is possible for this option to produce a warning even though there
2612 are circumstances under which part of the affected line can be executed,
2613 so care should be taken when removing apparently-unreachable code.
2615 For instance, when a function is inlined, a warning may mean that the
2616 line is unreachable in only one inlined copy of the function.
2618 This option is not made part of @option{-Wall} because in a debugging
2619 version of a program there is often substantial code which checks
2620 correct functioning of the program and is, hopefully, unreachable
2621 because the program does work. Another common use of unreachable
2622 code is to provide behavior which is selectable at compile-time.
2626 Warn if a function can not be inlined and it was declared as inline.
2630 @opindex Wno-long-long
2631 Warn if @samp{long long} type is used. This is default. To inhibit
2632 the warning messages, use @option{-Wno-long-long}. Flags
2633 @option{-Wlong-long} and @option{-Wno-long-long} are taken into account
2634 only when @option{-pedantic} flag is used.
2636 @item -Wdisabled-optimization
2637 @opindex Wdisabled-optimization
2638 Warn if a requested optimization pass is disabled. This warning does
2639 not generally indicate that there is anything wrong with your code; it
2640 merely indicates that GCC's optimizers were unable to handle the code
2641 effectively. Often, the problem is that your code is too big or too
2642 complex; GCC will refuse to optimize programs when the optimization
2643 itself is likely to take inordinate amounts of time.
2647 Make all warnings into errors.
2650 @node Debugging Options
2651 @section Options for Debugging Your Program or GCC
2652 @cindex options, debugging
2653 @cindex debugging information options
2655 GCC has various special options that are used for debugging
2656 either your program or GCC:
2661 Produce debugging information in the operating system's native format
2662 (stabs, COFF, XCOFF, or DWARF)@. GDB can work with this debugging
2665 On most systems that use stabs format, @option{-g} enables use of extra
2666 debugging information that only GDB can use; this extra information
2667 makes debugging work better in GDB but will probably make other debuggers
2669 refuse to read the program. If you want to control for certain whether
2670 to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
2671 @option{-gxcoff+}, @option{-gxcoff}, @option{-gdwarf-1+}, @option{-gdwarf-1},
2672 or @option{-gvms} (see below).
2674 Unlike most other C compilers, GCC allows you to use @option{-g} with
2675 @option{-O}. The shortcuts taken by optimized code may occasionally
2676 produce surprising results: some variables you declared may not exist
2677 at all; flow of control may briefly move where you did not expect it;
2678 some statements may not be executed because they compute constant
2679 results or their values were already at hand; some statements may
2680 execute in different places because they were moved out of loops.
2682 Nevertheless it proves possible to debug optimized output. This makes
2683 it reasonable to use the optimizer for programs that might have bugs.
2685 The following options are useful when GCC is generated with the
2686 capability for more than one debugging format.
2690 Produce debugging information for use by GDB@. This means to use the
2691 most expressive format available (DWARF 2, stabs, or the native format
2692 if neither of those are supported), including GDB extensions if at all
2697 Produce debugging information in stabs format (if that is supported),
2698 without GDB extensions. This is the format used by DBX on most BSD
2699 systems. On MIPS, Alpha and System V Release 4 systems this option
2700 produces stabs debugging output which is not understood by DBX or SDB@.
2701 On System V Release 4 systems this option requires the GNU assembler.
2705 Produce debugging information in stabs format (if that is supported),
2706 using GNU extensions understood only by the GNU debugger (GDB)@. The
2707 use of these extensions is likely to make other debuggers crash or
2708 refuse to read the program.
2712 Produce debugging information in COFF format (if that is supported).
2713 This is the format used by SDB on most System V systems prior to
2718 Produce debugging information in XCOFF format (if that is supported).
2719 This is the format used by the DBX debugger on IBM RS/6000 systems.
2723 Produce debugging information in XCOFF format (if that is supported),
2724 using GNU extensions understood only by the GNU debugger (GDB)@. The
2725 use of these extensions is likely to make other debuggers crash or
2726 refuse to read the program, and may cause assemblers other than the GNU
2727 assembler (GAS) to fail with an error.
2731 Produce debugging information in DWARF version 1 format (if that is
2732 supported). This is the format used by SDB on most System V Release 4
2735 This option is deprecated.
2739 Produce debugging information in DWARF version 1 format (if that is
2740 supported), using GNU extensions understood only by the GNU debugger
2741 (GDB)@. The use of these extensions is likely to make other debuggers
2742 crash or refuse to read the program.
2744 This option is deprecated.
2748 Produce debugging information in DWARF version 2 format (if that is
2749 supported). This is the format used by DBX on IRIX 6.
2753 Produce debugging information in VMS debug format (if that is
2754 supported). This is the format used by DEBUG on VMS systems.
2757 @itemx -ggdb@var{level}
2758 @itemx -gstabs@var{level}
2759 @itemx -gcoff@var{level}
2760 @itemx -gxcoff@var{level}
2761 @itemx -gvms@var{level}
2762 Request debugging information and also use @var{level} to specify how
2763 much information. The default level is 2.
2765 Level 1 produces minimal information, enough for making backtraces in
2766 parts of the program that you don't plan to debug. This includes
2767 descriptions of functions and external variables, but no information
2768 about local variables and no line numbers.
2770 Level 3 includes extra information, such as all the macro definitions
2771 present in the program. Some debuggers support macro expansion when
2772 you use @option{-g3}.
2774 Note that in order to avoid confusion between DWARF1 debug level 2,
2775 and DWARF2, neither @option{-gdwarf} nor @option{-gdwarf-2} accept
2776 a concatenated debug level. Instead use an additional @option{-g@var{level}}
2777 option to change the debug level for DWARF1 or DWARF2.
2782 Generate extra code to write profile information suitable for the
2783 analysis program @code{prof}. You must use this option when compiling
2784 the source files you want data about, and you must also use it when
2787 @cindex @code{gprof}
2790 Generate extra code to write profile information suitable for the
2791 analysis program @code{gprof}. You must use this option when compiling
2792 the source files you want data about, and you must also use it when
2798 Generate extra code to write profile information for basic blocks, which will
2799 record the number of times each basic block is executed, the basic block start
2800 address, and the function name containing the basic block. If @option{-g} is
2801 used, the line number and filename of the start of the basic block will also be
2802 recorded. If not overridden by the machine description, the default action is
2803 to append to the text file @file{bb.out}.
2805 This data could be analyzed by a program like @code{tcov}. Note,
2806 however, that the format of the data is not what @code{tcov} expects.
2807 Eventually GNU @code{gprof} should be extended to process this data.
2811 Makes the compiler print out each function name as it is compiled, and
2812 print some statistics about each pass when it finishes.
2815 @opindex ftime-report
2816 Makes the compiler print some statistics about the time consumed by each
2817 pass when it finishes.
2820 @opindex fmem-report
2821 Makes the compiler print some statistics about permanent memory
2822 allocation when it finishes.
2824 @item -fprofile-arcs
2825 @opindex fprofile-arcs
2826 Instrument @dfn{arcs} during compilation to generate coverage data
2827 or for profile-directed block ordering. During execution the program
2828 records how many times each branch is executed and how many times it is
2829 taken. When the compiled program exits it saves this data to a file
2830 called @file{@var{sourcename}.da} for each source file.
2832 For profile-directed block ordering, compile the program with
2833 @option{-fprofile-arcs} plus optimization and code generation options,
2834 generate the arc profile information by running the program on a
2835 selected workload, and then compile the program again with the same
2836 optimization and code generation options plus
2837 @option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
2838 Control Optimization}).
2840 The other use of @option{-fprofile-arcs} is for use with @code{gcov},
2841 when it is used with the @option{-ftest-coverage} option. GCC
2842 supports two methods of determining code coverage: the options that
2843 support @code{gcov}, and options @option{-a} and @option{-ax}, which
2844 write information to text files. The options that support @code{gcov}
2845 do not need to instrument every arc in the program, so a program compiled
2846 with them runs faster than a program compiled with @option{-a}, which
2847 adds instrumentation code to every basic block in the program. The
2848 tradeoff: since @code{gcov} does not have execution counts for all
2849 branches, it must start with the execution counts for the instrumented
2850 branches, and then iterate over the program flow graph until the entire
2851 graph has been solved. Hence, @code{gcov} runs a little more slowly than
2852 a program which uses information from @option{-a} and @option{-ax}.
2854 With @option{-fprofile-arcs}, for each function of your program GCC
2855 creates a program flow graph, then finds a spanning tree for the graph.
2856 Only arcs that are not on the spanning tree have to be instrumented: the
2857 compiler adds code to count the number of times that these arcs are
2858 executed. When an arc is the only exit or only entrance to a block, the
2859 instrumentation code can be added to the block; otherwise, a new basic
2860 block must be created to hold the instrumentation code.
2862 This option makes it possible to estimate branch probabilities and to
2863 calculate basic block execution counts. In general, basic block
2864 execution counts as provided by @option{-a} do not give enough
2865 information to estimate all branch probabilities.
2868 @item -ftest-coverage
2869 @opindex ftest-coverage
2870 Create data files for the @code{gcov} code-coverage utility
2871 (@pxref{Gcov,, @code{gcov}: a GCC Test Coverage Program}).
2872 The data file names begin with the name of your source file:
2875 @item @var{sourcename}.bb
2876 A mapping from basic blocks to line numbers, which @code{gcov} uses to
2877 associate basic block execution counts with line numbers.
2879 @item @var{sourcename}.bbg
2880 A list of all arcs in the program flow graph. This allows @code{gcov}
2881 to reconstruct the program flow graph, so that it can compute all basic
2882 block and arc execution counts from the information in the
2883 @code{@var{sourcename}.da} file.
2886 Use @option{-ftest-coverage} with @option{-fprofile-arcs}; the latter
2887 option adds instrumentation to the program, which then writes
2888 execution counts to another data file:
2891 @item @var{sourcename}.da
2892 Runtime arc execution counts, used in conjunction with the arc
2893 information in the file @code{@var{sourcename}.bbg}.
2896 Coverage data will map better to the source files if
2897 @option{-ftest-coverage} is used without optimization.
2899 @item -d@var{letters}
2901 Says to make debugging dumps during compilation at times specified by
2902 @var{letters}. This is used for debugging the compiler. The file names
2903 for most of the dumps are made by appending a pass number and a word to
2904 the source file name (e.g. @file{foo.c.00.rtl} or @file{foo.c.01.sibling}).
2905 Here are the possible letters for use in @var{letters}, and their meanings:
2910 Annotate the assembler output with miscellaneous debugging information.
2913 Dump after computing branch probabilities, to @file{@var{file}.15.bp}.
2916 Dump after block reordering, to @file{@var{file}.30.bbro}.
2919 Dump after instruction combination, to the file @file{@var{file}.17.combine}.
2922 Dump after the first if conversion, to the file @file{@var{file}.18.ce}.
2925 Dump after delayed branch scheduling, to @file{@var{file}.32.dbr}.
2928 Dump all macro definitions, at the end of preprocessing, in addition to
2932 Dump after SSA optimizations, to @file{@var{file}.04.ssa} and
2933 @file{@var{file}.07.ussa}.
2936 Dump after the second if conversion, to @file{@var{file}.27.ce2}.
2939 Dump after life analysis, to @file{@var{file}.16.life}.
2942 Dump after purging @code{ADDRESSOF} codes, to @file{@var{file}.10.addressof}.
2945 Dump after global register allocation, to @file{@var{file}.22.greg}.
2948 Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
2951 Dump after reg-to-stack conversion, to @file{@var{file}.29.stack}.
2954 Dump after post-reload optimizations, to @file{@var{file}.23.postreload}.
2957 Dump after GCSE, to @file{@var{file}.11.gcse}.
2960 Dump after sibling call optimizations, to @file{@var{file}.01.sibling}.
2963 Dump after the first jump optimization, to @file{@var{file}.03.jump}.
2966 Dump after conversion from registers to stack, to @file{@var{file}.33.stack}.
2969 Dump after local register allocation, to @file{@var{file}.21.lreg}.
2972 Dump after loop optimization, to @file{@var{file}.12.loop}.
2975 Dump after performing the machine dependent reorganisation pass, to
2976 @file{@var{file}.31.mach}.
2979 Dump after register renumbering, to @file{@var{file}.26.rnreg}.
2982 Dump after the register move pass, to @file{@var{file}.19.regmove}.
2985 Dump after RTL generation, to @file{@var{file}.00.rtl}.
2988 Dump after the second scheduling pass, to @file{@var{file}.28.sched2}.
2991 Dump after CSE (including the jump optimization that sometimes follows
2992 CSE), to @file{@var{file}.09.cse}.
2995 Dump after the first scheduling pass, to @file{@var{file}.20.sched}.
2998 Dump after the second CSE pass (including the jump optimization that
2999 sometimes follows CSE), to @file{@var{file}.13.cse2}.
3002 Dump after null pointer ellimination pass ti @file{@var{file}.08.null}.
3005 Dump after the second flow pass, to @file{@var{file}.24.flow2}.
3008 Dump after SSA dead code elimination, to @file{@var{file}.06.ssadce}.
3011 Dump after the peephole pass, to @file{@var{file}.25.peephole2}.
3014 Produce all the dumps listed above.
3017 Print statistics on memory usage, at the end of the run, to
3021 Annotate the assembler output with a comment indicating which
3022 pattern and alternative was used. The length of each instruction is
3026 Dump the RTL in the assembler output as a comment before each instruction.
3027 Also turns on @option{-dp} annotation.
3030 For each of the other indicated dump files (except for
3031 @file{@var{file}.00.rtl}), dump a representation of the control flow graph
3032 suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
3035 Just generate RTL for a function instead of compiling it. Usually used
3039 Dump debugging information during parsing, to standard error.
3042 @item -fdump-unnumbered
3043 @opindex fdump-unnumbered
3044 When doing debugging dumps (see @option{-d} option above), suppress instruction
3045 numbers and line number note output. This makes it more feasible to
3046 use diff on debugging dumps for compiler invocations with different
3047 options, in particular with and without @option{-g}.
3049 @item -fdump-translation-unit @r{(C and C++ only)}
3050 @itemx -fdump-translation-unit-@var{options} @r{(C and C++ only)}
3051 @opindex fdump-translation-unit
3052 Dump a representation of the tree structure for the entire translation
3053 unit to a file. The file name is made by appending @file{.tu} to the
3054 source file name. If the @samp{-@var{options}} form is used, @var{options}
3055 controls the details of the dump as described for the
3056 @option{-fdump-tree} options.
3058 @item -fdump-class-hierarchy @r{(C++ only)}
3059 @itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
3060 @opindex fdump-class-hierarchy
3061 Dump a representation of each class's hierarchy and virtual function
3062 table layout to a file. The file name is made by appending @file{.class}
3063 to the source file name. If the @samp{-@var{options}} form is used,
3064 @var{options} controls the details of the dump as described for the
3065 @option{-fdump-tree} options.
3067 @item -fdump-tree-@var{switch} @r{(C++ only)}
3068 @itemx -fdump-tree-@var{switch}-@var{options} @r{(C++ only)}
3070 Control the dumping at various stages of processing the intermediate
3071 language tree to a file. The file name is generated by appending a switch
3072 specific suffix to the source file name. If the @samp{-@var{options}}
3073 form is used, @var{options} is a list of @samp{-} separated options that
3074 control the details of the dump. Not all options are applicable to all
3075 dumps, those which are not meaningful will be ignored. The following
3076 options are available
3080 Print the address of each node. Usually this is not meaningful as it
3081 changes according to the environment and source file. Its primary use
3082 is for tying up a dump file with a debug environment.
3084 Inhibit dumping of members of a scope or body of a function merely
3085 because that scope has been reached. Only dump such items when they
3086 are directly reachable by some other path.
3088 Turn on all options.
3091 The following tree dumps are possible:
3094 Dump before any tree based optimization, to @file{@var{file}.original}.
3096 Dump after all tree based optimization, to @file{@var{file}.optimized}.
3098 Dump after function inlining, to @file{@var{file}.inlined}.
3103 Store the usual ``temporary'' intermediate files permanently; place them
3104 in the current directory and name them based on the source file. Thus,
3105 compiling @file{foo.c} with @samp{-c -save-temps} would produce files
3106 @file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
3107 preprocessed @file{foo.i} output file even though the compiler now
3108 normally uses an integrated preprocessor.
3112 Report the CPU time taken by each subprocess in the compilation
3113 sequence. For C source files, this is the compiler proper and assembler
3114 (plus the linker if linking is done). The output looks like this:
3121 The first number on each line is the ``user time,'' that is time spent
3122 executing the program itself. The second number is ``system time,''
3123 time spent executing operating system routines on behalf of the program.
3124 Both numbers are in seconds.
3126 @item -print-file-name=@var{library}
3127 @opindex print-file-name
3128 Print the full absolute name of the library file @var{library} that
3129 would be used when linking---and don't do anything else. With this
3130 option, GCC does not compile or link anything; it just prints the
3133 @item -print-multi-directory
3134 @opindex print-multi-directory
3135 Print the directory name corresponding to the multilib selected by any
3136 other switches present in the command line. This directory is supposed
3137 to exist in @env{GCC_EXEC_PREFIX}.
3139 @item -print-multi-lib
3140 @opindex print-multi-lib
3141 Print the mapping from multilib directory names to compiler switches
3142 that enable them. The directory name is separated from the switches by
3143 @samp{;}, and each switch starts with an @samp{@@} instead of the
3144 @samp{-}, without spaces between multiple switches. This is supposed to
3145 ease shell-processing.
3147 @item -print-prog-name=@var{program}
3148 @opindex print-prog-name
3149 Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
3151 @item -print-libgcc-file-name
3152 @opindex print-libgcc-file-name
3153 Same as @option{-print-file-name=libgcc.a}.
3155 This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
3156 but you do want to link with @file{libgcc.a}. You can do
3159 gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
3162 @item -print-search-dirs
3163 @opindex print-search-dirs
3164 Print the name of the configured installation directory and a list of
3165 program and library directories gcc will search---and don't do anything else.
3167 This is useful when gcc prints the error message
3168 @samp{installation problem, cannot exec cpp0: No such file or directory}.
3169 To resolve this you either need to put @file{cpp0} and the other compiler
3170 components where gcc expects to find them, or you can set the environment
3171 variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
3172 Don't forget the trailing '/'.
3173 @xref{Environment Variables}.
3176 @opindex dumpmachine
3177 Print the compiler's target machine (for example,
3178 @samp{i686-pc-linux-gnu})---and don't do anything else.
3181 @opindex dumpversion
3182 Print the compiler version (for example, @samp{3.0})---and don't do
3187 Print the compiler's built-in specs---and don't do anything else. (This
3188 is used when GCC itself is being built.) @xref{Spec Files}.
3191 @node Optimize Options
3192 @section Options That Control Optimization
3193 @cindex optimize options
3194 @cindex options, optimization
3196 These options control various sorts of optimizations:
3203 Optimize. Optimizing compilation takes somewhat more time, and a lot
3204 more memory for a large function.
3206 Without @option{-O}, the compiler's goal is to reduce the cost of
3207 compilation and to make debugging produce the expected results.
3208 Statements are independent: if you stop the program with a breakpoint
3209 between statements, you can then assign a new value to any variable or
3210 change the program counter to any other statement in the function and
3211 get exactly the results you would expect from the source code.
3213 With @option{-O}, the compiler tries to reduce code size and execution
3214 time, without performing any optimizations that take a great deal of
3219 Optimize even more. GCC performs nearly all supported optimizations
3220 that do not involve a space-speed tradeoff. The compiler does not
3221 perform loop unrolling or function inlining when you specify @option{-O2}.
3222 As compared to @option{-O}, this option increases both compilation time
3223 and the performance of the generated code.
3225 @option{-O2} turns on all optional optimizations except for loop
3226 unrolling, function inlining, and register renaming. It also turns on
3227 the @option{-fforce-mem} and @option{-fstrict-aliasing} option on all
3228 machines and frame pointer elimination on machines where doing so does
3229 not interfere with debugging.
3231 Please note the warning under @option{-fgcse} about
3232 invoking @option{-O2} on programs that use computed gotos.
3236 Optimize yet more. @option{-O3} turns on all optimizations specified by
3237 @option{-O2} and also turns on the @option{-finline-functions} and
3238 @option{-frename-registers} options.
3246 Optimize for size. @option{-Os} enables all @option{-O2} optimizations that
3247 do not typically increase code size. It also performs further
3248 optimizations designed to reduce code size.
3250 If you use multiple @option{-O} options, with or without level numbers,
3251 the last such option is the one that is effective.
3254 Options of the form @option{-f@var{flag}} specify machine-independent
3255 flags. Most flags have both positive and negative forms; the negative
3256 form of @option{-ffoo} would be @option{-fno-foo}. In the table below,
3257 only one of the forms is listed---the one which is not the default.
3258 You can figure out the other form by either removing @samp{no-} or
3263 @opindex ffloat-store
3264 Do not store floating point variables in registers, and inhibit other
3265 options that might change whether a floating point value is taken from a
3268 @cindex floating point precision
3269 This option prevents undesirable excess precision on machines such as
3270 the 68000 where the floating registers (of the 68881) keep more
3271 precision than a @code{double} is supposed to have. Similarly for the
3272 x86 architecture. For most programs, the excess precision does only
3273 good, but a few programs rely on the precise definition of IEEE floating
3274 point. Use @option{-ffloat-store} for such programs, after modifying
3275 them to store all pertinent intermediate computations into variables.
3277 @item -fno-default-inline
3278 @opindex fno-default-inline
3279 Do not make member functions inline by default merely because they are
3280 defined inside the class scope (C++ only). Otherwise, when you specify
3281 @w{@option{-O}}, member functions defined inside class scope are compiled
3282 inline by default; i.e., you don't need to add @samp{inline} in front of
3283 the member function name.
3285 @item -fno-defer-pop
3286 @opindex fno-defer-pop
3287 Always pop the arguments to each function call as soon as that function
3288 returns. For machines which must pop arguments after a function call,
3289 the compiler normally lets arguments accumulate on the stack for several
3290 function calls and pops them all at once.
3294 Force memory operands to be copied into registers before doing
3295 arithmetic on them. This produces better code by making all memory
3296 references potential common subexpressions. When they are not common
3297 subexpressions, instruction combination should eliminate the separate
3298 register-load. The @option{-O2} option turns on this option.
3301 @opindex fforce-addr
3302 Force memory address constants to be copied into registers before
3303 doing arithmetic on them. This may produce better code just as
3304 @option{-fforce-mem} may.
3306 @item -fomit-frame-pointer
3307 @opindex fomit-frame-pointer
3308 Don't keep the frame pointer in a register for functions that
3309 don't need one. This avoids the instructions to save, set up and
3310 restore frame pointers; it also makes an extra register available
3311 in many functions. @strong{It also makes debugging impossible on
3314 On some machines, such as the VAX, this flag has no effect, because
3315 the standard calling sequence automatically handles the frame pointer
3316 and nothing is saved by pretending it doesn't exist. The
3317 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
3318 whether a target machine supports this flag. @xref{Registers,,Register
3319 Usage, gccint, GNU Compiler Collection (GCC) Internals}.
3321 @item -foptimize-sibling-calls
3322 @opindex foptimize-sibling-calls
3323 Optimize sibling and tail recursive calls.
3327 This option generates traps for signed overflow on addition, subtraction,
3328 multiplication operations.
3332 Don't pay attention to the @code{inline} keyword. Normally this option
3333 is used to keep the compiler from expanding any functions inline.
3334 Note that if you are not optimizing, no functions can be expanded inline.
3336 @item -finline-functions
3337 @opindex finline-functions
3338 Integrate all simple functions into their callers. The compiler
3339 heuristically decides which functions are simple enough to be worth
3340 integrating in this way.
3342 If all calls to a given function are integrated, and the function is
3343 declared @code{static}, then the function is normally not output as
3344 assembler code in its own right.
3346 @item -finline-limit=@var{n}
3347 @opindex finline-limit
3348 By default, gcc limits the size of functions that can be inlined. This flag
3349 allows the control of this limit for functions that are explicitly marked as
3350 inline (ie marked with the inline keyword or defined within the class
3351 definition in c++). @var{n} is the size of functions that can be inlined in
3352 number of pseudo instructions (not counting parameter handling). The default
3353 value of @var{n} is 600.
3354 Increasing this value can result in more inlined code at
3355 the cost of compilation time and memory consumption. Decreasing usually makes
3356 the compilation faster and less code will be inlined (which presumably
3357 means slower programs). This option is particularly useful for programs that
3358 use inlining heavily such as those based on recursive templates with C++.
3360 @emph{Note:} pseudo instruction represents, in this particular context, an
3361 abstract measurement of function's size. In no way, it represents a count
3362 of assembly instructions and as such its exact meaning might change from one
3363 release to an another.
3365 @item -fkeep-inline-functions
3366 @opindex fkeep-inline-functions
3367 Even if all calls to a given function are integrated, and the function
3368 is declared @code{static}, nevertheless output a separate run-time
3369 callable version of the function. This switch does not affect
3370 @code{extern inline} functions.
3372 @item -fkeep-static-consts
3373 @opindex fkeep-static-consts
3374 Emit variables declared @code{static const} when optimization isn't turned
3375 on, even if the variables aren't referenced.
3377 GCC enables this option by default. If you want to force the compiler to
3378 check if the variable was referenced, regardless of whether or not
3379 optimization is turned on, use the @option{-fno-keep-static-consts} option.
3381 @item -fmerge-constants
3382 Attempt to merge identical constants (string constants and floating point
3383 constants) accross compilation units.
3385 This option is default for optimized compilation if assembler and linker
3386 support it. Use @option{-fno-merge-constants} to inhibit this behavior.
3388 @item -fmerge-all-constants
3389 Attempt to merge identical constants and identical variables.
3391 This option implies @option{-fmerge-constants}. In addition to
3392 @option{-fmerge-constants} this considers e.g. even constant initialized
3393 arrays or initialized constant variables with integral or floating point
3394 types. Languages like C or C++ require each non-automatic variable to
3395 have distinct location, so using this option will result in non-conforming
3398 @item -fno-function-cse
3399 @opindex fno-function-cse
3400 Do not put function addresses in registers; make each instruction that
3401 calls a constant function contain the function's address explicitly.
3403 This option results in less efficient code, but some strange hacks
3404 that alter the assembler output may be confused by the optimizations
3405 performed when this option is not used.
3409 Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, and @*
3410 @option{-fno-trapping-math}.
3412 This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
3414 This option should never be turned on by any @option{-O} option since
3415 it can result in incorrect output for programs which depend on
3416 an exact implementation of IEEE or ISO rules/specifications for
3419 @item -fno-math-errno
3420 @opindex fno-math-errno
3421 Do not set ERRNO after calling math functions that are executed
3422 with a single instruction, e.g., sqrt. A program that relies on
3423 IEEE exceptions for math error handling may want to use this flag
3424 for speed while maintaining IEEE arithmetic compatibility.
3426 This option should never be turned on by any @option{-O} option since
3427 it can result in incorrect output for programs which depend on
3428 an exact implementation of IEEE or ISO rules/specifications for
3431 The default is @option{-fmath-errno}.
3433 @item -funsafe-math-optimizations
3434 @opindex funsafe-math-optimizations
3435 Allow optimizations for floating-point arithmetic that (a) assume
3436 that arguments and results are valid and (b) may violate IEEE or
3437 ANSI standards. When used at link-time, it may include libraries
3438 or startup files that change the default FPU control word or other
3439 similar optimizations.
3441 This option should never be turned on by any @option{-O} option since
3442 it can result in incorrect output for programs which depend on
3443 an exact implementation of IEEE or ISO rules/specifications for
3446 The default is @option{-fno-unsafe-math-optimizations}.
3448 @item -fno-trapping-math
3449 @opindex fno-trapping-math
3450 Compile code assuming that floating-point operations cannot generate
3451 user-visible traps. Setting this option may allow faster code
3452 if one relies on ``non-stop'' IEEE arithmetic, for example.
3454 This option should never be turned on by any @option{-O} option since
3455 it can result in incorrect output for programs which depend on
3456 an exact implementation of IEEE or ISO rules/specifications for
3459 The default is @option{-ftrapping-math}.
3461 @item -fno-zero-initialized-in-bss
3462 @opindex fno-zero-initialized-in-bss
3463 If the target supports a BSS section, GCC by default puts variables that
3464 are initialized to zero into BSS@. This can save space in the resulting
3467 This option turns off this behavior because some programs explicitly
3468 rely on variables going to the data section. E.g., so that the
3469 resulting executable can find the beginning of that section and/or make
3470 assumptions based on that.
3472 The default is @option{-fzero-initialized-in-bss}.
3475 The following options control specific optimizations. The @option{-O2}
3476 option turns on all of these optimizations except @option{-funroll-loops}
3477 and @option{-funroll-all-loops}. On most machines, the @option{-O} option
3478 turns on the @option{-fthread-jumps} and @option{-fdelayed-branch} options,
3479 but specific machines may handle it differently.
3481 You can use the following flags in the rare cases when ``fine-tuning''
3482 of optimizations to be performed is desired.
3484 Not all of the optimizations performed by GCC have @option{-f} options
3488 @item -fstrength-reduce
3489 @opindex fstrength-reduce
3490 Perform the optimizations of loop strength reduction and
3491 elimination of iteration variables.
3493 @item -fthread-jumps
3494 @opindex fthread-jumps
3495 Perform optimizations where we check to see if a jump branches to a
3496 location where another comparison subsumed by the first is found. If
3497 so, the first branch is redirected to either the destination of the
3498 second branch or a point immediately following it, depending on whether
3499 the condition is known to be true or false.
3501 @item -fcse-follow-jumps
3502 @opindex fcse-follow-jumps
3503 In common subexpression elimination, scan through jump instructions
3504 when the target of the jump is not reached by any other path. For
3505 example, when CSE encounters an @code{if} statement with an
3506 @code{else} clause, CSE will follow the jump when the condition
3509 @item -fcse-skip-blocks
3510 @opindex fcse-skip-blocks
3511 This is similar to @option{-fcse-follow-jumps}, but causes CSE to
3512 follow jumps which conditionally skip over blocks. When CSE
3513 encounters a simple @code{if} statement with no else clause,
3514 @option{-fcse-skip-blocks} causes CSE to follow the jump around the
3515 body of the @code{if}.
3517 @item -frerun-cse-after-loop
3518 @opindex frerun-cse-after-loop
3519 Re-run common subexpression elimination after loop optimizations has been
3522 @item -frerun-loop-opt
3523 @opindex frerun-loop-opt
3524 Run the loop optimizer twice.
3528 Perform a global common subexpression elimination pass.
3529 This pass also performs global constant and copy propagation.
3531 @emph{Note:} When compiling a program using computed gotos, a GCC
3532 extension, you may get better runtime performance if you disable
3533 the global common subexpression elmination pass by adding
3534 @option{-fno-gcse} to the command line.
3538 When @option{-fgcse-lm} is enabled, global common subexpression elimination will
3539 attempt to move loads which are only killed by stores into themselves. This
3540 allows a loop containing a load/store sequence to be changed to a load outside
3541 the loop, and a copy/store within the loop.
3545 When @option{-fgcse-sm} is enabled, A store motion pass is run after global common
3546 subexpression elimination. This pass will attempt to move stores out of loops.
3547 When used in conjunction with @option{-fgcse-lm}, loops containing a load/store sequence
3548 can be changed to a load before the loop and a store after the loop.
3550 @item -floop-optimize
3551 @opindex floop-optimize
3552 Perform loop optimizations: move constant expressions out of loops, simplify
3553 exit test conditions and optionally do strength-reduction and loop unrolling as
3556 @item -fcrossjumping
3557 @opindex crossjumping
3558 Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
3559 resulting code may or may not perform better than without cross-jumping.
3561 @item -fif-conversion
3562 @opindex if-conversion
3563 Attempt to transform conditional jumps into branch-less equivalents. This
3564 include use of conditional moves, min, max, set flags and abs instructions, and
3565 some tricks doable by standard arithmetics. The use of conditional execution
3566 on chips where it is available is controlled by @code{if-conversion2}.
3568 @item -fif-conversion2
3569 @opindex if-conversion2
3570 Use conditional execution (where available) to transform conditional jumps into
3571 branch-less equivalents.
3573 @item -fdelete-null-pointer-checks
3574 @opindex fdelete-null-pointer-checks
3575 Use global dataflow analysis to identify and eliminate useless checks
3576 for null pointers. The compiler assumes that dereferencing a null
3577 pointer would have halted the program. If a pointer is checked after
3578 it has already been dereferenced, it cannot be null.
3580 In some environments, this assumption is not true, and programs can
3581 safely dereference null pointers. Use
3582 @option{-fno-delete-null-pointer-checks} to disable this optimization
3583 for programs which depend on that behavior.
3585 @item -fexpensive-optimizations
3586 @opindex fexpensive-optimizations
3587 Perform a number of minor optimizations that are relatively expensive.
3589 @item -foptimize-register-move
3591 @opindex foptimize-register-move
3593 Attempt to reassign register numbers in move instructions and as
3594 operands of other simple instructions in order to maximize the amount of
3595 register tying. This is especially helpful on machines with two-operand
3596 instructions. GCC enables this optimization by default with @option{-O2}
3599 Note @option{-fregmove} and @option{-foptimize-register-move} are the same
3602 @item -fdelayed-branch
3603 @opindex fdelayed-branch
3604 If supported for the target machine, attempt to reorder instructions
3605 to exploit instruction slots available after delayed branch
3608 @item -fschedule-insns
3609 @opindex fschedule-insns
3610 If supported for the target machine, attempt to reorder instructions to
3611 eliminate execution stalls due to required data being unavailable. This
3612 helps machines that have slow floating point or memory load instructions
3613 by allowing other instructions to be issued until the result of the load
3614 or floating point instruction is required.
3616 @item -fschedule-insns2
3617 @opindex fschedule-insns2
3618 Similar to @option{-fschedule-insns}, but requests an additional pass of
3619 instruction scheduling after register allocation has been done. This is
3620 especially useful on machines with a relatively small number of
3621 registers and where memory load instructions take more than one cycle.
3623 @item -ffunction-sections
3624 @itemx -fdata-sections
3625 @opindex ffunction-sections
3626 @opindex fdata-sections
3627 Place each function or data item into its own section in the output
3628 file if the target supports arbitrary sections. The name of the
3629 function or the name of the data item determines the section's name
3632 Use these options on systems where the linker can perform optimizations
3633 to improve locality of reference in the instruction space. HPPA
3634 processors running HP-UX and Sparc processors running Solaris 2 have
3635 linkers with such optimizations. Other systems using the ELF object format
3636 as well as AIX may have these optimizations in the future.
3638 Only use these options when there are significant benefits from doing
3639 so. When you specify these options, the assembler and linker will
3640 create larger object and executable files and will also be slower.
3641 You will not be able to use @code{gprof} on all systems if you
3642 specify this option and you may have problems with debugging if
3643 you specify both this option and @option{-g}.
3645 @item -fcaller-saves
3646 @opindex fcaller-saves
3647 Enable values to be allocated in registers that will be clobbered by
3648 function calls, by emitting extra instructions to save and restore the
3649 registers around such calls. Such allocation is done only when it
3650 seems to result in better code than would otherwise be produced.
3652 This option is always enabled by default on certain machines, usually
3653 those which have no call-preserved registers to use instead.
3655 For all machines, optimization level 2 and higher enables this flag by
3660 Perform tail duplication to enlarge superblock size. This transformation
3661 simplifies the control flow of the function allowing other optimizations to do
3664 @item -funroll-loops
3665 @opindex funroll-loops
3666 Unroll loops whose number of iterations can be determined at compile
3667 time or upon entry to the loop. @option{-funroll-loops} implies both
3668 @option{-fstrength-reduce} and @option{-frerun-cse-after-loop}. This
3669 option makes code larger, and may or may not make it run faster.
3671 @item -funroll-all-loops
3672 @opindex funroll-all-loops
3673 Unroll all loops, even if their number of iterations is uncertain when
3674 the loop is entered. This usually makes programs run more slowly.
3675 @option{-funroll-all-loops} implies the same options as
3676 @option{-funroll-loops},
3678 @item -fprefetch-loop-arrays
3679 @opindex fprefetch-loop-arrays
3680 If supported by the target machine, generate instructions to prefetch
3681 memory to improve the performance of loops that access large arrays.
3683 @item -fmove-all-movables
3684 @opindex fmove-all-movables
3685 Forces all invariant computations in loops to be moved
3688 @item -freduce-all-givs
3689 @opindex freduce-all-givs
3690 Forces all general-induction variables in loops to be
3693 @emph{Note:} When compiling programs written in Fortran,
3694 @option{-fmove-all-movables} and @option{-freduce-all-givs} are enabled
3695 by default when you use the optimizer.
3697 These options may generate better or worse code; results are highly
3698 dependent on the structure of loops within the source code.
3700 These two options are intended to be removed someday, once
3701 they have helped determine the efficacy of various
3702 approaches to improving loop optimizations.
3704 Please let us (@w{@email{gcc@@gcc.gnu.org}} and @w{@email{fortran@@gnu.org}})
3705 know how use of these options affects
3706 the performance of your production code.
3707 We're very interested in code that runs @emph{slower}
3708 when these options are @emph{enabled}.
3711 @itemx -fno-peephole2
3712 @opindex fno-peephole
3713 @opindex fno-peephole2
3714 Disable any machine-specific peephole optimizations. The difference
3715 between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
3716 are implemented in the compiler; some targets use one, some use the
3717 other, a few use both.
3719 @item -fbranch-probabilities
3720 @opindex fbranch-probabilities
3721 After running a program compiled with @option{-fprofile-arcs}
3722 (@pxref{Debugging Options,, Options for Debugging Your Program or
3723 @command{gcc}}), you can compile it a second time using
3724 @option{-fbranch-probabilities}, to improve optimizations based on
3725 the number of times each branch was taken. When the program
3726 compiled with @option{-fprofile-arcs} exits it saves arc execution
3727 counts to a file called @file{@var{sourcename}.da} for each source
3728 file The information in this data file is very dependent on the
3729 structure of the generated code, so you must use the same source code
3730 and the same optimization options for both compilations.
3732 With @option{-fbranch-probabilities}, GCC puts a @samp{REG_EXEC_COUNT}
3733 note on the first instruction of each basic block, and a
3734 @samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
3735 These can be used to improve optimization. Currently, they are only
3736 used in one place: in @file{reorg.c}, instead of guessing which path a
3737 branch is mostly to take, the @samp{REG_BR_PROB} values are used to
3738 exactly determine which path is taken more often.
3740 @item -fno-guess-branch-probability
3741 @opindex fno-guess-branch-probability
3742 Do not guess branch probabilities using a randomized model.
3744 Sometimes gcc will opt to use a randomized model to guess branch
3745 probabilities, when none are available from either profiling feedback
3746 (@option{-fprofile-arcs}) or @samp{__builtin_expect}. This means that
3747 different runs of the compiler on the same program may produce different
3750 In a hard real-time system, people don't want different runs of the
3751 compiler to produce code that has different behavior; minimizing
3752 non-determinism is of paramount import. This switch allows users to
3753 reduce non-determinism, possibly at the expense of inferior
3756 @item -freorder-blocks
3757 @opindex freorder-blocks
3758 Reorder basic blocks in the compiled function in order to reduce number of
3759 taken branches and improve code locality.
3761 @item -freorder-functions
3762 @opindex freorder-functions
3763 Reorder basic blocks in the compiled function in order to reduce number of
3764 taken branches and improve code locality. This is implemented by using special
3765 subsections @code{text.hot} for most frequently executed functions and
3766 @code{text.unlikely} for unlikely executed functions. Reordering is done by
3767 the linker so object file format must support named sections and linker must
3768 place them in resonable way.
3770 Also profile feedback must be available in to make this option effective. See
3771 @option{-fprofile-arcs} for details.
3773 @item -fstrict-aliasing
3774 @opindex fstrict-aliasing
3775 Allows the compiler to assume the strictest aliasing rules applicable to
3776 the language being compiled. For C (and C++), this activates
3777 optimizations based on the type of expressions. In particular, an
3778 object of one type is assumed never to reside at the same address as an
3779 object of a different type, unless the types are almost the same. For
3780 example, an @code{unsigned int} can alias an @code{int}, but not a
3781 @code{void*} or a @code{double}. A character type may alias any other
3784 Pay special attention to code like this:
3797 The practice of reading from a different union member than the one most
3798 recently written to (called ``type-punning'') is common. Even with
3799 @option{-fstrict-aliasing}, type-punning is allowed, provided the memory
3800 is accessed through the union type. So, the code above will work as
3801 expected. However, this code might not:
3812 Every language that wishes to perform language-specific alias analysis
3813 should define a function that computes, given an @code{tree}
3814 node, an alias set for the node. Nodes in different alias sets are not
3815 allowed to alias. For an example, see the C front-end function
3816 @code{c_get_alias_set}.
3818 For all machines, optimization level 2 and higher enables this flag by
3821 @item -falign-functions
3822 @itemx -falign-functions=@var{n}
3823 @opindex falign-functions
3824 Align the start of functions to the next power-of-two greater than
3825 @var{n}, skipping up to @var{n} bytes. For instance,
3826 @option{-falign-functions=32} aligns functions to the next 32-byte
3827 boundary, but @option{-falign-functions=24} would align to the next
3828 32-byte boundary only if this can be done by skipping 23 bytes or less.
3830 @option{-fno-align-functions} and @option{-falign-functions=1} are
3831 equivalent and mean that functions will not be aligned.
3833 Some assemblers only support this flag when @var{n} is a power of two;
3834 in that case, it is rounded up.
3836 If @var{n} is not specified, use a machine-dependent default.
3838 @item -falign-labels
3839 @itemx -falign-labels=@var{n}
3840 @opindex falign-labels
3841 Align all branch targets to a power-of-two boundary, skipping up to
3842 @var{n} bytes like @option{-falign-functions}. This option can easily
3843 make code slower, because it must insert dummy operations for when the
3844 branch target is reached in the usual flow of the code.
3846 If @option{-falign-loops} or @option{-falign-jumps} are applicable and
3847 are greater than this value, then their values are used instead.
3849 If @var{n} is not specified, use a machine-dependent default which is
3850 very likely to be @samp{1}, meaning no alignment.
3853 @itemx -falign-loops=@var{n}
3854 @opindex falign-loops
3855 Align loops to a power-of-two boundary, skipping up to @var{n} bytes
3856 like @option{-falign-functions}. The hope is that the loop will be
3857 executed many times, which will make up for any execution of the dummy
3860 If @var{n} is not specified, use a machine-dependent default.
3863 @itemx -falign-jumps=@var{n}
3864 @opindex falign-jumps
3865 Align branch targets to a power-of-two boundary, for branch targets
3866 where the targets can only be reached by jumping, skipping up to @var{n}
3867 bytes like @option{-falign-functions}. In this case, no dummy operations
3870 If @var{n} is not specified, use a machine-dependent default.
3874 Perform optimizations in static single assignment form. Each function's
3875 flow graph is translated into SSA form, optimizations are performed, and
3876 the flow graph is translated back from SSA form. Users should not
3877 specify this option, since it is not yet ready for production use.
3881 Perform Sparse Conditional Constant Propagation in SSA form. Requires
3882 @option{-fssa}. Like @option{-fssa}, this is an experimental feature.
3886 Perform aggressive dead-code elimination in SSA form. Requires @option{-fssa}.
3887 Like @option{-fssa}, this is an experimental feature.
3889 @item -fsingle-precision-constant
3890 @opindex fsingle-precision-constant
3891 Treat floating point constant as single precision constant instead of
3892 implicitly converting it to double precision constant.
3894 @item -frename-registers
3895 @opindex frename-registers
3896 Attempt to avoid false dependencies in scheduled code by making use
3897 of registers left over after register allocation. This optimization
3898 will most benefit processors with lots of registers. It can, however,
3899 make debugging impossible, since variables will no longer stay in
3900 a ``home register''.
3902 @item -fno-cprop-registers
3903 @opindex fno-cprop-registers
3904 After register allocation and post-register allocation instruction splitting,
3905 we perform a copy-propagation pass to try to reduce scheduling dependencies
3906 and occasionally eliminate the copy.
3908 @item --param @var{name}=@var{value}
3910 In some places, GCC uses various constants to control the amount of
3911 optimization that is done. For example, GCC will not inline functions
3912 that contain more that a certain number of instructions. You can
3913 control some of these constants on the command-line using the
3914 @option{--param} option.
3916 In each case, the @var{value} is an integer. The allowable choices for
3917 @var{name} are given in the following table:
3920 @item max-delay-slot-insn-search
3921 The maximum number of instructions to consider when looking for an
3922 instruction to fill a delay slot. If more than this arbitrary number of
3923 instructions is searched, the time savings from filling the delay slot
3924 will be minimal so stop searching. Increasing values mean more
3925 aggressive optimization, making the compile time increase with probably
3926 small improvement in executable run time.
3928 @item max-delay-slot-live-search
3929 When trying to fill delay slots, the maximum number of instructions to
3930 consider when searching for a block with valid live register
3931 information. Increasing this arbitrarily chosen value means more
3932 aggressive optimization, increasing the compile time. This parameter
3933 should be removed when the delay slot code is rewritten to maintain the
3936 @item max-gcse-memory
3937 The approximate maximum amount of memory that will be allocated in
3938 order to perform the global common subexpression elimination
3939 optimization. If more memory than specified is required, the
3940 optimization will not be done.
3942 @item max-gcse-passes
3943 The maximum number of passes of GCSE to run.
3945 @item max-pending-list-length
3946 The maximum number of pending dependencies scheduling will allow
3947 before flushing the current state and starting over. Large functions
3948 with few branches or calls can create excessively large lists which
3949 needlessly consume memory and resources.
3951 @item max-inline-insns
3952 If an function contains more than this many instructions, it
3953 will not be inlined. This option is precisely equivalent to
3954 @option{-finline-limit}.
3956 @item max-unrolled-insns
3957 The maximum number of instructions that a loop should have if that loop
3958 is unrolled, and if the loop is unrolled, it determines how many times
3959 the loop code is unrolled.
3961 @item hot-bb-count-fraction
3962 Select fraction of the maximal count of repetitions of basic block in program
3963 given basic block needs to have to be considered hot.
3965 @item hot-bb-frequency-fraction
3966 Select fraction of the maximal frequency of executions of basic block in
3967 function given basic block needs to have to be considered hot
3969 @item tracer-dynamic-coverage
3970 @itemx tracer-dynamic-coverage-feedback
3972 This value is used to limit superblock formation once given percentage of
3973 executed instructions is covered. This limits unnecesary code size expansion.
3975 The @option{tracer-dynamic-coverage-feedback} is used only when profile
3976 feedback is available. The real profiles (as opposed to statically estimated
3977 ones) are much less balanced allowing the threshold to be larger value.
3979 @item tracer-max-code-growth
3980 Stop tail duplication once code growth has reached given percentage. This is
3981 rather hokey argument, as most of the duplicates will be elliminated later in
3982 cross jumping, so it may be set to much higher values than is the desired code
3985 @item tracer-min-branch-ratio
3987 Stop reverse growth when the reverse probability of best edge is less than this
3988 threshold (in percent).
3990 @item tracer-min-branch-ratio
3991 @itemx tracer-min-branch-ratio-feedback
3993 Stop forward growth if the best edge do have probability lower than this
3996 Similary to @option{tracer-dynamic-coverage} two values are present, one for
3997 compilation for profile feedback and one for compilation without. The value
3998 for compilation with profile feedback needs to be more conservative (higher) in
3999 order to make tracer effective.
4004 @node Preprocessor Options
4005 @section Options Controlling the Preprocessor
4006 @cindex preprocessor options
4007 @cindex options, preprocessor
4009 These options control the C preprocessor, which is run on each C source
4010 file before actual compilation.
4012 If you use the @option{-E} option, nothing is done except preprocessing.
4013 Some of these options make sense only together with @option{-E} because
4014 they cause the preprocessor output to be unsuitable for actual
4018 You can use @option{-Wp,@var{option}} to bypass the compiler driver
4019 and pass @var{option} directly through to the preprocessor. If
4020 @var{option} contains commas, it is split into multiple options at the
4021 commas. However, many options are modified, translated or interpreted
4022 by the compiler driver before being passed to the preprocessor, and
4023 @option{-Wp} forcibly bypasses this phase. The preprocessor's direct
4024 interface is undocumented and subject to change, so whenever possible
4025 you should avoid using @option{-Wp} and let the driver handle the
4028 @include cppopts.texi
4030 @node Assembler Options
4031 @section Passing Options to the Assembler
4033 @c prevent bad page break with this line
4034 You can pass options to the assembler.
4037 @item -Wa,@var{option}
4039 Pass @var{option} as an option to the assembler. If @var{option}
4040 contains commas, it is split into multiple options at the commas.
4044 @section Options for Linking
4045 @cindex link options
4046 @cindex options, linking
4048 These options come into play when the compiler links object files into
4049 an executable output file. They are meaningless if the compiler is
4050 not doing a link step.
4054 @item @var{object-file-name}
4055 A file name that does not end in a special recognized suffix is
4056 considered to name an object file or library. (Object files are
4057 distinguished from libraries by the linker according to the file
4058 contents.) If linking is done, these object files are used as input
4067 If any of these options is used, then the linker is not run, and
4068 object file names should not be used as arguments. @xref{Overall
4072 @item -l@var{library}
4073 @itemx -l @var{library}
4075 Search the library named @var{library} when linking. (The second
4076 alternative with the library as a separate argument is only for
4077 POSIX compliance and is not recommended.)
4079 It makes a difference where in the command you write this option; the
4080 linker searches and processes libraries and object files in the order they
4081 are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
4082 after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
4083 to functions in @samp{z}, those functions may not be loaded.
4085 The linker searches a standard list of directories for the library,
4086 which is actually a file named @file{lib@var{library}.a}. The linker
4087 then uses this file as if it had been specified precisely by name.
4089 The directories searched include several standard system directories
4090 plus any that you specify with @option{-L}.
4092 Normally the files found this way are library files---archive files
4093 whose members are object files. The linker handles an archive file by
4094 scanning through it for members which define symbols that have so far
4095 been referenced but not defined. But if the file that is found is an
4096 ordinary object file, it is linked in the usual fashion. The only
4097 difference between using an @option{-l} option and specifying a file name
4098 is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
4099 and searches several directories.
4103 You need this special case of the @option{-l} option in order to
4104 link an Objective-C program.
4107 @opindex nostartfiles
4108 Do not use the standard system startup files when linking.
4109 The standard system libraries are used normally, unless @option{-nostdlib}
4110 or @option{-nodefaultlibs} is used.
4112 @item -nodefaultlibs
4113 @opindex nodefaultlibs
4114 Do not use the standard system libraries when linking.
4115 Only the libraries you specify will be passed to the linker.
4116 The standard startup files are used normally, unless @option{-nostartfiles}
4117 is used. The compiler may generate calls to memcmp, memset, and memcpy
4118 for System V (and ISO C) environments or to bcopy and bzero for
4119 BSD environments. These entries are usually resolved by entries in
4120 libc. These entry points should be supplied through some other
4121 mechanism when this option is specified.
4125 Do not use the standard system startup files or libraries when linking.
4126 No startup files and only the libraries you specify will be passed to
4127 the linker. The compiler may generate calls to memcmp, memset, and memcpy
4128 for System V (and ISO C) environments or to bcopy and bzero for
4129 BSD environments. These entries are usually resolved by entries in
4130 libc. These entry points should be supplied through some other
4131 mechanism when this option is specified.
4133 @cindex @option{-lgcc}, use with @option{-nostdlib}
4134 @cindex @option{-nostdlib} and unresolved references
4135 @cindex unresolved references and @option{-nostdlib}
4136 @cindex @option{-lgcc}, use with @option{-nodefaultlibs}
4137 @cindex @option{-nodefaultlibs} and unresolved references
4138 @cindex unresolved references and @option{-nodefaultlibs}
4139 One of the standard libraries bypassed by @option{-nostdlib} and
4140 @option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
4141 that GCC uses to overcome shortcomings of particular machines, or special
4142 needs for some languages.
4143 (@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
4144 Collection (GCC) Internals},
4145 for more discussion of @file{libgcc.a}.)
4146 In most cases, you need @file{libgcc.a} even when you want to avoid
4147 other standard libraries. In other words, when you specify @option{-nostdlib}
4148 or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
4149 This ensures that you have no unresolved references to internal GCC
4150 library subroutines. (For example, @samp{__main}, used to ensure C++
4151 constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
4152 GNU Compiler Collection (GCC) Internals}.)
4156 Remove all symbol table and relocation information from the executable.
4160 On systems that support dynamic linking, this prevents linking with the shared
4161 libraries. On other systems, this option has no effect.
4165 Produce a shared object which can then be linked with other objects to
4166 form an executable. Not all systems support this option. For predictable
4167 results, you must also specify the same set of options that were used to
4168 generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
4169 when you specify this option.@footnote{On some systems, @samp{gcc -shared}
4170 needs to build supplementary stub code for constructors to work. On
4171 multi-libbed systems, @samp{gcc -shared} must select the correct support
4172 libraries to link against. Failing to supply the correct flags may lead
4173 to subtle defects. Supplying them in cases where they are not necessary
4176 @item -shared-libgcc
4177 @itemx -static-libgcc
4178 @opindex shared-libgcc
4179 @opindex static-libgcc
4180 On systems that provide @file{libgcc} as a shared library, these options
4181 force the use of either the shared or static version respectively.
4182 If no shared version of @file{libgcc} was built when the compiler was
4183 configured, these options have no effect.
4185 There are several situations in which an application should use the
4186 shared @file{libgcc} instead of the static version. The most common
4187 of these is when the application wishes to throw and catch exceptions
4188 across different shared libraries. In that case, each of the libraries
4189 as well as the application itself should use the shared @file{libgcc}.
4191 Therefore, the G++ and GCJ drivers automatically add
4192 @option{-shared-libgcc} whenever you build a shared library or a main
4193 executable, because C++ and Java programs typically use exceptions, so
4194 this is the right thing to do.
4196 If, instead, you use the GCC driver to create shared libraries, you may
4197 find that they will not always be linked with the shared @file{libgcc}.
4198 If GCC finds, at its configuration time, that you have a GNU linker that
4199 does not support option @option{--eh-frame-hdr}, it will link the shared
4200 version of @file{libgcc} into shared libraries by default. Otherwise,
4201 it will take advantage of the linker and optimize away the linking with
4202 the shared version of @file{libgcc}, linking with the static version of
4203 libgcc by default. This allows exceptions to propagate through such
4204 shared libraries, without incurring relocation costs at library load
4207 However, if a library or main executable is supposed to throw or catch
4208 exceptions, you must link it using the G++ or GCJ driver, as appropriate
4209 for the languages used in the program, or using the option
4210 @option{-shared-libgcc}, such that it is linked with the shared
4215 Bind references to global symbols when building a shared object. Warn
4216 about any unresolved references (unless overridden by the link editor
4217 option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
4220 @item -Xlinker @var{option}
4222 Pass @var{option} as an option to the linker. You can use this to
4223 supply system-specific linker options which GCC does not know how to
4226 If you want to pass an option that takes an argument, you must use
4227 @option{-Xlinker} twice, once for the option and once for the argument.
4228 For example, to pass @option{-assert definitions}, you must write
4229 @samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
4230 @option{-Xlinker "-assert definitions"}, because this passes the entire
4231 string as a single argument, which is not what the linker expects.
4233 @item -Wl,@var{option}
4235 Pass @var{option} as an option to the linker. If @var{option} contains
4236 commas, it is split into multiple options at the commas.
4238 @item -u @var{symbol}
4240 Pretend the symbol @var{symbol} is undefined, to force linking of
4241 library modules to define it. You can use @option{-u} multiple times with
4242 different symbols to force loading of additional library modules.
4245 @node Directory Options
4246 @section Options for Directory Search
4247 @cindex directory options
4248 @cindex options, directory search
4251 These options specify directories to search for header files, for
4252 libraries and for parts of the compiler:
4257 Add the directory @var{dir} to the head of the list of directories to be
4258 searched for header files. This can be used to override a system header
4259 file, substituting your own version, since these directories are
4260 searched before the system header file directories. However, you should
4261 not use this option to add directories that contain vendor-supplied
4262 system header files (use @option{-isystem} for that). If you use more than
4263 one @option{-I} option, the directories are scanned in left-to-right
4264 order; the standard system directories come after.
4266 If a standard system include directory, or a directory specified with
4267 @option{-isystem}, is also specified with @option{-I}, it will be
4268 searched only in the position requested by @option{-I}. Also, it will
4269 not be considered a system include directory. If that directory really
4270 does contain system headers, there is a good chance that they will
4271 break. For instance, if GCC's installation procedure edited the headers
4272 in @file{/usr/include} to fix bugs, @samp{-I/usr/include} will cause the
4273 original, buggy headers to be found instead of the corrected ones. GCC
4274 will issue a warning when a system include directory is hidden in this
4279 Any directories you specify with @option{-I} options before the @option{-I-}
4280 option are searched only for the case of @samp{#include "@var{file}"};
4281 they are not searched for @samp{#include <@var{file}>}.
4283 If additional directories are specified with @option{-I} options after
4284 the @option{-I-}, these directories are searched for all @samp{#include}
4285 directives. (Ordinarily @emph{all} @option{-I} directories are used
4288 In addition, the @option{-I-} option inhibits the use of the current
4289 directory (where the current input file came from) as the first search
4290 directory for @samp{#include "@var{file}"}. There is no way to
4291 override this effect of @option{-I-}. With @option{-I.} you can specify
4292 searching the directory which was current when the compiler was
4293 invoked. That is not exactly the same as what the preprocessor does
4294 by default, but it is often satisfactory.
4296 @option{-I-} does not inhibit the use of the standard system directories
4297 for header files. Thus, @option{-I-} and @option{-nostdinc} are
4302 Add directory @var{dir} to the list of directories to be searched
4305 @item -B@var{prefix}
4307 This option specifies where to find the executables, libraries,
4308 include files, and data files of the compiler itself.
4310 The compiler driver program runs one or more of the subprograms
4311 @file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
4312 @var{prefix} as a prefix for each program it tries to run, both with and
4313 without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
4315 For each subprogram to be run, the compiler driver first tries the
4316 @option{-B} prefix, if any. If that name is not found, or if @option{-B}
4317 was not specified, the driver tries two standard prefixes, which are
4318 @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc-lib/}. If neither of
4319 those results in a file name that is found, the unmodified program
4320 name is searched for using the directories specified in your
4321 @env{PATH} environment variable.
4323 The compiler will check to see if the path provided by the @option{-B}
4324 refers to a directory, and if necessary it will add a directory
4325 separator character at the end of the path.
4327 @option{-B} prefixes that effectively specify directory names also apply
4328 to libraries in the linker, because the compiler translates these
4329 options into @option{-L} options for the linker. They also apply to
4330 includes files in the preprocessor, because the compiler translates these
4331 options into @option{-isystem} options for the preprocessor. In this case,
4332 the compiler appends @samp{include} to the prefix.
4334 The run-time support file @file{libgcc.a} can also be searched for using
4335 the @option{-B} prefix, if needed. If it is not found there, the two
4336 standard prefixes above are tried, and that is all. The file is left
4337 out of the link if it is not found by those means.
4339 Another way to specify a prefix much like the @option{-B} prefix is to use
4340 the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
4343 As a special kludge, if the path provided by @option{-B} is
4344 @file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
4345 9, then it will be replaced by @file{[dir/]include}. This is to help
4346 with boot-strapping the compiler.
4348 @item -specs=@var{file}
4350 Process @var{file} after the compiler reads in the standard @file{specs}
4351 file, in order to override the defaults that the @file{gcc} driver
4352 program uses when determining what switches to pass to @file{cc1},
4353 @file{cc1plus}, @file{as}, @file{ld}, etc. More than one
4354 @option{-specs=@var{file}} can be specified on the command line, and they
4355 are processed in order, from left to right.
4361 @section Specifying subprocesses and the switches to pass to them
4363 @command{gcc} is a driver program. It performs its job by invoking a
4364 sequence of other programs to do the work of compiling, assembling and
4365 linking. GCC interprets its command-line parameters and uses these to
4366 deduce which programs it should invoke, and which command-line options
4367 it ought to place on their command lines. This behavior is controlled
4368 by @dfn{spec strings}. In most cases there is one spec string for each
4369 program that GCC can invoke, but a few programs have multiple spec
4370 strings to control their behavior. The spec strings built into GCC can
4371 be overridden by using the @option{-specs=} command-line switch to specify
4374 @dfn{Spec files} are plaintext files that are used to construct spec
4375 strings. They consist of a sequence of directives separated by blank
4376 lines. The type of directive is determined by the first non-whitespace
4377 character on the line and it can be one of the following:
4380 @item %@var{command}
4381 Issues a @var{command} to the spec file processor. The commands that can
4385 @item %include <@var{file}>
4387 Search for @var{file} and insert its text at the current point in the
4390 @item %include_noerr <@var{file}>
4391 @cindex %include_noerr
4392 Just like @samp{%include}, but do not generate an error message if the include
4393 file cannot be found.
4395 @item %rename @var{old_name} @var{new_name}
4397 Rename the spec string @var{old_name} to @var{new_name}.
4401 @item *[@var{spec_name}]:
4402 This tells the compiler to create, override or delete the named spec
4403 string. All lines after this directive up to the next directive or
4404 blank line are considered to be the text for the spec string. If this
4405 results in an empty string then the spec will be deleted. (Or, if the
4406 spec did not exist, then nothing will happened.) Otherwise, if the spec
4407 does not currently exist a new spec will be created. If the spec does
4408 exist then its contents will be overridden by the text of this
4409 directive, unless the first character of that text is the @samp{+}
4410 character, in which case the text will be appended to the spec.
4412 @item [@var{suffix}]:
4413 Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
4414 and up to the next directive or blank line are considered to make up the
4415 spec string for the indicated suffix. When the compiler encounters an
4416 input file with the named suffix, it will processes the spec string in
4417 order to work out how to compile that file. For example:
4424 This says that any input file whose name ends in @samp{.ZZ} should be
4425 passed to the program @samp{z-compile}, which should be invoked with the
4426 command-line switch @option{-input} and with the result of performing the
4427 @samp{%i} substitution. (See below.)
4429 As an alternative to providing a spec string, the text that follows a
4430 suffix directive can be one of the following:
4433 @item @@@var{language}
4434 This says that the suffix is an alias for a known @var{language}. This is
4435 similar to using the @option{-x} command-line switch to GCC to specify a
4436 language explicitly. For example:
4443 Says that .ZZ files are, in fact, C++ source files.
4446 This causes an error messages saying:
4449 @var{name} compiler not installed on this system.
4453 GCC already has an extensive list of suffixes built into it.
4454 This directive will add an entry to the end of the list of suffixes, but
4455 since the list is searched from the end backwards, it is effectively
4456 possible to override earlier entries using this technique.
4460 GCC has the following spec strings built into it. Spec files can
4461 override these strings or create their own. Note that individual
4462 targets can also add their own spec strings to this list.
4465 asm Options to pass to the assembler
4466 asm_final Options to pass to the assembler post-processor
4467 cpp Options to pass to the C preprocessor
4468 cc1 Options to pass to the C compiler
4469 cc1plus Options to pass to the C++ compiler
4470 endfile Object files to include at the end of the link
4471 link Options to pass to the linker
4472 lib Libraries to include on the command line to the linker
4473 libgcc Decides which GCC support library to pass to the linker
4474 linker Sets the name of the linker
4475 predefines Defines to be passed to the C preprocessor
4476 signed_char Defines to pass to CPP to say whether @code{char} is signed
4478 startfile Object files to include at the start of the link
4481 Here is a small example of a spec file:
4487 --start-group -lgcc -lc -leval1 --end-group %(old_lib)
4490 This example renames the spec called @samp{lib} to @samp{old_lib} and
4491 then overrides the previous definition of @samp{lib} with a new one.
4492 The new definition adds in some extra command-line options before
4493 including the text of the old definition.
4495 @dfn{Spec strings} are a list of command-line options to be passed to their
4496 corresponding program. In addition, the spec strings can contain
4497 @samp{%}-prefixed sequences to substitute variable text or to
4498 conditionally insert text into the command line. Using these constructs
4499 it is possible to generate quite complex command lines.
4501 Here is a table of all defined @samp{%}-sequences for spec
4502 strings. Note that spaces are not generated automatically around the
4503 results of expanding these sequences. Therefore you can concatenate them
4504 together or combine them with constant text in a single argument.
4508 Substitute one @samp{%} into the program name or argument.
4511 Substitute the name of the input file being processed.
4514 Substitute the basename of the input file being processed.
4515 This is the substring up to (and not including) the last period
4516 and not including the directory.
4519 This is the same as @samp{%b}, but include the file suffix (text after
4523 Marks the argument containing or following the @samp{%d} as a
4524 temporary file name, so that that file will be deleted if GCC exits
4525 successfully. Unlike @samp{%g}, this contributes no text to the
4528 @item %g@var{suffix}
4529 Substitute a file name that has suffix @var{suffix} and is chosen
4530 once per compilation, and mark the argument in the same way as
4531 @samp{%d}. To reduce exposure to denial-of-service attacks, the file
4532 name is now chosen in a way that is hard to predict even when previously
4533 chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
4534 might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
4535 the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
4536 treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
4537 was simply substituted with a file name chosen once per compilation,
4538 without regard to any appended suffix (which was therefore treated
4539 just like ordinary text), making such attacks more likely to succeed.
4541 @item %u@var{suffix}
4542 Like @samp{%g}, but generates a new temporary file name even if
4543 @samp{%u@var{suffix}} was already seen.
4545 @item %U@var{suffix}
4546 Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
4547 new one if there is no such last file name. In the absence of any
4548 @samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
4549 the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
4550 would involve the generation of two distinct file names, one
4551 for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
4552 simply substituted with a file name chosen for the previous @samp{%u},
4553 without regard to any appended suffix.
4555 @item %j@var{SUFFIX}
4556 Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
4557 writable, and if save-temps is off; otherwise, substitute the name
4558 of a temporary file, just like @samp{%u}. This temporary file is not
4559 meant for communication between processes, but rather as a junk
4562 @item %.@var{SUFFIX}
4563 Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
4564 when it is subsequently output with @samp{%*}. @var{SUFFIX} is
4565 terminated by the next space or %.
4568 Marks the argument containing or following the @samp{%w} as the
4569 designated output file of this compilation. This puts the argument
4570 into the sequence of arguments that @samp{%o} will substitute later.
4573 Substitutes the names of all the output files, with spaces
4574 automatically placed around them. You should write spaces
4575 around the @samp{%o} as well or the results are undefined.
4576 @samp{%o} is for use in the specs for running the linker.
4577 Input files whose names have no recognized suffix are not compiled
4578 at all, but they are included among the output files, so they will
4582 Substitutes the suffix for object files. Note that this is
4583 handled specially when it immediately follows @samp{%g, %u, or %U},
4584 because of the need for those to form complete file names. The
4585 handling is such that @samp{%O} is treated exactly as if it had already
4586 been substituted, except that @samp{%g, %u, and %U} do not currently
4587 support additional @var{suffix} characters following @samp{%O} as they would
4588 following, for example, @samp{.o}.
4591 Substitutes the standard macro predefinitions for the
4592 current target machine. Use this when running @code{cpp}.
4595 Like @samp{%p}, but puts @samp{__} before and after the name of each
4596 predefined macro, except for macros that start with @samp{__} or with
4597 @samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
4601 Substitute a @option{-iprefix} option made from @env{GCC_EXEC_PREFIX}.
4604 Current argument is the name of a library or startup file of some sort.
4605 Search for that file in a standard list of directories and substitute
4606 the full name found.
4609 Print @var{str} as an error message. @var{str} is terminated by a newline.
4610 Use this when inconsistent options are detected.
4613 Output @samp{-} if the input for the current command is coming from a pipe.
4616 Substitute the contents of spec string @var{name} at this point.
4619 Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
4621 @item %x@{@var{option}@}
4622 Accumulate an option for @samp{%X}.
4625 Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
4629 Output the accumulated assembler options specified by @option{-Wa}.
4632 Output the accumulated preprocessor options specified by @option{-Wp}.
4635 Substitute the major version number of GCC@.
4636 (For version 2.9.5, this is 2.)
4639 Substitute the minor version number of GCC@.
4640 (For version 2.9.5, this is 9.)
4643 Substitute the patch level number of GCC@.
4644 (For version 2.9.5, this is 5.)
4647 Process the @code{asm} spec. This is used to compute the
4648 switches to be passed to the assembler.
4651 Process the @code{asm_final} spec. This is a spec string for
4652 passing switches to an assembler post-processor, if such a program is
4656 Process the @code{link} spec. This is the spec for computing the
4657 command line passed to the linker. Typically it will make use of the
4658 @samp{%L %G %S %D and %E} sequences.
4661 Dump out a @option{-L} option for each directory that GCC believes might
4662 contain startup files. If the target supports multilibs then the
4663 current multilib directory will be prepended to each of these paths.
4666 Output the multilib directory with directory separators replaced with
4667 @samp{_}. If multilib directories are not set, or the multilib directory is
4668 @file{.} then this option emits nothing.
4671 Process the @code{lib} spec. This is a spec string for deciding which
4672 libraries should be included on the command line to the linker.
4675 Process the @code{libgcc} spec. This is a spec string for deciding
4676 which GCC support library should be included on the command line to the linker.
4679 Process the @code{startfile} spec. This is a spec for deciding which
4680 object files should be the first ones passed to the linker. Typically
4681 this might be a file named @file{crt0.o}.
4684 Process the @code{endfile} spec. This is a spec string that specifies
4685 the last object files that will be passed to the linker.
4688 Process the @code{cpp} spec. This is used to construct the arguments
4689 to be passed to the C preprocessor.
4692 Process the @code{signed_char} spec. This is intended to be used
4693 to tell cpp whether a char is signed. It typically has the definition:
4695 %@{funsigned-char:-D__CHAR_UNSIGNED__@}
4699 Process the @code{cc1} spec. This is used to construct the options to be
4700 passed to the actual C compiler (@samp{cc1}).
4703 Process the @code{cc1plus} spec. This is used to construct the options to be
4704 passed to the actual C++ compiler (@samp{cc1plus}).
4707 Substitute the variable part of a matched option. See below.
4708 Note that each comma in the substituted string is replaced by
4712 Substitutes the @code{-S} switch, if that switch was given to GCC@.
4713 If that switch was not specified, this substitutes nothing. Note that
4714 the leading dash is omitted when specifying this option, and it is
4715 automatically inserted if the substitution is performed. Thus the spec
4716 string @samp{%@{foo@}} would match the command-line option @option{-foo}
4717 and would output the command line option @option{-foo}.
4719 @item %W@{@code{S}@}
4720 Like %@{@code{S}@} but mark last argument supplied within as a file to be
4723 @item %@{@code{S}*@}
4724 Substitutes all the switches specified to GCC whose names start
4725 with @code{-S}, but which also take an argument. This is used for
4726 switches like @option{-o}, @option{-D}, @option{-I}, etc.
4727 GCC considers @option{-o foo} as being
4728 one switch whose names starts with @samp{o}. %@{o*@} would substitute this
4729 text, including the space. Thus two arguments would be generated.
4731 @item %@{^@code{S}*@}
4732 Like %@{@code{S}*@}, but don't put a blank between a switch and its
4733 argument. Thus %@{^o*@} would only generate one argument, not two.
4735 @item %@{@code{S}*&@code{T}*@}
4736 Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
4737 (the order of @code{S} and @code{T} in the spec is not significant).
4738 There can be any number of ampersand-separated variables; for each the
4739 wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
4741 @item %@{<@code{S}@}
4742 Remove all occurrences of @code{-S} from the command line. Note---this
4743 command is position dependent. @samp{%} commands in the spec string
4744 before this option will see @code{-S}, @samp{%} commands in the spec
4745 string after this option will not.
4747 @item %@{@code{S}*:@code{X}@}
4748 Substitutes @code{X} if one or more switches whose names start with
4749 @code{-S} are specified to GCC@. Note that the tail part of the
4750 @code{-S} option (i.e.@: the part matched by the @samp{*}) will be substituted
4751 for each occurrence of @samp{%*} within @code{X}.
4753 @item %@{@code{S}:@code{X}@}
4754 Substitutes @code{X}, but only if the @samp{-S} switch was given to GCC@.
4756 @item %@{!@code{S}:@code{X}@}
4757 Substitutes @code{X}, but only if the @samp{-S} switch was @emph{not} given to GCC@.
4759 @item %@{|@code{S}:@code{X}@}
4760 Like %@{@code{S}:@code{X}@}, but if no @code{S} switch, substitute @samp{-}.
4762 @item %@{|!@code{S}:@code{X}@}
4763 Like %@{!@code{S}:@code{X}@}, but if there is an @code{S} switch, substitute @samp{-}.
4765 @item %@{.@code{S}:@code{X}@}
4766 Substitutes @code{X}, but only if processing a file with suffix @code{S}.
4768 @item %@{!.@code{S}:@code{X}@}
4769 Substitutes @code{X}, but only if @emph{not} processing a file with suffix @code{S}.
4771 @item %@{@code{S}|@code{P}:@code{X}@}
4772 Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@. This may be
4773 combined with @samp{!} and @samp{.} sequences as well, although they
4774 have a stronger binding than the @samp{|}. For example a spec string
4778 %@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
4781 will output the following command-line options from the following input
4782 command-line options:
4787 -d fred.c -foo -baz -boggle
4788 -d jim.d -bar -baz -boggle
4793 The conditional text @code{X} in a %@{@code{S}:@code{X}@} or
4794 %@{!@code{S}:@code{X}@} construct may contain other nested @samp{%} constructs
4795 or spaces, or even newlines. They are processed as usual, as described
4798 The @option{-O}, @option{-f}, @option{-m}, and @option{-W}
4799 switches are handled specifically in these
4800 constructs. If another value of @option{-O} or the negated form of a @option{-f}, @option{-m}, or
4801 @option{-W} switch is found later in the command line, the earlier switch
4802 value is ignored, except with @{@code{S}*@} where @code{S} is just one
4803 letter, which passes all matching options.
4805 The character @samp{|} at the beginning of the predicate text is used to indicate
4806 that a command should be piped to the following command, but only if @option{-pipe}
4809 It is built into GCC which switches take arguments and which do not.
4810 (You might think it would be useful to generalize this to allow each
4811 compiler's spec to say which switches take arguments. But this cannot
4812 be done in a consistent fashion. GCC cannot even decide which input
4813 files have been specified without knowing which switches take arguments,
4814 and it must know which input files to compile in order to tell which
4817 GCC also knows implicitly that arguments starting in @option{-l} are to be
4818 treated as compiler output files, and passed to the linker in their
4819 proper position among the other output files.
4821 @c man begin OPTIONS
4823 @node Target Options
4824 @section Specifying Target Machine and Compiler Version
4825 @cindex target options
4826 @cindex cross compiling
4827 @cindex specifying machine version
4828 @cindex specifying compiler version and target machine
4829 @cindex compiler version, specifying
4830 @cindex target machine, specifying
4832 The usual way to run GCC is to run the executable called @file{gcc}, or
4833 @file{<machine>-gcc} when cross-compiling, or
4834 @file{<machine>-gcc-<version>} to run a version other than the one that
4835 was installed last. Sometimes this is inconvenient, so GCC provides
4836 options that will switch to another cross-compiler or version.
4839 @item -b @var{machine}
4841 The argument @var{machine} specifies the target machine for compilation.
4843 The value to use for @var{machine} is the same as was specified as the
4844 machine type when configuring GCC as a cross-compiler. For
4845 example, if a cross-compiler was configured with @samp{configure
4846 i386v}, meaning to compile for an 80386 running System V, then you
4847 would specify @option{-b i386v} to run that cross compiler.
4849 @item -V @var{version}
4851 The argument @var{version} specifies which version of GCC to run.
4852 This is useful when multiple versions are installed. For example,
4853 @var{version} might be @samp{2.0}, meaning to run GCC version 2.0.
4856 The @option{-V} and @option{-b} options work by running the
4857 @file{<machine>-gcc-<version>} executable, so there's no real reason to
4858 use them if you can just run that directly.
4860 @node Submodel Options
4861 @section Hardware Models and Configurations
4862 @cindex submodel options
4863 @cindex specifying hardware config
4864 @cindex hardware models and configurations, specifying
4865 @cindex machine dependent options
4867 Earlier we discussed the standard option @option{-b} which chooses among
4868 different installed compilers for completely different target
4869 machines, such as VAX vs.@: 68000 vs.@: 80386.
4871 In addition, each of these target machine types can have its own
4872 special options, starting with @samp{-m}, to choose among various
4873 hardware models or configurations---for example, 68010 vs 68020,
4874 floating coprocessor or none. A single installed version of the
4875 compiler can compile for any model or configuration, according to the
4878 Some configurations of the compiler also support additional special
4879 options, usually for compatibility with other compilers on the same
4882 These options are defined by the macro @code{TARGET_SWITCHES} in the
4883 machine description. The default for the options is also defined by
4884 that macro, which enables you to change the defaults.
4898 * RS/6000 and PowerPC Options::
4901 * i386 and x86-64 Options::
4903 * Intel 960 Options::
4904 * DEC Alpha Options::
4905 * DEC Alpha/VMS Options::
4909 * System V Options::
4910 * TMS320C3x/C4x Options::
4918 * S/390 and zSeries Options::
4922 * Xstormy16 Options::
4926 @node M680x0 Options
4927 @subsection M680x0 Options
4928 @cindex M680x0 options
4930 These are the @samp{-m} options defined for the 68000 series. The default
4931 values for these options depends on which style of 68000 was selected when
4932 the compiler was configured; the defaults for the most common choices are
4940 Generate output for a 68000. This is the default
4941 when the compiler is configured for 68000-based systems.
4943 Use this option for microcontrollers with a 68000 or EC000 core,
4944 including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
4950 Generate output for a 68020. This is the default
4951 when the compiler is configured for 68020-based systems.
4955 Generate output containing 68881 instructions for floating point.
4956 This is the default for most 68020 systems unless @option{--nfp} was
4957 specified when the compiler was configured.
4961 Generate output for a 68030. This is the default when the compiler is
4962 configured for 68030-based systems.
4966 Generate output for a 68040. This is the default when the compiler is
4967 configured for 68040-based systems.
4969 This option inhibits the use of 68881/68882 instructions that have to be
4970 emulated by software on the 68040. Use this option if your 68040 does not
4971 have code to emulate those instructions.
4975 Generate output for a 68060. This is the default when the compiler is
4976 configured for 68060-based systems.
4978 This option inhibits the use of 68020 and 68881/68882 instructions that
4979 have to be emulated by software on the 68060. Use this option if your 68060
4980 does not have code to emulate those instructions.
4984 Generate output for a CPU32. This is the default
4985 when the compiler is configured for CPU32-based systems.
4987 Use this option for microcontrollers with a
4988 CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
4989 68336, 68340, 68341, 68349 and 68360.
4993 Generate output for a 520X ``coldfire'' family cpu. This is the default
4994 when the compiler is configured for 520X-based systems.
4996 Use this option for microcontroller with a 5200 core, including
4997 the MCF5202, MCF5203, MCF5204 and MCF5202.
5002 Generate output for a 68040, without using any of the new instructions.
5003 This results in code which can run relatively efficiently on either a
5004 68020/68881 or a 68030 or a 68040. The generated code does use the
5005 68881 instructions that are emulated on the 68040.
5009 Generate output for a 68060, without using any of the new instructions.
5010 This results in code which can run relatively efficiently on either a
5011 68020/68881 or a 68030 or a 68040. The generated code does use the
5012 68881 instructions that are emulated on the 68060.
5016 Generate output containing Sun FPA instructions for floating point.
5019 @opindex msoft-float
5020 Generate output containing library calls for floating point.
5021 @strong{Warning:} the requisite libraries are not available for all m68k
5022 targets. Normally the facilities of the machine's usual C compiler are
5023 used, but this can't be done directly in cross-compilation. You must
5024 make your own arrangements to provide suitable library functions for
5025 cross-compilation. The embedded targets @samp{m68k-*-aout} and
5026 @samp{m68k-*-coff} do provide software floating point support.
5030 Consider type @code{int} to be 16 bits wide, like @code{short int}.
5033 @opindex mnobitfield
5034 Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
5035 and @option{-m5200} options imply @w{@option{-mnobitfield}}.
5039 Do use the bit-field instructions. The @option{-m68020} option implies
5040 @option{-mbitfield}. This is the default if you use a configuration
5041 designed for a 68020.
5045 Use a different function-calling convention, in which functions
5046 that take a fixed number of arguments return with the @code{rtd}
5047 instruction, which pops their arguments while returning. This
5048 saves one instruction in the caller since there is no need to pop
5049 the arguments there.
5051 This calling convention is incompatible with the one normally
5052 used on Unix, so you cannot use it if you need to call libraries
5053 compiled with the Unix compiler.
5055 Also, you must provide function prototypes for all functions that
5056 take variable numbers of arguments (including @code{printf});
5057 otherwise incorrect code will be generated for calls to those
5060 In addition, seriously incorrect code will result if you call a
5061 function with too many arguments. (Normally, extra arguments are
5062 harmlessly ignored.)
5064 The @code{rtd} instruction is supported by the 68010, 68020, 68030,
5065 68040, 68060 and CPU32 processors, but not by the 68000 or 5200.
5068 @itemx -mno-align-int
5070 @opindex mno-align-int
5071 Control whether GCC aligns @code{int}, @code{long}, @code{long long},
5072 @code{float}, @code{double}, and @code{long double} variables on a 32-bit
5073 boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
5074 Aligning variables on 32-bit boundaries produces code that runs somewhat
5075 faster on processors with 32-bit busses at the expense of more memory.
5077 @strong{Warning:} if you use the @option{-malign-int} switch, GCC will
5078 align structures containing the above types differently than
5079 most published application binary interface specifications for the m68k.
5083 Use the pc-relative addressing mode of the 68000 directly, instead of
5084 using a global offset table. At present, this option implies @option{-fpic},
5085 allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
5086 not presently supported with @option{-mpcrel}, though this could be supported for
5087 68020 and higher processors.
5089 @item -mno-strict-align
5090 @itemx -mstrict-align
5091 @opindex mno-strict-align
5092 @opindex mstrict-align
5093 Do not (do) assume that unaligned memory references will be handled by
5098 @node M68hc1x Options
5099 @subsection M68hc1x Options
5100 @cindex M68hc1x options
5102 These are the @samp{-m} options defined for the 68hc11 and 68hc12
5103 microcontrollers. The default values for these options depends on
5104 which style of microcontroller was selected when the compiler was configured;
5105 the defaults for the most common choices are given below.
5112 Generate output for a 68HC11. This is the default
5113 when the compiler is configured for 68HC11-based systems.
5119 Generate output for a 68HC12. This is the default
5120 when the compiler is configured for 68HC12-based systems.
5123 @opindex mauto-incdec
5124 Enable the use of 68HC12 pre and post auto-increment and auto-decrement
5129 Consider type @code{int} to be 16 bits wide, like @code{short int}.
5131 @item -msoft-reg-count=@var{count}
5132 @opindex msoft-reg-count
5133 Specify the number of pseudo-soft registers which are used for the
5134 code generation. The maximum number is 32. Using more pseudo-soft
5135 register may or may not result in better code depending on the program.
5136 The default is 4 for 68HC11 and 2 for 68HC12.
5141 @subsection VAX Options
5144 These @samp{-m} options are defined for the VAX:
5149 Do not output certain jump instructions (@code{aobleq} and so on)
5150 that the Unix assembler for the VAX cannot handle across long
5155 Do output those jump instructions, on the assumption that you
5156 will assemble with the GNU assembler.
5160 Output code for g-format floating point numbers instead of d-format.
5164 @subsection SPARC Options
5165 @cindex SPARC options
5167 These @samp{-m} switches are supported on the SPARC:
5172 @opindex mno-app-regs
5174 Specify @option{-mapp-regs} to generate output using the global registers
5175 2 through 4, which the SPARC SVR4 ABI reserves for applications. This
5178 To be fully SVR4 ABI compliant at the cost of some performance loss,
5179 specify @option{-mno-app-regs}. You should compile libraries and system
5180 software with this option.
5185 @opindex mhard-float
5186 Generate output containing floating point instructions. This is the
5192 @opindex msoft-float
5193 Generate output containing library calls for floating point.
5194 @strong{Warning:} the requisite libraries are not available for all SPARC
5195 targets. Normally the facilities of the machine's usual C compiler are
5196 used, but this cannot be done directly in cross-compilation. You must make
5197 your own arrangements to provide suitable library functions for
5198 cross-compilation. The embedded targets @samp{sparc-*-aout} and
5199 @samp{sparclite-*-*} do provide software floating point support.
5201 @option{-msoft-float} changes the calling convention in the output file;
5202 therefore, it is only useful if you compile @emph{all} of a program with
5203 this option. In particular, you need to compile @file{libgcc.a}, the
5204 library that comes with GCC, with @option{-msoft-float} in order for
5207 @item -mhard-quad-float
5208 @opindex mhard-quad-float
5209 Generate output containing quad-word (long double) floating point
5212 @item -msoft-quad-float
5213 @opindex msoft-quad-float
5214 Generate output containing library calls for quad-word (long double)
5215 floating point instructions. The functions called are those specified
5216 in the SPARC ABI@. This is the default.
5218 As of this writing, there are no sparc implementations that have hardware
5219 support for the quad-word floating point instructions. They all invoke
5220 a trap handler for one of these instructions, and then the trap handler
5221 emulates the effect of the instruction. Because of the trap handler overhead,
5222 this is much slower than calling the ABI library routines. Thus the
5223 @option{-msoft-quad-float} option is the default.
5229 With @option{-mflat}, the compiler does not generate save/restore instructions
5230 and will use a ``flat'' or single register window calling convention.
5231 This model uses %i7 as the frame pointer and is compatible with the normal
5232 register window model. Code from either may be intermixed.
5233 The local registers and the input registers (0--5) are still treated as
5234 ``call saved'' registers and will be saved on the stack as necessary.
5236 With @option{-mno-flat} (the default), the compiler emits save/restore
5237 instructions (except for leaf functions) and is the normal mode of operation.
5239 @item -mno-unaligned-doubles
5240 @itemx -munaligned-doubles
5241 @opindex mno-unaligned-doubles
5242 @opindex munaligned-doubles
5243 Assume that doubles have 8 byte alignment. This is the default.
5245 With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
5246 alignment only if they are contained in another type, or if they have an
5247 absolute address. Otherwise, it assumes they have 4 byte alignment.
5248 Specifying this option avoids some rare compatibility problems with code
5249 generated by other compilers. It is not the default because it results
5250 in a performance loss, especially for floating point code.
5252 @item -mno-faster-structs
5253 @itemx -mfaster-structs
5254 @opindex mno-faster-structs
5255 @opindex mfaster-structs
5256 With @option{-mfaster-structs}, the compiler assumes that structures
5257 should have 8 byte alignment. This enables the use of pairs of
5258 @code{ldd} and @code{std} instructions for copies in structure
5259 assignment, in place of twice as many @code{ld} and @code{st} pairs.
5260 However, the use of this changed alignment directly violates the Sparc
5261 ABI@. Thus, it's intended only for use on targets where the developer
5262 acknowledges that their resulting code will not be directly in line with
5263 the rules of the ABI@.
5269 These two options select variations on the SPARC architecture.
5271 By default (unless specifically configured for the Fujitsu SPARClite),
5272 GCC generates code for the v7 variant of the SPARC architecture.
5274 @option{-mv8} will give you SPARC v8 code. The only difference from v7
5275 code is that the compiler emits the integer multiply and integer
5276 divide instructions which exist in SPARC v8 but not in SPARC v7.
5278 @option{-msparclite} will give you SPARClite code. This adds the integer
5279 multiply, integer divide step and scan (@code{ffs}) instructions which
5280 exist in SPARClite but not in SPARC v7.
5282 These options are deprecated and will be deleted in a future GCC release.
5283 They have been replaced with @option{-mcpu=xxx}.
5288 @opindex msupersparc
5289 These two options select the processor for which the code is optimized.
5291 With @option{-mcypress} (the default), the compiler optimizes code for the
5292 Cypress CY7C602 chip, as used in the SparcStation/SparcServer 3xx series.
5293 This is also appropriate for the older SparcStation 1, 2, IPX etc.
5295 With @option{-msupersparc} the compiler optimizes code for the SuperSparc cpu, as
5296 used in the SparcStation 10, 1000 and 2000 series. This flag also enables use
5297 of the full SPARC v8 instruction set.
5299 These options are deprecated and will be deleted in a future GCC release.
5300 They have been replaced with @option{-mcpu=xxx}.
5302 @item -mcpu=@var{cpu_type}
5304 Set the instruction set, register set, and instruction scheduling parameters
5305 for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
5306 @samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
5307 @samp{hypersparc}, @samp{sparclite86x}, @samp{f930}, @samp{f934},
5308 @samp{sparclet}, @samp{tsc701}, @samp{v9}, and @samp{ultrasparc}.
5310 Default instruction scheduling parameters are used for values that select
5311 an architecture and not an implementation. These are @samp{v7}, @samp{v8},
5312 @samp{sparclite}, @samp{sparclet}, @samp{v9}.
5314 Here is a list of each supported architecture and their supported
5319 v8: supersparc, hypersparc
5320 sparclite: f930, f934, sparclite86x
5325 @item -mtune=@var{cpu_type}
5327 Set the instruction scheduling parameters for machine type
5328 @var{cpu_type}, but do not set the instruction set or register set that the
5329 option @option{-mcpu=@var{cpu_type}} would.
5331 The same values for @option{-mcpu=@var{cpu_type}} can be used for
5332 @option{-mtune=@var{cpu_type}}, but the only useful values are those
5333 that select a particular cpu implementation. Those are @samp{cypress},
5334 @samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
5335 @samp{sparclite86x}, @samp{tsc701}, and @samp{ultrasparc}.
5339 These @samp{-m} switches are supported in addition to the above
5340 on the SPARCLET processor.
5343 @item -mlittle-endian
5344 @opindex mlittle-endian
5345 Generate code for a processor running in little-endian mode.
5349 Treat register @code{%g0} as a normal register.
5350 GCC will continue to clobber it as necessary but will not assume
5351 it always reads as 0.
5353 @item -mbroken-saverestore
5354 @opindex mbroken-saverestore
5355 Generate code that does not use non-trivial forms of the @code{save} and
5356 @code{restore} instructions. Early versions of the SPARCLET processor do
5357 not correctly handle @code{save} and @code{restore} instructions used with
5358 arguments. They correctly handle them used without arguments. A @code{save}
5359 instruction used without arguments increments the current window pointer
5360 but does not allocate a new stack frame. It is assumed that the window
5361 overflow trap handler will properly handle this case as will interrupt
5365 These @samp{-m} switches are supported in addition to the above
5366 on SPARC V9 processors in 64-bit environments.
5369 @item -mlittle-endian
5370 @opindex mlittle-endian
5371 Generate code for a processor running in little-endian mode.
5377 Generate code for a 32-bit or 64-bit environment.
5378 The 32-bit environment sets int, long and pointer to 32 bits.
5379 The 64-bit environment sets int to 32 bits and long and pointer
5382 @item -mcmodel=medlow
5383 @opindex mcmodel=medlow
5384 Generate code for the Medium/Low code model: the program must be linked
5385 in the low 32 bits of the address space. Pointers are 64 bits.
5386 Programs can be statically or dynamically linked.
5388 @item -mcmodel=medmid
5389 @opindex mcmodel=medmid
5390 Generate code for the Medium/Middle code model: the program must be linked
5391 in the low 44 bits of the address space, the text segment must be less than
5392 2G bytes, and data segment must be within 2G of the text segment.
5393 Pointers are 64 bits.
5395 @item -mcmodel=medany
5396 @opindex mcmodel=medany
5397 Generate code for the Medium/Anywhere code model: the program may be linked
5398 anywhere in the address space, the text segment must be less than
5399 2G bytes, and data segment must be within 2G of the text segment.
5400 Pointers are 64 bits.
5402 @item -mcmodel=embmedany
5403 @opindex mcmodel=embmedany
5404 Generate code for the Medium/Anywhere code model for embedded systems:
5405 assume a 32-bit text and a 32-bit data segment, both starting anywhere
5406 (determined at link time). Register %g4 points to the base of the
5407 data segment. Pointers are still 64 bits.
5408 Programs are statically linked, PIC is not supported.
5411 @itemx -mno-stack-bias
5412 @opindex mstack-bias
5413 @opindex mno-stack-bias
5414 With @option{-mstack-bias}, GCC assumes that the stack pointer, and
5415 frame pointer if present, are offset by @minus{}2047 which must be added back
5416 when making stack frame references.
5417 Otherwise, assume no such offset is present.
5420 @node Convex Options
5421 @subsection Convex Options
5422 @cindex Convex options
5424 These @samp{-m} options are defined for Convex:
5429 Generate output for C1. The code will run on any Convex machine.
5430 The preprocessor symbol @code{__convex__c1__} is defined.
5434 Generate output for C2. Uses instructions not available on C1.
5435 Scheduling and other optimizations are chosen for max performance on C2.
5436 The preprocessor symbol @code{__convex_c2__} is defined.
5440 Generate output for C32xx. Uses instructions not available on C1.
5441 Scheduling and other optimizations are chosen for max performance on C32.
5442 The preprocessor symbol @code{__convex_c32__} is defined.
5446 Generate output for C34xx. Uses instructions not available on C1.
5447 Scheduling and other optimizations are chosen for max performance on C34.
5448 The preprocessor symbol @code{__convex_c34__} is defined.
5452 Generate output for C38xx. Uses instructions not available on C1.
5453 Scheduling and other optimizations are chosen for max performance on C38.
5454 The preprocessor symbol @code{__convex_c38__} is defined.
5458 Generate code which puts an argument count in the word preceding each
5459 argument list. This is compatible with regular CC, and a few programs
5460 may need the argument count word. GDB and other source-level debuggers
5461 do not need it; this info is in the symbol table.
5464 @opindex mnoargcount
5465 Omit the argument count word. This is the default.
5467 @item -mvolatile-cache
5468 @opindex mvolatile-cache
5469 Allow volatile references to be cached. This is the default.
5471 @item -mvolatile-nocache
5472 @opindex mvolatile-nocache
5473 Volatile references bypass the data cache, going all the way to memory.
5474 This is only needed for multi-processor code that does not use standard
5475 synchronization instructions. Making non-volatile references to volatile
5476 locations will not necessarily work.
5480 Type long is 32 bits, the same as type int. This is the default.
5484 Type long is 64 bits, the same as type long long. This option is useless,
5485 because no library support exists for it.
5488 @node AMD29K Options
5489 @subsection AMD29K Options
5490 @cindex AMD29K options
5492 These @samp{-m} options are defined for the AMD Am29000:
5497 @cindex DW bit (29k)
5498 Generate code that assumes the @code{DW} bit is set, i.e., that byte and
5499 halfword operations are directly supported by the hardware. This is the
5504 Generate code that assumes the @code{DW} bit is not set.
5508 @cindex byte writes (29k)
5509 Generate code that assumes the system supports byte and halfword write
5510 operations. This is the default.
5514 Generate code that assumes the systems does not support byte and
5515 halfword write operations. @option{-mnbw} implies @option{-mndw}.
5519 @cindex memory model (29k)
5520 Use a small memory model that assumes that all function addresses are
5521 either within a single 256 KB segment or at an absolute address of less
5522 than 256k. This allows the @code{call} instruction to be used instead
5523 of a @code{const}, @code{consth}, @code{calli} sequence.
5527 Use the normal memory model: Generate @code{call} instructions only when
5528 calling functions in the same file and @code{calli} instructions
5529 otherwise. This works if each file occupies less than 256 KB but allows
5530 the entire executable to be larger than 256 KB@. This is the default.
5534 Always use @code{calli} instructions. Specify this option if you expect
5535 a single file to compile into more than 256 KB of code.
5539 @cindex processor selection (29k)
5540 Generate code for the Am29050.
5544 Generate code for the Am29000. This is the default.
5546 @item -mkernel-registers
5547 @opindex mkernel-registers
5548 @cindex kernel and user registers (29k)
5549 Generate references to registers @code{gr64-gr95} instead of to
5550 registers @code{gr96-gr127}. This option can be used when compiling
5551 kernel code that wants a set of global registers disjoint from that used
5554 Note that when this option is used, register names in @samp{-f} flags
5555 must use the normal, user-mode, names.
5557 @item -muser-registers
5558 @opindex muser-registers
5559 Use the normal set of global registers, @code{gr96-gr127}. This is the
5563 @itemx -mno-stack-check
5564 @opindex mstack-check
5565 @opindex mno-stack-check
5566 @cindex stack checks (29k)
5567 Insert (or do not insert) a call to @code{__msp_check} after each stack
5568 adjustment. This is often used for kernel code.
5571 @itemx -mno-storem-bug
5572 @opindex mstorem-bug
5573 @opindex mno-storem-bug
5574 @cindex storem bug (29k)
5575 @option{-mstorem-bug} handles 29k processors which cannot handle the
5576 separation of a mtsrim insn and a storem instruction (most 29000 chips
5577 to date, but not the 29050).
5579 @item -mno-reuse-arg-regs
5580 @itemx -mreuse-arg-regs
5581 @opindex mno-reuse-arg-regs
5582 @opindex mreuse-arg-regs
5583 @option{-mno-reuse-arg-regs} tells the compiler to only use incoming argument
5584 registers for copying out arguments. This helps detect calling a function
5585 with fewer arguments than it was declared with.
5587 @item -mno-impure-text
5588 @itemx -mimpure-text
5589 @opindex mno-impure-text
5590 @opindex mimpure-text
5591 @option{-mimpure-text}, used in addition to @option{-shared}, tells the compiler to
5592 not pass @option{-assert pure-text} to the linker when linking a shared object.
5595 @opindex msoft-float
5596 Generate output containing library calls for floating point.
5597 @strong{Warning:} the requisite libraries are not part of GCC@.
5598 Normally the facilities of the machine's usual C compiler are used, but
5599 this can't be done directly in cross-compilation. You must make your
5600 own arrangements to provide suitable library functions for
5605 Do not generate multm or multmu instructions. This is useful for some embedded
5606 systems which do not have trap handlers for these instructions.
5610 @subsection ARM Options
5613 These @samp{-m} options are defined for Advanced RISC Machines (ARM)
5618 @opindex mapcs-frame
5619 Generate a stack frame that is compliant with the ARM Procedure Call
5620 Standard for all functions, even if this is not strictly necessary for
5621 correct execution of the code. Specifying @option{-fomit-frame-pointer}
5622 with this option will cause the stack frames not to be generated for
5623 leaf functions. The default is @option{-mno-apcs-frame}.
5627 This is a synonym for @option{-mapcs-frame}.
5631 Generate code for a processor running with a 26-bit program counter,
5632 and conforming to the function calling standards for the APCS 26-bit
5633 option. This option replaces the @option{-m2} and @option{-m3} options
5634 of previous releases of the compiler.
5638 Generate code for a processor running with a 32-bit program counter,
5639 and conforming to the function calling standards for the APCS 32-bit
5640 option. This option replaces the @option{-m6} option of previous releases
5644 @c not currently implemented
5645 @item -mapcs-stack-check
5646 @opindex mapcs-stack-check
5647 Generate code to check the amount of stack space available upon entry to
5648 every function (that actually uses some stack space). If there is
5649 insufficient space available then either the function
5650 @samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
5651 called, depending upon the amount of stack space required. The run time
5652 system is required to provide these functions. The default is
5653 @option{-mno-apcs-stack-check}, since this produces smaller code.
5655 @c not currently implemented
5657 @opindex mapcs-float
5658 Pass floating point arguments using the float point registers. This is
5659 one of the variants of the APCS@. This option is recommended if the
5660 target hardware has a floating point unit or if a lot of floating point
5661 arithmetic is going to be performed by the code. The default is
5662 @option{-mno-apcs-float}, since integer only code is slightly increased in
5663 size if @option{-mapcs-float} is used.
5665 @c not currently implemented
5666 @item -mapcs-reentrant
5667 @opindex mapcs-reentrant
5668 Generate reentrant, position independent code. The default is
5669 @option{-mno-apcs-reentrant}.
5672 @item -mthumb-interwork
5673 @opindex mthumb-interwork
5674 Generate code which supports calling between the ARM and Thumb
5675 instruction sets. Without this option the two instruction sets cannot
5676 be reliably used inside one program. The default is
5677 @option{-mno-thumb-interwork}, since slightly larger code is generated
5678 when @option{-mthumb-interwork} is specified.
5680 @item -mno-sched-prolog
5681 @opindex mno-sched-prolog
5682 Prevent the reordering of instructions in the function prolog, or the
5683 merging of those instruction with the instructions in the function's
5684 body. This means that all functions will start with a recognizable set
5685 of instructions (or in fact one of a choice from a small set of
5686 different function prologues), and this information can be used to
5687 locate the start if functions inside an executable piece of code. The
5688 default is @option{-msched-prolog}.
5691 @opindex mhard-float
5692 Generate output containing floating point instructions. This is the
5696 @opindex msoft-float
5697 Generate output containing library calls for floating point.
5698 @strong{Warning:} the requisite libraries are not available for all ARM
5699 targets. Normally the facilities of the machine's usual C compiler are
5700 used, but this cannot be done directly in cross-compilation. You must make
5701 your own arrangements to provide suitable library functions for
5704 @option{-msoft-float} changes the calling convention in the output file;
5705 therefore, it is only useful if you compile @emph{all} of a program with
5706 this option. In particular, you need to compile @file{libgcc.a}, the
5707 library that comes with GCC, with @option{-msoft-float} in order for
5710 @item -mlittle-endian
5711 @opindex mlittle-endian
5712 Generate code for a processor running in little-endian mode. This is
5713 the default for all standard configurations.
5716 @opindex mbig-endian
5717 Generate code for a processor running in big-endian mode; the default is
5718 to compile code for a little-endian processor.
5720 @item -mwords-little-endian
5721 @opindex mwords-little-endian
5722 This option only applies when generating code for big-endian processors.
5723 Generate code for a little-endian word order but a big-endian byte
5724 order. That is, a byte order of the form @samp{32107654}. Note: this
5725 option should only be used if you require compatibility with code for
5726 big-endian ARM processors generated by versions of the compiler prior to
5729 @item -malignment-traps
5730 @opindex malignment-traps
5731 Generate code that will not trap if the MMU has alignment traps enabled.
5732 On ARM architectures prior to ARMv4, there were no instructions to
5733 access half-word objects stored in memory. However, when reading from
5734 memory a feature of the ARM architecture allows a word load to be used,
5735 even if the address is unaligned, and the processor core will rotate the
5736 data as it is being loaded. This option tells the compiler that such
5737 misaligned accesses will cause a MMU trap and that it should instead
5738 synthesise the access as a series of byte accesses. The compiler can
5739 still use word accesses to load half-word data if it knows that the
5740 address is aligned to a word boundary.
5742 This option is ignored when compiling for ARM architecture 4 or later,
5743 since these processors have instructions to directly access half-word
5746 @item -mno-alignment-traps
5747 @opindex mno-alignment-traps
5748 Generate code that assumes that the MMU will not trap unaligned
5749 accesses. This produces better code when the target instruction set
5750 does not have half-word memory operations (i.e.@: implementations prior to
5753 Note that you cannot use this option to access unaligned word objects,
5754 since the processor will only fetch one 32-bit aligned object from
5757 The default setting for most targets is @option{-mno-alignment-traps}, since
5758 this produces better code when there are no half-word memory
5759 instructions available.
5761 @item -mshort-load-bytes
5762 @itemx -mno-short-load-words
5763 @opindex mshort-load-bytes
5764 @opindex mno-short-load-words
5765 These are deprecated aliases for @option{-malignment-traps}.
5767 @item -mno-short-load-bytes
5768 @itemx -mshort-load-words
5769 @opindex mno-short-load-bytes
5770 @opindex mshort-load-words
5771 This are deprecated aliases for @option{-mno-alignment-traps}.
5775 This option only applies to RISC iX@. Emulate the native BSD-mode
5776 compiler. This is the default if @option{-ansi} is not specified.
5780 This option only applies to RISC iX@. Emulate the native X/Open-mode
5783 @item -mno-symrename
5784 @opindex mno-symrename
5785 This option only applies to RISC iX@. Do not run the assembler
5786 post-processor, @samp{symrename}, after code has been assembled.
5787 Normally it is necessary to modify some of the standard symbols in
5788 preparation for linking with the RISC iX C library; this option
5789 suppresses this pass. The post-processor is never run when the
5790 compiler is built for cross-compilation.
5792 @item -mcpu=@var{name}
5794 This specifies the name of the target ARM processor. GCC uses this name
5795 to determine what kind of instructions it can emit when generating
5796 assembly code. Permissible names are: @samp{arm2}, @samp{arm250},
5797 @samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
5798 @samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
5799 @samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
5800 @samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
5801 @samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm8},
5802 @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
5803 @samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
5804 @samp{arm920t}, @samp{arm940t}, @samp{arm9tdmi}, @samp{arm10tdmi},
5805 @samp{arm1020t}, @samp{xscale}.
5807 @itemx -mtune=@var{name}
5809 This option is very similar to the @option{-mcpu=} option, except that
5810 instead of specifying the actual target processor type, and hence
5811 restricting which instructions can be used, it specifies that GCC should
5812 tune the performance of the code as if the target were of the type
5813 specified in this option, but still choosing the instructions that it
5814 will generate based on the cpu specified by a @option{-mcpu=} option.
5815 For some ARM implementations better performance can be obtained by using
5818 @item -march=@var{name}
5820 This specifies the name of the target ARM architecture. GCC uses this
5821 name to determine what kind of instructions it can emit when generating
5822 assembly code. This option can be used in conjunction with or instead
5823 of the @option{-mcpu=} option. Permissible names are: @samp{armv2},
5824 @samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
5825 @samp{armv5}, @samp{armv5t}, @samp{armv5te}.
5827 @item -mfpe=@var{number}
5828 @itemx -mfp=@var{number}
5831 This specifies the version of the floating point emulation available on
5832 the target. Permissible values are 2 and 3. @option{-mfp=} is a synonym
5833 for @option{-mfpe=}, for compatibility with older versions of GCC@.
5835 @item -mstructure-size-boundary=@var{n}
5836 @opindex mstructure-size-boundary
5837 The size of all structures and unions will be rounded up to a multiple
5838 of the number of bits set by this option. Permissible values are 8 and
5839 32. The default value varies for different toolchains. For the COFF
5840 targeted toolchain the default value is 8. Specifying the larger number
5841 can produce faster, more efficient code, but can also increase the size
5842 of the program. The two values are potentially incompatible. Code
5843 compiled with one value cannot necessarily expect to work with code or
5844 libraries compiled with the other value, if they exchange information
5845 using structures or unions.
5847 @item -mabort-on-noreturn
5848 @opindex mabort-on-noreturn
5849 Generate a call to the function @code{abort} at the end of a
5850 @code{noreturn} function. It will be executed if the function tries to
5854 @itemx -mno-long-calls
5855 @opindex mlong-calls
5856 @opindex mno-long-calls
5857 Tells the compiler to perform function calls by first loading the
5858 address of the function into a register and then performing a subroutine
5859 call on this register. This switch is needed if the target function
5860 will lie outside of the 64 megabyte addressing range of the offset based
5861 version of subroutine call instruction.
5863 Even if this switch is enabled, not all function calls will be turned
5864 into long calls. The heuristic is that static functions, functions
5865 which have the @samp{short-call} attribute, functions that are inside
5866 the scope of a @samp{#pragma no_long_calls} directive and functions whose
5867 definitions have already been compiled within the current compilation
5868 unit, will not be turned into long calls. The exception to this rule is
5869 that weak function definitions, functions with the @samp{long-call}
5870 attribute or the @samp{section} attribute, and functions that are within
5871 the scope of a @samp{#pragma long_calls} directive, will always be
5872 turned into long calls.
5874 This feature is not enabled by default. Specifying
5875 @option{-mno-long-calls} will restore the default behavior, as will
5876 placing the function calls within the scope of a @samp{#pragma
5877 long_calls_off} directive. Note these switches have no effect on how
5878 the compiler generates code to handle function calls via function
5881 @item -mnop-fun-dllimport
5882 @opindex mnop-fun-dllimport
5883 Disable support for the @code{dllimport} attribute.
5885 @item -msingle-pic-base
5886 @opindex msingle-pic-base
5887 Treat the register used for PIC addressing as read-only, rather than
5888 loading it in the prologue for each function. The run-time system is
5889 responsible for initializing this register with an appropriate value
5890 before execution begins.
5892 @item -mpic-register=@var{reg}
5893 @opindex mpic-register
5894 Specify the register to be used for PIC addressing. The default is R10
5895 unless stack-checking is enabled, when R9 is used.
5897 @item -mpoke-function-name
5898 @opindex mpoke-function-name
5899 Write the name of each function into the text section, directly
5900 preceding the function prologue. The generated code is similar to this:
5904 .ascii "arm_poke_function_name", 0
5907 .word 0xff000000 + (t1 - t0)
5908 arm_poke_function_name
5910 stmfd sp!, @{fp, ip, lr, pc@}
5914 When performing a stack backtrace, code can inspect the value of
5915 @code{pc} stored at @code{fp + 0}. If the trace function then looks at
5916 location @code{pc - 12} and the top 8 bits are set, then we know that
5917 there is a function name embedded immediately preceding this location
5918 and has length @code{((pc[-3]) & 0xff000000)}.
5922 Generate code for the 16-bit Thumb instruction set. The default is to
5923 use the 32-bit ARM instruction set.
5926 @opindex mtpcs-frame
5927 Generate a stack frame that is compliant with the Thumb Procedure Call
5928 Standard for all non-leaf functions. (A leaf function is one that does
5929 not call any other functions.) The default is @option{-mno-tpcs-frame}.
5931 @item -mtpcs-leaf-frame
5932 @opindex mtpcs-leaf-frame
5933 Generate a stack frame that is compliant with the Thumb Procedure Call
5934 Standard for all leaf functions. (A leaf function is one that does
5935 not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
5937 @item -mcallee-super-interworking
5938 @opindex mcallee-super-interworking
5939 Gives all externally visible functions in the file being compiled an ARM
5940 instruction set header which switches to Thumb mode before executing the
5941 rest of the function. This allows these functions to be called from
5942 non-interworking code.
5944 @item -mcaller-super-interworking
5945 @opindex mcaller-super-interworking
5946 Allows calls via function pointers (including virtual functions) to
5947 execute correctly regardless of whether the target code has been
5948 compiled for interworking or not. There is a small overhead in the cost
5949 of executing a function pointer if this option is enabled.
5953 @node MN10200 Options
5954 @subsection MN10200 Options
5955 @cindex MN10200 options
5956 These @option{-m} options are defined for Matsushita MN10200 architectures:
5961 Indicate to the linker that it should perform a relaxation optimization pass
5962 to shorten branches, calls and absolute memory addresses. This option only
5963 has an effect when used on the command line for the final link step.
5965 This option makes symbolic debugging impossible.
5968 @node MN10300 Options
5969 @subsection MN10300 Options
5970 @cindex MN10300 options
5971 These @option{-m} options are defined for Matsushita MN10300 architectures:
5976 Generate code to avoid bugs in the multiply instructions for the MN10300
5977 processors. This is the default.
5980 @opindex mno-mult-bug
5981 Do not generate code to avoid bugs in the multiply instructions for the
5986 Generate code which uses features specific to the AM33 processor.
5990 Do not generate code which uses features specific to the AM33 processor. This
5995 Do not link in the C run-time initialization object file.
5999 Indicate to the linker that it should perform a relaxation optimization pass
6000 to shorten branches, calls and absolute memory addresses. This option only
6001 has an effect when used on the command line for the final link step.
6003 This option makes symbolic debugging impossible.
6007 @node M32R/D Options
6008 @subsection M32R/D Options
6009 @cindex M32R/D options
6011 These @option{-m} options are defined for Mitsubishi M32R/D architectures:
6016 Generate code for the M32R/X@.
6020 Generate code for the M32R@. This is the default.
6022 @item -mcode-model=small
6023 @opindex mcode-model=small
6024 Assume all objects live in the lower 16MB of memory (so that their addresses
6025 can be loaded with the @code{ld24} instruction), and assume all subroutines
6026 are reachable with the @code{bl} instruction.
6027 This is the default.
6029 The addressability of a particular object can be set with the
6030 @code{model} attribute.
6032 @item -mcode-model=medium
6033 @opindex mcode-model=medium
6034 Assume objects may be anywhere in the 32-bit address space (the compiler
6035 will generate @code{seth/add3} instructions to load their addresses), and
6036 assume all subroutines are reachable with the @code{bl} instruction.
6038 @item -mcode-model=large
6039 @opindex mcode-model=large
6040 Assume objects may be anywhere in the 32-bit address space (the compiler
6041 will generate @code{seth/add3} instructions to load their addresses), and
6042 assume subroutines may not be reachable with the @code{bl} instruction
6043 (the compiler will generate the much slower @code{seth/add3/jl}
6044 instruction sequence).
6047 @opindex msdata=none
6048 Disable use of the small data area. Variables will be put into
6049 one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
6050 @code{section} attribute has been specified).
6051 This is the default.
6053 The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
6054 Objects may be explicitly put in the small data area with the
6055 @code{section} attribute using one of these sections.
6058 @opindex msdata=sdata
6059 Put small global and static data in the small data area, but do not
6060 generate special code to reference them.
6064 Put small global and static data in the small data area, and generate
6065 special instructions to reference them.
6069 @cindex smaller data references
6070 Put global and static objects less than or equal to @var{num} bytes
6071 into the small data or bss sections instead of the normal data or bss
6072 sections. The default value of @var{num} is 8.
6073 The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
6074 for this option to have any effect.
6076 All modules should be compiled with the same @option{-G @var{num}} value.
6077 Compiling with different values of @var{num} may or may not work; if it
6078 doesn't the linker will give an error message---incorrect code will not be
6084 @subsection M88K Options
6085 @cindex M88k options
6087 These @samp{-m} options are defined for Motorola 88k architectures:
6092 Generate code that works well on both the m88100 and the
6097 Generate code that works best for the m88100, but that also
6102 Generate code that works best for the m88110, and may not run
6107 Obsolete option to be removed from the next revision.
6110 @item -midentify-revision
6111 @opindex midentify-revision
6112 @cindex identifying source, compiler (88k)
6113 Include an @code{ident} directive in the assembler output recording the
6114 source file name, compiler name and version, timestamp, and compilation
6117 @item -mno-underscores
6118 @opindex mno-underscores
6119 @cindex underscores, avoiding (88k)
6120 In assembler output, emit symbol names without adding an underscore
6121 character at the beginning of each name. The default is to use an
6122 underscore as prefix on each name.
6124 @item -mocs-debug-info
6125 @itemx -mno-ocs-debug-info
6126 @opindex mocs-debug-info
6127 @opindex mno-ocs-debug-info
6129 @cindex debugging, 88k OCS
6130 Include (or omit) additional debugging information (about registers used
6131 in each stack frame) as specified in the 88open Object Compatibility
6132 Standard, ``OCS''@. This extra information allows debugging of code that
6133 has had the frame pointer eliminated. The default for DG/UX, SVr4, and
6134 Delta 88 SVr3.2 is to include this information; other 88k configurations
6135 omit this information by default.
6137 @item -mocs-frame-position
6138 @opindex mocs-frame-position
6139 @cindex register positions in frame (88k)
6140 When emitting COFF debugging information for automatic variables and
6141 parameters stored on the stack, use the offset from the canonical frame
6142 address, which is the stack pointer (register 31) on entry to the
6143 function. The DG/UX, SVr4, Delta88 SVr3.2, and BCS configurations use
6144 @option{-mocs-frame-position}; other 88k configurations have the default
6145 @option{-mno-ocs-frame-position}.
6147 @item -mno-ocs-frame-position
6148 @opindex mno-ocs-frame-position
6149 @cindex register positions in frame (88k)
6150 When emitting COFF debugging information for automatic variables and
6151 parameters stored on the stack, use the offset from the frame pointer
6152 register (register 30). When this option is in effect, the frame
6153 pointer is not eliminated when debugging information is selected by the
6156 @item -moptimize-arg-area
6157 @opindex moptimize-arg-area
6158 @cindex arguments in frame (88k)
6159 Save space by reorganizing the stack frame. This option generates code
6160 that does not agree with the 88open specifications, but uses less
6163 @itemx -mno-optimize-arg-area
6164 @opindex mno-optimize-arg-area
6165 Do not reorganize the stack frame to save space. This is the default.
6166 The generated conforms to the specification, but uses more memory.
6168 @item -mshort-data-@var{num}
6169 @opindex mshort-data
6170 @cindex smaller data references (88k)
6171 @cindex r0-relative references (88k)
6172 Generate smaller data references by making them relative to @code{r0},
6173 which allows loading a value using a single instruction (rather than the
6174 usual two). You control which data references are affected by
6175 specifying @var{num} with this option. For example, if you specify
6176 @option{-mshort-data-512}, then the data references affected are those
6177 involving displacements of less than 512 bytes.
6178 @option{-mshort-data-@var{num}} is not effective for @var{num} greater
6181 @item -mserialize-volatile
6182 @opindex mserialize-volatile
6183 @itemx -mno-serialize-volatile
6184 @opindex mno-serialize-volatile
6185 @cindex sequential consistency on 88k
6186 Do, or don't, generate code to guarantee sequential consistency
6187 of volatile memory references. By default, consistency is
6190 The order of memory references made by the MC88110 processor does
6191 not always match the order of the instructions requesting those
6192 references. In particular, a load instruction may execute before
6193 a preceding store instruction. Such reordering violates
6194 sequential consistency of volatile memory references, when there
6195 are multiple processors. When consistency must be guaranteed,
6196 GCC generates special instructions, as needed, to force
6197 execution in the proper order.
6199 The MC88100 processor does not reorder memory references and so
6200 always provides sequential consistency. However, by default, GCC
6201 generates the special instructions to guarantee consistency
6202 even when you use @option{-m88100}, so that the code may be run on an
6203 MC88110 processor. If you intend to run your code only on the
6204 MC88100 processor, you may use @option{-mno-serialize-volatile}.
6206 The extra code generated to guarantee consistency may affect the
6207 performance of your application. If you know that you can safely
6208 forgo this guarantee, you may use @option{-mno-serialize-volatile}.
6214 @cindex assembler syntax, 88k
6216 Turn on (@option{-msvr4}) or off (@option{-msvr3}) compiler extensions
6217 related to System V release 4 (SVr4). This controls the following:
6221 Which variant of the assembler syntax to emit.
6223 @option{-msvr4} makes the C preprocessor recognize @samp{#pragma weak}
6224 that is used on System V release 4.
6226 @option{-msvr4} makes GCC issue additional declaration directives used in
6230 @option{-msvr4} is the default for the m88k-motorola-sysv4 and
6231 m88k-dg-dgux m88k configurations. @option{-msvr3} is the default for all
6232 other m88k configurations.
6234 @item -mversion-03.00
6235 @opindex mversion-03.00
6236 This option is obsolete, and is ignored.
6237 @c ??? which asm syntax better for GAS? option there too?
6239 @item -mno-check-zero-division
6240 @itemx -mcheck-zero-division
6241 @opindex mno-check-zero-division
6242 @opindex mcheck-zero-division
6243 @cindex zero division on 88k
6244 Do, or don't, generate code to guarantee that integer division by
6245 zero will be detected. By default, detection is guaranteed.
6247 Some models of the MC88100 processor fail to trap upon integer
6248 division by zero under certain conditions. By default, when
6249 compiling code that might be run on such a processor, GCC
6250 generates code that explicitly checks for zero-valued divisors
6251 and traps with exception number 503 when one is detected. Use of
6252 @option{-mno-check-zero-division} suppresses such checking for code
6253 generated to run on an MC88100 processor.
6255 GCC assumes that the MC88110 processor correctly detects all instances
6256 of integer division by zero. When @option{-m88110} is specified, no
6257 explicit checks for zero-valued divisors are generated, and both
6258 @option{-mcheck-zero-division} and @option{-mno-check-zero-division} are
6261 @item -muse-div-instruction
6262 @opindex muse-div-instruction
6263 @cindex divide instruction, 88k
6264 Use the div instruction for signed integer division on the
6265 MC88100 processor. By default, the div instruction is not used.
6267 On the MC88100 processor the signed integer division instruction
6268 div) traps to the operating system on a negative operand. The
6269 operating system transparently completes the operation, but at a
6270 large cost in execution time. By default, when compiling code
6271 that might be run on an MC88100 processor, GCC emulates signed
6272 integer division using the unsigned integer division instruction
6273 divu), thereby avoiding the large penalty of a trap to the
6274 operating system. Such emulation has its own, smaller, execution
6275 cost in both time and space. To the extent that your code's
6276 important signed integer division operations are performed on two
6277 nonnegative operands, it may be desirable to use the div
6278 instruction directly.
6280 On the MC88110 processor the div instruction (also known as the
6281 divs instruction) processes negative operands without trapping to
6282 the operating system. When @option{-m88110} is specified,
6283 @option{-muse-div-instruction} is ignored, and the div instruction is used
6284 for signed integer division.
6286 Note that the result of dividing @code{INT_MIN} by @minus{}1 is undefined. In
6287 particular, the behavior of such a division with and without
6288 @option{-muse-div-instruction} may differ.
6290 @item -mtrap-large-shift
6291 @itemx -mhandle-large-shift
6292 @opindex mtrap-large-shift
6293 @opindex mhandle-large-shift
6294 @cindex bit shift overflow (88k)
6295 @cindex large bit shifts (88k)
6296 Include code to detect bit-shifts of more than 31 bits; respectively,
6297 trap such shifts or emit code to handle them properly. By default GCC
6298 makes no special provision for large bit shifts.
6300 @item -mwarn-passed-structs
6301 @opindex mwarn-passed-structs
6302 @cindex structure passing (88k)
6303 Warn when a function passes a struct as an argument or result.
6304 Structure-passing conventions have changed during the evolution of the C
6305 language, and are often the source of portability problems. By default,
6306 GCC issues no such warning.
6309 @c break page here to avoid unsightly interparagraph stretch.
6313 @node RS/6000 and PowerPC Options
6314 @subsection IBM RS/6000 and PowerPC Options
6315 @cindex RS/6000 and PowerPC Options
6316 @cindex IBM RS/6000 and PowerPC Options
6318 These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
6326 @itemx -mpowerpc-gpopt
6327 @itemx -mno-powerpc-gpopt
6328 @itemx -mpowerpc-gfxopt
6329 @itemx -mno-powerpc-gfxopt
6331 @itemx -mno-powerpc64
6337 @opindex mno-powerpc
6338 @opindex mpowerpc-gpopt
6339 @opindex mno-powerpc-gpopt
6340 @opindex mpowerpc-gfxopt
6341 @opindex mno-powerpc-gfxopt
6343 @opindex mno-powerpc64
6344 GCC supports two related instruction set architectures for the
6345 RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those
6346 instructions supported by the @samp{rios} chip set used in the original
6347 RS/6000 systems and the @dfn{PowerPC} instruction set is the
6348 architecture of the Motorola MPC5xx, MPC6xx, MPC8xx microprocessors, and
6349 the IBM 4xx microprocessors.
6351 Neither architecture is a subset of the other. However there is a
6352 large common subset of instructions supported by both. An MQ
6353 register is included in processors supporting the POWER architecture.
6355 You use these options to specify which instructions are available on the
6356 processor you are using. The default value of these options is
6357 determined when configuring GCC@. Specifying the
6358 @option{-mcpu=@var{cpu_type}} overrides the specification of these
6359 options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
6360 rather than the options listed above.
6362 The @option{-mpower} option allows GCC to generate instructions that
6363 are found only in the POWER architecture and to use the MQ register.
6364 Specifying @option{-mpower2} implies @option{-power} and also allows GCC
6365 to generate instructions that are present in the POWER2 architecture but
6366 not the original POWER architecture.
6368 The @option{-mpowerpc} option allows GCC to generate instructions that
6369 are found only in the 32-bit subset of the PowerPC architecture.
6370 Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
6371 GCC to use the optional PowerPC architecture instructions in the
6372 General Purpose group, including floating-point square root. Specifying
6373 @option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
6374 use the optional PowerPC architecture instructions in the Graphics
6375 group, including floating-point select.
6377 The @option{-mpowerpc64} option allows GCC to generate the additional
6378 64-bit instructions that are found in the full PowerPC64 architecture
6379 and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
6380 @option{-mno-powerpc64}.
6382 If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
6383 will use only the instructions in the common subset of both
6384 architectures plus some special AIX common-mode calls, and will not use
6385 the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
6386 permits GCC to use any instruction from either architecture and to
6387 allow use of the MQ register; specify this for the Motorola MPC601.
6389 @item -mnew-mnemonics
6390 @itemx -mold-mnemonics
6391 @opindex mnew-mnemonics
6392 @opindex mold-mnemonics
6393 Select which mnemonics to use in the generated assembler code. With
6394 @option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
6395 the PowerPC architecture. With @option{-mold-mnemonics} it uses the
6396 assembler mnemonics defined for the POWER architecture. Instructions
6397 defined in only one architecture have only one mnemonic; GCC uses that
6398 mnemonic irrespective of which of these options is specified.
6400 GCC defaults to the mnemonics appropriate for the architecture in
6401 use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
6402 value of these option. Unless you are building a cross-compiler, you
6403 should normally not specify either @option{-mnew-mnemonics} or
6404 @option{-mold-mnemonics}, but should instead accept the default.
6406 @item -mcpu=@var{cpu_type}
6408 Set architecture type, register usage, choice of mnemonics, and
6409 instruction scheduling parameters for machine type @var{cpu_type}.
6410 Supported values for @var{cpu_type} are @samp{rios}, @samp{rios1},
6411 @samp{rsc}, @samp{rios2}, @samp{rs64a}, @samp{601}, @samp{602},
6412 @samp{603}, @samp{603e}, @samp{604}, @samp{604e}, @samp{620},
6413 @samp{630}, @samp{740}, @samp{7400}, @samp{7450}, @samp{750},
6414 @samp{power}, @samp{power2}, @samp{powerpc}, @samp{403}, @samp{505},
6415 @samp{801}, @samp{821}, @samp{823}, and @samp{860} and @samp{common}.
6417 @option{-mcpu=common} selects a completely generic processor. Code
6418 generated under this option will run on any POWER or PowerPC processor.
6419 GCC will use only the instructions in the common subset of both
6420 architectures, and will not use the MQ register. GCC assumes a generic
6421 processor model for scheduling purposes.
6423 @option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
6424 @option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
6425 PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
6426 types, with an appropriate, generic processor model assumed for
6427 scheduling purposes.
6429 The other options specify a specific processor. Code generated under
6430 those options will run best on that processor, and may not run at all on
6433 The @option{-mcpu} options automatically enable or disable other
6434 @option{-m} options as follows:
6438 @option{-mno-power}, @option{-mno-powerc}
6445 @option{-mpower}, @option{-mno-powerpc}, @option{-mno-new-mnemonics}
6460 @option{-mno-power}, @option{-mpowerpc}, @option{-mnew-mnemonics}
6463 @option{-mpower}, @option{-mpowerpc}, @option{-mnew-mnemonics}
6468 @option{-mno-power}, @option{-mpowerpc}, @option{-mnew-mnemonics}, @option{-msoft-float}
6471 @item -mtune=@var{cpu_type}
6473 Set the instruction scheduling parameters for machine type
6474 @var{cpu_type}, but do not set the architecture type, register usage, or
6475 choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
6476 values for @var{cpu_type} are used for @option{-mtune} as for
6477 @option{-mcpu}. If both are specified, the code generated will use the
6478 architecture, registers, and mnemonics set by @option{-mcpu}, but the
6479 scheduling parameters set by @option{-mtune}.
6484 @opindex mno-altivec
6485 These switches enable or disable the use of built-in functions that
6486 allow access to the AltiVec instruction set. You may also need to set
6487 @option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
6491 @itemx -mno-fp-in-toc
6492 @itemx -mno-sum-in-toc
6493 @itemx -mminimal-toc
6495 @opindex mno-fp-in-toc
6496 @opindex mno-sum-in-toc
6497 @opindex mminimal-toc
6498 Modify generation of the TOC (Table Of Contents), which is created for
6499 every executable file. The @option{-mfull-toc} option is selected by
6500 default. In that case, GCC will allocate at least one TOC entry for
6501 each unique non-automatic variable reference in your program. GCC
6502 will also place floating-point constants in the TOC@. However, only
6503 16,384 entries are available in the TOC@.
6505 If you receive a linker error message that saying you have overflowed
6506 the available TOC space, you can reduce the amount of TOC space used
6507 with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
6508 @option{-mno-fp-in-toc} prevents GCC from putting floating-point
6509 constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
6510 generate code to calculate the sum of an address and a constant at
6511 run-time instead of putting that sum into the TOC@. You may specify one
6512 or both of these options. Each causes GCC to produce very slightly
6513 slower and larger code at the expense of conserving TOC space.
6515 If you still run out of space in the TOC even when you specify both of
6516 these options, specify @option{-mminimal-toc} instead. This option causes
6517 GCC to make only one TOC entry for every file. When you specify this
6518 option, GCC will produce code that is slower and larger but which
6519 uses extremely little TOC space. You may wish to use this option
6520 only on files that contain less frequently executed code.
6526 Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
6527 @code{long} type, and the infrastructure needed to support them.
6528 Specifying @option{-maix64} implies @option{-mpowerpc64} and
6529 @option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
6530 implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
6535 @opindex mno-xl-call
6536 On AIX, pass floating-point arguments to prototyped functions beyond the
6537 register save area (RSA) on the stack in addition to argument FPRs. The
6538 AIX calling convention was extended but not initially documented to
6539 handle an obscure K&R C case of calling a function that takes the
6540 address of its arguments with fewer arguments than declared. AIX XL
6541 compilers access floating point arguments which do not fit in the
6542 RSA from the stack when a subroutine is compiled without
6543 optimization. Because always storing floating-point arguments on the
6544 stack is inefficient and rarely needed, this option is not enabled by
6545 default and only is necessary when calling subroutines compiled by AIX
6546 XL compilers without optimization.
6550 Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
6551 application written to use message passing with special startup code to
6552 enable the application to run. The system must have PE installed in the
6553 standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
6554 must be overridden with the @option{-specs=} option to specify the
6555 appropriate directory location. The Parallel Environment does not
6556 support threads, so the @option{-mpe} option and the @option{-pthread}
6557 option are incompatible.
6561 @opindex msoft-float
6562 @opindex mhard-float
6563 Generate code that does not use (uses) the floating-point register set.
6564 Software floating point emulation is provided if you use the
6565 @option{-msoft-float} option, and pass the option to GCC when linking.
6568 @itemx -mno-multiple
6570 @opindex mno-multiple
6571 Generate code that uses (does not use) the load multiple word
6572 instructions and the store multiple word instructions. These
6573 instructions are generated by default on POWER systems, and not
6574 generated on PowerPC systems. Do not use @option{-mmultiple} on little
6575 endian PowerPC systems, since those instructions do not work when the
6576 processor is in little endian mode. The exceptions are PPC740 and
6577 PPC750 which permit the instructions usage in little endian mode.
6583 Generate code that uses (does not use) the load string instructions
6584 and the store string word instructions to save multiple registers and
6585 do small block moves. These instructions are generated by default on
6586 POWER systems, and not generated on PowerPC systems. Do not use
6587 @option{-mstring} on little endian PowerPC systems, since those
6588 instructions do not work when the processor is in little endian mode.
6589 The exceptions are PPC740 and PPC750 which permit the instructions
6590 usage in little endian mode.
6596 Generate code that uses (does not use) the load or store instructions
6597 that update the base register to the address of the calculated memory
6598 location. These instructions are generated by default. If you use
6599 @option{-mno-update}, there is a small window between the time that the
6600 stack pointer is updated and the address of the previous frame is
6601 stored, which means code that walks the stack frame across interrupts or
6602 signals may get corrupted data.
6605 @itemx -mno-fused-madd
6606 @opindex mfused-madd
6607 @opindex mno-fused-madd
6608 Generate code that uses (does not use) the floating point multiply and
6609 accumulate instructions. These instructions are generated by default if
6610 hardware floating is used.
6612 @item -mno-bit-align
6614 @opindex mno-bit-align
6616 On System V.4 and embedded PowerPC systems do not (do) force structures
6617 and unions that contain bit-fields to be aligned to the base type of the
6620 For example, by default a structure containing nothing but 8
6621 @code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
6622 boundary and have a size of 4 bytes. By using @option{-mno-bit-align},
6623 the structure would be aligned to a 1 byte boundary and be one byte in
6626 @item -mno-strict-align
6627 @itemx -mstrict-align
6628 @opindex mno-strict-align
6629 @opindex mstrict-align
6630 On System V.4 and embedded PowerPC systems do not (do) assume that
6631 unaligned memory references will be handled by the system.
6634 @itemx -mno-relocatable
6635 @opindex mrelocatable
6636 @opindex mno-relocatable
6637 On embedded PowerPC systems generate code that allows (does not allow)
6638 the program to be relocated to a different address at runtime. If you
6639 use @option{-mrelocatable} on any module, all objects linked together must
6640 be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
6642 @item -mrelocatable-lib
6643 @itemx -mno-relocatable-lib
6644 @opindex mrelocatable-lib
6645 @opindex mno-relocatable-lib
6646 On embedded PowerPC systems generate code that allows (does not allow)
6647 the program to be relocated to a different address at runtime. Modules
6648 compiled with @option{-mrelocatable-lib} can be linked with either modules
6649 compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
6650 with modules compiled with the @option{-mrelocatable} options.
6656 On System V.4 and embedded PowerPC systems do not (do) assume that
6657 register 2 contains a pointer to a global area pointing to the addresses
6658 used in the program.
6661 @itemx -mlittle-endian
6663 @opindex mlittle-endian
6664 On System V.4 and embedded PowerPC systems compile code for the
6665 processor in little endian mode. The @option{-mlittle-endian} option is
6666 the same as @option{-mlittle}.
6671 @opindex mbig-endian
6672 On System V.4 and embedded PowerPC systems compile code for the
6673 processor in big endian mode. The @option{-mbig-endian} option is
6674 the same as @option{-mbig}.
6678 On System V.4 and embedded PowerPC systems compile code using calling
6679 conventions that adheres to the March 1995 draft of the System V
6680 Application Binary Interface, PowerPC processor supplement. This is the
6681 default unless you configured GCC using @samp{powerpc-*-eabiaix}.
6683 @item -mcall-sysv-eabi
6684 @opindex mcall-sysv-eabi
6685 Specify both @option{-mcall-sysv} and @option{-meabi} options.
6687 @item -mcall-sysv-noeabi
6688 @opindex mcall-sysv-noeabi
6689 Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
6693 On System V.4 and embedded PowerPC systems compile code using calling
6694 conventions that are similar to those used on AIX@. This is the
6695 default if you configured GCC using @samp{powerpc-*-eabiaix}.
6697 @item -mcall-solaris
6698 @opindex mcall-solaris
6699 On System V.4 and embedded PowerPC systems compile code for the Solaris
6703 @opindex mcall-linux
6704 On System V.4 and embedded PowerPC systems compile code for the
6705 Linux-based GNU system.
6709 On System V.4 and embedded PowerPC systems compile code for the
6710 Hurd-based GNU system.
6713 @opindex mcall-netbsd
6714 On System V.4 and embedded PowerPC systems compile code for the
6715 NetBSD operating system.
6717 @item -maix-struct-return
6718 @opindex maix-struct-return
6719 Return all structures in memory (as specified by the AIX ABI)@.
6721 @item -msvr4-struct-return
6722 @opindex msvr4-struct-return
6723 Return structures smaller than 8 bytes in registers (as specified by the
6727 @opindex mabi=altivec
6728 Extend the current ABI with AltiVec ABI extensions. This does not
6729 change the default ABI, instead it adds the AltiVec ABI extensions to
6732 @item -mabi=no-altivec
6733 @opindex mabi=no-altivec
6734 Disable AltiVec ABI extensions for the current ABI.
6737 @itemx -mno-prototype
6739 @opindex mno-prototype
6740 On System V.4 and embedded PowerPC systems assume that all calls to
6741 variable argument functions are properly prototyped. Otherwise, the
6742 compiler must insert an instruction before every non prototyped call to
6743 set or clear bit 6 of the condition code register (@var{CR}) to
6744 indicate whether floating point values were passed in the floating point
6745 registers in case the function takes a variable arguments. With
6746 @option{-mprototype}, only calls to prototyped variable argument functions
6747 will set or clear the bit.
6751 On embedded PowerPC systems, assume that the startup module is called
6752 @file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
6753 @file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
6758 On embedded PowerPC systems, assume that the startup module is called
6759 @file{crt0.o} and the standard C libraries are @file{libmvme.a} and
6764 On embedded PowerPC systems, assume that the startup module is called
6765 @file{crt0.o} and the standard C libraries are @file{libads.a} and
6769 @opindex myellowknife
6770 On embedded PowerPC systems, assume that the startup module is called
6771 @file{crt0.o} and the standard C libraries are @file{libyk.a} and
6776 On System V.4 and embedded PowerPC systems, specify that you are
6777 compiling for a VxWorks system.
6781 Specify that you are compiling for the WindISS simulation environment.
6785 On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
6786 header to indicate that @samp{eabi} extended relocations are used.
6792 On System V.4 and embedded PowerPC systems do (do not) adhere to the
6793 Embedded Applications Binary Interface (eabi) which is a set of
6794 modifications to the System V.4 specifications. Selecting @option{-meabi}
6795 means that the stack is aligned to an 8 byte boundary, a function
6796 @code{__eabi} is called to from @code{main} to set up the eabi
6797 environment, and the @option{-msdata} option can use both @code{r2} and
6798 @code{r13} to point to two separate small data areas. Selecting
6799 @option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
6800 do not call an initialization function from @code{main}, and the
6801 @option{-msdata} option will only use @code{r13} to point to a single
6802 small data area. The @option{-meabi} option is on by default if you
6803 configured GCC using one of the @samp{powerpc*-*-eabi*} options.
6806 @opindex msdata=eabi
6807 On System V.4 and embedded PowerPC systems, put small initialized
6808 @code{const} global and static data in the @samp{.sdata2} section, which
6809 is pointed to by register @code{r2}. Put small initialized
6810 non-@code{const} global and static data in the @samp{.sdata} section,
6811 which is pointed to by register @code{r13}. Put small uninitialized
6812 global and static data in the @samp{.sbss} section, which is adjacent to
6813 the @samp{.sdata} section. The @option{-msdata=eabi} option is
6814 incompatible with the @option{-mrelocatable} option. The
6815 @option{-msdata=eabi} option also sets the @option{-memb} option.
6818 @opindex msdata=sysv
6819 On System V.4 and embedded PowerPC systems, put small global and static
6820 data in the @samp{.sdata} section, which is pointed to by register
6821 @code{r13}. Put small uninitialized global and static data in the
6822 @samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
6823 The @option{-msdata=sysv} option is incompatible with the
6824 @option{-mrelocatable} option.
6826 @item -msdata=default
6828 @opindex msdata=default
6830 On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
6831 compile code the same as @option{-msdata=eabi}, otherwise compile code the
6832 same as @option{-msdata=sysv}.
6835 @opindex msdata-data
6836 On System V.4 and embedded PowerPC systems, put small global and static
6837 data in the @samp{.sdata} section. Put small uninitialized global and
6838 static data in the @samp{.sbss} section. Do not use register @code{r13}
6839 to address small data however. This is the default behavior unless
6840 other @option{-msdata} options are used.
6844 @opindex msdata=none
6846 On embedded PowerPC systems, put all initialized global and static data
6847 in the @samp{.data} section, and all uninitialized data in the
6848 @samp{.bss} section.
6852 @cindex smaller data references (PowerPC)
6853 @cindex .sdata/.sdata2 references (PowerPC)
6854 On embedded PowerPC systems, put global and static items less than or
6855 equal to @var{num} bytes into the small data or bss sections instead of
6856 the normal data or bss section. By default, @var{num} is 8. The
6857 @option{-G @var{num}} switch is also passed to the linker.
6858 All modules should be compiled with the same @option{-G @var{num}} value.
6861 @itemx -mno-regnames
6863 @opindex mno-regnames
6864 On System V.4 and embedded PowerPC systems do (do not) emit register
6865 names in the assembly language output using symbolic forms.
6868 @itemx -mno-longcall
6870 @opindex mno-longcall
6871 Default to making all function calls via pointers, so that functions
6872 which reside further than 64 megabytes (67,108,864 bytes) from the
6873 current location can be called. This setting can be overridden by the
6874 @code{shortcall} function attribute, or by @code{#pragma longcall(0)}.
6876 Some linkers are capable of detecting out-of-range calls and generating
6877 glue code on the fly. On these systems, long calls are unnecessary and
6878 generate slower code. As of this writing, the AIX linker can do this,
6879 as can the GNU linker for PowerPC/64. It is planned to add this feature
6880 to the GNU linker for 32-bit PowerPC systems as well.
6882 In the future, we may cause GCC to ignore all longcall specifications
6883 when the linker is known to generate glue.
6887 Adds support for multithreading with the @dfn{pthreads} library.
6888 This option sets flags for both the preprocessor and linker.
6893 @subsection IBM RT Options
6895 @cindex IBM RT options
6897 These @samp{-m} options are defined for the IBM RT PC:
6901 @opindex min-line-mul
6902 Use an in-line code sequence for integer multiplies. This is the
6905 @item -mcall-lib-mul
6906 @opindex mcall-lib-mul
6907 Call @code{lmul$$} for integer multiples.
6909 @item -mfull-fp-blocks
6910 @opindex mfull-fp-blocks
6911 Generate full-size floating point data blocks, including the minimum
6912 amount of scratch space recommended by IBM@. This is the default.
6914 @item -mminimum-fp-blocks
6915 @opindex mminimum-fp-blocks
6916 Do not include extra scratch space in floating point data blocks. This
6917 results in smaller code, but slower execution, since scratch space must
6918 be allocated dynamically.
6920 @cindex @file{varargs.h} and RT PC
6921 @cindex @file{stdarg.h} and RT PC
6922 @item -mfp-arg-in-fpregs
6923 @opindex mfp-arg-in-fpregs
6924 Use a calling sequence incompatible with the IBM calling convention in
6925 which floating point arguments are passed in floating point registers.
6926 Note that @code{varargs.h} and @code{stdarg.h} will not work with
6927 floating point operands if this option is specified.
6929 @item -mfp-arg-in-gregs
6930 @opindex mfp-arg-in-gregs
6931 Use the normal calling convention for floating point arguments. This is
6934 @item -mhc-struct-return
6935 @opindex mhc-struct-return
6936 Return structures of more than one word in memory, rather than in a
6937 register. This provides compatibility with the MetaWare HighC (hc)
6938 compiler. Use the option @option{-fpcc-struct-return} for compatibility
6939 with the Portable C Compiler (pcc).
6941 @item -mnohc-struct-return
6942 @opindex mnohc-struct-return
6943 Return some structures of more than one word in registers, when
6944 convenient. This is the default. For compatibility with the
6945 IBM-supplied compilers, use the option @option{-fpcc-struct-return} or the
6946 option @option{-mhc-struct-return}.
6950 @subsection MIPS Options
6951 @cindex MIPS options
6953 These @samp{-m} options are defined for the MIPS family of computers:
6957 @item -march=@var{cpu-type}
6959 Assume the defaults for the machine type @var{cpu-type} when generating
6960 instructions. The choices for @var{cpu-type} are @samp{r2000}, @samp{r3000},
6961 @samp{r3900}, @samp{r4000}, @samp{r4100}, @samp{r4300}, @samp{r4400},
6962 @samp{r4600}, @samp{r4650}, @samp{r5000}, @samp{r6000}, @samp{r8000},
6963 and @samp{orion}. Additionally, the @samp{r2000}, @samp{r3000},
6964 @samp{r4000}, @samp{r5000}, and @samp{r6000} can be abbreviated as
6965 @samp{r2k} (or @samp{r2K}), @samp{r3k}, etc.
6967 @item -mtune=@var{cpu-type}
6969 Assume the defaults for the machine type @var{cpu-type} when scheduling
6970 instructions. The choices for @var{cpu-type} are @samp{r2000}, @samp{r3000},
6971 @samp{r3900}, @samp{r4000}, @samp{r4100}, @samp{r4300}, @samp{r4400},
6972 @samp{r4600}, @samp{r4650}, @samp{r5000}, @samp{r6000}, @samp{r8000},
6973 and @samp{orion}. Additionally, the @samp{r2000}, @samp{r3000},
6974 @samp{r4000}, @samp{r5000}, and @samp{r6000} can be abbreviated as
6975 @samp{r2k} (or @samp{r2K}), @samp{r3k}, etc. While picking a specific
6976 @var{cpu-type} will schedule things appropriately for that particular
6977 chip, the compiler will not generate any code that does not meet level 1
6978 of the MIPS ISA (instruction set architecture) without a @option{-mipsX}
6979 or @option{-mabi} switch being used.
6981 @item -mcpu=@var{cpu-type}
6983 This is identical to specifying both @option{-march} and @option{-mtune}.
6987 Issue instructions from level 1 of the MIPS ISA@. This is the default.
6988 @samp{r3000} is the default @var{cpu-type} at this ISA level.
6992 Issue instructions from level 2 of the MIPS ISA (branch likely, square
6993 root instructions). @samp{r6000} is the default @var{cpu-type} at this
6998 Issue instructions from level 3 of the MIPS ISA (64-bit instructions).
6999 @samp{r4000} is the default @var{cpu-type} at this ISA level.
7003 Issue instructions from level 4 of the MIPS ISA (conditional move,
7004 prefetch, enhanced FPU instructions). @samp{r8000} is the default
7005 @var{cpu-type} at this ISA level.
7009 Assume that 32 32-bit floating point registers are available. This is
7014 Assume that 32 64-bit floating point registers are available. This is
7015 the default when the @option{-mips3} option is used.
7018 @itemx -mno-fused-madd
7019 @opindex mfused-madd
7020 @opindex mno-fused-madd
7021 Generate code that uses (does not use) the floating point multiply and
7022 accumulate instructions, when they are available. These instructions
7023 are generated by default if they are available, but this may be
7024 undesirable if the extra precision causes problems or on certain chips
7025 in the mode where denormals are rounded to zero where denormals
7026 generated by multiply and accumulate instructions cause exceptions
7031 Assume that 32 32-bit general purpose registers are available. This is
7036 Assume that 32 64-bit general purpose registers are available. This is
7037 the default when the @option{-mips3} option is used.
7041 Force int and long types to be 64 bits wide. See @option{-mlong32} for an
7042 explanation of the default, and the width of pointers.
7046 Force long types to be 64 bits wide. See @option{-mlong32} for an
7047 explanation of the default, and the width of pointers.
7051 Force long, int, and pointer types to be 32 bits wide.
7053 If none of @option{-mlong32}, @option{-mlong64}, or @option{-mint64} are set,
7054 the size of ints, longs, and pointers depends on the ABI and ISA chosen.
7055 For @option{-mabi=32}, and @option{-mabi=n32}, ints and longs are 32 bits
7056 wide. For @option{-mabi=64}, ints are 32 bits, and longs are 64 bits wide.
7057 For @option{-mabi=eabi} and either @option{-mips1} or @option{-mips2}, ints
7058 and longs are 32 bits wide. For @option{-mabi=eabi} and higher ISAs, ints
7059 are 32 bits, and longs are 64 bits wide. The width of pointer types is
7060 the smaller of the width of longs or the width of general purpose
7061 registers (which in turn depends on the ISA)@.
7073 Generate code for the indicated ABI@. The default instruction level is
7074 @option{-mips1} for @samp{32}, @option{-mips3} for @samp{n32}, and
7075 @option{-mips4} otherwise. Conversely, with @option{-mips1} or
7076 @option{-mips2}, the default ABI is @samp{32}; otherwise, the default ABI
7081 Generate code for the MIPS assembler, and invoke @file{mips-tfile} to
7082 add normal debug information. This is the default for all
7083 platforms except for the OSF/1 reference platform, using the OSF/rose
7084 object format. If the either of the @option{-gstabs} or @option{-gstabs+}
7085 switches are used, the @file{mips-tfile} program will encapsulate the
7086 stabs within MIPS ECOFF@.
7090 Generate code for the GNU assembler. This is the default on the OSF/1
7091 reference platform, using the OSF/rose object format. Also, this is
7092 the default if the configure option @option{--with-gnu-as} is used.
7094 @item -msplit-addresses
7095 @itemx -mno-split-addresses
7096 @opindex msplit-addresses
7097 @opindex mno-split-addresses
7098 Generate code to load the high and low parts of address constants separately.
7099 This allows GCC to optimize away redundant loads of the high order
7100 bits of addresses. This optimization requires GNU as and GNU ld.
7101 This optimization is enabled by default for some embedded targets where
7102 GNU as and GNU ld are standard.
7108 The @option{-mrnames} switch says to output code using the MIPS software
7109 names for the registers, instead of the hardware names (ie, @var{a0}
7110 instead of @var{$4}). The only known assembler that supports this option
7111 is the Algorithmics assembler.
7117 The @option{-mgpopt} switch says to write all of the data declarations
7118 before the instructions in the text section, this allows the MIPS
7119 assembler to generate one word memory references instead of using two
7120 words for short global or static data items. This is on by default if
7121 optimization is selected.
7127 For each non-inline function processed, the @option{-mstats} switch
7128 causes the compiler to emit one line to the standard error file to
7129 print statistics about the program (number of registers saved, stack
7136 The @option{-mmemcpy} switch makes all block moves call the appropriate
7137 string function (@samp{memcpy} or @samp{bcopy}) instead of possibly
7138 generating inline code.
7141 @itemx -mno-mips-tfile
7142 @opindex mmips-tfile
7143 @opindex mno-mips-tfile
7144 The @option{-mno-mips-tfile} switch causes the compiler not
7145 postprocess the object file with the @file{mips-tfile} program,
7146 after the MIPS assembler has generated it to add debug support. If
7147 @file{mips-tfile} is not run, then no local variables will be
7148 available to the debugger. In addition, @file{stage2} and
7149 @file{stage3} objects will have the temporary file names passed to the
7150 assembler embedded in the object file, which means the objects will
7151 not compare the same. The @option{-mno-mips-tfile} switch should only
7152 be used when there are bugs in the @file{mips-tfile} program that
7153 prevents compilation.
7156 @opindex msoft-float
7157 Generate output containing library calls for floating point.
7158 @strong{Warning:} the requisite libraries are not part of GCC@.
7159 Normally the facilities of the machine's usual C compiler are used, but
7160 this can't be done directly in cross-compilation. You must make your
7161 own arrangements to provide suitable library functions for
7165 @opindex mhard-float
7166 Generate output containing floating point instructions. This is the
7167 default if you use the unmodified sources.
7170 @itemx -mno-abicalls
7172 @opindex mno-abicalls
7173 Emit (or do not emit) the pseudo operations @samp{.abicalls},
7174 @samp{.cpload}, and @samp{.cprestore} that some System V.4 ports use for
7175 position independent code.
7178 @itemx -mno-long-calls
7179 @opindex mlong-calls
7180 @opindex mno-long-calls
7181 Do all calls with the @samp{JALR} instruction, which requires
7182 loading up a function's address into a register before the call.
7183 You need to use this switch, if you call outside of the current
7184 512 megabyte segment to functions that are not through pointers.
7187 @itemx -mno-half-pic
7189 @opindex mno-half-pic
7190 Put pointers to extern references into the data section and load them
7191 up, rather than put the references in the text section.
7193 @item -membedded-pic
7194 @itemx -mno-embedded-pic
7195 @opindex membedded-pic
7196 @opindex mno-embedded-pic
7197 Generate PIC code suitable for some embedded systems. All calls are
7198 made using PC relative address, and all data is addressed using the $gp
7199 register. No more than 65536 bytes of global data may be used. This
7200 requires GNU as and GNU ld which do most of the work. This currently
7201 only works on targets which use ECOFF; it does not work with ELF@.
7203 @item -membedded-data
7204 @itemx -mno-embedded-data
7205 @opindex membedded-data
7206 @opindex mno-embedded-data
7207 Allocate variables to the read-only data section first if possible, then
7208 next in the small data section if possible, otherwise in data. This gives
7209 slightly slower code than the default, but reduces the amount of RAM required
7210 when executing, and thus may be preferred for some embedded systems.
7212 @item -muninit-const-in-rodata
7213 @itemx -mno-uninit-const-in-rodata
7214 @opindex muninit-const-in-rodata
7215 @opindex mno-uninit-const-in-rodata
7216 When used together with @option{-membedded-data}, it will always store uninitialized
7217 const variables in the read-only data section.
7219 @item -msingle-float
7220 @itemx -mdouble-float
7221 @opindex msingle-float
7222 @opindex mdouble-float
7223 The @option{-msingle-float} switch tells gcc to assume that the floating
7224 point coprocessor only supports single precision operations, as on the
7225 @samp{r4650} chip. The @option{-mdouble-float} switch permits gcc to use
7226 double precision operations. This is the default.
7232 Permit use of the @samp{mad}, @samp{madu} and @samp{mul} instructions,
7233 as on the @samp{r4650} chip.
7237 Turns on @option{-msingle-float}, @option{-mmad}, and, at least for now,
7238 @option{-mcpu=r4650}.
7244 Enable 16-bit instructions.
7248 Use the entry and exit pseudo ops. This option can only be used with
7253 Compile code for the processor in little endian mode.
7254 The requisite libraries are assumed to exist.
7258 Compile code for the processor in big endian mode.
7259 The requisite libraries are assumed to exist.
7263 @cindex smaller data references (MIPS)
7264 @cindex gp-relative references (MIPS)
7265 Put global and static items less than or equal to @var{num} bytes into
7266 the small data or bss sections instead of the normal data or bss
7267 section. This allows the assembler to emit one word memory reference
7268 instructions based on the global pointer (@var{gp} or @var{$28}),
7269 instead of the normal two words used. By default, @var{num} is 8 when
7270 the MIPS assembler is used, and 0 when the GNU assembler is used. The
7271 @option{-G @var{num}} switch is also passed to the assembler and linker.
7272 All modules should be compiled with the same @option{-G @var{num}}
7277 Tell the MIPS assembler to not run its preprocessor over user
7278 assembler files (with a @samp{.s} suffix) when assembling them.
7282 Pass an option to gas which will cause nops to be inserted if
7283 the read of the destination register of an mfhi or mflo instruction
7284 occurs in the following two instructions.
7288 Do not include the default crt0.
7290 @item -mflush-func=@var{func}
7291 @itemx -mno-flush-func
7292 @opindex mflush-func
7293 Specifies the function to call to flush the I and D caches, or to not
7294 call any such function. If called, the function must take the same
7295 arguments as the common @code{_flush_func()}, that is, the address of the
7296 memory range for which the cache is being flushed, the size of the
7297 memory range, and the number 3 (to flush both caches). The default
7298 depends on the target gcc was configured for, but commonly is either
7299 @samp{_flush_func} or @samp{__cpu_flush}.
7302 These options are defined by the macro
7303 @code{TARGET_SWITCHES} in the machine description. The default for the
7304 options is also defined by that macro, which enables you to change the
7307 @node i386 and x86-64 Options
7308 @subsection Intel 386 and AMD x86-64 Options
7309 @cindex i386 Options
7310 @cindex x86-64 Options
7311 @cindex Intel 386 Options
7312 @cindex AMD x86-64 Options
7314 These @samp{-m} options are defined for the i386 and x86-64 family of
7318 @item -mcpu=@var{cpu-type}
7320 Tune to @var{cpu-type} everything applicable about the generated code, except
7321 for the ABI and the set of available instructions. The choices for
7322 @var{cpu-type} are @samp{i386}, @samp{i486}, @samp{i586}, @samp{i686},
7323 @samp{pentium}, @samp{pentium-mmx}, @samp{pentiumpro}, @samp{pentium2},
7324 @samp{pentium3}, @samp{pentium4}, @samp{k6}, @samp{k6-2}, @samp{k6-3},
7325 @samp{athlon}, @samp{athlon-tbird}, @samp{athlon-4}, @samp{athlon-xp}
7326 and @samp{athlon-mp}.
7328 While picking a specific @var{cpu-type} will schedule things appropriately
7329 for that particular chip, the compiler will not generate any code that
7330 does not run on the i386 without the @option{-march=@var{cpu-type}} option
7331 being used. @samp{i586} is equivalent to @samp{pentium} and @samp{i686}
7332 is equivalent to @samp{pentiumpro}. @samp{k6} and @samp{athlon} are the
7333 AMD chips as opposed to the Intel ones.
7335 @item -march=@var{cpu-type}
7337 Generate instructions for the machine type @var{cpu-type}. The choices
7338 for @var{cpu-type} are the same as for @option{-mcpu}. Moreover,
7339 specifying @option{-march=@var{cpu-type}} implies @option{-mcpu=@var{cpu-type}}.
7348 @opindex mpentiumpro
7349 These options are synonyms for @option{-mcpu=i386}, @option{-mcpu=i486},
7350 @option{-mcpu=pentium}, and @option{-mcpu=pentiumpro} respectively.
7351 These synonyms are deprecated.
7353 @item -mfpmath=@var{unit}
7355 generate floating point arithmetics for selected unit @var{unit}. the choices
7360 Use the standard 387 floating point coprocessor present majority of chips and
7361 emulated otherwise. Code compiled with this option will run almost everywhere.
7362 The temporary results are computed in 80bit precesion instead of precision
7363 specified by the type resulting in slightly different results compared to most
7364 of other chips. See @option{-ffloat-store} for more detailed description.
7366 This is the default choice for i386 compiler.
7369 Use scalar floating point instructions present in the SSE instruction set.
7370 This instruction set is supported by Pentium3 and newer chips, in the AMD line
7371 by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE
7372 instruction set supports only single precision arithmetics, thus the double and
7373 extended precision arithmetics is still done using 387. Later version, present
7374 only in Pentium4 and the future AMD x86-64 chips supports double precision
7377 For i387 you need to use @option{-march=@var{cpu-type}}, @option{-msse} or
7378 @option{-msse2} switches to enable SSE extensions and make this option
7379 effective. For x86-64 compiler, these extensions are enabled by default.
7381 The resulting code should be considerably faster in majority of cases and avoid
7382 the numerical instability problems of 387 code, but may break some existing
7383 code that expects temporaries to be 80bit.
7385 This is the default choice for x86-64 compiler.
7388 Attempt to utilize both instruction sets at once. This effectivly double the
7389 amount of available registers and on chips with separate execution units for
7390 387 and SSE the execution resources too. Use this option with care, as it is
7391 still experimental, because gcc register allocator does not model separate
7392 functional units well resulting in instable performance.
7395 @item -masm=@var{dialect}
7396 @opindex masm=@var{dialect}
7397 Output asm instructions using selected @var{dialect}. Supported choices are
7398 @samp{intel} or @samp{att} (the default one).
7403 @opindex mno-ieee-fp
7404 Control whether or not the compiler uses IEEE floating point
7405 comparisons. These handle correctly the case where the result of a
7406 comparison is unordered.
7409 @opindex msoft-float
7410 Generate output containing library calls for floating point.
7411 @strong{Warning:} the requisite libraries are not part of GCC@.
7412 Normally the facilities of the machine's usual C compiler are used, but
7413 this can't be done directly in cross-compilation. You must make your
7414 own arrangements to provide suitable library functions for
7417 On machines where a function returns floating point results in the 80387
7418 register stack, some floating point opcodes may be emitted even if
7419 @option{-msoft-float} is used.
7421 @item -mno-fp-ret-in-387
7422 @opindex mno-fp-ret-in-387
7423 Do not use the FPU registers for return values of functions.
7425 The usual calling convention has functions return values of types
7426 @code{float} and @code{double} in an FPU register, even if there
7427 is no FPU@. The idea is that the operating system should emulate
7430 The option @option{-mno-fp-ret-in-387} causes such values to be returned
7431 in ordinary CPU registers instead.
7433 @item -mno-fancy-math-387
7434 @opindex mno-fancy-math-387
7435 Some 387 emulators do not support the @code{sin}, @code{cos} and
7436 @code{sqrt} instructions for the 387. Specify this option to avoid
7437 generating those instructions. This option is the default on FreeBSD,
7438 OpenBSD and NetBSD@. This option is overridden when @option{-march}
7439 indicates that the target cpu will always have an FPU and so the
7440 instruction will not need emulation. As of revision 2.6.1, these
7441 instructions are not generated unless you also use the
7442 @option{-funsafe-math-optimizations} switch.
7444 @item -malign-double
7445 @itemx -mno-align-double
7446 @opindex malign-double
7447 @opindex mno-align-double
7448 Control whether GCC aligns @code{double}, @code{long double}, and
7449 @code{long long} variables on a two word boundary or a one word
7450 boundary. Aligning @code{double} variables on a two word boundary will
7451 produce code that runs somewhat faster on a @samp{Pentium} at the
7452 expense of more memory.
7454 @strong{Warning:} if you use the @samp{-malign-double} switch,
7455 structures containing the above types will be aligned differently than
7456 the published application binary interface specifications for the 386.
7458 @item -m128bit-long-double
7459 @opindex m128bit-long-double
7460 Control the size of @code{long double} type. i386 application binary interface
7461 specify the size to be 12 bytes, while modern architectures (Pentium and newer)
7462 prefer @code{long double} aligned to 8 or 16 byte boundary. This is
7463 impossible to reach with 12 byte long doubles in the array accesses.
7465 @strong{Warning:} if you use the @option{-m128bit-long-double} switch, the
7466 structures and arrays containing @code{long double} will change their size as
7467 well as function calling convention for function taking @code{long double}
7470 @item -m96bit-long-double
7471 @opindex m96bit-long-double
7472 Set the size of @code{long double} to 96 bits as required by the i386
7473 application binary interface. This is the default.
7476 @itemx -mno-svr3-shlib
7477 @opindex msvr3-shlib
7478 @opindex mno-svr3-shlib
7479 Control whether GCC places uninitialized local variables into the
7480 @code{bss} or @code{data} segments. @option{-msvr3-shlib} places them
7481 into @code{bss}. These options are meaningful only on System V Release 3.
7485 Use a different function-calling convention, in which functions that
7486 take a fixed number of arguments return with the @code{ret} @var{num}
7487 instruction, which pops their arguments while returning. This saves one
7488 instruction in the caller since there is no need to pop the arguments
7491 You can specify that an individual function is called with this calling
7492 sequence with the function attribute @samp{stdcall}. You can also
7493 override the @option{-mrtd} option by using the function attribute
7494 @samp{cdecl}. @xref{Function Attributes}.
7496 @strong{Warning:} this calling convention is incompatible with the one
7497 normally used on Unix, so you cannot use it if you need to call
7498 libraries compiled with the Unix compiler.
7500 Also, you must provide function prototypes for all functions that
7501 take variable numbers of arguments (including @code{printf});
7502 otherwise incorrect code will be generated for calls to those
7505 In addition, seriously incorrect code will result if you call a
7506 function with too many arguments. (Normally, extra arguments are
7507 harmlessly ignored.)
7509 @item -mregparm=@var{num}
7511 Control how many registers are used to pass integer arguments. By
7512 default, no registers are used to pass arguments, and at most 3
7513 registers can be used. You can control this behavior for a specific
7514 function by using the function attribute @samp{regparm}.
7515 @xref{Function Attributes}.
7517 @strong{Warning:} if you use this switch, and
7518 @var{num} is nonzero, then you must build all modules with the same
7519 value, including any libraries. This includes the system libraries and
7522 @item -mpreferred-stack-boundary=@var{num}
7523 @opindex mpreferred-stack-boundary
7524 Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
7525 byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
7526 the default is 4 (16 bytes or 128 bits), except when optimizing for code
7527 size (@option{-Os}), in which case the default is the minimum correct
7528 alignment (4 bytes for x86, and 8 bytes for x86-64).
7530 On Pentium and PentiumPro, @code{double} and @code{long double} values
7531 should be aligned to an 8 byte boundary (see @option{-malign-double}) or
7532 suffer significant run time performance penalties. On Pentium III, the
7533 Streaming SIMD Extension (SSE) data type @code{__m128} suffers similar
7534 penalties if it is not 16 byte aligned.
7536 To ensure proper alignment of this values on the stack, the stack boundary
7537 must be as aligned as that required by any value stored on the stack.
7538 Further, every function must be generated such that it keeps the stack
7539 aligned. Thus calling a function compiled with a higher preferred
7540 stack boundary from a function compiled with a lower preferred stack
7541 boundary will most likely misalign the stack. It is recommended that
7542 libraries that use callbacks always use the default setting.
7544 This extra alignment does consume extra stack space, and generally
7545 increases code size. Code that is sensitive to stack space usage, such
7546 as embedded systems and operating system kernels, may want to reduce the
7547 preferred alignment to @option{-mpreferred-stack-boundary=2}.
7563 These switches enable or disable the use of built-in functions that allow
7564 direct access to the MMX, SSE and 3Dnow extensions of the instruction set.
7566 @xref{X86 Built-in Functions}, for details of the functions enabled
7567 and disabled by these switches.
7570 @itemx -mno-push-args
7572 @opindex mno-push-args
7573 Use PUSH operations to store outgoing parameters. This method is shorter
7574 and usually equally fast as method using SUB/MOV operations and is enabled
7575 by default. In some cases disabling it may improve performance because of
7576 improved scheduling and reduced dependencies.
7578 @item -maccumulate-outgoing-args
7579 @opindex maccumulate-outgoing-args
7580 If enabled, the maximum amount of space required for outgoing arguments will be
7581 computed in the function prologue. This is faster on most modern CPUs
7582 because of reduced dependencies, improved scheduling and reduced stack usage
7583 when preferred stack boundary is not equal to 2. The drawback is a notable
7584 increase in code size. This switch implies @option{-mno-push-args}.
7588 Support thread-safe exception handling on @samp{Mingw32}. Code that relies
7589 on thread-safe exception handling must compile and link all code with the
7590 @option{-mthreads} option. When compiling, @option{-mthreads} defines
7591 @option{-D_MT}; when linking, it links in a special thread helper library
7592 @option{-lmingwthrd} which cleans up per thread exception handling data.
7594 @item -mno-align-stringops
7595 @opindex mno-align-stringops
7596 Do not align destination of inlined string operations. This switch reduces
7597 code size and improves performance in case the destination is already aligned,
7598 but gcc don't know about it.
7600 @item -minline-all-stringops
7601 @opindex minline-all-stringops
7602 By default GCC inlines string operations only when destination is known to be
7603 aligned at least to 4 byte boundary. This enables more inlining, increase code
7604 size, but may improve performance of code that depends on fast memcpy, strlen
7605 and memset for short lengths.
7607 @item -momit-leaf-frame-pointer
7608 @opindex momit-leaf-frame-pointer
7609 Don't keep the frame pointer in a register for leaf functions. This
7610 avoids the instructions to save, set up and restore frame pointers and
7611 makes an extra register available in leaf functions. The option
7612 @option{-fomit-frame-pointer} removes the frame pointer for all functions
7613 which might make debugging harder.
7616 These @samp{-m} switches are supported in addition to the above
7617 on AMD x86-64 processors in 64-bit environments.
7624 Generate code for a 32-bit or 64-bit environment.
7625 The 32-bit environment sets int, long and pointer to 32 bits and
7626 generates code that runs on any i386 system.
7627 The 64-bit environment sets int to 32 bits and long and pointer
7628 to 64 bits and generates code for AMD's x86-64 architecture.
7631 @opindex no-red-zone
7632 Do not use a so called red zone for x86-64 code. The red zone is mandated
7633 by the x86-64 ABI, it is a 128-byte area beyond the location of the
7634 stack pointer that will not be modified by signal or interrupt handlers
7635 and therefore can be used for temporary data without adjusting the stack
7636 pointer. The flag @option{-mno-red-zone} disables this red zone.
7640 @subsection HPPA Options
7641 @cindex HPPA Options
7643 These @samp{-m} options are defined for the HPPA family of computers:
7646 @item -march=@var{architecture-type}
7648 Generate code for the specified architecture. The choices for
7649 @var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
7650 1.1, and @samp{2.0} for PA 2.0 processors. Refer to
7651 @file{/usr/lib/sched.models} on an HP-UX system to determine the proper
7652 architecture option for your machine. Code compiled for lower numbered
7653 architectures will run on higher numbered architectures, but not the
7656 PA 2.0 support currently requires gas snapshot 19990413 or later. The
7657 next release of binutils (current is 2.9.1) will probably contain PA 2.0
7661 @itemx -mpa-risc-1-1
7662 @itemx -mpa-risc-2-0
7663 @opindex mpa-risc-1-0
7664 @opindex mpa-risc-1-1
7665 @opindex mpa-risc-2-0
7666 Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
7669 @opindex mbig-switch
7670 Generate code suitable for big switch tables. Use this option only if
7671 the assembler/linker complain about out of range branches within a switch
7674 @item -mjump-in-delay
7675 @opindex mjump-in-delay
7676 Fill delay slots of function calls with unconditional jump instructions
7677 by modifying the return pointer for the function call to be the target
7678 of the conditional jump.
7680 @item -mdisable-fpregs
7681 @opindex mdisable-fpregs
7682 Prevent floating point registers from being used in any manner. This is
7683 necessary for compiling kernels which perform lazy context switching of
7684 floating point registers. If you use this option and attempt to perform
7685 floating point operations, the compiler will abort.
7687 @item -mdisable-indexing
7688 @opindex mdisable-indexing
7689 Prevent the compiler from using indexing address modes. This avoids some
7690 rather obscure problems when compiling MIG generated code under MACH@.
7692 @item -mno-space-regs
7693 @opindex mno-space-regs
7694 Generate code that assumes the target has no space registers. This allows
7695 GCC to generate faster indirect calls and use unscaled index address modes.
7697 Such code is suitable for level 0 PA systems and kernels.
7699 @item -mfast-indirect-calls
7700 @opindex mfast-indirect-calls
7701 Generate code that assumes calls never cross space boundaries. This
7702 allows GCC to emit code which performs faster indirect calls.
7704 This option will not work in the presence of shared libraries or nested
7707 @item -mlong-load-store
7708 @opindex mlong-load-store
7709 Generate 3-instruction load and store sequences as sometimes required by
7710 the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
7713 @item -mportable-runtime
7714 @opindex mportable-runtime
7715 Use the portable calling conventions proposed by HP for ELF systems.
7719 Enable the use of assembler directives only GAS understands.
7721 @item -mschedule=@var{cpu-type}
7723 Schedule code according to the constraints for the machine type
7724 @var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
7725 @samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer
7726 to @file{/usr/lib/sched.models} on an HP-UX system to determine the
7727 proper scheduling option for your machine. The default scheduling is
7731 @opindex mlinker-opt
7732 Enable the optimization pass in the HPUX linker. Note this makes symbolic
7733 debugging impossible. It also triggers a bug in the HPUX 8 and HPUX 9 linkers
7734 in which they give bogus error messages when linking some programs.
7737 @opindex msoft-float
7738 Generate output containing library calls for floating point.
7739 @strong{Warning:} the requisite libraries are not available for all HPPA
7740 targets. Normally the facilities of the machine's usual C compiler are
7741 used, but this cannot be done directly in cross-compilation. You must make
7742 your own arrangements to provide suitable library functions for
7743 cross-compilation. The embedded target @samp{hppa1.1-*-pro}
7744 does provide software floating point support.
7746 @option{-msoft-float} changes the calling convention in the output file;
7747 therefore, it is only useful if you compile @emph{all} of a program with
7748 this option. In particular, you need to compile @file{libgcc.a}, the
7749 library that comes with GCC, with @option{-msoft-float} in order for
7753 @node Intel 960 Options
7754 @subsection Intel 960 Options
7756 These @samp{-m} options are defined for the Intel 960 implementations:
7759 @item -m@var{cpu-type}
7767 Assume the defaults for the machine type @var{cpu-type} for some of
7768 the other options, including instruction scheduling, floating point
7769 support, and addressing modes. The choices for @var{cpu-type} are
7770 @samp{ka}, @samp{kb}, @samp{mc}, @samp{ca}, @samp{cf},
7771 @samp{sa}, and @samp{sb}.
7778 @opindex msoft-float
7779 The @option{-mnumerics} option indicates that the processor does support
7780 floating-point instructions. The @option{-msoft-float} option indicates
7781 that floating-point support should not be assumed.
7783 @item -mleaf-procedures
7784 @itemx -mno-leaf-procedures
7785 @opindex mleaf-procedures
7786 @opindex mno-leaf-procedures
7787 Do (or do not) attempt to alter leaf procedures to be callable with the
7788 @code{bal} instruction as well as @code{call}. This will result in more
7789 efficient code for explicit calls when the @code{bal} instruction can be
7790 substituted by the assembler or linker, but less efficient code in other
7791 cases, such as calls via function pointers, or using a linker that doesn't
7792 support this optimization.
7795 @itemx -mno-tail-call
7797 @opindex mno-tail-call
7798 Do (or do not) make additional attempts (beyond those of the
7799 machine-independent portions of the compiler) to optimize tail-recursive
7800 calls into branches. You may not want to do this because the detection of
7801 cases where this is not valid is not totally complete. The default is
7802 @option{-mno-tail-call}.
7804 @item -mcomplex-addr
7805 @itemx -mno-complex-addr
7806 @opindex mcomplex-addr
7807 @opindex mno-complex-addr
7808 Assume (or do not assume) that the use of a complex addressing mode is a
7809 win on this implementation of the i960. Complex addressing modes may not
7810 be worthwhile on the K-series, but they definitely are on the C-series.
7811 The default is currently @option{-mcomplex-addr} for all processors except
7815 @itemx -mno-code-align
7816 @opindex mcode-align
7817 @opindex mno-code-align
7818 Align code to 8-byte boundaries for faster fetching (or don't bother).
7819 Currently turned on by default for C-series implementations only.
7822 @item -mclean-linkage
7823 @itemx -mno-clean-linkage
7824 @opindex mclean-linkage
7825 @opindex mno-clean-linkage
7826 These options are not fully implemented.
7830 @itemx -mic2.0-compat
7831 @itemx -mic3.0-compat
7833 @opindex mic2.0-compat
7834 @opindex mic3.0-compat
7835 Enable compatibility with iC960 v2.0 or v3.0.
7839 @opindex masm-compat
7841 Enable compatibility with the iC960 assembler.
7843 @item -mstrict-align
7844 @itemx -mno-strict-align
7845 @opindex mstrict-align
7846 @opindex mno-strict-align
7847 Do not permit (do permit) unaligned accesses.
7851 Enable structure-alignment compatibility with Intel's gcc release version
7852 1.3 (based on gcc 1.37). This option implies @option{-mstrict-align}.
7854 @item -mlong-double-64
7855 @opindex mlong-double-64
7856 Implement type @samp{long double} as 64-bit floating point numbers.
7857 Without the option @samp{long double} is implemented by 80-bit
7858 floating point numbers. The only reason we have it because there is
7859 no 128-bit @samp{long double} support in @samp{fp-bit.c} yet. So it
7860 is only useful for people using soft-float targets. Otherwise, we
7861 should recommend against use of it.
7865 @node DEC Alpha Options
7866 @subsection DEC Alpha Options
7868 These @samp{-m} options are defined for the DEC Alpha implementations:
7871 @item -mno-soft-float
7873 @opindex mno-soft-float
7874 @opindex msoft-float
7875 Use (do not use) the hardware floating-point instructions for
7876 floating-point operations. When @option{-msoft-float} is specified,
7877 functions in @file{libgcc.a} will be used to perform floating-point
7878 operations. Unless they are replaced by routines that emulate the
7879 floating-point operations, or compiled in such a way as to call such
7880 emulations routines, these routines will issue floating-point
7881 operations. If you are compiling for an Alpha without floating-point
7882 operations, you must ensure that the library is built so as not to call
7885 Note that Alpha implementations without floating-point operations are
7886 required to have floating-point registers.
7891 @opindex mno-fp-regs
7892 Generate code that uses (does not use) the floating-point register set.
7893 @option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
7894 register set is not used, floating point operands are passed in integer
7895 registers as if they were integers and floating-point results are passed
7896 in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
7897 so any function with a floating-point argument or return value called by code
7898 compiled with @option{-mno-fp-regs} must also be compiled with that
7901 A typical use of this option is building a kernel that does not use,
7902 and hence need not save and restore, any floating-point registers.
7906 The Alpha architecture implements floating-point hardware optimized for
7907 maximum performance. It is mostly compliant with the IEEE floating
7908 point standard. However, for full compliance, software assistance is
7909 required. This option generates code fully IEEE compliant code
7910 @emph{except} that the @var{inexact-flag} is not maintained (see below).
7911 If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
7912 defined during compilation. The resulting code is less efficient but is
7913 able to correctly support denormalized numbers and exceptional IEEE
7914 values such as not-a-number and plus/minus infinity. Other Alpha
7915 compilers call this option @option{-ieee_with_no_inexact}.
7917 @item -mieee-with-inexact
7918 @opindex mieee-with-inexact
7919 This is like @option{-mieee} except the generated code also maintains
7920 the IEEE @var{inexact-flag}. Turning on this option causes the
7921 generated code to implement fully-compliant IEEE math. In addition to
7922 @code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
7923 macro. On some Alpha implementations the resulting code may execute
7924 significantly slower than the code generated by default. Since there is
7925 very little code that depends on the @var{inexact-flag}, you should
7926 normally not specify this option. Other Alpha compilers call this
7927 option @option{-ieee_with_inexact}.
7929 @item -mfp-trap-mode=@var{trap-mode}
7930 @opindex mfp-trap-mode
7931 This option controls what floating-point related traps are enabled.
7932 Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
7933 The trap mode can be set to one of four values:
7937 This is the default (normal) setting. The only traps that are enabled
7938 are the ones that cannot be disabled in software (e.g., division by zero
7942 In addition to the traps enabled by @samp{n}, underflow traps are enabled
7946 Like @samp{su}, but the instructions are marked to be safe for software
7947 completion (see Alpha architecture manual for details).
7950 Like @samp{su}, but inexact traps are enabled as well.
7953 @item -mfp-rounding-mode=@var{rounding-mode}
7954 @opindex mfp-rounding-mode
7955 Selects the IEEE rounding mode. Other Alpha compilers call this option
7956 @option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
7961 Normal IEEE rounding mode. Floating point numbers are rounded towards
7962 the nearest machine number or towards the even machine number in case
7966 Round towards minus infinity.
7969 Chopped rounding mode. Floating point numbers are rounded towards zero.
7972 Dynamic rounding mode. A field in the floating point control register
7973 (@var{fpcr}, see Alpha architecture reference manual) controls the
7974 rounding mode in effect. The C library initializes this register for
7975 rounding towards plus infinity. Thus, unless your program modifies the
7976 @var{fpcr}, @samp{d} corresponds to round towards plus infinity.
7979 @item -mtrap-precision=@var{trap-precision}
7980 @opindex mtrap-precision
7981 In the Alpha architecture, floating point traps are imprecise. This
7982 means without software assistance it is impossible to recover from a
7983 floating trap and program execution normally needs to be terminated.
7984 GCC can generate code that can assist operating system trap handlers
7985 in determining the exact location that caused a floating point trap.
7986 Depending on the requirements of an application, different levels of
7987 precisions can be selected:
7991 Program precision. This option is the default and means a trap handler
7992 can only identify which program caused a floating point exception.
7995 Function precision. The trap handler can determine the function that
7996 caused a floating point exception.
7999 Instruction precision. The trap handler can determine the exact
8000 instruction that caused a floating point exception.
8003 Other Alpha compilers provide the equivalent options called
8004 @option{-scope_safe} and @option{-resumption_safe}.
8006 @item -mieee-conformant
8007 @opindex mieee-conformant
8008 This option marks the generated code as IEEE conformant. You must not
8009 use this option unless you also specify @option{-mtrap-precision=i} and either
8010 @option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
8011 is to emit the line @samp{.eflag 48} in the function prologue of the
8012 generated assembly file. Under DEC Unix, this has the effect that
8013 IEEE-conformant math library routines will be linked in.
8015 @item -mbuild-constants
8016 @opindex mbuild-constants
8017 Normally GCC examines a 32- or 64-bit integer constant to
8018 see if it can construct it from smaller constants in two or three
8019 instructions. If it cannot, it will output the constant as a literal and
8020 generate code to load it from the data segment at runtime.
8022 Use this option to require GCC to construct @emph{all} integer constants
8023 using code, even if it takes more instructions (the maximum is six).
8025 You would typically use this option to build a shared library dynamic
8026 loader. Itself a shared library, it must relocate itself in memory
8027 before it can find the variables and constants in its own data segment.
8033 Select whether to generate code to be assembled by the vendor-supplied
8034 assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
8052 Indicate whether GCC should generate code to use the optional BWX,
8053 CIX, FIX and MAX instruction sets. The default is to use the instruction
8054 sets supported by the CPU type specified via @option{-mcpu=} option or that
8055 of the CPU on which GCC was built if none was specified.
8060 @opindex mfloat-ieee
8061 Generate code that uses (does not use) VAX F and G floating point
8062 arithmetic instead of IEEE single and double precision.
8064 @item -mexplicit-relocs
8065 @itemx -mno-explicit-relocs
8066 @opindex mexplicit-relocs
8067 @opindex mno-explicit-relocs
8068 Older Alpha assemblers provided no way to generate symbol relocations
8069 except via assembler macros. Use of these macros does not allow
8070 optimial instruction scheduling. GNU binutils as of version 2.12
8071 supports a new syntax that allows the compiler to explicitly mark
8072 which relocations should apply to which instructions. This option
8073 is mostly useful for debugging, as GCC detects the capabilities of
8074 the assembler when it is built and sets the default accordingly.
8078 @opindex msmall-data
8079 @opindex mlarge-data
8080 When @option{-mexplicit-relocs} is in effect, static data is
8081 accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
8082 is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
8083 (the @code{.sdata} and @code{.sbss} sections) and are accessed via
8084 16-bit relocations off of the @code{$gp} register. This limits the
8085 size of the small data area to 64KB, but allows the variables to be
8086 directly accessed via a single instruction.
8088 The default is @option{-mlarge-data}. With this option the data area
8089 is limited to just below 2GB. Programs that require more than 2GB of
8090 data must use @code{malloc} or @code{mmap} to allocate the data in the
8091 heap instead of in the program's data segment.
8093 When generating code for shared libraries, @option{-fpic} implies
8094 @option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
8096 @item -mcpu=@var{cpu_type}
8098 Set the instruction set and instruction scheduling parameters for
8099 machine type @var{cpu_type}. You can specify either the @samp{EV}
8100 style name or the corresponding chip number. GCC supports scheduling
8101 parameters for the EV4, EV5 and EV6 family of processors and will
8102 choose the default values for the instruction set from the processor
8103 you specify. If you do not specify a processor type, GCC will default
8104 to the processor on which the compiler was built.
8106 Supported values for @var{cpu_type} are
8112 Schedules as an EV4 and has no instruction set extensions.
8116 Schedules as an EV5 and has no instruction set extensions.
8120 Schedules as an EV5 and supports the BWX extension.
8125 Schedules as an EV5 and supports the BWX and MAX extensions.
8129 Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
8133 Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
8136 @item -mtune=@var{cpu_type}
8138 Set only the instruction scheduling parameters for machine type
8139 @var{cpu_type}. The instruction set is not changed.
8141 @item -mmemory-latency=@var{time}
8142 @opindex mmemory-latency
8143 Sets the latency the scheduler should assume for typical memory
8144 references as seen by the application. This number is highly
8145 dependent on the memory access patterns used by the application
8146 and the size of the external cache on the machine.
8148 Valid options for @var{time} are
8152 A decimal number representing clock cycles.
8158 The compiler contains estimates of the number of clock cycles for
8159 ``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
8160 (also called Dcache, Scache, and Bcache), as well as to main memory.
8161 Note that L3 is only valid for EV5.
8166 @node DEC Alpha/VMS Options
8167 @subsection DEC Alpha/VMS Options
8169 These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
8172 @item -mvms-return-codes
8173 @opindex mvms-return-codes
8174 Return VMS condition codes from main. The default is to return POSIX
8175 style condition (e.g.@ error) codes.
8178 @node Clipper Options
8179 @subsection Clipper Options
8181 These @samp{-m} options are defined for the Clipper implementations:
8186 Produce code for a C300 Clipper processor. This is the default.
8190 Produce code for a C400 Clipper processor, i.e.@: use floating point
8194 @node H8/300 Options
8195 @subsection H8/300 Options
8197 These @samp{-m} options are defined for the H8/300 implementations:
8202 Shorten some address references at link time, when possible; uses the
8203 linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
8204 ld.info, Using ld}, for a fuller description.
8208 Generate code for the H8/300H@.
8212 Generate code for the H8/S@.
8216 Generate code for the H8/S2600. This switch must be used with @option{-ms}.
8220 Make @code{int} data 32 bits by default.
8224 On the H8/300H and H8/S, use the same alignment rules as for the H8/300.
8225 The default for the H8/300H and H8/S is to align longs and floats on 4
8227 @option{-malign-300} causes them to be aligned on 2 byte boundaries.
8228 This option has no effect on the H8/300.
8232 @subsection SH Options
8234 These @samp{-m} options are defined for the SH implementations:
8239 Generate code for the SH1.
8243 Generate code for the SH2.
8247 Generate code for the SH3.
8251 Generate code for the SH3e.
8255 Generate code for the SH4 without a floating-point unit.
8257 @item -m4-single-only
8258 @opindex m4-single-only
8259 Generate code for the SH4 with a floating-point unit that only
8260 supports single-precision arithmetic.
8264 Generate code for the SH4 assuming the floating-point unit is in
8265 single-precision mode by default.
8269 Generate code for the SH4.
8273 Compile code for the processor in big endian mode.
8277 Compile code for the processor in little endian mode.
8281 Align doubles at 64-bit boundaries. Note that this changes the calling
8282 conventions, and thus some functions from the standard C library will
8283 not work unless you recompile it first with @option{-mdalign}.
8287 Shorten some address references at link time, when possible; uses the
8288 linker option @option{-relax}.
8292 Use 32-bit offsets in @code{switch} tables. The default is to use
8297 Enable the use of the instruction @code{fmovd}.
8301 Comply with the calling conventions defined by Hitachi.
8305 Mark the @code{MAC} register as call-clobbered, even if
8306 @option{-mhitachi} is given.
8310 Increase IEEE-compliance of floating-point code.
8314 Dump instruction size and location in the assembly code.
8318 This option is deprecated. It pads structures to multiple of 4 bytes,
8319 which is incompatible with the SH ABI@.
8323 Optimize for space instead of speed. Implied by @option{-Os}.
8327 When generating position-independent code, emit function calls using
8328 the Global Offset Table instead of the Procedure Linkage Table.
8332 Generate a library function call to invalidate instruction cache
8333 entries, after fixing up a trampoline. This library function call
8334 doesn't assume it can write to the whole memory address space. This
8335 is the default when the target is @code{sh-*-linux*}.
8338 @node System V Options
8339 @subsection Options for System V
8341 These additional options are available on System V Release 4 for
8342 compatibility with other compilers on those systems:
8347 Create a shared object.
8348 It is recommended that @option{-symbolic} or @option{-shared} be used instead.
8352 Identify the versions of each tool used by the compiler, in a
8353 @code{.ident} assembler directive in the output.
8357 Refrain from adding @code{.ident} directives to the output file (this is
8360 @item -YP,@var{dirs}
8362 Search the directories @var{dirs}, and no others, for libraries
8363 specified with @option{-l}.
8367 Look in the directory @var{dir} to find the M4 preprocessor.
8368 The assembler uses this option.
8369 @c This is supposed to go with a -Yd for predefined M4 macro files, but
8370 @c the generic assembler that comes with Solaris takes just -Ym.
8373 @node TMS320C3x/C4x Options
8374 @subsection TMS320C3x/C4x Options
8375 @cindex TMS320C3x/C4x Options
8377 These @samp{-m} options are defined for TMS320C3x/C4x implementations:
8381 @item -mcpu=@var{cpu_type}
8383 Set the instruction set, register set, and instruction scheduling
8384 parameters for machine type @var{cpu_type}. Supported values for
8385 @var{cpu_type} are @samp{c30}, @samp{c31}, @samp{c32}, @samp{c40}, and
8386 @samp{c44}. The default is @samp{c40} to generate code for the
8391 @itemx -msmall-memory
8393 @opindex mbig-memory
8395 @opindex msmall-memory
8397 Generates code for the big or small memory model. The small memory
8398 model assumed that all data fits into one 64K word page. At run-time
8399 the data page (DP) register must be set to point to the 64K page
8400 containing the .bss and .data program sections. The big memory model is
8401 the default and requires reloading of the DP register for every direct
8408 Allow (disallow) allocation of general integer operands into the block
8415 Enable (disable) generation of code using decrement and branch,
8416 DBcond(D), instructions. This is enabled by default for the C4x. To be
8417 on the safe side, this is disabled for the C3x, since the maximum
8418 iteration count on the C3x is @math{2^{23} + 1} (but who iterates loops more than
8419 @math{2^{23}} times on the C3x?). Note that GCC will try to reverse a loop so
8420 that it can utilise the decrement and branch instruction, but will give
8421 up if there is more than one memory reference in the loop. Thus a loop
8422 where the loop counter is decremented can generate slightly more
8423 efficient code, in cases where the RPTB instruction cannot be utilised.
8425 @item -mdp-isr-reload
8427 @opindex mdp-isr-reload
8429 Force the DP register to be saved on entry to an interrupt service
8430 routine (ISR), reloaded to point to the data section, and restored on
8431 exit from the ISR@. This should not be required unless someone has
8432 violated the small memory model by modifying the DP register, say within
8439 For the C3x use the 24-bit MPYI instruction for integer multiplies
8440 instead of a library call to guarantee 32-bit results. Note that if one
8441 of the operands is a constant, then the multiplication will be performed
8442 using shifts and adds. If the @option{-mmpyi} option is not specified for the C3x,
8443 then squaring operations are performed inline instead of a library call.
8446 @itemx -mno-fast-fix
8448 @opindex mno-fast-fix
8449 The C3x/C4x FIX instruction to convert a floating point value to an
8450 integer value chooses the nearest integer less than or equal to the
8451 floating point value rather than to the nearest integer. Thus if the
8452 floating point number is negative, the result will be incorrectly
8453 truncated an additional code is necessary to detect and correct this
8454 case. This option can be used to disable generation of the additional
8455 code required to correct the result.
8461 Enable (disable) generation of repeat block sequences using the RPTB
8462 instruction for zero overhead looping. The RPTB construct is only used
8463 for innermost loops that do not call functions or jump across the loop
8464 boundaries. There is no advantage having nested RPTB loops due to the
8465 overhead required to save and restore the RC, RS, and RE registers.
8466 This is enabled by default with @option{-O2}.
8468 @item -mrpts=@var{count}
8472 Enable (disable) the use of the single instruction repeat instruction
8473 RPTS@. If a repeat block contains a single instruction, and the loop
8474 count can be guaranteed to be less than the value @var{count}, GCC will
8475 emit a RPTS instruction instead of a RPTB@. If no value is specified,
8476 then a RPTS will be emitted even if the loop count cannot be determined
8477 at compile time. Note that the repeated instruction following RPTS does
8478 not have to be reloaded from memory each iteration, thus freeing up the
8479 CPU buses for operands. However, since interrupts are blocked by this
8480 instruction, it is disabled by default.
8482 @item -mloop-unsigned
8483 @itemx -mno-loop-unsigned
8484 @opindex mloop-unsigned
8485 @opindex mno-loop-unsigned
8486 The maximum iteration count when using RPTS and RPTB (and DB on the C40)
8487 is @math{2^{31} + 1} since these instructions test if the iteration count is
8488 negative to terminate the loop. If the iteration count is unsigned
8489 there is a possibility than the @math{2^{31} + 1} maximum iteration count may be
8490 exceeded. This switch allows an unsigned iteration count.
8494 Try to emit an assembler syntax that the TI assembler (asm30) is happy
8495 with. This also enforces compatibility with the API employed by the TI
8496 C3x C compiler. For example, long doubles are passed as structures
8497 rather than in floating point registers.
8503 Generate code that uses registers (stack) for passing arguments to functions.
8504 By default, arguments are passed in registers where possible rather
8505 than by pushing arguments on to the stack.
8507 @item -mparallel-insns
8508 @itemx -mno-parallel-insns
8509 @opindex mparallel-insns
8510 @opindex mno-parallel-insns
8511 Allow the generation of parallel instructions. This is enabled by
8512 default with @option{-O2}.
8514 @item -mparallel-mpy
8515 @itemx -mno-parallel-mpy
8516 @opindex mparallel-mpy
8517 @opindex mno-parallel-mpy
8518 Allow the generation of MPY||ADD and MPY||SUB parallel instructions,
8519 provided @option{-mparallel-insns} is also specified. These instructions have
8520 tight register constraints which can pessimize the code generation
8526 @subsection V850 Options
8527 @cindex V850 Options
8529 These @samp{-m} options are defined for V850 implementations:
8533 @itemx -mno-long-calls
8534 @opindex mlong-calls
8535 @opindex mno-long-calls
8536 Treat all calls as being far away (near). If calls are assumed to be
8537 far away, the compiler will always load the functions address up into a
8538 register, and call indirect through the pointer.
8544 Do not optimize (do optimize) basic blocks that use the same index
8545 pointer 4 or more times to copy pointer into the @code{ep} register, and
8546 use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
8547 option is on by default if you optimize.
8549 @item -mno-prolog-function
8550 @itemx -mprolog-function
8551 @opindex mno-prolog-function
8552 @opindex mprolog-function
8553 Do not use (do use) external functions to save and restore registers at
8554 the prolog and epilog of a function. The external functions are slower,
8555 but use less code space if more than one function saves the same number
8556 of registers. The @option{-mprolog-function} option is on by default if
8561 Try to make the code as small as possible. At present, this just turns
8562 on the @option{-mep} and @option{-mprolog-function} options.
8566 Put static or global variables whose size is @var{n} bytes or less into
8567 the tiny data area that register @code{ep} points to. The tiny data
8568 area can hold up to 256 bytes in total (128 bytes for byte references).
8572 Put static or global variables whose size is @var{n} bytes or less into
8573 the small data area that register @code{gp} points to. The small data
8574 area can hold up to 64 kilobytes.
8578 Put static or global variables whose size is @var{n} bytes or less into
8579 the first 32 kilobytes of memory.
8583 Specify that the target processor is the V850.
8586 @opindex mbig-switch
8587 Generate code suitable for big switch tables. Use this option only if
8588 the assembler/linker complain about out of range branches within a switch
8593 @subsection ARC Options
8596 These options are defined for ARC implementations:
8601 Compile code for little endian mode. This is the default.
8605 Compile code for big endian mode.
8608 @opindex mmangle-cpu
8609 Prepend the name of the cpu to all public symbol names.
8610 In multiple-processor systems, there are many ARC variants with different
8611 instruction and register set characteristics. This flag prevents code
8612 compiled for one cpu to be linked with code compiled for another.
8613 No facility exists for handling variants that are ``almost identical''.
8614 This is an all or nothing option.
8616 @item -mcpu=@var{cpu}
8618 Compile code for ARC variant @var{cpu}.
8619 Which variants are supported depend on the configuration.
8620 All variants support @option{-mcpu=base}, this is the default.
8622 @item -mtext=@var{text-section}
8623 @itemx -mdata=@var{data-section}
8624 @itemx -mrodata=@var{readonly-data-section}
8628 Put functions, data, and readonly data in @var{text-section},
8629 @var{data-section}, and @var{readonly-data-section} respectively
8630 by default. This can be overridden with the @code{section} attribute.
8631 @xref{Variable Attributes}.
8636 @subsection NS32K Options
8637 @cindex NS32K options
8639 These are the @samp{-m} options defined for the 32000 series. The default
8640 values for these options depends on which style of 32000 was selected when
8641 the compiler was configured; the defaults for the most common choices are
8649 Generate output for a 32032. This is the default
8650 when the compiler is configured for 32032 and 32016 based systems.
8656 Generate output for a 32332. This is the default
8657 when the compiler is configured for 32332-based systems.
8663 Generate output for a 32532. This is the default
8664 when the compiler is configured for 32532-based systems.
8668 Generate output containing 32081 instructions for floating point.
8669 This is the default for all systems.
8673 Generate output containing 32381 instructions for floating point. This
8674 also implies @option{-m32081}. The 32381 is only compatible with the 32332
8675 and 32532 cpus. This is the default for the pc532-netbsd configuration.
8679 Try and generate multiply-add floating point instructions @code{polyF}
8680 and @code{dotF}. This option is only available if the @option{-m32381}
8681 option is in effect. Using these instructions requires changes to
8682 register allocation which generally has a negative impact on
8683 performance. This option should only be enabled when compiling code
8684 particularly likely to make heavy use of multiply-add instructions.
8687 @opindex mnomulti-add
8688 Do not try and generate multiply-add floating point instructions
8689 @code{polyF} and @code{dotF}. This is the default on all platforms.
8692 @opindex msoft-float
8693 Generate output containing library calls for floating point.
8694 @strong{Warning:} the requisite libraries may not be available.
8697 @opindex mnobitfield
8698 Do not use the bit-field instructions. On some machines it is faster to
8699 use shifting and masking operations. This is the default for the pc532.
8703 Do use the bit-field instructions. This is the default for all platforms
8708 Use a different function-calling convention, in which functions
8709 that take a fixed number of arguments return pop their
8710 arguments on return with the @code{ret} instruction.
8712 This calling convention is incompatible with the one normally
8713 used on Unix, so you cannot use it if you need to call libraries
8714 compiled with the Unix compiler.
8716 Also, you must provide function prototypes for all functions that
8717 take variable numbers of arguments (including @code{printf});
8718 otherwise incorrect code will be generated for calls to those
8721 In addition, seriously incorrect code will result if you call a
8722 function with too many arguments. (Normally, extra arguments are
8723 harmlessly ignored.)
8725 This option takes its name from the 680x0 @code{rtd} instruction.
8730 Use a different function-calling convention where the first two arguments
8731 are passed in registers.
8733 This calling convention is incompatible with the one normally
8734 used on Unix, so you cannot use it if you need to call libraries
8735 compiled with the Unix compiler.
8738 @opindex mnoregparam
8739 Do not pass any arguments in registers. This is the default for all
8744 It is OK to use the sb as an index register which is always loaded with
8745 zero. This is the default for the pc532-netbsd target.
8749 The sb register is not available for use or has not been initialized to
8750 zero by the run time system. This is the default for all targets except
8751 the pc532-netbsd. It is also implied whenever @option{-mhimem} or
8752 @option{-fpic} is set.
8756 Many ns32000 series addressing modes use displacements of up to 512MB@.
8757 If an address is above 512MB then displacements from zero can not be used.
8758 This option causes code to be generated which can be loaded above 512MB@.
8759 This may be useful for operating systems or ROM code.
8763 Assume code will be loaded in the first 512MB of virtual address space.
8764 This is the default for all platforms.
8770 @subsection AVR Options
8773 These options are defined for AVR implementations:
8776 @item -mmcu=@var{mcu}
8778 Specify ATMEL AVR instruction set or MCU type.
8780 Instruction set avr1 is for the minimal AVR core, not supported by the C
8781 compiler, only for assembler programs (MCU types: at90s1200, attiny10,
8782 attiny11, attiny12, attiny15, attiny28).
8784 Instruction set avr2 (default) is for the classic AVR core with up to
8785 8K program memory space (MCU types: at90s2313, at90s2323, attiny22,
8786 at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
8787 at90c8534, at90s8535).
8789 Instruction set avr3 is for the classic AVR core with up to 128K program
8790 memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
8792 Instruction set avr4 is for the enhanced AVR core with up to 8K program
8793 memory space (MCU types: atmega8, atmega83, atmega85).
8795 Instruction set avr5 is for the enhanced AVR core with up to 128K program
8796 memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
8797 atmega64, atmega128, at43usb355, at94k).
8801 Output instruction sizes to the asm file.
8803 @item -minit-stack=@var{N}
8804 @opindex minit-stack
8805 Specify the initial stack address, which may be a symbol or numeric value,
8806 @samp{__stack} is the default.
8808 @item -mno-interrupts
8809 @opindex mno-interrupts
8810 Generated code is not compatible with hardware interrupts.
8811 Code size will be smaller.
8813 @item -mcall-prologues
8814 @opindex mcall-prologues
8815 Functions prologues/epilogues expanded as call to appropriate
8816 subroutines. Code size will be smaller.
8818 @item -mno-tablejump
8819 @opindex mno-tablejump
8820 Do not generate tablejump insns which sometimes increase code size.
8823 @opindex mtiny-stack
8824 Change only the low 8 bits of the stack pointer.
8828 @subsection MCore Options
8829 @cindex MCore options
8831 These are the @samp{-m} options defined for the Motorola M*Core
8841 @opindex mno-hardlit
8842 Inline constants into the code stream if it can be done in two
8843 instructions or less.
8851 Use the divide instruction. (Enabled by default).
8853 @item -mrelax-immediate
8854 @itemx -mrelax-immediate
8855 @itemx -mno-relax-immediate
8856 @opindex mrelax-immediate
8857 @opindex mrelax-immediate
8858 @opindex mno-relax-immediate
8859 Allow arbitrary sized immediates in bit operations.
8861 @item -mwide-bitfields
8862 @itemx -mwide-bitfields
8863 @itemx -mno-wide-bitfields
8864 @opindex mwide-bitfields
8865 @opindex mwide-bitfields
8866 @opindex mno-wide-bitfields
8867 Always treat bit-fields as int-sized.
8869 @item -m4byte-functions
8870 @itemx -m4byte-functions
8871 @itemx -mno-4byte-functions
8872 @opindex m4byte-functions
8873 @opindex m4byte-functions
8874 @opindex mno-4byte-functions
8875 Force all functions to be aligned to a four byte boundary.
8877 @item -mcallgraph-data
8878 @itemx -mcallgraph-data
8879 @itemx -mno-callgraph-data
8880 @opindex mcallgraph-data
8881 @opindex mcallgraph-data
8882 @opindex mno-callgraph-data
8883 Emit callgraph information.
8887 @itemx -mno-slow-bytes
8888 @opindex mslow-bytes
8889 @opindex mslow-bytes
8890 @opindex mno-slow-bytes
8891 Prefer word access when reading byte quantities.
8893 @item -mlittle-endian
8894 @itemx -mlittle-endian
8896 @opindex mlittle-endian
8897 @opindex mlittle-endian
8898 @opindex mbig-endian
8899 Generate code for a little endian target.
8907 Generate code for the 210 processor.
8911 @subsection IA-64 Options
8912 @cindex IA-64 Options
8914 These are the @samp{-m} options defined for the Intel IA-64 architecture.
8918 @opindex mbig-endian
8919 Generate code for a big endian target. This is the default for HPUX@.
8921 @item -mlittle-endian
8922 @opindex mlittle-endian
8923 Generate code for a little endian target. This is the default for AIX5
8930 Generate (or don't) code for the GNU assembler. This is the default.
8931 @c Also, this is the default if the configure option @option{--with-gnu-as}
8938 Generate (or don't) code for the GNU linker. This is the default.
8939 @c Also, this is the default if the configure option @option{--with-gnu-ld}
8944 Generate code that does not use a global pointer register. The result
8945 is not position independent code, and violates the IA-64 ABI@.
8947 @item -mvolatile-asm-stop
8948 @itemx -mno-volatile-asm-stop
8949 @opindex mvolatile-asm-stop
8950 @opindex mno-volatile-asm-stop
8951 Generate (or don't) a stop bit immediately before and after volatile asm
8956 Generate code that works around Itanium B step errata.
8958 @item -mregister-names
8959 @itemx -mno-register-names
8960 @opindex mregister-names
8961 @opindex mno-register-names
8962 Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
8963 the stacked registers. This may make assembler output more readable.
8969 Disable (or enable) optimizations that use the small data section. This may
8970 be useful for working around optimizer bugs.
8973 @opindex mconstant-gp
8974 Generate code that uses a single constant global pointer value. This is
8975 useful when compiling kernel code.
8979 Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
8980 This is useful when compiling firmware code.
8982 @item -minline-divide-min-latency
8983 @opindex minline-divide-min-latency
8984 Generate code for inline divides using the minimum latency algorithm.
8986 @item -minline-divide-max-throughput
8987 @opindex minline-divide-max-throughput
8988 Generate code for inline divides using the maximum throughput algorithm.
8990 @item -mno-dwarf2-asm
8992 @opindex mno-dwarf2-asm
8993 @opindex mdwarf2-asm
8994 Don't (or do) generate assembler code for the DWARF2 line number debugging
8995 info. This may be useful when not using the GNU assembler.
8997 @item -mfixed-range=@var{register-range}
8998 @opindex mfixed-range
8999 Generate code treating the given register range as fixed registers.
9000 A fixed register is one that the register allocator can not use. This is
9001 useful when compiling kernel code. A register range is specified as
9002 two registers separated by a dash. Multiple register ranges can be
9003 specified separated by a comma.
9007 @subsection D30V Options
9008 @cindex D30V Options
9010 These @samp{-m} options are defined for D30V implementations:
9015 Link the @samp{.text}, @samp{.data}, @samp{.bss}, @samp{.strings},
9016 @samp{.rodata}, @samp{.rodata1}, @samp{.data1} sections into external
9017 memory, which starts at location @code{0x80000000}.
9021 Same as the @option{-mextmem} switch.
9025 Link the @samp{.text} section into onchip text memory, which starts at
9026 location @code{0x0}. Also link @samp{.data}, @samp{.bss},
9027 @samp{.strings}, @samp{.rodata}, @samp{.rodata1}, @samp{.data1} sections
9028 into onchip data memory, which starts at location @code{0x20000000}.
9030 @item -mno-asm-optimize
9031 @itemx -masm-optimize
9032 @opindex mno-asm-optimize
9033 @opindex masm-optimize
9034 Disable (enable) passing @option{-O} to the assembler when optimizing.
9035 The assembler uses the @option{-O} option to automatically parallelize
9036 adjacent short instructions where possible.
9038 @item -mbranch-cost=@var{n}
9039 @opindex mbranch-cost
9040 Increase the internal costs of branches to @var{n}. Higher costs means
9041 that the compiler will issue more instructions to avoid doing a branch.
9044 @item -mcond-exec=@var{n}
9046 Specify the maximum number of conditionally executed instructions that
9047 replace a branch. The default is 4.
9050 @node S/390 and zSeries Options
9051 @subsection S/390 and zSeries Options
9052 @cindex S/390 and zSeries Options
9054 These are the @samp{-m} options defined for the S/390 and zSeries architecture.
9059 @opindex mhard-float
9060 @opindex msoft-float
9061 Use (do not use) the hardware floating-point instructions and registers
9062 for floating-point operations. When @option{-msoft-float} is specified,
9063 functions in @file{libgcc.a} will be used to perform floating-point
9064 operations. When @option{-mhard-float} is specified, the compiler
9065 generates IEEE floating-point instructions. This is the default.
9068 @itemx -mno-backchain
9070 @opindex mno-backchain
9071 Generate (or do not generate) code which maintains an explicit
9072 backchain within the stack frame that points to the caller's frame.
9073 This is currently needed to allow debugging. The default is to
9074 generate the backchain.
9077 @itemx -mno-small-exec
9078 @opindex msmall-exec
9079 @opindex mno-small-exec
9080 Generate (or do not generate) code using the @code{bras} instruction
9081 to do subroutine calls.
9082 This only works reliably if the total executable size does not
9083 exceed 64k. The default is to use the @code{basr} instruction instead,
9084 which does not have this limitation.
9090 When @option{-m31} is specified, generate code compliant to the
9091 Linux for S/390 ABI@. When @option{-m64} is specified, generate
9092 code compliant to the Linux for zSeries ABI@. This allows GCC in
9093 particular to generate 64-bit instructions. For the @samp{s390}
9094 targets, the default is @option{-m31}, while the @samp{s390x}
9095 targets default to @option{-m64}.
9101 Generate (or do not generate) code using the @code{mvcle} instruction
9102 to perform block moves. When @option{-mno-mvcle} is specifed,
9103 use a @code{mvc} loop instead. This is the default.
9109 Print (or do not print) additional debug information when compiling.
9110 The default is to not print debug information.
9115 @subsection CRIS Options
9116 @cindex CRIS Options
9118 These options are defined specifically for the CRIS ports.
9121 @item -march=@var{architecture-type}
9122 @itemx -mcpu=@var{architecture-type}
9125 Generate code for the specified architecture. The choices for
9126 @var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
9127 respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX.
9128 Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
9131 @item -mtune=@var{architecture-type}
9133 Tune to @var{architecture-type} everything applicable about the generated
9134 code, except for the ABI and the set of available instructions. The
9135 choices for @var{architecture-type} are the same as for
9136 @option{-march=@var{architecture-type}}.
9138 @item -mmax-stack-frame=@var{n}
9139 @opindex mmax-stack-frame
9140 Warn when the stack frame of a function exceeds @var{n} bytes.
9142 @item -melinux-stacksize=@var{n}
9143 @opindex melinux-stacksize
9144 Only available with the @samp{cris-axis-aout} target. Arranges for
9145 indications in the program to the kernel loader that the stack of the
9146 program should be set to @var{n} bytes.
9152 The options @option{-metrax4} and @option{-metrax100} are synonyms for
9153 @option{-march=v3} and @option{-march=v8} respectively.
9157 Enable CRIS-specific verbose debug-related information in the assembly
9158 code. This option also has the effect to turn off the @samp{#NO_APP}
9159 formatted-code indicator to the assembler at the beginning of the
9164 Do not use condition-code results from previous instruction; always emit
9165 compare and test instructions before use of condition codes.
9167 @item -mno-side-effects
9168 @opindex mno-side-effects
9169 Do not emit instructions with side-effects in addressing modes other than
9173 @itemx -mno-stack-align
9175 @itemx -mno-data-align
9176 @itemx -mconst-align
9177 @itemx -mno-const-align
9178 @opindex mstack-align
9179 @opindex mno-stack-align
9180 @opindex mdata-align
9181 @opindex mno-data-align
9182 @opindex mconst-align
9183 @opindex mno-const-align
9184 These options (no-options) arranges (eliminate arrangements) for the
9185 stack-frame, individual data and constants to be aligned for the maximum
9186 single data access size for the chosen CPU model. The default is to
9187 arrange for 32-bit alignment. ABI details such as structure layout are
9188 not affected by these options.
9196 Similar to the stack- data- and const-align options above, these options
9197 arrange for stack-frame, writable data and constants to all be 32-bit,
9198 16-bit or 8-bit aligned. The default is 32-bit alignment.
9200 @item -mno-prologue-epilogue
9201 @itemx -mprologue-epilogue
9202 @opindex mno-prologue-epilogue
9203 @opindex mprologue-epilogue
9204 With @option{-mno-prologue-epilogue}, the normal function prologue and
9205 epilogue that sets up the stack-frame are omitted and no return
9206 instructions or return sequences are generated in the code. Use this
9207 option only together with visual inspection of the compiled code: no
9208 warnings or errors are generated when call-saved registers must be saved,
9209 or storage for local variable needs to be allocated.
9215 With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
9216 instruction sequences that load addresses for functions from the PLT part
9217 of the GOT rather than (traditional on other architectures) calls to the
9218 PLT. The default is @option{-mgotplt}.
9222 Legacy no-op option only recognized with the cris-axis-aout target.
9226 Legacy no-op option only recognized with the cris-axis-elf and
9227 cris-axis-linux-gnu targets.
9231 Only recognized with the cris-axis-aout target, where it selects a
9232 GNU/linux-like multilib, include files and instruction set for
9237 Legacy no-op option only recognized with the cris-axis-linux-gnu target.
9241 This option, recognized for the cris-axis-aout and cris-axis-elf arranges
9242 to link with input-output functions from a simulator library. Code,
9243 initialized data and zero-initialized data are allocated consecutively.
9247 Like @option{-sim}, but pass linker options to locate initialized data at
9248 0x40000000 and zero-initialized data at 0x80000000.
9252 @subsection MMIX Options
9253 @cindex MMIX Options
9255 These options are defined for the MMIX:
9259 @itemx -mno-libfuncs
9261 @opindex mno-libfuncs
9262 Specify that intrinsic library functions are being compiled, passing all
9263 values in registers, no matter the size.
9268 @opindex mno-epsilon
9269 Generate floating-point comparison instructions that compare with respect
9270 to the @code{rE} epsilon register.
9272 @item -mabi=mmixware
9274 @opindex mabi-mmixware
9276 Generate code that passes function parameters and return values that (in
9277 the called function) are seen as registers @code{$0} and up, as opposed to
9278 the GNU ABI which uses global registers @code{$231} and up.
9281 @itemx -mno-zero-extend
9282 @opindex mzero-extend
9283 @opindex mno-zero-extend
9284 When reading data from memory in sizes shorter than 64 bits, use (do not
9285 use) zero-extending load instructions by default, rather than
9286 sign-extending ones.
9289 @itemx -mno-knuthdiv
9291 @opindex mno-knuthdiv
9292 Make the result of a division yielding a remainder have the same sign as
9293 the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
9294 remainder follows the sign of the dividend. Both methods are
9295 arithmetically valid, the latter being almost exclusively used.
9297 @item -mtoplevel-symbols
9298 @itemx -mno-toplevel-symbols
9299 @opindex mtoplevel-symbols
9300 @opindex mno-toplevel-symbols
9301 Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
9302 code can be used with the @code{PREFIX} assembly directive.
9306 Generate an executable in the ELF format, rather than the default
9307 @samp{mmo} format used by the @command{mmix} simulator.
9309 @item -mbranch-predict
9310 @itemx -mno-branch-predict
9311 @opindex mbranch-predict
9312 @opindex mno-branch-predict
9313 Use (do not use) the probable-branch instructions, when static branch
9314 prediction indicates a probable branch.
9316 @item -mbase-addresses
9317 @itemx -mno-base-addresses
9318 @opindex mbase-addresses
9319 @opindex mno-base-addresses
9320 Generate (do not generate) code that uses @emph{base addresses}. Using a
9321 base address automatically generates a request (handled by the assembler
9322 and the linker) for a constant to be set up in a global register. The
9323 register is used for one or more base address requests within the range 0
9324 to 255 from the value held in the register. The generally leads to short
9325 and fast code, but the number of different data items that can be
9326 addressed is limited. This means that a program that uses lots of static
9327 data may require @option{-mno-base-addresses}.
9330 @itemx -mno-single-exit
9331 @opindex msingle-exit
9332 @opindex mno-single-exit
9333 Force (do not force) generated code to have a single exit point in each
9337 @node PDP-11 Options
9338 @subsection PDP-11 Options
9339 @cindex PDP-11 Options
9341 These options are defined for the PDP-11:
9346 Use hardware FPP floating point. This is the default. (FIS floating
9347 point on the PDP-11/40 is not supported.)
9350 @opindex msoft-float
9351 Do not use hardware floating point.
9355 Return floating-point results in ac0 (fr0 in Unix assembler syntax).
9359 Return floating-point results in memory. This is the default.
9363 Generate code for a PDP-11/40.
9367 Generate code for a PDP-11/45. This is the default.
9371 Generate code for a PDP-11/10.
9373 @item -mbcopy-builtin
9374 @opindex bcopy-builtin
9375 Use inline @code{movstrhi} patterns for copying memory. This is the
9380 Do not use inline @code{movstrhi} patterns for copying memory.
9386 Use 16-bit @code{int}. This is the default.
9392 Use 32-bit @code{int}.
9397 @opindex mno-float32
9398 Use 64-bit @code{float}. This is the default.
9403 @opindex mno-float64
9404 Use 32-bit @code{float}.
9408 Use @code{abshi2} pattern. This is the default.
9412 Do not use @code{abshi2} pattern.
9414 @item -mbranch-expensive
9415 @opindex mbranch-expensive
9416 Pretend that branches are expensive. This is for experimenting with
9417 code generation only.
9419 @item -mbranch-cheap
9420 @opindex mbranch-cheap
9421 Do not pretend that branches are expensive. This is the default.
9425 Generate code for a system with split I&D.
9429 Generate code for a system without split I&D. This is the default.
9433 Use Unix assembler syntax. This is the default when configured for
9438 Use DEC assembler syntax. This is the default when configured for any
9439 PDP-11 target other than @samp{pdp11-*-bsd}.
9442 @node Xstormy16 Options
9443 @subsection Xstormy16 Options
9444 @cindex Xstormy16 Options
9446 These options are defined for Xstormy16:
9451 Choose startup files and linker script suitable for the simulator.
9454 @node Xtensa Options
9455 @subsection Xtensa Options
9456 @cindex Xtensa Options
9458 The Xtensa architecture is designed to support many different
9459 configurations. The compiler's default options can be set to match a
9460 particular Xtensa configuration by copying a configuration file into the
9461 GCC sources when building GCC@. The options below may be used to
9462 override the default options.
9466 @itemx -mlittle-endian
9467 @opindex mbig-endian
9468 @opindex mlittle-endian
9469 Specify big-endian or little-endian byte ordering for the target Xtensa
9475 @opindex mno-density
9476 Enable or disable use of the optional Xtensa code density instructions.
9482 Enable or disable use of the Xtensa MAC16 option. When enabled, GCC
9483 will generate MAC16 instructions from standard C code, with the
9484 limitation that it will use neither the MR register file nor any
9485 instruction that operates on the MR registers. When this option is
9486 disabled, GCC will translate 16-bit multiply/accumulate operations to a
9487 combination of core instructions and library calls, depending on whether
9488 any other multiplier options are enabled.
9494 Enable or disable use of the 16-bit integer multiplier option. When
9495 enabled, the compiler will generate 16-bit multiply instructions for
9496 multiplications of 16 bits or smaller in standard C code. When this
9497 option is disabled, the compiler will either use 32-bit multiply or
9498 MAC16 instructions if they are available or generate library calls to
9499 perform the multiply operations using shifts and adds.
9505 Enable or disable use of the 32-bit integer multiplier option. When
9506 enabled, the compiler will generate 32-bit multiply instructions for
9507 multiplications of 32 bits or smaller in standard C code. When this
9508 option is disabled, the compiler will generate library calls to perform
9509 the multiply operations using either shifts and adds or 16-bit multiply
9510 instructions if they are available.
9516 Enable or disable use of the optional normalization shift amount
9517 (@code{NSA}) instructions to implement the built-in @code{ffs} function.
9523 Enable or disable use of the optional minimum and maximum value
9530 Enable or disable use of the optional sign extend (@code{SEXT})
9534 @itemx -mno-booleans
9536 @opindex mno-booleans
9537 Enable or disable support for the boolean register file used by Xtensa
9538 coprocessors. This is not typically useful by itself but may be
9539 required for other options that make use of the boolean registers (e.g.,
9540 the floating-point option).
9544 @opindex mhard-float
9545 @opindex msoft-float
9546 Enable or disable use of the floating-point option. When enabled, GCC
9547 generates floating-point instructions for 32-bit @code{float}
9548 operations. When this option is disabled, GCC generates library calls
9549 to emulate 32-bit floating-point operations using integer instructions.
9550 Regardless of this option, 64-bit @code{double} operations are always
9551 emulated with calls to library functions.
9554 @itemx -mno-fused-madd
9555 @opindex mfused-madd
9556 @opindex mno-fused-madd
9557 Enable or disable use of fused multiply/add and multiply/subtract
9558 instructions in the floating-point option. This has no effect if the
9559 floating-point option is not also enabled. Disabling fused multiply/add
9560 and multiply/subtract instructions forces the compiler to use separate
9561 instructions for the multiply and add/subtract operations. This may be
9562 desirable in some cases where strict IEEE 754-compliant results are
9563 required: the fused multiply add/subtract instructions do not round the
9564 intermediate result, thereby producing results with @emph{more} bits of
9565 precision than specified by the IEEE standard. Disabling fused multiply
9566 add/subtract instructions also ensures that the program output is not
9567 sensitive to the compiler's ability to combine multiply and add/subtract
9570 @item -mserialize-volatile
9571 @itemx -mno-serialize-volatile
9572 @opindex mserialize-volatile
9573 @opindex mno-serialize-volatile
9574 When this option is enabled, GCC inserts @code{MEMW} instructions before
9575 @code{volatile} memory references to guarantee sequential consistency.
9576 The default is @option{-mserialize-volatile}. Use
9577 @option{-mno-serialize-volatile} to omit the @code{MEMW} instructions.
9579 @item -mtext-section-literals
9580 @itemx -mno-text-section-literals
9581 @opindex mtext-section-literals
9582 @opindex mno-text-section-literals
9583 Control the treatment of literal pools. The default is
9584 @option{-mno-text-section-literals}, which places literals in a separate
9585 section in the output file. This allows the literal pool to be placed
9586 in a data RAM/ROM, and it also allows the linker to combine literal
9587 pools from separate object files to remove redundant literals and
9588 improve code size. With @option{-mtext-section-literals}, the literals
9589 are interspersed in the text section in order to keep them as close as
9590 possible to their references. This may be necessary for large assembly
9593 @item -mtarget-align
9594 @itemx -mno-target-align
9595 @opindex mtarget-align
9596 @opindex mno-target-align
9597 When this option is enabled, GCC instructs the assembler to
9598 automatically align instructions to reduce branch penalties at the
9599 expense of some code density. The assembler attempts to widen density
9600 instructions to align branch targets and the instructions following call
9601 instructions. If there are not enough preceding safe density
9602 instructions to align a target, no widening will be performed. The
9603 default is @option{-mtarget-align}. These options do not affect the
9604 treatment of auto-aligned instructions like @code{LOOP}, which the
9605 assembler will always align, either by widening density instructions or
9606 by inserting no-op instructions.
9609 @itemx -mno-longcalls
9611 @opindex mno-longcalls
9612 When this option is enabled, GCC instructs the assembler to translate
9613 direct calls to indirect calls unless it can determine that the target
9614 of a direct call is in the range allowed by the call instruction. This
9615 translation typically occurs for calls to functions in other source
9616 files. Specifically, the assembler translates a direct @code{CALL}
9617 instruction into an @code{L32R} followed by a @code{CALLX} instruction.
9618 The default is @option{-mno-longcalls}. This option should be used in
9619 programs where the call target can potentially be out of range. This
9620 option is implemented in the assembler, not the compiler, so the
9621 assembly code generated by GCC will still show direct call
9622 instructions---look at the disassembled object code to see the actual
9623 instructions. Note that the assembler will use an indirect call for
9624 every cross-file call, not just those that really will be out of range.
9627 @node Code Gen Options
9628 @section Options for Code Generation Conventions
9629 @cindex code generation conventions
9630 @cindex options, code generation
9631 @cindex run-time options
9633 These machine-independent options control the interface conventions
9634 used in code generation.
9636 Most of them have both positive and negative forms; the negative form
9637 of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
9638 one of the forms is listed---the one which is not the default. You
9639 can figure out the other form by either removing @samp{no-} or adding
9644 @opindex fexceptions
9645 Enable exception handling. Generates extra code needed to propagate
9646 exceptions. For some targets, this implies GCC will generate frame
9647 unwind information for all functions, which can produce significant data
9648 size overhead, although it does not affect execution. If you do not
9649 specify this option, GCC will enable it by default for languages like
9650 C++ which normally require exception handling, and disable it for
9651 languages like C that do not normally require it. However, you may need
9652 to enable this option when compiling C code that needs to interoperate
9653 properly with exception handlers written in C++. You may also wish to
9654 disable this option if you are compiling older C++ programs that don't
9655 use exception handling.
9657 @item -fnon-call-exceptions
9658 @opindex fnon-call-exceptions
9659 Generate code that allows trapping instructions to throw exceptions.
9660 Note that this requires platform-specific runtime support that does
9661 not exist everywhere. Moreover, it only allows @emph{trapping}
9662 instructions to throw exceptions, i.e.@: memory references or floating
9663 point instructions. It does not allow exceptions to be thrown from
9664 arbitrary signal handlers such as @code{SIGALRM}.
9666 @item -funwind-tables
9667 @opindex funwind-tables
9668 Similar to @option{-fexceptions}, except that it will just generate any needed
9669 static data, but will not affect the generated code in any other way.
9670 You will normally not enable this option; instead, a language processor
9671 that needs this handling would enable it on your behalf.
9673 @item -fasynchronous-unwind-tables
9674 @opindex funwind-tables
9675 Generate unwind table in dwarf2 format, if supported by target machine. The
9676 table is exact at each instruction boundary, so it can be used for stack
9677 unwinding from asynchronous events (such as debugger or garbage collector).
9679 @item -fpcc-struct-return
9680 @opindex fpcc-struct-return
9681 Return ``short'' @code{struct} and @code{union} values in memory like
9682 longer ones, rather than in registers. This convention is less
9683 efficient, but it has the advantage of allowing intercallability between
9684 GCC-compiled files and files compiled with other compilers.
9686 The precise convention for returning structures in memory depends
9687 on the target configuration macros.
9689 Short structures and unions are those whose size and alignment match
9690 that of some integer type.
9692 @item -freg-struct-return
9693 @opindex freg-struct-return
9694 Return @code{struct} and @code{union} values in registers when possible.
9695 This is more efficient for small structures than
9696 @option{-fpcc-struct-return}.
9698 If you specify neither @option{-fpcc-struct-return} nor
9699 @option{-freg-struct-return}, GCC defaults to whichever convention is
9700 standard for the target. If there is no standard convention, GCC
9701 defaults to @option{-fpcc-struct-return}, except on targets where GCC is
9702 the principal compiler. In those cases, we can choose the standard, and
9703 we chose the more efficient register return alternative.
9706 @opindex fshort-enums
9707 Allocate to an @code{enum} type only as many bytes as it needs for the
9708 declared range of possible values. Specifically, the @code{enum} type
9709 will be equivalent to the smallest integer type which has enough room.
9711 @item -fshort-double
9712 @opindex fshort-double
9713 Use the same size for @code{double} as for @code{float}.
9716 @opindex fshared-data
9717 Requests that the data and non-@code{const} variables of this
9718 compilation be shared data rather than private data. The distinction
9719 makes sense only on certain operating systems, where shared data is
9720 shared between processes running the same program, while private data
9721 exists in one copy per process.
9725 In C, allocate even uninitialized global variables in the data section of the
9726 object file, rather than generating them as common blocks. This has the
9727 effect that if the same variable is declared (without @code{extern}) in
9728 two different compilations, you will get an error when you link them.
9729 The only reason this might be useful is if you wish to verify that the
9730 program will work on other systems which always work this way.
9734 Ignore the @samp{#ident} directive.
9736 @item -fno-gnu-linker
9737 @opindex fno-gnu-linker
9738 Do not output global initializations (such as C++ constructors and
9739 destructors) in the form used by the GNU linker (on systems where the GNU
9740 linker is the standard method of handling them). Use this option when
9741 you want to use a non-GNU linker, which also requires using the
9742 @command{collect2} program to make sure the system linker includes
9743 constructors and destructors. (@command{collect2} is included in the GCC
9744 distribution.) For systems which @emph{must} use @command{collect2}, the
9745 compiler driver @command{gcc} is configured to do this automatically.
9747 @item -finhibit-size-directive
9748 @opindex finhibit-size-directive
9749 Don't output a @code{.size} assembler directive, or anything else that
9750 would cause trouble if the function is split in the middle, and the
9751 two halves are placed at locations far apart in memory. This option is
9752 used when compiling @file{crtstuff.c}; you should not need to use it
9756 @opindex fverbose-asm
9757 Put extra commentary information in the generated assembly code to
9758 make it more readable. This option is generally only of use to those
9759 who actually need to read the generated assembly code (perhaps while
9760 debugging the compiler itself).
9762 @option{-fno-verbose-asm}, the default, causes the
9763 extra information to be omitted and is useful when comparing two assembler
9768 Consider all memory references through pointers to be volatile.
9770 @item -fvolatile-global
9771 @opindex fvolatile-global
9772 Consider all memory references to extern and global data items to
9773 be volatile. GCC does not consider static data items to be volatile
9774 because of this switch.
9776 @item -fvolatile-static
9777 @opindex fvolatile-static
9778 Consider all memory references to static data to be volatile.
9782 @cindex global offset table
9784 Generate position-independent code (PIC) suitable for use in a shared
9785 library, if supported for the target machine. Such code accesses all
9786 constant addresses through a global offset table (GOT)@. The dynamic
9787 loader resolves the GOT entries when the program starts (the dynamic
9788 loader is not part of GCC; it is part of the operating system). If
9789 the GOT size for the linked executable exceeds a machine-specific
9790 maximum size, you get an error message from the linker indicating that
9791 @option{-fpic} does not work; in that case, recompile with @option{-fPIC}
9792 instead. (These maximums are 16k on the m88k, 8k on the Sparc, and 32k
9793 on the m68k and RS/6000. The 386 has no such limit.)
9795 Position-independent code requires special support, and therefore works
9796 only on certain machines. For the 386, GCC supports PIC for System V
9797 but not for the Sun 386i. Code generated for the IBM RS/6000 is always
9798 position-independent.
9802 If supported for the target machine, emit position-independent code,
9803 suitable for dynamic linking and avoiding any limit on the size of the
9804 global offset table. This option makes a difference on the m68k, m88k,
9807 Position-independent code requires special support, and therefore works
9808 only on certain machines.
9810 @item -ffixed-@var{reg}
9812 Treat the register named @var{reg} as a fixed register; generated code
9813 should never refer to it (except perhaps as a stack pointer, frame
9814 pointer or in some other fixed role).
9816 @var{reg} must be the name of a register. The register names accepted
9817 are machine-specific and are defined in the @code{REGISTER_NAMES}
9818 macro in the machine description macro file.
9820 This flag does not have a negative form, because it specifies a
9823 @item -fcall-used-@var{reg}
9825 Treat the register named @var{reg} as an allocable register that is
9826 clobbered by function calls. It may be allocated for temporaries or
9827 variables that do not live across a call. Functions compiled this way
9828 will not save and restore the register @var{reg}.
9830 It is an error to used this flag with the frame pointer or stack pointer.
9831 Use of this flag for other registers that have fixed pervasive roles in
9832 the machine's execution model will produce disastrous results.
9834 This flag does not have a negative form, because it specifies a
9837 @item -fcall-saved-@var{reg}
9838 @opindex fcall-saved
9839 Treat the register named @var{reg} as an allocable register saved by
9840 functions. It may be allocated even for temporaries or variables that
9841 live across a call. Functions compiled this way will save and restore
9842 the register @var{reg} if they use it.
9844 It is an error to used this flag with the frame pointer or stack pointer.
9845 Use of this flag for other registers that have fixed pervasive roles in
9846 the machine's execution model will produce disastrous results.
9848 A different sort of disaster will result from the use of this flag for
9849 a register in which function values may be returned.
9851 This flag does not have a negative form, because it specifies a
9855 @opindex fpack-struct
9856 Pack all structure members together without holes. Usually you would
9857 not want to use this option, since it makes the code suboptimal, and
9858 the offsets of structure members won't agree with system libraries.
9860 @item -finstrument-functions
9861 @opindex finstrument-functions
9862 Generate instrumentation calls for entry and exit to functions. Just
9863 after function entry and just before function exit, the following
9864 profiling functions will be called with the address of the current
9865 function and its call site. (On some platforms,
9866 @code{__builtin_return_address} does not work beyond the current
9867 function, so the call site information may not be available to the
9868 profiling functions otherwise.)
9871 void __cyg_profile_func_enter (void *this_fn,
9873 void __cyg_profile_func_exit (void *this_fn,
9877 The first argument is the address of the start of the current function,
9878 which may be looked up exactly in the symbol table.
9880 This instrumentation is also done for functions expanded inline in other
9881 functions. The profiling calls will indicate where, conceptually, the
9882 inline function is entered and exited. This means that addressable
9883 versions of such functions must be available. If all your uses of a
9884 function are expanded inline, this may mean an additional expansion of
9885 code size. If you use @samp{extern inline} in your C code, an
9886 addressable version of such functions must be provided. (This is
9887 normally the case anyways, but if you get lucky and the optimizer always
9888 expands the functions inline, you might have gotten away without
9889 providing static copies.)
9891 A function may be given the attribute @code{no_instrument_function}, in
9892 which case this instrumentation will not be done. This can be used, for
9893 example, for the profiling functions listed above, high-priority
9894 interrupt routines, and any functions from which the profiling functions
9895 cannot safely be called (perhaps signal handlers, if the profiling
9896 routines generate output or allocate memory).
9899 @opindex fstack-check
9900 Generate code to verify that you do not go beyond the boundary of the
9901 stack. You should specify this flag if you are running in an
9902 environment with multiple threads, but only rarely need to specify it in
9903 a single-threaded environment since stack overflow is automatically
9904 detected on nearly all systems if there is only one stack.
9906 Note that this switch does not actually cause checking to be done; the
9907 operating system must do that. The switch causes generation of code
9908 to ensure that the operating system sees the stack being extended.
9910 @item -fstack-limit-register=@var{reg}
9911 @itemx -fstack-limit-symbol=@var{sym}
9912 @itemx -fno-stack-limit
9913 @opindex fstack-limit-register
9914 @opindex fstack-limit-symbol
9915 @opindex fno-stack-limit
9916 Generate code to ensure that the stack does not grow beyond a certain value,
9917 either the value of a register or the address of a symbol. If the stack
9918 would grow beyond the value, a signal is raised. For most targets,
9919 the signal is raised before the stack overruns the boundary, so
9920 it is possible to catch the signal without taking special precautions.
9922 For instance, if the stack starts at absolute address @samp{0x80000000}
9923 and grows downwards, you can use the flags
9924 @option{-fstack-limit-symbol=__stack_limit} and
9925 @option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
9926 of 128KB@. Note that this may only work with the GNU linker.
9928 @cindex aliasing of parameters
9929 @cindex parameters, aliased
9930 @item -fargument-alias
9931 @itemx -fargument-noalias
9932 @itemx -fargument-noalias-global
9933 @opindex fargument-alias
9934 @opindex fargument-noalias
9935 @opindex fargument-noalias-global
9936 Specify the possible relationships among parameters and between
9937 parameters and global data.
9939 @option{-fargument-alias} specifies that arguments (parameters) may
9940 alias each other and may alias global storage.@*
9941 @option{-fargument-noalias} specifies that arguments do not alias
9942 each other, but may alias global storage.@*
9943 @option{-fargument-noalias-global} specifies that arguments do not
9944 alias each other and do not alias global storage.
9946 Each language will automatically use whatever option is required by
9947 the language standard. You should not need to use these options yourself.
9949 @item -fleading-underscore
9950 @opindex fleading-underscore
9951 This option and its counterpart, @option{-fno-leading-underscore}, forcibly
9952 change the way C symbols are represented in the object file. One use
9953 is to help link with legacy assembly code.
9955 Be warned that you should know what you are doing when invoking this
9956 option, and that not all targets provide complete support for it.
9958 @item -ftls-model=@var{model}
9959 Alter the thread-local storage model to be used (@pxref{Thread-Local}).
9960 The @var{model} argument should be one of @code{global-dynamic},
9961 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
9963 The default without @option{-fpic} is @code{initial-exec}; with
9964 @option{-fpic} the default is @code{global-dynamic}.
9969 @node Environment Variables
9970 @section Environment Variables Affecting GCC
9971 @cindex environment variables
9973 @c man begin ENVIRONMENT
9975 This section describes several environment variables that affect how GCC
9976 operates. Some of them work by specifying directories or prefixes to use
9977 when searching for various kinds of files. Some are used to specify other
9978 aspects of the compilation environment.
9980 Note that you can also specify places to search using options such as
9981 @option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
9982 take precedence over places specified using environment variables, which
9983 in turn take precedence over those specified by the configuration of GCC@.
9984 @xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
9985 GNU Compiler Collection (GCC) Internals}.
9990 @c @itemx LC_COLLATE
9992 @c @itemx LC_MONETARY
9993 @c @itemx LC_NUMERIC
9998 @c @findex LC_COLLATE
10000 @c @findex LC_MONETARY
10001 @c @findex LC_NUMERIC
10005 These environment variables control the way that GCC uses
10006 localization information that allow GCC to work with different
10007 national conventions. GCC inspects the locale categories
10008 @env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
10009 so. These locale categories can be set to any value supported by your
10010 installation. A typical value is @samp{en_UK} for English in the United
10013 The @env{LC_CTYPE} environment variable specifies character
10014 classification. GCC uses it to determine the character boundaries in
10015 a string; this is needed for some multibyte encodings that contain quote
10016 and escape characters that would otherwise be interpreted as a string
10019 The @env{LC_MESSAGES} environment variable specifies the language to
10020 use in diagnostic messages.
10022 If the @env{LC_ALL} environment variable is set, it overrides the value
10023 of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
10024 and @env{LC_MESSAGES} default to the value of the @env{LANG}
10025 environment variable. If none of these variables are set, GCC
10026 defaults to traditional C English behavior.
10030 If @env{TMPDIR} is set, it specifies the directory to use for temporary
10031 files. GCC uses temporary files to hold the output of one stage of
10032 compilation which is to be used as input to the next stage: for example,
10033 the output of the preprocessor, which is the input to the compiler
10036 @item GCC_EXEC_PREFIX
10037 @findex GCC_EXEC_PREFIX
10038 If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
10039 names of the subprograms executed by the compiler. No slash is added
10040 when this prefix is combined with the name of a subprogram, but you can
10041 specify a prefix that ends with a slash if you wish.
10043 If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
10044 an appropriate prefix to use based on the pathname it was invoked with.
10046 If GCC cannot find the subprogram using the specified prefix, it
10047 tries looking in the usual places for the subprogram.
10049 The default value of @env{GCC_EXEC_PREFIX} is
10050 @file{@var{prefix}/lib/gcc-lib/} where @var{prefix} is the value
10051 of @code{prefix} when you ran the @file{configure} script.
10053 Other prefixes specified with @option{-B} take precedence over this prefix.
10055 This prefix is also used for finding files such as @file{crt0.o} that are
10058 In addition, the prefix is used in an unusual way in finding the
10059 directories to search for header files. For each of the standard
10060 directories whose name normally begins with @samp{/usr/local/lib/gcc-lib}
10061 (more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
10062 replacing that beginning with the specified prefix to produce an
10063 alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
10064 @file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
10065 These alternate directories are searched first; the standard directories
10068 @item COMPILER_PATH
10069 @findex COMPILER_PATH
10070 The value of @env{COMPILER_PATH} is a colon-separated list of
10071 directories, much like @env{PATH}. GCC tries the directories thus
10072 specified when searching for subprograms, if it can't find the
10073 subprograms using @env{GCC_EXEC_PREFIX}.
10076 @findex LIBRARY_PATH
10077 The value of @env{LIBRARY_PATH} is a colon-separated list of
10078 directories, much like @env{PATH}. When configured as a native compiler,
10079 GCC tries the directories thus specified when searching for special
10080 linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking
10081 using GCC also uses these directories when searching for ordinary
10082 libraries for the @option{-l} option (but directories specified with
10083 @option{-L} come first).
10087 @cindex locale definition
10088 This variable is used to pass locale information to the compiler. One way in
10089 which this information is used is to determine the character set to be used
10090 when character literals, string literals and comments are parsed in C and C++.
10091 When the compiler is configured to allow multibyte characters,
10092 the following values for @env{LANG} are recognized:
10096 Recognize JIS characters.
10098 Recognize SJIS characters.
10100 Recognize EUCJP characters.
10103 If @env{LANG} is not defined, or if it has some other value, then the
10104 compiler will use mblen and mbtowc as defined by the default locale to
10105 recognize and translate multibyte characters.
10109 Some additional environments variables affect the behavior of the
10112 @include cppenv.texi
10116 @node Running Protoize
10117 @section Running Protoize
10119 The program @code{protoize} is an optional part of GCC@. You can use
10120 it to add prototypes to a program, thus converting the program to ISO
10121 C in one respect. The companion program @code{unprotoize} does the
10122 reverse: it removes argument types from any prototypes that are found.
10124 When you run these programs, you must specify a set of source files as
10125 command line arguments. The conversion programs start out by compiling
10126 these files to see what functions they define. The information gathered
10127 about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
10129 After scanning comes actual conversion. The specified files are all
10130 eligible to be converted; any files they include (whether sources or
10131 just headers) are eligible as well.
10133 But not all the eligible files are converted. By default,
10134 @code{protoize} and @code{unprotoize} convert only source and header
10135 files in the current directory. You can specify additional directories
10136 whose files should be converted with the @option{-d @var{directory}}
10137 option. You can also specify particular files to exclude with the
10138 @option{-x @var{file}} option. A file is converted if it is eligible, its
10139 directory name matches one of the specified directory names, and its
10140 name within the directory has not been excluded.
10142 Basic conversion with @code{protoize} consists of rewriting most
10143 function definitions and function declarations to specify the types of
10144 the arguments. The only ones not rewritten are those for varargs
10147 @code{protoize} optionally inserts prototype declarations at the
10148 beginning of the source file, to make them available for any calls that
10149 precede the function's definition. Or it can insert prototype
10150 declarations with block scope in the blocks where undeclared functions
10153 Basic conversion with @code{unprotoize} consists of rewriting most
10154 function declarations to remove any argument types, and rewriting
10155 function definitions to the old-style pre-ISO form.
10157 Both conversion programs print a warning for any function declaration or
10158 definition that they can't convert. You can suppress these warnings
10161 The output from @code{protoize} or @code{unprotoize} replaces the
10162 original source file. The original file is renamed to a name ending
10163 with @samp{.save} (for DOS, the saved filename ends in @samp{.sav}
10164 without the original @samp{.c} suffix). If the @samp{.save} (@samp{.sav}
10165 for DOS) file already exists, then the source file is simply discarded.
10167 @code{protoize} and @code{unprotoize} both depend on GCC itself to
10168 scan the program and collect information about the functions it uses.
10169 So neither of these programs will work until GCC is installed.
10171 Here is a table of the options you can use with @code{protoize} and
10172 @code{unprotoize}. Each option works with both programs unless
10176 @item -B @var{directory}
10177 Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
10178 usual directory (normally @file{/usr/local/lib}). This file contains
10179 prototype information about standard system functions. This option
10180 applies only to @code{protoize}.
10182 @item -c @var{compilation-options}
10183 Use @var{compilation-options} as the options when running @code{gcc} to
10184 produce the @samp{.X} files. The special option @option{-aux-info} is
10185 always passed in addition, to tell @code{gcc} to write a @samp{.X} file.
10187 Note that the compilation options must be given as a single argument to
10188 @code{protoize} or @code{unprotoize}. If you want to specify several
10189 @code{gcc} options, you must quote the entire set of compilation options
10190 to make them a single word in the shell.
10192 There are certain @code{gcc} arguments that you cannot use, because they
10193 would produce the wrong kind of output. These include @option{-g},
10194 @option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in
10195 the @var{compilation-options}, they are ignored.
10198 Rename files to end in @samp{.C} (@samp{.cc} for DOS-based file
10199 systems) instead of @samp{.c}. This is convenient if you are converting
10200 a C program to C++. This option applies only to @code{protoize}.
10203 Add explicit global declarations. This means inserting explicit
10204 declarations at the beginning of each source file for each function
10205 that is called in the file and was not declared. These declarations
10206 precede the first function definition that contains a call to an
10207 undeclared function. This option applies only to @code{protoize}.
10209 @item -i @var{string}
10210 Indent old-style parameter declarations with the string @var{string}.
10211 This option applies only to @code{protoize}.
10213 @code{unprotoize} converts prototyped function definitions to old-style
10214 function definitions, where the arguments are declared between the
10215 argument list and the initial @samp{@{}. By default, @code{unprotoize}
10216 uses five spaces as the indentation. If you want to indent with just
10217 one space instead, use @option{-i " "}.
10220 Keep the @samp{.X} files. Normally, they are deleted after conversion
10224 Add explicit local declarations. @code{protoize} with @option{-l} inserts
10225 a prototype declaration for each function in each block which calls the
10226 function without any declaration. This option applies only to
10230 Make no real changes. This mode just prints information about the conversions
10231 that would have been done without @option{-n}.
10234 Make no @samp{.save} files. The original files are simply deleted.
10235 Use this option with caution.
10237 @item -p @var{program}
10238 Use the program @var{program} as the compiler. Normally, the name
10239 @file{gcc} is used.
10242 Work quietly. Most warnings are suppressed.
10245 Print the version number, just like @option{-v} for @code{gcc}.
10248 If you need special compiler options to compile one of your program's
10249 source files, then you should generate that file's @samp{.X} file
10250 specially, by running @code{gcc} on that source file with the
10251 appropriate options and the option @option{-aux-info}. Then run
10252 @code{protoize} on the entire set of files. @code{protoize} will use
10253 the existing @samp{.X} file because it is newer than the source file.
10257 gcc -Dfoo=bar file1.c -aux-info file1.X
10262 You need to include the special files along with the rest in the
10263 @code{protoize} command, even though their @samp{.X} files already
10264 exist, because otherwise they won't get converted.
10266 @xref{Protoize Caveats}, for more information on how to use
10267 @code{protoize} successfully.