1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2 @c 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
3 @c Free Software Foundation, Inc.
4 @c This is part of the GCC manual.
5 @c For copying conditions, see the file gcc.texi.
12 @c man begin COPYRIGHT
13 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
14 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
16 Permission is granted to copy, distribute and/or modify this document
17 under the terms of the GNU Free Documentation License, Version 1.2 or
18 any later version published by the Free Software Foundation; with the
19 Invariant Sections being ``GNU General Public License'' and ``Funding
20 Free Software'', the Front-Cover texts being (a) (see below), and with
21 the Back-Cover Texts being (b) (see below). A copy of the license is
22 included in the gfdl(7) man page.
24 (a) The FSF's Front-Cover Text is:
28 (b) The FSF's Back-Cover Text is:
30 You have freedom to copy and modify this GNU Manual, like GNU
31 software. Copies published by the Free Software Foundation raise
32 funds for GNU development.
34 @c Set file name and title for the man page.
36 @settitle GNU project C and C++ compiler
38 gcc [@option{-c}|@option{-S}|@option{-E}] [@option{-std=}@var{standard}]
39 [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
40 [@option{-W}@var{warn}@dots{}] [@option{-pedantic}]
41 [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
42 [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
43 [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
44 [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}
46 Only the most useful options are listed here; see below for the
47 remainder. @samp{g++} accepts mostly the same options as @samp{gcc}.
50 gpl(7), gfdl(7), fsf-funding(7),
51 cpp(1), gcov(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1)
52 and the Info entries for @file{gcc}, @file{cpp}, @file{as},
53 @file{ld}, @file{binutils} and @file{gdb}.
56 For instructions on reporting bugs, see
57 @w{@uref{http://gcc.gnu.org/bugs.html}}.
60 See the Info entry for @command{gcc}, or
61 @w{@uref{http://gcc.gnu.org/onlinedocs/gcc/Contributors.html}},
62 for contributors to GCC@.
67 @chapter GCC Command Options
68 @cindex GCC command options
69 @cindex command options
70 @cindex options, GCC command
72 @c man begin DESCRIPTION
73 When you invoke GCC, it normally does preprocessing, compilation,
74 assembly and linking. The ``overall options'' allow you to stop this
75 process at an intermediate stage. For example, the @option{-c} option
76 says not to run the linker. Then the output consists of object files
77 output by the assembler.
79 Other options are passed on to one stage of processing. Some options
80 control the preprocessor and others the compiler itself. Yet other
81 options control the assembler and linker; most of these are not
82 documented here, since you rarely need to use any of them.
84 @cindex C compilation options
85 Most of the command line options that you can use with GCC are useful
86 for C programs; when an option is only useful with another language
87 (usually C++), the explanation says so explicitly. If the description
88 for a particular option does not mention a source language, you can use
89 that option with all supported languages.
91 @cindex C++ compilation options
92 @xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
93 options for compiling C++ programs.
95 @cindex grouping options
96 @cindex options, grouping
97 The @command{gcc} program accepts options and file names as operands. Many
98 options have multi-letter names; therefore multiple single-letter options
99 may @emph{not} be grouped: @option{-dr} is very different from @w{@samp{-d
102 @cindex order of options
103 @cindex options, order
104 You can mix options and other arguments. For the most part, the order
105 you use doesn't matter. Order does matter when you use several
106 options of the same kind; for example, if you specify @option{-L} more
107 than once, the directories are searched in the order specified. Also,
108 the placement of the @option{-l} option is significant.
110 Many options have long names starting with @samp{-f} or with
111 @samp{-W}---for example,
112 @option{-fmove-loop-invariants}, @option{-Wformat} and so on. Most of
113 these have both positive and negative forms; the negative form of
114 @option{-ffoo} would be @option{-fno-foo}. This manual documents
115 only one of these two forms, whichever one is not the default.
119 @xref{Option Index}, for an index to GCC's options.
122 * Option Summary:: Brief list of all options, without explanations.
123 * Overall Options:: Controlling the kind of output:
124 an executable, object files, assembler files,
125 or preprocessed source.
126 * Invoking G++:: Compiling C++ programs.
127 * C Dialect Options:: Controlling the variant of C language compiled.
128 * C++ Dialect Options:: Variations on C++.
129 * Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
131 * Language Independent Options:: Controlling how diagnostics should be
133 * Warning Options:: How picky should the compiler be?
134 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
135 * Optimize Options:: How much optimization?
136 * Preprocessor Options:: Controlling header files and macro definitions.
137 Also, getting dependency information for Make.
138 * Assembler Options:: Passing options to the assembler.
139 * Link Options:: Specifying libraries and so on.
140 * Directory Options:: Where to find header files and libraries.
141 Where to find the compiler executable files.
142 * Spec Files:: How to pass switches to sub-processes.
143 * Target Options:: Running a cross-compiler, or an old version of GCC.
144 * Submodel Options:: Specifying minor hardware or convention variations,
145 such as 68010 vs 68020.
146 * Code Gen Options:: Specifying conventions for function calls, data layout
148 * Environment Variables:: Env vars that affect GCC.
149 * Precompiled Headers:: Compiling a header once, and using it many times.
150 * Running Protoize:: Automatically adding or removing function prototypes.
156 @section Option Summary
158 Here is a summary of all the options, grouped by type. Explanations are
159 in the following sections.
162 @item Overall Options
163 @xref{Overall Options,,Options Controlling the Kind of Output}.
164 @gccoptlist{-c -S -E -o @var{file} -combine -pipe -pass-exit-codes @gol
165 -x @var{language} -v -### --help@r{[}=@var{class}@r{]} --target-help @gol
166 --version @@@var{file}}
168 @item C Language Options
169 @xref{C Dialect Options,,Options Controlling C Dialect}.
170 @gccoptlist{-ansi -std=@var{standard} -fgnu89-inline @gol
171 -aux-info @var{filename} @gol
172 -fno-asm -fno-builtin -fno-builtin-@var{function} @gol
173 -fhosted -ffreestanding -fopenmp -fms-extensions @gol
174 -trigraphs -no-integrated-cpp -traditional -traditional-cpp @gol
175 -fallow-single-precision -fcond-mismatch -flax-vector-conversions @gol
176 -fsigned-bitfields -fsigned-char @gol
177 -funsigned-bitfields -funsigned-char}
179 @item C++ Language Options
180 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
181 @gccoptlist{-fabi-version=@var{n} -fno-access-control -fcheck-new @gol
182 -fconserve-space -ffriend-injection @gol
183 -fno-elide-constructors @gol
184 -fno-enforce-eh-specs @gol
185 -ffor-scope -fno-for-scope -fno-gnu-keywords @gol
186 -fno-implicit-templates @gol
187 -fno-implicit-inline-templates @gol
188 -fno-implement-inlines -fms-extensions @gol
189 -fno-nonansi-builtins -fno-operator-names @gol
190 -fno-optional-diags -fpermissive @gol
191 -frepo -fno-rtti -fstats -ftemplate-depth-@var{n} @gol
192 -fno-threadsafe-statics -fuse-cxa-atexit -fno-weak -nostdinc++ @gol
193 -fno-default-inline -fvisibility-inlines-hidden @gol
194 -Wabi -Wctor-dtor-privacy @gol
195 -Wnon-virtual-dtor -Wreorder @gol
196 -Weffc++ -Wno-deprecated -Wstrict-null-sentinel @gol
197 -Wno-non-template-friend -Wold-style-cast @gol
198 -Woverloaded-virtual -Wno-pmf-conversions @gol
201 @item Objective-C and Objective-C++ Language Options
202 @xref{Objective-C and Objective-C++ Dialect Options,,Options Controlling
203 Objective-C and Objective-C++ Dialects}.
204 @gccoptlist{-fconstant-string-class=@var{class-name} @gol
205 -fgnu-runtime -fnext-runtime @gol
206 -fno-nil-receivers @gol
207 -fobjc-call-cxx-cdtors @gol
208 -fobjc-direct-dispatch @gol
209 -fobjc-exceptions @gol
211 -freplace-objc-classes @gol
214 -Wassign-intercept @gol
215 -Wno-protocol -Wselector @gol
216 -Wstrict-selector-match @gol
217 -Wundeclared-selector}
219 @item Language Independent Options
220 @xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}.
221 @gccoptlist{-fmessage-length=@var{n} @gol
222 -fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]} @gol
223 -fdiagnostics-show-option}
225 @item Warning Options
226 @xref{Warning Options,,Options to Request or Suppress Warnings}.
227 @gccoptlist{-fsyntax-only -pedantic -pedantic-errors @gol
228 -w -Wextra -Wall -Waddress -Waggregate-return -Warray-bounds @gol
229 -Wno-attributes -Wc++-compat -Wc++0x-compat -Wcast-align -Wcast-qual @gol
230 -Wchar-subscripts -Wclobbered -Wcomment @gol
231 -Wconversion -Wcoverage-mismatch -Wno-deprecated-declarations @gol
232 -Wdisabled-optimization -Wno-div-by-zero @gol
233 -Wempty-body -Wno-endif-labels @gol
234 -Werror -Werror=* @gol
235 -Wfatal-errors -Wfloat-equal -Wformat -Wformat=2 @gol
236 -Wno-format-extra-args -Wformat-nonliteral @gol
237 -Wformat-security -Wformat-y2k @gol
238 -Wimplicit -Wimplicit-function-declaration -Wimplicit-int @gol
239 -Wimport -Wno-import -Winit-self -Winline @gol
240 -Wno-int-to-pointer-cast -Wno-invalid-offsetof @gol
241 -Winvalid-pch -Wlarger-than-@var{len} -Wunsafe-loop-optimizations @gol
242 -Wlogical-op -Wlong-long @gol
243 -Wmain -Wmissing-braces -Wmissing-field-initializers @gol
244 -Wmissing-format-attribute -Wmissing-include-dirs @gol
245 -Wmissing-noreturn @gol
246 -Wno-multichar -Wnonnull -Wno-overflow @gol
247 -Woverlength-strings -Wpacked -Wpadded @gol
248 -Wparentheses -Wpointer-arith -Wno-pointer-to-int-cast @gol
249 -Wredundant-decls @gol
250 -Wreturn-type -Wsequence-point -Wshadow @gol
251 -Wsign-compare -Wsign-conversion -Wstack-protector @gol
252 -Wstrict-aliasing -Wstrict-aliasing=n @gol
253 -Wstrict-overflow -Wstrict-overflow=@var{n} @gol
254 -Wswitch -Wswitch-default -Wswitch-enum @gol
255 -Wsystem-headers -Wtrigraphs -Wtype-limits -Wundef -Wuninitialized @gol
256 -Wunknown-pragmas -Wno-pragmas -Wunreachable-code @gol
257 -Wunused -Wunused-function -Wunused-label -Wunused-parameter @gol
258 -Wunused-value -Wunused-variable @gol
259 -Wvariadic-macros -Wvla @gol
260 -Wvolatile-register-var -Wwrite-strings}
262 @item C-only Warning Options
263 @gccoptlist{-Wbad-function-cast -Wmissing-declarations @gol
264 -Wmissing-parameter-type -Wmissing-prototypes -Wnested-externs @gol
265 -Wold-style-declaration -Wold-style-definition @gol
266 -Wstrict-prototypes -Wtraditional -Wtraditional-conversion @gol
267 -Wdeclaration-after-statement -Wpointer-sign}
269 @item Debugging Options
270 @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
271 @gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
272 -fdbg-cnt-list -fdbg-cnt=@var{counter-value-list} @gol
273 -fdump-noaddr -fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} @gol
274 -fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
275 -fdump-ipa-all -fdump-ipa-cgraph @gol
277 -fdump-tree-original@r{[}-@var{n}@r{]} @gol
278 -fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
279 -fdump-tree-inlined@r{[}-@var{n}@r{]} @gol
280 -fdump-tree-cfg -fdump-tree-vcg -fdump-tree-alias @gol
282 -fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol
283 -fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol
284 -fdump-tree-gimple@r{[}-raw@r{]} -fdump-tree-mudflap@r{[}-@var{n}@r{]} @gol
285 -fdump-tree-dom@r{[}-@var{n}@r{]} @gol
286 -fdump-tree-dse@r{[}-@var{n}@r{]} @gol
287 -fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol
288 -fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
289 -fdump-tree-copyrename@r{[}-@var{n}@r{]} @gol
290 -fdump-tree-nrv -fdump-tree-vect @gol
291 -fdump-tree-sink @gol
292 -fdump-tree-sra@r{[}-@var{n}@r{]} @gol
293 -fdump-tree-salias @gol
294 -fdump-tree-fre@r{[}-@var{n}@r{]} @gol
295 -fdump-tree-vrp@r{[}-@var{n}@r{]} @gol
296 -ftree-vectorizer-verbose=@var{n} @gol
297 -fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol
298 -feliminate-dwarf2-dups -feliminate-unused-debug-types @gol
299 -feliminate-unused-debug-symbols -femit-class-debug-always @gol
300 -fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report -fprofile-arcs @gol
301 -frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
302 -ftest-coverage -ftime-report -fvar-tracking @gol
303 -g -g@var{level} -gcoff -gdwarf-2 @gol
304 -ggdb -gstabs -gstabs+ -gvms -gxcoff -gxcoff+ @gol
305 -femit-struct-debug-baseonly -femit-struct-debug-reduced @gol
306 -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} @gol
307 -p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol
308 -print-multi-directory -print-multi-lib @gol
309 -print-prog-name=@var{program} -print-search-dirs -Q @gol
310 -print-sysroot-headers-suffix @gol
313 @item Optimization Options
314 @xref{Optimize Options,,Options that Control Optimization}.
315 @gccoptlist{-falign-functions=@var{n} -falign-jumps=@var{n} @gol
316 -falign-labels=@var{n} -falign-loops=@var{n} @gol
317 -fbounds-check -fmudflap -fmudflapth -fmudflapir @gol
318 -fbranch-probabilities -fprofile-values -fvpt -fbranch-target-load-optimize @gol
319 -fbranch-target-load-optimize2 -fbtr-bb-exclusive @gol
320 -fcaller-saves -fcprop-registers -fcse-follow-jumps @gol
321 -fcse-skip-blocks -fcx-limited-range -fdata-sections @gol
322 -fdelayed-branch -fdelete-null-pointer-checks -fearly-inlining @gol
323 -fexpensive-optimizations -ffast-math -ffloat-store @gol
324 -fforce-addr -fforward-propagate -ffunction-sections @gol
325 -fgcse -fgcse-lm -fgcse-sm -fgcse-las -fgcse-after-reload @gol
326 -fcrossjumping -fif-conversion -fif-conversion2 @gol
327 -finline-functions -finline-functions-called-once @gol
328 -finline-limit=@var{n} -fkeep-inline-functions @gol
329 -fkeep-static-consts -fmerge-constants -fmerge-all-constants @gol
330 -fmodulo-sched -fno-branch-count-reg @gol
331 -fno-default-inline -fno-defer-pop -fmove-loop-invariants @gol
332 -fno-function-cse -fno-guess-branch-probability @gol
333 -fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol
334 -funsafe-math-optimizations -funsafe-loop-optimizations @gol
335 -ffinite-math-only -fno-signed-zeros @gol
336 -fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol
337 -fomit-frame-pointer -foptimize-register-move @gol
338 -foptimize-sibling-calls -fpredictive-commoning -fprefetch-loop-arrays @gol
339 -fprofile-generate -fprofile-use @gol
340 -fregmove -frename-registers @gol
341 -freorder-blocks -freorder-blocks-and-partition -freorder-functions @gol
342 -frerun-cse-after-loop @gol
343 -frounding-math -frtl-abstract-sequences @gol
344 -fschedule-insns -fschedule-insns2 @gol
345 -fno-sched-interblock -fno-sched-spec -fsched-spec-load @gol
346 -fsched-spec-load-dangerous @gol
347 -fsched-stalled-insns=@var{n} -fsched-stalled-insns-dep=@var{n} @gol
348 -fsched2-use-superblocks @gol
349 -fsched2-use-traces -fsee -freschedule-modulo-scheduled-loops @gol
350 -fsection-anchors -fsignaling-nans -fsingle-precision-constant @gol
351 -fno-split-wide-types -fstack-protector -fstack-protector-all @gol
352 -fstrict-aliasing -fstrict-overflow -ftracer -fthread-jumps @gol
353 -funroll-all-loops -funroll-loops -fpeel-loops @gol
354 -fsplit-ivs-in-unroller -funswitch-loops @gol
355 -fvariable-expansion-in-unroller @gol
356 -ftree-pre -ftree-ccp -ftree-dce -ftree-loop-optimize @gol
357 -ftree-loop-linear -ftree-loop-im -ftree-loop-ivcanon -fivopts @gol
358 -fcheck-data-deps @gol
359 -ftree-dominator-opts -ftree-dse -ftree-copyrename -ftree-sink @gol
360 -ftree-ch -ftree-sra -ftree-ter -ftree-fre -ftree-vectorize @gol
361 -ftree-vect-loop-version -fvect-cost-model -ftree-salias -fipa-pta -fweb @gol
362 -ftree-copy-prop -ftree-store-ccp -ftree-store-copy-prop -fwhole-program @gol
363 --param @var{name}=@var{value}
364 -O -O0 -O1 -O2 -O3 -Os}
366 @item Preprocessor Options
367 @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
368 @gccoptlist{-A@var{question}=@var{answer} @gol
369 -A-@var{question}@r{[}=@var{answer}@r{]} @gol
370 -C -dD -dI -dM -dN @gol
371 -D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol
372 -idirafter @var{dir} @gol
373 -include @var{file} -imacros @var{file} @gol
374 -iprefix @var{file} -iwithprefix @var{dir} @gol
375 -iwithprefixbefore @var{dir} -isystem @var{dir} @gol
376 -imultilib @var{dir} -isysroot @var{dir} @gol
377 -M -MM -MF -MG -MP -MQ -MT -nostdinc @gol
378 -P -fworking-directory -remap @gol
379 -trigraphs -undef -U@var{macro} -Wp,@var{option} @gol
380 -Xpreprocessor @var{option}}
382 @item Assembler Option
383 @xref{Assembler Options,,Passing Options to the Assembler}.
384 @gccoptlist{-Wa,@var{option} -Xassembler @var{option}}
387 @xref{Link Options,,Options for Linking}.
388 @gccoptlist{@var{object-file-name} -l@var{library} @gol
389 -nostartfiles -nodefaultlibs -nostdlib -pie -rdynamic @gol
390 -s -static -static-libgcc -shared -shared-libgcc -symbolic @gol
391 -Wl,@var{option} -Xlinker @var{option} @gol
394 @item Directory Options
395 @xref{Directory Options,,Options for Directory Search}.
396 @gccoptlist{-B@var{prefix} -I@var{dir} -iquote@var{dir} -L@var{dir}
397 -specs=@var{file} -I- --sysroot=@var{dir}}
400 @c I wrote this xref this way to avoid overfull hbox. -- rms
401 @xref{Target Options}.
402 @gccoptlist{-V @var{version} -b @var{machine}}
404 @item Machine Dependent Options
405 @xref{Submodel Options,,Hardware Models and Configurations}.
406 @c This list is ordered alphanumerically by subsection name.
407 @c Try and put the significant identifier (CPU or system) first,
408 @c so users have a clue at guessing where the ones they want will be.
411 @gccoptlist{-EB -EL @gol
412 -mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text-section} @gol
413 -mdata=@var{data-section} -mrodata=@var{readonly-data-section}}
416 @gccoptlist{-mapcs-frame -mno-apcs-frame @gol
417 -mabi=@var{name} @gol
418 -mapcs-stack-check -mno-apcs-stack-check @gol
419 -mapcs-float -mno-apcs-float @gol
420 -mapcs-reentrant -mno-apcs-reentrant @gol
421 -msched-prolog -mno-sched-prolog @gol
422 -mlittle-endian -mbig-endian -mwords-little-endian @gol
423 -mfloat-abi=@var{name} -msoft-float -mhard-float -mfpe @gol
424 -mthumb-interwork -mno-thumb-interwork @gol
425 -mcpu=@var{name} -march=@var{name} -mfpu=@var{name} @gol
426 -mstructure-size-boundary=@var{n} @gol
427 -mabort-on-noreturn @gol
428 -mlong-calls -mno-long-calls @gol
429 -msingle-pic-base -mno-single-pic-base @gol
430 -mpic-register=@var{reg} @gol
431 -mnop-fun-dllimport @gol
432 -mcirrus-fix-invalid-insns -mno-cirrus-fix-invalid-insns @gol
433 -mpoke-function-name @gol
435 -mtpcs-frame -mtpcs-leaf-frame @gol
436 -mcaller-super-interworking -mcallee-super-interworking @gol
440 @gccoptlist{-mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts @gol
441 -mcall-prologues -mno-tablejump -mtiny-stack -mint8}
443 @emph{Blackfin Options}
444 @gccoptlist{-mcpu=@var{cpu} -msim -momit-leaf-frame-pointer @gol
445 -mno-omit-leaf-frame-pointer -mspecld-anomaly -mno-specld-anomaly @gol
446 -mcsync-anomaly -mno-csync-anomaly -mlow-64k -mno-low64k @gol
447 -mstack-check-l1 -mid-shared-library -mno-id-shared-library @gol
448 -mshared-library-id=@var{n} -mleaf-id-shared-library @gol
449 -mno-leaf-id-shared-library -msep-data -mno-sep-data -mlong-calls @gol
453 @gccoptlist{-mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol
454 -mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol
455 -metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol
456 -mstack-align -mdata-align -mconst-align @gol
457 -m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol
458 -melf -maout -melinux -mlinux -sim -sim2 @gol
459 -mmul-bug-workaround -mno-mul-bug-workaround}
462 @gccoptlist{-mmac -mpush-args}
464 @emph{Darwin Options}
465 @gccoptlist{-all_load -allowable_client -arch -arch_errors_fatal @gol
466 -arch_only -bind_at_load -bundle -bundle_loader @gol
467 -client_name -compatibility_version -current_version @gol
469 -dependency-file -dylib_file -dylinker_install_name @gol
470 -dynamic -dynamiclib -exported_symbols_list @gol
471 -filelist -flat_namespace -force_cpusubtype_ALL @gol
472 -force_flat_namespace -headerpad_max_install_names @gol
474 -image_base -init -install_name -keep_private_externs @gol
475 -multi_module -multiply_defined -multiply_defined_unused @gol
476 -noall_load -no_dead_strip_inits_and_terms @gol
477 -nofixprebinding -nomultidefs -noprebind -noseglinkedit @gol
478 -pagezero_size -prebind -prebind_all_twolevel_modules @gol
479 -private_bundle -read_only_relocs -sectalign @gol
480 -sectobjectsymbols -whyload -seg1addr @gol
481 -sectcreate -sectobjectsymbols -sectorder @gol
482 -segaddr -segs_read_only_addr -segs_read_write_addr @gol
483 -seg_addr_table -seg_addr_table_filename -seglinkedit @gol
484 -segprot -segs_read_only_addr -segs_read_write_addr @gol
485 -single_module -static -sub_library -sub_umbrella @gol
486 -twolevel_namespace -umbrella -undefined @gol
487 -unexported_symbols_list -weak_reference_mismatches @gol
488 -whatsloaded -F -gused -gfull -mmacosx-version-min=@var{version} @gol
489 -mkernel -mone-byte-bool}
491 @emph{DEC Alpha Options}
492 @gccoptlist{-mno-fp-regs -msoft-float -malpha-as -mgas @gol
493 -mieee -mieee-with-inexact -mieee-conformant @gol
494 -mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} @gol
495 -mtrap-precision=@var{mode} -mbuild-constants @gol
496 -mcpu=@var{cpu-type} -mtune=@var{cpu-type} @gol
497 -mbwx -mmax -mfix -mcix @gol
498 -mfloat-vax -mfloat-ieee @gol
499 -mexplicit-relocs -msmall-data -mlarge-data @gol
500 -msmall-text -mlarge-text @gol
501 -mmemory-latency=@var{time}}
503 @emph{DEC Alpha/VMS Options}
504 @gccoptlist{-mvms-return-codes}
507 @gccoptlist{-mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 @gol
508 -mhard-float -msoft-float @gol
509 -malloc-cc -mfixed-cc -mdword -mno-dword @gol
510 -mdouble -mno-double @gol
511 -mmedia -mno-media -mmuladd -mno-muladd @gol
512 -mfdpic -minline-plt -mgprel-ro -multilib-library-pic @gol
513 -mlinked-fp -mlong-calls -malign-labels @gol
514 -mlibrary-pic -macc-4 -macc-8 @gol
515 -mpack -mno-pack -mno-eflags -mcond-move -mno-cond-move @gol
516 -moptimize-membar -mno-optimize-membar @gol
517 -mscc -mno-scc -mcond-exec -mno-cond-exec @gol
518 -mvliw-branch -mno-vliw-branch @gol
519 -mmulti-cond-exec -mno-multi-cond-exec -mnested-cond-exec @gol
520 -mno-nested-cond-exec -mtomcat-stats @gol
524 @emph{GNU/Linux Options}
525 @gccoptlist{-muclibc}
527 @emph{H8/300 Options}
528 @gccoptlist{-mrelax -mh -ms -mn -mint32 -malign-300}
531 @gccoptlist{-march=@var{architecture-type} @gol
532 -mbig-switch -mdisable-fpregs -mdisable-indexing @gol
533 -mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol
534 -mfixed-range=@var{register-range} @gol
535 -mjump-in-delay -mlinker-opt -mlong-calls @gol
536 -mlong-load-store -mno-big-switch -mno-disable-fpregs @gol
537 -mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol
538 -mno-jump-in-delay -mno-long-load-store @gol
539 -mno-portable-runtime -mno-soft-float @gol
540 -mno-space-regs -msoft-float -mpa-risc-1-0 @gol
541 -mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime @gol
542 -mschedule=@var{cpu-type} -mspace-regs -msio -mwsio @gol
543 -munix=@var{unix-std} -nolibdld -static -threads}
545 @emph{i386 and x86-64 Options}
546 @gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
547 -mfpmath=@var{unit} @gol
548 -masm=@var{dialect} -mno-fancy-math-387 @gol
549 -mno-fp-ret-in-387 -msoft-float @gol
550 -mno-wide-multiply -mrtd -malign-double @gol
551 -mpreferred-stack-boundary=@var{num} -mcx16 -msahf -mrecip @gol
552 -mmmx -msse -msse2 -msse3 -mssse3 -msse4.1 -msse4.2 -msse4 @gol
553 -msse4a -m3dnow -mpopcnt -mabm @gol
554 -mthreads -mno-align-stringops -minline-all-stringops @gol
555 -mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol
556 -m96bit-long-double -mregparm=@var{num} -msseregparm @gol
557 -mpc32 -mpc64 -mpc80 mstackrealign @gol
558 -momit-leaf-frame-pointer -mno-red-zone -mno-tls-direct-seg-refs @gol
559 -mcmodel=@var{code-model} @gol
560 -m32 -m64 -mlarge-data-threshold=@var{num}}
563 @gccoptlist{-mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol
564 -mvolatile-asm-stop -mregister-names -mno-sdata @gol
565 -mconstant-gp -mauto-pic -minline-float-divide-min-latency @gol
566 -minline-float-divide-max-throughput @gol
567 -minline-int-divide-min-latency @gol
568 -minline-int-divide-max-throughput @gol
569 -minline-sqrt-min-latency -minline-sqrt-max-throughput @gol
570 -mno-dwarf2-asm -mearly-stop-bits @gol
571 -mfixed-range=@var{register-range} -mtls-size=@var{tls-size} @gol
572 -mtune=@var{cpu-type} -mt -pthread -milp32 -mlp64 @gol
573 -mno-sched-br-data-spec -msched-ar-data-spec -mno-sched-control-spec @gol
574 -msched-br-in-data-spec -msched-ar-in-data-spec -msched-in-control-spec @gol
575 -msched-ldc -mno-sched-control-ldc -mno-sched-spec-verbose @gol
576 -mno-sched-prefer-non-data-spec-insns @gol
577 -mno-sched-prefer-non-control-spec-insns @gol
578 -mno-sched-count-spec-in-critical-path}
580 @emph{M32R/D Options}
581 @gccoptlist{-m32r2 -m32rx -m32r @gol
583 -malign-loops -mno-align-loops @gol
584 -missue-rate=@var{number} @gol
585 -mbranch-cost=@var{number} @gol
586 -mmodel=@var{code-size-model-type} @gol
587 -msdata=@var{sdata-type} @gol
588 -mno-flush-func -mflush-func=@var{name} @gol
589 -mno-flush-trap -mflush-trap=@var{number} @gol
593 @gccoptlist{-mcpu=@var{cpu} -msim -memregs=@var{number}}
595 @emph{M680x0 Options}
596 @gccoptlist{-march=@var{arch} -mcpu=@var{cpu} -mtune=@var{tune}
597 -m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol
598 -m68060 -mcpu32 -m5200 -m5206e -m528x -m5307 -m5407 @gol
599 -mcfv4e -mbitfield -mno-bitfield -mc68000 -mc68020 @gol
600 -mnobitfield -mrtd -mno-rtd -mdiv -mno-div -mshort @gol
601 -mno-short -mhard-float -m68881 -msoft-float -mpcrel @gol
602 -malign-int -mstrict-align -msep-data -mno-sep-data @gol
603 -mshared-library-id=n -mid-shared-library -mno-id-shared-library}
605 @emph{M68hc1x Options}
606 @gccoptlist{-m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 @gol
607 -mauto-incdec -minmax -mlong-calls -mshort @gol
608 -msoft-reg-count=@var{count}}
611 @gccoptlist{-mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol
612 -mno-relax-immediates -mwide-bitfields -mno-wide-bitfields @gol
613 -m4byte-functions -mno-4byte-functions -mcallgraph-data @gol
614 -mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim @gol
615 -mlittle-endian -mbig-endian -m210 -m340 -mstack-increment}
618 @gccoptlist{-EL -EB -march=@var{arch} -mtune=@var{arch} @gol
619 -mips1 -mips2 -mips3 -mips4 -mips32 -mips32r2 -mips64 @gol
620 -mips16 -mno-mips16 -mabi=@var{abi} -mabicalls -mno-abicalls @gol
621 -mshared -mno-shared -mxgot -mno-xgot -mgp32 -mgp64 @gol
622 -mfp32 -mfp64 -mhard-float -msoft-float @gol
623 -msingle-float -mdouble-float -mdsp -mno-dsp -mdspr2 -mno-dspr2 @gol
624 -mpaired-single -mno-paired-single -mdmx -mno-mdmx @gol
625 -mips3d -mno-mips3d -mmt -mno-mt @gol
626 -mlong64 -mlong32 -msym32 -mno-sym32 @gol
627 -G@var{num} -membedded-data -mno-embedded-data @gol
628 -muninit-const-in-rodata -mno-uninit-const-in-rodata @gol
629 -msplit-addresses -mno-split-addresses @gol
630 -mexplicit-relocs -mno-explicit-relocs @gol
631 -mcheck-zero-division -mno-check-zero-division @gol
632 -mdivide-traps -mdivide-breaks @gol
633 -mmemcpy -mno-memcpy -mlong-calls -mno-long-calls @gol
634 -mmad -mno-mad -mfused-madd -mno-fused-madd -nocpp @gol
635 -mfix-r4000 -mno-fix-r4000 -mfix-r4400 -mno-fix-r4400 @gol
636 -mfix-vr4120 -mno-fix-vr4120 -mfix-vr4130 -mno-fix-vr4130 @gol
637 -mfix-sb1 -mno-fix-sb1 @gol
638 -mflush-func=@var{func} -mno-flush-func @gol
639 -mbranch-likely -mno-branch-likely @gol
640 -mfp-exceptions -mno-fp-exceptions @gol
641 -mvr4130-align -mno-vr4130-align}
644 @gccoptlist{-mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol
645 -mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol
646 -melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol
647 -mno-base-addresses -msingle-exit -mno-single-exit}
649 @emph{MN10300 Options}
650 @gccoptlist{-mmult-bug -mno-mult-bug @gol
651 -mam33 -mno-am33 @gol
652 -mam33-2 -mno-am33-2 @gol
653 -mreturn-pointer-on-d0 @gol
657 @gccoptlist{-mno-crt0 -mbacc -msim @gol
658 -march=@var{cpu-type} }
660 @emph{PDP-11 Options}
661 @gccoptlist{-mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol
662 -mbcopy -mbcopy-builtin -mint32 -mno-int16 @gol
663 -mint16 -mno-int32 -mfloat32 -mno-float64 @gol
664 -mfloat64 -mno-float32 -mabshi -mno-abshi @gol
665 -mbranch-expensive -mbranch-cheap @gol
666 -msplit -mno-split -munix-asm -mdec-asm}
668 @emph{PowerPC Options}
669 See RS/6000 and PowerPC Options.
671 @emph{RS/6000 and PowerPC Options}
672 @gccoptlist{-mcpu=@var{cpu-type} @gol
673 -mtune=@var{cpu-type} @gol
674 -mpower -mno-power -mpower2 -mno-power2 @gol
675 -mpowerpc -mpowerpc64 -mno-powerpc @gol
676 -maltivec -mno-altivec @gol
677 -mpowerpc-gpopt -mno-powerpc-gpopt @gol
678 -mpowerpc-gfxopt -mno-powerpc-gfxopt @gol
679 -mmfcrf -mno-mfcrf -mpopcntb -mno-popcntb -mfprnd -mno-fprnd @gol
680 -mcmpb -mno-cmpb -mmfpgpr -mno-mfpgpr -mdfp -mno-dfp @gol
681 -mnew-mnemonics -mold-mnemonics @gol
682 -mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc @gol
683 -m64 -m32 -mxl-compat -mno-xl-compat -mpe @gol
684 -malign-power -malign-natural @gol
685 -msoft-float -mhard-float -mmultiple -mno-multiple @gol
686 -mstring -mno-string -mupdate -mno-update @gol
687 -mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol
688 -mstrict-align -mno-strict-align -mrelocatable @gol
689 -mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol
690 -mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol
691 -mdynamic-no-pic -maltivec -mswdiv @gol
692 -mprioritize-restricted-insns=@var{priority} @gol
693 -msched-costly-dep=@var{dependence_type} @gol
694 -minsert-sched-nops=@var{scheme} @gol
695 -mcall-sysv -mcall-netbsd @gol
696 -maix-struct-return -msvr4-struct-return @gol
697 -mabi=@var{abi-type} -msecure-plt -mbss-plt @gol
698 -misel -mno-isel @gol
699 -misel=yes -misel=no @gol
701 -mspe=yes -mspe=no @gol
702 -mvrsave -mno-vrsave @gol
703 -mmulhw -mno-mulhw @gol
704 -mdlmzb -mno-dlmzb @gol
705 -mfloat-gprs=yes -mfloat-gprs=no -mfloat-gprs=single -mfloat-gprs=double @gol
706 -mprototype -mno-prototype @gol
707 -msim -mmvme -mads -myellowknife -memb -msdata @gol
708 -msdata=@var{opt} -mvxworks -mwindiss -G @var{num} -pthread}
710 @emph{S/390 and zSeries Options}
711 @gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
712 -mhard-float -msoft-float -mlong-double-64 -mlong-double-128 @gol
713 -mbackchain -mno-backchain -mpacked-stack -mno-packed-stack @gol
714 -msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol
715 -m64 -m31 -mdebug -mno-debug -mesa -mzarch @gol
716 -mtpf-trace -mno-tpf-trace -mfused-madd -mno-fused-madd @gol
717 -mwarn-framesize -mwarn-dynamicstack -mstack-size -mstack-guard}
720 @gccoptlist{-meb -mel @gol
724 -mscore5 -mscore5u -mscore7 -mscore7d}
727 @gccoptlist{-m1 -m2 -m2e -m3 -m3e @gol
728 -m4-nofpu -m4-single-only -m4-single -m4 @gol
729 -m4a-nofpu -m4a-single-only -m4a-single -m4a -m4al @gol
730 -m5-64media -m5-64media-nofpu @gol
731 -m5-32media -m5-32media-nofpu @gol
732 -m5-compact -m5-compact-nofpu @gol
733 -mb -ml -mdalign -mrelax @gol
734 -mbigtable -mfmovd -mhitachi -mrenesas -mno-renesas -mnomacsave @gol
735 -mieee -misize -minline-ic_invalidate -mpadstruct -mspace @gol
736 -mprefergot -musermode -multcost=@var{number} -mdiv=@var{strategy} @gol
737 -mdivsi3_libfunc=@var{name} @gol
738 -madjust-unroll -mindexed-addressing -mgettrcost=@var{number} -mpt-fixed @gol
742 @gccoptlist{-mcpu=@var{cpu-type} @gol
743 -mtune=@var{cpu-type} @gol
744 -mcmodel=@var{code-model} @gol
745 -m32 -m64 -mapp-regs -mno-app-regs @gol
746 -mfaster-structs -mno-faster-structs @gol
747 -mfpu -mno-fpu -mhard-float -msoft-float @gol
748 -mhard-quad-float -msoft-quad-float @gol
749 -mimpure-text -mno-impure-text -mlittle-endian @gol
750 -mstack-bias -mno-stack-bias @gol
751 -munaligned-doubles -mno-unaligned-doubles @gol
752 -mv8plus -mno-v8plus -mvis -mno-vis
753 -threads -pthreads -pthread}
756 @gccoptlist{-mwarn-reloc -merror-reloc @gol
757 -msafe-dma -munsafe-dma @gol
759 -msmall-mem -mlarge-mem -mstdmain @gol
760 -mfixed-range=@var{register-range}}
762 @emph{System V Options}
763 @gccoptlist{-Qy -Qn -YP,@var{paths} -Ym,@var{dir}}
765 @emph{TMS320C3x/C4x Options}
766 @gccoptlist{-mcpu=@var{cpu} -mbig -msmall -mregparm -mmemparm @gol
767 -mfast-fix -mmpyi -mbk -mti -mdp-isr-reload @gol
768 -mrpts=@var{count} -mrptb -mdb -mloop-unsigned @gol
769 -mparallel-insns -mparallel-mpy -mpreserve-float}
772 @gccoptlist{-mlong-calls -mno-long-calls -mep -mno-ep @gol
773 -mprolog-function -mno-prolog-function -mspace @gol
774 -mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol
775 -mapp-regs -mno-app-regs @gol
776 -mdisable-callt -mno-disable-callt @gol
782 @gccoptlist{-mg -mgnu -munix}
784 @emph{VxWorks Options}
785 @gccoptlist{-mrtp -non-static -Bstatic -Bdynamic @gol
786 -Xbind-lazy -Xbind-now}
788 @emph{x86-64 Options}
789 See i386 and x86-64 Options.
791 @emph{Xstormy16 Options}
794 @emph{Xtensa Options}
795 @gccoptlist{-mconst16 -mno-const16 @gol
796 -mfused-madd -mno-fused-madd @gol
797 -mtext-section-literals -mno-text-section-literals @gol
798 -mtarget-align -mno-target-align @gol
799 -mlongcalls -mno-longcalls}
801 @emph{zSeries Options}
802 See S/390 and zSeries Options.
804 @item Code Generation Options
805 @xref{Code Gen Options,,Options for Code Generation Conventions}.
806 @gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol
807 -ffixed-@var{reg} -fexceptions @gol
808 -fnon-call-exceptions -funwind-tables @gol
809 -fasynchronous-unwind-tables @gol
810 -finhibit-size-directive -finstrument-functions @gol
811 -fno-common -fno-ident @gol
812 -fpcc-struct-return -fpic -fPIC -fpie -fPIE @gol
813 -fno-jump-tables @gol
814 -frecord-gcc-switches @gol
815 -freg-struct-return -fshort-enums @gol
816 -fshort-double -fshort-wchar @gol
817 -fverbose-asm -fpack-struct[=@var{n}] -fstack-check @gol
818 -fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
819 -fargument-alias -fargument-noalias @gol
820 -fargument-noalias-global -fargument-noalias-anything
821 -fleading-underscore -ftls-model=@var{model} @gol
822 -ftrapv -fwrapv -fbounds-check @gol
827 * Overall Options:: Controlling the kind of output:
828 an executable, object files, assembler files,
829 or preprocessed source.
830 * C Dialect Options:: Controlling the variant of C language compiled.
831 * C++ Dialect Options:: Variations on C++.
832 * Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
834 * Language Independent Options:: Controlling how diagnostics should be
836 * Warning Options:: How picky should the compiler be?
837 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
838 * Optimize Options:: How much optimization?
839 * Preprocessor Options:: Controlling header files and macro definitions.
840 Also, getting dependency information for Make.
841 * Assembler Options:: Passing options to the assembler.
842 * Link Options:: Specifying libraries and so on.
843 * Directory Options:: Where to find header files and libraries.
844 Where to find the compiler executable files.
845 * Spec Files:: How to pass switches to sub-processes.
846 * Target Options:: Running a cross-compiler, or an old version of GCC.
849 @node Overall Options
850 @section Options Controlling the Kind of Output
852 Compilation can involve up to four stages: preprocessing, compilation
853 proper, assembly and linking, always in that order. GCC is capable of
854 preprocessing and compiling several files either into several
855 assembler input files, or into one assembler input file; then each
856 assembler input file produces an object file, and linking combines all
857 the object files (those newly compiled, and those specified as input)
858 into an executable file.
860 @cindex file name suffix
861 For any given input file, the file name suffix determines what kind of
866 C source code which must be preprocessed.
869 C source code which should not be preprocessed.
872 C++ source code which should not be preprocessed.
875 Objective-C source code. Note that you must link with the @file{libobjc}
876 library to make an Objective-C program work.
879 Objective-C source code which should not be preprocessed.
883 Objective-C++ source code. Note that you must link with the @file{libobjc}
884 library to make an Objective-C++ program work. Note that @samp{.M} refers
885 to a literal capital M@.
888 Objective-C++ source code which should not be preprocessed.
891 C, C++, Objective-C or Objective-C++ header file to be turned into a
896 @itemx @var{file}.cxx
897 @itemx @var{file}.cpp
898 @itemx @var{file}.CPP
899 @itemx @var{file}.c++
901 C++ source code which must be preprocessed. Note that in @samp{.cxx},
902 the last two letters must both be literally @samp{x}. Likewise,
903 @samp{.C} refers to a literal capital C@.
907 Objective-C++ source code which must be preprocessed.
910 Objective-C++ source code which should not be preprocessed.
914 C++ header file to be turned into a precompiled header.
917 @itemx @var{file}.for
918 @itemx @var{file}.FOR
919 Fixed form Fortran source code which should not be preprocessed.
922 @itemx @var{file}.fpp
923 @itemx @var{file}.FPP
924 Fixed form Fortran source code which must be preprocessed (with the traditional
928 @itemx @var{file}.f95
929 Free form Fortran source code which should not be preprocessed.
932 @itemx @var{file}.F95
933 Free form Fortran source code which must be preprocessed (with the
934 traditional preprocessor).
936 @c FIXME: Descriptions of Java file types.
943 Ada source code file which contains a library unit declaration (a
944 declaration of a package, subprogram, or generic, or a generic
945 instantiation), or a library unit renaming declaration (a package,
946 generic, or subprogram renaming declaration). Such files are also
949 @itemx @var{file}.adb
950 Ada source code file containing a library unit body (a subprogram or
951 package body). Such files are also called @dfn{bodies}.
953 @c GCC also knows about some suffixes for languages not yet included:
964 Assembler code which must be preprocessed.
967 An object file to be fed straight into linking.
968 Any file name with no recognized suffix is treated this way.
972 You can specify the input language explicitly with the @option{-x} option:
975 @item -x @var{language}
976 Specify explicitly the @var{language} for the following input files
977 (rather than letting the compiler choose a default based on the file
978 name suffix). This option applies to all following input files until
979 the next @option{-x} option. Possible values for @var{language} are:
981 c c-header c-cpp-output
982 c++ c++-header c++-cpp-output
983 objective-c objective-c-header objective-c-cpp-output
984 objective-c++ objective-c++-header objective-c++-cpp-output
985 assembler assembler-with-cpp
993 Turn off any specification of a language, so that subsequent files are
994 handled according to their file name suffixes (as they are if @option{-x}
995 has not been used at all).
997 @item -pass-exit-codes
998 @opindex pass-exit-codes
999 Normally the @command{gcc} program will exit with the code of 1 if any
1000 phase of the compiler returns a non-success return code. If you specify
1001 @option{-pass-exit-codes}, the @command{gcc} program will instead return with
1002 numerically highest error produced by any phase that returned an error
1003 indication. The C, C++, and Fortran frontends return 4, if an internal
1004 compiler error is encountered.
1007 If you only want some of the stages of compilation, you can use
1008 @option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
1009 one of the options @option{-c}, @option{-S}, or @option{-E} to say where
1010 @command{gcc} is to stop. Note that some combinations (for example,
1011 @samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
1016 Compile or assemble the source files, but do not link. The linking
1017 stage simply is not done. The ultimate output is in the form of an
1018 object file for each source file.
1020 By default, the object file name for a source file is made by replacing
1021 the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
1023 Unrecognized input files, not requiring compilation or assembly, are
1028 Stop after the stage of compilation proper; do not assemble. The output
1029 is in the form of an assembler code file for each non-assembler input
1032 By default, the assembler file name for a source file is made by
1033 replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
1035 Input files that don't require compilation are ignored.
1039 Stop after the preprocessing stage; do not run the compiler proper. The
1040 output is in the form of preprocessed source code, which is sent to the
1043 Input files which don't require preprocessing are ignored.
1045 @cindex output file option
1048 Place output in file @var{file}. This applies regardless to whatever
1049 sort of output is being produced, whether it be an executable file,
1050 an object file, an assembler file or preprocessed C code.
1052 If @option{-o} is not specified, the default is to put an executable
1053 file in @file{a.out}, the object file for
1054 @file{@var{source}.@var{suffix}} in @file{@var{source}.o}, its
1055 assembler file in @file{@var{source}.s}, a precompiled header file in
1056 @file{@var{source}.@var{suffix}.gch}, and all preprocessed C source on
1061 Print (on standard error output) the commands executed to run the stages
1062 of compilation. Also print the version number of the compiler driver
1063 program and of the preprocessor and the compiler proper.
1067 Like @option{-v} except the commands are not executed and all command
1068 arguments are quoted. This is useful for shell scripts to capture the
1069 driver-generated command lines.
1073 Use pipes rather than temporary files for communication between the
1074 various stages of compilation. This fails to work on some systems where
1075 the assembler is unable to read from a pipe; but the GNU assembler has
1080 If you are compiling multiple source files, this option tells the driver
1081 to pass all the source files to the compiler at once (for those
1082 languages for which the compiler can handle this). This will allow
1083 intermodule analysis (IMA) to be performed by the compiler. Currently the only
1084 language for which this is supported is C@. If you pass source files for
1085 multiple languages to the driver, using this option, the driver will invoke
1086 the compiler(s) that support IMA once each, passing each compiler all the
1087 source files appropriate for it. For those languages that do not support
1088 IMA this option will be ignored, and the compiler will be invoked once for
1089 each source file in that language. If you use this option in conjunction
1090 with @option{-save-temps}, the compiler will generate multiple
1092 (one for each source file), but only one (combined) @file{.o} or
1097 Print (on the standard output) a description of the command line options
1098 understood by @command{gcc}. If the @option{-v} option is also specified
1099 then @option{--help} will also be passed on to the various processes
1100 invoked by @command{gcc}, so that they can display the command line options
1101 they accept. If the @option{-Wextra} option has also been specified
1102 (prior to the @option{--help} option), then command line options which
1103 have no documentation associated with them will also be displayed.
1106 @opindex target-help
1107 Print (on the standard output) a description of target-specific command
1108 line options for each tool.
1110 @item --help=@var{class}@r{[},@var{qualifier}@r{]}
1111 Print (on the standard output) a description of the command line
1112 options understood by the compiler that fit into a specific class.
1113 The class can be one of @samp{optimizers}, @samp{warnings}, @samp{target},
1114 @samp{params}, or @var{language}:
1117 @item @samp{optimizers}
1118 This will display all of the optimization options supported by the
1121 @item @samp{warnings}
1122 This will display all of the options controlling warning messages
1123 produced by the compiler.
1126 This will display target-specific options. Unlike the
1127 @option{--target-help} option however, target-specific options of the
1128 linker and assembler will not be displayed. This is because those
1129 tools do not currently support the extended @option{--help=} syntax.
1132 This will display the values recognized by the @option{--param}
1135 @item @var{language}
1136 This will display the options supported for @var{language}, where
1137 @var{language} is the name of one of the languages supported in this
1141 This will display the options that are common to all languages.
1144 It is possible to further refine the output of the @option{--help=}
1145 option by adding a comma separated list of qualifiers after the
1146 class. These can be any from the following list:
1149 @item @samp{undocumented}
1150 Display only those options which are undocumented.
1153 Display options which take an argument that appears after an equal
1154 sign in the same continuous piece of text, such as:
1155 @samp{--help=target}.
1157 @item @samp{separate}
1158 Display options which take an argument that appears as a separate word
1159 following the original option, such as: @samp{-o output-file}.
1162 Thus for example to display all the undocumented target-specific
1163 switches supported by the compiler the following can be used:
1166 --help=target,undocumented
1169 The sense of a qualifier can be inverted by prefixing it with the
1170 @var{^} character, so for example to display all binary warning
1171 options (i.e. ones that are either on or off and that do not take an
1172 argument), which have a description the following can be used:
1175 --help=warnings,^joined,^undocumented
1178 A class can also be used as a qualifier, although this usually
1179 restricts the output by so much that there is nothing to display. One
1180 case where it does work however is when one of the classes is
1181 @var{target}. So for example to display all the target-specific
1182 optimization options the following can be used:
1185 --help=target,optimizers
1188 The @option{--help=} option can be repeated on the command line. Each
1189 successive use will display its requested class of options, skipping
1190 those that have already been displayed.
1192 If the @option{-Q} option appears on the command line before the
1193 @option{--help=} option, then the descriptive text displayed by
1194 @option{--help=} is changed. Instead of describing the displayed
1195 options, an indication is given as to whether the option is enabled,
1196 disabled or set to a specific value (assuming that the compiler
1197 knows this at the point where the @option{--help=} option is used).
1199 Here is a truncated example from the ARM port of @command{gcc}:
1202 % gcc -Q -mabi=2 --help=target -c
1203 The following options are target specific:
1205 -mabort-on-noreturn [disabled]
1209 The output is sensitive to the effects of previous command line
1210 options, so for example it is possible to find out which optimizations
1211 are enabled at @option{-O2} by using:
1214 -O2 --help=optimizers
1217 Alternatively you can discover which binary optimizations are enabled
1218 by @option{-O3} by using:
1221 gcc -c -Q -O3 --help=optimizers > /tmp/O3-opts
1222 gcc -c -Q -O2 --help=optimizers > /tmp/O2-opts
1223 diff /tmp/O2-opts /tmp/O3-opts | grep enabled
1228 Display the version number and copyrights of the invoked GCC@.
1230 @include @value{srcdir}/../libiberty/at-file.texi
1234 @section Compiling C++ Programs
1236 @cindex suffixes for C++ source
1237 @cindex C++ source file suffixes
1238 C++ source files conventionally use one of the suffixes @samp{.C},
1239 @samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or
1240 @samp{.cxx}; C++ header files often use @samp{.hh} or @samp{.H}; and
1241 preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes
1242 files with these names and compiles them as C++ programs even if you
1243 call the compiler the same way as for compiling C programs (usually
1244 with the name @command{gcc}).
1248 However, the use of @command{gcc} does not add the C++ library.
1249 @command{g++} is a program that calls GCC and treats @samp{.c},
1250 @samp{.h} and @samp{.i} files as C++ source files instead of C source
1251 files unless @option{-x} is used, and automatically specifies linking
1252 against the C++ library. This program is also useful when
1253 precompiling a C header file with a @samp{.h} extension for use in C++
1254 compilations. On many systems, @command{g++} is also installed with
1255 the name @command{c++}.
1257 @cindex invoking @command{g++}
1258 When you compile C++ programs, you may specify many of the same
1259 command-line options that you use for compiling programs in any
1260 language; or command-line options meaningful for C and related
1261 languages; or options that are meaningful only for C++ programs.
1262 @xref{C Dialect Options,,Options Controlling C Dialect}, for
1263 explanations of options for languages related to C@.
1264 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
1265 explanations of options that are meaningful only for C++ programs.
1267 @node C Dialect Options
1268 @section Options Controlling C Dialect
1269 @cindex dialect options
1270 @cindex language dialect options
1271 @cindex options, dialect
1273 The following options control the dialect of C (or languages derived
1274 from C, such as C++, Objective-C and Objective-C++) that the compiler
1278 @cindex ANSI support
1282 In C mode, support all ISO C90 programs. In C++ mode,
1283 remove GNU extensions that conflict with ISO C++.
1285 This turns off certain features of GCC that are incompatible with ISO
1286 C90 (when compiling C code), or of standard C++ (when compiling C++ code),
1287 such as the @code{asm} and @code{typeof} keywords, and
1288 predefined macros such as @code{unix} and @code{vax} that identify the
1289 type of system you are using. It also enables the undesirable and
1290 rarely used ISO trigraph feature. For the C compiler,
1291 it disables recognition of C++ style @samp{//} comments as well as
1292 the @code{inline} keyword.
1294 The alternate keywords @code{__asm__}, @code{__extension__},
1295 @code{__inline__} and @code{__typeof__} continue to work despite
1296 @option{-ansi}. You would not want to use them in an ISO C program, of
1297 course, but it is useful to put them in header files that might be included
1298 in compilations done with @option{-ansi}. Alternate predefined macros
1299 such as @code{__unix__} and @code{__vax__} are also available, with or
1300 without @option{-ansi}.
1302 The @option{-ansi} option does not cause non-ISO programs to be
1303 rejected gratuitously. For that, @option{-pedantic} is required in
1304 addition to @option{-ansi}. @xref{Warning Options}.
1306 The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
1307 option is used. Some header files may notice this macro and refrain
1308 from declaring certain functions or defining certain macros that the
1309 ISO standard doesn't call for; this is to avoid interfering with any
1310 programs that might use these names for other things.
1312 Functions which would normally be built in but do not have semantics
1313 defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
1314 functions with @option{-ansi} is used. @xref{Other Builtins,,Other
1315 built-in functions provided by GCC}, for details of the functions
1320 Determine the language standard. This option is currently only
1321 supported when compiling C or C++. A value for this option must be
1322 provided; possible values are
1327 ISO C90 (same as @option{-ansi}).
1329 @item iso9899:199409
1330 ISO C90 as modified in amendment 1.
1336 ISO C99. Note that this standard is not yet fully supported; see
1337 @w{@uref{http://gcc.gnu.org/c99status.html}} for more information. The
1338 names @samp{c9x} and @samp{iso9899:199x} are deprecated.
1341 Default, ISO C90 plus GNU extensions (including some C99 features).
1345 ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC,
1346 this will become the default. The name @samp{gnu9x} is deprecated.
1349 The 1998 ISO C++ standard plus amendments.
1352 The same as @option{-std=c++98} plus GNU extensions. This is the
1353 default for C++ code.
1356 The working draft of the upcoming ISO C++0x standard. This option
1357 enables experimental features that are likely to be included in
1358 C++0x. The working draft is constantly changing, and any feature that is
1359 enabled by this flag may be removed from future versions of GCC if it is
1360 not part of the C++0x standard.
1363 The same as @option{-std=c++0x} plus GNU extensions. As with
1364 @option{-std=c++0x}, this option enables experimental features that may
1365 be removed in future versions of GCC.
1368 Even when this option is not specified, you can still use some of the
1369 features of newer standards in so far as they do not conflict with
1370 previous C standards. For example, you may use @code{__restrict__} even
1371 when @option{-std=c99} is not specified.
1373 The @option{-std} options specifying some version of ISO C have the same
1374 effects as @option{-ansi}, except that features that were not in ISO C90
1375 but are in the specified version (for example, @samp{//} comments and
1376 the @code{inline} keyword in ISO C99) are not disabled.
1378 @xref{Standards,,Language Standards Supported by GCC}, for details of
1379 these standard versions.
1381 @item -fgnu89-inline
1382 @opindex fgnu89-inline
1383 The option @option{-fgnu89-inline} tells GCC to use the traditional
1384 GNU semantics for @code{inline} functions when in C99 mode.
1385 @xref{Inline,,An Inline Function is As Fast As a Macro}. This option
1386 is accepted and ignored by GCC versions 4.1.3 up to but not including
1387 4.3. In GCC versions 4.3 and later it changes the behavior of GCC in
1388 C99 mode. Using this option is roughly equivalent to adding the
1389 @code{gnu_inline} function attribute to all inline functions
1390 (@pxref{Function Attributes}).
1392 The option @option{-fno-gnu89-inline} explicitly tells GCC to use the
1393 C99 semantics for @code{inline} when in C99 or gnu99 mode (i.e., it
1394 specifies the default behavior). This option was first supported in
1395 GCC 4.3. This option is not supported in C89 or gnu89 mode.
1397 The preprocessor macros @code{__GNUC_GNU_INLINE__} and
1398 @code{__GNUC_STDC_INLINE__} may be used to check which semantics are
1399 in effect for @code{inline} functions. @xref{Common Predefined
1400 Macros,,,cpp,The C Preprocessor}.
1402 @item -aux-info @var{filename}
1404 Output to the given filename prototyped declarations for all functions
1405 declared and/or defined in a translation unit, including those in header
1406 files. This option is silently ignored in any language other than C@.
1408 Besides declarations, the file indicates, in comments, the origin of
1409 each declaration (source file and line), whether the declaration was
1410 implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
1411 @samp{O} for old, respectively, in the first character after the line
1412 number and the colon), and whether it came from a declaration or a
1413 definition (@samp{C} or @samp{F}, respectively, in the following
1414 character). In the case of function definitions, a K&R-style list of
1415 arguments followed by their declarations is also provided, inside
1416 comments, after the declaration.
1420 Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1421 keyword, so that code can use these words as identifiers. You can use
1422 the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
1423 instead. @option{-ansi} implies @option{-fno-asm}.
1425 In C++, this switch only affects the @code{typeof} keyword, since
1426 @code{asm} and @code{inline} are standard keywords. You may want to
1427 use the @option{-fno-gnu-keywords} flag instead, which has the same
1428 effect. In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
1429 switch only affects the @code{asm} and @code{typeof} keywords, since
1430 @code{inline} is a standard keyword in ISO C99.
1433 @itemx -fno-builtin-@var{function}
1434 @opindex fno-builtin
1435 @cindex built-in functions
1436 Don't recognize built-in functions that do not begin with
1437 @samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in
1438 functions provided by GCC}, for details of the functions affected,
1439 including those which are not built-in functions when @option{-ansi} or
1440 @option{-std} options for strict ISO C conformance are used because they
1441 do not have an ISO standard meaning.
1443 GCC normally generates special code to handle certain built-in functions
1444 more efficiently; for instance, calls to @code{alloca} may become single
1445 instructions that adjust the stack directly, and calls to @code{memcpy}
1446 may become inline copy loops. The resulting code is often both smaller
1447 and faster, but since the function calls no longer appear as such, you
1448 cannot set a breakpoint on those calls, nor can you change the behavior
1449 of the functions by linking with a different library. In addition,
1450 when a function is recognized as a built-in function, GCC may use
1451 information about that function to warn about problems with calls to
1452 that function, or to generate more efficient code, even if the
1453 resulting code still contains calls to that function. For example,
1454 warnings are given with @option{-Wformat} for bad calls to
1455 @code{printf}, when @code{printf} is built in, and @code{strlen} is
1456 known not to modify global memory.
1458 With the @option{-fno-builtin-@var{function}} option
1459 only the built-in function @var{function} is
1460 disabled. @var{function} must not begin with @samp{__builtin_}. If a
1461 function is named this is not built-in in this version of GCC, this
1462 option is ignored. There is no corresponding
1463 @option{-fbuiltin-@var{function}} option; if you wish to enable
1464 built-in functions selectively when using @option{-fno-builtin} or
1465 @option{-ffreestanding}, you may define macros such as:
1468 #define abs(n) __builtin_abs ((n))
1469 #define strcpy(d, s) __builtin_strcpy ((d), (s))
1474 @cindex hosted environment
1476 Assert that compilation takes place in a hosted environment. This implies
1477 @option{-fbuiltin}. A hosted environment is one in which the
1478 entire standard library is available, and in which @code{main} has a return
1479 type of @code{int}. Examples are nearly everything except a kernel.
1480 This is equivalent to @option{-fno-freestanding}.
1482 @item -ffreestanding
1483 @opindex ffreestanding
1484 @cindex hosted environment
1486 Assert that compilation takes place in a freestanding environment. This
1487 implies @option{-fno-builtin}. A freestanding environment
1488 is one in which the standard library may not exist, and program startup may
1489 not necessarily be at @code{main}. The most obvious example is an OS kernel.
1490 This is equivalent to @option{-fno-hosted}.
1492 @xref{Standards,,Language Standards Supported by GCC}, for details of
1493 freestanding and hosted environments.
1497 @cindex openmp parallel
1498 Enable handling of OpenMP directives @code{#pragma omp} in C/C++ and
1499 @code{!$omp} in Fortran. When @option{-fopenmp} is specified, the
1500 compiler generates parallel code according to the OpenMP Application
1501 Program Interface v2.5 @w{@uref{http://www.openmp.org/}}.
1503 @item -fms-extensions
1504 @opindex fms-extensions
1505 Accept some non-standard constructs used in Microsoft header files.
1507 Some cases of unnamed fields in structures and unions are only
1508 accepted with this option. @xref{Unnamed Fields,,Unnamed struct/union
1509 fields within structs/unions}, for details.
1513 Support ISO C trigraphs. The @option{-ansi} option (and @option{-std}
1514 options for strict ISO C conformance) implies @option{-trigraphs}.
1516 @item -no-integrated-cpp
1517 @opindex no-integrated-cpp
1518 Performs a compilation in two passes: preprocessing and compiling. This
1519 option allows a user supplied "cc1", "cc1plus", or "cc1obj" via the
1520 @option{-B} option. The user supplied compilation step can then add in
1521 an additional preprocessing step after normal preprocessing but before
1522 compiling. The default is to use the integrated cpp (internal cpp)
1524 The semantics of this option will change if "cc1", "cc1plus", and
1525 "cc1obj" are merged.
1527 @cindex traditional C language
1528 @cindex C language, traditional
1530 @itemx -traditional-cpp
1531 @opindex traditional-cpp
1532 @opindex traditional
1533 Formerly, these options caused GCC to attempt to emulate a pre-standard
1534 C compiler. They are now only supported with the @option{-E} switch.
1535 The preprocessor continues to support a pre-standard mode. See the GNU
1536 CPP manual for details.
1538 @item -fcond-mismatch
1539 @opindex fcond-mismatch
1540 Allow conditional expressions with mismatched types in the second and
1541 third arguments. The value of such an expression is void. This option
1542 is not supported for C++.
1544 @item -flax-vector-conversions
1545 @opindex flax-vector-conversions
1546 Allow implicit conversions between vectors with differing numbers of
1547 elements and/or incompatible element types. This option should not be
1550 @item -funsigned-char
1551 @opindex funsigned-char
1552 Let the type @code{char} be unsigned, like @code{unsigned char}.
1554 Each kind of machine has a default for what @code{char} should
1555 be. It is either like @code{unsigned char} by default or like
1556 @code{signed char} by default.
1558 Ideally, a portable program should always use @code{signed char} or
1559 @code{unsigned char} when it depends on the signedness of an object.
1560 But many programs have been written to use plain @code{char} and
1561 expect it to be signed, or expect it to be unsigned, depending on the
1562 machines they were written for. This option, and its inverse, let you
1563 make such a program work with the opposite default.
1565 The type @code{char} is always a distinct type from each of
1566 @code{signed char} or @code{unsigned char}, even though its behavior
1567 is always just like one of those two.
1570 @opindex fsigned-char
1571 Let the type @code{char} be signed, like @code{signed char}.
1573 Note that this is equivalent to @option{-fno-unsigned-char}, which is
1574 the negative form of @option{-funsigned-char}. Likewise, the option
1575 @option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
1577 @item -fsigned-bitfields
1578 @itemx -funsigned-bitfields
1579 @itemx -fno-signed-bitfields
1580 @itemx -fno-unsigned-bitfields
1581 @opindex fsigned-bitfields
1582 @opindex funsigned-bitfields
1583 @opindex fno-signed-bitfields
1584 @opindex fno-unsigned-bitfields
1585 These options control whether a bit-field is signed or unsigned, when the
1586 declaration does not use either @code{signed} or @code{unsigned}. By
1587 default, such a bit-field is signed, because this is consistent: the
1588 basic integer types such as @code{int} are signed types.
1591 @node C++ Dialect Options
1592 @section Options Controlling C++ Dialect
1594 @cindex compiler options, C++
1595 @cindex C++ options, command line
1596 @cindex options, C++
1597 This section describes the command-line options that are only meaningful
1598 for C++ programs; but you can also use most of the GNU compiler options
1599 regardless of what language your program is in. For example, you
1600 might compile a file @code{firstClass.C} like this:
1603 g++ -g -frepo -O -c firstClass.C
1607 In this example, only @option{-frepo} is an option meant
1608 only for C++ programs; you can use the other options with any
1609 language supported by GCC@.
1611 Here is a list of options that are @emph{only} for compiling C++ programs:
1615 @item -fabi-version=@var{n}
1616 @opindex fabi-version
1617 Use version @var{n} of the C++ ABI@. Version 2 is the version of the
1618 C++ ABI that first appeared in G++ 3.4. Version 1 is the version of
1619 the C++ ABI that first appeared in G++ 3.2. Version 0 will always be
1620 the version that conforms most closely to the C++ ABI specification.
1621 Therefore, the ABI obtained using version 0 will change as ABI bugs
1624 The default is version 2.
1626 @item -fno-access-control
1627 @opindex fno-access-control
1628 Turn off all access checking. This switch is mainly useful for working
1629 around bugs in the access control code.
1633 Check that the pointer returned by @code{operator new} is non-null
1634 before attempting to modify the storage allocated. This check is
1635 normally unnecessary because the C++ standard specifies that
1636 @code{operator new} will only return @code{0} if it is declared
1637 @samp{throw()}, in which case the compiler will always check the
1638 return value even without this option. In all other cases, when
1639 @code{operator new} has a non-empty exception specification, memory
1640 exhaustion is signalled by throwing @code{std::bad_alloc}. See also
1641 @samp{new (nothrow)}.
1643 @item -fconserve-space
1644 @opindex fconserve-space
1645 Put uninitialized or runtime-initialized global variables into the
1646 common segment, as C does. This saves space in the executable at the
1647 cost of not diagnosing duplicate definitions. If you compile with this
1648 flag and your program mysteriously crashes after @code{main()} has
1649 completed, you may have an object that is being destroyed twice because
1650 two definitions were merged.
1652 This option is no longer useful on most targets, now that support has
1653 been added for putting variables into BSS without making them common.
1655 @item -ffriend-injection
1656 @opindex ffriend-injection
1657 Inject friend functions into the enclosing namespace, so that they are
1658 visible outside the scope of the class in which they are declared.
1659 Friend functions were documented to work this way in the old Annotated
1660 C++ Reference Manual, and versions of G++ before 4.1 always worked
1661 that way. However, in ISO C++ a friend function which is not declared
1662 in an enclosing scope can only be found using argument dependent
1663 lookup. This option causes friends to be injected as they were in
1666 This option is for compatibility, and may be removed in a future
1669 @item -fno-elide-constructors
1670 @opindex fno-elide-constructors
1671 The C++ standard allows an implementation to omit creating a temporary
1672 which is only used to initialize another object of the same type.
1673 Specifying this option disables that optimization, and forces G++ to
1674 call the copy constructor in all cases.
1676 @item -fno-enforce-eh-specs
1677 @opindex fno-enforce-eh-specs
1678 Don't generate code to check for violation of exception specifications
1679 at runtime. This option violates the C++ standard, but may be useful
1680 for reducing code size in production builds, much like defining
1681 @samp{NDEBUG}. This does not give user code permission to throw
1682 exceptions in violation of the exception specifications; the compiler
1683 will still optimize based on the specifications, so throwing an
1684 unexpected exception will result in undefined behavior.
1687 @itemx -fno-for-scope
1689 @opindex fno-for-scope
1690 If @option{-ffor-scope} is specified, the scope of variables declared in
1691 a @i{for-init-statement} is limited to the @samp{for} loop itself,
1692 as specified by the C++ standard.
1693 If @option{-fno-for-scope} is specified, the scope of variables declared in
1694 a @i{for-init-statement} extends to the end of the enclosing scope,
1695 as was the case in old versions of G++, and other (traditional)
1696 implementations of C++.
1698 The default if neither flag is given to follow the standard,
1699 but to allow and give a warning for old-style code that would
1700 otherwise be invalid, or have different behavior.
1702 @item -fno-gnu-keywords
1703 @opindex fno-gnu-keywords
1704 Do not recognize @code{typeof} as a keyword, so that code can use this
1705 word as an identifier. You can use the keyword @code{__typeof__} instead.
1706 @option{-ansi} implies @option{-fno-gnu-keywords}.
1708 @item -fno-implicit-templates
1709 @opindex fno-implicit-templates
1710 Never emit code for non-inline templates which are instantiated
1711 implicitly (i.e.@: by use); only emit code for explicit instantiations.
1712 @xref{Template Instantiation}, for more information.
1714 @item -fno-implicit-inline-templates
1715 @opindex fno-implicit-inline-templates
1716 Don't emit code for implicit instantiations of inline templates, either.
1717 The default is to handle inlines differently so that compiles with and
1718 without optimization will need the same set of explicit instantiations.
1720 @item -fno-implement-inlines
1721 @opindex fno-implement-inlines
1722 To save space, do not emit out-of-line copies of inline functions
1723 controlled by @samp{#pragma implementation}. This will cause linker
1724 errors if these functions are not inlined everywhere they are called.
1726 @item -fms-extensions
1727 @opindex fms-extensions
1728 Disable pedantic warnings about constructs used in MFC, such as implicit
1729 int and getting a pointer to member function via non-standard syntax.
1731 @item -fno-nonansi-builtins
1732 @opindex fno-nonansi-builtins
1733 Disable built-in declarations of functions that are not mandated by
1734 ANSI/ISO C@. These include @code{ffs}, @code{alloca}, @code{_exit},
1735 @code{index}, @code{bzero}, @code{conjf}, and other related functions.
1737 @item -fno-operator-names
1738 @opindex fno-operator-names
1739 Do not treat the operator name keywords @code{and}, @code{bitand},
1740 @code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1741 synonyms as keywords.
1743 @item -fno-optional-diags
1744 @opindex fno-optional-diags
1745 Disable diagnostics that the standard says a compiler does not need to
1746 issue. Currently, the only such diagnostic issued by G++ is the one for
1747 a name having multiple meanings within a class.
1750 @opindex fpermissive
1751 Downgrade some diagnostics about nonconformant code from errors to
1752 warnings. Thus, using @option{-fpermissive} will allow some
1753 nonconforming code to compile.
1757 Enable automatic template instantiation at link time. This option also
1758 implies @option{-fno-implicit-templates}. @xref{Template
1759 Instantiation}, for more information.
1763 Disable generation of information about every class with virtual
1764 functions for use by the C++ runtime type identification features
1765 (@samp{dynamic_cast} and @samp{typeid}). If you don't use those parts
1766 of the language, you can save some space by using this flag. Note that
1767 exception handling uses the same information, but it will generate it as
1768 needed. The @samp{dynamic_cast} operator can still be used for casts that
1769 do not require runtime type information, i.e. casts to @code{void *} or to
1770 unambiguous base classes.
1774 Emit statistics about front-end processing at the end of the compilation.
1775 This information is generally only useful to the G++ development team.
1777 @item -ftemplate-depth-@var{n}
1778 @opindex ftemplate-depth
1779 Set the maximum instantiation depth for template classes to @var{n}.
1780 A limit on the template instantiation depth is needed to detect
1781 endless recursions during template class instantiation. ANSI/ISO C++
1782 conforming programs must not rely on a maximum depth greater than 17.
1784 @item -fno-threadsafe-statics
1785 @opindex fno-threadsafe-statics
1786 Do not emit the extra code to use the routines specified in the C++
1787 ABI for thread-safe initialization of local statics. You can use this
1788 option to reduce code size slightly in code that doesn't need to be
1791 @item -fuse-cxa-atexit
1792 @opindex fuse-cxa-atexit
1793 Register destructors for objects with static storage duration with the
1794 @code{__cxa_atexit} function rather than the @code{atexit} function.
1795 This option is required for fully standards-compliant handling of static
1796 destructors, but will only work if your C library supports
1797 @code{__cxa_atexit}.
1799 @item -fno-use-cxa-get-exception-ptr
1800 @opindex fno-use-cxa-get-exception-ptr
1801 Don't use the @code{__cxa_get_exception_ptr} runtime routine. This
1802 will cause @code{std::uncaught_exception} to be incorrect, but is necessary
1803 if the runtime routine is not available.
1805 @item -fvisibility-inlines-hidden
1806 @opindex fvisibility-inlines-hidden
1807 This switch declares that the user does not attempt to compare
1808 pointers to inline methods where the addresses of the two functions
1809 were taken in different shared objects.
1811 The effect of this is that GCC may, effectively, mark inline methods with
1812 @code{__attribute__ ((visibility ("hidden")))} so that they do not
1813 appear in the export table of a DSO and do not require a PLT indirection
1814 when used within the DSO@. Enabling this option can have a dramatic effect
1815 on load and link times of a DSO as it massively reduces the size of the
1816 dynamic export table when the library makes heavy use of templates.
1818 The behavior of this switch is not quite the same as marking the
1819 methods as hidden directly, because it does not affect static variables
1820 local to the function or cause the compiler to deduce that
1821 the function is defined in only one shared object.
1823 You may mark a method as having a visibility explicitly to negate the
1824 effect of the switch for that method. For example, if you do want to
1825 compare pointers to a particular inline method, you might mark it as
1826 having default visibility. Marking the enclosing class with explicit
1827 visibility will have no effect.
1829 Explicitly instantiated inline methods are unaffected by this option
1830 as their linkage might otherwise cross a shared library boundary.
1831 @xref{Template Instantiation}.
1835 Do not use weak symbol support, even if it is provided by the linker.
1836 By default, G++ will use weak symbols if they are available. This
1837 option exists only for testing, and should not be used by end-users;
1838 it will result in inferior code and has no benefits. This option may
1839 be removed in a future release of G++.
1843 Do not search for header files in the standard directories specific to
1844 C++, but do still search the other standard directories. (This option
1845 is used when building the C++ library.)
1848 In addition, these optimization, warning, and code generation options
1849 have meanings only for C++ programs:
1852 @item -fno-default-inline
1853 @opindex fno-default-inline
1854 Do not assume @samp{inline} for functions defined inside a class scope.
1855 @xref{Optimize Options,,Options That Control Optimization}. Note that these
1856 functions will have linkage like inline functions; they just won't be
1859 @item -Wabi @r{(C++ only)}
1861 Warn when G++ generates code that is probably not compatible with the
1862 vendor-neutral C++ ABI@. Although an effort has been made to warn about
1863 all such cases, there are probably some cases that are not warned about,
1864 even though G++ is generating incompatible code. There may also be
1865 cases where warnings are emitted even though the code that is generated
1868 You should rewrite your code to avoid these warnings if you are
1869 concerned about the fact that code generated by G++ may not be binary
1870 compatible with code generated by other compilers.
1872 The known incompatibilities at this point include:
1877 Incorrect handling of tail-padding for bit-fields. G++ may attempt to
1878 pack data into the same byte as a base class. For example:
1881 struct A @{ virtual void f(); int f1 : 1; @};
1882 struct B : public A @{ int f2 : 1; @};
1886 In this case, G++ will place @code{B::f2} into the same byte
1887 as@code{A::f1}; other compilers will not. You can avoid this problem
1888 by explicitly padding @code{A} so that its size is a multiple of the
1889 byte size on your platform; that will cause G++ and other compilers to
1890 layout @code{B} identically.
1893 Incorrect handling of tail-padding for virtual bases. G++ does not use
1894 tail padding when laying out virtual bases. For example:
1897 struct A @{ virtual void f(); char c1; @};
1898 struct B @{ B(); char c2; @};
1899 struct C : public A, public virtual B @{@};
1903 In this case, G++ will not place @code{B} into the tail-padding for
1904 @code{A}; other compilers will. You can avoid this problem by
1905 explicitly padding @code{A} so that its size is a multiple of its
1906 alignment (ignoring virtual base classes); that will cause G++ and other
1907 compilers to layout @code{C} identically.
1910 Incorrect handling of bit-fields with declared widths greater than that
1911 of their underlying types, when the bit-fields appear in a union. For
1915 union U @{ int i : 4096; @};
1919 Assuming that an @code{int} does not have 4096 bits, G++ will make the
1920 union too small by the number of bits in an @code{int}.
1923 Empty classes can be placed at incorrect offsets. For example:
1933 struct C : public B, public A @{@};
1937 G++ will place the @code{A} base class of @code{C} at a nonzero offset;
1938 it should be placed at offset zero. G++ mistakenly believes that the
1939 @code{A} data member of @code{B} is already at offset zero.
1942 Names of template functions whose types involve @code{typename} or
1943 template template parameters can be mangled incorrectly.
1946 template <typename Q>
1947 void f(typename Q::X) @{@}
1949 template <template <typename> class Q>
1950 void f(typename Q<int>::X) @{@}
1954 Instantiations of these templates may be mangled incorrectly.
1958 @item -Wctor-dtor-privacy @r{(C++ only)}
1959 @opindex Wctor-dtor-privacy
1960 Warn when a class seems unusable because all the constructors or
1961 destructors in that class are private, and it has neither friends nor
1962 public static member functions.
1964 @item -Wnon-virtual-dtor @r{(C++ only)}
1965 @opindex Wnon-virtual-dtor
1966 Warn when a class appears to be polymorphic, thereby requiring a virtual
1967 destructor, yet it declares a non-virtual one. This warning is also
1968 enabled if -Weffc++ is specified.
1970 @item -Wreorder @r{(C++ only)}
1972 @cindex reordering, warning
1973 @cindex warning for reordering of member initializers
1974 Warn when the order of member initializers given in the code does not
1975 match the order in which they must be executed. For instance:
1981 A(): j (0), i (1) @{ @}
1985 The compiler will rearrange the member initializers for @samp{i}
1986 and @samp{j} to match the declaration order of the members, emitting
1987 a warning to that effect. This warning is enabled by @option{-Wall}.
1990 The following @option{-W@dots{}} options are not affected by @option{-Wall}.
1993 @item -Weffc++ @r{(C++ only)}
1995 Warn about violations of the following style guidelines from Scott Meyers'
1996 @cite{Effective C++} book:
2000 Item 11: Define a copy constructor and an assignment operator for classes
2001 with dynamically allocated memory.
2004 Item 12: Prefer initialization to assignment in constructors.
2007 Item 14: Make destructors virtual in base classes.
2010 Item 15: Have @code{operator=} return a reference to @code{*this}.
2013 Item 23: Don't try to return a reference when you must return an object.
2017 Also warn about violations of the following style guidelines from
2018 Scott Meyers' @cite{More Effective C++} book:
2022 Item 6: Distinguish between prefix and postfix forms of increment and
2023 decrement operators.
2026 Item 7: Never overload @code{&&}, @code{||}, or @code{,}.
2030 When selecting this option, be aware that the standard library
2031 headers do not obey all of these guidelines; use @samp{grep -v}
2032 to filter out those warnings.
2034 @item -Wno-deprecated @r{(C++ only)}
2035 @opindex Wno-deprecated
2036 Do not warn about usage of deprecated features. @xref{Deprecated Features}.
2038 @item -Wstrict-null-sentinel @r{(C++ only)}
2039 @opindex Wstrict-null-sentinel
2040 Warn also about the use of an uncasted @code{NULL} as sentinel. When
2041 compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
2042 to @code{__null}. Although it is a null pointer constant not a null pointer,
2043 it is guaranteed to of the same size as a pointer. But this use is
2044 not portable across different compilers.
2046 @item -Wno-non-template-friend @r{(C++ only)}
2047 @opindex Wno-non-template-friend
2048 Disable warnings when non-templatized friend functions are declared
2049 within a template. Since the advent of explicit template specification
2050 support in G++, if the name of the friend is an unqualified-id (i.e.,
2051 @samp{friend foo(int)}), the C++ language specification demands that the
2052 friend declare or define an ordinary, nontemplate function. (Section
2053 14.5.3). Before G++ implemented explicit specification, unqualified-ids
2054 could be interpreted as a particular specialization of a templatized
2055 function. Because this non-conforming behavior is no longer the default
2056 behavior for G++, @option{-Wnon-template-friend} allows the compiler to
2057 check existing code for potential trouble spots and is on by default.
2058 This new compiler behavior can be turned off with
2059 @option{-Wno-non-template-friend} which keeps the conformant compiler code
2060 but disables the helpful warning.
2062 @item -Wold-style-cast @r{(C++ only)}
2063 @opindex Wold-style-cast
2064 Warn if an old-style (C-style) cast to a non-void type is used within
2065 a C++ program. The new-style casts (@samp{dynamic_cast},
2066 @samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are
2067 less vulnerable to unintended effects and much easier to search for.
2069 @item -Woverloaded-virtual @r{(C++ only)}
2070 @opindex Woverloaded-virtual
2071 @cindex overloaded virtual fn, warning
2072 @cindex warning for overloaded virtual fn
2073 Warn when a function declaration hides virtual functions from a
2074 base class. For example, in:
2081 struct B: public A @{
2086 the @code{A} class version of @code{f} is hidden in @code{B}, and code
2094 will fail to compile.
2096 @item -Wno-pmf-conversions @r{(C++ only)}
2097 @opindex Wno-pmf-conversions
2098 Disable the diagnostic for converting a bound pointer to member function
2101 @item -Wsign-promo @r{(C++ only)}
2102 @opindex Wsign-promo
2103 Warn when overload resolution chooses a promotion from unsigned or
2104 enumerated type to a signed type, over a conversion to an unsigned type of
2105 the same size. Previous versions of G++ would try to preserve
2106 unsignedness, but the standard mandates the current behavior.
2111 A& operator = (int);
2121 In this example, G++ will synthesize a default @samp{A& operator =
2122 (const A&);}, while cfront will use the user-defined @samp{operator =}.
2125 @node Objective-C and Objective-C++ Dialect Options
2126 @section Options Controlling Objective-C and Objective-C++ Dialects
2128 @cindex compiler options, Objective-C and Objective-C++
2129 @cindex Objective-C and Objective-C++ options, command line
2130 @cindex options, Objective-C and Objective-C++
2131 (NOTE: This manual does not describe the Objective-C and Objective-C++
2132 languages themselves. See @xref{Standards,,Language Standards
2133 Supported by GCC}, for references.)
2135 This section describes the command-line options that are only meaningful
2136 for Objective-C and Objective-C++ programs, but you can also use most of
2137 the language-independent GNU compiler options.
2138 For example, you might compile a file @code{some_class.m} like this:
2141 gcc -g -fgnu-runtime -O -c some_class.m
2145 In this example, @option{-fgnu-runtime} is an option meant only for
2146 Objective-C and Objective-C++ programs; you can use the other options with
2147 any language supported by GCC@.
2149 Note that since Objective-C is an extension of the C language, Objective-C
2150 compilations may also use options specific to the C front-end (e.g.,
2151 @option{-Wtraditional}). Similarly, Objective-C++ compilations may use
2152 C++-specific options (e.g., @option{-Wabi}).
2154 Here is a list of options that are @emph{only} for compiling Objective-C
2155 and Objective-C++ programs:
2158 @item -fconstant-string-class=@var{class-name}
2159 @opindex fconstant-string-class
2160 Use @var{class-name} as the name of the class to instantiate for each
2161 literal string specified with the syntax @code{@@"@dots{}"}. The default
2162 class name is @code{NXConstantString} if the GNU runtime is being used, and
2163 @code{NSConstantString} if the NeXT runtime is being used (see below). The
2164 @option{-fconstant-cfstrings} option, if also present, will override the
2165 @option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} literals
2166 to be laid out as constant CoreFoundation strings.
2169 @opindex fgnu-runtime
2170 Generate object code compatible with the standard GNU Objective-C
2171 runtime. This is the default for most types of systems.
2173 @item -fnext-runtime
2174 @opindex fnext-runtime
2175 Generate output compatible with the NeXT runtime. This is the default
2176 for NeXT-based systems, including Darwin and Mac OS X@. The macro
2177 @code{__NEXT_RUNTIME__} is predefined if (and only if) this option is
2180 @item -fno-nil-receivers
2181 @opindex fno-nil-receivers
2182 Assume that all Objective-C message dispatches (e.g.,
2183 @code{[receiver message:arg]}) in this translation unit ensure that the receiver
2184 is not @code{nil}. This allows for more efficient entry points in the runtime
2185 to be used. Currently, this option is only available in conjunction with
2186 the NeXT runtime on Mac OS X 10.3 and later.
2188 @item -fobjc-call-cxx-cdtors
2189 @opindex fobjc-call-cxx-cdtors
2190 For each Objective-C class, check if any of its instance variables is a
2191 C++ object with a non-trivial default constructor. If so, synthesize a
2192 special @code{- (id) .cxx_construct} instance method that will run
2193 non-trivial default constructors on any such instance variables, in order,
2194 and then return @code{self}. Similarly, check if any instance variable
2195 is a C++ object with a non-trivial destructor, and if so, synthesize a
2196 special @code{- (void) .cxx_destruct} method that will run
2197 all such default destructors, in reverse order.
2199 The @code{- (id) .cxx_construct} and/or @code{- (void) .cxx_destruct} methods
2200 thusly generated will only operate on instance variables declared in the
2201 current Objective-C class, and not those inherited from superclasses. It
2202 is the responsibility of the Objective-C runtime to invoke all such methods
2203 in an object's inheritance hierarchy. The @code{- (id) .cxx_construct} methods
2204 will be invoked by the runtime immediately after a new object
2205 instance is allocated; the @code{- (void) .cxx_destruct} methods will
2206 be invoked immediately before the runtime deallocates an object instance.
2208 As of this writing, only the NeXT runtime on Mac OS X 10.4 and later has
2209 support for invoking the @code{- (id) .cxx_construct} and
2210 @code{- (void) .cxx_destruct} methods.
2212 @item -fobjc-direct-dispatch
2213 @opindex fobjc-direct-dispatch
2214 Allow fast jumps to the message dispatcher. On Darwin this is
2215 accomplished via the comm page.
2217 @item -fobjc-exceptions
2218 @opindex fobjc-exceptions
2219 Enable syntactic support for structured exception handling in Objective-C,
2220 similar to what is offered by C++ and Java. This option is
2221 unavailable in conjunction with the NeXT runtime on Mac OS X 10.2 and
2230 @@catch (AnObjCClass *exc) @{
2237 @@catch (AnotherClass *exc) @{
2240 @@catch (id allOthers) @{
2250 The @code{@@throw} statement may appear anywhere in an Objective-C or
2251 Objective-C++ program; when used inside of a @code{@@catch} block, the
2252 @code{@@throw} may appear without an argument (as shown above), in which case
2253 the object caught by the @code{@@catch} will be rethrown.
2255 Note that only (pointers to) Objective-C objects may be thrown and
2256 caught using this scheme. When an object is thrown, it will be caught
2257 by the nearest @code{@@catch} clause capable of handling objects of that type,
2258 analogously to how @code{catch} blocks work in C++ and Java. A
2259 @code{@@catch(id @dots{})} clause (as shown above) may also be provided to catch
2260 any and all Objective-C exceptions not caught by previous @code{@@catch}
2263 The @code{@@finally} clause, if present, will be executed upon exit from the
2264 immediately preceding @code{@@try @dots{} @@catch} section. This will happen
2265 regardless of whether any exceptions are thrown, caught or rethrown
2266 inside the @code{@@try @dots{} @@catch} section, analogously to the behavior
2267 of the @code{finally} clause in Java.
2269 There are several caveats to using the new exception mechanism:
2273 Although currently designed to be binary compatible with @code{NS_HANDLER}-style
2274 idioms provided by the @code{NSException} class, the new
2275 exceptions can only be used on Mac OS X 10.3 (Panther) and later
2276 systems, due to additional functionality needed in the (NeXT) Objective-C
2280 As mentioned above, the new exceptions do not support handling
2281 types other than Objective-C objects. Furthermore, when used from
2282 Objective-C++, the Objective-C exception model does not interoperate with C++
2283 exceptions at this time. This means you cannot @code{@@throw} an exception
2284 from Objective-C and @code{catch} it in C++, or vice versa
2285 (i.e., @code{throw @dots{} @@catch}).
2288 The @option{-fobjc-exceptions} switch also enables the use of synchronization
2289 blocks for thread-safe execution:
2292 @@synchronized (ObjCClass *guard) @{
2297 Upon entering the @code{@@synchronized} block, a thread of execution shall
2298 first check whether a lock has been placed on the corresponding @code{guard}
2299 object by another thread. If it has, the current thread shall wait until
2300 the other thread relinquishes its lock. Once @code{guard} becomes available,
2301 the current thread will place its own lock on it, execute the code contained in
2302 the @code{@@synchronized} block, and finally relinquish the lock (thereby
2303 making @code{guard} available to other threads).
2305 Unlike Java, Objective-C does not allow for entire methods to be marked
2306 @code{@@synchronized}. Note that throwing exceptions out of
2307 @code{@@synchronized} blocks is allowed, and will cause the guarding object
2308 to be unlocked properly.
2312 Enable garbage collection (GC) in Objective-C and Objective-C++ programs.
2314 @item -freplace-objc-classes
2315 @opindex freplace-objc-classes
2316 Emit a special marker instructing @command{ld(1)} not to statically link in
2317 the resulting object file, and allow @command{dyld(1)} to load it in at
2318 run time instead. This is used in conjunction with the Fix-and-Continue
2319 debugging mode, where the object file in question may be recompiled and
2320 dynamically reloaded in the course of program execution, without the need
2321 to restart the program itself. Currently, Fix-and-Continue functionality
2322 is only available in conjunction with the NeXT runtime on Mac OS X 10.3
2327 When compiling for the NeXT runtime, the compiler ordinarily replaces calls
2328 to @code{objc_getClass("@dots{}")} (when the name of the class is known at
2329 compile time) with static class references that get initialized at load time,
2330 which improves run-time performance. Specifying the @option{-fzero-link} flag
2331 suppresses this behavior and causes calls to @code{objc_getClass("@dots{}")}
2332 to be retained. This is useful in Zero-Link debugging mode, since it allows
2333 for individual class implementations to be modified during program execution.
2337 Dump interface declarations for all classes seen in the source file to a
2338 file named @file{@var{sourcename}.decl}.
2340 @item -Wassign-intercept
2341 @opindex Wassign-intercept
2342 Warn whenever an Objective-C assignment is being intercepted by the
2346 @opindex Wno-protocol
2347 If a class is declared to implement a protocol, a warning is issued for
2348 every method in the protocol that is not implemented by the class. The
2349 default behavior is to issue a warning for every method not explicitly
2350 implemented in the class, even if a method implementation is inherited
2351 from the superclass. If you use the @option{-Wno-protocol} option, then
2352 methods inherited from the superclass are considered to be implemented,
2353 and no warning is issued for them.
2357 Warn if multiple methods of different types for the same selector are
2358 found during compilation. The check is performed on the list of methods
2359 in the final stage of compilation. Additionally, a check is performed
2360 for each selector appearing in a @code{@@selector(@dots{})}
2361 expression, and a corresponding method for that selector has been found
2362 during compilation. Because these checks scan the method table only at
2363 the end of compilation, these warnings are not produced if the final
2364 stage of compilation is not reached, for example because an error is
2365 found during compilation, or because the @option{-fsyntax-only} option is
2368 @item -Wstrict-selector-match
2369 @opindex Wstrict-selector-match
2370 Warn if multiple methods with differing argument and/or return types are
2371 found for a given selector when attempting to send a message using this
2372 selector to a receiver of type @code{id} or @code{Class}. When this flag
2373 is off (which is the default behavior), the compiler will omit such warnings
2374 if any differences found are confined to types which share the same size
2377 @item -Wundeclared-selector
2378 @opindex Wundeclared-selector
2379 Warn if a @code{@@selector(@dots{})} expression referring to an
2380 undeclared selector is found. A selector is considered undeclared if no
2381 method with that name has been declared before the
2382 @code{@@selector(@dots{})} expression, either explicitly in an
2383 @code{@@interface} or @code{@@protocol} declaration, or implicitly in
2384 an @code{@@implementation} section. This option always performs its
2385 checks as soon as a @code{@@selector(@dots{})} expression is found,
2386 while @option{-Wselector} only performs its checks in the final stage of
2387 compilation. This also enforces the coding style convention
2388 that methods and selectors must be declared before being used.
2390 @item -print-objc-runtime-info
2391 @opindex print-objc-runtime-info
2392 Generate C header describing the largest structure that is passed by
2397 @node Language Independent Options
2398 @section Options to Control Diagnostic Messages Formatting
2399 @cindex options to control diagnostics formatting
2400 @cindex diagnostic messages
2401 @cindex message formatting
2403 Traditionally, diagnostic messages have been formatted irrespective of
2404 the output device's aspect (e.g.@: its width, @dots{}). The options described
2405 below can be used to control the diagnostic messages formatting
2406 algorithm, e.g.@: how many characters per line, how often source location
2407 information should be reported. Right now, only the C++ front end can
2408 honor these options. However it is expected, in the near future, that
2409 the remaining front ends would be able to digest them correctly.
2412 @item -fmessage-length=@var{n}
2413 @opindex fmessage-length
2414 Try to format error messages so that they fit on lines of about @var{n}
2415 characters. The default is 72 characters for @command{g++} and 0 for the rest of
2416 the front ends supported by GCC@. If @var{n} is zero, then no
2417 line-wrapping will be done; each error message will appear on a single
2420 @opindex fdiagnostics-show-location
2421 @item -fdiagnostics-show-location=once
2422 Only meaningful in line-wrapping mode. Instructs the diagnostic messages
2423 reporter to emit @emph{once} source location information; that is, in
2424 case the message is too long to fit on a single physical line and has to
2425 be wrapped, the source location won't be emitted (as prefix) again,
2426 over and over, in subsequent continuation lines. This is the default
2429 @item -fdiagnostics-show-location=every-line
2430 Only meaningful in line-wrapping mode. Instructs the diagnostic
2431 messages reporter to emit the same source location information (as
2432 prefix) for physical lines that result from the process of breaking
2433 a message which is too long to fit on a single line.
2435 @item -fdiagnostics-show-option
2436 @opindex fdiagnostics-show-option
2437 This option instructs the diagnostic machinery to add text to each
2438 diagnostic emitted, which indicates which command line option directly
2439 controls that diagnostic, when such an option is known to the
2440 diagnostic machinery.
2442 @item -Wcoverage-mismatch
2443 @opindex Wcoverage-mismatch
2444 Warn if feedback profiles do not match when using the
2445 @option{-fprofile-use} option.
2446 If a source file was changed between @option{-fprofile-gen} and
2447 @option{-fprofile-use}, the files with the profile feedback can fail
2448 to match the source file and GCC can not use the profile feedback
2449 information. By default, GCC emits an error message in this case.
2450 The option @option{-Wcoverage-mismatch} emits a warning instead of an
2451 error. GCC does not use appropriate feedback profiles, so using this
2452 option can result in poorly optimized code. This option is useful
2453 only in the case of very minor changes such as bug fixes to an
2458 @node Warning Options
2459 @section Options to Request or Suppress Warnings
2460 @cindex options to control warnings
2461 @cindex warning messages
2462 @cindex messages, warning
2463 @cindex suppressing warnings
2465 Warnings are diagnostic messages that report constructions which
2466 are not inherently erroneous but which are risky or suggest there
2467 may have been an error.
2469 You can request many specific warnings with options beginning @samp{-W},
2470 for example @option{-Wimplicit} to request warnings on implicit
2471 declarations. Each of these specific warning options also has a
2472 negative form beginning @samp{-Wno-} to turn off warnings;
2473 for example, @option{-Wno-implicit}. This manual lists only one of the
2474 two forms, whichever is not the default.
2476 The following options control the amount and kinds of warnings produced
2477 by GCC; for further, language-specific options also refer to
2478 @ref{C++ Dialect Options} and @ref{Objective-C and Objective-C++ Dialect
2482 @cindex syntax checking
2484 @opindex fsyntax-only
2485 Check the code for syntax errors, but don't do anything beyond that.
2489 Issue all the warnings demanded by strict ISO C and ISO C++;
2490 reject all programs that use forbidden extensions, and some other
2491 programs that do not follow ISO C and ISO C++. For ISO C, follows the
2492 version of the ISO C standard specified by any @option{-std} option used.
2494 Valid ISO C and ISO C++ programs should compile properly with or without
2495 this option (though a rare few will require @option{-ansi} or a
2496 @option{-std} option specifying the required version of ISO C)@. However,
2497 without this option, certain GNU extensions and traditional C and C++
2498 features are supported as well. With this option, they are rejected.
2500 @option{-pedantic} does not cause warning messages for use of the
2501 alternate keywords whose names begin and end with @samp{__}. Pedantic
2502 warnings are also disabled in the expression that follows
2503 @code{__extension__}. However, only system header files should use
2504 these escape routes; application programs should avoid them.
2505 @xref{Alternate Keywords}.
2507 Some users try to use @option{-pedantic} to check programs for strict ISO
2508 C conformance. They soon find that it does not do quite what they want:
2509 it finds some non-ISO practices, but not all---only those for which
2510 ISO C @emph{requires} a diagnostic, and some others for which
2511 diagnostics have been added.
2513 A feature to report any failure to conform to ISO C might be useful in
2514 some instances, but would require considerable additional work and would
2515 be quite different from @option{-pedantic}. We don't have plans to
2516 support such a feature in the near future.
2518 Where the standard specified with @option{-std} represents a GNU
2519 extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
2520 corresponding @dfn{base standard}, the version of ISO C on which the GNU
2521 extended dialect is based. Warnings from @option{-pedantic} are given
2522 where they are required by the base standard. (It would not make sense
2523 for such warnings to be given only for features not in the specified GNU
2524 C dialect, since by definition the GNU dialects of C include all
2525 features the compiler supports with the given option, and there would be
2526 nothing to warn about.)
2528 @item -pedantic-errors
2529 @opindex pedantic-errors
2530 Like @option{-pedantic}, except that errors are produced rather than
2535 Inhibit all warning messages.
2539 Inhibit warning messages about the use of @samp{#import}.
2541 @item -Wchar-subscripts
2542 @opindex Wchar-subscripts
2543 Warn if an array subscript has type @code{char}. This is a common cause
2544 of error, as programmers often forget that this type is signed on some
2546 This warning is enabled by @option{-Wall}.
2550 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
2551 comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
2552 This warning is enabled by @option{-Wall}.
2554 @item -Wfatal-errors
2555 @opindex Wfatal-errors
2556 This option causes the compiler to abort compilation on the first error
2557 occurred rather than trying to keep going and printing further error
2562 @opindex ffreestanding
2563 @opindex fno-builtin
2564 Check calls to @code{printf} and @code{scanf}, etc., to make sure that
2565 the arguments supplied have types appropriate to the format string
2566 specified, and that the conversions specified in the format string make
2567 sense. This includes standard functions, and others specified by format
2568 attributes (@pxref{Function Attributes}), in the @code{printf},
2569 @code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
2570 not in the C standard) families (or other target-specific families).
2571 Which functions are checked without format attributes having been
2572 specified depends on the standard version selected, and such checks of
2573 functions without the attribute specified are disabled by
2574 @option{-ffreestanding} or @option{-fno-builtin}.
2576 The formats are checked against the format features supported by GNU
2577 libc version 2.2. These include all ISO C90 and C99 features, as well
2578 as features from the Single Unix Specification and some BSD and GNU
2579 extensions. Other library implementations may not support all these
2580 features; GCC does not support warning about features that go beyond a
2581 particular library's limitations. However, if @option{-pedantic} is used
2582 with @option{-Wformat}, warnings will be given about format features not
2583 in the selected standard version (but not for @code{strfmon} formats,
2584 since those are not in any version of the C standard). @xref{C Dialect
2585 Options,,Options Controlling C Dialect}.
2587 Since @option{-Wformat} also checks for null format arguments for
2588 several functions, @option{-Wformat} also implies @option{-Wnonnull}.
2590 @option{-Wformat} is included in @option{-Wall}. For more control over some
2591 aspects of format checking, the options @option{-Wformat-y2k},
2592 @option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
2593 @option{-Wformat-nonliteral}, @option{-Wformat-security}, and
2594 @option{-Wformat=2} are available, but are not included in @option{-Wall}.
2597 @opindex Wformat-y2k
2598 If @option{-Wformat} is specified, also warn about @code{strftime}
2599 formats which may yield only a two-digit year.
2601 @item -Wno-format-extra-args
2602 @opindex Wno-format-extra-args
2603 If @option{-Wformat} is specified, do not warn about excess arguments to a
2604 @code{printf} or @code{scanf} format function. The C standard specifies
2605 that such arguments are ignored.
2607 Where the unused arguments lie between used arguments that are
2608 specified with @samp{$} operand number specifications, normally
2609 warnings are still given, since the implementation could not know what
2610 type to pass to @code{va_arg} to skip the unused arguments. However,
2611 in the case of @code{scanf} formats, this option will suppress the
2612 warning if the unused arguments are all pointers, since the Single
2613 Unix Specification says that such unused arguments are allowed.
2615 @item -Wno-format-zero-length
2616 @opindex Wno-format-zero-length
2617 If @option{-Wformat} is specified, do not warn about zero-length formats.
2618 The C standard specifies that zero-length formats are allowed.
2620 @item -Wformat-nonliteral
2621 @opindex Wformat-nonliteral
2622 If @option{-Wformat} is specified, also warn if the format string is not a
2623 string literal and so cannot be checked, unless the format function
2624 takes its format arguments as a @code{va_list}.
2626 @item -Wformat-security
2627 @opindex Wformat-security
2628 If @option{-Wformat} is specified, also warn about uses of format
2629 functions that represent possible security problems. At present, this
2630 warns about calls to @code{printf} and @code{scanf} functions where the
2631 format string is not a string literal and there are no format arguments,
2632 as in @code{printf (foo);}. This may be a security hole if the format
2633 string came from untrusted input and contains @samp{%n}. (This is
2634 currently a subset of what @option{-Wformat-nonliteral} warns about, but
2635 in future warnings may be added to @option{-Wformat-security} that are not
2636 included in @option{-Wformat-nonliteral}.)
2640 Enable @option{-Wformat} plus format checks not included in
2641 @option{-Wformat}. Currently equivalent to @samp{-Wformat
2642 -Wformat-nonliteral -Wformat-security -Wformat-y2k}.
2646 Warn about passing a null pointer for arguments marked as
2647 requiring a non-null value by the @code{nonnull} function attribute.
2649 @option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It
2650 can be disabled with the @option{-Wno-nonnull} option.
2652 @item -Winit-self @r{(C, C++, Objective-C and Objective-C++ only)}
2654 Warn about uninitialized variables which are initialized with themselves.
2655 Note this option can only be used with the @option{-Wuninitialized} option,
2656 which in turn only works with @option{-O1} and above.
2658 For example, GCC will warn about @code{i} being uninitialized in the
2659 following snippet only when @option{-Winit-self} has been specified:
2670 @item -Wimplicit-int
2671 @opindex Wimplicit-int
2672 Warn when a declaration does not specify a type.
2673 This warning is enabled by @option{-Wall}.
2675 @item -Wimplicit-function-declaration
2676 @opindex Wimplicit-function-declaration
2677 @opindex Wno-implicit-function-declaration
2678 Give a warning whenever a function is used before being declared. In
2679 C99 mode (@option{-std=c99} or @option{-std=gnu99}), this warning is
2680 enabled by default and it is made into an error by
2681 @option{-pedantic-errors}. This warning is also enabled by
2686 Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
2687 This warning is enabled by @option{-Wall}.
2691 Warn if the type of @samp{main} is suspicious. @samp{main} should be a
2692 function with external linkage, returning int, taking either zero
2693 arguments, two, or three arguments of appropriate types.
2694 This warning is enabled by @option{-Wall}.
2696 @item -Wmissing-braces
2697 @opindex Wmissing-braces
2698 Warn if an aggregate or union initializer is not fully bracketed. In
2699 the following example, the initializer for @samp{a} is not fully
2700 bracketed, but that for @samp{b} is fully bracketed.
2703 int a[2][2] = @{ 0, 1, 2, 3 @};
2704 int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
2707 This warning is enabled by @option{-Wall}.
2709 @item -Wmissing-include-dirs @r{(C, C++, Objective-C and Objective-C++ only)}
2710 @opindex Wmissing-include-dirs
2711 Warn if a user-supplied include directory does not exist.
2714 @opindex Wparentheses
2715 Warn if parentheses are omitted in certain contexts, such
2716 as when there is an assignment in a context where a truth value
2717 is expected, or when operators are nested whose precedence people
2718 often get confused about.
2720 Also warn if a comparison like @samp{x<=y<=z} appears; this is
2721 equivalent to @samp{(x<=y ? 1 : 0) <= z}, which is a different
2722 interpretation from that of ordinary mathematical notation.
2724 Also warn about constructions where there may be confusion to which
2725 @code{if} statement an @code{else} branch belongs. Here is an example of
2740 In C/C++, every @code{else} branch belongs to the innermost possible
2741 @code{if} statement, which in this example is @code{if (b)}. This is
2742 often not what the programmer expected, as illustrated in the above
2743 example by indentation the programmer chose. When there is the
2744 potential for this confusion, GCC will issue a warning when this flag
2745 is specified. To eliminate the warning, add explicit braces around
2746 the innermost @code{if} statement so there is no way the @code{else}
2747 could belong to the enclosing @code{if}. The resulting code would
2764 This warning is enabled by @option{-Wall}.
2766 @item -Wsequence-point
2767 @opindex Wsequence-point
2768 Warn about code that may have undefined semantics because of violations
2769 of sequence point rules in the C and C++ standards.
2771 The C and C++ standards defines the order in which expressions in a C/C++
2772 program are evaluated in terms of @dfn{sequence points}, which represent
2773 a partial ordering between the execution of parts of the program: those
2774 executed before the sequence point, and those executed after it. These
2775 occur after the evaluation of a full expression (one which is not part
2776 of a larger expression), after the evaluation of the first operand of a
2777 @code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
2778 function is called (but after the evaluation of its arguments and the
2779 expression denoting the called function), and in certain other places.
2780 Other than as expressed by the sequence point rules, the order of
2781 evaluation of subexpressions of an expression is not specified. All
2782 these rules describe only a partial order rather than a total order,
2783 since, for example, if two functions are called within one expression
2784 with no sequence point between them, the order in which the functions
2785 are called is not specified. However, the standards committee have
2786 ruled that function calls do not overlap.
2788 It is not specified when between sequence points modifications to the
2789 values of objects take effect. Programs whose behavior depends on this
2790 have undefined behavior; the C and C++ standards specify that ``Between
2791 the previous and next sequence point an object shall have its stored
2792 value modified at most once by the evaluation of an expression.
2793 Furthermore, the prior value shall be read only to determine the value
2794 to be stored.''. If a program breaks these rules, the results on any
2795 particular implementation are entirely unpredictable.
2797 Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
2798 = b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
2799 diagnosed by this option, and it may give an occasional false positive
2800 result, but in general it has been found fairly effective at detecting
2801 this sort of problem in programs.
2803 The standard is worded confusingly, therefore there is some debate
2804 over the precise meaning of the sequence point rules in subtle cases.
2805 Links to discussions of the problem, including proposed formal
2806 definitions, may be found on the GCC readings page, at
2807 @w{@uref{http://gcc.gnu.org/readings.html}}.
2809 This warning is enabled by @option{-Wall} for C and C++.
2812 @opindex Wreturn-type
2813 @opindex Wno-return-type
2814 Warn whenever a function is defined with a return-type that defaults
2815 to @code{int}. Also warn about any @code{return} statement with no
2816 return-value in a function whose return-type is not @code{void}
2817 (falling off the end of the function body is considered returning
2818 without a value), and about a @code{return} statement with a
2819 expression in a function whose return-type is @code{void}.
2821 Also warn if the return type of a function has a type qualifier
2822 such as @code{const}. For ISO C such a type qualifier has no effect,
2823 since the value returned by a function is not an lvalue.
2824 For C++, the warning is only emitted for scalar types or @code{void}.
2825 ISO C prohibits qualified @code{void} return types on function
2826 definitions, so such return types always receive a warning
2827 even without this option.
2829 For C++, a function without return type always produces a diagnostic
2830 message, even when @option{-Wno-return-type} is specified. The only
2831 exceptions are @samp{main} and functions defined in system headers.
2833 This warning is enabled by @option{-Wall}.
2837 Warn whenever a @code{switch} statement has an index of enumerated type
2838 and lacks a @code{case} for one or more of the named codes of that
2839 enumeration. (The presence of a @code{default} label prevents this
2840 warning.) @code{case} labels outside the enumeration range also
2841 provoke warnings when this option is used.
2842 This warning is enabled by @option{-Wall}.
2844 @item -Wswitch-default
2845 @opindex Wswitch-switch
2846 Warn whenever a @code{switch} statement does not have a @code{default}
2850 @opindex Wswitch-enum
2851 Warn whenever a @code{switch} statement has an index of enumerated type
2852 and lacks a @code{case} for one or more of the named codes of that
2853 enumeration. @code{case} labels outside the enumeration range also
2854 provoke warnings when this option is used.
2858 Warn if any trigraphs are encountered that might change the meaning of
2859 the program (trigraphs within comments are not warned about).
2860 This warning is enabled by @option{-Wall}.
2862 @item -Wunused-function
2863 @opindex Wunused-function
2864 Warn whenever a static function is declared but not defined or a
2865 non-inline static function is unused.
2866 This warning is enabled by @option{-Wall}.
2868 @item -Wunused-label
2869 @opindex Wunused-label
2870 Warn whenever a label is declared but not used.
2871 This warning is enabled by @option{-Wall}.
2873 To suppress this warning use the @samp{unused} attribute
2874 (@pxref{Variable Attributes}).
2876 @item -Wunused-parameter
2877 @opindex Wunused-parameter
2878 Warn whenever a function parameter is unused aside from its declaration.
2880 To suppress this warning use the @samp{unused} attribute
2881 (@pxref{Variable Attributes}).
2883 @item -Wunused-variable
2884 @opindex Wunused-variable
2885 Warn whenever a local variable or non-constant static variable is unused
2886 aside from its declaration.
2887 This warning is enabled by @option{-Wall}.
2889 To suppress this warning use the @samp{unused} attribute
2890 (@pxref{Variable Attributes}).
2892 @item -Wunused-value
2893 @opindex Wunused-value
2894 Warn whenever a statement computes a result that is explicitly not
2895 used. To suppress this warning cast the unused expression to
2896 @samp{void}. This includes an expression-statement or the left-hand
2897 side of a comma expression that contains no side effects. For example,
2898 an expression such as @samp{x[i,j]} will cause a warning, while
2899 @samp{x[(void)i,j]} will not.
2901 This warning is enabled by @option{-Wall}.
2905 All the above @option{-Wunused} options combined.
2907 In order to get a warning about an unused function parameter, you must
2908 either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
2909 @samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
2911 @item -Wuninitialized
2912 @opindex Wuninitialized
2913 Warn if an automatic variable is used without first being initialized or
2914 if a variable may be clobbered by a @code{setjmp} call.
2916 These warnings are possible only in optimizing compilation,
2917 because they require data flow information that is computed only
2918 when optimizing. If you do not specify @option{-O}, you will not get
2919 these warnings. Instead, GCC will issue a warning about @option{-Wuninitialized}
2920 requiring @option{-O}.
2922 If you want to warn about code which uses the uninitialized value of the
2923 variable in its own initializer, use the @option{-Winit-self} option.
2925 These warnings occur for individual uninitialized or clobbered
2926 elements of structure, union or array variables as well as for
2927 variables which are uninitialized or clobbered as a whole. They do
2928 not occur for variables or elements declared @code{volatile}. Because
2929 these warnings depend on optimization, the exact variables or elements
2930 for which there are warnings will depend on the precise optimization
2931 options and version of GCC used.
2933 Note that there may be no warning about a variable that is used only
2934 to compute a value that itself is never used, because such
2935 computations may be deleted by data flow analysis before the warnings
2938 These warnings are made optional because GCC is not smart
2939 enough to see all the reasons why the code might be correct
2940 despite appearing to have an error. Here is one example of how
2961 If the value of @code{y} is always 1, 2 or 3, then @code{x} is
2962 always initialized, but GCC doesn't know this. Here is
2963 another common case:
2968 if (change_y) save_y = y, y = new_y;
2970 if (change_y) y = save_y;
2975 This has no bug because @code{save_y} is used only if it is set.
2977 @cindex @code{longjmp} warnings
2978 This option also warns when a non-volatile automatic variable might be
2979 changed by a call to @code{longjmp}. These warnings as well are possible
2980 only in optimizing compilation.
2982 The compiler sees only the calls to @code{setjmp}. It cannot know
2983 where @code{longjmp} will be called; in fact, a signal handler could
2984 call it at any point in the code. As a result, you may get a warning
2985 even when there is in fact no problem because @code{longjmp} cannot
2986 in fact be called at the place which would cause a problem.
2988 Some spurious warnings can be avoided if you declare all the functions
2989 you use that never return as @code{noreturn}. @xref{Function
2992 This warning is enabled by @option{-Wall}.
2994 @item -Wunknown-pragmas
2995 @opindex Wunknown-pragmas
2996 @cindex warning for unknown pragmas
2997 @cindex unknown pragmas, warning
2998 @cindex pragmas, warning of unknown
2999 Warn when a #pragma directive is encountered which is not understood by
3000 GCC@. If this command line option is used, warnings will even be issued
3001 for unknown pragmas in system header files. This is not the case if
3002 the warnings were only enabled by the @option{-Wall} command line option.
3005 @opindex Wno-pragmas
3007 Do not warn about misuses of pragmas, such as incorrect parameters,
3008 invalid syntax, or conflicts between pragmas. See also
3009 @samp{-Wunknown-pragmas}.
3011 @item -Wstrict-aliasing
3012 @opindex Wstrict-aliasing
3013 This option is only active when @option{-fstrict-aliasing} is active.
3014 It warns about code which might break the strict aliasing rules that the
3015 compiler is using for optimization. The warning does not catch all
3016 cases, but does attempt to catch the more common pitfalls. It is
3017 included in @option{-Wall}.
3018 It is equivalent to -Wstrict-aliasing=3
3020 @item -Wstrict-aliasing=n
3021 @opindex Wstrict-aliasing=n
3022 This option is only active when @option{-fstrict-aliasing} is active.
3023 It warns about code which might break the strict aliasing rules that the
3024 compiler is using for optimization.
3025 Higher levels correspond to higher accuracy (fewer false positives).
3026 Higher levels also correspond to more effort, similar to the way -O works.
3027 @option{-Wstrict-aliasing} is equivalent to @option{-Wstrict-aliasing=n},
3030 Level 1: Most aggressive, quick, least accurate.
3031 Possibly useful when higher levels
3032 do not warn but -fstrict-aliasing still breaks the code, as it has very few
3033 false negatives. However, it has many false positives.
3034 Warns for all pointer conversions between possibly incompatible types,
3035 even if never dereferenced. Runs in the frontend only.
3037 Level 2: Aggressive, quick, not too precise.
3038 May still have many false positives (not as many as level 1 though),
3039 and few false negatives (but possibly more than level 1).
3040 Unlike level 1, it only warns when an address is taken. Warns about
3041 incomplete types. Runs in the frontend only.
3043 Level 3 (default for @option{-Wstrict-aliasing}):
3044 Should have very few false positives and few false
3045 negatives. Slightly slower than levels 1 or 2 when optimization is enabled.
3046 Takes care of the common punn+dereference pattern in the frontend:
3047 @code{*(int*)&some_float}.
3048 If optimization is enabled, it also runs in the backend, where it deals
3049 with multiple statement cases using flow-sensitive points-to information.
3050 Only warns when the converted pointer is dereferenced.
3051 Does not warn about incomplete types.
3053 @item -Wstrict-overflow
3054 @item -Wstrict-overflow=@var{n}
3055 @opindex Wstrict-overflow
3056 This option is only active when @option{-fstrict-overflow} is active.
3057 It warns about cases where the compiler optimizes based on the
3058 assumption that signed overflow does not occur. Note that it does not
3059 warn about all cases where the code might overflow: it only warns
3060 about cases where the compiler implements some optimization. Thus
3061 this warning depends on the optimization level.
3063 An optimization which assumes that signed overflow does not occur is
3064 perfectly safe if the values of the variables involved are such that
3065 overflow never does, in fact, occur. Therefore this warning can
3066 easily give a false positive: a warning about code which is not
3067 actually a problem. To help focus on important issues, several
3068 warning levels are defined. No warnings are issued for the use of
3069 undefined signed overflow when estimating how many iterations a loop
3070 will require, in particular when determining whether a loop will be
3074 @item -Wstrict-overflow=1
3075 Warn about cases which are both questionable and easy to avoid. For
3076 example: @code{x + 1 > x}; with @option{-fstrict-overflow}, the
3077 compiler will simplify this to @code{1}. This level of
3078 @option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
3079 are not, and must be explicitly requested.
3081 @item -Wstrict-overflow=2
3082 Also warn about other cases where a comparison is simplified to a
3083 constant. For example: @code{abs (x) >= 0}. This can only be
3084 simplified when @option{-fstrict-overflow} is in effect, because
3085 @code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
3086 zero. @option{-Wstrict-overflow} (with no level) is the same as
3087 @option{-Wstrict-overflow=2}.
3089 @item -Wstrict-overflow=3
3090 Also warn about other cases where a comparison is simplified. For
3091 example: @code{x + 1 > 1} will be simplified to @code{x > 0}.
3093 @item -Wstrict-overflow=4
3094 Also warn about other simplifications not covered by the above cases.
3095 For example: @code{(x * 10) / 5} will be simplified to @code{x * 2}.
3097 @item -Wstrict-overflow=5
3098 Also warn about cases where the compiler reduces the magnitude of a
3099 constant involved in a comparison. For example: @code{x + 2 > y} will
3100 be simplified to @code{x + 1 >= y}. This is reported only at the
3101 highest warning level because this simplification applies to many
3102 comparisons, so this warning level will give a very large number of
3106 @item -Warray-bounds
3107 @opindex Wno-array-bounds
3108 @opindex Warray-bounds
3109 This option is only active when @option{-ftree-vrp} is active
3110 (default for -O2 and above). It warns about subscripts to arrays
3111 that are always out of bounds. This warning is enabled by @option{-Wall}.
3115 All of the above @samp{-W} options combined. This enables all the
3116 warnings about constructions that some users consider questionable, and
3117 that are easy to avoid (or modify to prevent the warning), even in
3118 conjunction with macros. This also enables some language-specific
3119 warnings described in @ref{C++ Dialect Options} and
3120 @ref{Objective-C and Objective-C++ Dialect Options}.
3123 The following @option{-W@dots{}} options are not implied by @option{-Wall}.
3124 Some of them warn about constructions that users generally do not
3125 consider questionable, but which occasionally you might wish to check
3126 for; others warn about constructions that are necessary or hard to avoid
3127 in some cases, and there is no simple way to modify the code to suppress
3134 (This option used to be called @option{-W}. The older name is still
3135 supported, but the newer name is more descriptive.) Print extra warning
3136 messages for these events:
3140 Warn if a comparison is always true or always false due to the limited
3141 range of the data type, but do not warn for constant expressions. For
3142 example, warn if an unsigned variable is compared against zero with
3143 @samp{<} or @samp{>=}. This warning can be independently controlled
3144 by @option{-Wtype-limits}.
3147 Storage-class specifiers like @code{static} are not the first things
3148 in a declaration. According to the C Standard, this usage is
3149 obsolescent. This warning can be independently controlled by
3150 @option{-Wold-style-declaration}.
3153 If @option{-Wall} or @option{-Wunused} is also specified, warn about unused
3157 A comparison between signed and unsigned values could produce an
3158 incorrect result when the signed value is converted to unsigned.
3159 (But don't warn if @option{-Wno-sign-compare} is also specified.)
3162 An aggregate has an initializer which does not initialize all members.
3163 This warning can be independently controlled by
3164 @option{-Wmissing-field-initializers}.
3167 An initialized field without side effects is overridden when using
3168 designated initializers (@pxref{Designated Inits, , Designated
3169 Initializers}). This warning can be independently controlled by
3170 @option{-Woverride-init}.
3173 A function parameter is declared without a type specifier in K&R-style
3174 functions. This warning can be independently controlled by
3175 @option{-Wmissing-parameter-type}.
3178 An empty body occurs in an @samp{if}, @samp{else} or
3179 @samp{do while} statement. This warning can be independently
3180 controlled by @option{-Wempty-body}.
3182 @item @r{(C++ only)}
3183 An empty body occurs in a @samp{while} or @samp{for} statement with no
3184 whitespacing before the semicolon. This warning can be independently
3185 controlled by @option{-Wempty-body}.
3188 A pointer is compared against integer zero with @samp{<}, @samp{<=},
3189 @samp{>}, or @samp{>=}.
3192 A variable might be changed by @samp{longjmp} or @samp{vfork}.
3193 This warning can be independently controlled by @option{-Wclobbered}.
3195 @item @r{(C++ only)}
3196 An enumerator and a non-enumerator both appear in a conditional expression.
3198 @item @r{(C++ only)}
3199 A non-static reference or non-static @samp{const} member appears in a
3200 class without constructors.
3202 @item @r{(C++ only)}
3203 Ambiguous virtual bases.
3205 @item @r{(C++ only)}
3206 Subscripting an array which has been declared @samp{register}.
3208 @item @r{(C++ only)}
3209 Taking the address of a variable which has been declared @samp{register}.
3211 @item @r{(C++ only)}
3212 A base class is not initialized in a derived class' copy constructor.
3215 @item -Wno-div-by-zero
3216 @opindex Wno-div-by-zero
3217 @opindex Wdiv-by-zero
3218 Do not warn about compile-time integer division by zero. Floating point
3219 division by zero is not warned about, as it can be a legitimate way of
3220 obtaining infinities and NaNs.
3222 @item -Wsystem-headers
3223 @opindex Wsystem-headers
3224 @cindex warnings from system headers
3225 @cindex system headers, warnings from
3226 Print warning messages for constructs found in system header files.
3227 Warnings from system headers are normally suppressed, on the assumption
3228 that they usually do not indicate real problems and would only make the
3229 compiler output harder to read. Using this command line option tells
3230 GCC to emit warnings from system headers as if they occurred in user
3231 code. However, note that using @option{-Wall} in conjunction with this
3232 option will @emph{not} warn about unknown pragmas in system
3233 headers---for that, @option{-Wunknown-pragmas} must also be used.
3236 @opindex Wfloat-equal
3237 Warn if floating point values are used in equality comparisons.
3239 The idea behind this is that sometimes it is convenient (for the
3240 programmer) to consider floating-point values as approximations to
3241 infinitely precise real numbers. If you are doing this, then you need
3242 to compute (by analyzing the code, or in some other way) the maximum or
3243 likely maximum error that the computation introduces, and allow for it
3244 when performing comparisons (and when producing output, but that's a
3245 different problem). In particular, instead of testing for equality, you
3246 would check to see whether the two values have ranges that overlap; and
3247 this is done with the relational operators, so equality comparisons are
3250 @item -Wtraditional @r{(C only)}
3251 @opindex Wtraditional
3252 Warn about certain constructs that behave differently in traditional and
3253 ISO C@. Also warn about ISO C constructs that have no traditional C
3254 equivalent, and/or problematic constructs which should be avoided.
3258 Macro parameters that appear within string literals in the macro body.
3259 In traditional C macro replacement takes place within string literals,
3260 but does not in ISO C@.
3263 In traditional C, some preprocessor directives did not exist.
3264 Traditional preprocessors would only consider a line to be a directive
3265 if the @samp{#} appeared in column 1 on the line. Therefore
3266 @option{-Wtraditional} warns about directives that traditional C
3267 understands but would ignore because the @samp{#} does not appear as the
3268 first character on the line. It also suggests you hide directives like
3269 @samp{#pragma} not understood by traditional C by indenting them. Some
3270 traditional implementations would not recognize @samp{#elif}, so it
3271 suggests avoiding it altogether.
3274 A function-like macro that appears without arguments.
3277 The unary plus operator.
3280 The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
3281 constant suffixes. (Traditional C does support the @samp{L} suffix on integer
3282 constants.) Note, these suffixes appear in macros defined in the system
3283 headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
3284 Use of these macros in user code might normally lead to spurious
3285 warnings, however GCC's integrated preprocessor has enough context to
3286 avoid warning in these cases.
3289 A function declared external in one block and then used after the end of
3293 A @code{switch} statement has an operand of type @code{long}.
3296 A non-@code{static} function declaration follows a @code{static} one.
3297 This construct is not accepted by some traditional C compilers.
3300 The ISO type of an integer constant has a different width or
3301 signedness from its traditional type. This warning is only issued if
3302 the base of the constant is ten. I.e.@: hexadecimal or octal values, which
3303 typically represent bit patterns, are not warned about.
3306 Usage of ISO string concatenation is detected.
3309 Initialization of automatic aggregates.
3312 Identifier conflicts with labels. Traditional C lacks a separate
3313 namespace for labels.
3316 Initialization of unions. If the initializer is zero, the warning is
3317 omitted. This is done under the assumption that the zero initializer in
3318 user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
3319 initializer warnings and relies on default initialization to zero in the
3323 Conversions by prototypes between fixed/floating point values and vice
3324 versa. The absence of these prototypes when compiling with traditional
3325 C would cause serious problems. This is a subset of the possible
3326 conversion warnings, for the full set use @option{-Wtraditional-conversion}.
3329 Use of ISO C style function definitions. This warning intentionally is
3330 @emph{not} issued for prototype declarations or variadic functions
3331 because these ISO C features will appear in your code when using
3332 libiberty's traditional C compatibility macros, @code{PARAMS} and
3333 @code{VPARAMS}. This warning is also bypassed for nested functions
3334 because that feature is already a GCC extension and thus not relevant to
3335 traditional C compatibility.
3338 @item -Wtraditional-conversion @r{(C only)}
3339 @opindex Wtraditional-conversion
3340 Warn if a prototype causes a type conversion that is different from what
3341 would happen to the same argument in the absence of a prototype. This
3342 includes conversions of fixed point to floating and vice versa, and
3343 conversions changing the width or signedness of a fixed point argument
3344 except when the same as the default promotion.
3346 @item -Wdeclaration-after-statement @r{(C only)}
3347 @opindex Wdeclaration-after-statement
3348 Warn when a declaration is found after a statement in a block. This
3349 construct, known from C++, was introduced with ISO C99 and is by default
3350 allowed in GCC@. It is not supported by ISO C90 and was not supported by
3351 GCC versions before GCC 3.0. @xref{Mixed Declarations}.
3355 Warn if an undefined identifier is evaluated in an @samp{#if} directive.
3357 @item -Wno-endif-labels
3358 @opindex Wno-endif-labels
3359 @opindex Wendif-labels
3360 Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
3364 Warn whenever a local variable shadows another local variable, parameter or
3365 global variable or whenever a built-in function is shadowed.
3367 @item -Wlarger-than-@var{len}
3368 @opindex Wlarger-than
3369 Warn whenever an object of larger than @var{len} bytes is defined.
3371 @item -Wunsafe-loop-optimizations
3372 @opindex Wunsafe-loop-optimizations
3373 Warn if the loop cannot be optimized because the compiler could not
3374 assume anything on the bounds of the loop indices. With
3375 @option{-funsafe-loop-optimizations} warn if the compiler made
3378 @item -Wpointer-arith
3379 @opindex Wpointer-arith
3380 Warn about anything that depends on the ``size of'' a function type or
3381 of @code{void}. GNU C assigns these types a size of 1, for
3382 convenience in calculations with @code{void *} pointers and pointers
3383 to functions. In C++, warn also when an arithmetic operation involves
3384 @code{NULL}. This warning is also enabled by @option{-pedantic}.
3387 @opindex Wtype-limits
3388 @opindex Wno-type-limits
3389 Warn if a comparison is always true or always false due to the limited
3390 range of the data type, but do not warn for constant expressions. For
3391 example, warn if an unsigned variable is compared against zero with
3392 @samp{<} or @samp{>=}. This warning is also enabled by
3395 @item -Wbad-function-cast @r{(C only)}
3396 @opindex Wbad-function-cast
3397 Warn whenever a function call is cast to a non-matching type.
3398 For example, warn if @code{int malloc()} is cast to @code{anything *}.
3401 Warn about ISO C constructs that are outside of the common subset of
3402 ISO C and ISO C++, e.g.@: request for implicit conversion from
3403 @code{void *} to a pointer to non-@code{void} type.
3405 @item -Wc++0x-compat @r{(C++ and Objective-C++ only)}
3406 Warn about C++ constructs whose meaning differs between ISO C++ 1998 and
3407 ISO C++ 200x, e.g., identifiers in ISO C++ 1998 that will become keywords
3408 in ISO C++ 200x. This warning is enabled by @option{-Wall}.
3412 Warn whenever a pointer is cast so as to remove a type qualifier from
3413 the target type. For example, warn if a @code{const char *} is cast
3414 to an ordinary @code{char *}.
3417 @opindex Wcast-align
3418 Warn whenever a pointer is cast such that the required alignment of the
3419 target is increased. For example, warn if a @code{char *} is cast to
3420 an @code{int *} on machines where integers can only be accessed at
3421 two- or four-byte boundaries.
3423 @item -Wwrite-strings
3424 @opindex Wwrite-strings
3425 When compiling C, give string constants the type @code{const
3426 char[@var{length}]} so that
3427 copying the address of one into a non-@code{const} @code{char *}
3428 pointer will get a warning; when compiling C++, warn about the
3429 deprecated conversion from string literals to @code{char *}. This
3430 warning, by default, is enabled for C++ programs.
3431 These warnings will help you find at
3432 compile time code that can try to write into a string constant, but
3433 only if you have been very careful about using @code{const} in
3434 declarations and prototypes. Otherwise, it will just be a nuisance;
3435 this is why we did not make @option{-Wall} request these warnings.
3439 Warn for variables that might be changed by @samp{longjmp} or
3440 @samp{vfork}. This warning is also enabled by @option{-Wextra}.
3443 @opindex Wconversion
3444 @opindex Wno-conversion
3445 Warn for implicit conversions that may alter a value. This includes
3446 conversions between real and integer, like @code{abs (x)} when
3447 @code{x} is @code{double}; conversions between signed and unsigned,
3448 like @code{unsigned ui = -1}; and conversions to smaller types, like
3449 @code{sqrtf (M_PI)}. Do not warn for explicit casts like @code{abs
3450 ((int) x)} and @code{ui = (unsigned) -1}, or if the value is not
3451 changed by the conversion like in @code{abs (2.0)}. Warnings about
3452 conversions between signed and unsigned integers can be disabled by
3453 using @option{-Wno-sign-conversion}.
3455 For C++, also warn for conversions between @code{NULL} and non-pointer
3456 types; confusing overload resolution for user-defined conversions; and
3457 conversions that will never use a type conversion operator:
3458 conversions to @code{void}, the same type, a base class or a reference
3459 to them. Warnings about conversions between signed and unsigned
3460 integers are disabled by default in C++ unless
3461 @option{-Wsign-conversion} is explicitly enabled.
3464 @opindex Wempty-body
3465 Warn if an empty body occurs in an @samp{if}, @samp{else} or @samp{do
3466 while} statement. Additionally, in C++, warn when an empty body occurs
3467 in a @samp{while} or @samp{for} statement with no whitespacing before
3468 the semicolon. This warning is also enabled by @option{-Wextra}.
3470 @item -Wsign-compare
3471 @opindex Wsign-compare
3472 @cindex warning for comparison of signed and unsigned values
3473 @cindex comparison of signed and unsigned values, warning
3474 @cindex signed and unsigned values, comparison warning
3475 Warn when a comparison between signed and unsigned values could produce
3476 an incorrect result when the signed value is converted to unsigned.
3477 This warning is also enabled by @option{-Wextra}; to get the other warnings
3478 of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
3480 @item -Wsign-conversion
3481 @opindex Wsign-conversion
3482 @opindex Wno-sign-conversion
3483 Warn for implicit conversions that may change the sign of an integer
3484 value, like assigning a signed integer expression to an unsigned
3485 integer variable. An explicit cast silences the warning. In C, this
3486 option is enabled also by @option{-Wconversion}.
3490 @opindex Wno-address
3491 Warn about suspicious uses of memory addresses. These include using
3492 the address of a function in a conditional expression, such as
3493 @code{void func(void); if (func)}, and comparisons against the memory
3494 address of a string literal, such as @code{if (x == "abc")}. Such
3495 uses typically indicate a programmer error: the address of a function
3496 always evaluates to true, so their use in a conditional usually
3497 indicate that the programmer forgot the parentheses in a function
3498 call; and comparisons against string literals result in unspecified
3499 behavior and are not portable in C, so they usually indicate that the
3500 programmer intended to use @code{strcmp}. This warning is enabled by
3504 @opindex Wlogical-op
3505 @opindex Wno-logical-op
3506 Warn about suspicious uses of logical operators in expressions.
3507 This includes using logical operators in contexts where a
3508 bit-wise operator is likely to be expected.
3510 @item -Waggregate-return
3511 @opindex Waggregate-return
3512 Warn if any functions that return structures or unions are defined or
3513 called. (In languages where you can return an array, this also elicits
3516 @item -Wno-attributes
3517 @opindex Wno-attributes
3518 @opindex Wattributes
3519 Do not warn if an unexpected @code{__attribute__} is used, such as
3520 unrecognized attributes, function attributes applied to variables,
3521 etc. This will not stop errors for incorrect use of supported
3524 @item -Wstrict-prototypes @r{(C only)}
3525 @opindex Wstrict-prototypes
3526 Warn if a function is declared or defined without specifying the
3527 argument types. (An old-style function definition is permitted without
3528 a warning if preceded by a declaration which specifies the argument
3531 @item -Wold-style-declaration @r{(C only)}
3532 @opindex Wold-style-declaration
3533 Warn for obsolescent usages, according to the C Standard, in a
3534 declaration. For example, warn if storage-class specifiers like
3535 @code{static} are not the first things in a declaration. This warning
3536 is also enabled by @option{-Wextra}.
3538 @item -Wold-style-definition @r{(C only)}
3539 @opindex Wold-style-definition
3540 Warn if an old-style function definition is used. A warning is given
3541 even if there is a previous prototype.
3543 @item -Wmissing-parameter-type @r{(C only)}
3544 @opindex Wmissing-parameter-type
3545 A function parameter is declared without a type specifier in K&R-style
3552 This warning is also enabled by @option{-Wextra}.
3554 @item -Wmissing-prototypes @r{(C only)}
3555 @opindex Wmissing-prototypes
3556 Warn if a global function is defined without a previous prototype
3557 declaration. This warning is issued even if the definition itself
3558 provides a prototype. The aim is to detect global functions that fail
3559 to be declared in header files.
3561 @item -Wmissing-declarations @r{(C and C++ only)}
3562 @opindex Wmissing-declarations
3563 Warn if a global function is defined without a previous declaration.
3564 Do so even if the definition itself provides a prototype.
3565 Use this option to detect global functions that are not declared in
3566 header files. In C++, no warnings are issued for function templates,
3567 or for inline functions, or for functions in anonymous namespaces.
3569 @item -Wmissing-field-initializers
3570 @opindex Wmissing-field-initializers
3573 Warn if a structure's initializer has some fields missing. For
3574 example, the following code would cause such a warning, because
3575 @code{x.h} is implicitly zero:
3578 struct s @{ int f, g, h; @};
3579 struct s x = @{ 3, 4 @};
3582 This option does not warn about designated initializers, so the following
3583 modification would not trigger a warning:
3586 struct s @{ int f, g, h; @};
3587 struct s x = @{ .f = 3, .g = 4 @};
3590 This warning is included in @option{-Wextra}. To get other @option{-Wextra}
3591 warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
3593 @item -Wmissing-noreturn
3594 @opindex Wmissing-noreturn
3595 Warn about functions which might be candidates for attribute @code{noreturn}.
3596 Note these are only possible candidates, not absolute ones. Care should
3597 be taken to manually verify functions actually do not ever return before
3598 adding the @code{noreturn} attribute, otherwise subtle code generation
3599 bugs could be introduced. You will not get a warning for @code{main} in
3600 hosted C environments.
3602 @item -Wmissing-format-attribute
3603 @opindex Wmissing-format-attribute
3605 Warn about function pointers which might be candidates for @code{format}
3606 attributes. Note these are only possible candidates, not absolute ones.
3607 GCC will guess that function pointers with @code{format} attributes that
3608 are used in assignment, initialization, parameter passing or return
3609 statements should have a corresponding @code{format} attribute in the
3610 resulting type. I.e.@: the left-hand side of the assignment or
3611 initialization, the type of the parameter variable, or the return type
3612 of the containing function respectively should also have a @code{format}
3613 attribute to avoid the warning.
3615 GCC will also warn about function definitions which might be
3616 candidates for @code{format} attributes. Again, these are only
3617 possible candidates. GCC will guess that @code{format} attributes
3618 might be appropriate for any function that calls a function like
3619 @code{vprintf} or @code{vscanf}, but this might not always be the
3620 case, and some functions for which @code{format} attributes are
3621 appropriate may not be detected.
3623 @item -Wno-multichar
3624 @opindex Wno-multichar
3626 Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
3627 Usually they indicate a typo in the user's code, as they have
3628 implementation-defined values, and should not be used in portable code.
3630 @item -Wnormalized=<none|id|nfc|nfkc>
3631 @opindex Wnormalized
3634 @cindex character set, input normalization
3635 In ISO C and ISO C++, two identifiers are different if they are
3636 different sequences of characters. However, sometimes when characters
3637 outside the basic ASCII character set are used, you can have two
3638 different character sequences that look the same. To avoid confusion,
3639 the ISO 10646 standard sets out some @dfn{normalization rules} which
3640 when applied ensure that two sequences that look the same are turned into
3641 the same sequence. GCC can warn you if you are using identifiers which
3642 have not been normalized; this option controls that warning.
3644 There are four levels of warning that GCC supports. The default is
3645 @option{-Wnormalized=nfc}, which warns about any identifier which is
3646 not in the ISO 10646 ``C'' normalized form, @dfn{NFC}. NFC is the
3647 recommended form for most uses.
3649 Unfortunately, there are some characters which ISO C and ISO C++ allow
3650 in identifiers that when turned into NFC aren't allowable as
3651 identifiers. That is, there's no way to use these symbols in portable
3652 ISO C or C++ and have all your identifiers in NFC.
3653 @option{-Wnormalized=id} suppresses the warning for these characters.
3654 It is hoped that future versions of the standards involved will correct
3655 this, which is why this option is not the default.
3657 You can switch the warning off for all characters by writing
3658 @option{-Wnormalized=none}. You would only want to do this if you
3659 were using some other normalization scheme (like ``D''), because
3660 otherwise you can easily create bugs that are literally impossible to see.
3662 Some characters in ISO 10646 have distinct meanings but look identical
3663 in some fonts or display methodologies, especially once formatting has
3664 been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
3665 LETTER N'', will display just like a regular @code{n} which has been
3666 placed in a superscript. ISO 10646 defines the @dfn{NFKC}
3667 normalization scheme to convert all these into a standard form as
3668 well, and GCC will warn if your code is not in NFKC if you use
3669 @option{-Wnormalized=nfkc}. This warning is comparable to warning
3670 about every identifier that contains the letter O because it might be
3671 confused with the digit 0, and so is not the default, but may be
3672 useful as a local coding convention if the programming environment is
3673 unable to be fixed to display these characters distinctly.
3675 @item -Wno-deprecated-declarations
3676 @opindex Wno-deprecated-declarations
3677 Do not warn about uses of functions (@pxref{Function Attributes}),
3678 variables (@pxref{Variable Attributes}), and types (@pxref{Type
3679 Attributes}) marked as deprecated by using the @code{deprecated}
3683 @opindex Wno-overflow
3684 Do not warn about compile-time overflow in constant expressions.
3686 @item -Woverride-init
3687 @opindex Woverride-init
3690 Warn if an initialized field without side effects is overridden when
3691 using designated initializers (@pxref{Designated Inits, , Designated
3694 This warning is included in @option{-Wextra}. To get other
3695 @option{-Wextra} warnings without this one, use @samp{-Wextra
3696 -Wno-override-init}.
3700 Warn if a structure is given the packed attribute, but the packed
3701 attribute has no effect on the layout or size of the structure.
3702 Such structures may be mis-aligned for little benefit. For
3703 instance, in this code, the variable @code{f.x} in @code{struct bar}
3704 will be misaligned even though @code{struct bar} does not itself
3705 have the packed attribute:
3712 @} __attribute__((packed));
3722 Warn if padding is included in a structure, either to align an element
3723 of the structure or to align the whole structure. Sometimes when this
3724 happens it is possible to rearrange the fields of the structure to
3725 reduce the padding and so make the structure smaller.
3727 @item -Wredundant-decls
3728 @opindex Wredundant-decls
3729 Warn if anything is declared more than once in the same scope, even in
3730 cases where multiple declaration is valid and changes nothing.
3732 @item -Wnested-externs @r{(C only)}
3733 @opindex Wnested-externs
3734 Warn if an @code{extern} declaration is encountered within a function.
3736 @item -Wunreachable-code
3737 @opindex Wunreachable-code
3738 Warn if the compiler detects that code will never be executed.
3740 This option is intended to warn when the compiler detects that at
3741 least a whole line of source code will never be executed, because
3742 some condition is never satisfied or because it is after a
3743 procedure that never returns.
3745 It is possible for this option to produce a warning even though there
3746 are circumstances under which part of the affected line can be executed,
3747 so care should be taken when removing apparently-unreachable code.
3749 For instance, when a function is inlined, a warning may mean that the
3750 line is unreachable in only one inlined copy of the function.
3752 This option is not made part of @option{-Wall} because in a debugging
3753 version of a program there is often substantial code which checks
3754 correct functioning of the program and is, hopefully, unreachable
3755 because the program does work. Another common use of unreachable
3756 code is to provide behavior which is selectable at compile-time.
3760 Warn if a function can not be inlined and it was declared as inline.
3761 Even with this option, the compiler will not warn about failures to
3762 inline functions declared in system headers.
3764 The compiler uses a variety of heuristics to determine whether or not
3765 to inline a function. For example, the compiler takes into account
3766 the size of the function being inlined and the amount of inlining
3767 that has already been done in the current function. Therefore,
3768 seemingly insignificant changes in the source program can cause the
3769 warnings produced by @option{-Winline} to appear or disappear.
3771 @item -Wno-invalid-offsetof @r{(C++ only)}
3772 @opindex Wno-invalid-offsetof
3773 Suppress warnings from applying the @samp{offsetof} macro to a non-POD
3774 type. According to the 1998 ISO C++ standard, applying @samp{offsetof}
3775 to a non-POD type is undefined. In existing C++ implementations,
3776 however, @samp{offsetof} typically gives meaningful results even when
3777 applied to certain kinds of non-POD types. (Such as a simple
3778 @samp{struct} that fails to be a POD type only by virtue of having a
3779 constructor.) This flag is for users who are aware that they are
3780 writing nonportable code and who have deliberately chosen to ignore the
3783 The restrictions on @samp{offsetof} may be relaxed in a future version
3784 of the C++ standard.
3786 @item -Wno-int-to-pointer-cast @r{(C only)}
3787 @opindex Wno-int-to-pointer-cast
3788 Suppress warnings from casts to pointer type of an integer of a
3791 @item -Wno-pointer-to-int-cast @r{(C only)}
3792 @opindex Wno-pointer-to-int-cast
3793 Suppress warnings from casts from a pointer to an integer type of a
3797 @opindex Winvalid-pch
3798 Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
3799 the search path but can't be used.
3803 @opindex Wno-long-long
3804 Warn if @samp{long long} type is used. This is default. To inhibit
3805 the warning messages, use @option{-Wno-long-long}. Flags
3806 @option{-Wlong-long} and @option{-Wno-long-long} are taken into account
3807 only when @option{-pedantic} flag is used.
3809 @item -Wvariadic-macros
3810 @opindex Wvariadic-macros
3811 @opindex Wno-variadic-macros
3812 Warn if variadic macros are used in pedantic ISO C90 mode, or the GNU
3813 alternate syntax when in pedantic ISO C99 mode. This is default.
3814 To inhibit the warning messages, use @option{-Wno-variadic-macros}.
3819 Warn if variable length array is used in the code.
3820 @option{-Wno-vla} will prevent the @option{-pedantic} warning of
3821 the variable length array.
3823 @item -Wvolatile-register-var
3824 @opindex Wvolatile-register-var
3825 @opindex Wno-volatile-register-var
3826 Warn if a register variable is declared volatile. The volatile
3827 modifier does not inhibit all optimizations that may eliminate reads
3828 and/or writes to register variables.
3830 @item -Wdisabled-optimization
3831 @opindex Wdisabled-optimization
3832 Warn if a requested optimization pass is disabled. This warning does
3833 not generally indicate that there is anything wrong with your code; it
3834 merely indicates that GCC's optimizers were unable to handle the code
3835 effectively. Often, the problem is that your code is too big or too
3836 complex; GCC will refuse to optimize programs when the optimization
3837 itself is likely to take inordinate amounts of time.
3839 @item -Wpointer-sign
3840 @opindex Wpointer-sign
3841 @opindex Wno-pointer-sign
3842 Warn for pointer argument passing or assignment with different signedness.
3843 This option is only supported for C and Objective-C@. It is implied by
3844 @option{-Wall} and by @option{-pedantic}, which can be disabled with
3845 @option{-Wno-pointer-sign}.
3849 Make all warnings into errors.
3853 Make the specified warning into an errors. The specifier for a
3854 warning is appended, for example @option{-Werror=switch} turns the
3855 warnings controlled by @option{-Wswitch} into errors. This switch
3856 takes a negative form, to be used to negate @option{-Werror} for
3857 specific warnings, for example @option{-Wno-error=switch} makes
3858 @option{-Wswitch} warnings not be errors, even when @option{-Werror}
3859 is in effect. You can use the @option{-fdiagnostics-show-option}
3860 option to have each controllable warning amended with the option which
3861 controls it, to determine what to use with this option.
3863 Note that specifying @option{-Werror=}@var{foo} automatically implies
3864 @option{-W}@var{foo}. However, @option{-Wno-error=}@var{foo} does not
3867 @item -Wstack-protector
3868 @opindex Wstack-protector
3869 This option is only active when @option{-fstack-protector} is active. It
3870 warns about functions that will not be protected against stack smashing.
3872 @item -Woverlength-strings
3873 @opindex Woverlength-strings
3874 Warn about string constants which are longer than the ``minimum
3875 maximum'' length specified in the C standard. Modern compilers
3876 generally allow string constants which are much longer than the
3877 standard's minimum limit, but very portable programs should avoid
3878 using longer strings.
3880 The limit applies @emph{after} string constant concatenation, and does
3881 not count the trailing NUL@. In C89, the limit was 509 characters; in
3882 C99, it was raised to 4095. C++98 does not specify a normative
3883 minimum maximum, so we do not diagnose overlength strings in C++@.
3885 This option is implied by @option{-pedantic}, and can be disabled with
3886 @option{-Wno-overlength-strings}.
3889 @node Debugging Options
3890 @section Options for Debugging Your Program or GCC
3891 @cindex options, debugging
3892 @cindex debugging information options
3894 GCC has various special options that are used for debugging
3895 either your program or GCC:
3900 Produce debugging information in the operating system's native format
3901 (stabs, COFF, XCOFF, or DWARF 2)@. GDB can work with this debugging
3904 On most systems that use stabs format, @option{-g} enables use of extra
3905 debugging information that only GDB can use; this extra information
3906 makes debugging work better in GDB but will probably make other debuggers
3908 refuse to read the program. If you want to control for certain whether
3909 to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
3910 @option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
3912 GCC allows you to use @option{-g} with
3913 @option{-O}. The shortcuts taken by optimized code may occasionally
3914 produce surprising results: some variables you declared may not exist
3915 at all; flow of control may briefly move where you did not expect it;
3916 some statements may not be executed because they compute constant
3917 results or their values were already at hand; some statements may
3918 execute in different places because they were moved out of loops.
3920 Nevertheless it proves possible to debug optimized output. This makes
3921 it reasonable to use the optimizer for programs that might have bugs.
3923 The following options are useful when GCC is generated with the
3924 capability for more than one debugging format.
3928 Produce debugging information for use by GDB@. This means to use the
3929 most expressive format available (DWARF 2, stabs, or the native format
3930 if neither of those are supported), including GDB extensions if at all
3935 Produce debugging information in stabs format (if that is supported),
3936 without GDB extensions. This is the format used by DBX on most BSD
3937 systems. On MIPS, Alpha and System V Release 4 systems this option
3938 produces stabs debugging output which is not understood by DBX or SDB@.
3939 On System V Release 4 systems this option requires the GNU assembler.
3941 @item -feliminate-unused-debug-symbols
3942 @opindex feliminate-unused-debug-symbols
3943 Produce debugging information in stabs format (if that is supported),
3944 for only symbols that are actually used.
3946 @item -femit-class-debug-always
3947 Instead of emitting debugging information for a C++ class in only one
3948 object file, emit it in all object files using the class. This option
3949 should be used only with debuggers that are unable to handle the way GCC
3950 normally emits debugging information for classes because using this
3951 option will increase the size of debugging information by as much as a
3956 Produce debugging information in stabs format (if that is supported),
3957 using GNU extensions understood only by the GNU debugger (GDB)@. The
3958 use of these extensions is likely to make other debuggers crash or
3959 refuse to read the program.
3963 Produce debugging information in COFF format (if that is supported).
3964 This is the format used by SDB on most System V systems prior to
3969 Produce debugging information in XCOFF format (if that is supported).
3970 This is the format used by the DBX debugger on IBM RS/6000 systems.
3974 Produce debugging information in XCOFF format (if that is supported),
3975 using GNU extensions understood only by the GNU debugger (GDB)@. The
3976 use of these extensions is likely to make other debuggers crash or
3977 refuse to read the program, and may cause assemblers other than the GNU
3978 assembler (GAS) to fail with an error.
3982 Produce debugging information in DWARF version 2 format (if that is
3983 supported). This is the format used by DBX on IRIX 6. With this
3984 option, GCC uses features of DWARF version 3 when they are useful;
3985 version 3 is upward compatible with version 2, but may still cause
3986 problems for older debuggers.
3990 Produce debugging information in VMS debug format (if that is
3991 supported). This is the format used by DEBUG on VMS systems.
3994 @itemx -ggdb@var{level}
3995 @itemx -gstabs@var{level}
3996 @itemx -gcoff@var{level}
3997 @itemx -gxcoff@var{level}
3998 @itemx -gvms@var{level}
3999 Request debugging information and also use @var{level} to specify how
4000 much information. The default level is 2.
4002 Level 0 produces no debug information at all. Thus, @option{-g0} negates
4005 Level 1 produces minimal information, enough for making backtraces in
4006 parts of the program that you don't plan to debug. This includes
4007 descriptions of functions and external variables, but no information
4008 about local variables and no line numbers.
4010 Level 3 includes extra information, such as all the macro definitions
4011 present in the program. Some debuggers support macro expansion when
4012 you use @option{-g3}.
4014 @option{-gdwarf-2} does not accept a concatenated debug level, because
4015 GCC used to support an option @option{-gdwarf} that meant to generate
4016 debug information in version 1 of the DWARF format (which is very
4017 different from version 2), and it would have been too confusing. That
4018 debug format is long obsolete, but the option cannot be changed now.
4019 Instead use an additional @option{-g@var{level}} option to change the
4020 debug level for DWARF2.
4022 @item -feliminate-dwarf2-dups
4023 @opindex feliminate-dwarf2-dups
4024 Compress DWARF2 debugging information by eliminating duplicated
4025 information about each symbol. This option only makes sense when
4026 generating DWARF2 debugging information with @option{-gdwarf-2}.
4028 @item -femit-struct-debug-baseonly
4029 Emit debug information for struct-like types
4030 only when the base name of the compilation source file
4031 matches the base name of file in which the struct was defined.
4033 This option substantially reduces the size of debugging information,
4034 but at significant potential loss in type information to the debugger.
4035 See @option{-femit-struct-debug-reduced} for a less aggressive option.
4036 See @option{-femit-struct-debug-detailed} for more detailed control.
4038 This option works only with DWARF 2.
4040 @item -femit-struct-debug-reduced
4041 Emit debug information for struct-like types
4042 only when the base name of the compilation source file
4043 matches the base name of file in which the type was defined,
4044 unless the struct is a template or defined in a system header.
4046 This option significantly reduces the size of debugging information,
4047 with some potential loss in type information to the debugger.
4048 See @option{-femit-struct-debug-baseonly} for a more aggressive option.
4049 See @option{-femit-struct-debug-detailed} for more detailed control.
4051 This option works only with DWARF 2.
4053 @item -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]}
4054 Specify the struct-like types
4055 for which the compiler will generate debug information.
4056 The intent is to reduce duplicate struct debug information
4057 between different object files within the same program.
4059 This option is a detailed version of
4060 @option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly},
4061 which will serve for most needs.
4063 A specification has the syntax
4064 [@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none})
4066 The optional first word limits the specification to
4067 structs that are used directly (@samp{dir:}) or used indirectly (@samp{ind:}).
4068 A struct type is used directly when it is the type of a variable, member.
4069 Indirect uses arise through pointers to structs.
4070 That is, when use of an incomplete struct would be legal, the use is indirect.
4072 @samp{struct one direct; struct two * indirect;}.
4074 The optional second word limits the specification to
4075 ordinary structs (@samp{ord:}) or generic structs (@samp{gen:}).
4076 Generic structs are a bit complicated to explain.
4077 For C++, these are non-explicit specializations of template classes,
4078 or non-template classes within the above.
4079 Other programming languages have generics,
4080 but @samp{-femit-struct-debug-detailed} does not yet implement them.
4082 The third word specifies the source files for those
4083 structs for which the compiler will emit debug information.
4084 The values @samp{none} and @samp{any} have the normal meaning.
4085 The value @samp{base} means that
4086 the base of name of the file in which the type declaration appears
4087 must match the base of the name of the main compilation file.
4088 In practice, this means that
4089 types declared in @file{foo.c} and @file{foo.h} will have debug information,
4090 but types declared in other header will not.
4091 The value @samp{sys} means those types satisfying @samp{base}
4092 or declared in system or compiler headers.
4094 You may need to experiment to determine the best settings for your application.
4096 The default is @samp{-femit-struct-debug-detailed=all}.
4098 This option works only with DWARF 2.
4100 @cindex @command{prof}
4103 Generate extra code to write profile information suitable for the
4104 analysis program @command{prof}. You must use this option when compiling
4105 the source files you want data about, and you must also use it when
4108 @cindex @command{gprof}
4111 Generate extra code to write profile information suitable for the
4112 analysis program @command{gprof}. You must use this option when compiling
4113 the source files you want data about, and you must also use it when
4118 Makes the compiler print out each function name as it is compiled, and
4119 print some statistics about each pass when it finishes.
4122 @opindex ftime-report
4123 Makes the compiler print some statistics about the time consumed by each
4124 pass when it finishes.
4127 @opindex fmem-report
4128 Makes the compiler print some statistics about permanent memory
4129 allocation when it finishes.
4131 @item -fpre-ipa-mem-report
4132 @opindex fpre-ipa-mem-report
4133 @item -fpost-ipa-mem-report
4134 @opindex fpost-ipa-mem-report
4135 Makes the compiler print some statistics about permanent memory
4136 allocation before or after interprocedural optimization.
4138 @item -fprofile-arcs
4139 @opindex fprofile-arcs
4140 Add code so that program flow @dfn{arcs} are instrumented. During
4141 execution the program records how many times each branch and call is
4142 executed and how many times it is taken or returns. When the compiled
4143 program exits it saves this data to a file called
4144 @file{@var{auxname}.gcda} for each source file. The data may be used for
4145 profile-directed optimizations (@option{-fbranch-probabilities}), or for
4146 test coverage analysis (@option{-ftest-coverage}). Each object file's
4147 @var{auxname} is generated from the name of the output file, if
4148 explicitly specified and it is not the final executable, otherwise it is
4149 the basename of the source file. In both cases any suffix is removed
4150 (e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
4151 @file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
4152 @xref{Cross-profiling}.
4154 @cindex @command{gcov}
4158 This option is used to compile and link code instrumented for coverage
4159 analysis. The option is a synonym for @option{-fprofile-arcs}
4160 @option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
4161 linking). See the documentation for those options for more details.
4166 Compile the source files with @option{-fprofile-arcs} plus optimization
4167 and code generation options. For test coverage analysis, use the
4168 additional @option{-ftest-coverage} option. You do not need to profile
4169 every source file in a program.
4172 Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
4173 (the latter implies the former).
4176 Run the program on a representative workload to generate the arc profile
4177 information. This may be repeated any number of times. You can run
4178 concurrent instances of your program, and provided that the file system
4179 supports locking, the data files will be correctly updated. Also
4180 @code{fork} calls are detected and correctly handled (double counting
4184 For profile-directed optimizations, compile the source files again with
4185 the same optimization and code generation options plus
4186 @option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
4187 Control Optimization}).
4190 For test coverage analysis, use @command{gcov} to produce human readable
4191 information from the @file{.gcno} and @file{.gcda} files. Refer to the
4192 @command{gcov} documentation for further information.
4196 With @option{-fprofile-arcs}, for each function of your program GCC
4197 creates a program flow graph, then finds a spanning tree for the graph.
4198 Only arcs that are not on the spanning tree have to be instrumented: the
4199 compiler adds code to count the number of times that these arcs are
4200 executed. When an arc is the only exit or only entrance to a block, the
4201 instrumentation code can be added to the block; otherwise, a new basic
4202 block must be created to hold the instrumentation code.
4205 @item -ftest-coverage
4206 @opindex ftest-coverage
4207 Produce a notes file that the @command{gcov} code-coverage utility
4208 (@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
4209 show program coverage. Each source file's note file is called
4210 @file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
4211 above for a description of @var{auxname} and instructions on how to
4212 generate test coverage data. Coverage data will match the source files
4213 more closely, if you do not optimize.
4215 @item -fdbg-cnt-list
4216 @opindex fdbg-cnt-list
4217 Print the name and the counter upperbound for all debug counters.
4219 @item -fdbg-cnt=@var{counter-value-list}
4221 Set the internal debug counter upperbound. @var{counter-value-list}
4222 is a comma-separated list of @var{name}:@var{value} pairs
4223 which sets the upperbound of each debug counter @var{name} to @var{value}.
4224 All debug counters have the initial upperbound of @var{UINT_MAX},
4225 thus dbg_cnt() returns true always unless the upperbound is set by this option.
4226 e.g. With -fdbg-cnt=dce:10,tail_call:0
4227 dbg_cnt(dce) will return true only for first 10 invocations
4228 and dbg_cnt(tail_call) will return false always.
4230 @item -d@var{letters}
4231 @item -fdump-rtl-@var{pass}
4233 Says to make debugging dumps during compilation at times specified by
4234 @var{letters}. This is used for debugging the RTL-based passes of the
4235 compiler. The file names for most of the dumps are made by appending a
4236 pass number and a word to the @var{dumpname}. @var{dumpname} is generated
4237 from the name of the output file, if explicitly specified and it is not
4238 an executable, otherwise it is the basename of the source file.
4240 Most debug dumps can be enabled either passing a letter to the @option{-d}
4241 option, or with a long @option{-fdump-rtl} switch; here are the possible
4242 letters for use in @var{letters} and @var{pass}, and their meanings:
4247 Annotate the assembler output with miscellaneous debugging information.
4250 @itemx -fdump-rtl-bbro
4252 @opindex fdump-rtl-bbro
4253 Dump after block reordering, to @file{@var{file}.148r.bbro}.
4256 @itemx -fdump-rtl-combine
4258 @opindex fdump-rtl-combine
4259 Dump after the RTL instruction combination pass, to the file
4260 @file{@var{file}.129r.combine}.
4263 @itemx -fdump-rtl-ce1
4264 @itemx -fdump-rtl-ce2
4266 @opindex fdump-rtl-ce1
4267 @opindex fdump-rtl-ce2
4268 @option{-dC} and @option{-fdump-rtl-ce1} enable dumping after the
4269 first if conversion, to the file @file{@var{file}.117r.ce1}. @option{-dC}
4270 and @option{-fdump-rtl-ce2} enable dumping after the second if
4271 conversion, to the file @file{@var{file}.130r.ce2}.
4274 @itemx -fdump-rtl-btl
4275 @itemx -fdump-rtl-dbr
4277 @opindex fdump-rtl-btl
4278 @opindex fdump-rtl-dbr
4279 @option{-dd} and @option{-fdump-rtl-btl} enable dumping after branch
4280 target load optimization, to @file{@var{file}.31.btl}. @option{-dd}
4281 and @option{-fdump-rtl-dbr} enable dumping after delayed branch
4282 scheduling, to @file{@var{file}.36.dbr}.
4286 Dump all macro definitions, at the end of preprocessing, in addition to
4290 @itemx -fdump-rtl-ce3
4292 @opindex fdump-rtl-ce3
4293 Dump after the third if conversion, to @file{@var{file}.146r.ce3}.
4296 @itemx -fdump-rtl-cfg
4297 @itemx -fdump-rtl-life
4299 @opindex fdump-rtl-cfg
4300 @opindex fdump-rtl-life
4301 @option{-df} and @option{-fdump-rtl-cfg} enable dumping after control
4302 and data flow analysis, to @file{@var{file}.116r.cfg}. @option{-df}
4303 and @option{-fdump-rtl-cfg} enable dumping dump after life analysis,
4304 to @file{@var{file}.128r.life1} and @file{@var{file}.135r.life2}.
4307 @itemx -fdump-rtl-greg
4309 @opindex fdump-rtl-greg
4310 Dump after global register allocation, to @file{@var{file}.139r.greg}.
4313 @itemx -fdump-rtl-gcse
4314 @itemx -fdump-rtl-bypass
4316 @opindex fdump-rtl-gcse
4317 @opindex fdump-rtl-bypass
4318 @option{-dG} and @option{-fdump-rtl-gcse} enable dumping after GCSE, to
4319 @file{@var{file}.114r.gcse}. @option{-dG} and @option{-fdump-rtl-bypass}
4320 enable dumping after jump bypassing and control flow optimizations, to
4321 @file{@var{file}.115r.bypass}.
4324 @itemx -fdump-rtl-eh
4326 @opindex fdump-rtl-eh
4327 Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
4330 @itemx -fdump-rtl-sibling
4332 @opindex fdump-rtl-sibling
4333 Dump after sibling call optimizations, to @file{@var{file}.106r.sibling}.
4336 @itemx -fdump-rtl-jump
4338 @opindex fdump-rtl-jump
4339 Dump after the first jump optimization, to @file{@var{file}.112r.jump}.
4342 @itemx -fdump-rtl-stack
4344 @opindex fdump-rtl-stack
4345 Dump after conversion from GCC's "flat register file" registers to the
4346 x87's stack-like registers, to @file{@var{file}.152r.stack}.
4349 @itemx -fdump-rtl-lreg
4351 @opindex fdump-rtl-lreg
4352 Dump after local register allocation, to @file{@var{file}.138r.lreg}.
4355 @itemx -fdump-rtl-loop2
4357 @opindex fdump-rtl-loop2
4358 @option{-dL} and @option{-fdump-rtl-loop2} enable dumping after the
4359 loop optimization pass, to @file{@var{file}.119r.loop2},
4360 @file{@var{file}.120r.loop2_init},
4361 @file{@var{file}.121r.loop2_invariant}, and
4362 @file{@var{file}.125r.loop2_done}.
4365 @itemx -fdump-rtl-sms
4367 @opindex fdump-rtl-sms
4368 Dump after modulo scheduling, to @file{@var{file}.136r.sms}.
4371 @itemx -fdump-rtl-mach
4373 @opindex fdump-rtl-mach
4374 Dump after performing the machine dependent reorganization pass, to
4375 @file{@var{file}.155r.mach}.
4378 @itemx -fdump-rtl-rnreg
4380 @opindex fdump-rtl-rnreg
4381 Dump after register renumbering, to @file{@var{file}.147r.rnreg}.
4384 @itemx -fdump-rtl-regmove
4386 @opindex fdump-rtl-regmove
4387 Dump after the register move pass, to @file{@var{file}.132r.regmove}.
4390 @itemx -fdump-rtl-postreload
4392 @opindex fdump-rtl-postreload
4393 Dump after post-reload optimizations, to @file{@var{file}.24.postreload}.
4396 @itemx -fdump-rtl-expand
4398 @opindex fdump-rtl-expand
4399 Dump after RTL generation, to @file{@var{file}.104r.expand}.
4402 @itemx -fdump-rtl-sched2
4404 @opindex fdump-rtl-sched2
4405 Dump after the second scheduling pass, to @file{@var{file}.149r.sched2}.
4408 @itemx -fdump-rtl-cse
4410 @opindex fdump-rtl-cse
4411 Dump after CSE (including the jump optimization that sometimes follows
4412 CSE), to @file{@var{file}.113r.cse}.
4415 @itemx -fdump-rtl-sched1
4417 @opindex fdump-rtl-sched1
4418 Dump after the first scheduling pass, to @file{@var{file}.136r.sched1}.
4421 @itemx -fdump-rtl-cse2
4423 @opindex fdump-rtl-cse2
4424 Dump after the second CSE pass (including the jump optimization that
4425 sometimes follows CSE), to @file{@var{file}.127r.cse2}.
4428 @itemx -fdump-rtl-tracer
4430 @opindex fdump-rtl-tracer
4431 Dump after running tracer, to @file{@var{file}.118r.tracer}.
4434 @itemx -fdump-rtl-vpt
4435 @itemx -fdump-rtl-vartrack
4437 @opindex fdump-rtl-vpt
4438 @opindex fdump-rtl-vartrack
4439 @option{-dV} and @option{-fdump-rtl-vpt} enable dumping after the value
4440 profile transformations, to @file{@var{file}.10.vpt}. @option{-dV}
4441 and @option{-fdump-rtl-vartrack} enable dumping after variable tracking,
4442 to @file{@var{file}.154r.vartrack}.
4445 @itemx -fdump-rtl-flow2
4447 @opindex fdump-rtl-flow2
4448 Dump after the second flow pass, to @file{@var{file}.142r.flow2}.
4451 @itemx -fdump-rtl-peephole2
4453 @opindex fdump-rtl-peephole2
4454 Dump after the peephole pass, to @file{@var{file}.145r.peephole2}.
4457 @itemx -fdump-rtl-web
4459 @opindex fdump-rtl-web
4460 Dump after live range splitting, to @file{@var{file}.126r.web}.
4463 @itemx -fdump-rtl-all
4465 @opindex fdump-rtl-all
4466 Produce all the dumps listed above.
4470 Produce a core dump whenever an error occurs.
4474 Print statistics on memory usage, at the end of the run, to
4479 Annotate the assembler output with a comment indicating which
4480 pattern and alternative was used. The length of each instruction is
4485 Dump the RTL in the assembler output as a comment before each instruction.
4486 Also turns on @option{-dp} annotation.
4490 For each of the other indicated dump files (either with @option{-d} or
4491 @option{-fdump-rtl-@var{pass}}), dump a representation of the control flow
4492 graph suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
4496 Just generate RTL for a function instead of compiling it. Usually used
4497 with @samp{r} (@option{-fdump-rtl-expand}).
4501 Dump debugging information during parsing, to standard error.
4505 @opindex fdump-noaddr
4506 When doing debugging dumps (see @option{-d} option above), suppress
4507 address output. This makes it more feasible to use diff on debugging
4508 dumps for compiler invocations with different compiler binaries and/or
4509 different text / bss / data / heap / stack / dso start locations.
4511 @item -fdump-unnumbered
4512 @opindex fdump-unnumbered
4513 When doing debugging dumps (see @option{-d} option above), suppress instruction
4514 numbers and address output. This makes it more feasible to
4515 use diff on debugging dumps for compiler invocations with different
4516 options, in particular with and without @option{-g}.
4518 @item -fdump-translation-unit @r{(C++ only)}
4519 @itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
4520 @opindex fdump-translation-unit
4521 Dump a representation of the tree structure for the entire translation
4522 unit to a file. The file name is made by appending @file{.tu} to the
4523 source file name. If the @samp{-@var{options}} form is used, @var{options}
4524 controls the details of the dump as described for the
4525 @option{-fdump-tree} options.
4527 @item -fdump-class-hierarchy @r{(C++ only)}
4528 @itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
4529 @opindex fdump-class-hierarchy
4530 Dump a representation of each class's hierarchy and virtual function
4531 table layout to a file. The file name is made by appending @file{.class}
4532 to the source file name. If the @samp{-@var{options}} form is used,
4533 @var{options} controls the details of the dump as described for the
4534 @option{-fdump-tree} options.
4536 @item -fdump-ipa-@var{switch}
4538 Control the dumping at various stages of inter-procedural analysis
4539 language tree to a file. The file name is generated by appending a switch
4540 specific suffix to the source file name. The following dumps are possible:
4544 Enables all inter-procedural analysis dumps; currently the only produced
4545 dump is the @samp{cgraph} dump.
4548 Dumps information about call-graph optimization, unused function removal,
4549 and inlining decisions.
4552 @item -fdump-tree-@var{switch}
4553 @itemx -fdump-tree-@var{switch}-@var{options}
4555 Control the dumping at various stages of processing the intermediate
4556 language tree to a file. The file name is generated by appending a switch
4557 specific suffix to the source file name. If the @samp{-@var{options}}
4558 form is used, @var{options} is a list of @samp{-} separated options that
4559 control the details of the dump. Not all options are applicable to all
4560 dumps, those which are not meaningful will be ignored. The following
4561 options are available
4565 Print the address of each node. Usually this is not meaningful as it
4566 changes according to the environment and source file. Its primary use
4567 is for tying up a dump file with a debug environment.
4569 Inhibit dumping of members of a scope or body of a function merely
4570 because that scope has been reached. Only dump such items when they
4571 are directly reachable by some other path. When dumping pretty-printed
4572 trees, this option inhibits dumping the bodies of control structures.
4574 Print a raw representation of the tree. By default, trees are
4575 pretty-printed into a C-like representation.
4577 Enable more detailed dumps (not honored by every dump option).
4579 Enable dumping various statistics about the pass (not honored by every dump
4582 Enable showing basic block boundaries (disabled in raw dumps).
4584 Enable showing virtual operands for every statement.
4586 Enable showing line numbers for statements.
4588 Enable showing the unique ID (@code{DECL_UID}) for each variable.
4590 Turn on all options, except @option{raw}, @option{slim} and @option{lineno}.
4593 The following tree dumps are possible:
4597 Dump before any tree based optimization, to @file{@var{file}.original}.
4600 Dump after all tree based optimization, to @file{@var{file}.optimized}.
4603 Dump after function inlining, to @file{@var{file}.inlined}.
4606 @opindex fdump-tree-gimple
4607 Dump each function before and after the gimplification pass to a file. The
4608 file name is made by appending @file{.gimple} to the source file name.
4611 @opindex fdump-tree-cfg
4612 Dump the control flow graph of each function to a file. The file name is
4613 made by appending @file{.cfg} to the source file name.
4616 @opindex fdump-tree-vcg
4617 Dump the control flow graph of each function to a file in VCG format. The
4618 file name is made by appending @file{.vcg} to the source file name. Note
4619 that if the file contains more than one function, the generated file cannot
4620 be used directly by VCG@. You will need to cut and paste each function's
4621 graph into its own separate file first.
4624 @opindex fdump-tree-ch
4625 Dump each function after copying loop headers. The file name is made by
4626 appending @file{.ch} to the source file name.
4629 @opindex fdump-tree-ssa
4630 Dump SSA related information to a file. The file name is made by appending
4631 @file{.ssa} to the source file name.
4634 @opindex fdump-tree-salias
4635 Dump structure aliasing variable information to a file. This file name
4636 is made by appending @file{.salias} to the source file name.
4639 @opindex fdump-tree-alias
4640 Dump aliasing information for each function. The file name is made by
4641 appending @file{.alias} to the source file name.
4644 @opindex fdump-tree-ccp
4645 Dump each function after CCP@. The file name is made by appending
4646 @file{.ccp} to the source file name.
4649 @opindex fdump-tree-storeccp
4650 Dump each function after STORE-CCP. The file name is made by appending
4651 @file{.storeccp} to the source file name.
4654 @opindex fdump-tree-pre
4655 Dump trees after partial redundancy elimination. The file name is made
4656 by appending @file{.pre} to the source file name.
4659 @opindex fdump-tree-fre
4660 Dump trees after full redundancy elimination. The file name is made
4661 by appending @file{.fre} to the source file name.
4664 @opindex fdump-tree-copyprop
4665 Dump trees after copy propagation. The file name is made
4666 by appending @file{.copyprop} to the source file name.
4668 @item store_copyprop
4669 @opindex fdump-tree-store_copyprop
4670 Dump trees after store copy-propagation. The file name is made
4671 by appending @file{.store_copyprop} to the source file name.
4674 @opindex fdump-tree-dce
4675 Dump each function after dead code elimination. The file name is made by
4676 appending @file{.dce} to the source file name.
4679 @opindex fdump-tree-mudflap
4680 Dump each function after adding mudflap instrumentation. The file name is
4681 made by appending @file{.mudflap} to the source file name.
4684 @opindex fdump-tree-sra
4685 Dump each function after performing scalar replacement of aggregates. The
4686 file name is made by appending @file{.sra} to the source file name.
4689 @opindex fdump-tree-sink
4690 Dump each function after performing code sinking. The file name is made
4691 by appending @file{.sink} to the source file name.
4694 @opindex fdump-tree-dom
4695 Dump each function after applying dominator tree optimizations. The file
4696 name is made by appending @file{.dom} to the source file name.
4699 @opindex fdump-tree-dse
4700 Dump each function after applying dead store elimination. The file
4701 name is made by appending @file{.dse} to the source file name.
4704 @opindex fdump-tree-phiopt
4705 Dump each function after optimizing PHI nodes into straightline code. The file
4706 name is made by appending @file{.phiopt} to the source file name.
4709 @opindex fdump-tree-forwprop
4710 Dump each function after forward propagating single use variables. The file
4711 name is made by appending @file{.forwprop} to the source file name.
4714 @opindex fdump-tree-copyrename
4715 Dump each function after applying the copy rename optimization. The file
4716 name is made by appending @file{.copyrename} to the source file name.
4719 @opindex fdump-tree-nrv
4720 Dump each function after applying the named return value optimization on
4721 generic trees. The file name is made by appending @file{.nrv} to the source
4725 @opindex fdump-tree-vect
4726 Dump each function after applying vectorization of loops. The file name is
4727 made by appending @file{.vect} to the source file name.
4730 @opindex fdump-tree-vrp
4731 Dump each function after Value Range Propagation (VRP). The file name
4732 is made by appending @file{.vrp} to the source file name.
4735 @opindex fdump-tree-all
4736 Enable all the available tree dumps with the flags provided in this option.
4739 @item -ftree-vectorizer-verbose=@var{n}
4740 @opindex ftree-vectorizer-verbose
4741 This option controls the amount of debugging output the vectorizer prints.
4742 This information is written to standard error, unless
4743 @option{-fdump-tree-all} or @option{-fdump-tree-vect} is specified,
4744 in which case it is output to the usual dump listing file, @file{.vect}.
4745 For @var{n}=0 no diagnostic information is reported.
4746 If @var{n}=1 the vectorizer reports each loop that got vectorized,
4747 and the total number of loops that got vectorized.
4748 If @var{n}=2 the vectorizer also reports non-vectorized loops that passed
4749 the first analysis phase (vect_analyze_loop_form) - i.e. countable,
4750 inner-most, single-bb, single-entry/exit loops. This is the same verbosity
4751 level that @option{-fdump-tree-vect-stats} uses.
4752 Higher verbosity levels mean either more information dumped for each
4753 reported loop, or same amount of information reported for more loops:
4754 If @var{n}=3, alignment related information is added to the reports.
4755 If @var{n}=4, data-references related information (e.g. memory dependences,
4756 memory access-patterns) is added to the reports.
4757 If @var{n}=5, the vectorizer reports also non-vectorized inner-most loops
4758 that did not pass the first analysis phase (i.e. may not be countable, or
4759 may have complicated control-flow).
4760 If @var{n}=6, the vectorizer reports also non-vectorized nested loops.
4761 For @var{n}=7, all the information the vectorizer generates during its
4762 analysis and transformation is reported. This is the same verbosity level
4763 that @option{-fdump-tree-vect-details} uses.
4765 @item -frandom-seed=@var{string}
4766 @opindex frandom-string
4767 This option provides a seed that GCC uses when it would otherwise use
4768 random numbers. It is used to generate certain symbol names
4769 that have to be different in every compiled file. It is also used to
4770 place unique stamps in coverage data files and the object files that
4771 produce them. You can use the @option{-frandom-seed} option to produce
4772 reproducibly identical object files.
4774 The @var{string} should be different for every file you compile.
4776 @item -fsched-verbose=@var{n}
4777 @opindex fsched-verbose
4778 On targets that use instruction scheduling, this option controls the
4779 amount of debugging output the scheduler prints. This information is
4780 written to standard error, unless @option{-dS} or @option{-dR} is
4781 specified, in which case it is output to the usual dump
4782 listing file, @file{.sched} or @file{.sched2} respectively. However
4783 for @var{n} greater than nine, the output is always printed to standard
4786 For @var{n} greater than zero, @option{-fsched-verbose} outputs the
4787 same information as @option{-dRS}. For @var{n} greater than one, it
4788 also output basic block probabilities, detailed ready list information
4789 and unit/insn info. For @var{n} greater than two, it includes RTL
4790 at abort point, control-flow and regions info. And for @var{n} over
4791 four, @option{-fsched-verbose} also includes dependence info.
4795 Store the usual ``temporary'' intermediate files permanently; place them
4796 in the current directory and name them based on the source file. Thus,
4797 compiling @file{foo.c} with @samp{-c -save-temps} would produce files
4798 @file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
4799 preprocessed @file{foo.i} output file even though the compiler now
4800 normally uses an integrated preprocessor.
4802 When used in combination with the @option{-x} command line option,
4803 @option{-save-temps} is sensible enough to avoid over writing an
4804 input source file with the same extension as an intermediate file.
4805 The corresponding intermediate file may be obtained by renaming the
4806 source file before using @option{-save-temps}.
4810 Report the CPU time taken by each subprocess in the compilation
4811 sequence. For C source files, this is the compiler proper and assembler
4812 (plus the linker if linking is done). The output looks like this:
4819 The first number on each line is the ``user time'', that is time spent
4820 executing the program itself. The second number is ``system time'',
4821 time spent executing operating system routines on behalf of the program.
4822 Both numbers are in seconds.
4824 @item -fvar-tracking
4825 @opindex fvar-tracking
4826 Run variable tracking pass. It computes where variables are stored at each
4827 position in code. Better debugging information is then generated
4828 (if the debugging information format supports this information).
4830 It is enabled by default when compiling with optimization (@option{-Os},
4831 @option{-O}, @option{-O2}, ...), debugging information (@option{-g}) and
4832 the debug info format supports it.
4834 @item -print-file-name=@var{library}
4835 @opindex print-file-name
4836 Print the full absolute name of the library file @var{library} that
4837 would be used when linking---and don't do anything else. With this
4838 option, GCC does not compile or link anything; it just prints the
4841 @item -print-multi-directory
4842 @opindex print-multi-directory
4843 Print the directory name corresponding to the multilib selected by any
4844 other switches present in the command line. This directory is supposed
4845 to exist in @env{GCC_EXEC_PREFIX}.
4847 @item -print-multi-lib
4848 @opindex print-multi-lib
4849 Print the mapping from multilib directory names to compiler switches
4850 that enable them. The directory name is separated from the switches by
4851 @samp{;}, and each switch starts with an @samp{@@} instead of the
4852 @samp{-}, without spaces between multiple switches. This is supposed to
4853 ease shell-processing.
4855 @item -print-prog-name=@var{program}
4856 @opindex print-prog-name
4857 Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
4859 @item -print-libgcc-file-name
4860 @opindex print-libgcc-file-name
4861 Same as @option{-print-file-name=libgcc.a}.
4863 This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
4864 but you do want to link with @file{libgcc.a}. You can do
4867 gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
4870 @item -print-search-dirs
4871 @opindex print-search-dirs
4872 Print the name of the configured installation directory and a list of
4873 program and library directories @command{gcc} will search---and don't do anything else.
4875 This is useful when @command{gcc} prints the error message
4876 @samp{installation problem, cannot exec cpp0: No such file or directory}.
4877 To resolve this you either need to put @file{cpp0} and the other compiler
4878 components where @command{gcc} expects to find them, or you can set the environment
4879 variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
4880 Don't forget the trailing @samp{/}.
4881 @xref{Environment Variables}.
4883 @item -print-sysroot-headers-suffix
4884 @opindex print-sysroot-headers-suffix
4885 Print the suffix added to the target sysroot when searching for
4886 headers, or give an error if the compiler is not configured with such
4887 a suffix---and don't do anything else.
4890 @opindex dumpmachine
4891 Print the compiler's target machine (for example,
4892 @samp{i686-pc-linux-gnu})---and don't do anything else.
4895 @opindex dumpversion
4896 Print the compiler version (for example, @samp{3.0})---and don't do
4901 Print the compiler's built-in specs---and don't do anything else. (This
4902 is used when GCC itself is being built.) @xref{Spec Files}.
4904 @item -feliminate-unused-debug-types
4905 @opindex feliminate-unused-debug-types
4906 Normally, when producing DWARF2 output, GCC will emit debugging
4907 information for all types declared in a compilation
4908 unit, regardless of whether or not they are actually used
4909 in that compilation unit. Sometimes this is useful, such as
4910 if, in the debugger, you want to cast a value to a type that is
4911 not actually used in your program (but is declared). More often,
4912 however, this results in a significant amount of wasted space.
4913 With this option, GCC will avoid producing debug symbol output
4914 for types that are nowhere used in the source file being compiled.
4917 @node Optimize Options
4918 @section Options That Control Optimization
4919 @cindex optimize options
4920 @cindex options, optimization
4922 These options control various sorts of optimizations.
4924 Without any optimization option, the compiler's goal is to reduce the
4925 cost of compilation and to make debugging produce the expected
4926 results. Statements are independent: if you stop the program with a
4927 breakpoint between statements, you can then assign a new value to any
4928 variable or change the program counter to any other statement in the
4929 function and get exactly the results you would expect from the source
4932 Turning on optimization flags makes the compiler attempt to improve
4933 the performance and/or code size at the expense of compilation time
4934 and possibly the ability to debug the program.
4936 The compiler performs optimization based on the knowledge it has of
4937 the program. Optimization levels @option{-O} and above, in
4938 particular, enable @emph{unit-at-a-time} mode, which allows the
4939 compiler to consider information gained from later functions in
4940 the file when compiling a function. Compiling multiple files at
4941 once to a single output file in @emph{unit-at-a-time} mode allows
4942 the compiler to use information gained from all of the files when
4943 compiling each of them.
4945 Not all optimizations are controlled directly by a flag. Only
4946 optimizations that have a flag are listed.
4953 Optimize. Optimizing compilation takes somewhat more time, and a lot
4954 more memory for a large function.
4956 With @option{-O}, the compiler tries to reduce code size and execution
4957 time, without performing any optimizations that take a great deal of
4960 @option{-O} turns on the following optimization flags:
4961 @gccoptlist{-fdefer-pop @gol
4962 -fdelayed-branch @gol
4963 -fguess-branch-probability @gol
4964 -fcprop-registers @gol
4965 -fif-conversion @gol
4966 -fif-conversion2 @gol
4967 -fsplit-wide-types @gol
4970 -ftree-dominator-opts @gol
4974 -ftree-copyrename @gol
4977 -funit-at-a-time @gol
4980 @option{-O} also turns on @option{-fomit-frame-pointer} on machines
4981 where doing so does not interfere with debugging.
4985 Optimize even more. GCC performs nearly all supported optimizations
4986 that do not involve a space-speed tradeoff. The compiler does not
4987 perform loop unrolling or function inlining when you specify @option{-O2}.
4988 As compared to @option{-O}, this option increases both compilation time
4989 and the performance of the generated code.
4991 @option{-O2} turns on all optimization flags specified by @option{-O}. It
4992 also turns on the following optimization flags:
4993 @gccoptlist{-fthread-jumps @gol
4995 -foptimize-sibling-calls @gol
4996 -fcse-follow-jumps -fcse-skip-blocks @gol
4997 -fgcse -fgcse-lm @gol
4998 -fexpensive-optimizations @gol
4999 -frerun-cse-after-loop @gol
5002 -fschedule-insns -fschedule-insns2 @gol
5003 -fsched-interblock -fsched-spec @gol
5005 -fstrict-aliasing -fstrict-overflow @gol
5006 -fdelete-null-pointer-checks @gol
5007 -freorder-blocks -freorder-functions @gol
5008 -falign-functions -falign-jumps @gol
5009 -falign-loops -falign-labels @gol
5013 Please note the warning under @option{-fgcse} about
5014 invoking @option{-O2} on programs that use computed gotos.
5018 Optimize yet more. @option{-O3} turns on all optimizations specified by
5019 @option{-O2} and also turns on the @option{-finline-functions},
5020 @option{-funswitch-loops}, @option{-fpredictive-commoning} and
5021 @option{-fgcse-after-reload} options.
5025 Reduce compilation time and make debugging produce the expected
5026 results. This is the default.
5030 Optimize for size. @option{-Os} enables all @option{-O2} optimizations that
5031 do not typically increase code size. It also performs further
5032 optimizations designed to reduce code size.
5034 @option{-Os} disables the following optimization flags:
5035 @gccoptlist{-falign-functions -falign-jumps -falign-loops @gol
5036 -falign-labels -freorder-blocks -freorder-blocks-and-partition @gol
5037 -fprefetch-loop-arrays -ftree-vect-loop-version}
5039 If you use multiple @option{-O} options, with or without level numbers,
5040 the last such option is the one that is effective.
5043 Options of the form @option{-f@var{flag}} specify machine-independent
5044 flags. Most flags have both positive and negative forms; the negative
5045 form of @option{-ffoo} would be @option{-fno-foo}. In the table
5046 below, only one of the forms is listed---the one you typically will
5047 use. You can figure out the other form by either removing @samp{no-}
5050 The following options control specific optimizations. They are either
5051 activated by @option{-O} options or are related to ones that are. You
5052 can use the following flags in the rare cases when ``fine-tuning'' of
5053 optimizations to be performed is desired.
5056 @item -fno-default-inline
5057 @opindex fno-default-inline
5058 Do not make member functions inline by default merely because they are
5059 defined inside the class scope (C++ only). Otherwise, when you specify
5060 @w{@option{-O}}, member functions defined inside class scope are compiled
5061 inline by default; i.e., you don't need to add @samp{inline} in front of
5062 the member function name.
5064 @item -fno-defer-pop
5065 @opindex fno-defer-pop
5066 Always pop the arguments to each function call as soon as that function
5067 returns. For machines which must pop arguments after a function call,
5068 the compiler normally lets arguments accumulate on the stack for several
5069 function calls and pops them all at once.
5071 Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5074 @opindex fforce-addr
5075 Force memory address constants to be copied into registers before
5076 doing arithmetic on them.
5078 @item -fforward-propagate
5079 @opindex fforward-propagate
5080 Perform a forward propagation pass on RTL. The pass tries to combine two
5081 instructions and checks if the result can be simplified. If loop unrolling
5082 is active, two passes are performed and the second is scheduled after
5085 This option is enabled by default at optimization levels @option{-O2},
5086 @option{-O3}, @option{-Os}.
5088 @item -fomit-frame-pointer
5089 @opindex fomit-frame-pointer
5090 Don't keep the frame pointer in a register for functions that
5091 don't need one. This avoids the instructions to save, set up and
5092 restore frame pointers; it also makes an extra register available
5093 in many functions. @strong{It also makes debugging impossible on
5096 On some machines, such as the VAX, this flag has no effect, because
5097 the standard calling sequence automatically handles the frame pointer
5098 and nothing is saved by pretending it doesn't exist. The
5099 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
5100 whether a target machine supports this flag. @xref{Registers,,Register
5101 Usage, gccint, GNU Compiler Collection (GCC) Internals}.
5103 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5105 @item -foptimize-sibling-calls
5106 @opindex foptimize-sibling-calls
5107 Optimize sibling and tail recursive calls.
5109 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5113 Don't pay attention to the @code{inline} keyword. Normally this option
5114 is used to keep the compiler from expanding any functions inline.
5115 Note that if you are not optimizing, no functions can be expanded inline.
5117 @item -finline-functions
5118 @opindex finline-functions
5119 Integrate all simple functions into their callers. The compiler
5120 heuristically decides which functions are simple enough to be worth
5121 integrating in this way.
5123 If all calls to a given function are integrated, and the function is
5124 declared @code{static}, then the function is normally not output as
5125 assembler code in its own right.
5127 Enabled at level @option{-O3}.
5129 @item -finline-functions-called-once
5130 @opindex finline-functions-called-once
5131 Consider all @code{static} functions called once for inlining into their
5132 caller even if they are not marked @code{inline}. If a call to a given
5133 function is integrated, then the function is not output as assembler code
5136 Enabled if @option{-funit-at-a-time} is enabled.
5138 @item -fearly-inlining
5139 @opindex fearly-inlining
5140 Inline functions marked by @code{always_inline} and functions whose body seems
5141 smaller than the function call overhead early before doing
5142 @option{-fprofile-generate} instrumentation and real inlining pass. Doing so
5143 makes profiling significantly cheaper and usually inlining faster on programs
5144 having large chains of nested wrapper functions.
5148 @item -finline-limit=@var{n}
5149 @opindex finline-limit
5150 By default, GCC limits the size of functions that can be inlined. This flag
5151 allows the control of this limit for functions that are explicitly marked as
5152 inline (i.e., marked with the inline keyword or defined within the class
5153 definition in c++). @var{n} is the size of functions that can be inlined in
5154 number of pseudo instructions (not counting parameter handling). The default
5155 value of @var{n} is 600.
5156 Increasing this value can result in more inlined code at
5157 the cost of compilation time and memory consumption. Decreasing usually makes
5158 the compilation faster and less code will be inlined (which presumably
5159 means slower programs). This option is particularly useful for programs that
5160 use inlining heavily such as those based on recursive templates with C++.
5162 Inlining is actually controlled by a number of parameters, which may be
5163 specified individually by using @option{--param @var{name}=@var{value}}.
5164 The @option{-finline-limit=@var{n}} option sets some of these parameters
5168 @item max-inline-insns-single
5169 is set to @var{n}/2.
5170 @item max-inline-insns-auto
5171 is set to @var{n}/2.
5172 @item min-inline-insns
5173 is set to 130 or @var{n}/4, whichever is smaller.
5174 @item max-inline-insns-rtl
5178 See below for a documentation of the individual
5179 parameters controlling inlining.
5181 @emph{Note:} pseudo instruction represents, in this particular context, an
5182 abstract measurement of function's size. In no way does it represent a count
5183 of assembly instructions and as such its exact meaning might change from one
5184 release to an another.
5186 @item -fkeep-inline-functions
5187 @opindex fkeep-inline-functions
5188 In C, emit @code{static} functions that are declared @code{inline}
5189 into the object file, even if the function has been inlined into all
5190 of its callers. This switch does not affect functions using the
5191 @code{extern inline} extension in GNU C89@. In C++, emit any and all
5192 inline functions into the object file.
5194 @item -fkeep-static-consts
5195 @opindex fkeep-static-consts
5196 Emit variables declared @code{static const} when optimization isn't turned
5197 on, even if the variables aren't referenced.
5199 GCC enables this option by default. If you want to force the compiler to
5200 check if the variable was referenced, regardless of whether or not
5201 optimization is turned on, use the @option{-fno-keep-static-consts} option.
5203 @item -fmerge-constants
5204 Attempt to merge identical constants (string constants and floating point
5205 constants) across compilation units.
5207 This option is the default for optimized compilation if the assembler and
5208 linker support it. Use @option{-fno-merge-constants} to inhibit this
5211 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5213 @item -fmerge-all-constants
5214 Attempt to merge identical constants and identical variables.
5216 This option implies @option{-fmerge-constants}. In addition to
5217 @option{-fmerge-constants} this considers e.g.@: even constant initialized
5218 arrays or initialized constant variables with integral or floating point
5219 types. Languages like C or C++ require each non-automatic variable to
5220 have distinct location, so using this option will result in non-conforming
5223 @item -fmodulo-sched
5224 @opindex fmodulo-sched
5225 Perform swing modulo scheduling immediately before the first scheduling
5226 pass. This pass looks at innermost loops and reorders their
5227 instructions by overlapping different iterations.
5229 @item -fno-branch-count-reg
5230 @opindex fno-branch-count-reg
5231 Do not use ``decrement and branch'' instructions on a count register,
5232 but instead generate a sequence of instructions that decrement a
5233 register, compare it against zero, then branch based upon the result.
5234 This option is only meaningful on architectures that support such
5235 instructions, which include x86, PowerPC, IA-64 and S/390.
5237 The default is @option{-fbranch-count-reg}.
5239 @item -fno-function-cse
5240 @opindex fno-function-cse
5241 Do not put function addresses in registers; make each instruction that
5242 calls a constant function contain the function's address explicitly.
5244 This option results in less efficient code, but some strange hacks
5245 that alter the assembler output may be confused by the optimizations
5246 performed when this option is not used.
5248 The default is @option{-ffunction-cse}
5250 @item -fno-zero-initialized-in-bss
5251 @opindex fno-zero-initialized-in-bss
5252 If the target supports a BSS section, GCC by default puts variables that
5253 are initialized to zero into BSS@. This can save space in the resulting
5256 This option turns off this behavior because some programs explicitly
5257 rely on variables going to the data section. E.g., so that the
5258 resulting executable can find the beginning of that section and/or make
5259 assumptions based on that.
5261 The default is @option{-fzero-initialized-in-bss}.
5263 @item -fbounds-check
5264 @opindex fbounds-check
5265 For front-ends that support it, generate additional code to check that
5266 indices used to access arrays are within the declared range. This is
5267 currently only supported by the Java and Fortran front-ends, where
5268 this option defaults to true and false respectively.
5270 @item -fmudflap -fmudflapth -fmudflapir
5274 @cindex bounds checking
5276 For front-ends that support it (C and C++), instrument all risky
5277 pointer/array dereferencing operations, some standard library
5278 string/heap functions, and some other associated constructs with
5279 range/validity tests. Modules so instrumented should be immune to
5280 buffer overflows, invalid heap use, and some other classes of C/C++
5281 programming errors. The instrumentation relies on a separate runtime
5282 library (@file{libmudflap}), which will be linked into a program if
5283 @option{-fmudflap} is given at link time. Run-time behavior of the
5284 instrumented program is controlled by the @env{MUDFLAP_OPTIONS}
5285 environment variable. See @code{env MUDFLAP_OPTIONS=-help a.out}
5288 Use @option{-fmudflapth} instead of @option{-fmudflap} to compile and to
5289 link if your program is multi-threaded. Use @option{-fmudflapir}, in
5290 addition to @option{-fmudflap} or @option{-fmudflapth}, if
5291 instrumentation should ignore pointer reads. This produces less
5292 instrumentation (and therefore faster execution) and still provides
5293 some protection against outright memory corrupting writes, but allows
5294 erroneously read data to propagate within a program.
5296 @item -fthread-jumps
5297 @opindex fthread-jumps
5298 Perform optimizations where we check to see if a jump branches to a
5299 location where another comparison subsumed by the first is found. If
5300 so, the first branch is redirected to either the destination of the
5301 second branch or a point immediately following it, depending on whether
5302 the condition is known to be true or false.
5304 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5306 @item -fsplit-wide-types
5307 @opindex fsplit-wide-types
5308 When using a type that occupies multiple registers, such as @code{long
5309 long} on a 32-bit system, split the registers apart and allocate them
5310 independently. This normally generates better code for those types,
5311 but may make debugging more difficult.
5313 Enabled at levels @option{-O}, @option{-O2}, @option{-O3},
5316 @item -fcse-follow-jumps
5317 @opindex fcse-follow-jumps
5318 In common subexpression elimination, scan through jump instructions
5319 when the target of the jump is not reached by any other path. For
5320 example, when CSE encounters an @code{if} statement with an
5321 @code{else} clause, CSE will follow the jump when the condition
5324 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5326 @item -fcse-skip-blocks
5327 @opindex fcse-skip-blocks
5328 This is similar to @option{-fcse-follow-jumps}, but causes CSE to
5329 follow jumps which conditionally skip over blocks. When CSE
5330 encounters a simple @code{if} statement with no else clause,
5331 @option{-fcse-skip-blocks} causes CSE to follow the jump around the
5332 body of the @code{if}.
5334 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5336 @item -frerun-cse-after-loop
5337 @opindex frerun-cse-after-loop
5338 Re-run common subexpression elimination after loop optimizations has been
5341 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5345 Perform a global common subexpression elimination pass.
5346 This pass also performs global constant and copy propagation.
5348 @emph{Note:} When compiling a program using computed gotos, a GCC
5349 extension, you may get better runtime performance if you disable
5350 the global common subexpression elimination pass by adding
5351 @option{-fno-gcse} to the command line.
5353 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5357 When @option{-fgcse-lm} is enabled, global common subexpression elimination will
5358 attempt to move loads which are only killed by stores into themselves. This
5359 allows a loop containing a load/store sequence to be changed to a load outside
5360 the loop, and a copy/store within the loop.
5362 Enabled by default when gcse is enabled.
5366 When @option{-fgcse-sm} is enabled, a store motion pass is run after
5367 global common subexpression elimination. This pass will attempt to move
5368 stores out of loops. When used in conjunction with @option{-fgcse-lm},
5369 loops containing a load/store sequence can be changed to a load before
5370 the loop and a store after the loop.
5372 Not enabled at any optimization level.
5376 When @option{-fgcse-las} is enabled, the global common subexpression
5377 elimination pass eliminates redundant loads that come after stores to the
5378 same memory location (both partial and full redundancies).
5380 Not enabled at any optimization level.
5382 @item -fgcse-after-reload
5383 @opindex fgcse-after-reload
5384 When @option{-fgcse-after-reload} is enabled, a redundant load elimination
5385 pass is performed after reload. The purpose of this pass is to cleanup
5388 @item -funsafe-loop-optimizations
5389 @opindex funsafe-loop-optimizations
5390 If given, the loop optimizer will assume that loop indices do not
5391 overflow, and that the loops with nontrivial exit condition are not
5392 infinite. This enables a wider range of loop optimizations even if
5393 the loop optimizer itself cannot prove that these assumptions are valid.
5394 Using @option{-Wunsafe-loop-optimizations}, the compiler will warn you
5395 if it finds this kind of loop.
5397 @item -fcrossjumping
5398 @opindex crossjumping
5399 Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
5400 resulting code may or may not perform better than without cross-jumping.
5402 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5404 @item -fif-conversion
5405 @opindex if-conversion
5406 Attempt to transform conditional jumps into branch-less equivalents. This
5407 include use of conditional moves, min, max, set flags and abs instructions, and
5408 some tricks doable by standard arithmetics. The use of conditional execution
5409 on chips where it is available is controlled by @code{if-conversion2}.
5411 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5413 @item -fif-conversion2
5414 @opindex if-conversion2
5415 Use conditional execution (where available) to transform conditional jumps into
5416 branch-less equivalents.
5418 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5420 @item -fdelete-null-pointer-checks
5421 @opindex fdelete-null-pointer-checks
5422 Use global dataflow analysis to identify and eliminate useless checks
5423 for null pointers. The compiler assumes that dereferencing a null
5424 pointer would have halted the program. If a pointer is checked after
5425 it has already been dereferenced, it cannot be null.
5427 In some environments, this assumption is not true, and programs can
5428 safely dereference null pointers. Use
5429 @option{-fno-delete-null-pointer-checks} to disable this optimization
5430 for programs which depend on that behavior.
5432 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5434 @item -fexpensive-optimizations
5435 @opindex fexpensive-optimizations
5436 Perform a number of minor optimizations that are relatively expensive.
5438 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5440 @item -foptimize-register-move
5442 @opindex foptimize-register-move
5444 Attempt to reassign register numbers in move instructions and as
5445 operands of other simple instructions in order to maximize the amount of
5446 register tying. This is especially helpful on machines with two-operand
5449 Note @option{-fregmove} and @option{-foptimize-register-move} are the same
5452 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5454 @item -fdelayed-branch
5455 @opindex fdelayed-branch
5456 If supported for the target machine, attempt to reorder instructions
5457 to exploit instruction slots available after delayed branch
5460 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5462 @item -fschedule-insns
5463 @opindex fschedule-insns
5464 If supported for the target machine, attempt to reorder instructions to
5465 eliminate execution stalls due to required data being unavailable. This
5466 helps machines that have slow floating point or memory load instructions
5467 by allowing other instructions to be issued until the result of the load
5468 or floating point instruction is required.
5470 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5472 @item -fschedule-insns2
5473 @opindex fschedule-insns2
5474 Similar to @option{-fschedule-insns}, but requests an additional pass of
5475 instruction scheduling after register allocation has been done. This is
5476 especially useful on machines with a relatively small number of
5477 registers and where memory load instructions take more than one cycle.
5479 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5481 @item -fno-sched-interblock
5482 @opindex fno-sched-interblock
5483 Don't schedule instructions across basic blocks. This is normally
5484 enabled by default when scheduling before register allocation, i.e.@:
5485 with @option{-fschedule-insns} or at @option{-O2} or higher.
5487 @item -fno-sched-spec
5488 @opindex fno-sched-spec
5489 Don't allow speculative motion of non-load instructions. This is normally
5490 enabled by default when scheduling before register allocation, i.e.@:
5491 with @option{-fschedule-insns} or at @option{-O2} or higher.
5493 @item -fsched-spec-load
5494 @opindex fsched-spec-load
5495 Allow speculative motion of some load instructions. This only makes
5496 sense when scheduling before register allocation, i.e.@: with
5497 @option{-fschedule-insns} or at @option{-O2} or higher.
5499 @item -fsched-spec-load-dangerous
5500 @opindex fsched-spec-load-dangerous
5501 Allow speculative motion of more load instructions. This only makes
5502 sense when scheduling before register allocation, i.e.@: with
5503 @option{-fschedule-insns} or at @option{-O2} or higher.
5505 @item -fsched-stalled-insns=@var{n}
5506 @opindex fsched-stalled-insns
5507 Define how many insns (if any) can be moved prematurely from the queue
5508 of stalled insns into the ready list, during the second scheduling pass.
5510 @item -fsched-stalled-insns-dep=@var{n}
5511 @opindex fsched-stalled-insns-dep
5512 Define how many insn groups (cycles) will be examined for a dependency
5513 on a stalled insn that is candidate for premature removal from the queue
5514 of stalled insns. Has an effect only during the second scheduling pass,
5515 and only if @option{-fsched-stalled-insns} is used and its value is not zero.
5517 @item -fsched2-use-superblocks
5518 @opindex fsched2-use-superblocks
5519 When scheduling after register allocation, do use superblock scheduling
5520 algorithm. Superblock scheduling allows motion across basic block boundaries
5521 resulting on faster schedules. This option is experimental, as not all machine
5522 descriptions used by GCC model the CPU closely enough to avoid unreliable
5523 results from the algorithm.
5525 This only makes sense when scheduling after register allocation, i.e.@: with
5526 @option{-fschedule-insns2} or at @option{-O2} or higher.
5528 @item -fsched2-use-traces
5529 @opindex fsched2-use-traces
5530 Use @option{-fsched2-use-superblocks} algorithm when scheduling after register
5531 allocation and additionally perform code duplication in order to increase the
5532 size of superblocks using tracer pass. See @option{-ftracer} for details on
5535 This mode should produce faster but significantly longer programs. Also
5536 without @option{-fbranch-probabilities} the traces constructed may not
5537 match the reality and hurt the performance. This only makes
5538 sense when scheduling after register allocation, i.e.@: with
5539 @option{-fschedule-insns2} or at @option{-O2} or higher.
5543 Eliminates redundant extension instructions and move the non redundant
5544 ones to optimal placement using LCM.
5546 @item -freschedule-modulo-scheduled-loops
5547 @opindex fscheduling-in-modulo-scheduled-loops
5548 The modulo scheduling comes before the traditional scheduling, if a loop was modulo scheduled
5549 we may want to prevent the later scheduling passes from changing its schedule, we use this
5550 option to control that.
5552 @item -fcaller-saves
5553 @opindex fcaller-saves
5554 Enable values to be allocated in registers that will be clobbered by
5555 function calls, by emitting extra instructions to save and restore the
5556 registers around such calls. Such allocation is done only when it
5557 seems to result in better code than would otherwise be produced.
5559 This option is always enabled by default on certain machines, usually
5560 those which have no call-preserved registers to use instead.
5562 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5565 Perform Partial Redundancy Elimination (PRE) on trees. This flag is
5566 enabled by default at @option{-O2} and @option{-O3}.
5569 Perform Full Redundancy Elimination (FRE) on trees. The difference
5570 between FRE and PRE is that FRE only considers expressions
5571 that are computed on all paths leading to the redundant computation.
5572 This analysis is faster than PRE, though it exposes fewer redundancies.
5573 This flag is enabled by default at @option{-O} and higher.
5575 @item -ftree-copy-prop
5576 Perform copy propagation on trees. This pass eliminates unnecessary
5577 copy operations. This flag is enabled by default at @option{-O} and
5580 @item -ftree-store-copy-prop
5581 Perform copy propagation of memory loads and stores. This pass
5582 eliminates unnecessary copy operations in memory references
5583 (structures, global variables, arrays, etc). This flag is enabled by
5584 default at @option{-O2} and higher.
5587 Perform structural alias analysis on trees. This flag
5588 is enabled by default at @option{-O} and higher.
5591 Perform interprocedural pointer analysis.
5594 Perform forward store motion on trees. This flag is
5595 enabled by default at @option{-O} and higher.
5598 Perform sparse conditional constant propagation (CCP) on trees. This
5599 pass only operates on local scalar variables and is enabled by default
5600 at @option{-O} and higher.
5602 @item -ftree-store-ccp
5603 Perform sparse conditional constant propagation (CCP) on trees. This
5604 pass operates on both local scalar variables and memory stores and
5605 loads (global variables, structures, arrays, etc). This flag is
5606 enabled by default at @option{-O2} and higher.
5609 Perform dead code elimination (DCE) on trees. This flag is enabled by
5610 default at @option{-O} and higher.
5612 @item -ftree-dominator-opts
5613 Perform a variety of simple scalar cleanups (constant/copy
5614 propagation, redundancy elimination, range propagation and expression
5615 simplification) based on a dominator tree traversal. This also
5616 performs jump threading (to reduce jumps to jumps). This flag is
5617 enabled by default at @option{-O} and higher.
5620 Perform loop header copying on trees. This is beneficial since it increases
5621 effectiveness of code motion optimizations. It also saves one jump. This flag
5622 is enabled by default at @option{-O} and higher. It is not enabled
5623 for @option{-Os}, since it usually increases code size.
5625 @item -ftree-loop-optimize
5626 Perform loop optimizations on trees. This flag is enabled by default
5627 at @option{-O} and higher.
5629 @item -ftree-loop-linear
5630 Perform linear loop transformations on tree. This flag can improve cache
5631 performance and allow further loop optimizations to take place.
5633 @item -fcheck-data-deps
5634 Compare the results of several data dependence analyzers. This option
5635 is used for debugging the data dependence analyzers.
5637 @item -ftree-loop-im
5638 Perform loop invariant motion on trees. This pass moves only invariants that
5639 would be hard to handle at RTL level (function calls, operations that expand to
5640 nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
5641 operands of conditions that are invariant out of the loop, so that we can use
5642 just trivial invariantness analysis in loop unswitching. The pass also includes
5645 @item -ftree-loop-ivcanon
5646 Create a canonical counter for number of iterations in the loop for that
5647 determining number of iterations requires complicated analysis. Later
5648 optimizations then may determine the number easily. Useful especially
5649 in connection with unrolling.
5652 Perform induction variable optimizations (strength reduction, induction
5653 variable merging and induction variable elimination) on trees.
5656 Perform scalar replacement of aggregates. This pass replaces structure
5657 references with scalars to prevent committing structures to memory too
5658 early. This flag is enabled by default at @option{-O} and higher.
5660 @item -ftree-copyrename
5661 Perform copy renaming on trees. This pass attempts to rename compiler
5662 temporaries to other variables at copy locations, usually resulting in
5663 variable names which more closely resemble the original variables. This flag
5664 is enabled by default at @option{-O} and higher.
5667 Perform temporary expression replacement during the SSA->normal phase. Single
5668 use/single def temporaries are replaced at their use location with their
5669 defining expression. This results in non-GIMPLE code, but gives the expanders
5670 much more complex trees to work on resulting in better RTL generation. This is
5671 enabled by default at @option{-O} and higher.
5673 @item -ftree-vectorize
5674 Perform loop vectorization on trees.
5676 @item -ftree-vect-loop-version
5677 @opindex ftree-vect-loop-version
5678 Perform loop versioning when doing loop vectorization on trees. When a loop
5679 appears to be vectorizable except that data alignment or data dependence cannot
5680 be determined at compile time then vectorized and non-vectorized versions of
5681 the loop are generated along with runtime checks for alignment or dependence
5682 to control which version is executed. This option is enabled by default
5683 except at level @option{-Os} where it is disabled.
5685 @item -fvect-cost-model
5686 Enable cost model for vectorization.
5689 Perform Value Range Propagation on trees. This is similar to the
5690 constant propagation pass, but instead of values, ranges of values are
5691 propagated. This allows the optimizers to remove unnecessary range
5692 checks like array bound checks and null pointer checks. This is
5693 enabled by default at @option{-O2} and higher. Null pointer check
5694 elimination is only done if @option{-fdelete-null-pointer-checks} is
5699 Perform tail duplication to enlarge superblock size. This transformation
5700 simplifies the control flow of the function allowing other optimizations to do
5703 @item -funroll-loops
5704 @opindex funroll-loops
5705 Unroll loops whose number of iterations can be determined at compile
5706 time or upon entry to the loop. @option{-funroll-loops} implies
5707 @option{-frerun-cse-after-loop}. This option makes code larger,
5708 and may or may not make it run faster.
5710 @item -funroll-all-loops
5711 @opindex funroll-all-loops
5712 Unroll all loops, even if their number of iterations is uncertain when
5713 the loop is entered. This usually makes programs run more slowly.
5714 @option{-funroll-all-loops} implies the same options as
5715 @option{-funroll-loops},
5717 @item -fsplit-ivs-in-unroller
5718 @opindex fsplit-ivs-in-unroller
5719 Enables expressing of values of induction variables in later iterations
5720 of the unrolled loop using the value in the first iteration. This breaks
5721 long dependency chains, thus improving efficiency of the scheduling passes.
5723 Combination of @option{-fweb} and CSE is often sufficient to obtain the
5724 same effect. However in cases the loop body is more complicated than
5725 a single basic block, this is not reliable. It also does not work at all
5726 on some of the architectures due to restrictions in the CSE pass.
5728 This optimization is enabled by default.
5730 @item -fvariable-expansion-in-unroller
5731 @opindex fvariable-expansion-in-unroller
5732 With this option, the compiler will create multiple copies of some
5733 local variables when unrolling a loop which can result in superior code.
5735 @item -fpredictive-commoning
5736 @opindex fpredictive-commoning
5737 Perform predictive commoning optimization, i.e., reusing computations
5738 (especially memory loads and stores) performed in previous
5739 iterations of loops.
5741 This option is enabled at level @option{-O3}.
5743 @item -fprefetch-loop-arrays
5744 @opindex fprefetch-loop-arrays
5745 If supported by the target machine, generate instructions to prefetch
5746 memory to improve the performance of loops that access large arrays.
5748 This option may generate better or worse code; results are highly
5749 dependent on the structure of loops within the source code.
5751 Disabled at level @option{-Os}.
5754 @itemx -fno-peephole2
5755 @opindex fno-peephole
5756 @opindex fno-peephole2
5757 Disable any machine-specific peephole optimizations. The difference
5758 between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
5759 are implemented in the compiler; some targets use one, some use the
5760 other, a few use both.
5762 @option{-fpeephole} is enabled by default.
5763 @option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5765 @item -fno-guess-branch-probability
5766 @opindex fno-guess-branch-probability
5767 Do not guess branch probabilities using heuristics.
5769 GCC will use heuristics to guess branch probabilities if they are
5770 not provided by profiling feedback (@option{-fprofile-arcs}). These
5771 heuristics are based on the control flow graph. If some branch probabilities
5772 are specified by @samp{__builtin_expect}, then the heuristics will be
5773 used to guess branch probabilities for the rest of the control flow graph,
5774 taking the @samp{__builtin_expect} info into account. The interactions
5775 between the heuristics and @samp{__builtin_expect} can be complex, and in
5776 some cases, it may be useful to disable the heuristics so that the effects
5777 of @samp{__builtin_expect} are easier to understand.
5779 The default is @option{-fguess-branch-probability} at levels
5780 @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5782 @item -freorder-blocks
5783 @opindex freorder-blocks
5784 Reorder basic blocks in the compiled function in order to reduce number of
5785 taken branches and improve code locality.
5787 Enabled at levels @option{-O2}, @option{-O3}.
5789 @item -freorder-blocks-and-partition
5790 @opindex freorder-blocks-and-partition
5791 In addition to reordering basic blocks in the compiled function, in order
5792 to reduce number of taken branches, partitions hot and cold basic blocks
5793 into separate sections of the assembly and .o files, to improve
5794 paging and cache locality performance.
5796 This optimization is automatically turned off in the presence of
5797 exception handling, for linkonce sections, for functions with a user-defined
5798 section attribute and on any architecture that does not support named
5801 @item -freorder-functions
5802 @opindex freorder-functions
5803 Reorder functions in the object file in order to
5804 improve code locality. This is implemented by using special
5805 subsections @code{.text.hot} for most frequently executed functions and
5806 @code{.text.unlikely} for unlikely executed functions. Reordering is done by
5807 the linker so object file format must support named sections and linker must
5808 place them in a reasonable way.
5810 Also profile feedback must be available in to make this option effective. See
5811 @option{-fprofile-arcs} for details.
5813 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5815 @item -fstrict-aliasing
5816 @opindex fstrict-aliasing
5817 Allows the compiler to assume the strictest aliasing rules applicable to
5818 the language being compiled. For C (and C++), this activates
5819 optimizations based on the type of expressions. In particular, an
5820 object of one type is assumed never to reside at the same address as an
5821 object of a different type, unless the types are almost the same. For
5822 example, an @code{unsigned int} can alias an @code{int}, but not a
5823 @code{void*} or a @code{double}. A character type may alias any other
5826 Pay special attention to code like this:
5839 The practice of reading from a different union member than the one most
5840 recently written to (called ``type-punning'') is common. Even with
5841 @option{-fstrict-aliasing}, type-punning is allowed, provided the memory
5842 is accessed through the union type. So, the code above will work as
5843 expected. However, this code might not:
5854 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5856 @item -fstrict-overflow
5857 @opindex fstrict-overflow
5858 Allow the compiler to assume strict signed overflow rules, depending
5859 on the language being compiled. For C (and C++) this means that
5860 overflow when doing arithmetic with signed numbers is undefined, which
5861 means that the compiler may assume that it will not happen. This
5862 permits various optimizations. For example, the compiler will assume
5863 that an expression like @code{i + 10 > i} will always be true for
5864 signed @code{i}. This assumption is only valid if signed overflow is
5865 undefined, as the expression is false if @code{i + 10} overflows when
5866 using twos complement arithmetic. When this option is in effect any
5867 attempt to determine whether an operation on signed numbers will
5868 overflow must be written carefully to not actually involve overflow.
5870 See also the @option{-fwrapv} option. Using @option{-fwrapv} means
5871 that signed overflow is fully defined: it wraps. When
5872 @option{-fwrapv} is used, there is no difference between
5873 @option{-fstrict-overflow} and @option{-fno-strict-overflow}. With
5874 @option{-fwrapv} certain types of overflow are permitted. For
5875 example, if the compiler gets an overflow when doing arithmetic on
5876 constants, the overflowed value can still be used with
5877 @option{-fwrapv}, but not otherwise.
5879 The @option{-fstrict-overflow} option is enabled at levels
5880 @option{-O2}, @option{-O3}, @option{-Os}.
5882 @item -falign-functions
5883 @itemx -falign-functions=@var{n}
5884 @opindex falign-functions
5885 Align the start of functions to the next power-of-two greater than
5886 @var{n}, skipping up to @var{n} bytes. For instance,
5887 @option{-falign-functions=32} aligns functions to the next 32-byte
5888 boundary, but @option{-falign-functions=24} would align to the next
5889 32-byte boundary only if this can be done by skipping 23 bytes or less.
5891 @option{-fno-align-functions} and @option{-falign-functions=1} are
5892 equivalent and mean that functions will not be aligned.
5894 Some assemblers only support this flag when @var{n} is a power of two;
5895 in that case, it is rounded up.
5897 If @var{n} is not specified or is zero, use a machine-dependent default.
5899 Enabled at levels @option{-O2}, @option{-O3}.
5901 @item -falign-labels
5902 @itemx -falign-labels=@var{n}
5903 @opindex falign-labels
5904 Align all branch targets to a power-of-two boundary, skipping up to
5905 @var{n} bytes like @option{-falign-functions}. This option can easily
5906 make code slower, because it must insert dummy operations for when the
5907 branch target is reached in the usual flow of the code.
5909 @option{-fno-align-labels} and @option{-falign-labels=1} are
5910 equivalent and mean that labels will not be aligned.
5912 If @option{-falign-loops} or @option{-falign-jumps} are applicable and
5913 are greater than this value, then their values are used instead.
5915 If @var{n} is not specified or is zero, use a machine-dependent default
5916 which is very likely to be @samp{1}, meaning no alignment.
5918 Enabled at levels @option{-O2}, @option{-O3}.
5921 @itemx -falign-loops=@var{n}
5922 @opindex falign-loops
5923 Align loops to a power-of-two boundary, skipping up to @var{n} bytes
5924 like @option{-falign-functions}. The hope is that the loop will be
5925 executed many times, which will make up for any execution of the dummy
5928 @option{-fno-align-loops} and @option{-falign-loops=1} are
5929 equivalent and mean that loops will not be aligned.
5931 If @var{n} is not specified or is zero, use a machine-dependent default.
5933 Enabled at levels @option{-O2}, @option{-O3}.
5936 @itemx -falign-jumps=@var{n}
5937 @opindex falign-jumps
5938 Align branch targets to a power-of-two boundary, for branch targets
5939 where the targets can only be reached by jumping, skipping up to @var{n}
5940 bytes like @option{-falign-functions}. In this case, no dummy operations
5943 @option{-fno-align-jumps} and @option{-falign-jumps=1} are
5944 equivalent and mean that loops will not be aligned.
5946 If @var{n} is not specified or is zero, use a machine-dependent default.
5948 Enabled at levels @option{-O2}, @option{-O3}.
5950 @item -funit-at-a-time
5951 @opindex funit-at-a-time
5952 Parse the whole compilation unit before starting to produce code.
5953 This allows some extra optimizations to take place but consumes
5954 more memory (in general). There are some compatibility issues
5955 with @emph{unit-at-a-time} mode:
5958 enabling @emph{unit-at-a-time} mode may change the order
5959 in which functions, variables, and top-level @code{asm} statements
5960 are emitted, and will likely break code relying on some particular
5961 ordering. The majority of such top-level @code{asm} statements,
5962 though, can be replaced by @code{section} attributes. The
5963 @option{fno-toplevel-reorder} option may be used to keep the ordering
5964 used in the input file, at the cost of some optimizations.
5967 @emph{unit-at-a-time} mode removes unreferenced static variables
5968 and functions. This may result in undefined references
5969 when an @code{asm} statement refers directly to variables or functions
5970 that are otherwise unused. In that case either the variable/function
5971 shall be listed as an operand of the @code{asm} statement operand or,
5972 in the case of top-level @code{asm} statements the attribute @code{used}
5973 shall be used on the declaration.
5976 Static functions now can use non-standard passing conventions that
5977 may break @code{asm} statements calling functions directly. Again,
5978 attribute @code{used} will prevent this behavior.
5981 As a temporary workaround, @option{-fno-unit-at-a-time} can be used,
5982 but this scheme may not be supported by future releases of GCC@.
5984 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5986 @item -fno-toplevel-reorder
5987 Do not reorder top-level functions, variables, and @code{asm}
5988 statements. Output them in the same order that they appear in the
5989 input file. When this option is used, unreferenced static variables
5990 will not be removed. This option is intended to support existing code
5991 which relies on a particular ordering. For new code, it is better to
5996 Constructs webs as commonly used for register allocation purposes and assign
5997 each web individual pseudo register. This allows the register allocation pass
5998 to operate on pseudos directly, but also strengthens several other optimization
5999 passes, such as CSE, loop optimizer and trivial dead code remover. It can,
6000 however, make debugging impossible, since variables will no longer stay in a
6003 Enabled by default with @option{-funroll-loops}.
6005 @item -fwhole-program
6006 @opindex fwhole-program
6007 Assume that the current compilation unit represents whole program being
6008 compiled. All public functions and variables with the exception of @code{main}
6009 and those merged by attribute @code{externally_visible} become static functions
6010 and in a affect gets more aggressively optimized by interprocedural optimizers.
6011 While this option is equivalent to proper use of @code{static} keyword for
6012 programs consisting of single file, in combination with option
6013 @option{--combine} this flag can be used to compile most of smaller scale C
6014 programs since the functions and variables become local for the whole combined
6015 compilation unit, not for the single source file itself.
6018 @item -fno-cprop-registers
6019 @opindex fno-cprop-registers
6020 After register allocation and post-register allocation instruction splitting,
6021 we perform a copy-propagation pass to try to reduce scheduling dependencies
6022 and occasionally eliminate the copy.
6024 Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
6026 @item -fprofile-generate
6027 @opindex fprofile-generate
6029 Enable options usually used for instrumenting application to produce
6030 profile useful for later recompilation with profile feedback based
6031 optimization. You must use @option{-fprofile-generate} both when
6032 compiling and when linking your program.
6034 The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
6037 @opindex fprofile-use
6038 Enable profile feedback directed optimizations, and optimizations
6039 generally profitable only with profile feedback available.
6041 The following options are enabled: @code{-fbranch-probabilities}, @code{-fvpt},
6042 @code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}
6044 By default, GCC emits an error message if the feedback profiles do not
6045 match the source code. This error can be turned into a warning by using
6046 @option{-Wcoverage-mismatch}. Note this may result in poorly optimized
6050 The following options control compiler behavior regarding floating
6051 point arithmetic. These options trade off between speed and
6052 correctness. All must be specifically enabled.
6056 @opindex ffloat-store
6057 Do not store floating point variables in registers, and inhibit other
6058 options that might change whether a floating point value is taken from a
6061 @cindex floating point precision
6062 This option prevents undesirable excess precision on machines such as
6063 the 68000 where the floating registers (of the 68881) keep more
6064 precision than a @code{double} is supposed to have. Similarly for the
6065 x86 architecture. For most programs, the excess precision does only
6066 good, but a few programs rely on the precise definition of IEEE floating
6067 point. Use @option{-ffloat-store} for such programs, after modifying
6068 them to store all pertinent intermediate computations into variables.
6072 Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
6073 @option{-fno-trapping-math}, @option{-ffinite-math-only},
6074 @option{-fno-rounding-math}, @option{-fno-signaling-nans},
6075 @option{-fno-signed-zeros} and @option{fcx-limited-range}.
6077 This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
6079 This option is not turned on by any @option{-O} option since
6080 it can result in incorrect output for programs which depend on
6081 an exact implementation of IEEE or ISO rules/specifications for
6082 math functions. It may, however, yield faster code for programs
6083 that do not require the guarantees of these specifications.
6085 @item -fno-math-errno
6086 @opindex fno-math-errno
6087 Do not set ERRNO after calling math functions that are executed
6088 with a single instruction, e.g., sqrt. A program that relies on
6089 IEEE exceptions for math error handling may want to use this flag
6090 for speed while maintaining IEEE arithmetic compatibility.
6092 This option is not turned on by any @option{-O} option since
6093 it can result in incorrect output for programs which depend on
6094 an exact implementation of IEEE or ISO rules/specifications for
6095 math functions. It may, however, yield faster code for programs
6096 that do not require the guarantees of these specifications.
6098 The default is @option{-fmath-errno}.
6100 On Darwin systems, the math library never sets @code{errno}. There is
6101 therefore no reason for the compiler to consider the possibility that
6102 it might, and @option{-fno-math-errno} is the default.
6104 @item -funsafe-math-optimizations
6105 @opindex funsafe-math-optimizations
6106 Allow optimizations for floating-point arithmetic that (a) assume
6107 that arguments and results are valid and (b) may violate IEEE or
6108 ANSI standards. When used at link-time, it may include libraries
6109 or startup files that change the default FPU control word or other
6110 similar optimizations.
6112 This option is not turned on by any @option{-O} option since
6113 it can result in incorrect output for programs which depend on
6114 an exact implementation of IEEE or ISO rules/specifications for
6115 math functions. It may, however, yield faster code for programs
6116 that do not require the guarantees of these specifications.
6118 The default is @option{-fno-unsafe-math-optimizations}.
6120 @item -ffinite-math-only
6121 @opindex ffinite-math-only
6122 Allow optimizations for floating-point arithmetic that assume
6123 that arguments and results are not NaNs or +-Infs.
6125 This option is not turned on by any @option{-O} option since
6126 it can result in incorrect output for programs which depend on
6127 an exact implementation of IEEE or ISO rules/specifications for
6128 math functions. It may, however, yield faster code for programs
6129 that do not require the guarantees of these specifications.
6131 The default is @option{-fno-finite-math-only}.
6133 @item -fno-signed-zeros
6134 @opindex fno-signed-zeros
6135 Allow optimizations for floating point arithmetic that ignore the
6136 signedness of zero. IEEE arithmetic specifies the behavior of
6137 distinct +0.0 and @minus{}0.0 values, which then prohibits simplification
6138 of expressions such as x+0.0 or 0.0*x (even with @option{-ffinite-math-only}).
6139 This option implies that the sign of a zero result isn't significant.
6141 The default is @option{-fsigned-zeros}.
6143 @item -fno-trapping-math
6144 @opindex fno-trapping-math
6145 Compile code assuming that floating-point operations cannot generate
6146 user-visible traps. These traps include division by zero, overflow,
6147 underflow, inexact result and invalid operation. This option implies
6148 @option{-fno-signaling-nans}. Setting this option may allow faster
6149 code if one relies on ``non-stop'' IEEE arithmetic, for example.
6151 This option should never be turned on by any @option{-O} option since
6152 it can result in incorrect output for programs which depend on
6153 an exact implementation of IEEE or ISO rules/specifications for
6156 The default is @option{-ftrapping-math}.
6158 @item -frounding-math
6159 @opindex frounding-math
6160 Disable transformations and optimizations that assume default floating
6161 point rounding behavior. This is round-to-zero for all floating point
6162 to integer conversions, and round-to-nearest for all other arithmetic
6163 truncations. This option should be specified for programs that change
6164 the FP rounding mode dynamically, or that may be executed with a
6165 non-default rounding mode. This option disables constant folding of
6166 floating point expressions at compile-time (which may be affected by
6167 rounding mode) and arithmetic transformations that are unsafe in the
6168 presence of sign-dependent rounding modes.
6170 The default is @option{-fno-rounding-math}.
6172 This option is experimental and does not currently guarantee to
6173 disable all GCC optimizations that are affected by rounding mode.
6174 Future versions of GCC may provide finer control of this setting
6175 using C99's @code{FENV_ACCESS} pragma. This command line option
6176 will be used to specify the default state for @code{FENV_ACCESS}.
6178 @item -frtl-abstract-sequences
6179 @opindex frtl-abstract-sequences
6180 It is a size optimization method. This option is to find identical
6181 sequences of code, which can be turned into pseudo-procedures and
6182 then replace all occurrences with calls to the newly created
6183 subroutine. It is kind of an opposite of @option{-finline-functions}.
6184 This optimization runs at RTL level.
6186 @item -fsignaling-nans
6187 @opindex fsignaling-nans
6188 Compile code assuming that IEEE signaling NaNs may generate user-visible
6189 traps during floating-point operations. Setting this option disables
6190 optimizations that may change the number of exceptions visible with
6191 signaling NaNs. This option implies @option{-ftrapping-math}.
6193 This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
6196 The default is @option{-fno-signaling-nans}.
6198 This option is experimental and does not currently guarantee to
6199 disable all GCC optimizations that affect signaling NaN behavior.
6201 @item -fsingle-precision-constant
6202 @opindex fsingle-precision-constant
6203 Treat floating point constant as single precision constant instead of
6204 implicitly converting it to double precision constant.
6206 @item -fcx-limited-range
6207 @itemx -fno-cx-limited-range
6208 @opindex fcx-limited-range
6209 @opindex fno-cx-limited-range
6210 When enabled, this option states that a range reduction step is not
6211 needed when performing complex division. The default is
6212 @option{-fno-cx-limited-range}, but is enabled by @option{-ffast-math}.
6214 This option controls the default setting of the ISO C99
6215 @code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to
6220 The following options control optimizations that may improve
6221 performance, but are not enabled by any @option{-O} options. This
6222 section includes experimental options that may produce broken code.
6225 @item -fbranch-probabilities
6226 @opindex fbranch-probabilities
6227 After running a program compiled with @option{-fprofile-arcs}
6228 (@pxref{Debugging Options,, Options for Debugging Your Program or
6229 @command{gcc}}), you can compile it a second time using
6230 @option{-fbranch-probabilities}, to improve optimizations based on
6231 the number of times each branch was taken. When the program
6232 compiled with @option{-fprofile-arcs} exits it saves arc execution
6233 counts to a file called @file{@var{sourcename}.gcda} for each source
6234 file. The information in this data file is very dependent on the
6235 structure of the generated code, so you must use the same source code
6236 and the same optimization options for both compilations.
6238 With @option{-fbranch-probabilities}, GCC puts a
6239 @samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
6240 These can be used to improve optimization. Currently, they are only
6241 used in one place: in @file{reorg.c}, instead of guessing which path a
6242 branch is mostly to take, the @samp{REG_BR_PROB} values are used to
6243 exactly determine which path is taken more often.
6245 @item -fprofile-values
6246 @opindex fprofile-values
6247 If combined with @option{-fprofile-arcs}, it adds code so that some
6248 data about values of expressions in the program is gathered.
6250 With @option{-fbranch-probabilities}, it reads back the data gathered
6251 from profiling values of expressions and adds @samp{REG_VALUE_PROFILE}
6252 notes to instructions for their later usage in optimizations.
6254 Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
6258 If combined with @option{-fprofile-arcs}, it instructs the compiler to add
6259 a code to gather information about values of expressions.
6261 With @option{-fbranch-probabilities}, it reads back the data gathered
6262 and actually performs the optimizations based on them.
6263 Currently the optimizations include specialization of division operation
6264 using the knowledge about the value of the denominator.
6266 @item -frename-registers
6267 @opindex frename-registers
6268 Attempt to avoid false dependencies in scheduled code by making use
6269 of registers left over after register allocation. This optimization
6270 will most benefit processors with lots of registers. Depending on the
6271 debug information format adopted by the target, however, it can
6272 make debugging impossible, since variables will no longer stay in
6273 a ``home register''.
6275 Enabled by default with @option{-funroll-loops}.
6279 Perform tail duplication to enlarge superblock size. This transformation
6280 simplifies the control flow of the function allowing other optimizations to do
6283 Enabled with @option{-fprofile-use}.
6285 @item -funroll-loops
6286 @opindex funroll-loops
6287 Unroll loops whose number of iterations can be determined at compile time or
6288 upon entry to the loop. @option{-funroll-loops} implies
6289 @option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.
6290 It also turns on complete loop peeling (i.e.@: complete removal of loops with
6291 small constant number of iterations). This option makes code larger, and may
6292 or may not make it run faster.
6294 Enabled with @option{-fprofile-use}.
6296 @item -funroll-all-loops
6297 @opindex funroll-all-loops
6298 Unroll all loops, even if their number of iterations is uncertain when
6299 the loop is entered. This usually makes programs run more slowly.
6300 @option{-funroll-all-loops} implies the same options as
6301 @option{-funroll-loops}.
6304 @opindex fpeel-loops
6305 Peels the loops for that there is enough information that they do not
6306 roll much (from profile feedback). It also turns on complete loop peeling
6307 (i.e.@: complete removal of loops with small constant number of iterations).
6309 Enabled with @option{-fprofile-use}.
6311 @item -fmove-loop-invariants
6312 @opindex fmove-loop-invariants
6313 Enables the loop invariant motion pass in the RTL loop optimizer. Enabled
6314 at level @option{-O1}
6316 @item -funswitch-loops
6317 @opindex funswitch-loops
6318 Move branches with loop invariant conditions out of the loop, with duplicates
6319 of the loop on both branches (modified according to result of the condition).
6321 @item -ffunction-sections
6322 @itemx -fdata-sections
6323 @opindex ffunction-sections
6324 @opindex fdata-sections
6325 Place each function or data item into its own section in the output
6326 file if the target supports arbitrary sections. The name of the
6327 function or the name of the data item determines the section's name
6330 Use these options on systems where the linker can perform optimizations
6331 to improve locality of reference in the instruction space. Most systems
6332 using the ELF object format and SPARC processors running Solaris 2 have
6333 linkers with such optimizations. AIX may have these optimizations in
6336 Only use these options when there are significant benefits from doing
6337 so. When you specify these options, the assembler and linker will
6338 create larger object and executable files and will also be slower.
6339 You will not be able to use @code{gprof} on all systems if you
6340 specify this option and you may have problems with debugging if
6341 you specify both this option and @option{-g}.
6343 @item -fbranch-target-load-optimize
6344 @opindex fbranch-target-load-optimize
6345 Perform branch target register load optimization before prologue / epilogue
6347 The use of target registers can typically be exposed only during reload,
6348 thus hoisting loads out of loops and doing inter-block scheduling needs
6349 a separate optimization pass.
6351 @item -fbranch-target-load-optimize2
6352 @opindex fbranch-target-load-optimize2
6353 Perform branch target register load optimization after prologue / epilogue
6356 @item -fbtr-bb-exclusive
6357 @opindex fbtr-bb-exclusive
6358 When performing branch target register load optimization, don't reuse
6359 branch target registers in within any basic block.
6361 @item -fstack-protector
6362 Emit extra code to check for buffer overflows, such as stack smashing
6363 attacks. This is done by adding a guard variable to functions with
6364 vulnerable objects. This includes functions that call alloca, and
6365 functions with buffers larger than 8 bytes. The guards are initialized
6366 when a function is entered and then checked when the function exits.
6367 If a guard check fails, an error message is printed and the program exits.
6369 @item -fstack-protector-all
6370 Like @option{-fstack-protector} except that all functions are protected.
6372 @item -fsection-anchors
6373 @opindex fsection-anchors
6374 Try to reduce the number of symbolic address calculations by using
6375 shared ``anchor'' symbols to address nearby objects. This transformation
6376 can help to reduce the number of GOT entries and GOT accesses on some
6379 For example, the implementation of the following function @code{foo}:
6383 int foo (void) @{ return a + b + c; @}
6386 would usually calculate the addresses of all three variables, but if you
6387 compile it with @option{-fsection-anchors}, it will access the variables
6388 from a common anchor point instead. The effect is similar to the
6389 following pseudocode (which isn't valid C):
6394 register int *xr = &x;
6395 return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
6399 Not all targets support this option.
6401 @item --param @var{name}=@var{value}
6403 In some places, GCC uses various constants to control the amount of
6404 optimization that is done. For example, GCC will not inline functions
6405 that contain more that a certain number of instructions. You can
6406 control some of these constants on the command-line using the
6407 @option{--param} option.
6409 The names of specific parameters, and the meaning of the values, are
6410 tied to the internals of the compiler, and are subject to change
6411 without notice in future releases.
6413 In each case, the @var{value} is an integer. The allowable choices for
6414 @var{name} are given in the following table:
6417 @item salias-max-implicit-fields
6418 The maximum number of fields in a variable without direct
6419 structure accesses for which structure aliasing will consider trying
6420 to track each field. The default is 5
6422 @item salias-max-array-elements
6423 The maximum number of elements an array can have and its elements
6424 still be tracked individually by structure aliasing. The default is 4
6426 @item sra-max-structure-size
6427 The maximum structure size, in bytes, at which the scalar replacement
6428 of aggregates (SRA) optimization will perform block copies. The
6429 default value, 0, implies that GCC will select the most appropriate
6432 @item sra-field-structure-ratio
6433 The threshold ratio (as a percentage) between instantiated fields and
6434 the complete structure size. We say that if the ratio of the number
6435 of bytes in instantiated fields to the number of bytes in the complete
6436 structure exceeds this parameter, then block copies are not used. The
6439 @item max-crossjump-edges
6440 The maximum number of incoming edges to consider for crossjumping.
6441 The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
6442 the number of edges incoming to each block. Increasing values mean
6443 more aggressive optimization, making the compile time increase with
6444 probably small improvement in executable size.
6446 @item min-crossjump-insns
6447 The minimum number of instructions which must be matched at the end
6448 of two blocks before crossjumping will be performed on them. This
6449 value is ignored in the case where all instructions in the block being
6450 crossjumped from are matched. The default value is 5.
6452 @item max-grow-copy-bb-insns
6453 The maximum code size expansion factor when copying basic blocks
6454 instead of jumping. The expansion is relative to a jump instruction.
6455 The default value is 8.
6457 @item max-goto-duplication-insns
6458 The maximum number of instructions to duplicate to a block that jumps
6459 to a computed goto. To avoid @math{O(N^2)} behavior in a number of
6460 passes, GCC factors computed gotos early in the compilation process,
6461 and unfactors them as late as possible. Only computed jumps at the
6462 end of a basic blocks with no more than max-goto-duplication-insns are
6463 unfactored. The default value is 8.
6465 @item max-delay-slot-insn-search
6466 The maximum number of instructions to consider when looking for an
6467 instruction to fill a delay slot. If more than this arbitrary number of
6468 instructions is searched, the time savings from filling the delay slot
6469 will be minimal so stop searching. Increasing values mean more
6470 aggressive optimization, making the compile time increase with probably
6471 small improvement in executable run time.
6473 @item max-delay-slot-live-search
6474 When trying to fill delay slots, the maximum number of instructions to
6475 consider when searching for a block with valid live register
6476 information. Increasing this arbitrarily chosen value means more
6477 aggressive optimization, increasing the compile time. This parameter
6478 should be removed when the delay slot code is rewritten to maintain the
6481 @item max-gcse-memory
6482 The approximate maximum amount of memory that will be allocated in
6483 order to perform the global common subexpression elimination
6484 optimization. If more memory than specified is required, the
6485 optimization will not be done.
6487 @item max-gcse-passes
6488 The maximum number of passes of GCSE to run. The default is 1.
6490 @item max-pending-list-length
6491 The maximum number of pending dependencies scheduling will allow
6492 before flushing the current state and starting over. Large functions
6493 with few branches or calls can create excessively large lists which
6494 needlessly consume memory and resources.
6496 @item max-inline-insns-single
6497 Several parameters control the tree inliner used in gcc.
6498 This number sets the maximum number of instructions (counted in GCC's
6499 internal representation) in a single function that the tree inliner
6500 will consider for inlining. This only affects functions declared
6501 inline and methods implemented in a class declaration (C++).
6502 The default value is 450.
6504 @item max-inline-insns-auto
6505 When you use @option{-finline-functions} (included in @option{-O3}),
6506 a lot of functions that would otherwise not be considered for inlining
6507 by the compiler will be investigated. To those functions, a different
6508 (more restrictive) limit compared to functions declared inline can
6510 The default value is 90.
6512 @item large-function-insns
6513 The limit specifying really large functions. For functions larger than this
6514 limit after inlining inlining is constrained by
6515 @option{--param large-function-growth}. This parameter is useful primarily
6516 to avoid extreme compilation time caused by non-linear algorithms used by the
6518 This parameter is ignored when @option{-funit-at-a-time} is not used.
6519 The default value is 2700.
6521 @item large-function-growth
6522 Specifies maximal growth of large function caused by inlining in percents.
6523 This parameter is ignored when @option{-funit-at-a-time} is not used.
6524 The default value is 100 which limits large function growth to 2.0 times
6527 @item large-unit-insns
6528 The limit specifying large translation unit. Growth caused by inlining of
6529 units larger than this limit is limited by @option{--param inline-unit-growth}.
6530 For small units this might be too tight (consider unit consisting of function A
6531 that is inline and B that just calls A three time. If B is small relative to
6532 A, the growth of unit is 300\% and yet such inlining is very sane. For very
6533 large units consisting of small inlininable functions however the overall unit
6534 growth limit is needed to avoid exponential explosion of code size. Thus for
6535 smaller units, the size is increased to @option{--param large-unit-insns}
6536 before applying @option{--param inline-unit-growth}. The default is 10000
6538 @item inline-unit-growth
6539 Specifies maximal overall growth of the compilation unit caused by inlining.
6540 This parameter is ignored when @option{-funit-at-a-time} is not used.
6541 The default value is 30 which limits unit growth to 1.3 times the original
6544 @item large-stack-frame
6545 The limit specifying large stack frames. While inlining the algorithm is trying
6546 to not grow past this limit too much. Default value is 256 bytes.
6548 @item large-stack-frame-growth
6549 Specifies maximal growth of large stack frames caused by inlining in percents.
6550 The default value is 1000 which limits large stack frame growth to 11 times
6553 @item max-inline-insns-recursive
6554 @itemx max-inline-insns-recursive-auto
6555 Specifies maximum number of instructions out-of-line copy of self recursive inline
6556 function can grow into by performing recursive inlining.
6558 For functions declared inline @option{--param max-inline-insns-recursive} is
6559 taken into account. For function not declared inline, recursive inlining
6560 happens only when @option{-finline-functions} (included in @option{-O3}) is
6561 enabled and @option{--param max-inline-insns-recursive-auto} is used. The
6562 default value is 450.
6564 @item max-inline-recursive-depth
6565 @itemx max-inline-recursive-depth-auto
6566 Specifies maximum recursion depth used by the recursive inlining.
6568 For functions declared inline @option{--param max-inline-recursive-depth} is
6569 taken into account. For function not declared inline, recursive inlining
6570 happens only when @option{-finline-functions} (included in @option{-O3}) is
6571 enabled and @option{--param max-inline-recursive-depth-auto} is used. The
6572 default value is 450.
6574 @item min-inline-recursive-probability
6575 Recursive inlining is profitable only for function having deep recursion
6576 in average and can hurt for function having little recursion depth by
6577 increasing the prologue size or complexity of function body to other
6580 When profile feedback is available (see @option{-fprofile-generate}) the actual
6581 recursion depth can be guessed from probability that function will recurse via
6582 given call expression. This parameter limits inlining only to call expression
6583 whose probability exceeds given threshold (in percents). The default value is
6586 @item inline-call-cost
6587 Specify cost of call instruction relative to simple arithmetics operations
6588 (having cost of 1). Increasing this cost disqualifies inlining of non-leaf
6589 functions and at the same time increases size of leaf function that is believed to
6590 reduce function size by being inlined. In effect it increases amount of
6591 inlining for code having large abstraction penalty (many functions that just
6592 pass the arguments to other functions) and decrease inlining for code with low
6593 abstraction penalty. The default value is 16.
6595 @item min-vect-loop-bound
6596 The minimum number of iterations under which a loop will not get vectorized
6597 when @option{-ftree-vectorize} is used. The number of iterations after
6598 vectorization needs to be greater than the value specified by this option
6599 to allow vectorization. The default value is 0.
6601 @item max-unrolled-insns
6602 The maximum number of instructions that a loop should have if that loop
6603 is unrolled, and if the loop is unrolled, it determines how many times
6604 the loop code is unrolled.
6606 @item max-average-unrolled-insns
6607 The maximum number of instructions biased by probabilities of their execution
6608 that a loop should have if that loop is unrolled, and if the loop is unrolled,
6609 it determines how many times the loop code is unrolled.
6611 @item max-unroll-times
6612 The maximum number of unrollings of a single loop.
6614 @item max-peeled-insns
6615 The maximum number of instructions that a loop should have if that loop
6616 is peeled, and if the loop is peeled, it determines how many times
6617 the loop code is peeled.
6619 @item max-peel-times
6620 The maximum number of peelings of a single loop.
6622 @item max-completely-peeled-insns
6623 The maximum number of insns of a completely peeled loop.
6625 @item max-completely-peel-times
6626 The maximum number of iterations of a loop to be suitable for complete peeling.
6628 @item max-unswitch-insns
6629 The maximum number of insns of an unswitched loop.
6631 @item max-unswitch-level
6632 The maximum number of branches unswitched in a single loop.
6635 The minimum cost of an expensive expression in the loop invariant motion.
6637 @item iv-consider-all-candidates-bound
6638 Bound on number of candidates for induction variables below that
6639 all candidates are considered for each use in induction variable
6640 optimizations. Only the most relevant candidates are considered
6641 if there are more candidates, to avoid quadratic time complexity.
6643 @item iv-max-considered-uses
6644 The induction variable optimizations give up on loops that contain more
6645 induction variable uses.
6647 @item iv-always-prune-cand-set-bound
6648 If number of candidates in the set is smaller than this value,
6649 we always try to remove unnecessary ivs from the set during its
6650 optimization when a new iv is added to the set.
6652 @item scev-max-expr-size
6653 Bound on size of expressions used in the scalar evolutions analyzer.
6654 Large expressions slow the analyzer.
6656 @item omega-max-vars
6657 The maximum number of variables in an Omega constraint system.
6658 The default value is 128.
6660 @item omega-max-geqs
6661 The maximum number of inequalities in an Omega constraint system.
6662 The default value is 256.
6665 The maximum number of equalities in an Omega constraint system.
6666 The default value is 128.
6668 @item omega-max-wild-cards
6669 The maximum number of wildcard variables that the Omega solver will
6670 be able to insert. The default value is 18.
6672 @item omega-hash-table-size
6673 The size of the hash table in the Omega solver. The default value is
6676 @item omega-max-keys
6677 The maximal number of keys used by the Omega solver. The default
6680 @item omega-eliminate-redundant-constraints
6681 When set to 1, use expensive methods to eliminate all redundant
6682 constraints. The default value is 0.
6684 @item vect-max-version-checks
6685 The maximum number of runtime checks that can be performed when doing
6686 loop versioning in the vectorizer. See option ftree-vect-loop-version
6687 for more information.
6689 @item max-iterations-to-track
6691 The maximum number of iterations of a loop the brute force algorithm
6692 for analysis of # of iterations of the loop tries to evaluate.
6694 @item hot-bb-count-fraction
6695 Select fraction of the maximal count of repetitions of basic block in program
6696 given basic block needs to have to be considered hot.
6698 @item hot-bb-frequency-fraction
6699 Select fraction of the maximal frequency of executions of basic block in
6700 function given basic block needs to have to be considered hot
6702 @item max-predicted-iterations
6703 The maximum number of loop iterations we predict statically. This is useful
6704 in cases where function contain single loop with known bound and other loop
6705 with unknown. We predict the known number of iterations correctly, while
6706 the unknown number of iterations average to roughly 10. This means that the
6707 loop without bounds would appear artificially cold relative to the other one.
6709 @item tracer-dynamic-coverage
6710 @itemx tracer-dynamic-coverage-feedback
6712 This value is used to limit superblock formation once the given percentage of
6713 executed instructions is covered. This limits unnecessary code size
6716 The @option{tracer-dynamic-coverage-feedback} is used only when profile
6717 feedback is available. The real profiles (as opposed to statically estimated
6718 ones) are much less balanced allowing the threshold to be larger value.
6720 @item tracer-max-code-growth
6721 Stop tail duplication once code growth has reached given percentage. This is
6722 rather hokey argument, as most of the duplicates will be eliminated later in
6723 cross jumping, so it may be set to much higher values than is the desired code
6726 @item tracer-min-branch-ratio
6728 Stop reverse growth when the reverse probability of best edge is less than this
6729 threshold (in percent).
6731 @item tracer-min-branch-ratio
6732 @itemx tracer-min-branch-ratio-feedback
6734 Stop forward growth if the best edge do have probability lower than this
6737 Similarly to @option{tracer-dynamic-coverage} two values are present, one for
6738 compilation for profile feedback and one for compilation without. The value
6739 for compilation with profile feedback needs to be more conservative (higher) in
6740 order to make tracer effective.
6742 @item max-cse-path-length
6744 Maximum number of basic blocks on path that cse considers. The default is 10.
6747 The maximum instructions CSE process before flushing. The default is 1000.
6749 @item max-aliased-vops
6751 Maximum number of virtual operands per function allowed to represent
6752 aliases before triggering the alias partitioning heuristic. Alias
6753 partitioning reduces compile times and memory consumption needed for
6754 aliasing at the expense of precision loss in alias information. The
6755 default value for this parameter is 100 for -O1, 500 for -O2 and 1000
6758 Notice that if a function contains more memory statements than the
6759 value of this parameter, it is not really possible to achieve this
6760 reduction. In this case, the compiler will use the number of memory
6761 statements as the value for @option{max-aliased-vops}.
6763 @item avg-aliased-vops
6765 Average number of virtual operands per statement allowed to represent
6766 aliases before triggering the alias partitioning heuristic. This
6767 works in conjunction with @option{max-aliased-vops}. If a function
6768 contains more than @option{max-aliased-vops} virtual operators, then
6769 memory symbols will be grouped into memory partitions until either the
6770 total number of virtual operators is below @option{max-aliased-vops}
6771 or the average number of virtual operators per memory statement is
6772 below @option{avg-aliased-vops}. The default value for this parameter
6773 is 1 for -O1 and -O2, and 3 for -O3.
6775 @item ggc-min-expand
6777 GCC uses a garbage collector to manage its own memory allocation. This
6778 parameter specifies the minimum percentage by which the garbage
6779 collector's heap should be allowed to expand between collections.
6780 Tuning this may improve compilation speed; it has no effect on code
6783 The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
6784 RAM >= 1GB@. If @code{getrlimit} is available, the notion of "RAM" is
6785 the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If
6786 GCC is not able to calculate RAM on a particular platform, the lower
6787 bound of 30% is used. Setting this parameter and
6788 @option{ggc-min-heapsize} to zero causes a full collection to occur at
6789 every opportunity. This is extremely slow, but can be useful for
6792 @item ggc-min-heapsize
6794 Minimum size of the garbage collector's heap before it begins bothering
6795 to collect garbage. The first collection occurs after the heap expands
6796 by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again,
6797 tuning this may improve compilation speed, and has no effect on code
6800 The default is the smaller of RAM/8, RLIMIT_RSS, or a limit which
6801 tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
6802 with a lower bound of 4096 (four megabytes) and an upper bound of
6803 131072 (128 megabytes). If GCC is not able to calculate RAM on a
6804 particular platform, the lower bound is used. Setting this parameter
6805 very large effectively disables garbage collection. Setting this
6806 parameter and @option{ggc-min-expand} to zero causes a full collection
6807 to occur at every opportunity.
6809 @item max-reload-search-insns
6810 The maximum number of instruction reload should look backward for equivalent
6811 register. Increasing values mean more aggressive optimization, making the
6812 compile time increase with probably slightly better performance. The default
6815 @item max-cselib-memory-locations
6816 The maximum number of memory locations cselib should take into account.
6817 Increasing values mean more aggressive optimization, making the compile time
6818 increase with probably slightly better performance. The default value is 500.
6820 @item max-flow-memory-locations
6821 Similar as @option{max-cselib-memory-locations} but for dataflow liveness.
6822 The default value is 100.
6824 @item reorder-blocks-duplicate
6825 @itemx reorder-blocks-duplicate-feedback
6827 Used by basic block reordering pass to decide whether to use unconditional
6828 branch or duplicate the code on its destination. Code is duplicated when its
6829 estimated size is smaller than this value multiplied by the estimated size of
6830 unconditional jump in the hot spots of the program.
6832 The @option{reorder-block-duplicate-feedback} is used only when profile
6833 feedback is available and may be set to higher values than
6834 @option{reorder-block-duplicate} since information about the hot spots is more
6837 @item max-sched-ready-insns
6838 The maximum number of instructions ready to be issued the scheduler should
6839 consider at any given time during the first scheduling pass. Increasing
6840 values mean more thorough searches, making the compilation time increase
6841 with probably little benefit. The default value is 100.
6843 @item max-sched-region-blocks
6844 The maximum number of blocks in a region to be considered for
6845 interblock scheduling. The default value is 10.
6847 @item max-sched-region-insns
6848 The maximum number of insns in a region to be considered for
6849 interblock scheduling. The default value is 100.
6852 The minimum probability (in percents) of reaching a source block
6853 for interblock speculative scheduling. The default value is 40.
6855 @item max-sched-extend-regions-iters
6856 The maximum number of iterations through CFG to extend regions.
6857 0 - disable region extension,
6858 N - do at most N iterations.
6859 The default value is 0.
6861 @item max-sched-insn-conflict-delay
6862 The maximum conflict delay for an insn to be considered for speculative motion.
6863 The default value is 3.
6865 @item sched-spec-prob-cutoff
6866 The minimal probability of speculation success (in percents), so that
6867 speculative insn will be scheduled.
6868 The default value is 40.
6870 @item max-last-value-rtl
6872 The maximum size measured as number of RTLs that can be recorded in an expression
6873 in combiner for a pseudo register as last known value of that register. The default
6876 @item integer-share-limit
6877 Small integer constants can use a shared data structure, reducing the
6878 compiler's memory usage and increasing its speed. This sets the maximum
6879 value of a shared integer constant's. The default value is 256.
6881 @item min-virtual-mappings
6882 Specifies the minimum number of virtual mappings in the incremental
6883 SSA updater that should be registered to trigger the virtual mappings
6884 heuristic defined by virtual-mappings-ratio. The default value is
6887 @item virtual-mappings-ratio
6888 If the number of virtual mappings is virtual-mappings-ratio bigger
6889 than the number of virtual symbols to be updated, then the incremental
6890 SSA updater switches to a full update for those symbols. The default
6893 @item ssp-buffer-size
6894 The minimum size of buffers (i.e. arrays) that will receive stack smashing
6895 protection when @option{-fstack-protection} is used.
6897 @item max-jump-thread-duplication-stmts
6898 Maximum number of statements allowed in a block that needs to be
6899 duplicated when threading jumps.
6901 @item max-fields-for-field-sensitive
6902 Maximum number of fields in a structure we will treat in
6903 a field sensitive manner during pointer analysis.
6905 @item prefetch-latency
6906 Estimate on average number of instructions that are executed before
6907 prefetch finishes. The distance we prefetch ahead is proportional
6908 to this constant. Increasing this number may also lead to less
6909 streams being prefetched (see @option{simultaneous-prefetches}).
6911 @item simultaneous-prefetches
6912 Maximum number of prefetches that can run at the same time.
6914 @item l1-cache-line-size
6915 The size of cache line in L1 cache, in bytes.
6918 The number of cache lines in L1 cache.
6920 @item verify-canonical-types
6921 Whether the compiler should verify the ``canonical'' types used for
6922 type equality comparisons within the C++ and Objective-C++ front
6923 ends. Set to 1 (the default when GCC is configured with
6924 --enable-checking) to enable verification, 0 to disable verification
6925 (the default when GCC is configured with --disable-checking).
6930 @node Preprocessor Options
6931 @section Options Controlling the Preprocessor
6932 @cindex preprocessor options
6933 @cindex options, preprocessor
6935 These options control the C preprocessor, which is run on each C source
6936 file before actual compilation.
6938 If you use the @option{-E} option, nothing is done except preprocessing.
6939 Some of these options make sense only together with @option{-E} because
6940 they cause the preprocessor output to be unsuitable for actual
6945 You can use @option{-Wp,@var{option}} to bypass the compiler driver
6946 and pass @var{option} directly through to the preprocessor. If
6947 @var{option} contains commas, it is split into multiple options at the
6948 commas. However, many options are modified, translated or interpreted
6949 by the compiler driver before being passed to the preprocessor, and
6950 @option{-Wp} forcibly bypasses this phase. The preprocessor's direct
6951 interface is undocumented and subject to change, so whenever possible
6952 you should avoid using @option{-Wp} and let the driver handle the
6955 @item -Xpreprocessor @var{option}
6956 @opindex preprocessor
6957 Pass @var{option} as an option to the preprocessor. You can use this to
6958 supply system-specific preprocessor options which GCC does not know how to
6961 If you want to pass an option that takes an argument, you must use
6962 @option{-Xpreprocessor} twice, once for the option and once for the argument.
6965 @include cppopts.texi
6967 @node Assembler Options
6968 @section Passing Options to the Assembler
6970 @c prevent bad page break with this line
6971 You can pass options to the assembler.
6974 @item -Wa,@var{option}
6976 Pass @var{option} as an option to the assembler. If @var{option}
6977 contains commas, it is split into multiple options at the commas.
6979 @item -Xassembler @var{option}
6981 Pass @var{option} as an option to the assembler. You can use this to
6982 supply system-specific assembler options which GCC does not know how to
6985 If you want to pass an option that takes an argument, you must use
6986 @option{-Xassembler} twice, once for the option and once for the argument.
6991 @section Options for Linking
6992 @cindex link options
6993 @cindex options, linking
6995 These options come into play when the compiler links object files into
6996 an executable output file. They are meaningless if the compiler is
6997 not doing a link step.
7001 @item @var{object-file-name}
7002 A file name that does not end in a special recognized suffix is
7003 considered to name an object file or library. (Object files are
7004 distinguished from libraries by the linker according to the file
7005 contents.) If linking is done, these object files are used as input
7014 If any of these options is used, then the linker is not run, and
7015 object file names should not be used as arguments. @xref{Overall
7019 @item -l@var{library}
7020 @itemx -l @var{library}
7022 Search the library named @var{library} when linking. (The second
7023 alternative with the library as a separate argument is only for
7024 POSIX compliance and is not recommended.)
7026 It makes a difference where in the command you write this option; the
7027 linker searches and processes libraries and object files in the order they
7028 are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
7029 after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
7030 to functions in @samp{z}, those functions may not be loaded.
7032 The linker searches a standard list of directories for the library,
7033 which is actually a file named @file{lib@var{library}.a}. The linker
7034 then uses this file as if it had been specified precisely by name.
7036 The directories searched include several standard system directories
7037 plus any that you specify with @option{-L}.
7039 Normally the files found this way are library files---archive files
7040 whose members are object files. The linker handles an archive file by
7041 scanning through it for members which define symbols that have so far
7042 been referenced but not defined. But if the file that is found is an
7043 ordinary object file, it is linked in the usual fashion. The only
7044 difference between using an @option{-l} option and specifying a file name
7045 is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
7046 and searches several directories.
7050 You need this special case of the @option{-l} option in order to
7051 link an Objective-C or Objective-C++ program.
7054 @opindex nostartfiles
7055 Do not use the standard system startup files when linking.
7056 The standard system libraries are used normally, unless @option{-nostdlib}
7057 or @option{-nodefaultlibs} is used.
7059 @item -nodefaultlibs
7060 @opindex nodefaultlibs
7061 Do not use the standard system libraries when linking.
7062 Only the libraries you specify will be passed to the linker.
7063 The standard startup files are used normally, unless @option{-nostartfiles}
7064 is used. The compiler may generate calls to @code{memcmp},
7065 @code{memset}, @code{memcpy} and @code{memmove}.
7066 These entries are usually resolved by entries in
7067 libc. These entry points should be supplied through some other
7068 mechanism when this option is specified.
7072 Do not use the standard system startup files or libraries when linking.
7073 No startup files and only the libraries you specify will be passed to
7074 the linker. The compiler may generate calls to @code{memcmp}, @code{memset},
7075 @code{memcpy} and @code{memmove}.
7076 These entries are usually resolved by entries in
7077 libc. These entry points should be supplied through some other
7078 mechanism when this option is specified.
7080 @cindex @option{-lgcc}, use with @option{-nostdlib}
7081 @cindex @option{-nostdlib} and unresolved references
7082 @cindex unresolved references and @option{-nostdlib}
7083 @cindex @option{-lgcc}, use with @option{-nodefaultlibs}
7084 @cindex @option{-nodefaultlibs} and unresolved references
7085 @cindex unresolved references and @option{-nodefaultlibs}
7086 One of the standard libraries bypassed by @option{-nostdlib} and
7087 @option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
7088 that GCC uses to overcome shortcomings of particular machines, or special
7089 needs for some languages.
7090 (@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
7091 Collection (GCC) Internals},
7092 for more discussion of @file{libgcc.a}.)
7093 In most cases, you need @file{libgcc.a} even when you want to avoid
7094 other standard libraries. In other words, when you specify @option{-nostdlib}
7095 or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
7096 This ensures that you have no unresolved references to internal GCC
7097 library subroutines. (For example, @samp{__main}, used to ensure C++
7098 constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
7099 GNU Compiler Collection (GCC) Internals}.)
7103 Produce a position independent executable on targets which support it.
7104 For predictable results, you must also specify the same set of options
7105 that were used to generate code (@option{-fpie}, @option{-fPIE},
7106 or model suboptions) when you specify this option.
7110 Pass the flag @option{-export-dynamic} to the ELF linker, on targets
7111 that support it. This instructs the linker to add all symbols, not
7112 only used ones, to the dynamic symbol table. This option is needed
7113 for some uses of @code{dlopen} or to allow obtaining backtraces
7114 from within a program.
7118 Remove all symbol table and relocation information from the executable.
7122 On systems that support dynamic linking, this prevents linking with the shared
7123 libraries. On other systems, this option has no effect.
7127 Produce a shared object which can then be linked with other objects to
7128 form an executable. Not all systems support this option. For predictable
7129 results, you must also specify the same set of options that were used to
7130 generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
7131 when you specify this option.@footnote{On some systems, @samp{gcc -shared}
7132 needs to build supplementary stub code for constructors to work. On
7133 multi-libbed systems, @samp{gcc -shared} must select the correct support
7134 libraries to link against. Failing to supply the correct flags may lead
7135 to subtle defects. Supplying them in cases where they are not necessary
7138 @item -shared-libgcc
7139 @itemx -static-libgcc
7140 @opindex shared-libgcc
7141 @opindex static-libgcc
7142 On systems that provide @file{libgcc} as a shared library, these options
7143 force the use of either the shared or static version respectively.
7144 If no shared version of @file{libgcc} was built when the compiler was
7145 configured, these options have no effect.
7147 There are several situations in which an application should use the
7148 shared @file{libgcc} instead of the static version. The most common
7149 of these is when the application wishes to throw and catch exceptions
7150 across different shared libraries. In that case, each of the libraries
7151 as well as the application itself should use the shared @file{libgcc}.
7153 Therefore, the G++ and GCJ drivers automatically add
7154 @option{-shared-libgcc} whenever you build a shared library or a main
7155 executable, because C++ and Java programs typically use exceptions, so
7156 this is the right thing to do.
7158 If, instead, you use the GCC driver to create shared libraries, you may
7159 find that they will not always be linked with the shared @file{libgcc}.
7160 If GCC finds, at its configuration time, that you have a non-GNU linker
7161 or a GNU linker that does not support option @option{--eh-frame-hdr},
7162 it will link the shared version of @file{libgcc} into shared libraries
7163 by default. Otherwise, it will take advantage of the linker and optimize
7164 away the linking with the shared version of @file{libgcc}, linking with
7165 the static version of libgcc by default. This allows exceptions to
7166 propagate through such shared libraries, without incurring relocation
7167 costs at library load time.
7169 However, if a library or main executable is supposed to throw or catch
7170 exceptions, you must link it using the G++ or GCJ driver, as appropriate
7171 for the languages used in the program, or using the option
7172 @option{-shared-libgcc}, such that it is linked with the shared
7177 Bind references to global symbols when building a shared object. Warn
7178 about any unresolved references (unless overridden by the link editor
7179 option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
7182 @item -Xlinker @var{option}
7184 Pass @var{option} as an option to the linker. You can use this to
7185 supply system-specific linker options which GCC does not know how to
7188 If you want to pass an option that takes an argument, you must use
7189 @option{-Xlinker} twice, once for the option and once for the argument.
7190 For example, to pass @option{-assert definitions}, you must write
7191 @samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
7192 @option{-Xlinker "-assert definitions"}, because this passes the entire
7193 string as a single argument, which is not what the linker expects.
7195 @item -Wl,@var{option}
7197 Pass @var{option} as an option to the linker. If @var{option} contains
7198 commas, it is split into multiple options at the commas.
7200 @item -u @var{symbol}
7202 Pretend the symbol @var{symbol} is undefined, to force linking of
7203 library modules to define it. You can use @option{-u} multiple times with
7204 different symbols to force loading of additional library modules.
7207 @node Directory Options
7208 @section Options for Directory Search
7209 @cindex directory options
7210 @cindex options, directory search
7213 These options specify directories to search for header files, for
7214 libraries and for parts of the compiler:
7219 Add the directory @var{dir} to the head of the list of directories to be
7220 searched for header files. This can be used to override a system header
7221 file, substituting your own version, since these directories are
7222 searched before the system header file directories. However, you should
7223 not use this option to add directories that contain vendor-supplied
7224 system header files (use @option{-isystem} for that). If you use more than
7225 one @option{-I} option, the directories are scanned in left-to-right
7226 order; the standard system directories come after.
7228 If a standard system include directory, or a directory specified with
7229 @option{-isystem}, is also specified with @option{-I}, the @option{-I}
7230 option will be ignored. The directory will still be searched but as a
7231 system directory at its normal position in the system include chain.
7232 This is to ensure that GCC's procedure to fix buggy system headers and
7233 the ordering for the include_next directive are not inadvertently changed.
7234 If you really need to change the search order for system directories,
7235 use the @option{-nostdinc} and/or @option{-isystem} options.
7237 @item -iquote@var{dir}
7239 Add the directory @var{dir} to the head of the list of directories to
7240 be searched for header files only for the case of @samp{#include
7241 "@var{file}"}; they are not searched for @samp{#include <@var{file}>},
7242 otherwise just like @option{-I}.
7246 Add directory @var{dir} to the list of directories to be searched
7249 @item -B@var{prefix}
7251 This option specifies where to find the executables, libraries,
7252 include files, and data files of the compiler itself.
7254 The compiler driver program runs one or more of the subprograms
7255 @file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
7256 @var{prefix} as a prefix for each program it tries to run, both with and
7257 without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
7259 For each subprogram to be run, the compiler driver first tries the
7260 @option{-B} prefix, if any. If that name is not found, or if @option{-B}
7261 was not specified, the driver tries two standard prefixes, which are
7262 @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of
7263 those results in a file name that is found, the unmodified program
7264 name is searched for using the directories specified in your
7265 @env{PATH} environment variable.
7267 The compiler will check to see if the path provided by the @option{-B}
7268 refers to a directory, and if necessary it will add a directory
7269 separator character at the end of the path.
7271 @option{-B} prefixes that effectively specify directory names also apply
7272 to libraries in the linker, because the compiler translates these
7273 options into @option{-L} options for the linker. They also apply to
7274 includes files in the preprocessor, because the compiler translates these
7275 options into @option{-isystem} options for the preprocessor. In this case,
7276 the compiler appends @samp{include} to the prefix.
7278 The run-time support file @file{libgcc.a} can also be searched for using
7279 the @option{-B} prefix, if needed. If it is not found there, the two
7280 standard prefixes above are tried, and that is all. The file is left
7281 out of the link if it is not found by those means.
7283 Another way to specify a prefix much like the @option{-B} prefix is to use
7284 the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
7287 As a special kludge, if the path provided by @option{-B} is
7288 @file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
7289 9, then it will be replaced by @file{[dir/]include}. This is to help
7290 with boot-strapping the compiler.
7292 @item -specs=@var{file}
7294 Process @var{file} after the compiler reads in the standard @file{specs}
7295 file, in order to override the defaults that the @file{gcc} driver
7296 program uses when determining what switches to pass to @file{cc1},
7297 @file{cc1plus}, @file{as}, @file{ld}, etc. More than one
7298 @option{-specs=@var{file}} can be specified on the command line, and they
7299 are processed in order, from left to right.
7301 @item --sysroot=@var{dir}
7303 Use @var{dir} as the logical root directory for headers and libraries.
7304 For example, if the compiler would normally search for headers in
7305 @file{/usr/include} and libraries in @file{/usr/lib}, it will instead
7306 search @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
7308 If you use both this option and the @option{-isysroot} option, then
7309 the @option{--sysroot} option will apply to libraries, but the
7310 @option{-isysroot} option will apply to header files.
7312 The GNU linker (beginning with version 2.16) has the necessary support
7313 for this option. If your linker does not support this option, the
7314 header file aspect of @option{--sysroot} will still work, but the
7315 library aspect will not.
7319 This option has been deprecated. Please use @option{-iquote} instead for
7320 @option{-I} directories before the @option{-I-} and remove the @option{-I-}.
7321 Any directories you specify with @option{-I} options before the @option{-I-}
7322 option are searched only for the case of @samp{#include "@var{file}"};
7323 they are not searched for @samp{#include <@var{file}>}.
7325 If additional directories are specified with @option{-I} options after
7326 the @option{-I-}, these directories are searched for all @samp{#include}
7327 directives. (Ordinarily @emph{all} @option{-I} directories are used
7330 In addition, the @option{-I-} option inhibits the use of the current
7331 directory (where the current input file came from) as the first search
7332 directory for @samp{#include "@var{file}"}. There is no way to
7333 override this effect of @option{-I-}. With @option{-I.} you can specify
7334 searching the directory which was current when the compiler was
7335 invoked. That is not exactly the same as what the preprocessor does
7336 by default, but it is often satisfactory.
7338 @option{-I-} does not inhibit the use of the standard system directories
7339 for header files. Thus, @option{-I-} and @option{-nostdinc} are
7346 @section Specifying subprocesses and the switches to pass to them
7349 @command{gcc} is a driver program. It performs its job by invoking a
7350 sequence of other programs to do the work of compiling, assembling and
7351 linking. GCC interprets its command-line parameters and uses these to
7352 deduce which programs it should invoke, and which command-line options
7353 it ought to place on their command lines. This behavior is controlled
7354 by @dfn{spec strings}. In most cases there is one spec string for each
7355 program that GCC can invoke, but a few programs have multiple spec
7356 strings to control their behavior. The spec strings built into GCC can
7357 be overridden by using the @option{-specs=} command-line switch to specify
7360 @dfn{Spec files} are plaintext files that are used to construct spec
7361 strings. They consist of a sequence of directives separated by blank
7362 lines. The type of directive is determined by the first non-whitespace
7363 character on the line and it can be one of the following:
7366 @item %@var{command}
7367 Issues a @var{command} to the spec file processor. The commands that can
7371 @item %include <@var{file}>
7373 Search for @var{file} and insert its text at the current point in the
7376 @item %include_noerr <@var{file}>
7377 @cindex %include_noerr
7378 Just like @samp{%include}, but do not generate an error message if the include
7379 file cannot be found.
7381 @item %rename @var{old_name} @var{new_name}
7383 Rename the spec string @var{old_name} to @var{new_name}.
7387 @item *[@var{spec_name}]:
7388 This tells the compiler to create, override or delete the named spec
7389 string. All lines after this directive up to the next directive or
7390 blank line are considered to be the text for the spec string. If this
7391 results in an empty string then the spec will be deleted. (Or, if the
7392 spec did not exist, then nothing will happened.) Otherwise, if the spec
7393 does not currently exist a new spec will be created. If the spec does
7394 exist then its contents will be overridden by the text of this
7395 directive, unless the first character of that text is the @samp{+}
7396 character, in which case the text will be appended to the spec.
7398 @item [@var{suffix}]:
7399 Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
7400 and up to the next directive or blank line are considered to make up the
7401 spec string for the indicated suffix. When the compiler encounters an
7402 input file with the named suffix, it will processes the spec string in
7403 order to work out how to compile that file. For example:
7410 This says that any input file whose name ends in @samp{.ZZ} should be
7411 passed to the program @samp{z-compile}, which should be invoked with the
7412 command-line switch @option{-input} and with the result of performing the
7413 @samp{%i} substitution. (See below.)
7415 As an alternative to providing a spec string, the text that follows a
7416 suffix directive can be one of the following:
7419 @item @@@var{language}
7420 This says that the suffix is an alias for a known @var{language}. This is
7421 similar to using the @option{-x} command-line switch to GCC to specify a
7422 language explicitly. For example:
7429 Says that .ZZ files are, in fact, C++ source files.
7432 This causes an error messages saying:
7435 @var{name} compiler not installed on this system.
7439 GCC already has an extensive list of suffixes built into it.
7440 This directive will add an entry to the end of the list of suffixes, but
7441 since the list is searched from the end backwards, it is effectively
7442 possible to override earlier entries using this technique.
7446 GCC has the following spec strings built into it. Spec files can
7447 override these strings or create their own. Note that individual
7448 targets can also add their own spec strings to this list.
7451 asm Options to pass to the assembler
7452 asm_final Options to pass to the assembler post-processor
7453 cpp Options to pass to the C preprocessor
7454 cc1 Options to pass to the C compiler
7455 cc1plus Options to pass to the C++ compiler
7456 endfile Object files to include at the end of the link
7457 link Options to pass to the linker
7458 lib Libraries to include on the command line to the linker
7459 libgcc Decides which GCC support library to pass to the linker
7460 linker Sets the name of the linker
7461 predefines Defines to be passed to the C preprocessor
7462 signed_char Defines to pass to CPP to say whether @code{char} is signed
7464 startfile Object files to include at the start of the link
7467 Here is a small example of a spec file:
7473 --start-group -lgcc -lc -leval1 --end-group %(old_lib)
7476 This example renames the spec called @samp{lib} to @samp{old_lib} and
7477 then overrides the previous definition of @samp{lib} with a new one.
7478 The new definition adds in some extra command-line options before
7479 including the text of the old definition.
7481 @dfn{Spec strings} are a list of command-line options to be passed to their
7482 corresponding program. In addition, the spec strings can contain
7483 @samp{%}-prefixed sequences to substitute variable text or to
7484 conditionally insert text into the command line. Using these constructs
7485 it is possible to generate quite complex command lines.
7487 Here is a table of all defined @samp{%}-sequences for spec
7488 strings. Note that spaces are not generated automatically around the
7489 results of expanding these sequences. Therefore you can concatenate them
7490 together or combine them with constant text in a single argument.
7494 Substitute one @samp{%} into the program name or argument.
7497 Substitute the name of the input file being processed.
7500 Substitute the basename of the input file being processed.
7501 This is the substring up to (and not including) the last period
7502 and not including the directory.
7505 This is the same as @samp{%b}, but include the file suffix (text after
7509 Marks the argument containing or following the @samp{%d} as a
7510 temporary file name, so that that file will be deleted if GCC exits
7511 successfully. Unlike @samp{%g}, this contributes no text to the
7514 @item %g@var{suffix}
7515 Substitute a file name that has suffix @var{suffix} and is chosen
7516 once per compilation, and mark the argument in the same way as
7517 @samp{%d}. To reduce exposure to denial-of-service attacks, the file
7518 name is now chosen in a way that is hard to predict even when previously
7519 chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
7520 might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
7521 the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
7522 treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
7523 was simply substituted with a file name chosen once per compilation,
7524 without regard to any appended suffix (which was therefore treated
7525 just like ordinary text), making such attacks more likely to succeed.
7527 @item %u@var{suffix}
7528 Like @samp{%g}, but generates a new temporary file name even if
7529 @samp{%u@var{suffix}} was already seen.
7531 @item %U@var{suffix}
7532 Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
7533 new one if there is no such last file name. In the absence of any
7534 @samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
7535 the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
7536 would involve the generation of two distinct file names, one
7537 for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
7538 simply substituted with a file name chosen for the previous @samp{%u},
7539 without regard to any appended suffix.
7541 @item %j@var{suffix}
7542 Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
7543 writable, and if save-temps is off; otherwise, substitute the name
7544 of a temporary file, just like @samp{%u}. This temporary file is not
7545 meant for communication between processes, but rather as a junk
7548 @item %|@var{suffix}
7549 @itemx %m@var{suffix}
7550 Like @samp{%g}, except if @option{-pipe} is in effect. In that case
7551 @samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
7552 all. These are the two most common ways to instruct a program that it
7553 should read from standard input or write to standard output. If you
7554 need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
7555 construct: see for example @file{f/lang-specs.h}.
7557 @item %.@var{SUFFIX}
7558 Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
7559 when it is subsequently output with @samp{%*}. @var{SUFFIX} is
7560 terminated by the next space or %.
7563 Marks the argument containing or following the @samp{%w} as the
7564 designated output file of this compilation. This puts the argument
7565 into the sequence of arguments that @samp{%o} will substitute later.
7568 Substitutes the names of all the output files, with spaces
7569 automatically placed around them. You should write spaces
7570 around the @samp{%o} as well or the results are undefined.
7571 @samp{%o} is for use in the specs for running the linker.
7572 Input files whose names have no recognized suffix are not compiled
7573 at all, but they are included among the output files, so they will
7577 Substitutes the suffix for object files. Note that this is
7578 handled specially when it immediately follows @samp{%g, %u, or %U},
7579 because of the need for those to form complete file names. The
7580 handling is such that @samp{%O} is treated exactly as if it had already
7581 been substituted, except that @samp{%g, %u, and %U} do not currently
7582 support additional @var{suffix} characters following @samp{%O} as they would
7583 following, for example, @samp{.o}.
7586 Substitutes the standard macro predefinitions for the
7587 current target machine. Use this when running @code{cpp}.
7590 Like @samp{%p}, but puts @samp{__} before and after the name of each
7591 predefined macro, except for macros that start with @samp{__} or with
7592 @samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
7596 Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
7597 @option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
7598 @option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
7599 and @option{-imultilib} as necessary.
7602 Current argument is the name of a library or startup file of some sort.
7603 Search for that file in a standard list of directories and substitute
7604 the full name found.
7607 Print @var{str} as an error message. @var{str} is terminated by a newline.
7608 Use this when inconsistent options are detected.
7611 Substitute the contents of spec string @var{name} at this point.
7614 Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
7616 @item %x@{@var{option}@}
7617 Accumulate an option for @samp{%X}.
7620 Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
7624 Output the accumulated assembler options specified by @option{-Wa}.
7627 Output the accumulated preprocessor options specified by @option{-Wp}.
7630 Process the @code{asm} spec. This is used to compute the
7631 switches to be passed to the assembler.
7634 Process the @code{asm_final} spec. This is a spec string for
7635 passing switches to an assembler post-processor, if such a program is
7639 Process the @code{link} spec. This is the spec for computing the
7640 command line passed to the linker. Typically it will make use of the
7641 @samp{%L %G %S %D and %E} sequences.
7644 Dump out a @option{-L} option for each directory that GCC believes might
7645 contain startup files. If the target supports multilibs then the
7646 current multilib directory will be prepended to each of these paths.
7649 Process the @code{lib} spec. This is a spec string for deciding which
7650 libraries should be included on the command line to the linker.
7653 Process the @code{libgcc} spec. This is a spec string for deciding
7654 which GCC support library should be included on the command line to the linker.
7657 Process the @code{startfile} spec. This is a spec for deciding which
7658 object files should be the first ones passed to the linker. Typically
7659 this might be a file named @file{crt0.o}.
7662 Process the @code{endfile} spec. This is a spec string that specifies
7663 the last object files that will be passed to the linker.
7666 Process the @code{cpp} spec. This is used to construct the arguments
7667 to be passed to the C preprocessor.
7670 Process the @code{cc1} spec. This is used to construct the options to be
7671 passed to the actual C compiler (@samp{cc1}).
7674 Process the @code{cc1plus} spec. This is used to construct the options to be
7675 passed to the actual C++ compiler (@samp{cc1plus}).
7678 Substitute the variable part of a matched option. See below.
7679 Note that each comma in the substituted string is replaced by
7683 Remove all occurrences of @code{-S} from the command line. Note---this
7684 command is position dependent. @samp{%} commands in the spec string
7685 before this one will see @code{-S}, @samp{%} commands in the spec string
7686 after this one will not.
7688 @item %:@var{function}(@var{args})
7689 Call the named function @var{function}, passing it @var{args}.
7690 @var{args} is first processed as a nested spec string, then split
7691 into an argument vector in the usual fashion. The function returns
7692 a string which is processed as if it had appeared literally as part
7693 of the current spec.
7695 The following built-in spec functions are provided:
7699 The @code{getenv} spec function takes two arguments: an environment
7700 variable name and a string. If the environment variable is not
7701 defined, a fatal error is issued. Otherwise, the return value is the
7702 value of the environment variable concatenated with the string. For
7703 example, if @env{TOPDIR} is defined as @file{/path/to/top}, then:
7706 %:getenv(TOPDIR /include)
7709 expands to @file{/path/to/top/include}.
7711 @item @code{if-exists}
7712 The @code{if-exists} spec function takes one argument, an absolute
7713 pathname to a file. If the file exists, @code{if-exists} returns the
7714 pathname. Here is a small example of its usage:
7718 crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
7721 @item @code{if-exists-else}
7722 The @code{if-exists-else} spec function is similar to the @code{if-exists}
7723 spec function, except that it takes two arguments. The first argument is
7724 an absolute pathname to a file. If the file exists, @code{if-exists-else}
7725 returns the pathname. If it does not exist, it returns the second argument.
7726 This way, @code{if-exists-else} can be used to select one file or another,
7727 based on the existence of the first. Here is a small example of its usage:
7731 crt0%O%s %:if-exists(crti%O%s) \
7732 %:if-exists-else(crtbeginT%O%s crtbegin%O%s)
7735 @item @code{replace-outfile}
7736 The @code{replace-outfile} spec function takes two arguments. It looks for the
7737 first argument in the outfiles array and replaces it with the second argument. Here
7738 is a small example of its usage:
7741 %@{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)@}
7744 @item @code{print-asm-header}
7745 The @code{print-asm-header} function takes no arguments and simply
7746 prints a banner like:
7752 Use "-Wa,OPTION" to pass "OPTION" to the assembler.
7755 It is used to separate compiler options from assembler options
7756 in the @option{--target-help} output.
7760 Substitutes the @code{-S} switch, if that switch was given to GCC@.
7761 If that switch was not specified, this substitutes nothing. Note that
7762 the leading dash is omitted when specifying this option, and it is
7763 automatically inserted if the substitution is performed. Thus the spec
7764 string @samp{%@{foo@}} would match the command-line option @option{-foo}
7765 and would output the command line option @option{-foo}.
7767 @item %W@{@code{S}@}
7768 Like %@{@code{S}@} but mark last argument supplied within as a file to be
7771 @item %@{@code{S}*@}
7772 Substitutes all the switches specified to GCC whose names start
7773 with @code{-S}, but which also take an argument. This is used for
7774 switches like @option{-o}, @option{-D}, @option{-I}, etc.
7775 GCC considers @option{-o foo} as being
7776 one switch whose names starts with @samp{o}. %@{o*@} would substitute this
7777 text, including the space. Thus two arguments would be generated.
7779 @item %@{@code{S}*&@code{T}*@}
7780 Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
7781 (the order of @code{S} and @code{T} in the spec is not significant).
7782 There can be any number of ampersand-separated variables; for each the
7783 wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
7785 @item %@{@code{S}:@code{X}@}
7786 Substitutes @code{X}, if the @samp{-S} switch was given to GCC@.
7788 @item %@{!@code{S}:@code{X}@}
7789 Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@.
7791 @item %@{@code{S}*:@code{X}@}
7792 Substitutes @code{X} if one or more switches whose names start with
7793 @code{-S} are specified to GCC@. Normally @code{X} is substituted only
7794 once, no matter how many such switches appeared. However, if @code{%*}
7795 appears somewhere in @code{X}, then @code{X} will be substituted once
7796 for each matching switch, with the @code{%*} replaced by the part of
7797 that switch that matched the @code{*}.
7799 @item %@{.@code{S}:@code{X}@}
7800 Substitutes @code{X}, if processing a file with suffix @code{S}.
7802 @item %@{!.@code{S}:@code{X}@}
7803 Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
7805 @item %@{,@code{S}:@code{X}@}
7806 Substitutes @code{X}, if processing a file for language @code{S}.
7808 @item %@{!,@code{S}:@code{X}@}
7809 Substitutes @code{X}, if not processing a file for language @code{S}.
7811 @item %@{@code{S}|@code{P}:@code{X}@}
7812 Substitutes @code{X} if either @code{-S} or @code{-P} was given to
7813 GCC@. This may be combined with @samp{!}, @samp{.}, @samp{,}, and
7814 @code{*} sequences as well, although they have a stronger binding than
7815 the @samp{|}. If @code{%*} appears in @code{X}, all of the
7816 alternatives must be starred, and only the first matching alternative
7819 For example, a spec string like this:
7822 %@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
7825 will output the following command-line options from the following input
7826 command-line options:
7831 -d fred.c -foo -baz -boggle
7832 -d jim.d -bar -baz -boggle
7835 @item %@{S:X; T:Y; :D@}
7837 If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was
7838 given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
7839 be as many clauses as you need. This may be combined with @code{.},
7840 @code{,}, @code{!}, @code{|}, and @code{*} as needed.
7845 The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
7846 construct may contain other nested @samp{%} constructs or spaces, or
7847 even newlines. They are processed as usual, as described above.
7848 Trailing white space in @code{X} is ignored. White space may also
7849 appear anywhere on the left side of the colon in these constructs,
7850 except between @code{.} or @code{*} and the corresponding word.
7852 The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
7853 handled specifically in these constructs. If another value of
7854 @option{-O} or the negated form of a @option{-f}, @option{-m}, or
7855 @option{-W} switch is found later in the command line, the earlier
7856 switch value is ignored, except with @{@code{S}*@} where @code{S} is
7857 just one letter, which passes all matching options.
7859 The character @samp{|} at the beginning of the predicate text is used to
7860 indicate that a command should be piped to the following command, but
7861 only if @option{-pipe} is specified.
7863 It is built into GCC which switches take arguments and which do not.
7864 (You might think it would be useful to generalize this to allow each
7865 compiler's spec to say which switches take arguments. But this cannot
7866 be done in a consistent fashion. GCC cannot even decide which input
7867 files have been specified without knowing which switches take arguments,
7868 and it must know which input files to compile in order to tell which
7871 GCC also knows implicitly that arguments starting in @option{-l} are to be
7872 treated as compiler output files, and passed to the linker in their
7873 proper position among the other output files.
7875 @c man begin OPTIONS
7877 @node Target Options
7878 @section Specifying Target Machine and Compiler Version
7879 @cindex target options
7880 @cindex cross compiling
7881 @cindex specifying machine version
7882 @cindex specifying compiler version and target machine
7883 @cindex compiler version, specifying
7884 @cindex target machine, specifying
7886 The usual way to run GCC is to run the executable called @file{gcc}, or
7887 @file{<machine>-gcc} when cross-compiling, or
7888 @file{<machine>-gcc-<version>} to run a version other than the one that
7889 was installed last. Sometimes this is inconvenient, so GCC provides
7890 options that will switch to another cross-compiler or version.
7893 @item -b @var{machine}
7895 The argument @var{machine} specifies the target machine for compilation.
7897 The value to use for @var{machine} is the same as was specified as the
7898 machine type when configuring GCC as a cross-compiler. For
7899 example, if a cross-compiler was configured with @samp{configure
7900 arm-elf}, meaning to compile for an arm processor with elf binaries,
7901 then you would specify @option{-b arm-elf} to run that cross compiler.
7902 Because there are other options beginning with @option{-b}, the
7903 configuration must contain a hyphen.
7905 @item -V @var{version}
7907 The argument @var{version} specifies which version of GCC to run.
7908 This is useful when multiple versions are installed. For example,
7909 @var{version} might be @samp{4.0}, meaning to run GCC version 4.0.
7912 The @option{-V} and @option{-b} options work by running the
7913 @file{<machine>-gcc-<version>} executable, so there's no real reason to
7914 use them if you can just run that directly.
7916 @node Submodel Options
7917 @section Hardware Models and Configurations
7918 @cindex submodel options
7919 @cindex specifying hardware config
7920 @cindex hardware models and configurations, specifying
7921 @cindex machine dependent options
7923 Earlier we discussed the standard option @option{-b} which chooses among
7924 different installed compilers for completely different target
7925 machines, such as VAX vs.@: 68000 vs.@: 80386.
7927 In addition, each of these target machine types can have its own
7928 special options, starting with @samp{-m}, to choose among various
7929 hardware models or configurations---for example, 68010 vs 68020,
7930 floating coprocessor or none. A single installed version of the
7931 compiler can compile for any model or configuration, according to the
7934 Some configurations of the compiler also support additional special
7935 options, usually for compatibility with other compilers on the same
7938 @c This list is ordered alphanumerically by subsection name.
7939 @c It should be the same order and spelling as these options are listed
7940 @c in Machine Dependent Options
7946 * Blackfin Options::
7950 * DEC Alpha Options::
7951 * DEC Alpha/VMS Options::
7953 * GNU/Linux Options::
7956 * i386 and x86-64 Options::
7969 * RS/6000 and PowerPC Options::
7970 * S/390 and zSeries Options::
7975 * System V Options::
7976 * TMS320C3x/C4x Options::
7981 * Xstormy16 Options::
7987 @subsection ARC Options
7990 These options are defined for ARC implementations:
7995 Compile code for little endian mode. This is the default.
7999 Compile code for big endian mode.
8002 @opindex mmangle-cpu
8003 Prepend the name of the cpu to all public symbol names.
8004 In multiple-processor systems, there are many ARC variants with different
8005 instruction and register set characteristics. This flag prevents code
8006 compiled for one cpu to be linked with code compiled for another.
8007 No facility exists for handling variants that are ``almost identical''.
8008 This is an all or nothing option.
8010 @item -mcpu=@var{cpu}
8012 Compile code for ARC variant @var{cpu}.
8013 Which variants are supported depend on the configuration.
8014 All variants support @option{-mcpu=base}, this is the default.
8016 @item -mtext=@var{text-section}
8017 @itemx -mdata=@var{data-section}
8018 @itemx -mrodata=@var{readonly-data-section}
8022 Put functions, data, and readonly data in @var{text-section},
8023 @var{data-section}, and @var{readonly-data-section} respectively
8024 by default. This can be overridden with the @code{section} attribute.
8025 @xref{Variable Attributes}.
8030 @subsection ARM Options
8033 These @samp{-m} options are defined for Advanced RISC Machines (ARM)
8037 @item -mabi=@var{name}
8039 Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu},
8040 @samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.
8043 @opindex mapcs-frame
8044 Generate a stack frame that is compliant with the ARM Procedure Call
8045 Standard for all functions, even if this is not strictly necessary for
8046 correct execution of the code. Specifying @option{-fomit-frame-pointer}
8047 with this option will cause the stack frames not to be generated for
8048 leaf functions. The default is @option{-mno-apcs-frame}.
8052 This is a synonym for @option{-mapcs-frame}.
8055 @c not currently implemented
8056 @item -mapcs-stack-check
8057 @opindex mapcs-stack-check
8058 Generate code to check the amount of stack space available upon entry to
8059 every function (that actually uses some stack space). If there is
8060 insufficient space available then either the function
8061 @samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
8062 called, depending upon the amount of stack space required. The run time
8063 system is required to provide these functions. The default is
8064 @option{-mno-apcs-stack-check}, since this produces smaller code.
8066 @c not currently implemented
8068 @opindex mapcs-float
8069 Pass floating point arguments using the float point registers. This is
8070 one of the variants of the APCS@. This option is recommended if the
8071 target hardware has a floating point unit or if a lot of floating point
8072 arithmetic is going to be performed by the code. The default is
8073 @option{-mno-apcs-float}, since integer only code is slightly increased in
8074 size if @option{-mapcs-float} is used.
8076 @c not currently implemented
8077 @item -mapcs-reentrant
8078 @opindex mapcs-reentrant
8079 Generate reentrant, position independent code. The default is
8080 @option{-mno-apcs-reentrant}.
8083 @item -mthumb-interwork
8084 @opindex mthumb-interwork
8085 Generate code which supports calling between the ARM and Thumb
8086 instruction sets. Without this option the two instruction sets cannot
8087 be reliably used inside one program. The default is
8088 @option{-mno-thumb-interwork}, since slightly larger code is generated
8089 when @option{-mthumb-interwork} is specified.
8091 @item -mno-sched-prolog
8092 @opindex mno-sched-prolog
8093 Prevent the reordering of instructions in the function prolog, or the
8094 merging of those instruction with the instructions in the function's
8095 body. This means that all functions will start with a recognizable set
8096 of instructions (or in fact one of a choice from a small set of
8097 different function prologues), and this information can be used to
8098 locate the start if functions inside an executable piece of code. The
8099 default is @option{-msched-prolog}.
8102 @opindex mhard-float
8103 Generate output containing floating point instructions. This is the
8107 @opindex msoft-float
8108 Generate output containing library calls for floating point.
8109 @strong{Warning:} the requisite libraries are not available for all ARM
8110 targets. Normally the facilities of the machine's usual C compiler are
8111 used, but this cannot be done directly in cross-compilation. You must make
8112 your own arrangements to provide suitable library functions for
8115 @option{-msoft-float} changes the calling convention in the output file;
8116 therefore, it is only useful if you compile @emph{all} of a program with
8117 this option. In particular, you need to compile @file{libgcc.a}, the
8118 library that comes with GCC, with @option{-msoft-float} in order for
8121 @item -mfloat-abi=@var{name}
8123 Specifies which ABI to use for floating point values. Permissible values
8124 are: @samp{soft}, @samp{softfp} and @samp{hard}.
8126 @samp{soft} and @samp{hard} are equivalent to @option{-msoft-float}
8127 and @option{-mhard-float} respectively. @samp{softfp} allows the generation
8128 of floating point instructions, but still uses the soft-float calling
8131 @item -mlittle-endian
8132 @opindex mlittle-endian
8133 Generate code for a processor running in little-endian mode. This is
8134 the default for all standard configurations.
8137 @opindex mbig-endian
8138 Generate code for a processor running in big-endian mode; the default is
8139 to compile code for a little-endian processor.
8141 @item -mwords-little-endian
8142 @opindex mwords-little-endian
8143 This option only applies when generating code for big-endian processors.
8144 Generate code for a little-endian word order but a big-endian byte
8145 order. That is, a byte order of the form @samp{32107654}. Note: this
8146 option should only be used if you require compatibility with code for
8147 big-endian ARM processors generated by versions of the compiler prior to
8150 @item -mcpu=@var{name}
8152 This specifies the name of the target ARM processor. GCC uses this name
8153 to determine what kind of instructions it can emit when generating
8154 assembly code. Permissible names are: @samp{arm2}, @samp{arm250},
8155 @samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
8156 @samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
8157 @samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
8158 @samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
8159 @samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},
8160 @samp{arm8}, @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
8161 @samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
8162 @samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},
8163 @samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},
8164 @samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},
8165 @samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
8166 @samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
8167 @samp{arm1156t2-s}, @samp{arm1176jz-s}, @samp{arm1176jzf-s},
8168 @samp{cortex-a8}, @samp{cortex-r4}, @samp{cortex-m3},
8169 @samp{xscale}, @samp{iwmmxt}, @samp{ep9312}.
8171 @itemx -mtune=@var{name}
8173 This option is very similar to the @option{-mcpu=} option, except that
8174 instead of specifying the actual target processor type, and hence
8175 restricting which instructions can be used, it specifies that GCC should
8176 tune the performance of the code as if the target were of the type
8177 specified in this option, but still choosing the instructions that it
8178 will generate based on the cpu specified by a @option{-mcpu=} option.
8179 For some ARM implementations better performance can be obtained by using
8182 @item -march=@var{name}
8184 This specifies the name of the target ARM architecture. GCC uses this
8185 name to determine what kind of instructions it can emit when generating
8186 assembly code. This option can be used in conjunction with or instead
8187 of the @option{-mcpu=} option. Permissible names are: @samp{armv2},
8188 @samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
8189 @samp{armv5}, @samp{armv5t}, @samp{armv5te}, @samp{armv6}, @samp{armv6j},
8190 @samp{armv6t2}, @samp{armv6z}, @samp{armv6zk}, @samp{armv7}, @samp{armv7-a},
8191 @samp{armv7-r}, @samp{armv7-m}, @samp{iwmmxt}, @samp{ep9312}.
8193 @item -mfpu=@var{name}
8194 @itemx -mfpe=@var{number}
8195 @itemx -mfp=@var{number}
8199 This specifies what floating point hardware (or hardware emulation) is
8200 available on the target. Permissible names are: @samp{fpa}, @samp{fpe2},
8201 @samp{fpe3}, @samp{maverick}, @samp{vfp}. @option{-mfp} and @option{-mfpe}
8202 are synonyms for @option{-mfpu}=@samp{fpe}@var{number}, for compatibility
8203 with older versions of GCC@.
8205 If @option{-msoft-float} is specified this specifies the format of
8206 floating point values.
8208 @item -mstructure-size-boundary=@var{n}
8209 @opindex mstructure-size-boundary
8210 The size of all structures and unions will be rounded up to a multiple
8211 of the number of bits set by this option. Permissible values are 8, 32
8212 and 64. The default value varies for different toolchains. For the COFF
8213 targeted toolchain the default value is 8. A value of 64 is only allowed
8214 if the underlying ABI supports it.
8216 Specifying the larger number can produce faster, more efficient code, but
8217 can also increase the size of the program. Different values are potentially
8218 incompatible. Code compiled with one value cannot necessarily expect to
8219 work with code or libraries compiled with another value, if they exchange
8220 information using structures or unions.
8222 @item -mabort-on-noreturn
8223 @opindex mabort-on-noreturn
8224 Generate a call to the function @code{abort} at the end of a
8225 @code{noreturn} function. It will be executed if the function tries to
8229 @itemx -mno-long-calls
8230 @opindex mlong-calls
8231 @opindex mno-long-calls
8232 Tells the compiler to perform function calls by first loading the
8233 address of the function into a register and then performing a subroutine
8234 call on this register. This switch is needed if the target function
8235 will lie outside of the 64 megabyte addressing range of the offset based
8236 version of subroutine call instruction.
8238 Even if this switch is enabled, not all function calls will be turned
8239 into long calls. The heuristic is that static functions, functions
8240 which have the @samp{short-call} attribute, functions that are inside
8241 the scope of a @samp{#pragma no_long_calls} directive and functions whose
8242 definitions have already been compiled within the current compilation
8243 unit, will not be turned into long calls. The exception to this rule is
8244 that weak function definitions, functions with the @samp{long-call}
8245 attribute or the @samp{section} attribute, and functions that are within
8246 the scope of a @samp{#pragma long_calls} directive, will always be
8247 turned into long calls.
8249 This feature is not enabled by default. Specifying
8250 @option{-mno-long-calls} will restore the default behavior, as will
8251 placing the function calls within the scope of a @samp{#pragma
8252 long_calls_off} directive. Note these switches have no effect on how
8253 the compiler generates code to handle function calls via function
8256 @item -mnop-fun-dllimport
8257 @opindex mnop-fun-dllimport
8258 Disable support for the @code{dllimport} attribute.
8260 @item -msingle-pic-base
8261 @opindex msingle-pic-base
8262 Treat the register used for PIC addressing as read-only, rather than
8263 loading it in the prologue for each function. The run-time system is
8264 responsible for initializing this register with an appropriate value
8265 before execution begins.
8267 @item -mpic-register=@var{reg}
8268 @opindex mpic-register
8269 Specify the register to be used for PIC addressing. The default is R10
8270 unless stack-checking is enabled, when R9 is used.
8272 @item -mcirrus-fix-invalid-insns
8273 @opindex mcirrus-fix-invalid-insns
8274 @opindex mno-cirrus-fix-invalid-insns
8275 Insert NOPs into the instruction stream to in order to work around
8276 problems with invalid Maverick instruction combinations. This option
8277 is only valid if the @option{-mcpu=ep9312} option has been used to
8278 enable generation of instructions for the Cirrus Maverick floating
8279 point co-processor. This option is not enabled by default, since the
8280 problem is only present in older Maverick implementations. The default
8281 can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns}
8284 @item -mpoke-function-name
8285 @opindex mpoke-function-name
8286 Write the name of each function into the text section, directly
8287 preceding the function prologue. The generated code is similar to this:
8291 .ascii "arm_poke_function_name", 0
8294 .word 0xff000000 + (t1 - t0)
8295 arm_poke_function_name
8297 stmfd sp!, @{fp, ip, lr, pc@}
8301 When performing a stack backtrace, code can inspect the value of
8302 @code{pc} stored at @code{fp + 0}. If the trace function then looks at
8303 location @code{pc - 12} and the top 8 bits are set, then we know that
8304 there is a function name embedded immediately preceding this location
8305 and has length @code{((pc[-3]) & 0xff000000)}.
8309 Generate code for the Thumb instruction set. The default is to
8310 use the 32-bit ARM instruction set.
8311 This option automatically enables either 16-bit Thumb-1 or
8312 mixed 16/32-bit Thumb-2 instructions based on the @option{-mcpu=@var{name}}
8313 and @option{-march=@var{name}} options.
8316 @opindex mtpcs-frame
8317 Generate a stack frame that is compliant with the Thumb Procedure Call
8318 Standard for all non-leaf functions. (A leaf function is one that does
8319 not call any other functions.) The default is @option{-mno-tpcs-frame}.
8321 @item -mtpcs-leaf-frame
8322 @opindex mtpcs-leaf-frame
8323 Generate a stack frame that is compliant with the Thumb Procedure Call
8324 Standard for all leaf functions. (A leaf function is one that does
8325 not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
8327 @item -mcallee-super-interworking
8328 @opindex mcallee-super-interworking
8329 Gives all externally visible functions in the file being compiled an ARM
8330 instruction set header which switches to Thumb mode before executing the
8331 rest of the function. This allows these functions to be called from
8332 non-interworking code.
8334 @item -mcaller-super-interworking
8335 @opindex mcaller-super-interworking
8336 Allows calls via function pointers (including virtual functions) to
8337 execute correctly regardless of whether the target code has been
8338 compiled for interworking or not. There is a small overhead in the cost
8339 of executing a function pointer if this option is enabled.
8341 @item -mtp=@var{name}
8343 Specify the access model for the thread local storage pointer. The valid
8344 models are @option{soft}, which generates calls to @code{__aeabi_read_tp},
8345 @option{cp15}, which fetches the thread pointer from @code{cp15} directly
8346 (supported in the arm6k architecture), and @option{auto}, which uses the
8347 best available method for the selected processor. The default setting is
8353 @subsection AVR Options
8356 These options are defined for AVR implementations:
8359 @item -mmcu=@var{mcu}
8361 Specify ATMEL AVR instruction set or MCU type.
8363 Instruction set avr1 is for the minimal AVR core, not supported by the C
8364 compiler, only for assembler programs (MCU types: at90s1200, attiny10,
8365 attiny11, attiny12, attiny15, attiny28).
8367 Instruction set avr2 (default) is for the classic AVR core with up to
8368 8K program memory space (MCU types: at90s2313, at90s2323, attiny22,
8369 at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
8370 at90c8534, at90s8535).
8372 Instruction set avr3 is for the classic AVR core with up to 128K program
8373 memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
8375 Instruction set avr4 is for the enhanced AVR core with up to 8K program
8376 memory space (MCU types: atmega8, atmega83, atmega85).
8378 Instruction set avr5 is for the enhanced AVR core with up to 128K program
8379 memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
8380 atmega64, atmega128, at43usb355, at94k).
8384 Output instruction sizes to the asm file.
8386 @item -minit-stack=@var{N}
8387 @opindex minit-stack
8388 Specify the initial stack address, which may be a symbol or numeric value,
8389 @samp{__stack} is the default.
8391 @item -mno-interrupts
8392 @opindex mno-interrupts
8393 Generated code is not compatible with hardware interrupts.
8394 Code size will be smaller.
8396 @item -mcall-prologues
8397 @opindex mcall-prologues
8398 Functions prologues/epilogues expanded as call to appropriate
8399 subroutines. Code size will be smaller.
8401 @item -mno-tablejump
8402 @opindex mno-tablejump
8403 Do not generate tablejump insns which sometimes increase code size.
8406 @opindex mtiny-stack
8407 Change only the low 8 bits of the stack pointer.
8411 Assume int to be 8 bit integer. This affects the sizes of all types: A
8412 char will be 1 byte, an int will be 1 byte, an long will be 2 bytes
8413 and long long will be 4 bytes. Please note that this option does not
8414 comply to the C standards, but it will provide you with smaller code
8418 @node Blackfin Options
8419 @subsection Blackfin Options
8420 @cindex Blackfin Options
8423 @item -mcpu=@var{cpu}
8425 Specifies the name of the target Blackfin processor. Currently, @var{cpu}
8426 can be one of @samp{bf531}, @samp{bf532}, @samp{bf533},
8427 @samp{bf534}, @samp{bf536}, @samp{bf537}, @samp{bf561}.
8428 Without this option, @samp{bf532} is used as the processor by default.
8429 The corresponding predefined processor macros for @var{cpu} is to
8430 be defined. For the @samp{bfin-elf} toolchain, this causes the hardware
8431 BSP provided by libgloss to be linked in if @samp{-msim} is not given.
8432 Support for @samp{bf561} is incomplete; only the processor macro is defined.
8436 Specifies that the program will be run on the simulator. This causes
8437 the simulator BSP provided by libgloss to be linked in. This option
8438 has effect only for @samp{bfin-elf} toolchain.
8440 @item -momit-leaf-frame-pointer
8441 @opindex momit-leaf-frame-pointer
8442 Don't keep the frame pointer in a register for leaf functions. This
8443 avoids the instructions to save, set up and restore frame pointers and
8444 makes an extra register available in leaf functions. The option
8445 @option{-fomit-frame-pointer} removes the frame pointer for all functions
8446 which might make debugging harder.
8448 @item -mspecld-anomaly
8449 @opindex mspecld-anomaly
8450 When enabled, the compiler will ensure that the generated code does not
8451 contain speculative loads after jump instructions. This option is enabled
8454 @item -mno-specld-anomaly
8455 @opindex mno-specld-anomaly
8456 Don't generate extra code to prevent speculative loads from occurring.
8458 @item -mcsync-anomaly
8459 @opindex mcsync-anomaly
8460 When enabled, the compiler will ensure that the generated code does not
8461 contain CSYNC or SSYNC instructions too soon after conditional branches.
8462 This option is enabled by default.
8464 @item -mno-csync-anomaly
8465 @opindex mno-csync-anomaly
8466 Don't generate extra code to prevent CSYNC or SSYNC instructions from
8467 occurring too soon after a conditional branch.
8471 When enabled, the compiler is free to take advantage of the knowledge that
8472 the entire program fits into the low 64k of memory.
8475 @opindex mno-low-64k
8476 Assume that the program is arbitrarily large. This is the default.
8478 @item -mstack-check-l1
8479 @opindex mstack-check-l1
8480 Do stack checking using information placed into L1 scratchpad memory by the
8483 @item -mid-shared-library
8484 @opindex mid-shared-library
8485 Generate code that supports shared libraries via the library ID method.
8486 This allows for execute in place and shared libraries in an environment
8487 without virtual memory management. This option implies @option{-fPIC}.
8489 @item -mno-id-shared-library
8490 @opindex mno-id-shared-library
8491 Generate code that doesn't assume ID based shared libraries are being used.
8492 This is the default.
8494 @item -mleaf-id-shared-library
8495 @opindex mleaf-id-shared-library
8496 Generate code that supports shared libraries via the library ID method,
8497 but assumes that this library or executable won't link against any other
8498 ID shared libraries. That allows the compiler to use faster code for jumps
8501 @item -mno-leaf-id-shared-library
8502 @opindex mno-leaf-id-shared-library
8503 Do not assume that the code being compiled won't link against any ID shared
8504 libraries. Slower code will be generated for jump and call insns.
8506 @item -mshared-library-id=n
8507 @opindex mshared-library-id
8508 Specified the identification number of the ID based shared library being
8509 compiled. Specifying a value of 0 will generate more compact code, specifying
8510 other values will force the allocation of that number to the current
8511 library but is no more space or time efficient than omitting this option.
8515 Generate code that allows the data segment to be located in a different
8516 area of memory from the text segment. This allows for execute in place in
8517 an environment without virtual memory management by eliminating relocations
8518 against the text section.
8521 @opindex mno-sep-data
8522 Generate code that assumes that the data segment follows the text segment.
8523 This is the default.
8526 @itemx -mno-long-calls
8527 @opindex mlong-calls
8528 @opindex mno-long-calls
8529 Tells the compiler to perform function calls by first loading the
8530 address of the function into a register and then performing a subroutine
8531 call on this register. This switch is needed if the target function
8532 will lie outside of the 24 bit addressing range of the offset based
8533 version of subroutine call instruction.
8535 This feature is not enabled by default. Specifying
8536 @option{-mno-long-calls} will restore the default behavior. Note these
8537 switches have no effect on how the compiler generates code to handle
8538 function calls via function pointers.
8542 @subsection CRIS Options
8543 @cindex CRIS Options
8545 These options are defined specifically for the CRIS ports.
8548 @item -march=@var{architecture-type}
8549 @itemx -mcpu=@var{architecture-type}
8552 Generate code for the specified architecture. The choices for
8553 @var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
8554 respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
8555 Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
8558 @item -mtune=@var{architecture-type}
8560 Tune to @var{architecture-type} everything applicable about the generated
8561 code, except for the ABI and the set of available instructions. The
8562 choices for @var{architecture-type} are the same as for
8563 @option{-march=@var{architecture-type}}.
8565 @item -mmax-stack-frame=@var{n}
8566 @opindex mmax-stack-frame
8567 Warn when the stack frame of a function exceeds @var{n} bytes.
8569 @item -melinux-stacksize=@var{n}
8570 @opindex melinux-stacksize
8571 Only available with the @samp{cris-axis-aout} target. Arranges for
8572 indications in the program to the kernel loader that the stack of the
8573 program should be set to @var{n} bytes.
8579 The options @option{-metrax4} and @option{-metrax100} are synonyms for
8580 @option{-march=v3} and @option{-march=v8} respectively.
8582 @item -mmul-bug-workaround
8583 @itemx -mno-mul-bug-workaround
8584 @opindex mmul-bug-workaround
8585 @opindex mno-mul-bug-workaround
8586 Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
8587 models where it applies. This option is active by default.
8591 Enable CRIS-specific verbose debug-related information in the assembly
8592 code. This option also has the effect to turn off the @samp{#NO_APP}
8593 formatted-code indicator to the assembler at the beginning of the
8598 Do not use condition-code results from previous instruction; always emit
8599 compare and test instructions before use of condition codes.
8601 @item -mno-side-effects
8602 @opindex mno-side-effects
8603 Do not emit instructions with side-effects in addressing modes other than
8607 @itemx -mno-stack-align
8609 @itemx -mno-data-align
8610 @itemx -mconst-align
8611 @itemx -mno-const-align
8612 @opindex mstack-align
8613 @opindex mno-stack-align
8614 @opindex mdata-align
8615 @opindex mno-data-align
8616 @opindex mconst-align
8617 @opindex mno-const-align
8618 These options (no-options) arranges (eliminate arrangements) for the
8619 stack-frame, individual data and constants to be aligned for the maximum
8620 single data access size for the chosen CPU model. The default is to
8621 arrange for 32-bit alignment. ABI details such as structure layout are
8622 not affected by these options.
8630 Similar to the stack- data- and const-align options above, these options
8631 arrange for stack-frame, writable data and constants to all be 32-bit,
8632 16-bit or 8-bit aligned. The default is 32-bit alignment.
8634 @item -mno-prologue-epilogue
8635 @itemx -mprologue-epilogue
8636 @opindex mno-prologue-epilogue
8637 @opindex mprologue-epilogue
8638 With @option{-mno-prologue-epilogue}, the normal function prologue and
8639 epilogue that sets up the stack-frame are omitted and no return
8640 instructions or return sequences are generated in the code. Use this
8641 option only together with visual inspection of the compiled code: no
8642 warnings or errors are generated when call-saved registers must be saved,
8643 or storage for local variable needs to be allocated.
8649 With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
8650 instruction sequences that load addresses for functions from the PLT part
8651 of the GOT rather than (traditional on other architectures) calls to the
8652 PLT@. The default is @option{-mgotplt}.
8656 Legacy no-op option only recognized with the cris-axis-aout target.
8660 Legacy no-op option only recognized with the cris-axis-elf and
8661 cris-axis-linux-gnu targets.
8665 Only recognized with the cris-axis-aout target, where it selects a
8666 GNU/linux-like multilib, include files and instruction set for
8671 Legacy no-op option only recognized with the cris-axis-linux-gnu target.
8675 This option, recognized for the cris-axis-aout and cris-axis-elf arranges
8676 to link with input-output functions from a simulator library. Code,
8677 initialized data and zero-initialized data are allocated consecutively.
8681 Like @option{-sim}, but pass linker options to locate initialized data at
8682 0x40000000 and zero-initialized data at 0x80000000.
8686 @subsection CRX Options
8689 These options are defined specifically for the CRX ports.
8695 Enable the use of multiply-accumulate instructions. Disabled by default.
8699 Push instructions will be used to pass outgoing arguments when functions
8700 are called. Enabled by default.
8703 @node Darwin Options
8704 @subsection Darwin Options
8705 @cindex Darwin options
8707 These options are defined for all architectures running the Darwin operating
8710 FSF GCC on Darwin does not create ``fat'' object files; it will create
8711 an object file for the single architecture that it was built to
8712 target. Apple's GCC on Darwin does create ``fat'' files if multiple
8713 @option{-arch} options are used; it does so by running the compiler or
8714 linker multiple times and joining the results together with
8717 The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
8718 @samp{i686}) is determined by the flags that specify the ISA
8719 that GCC is targetting, like @option{-mcpu} or @option{-march}. The
8720 @option{-force_cpusubtype_ALL} option can be used to override this.
8722 The Darwin tools vary in their behavior when presented with an ISA
8723 mismatch. The assembler, @file{as}, will only permit instructions to
8724 be used that are valid for the subtype of the file it is generating,
8725 so you cannot put 64-bit instructions in an @samp{ppc750} object file.
8726 The linker for shared libraries, @file{/usr/bin/libtool}, will fail
8727 and print an error if asked to create a shared library with a less
8728 restrictive subtype than its input files (for instance, trying to put
8729 a @samp{ppc970} object file in a @samp{ppc7400} library). The linker
8730 for executables, @file{ld}, will quietly give the executable the most
8731 restrictive subtype of any of its input files.
8736 Add the framework directory @var{dir} to the head of the list of
8737 directories to be searched for header files. These directories are
8738 interleaved with those specified by @option{-I} options and are
8739 scanned in a left-to-right order.
8741 A framework directory is a directory with frameworks in it. A
8742 framework is a directory with a @samp{"Headers"} and/or
8743 @samp{"PrivateHeaders"} directory contained directly in it that ends
8744 in @samp{".framework"}. The name of a framework is the name of this
8745 directory excluding the @samp{".framework"}. Headers associated with
8746 the framework are found in one of those two directories, with
8747 @samp{"Headers"} being searched first. A subframework is a framework
8748 directory that is in a framework's @samp{"Frameworks"} directory.
8749 Includes of subframework headers can only appear in a header of a
8750 framework that contains the subframework, or in a sibling subframework
8751 header. Two subframeworks are siblings if they occur in the same
8752 framework. A subframework should not have the same name as a
8753 framework, a warning will be issued if this is violated. Currently a
8754 subframework cannot have subframeworks, in the future, the mechanism
8755 may be extended to support this. The standard frameworks can be found
8756 in @samp{"/System/Library/Frameworks"} and
8757 @samp{"/Library/Frameworks"}. An example include looks like
8758 @code{#include <Framework/header.h>}, where @samp{Framework} denotes
8759 the name of the framework and header.h is found in the
8760 @samp{"PrivateHeaders"} or @samp{"Headers"} directory.
8762 @item -iframework@var{dir}
8764 Like @option{-F} except the directory is a treated as a system
8765 directory. The main difference between this @option{-iframework} and
8766 @option{-F} is that with @option{-iframework} the compiler does not
8767 warn about constructs contained within header files found via
8768 @var{dir}. This option is valid only for the C family of languages.
8772 Emit debugging information for symbols that are used. For STABS
8773 debugging format, this enables @option{-feliminate-unused-debug-symbols}.
8774 This is by default ON@.
8778 Emit debugging information for all symbols and types.
8780 @item -mmacosx-version-min=@var{version}
8781 The earliest version of MacOS X that this executable will run on
8782 is @var{version}. Typical values of @var{version} include @code{10.1},
8783 @code{10.2}, and @code{10.3.9}.
8785 If the compiler was built to use the system's headers by default,
8786 then the default for this option is the system version on which the
8787 compiler is running, otherwise the default is to make choices which
8788 are compatible with as many systems and code bases as possible.
8792 Enable kernel development mode. The @option{-mkernel} option sets
8793 @option{-static}, @option{-fno-common}, @option{-fno-cxa-atexit},
8794 @option{-fno-exceptions}, @option{-fno-non-call-exceptions},
8795 @option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where
8796 applicable. This mode also sets @option{-mno-altivec},
8797 @option{-msoft-float}, @option{-fno-builtin} and
8798 @option{-mlong-branch} for PowerPC targets.
8800 @item -mone-byte-bool
8801 @opindex mone-byte-bool
8802 Override the defaults for @samp{bool} so that @samp{sizeof(bool)==1}.
8803 By default @samp{sizeof(bool)} is @samp{4} when compiling for
8804 Darwin/PowerPC and @samp{1} when compiling for Darwin/x86, so this
8805 option has no effect on x86.
8807 @strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
8808 to generate code that is not binary compatible with code generated
8809 without that switch. Using this switch may require recompiling all
8810 other modules in a program, including system libraries. Use this
8811 switch to conform to a non-default data model.
8813 @item -mfix-and-continue
8814 @itemx -ffix-and-continue
8815 @itemx -findirect-data
8816 @opindex mfix-and-continue
8817 @opindex ffix-and-continue
8818 @opindex findirect-data
8819 Generate code suitable for fast turn around development. Needed to
8820 enable gdb to dynamically load @code{.o} files into already running
8821 programs. @option{-findirect-data} and @option{-ffix-and-continue}
8822 are provided for backwards compatibility.
8826 Loads all members of static archive libraries.
8827 See man ld(1) for more information.
8829 @item -arch_errors_fatal
8830 @opindex arch_errors_fatal
8831 Cause the errors having to do with files that have the wrong architecture
8835 @opindex bind_at_load
8836 Causes the output file to be marked such that the dynamic linker will
8837 bind all undefined references when the file is loaded or launched.
8841 Produce a Mach-o bundle format file.
8842 See man ld(1) for more information.
8844 @item -bundle_loader @var{executable}
8845 @opindex bundle_loader
8846 This option specifies the @var{executable} that will be loading the build
8847 output file being linked. See man ld(1) for more information.
8851 When passed this option, GCC will produce a dynamic library instead of
8852 an executable when linking, using the Darwin @file{libtool} command.
8854 @item -force_cpusubtype_ALL
8855 @opindex force_cpusubtype_ALL
8856 This causes GCC's output file to have the @var{ALL} subtype, instead of
8857 one controlled by the @option{-mcpu} or @option{-march} option.
8859 @item -allowable_client @var{client_name}
8861 @itemx -compatibility_version
8862 @itemx -current_version
8864 @itemx -dependency-file
8866 @itemx -dylinker_install_name
8868 @itemx -exported_symbols_list
8870 @itemx -flat_namespace
8871 @itemx -force_flat_namespace
8872 @itemx -headerpad_max_install_names
8875 @itemx -install_name
8876 @itemx -keep_private_externs
8877 @itemx -multi_module
8878 @itemx -multiply_defined
8879 @itemx -multiply_defined_unused
8881 @itemx -no_dead_strip_inits_and_terms
8882 @itemx -nofixprebinding
8885 @itemx -noseglinkedit
8886 @itemx -pagezero_size
8888 @itemx -prebind_all_twolevel_modules
8889 @itemx -private_bundle
8890 @itemx -read_only_relocs
8892 @itemx -sectobjectsymbols
8896 @itemx -sectobjectsymbols
8899 @itemx -segs_read_only_addr
8900 @itemx -segs_read_write_addr
8901 @itemx -seg_addr_table
8902 @itemx -seg_addr_table_filename
8905 @itemx -segs_read_only_addr
8906 @itemx -segs_read_write_addr
8907 @itemx -single_module
8910 @itemx -sub_umbrella
8911 @itemx -twolevel_namespace
8914 @itemx -unexported_symbols_list
8915 @itemx -weak_reference_mismatches
8918 @opindex allowable_client
8919 @opindex client_name
8920 @opindex compatibility_version
8921 @opindex current_version
8923 @opindex dependency-file
8925 @opindex dylinker_install_name
8927 @opindex exported_symbols_list
8929 @opindex flat_namespace
8930 @opindex force_flat_namespace
8931 @opindex headerpad_max_install_names
8934 @opindex install_name
8935 @opindex keep_private_externs
8936 @opindex multi_module
8937 @opindex multiply_defined
8938 @opindex multiply_defined_unused
8940 @opindex no_dead_strip_inits_and_terms
8941 @opindex nofixprebinding
8942 @opindex nomultidefs
8944 @opindex noseglinkedit
8945 @opindex pagezero_size
8947 @opindex prebind_all_twolevel_modules
8948 @opindex private_bundle
8949 @opindex read_only_relocs
8951 @opindex sectobjectsymbols
8955 @opindex sectobjectsymbols
8958 @opindex segs_read_only_addr
8959 @opindex segs_read_write_addr
8960 @opindex seg_addr_table
8961 @opindex seg_addr_table_filename
8962 @opindex seglinkedit
8964 @opindex segs_read_only_addr
8965 @opindex segs_read_write_addr
8966 @opindex single_module
8968 @opindex sub_library
8969 @opindex sub_umbrella
8970 @opindex twolevel_namespace
8973 @opindex unexported_symbols_list
8974 @opindex weak_reference_mismatches
8975 @opindex whatsloaded
8977 These options are passed to the Darwin linker. The Darwin linker man page
8978 describes them in detail.
8981 @node DEC Alpha Options
8982 @subsection DEC Alpha Options
8984 These @samp{-m} options are defined for the DEC Alpha implementations:
8987 @item -mno-soft-float
8989 @opindex mno-soft-float
8990 @opindex msoft-float
8991 Use (do not use) the hardware floating-point instructions for
8992 floating-point operations. When @option{-msoft-float} is specified,
8993 functions in @file{libgcc.a} will be used to perform floating-point
8994 operations. Unless they are replaced by routines that emulate the
8995 floating-point operations, or compiled in such a way as to call such
8996 emulations routines, these routines will issue floating-point
8997 operations. If you are compiling for an Alpha without floating-point
8998 operations, you must ensure that the library is built so as not to call
9001 Note that Alpha implementations without floating-point operations are
9002 required to have floating-point registers.
9007 @opindex mno-fp-regs
9008 Generate code that uses (does not use) the floating-point register set.
9009 @option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
9010 register set is not used, floating point operands are passed in integer
9011 registers as if they were integers and floating-point results are passed
9012 in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
9013 so any function with a floating-point argument or return value called by code
9014 compiled with @option{-mno-fp-regs} must also be compiled with that
9017 A typical use of this option is building a kernel that does not use,
9018 and hence need not save and restore, any floating-point registers.
9022 The Alpha architecture implements floating-point hardware optimized for
9023 maximum performance. It is mostly compliant with the IEEE floating
9024 point standard. However, for full compliance, software assistance is
9025 required. This option generates code fully IEEE compliant code
9026 @emph{except} that the @var{inexact-flag} is not maintained (see below).
9027 If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
9028 defined during compilation. The resulting code is less efficient but is
9029 able to correctly support denormalized numbers and exceptional IEEE
9030 values such as not-a-number and plus/minus infinity. Other Alpha
9031 compilers call this option @option{-ieee_with_no_inexact}.
9033 @item -mieee-with-inexact
9034 @opindex mieee-with-inexact
9035 This is like @option{-mieee} except the generated code also maintains
9036 the IEEE @var{inexact-flag}. Turning on this option causes the
9037 generated code to implement fully-compliant IEEE math. In addition to
9038 @code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
9039 macro. On some Alpha implementations the resulting code may execute
9040 significantly slower than the code generated by default. Since there is
9041 very little code that depends on the @var{inexact-flag}, you should
9042 normally not specify this option. Other Alpha compilers call this
9043 option @option{-ieee_with_inexact}.
9045 @item -mfp-trap-mode=@var{trap-mode}
9046 @opindex mfp-trap-mode
9047 This option controls what floating-point related traps are enabled.
9048 Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
9049 The trap mode can be set to one of four values:
9053 This is the default (normal) setting. The only traps that are enabled
9054 are the ones that cannot be disabled in software (e.g., division by zero
9058 In addition to the traps enabled by @samp{n}, underflow traps are enabled
9062 Like @samp{u}, but the instructions are marked to be safe for software
9063 completion (see Alpha architecture manual for details).
9066 Like @samp{su}, but inexact traps are enabled as well.
9069 @item -mfp-rounding-mode=@var{rounding-mode}
9070 @opindex mfp-rounding-mode
9071 Selects the IEEE rounding mode. Other Alpha compilers call this option
9072 @option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
9077 Normal IEEE rounding mode. Floating point numbers are rounded towards
9078 the nearest machine number or towards the even machine number in case
9082 Round towards minus infinity.
9085 Chopped rounding mode. Floating point numbers are rounded towards zero.
9088 Dynamic rounding mode. A field in the floating point control register
9089 (@var{fpcr}, see Alpha architecture reference manual) controls the
9090 rounding mode in effect. The C library initializes this register for
9091 rounding towards plus infinity. Thus, unless your program modifies the
9092 @var{fpcr}, @samp{d} corresponds to round towards plus infinity.
9095 @item -mtrap-precision=@var{trap-precision}
9096 @opindex mtrap-precision
9097 In the Alpha architecture, floating point traps are imprecise. This
9098 means without software assistance it is impossible to recover from a
9099 floating trap and program execution normally needs to be terminated.
9100 GCC can generate code that can assist operating system trap handlers
9101 in determining the exact location that caused a floating point trap.
9102 Depending on the requirements of an application, different levels of
9103 precisions can be selected:
9107 Program precision. This option is the default and means a trap handler
9108 can only identify which program caused a floating point exception.
9111 Function precision. The trap handler can determine the function that
9112 caused a floating point exception.
9115 Instruction precision. The trap handler can determine the exact
9116 instruction that caused a floating point exception.
9119 Other Alpha compilers provide the equivalent options called
9120 @option{-scope_safe} and @option{-resumption_safe}.
9122 @item -mieee-conformant
9123 @opindex mieee-conformant
9124 This option marks the generated code as IEEE conformant. You must not
9125 use this option unless you also specify @option{-mtrap-precision=i} and either
9126 @option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
9127 is to emit the line @samp{.eflag 48} in the function prologue of the
9128 generated assembly file. Under DEC Unix, this has the effect that
9129 IEEE-conformant math library routines will be linked in.
9131 @item -mbuild-constants
9132 @opindex mbuild-constants
9133 Normally GCC examines a 32- or 64-bit integer constant to
9134 see if it can construct it from smaller constants in two or three
9135 instructions. If it cannot, it will output the constant as a literal and
9136 generate code to load it from the data segment at runtime.
9138 Use this option to require GCC to construct @emph{all} integer constants
9139 using code, even if it takes more instructions (the maximum is six).
9141 You would typically use this option to build a shared library dynamic
9142 loader. Itself a shared library, it must relocate itself in memory
9143 before it can find the variables and constants in its own data segment.
9149 Select whether to generate code to be assembled by the vendor-supplied
9150 assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
9168 Indicate whether GCC should generate code to use the optional BWX,
9169 CIX, FIX and MAX instruction sets. The default is to use the instruction
9170 sets supported by the CPU type specified via @option{-mcpu=} option or that
9171 of the CPU on which GCC was built if none was specified.
9176 @opindex mfloat-ieee
9177 Generate code that uses (does not use) VAX F and G floating point
9178 arithmetic instead of IEEE single and double precision.
9180 @item -mexplicit-relocs
9181 @itemx -mno-explicit-relocs
9182 @opindex mexplicit-relocs
9183 @opindex mno-explicit-relocs
9184 Older Alpha assemblers provided no way to generate symbol relocations
9185 except via assembler macros. Use of these macros does not allow
9186 optimal instruction scheduling. GNU binutils as of version 2.12
9187 supports a new syntax that allows the compiler to explicitly mark
9188 which relocations should apply to which instructions. This option
9189 is mostly useful for debugging, as GCC detects the capabilities of
9190 the assembler when it is built and sets the default accordingly.
9194 @opindex msmall-data
9195 @opindex mlarge-data
9196 When @option{-mexplicit-relocs} is in effect, static data is
9197 accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
9198 is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
9199 (the @code{.sdata} and @code{.sbss} sections) and are accessed via
9200 16-bit relocations off of the @code{$gp} register. This limits the
9201 size of the small data area to 64KB, but allows the variables to be
9202 directly accessed via a single instruction.
9204 The default is @option{-mlarge-data}. With this option the data area
9205 is limited to just below 2GB@. Programs that require more than 2GB of
9206 data must use @code{malloc} or @code{mmap} to allocate the data in the
9207 heap instead of in the program's data segment.
9209 When generating code for shared libraries, @option{-fpic} implies
9210 @option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
9214 @opindex msmall-text
9215 @opindex mlarge-text
9216 When @option{-msmall-text} is used, the compiler assumes that the
9217 code of the entire program (or shared library) fits in 4MB, and is
9218 thus reachable with a branch instruction. When @option{-msmall-data}
9219 is used, the compiler can assume that all local symbols share the
9220 same @code{$gp} value, and thus reduce the number of instructions
9221 required for a function call from 4 to 1.
9223 The default is @option{-mlarge-text}.
9225 @item -mcpu=@var{cpu_type}
9227 Set the instruction set and instruction scheduling parameters for
9228 machine type @var{cpu_type}. You can specify either the @samp{EV}
9229 style name or the corresponding chip number. GCC supports scheduling
9230 parameters for the EV4, EV5 and EV6 family of processors and will
9231 choose the default values for the instruction set from the processor
9232 you specify. If you do not specify a processor type, GCC will default
9233 to the processor on which the compiler was built.
9235 Supported values for @var{cpu_type} are
9241 Schedules as an EV4 and has no instruction set extensions.
9245 Schedules as an EV5 and has no instruction set extensions.
9249 Schedules as an EV5 and supports the BWX extension.
9254 Schedules as an EV5 and supports the BWX and MAX extensions.
9258 Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
9262 Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
9265 @item -mtune=@var{cpu_type}
9267 Set only the instruction scheduling parameters for machine type
9268 @var{cpu_type}. The instruction set is not changed.
9270 @item -mmemory-latency=@var{time}
9271 @opindex mmemory-latency
9272 Sets the latency the scheduler should assume for typical memory
9273 references as seen by the application. This number is highly
9274 dependent on the memory access patterns used by the application
9275 and the size of the external cache on the machine.
9277 Valid options for @var{time} are
9281 A decimal number representing clock cycles.
9287 The compiler contains estimates of the number of clock cycles for
9288 ``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
9289 (also called Dcache, Scache, and Bcache), as well as to main memory.
9290 Note that L3 is only valid for EV5.
9295 @node DEC Alpha/VMS Options
9296 @subsection DEC Alpha/VMS Options
9298 These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
9301 @item -mvms-return-codes
9302 @opindex mvms-return-codes
9303 Return VMS condition codes from main. The default is to return POSIX
9304 style condition (e.g.@ error) codes.
9308 @subsection FRV Options
9315 Only use the first 32 general purpose registers.
9320 Use all 64 general purpose registers.
9325 Use only the first 32 floating point registers.
9330 Use all 64 floating point registers
9333 @opindex mhard-float
9335 Use hardware instructions for floating point operations.
9338 @opindex msoft-float
9340 Use library routines for floating point operations.
9345 Dynamically allocate condition code registers.
9350 Do not try to dynamically allocate condition code registers, only
9351 use @code{icc0} and @code{fcc0}.
9356 Change ABI to use double word insns.
9361 Do not use double word instructions.
9366 Use floating point double instructions.
9371 Do not use floating point double instructions.
9376 Use media instructions.
9381 Do not use media instructions.
9386 Use multiply and add/subtract instructions.
9391 Do not use multiply and add/subtract instructions.
9396 Select the FDPIC ABI, that uses function descriptors to represent
9397 pointers to functions. Without any PIC/PIE-related options, it
9398 implies @option{-fPIE}. With @option{-fpic} or @option{-fpie}, it
9399 assumes GOT entries and small data are within a 12-bit range from the
9400 GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
9401 are computed with 32 bits.
9404 @opindex minline-plt
9406 Enable inlining of PLT entries in function calls to functions that are
9407 not known to bind locally. It has no effect without @option{-mfdpic}.
9408 It's enabled by default if optimizing for speed and compiling for
9409 shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
9410 optimization option such as @option{-O3} or above is present in the
9416 Assume a large TLS segment when generating thread-local code.
9421 Do not assume a large TLS segment when generating thread-local code.
9426 Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
9427 that is known to be in read-only sections. It's enabled by default,
9428 except for @option{-fpic} or @option{-fpie}: even though it may help
9429 make the global offset table smaller, it trades 1 instruction for 4.
9430 With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
9431 one of which may be shared by multiple symbols, and it avoids the need
9432 for a GOT entry for the referenced symbol, so it's more likely to be a
9433 win. If it is not, @option{-mno-gprel-ro} can be used to disable it.
9435 @item -multilib-library-pic
9436 @opindex multilib-library-pic
9438 Link with the (library, not FD) pic libraries. It's implied by
9439 @option{-mlibrary-pic}, as well as by @option{-fPIC} and
9440 @option{-fpic} without @option{-mfdpic}. You should never have to use
9446 Follow the EABI requirement of always creating a frame pointer whenever
9447 a stack frame is allocated. This option is enabled by default and can
9448 be disabled with @option{-mno-linked-fp}.
9451 @opindex mlong-calls
9453 Use indirect addressing to call functions outside the current
9454 compilation unit. This allows the functions to be placed anywhere
9455 within the 32-bit address space.
9457 @item -malign-labels
9458 @opindex malign-labels
9460 Try to align labels to an 8-byte boundary by inserting nops into the
9461 previous packet. This option only has an effect when VLIW packing
9462 is enabled. It doesn't create new packets; it merely adds nops to
9466 @opindex mlibrary-pic
9468 Generate position-independent EABI code.
9473 Use only the first four media accumulator registers.
9478 Use all eight media accumulator registers.
9483 Pack VLIW instructions.
9488 Do not pack VLIW instructions.
9493 Do not mark ABI switches in e_flags.
9498 Enable the use of conditional-move instructions (default).
9500 This switch is mainly for debugging the compiler and will likely be removed
9501 in a future version.
9503 @item -mno-cond-move
9504 @opindex mno-cond-move
9506 Disable the use of conditional-move instructions.
9508 This switch is mainly for debugging the compiler and will likely be removed
9509 in a future version.
9514 Enable the use of conditional set instructions (default).
9516 This switch is mainly for debugging the compiler and will likely be removed
9517 in a future version.
9522 Disable the use of conditional set instructions.
9524 This switch is mainly for debugging the compiler and will likely be removed
9525 in a future version.
9530 Enable the use of conditional execution (default).
9532 This switch is mainly for debugging the compiler and will likely be removed
9533 in a future version.
9535 @item -mno-cond-exec
9536 @opindex mno-cond-exec
9538 Disable the use of conditional execution.
9540 This switch is mainly for debugging the compiler and will likely be removed
9541 in a future version.
9544 @opindex mvliw-branch
9546 Run a pass to pack branches into VLIW instructions (default).
9548 This switch is mainly for debugging the compiler and will likely be removed
9549 in a future version.
9551 @item -mno-vliw-branch
9552 @opindex mno-vliw-branch
9554 Do not run a pass to pack branches into VLIW instructions.
9556 This switch is mainly for debugging the compiler and will likely be removed
9557 in a future version.
9559 @item -mmulti-cond-exec
9560 @opindex mmulti-cond-exec
9562 Enable optimization of @code{&&} and @code{||} in conditional execution
9565 This switch is mainly for debugging the compiler and will likely be removed
9566 in a future version.
9568 @item -mno-multi-cond-exec
9569 @opindex mno-multi-cond-exec
9571 Disable optimization of @code{&&} and @code{||} in conditional execution.
9573 This switch is mainly for debugging the compiler and will likely be removed
9574 in a future version.
9576 @item -mnested-cond-exec
9577 @opindex mnested-cond-exec
9579 Enable nested conditional execution optimizations (default).
9581 This switch is mainly for debugging the compiler and will likely be removed
9582 in a future version.
9584 @item -mno-nested-cond-exec
9585 @opindex mno-nested-cond-exec
9587 Disable nested conditional execution optimizations.
9589 This switch is mainly for debugging the compiler and will likely be removed
9590 in a future version.
9592 @item -moptimize-membar
9593 @opindex moptimize-membar
9595 This switch removes redundant @code{membar} instructions from the
9596 compiler generated code. It is enabled by default.
9598 @item -mno-optimize-membar
9599 @opindex mno-optimize-membar
9601 This switch disables the automatic removal of redundant @code{membar}
9602 instructions from the generated code.
9604 @item -mtomcat-stats
9605 @opindex mtomcat-stats
9607 Cause gas to print out tomcat statistics.
9609 @item -mcpu=@var{cpu}
9612 Select the processor type for which to generate code. Possible values are
9613 @samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
9614 @samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
9618 @node GNU/Linux Options
9619 @subsection GNU/Linux Options
9621 These @samp{-m} options are defined for GNU/Linux targets:
9626 Use the GNU C library instead of uClibc. This is the default except
9627 on @samp{*-*-linux-*uclibc*} targets.
9631 Use uClibc instead of the GNU C library. This is the default on
9632 @samp{*-*-linux-*uclibc*} targets.
9635 @node H8/300 Options
9636 @subsection H8/300 Options
9638 These @samp{-m} options are defined for the H8/300 implementations:
9643 Shorten some address references at link time, when possible; uses the
9644 linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
9645 ld, Using ld}, for a fuller description.
9649 Generate code for the H8/300H@.
9653 Generate code for the H8S@.
9657 Generate code for the H8S and H8/300H in the normal mode. This switch
9658 must be used either with @option{-mh} or @option{-ms}.
9662 Generate code for the H8S/2600. This switch must be used with @option{-ms}.
9666 Make @code{int} data 32 bits by default.
9670 On the H8/300H and H8S, use the same alignment rules as for the H8/300.
9671 The default for the H8/300H and H8S is to align longs and floats on 4
9673 @option{-malign-300} causes them to be aligned on 2 byte boundaries.
9674 This option has no effect on the H8/300.
9678 @subsection HPPA Options
9679 @cindex HPPA Options
9681 These @samp{-m} options are defined for the HPPA family of computers:
9684 @item -march=@var{architecture-type}
9686 Generate code for the specified architecture. The choices for
9687 @var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
9688 1.1, and @samp{2.0} for PA 2.0 processors. Refer to
9689 @file{/usr/lib/sched.models} on an HP-UX system to determine the proper
9690 architecture option for your machine. Code compiled for lower numbered
9691 architectures will run on higher numbered architectures, but not the
9695 @itemx -mpa-risc-1-1
9696 @itemx -mpa-risc-2-0
9697 @opindex mpa-risc-1-0
9698 @opindex mpa-risc-1-1
9699 @opindex mpa-risc-2-0
9700 Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
9703 @opindex mbig-switch
9704 Generate code suitable for big switch tables. Use this option only if
9705 the assembler/linker complain about out of range branches within a switch
9708 @item -mjump-in-delay
9709 @opindex mjump-in-delay
9710 Fill delay slots of function calls with unconditional jump instructions
9711 by modifying the return pointer for the function call to be the target
9712 of the conditional jump.
9714 @item -mdisable-fpregs
9715 @opindex mdisable-fpregs
9716 Prevent floating point registers from being used in any manner. This is
9717 necessary for compiling kernels which perform lazy context switching of
9718 floating point registers. If you use this option and attempt to perform
9719 floating point operations, the compiler will abort.
9721 @item -mdisable-indexing
9722 @opindex mdisable-indexing
9723 Prevent the compiler from using indexing address modes. This avoids some
9724 rather obscure problems when compiling MIG generated code under MACH@.
9726 @item -mno-space-regs
9727 @opindex mno-space-regs
9728 Generate code that assumes the target has no space registers. This allows
9729 GCC to generate faster indirect calls and use unscaled index address modes.
9731 Such code is suitable for level 0 PA systems and kernels.
9733 @item -mfast-indirect-calls
9734 @opindex mfast-indirect-calls
9735 Generate code that assumes calls never cross space boundaries. This
9736 allows GCC to emit code which performs faster indirect calls.
9738 This option will not work in the presence of shared libraries or nested
9741 @item -mfixed-range=@var{register-range}
9742 @opindex mfixed-range
9743 Generate code treating the given register range as fixed registers.
9744 A fixed register is one that the register allocator can not use. This is
9745 useful when compiling kernel code. A register range is specified as
9746 two registers separated by a dash. Multiple register ranges can be
9747 specified separated by a comma.
9749 @item -mlong-load-store
9750 @opindex mlong-load-store
9751 Generate 3-instruction load and store sequences as sometimes required by
9752 the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
9755 @item -mportable-runtime
9756 @opindex mportable-runtime
9757 Use the portable calling conventions proposed by HP for ELF systems.
9761 Enable the use of assembler directives only GAS understands.
9763 @item -mschedule=@var{cpu-type}
9765 Schedule code according to the constraints for the machine type
9766 @var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
9767 @samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer
9768 to @file{/usr/lib/sched.models} on an HP-UX system to determine the
9769 proper scheduling option for your machine. The default scheduling is
9773 @opindex mlinker-opt
9774 Enable the optimization pass in the HP-UX linker. Note this makes symbolic
9775 debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9
9776 linkers in which they give bogus error messages when linking some programs.
9779 @opindex msoft-float
9780 Generate output containing library calls for floating point.
9781 @strong{Warning:} the requisite libraries are not available for all HPPA
9782 targets. Normally the facilities of the machine's usual C compiler are
9783 used, but this cannot be done directly in cross-compilation. You must make
9784 your own arrangements to provide suitable library functions for
9785 cross-compilation. The embedded target @samp{hppa1.1-*-pro}
9786 does provide software floating point support.
9788 @option{-msoft-float} changes the calling convention in the output file;
9789 therefore, it is only useful if you compile @emph{all} of a program with
9790 this option. In particular, you need to compile @file{libgcc.a}, the
9791 library that comes with GCC, with @option{-msoft-float} in order for
9796 Generate the predefine, @code{_SIO}, for server IO@. The default is
9797 @option{-mwsio}. This generates the predefines, @code{__hp9000s700},
9798 @code{__hp9000s700__} and @code{_WSIO}, for workstation IO@. These
9799 options are available under HP-UX and HI-UX@.
9803 Use GNU ld specific options. This passes @option{-shared} to ld when
9804 building a shared library. It is the default when GCC is configured,
9805 explicitly or implicitly, with the GNU linker. This option does not
9806 have any affect on which ld is called, it only changes what parameters
9807 are passed to that ld. The ld that is called is determined by the
9808 @option{--with-ld} configure option, GCC's program search path, and
9809 finally by the user's @env{PATH}. The linker used by GCC can be printed
9810 using @samp{which `gcc -print-prog-name=ld`}. This option is only available
9811 on the 64 bit HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
9815 Use HP ld specific options. This passes @option{-b} to ld when building
9816 a shared library and passes @option{+Accept TypeMismatch} to ld on all
9817 links. It is the default when GCC is configured, explicitly or
9818 implicitly, with the HP linker. This option does not have any affect on
9819 which ld is called, it only changes what parameters are passed to that
9820 ld. The ld that is called is determined by the @option{--with-ld}
9821 configure option, GCC's program search path, and finally by the user's
9822 @env{PATH}. The linker used by GCC can be printed using @samp{which
9823 `gcc -print-prog-name=ld`}. This option is only available on the 64 bit
9824 HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
9827 @opindex mno-long-calls
9828 Generate code that uses long call sequences. This ensures that a call
9829 is always able to reach linker generated stubs. The default is to generate
9830 long calls only when the distance from the call site to the beginning
9831 of the function or translation unit, as the case may be, exceeds a
9832 predefined limit set by the branch type being used. The limits for
9833 normal calls are 7,600,000 and 240,000 bytes, respectively for the
9834 PA 2.0 and PA 1.X architectures. Sibcalls are always limited at
9837 Distances are measured from the beginning of functions when using the
9838 @option{-ffunction-sections} option, or when using the @option{-mgas}
9839 and @option{-mno-portable-runtime} options together under HP-UX with
9842 It is normally not desirable to use this option as it will degrade
9843 performance. However, it may be useful in large applications,
9844 particularly when partial linking is used to build the application.
9846 The types of long calls used depends on the capabilities of the
9847 assembler and linker, and the type of code being generated. The
9848 impact on systems that support long absolute calls, and long pic
9849 symbol-difference or pc-relative calls should be relatively small.
9850 However, an indirect call is used on 32-bit ELF systems in pic code
9851 and it is quite long.
9853 @item -munix=@var{unix-std}
9855 Generate compiler predefines and select a startfile for the specified
9856 UNIX standard. The choices for @var{unix-std} are @samp{93}, @samp{95}
9857 and @samp{98}. @samp{93} is supported on all HP-UX versions. @samp{95}
9858 is available on HP-UX 10.10 and later. @samp{98} is available on HP-UX
9859 11.11 and later. The default values are @samp{93} for HP-UX 10.00,
9860 @samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
9863 @option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
9864 @option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
9865 and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
9866 @option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
9867 @code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
9868 @code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
9870 It is @emph{important} to note that this option changes the interfaces
9871 for various library routines. It also affects the operational behavior
9872 of the C library. Thus, @emph{extreme} care is needed in using this
9875 Library code that is intended to operate with more than one UNIX
9876 standard must test, set and restore the variable @var{__xpg4_extended_mask}
9877 as appropriate. Most GNU software doesn't provide this capability.
9881 Suppress the generation of link options to search libdld.sl when the
9882 @option{-static} option is specified on HP-UX 10 and later.
9886 The HP-UX implementation of setlocale in libc has a dependency on
9887 libdld.sl. There isn't an archive version of libdld.sl. Thus,
9888 when the @option{-static} option is specified, special link options
9889 are needed to resolve this dependency.
9891 On HP-UX 10 and later, the GCC driver adds the necessary options to
9892 link with libdld.sl when the @option{-static} option is specified.
9893 This causes the resulting binary to be dynamic. On the 64-bit port,
9894 the linkers generate dynamic binaries by default in any case. The
9895 @option{-nolibdld} option can be used to prevent the GCC driver from
9896 adding these link options.
9900 Add support for multithreading with the @dfn{dce thread} library
9901 under HP-UX@. This option sets flags for both the preprocessor and
9905 @node i386 and x86-64 Options
9906 @subsection Intel 386 and AMD x86-64 Options
9907 @cindex i386 Options
9908 @cindex x86-64 Options
9909 @cindex Intel 386 Options
9910 @cindex AMD x86-64 Options
9912 These @samp{-m} options are defined for the i386 and x86-64 family of
9916 @item -mtune=@var{cpu-type}
9918 Tune to @var{cpu-type} everything applicable about the generated code, except
9919 for the ABI and the set of available instructions. The choices for
9923 Produce code optimized for the most common IA32/AMD64/EM64T processors.
9924 If you know the CPU on which your code will run, then you should use
9925 the corresponding @option{-mtune} option instead of
9926 @option{-mtune=generic}. But, if you do not know exactly what CPU users
9927 of your application will have, then you should use this option.
9929 As new processors are deployed in the marketplace, the behavior of this
9930 option will change. Therefore, if you upgrade to a newer version of
9931 GCC, the code generated option will change to reflect the processors
9932 that were most common when that version of GCC was released.
9934 There is no @option{-march=generic} option because @option{-march}
9935 indicates the instruction set the compiler can use, and there is no
9936 generic instruction set applicable to all processors. In contrast,
9937 @option{-mtune} indicates the processor (or, in this case, collection of
9938 processors) for which the code is optimized.
9940 This selects the CPU to tune for at compilation time by determining
9941 the processor type of the compiling machine. Using @option{-mtune=native}
9942 will produce code optimized for the local machine under the constraints
9943 of the selected instruction set. Using @option{-march=native} will
9944 enable all instruction subsets supported by the local machine (hence
9945 the result might not run on different machines).
9947 Original Intel's i386 CPU@.
9949 Intel's i486 CPU@. (No scheduling is implemented for this chip.)
9951 Intel Pentium CPU with no MMX support.
9953 Intel PentiumMMX CPU based on Pentium core with MMX instruction set support.
9955 Intel PentiumPro CPU@.
9957 Same as @code{generic}, but when used as @code{march} option, PentiumPro
9958 instruction set will be used, so the code will run on all i686 family chips.
9960 Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support.
9961 @item pentium3, pentium3m
9962 Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set
9965 Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set
9966 support. Used by Centrino notebooks.
9967 @item pentium4, pentium4m
9968 Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support.
9970 Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction
9973 Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE,
9974 SSE2 and SSE3 instruction set support.
9976 Intel Core2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3
9977 instruction set support.
9979 AMD K6 CPU with MMX instruction set support.
9981 Improved versions of AMD K6 CPU with MMX and 3dNOW! instruction set support.
9982 @item athlon, athlon-tbird
9983 AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and SSE prefetch instructions
9985 @item athlon-4, athlon-xp, athlon-mp
9986 Improved AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and full SSE
9987 instruction set support.
9988 @item k8, opteron, athlon64, athlon-fx
9989 AMD K8 core based CPUs with x86-64 instruction set support. (This supersets
9990 MMX, SSE, SSE2, 3dNOW!, enhanced 3dNOW! and 64-bit instruction set extensions.)
9991 @item k8-sse3, opteron-sse3, athlon64-sse3
9992 Improved versions of k8, opteron and athlon64 with SSE3 instruction set support.
9993 @item amdfam10, barcelona
9994 AMD Family 10h core based CPUs with x86-64 instruction set support. (This
9995 supersets MMX, SSE, SSE2, SSE3, SSE4A, 3dNOW!, enhanced 3dNOW!, ABM and 64-bit
9996 instruction set extensions.)
9998 IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction
10001 IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3dNOW!
10002 instruction set support.
10004 Via C3 CPU with MMX and 3dNOW! instruction set support. (No scheduling is
10005 implemented for this chip.)
10007 Via C3-2 CPU with MMX and SSE instruction set support. (No scheduling is
10008 implemented for this chip.)
10010 Embedded AMD CPU with MMX and 3dNOW! instruction set support.
10013 While picking a specific @var{cpu-type} will schedule things appropriately
10014 for that particular chip, the compiler will not generate any code that
10015 does not run on the i386 without the @option{-march=@var{cpu-type}} option
10018 @item -march=@var{cpu-type}
10020 Generate instructions for the machine type @var{cpu-type}. The choices
10021 for @var{cpu-type} are the same as for @option{-mtune}. Moreover,
10022 specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}.
10024 @item -mcpu=@var{cpu-type}
10026 A deprecated synonym for @option{-mtune}.
10028 @item -mfpmath=@var{unit}
10030 Generate floating point arithmetics for selected unit @var{unit}. The choices
10031 for @var{unit} are:
10035 Use the standard 387 floating point coprocessor present majority of chips and
10036 emulated otherwise. Code compiled with this option will run almost everywhere.
10037 The temporary results are computed in 80bit precision instead of precision
10038 specified by the type resulting in slightly different results compared to most
10039 of other chips. See @option{-ffloat-store} for more detailed description.
10041 This is the default choice for i386 compiler.
10044 Use scalar floating point instructions present in the SSE instruction set.
10045 This instruction set is supported by Pentium3 and newer chips, in the AMD line
10046 by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE
10047 instruction set supports only single precision arithmetics, thus the double and
10048 extended precision arithmetics is still done using 387. Later version, present
10049 only in Pentium4 and the future AMD x86-64 chips supports double precision
10052 For the i386 compiler, you need to use @option{-march=@var{cpu-type}}, @option{-msse}
10053 or @option{-msse2} switches to enable SSE extensions and make this option
10054 effective. For the x86-64 compiler, these extensions are enabled by default.
10056 The resulting code should be considerably faster in the majority of cases and avoid
10057 the numerical instability problems of 387 code, but may break some existing
10058 code that expects temporaries to be 80bit.
10060 This is the default choice for the x86-64 compiler.
10063 Attempt to utilize both instruction sets at once. This effectively double the
10064 amount of available registers and on chips with separate execution units for
10065 387 and SSE the execution resources too. Use this option with care, as it is
10066 still experimental, because the GCC register allocator does not model separate
10067 functional units well resulting in instable performance.
10070 @item -masm=@var{dialect}
10071 @opindex masm=@var{dialect}
10072 Output asm instructions using selected @var{dialect}. Supported
10073 choices are @samp{intel} or @samp{att} (the default one). Darwin does
10074 not support @samp{intel}.
10077 @itemx -mno-ieee-fp
10079 @opindex mno-ieee-fp
10080 Control whether or not the compiler uses IEEE floating point
10081 comparisons. These handle correctly the case where the result of a
10082 comparison is unordered.
10085 @opindex msoft-float
10086 Generate output containing library calls for floating point.
10087 @strong{Warning:} the requisite libraries are not part of GCC@.
10088 Normally the facilities of the machine's usual C compiler are used, but
10089 this can't be done directly in cross-compilation. You must make your
10090 own arrangements to provide suitable library functions for
10093 On machines where a function returns floating point results in the 80387
10094 register stack, some floating point opcodes may be emitted even if
10095 @option{-msoft-float} is used.
10097 @item -mno-fp-ret-in-387
10098 @opindex mno-fp-ret-in-387
10099 Do not use the FPU registers for return values of functions.
10101 The usual calling convention has functions return values of types
10102 @code{float} and @code{double} in an FPU register, even if there
10103 is no FPU@. The idea is that the operating system should emulate
10106 The option @option{-mno-fp-ret-in-387} causes such values to be returned
10107 in ordinary CPU registers instead.
10109 @item -mno-fancy-math-387
10110 @opindex mno-fancy-math-387
10111 Some 387 emulators do not support the @code{sin}, @code{cos} and
10112 @code{sqrt} instructions for the 387. Specify this option to avoid
10113 generating those instructions. This option is the default on FreeBSD,
10114 OpenBSD and NetBSD@. This option is overridden when @option{-march}
10115 indicates that the target cpu will always have an FPU and so the
10116 instruction will not need emulation. As of revision 2.6.1, these
10117 instructions are not generated unless you also use the
10118 @option{-funsafe-math-optimizations} switch.
10120 @item -malign-double
10121 @itemx -mno-align-double
10122 @opindex malign-double
10123 @opindex mno-align-double
10124 Control whether GCC aligns @code{double}, @code{long double}, and
10125 @code{long long} variables on a two word boundary or a one word
10126 boundary. Aligning @code{double} variables on a two word boundary will
10127 produce code that runs somewhat faster on a @samp{Pentium} at the
10128 expense of more memory.
10130 On x86-64, @option{-malign-double} is enabled by default.
10132 @strong{Warning:} if you use the @option{-malign-double} switch,
10133 structures containing the above types will be aligned differently than
10134 the published application binary interface specifications for the 386
10135 and will not be binary compatible with structures in code compiled
10136 without that switch.
10138 @item -m96bit-long-double
10139 @itemx -m128bit-long-double
10140 @opindex m96bit-long-double
10141 @opindex m128bit-long-double
10142 These switches control the size of @code{long double} type. The i386
10143 application binary interface specifies the size to be 96 bits,
10144 so @option{-m96bit-long-double} is the default in 32 bit mode.
10146 Modern architectures (Pentium and newer) would prefer @code{long double}
10147 to be aligned to an 8 or 16 byte boundary. In arrays or structures
10148 conforming to the ABI, this would not be possible. So specifying a
10149 @option{-m128bit-long-double} will align @code{long double}
10150 to a 16 byte boundary by padding the @code{long double} with an additional
10153 In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
10154 its ABI specifies that @code{long double} is to be aligned on 16 byte boundary.
10156 Notice that neither of these options enable any extra precision over the x87
10157 standard of 80 bits for a @code{long double}.
10159 @strong{Warning:} if you override the default value for your target ABI, the
10160 structures and arrays containing @code{long double} variables will change
10161 their size as well as function calling convention for function taking
10162 @code{long double} will be modified. Hence they will not be binary
10163 compatible with arrays or structures in code compiled without that switch.
10165 @item -mmlarge-data-threshold=@var{number}
10166 @opindex mlarge-data-threshold=@var{number}
10167 When @option{-mcmodel=medium} is specified, the data greater than
10168 @var{threshold} are placed in large data section. This value must be the
10169 same across all object linked into the binary and defaults to 65535.
10173 Use a different function-calling convention, in which functions that
10174 take a fixed number of arguments return with the @code{ret} @var{num}
10175 instruction, which pops their arguments while returning. This saves one
10176 instruction in the caller since there is no need to pop the arguments
10179 You can specify that an individual function is called with this calling
10180 sequence with the function attribute @samp{stdcall}. You can also
10181 override the @option{-mrtd} option by using the function attribute
10182 @samp{cdecl}. @xref{Function Attributes}.
10184 @strong{Warning:} this calling convention is incompatible with the one
10185 normally used on Unix, so you cannot use it if you need to call
10186 libraries compiled with the Unix compiler.
10188 Also, you must provide function prototypes for all functions that
10189 take variable numbers of arguments (including @code{printf});
10190 otherwise incorrect code will be generated for calls to those
10193 In addition, seriously incorrect code will result if you call a
10194 function with too many arguments. (Normally, extra arguments are
10195 harmlessly ignored.)
10197 @item -mregparm=@var{num}
10199 Control how many registers are used to pass integer arguments. By
10200 default, no registers are used to pass arguments, and at most 3
10201 registers can be used. You can control this behavior for a specific
10202 function by using the function attribute @samp{regparm}.
10203 @xref{Function Attributes}.
10205 @strong{Warning:} if you use this switch, and
10206 @var{num} is nonzero, then you must build all modules with the same
10207 value, including any libraries. This includes the system libraries and
10211 @opindex msseregparm
10212 Use SSE register passing conventions for float and double arguments
10213 and return values. You can control this behavior for a specific
10214 function by using the function attribute @samp{sseregparm}.
10215 @xref{Function Attributes}.
10217 @strong{Warning:} if you use this switch then you must build all
10218 modules with the same value, including any libraries. This includes
10219 the system libraries and startup modules.
10228 Set 80387 floating-point precision to 32, 64 or 80 bits. When @option{-mpc32}
10229 is specified, the significands of results of floating-point operations are
10230 rounded to 24 bits (single precision); @option{-mpc64} rounds the the
10231 significands of results of floating-point operations to 53 bits (double
10232 precision) and @option{-mpc80} rounds the significands of results of
10233 floating-point operations to 64 bits (extended double precision), which is
10234 the default. When this option is used, floating-point operations in higher
10235 precisions are not available to the programmer without setting the FPU
10236 control word explicitly.
10238 Setting the rounding of floating-point operations to less than the default
10239 80 bits can speed some programs by 2% or more. Note that some mathematical
10240 libraries assume that extended precision (80 bit) floating-point operations
10241 are enabled by default; routines in such libraries could suffer significant
10242 loss of accuracy, typically through so-called "catastrophic cancellation",
10243 when this option is used to set the precision to less than extended precision.
10245 @item -mstackrealign
10246 @opindex mstackrealign
10247 Realign the stack at entry. On the Intel x86, the
10248 @option{-mstackrealign} option will generate an alternate prologue and
10249 epilogue that realigns the runtime stack. This supports mixing legacy
10250 codes that keep a 4-byte aligned stack with modern codes that keep a
10251 16-byte stack for SSE compatibility. The alternate prologue and
10252 epilogue are slower and bigger than the regular ones, and the
10253 alternate prologue requires an extra scratch register; this lowers the
10254 number of registers available if used in conjunction with the
10255 @code{regparm} attribute. The @option{-mstackrealign} option is
10256 incompatible with the nested function prologue; this is considered a
10257 hard error. See also the attribute @code{force_align_arg_pointer},
10258 applicable to individual functions.
10260 @item -mpreferred-stack-boundary=@var{num}
10261 @opindex mpreferred-stack-boundary
10262 Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
10263 byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
10264 the default is 4 (16 bytes or 128 bits).
10266 On Pentium and PentiumPro, @code{double} and @code{long double} values
10267 should be aligned to an 8 byte boundary (see @option{-malign-double}) or
10268 suffer significant run time performance penalties. On Pentium III, the
10269 Streaming SIMD Extension (SSE) data type @code{__m128} may not work
10270 properly if it is not 16 byte aligned.
10272 To ensure proper alignment of this values on the stack, the stack boundary
10273 must be as aligned as that required by any value stored on the stack.
10274 Further, every function must be generated such that it keeps the stack
10275 aligned. Thus calling a function compiled with a higher preferred
10276 stack boundary from a function compiled with a lower preferred stack
10277 boundary will most likely misalign the stack. It is recommended that
10278 libraries that use callbacks always use the default setting.
10280 This extra alignment does consume extra stack space, and generally
10281 increases code size. Code that is sensitive to stack space usage, such
10282 as embedded systems and operating system kernels, may want to reduce the
10283 preferred alignment to @option{-mpreferred-stack-boundary=2}.
10315 These switches enable or disable the use of instructions in the MMX,
10316 SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4A, ABM or 3DNow! extended
10318 These extensions are also available as built-in functions: see
10319 @ref{X86 Built-in Functions}, for details of the functions enabled and
10320 disabled by these switches.
10322 To have SSE/SSE2 instructions generated automatically from floating-point
10323 code (as opposed to 387 instructions), see @option{-mfpmath=sse}.
10325 These options will enable GCC to use these extended instructions in
10326 generated code, even without @option{-mfpmath=sse}. Applications which
10327 perform runtime CPU detection must compile separate files for each
10328 supported architecture, using the appropriate flags. In particular,
10329 the file containing the CPU detection code should be compiled without
10334 This option will enable GCC to use CMPXCHG16B instruction in generated code.
10335 CMPXCHG16B allows for atomic operations on 128-bit double quadword (or oword)
10336 data types. This is useful for high resolution counters that could be updated
10337 by multiple processors (or cores). This instruction is generated as part of
10338 atomic built-in functions: see @ref{Atomic Builtins} for details.
10342 This option will enable GCC to use SAHF instruction in generated 64-bit code.
10343 Early Intel CPUs with Intel 64 lacked LAHF and SAHF instructions supported
10344 by AMD64 until introduction of Pentium 4 G1 step in December 2005. LAHF and
10345 SAHF are load and store instructions, respectively, for certain status flags.
10346 In 64-bit mode, SAHF instruction is used to optimize @code{fmod}, @code{drem}
10347 or @code{remainder} built-in functions: see @ref{Other Builtins} for details.
10351 This option will enable GCC to use RCPSS and RSQRTSS instructions (and their
10352 vectorized variants RCPPS and RSQRTPS) instead of DIVSS and SQRTSS (and their
10353 vectorized variants). These instructions will be generated only when
10354 @option{-funsafe-math-optimizatons} is enabled.
10357 @itemx -mno-push-args
10358 @opindex mpush-args
10359 @opindex mno-push-args
10360 Use PUSH operations to store outgoing parameters. This method is shorter
10361 and usually equally fast as method using SUB/MOV operations and is enabled
10362 by default. In some cases disabling it may improve performance because of
10363 improved scheduling and reduced dependencies.
10365 @item -maccumulate-outgoing-args
10366 @opindex maccumulate-outgoing-args
10367 If enabled, the maximum amount of space required for outgoing arguments will be
10368 computed in the function prologue. This is faster on most modern CPUs
10369 because of reduced dependencies, improved scheduling and reduced stack usage
10370 when preferred stack boundary is not equal to 2. The drawback is a notable
10371 increase in code size. This switch implies @option{-mno-push-args}.
10375 Support thread-safe exception handling on @samp{Mingw32}. Code that relies
10376 on thread-safe exception handling must compile and link all code with the
10377 @option{-mthreads} option. When compiling, @option{-mthreads} defines
10378 @option{-D_MT}; when linking, it links in a special thread helper library
10379 @option{-lmingwthrd} which cleans up per thread exception handling data.
10381 @item -mno-align-stringops
10382 @opindex mno-align-stringops
10383 Do not align destination of inlined string operations. This switch reduces
10384 code size and improves performance in case the destination is already aligned,
10385 but GCC doesn't know about it.
10387 @item -minline-all-stringops
10388 @opindex minline-all-stringops
10389 By default GCC inlines string operations only when destination is known to be
10390 aligned at least to 4 byte boundary. This enables more inlining, increase code
10391 size, but may improve performance of code that depends on fast memcpy, strlen
10392 and memset for short lengths.
10394 @item -minline-stringops-dynamically
10395 @opindex minline-stringops-dynamically
10396 For string operation of unknown size, inline runtime checks so for small
10397 blocks inline code is used, while for large blocks library call is used.
10399 @item -mstringop-strategy=@var{alg}
10400 @opindex mstringop-strategy=@var{alg}
10401 Overwrite internal decision heuristic about particular algorithm to inline
10402 string operation with. The allowed values are @code{rep_byte},
10403 @code{rep_4byte}, @code{rep_8byte} for expanding using i386 @code{rep} prefix
10404 of specified size, @code{byte_loop}, @code{loop}, @code{unrolled_loop} for
10405 expanding inline loop, @code{libcall} for always expanding library call.
10407 @item -momit-leaf-frame-pointer
10408 @opindex momit-leaf-frame-pointer
10409 Don't keep the frame pointer in a register for leaf functions. This
10410 avoids the instructions to save, set up and restore frame pointers and
10411 makes an extra register available in leaf functions. The option
10412 @option{-fomit-frame-pointer} removes the frame pointer for all functions
10413 which might make debugging harder.
10415 @item -mtls-direct-seg-refs
10416 @itemx -mno-tls-direct-seg-refs
10417 @opindex mtls-direct-seg-refs
10418 Controls whether TLS variables may be accessed with offsets from the
10419 TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
10420 or whether the thread base pointer must be added. Whether or not this
10421 is legal depends on the operating system, and whether it maps the
10422 segment to cover the entire TLS area.
10424 For systems that use GNU libc, the default is on.
10427 These @samp{-m} switches are supported in addition to the above
10428 on AMD x86-64 processors in 64-bit environments.
10435 Generate code for a 32-bit or 64-bit environment.
10436 The 32-bit environment sets int, long and pointer to 32 bits and
10437 generates code that runs on any i386 system.
10438 The 64-bit environment sets int to 32 bits and long and pointer
10439 to 64 bits and generates code for AMD's x86-64 architecture. For
10440 darwin only the -m64 option turns off the @option{-fno-pic} and
10441 @option{-mdynamic-no-pic} options.
10443 @item -mno-red-zone
10444 @opindex no-red-zone
10445 Do not use a so called red zone for x86-64 code. The red zone is mandated
10446 by the x86-64 ABI, it is a 128-byte area beyond the location of the
10447 stack pointer that will not be modified by signal or interrupt handlers
10448 and therefore can be used for temporary data without adjusting the stack
10449 pointer. The flag @option{-mno-red-zone} disables this red zone.
10451 @item -mcmodel=small
10452 @opindex mcmodel=small
10453 Generate code for the small code model: the program and its symbols must
10454 be linked in the lower 2 GB of the address space. Pointers are 64 bits.
10455 Programs can be statically or dynamically linked. This is the default
10458 @item -mcmodel=kernel
10459 @opindex mcmodel=kernel
10460 Generate code for the kernel code model. The kernel runs in the
10461 negative 2 GB of the address space.
10462 This model has to be used for Linux kernel code.
10464 @item -mcmodel=medium
10465 @opindex mcmodel=medium
10466 Generate code for the medium model: The program is linked in the lower 2
10467 GB of the address space but symbols can be located anywhere in the
10468 address space. Programs can be statically or dynamically linked, but
10469 building of shared libraries are not supported with the medium model.
10471 @item -mcmodel=large
10472 @opindex mcmodel=large
10473 Generate code for the large model: This model makes no assumptions
10474 about addresses and sizes of sections.
10477 @node IA-64 Options
10478 @subsection IA-64 Options
10479 @cindex IA-64 Options
10481 These are the @samp{-m} options defined for the Intel IA-64 architecture.
10485 @opindex mbig-endian
10486 Generate code for a big endian target. This is the default for HP-UX@.
10488 @item -mlittle-endian
10489 @opindex mlittle-endian
10490 Generate code for a little endian target. This is the default for AIX5
10496 @opindex mno-gnu-as
10497 Generate (or don't) code for the GNU assembler. This is the default.
10498 @c Also, this is the default if the configure option @option{--with-gnu-as}
10504 @opindex mno-gnu-ld
10505 Generate (or don't) code for the GNU linker. This is the default.
10506 @c Also, this is the default if the configure option @option{--with-gnu-ld}
10511 Generate code that does not use a global pointer register. The result
10512 is not position independent code, and violates the IA-64 ABI@.
10514 @item -mvolatile-asm-stop
10515 @itemx -mno-volatile-asm-stop
10516 @opindex mvolatile-asm-stop
10517 @opindex mno-volatile-asm-stop
10518 Generate (or don't) a stop bit immediately before and after volatile asm
10521 @item -mregister-names
10522 @itemx -mno-register-names
10523 @opindex mregister-names
10524 @opindex mno-register-names
10525 Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
10526 the stacked registers. This may make assembler output more readable.
10532 Disable (or enable) optimizations that use the small data section. This may
10533 be useful for working around optimizer bugs.
10535 @item -mconstant-gp
10536 @opindex mconstant-gp
10537 Generate code that uses a single constant global pointer value. This is
10538 useful when compiling kernel code.
10542 Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
10543 This is useful when compiling firmware code.
10545 @item -minline-float-divide-min-latency
10546 @opindex minline-float-divide-min-latency
10547 Generate code for inline divides of floating point values
10548 using the minimum latency algorithm.
10550 @item -minline-float-divide-max-throughput
10551 @opindex minline-float-divide-max-throughput
10552 Generate code for inline divides of floating point values
10553 using the maximum throughput algorithm.
10555 @item -minline-int-divide-min-latency
10556 @opindex minline-int-divide-min-latency
10557 Generate code for inline divides of integer values
10558 using the minimum latency algorithm.
10560 @item -minline-int-divide-max-throughput
10561 @opindex minline-int-divide-max-throughput
10562 Generate code for inline divides of integer values
10563 using the maximum throughput algorithm.
10565 @item -minline-sqrt-min-latency
10566 @opindex minline-sqrt-min-latency
10567 Generate code for inline square roots
10568 using the minimum latency algorithm.
10570 @item -minline-sqrt-max-throughput
10571 @opindex minline-sqrt-max-throughput
10572 Generate code for inline square roots
10573 using the maximum throughput algorithm.
10575 @item -mno-dwarf2-asm
10576 @itemx -mdwarf2-asm
10577 @opindex mno-dwarf2-asm
10578 @opindex mdwarf2-asm
10579 Don't (or do) generate assembler code for the DWARF2 line number debugging
10580 info. This may be useful when not using the GNU assembler.
10582 @item -mearly-stop-bits
10583 @itemx -mno-early-stop-bits
10584 @opindex mearly-stop-bits
10585 @opindex mno-early-stop-bits
10586 Allow stop bits to be placed earlier than immediately preceding the
10587 instruction that triggered the stop bit. This can improve instruction
10588 scheduling, but does not always do so.
10590 @item -mfixed-range=@var{register-range}
10591 @opindex mfixed-range
10592 Generate code treating the given register range as fixed registers.
10593 A fixed register is one that the register allocator can not use. This is
10594 useful when compiling kernel code. A register range is specified as
10595 two registers separated by a dash. Multiple register ranges can be
10596 specified separated by a comma.
10598 @item -mtls-size=@var{tls-size}
10600 Specify bit size of immediate TLS offsets. Valid values are 14, 22, and
10603 @item -mtune=@var{cpu-type}
10605 Tune the instruction scheduling for a particular CPU, Valid values are
10606 itanium, itanium1, merced, itanium2, and mckinley.
10612 Add support for multithreading using the POSIX threads library. This
10613 option sets flags for both the preprocessor and linker. It does
10614 not affect the thread safety of object code produced by the compiler or
10615 that of libraries supplied with it. These are HP-UX specific flags.
10621 Generate code for a 32-bit or 64-bit environment.
10622 The 32-bit environment sets int, long and pointer to 32 bits.
10623 The 64-bit environment sets int to 32 bits and long and pointer
10624 to 64 bits. These are HP-UX specific flags.
10626 @item -mno-sched-br-data-spec
10627 @itemx -msched-br-data-spec
10628 @opindex mno-sched-br-data-spec
10629 @opindex msched-br-data-spec
10630 (Dis/En)able data speculative scheduling before reload.
10631 This will result in generation of the ld.a instructions and
10632 the corresponding check instructions (ld.c / chk.a).
10633 The default is 'disable'.
10635 @item -msched-ar-data-spec
10636 @itemx -mno-sched-ar-data-spec
10637 @opindex msched-ar-data-spec
10638 @opindex mno-sched-ar-data-spec
10639 (En/Dis)able data speculative scheduling after reload.
10640 This will result in generation of the ld.a instructions and
10641 the corresponding check instructions (ld.c / chk.a).
10642 The default is 'enable'.
10644 @item -mno-sched-control-spec
10645 @itemx -msched-control-spec
10646 @opindex mno-sched-control-spec
10647 @opindex msched-control-spec
10648 (Dis/En)able control speculative scheduling. This feature is
10649 available only during region scheduling (i.e. before reload).
10650 This will result in generation of the ld.s instructions and
10651 the corresponding check instructions chk.s .
10652 The default is 'disable'.
10654 @item -msched-br-in-data-spec
10655 @itemx -mno-sched-br-in-data-spec
10656 @opindex msched-br-in-data-spec
10657 @opindex mno-sched-br-in-data-spec
10658 (En/Dis)able speculative scheduling of the instructions that
10659 are dependent on the data speculative loads before reload.
10660 This is effective only with @option{-msched-br-data-spec} enabled.
10661 The default is 'enable'.
10663 @item -msched-ar-in-data-spec
10664 @itemx -mno-sched-ar-in-data-spec
10665 @opindex msched-ar-in-data-spec
10666 @opindex mno-sched-ar-in-data-spec
10667 (En/Dis)able speculative scheduling of the instructions that
10668 are dependent on the data speculative loads after reload.
10669 This is effective only with @option{-msched-ar-data-spec} enabled.
10670 The default is 'enable'.
10672 @item -msched-in-control-spec
10673 @itemx -mno-sched-in-control-spec
10674 @opindex msched-in-control-spec
10675 @opindex mno-sched-in-control-spec
10676 (En/Dis)able speculative scheduling of the instructions that
10677 are dependent on the control speculative loads.
10678 This is effective only with @option{-msched-control-spec} enabled.
10679 The default is 'enable'.
10682 @itemx -mno-sched-ldc
10683 @opindex msched-ldc
10684 @opindex mno-sched-ldc
10685 (En/Dis)able use of simple data speculation checks ld.c .
10686 If disabled, only chk.a instructions will be emitted to check
10687 data speculative loads.
10688 The default is 'enable'.
10690 @item -mno-sched-control-ldc
10691 @itemx -msched-control-ldc
10692 @opindex mno-sched-control-ldc
10693 @opindex msched-control-ldc
10694 (Dis/En)able use of ld.c instructions to check control speculative loads.
10695 If enabled, in case of control speculative load with no speculatively
10696 scheduled dependent instructions this load will be emitted as ld.sa and
10697 ld.c will be used to check it.
10698 The default is 'disable'.
10700 @item -mno-sched-spec-verbose
10701 @itemx -msched-spec-verbose
10702 @opindex mno-sched-spec-verbose
10703 @opindex msched-spec-verbose
10704 (Dis/En)able printing of the information about speculative motions.
10706 @item -mno-sched-prefer-non-data-spec-insns
10707 @itemx -msched-prefer-non-data-spec-insns
10708 @opindex mno-sched-prefer-non-data-spec-insns
10709 @opindex msched-prefer-non-data-spec-insns
10710 If enabled, data speculative instructions will be chosen for schedule
10711 only if there are no other choices at the moment. This will make
10712 the use of the data speculation much more conservative.
10713 The default is 'disable'.
10715 @item -mno-sched-prefer-non-control-spec-insns
10716 @itemx -msched-prefer-non-control-spec-insns
10717 @opindex mno-sched-prefer-non-control-spec-insns
10718 @opindex msched-prefer-non-control-spec-insns
10719 If enabled, control speculative instructions will be chosen for schedule
10720 only if there are no other choices at the moment. This will make
10721 the use of the control speculation much more conservative.
10722 The default is 'disable'.
10724 @item -mno-sched-count-spec-in-critical-path
10725 @itemx -msched-count-spec-in-critical-path
10726 @opindex mno-sched-count-spec-in-critical-path
10727 @opindex msched-count-spec-in-critical-path
10728 If enabled, speculative dependencies will be considered during
10729 computation of the instructions priorities. This will make the use of the
10730 speculation a bit more conservative.
10731 The default is 'disable'.
10736 @subsection M32C Options
10737 @cindex M32C options
10740 @item -mcpu=@var{name}
10742 Select the CPU for which code is generated. @var{name} may be one of
10743 @samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to
10744 /60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for
10745 the M32C/80 series.
10749 Specifies that the program will be run on the simulator. This causes
10750 an alternate runtime library to be linked in which supports, for
10751 example, file I/O. You must not use this option when generating
10752 programs that will run on real hardware; you must provide your own
10753 runtime library for whatever I/O functions are needed.
10755 @item -memregs=@var{number}
10757 Specifies the number of memory-based pseudo-registers GCC will use
10758 during code generation. These pseudo-registers will be used like real
10759 registers, so there is a tradeoff between GCC's ability to fit the
10760 code into available registers, and the performance penalty of using
10761 memory instead of registers. Note that all modules in a program must
10762 be compiled with the same value for this option. Because of that, you
10763 must not use this option with the default runtime libraries gcc
10768 @node M32R/D Options
10769 @subsection M32R/D Options
10770 @cindex M32R/D options
10772 These @option{-m} options are defined for Renesas M32R/D architectures:
10777 Generate code for the M32R/2@.
10781 Generate code for the M32R/X@.
10785 Generate code for the M32R@. This is the default.
10787 @item -mmodel=small
10788 @opindex mmodel=small
10789 Assume all objects live in the lower 16MB of memory (so that their addresses
10790 can be loaded with the @code{ld24} instruction), and assume all subroutines
10791 are reachable with the @code{bl} instruction.
10792 This is the default.
10794 The addressability of a particular object can be set with the
10795 @code{model} attribute.
10797 @item -mmodel=medium
10798 @opindex mmodel=medium
10799 Assume objects may be anywhere in the 32-bit address space (the compiler
10800 will generate @code{seth/add3} instructions to load their addresses), and
10801 assume all subroutines are reachable with the @code{bl} instruction.
10803 @item -mmodel=large
10804 @opindex mmodel=large
10805 Assume objects may be anywhere in the 32-bit address space (the compiler
10806 will generate @code{seth/add3} instructions to load their addresses), and
10807 assume subroutines may not be reachable with the @code{bl} instruction
10808 (the compiler will generate the much slower @code{seth/add3/jl}
10809 instruction sequence).
10812 @opindex msdata=none
10813 Disable use of the small data area. Variables will be put into
10814 one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
10815 @code{section} attribute has been specified).
10816 This is the default.
10818 The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
10819 Objects may be explicitly put in the small data area with the
10820 @code{section} attribute using one of these sections.
10822 @item -msdata=sdata
10823 @opindex msdata=sdata
10824 Put small global and static data in the small data area, but do not
10825 generate special code to reference them.
10828 @opindex msdata=use
10829 Put small global and static data in the small data area, and generate
10830 special instructions to reference them.
10834 @cindex smaller data references
10835 Put global and static objects less than or equal to @var{num} bytes
10836 into the small data or bss sections instead of the normal data or bss
10837 sections. The default value of @var{num} is 8.
10838 The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
10839 for this option to have any effect.
10841 All modules should be compiled with the same @option{-G @var{num}} value.
10842 Compiling with different values of @var{num} may or may not work; if it
10843 doesn't the linker will give an error message---incorrect code will not be
10848 Makes the M32R specific code in the compiler display some statistics
10849 that might help in debugging programs.
10851 @item -malign-loops
10852 @opindex malign-loops
10853 Align all loops to a 32-byte boundary.
10855 @item -mno-align-loops
10856 @opindex mno-align-loops
10857 Do not enforce a 32-byte alignment for loops. This is the default.
10859 @item -missue-rate=@var{number}
10860 @opindex missue-rate=@var{number}
10861 Issue @var{number} instructions per cycle. @var{number} can only be 1
10864 @item -mbranch-cost=@var{number}
10865 @opindex mbranch-cost=@var{number}
10866 @var{number} can only be 1 or 2. If it is 1 then branches will be
10867 preferred over conditional code, if it is 2, then the opposite will
10870 @item -mflush-trap=@var{number}
10871 @opindex mflush-trap=@var{number}
10872 Specifies the trap number to use to flush the cache. The default is
10873 12. Valid numbers are between 0 and 15 inclusive.
10875 @item -mno-flush-trap
10876 @opindex mno-flush-trap
10877 Specifies that the cache cannot be flushed by using a trap.
10879 @item -mflush-func=@var{name}
10880 @opindex mflush-func=@var{name}
10881 Specifies the name of the operating system function to call to flush
10882 the cache. The default is @emph{_flush_cache}, but a function call
10883 will only be used if a trap is not available.
10885 @item -mno-flush-func
10886 @opindex mno-flush-func
10887 Indicates that there is no OS function for flushing the cache.
10891 @node M680x0 Options
10892 @subsection M680x0 Options
10893 @cindex M680x0 options
10895 These are the @samp{-m} options defined for M680x0 and ColdFire processors.
10896 The default settings depend on which architecture was selected when
10897 the compiler was configured; the defaults for the most common choices
10901 @item -march=@var{arch}
10903 Generate code for a specific M680x0 or ColdFire instruction set
10904 architecture. Permissible values of @var{arch} for M680x0
10905 architectures are: @samp{68000}, @samp{68010}, @samp{68020},
10906 @samp{68030}, @samp{68040}, @samp{68060} and @samp{cpu32}. ColdFire
10907 architectures are selected according to Freescale's ISA classification
10908 and the permissible values are: @samp{isaa}, @samp{isaaplus},
10909 @samp{isab} and @samp{isac}.
10911 gcc defines a macro @samp{__mcf@var{arch}__} whenever it is generating
10912 code for a ColdFire target. The @var{arch} in this macro is one of the
10913 @option{-march} arguments given above.
10915 When used together, @option{-march} and @option{-mtune} select code
10916 that runs on a family of similar processors but that is optimized
10917 for a particular microarchitecture.
10919 @item -mcpu=@var{cpu}
10921 Generate code for a specific M680x0 or ColdFire processor.
10922 The M680x0 @var{cpu}s are: @samp{68000}, @samp{68010}, @samp{68020},
10923 @samp{68030}, @samp{68040}, @samp{68060}, @samp{68302}, @samp{68332}
10924 and @samp{cpu32}. The ColdFire @var{cpu}s are given by the table
10925 below, which also classifies the CPUs into families:
10927 @multitable @columnfractions 0.20 0.80
10928 @item @strong{Family} @tab @strong{@samp{-mcpu} arguments}
10929 @item @samp{5206} @tab @samp{5202} @samp{5204} @samp{5206}
10930 @item @samp{5206e} @tab @samp{5206e}
10931 @item @samp{5208} @tab @samp{5207} @samp{5208}
10932 @item @samp{5211a} @tab @samp{5210a} @samp{5211a}
10933 @item @samp{5213} @tab @samp{5211} @samp{5212} @samp{5213}
10934 @item @samp{5216} @tab @samp{5214} @samp{5216}
10935 @item @samp{52235} @tab @samp{52230} @samp{52231} @samp{52232} @samp{52233} @samp{52234} @samp{52235}
10936 @item @samp{5225} @tab @samp{5224} @samp{5225}
10937 @item @samp{5235} @tab @samp{5232} @samp{5233} @samp{5234} @samp{5235} @samp{523x}
10938 @item @samp{5249} @tab @samp{5249}
10939 @item @samp{5250} @tab @samp{5250}
10940 @item @samp{5271} @tab @samp{5270} @samp{5271}
10941 @item @samp{5272} @tab @samp{5272}
10942 @item @samp{5275} @tab @samp{5274} @samp{5275}
10943 @item @samp{5282} @tab @samp{5280} @samp{5281} @samp{5282} @samp{528x}
10944 @item @samp{5307} @tab @samp{5307}
10945 @item @samp{5329} @tab @samp{5327} @samp{5328} @samp{5329} @samp{532x}
10946 @item @samp{5373} @tab @samp{5372} @samp{5373} @samp{537x}
10947 @item @samp{5407} @tab @samp{5407}
10948 @item @samp{5475} @tab @samp{5470} @samp{5471} @samp{5472} @samp{5473} @samp{5474} @samp{5475} @samp{547x} @samp{5480} @samp{5481} @samp{5482} @samp{5483} @samp{5484} @samp{5485}
10951 @option{-mcpu=@var{cpu}} overrides @option{-march=@var{arch}} if
10952 @var{arch} is compatible with @var{cpu}. Other combinations of
10953 @option{-mcpu} and @option{-march} are rejected.
10955 gcc defines the macro @samp{__mcf_cpu_@var{cpu}} when ColdFire target
10956 @var{cpu} is selected. It also defines @samp{__mcf_family_@var{family}},
10957 where the value of @var{family} is given by the table above.
10959 @item -mtune=@var{tune}
10961 Tune the code for a particular microarchitecture, within the
10962 constraints set by @option{-march} and @option{-mcpu}.
10963 The M680x0 microarchitectures are: @samp{68000}, @samp{68010},
10964 @samp{68020}, @samp{68030}, @samp{68040}, @samp{68060}
10965 and @samp{cpu32}. The ColdFire microarchitectures
10966 are: @samp{cfv2}, @samp{cfv3}, @samp{cfv4} and @samp{cfv4e}.
10968 You can also use @option{-mtune=68020-40} for code that needs
10969 to run relatively well on 68020, 68030 and 68040 targets.
10970 @option{-mtune=68020-60} is similar but includes 68060 targets
10971 as well. These two options select the same tuning decisions as
10972 @option{-m68020-40} and @option{-m68020-60} respectively.
10974 gcc defines the macros @samp{__mc@var{arch}} and @samp{__mc@var{arch}__}
10975 when tuning for 680x0 architecture @var{arch}. It also defines
10976 @samp{mc@var{arch}} unless either @option{-ansi} or a non-GNU @option{-std}
10977 option is used. If gcc is tuning for a range of architectures,
10978 as selected by @option{-mtune=68020-40} or @option{-mtune=68020-60},
10979 it defines the macros for every architecture in the range.
10981 gcc also defines the macro @samp{__m@var{uarch}__} when tuning for
10982 ColdFire microarchitecture @var{uarch}, where @var{uarch} is one
10983 of the arguments given above.
10989 Generate output for a 68000. This is the default
10990 when the compiler is configured for 68000-based systems.
10991 It is equivalent to @option{-march=68000}.
10993 Use this option for microcontrollers with a 68000 or EC000 core,
10994 including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
10998 Generate output for a 68010. This is the default
10999 when the compiler is configured for 68010-based systems.
11000 It is equivalent to @option{-march=68010}.
11006 Generate output for a 68020. This is the default
11007 when the compiler is configured for 68020-based systems.
11008 It is equivalent to @option{-march=68020}.
11012 Generate output for a 68030. This is the default when the compiler is
11013 configured for 68030-based systems. It is equivalent to
11014 @option{-march=68030}.
11018 Generate output for a 68040. This is the default when the compiler is
11019 configured for 68040-based systems. It is equivalent to
11020 @option{-march=68040}.
11022 This option inhibits the use of 68881/68882 instructions that have to be
11023 emulated by software on the 68040. Use this option if your 68040 does not
11024 have code to emulate those instructions.
11028 Generate output for a 68060. This is the default when the compiler is
11029 configured for 68060-based systems. It is equivalent to
11030 @option{-march=68060}.
11032 This option inhibits the use of 68020 and 68881/68882 instructions that
11033 have to be emulated by software on the 68060. Use this option if your 68060
11034 does not have code to emulate those instructions.
11038 Generate output for a CPU32. This is the default
11039 when the compiler is configured for CPU32-based systems.
11040 It is equivalent to @option{-march=cpu32}.
11042 Use this option for microcontrollers with a
11043 CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
11044 68336, 68340, 68341, 68349 and 68360.
11048 Generate output for a 520X ColdFire CPU. This is the default
11049 when the compiler is configured for 520X-based systems.
11050 It is equivalent to @option{-mcpu=5206}, and is now deprecated
11051 in favor of that option.
11053 Use this option for microcontroller with a 5200 core, including
11054 the MCF5202, MCF5203, MCF5204 and MCF5206.
11058 Generate output for a 5206e ColdFire CPU. The option is now
11059 deprecated in favor of the equivalent @option{-mcpu=5206e}.
11063 Generate output for a member of the ColdFire 528X family.
11064 The option is now deprecated in favor of the equivalent
11065 @option{-mcpu=528x}.
11069 Generate output for a ColdFire 5307 CPU. The option is now deprecated
11070 in favor of the equivalent @option{-mcpu=5307}.
11074 Generate output for a ColdFire 5407 CPU. The option is now deprecated
11075 in favor of the equivalent @option{-mcpu=5407}.
11079 Generate output for a ColdFire V4e family CPU (e.g.@: 547x/548x).
11080 This includes use of hardware floating point instructions.
11081 The option is equivalent to @option{-mcpu=547x}, and is now
11082 deprecated in favor of that option.
11086 Generate output for a 68040, without using any of the new instructions.
11087 This results in code which can run relatively efficiently on either a
11088 68020/68881 or a 68030 or a 68040. The generated code does use the
11089 68881 instructions that are emulated on the 68040.
11091 The option is equivalent to @option{-march=68020} @option{-mtune=68020-40}.
11095 Generate output for a 68060, without using any of the new instructions.
11096 This results in code which can run relatively efficiently on either a
11097 68020/68881 or a 68030 or a 68040. The generated code does use the
11098 68881 instructions that are emulated on the 68060.
11100 The option is equivalent to @option{-march=68020} @option{-mtune=68020-60}.
11104 @opindex mhard-float
11106 Generate floating-point instructions. This is the default for 68020
11107 and above, and for ColdFire devices that have an FPU. It defines the
11108 macro @samp{__HAVE_68881__} on M680x0 targets and @samp{__mcffpu__}
11109 on ColdFire targets.
11112 @opindex msoft-float
11113 Do not generate floating-point instructions; use library calls instead.
11114 This is the default for 68000, 68010, and 68832 targets. It is also
11115 the default for ColdFire devices that have no FPU.
11121 Generate (do not generate) ColdFire hardware divide and remainder
11122 instructions. If @option{-march} is used without @option{-mcpu},
11123 the default is ``on'' for ColdFire architectures and ``off'' for M680x0
11124 architectures. Otherwise, the default is taken from the target CPU
11125 (either the default CPU, or the one specified by @option{-mcpu}). For
11126 example, the default is ``off'' for @option{-mcpu=5206} and ``on'' for
11127 @option{-mcpu=5206e}.
11129 gcc defines the macro @samp{__mcfhwdiv__} when this option is enabled.
11133 Consider type @code{int} to be 16 bits wide, like @code{short int}.
11134 Additionally, parameters passed on the stack are also aligned to a
11135 16-bit boundary even on targets whose API mandates promotion to 32-bit.
11139 Do not consider type @code{int} to be 16 bits wide. This is the default.
11142 @itemx -mno-bitfield
11143 @opindex mnobitfield
11144 @opindex mno-bitfield
11145 Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
11146 and @option{-m5200} options imply @w{@option{-mnobitfield}}.
11150 Do use the bit-field instructions. The @option{-m68020} option implies
11151 @option{-mbitfield}. This is the default if you use a configuration
11152 designed for a 68020.
11156 Use a different function-calling convention, in which functions
11157 that take a fixed number of arguments return with the @code{rtd}
11158 instruction, which pops their arguments while returning. This
11159 saves one instruction in the caller since there is no need to pop
11160 the arguments there.
11162 This calling convention is incompatible with the one normally
11163 used on Unix, so you cannot use it if you need to call libraries
11164 compiled with the Unix compiler.
11166 Also, you must provide function prototypes for all functions that
11167 take variable numbers of arguments (including @code{printf});
11168 otherwise incorrect code will be generated for calls to those
11171 In addition, seriously incorrect code will result if you call a
11172 function with too many arguments. (Normally, extra arguments are
11173 harmlessly ignored.)
11175 The @code{rtd} instruction is supported by the 68010, 68020, 68030,
11176 68040, 68060 and CPU32 processors, but not by the 68000 or 5200.
11180 Do not use the calling conventions selected by @option{-mrtd}.
11181 This is the default.
11184 @itemx -mno-align-int
11185 @opindex malign-int
11186 @opindex mno-align-int
11187 Control whether GCC aligns @code{int}, @code{long}, @code{long long},
11188 @code{float}, @code{double}, and @code{long double} variables on a 32-bit
11189 boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
11190 Aligning variables on 32-bit boundaries produces code that runs somewhat
11191 faster on processors with 32-bit busses at the expense of more memory.
11193 @strong{Warning:} if you use the @option{-malign-int} switch, GCC will
11194 align structures containing the above types differently than
11195 most published application binary interface specifications for the m68k.
11199 Use the pc-relative addressing mode of the 68000 directly, instead of
11200 using a global offset table. At present, this option implies @option{-fpic},
11201 allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
11202 not presently supported with @option{-mpcrel}, though this could be supported for
11203 68020 and higher processors.
11205 @item -mno-strict-align
11206 @itemx -mstrict-align
11207 @opindex mno-strict-align
11208 @opindex mstrict-align
11209 Do not (do) assume that unaligned memory references will be handled by
11213 Generate code that allows the data segment to be located in a different
11214 area of memory from the text segment. This allows for execute in place in
11215 an environment without virtual memory management. This option implies
11218 @item -mno-sep-data
11219 Generate code that assumes that the data segment follows the text segment.
11220 This is the default.
11222 @item -mid-shared-library
11223 Generate code that supports shared libraries via the library ID method.
11224 This allows for execute in place and shared libraries in an environment
11225 without virtual memory management. This option implies @option{-fPIC}.
11227 @item -mno-id-shared-library
11228 Generate code that doesn't assume ID based shared libraries are being used.
11229 This is the default.
11231 @item -mshared-library-id=n
11232 Specified the identification number of the ID based shared library being
11233 compiled. Specifying a value of 0 will generate more compact code, specifying
11234 other values will force the allocation of that number to the current
11235 library but is no more space or time efficient than omitting this option.
11239 @node M68hc1x Options
11240 @subsection M68hc1x Options
11241 @cindex M68hc1x options
11243 These are the @samp{-m} options defined for the 68hc11 and 68hc12
11244 microcontrollers. The default values for these options depends on
11245 which style of microcontroller was selected when the compiler was configured;
11246 the defaults for the most common choices are given below.
11253 Generate output for a 68HC11. This is the default
11254 when the compiler is configured for 68HC11-based systems.
11260 Generate output for a 68HC12. This is the default
11261 when the compiler is configured for 68HC12-based systems.
11267 Generate output for a 68HCS12.
11269 @item -mauto-incdec
11270 @opindex mauto-incdec
11271 Enable the use of 68HC12 pre and post auto-increment and auto-decrement
11278 Enable the use of 68HC12 min and max instructions.
11281 @itemx -mno-long-calls
11282 @opindex mlong-calls
11283 @opindex mno-long-calls
11284 Treat all calls as being far away (near). If calls are assumed to be
11285 far away, the compiler will use the @code{call} instruction to
11286 call a function and the @code{rtc} instruction for returning.
11290 Consider type @code{int} to be 16 bits wide, like @code{short int}.
11292 @item -msoft-reg-count=@var{count}
11293 @opindex msoft-reg-count
11294 Specify the number of pseudo-soft registers which are used for the
11295 code generation. The maximum number is 32. Using more pseudo-soft
11296 register may or may not result in better code depending on the program.
11297 The default is 4 for 68HC11 and 2 for 68HC12.
11301 @node MCore Options
11302 @subsection MCore Options
11303 @cindex MCore options
11305 These are the @samp{-m} options defined for the Motorola M*Core
11311 @itemx -mno-hardlit
11313 @opindex mno-hardlit
11314 Inline constants into the code stream if it can be done in two
11315 instructions or less.
11321 Use the divide instruction. (Enabled by default).
11323 @item -mrelax-immediate
11324 @itemx -mno-relax-immediate
11325 @opindex mrelax-immediate
11326 @opindex mno-relax-immediate
11327 Allow arbitrary sized immediates in bit operations.
11329 @item -mwide-bitfields
11330 @itemx -mno-wide-bitfields
11331 @opindex mwide-bitfields
11332 @opindex mno-wide-bitfields
11333 Always treat bit-fields as int-sized.
11335 @item -m4byte-functions
11336 @itemx -mno-4byte-functions
11337 @opindex m4byte-functions
11338 @opindex mno-4byte-functions
11339 Force all functions to be aligned to a four byte boundary.
11341 @item -mcallgraph-data
11342 @itemx -mno-callgraph-data
11343 @opindex mcallgraph-data
11344 @opindex mno-callgraph-data
11345 Emit callgraph information.
11348 @itemx -mno-slow-bytes
11349 @opindex mslow-bytes
11350 @opindex mno-slow-bytes
11351 Prefer word access when reading byte quantities.
11353 @item -mlittle-endian
11354 @itemx -mbig-endian
11355 @opindex mlittle-endian
11356 @opindex mbig-endian
11357 Generate code for a little endian target.
11363 Generate code for the 210 processor.
11367 @subsection MIPS Options
11368 @cindex MIPS options
11374 Generate big-endian code.
11378 Generate little-endian code. This is the default for @samp{mips*el-*-*}
11381 @item -march=@var{arch}
11383 Generate code that will run on @var{arch}, which can be the name of a
11384 generic MIPS ISA, or the name of a particular processor.
11386 @samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
11387 @samp{mips32}, @samp{mips32r2}, and @samp{mips64}.
11388 The processor names are:
11389 @samp{4kc}, @samp{4km}, @samp{4kp},
11390 @samp{4kec}, @samp{4kem}, @samp{4kep},
11391 @samp{5kc}, @samp{5kf},
11393 @samp{24kc}, @samp{24kf}, @samp{24kx},
11394 @samp{24kec}, @samp{24kef}, @samp{24kex},
11395 @samp{34kc}, @samp{34kf}, @samp{34kx},
11396 @samp{74kc}, @samp{74kf}, @samp{74kx},
11399 @samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
11400 @samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000},
11401 @samp{rm7000}, @samp{rm9000},
11404 @samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
11405 @samp{vr5000}, @samp{vr5400} and @samp{vr5500}.
11406 The special value @samp{from-abi} selects the
11407 most compatible architecture for the selected ABI (that is,
11408 @samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
11410 In processor names, a final @samp{000} can be abbreviated as @samp{k}
11411 (for example, @samp{-march=r2k}). Prefixes are optional, and
11412 @samp{vr} may be written @samp{r}.
11414 GCC defines two macros based on the value of this option. The first
11415 is @samp{_MIPS_ARCH}, which gives the name of target architecture, as
11416 a string. The second has the form @samp{_MIPS_ARCH_@var{foo}},
11417 where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@.
11418 For example, @samp{-march=r2000} will set @samp{_MIPS_ARCH}
11419 to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}.
11421 Note that the @samp{_MIPS_ARCH} macro uses the processor names given
11422 above. In other words, it will have the full prefix and will not
11423 abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},
11424 the macro names the resolved architecture (either @samp{"mips1"} or
11425 @samp{"mips3"}). It names the default architecture when no
11426 @option{-march} option is given.
11428 @item -mtune=@var{arch}
11430 Optimize for @var{arch}. Among other things, this option controls
11431 the way instructions are scheduled, and the perceived cost of arithmetic
11432 operations. The list of @var{arch} values is the same as for
11435 When this option is not used, GCC will optimize for the processor
11436 specified by @option{-march}. By using @option{-march} and
11437 @option{-mtune} together, it is possible to generate code that will
11438 run on a family of processors, but optimize the code for one
11439 particular member of that family.
11441 @samp{-mtune} defines the macros @samp{_MIPS_TUNE} and
11442 @samp{_MIPS_TUNE_@var{foo}}, which work in the same way as the
11443 @samp{-march} ones described above.
11447 Equivalent to @samp{-march=mips1}.
11451 Equivalent to @samp{-march=mips2}.
11455 Equivalent to @samp{-march=mips3}.
11459 Equivalent to @samp{-march=mips4}.
11463 Equivalent to @samp{-march=mips32}.
11467 Equivalent to @samp{-march=mips32r2}.
11471 Equivalent to @samp{-march=mips64}.
11476 @opindex mno-mips16
11477 Generate (do not generate) MIPS16 code. If GCC is targetting a
11478 MIPS32 or MIPS64 architecture, it will make use of the MIPS16e ASE@.
11490 Generate code for the given ABI@.
11492 Note that the EABI has a 32-bit and a 64-bit variant. GCC normally
11493 generates 64-bit code when you select a 64-bit architecture, but you
11494 can use @option{-mgp32} to get 32-bit code instead.
11496 For information about the O64 ABI, see
11497 @w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
11499 GCC supports a variant of the o32 ABI in which floating-point registers
11500 are 64 rather than 32 bits wide. You can select this combination with
11501 @option{-mabi=32} @option{-mfp64}. This ABI relies on the @samp{mthc1}
11502 and @samp{mfhc1} instructions and is therefore only supported for
11503 MIPS32R2 processors.
11505 The register assignments for arguments and return values remain the
11506 same, but each scalar value is passed in a single 64-bit register
11507 rather than a pair of 32-bit registers. For example, scalar
11508 floating-point values are returned in @samp{$f0} only, not a
11509 @samp{$f0}/@samp{$f1} pair. The set of call-saved registers also
11510 remains the same, but all 64 bits are saved.
11513 @itemx -mno-abicalls
11515 @opindex mno-abicalls
11516 Generate (do not generate) code that is suitable for SVR4-style
11517 dynamic objects. @option{-mabicalls} is the default for SVR4-based
11522 Generate (do not generate) code that is fully position-independent,
11523 and that can therefore be linked into shared libraries. This option
11524 only affects @option{-mabicalls}.
11526 All @option{-mabicalls} code has traditionally been position-independent,
11527 regardless of options like @option{-fPIC} and @option{-fpic}. However,
11528 as an extension, the GNU toolchain allows executables to use absolute
11529 accesses for locally-binding symbols. It can also use shorter GP
11530 initialization sequences and generate direct calls to locally-defined
11531 functions. This mode is selected by @option{-mno-shared}.
11533 @option{-mno-shared} depends on binutils 2.16 or higher and generates
11534 objects that can only be linked by the GNU linker. However, the option
11535 does not affect the ABI of the final executable; it only affects the ABI
11536 of relocatable objects. Using @option{-mno-shared} will generally make
11537 executables both smaller and quicker.
11539 @option{-mshared} is the default.
11545 Lift (do not lift) the usual restrictions on the size of the global
11548 GCC normally uses a single instruction to load values from the GOT@.
11549 While this is relatively efficient, it will only work if the GOT
11550 is smaller than about 64k. Anything larger will cause the linker
11551 to report an error such as:
11553 @cindex relocation truncated to fit (MIPS)
11555 relocation truncated to fit: R_MIPS_GOT16 foobar
11558 If this happens, you should recompile your code with @option{-mxgot}.
11559 It should then work with very large GOTs, although it will also be
11560 less efficient, since it will take three instructions to fetch the
11561 value of a global symbol.
11563 Note that some linkers can create multiple GOTs. If you have such a
11564 linker, you should only need to use @option{-mxgot} when a single object
11565 file accesses more than 64k's worth of GOT entries. Very few do.
11567 These options have no effect unless GCC is generating position
11572 Assume that general-purpose registers are 32 bits wide.
11576 Assume that general-purpose registers are 64 bits wide.
11580 Assume that floating-point registers are 32 bits wide.
11584 Assume that floating-point registers are 64 bits wide.
11587 @opindex mhard-float
11588 Use floating-point coprocessor instructions.
11591 @opindex msoft-float
11592 Do not use floating-point coprocessor instructions. Implement
11593 floating-point calculations using library calls instead.
11595 @item -msingle-float
11596 @opindex msingle-float
11597 Assume that the floating-point coprocessor only supports single-precision
11600 @item -mdouble-float
11601 @opindex mdouble-float
11602 Assume that the floating-point coprocessor supports double-precision
11603 operations. This is the default.
11609 Use (do not use) the MIPS DSP ASE. @xref{MIPS DSP Built-in Functions}.
11615 Use (do not use) the MIPS DSP ASE REV 2. @xref{MIPS DSP Built-in Functions}.
11616 The option @option{-mdspr2} implies @option{-mdsp}.
11618 @item -mpaired-single
11619 @itemx -mno-paired-single
11620 @opindex mpaired-single
11621 @opindex mno-paired-single
11622 Use (do not use) paired-single floating-point instructions.
11623 @xref{MIPS Paired-Single Support}. This option can only be used
11624 when generating 64-bit code and requires hardware floating-point
11625 support to be enabled.
11631 Use (do not use) MIPS Digital Media Extension instructions.
11632 This option can only be used when generating 64-bit code and requires
11633 hardware floating-point support to be enabled.
11638 @opindex mno-mips3d
11639 Use (do not use) the MIPS-3D ASE@. @xref{MIPS-3D Built-in Functions}.
11640 The option @option{-mips3d} implies @option{-mpaired-single}.
11646 Use (do not use) MT Multithreading instructions.
11650 Force @code{long} types to be 64 bits wide. See @option{-mlong32} for
11651 an explanation of the default and the way that the pointer size is
11656 Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
11658 The default size of @code{int}s, @code{long}s and pointers depends on
11659 the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI
11660 uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
11661 32-bit @code{long}s. Pointers are the same size as @code{long}s,
11662 or the same size as integer registers, whichever is smaller.
11668 Assume (do not assume) that all symbols have 32-bit values, regardless
11669 of the selected ABI@. This option is useful in combination with
11670 @option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
11671 to generate shorter and faster references to symbolic addresses.
11675 @cindex smaller data references (MIPS)
11676 @cindex gp-relative references (MIPS)
11677 Put global and static items less than or equal to @var{num} bytes into
11678 the small data or bss section instead of the normal data or bss section.
11679 This allows the data to be accessed using a single instruction.
11681 All modules should be compiled with the same @option{-G @var{num}}
11684 @item -membedded-data
11685 @itemx -mno-embedded-data
11686 @opindex membedded-data
11687 @opindex mno-embedded-data
11688 Allocate variables to the read-only data section first if possible, then
11689 next in the small data section if possible, otherwise in data. This gives
11690 slightly slower code than the default, but reduces the amount of RAM required
11691 when executing, and thus may be preferred for some embedded systems.
11693 @item -muninit-const-in-rodata
11694 @itemx -mno-uninit-const-in-rodata
11695 @opindex muninit-const-in-rodata
11696 @opindex mno-uninit-const-in-rodata
11697 Put uninitialized @code{const} variables in the read-only data section.
11698 This option is only meaningful in conjunction with @option{-membedded-data}.
11700 @item -msplit-addresses
11701 @itemx -mno-split-addresses
11702 @opindex msplit-addresses
11703 @opindex mno-split-addresses
11704 Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
11705 relocation operators. This option has been superseded by
11706 @option{-mexplicit-relocs} but is retained for backwards compatibility.
11708 @item -mexplicit-relocs
11709 @itemx -mno-explicit-relocs
11710 @opindex mexplicit-relocs
11711 @opindex mno-explicit-relocs
11712 Use (do not use) assembler relocation operators when dealing with symbolic
11713 addresses. The alternative, selected by @option{-mno-explicit-relocs},
11714 is to use assembler macros instead.
11716 @option{-mexplicit-relocs} is the default if GCC was configured
11717 to use an assembler that supports relocation operators.
11719 @item -mcheck-zero-division
11720 @itemx -mno-check-zero-division
11721 @opindex mcheck-zero-division
11722 @opindex mno-check-zero-division
11723 Trap (do not trap) on integer division by zero.
11725 The default is @option{-mcheck-zero-division}.
11727 @item -mdivide-traps
11728 @itemx -mdivide-breaks
11729 @opindex mdivide-traps
11730 @opindex mdivide-breaks
11731 MIPS systems check for division by zero by generating either a
11732 conditional trap or a break instruction. Using traps results in
11733 smaller code, but is only supported on MIPS II and later. Also, some
11734 versions of the Linux kernel have a bug that prevents trap from
11735 generating the proper signal (@code{SIGFPE}). Use @option{-mdivide-traps} to
11736 allow conditional traps on architectures that support them and
11737 @option{-mdivide-breaks} to force the use of breaks.
11739 The default is usually @option{-mdivide-traps}, but this can be
11740 overridden at configure time using @option{--with-divide=breaks}.
11741 Divide-by-zero checks can be completely disabled using
11742 @option{-mno-check-zero-division}.
11747 @opindex mno-memcpy
11748 Force (do not force) the use of @code{memcpy()} for non-trivial block
11749 moves. The default is @option{-mno-memcpy}, which allows GCC to inline
11750 most constant-sized copies.
11753 @itemx -mno-long-calls
11754 @opindex mlong-calls
11755 @opindex mno-long-calls
11756 Disable (do not disable) use of the @code{jal} instruction. Calling
11757 functions using @code{jal} is more efficient but requires the caller
11758 and callee to be in the same 256 megabyte segment.
11760 This option has no effect on abicalls code. The default is
11761 @option{-mno-long-calls}.
11767 Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
11768 instructions, as provided by the R4650 ISA@.
11771 @itemx -mno-fused-madd
11772 @opindex mfused-madd
11773 @opindex mno-fused-madd
11774 Enable (disable) use of the floating point multiply-accumulate
11775 instructions, when they are available. The default is
11776 @option{-mfused-madd}.
11778 When multiply-accumulate instructions are used, the intermediate
11779 product is calculated to infinite precision and is not subject to
11780 the FCSR Flush to Zero bit. This may be undesirable in some
11785 Tell the MIPS assembler to not run its preprocessor over user
11786 assembler files (with a @samp{.s} suffix) when assembling them.
11789 @itemx -mno-fix-r4000
11790 @opindex mfix-r4000
11791 @opindex mno-fix-r4000
11792 Work around certain R4000 CPU errata:
11795 A double-word or a variable shift may give an incorrect result if executed
11796 immediately after starting an integer division.
11798 A double-word or a variable shift may give an incorrect result if executed
11799 while an integer multiplication is in progress.
11801 An integer division may give an incorrect result if started in a delay slot
11802 of a taken branch or a jump.
11806 @itemx -mno-fix-r4400
11807 @opindex mfix-r4400
11808 @opindex mno-fix-r4400
11809 Work around certain R4400 CPU errata:
11812 A double-word or a variable shift may give an incorrect result if executed
11813 immediately after starting an integer division.
11817 @itemx -mno-fix-vr4120
11818 @opindex mfix-vr4120
11819 Work around certain VR4120 errata:
11822 @code{dmultu} does not always produce the correct result.
11824 @code{div} and @code{ddiv} do not always produce the correct result if one
11825 of the operands is negative.
11827 The workarounds for the division errata rely on special functions in
11828 @file{libgcc.a}. At present, these functions are only provided by
11829 the @code{mips64vr*-elf} configurations.
11831 Other VR4120 errata require a nop to be inserted between certain pairs of
11832 instructions. These errata are handled by the assembler, not by GCC itself.
11835 @opindex mfix-vr4130
11836 Work around the VR4130 @code{mflo}/@code{mfhi} errata. The
11837 workarounds are implemented by the assembler rather than by GCC,
11838 although GCC will avoid using @code{mflo} and @code{mfhi} if the
11839 VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
11840 instructions are available instead.
11843 @itemx -mno-fix-sb1
11845 Work around certain SB-1 CPU core errata.
11846 (This flag currently works around the SB-1 revision 2
11847 ``F1'' and ``F2'' floating point errata.)
11849 @item -mflush-func=@var{func}
11850 @itemx -mno-flush-func
11851 @opindex mflush-func
11852 Specifies the function to call to flush the I and D caches, or to not
11853 call any such function. If called, the function must take the same
11854 arguments as the common @code{_flush_func()}, that is, the address of the
11855 memory range for which the cache is being flushed, the size of the
11856 memory range, and the number 3 (to flush both caches). The default
11857 depends on the target GCC was configured for, but commonly is either
11858 @samp{_flush_func} or @samp{__cpu_flush}.
11860 @item -mbranch-likely
11861 @itemx -mno-branch-likely
11862 @opindex mbranch-likely
11863 @opindex mno-branch-likely
11864 Enable or disable use of Branch Likely instructions, regardless of the
11865 default for the selected architecture. By default, Branch Likely
11866 instructions may be generated if they are supported by the selected
11867 architecture. An exception is for the MIPS32 and MIPS64 architectures
11868 and processors which implement those architectures; for those, Branch
11869 Likely instructions will not be generated by default because the MIPS32
11870 and MIPS64 architectures specifically deprecate their use.
11872 @item -mfp-exceptions
11873 @itemx -mno-fp-exceptions
11874 @opindex mfp-exceptions
11875 Specifies whether FP exceptions are enabled. This affects how we schedule
11876 FP instructions for some processors. The default is that FP exceptions are
11879 For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
11880 64-bit code, then we can use both FP pipes. Otherwise, we can only use one
11883 @item -mvr4130-align
11884 @itemx -mno-vr4130-align
11885 @opindex mvr4130-align
11886 The VR4130 pipeline is two-way superscalar, but can only issue two
11887 instructions together if the first one is 8-byte aligned. When this
11888 option is enabled, GCC will align pairs of instructions that it
11889 thinks should execute in parallel.
11891 This option only has an effect when optimizing for the VR4130.
11892 It normally makes code faster, but at the expense of making it bigger.
11893 It is enabled by default at optimization level @option{-O3}.
11897 @subsection MMIX Options
11898 @cindex MMIX Options
11900 These options are defined for the MMIX:
11904 @itemx -mno-libfuncs
11906 @opindex mno-libfuncs
11907 Specify that intrinsic library functions are being compiled, passing all
11908 values in registers, no matter the size.
11911 @itemx -mno-epsilon
11913 @opindex mno-epsilon
11914 Generate floating-point comparison instructions that compare with respect
11915 to the @code{rE} epsilon register.
11917 @item -mabi=mmixware
11919 @opindex mabi-mmixware
11921 Generate code that passes function parameters and return values that (in
11922 the called function) are seen as registers @code{$0} and up, as opposed to
11923 the GNU ABI which uses global registers @code{$231} and up.
11925 @item -mzero-extend
11926 @itemx -mno-zero-extend
11927 @opindex mzero-extend
11928 @opindex mno-zero-extend
11929 When reading data from memory in sizes shorter than 64 bits, use (do not
11930 use) zero-extending load instructions by default, rather than
11931 sign-extending ones.
11934 @itemx -mno-knuthdiv
11936 @opindex mno-knuthdiv
11937 Make the result of a division yielding a remainder have the same sign as
11938 the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
11939 remainder follows the sign of the dividend. Both methods are
11940 arithmetically valid, the latter being almost exclusively used.
11942 @item -mtoplevel-symbols
11943 @itemx -mno-toplevel-symbols
11944 @opindex mtoplevel-symbols
11945 @opindex mno-toplevel-symbols
11946 Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
11947 code can be used with the @code{PREFIX} assembly directive.
11951 Generate an executable in the ELF format, rather than the default
11952 @samp{mmo} format used by the @command{mmix} simulator.
11954 @item -mbranch-predict
11955 @itemx -mno-branch-predict
11956 @opindex mbranch-predict
11957 @opindex mno-branch-predict
11958 Use (do not use) the probable-branch instructions, when static branch
11959 prediction indicates a probable branch.
11961 @item -mbase-addresses
11962 @itemx -mno-base-addresses
11963 @opindex mbase-addresses
11964 @opindex mno-base-addresses
11965 Generate (do not generate) code that uses @emph{base addresses}. Using a
11966 base address automatically generates a request (handled by the assembler
11967 and the linker) for a constant to be set up in a global register. The
11968 register is used for one or more base address requests within the range 0
11969 to 255 from the value held in the register. The generally leads to short
11970 and fast code, but the number of different data items that can be
11971 addressed is limited. This means that a program that uses lots of static
11972 data may require @option{-mno-base-addresses}.
11974 @item -msingle-exit
11975 @itemx -mno-single-exit
11976 @opindex msingle-exit
11977 @opindex mno-single-exit
11978 Force (do not force) generated code to have a single exit point in each
11982 @node MN10300 Options
11983 @subsection MN10300 Options
11984 @cindex MN10300 options
11986 These @option{-m} options are defined for Matsushita MN10300 architectures:
11991 Generate code to avoid bugs in the multiply instructions for the MN10300
11992 processors. This is the default.
11994 @item -mno-mult-bug
11995 @opindex mno-mult-bug
11996 Do not generate code to avoid bugs in the multiply instructions for the
11997 MN10300 processors.
12001 Generate code which uses features specific to the AM33 processor.
12005 Do not generate code which uses features specific to the AM33 processor. This
12008 @item -mreturn-pointer-on-d0
12009 @opindex mreturn-pointer-on-d0
12010 When generating a function which returns a pointer, return the pointer
12011 in both @code{a0} and @code{d0}. Otherwise, the pointer is returned
12012 only in a0, and attempts to call such functions without a prototype
12013 would result in errors. Note that this option is on by default; use
12014 @option{-mno-return-pointer-on-d0} to disable it.
12018 Do not link in the C run-time initialization object file.
12022 Indicate to the linker that it should perform a relaxation optimization pass
12023 to shorten branches, calls and absolute memory addresses. This option only
12024 has an effect when used on the command line for the final link step.
12026 This option makes symbolic debugging impossible.
12030 @subsection MT Options
12033 These @option{-m} options are defined for Morpho MT architectures:
12037 @item -march=@var{cpu-type}
12039 Generate code that will run on @var{cpu-type}, which is the name of a system
12040 representing a certain processor type. Possible values for
12041 @var{cpu-type} are @samp{ms1-64-001}, @samp{ms1-16-002},
12042 @samp{ms1-16-003} and @samp{ms2}.
12044 When this option is not used, the default is @option{-march=ms1-16-002}.
12048 Use byte loads and stores when generating code.
12052 Do not use byte loads and stores when generating code.
12056 Use simulator runtime
12060 Do not link in the C run-time initialization object file
12061 @file{crti.o}. Other run-time initialization and termination files
12062 such as @file{startup.o} and @file{exit.o} are still included on the
12063 linker command line.
12067 @node PDP-11 Options
12068 @subsection PDP-11 Options
12069 @cindex PDP-11 Options
12071 These options are defined for the PDP-11:
12076 Use hardware FPP floating point. This is the default. (FIS floating
12077 point on the PDP-11/40 is not supported.)
12080 @opindex msoft-float
12081 Do not use hardware floating point.
12085 Return floating-point results in ac0 (fr0 in Unix assembler syntax).
12089 Return floating-point results in memory. This is the default.
12093 Generate code for a PDP-11/40.
12097 Generate code for a PDP-11/45. This is the default.
12101 Generate code for a PDP-11/10.
12103 @item -mbcopy-builtin
12104 @opindex bcopy-builtin
12105 Use inline @code{movmemhi} patterns for copying memory. This is the
12110 Do not use inline @code{movmemhi} patterns for copying memory.
12116 Use 16-bit @code{int}. This is the default.
12122 Use 32-bit @code{int}.
12125 @itemx -mno-float32
12127 @opindex mno-float32
12128 Use 64-bit @code{float}. This is the default.
12131 @itemx -mno-float64
12133 @opindex mno-float64
12134 Use 32-bit @code{float}.
12138 Use @code{abshi2} pattern. This is the default.
12142 Do not use @code{abshi2} pattern.
12144 @item -mbranch-expensive
12145 @opindex mbranch-expensive
12146 Pretend that branches are expensive. This is for experimenting with
12147 code generation only.
12149 @item -mbranch-cheap
12150 @opindex mbranch-cheap
12151 Do not pretend that branches are expensive. This is the default.
12155 Generate code for a system with split I&D@.
12159 Generate code for a system without split I&D@. This is the default.
12163 Use Unix assembler syntax. This is the default when configured for
12164 @samp{pdp11-*-bsd}.
12168 Use DEC assembler syntax. This is the default when configured for any
12169 PDP-11 target other than @samp{pdp11-*-bsd}.
12172 @node PowerPC Options
12173 @subsection PowerPC Options
12174 @cindex PowerPC options
12176 These are listed under @xref{RS/6000 and PowerPC Options}.
12178 @node RS/6000 and PowerPC Options
12179 @subsection IBM RS/6000 and PowerPC Options
12180 @cindex RS/6000 and PowerPC Options
12181 @cindex IBM RS/6000 and PowerPC Options
12183 These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
12190 @itemx -mno-powerpc
12191 @itemx -mpowerpc-gpopt
12192 @itemx -mno-powerpc-gpopt
12193 @itemx -mpowerpc-gfxopt
12194 @itemx -mno-powerpc-gfxopt
12196 @itemx -mno-powerpc64
12200 @itemx -mno-popcntb
12212 @opindex mno-power2
12214 @opindex mno-powerpc
12215 @opindex mpowerpc-gpopt
12216 @opindex mno-powerpc-gpopt
12217 @opindex mpowerpc-gfxopt
12218 @opindex mno-powerpc-gfxopt
12219 @opindex mpowerpc64
12220 @opindex mno-powerpc64
12224 @opindex mno-popcntb
12230 @opindex mno-mfpgpr
12233 GCC supports two related instruction set architectures for the
12234 RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those
12235 instructions supported by the @samp{rios} chip set used in the original
12236 RS/6000 systems and the @dfn{PowerPC} instruction set is the
12237 architecture of the Freescale MPC5xx, MPC6xx, MPC8xx microprocessors, and
12238 the IBM 4xx, 6xx, and follow-on microprocessors.
12240 Neither architecture is a subset of the other. However there is a
12241 large common subset of instructions supported by both. An MQ
12242 register is included in processors supporting the POWER architecture.
12244 You use these options to specify which instructions are available on the
12245 processor you are using. The default value of these options is
12246 determined when configuring GCC@. Specifying the
12247 @option{-mcpu=@var{cpu_type}} overrides the specification of these
12248 options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
12249 rather than the options listed above.
12251 The @option{-mpower} option allows GCC to generate instructions that
12252 are found only in the POWER architecture and to use the MQ register.
12253 Specifying @option{-mpower2} implies @option{-power} and also allows GCC
12254 to generate instructions that are present in the POWER2 architecture but
12255 not the original POWER architecture.
12257 The @option{-mpowerpc} option allows GCC to generate instructions that
12258 are found only in the 32-bit subset of the PowerPC architecture.
12259 Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
12260 GCC to use the optional PowerPC architecture instructions in the
12261 General Purpose group, including floating-point square root. Specifying
12262 @option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
12263 use the optional PowerPC architecture instructions in the Graphics
12264 group, including floating-point select.
12266 The @option{-mmfcrf} option allows GCC to generate the move from
12267 condition register field instruction implemented on the POWER4
12268 processor and other processors that support the PowerPC V2.01
12270 The @option{-mpopcntb} option allows GCC to generate the popcount and
12271 double precision FP reciprocal estimate instruction implemented on the
12272 POWER5 processor and other processors that support the PowerPC V2.02
12274 The @option{-mfprnd} option allows GCC to generate the FP round to
12275 integer instructions implemented on the POWER5+ processor and other
12276 processors that support the PowerPC V2.03 architecture.
12277 The @option{-mcmpb} option allows GCC to generate the compare bytes
12278 instruction implemented on the POWER6 processor and other processors
12279 that support the PowerPC V2.05 architecture.
12280 The @option{-mmfpgpr} option allows GCC to generate the FP move to/from
12281 general purpose register instructions implemented on the POWER6X
12282 processor and other processors that support the extended PowerPC V2.05
12284 The @option{-mdfp} option allows GCC to generate the decimal floating
12285 point instructions implemented on some POWER processors.
12287 The @option{-mpowerpc64} option allows GCC to generate the additional
12288 64-bit instructions that are found in the full PowerPC64 architecture
12289 and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
12290 @option{-mno-powerpc64}.
12292 If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
12293 will use only the instructions in the common subset of both
12294 architectures plus some special AIX common-mode calls, and will not use
12295 the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
12296 permits GCC to use any instruction from either architecture and to
12297 allow use of the MQ register; specify this for the Motorola MPC601.
12299 @item -mnew-mnemonics
12300 @itemx -mold-mnemonics
12301 @opindex mnew-mnemonics
12302 @opindex mold-mnemonics
12303 Select which mnemonics to use in the generated assembler code. With
12304 @option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
12305 the PowerPC architecture. With @option{-mold-mnemonics} it uses the
12306 assembler mnemonics defined for the POWER architecture. Instructions
12307 defined in only one architecture have only one mnemonic; GCC uses that
12308 mnemonic irrespective of which of these options is specified.
12310 GCC defaults to the mnemonics appropriate for the architecture in
12311 use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
12312 value of these option. Unless you are building a cross-compiler, you
12313 should normally not specify either @option{-mnew-mnemonics} or
12314 @option{-mold-mnemonics}, but should instead accept the default.
12316 @item -mcpu=@var{cpu_type}
12318 Set architecture type, register usage, choice of mnemonics, and
12319 instruction scheduling parameters for machine type @var{cpu_type}.
12320 Supported values for @var{cpu_type} are @samp{401}, @samp{403},
12321 @samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{505},
12322 @samp{601}, @samp{602}, @samp{603}, @samp{603e}, @samp{604},
12323 @samp{604e}, @samp{620}, @samp{630}, @samp{740}, @samp{7400},
12324 @samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
12325 @samp{860}, @samp{970}, @samp{8540}, @samp{ec603e}, @samp{G3},
12326 @samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3},
12327 @samp{power4}, @samp{power5}, @samp{power5+}, @samp{power6},
12328 @samp{power6x}, @samp{common}, @samp{powerpc}, @samp{powerpc64},
12329 @samp{rios}, @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64}.
12331 @option{-mcpu=common} selects a completely generic processor. Code
12332 generated under this option will run on any POWER or PowerPC processor.
12333 GCC will use only the instructions in the common subset of both
12334 architectures, and will not use the MQ register. GCC assumes a generic
12335 processor model for scheduling purposes.
12337 @option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
12338 @option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
12339 PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
12340 types, with an appropriate, generic processor model assumed for
12341 scheduling purposes.
12343 The other options specify a specific processor. Code generated under
12344 those options will run best on that processor, and may not run at all on
12347 The @option{-mcpu} options automatically enable or disable the
12350 @gccoptlist{-maltivec -mfprnd -mhard-float -mmfcrf -mmultiple @gol
12351 -mnew-mnemonics -mpopcntb -mpower -mpower2 -mpowerpc64 @gol
12352 -mpowerpc-gpopt -mpowerpc-gfxopt -mstring -mmulhw -mdlmzb -mmfpgpr}
12354 The particular options set for any particular CPU will vary between
12355 compiler versions, depending on what setting seems to produce optimal
12356 code for that CPU; it doesn't necessarily reflect the actual hardware's
12357 capabilities. If you wish to set an individual option to a particular
12358 value, you may specify it after the @option{-mcpu} option, like
12359 @samp{-mcpu=970 -mno-altivec}.
12361 On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
12362 not enabled or disabled by the @option{-mcpu} option at present because
12363 AIX does not have full support for these options. You may still
12364 enable or disable them individually if you're sure it'll work in your
12367 @item -mtune=@var{cpu_type}
12369 Set the instruction scheduling parameters for machine type
12370 @var{cpu_type}, but do not set the architecture type, register usage, or
12371 choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
12372 values for @var{cpu_type} are used for @option{-mtune} as for
12373 @option{-mcpu}. If both are specified, the code generated will use the
12374 architecture, registers, and mnemonics set by @option{-mcpu}, but the
12375 scheduling parameters set by @option{-mtune}.
12381 Generate code to compute division as reciprocal estimate and iterative
12382 refinement, creating opportunities for increased throughput. This
12383 feature requires: optional PowerPC Graphics instruction set for single
12384 precision and FRE instruction for double precision, assuming divides
12385 cannot generate user-visible traps, and the domain values not include
12386 Infinities, denormals or zero denominator.
12389 @itemx -mno-altivec
12391 @opindex mno-altivec
12392 Generate code that uses (does not use) AltiVec instructions, and also
12393 enable the use of built-in functions that allow more direct access to
12394 the AltiVec instruction set. You may also need to set
12395 @option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
12401 @opindex mno-vrsave
12402 Generate VRSAVE instructions when generating AltiVec code.
12405 @opindex msecure-plt
12406 Generate code that allows ld and ld.so to build executables and shared
12407 libraries with non-exec .plt and .got sections. This is a PowerPC
12408 32-bit SYSV ABI option.
12412 Generate code that uses a BSS .plt section that ld.so fills in, and
12413 requires .plt and .got sections that are both writable and executable.
12414 This is a PowerPC 32-bit SYSV ABI option.
12420 This switch enables or disables the generation of ISEL instructions.
12422 @item -misel=@var{yes/no}
12423 This switch has been deprecated. Use @option{-misel} and
12424 @option{-mno-isel} instead.
12430 This switch enables or disables the generation of SPE simd
12433 @item -mspe=@var{yes/no}
12434 This option has been deprecated. Use @option{-mspe} and
12435 @option{-mno-spe} instead.
12437 @item -mfloat-gprs=@var{yes/single/double/no}
12438 @itemx -mfloat-gprs
12439 @opindex mfloat-gprs
12440 This switch enables or disables the generation of floating point
12441 operations on the general purpose registers for architectures that
12444 The argument @var{yes} or @var{single} enables the use of
12445 single-precision floating point operations.
12447 The argument @var{double} enables the use of single and
12448 double-precision floating point operations.
12450 The argument @var{no} disables floating point operations on the
12451 general purpose registers.
12453 This option is currently only available on the MPC854x.
12459 Generate code for 32-bit or 64-bit environments of Darwin and SVR4
12460 targets (including GNU/Linux). The 32-bit environment sets int, long
12461 and pointer to 32 bits and generates code that runs on any PowerPC
12462 variant. The 64-bit environment sets int to 32 bits and long and
12463 pointer to 64 bits, and generates code for PowerPC64, as for
12464 @option{-mpowerpc64}.
12467 @itemx -mno-fp-in-toc
12468 @itemx -mno-sum-in-toc
12469 @itemx -mminimal-toc
12471 @opindex mno-fp-in-toc
12472 @opindex mno-sum-in-toc
12473 @opindex mminimal-toc
12474 Modify generation of the TOC (Table Of Contents), which is created for
12475 every executable file. The @option{-mfull-toc} option is selected by
12476 default. In that case, GCC will allocate at least one TOC entry for
12477 each unique non-automatic variable reference in your program. GCC
12478 will also place floating-point constants in the TOC@. However, only
12479 16,384 entries are available in the TOC@.
12481 If you receive a linker error message that saying you have overflowed
12482 the available TOC space, you can reduce the amount of TOC space used
12483 with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
12484 @option{-mno-fp-in-toc} prevents GCC from putting floating-point
12485 constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
12486 generate code to calculate the sum of an address and a constant at
12487 run-time instead of putting that sum into the TOC@. You may specify one
12488 or both of these options. Each causes GCC to produce very slightly
12489 slower and larger code at the expense of conserving TOC space.
12491 If you still run out of space in the TOC even when you specify both of
12492 these options, specify @option{-mminimal-toc} instead. This option causes
12493 GCC to make only one TOC entry for every file. When you specify this
12494 option, GCC will produce code that is slower and larger but which
12495 uses extremely little TOC space. You may wish to use this option
12496 only on files that contain less frequently executed code.
12502 Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
12503 @code{long} type, and the infrastructure needed to support them.
12504 Specifying @option{-maix64} implies @option{-mpowerpc64} and
12505 @option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
12506 implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
12509 @itemx -mno-xl-compat
12510 @opindex mxl-compat
12511 @opindex mno-xl-compat
12512 Produce code that conforms more closely to IBM XL compiler semantics
12513 when using AIX-compatible ABI. Pass floating-point arguments to
12514 prototyped functions beyond the register save area (RSA) on the stack
12515 in addition to argument FPRs. Do not assume that most significant
12516 double in 128-bit long double value is properly rounded when comparing
12517 values and converting to double. Use XL symbol names for long double
12520 The AIX calling convention was extended but not initially documented to
12521 handle an obscure K&R C case of calling a function that takes the
12522 address of its arguments with fewer arguments than declared. IBM XL
12523 compilers access floating point arguments which do not fit in the
12524 RSA from the stack when a subroutine is compiled without
12525 optimization. Because always storing floating-point arguments on the
12526 stack is inefficient and rarely needed, this option is not enabled by
12527 default and only is necessary when calling subroutines compiled by IBM
12528 XL compilers without optimization.
12532 Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
12533 application written to use message passing with special startup code to
12534 enable the application to run. The system must have PE installed in the
12535 standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
12536 must be overridden with the @option{-specs=} option to specify the
12537 appropriate directory location. The Parallel Environment does not
12538 support threads, so the @option{-mpe} option and the @option{-pthread}
12539 option are incompatible.
12541 @item -malign-natural
12542 @itemx -malign-power
12543 @opindex malign-natural
12544 @opindex malign-power
12545 On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
12546 @option{-malign-natural} overrides the ABI-defined alignment of larger
12547 types, such as floating-point doubles, on their natural size-based boundary.
12548 The option @option{-malign-power} instructs GCC to follow the ABI-specified
12549 alignment rules. GCC defaults to the standard alignment defined in the ABI@.
12551 On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
12555 @itemx -mhard-float
12556 @opindex msoft-float
12557 @opindex mhard-float
12558 Generate code that does not use (uses) the floating-point register set.
12559 Software floating point emulation is provided if you use the
12560 @option{-msoft-float} option, and pass the option to GCC when linking.
12563 @itemx -mno-multiple
12565 @opindex mno-multiple
12566 Generate code that uses (does not use) the load multiple word
12567 instructions and the store multiple word instructions. These
12568 instructions are generated by default on POWER systems, and not
12569 generated on PowerPC systems. Do not use @option{-mmultiple} on little
12570 endian PowerPC systems, since those instructions do not work when the
12571 processor is in little endian mode. The exceptions are PPC740 and
12572 PPC750 which permit the instructions usage in little endian mode.
12577 @opindex mno-string
12578 Generate code that uses (does not use) the load string instructions
12579 and the store string word instructions to save multiple registers and
12580 do small block moves. These instructions are generated by default on
12581 POWER systems, and not generated on PowerPC systems. Do not use
12582 @option{-mstring} on little endian PowerPC systems, since those
12583 instructions do not work when the processor is in little endian mode.
12584 The exceptions are PPC740 and PPC750 which permit the instructions
12585 usage in little endian mode.
12590 @opindex mno-update
12591 Generate code that uses (does not use) the load or store instructions
12592 that update the base register to the address of the calculated memory
12593 location. These instructions are generated by default. If you use
12594 @option{-mno-update}, there is a small window between the time that the
12595 stack pointer is updated and the address of the previous frame is
12596 stored, which means code that walks the stack frame across interrupts or
12597 signals may get corrupted data.
12600 @itemx -mno-fused-madd
12601 @opindex mfused-madd
12602 @opindex mno-fused-madd
12603 Generate code that uses (does not use) the floating point multiply and
12604 accumulate instructions. These instructions are generated by default if
12605 hardware floating is used.
12611 Generate code that uses (does not use) the half-word multiply and
12612 multiply-accumulate instructions on the IBM 405 and 440 processors.
12613 These instructions are generated by default when targetting those
12620 Generate code that uses (does not use) the string-search @samp{dlmzb}
12621 instruction on the IBM 405 and 440 processors. This instruction is
12622 generated by default when targetting those processors.
12624 @item -mno-bit-align
12626 @opindex mno-bit-align
12627 @opindex mbit-align
12628 On System V.4 and embedded PowerPC systems do not (do) force structures
12629 and unions that contain bit-fields to be aligned to the base type of the
12632 For example, by default a structure containing nothing but 8
12633 @code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
12634 boundary and have a size of 4 bytes. By using @option{-mno-bit-align},
12635 the structure would be aligned to a 1 byte boundary and be one byte in
12638 @item -mno-strict-align
12639 @itemx -mstrict-align
12640 @opindex mno-strict-align
12641 @opindex mstrict-align
12642 On System V.4 and embedded PowerPC systems do not (do) assume that
12643 unaligned memory references will be handled by the system.
12645 @item -mrelocatable
12646 @itemx -mno-relocatable
12647 @opindex mrelocatable
12648 @opindex mno-relocatable
12649 On embedded PowerPC systems generate code that allows (does not allow)
12650 the program to be relocated to a different address at runtime. If you
12651 use @option{-mrelocatable} on any module, all objects linked together must
12652 be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
12654 @item -mrelocatable-lib
12655 @itemx -mno-relocatable-lib
12656 @opindex mrelocatable-lib
12657 @opindex mno-relocatable-lib
12658 On embedded PowerPC systems generate code that allows (does not allow)
12659 the program to be relocated to a different address at runtime. Modules
12660 compiled with @option{-mrelocatable-lib} can be linked with either modules
12661 compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
12662 with modules compiled with the @option{-mrelocatable} options.
12668 On System V.4 and embedded PowerPC systems do not (do) assume that
12669 register 2 contains a pointer to a global area pointing to the addresses
12670 used in the program.
12673 @itemx -mlittle-endian
12675 @opindex mlittle-endian
12676 On System V.4 and embedded PowerPC systems compile code for the
12677 processor in little endian mode. The @option{-mlittle-endian} option is
12678 the same as @option{-mlittle}.
12681 @itemx -mbig-endian
12683 @opindex mbig-endian
12684 On System V.4 and embedded PowerPC systems compile code for the
12685 processor in big endian mode. The @option{-mbig-endian} option is
12686 the same as @option{-mbig}.
12688 @item -mdynamic-no-pic
12689 @opindex mdynamic-no-pic
12690 On Darwin and Mac OS X systems, compile code so that it is not
12691 relocatable, but that its external references are relocatable. The
12692 resulting code is suitable for applications, but not shared
12695 @item -mprioritize-restricted-insns=@var{priority}
12696 @opindex mprioritize-restricted-insns
12697 This option controls the priority that is assigned to
12698 dispatch-slot restricted instructions during the second scheduling
12699 pass. The argument @var{priority} takes the value @var{0/1/2} to assign
12700 @var{no/highest/second-highest} priority to dispatch slot restricted
12703 @item -msched-costly-dep=@var{dependence_type}
12704 @opindex msched-costly-dep
12705 This option controls which dependences are considered costly
12706 by the target during instruction scheduling. The argument
12707 @var{dependence_type} takes one of the following values:
12708 @var{no}: no dependence is costly,
12709 @var{all}: all dependences are costly,
12710 @var{true_store_to_load}: a true dependence from store to load is costly,
12711 @var{store_to_load}: any dependence from store to load is costly,
12712 @var{number}: any dependence which latency >= @var{number} is costly.
12714 @item -minsert-sched-nops=@var{scheme}
12715 @opindex minsert-sched-nops
12716 This option controls which nop insertion scheme will be used during
12717 the second scheduling pass. The argument @var{scheme} takes one of the
12719 @var{no}: Don't insert nops.
12720 @var{pad}: Pad with nops any dispatch group which has vacant issue slots,
12721 according to the scheduler's grouping.
12722 @var{regroup_exact}: Insert nops to force costly dependent insns into
12723 separate groups. Insert exactly as many nops as needed to force an insn
12724 to a new group, according to the estimated processor grouping.
12725 @var{number}: Insert nops to force costly dependent insns into
12726 separate groups. Insert @var{number} nops to force an insn to a new group.
12729 @opindex mcall-sysv
12730 On System V.4 and embedded PowerPC systems compile code using calling
12731 conventions that adheres to the March 1995 draft of the System V
12732 Application Binary Interface, PowerPC processor supplement. This is the
12733 default unless you configured GCC using @samp{powerpc-*-eabiaix}.
12735 @item -mcall-sysv-eabi
12736 @opindex mcall-sysv-eabi
12737 Specify both @option{-mcall-sysv} and @option{-meabi} options.
12739 @item -mcall-sysv-noeabi
12740 @opindex mcall-sysv-noeabi
12741 Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
12743 @item -mcall-solaris
12744 @opindex mcall-solaris
12745 On System V.4 and embedded PowerPC systems compile code for the Solaris
12749 @opindex mcall-linux
12750 On System V.4 and embedded PowerPC systems compile code for the
12751 Linux-based GNU system.
12755 On System V.4 and embedded PowerPC systems compile code for the
12756 Hurd-based GNU system.
12758 @item -mcall-netbsd
12759 @opindex mcall-netbsd
12760 On System V.4 and embedded PowerPC systems compile code for the
12761 NetBSD operating system.
12763 @item -maix-struct-return
12764 @opindex maix-struct-return
12765 Return all structures in memory (as specified by the AIX ABI)@.
12767 @item -msvr4-struct-return
12768 @opindex msvr4-struct-return
12769 Return structures smaller than 8 bytes in registers (as specified by the
12772 @item -mabi=@var{abi-type}
12774 Extend the current ABI with a particular extension, or remove such extension.
12775 Valid values are @var{altivec}, @var{no-altivec}, @var{spe},
12776 @var{no-spe}, @var{ibmlongdouble}, @var{ieeelongdouble}@.
12780 Extend the current ABI with SPE ABI extensions. This does not change
12781 the default ABI, instead it adds the SPE ABI extensions to the current
12785 @opindex mabi=no-spe
12786 Disable Booke SPE ABI extensions for the current ABI@.
12788 @item -mabi=ibmlongdouble
12789 @opindex mabi=ibmlongdouble
12790 Change the current ABI to use IBM extended precision long double.
12791 This is a PowerPC 32-bit SYSV ABI option.
12793 @item -mabi=ieeelongdouble
12794 @opindex mabi=ieeelongdouble
12795 Change the current ABI to use IEEE extended precision long double.
12796 This is a PowerPC 32-bit Linux ABI option.
12799 @itemx -mno-prototype
12800 @opindex mprototype
12801 @opindex mno-prototype
12802 On System V.4 and embedded PowerPC systems assume that all calls to
12803 variable argument functions are properly prototyped. Otherwise, the
12804 compiler must insert an instruction before every non prototyped call to
12805 set or clear bit 6 of the condition code register (@var{CR}) to
12806 indicate whether floating point values were passed in the floating point
12807 registers in case the function takes a variable arguments. With
12808 @option{-mprototype}, only calls to prototyped variable argument functions
12809 will set or clear the bit.
12813 On embedded PowerPC systems, assume that the startup module is called
12814 @file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
12815 @file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
12820 On embedded PowerPC systems, assume that the startup module is called
12821 @file{crt0.o} and the standard C libraries are @file{libmvme.a} and
12826 On embedded PowerPC systems, assume that the startup module is called
12827 @file{crt0.o} and the standard C libraries are @file{libads.a} and
12830 @item -myellowknife
12831 @opindex myellowknife
12832 On embedded PowerPC systems, assume that the startup module is called
12833 @file{crt0.o} and the standard C libraries are @file{libyk.a} and
12838 On System V.4 and embedded PowerPC systems, specify that you are
12839 compiling for a VxWorks system.
12843 Specify that you are compiling for the WindISS simulation environment.
12847 On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
12848 header to indicate that @samp{eabi} extended relocations are used.
12854 On System V.4 and embedded PowerPC systems do (do not) adhere to the
12855 Embedded Applications Binary Interface (eabi) which is a set of
12856 modifications to the System V.4 specifications. Selecting @option{-meabi}
12857 means that the stack is aligned to an 8 byte boundary, a function
12858 @code{__eabi} is called to from @code{main} to set up the eabi
12859 environment, and the @option{-msdata} option can use both @code{r2} and
12860 @code{r13} to point to two separate small data areas. Selecting
12861 @option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
12862 do not call an initialization function from @code{main}, and the
12863 @option{-msdata} option will only use @code{r13} to point to a single
12864 small data area. The @option{-meabi} option is on by default if you
12865 configured GCC using one of the @samp{powerpc*-*-eabi*} options.
12868 @opindex msdata=eabi
12869 On System V.4 and embedded PowerPC systems, put small initialized
12870 @code{const} global and static data in the @samp{.sdata2} section, which
12871 is pointed to by register @code{r2}. Put small initialized
12872 non-@code{const} global and static data in the @samp{.sdata} section,
12873 which is pointed to by register @code{r13}. Put small uninitialized
12874 global and static data in the @samp{.sbss} section, which is adjacent to
12875 the @samp{.sdata} section. The @option{-msdata=eabi} option is
12876 incompatible with the @option{-mrelocatable} option. The
12877 @option{-msdata=eabi} option also sets the @option{-memb} option.
12880 @opindex msdata=sysv
12881 On System V.4 and embedded PowerPC systems, put small global and static
12882 data in the @samp{.sdata} section, which is pointed to by register
12883 @code{r13}. Put small uninitialized global and static data in the
12884 @samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
12885 The @option{-msdata=sysv} option is incompatible with the
12886 @option{-mrelocatable} option.
12888 @item -msdata=default
12890 @opindex msdata=default
12892 On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
12893 compile code the same as @option{-msdata=eabi}, otherwise compile code the
12894 same as @option{-msdata=sysv}.
12897 @opindex msdata-data
12898 On System V.4 and embedded PowerPC systems, put small global
12899 data in the @samp{.sdata} section. Put small uninitialized global
12900 data in the @samp{.sbss} section. Do not use register @code{r13}
12901 to address small data however. This is the default behavior unless
12902 other @option{-msdata} options are used.
12906 @opindex msdata=none
12908 On embedded PowerPC systems, put all initialized global and static data
12909 in the @samp{.data} section, and all uninitialized data in the
12910 @samp{.bss} section.
12914 @cindex smaller data references (PowerPC)
12915 @cindex .sdata/.sdata2 references (PowerPC)
12916 On embedded PowerPC systems, put global and static items less than or
12917 equal to @var{num} bytes into the small data or bss sections instead of
12918 the normal data or bss section. By default, @var{num} is 8. The
12919 @option{-G @var{num}} switch is also passed to the linker.
12920 All modules should be compiled with the same @option{-G @var{num}} value.
12923 @itemx -mno-regnames
12925 @opindex mno-regnames
12926 On System V.4 and embedded PowerPC systems do (do not) emit register
12927 names in the assembly language output using symbolic forms.
12930 @itemx -mno-longcall
12932 @opindex mno-longcall
12933 By default assume that all calls are far away so that a longer more
12934 expensive calling sequence is required. This is required for calls
12935 further than 32 megabytes (33,554,432 bytes) from the current location.
12936 A short call will be generated if the compiler knows
12937 the call cannot be that far away. This setting can be overridden by
12938 the @code{shortcall} function attribute, or by @code{#pragma
12941 Some linkers are capable of detecting out-of-range calls and generating
12942 glue code on the fly. On these systems, long calls are unnecessary and
12943 generate slower code. As of this writing, the AIX linker can do this,
12944 as can the GNU linker for PowerPC/64. It is planned to add this feature
12945 to the GNU linker for 32-bit PowerPC systems as well.
12947 On Darwin/PPC systems, @code{#pragma longcall} will generate ``jbsr
12948 callee, L42'', plus a ``branch island'' (glue code). The two target
12949 addresses represent the callee and the ``branch island''. The
12950 Darwin/PPC linker will prefer the first address and generate a ``bl
12951 callee'' if the PPC ``bl'' instruction will reach the callee directly;
12952 otherwise, the linker will generate ``bl L42'' to call the ``branch
12953 island''. The ``branch island'' is appended to the body of the
12954 calling function; it computes the full 32-bit address of the callee
12957 On Mach-O (Darwin) systems, this option directs the compiler emit to
12958 the glue for every direct call, and the Darwin linker decides whether
12959 to use or discard it.
12961 In the future, we may cause GCC to ignore all longcall specifications
12962 when the linker is known to generate glue.
12966 Adds support for multithreading with the @dfn{pthreads} library.
12967 This option sets flags for both the preprocessor and linker.
12971 @node S/390 and zSeries Options
12972 @subsection S/390 and zSeries Options
12973 @cindex S/390 and zSeries Options
12975 These are the @samp{-m} options defined for the S/390 and zSeries architecture.
12979 @itemx -msoft-float
12980 @opindex mhard-float
12981 @opindex msoft-float
12982 Use (do not use) the hardware floating-point instructions and registers
12983 for floating-point operations. When @option{-msoft-float} is specified,
12984 functions in @file{libgcc.a} will be used to perform floating-point
12985 operations. When @option{-mhard-float} is specified, the compiler
12986 generates IEEE floating-point instructions. This is the default.
12988 @item -mlong-double-64
12989 @itemx -mlong-double-128
12990 @opindex mlong-double-64
12991 @opindex mlong-double-128
12992 These switches control the size of @code{long double} type. A size
12993 of 64bit makes the @code{long double} type equivalent to the @code{double}
12994 type. This is the default.
12997 @itemx -mno-backchain
12998 @opindex mbackchain
12999 @opindex mno-backchain
13000 Store (do not store) the address of the caller's frame as backchain pointer
13001 into the callee's stack frame.
13002 A backchain may be needed to allow debugging using tools that do not understand
13003 DWARF-2 call frame information.
13004 When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
13005 at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
13006 the backchain is placed into the topmost word of the 96/160 byte register
13009 In general, code compiled with @option{-mbackchain} is call-compatible with
13010 code compiled with @option{-mmo-backchain}; however, use of the backchain
13011 for debugging purposes usually requires that the whole binary is built with
13012 @option{-mbackchain}. Note that the combination of @option{-mbackchain},
13013 @option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
13014 to build a linux kernel use @option{-msoft-float}.
13016 The default is to not maintain the backchain.
13018 @item -mpacked-stack
13019 @item -mno-packed-stack
13020 @opindex mpacked-stack
13021 @opindex mno-packed-stack
13022 Use (do not use) the packed stack layout. When @option{-mno-packed-stack} is
13023 specified, the compiler uses the all fields of the 96/160 byte register save
13024 area only for their default purpose; unused fields still take up stack space.
13025 When @option{-mpacked-stack} is specified, register save slots are densely
13026 packed at the top of the register save area; unused space is reused for other
13027 purposes, allowing for more efficient use of the available stack space.
13028 However, when @option{-mbackchain} is also in effect, the topmost word of
13029 the save area is always used to store the backchain, and the return address
13030 register is always saved two words below the backchain.
13032 As long as the stack frame backchain is not used, code generated with
13033 @option{-mpacked-stack} is call-compatible with code generated with
13034 @option{-mno-packed-stack}. Note that some non-FSF releases of GCC 2.95 for
13035 S/390 or zSeries generated code that uses the stack frame backchain at run
13036 time, not just for debugging purposes. Such code is not call-compatible
13037 with code compiled with @option{-mpacked-stack}. Also, note that the
13038 combination of @option{-mbackchain},
13039 @option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
13040 to build a linux kernel use @option{-msoft-float}.
13042 The default is to not use the packed stack layout.
13045 @itemx -mno-small-exec
13046 @opindex msmall-exec
13047 @opindex mno-small-exec
13048 Generate (or do not generate) code using the @code{bras} instruction
13049 to do subroutine calls.
13050 This only works reliably if the total executable size does not
13051 exceed 64k. The default is to use the @code{basr} instruction instead,
13052 which does not have this limitation.
13058 When @option{-m31} is specified, generate code compliant to the
13059 GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate
13060 code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in
13061 particular to generate 64-bit instructions. For the @samp{s390}
13062 targets, the default is @option{-m31}, while the @samp{s390x}
13063 targets default to @option{-m64}.
13069 When @option{-mzarch} is specified, generate code using the
13070 instructions available on z/Architecture.
13071 When @option{-mesa} is specified, generate code using the
13072 instructions available on ESA/390. Note that @option{-mesa} is
13073 not possible with @option{-m64}.
13074 When generating code compliant to the GNU/Linux for S/390 ABI,
13075 the default is @option{-mesa}. When generating code compliant
13076 to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
13082 Generate (or do not generate) code using the @code{mvcle} instruction
13083 to perform block moves. When @option{-mno-mvcle} is specified,
13084 use a @code{mvc} loop instead. This is the default unless optimizing for
13091 Print (or do not print) additional debug information when compiling.
13092 The default is to not print debug information.
13094 @item -march=@var{cpu-type}
13096 Generate code that will run on @var{cpu-type}, which is the name of a system
13097 representing a certain processor type. Possible values for
13098 @var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, and @samp{z990}.
13099 When generating code using the instructions available on z/Architecture,
13100 the default is @option{-march=z900}. Otherwise, the default is
13101 @option{-march=g5}.
13103 @item -mtune=@var{cpu-type}
13105 Tune to @var{cpu-type} everything applicable about the generated code,
13106 except for the ABI and the set of available instructions.
13107 The list of @var{cpu-type} values is the same as for @option{-march}.
13108 The default is the value used for @option{-march}.
13111 @itemx -mno-tpf-trace
13112 @opindex mtpf-trace
13113 @opindex mno-tpf-trace
13114 Generate code that adds (does not add) in TPF OS specific branches to trace
13115 routines in the operating system. This option is off by default, even
13116 when compiling for the TPF OS@.
13119 @itemx -mno-fused-madd
13120 @opindex mfused-madd
13121 @opindex mno-fused-madd
13122 Generate code that uses (does not use) the floating point multiply and
13123 accumulate instructions. These instructions are generated by default if
13124 hardware floating point is used.
13126 @item -mwarn-framesize=@var{framesize}
13127 @opindex mwarn-framesize
13128 Emit a warning if the current function exceeds the given frame size. Because
13129 this is a compile time check it doesn't need to be a real problem when the program
13130 runs. It is intended to identify functions which most probably cause
13131 a stack overflow. It is useful to be used in an environment with limited stack
13132 size e.g.@: the linux kernel.
13134 @item -mwarn-dynamicstack
13135 @opindex mwarn-dynamicstack
13136 Emit a warning if the function calls alloca or uses dynamically
13137 sized arrays. This is generally a bad idea with a limited stack size.
13139 @item -mstack-guard=@var{stack-guard}
13140 @item -mstack-size=@var{stack-size}
13141 @opindex mstack-guard
13142 @opindex mstack-size
13143 If these options are provided the s390 back end emits additional instructions in
13144 the function prologue which trigger a trap if the stack size is @var{stack-guard}
13145 bytes above the @var{stack-size} (remember that the stack on s390 grows downward).
13146 If the @var{stack-guard} option is omitted the smallest power of 2 larger than
13147 the frame size of the compiled function is chosen.
13148 These options are intended to be used to help debugging stack overflow problems.
13149 The additionally emitted code causes only little overhead and hence can also be
13150 used in production like systems without greater performance degradation. The given
13151 values have to be exact powers of 2 and @var{stack-size} has to be greater than
13152 @var{stack-guard} without exceeding 64k.
13153 In order to be efficient the extra code makes the assumption that the stack starts
13154 at an address aligned to the value given by @var{stack-size}.
13155 The @var{stack-guard} option can only be used in conjunction with @var{stack-size}.
13158 @node Score Options
13159 @subsection Score Options
13160 @cindex Score Options
13162 These options are defined for Score implementations:
13167 Compile code for big endian mode. This is the default.
13171 Compile code for little endian mode.
13175 Disable generate bcnz instruction.
13179 Enable generate unaligned load and store instruction.
13183 Enable the use of multiply-accumulate instructions. Disabled by default.
13187 Specify the SCORE5 as the target architecture.
13191 Specify the SCORE5U of the target architecture.
13195 Specify the SCORE7 as the target architecture. This is the default.
13199 Specify the SCORE7D as the target architecture.
13203 @subsection SH Options
13205 These @samp{-m} options are defined for the SH implementations:
13210 Generate code for the SH1.
13214 Generate code for the SH2.
13217 Generate code for the SH2e.
13221 Generate code for the SH3.
13225 Generate code for the SH3e.
13229 Generate code for the SH4 without a floating-point unit.
13231 @item -m4-single-only
13232 @opindex m4-single-only
13233 Generate code for the SH4 with a floating-point unit that only
13234 supports single-precision arithmetic.
13238 Generate code for the SH4 assuming the floating-point unit is in
13239 single-precision mode by default.
13243 Generate code for the SH4.
13247 Generate code for the SH4al-dsp, or for a SH4a in such a way that the
13248 floating-point unit is not used.
13250 @item -m4a-single-only
13251 @opindex m4a-single-only
13252 Generate code for the SH4a, in such a way that no double-precision
13253 floating point operations are used.
13256 @opindex m4a-single
13257 Generate code for the SH4a assuming the floating-point unit is in
13258 single-precision mode by default.
13262 Generate code for the SH4a.
13266 Same as @option{-m4a-nofpu}, except that it implicitly passes
13267 @option{-dsp} to the assembler. GCC doesn't generate any DSP
13268 instructions at the moment.
13272 Compile code for the processor in big endian mode.
13276 Compile code for the processor in little endian mode.
13280 Align doubles at 64-bit boundaries. Note that this changes the calling
13281 conventions, and thus some functions from the standard C library will
13282 not work unless you recompile it first with @option{-mdalign}.
13286 Shorten some address references at link time, when possible; uses the
13287 linker option @option{-relax}.
13291 Use 32-bit offsets in @code{switch} tables. The default is to use
13296 Enable the use of the instruction @code{fmovd}.
13300 Comply with the calling conventions defined by Renesas.
13304 Comply with the calling conventions defined by Renesas.
13308 Comply with the calling conventions defined for GCC before the Renesas
13309 conventions were available. This option is the default for all
13310 targets of the SH toolchain except for @samp{sh-symbianelf}.
13313 @opindex mnomacsave
13314 Mark the @code{MAC} register as call-clobbered, even if
13315 @option{-mhitachi} is given.
13319 Increase IEEE-compliance of floating-point code.
13320 At the moment, this is equivalent to @option{-fno-finite-math-only}.
13321 When generating 16 bit SH opcodes, getting IEEE-conforming results for
13322 comparisons of NANs / infinities incurs extra overhead in every
13323 floating point comparison, therefore the default is set to
13324 @option{-ffinite-math-only}.
13326 @item -minline-ic_invalidate
13327 @opindex minline-ic_invalidate
13328 Inline code to invalidate instruction cache entries after setting up
13329 nested function trampolines.
13330 This option has no effect if -musermode is in effect and the selected
13331 code generation option (e.g. -m4) does not allow the use of the icbi
13333 If the selected code generation option does not allow the use of the icbi
13334 instruction, and -musermode is not in effect, the inlined code will
13335 manipulate the instruction cache address array directly with an associative
13336 write. This not only requires privileged mode, but it will also
13337 fail if the cache line had been mapped via the TLB and has become unmapped.
13341 Dump instruction size and location in the assembly code.
13344 @opindex mpadstruct
13345 This option is deprecated. It pads structures to multiple of 4 bytes,
13346 which is incompatible with the SH ABI@.
13350 Optimize for space instead of speed. Implied by @option{-Os}.
13353 @opindex mprefergot
13354 When generating position-independent code, emit function calls using
13355 the Global Offset Table instead of the Procedure Linkage Table.
13359 Don't generate privileged mode only code; implies -mno-inline-ic_invalidate
13360 if the inlined code would not work in user mode.
13361 This is the default when the target is @code{sh-*-linux*}.
13363 @item -multcost=@var{number}
13364 @opindex multcost=@var{number}
13365 Set the cost to assume for a multiply insn.
13367 @item -mdiv=@var{strategy}
13368 @opindex mdiv=@var{strategy}
13369 Set the division strategy to use for SHmedia code. @var{strategy} must be
13370 one of: call, call2, fp, inv, inv:minlat, inv20u, inv20l, inv:call,
13371 inv:call2, inv:fp .
13372 "fp" performs the operation in floating point. This has a very high latency,
13373 but needs only a few instructions, so it might be a good choice if
13374 your code has enough easily exploitable ILP to allow the compiler to
13375 schedule the floating point instructions together with other instructions.
13376 Division by zero causes a floating point exception.
13377 "inv" uses integer operations to calculate the inverse of the divisor,
13378 and then multiplies the dividend with the inverse. This strategy allows
13379 cse and hoisting of the inverse calculation. Division by zero calculates
13380 an unspecified result, but does not trap.
13381 "inv:minlat" is a variant of "inv" where if no cse / hoisting opportunities
13382 have been found, or if the entire operation has been hoisted to the same
13383 place, the last stages of the inverse calculation are intertwined with the
13384 final multiply to reduce the overall latency, at the expense of using a few
13385 more instructions, and thus offering fewer scheduling opportunities with
13387 "call" calls a library function that usually implements the inv:minlat
13389 This gives high code density for m5-*media-nofpu compilations.
13390 "call2" uses a different entry point of the same library function, where it
13391 assumes that a pointer to a lookup table has already been set up, which
13392 exposes the pointer load to cse / code hoisting optimizations.
13393 "inv:call", "inv:call2" and "inv:fp" all use the "inv" algorithm for initial
13394 code generation, but if the code stays unoptimized, revert to the "call",
13395 "call2", or "fp" strategies, respectively. Note that the
13396 potentially-trapping side effect of division by zero is carried by a
13397 separate instruction, so it is possible that all the integer instructions
13398 are hoisted out, but the marker for the side effect stays where it is.
13399 A recombination to fp operations or a call is not possible in that case.
13400 "inv20u" and "inv20l" are variants of the "inv:minlat" strategy. In the case
13401 that the inverse calculation was nor separated from the multiply, they speed
13402 up division where the dividend fits into 20 bits (plus sign where applicable),
13403 by inserting a test to skip a number of operations in this case; this test
13404 slows down the case of larger dividends. inv20u assumes the case of a such
13405 a small dividend to be unlikely, and inv20l assumes it to be likely.
13407 @item -mdivsi3_libfunc=@var{name}
13408 @opindex mdivsi3_libfunc=@var{name}
13409 Set the name of the library function used for 32 bit signed division to
13410 @var{name}. This only affect the name used in the call and inv:call
13411 division strategies, and the compiler will still expect the same
13412 sets of input/output/clobbered registers as if this option was not present.
13414 @item -madjust-unroll
13415 @opindex madjust-unroll
13416 Throttle unrolling to avoid thrashing target registers.
13417 This option only has an effect if the gcc code base supports the
13418 TARGET_ADJUST_UNROLL_MAX target hook.
13420 @item -mindexed-addressing
13421 @opindex mindexed-addressing
13422 Enable the use of the indexed addressing mode for SHmedia32/SHcompact.
13423 This is only safe if the hardware and/or OS implement 32 bit wrap-around
13424 semantics for the indexed addressing mode. The architecture allows the
13425 implementation of processors with 64 bit MMU, which the OS could use to
13426 get 32 bit addressing, but since no current hardware implementation supports
13427 this or any other way to make the indexed addressing mode safe to use in
13428 the 32 bit ABI, the default is -mno-indexed-addressing.
13430 @item -mgettrcost=@var{number}
13431 @opindex mgettrcost=@var{number}
13432 Set the cost assumed for the gettr instruction to @var{number}.
13433 The default is 2 if @option{-mpt-fixed} is in effect, 100 otherwise.
13437 Assume pt* instructions won't trap. This will generally generate better
13438 scheduled code, but is unsafe on current hardware. The current architecture
13439 definition says that ptabs and ptrel trap when the target anded with 3 is 3.
13440 This has the unintentional effect of making it unsafe to schedule ptabs /
13441 ptrel before a branch, or hoist it out of a loop. For example,
13442 __do_global_ctors, a part of libgcc that runs constructors at program
13443 startup, calls functions in a list which is delimited by @minus{}1. With the
13444 -mpt-fixed option, the ptabs will be done before testing against @minus{}1.
13445 That means that all the constructors will be run a bit quicker, but when
13446 the loop comes to the end of the list, the program crashes because ptabs
13447 loads @minus{}1 into a target register. Since this option is unsafe for any
13448 hardware implementing the current architecture specification, the default
13449 is -mno-pt-fixed. Unless the user specifies a specific cost with
13450 @option{-mgettrcost}, -mno-pt-fixed also implies @option{-mgettrcost=100};
13451 this deters register allocation using target registers for storing
13454 @item -minvalid-symbols
13455 @opindex minvalid-symbols
13456 Assume symbols might be invalid. Ordinary function symbols generated by
13457 the compiler will always be valid to load with movi/shori/ptabs or
13458 movi/shori/ptrel, but with assembler and/or linker tricks it is possible
13459 to generate symbols that will cause ptabs / ptrel to trap.
13460 This option is only meaningful when @option{-mno-pt-fixed} is in effect.
13461 It will then prevent cross-basic-block cse, hoisting and most scheduling
13462 of symbol loads. The default is @option{-mno-invalid-symbols}.
13465 @node SPARC Options
13466 @subsection SPARC Options
13467 @cindex SPARC options
13469 These @samp{-m} options are supported on the SPARC:
13472 @item -mno-app-regs
13474 @opindex mno-app-regs
13476 Specify @option{-mapp-regs} to generate output using the global registers
13477 2 through 4, which the SPARC SVR4 ABI reserves for applications. This
13480 To be fully SVR4 ABI compliant at the cost of some performance loss,
13481 specify @option{-mno-app-regs}. You should compile libraries and system
13482 software with this option.
13485 @itemx -mhard-float
13487 @opindex mhard-float
13488 Generate output containing floating point instructions. This is the
13492 @itemx -msoft-float
13494 @opindex msoft-float
13495 Generate output containing library calls for floating point.
13496 @strong{Warning:} the requisite libraries are not available for all SPARC
13497 targets. Normally the facilities of the machine's usual C compiler are
13498 used, but this cannot be done directly in cross-compilation. You must make
13499 your own arrangements to provide suitable library functions for
13500 cross-compilation. The embedded targets @samp{sparc-*-aout} and
13501 @samp{sparclite-*-*} do provide software floating point support.
13503 @option{-msoft-float} changes the calling convention in the output file;
13504 therefore, it is only useful if you compile @emph{all} of a program with
13505 this option. In particular, you need to compile @file{libgcc.a}, the
13506 library that comes with GCC, with @option{-msoft-float} in order for
13509 @item -mhard-quad-float
13510 @opindex mhard-quad-float
13511 Generate output containing quad-word (long double) floating point
13514 @item -msoft-quad-float
13515 @opindex msoft-quad-float
13516 Generate output containing library calls for quad-word (long double)
13517 floating point instructions. The functions called are those specified
13518 in the SPARC ABI@. This is the default.
13520 As of this writing, there are no SPARC implementations that have hardware
13521 support for the quad-word floating point instructions. They all invoke
13522 a trap handler for one of these instructions, and then the trap handler
13523 emulates the effect of the instruction. Because of the trap handler overhead,
13524 this is much slower than calling the ABI library routines. Thus the
13525 @option{-msoft-quad-float} option is the default.
13527 @item -mno-unaligned-doubles
13528 @itemx -munaligned-doubles
13529 @opindex mno-unaligned-doubles
13530 @opindex munaligned-doubles
13531 Assume that doubles have 8 byte alignment. This is the default.
13533 With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
13534 alignment only if they are contained in another type, or if they have an
13535 absolute address. Otherwise, it assumes they have 4 byte alignment.
13536 Specifying this option avoids some rare compatibility problems with code
13537 generated by other compilers. It is not the default because it results
13538 in a performance loss, especially for floating point code.
13540 @item -mno-faster-structs
13541 @itemx -mfaster-structs
13542 @opindex mno-faster-structs
13543 @opindex mfaster-structs
13544 With @option{-mfaster-structs}, the compiler assumes that structures
13545 should have 8 byte alignment. This enables the use of pairs of
13546 @code{ldd} and @code{std} instructions for copies in structure
13547 assignment, in place of twice as many @code{ld} and @code{st} pairs.
13548 However, the use of this changed alignment directly violates the SPARC
13549 ABI@. Thus, it's intended only for use on targets where the developer
13550 acknowledges that their resulting code will not be directly in line with
13551 the rules of the ABI@.
13553 @item -mimpure-text
13554 @opindex mimpure-text
13555 @option{-mimpure-text}, used in addition to @option{-shared}, tells
13556 the compiler to not pass @option{-z text} to the linker when linking a
13557 shared object. Using this option, you can link position-dependent
13558 code into a shared object.
13560 @option{-mimpure-text} suppresses the ``relocations remain against
13561 allocatable but non-writable sections'' linker error message.
13562 However, the necessary relocations will trigger copy-on-write, and the
13563 shared object is not actually shared across processes. Instead of
13564 using @option{-mimpure-text}, you should compile all source code with
13565 @option{-fpic} or @option{-fPIC}.
13567 This option is only available on SunOS and Solaris.
13569 @item -mcpu=@var{cpu_type}
13571 Set the instruction set, register set, and instruction scheduling parameters
13572 for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
13573 @samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
13574 @samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x},
13575 @samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc},
13576 @samp{ultrasparc3}, and @samp{niagara}.
13578 Default instruction scheduling parameters are used for values that select
13579 an architecture and not an implementation. These are @samp{v7}, @samp{v8},
13580 @samp{sparclite}, @samp{sparclet}, @samp{v9}.
13582 Here is a list of each supported architecture and their supported
13587 v8: supersparc, hypersparc
13588 sparclite: f930, f934, sparclite86x
13590 v9: ultrasparc, ultrasparc3, niagara
13593 By default (unless configured otherwise), GCC generates code for the V7
13594 variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler
13595 additionally optimizes it for the Cypress CY7C602 chip, as used in the
13596 SPARCStation/SPARCServer 3xx series. This is also appropriate for the older
13597 SPARCStation 1, 2, IPX etc.
13599 With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
13600 architecture. The only difference from V7 code is that the compiler emits
13601 the integer multiply and integer divide instructions which exist in SPARC-V8
13602 but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally
13603 optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
13606 With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
13607 the SPARC architecture. This adds the integer multiply, integer divide step
13608 and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
13609 With @option{-mcpu=f930}, the compiler additionally optimizes it for the
13610 Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@. With
13611 @option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
13612 MB86934 chip, which is the more recent SPARClite with FPU@.
13614 With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
13615 the SPARC architecture. This adds the integer multiply, multiply/accumulate,
13616 integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
13617 but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally
13618 optimizes it for the TEMIC SPARClet chip.
13620 With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
13621 architecture. This adds 64-bit integer and floating-point move instructions,
13622 3 additional floating-point condition code registers and conditional move
13623 instructions. With @option{-mcpu=ultrasparc}, the compiler additionally
13624 optimizes it for the Sun UltraSPARC I/II/IIi chips. With
13625 @option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
13626 Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips. With
13627 @option{-mcpu=niagara}, the compiler additionally optimizes it for
13628 Sun UltraSPARC T1 chips.
13630 @item -mtune=@var{cpu_type}
13632 Set the instruction scheduling parameters for machine type
13633 @var{cpu_type}, but do not set the instruction set or register set that the
13634 option @option{-mcpu=@var{cpu_type}} would.
13636 The same values for @option{-mcpu=@var{cpu_type}} can be used for
13637 @option{-mtune=@var{cpu_type}}, but the only useful values are those
13638 that select a particular cpu implementation. Those are @samp{cypress},
13639 @samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
13640 @samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc},
13641 @samp{ultrasparc3}, and @samp{niagara}.
13646 @opindex mno-v8plus
13647 With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@. The
13648 difference from the V8 ABI is that the global and out registers are
13649 considered 64-bit wide. This is enabled by default on Solaris in 32-bit
13650 mode for all SPARC-V9 processors.
13656 With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
13657 Visual Instruction Set extensions. The default is @option{-mno-vis}.
13660 These @samp{-m} options are supported in addition to the above
13661 on SPARC-V9 processors in 64-bit environments:
13664 @item -mlittle-endian
13665 @opindex mlittle-endian
13666 Generate code for a processor running in little-endian mode. It is only
13667 available for a few configurations and most notably not on Solaris and Linux.
13673 Generate code for a 32-bit or 64-bit environment.
13674 The 32-bit environment sets int, long and pointer to 32 bits.
13675 The 64-bit environment sets int to 32 bits and long and pointer
13678 @item -mcmodel=medlow
13679 @opindex mcmodel=medlow
13680 Generate code for the Medium/Low code model: 64-bit addresses, programs
13681 must be linked in the low 32 bits of memory. Programs can be statically
13682 or dynamically linked.
13684 @item -mcmodel=medmid
13685 @opindex mcmodel=medmid
13686 Generate code for the Medium/Middle code model: 64-bit addresses, programs
13687 must be linked in the low 44 bits of memory, the text and data segments must
13688 be less than 2GB in size and the data segment must be located within 2GB of
13691 @item -mcmodel=medany
13692 @opindex mcmodel=medany
13693 Generate code for the Medium/Anywhere code model: 64-bit addresses, programs
13694 may be linked anywhere in memory, the text and data segments must be less
13695 than 2GB in size and the data segment must be located within 2GB of the
13698 @item -mcmodel=embmedany
13699 @opindex mcmodel=embmedany
13700 Generate code for the Medium/Anywhere code model for embedded systems:
13701 64-bit addresses, the text and data segments must be less than 2GB in
13702 size, both starting anywhere in memory (determined at link time). The
13703 global register %g4 points to the base of the data segment. Programs
13704 are statically linked and PIC is not supported.
13707 @itemx -mno-stack-bias
13708 @opindex mstack-bias
13709 @opindex mno-stack-bias
13710 With @option{-mstack-bias}, GCC assumes that the stack pointer, and
13711 frame pointer if present, are offset by @minus{}2047 which must be added back
13712 when making stack frame references. This is the default in 64-bit mode.
13713 Otherwise, assume no such offset is present.
13716 These switches are supported in addition to the above on Solaris:
13721 Add support for multithreading using the Solaris threads library. This
13722 option sets flags for both the preprocessor and linker. This option does
13723 not affect the thread safety of object code produced by the compiler or
13724 that of libraries supplied with it.
13728 Add support for multithreading using the POSIX threads library. This
13729 option sets flags for both the preprocessor and linker. This option does
13730 not affect the thread safety of object code produced by the compiler or
13731 that of libraries supplied with it.
13735 This is a synonym for @option{-pthreads}.
13739 @subsection SPU Options
13740 @cindex SPU options
13742 These @samp{-m} options are supported on the SPU:
13746 @itemx -merror-reloc
13747 @opindex mwarn-reloc
13748 @opindex merror-reloc
13750 The loader for SPU does not handle dynamic relocations. By default, GCC
13751 will give an error when it generates code that requires a dynamic
13752 relocation. @option{-mno-error-reloc} disables the error,
13753 @option{-mwarn-reloc} will generate a warning instead.
13756 @itemx -munsafe-dma
13758 @opindex munsafe-dma
13760 Instructions which initiate or test completion of DMA must not be
13761 reordered with respect to loads and stores of the memory which is being
13762 accessed. Users typically address this problem using the volatile
13763 keyword, but that can lead to inefficient code in places where the
13764 memory is known to not change. Rather than mark the memory as volatile
13765 we treat the DMA instructions as potentially effecting all memory. With
13766 @option{-munsafe-dma} users must use the volatile keyword to protect
13769 @item -mbranch-hints
13770 @opindex mbranch-hints
13772 By default, GCC will generate a branch hint instruction to avoid
13773 pipeline stalls for always taken or probably taken branches. A hint
13774 will not be generated closer than 8 instructions away from its branch.
13775 There is little reason to disable them, except for debugging purposes,
13776 or to make an object a little bit smaller.
13780 @opindex msmall-mem
13781 @opindex mlarge-mem
13783 By default, GCC generates code assuming that addresses are never larger
13784 than 18 bits. With @option{-mlarge-mem} code is generated that assumes
13785 a full 32 bit address.
13790 By default, GCC links against startup code that assumes the SPU-style
13791 main function interface (which has an unconventional parameter list).
13792 With @option{-mstdmain}, GCC will link your program against startup
13793 code that assumes a C99-style interface to @code{main}, including a
13794 local copy of @code{argv} strings.
13796 @item -mfixed-range=@var{register-range}
13797 @opindex mfixed-range
13798 Generate code treating the given register range as fixed registers.
13799 A fixed register is one that the register allocator can not use. This is
13800 useful when compiling kernel code. A register range is specified as
13801 two registers separated by a dash. Multiple register ranges can be
13802 specified separated by a comma.
13806 @node System V Options
13807 @subsection Options for System V
13809 These additional options are available on System V Release 4 for
13810 compatibility with other compilers on those systems:
13815 Create a shared object.
13816 It is recommended that @option{-symbolic} or @option{-shared} be used instead.
13820 Identify the versions of each tool used by the compiler, in a
13821 @code{.ident} assembler directive in the output.
13825 Refrain from adding @code{.ident} directives to the output file (this is
13828 @item -YP,@var{dirs}
13830 Search the directories @var{dirs}, and no others, for libraries
13831 specified with @option{-l}.
13833 @item -Ym,@var{dir}
13835 Look in the directory @var{dir} to find the M4 preprocessor.
13836 The assembler uses this option.
13837 @c This is supposed to go with a -Yd for predefined M4 macro files, but
13838 @c the generic assembler that comes with Solaris takes just -Ym.
13841 @node TMS320C3x/C4x Options
13842 @subsection TMS320C3x/C4x Options
13843 @cindex TMS320C3x/C4x Options
13845 These @samp{-m} options are defined for TMS320C3x/C4x implementations:
13849 @item -mcpu=@var{cpu_type}
13851 Set the instruction set, register set, and instruction scheduling
13852 parameters for machine type @var{cpu_type}. Supported values for
13853 @var{cpu_type} are @samp{c30}, @samp{c31}, @samp{c32}, @samp{c40}, and
13854 @samp{c44}. The default is @samp{c40} to generate code for the
13859 @itemx -msmall-memory
13861 @opindex mbig-memory
13863 @opindex msmall-memory
13865 Generates code for the big or small memory model. The small memory
13866 model assumed that all data fits into one 64K word page. At run-time
13867 the data page (DP) register must be set to point to the 64K page
13868 containing the .bss and .data program sections. The big memory model is
13869 the default and requires reloading of the DP register for every direct
13876 Allow (disallow) allocation of general integer operands into the block
13877 count register BK@.
13883 Enable (disable) generation of code using decrement and branch,
13884 DBcond(D), instructions. This is enabled by default for the C4x. To be
13885 on the safe side, this is disabled for the C3x, since the maximum
13886 iteration count on the C3x is @math{2^{23} + 1} (but who iterates loops more than
13887 @math{2^{23}} times on the C3x?). Note that GCC will try to reverse a loop so
13888 that it can utilize the decrement and branch instruction, but will give
13889 up if there is more than one memory reference in the loop. Thus a loop
13890 where the loop counter is decremented can generate slightly more
13891 efficient code, in cases where the RPTB instruction cannot be utilized.
13893 @item -mdp-isr-reload
13895 @opindex mdp-isr-reload
13897 Force the DP register to be saved on entry to an interrupt service
13898 routine (ISR), reloaded to point to the data section, and restored on
13899 exit from the ISR@. This should not be required unless someone has
13900 violated the small memory model by modifying the DP register, say within
13907 For the C3x use the 24-bit MPYI instruction for integer multiplies
13908 instead of a library call to guarantee 32-bit results. Note that if one
13909 of the operands is a constant, then the multiplication will be performed
13910 using shifts and adds. If the @option{-mmpyi} option is not specified for the C3x,
13911 then squaring operations are performed inline instead of a library call.
13914 @itemx -mno-fast-fix
13916 @opindex mno-fast-fix
13917 The C3x/C4x FIX instruction to convert a floating point value to an
13918 integer value chooses the nearest integer less than or equal to the
13919 floating point value rather than to the nearest integer. Thus if the
13920 floating point number is negative, the result will be incorrectly
13921 truncated an additional code is necessary to detect and correct this
13922 case. This option can be used to disable generation of the additional
13923 code required to correct the result.
13929 Enable (disable) generation of repeat block sequences using the RPTB
13930 instruction for zero overhead looping. The RPTB construct is only used
13931 for innermost loops that do not call functions or jump across the loop
13932 boundaries. There is no advantage having nested RPTB loops due to the
13933 overhead required to save and restore the RC, RS, and RE registers.
13934 This is enabled by default with @option{-O2}.
13936 @item -mrpts=@var{count}
13940 Enable (disable) the use of the single instruction repeat instruction
13941 RPTS@. If a repeat block contains a single instruction, and the loop
13942 count can be guaranteed to be less than the value @var{count}, GCC will
13943 emit a RPTS instruction instead of a RPTB@. If no value is specified,
13944 then a RPTS will be emitted even if the loop count cannot be determined
13945 at compile time. Note that the repeated instruction following RPTS does
13946 not have to be reloaded from memory each iteration, thus freeing up the
13947 CPU buses for operands. However, since interrupts are blocked by this
13948 instruction, it is disabled by default.
13950 @item -mloop-unsigned
13951 @itemx -mno-loop-unsigned
13952 @opindex mloop-unsigned
13953 @opindex mno-loop-unsigned
13954 The maximum iteration count when using RPTS and RPTB (and DB on the C40)
13955 is @math{2^{31} + 1} since these instructions test if the iteration count is
13956 negative to terminate the loop. If the iteration count is unsigned
13957 there is a possibility than the @math{2^{31} + 1} maximum iteration count may be
13958 exceeded. This switch allows an unsigned iteration count.
13962 Try to emit an assembler syntax that the TI assembler (asm30) is happy
13963 with. This also enforces compatibility with the API employed by the TI
13964 C3x C compiler. For example, long doubles are passed as structures
13965 rather than in floating point registers.
13971 Generate code that uses registers (stack) for passing arguments to functions.
13972 By default, arguments are passed in registers where possible rather
13973 than by pushing arguments on to the stack.
13975 @item -mparallel-insns
13976 @itemx -mno-parallel-insns
13977 @opindex mparallel-insns
13978 @opindex mno-parallel-insns
13979 Allow the generation of parallel instructions. This is enabled by
13980 default with @option{-O2}.
13982 @item -mparallel-mpy
13983 @itemx -mno-parallel-mpy
13984 @opindex mparallel-mpy
13985 @opindex mno-parallel-mpy
13986 Allow the generation of MPY||ADD and MPY||SUB parallel instructions,
13987 provided @option{-mparallel-insns} is also specified. These instructions have
13988 tight register constraints which can pessimize the code generation
13989 of large functions.
13994 @subsection V850 Options
13995 @cindex V850 Options
13997 These @samp{-m} options are defined for V850 implementations:
14001 @itemx -mno-long-calls
14002 @opindex mlong-calls
14003 @opindex mno-long-calls
14004 Treat all calls as being far away (near). If calls are assumed to be
14005 far away, the compiler will always load the functions address up into a
14006 register, and call indirect through the pointer.
14012 Do not optimize (do optimize) basic blocks that use the same index
14013 pointer 4 or more times to copy pointer into the @code{ep} register, and
14014 use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
14015 option is on by default if you optimize.
14017 @item -mno-prolog-function
14018 @itemx -mprolog-function
14019 @opindex mno-prolog-function
14020 @opindex mprolog-function
14021 Do not use (do use) external functions to save and restore registers
14022 at the prologue and epilogue of a function. The external functions
14023 are slower, but use less code space if more than one function saves
14024 the same number of registers. The @option{-mprolog-function} option
14025 is on by default if you optimize.
14029 Try to make the code as small as possible. At present, this just turns
14030 on the @option{-mep} and @option{-mprolog-function} options.
14032 @item -mtda=@var{n}
14034 Put static or global variables whose size is @var{n} bytes or less into
14035 the tiny data area that register @code{ep} points to. The tiny data
14036 area can hold up to 256 bytes in total (128 bytes for byte references).
14038 @item -msda=@var{n}
14040 Put static or global variables whose size is @var{n} bytes or less into
14041 the small data area that register @code{gp} points to. The small data
14042 area can hold up to 64 kilobytes.
14044 @item -mzda=@var{n}
14046 Put static or global variables whose size is @var{n} bytes or less into
14047 the first 32 kilobytes of memory.
14051 Specify that the target processor is the V850.
14054 @opindex mbig-switch
14055 Generate code suitable for big switch tables. Use this option only if
14056 the assembler/linker complain about out of range branches within a switch
14061 This option will cause r2 and r5 to be used in the code generated by
14062 the compiler. This setting is the default.
14064 @item -mno-app-regs
14065 @opindex mno-app-regs
14066 This option will cause r2 and r5 to be treated as fixed registers.
14070 Specify that the target processor is the V850E1. The preprocessor
14071 constants @samp{__v850e1__} and @samp{__v850e__} will be defined if
14072 this option is used.
14076 Specify that the target processor is the V850E@. The preprocessor
14077 constant @samp{__v850e__} will be defined if this option is used.
14079 If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
14080 are defined then a default target processor will be chosen and the
14081 relevant @samp{__v850*__} preprocessor constant will be defined.
14083 The preprocessor constants @samp{__v850} and @samp{__v851__} are always
14084 defined, regardless of which processor variant is the target.
14086 @item -mdisable-callt
14087 @opindex mdisable-callt
14088 This option will suppress generation of the CALLT instruction for the
14089 v850e and v850e1 flavors of the v850 architecture. The default is
14090 @option{-mno-disable-callt} which allows the CALLT instruction to be used.
14095 @subsection VAX Options
14096 @cindex VAX options
14098 These @samp{-m} options are defined for the VAX:
14103 Do not output certain jump instructions (@code{aobleq} and so on)
14104 that the Unix assembler for the VAX cannot handle across long
14109 Do output those jump instructions, on the assumption that you
14110 will assemble with the GNU assembler.
14114 Output code for g-format floating point numbers instead of d-format.
14117 @node VxWorks Options
14118 @subsection VxWorks Options
14119 @cindex VxWorks Options
14121 The options in this section are defined for all VxWorks targets.
14122 Options specific to the target hardware are listed with the other
14123 options for that target.
14128 GCC can generate code for both VxWorks kernels and real time processes
14129 (RTPs). This option switches from the former to the latter. It also
14130 defines the preprocessor macro @code{__RTP__}.
14133 @opindex non-static
14134 Link an RTP executable against shared libraries rather than static
14135 libraries. The options @option{-static} and @option{-shared} can
14136 also be used for RTPs (@pxref{Link Options}); @option{-static}
14143 These options are passed down to the linker. They are defined for
14144 compatibility with Diab.
14147 @opindex Xbind-lazy
14148 Enable lazy binding of function calls. This option is equivalent to
14149 @option{-Wl,-z,now} and is defined for compatibility with Diab.
14153 Disable lazy binding of function calls. This option is the default and
14154 is defined for compatibility with Diab.
14157 @node x86-64 Options
14158 @subsection x86-64 Options
14159 @cindex x86-64 options
14161 These are listed under @xref{i386 and x86-64 Options}.
14163 @node Xstormy16 Options
14164 @subsection Xstormy16 Options
14165 @cindex Xstormy16 Options
14167 These options are defined for Xstormy16:
14172 Choose startup files and linker script suitable for the simulator.
14175 @node Xtensa Options
14176 @subsection Xtensa Options
14177 @cindex Xtensa Options
14179 These options are supported for Xtensa targets:
14183 @itemx -mno-const16
14185 @opindex mno-const16
14186 Enable or disable use of @code{CONST16} instructions for loading
14187 constant values. The @code{CONST16} instruction is currently not a
14188 standard option from Tensilica. When enabled, @code{CONST16}
14189 instructions are always used in place of the standard @code{L32R}
14190 instructions. The use of @code{CONST16} is enabled by default only if
14191 the @code{L32R} instruction is not available.
14194 @itemx -mno-fused-madd
14195 @opindex mfused-madd
14196 @opindex mno-fused-madd
14197 Enable or disable use of fused multiply/add and multiply/subtract
14198 instructions in the floating-point option. This has no effect if the
14199 floating-point option is not also enabled. Disabling fused multiply/add
14200 and multiply/subtract instructions forces the compiler to use separate
14201 instructions for the multiply and add/subtract operations. This may be
14202 desirable in some cases where strict IEEE 754-compliant results are
14203 required: the fused multiply add/subtract instructions do not round the
14204 intermediate result, thereby producing results with @emph{more} bits of
14205 precision than specified by the IEEE standard. Disabling fused multiply
14206 add/subtract instructions also ensures that the program output is not
14207 sensitive to the compiler's ability to combine multiply and add/subtract
14210 @item -mtext-section-literals
14211 @itemx -mno-text-section-literals
14212 @opindex mtext-section-literals
14213 @opindex mno-text-section-literals
14214 Control the treatment of literal pools. The default is
14215 @option{-mno-text-section-literals}, which places literals in a separate
14216 section in the output file. This allows the literal pool to be placed
14217 in a data RAM/ROM, and it also allows the linker to combine literal
14218 pools from separate object files to remove redundant literals and
14219 improve code size. With @option{-mtext-section-literals}, the literals
14220 are interspersed in the text section in order to keep them as close as
14221 possible to their references. This may be necessary for large assembly
14224 @item -mtarget-align
14225 @itemx -mno-target-align
14226 @opindex mtarget-align
14227 @opindex mno-target-align
14228 When this option is enabled, GCC instructs the assembler to
14229 automatically align instructions to reduce branch penalties at the
14230 expense of some code density. The assembler attempts to widen density
14231 instructions to align branch targets and the instructions following call
14232 instructions. If there are not enough preceding safe density
14233 instructions to align a target, no widening will be performed. The
14234 default is @option{-mtarget-align}. These options do not affect the
14235 treatment of auto-aligned instructions like @code{LOOP}, which the
14236 assembler will always align, either by widening density instructions or
14237 by inserting no-op instructions.
14240 @itemx -mno-longcalls
14241 @opindex mlongcalls
14242 @opindex mno-longcalls
14243 When this option is enabled, GCC instructs the assembler to translate
14244 direct calls to indirect calls unless it can determine that the target
14245 of a direct call is in the range allowed by the call instruction. This
14246 translation typically occurs for calls to functions in other source
14247 files. Specifically, the assembler translates a direct @code{CALL}
14248 instruction into an @code{L32R} followed by a @code{CALLX} instruction.
14249 The default is @option{-mno-longcalls}. This option should be used in
14250 programs where the call target can potentially be out of range. This
14251 option is implemented in the assembler, not the compiler, so the
14252 assembly code generated by GCC will still show direct call
14253 instructions---look at the disassembled object code to see the actual
14254 instructions. Note that the assembler will use an indirect call for
14255 every cross-file call, not just those that really will be out of range.
14258 @node zSeries Options
14259 @subsection zSeries Options
14260 @cindex zSeries options
14262 These are listed under @xref{S/390 and zSeries Options}.
14264 @node Code Gen Options
14265 @section Options for Code Generation Conventions
14266 @cindex code generation conventions
14267 @cindex options, code generation
14268 @cindex run-time options
14270 These machine-independent options control the interface conventions
14271 used in code generation.
14273 Most of them have both positive and negative forms; the negative form
14274 of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
14275 one of the forms is listed---the one which is not the default. You
14276 can figure out the other form by either removing @samp{no-} or adding
14280 @item -fbounds-check
14281 @opindex fbounds-check
14282 For front-ends that support it, generate additional code to check that
14283 indices used to access arrays are within the declared range. This is
14284 currently only supported by the Java and Fortran front-ends, where
14285 this option defaults to true and false respectively.
14289 This option generates traps for signed overflow on addition, subtraction,
14290 multiplication operations.
14294 This option instructs the compiler to assume that signed arithmetic
14295 overflow of addition, subtraction and multiplication wraps around
14296 using twos-complement representation. This flag enables some optimizations
14297 and disables others. This option is enabled by default for the Java
14298 front-end, as required by the Java language specification.
14301 @opindex fexceptions
14302 Enable exception handling. Generates extra code needed to propagate
14303 exceptions. For some targets, this implies GCC will generate frame
14304 unwind information for all functions, which can produce significant data
14305 size overhead, although it does not affect execution. If you do not
14306 specify this option, GCC will enable it by default for languages like
14307 C++ which normally require exception handling, and disable it for
14308 languages like C that do not normally require it. However, you may need
14309 to enable this option when compiling C code that needs to interoperate
14310 properly with exception handlers written in C++. You may also wish to
14311 disable this option if you are compiling older C++ programs that don't
14312 use exception handling.
14314 @item -fnon-call-exceptions
14315 @opindex fnon-call-exceptions
14316 Generate code that allows trapping instructions to throw exceptions.
14317 Note that this requires platform-specific runtime support that does
14318 not exist everywhere. Moreover, it only allows @emph{trapping}
14319 instructions to throw exceptions, i.e.@: memory references or floating
14320 point instructions. It does not allow exceptions to be thrown from
14321 arbitrary signal handlers such as @code{SIGALRM}.
14323 @item -funwind-tables
14324 @opindex funwind-tables
14325 Similar to @option{-fexceptions}, except that it will just generate any needed
14326 static data, but will not affect the generated code in any other way.
14327 You will normally not enable this option; instead, a language processor
14328 that needs this handling would enable it on your behalf.
14330 @item -fasynchronous-unwind-tables
14331 @opindex fasynchronous-unwind-tables
14332 Generate unwind table in dwarf2 format, if supported by target machine. The
14333 table is exact at each instruction boundary, so it can be used for stack
14334 unwinding from asynchronous events (such as debugger or garbage collector).
14336 @item -fpcc-struct-return
14337 @opindex fpcc-struct-return
14338 Return ``short'' @code{struct} and @code{union} values in memory like
14339 longer ones, rather than in registers. This convention is less
14340 efficient, but it has the advantage of allowing intercallability between
14341 GCC-compiled files and files compiled with other compilers, particularly
14342 the Portable C Compiler (pcc).
14344 The precise convention for returning structures in memory depends
14345 on the target configuration macros.
14347 Short structures and unions are those whose size and alignment match
14348 that of some integer type.
14350 @strong{Warning:} code compiled with the @option{-fpcc-struct-return}
14351 switch is not binary compatible with code compiled with the
14352 @option{-freg-struct-return} switch.
14353 Use it to conform to a non-default application binary interface.
14355 @item -freg-struct-return
14356 @opindex freg-struct-return
14357 Return @code{struct} and @code{union} values in registers when possible.
14358 This is more efficient for small structures than
14359 @option{-fpcc-struct-return}.
14361 If you specify neither @option{-fpcc-struct-return} nor
14362 @option{-freg-struct-return}, GCC defaults to whichever convention is
14363 standard for the target. If there is no standard convention, GCC
14364 defaults to @option{-fpcc-struct-return}, except on targets where GCC is
14365 the principal compiler. In those cases, we can choose the standard, and
14366 we chose the more efficient register return alternative.
14368 @strong{Warning:} code compiled with the @option{-freg-struct-return}
14369 switch is not binary compatible with code compiled with the
14370 @option{-fpcc-struct-return} switch.
14371 Use it to conform to a non-default application binary interface.
14373 @item -fshort-enums
14374 @opindex fshort-enums
14375 Allocate to an @code{enum} type only as many bytes as it needs for the
14376 declared range of possible values. Specifically, the @code{enum} type
14377 will be equivalent to the smallest integer type which has enough room.
14379 @strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
14380 code that is not binary compatible with code generated without that switch.
14381 Use it to conform to a non-default application binary interface.
14383 @item -fshort-double
14384 @opindex fshort-double
14385 Use the same size for @code{double} as for @code{float}.
14387 @strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
14388 code that is not binary compatible with code generated without that switch.
14389 Use it to conform to a non-default application binary interface.
14391 @item -fshort-wchar
14392 @opindex fshort-wchar
14393 Override the underlying type for @samp{wchar_t} to be @samp{short
14394 unsigned int} instead of the default for the target. This option is
14395 useful for building programs to run under WINE@.
14397 @strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
14398 code that is not binary compatible with code generated without that switch.
14399 Use it to conform to a non-default application binary interface.
14402 @opindex fno-common
14403 In C, allocate even uninitialized global variables in the data section of the
14404 object file, rather than generating them as common blocks. This has the
14405 effect that if the same variable is declared (without @code{extern}) in
14406 two different compilations, you will get an error when you link them.
14407 The only reason this might be useful is if you wish to verify that the
14408 program will work on other systems which always work this way.
14412 Ignore the @samp{#ident} directive.
14414 @item -finhibit-size-directive
14415 @opindex finhibit-size-directive
14416 Don't output a @code{.size} assembler directive, or anything else that
14417 would cause trouble if the function is split in the middle, and the
14418 two halves are placed at locations far apart in memory. This option is
14419 used when compiling @file{crtstuff.c}; you should not need to use it
14422 @item -fverbose-asm
14423 @opindex fverbose-asm
14424 Put extra commentary information in the generated assembly code to
14425 make it more readable. This option is generally only of use to those
14426 who actually need to read the generated assembly code (perhaps while
14427 debugging the compiler itself).
14429 @option{-fno-verbose-asm}, the default, causes the
14430 extra information to be omitted and is useful when comparing two assembler
14433 @item -frecord-gcc-switches
14434 @opindex frecord-gcc-switches
14435 This switch causes the command line that was used to invoke the
14436 compiler to be recorded into the object file that is being created.
14437 This switch is only implemented on some targets and the exact format
14438 of the recording is target and binary file format dependent, but it
14439 usually takes the form of a section containing ASCII text. This
14440 switch is related to the @option{-fverbose-asm} switch, but that
14441 switch only records information in the assembler output file as
14442 comments, so it never reaches the object file.
14446 @cindex global offset table
14448 Generate position-independent code (PIC) suitable for use in a shared
14449 library, if supported for the target machine. Such code accesses all
14450 constant addresses through a global offset table (GOT)@. The dynamic
14451 loader resolves the GOT entries when the program starts (the dynamic
14452 loader is not part of GCC; it is part of the operating system). If
14453 the GOT size for the linked executable exceeds a machine-specific
14454 maximum size, you get an error message from the linker indicating that
14455 @option{-fpic} does not work; in that case, recompile with @option{-fPIC}
14456 instead. (These maximums are 8k on the SPARC and 32k
14457 on the m68k and RS/6000. The 386 has no such limit.)
14459 Position-independent code requires special support, and therefore works
14460 only on certain machines. For the 386, GCC supports PIC for System V
14461 but not for the Sun 386i. Code generated for the IBM RS/6000 is always
14462 position-independent.
14464 When this flag is set, the macros @code{__pic__} and @code{__PIC__}
14469 If supported for the target machine, emit position-independent code,
14470 suitable for dynamic linking and avoiding any limit on the size of the
14471 global offset table. This option makes a difference on the m68k,
14472 PowerPC and SPARC@.
14474 Position-independent code requires special support, and therefore works
14475 only on certain machines.
14477 When this flag is set, the macros @code{__pic__} and @code{__PIC__}
14484 These options are similar to @option{-fpic} and @option{-fPIC}, but
14485 generated position independent code can be only linked into executables.
14486 Usually these options are used when @option{-pie} GCC option will be
14487 used during linking.
14489 @option{-fpie} and @option{-fPIE} both define the macros
14490 @code{__pie__} and @code{__PIE__}. The macros have the value 1
14491 for @option{-fpie} and 2 for @option{-fPIE}.
14493 @item -fno-jump-tables
14494 @opindex fno-jump-tables
14495 Do not use jump tables for switch statements even where it would be
14496 more efficient than other code generation strategies. This option is
14497 of use in conjunction with @option{-fpic} or @option{-fPIC} for
14498 building code which forms part of a dynamic linker and cannot
14499 reference the address of a jump table. On some targets, jump tables
14500 do not require a GOT and this option is not needed.
14502 @item -ffixed-@var{reg}
14504 Treat the register named @var{reg} as a fixed register; generated code
14505 should never refer to it (except perhaps as a stack pointer, frame
14506 pointer or in some other fixed role).
14508 @var{reg} must be the name of a register. The register names accepted
14509 are machine-specific and are defined in the @code{REGISTER_NAMES}
14510 macro in the machine description macro file.
14512 This flag does not have a negative form, because it specifies a
14515 @item -fcall-used-@var{reg}
14516 @opindex fcall-used
14517 Treat the register named @var{reg} as an allocable register that is
14518 clobbered by function calls. It may be allocated for temporaries or
14519 variables that do not live across a call. Functions compiled this way
14520 will not save and restore the register @var{reg}.
14522 It is an error to used this flag with the frame pointer or stack pointer.
14523 Use of this flag for other registers that have fixed pervasive roles in
14524 the machine's execution model will produce disastrous results.
14526 This flag does not have a negative form, because it specifies a
14529 @item -fcall-saved-@var{reg}
14530 @opindex fcall-saved
14531 Treat the register named @var{reg} as an allocable register saved by
14532 functions. It may be allocated even for temporaries or variables that
14533 live across a call. Functions compiled this way will save and restore
14534 the register @var{reg} if they use it.
14536 It is an error to used this flag with the frame pointer or stack pointer.
14537 Use of this flag for other registers that have fixed pervasive roles in
14538 the machine's execution model will produce disastrous results.
14540 A different sort of disaster will result from the use of this flag for
14541 a register in which function values may be returned.
14543 This flag does not have a negative form, because it specifies a
14546 @item -fpack-struct[=@var{n}]
14547 @opindex fpack-struct
14548 Without a value specified, pack all structure members together without
14549 holes. When a value is specified (which must be a small power of two), pack
14550 structure members according to this value, representing the maximum
14551 alignment (that is, objects with default alignment requirements larger than
14552 this will be output potentially unaligned at the next fitting location.
14554 @strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
14555 code that is not binary compatible with code generated without that switch.
14556 Additionally, it makes the code suboptimal.
14557 Use it to conform to a non-default application binary interface.
14559 @item -finstrument-functions
14560 @opindex finstrument-functions
14561 Generate instrumentation calls for entry and exit to functions. Just
14562 after function entry and just before function exit, the following
14563 profiling functions will be called with the address of the current
14564 function and its call site. (On some platforms,
14565 @code{__builtin_return_address} does not work beyond the current
14566 function, so the call site information may not be available to the
14567 profiling functions otherwise.)
14570 void __cyg_profile_func_enter (void *this_fn,
14572 void __cyg_profile_func_exit (void *this_fn,
14576 The first argument is the address of the start of the current function,
14577 which may be looked up exactly in the symbol table.
14579 This instrumentation is also done for functions expanded inline in other
14580 functions. The profiling calls will indicate where, conceptually, the
14581 inline function is entered and exited. This means that addressable
14582 versions of such functions must be available. If all your uses of a
14583 function are expanded inline, this may mean an additional expansion of
14584 code size. If you use @samp{extern inline} in your C code, an
14585 addressable version of such functions must be provided. (This is
14586 normally the case anyways, but if you get lucky and the optimizer always
14587 expands the functions inline, you might have gotten away without
14588 providing static copies.)
14590 A function may be given the attribute @code{no_instrument_function}, in
14591 which case this instrumentation will not be done. This can be used, for
14592 example, for the profiling functions listed above, high-priority
14593 interrupt routines, and any functions from which the profiling functions
14594 cannot safely be called (perhaps signal handlers, if the profiling
14595 routines generate output or allocate memory).
14597 @item -fstack-check
14598 @opindex fstack-check
14599 Generate code to verify that you do not go beyond the boundary of the
14600 stack. You should specify this flag if you are running in an
14601 environment with multiple threads, but only rarely need to specify it in
14602 a single-threaded environment since stack overflow is automatically
14603 detected on nearly all systems if there is only one stack.
14605 Note that this switch does not actually cause checking to be done; the
14606 operating system must do that. The switch causes generation of code
14607 to ensure that the operating system sees the stack being extended.
14609 @item -fstack-limit-register=@var{reg}
14610 @itemx -fstack-limit-symbol=@var{sym}
14611 @itemx -fno-stack-limit
14612 @opindex fstack-limit-register
14613 @opindex fstack-limit-symbol
14614 @opindex fno-stack-limit
14615 Generate code to ensure that the stack does not grow beyond a certain value,
14616 either the value of a register or the address of a symbol. If the stack
14617 would grow beyond the value, a signal is raised. For most targets,
14618 the signal is raised before the stack overruns the boundary, so
14619 it is possible to catch the signal without taking special precautions.
14621 For instance, if the stack starts at absolute address @samp{0x80000000}
14622 and grows downwards, you can use the flags
14623 @option{-fstack-limit-symbol=__stack_limit} and
14624 @option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
14625 of 128KB@. Note that this may only work with the GNU linker.
14627 @cindex aliasing of parameters
14628 @cindex parameters, aliased
14629 @item -fargument-alias
14630 @itemx -fargument-noalias
14631 @itemx -fargument-noalias-global
14632 @itemx -fargument-noalias-anything
14633 @opindex fargument-alias
14634 @opindex fargument-noalias
14635 @opindex fargument-noalias-global
14636 @opindex fargument-noalias-anything
14637 Specify the possible relationships among parameters and between
14638 parameters and global data.
14640 @option{-fargument-alias} specifies that arguments (parameters) may
14641 alias each other and may alias global storage.@*
14642 @option{-fargument-noalias} specifies that arguments do not alias
14643 each other, but may alias global storage.@*
14644 @option{-fargument-noalias-global} specifies that arguments do not
14645 alias each other and do not alias global storage.
14646 @option{-fargument-noalias-anything} specifies that arguments do not
14647 alias any other storage.
14649 Each language will automatically use whatever option is required by
14650 the language standard. You should not need to use these options yourself.
14652 @item -fleading-underscore
14653 @opindex fleading-underscore
14654 This option and its counterpart, @option{-fno-leading-underscore}, forcibly
14655 change the way C symbols are represented in the object file. One use
14656 is to help link with legacy assembly code.
14658 @strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
14659 generate code that is not binary compatible with code generated without that
14660 switch. Use it to conform to a non-default application binary interface.
14661 Not all targets provide complete support for this switch.
14663 @item -ftls-model=@var{model}
14664 Alter the thread-local storage model to be used (@pxref{Thread-Local}).
14665 The @var{model} argument should be one of @code{global-dynamic},
14666 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
14668 The default without @option{-fpic} is @code{initial-exec}; with
14669 @option{-fpic} the default is @code{global-dynamic}.
14671 @item -fvisibility=@var{default|internal|hidden|protected}
14672 @opindex fvisibility
14673 Set the default ELF image symbol visibility to the specified option---all
14674 symbols will be marked with this unless overridden within the code.
14675 Using this feature can very substantially improve linking and
14676 load times of shared object libraries, produce more optimized
14677 code, provide near-perfect API export and prevent symbol clashes.
14678 It is @strong{strongly} recommended that you use this in any shared objects
14681 Despite the nomenclature, @code{default} always means public ie;
14682 available to be linked against from outside the shared object.
14683 @code{protected} and @code{internal} are pretty useless in real-world
14684 usage so the only other commonly used option will be @code{hidden}.
14685 The default if @option{-fvisibility} isn't specified is
14686 @code{default}, i.e., make every
14687 symbol public---this causes the same behavior as previous versions of
14690 A good explanation of the benefits offered by ensuring ELF
14691 symbols have the correct visibility is given by ``How To Write
14692 Shared Libraries'' by Ulrich Drepper (which can be found at
14693 @w{@uref{http://people.redhat.com/~drepper/}})---however a superior
14694 solution made possible by this option to marking things hidden when
14695 the default is public is to make the default hidden and mark things
14696 public. This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
14697 and @code{__attribute__ ((visibility("default")))} instead of
14698 @code{__declspec(dllexport)} you get almost identical semantics with
14699 identical syntax. This is a great boon to those working with
14700 cross-platform projects.
14702 For those adding visibility support to existing code, you may find
14703 @samp{#pragma GCC visibility} of use. This works by you enclosing
14704 the declarations you wish to set visibility for with (for example)
14705 @samp{#pragma GCC visibility push(hidden)} and
14706 @samp{#pragma GCC visibility pop}.
14707 Bear in mind that symbol visibility should be viewed @strong{as
14708 part of the API interface contract} and thus all new code should
14709 always specify visibility when it is not the default ie; declarations
14710 only for use within the local DSO should @strong{always} be marked explicitly
14711 as hidden as so to avoid PLT indirection overheads---making this
14712 abundantly clear also aids readability and self-documentation of the code.
14713 Note that due to ISO C++ specification requirements, operator new and
14714 operator delete must always be of default visibility.
14716 Be aware that headers from outside your project, in particular system
14717 headers and headers from any other library you use, may not be
14718 expecting to be compiled with visibility other than the default. You
14719 may need to explicitly say @samp{#pragma GCC visibility push(default)}
14720 before including any such headers.
14722 @samp{extern} declarations are not affected by @samp{-fvisibility}, so
14723 a lot of code can be recompiled with @samp{-fvisibility=hidden} with
14724 no modifications. However, this means that calls to @samp{extern}
14725 functions with no explicit visibility will use the PLT, so it is more
14726 effective to use @samp{__attribute ((visibility))} and/or
14727 @samp{#pragma GCC visibility} to tell the compiler which @samp{extern}
14728 declarations should be treated as hidden.
14730 Note that @samp{-fvisibility} does affect C++ vague linkage
14731 entities. This means that, for instance, an exception class that will
14732 be thrown between DSOs must be explicitly marked with default
14733 visibility so that the @samp{type_info} nodes will be unified between
14736 An overview of these techniques, their benefits and how to use them
14737 is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
14743 @node Environment Variables
14744 @section Environment Variables Affecting GCC
14745 @cindex environment variables
14747 @c man begin ENVIRONMENT
14748 This section describes several environment variables that affect how GCC
14749 operates. Some of them work by specifying directories or prefixes to use
14750 when searching for various kinds of files. Some are used to specify other
14751 aspects of the compilation environment.
14753 Note that you can also specify places to search using options such as
14754 @option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
14755 take precedence over places specified using environment variables, which
14756 in turn take precedence over those specified by the configuration of GCC@.
14757 @xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
14758 GNU Compiler Collection (GCC) Internals}.
14763 @c @itemx LC_COLLATE
14765 @c @itemx LC_MONETARY
14766 @c @itemx LC_NUMERIC
14771 @c @findex LC_COLLATE
14772 @findex LC_MESSAGES
14773 @c @findex LC_MONETARY
14774 @c @findex LC_NUMERIC
14778 These environment variables control the way that GCC uses
14779 localization information that allow GCC to work with different
14780 national conventions. GCC inspects the locale categories
14781 @env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
14782 so. These locale categories can be set to any value supported by your
14783 installation. A typical value is @samp{en_GB.UTF-8} for English in the United
14784 Kingdom encoded in UTF-8.
14786 The @env{LC_CTYPE} environment variable specifies character
14787 classification. GCC uses it to determine the character boundaries in
14788 a string; this is needed for some multibyte encodings that contain quote
14789 and escape characters that would otherwise be interpreted as a string
14792 The @env{LC_MESSAGES} environment variable specifies the language to
14793 use in diagnostic messages.
14795 If the @env{LC_ALL} environment variable is set, it overrides the value
14796 of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
14797 and @env{LC_MESSAGES} default to the value of the @env{LANG}
14798 environment variable. If none of these variables are set, GCC
14799 defaults to traditional C English behavior.
14803 If @env{TMPDIR} is set, it specifies the directory to use for temporary
14804 files. GCC uses temporary files to hold the output of one stage of
14805 compilation which is to be used as input to the next stage: for example,
14806 the output of the preprocessor, which is the input to the compiler
14809 @item GCC_EXEC_PREFIX
14810 @findex GCC_EXEC_PREFIX
14811 If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
14812 names of the subprograms executed by the compiler. No slash is added
14813 when this prefix is combined with the name of a subprogram, but you can
14814 specify a prefix that ends with a slash if you wish.
14816 If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
14817 an appropriate prefix to use based on the pathname it was invoked with.
14819 If GCC cannot find the subprogram using the specified prefix, it
14820 tries looking in the usual places for the subprogram.
14822 The default value of @env{GCC_EXEC_PREFIX} is
14823 @file{@var{prefix}/lib/gcc/} where @var{prefix} is the prefix to
14824 the installed compiler. In many cases @var{prefix} is the value
14825 of @code{prefix} when you ran the @file{configure} script.
14827 Other prefixes specified with @option{-B} take precedence over this prefix.
14829 This prefix is also used for finding files such as @file{crt0.o} that are
14832 In addition, the prefix is used in an unusual way in finding the
14833 directories to search for header files. For each of the standard
14834 directories whose name normally begins with @samp{/usr/local/lib/gcc}
14835 (more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
14836 replacing that beginning with the specified prefix to produce an
14837 alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
14838 @file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
14839 These alternate directories are searched first; the standard directories
14840 come next. If a standard directory begins with the configured
14841 @var{prefix} then the value of @var{prefix} is replaced by
14842 @env{GCC_EXEC_PREFIX} when looking for header files.
14844 @item COMPILER_PATH
14845 @findex COMPILER_PATH
14846 The value of @env{COMPILER_PATH} is a colon-separated list of
14847 directories, much like @env{PATH}. GCC tries the directories thus
14848 specified when searching for subprograms, if it can't find the
14849 subprograms using @env{GCC_EXEC_PREFIX}.
14852 @findex LIBRARY_PATH
14853 The value of @env{LIBRARY_PATH} is a colon-separated list of
14854 directories, much like @env{PATH}. When configured as a native compiler,
14855 GCC tries the directories thus specified when searching for special
14856 linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking
14857 using GCC also uses these directories when searching for ordinary
14858 libraries for the @option{-l} option (but directories specified with
14859 @option{-L} come first).
14863 @cindex locale definition
14864 This variable is used to pass locale information to the compiler. One way in
14865 which this information is used is to determine the character set to be used
14866 when character literals, string literals and comments are parsed in C and C++.
14867 When the compiler is configured to allow multibyte characters,
14868 the following values for @env{LANG} are recognized:
14872 Recognize JIS characters.
14874 Recognize SJIS characters.
14876 Recognize EUCJP characters.
14879 If @env{LANG} is not defined, or if it has some other value, then the
14880 compiler will use mblen and mbtowc as defined by the default locale to
14881 recognize and translate multibyte characters.
14885 Some additional environments variables affect the behavior of the
14888 @include cppenv.texi
14892 @node Precompiled Headers
14893 @section Using Precompiled Headers
14894 @cindex precompiled headers
14895 @cindex speed of compilation
14897 Often large projects have many header files that are included in every
14898 source file. The time the compiler takes to process these header files
14899 over and over again can account for nearly all of the time required to
14900 build the project. To make builds faster, GCC allows users to
14901 `precompile' a header file; then, if builds can use the precompiled
14902 header file they will be much faster.
14904 To create a precompiled header file, simply compile it as you would any
14905 other file, if necessary using the @option{-x} option to make the driver
14906 treat it as a C or C++ header file. You will probably want to use a
14907 tool like @command{make} to keep the precompiled header up-to-date when
14908 the headers it contains change.
14910 A precompiled header file will be searched for when @code{#include} is
14911 seen in the compilation. As it searches for the included file
14912 (@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
14913 compiler looks for a precompiled header in each directory just before it
14914 looks for the include file in that directory. The name searched for is
14915 the name specified in the @code{#include} with @samp{.gch} appended. If
14916 the precompiled header file can't be used, it is ignored.
14918 For instance, if you have @code{#include "all.h"}, and you have
14919 @file{all.h.gch} in the same directory as @file{all.h}, then the
14920 precompiled header file will be used if possible, and the original
14921 header will be used otherwise.
14923 Alternatively, you might decide to put the precompiled header file in a
14924 directory and use @option{-I} to ensure that directory is searched
14925 before (or instead of) the directory containing the original header.
14926 Then, if you want to check that the precompiled header file is always
14927 used, you can put a file of the same name as the original header in this
14928 directory containing an @code{#error} command.
14930 This also works with @option{-include}. So yet another way to use
14931 precompiled headers, good for projects not designed with precompiled
14932 header files in mind, is to simply take most of the header files used by
14933 a project, include them from another header file, precompile that header
14934 file, and @option{-include} the precompiled header. If the header files
14935 have guards against multiple inclusion, they will be skipped because
14936 they've already been included (in the precompiled header).
14938 If you need to precompile the same header file for different
14939 languages, targets, or compiler options, you can instead make a
14940 @emph{directory} named like @file{all.h.gch}, and put each precompiled
14941 header in the directory, perhaps using @option{-o}. It doesn't matter
14942 what you call the files in the directory, every precompiled header in
14943 the directory will be considered. The first precompiled header
14944 encountered in the directory that is valid for this compilation will
14945 be used; they're searched in no particular order.
14947 There are many other possibilities, limited only by your imagination,
14948 good sense, and the constraints of your build system.
14950 A precompiled header file can be used only when these conditions apply:
14954 Only one precompiled header can be used in a particular compilation.
14957 A precompiled header can't be used once the first C token is seen. You
14958 can have preprocessor directives before a precompiled header; you can
14959 even include a precompiled header from inside another header, so long as
14960 there are no C tokens before the @code{#include}.
14963 The precompiled header file must be produced for the same language as
14964 the current compilation. You can't use a C precompiled header for a C++
14968 The precompiled header file must have been produced by the same compiler
14969 binary as the current compilation is using.
14972 Any macros defined before the precompiled header is included must
14973 either be defined in the same way as when the precompiled header was
14974 generated, or must not affect the precompiled header, which usually
14975 means that they don't appear in the precompiled header at all.
14977 The @option{-D} option is one way to define a macro before a
14978 precompiled header is included; using a @code{#define} can also do it.
14979 There are also some options that define macros implicitly, like
14980 @option{-O} and @option{-Wdeprecated}; the same rule applies to macros
14983 @item If debugging information is output when using the precompiled
14984 header, using @option{-g} or similar, the same kind of debugging information
14985 must have been output when building the precompiled header. However,
14986 a precompiled header built using @option{-g} can be used in a compilation
14987 when no debugging information is being output.
14989 @item The same @option{-m} options must generally be used when building
14990 and using the precompiled header. @xref{Submodel Options},
14991 for any cases where this rule is relaxed.
14993 @item Each of the following options must be the same when building and using
14994 the precompiled header:
14996 @gccoptlist{-fexceptions -funit-at-a-time}
14999 Some other command-line options starting with @option{-f},
15000 @option{-p}, or @option{-O} must be defined in the same way as when
15001 the precompiled header was generated. At present, it's not clear
15002 which options are safe to change and which are not; the safest choice
15003 is to use exactly the same options when generating and using the
15004 precompiled header. The following are known to be safe:
15006 @gccoptlist{-fmessage-length= -fpreprocessed -fsched-interblock @gol
15007 -fsched-spec -fsched-spec-load -fsched-spec-load-dangerous @gol
15008 -fsched-verbose=<number> -fschedule-insns -fvisibility= @gol
15013 For all of these except the last, the compiler will automatically
15014 ignore the precompiled header if the conditions aren't met. If you
15015 find an option combination that doesn't work and doesn't cause the
15016 precompiled header to be ignored, please consider filing a bug report,
15019 If you do use differing options when generating and using the
15020 precompiled header, the actual behavior will be a mixture of the
15021 behavior for the options. For instance, if you use @option{-g} to
15022 generate the precompiled header but not when using it, you may or may
15023 not get debugging information for routines in the precompiled header.
15025 @node Running Protoize
15026 @section Running Protoize
15028 The program @code{protoize} is an optional part of GCC@. You can use
15029 it to add prototypes to a program, thus converting the program to ISO
15030 C in one respect. The companion program @code{unprotoize} does the
15031 reverse: it removes argument types from any prototypes that are found.
15033 When you run these programs, you must specify a set of source files as
15034 command line arguments. The conversion programs start out by compiling
15035 these files to see what functions they define. The information gathered
15036 about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
15038 After scanning comes actual conversion. The specified files are all
15039 eligible to be converted; any files they include (whether sources or
15040 just headers) are eligible as well.
15042 But not all the eligible files are converted. By default,
15043 @code{protoize} and @code{unprotoize} convert only source and header
15044 files in the current directory. You can specify additional directories
15045 whose files should be converted with the @option{-d @var{directory}}
15046 option. You can also specify particular files to exclude with the
15047 @option{-x @var{file}} option. A file is converted if it is eligible, its
15048 directory name matches one of the specified directory names, and its
15049 name within the directory has not been excluded.
15051 Basic conversion with @code{protoize} consists of rewriting most
15052 function definitions and function declarations to specify the types of
15053 the arguments. The only ones not rewritten are those for varargs
15056 @code{protoize} optionally inserts prototype declarations at the
15057 beginning of the source file, to make them available for any calls that
15058 precede the function's definition. Or it can insert prototype
15059 declarations with block scope in the blocks where undeclared functions
15062 Basic conversion with @code{unprotoize} consists of rewriting most
15063 function declarations to remove any argument types, and rewriting
15064 function definitions to the old-style pre-ISO form.
15066 Both conversion programs print a warning for any function declaration or
15067 definition that they can't convert. You can suppress these warnings
15070 The output from @code{protoize} or @code{unprotoize} replaces the
15071 original source file. The original file is renamed to a name ending
15072 with @samp{.save} (for DOS, the saved filename ends in @samp{.sav}
15073 without the original @samp{.c} suffix). If the @samp{.save} (@samp{.sav}
15074 for DOS) file already exists, then the source file is simply discarded.
15076 @code{protoize} and @code{unprotoize} both depend on GCC itself to
15077 scan the program and collect information about the functions it uses.
15078 So neither of these programs will work until GCC is installed.
15080 Here is a table of the options you can use with @code{protoize} and
15081 @code{unprotoize}. Each option works with both programs unless
15085 @item -B @var{directory}
15086 Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
15087 usual directory (normally @file{/usr/local/lib}). This file contains
15088 prototype information about standard system functions. This option
15089 applies only to @code{protoize}.
15091 @item -c @var{compilation-options}
15092 Use @var{compilation-options} as the options when running @command{gcc} to
15093 produce the @samp{.X} files. The special option @option{-aux-info} is
15094 always passed in addition, to tell @command{gcc} to write a @samp{.X} file.
15096 Note that the compilation options must be given as a single argument to
15097 @code{protoize} or @code{unprotoize}. If you want to specify several
15098 @command{gcc} options, you must quote the entire set of compilation options
15099 to make them a single word in the shell.
15101 There are certain @command{gcc} arguments that you cannot use, because they
15102 would produce the wrong kind of output. These include @option{-g},
15103 @option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in
15104 the @var{compilation-options}, they are ignored.
15107 Rename files to end in @samp{.C} (@samp{.cc} for DOS-based file
15108 systems) instead of @samp{.c}. This is convenient if you are converting
15109 a C program to C++. This option applies only to @code{protoize}.
15112 Add explicit global declarations. This means inserting explicit
15113 declarations at the beginning of each source file for each function
15114 that is called in the file and was not declared. These declarations
15115 precede the first function definition that contains a call to an
15116 undeclared function. This option applies only to @code{protoize}.
15118 @item -i @var{string}
15119 Indent old-style parameter declarations with the string @var{string}.
15120 This option applies only to @code{protoize}.
15122 @code{unprotoize} converts prototyped function definitions to old-style
15123 function definitions, where the arguments are declared between the
15124 argument list and the initial @samp{@{}. By default, @code{unprotoize}
15125 uses five spaces as the indentation. If you want to indent with just
15126 one space instead, use @option{-i " "}.
15129 Keep the @samp{.X} files. Normally, they are deleted after conversion
15133 Add explicit local declarations. @code{protoize} with @option{-l} inserts
15134 a prototype declaration for each function in each block which calls the
15135 function without any declaration. This option applies only to
15139 Make no real changes. This mode just prints information about the conversions
15140 that would have been done without @option{-n}.
15143 Make no @samp{.save} files. The original files are simply deleted.
15144 Use this option with caution.
15146 @item -p @var{program}
15147 Use the program @var{program} as the compiler. Normally, the name
15148 @file{gcc} is used.
15151 Work quietly. Most warnings are suppressed.
15154 Print the version number, just like @option{-v} for @command{gcc}.
15157 If you need special compiler options to compile one of your program's
15158 source files, then you should generate that file's @samp{.X} file
15159 specially, by running @command{gcc} on that source file with the
15160 appropriate options and the option @option{-aux-info}. Then run
15161 @code{protoize} on the entire set of files. @code{protoize} will use
15162 the existing @samp{.X} file because it is newer than the source file.
15166 gcc -Dfoo=bar file1.c -aux-info file1.X
15171 You need to include the special files along with the rest in the
15172 @code{protoize} command, even though their @samp{.X} files already
15173 exist, because otherwise they won't get converted.
15175 @xref{Protoize Caveats}, for more information on how to use
15176 @code{protoize} successfully.