1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2 @c 2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi.
8 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997,
9 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
11 Permission is granted to copy, distribute and/or modify this document
12 under the terms of the GNU Free Documentation License, Version 1.2 or
13 any later version published by the Free Software Foundation; with the
14 Invariant Sections being ``GNU General Public License'' and ``Funding
15 Free Software'', the Front-Cover texts being (a) (see below), and with
16 the Back-Cover Texts being (b) (see below). A copy of the license is
17 included in the gfdl(7) man page.
19 (a) The FSF's Front-Cover Text is:
23 (b) The FSF's Back-Cover Text is:
25 You have freedom to copy and modify this GNU Manual, like GNU
26 software. Copies published by the Free Software Foundation raise
27 funds for GNU development.
29 @c Set file name and title for the man page.
31 @settitle GNU project C and C++ compiler
33 gcc [@option{-c}|@option{-S}|@option{-E}] [@option{-std=}@var{standard}]
34 [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
35 [@option{-W}@var{warn}@dots{}] [@option{-pedantic}]
36 [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
37 [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
38 [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
39 [@option{-o} @var{outfile}] @var{infile}@dots{}
41 Only the most useful options are listed here; see below for the
42 remainder. @samp{g++} accepts mostly the same options as @samp{gcc}.
45 gpl(7), gfdl(7), fsf-funding(7),
46 cpp(1), gcov(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1)
47 and the Info entries for @file{gcc}, @file{cpp}, @file{as},
48 @file{ld}, @file{binutils} and @file{gdb}.
51 For instructions on reporting bugs, see
52 @w{@uref{http://gcc.gnu.org/bugs.html}}.
55 See the Info entry for @command{gcc}, or
56 @w{@uref{http://gcc.gnu.org/onlinedocs/gcc/Contributors.html}},
57 for contributors to GCC@.
62 @chapter GCC Command Options
63 @cindex GCC command options
64 @cindex command options
65 @cindex options, GCC command
67 @c man begin DESCRIPTION
68 When you invoke GCC, it normally does preprocessing, compilation,
69 assembly and linking. The ``overall options'' allow you to stop this
70 process at an intermediate stage. For example, the @option{-c} option
71 says not to run the linker. Then the output consists of object files
72 output by the assembler.
74 Other options are passed on to one stage of processing. Some options
75 control the preprocessor and others the compiler itself. Yet other
76 options control the assembler and linker; most of these are not
77 documented here, since you rarely need to use any of them.
79 @cindex C compilation options
80 Most of the command line options that you can use with GCC are useful
81 for C programs; when an option is only useful with another language
82 (usually C++), the explanation says so explicitly. If the description
83 for a particular option does not mention a source language, you can use
84 that option with all supported languages.
86 @cindex C++ compilation options
87 @xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
88 options for compiling C++ programs.
90 @cindex grouping options
91 @cindex options, grouping
92 The @command{gcc} program accepts options and file names as operands. Many
93 options have multi-letter names; therefore multiple single-letter options
94 may @emph{not} be grouped: @option{-dr} is very different from @w{@samp{-d
97 @cindex order of options
98 @cindex options, order
99 You can mix options and other arguments. For the most part, the order
100 you use doesn't matter. Order does matter when you use several options
101 of the same kind; for example, if you specify @option{-L} more than once,
102 the directories are searched in the order specified.
104 Many options have long names starting with @samp{-f} or with
105 @samp{-W}---for example, @option{-fforce-mem},
106 @option{-fstrength-reduce}, @option{-Wformat} and so on. Most of
107 these have both positive and negative forms; the negative form of
108 @option{-ffoo} would be @option{-fno-foo}. This manual documents
109 only one of these two forms, whichever one is not the default.
113 @xref{Option Index}, for an index to GCC's options.
116 * Option Summary:: Brief list of all options, without explanations.
117 * Overall Options:: Controlling the kind of output:
118 an executable, object files, assembler files,
119 or preprocessed source.
120 * Invoking G++:: Compiling C++ programs.
121 * C Dialect Options:: Controlling the variant of C language compiled.
122 * C++ Dialect Options:: Variations on C++.
123 * Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
125 * Language Independent Options:: Controlling how diagnostics should be
127 * Warning Options:: How picky should the compiler be?
128 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
129 * Optimize Options:: How much optimization?
130 * Preprocessor Options:: Controlling header files and macro definitions.
131 Also, getting dependency information for Make.
132 * Assembler Options:: Passing options to the assembler.
133 * Link Options:: Specifying libraries and so on.
134 * Directory Options:: Where to find header files and libraries.
135 Where to find the compiler executable files.
136 * Spec Files:: How to pass switches to sub-processes.
137 * Target Options:: Running a cross-compiler, or an old version of GCC.
138 * Submodel Options:: Specifying minor hardware or convention variations,
139 such as 68010 vs 68020.
140 * Code Gen Options:: Specifying conventions for function calls, data layout
142 * Environment Variables:: Env vars that affect GCC.
143 * Precompiled Headers:: Compiling a header once, and using it many times.
144 * Running Protoize:: Automatically adding or removing function prototypes.
150 @section Option Summary
152 Here is a summary of all the options, grouped by type. Explanations are
153 in the following sections.
156 @item Overall Options
157 @xref{Overall Options,,Options Controlling the Kind of Output}.
158 @gccoptlist{-c -S -E -o @var{file} -combine -pipe -pass-exit-codes @gol
159 -x @var{language} -v -### --help --target-help --version}
161 @item C Language Options
162 @xref{C Dialect Options,,Options Controlling C Dialect}.
163 @gccoptlist{-ansi -std=@var{standard} -aux-info @var{filename} @gol
164 -fno-asm -fno-builtin -fno-builtin-@var{function} @gol
165 -fhosted -ffreestanding -fms-extensions @gol
166 -trigraphs -no-integrated-cpp -traditional -traditional-cpp @gol
167 -fallow-single-precision -fcond-mismatch @gol
168 -fsigned-bitfields -fsigned-char @gol
169 -funsigned-bitfields -funsigned-char}
171 @item C++ Language Options
172 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
173 @gccoptlist{-fabi-version=@var{n} -fno-access-control -fcheck-new @gol
174 -fconserve-space -fno-const-strings @gol
175 -fno-elide-constructors @gol
176 -fno-enforce-eh-specs @gol
177 -ffor-scope -fno-for-scope -fno-gnu-keywords @gol
178 -fno-implicit-templates @gol
179 -fno-implicit-inline-templates @gol
180 -fno-implement-inlines -fms-extensions @gol
181 -fno-nonansi-builtins -fno-operator-names @gol
182 -fno-optional-diags -fpermissive @gol
183 -frepo -fno-rtti -fstats -ftemplate-depth-@var{n} @gol
184 -fno-threadsafe-statics -fuse-cxa-atexit -fno-weak -nostdinc++ @gol
185 -fno-default-inline -fvisibility-inlines-hidden @gol
186 -Wabi -Wctor-dtor-privacy @gol
187 -Wnon-virtual-dtor -Wreorder @gol
188 -Weffc++ -Wno-deprecated @gol
189 -Wno-non-template-friend -Wold-style-cast @gol
190 -Woverloaded-virtual -Wno-pmf-conversions @gol
193 @item Objective-C and Objective-C++ Language Options
194 @xref{Objective-C and Objective-C++ Dialect Options,,Options Controlling
195 Objective-C and Objective-C++ Dialects}.
197 -fconstant-string-class=@var{class-name} @gol
198 -fgnu-runtime -fnext-runtime @gol
199 -fno-nil-receivers @gol
200 -fobjc-exceptions @gol
201 -freplace-objc-classes @gol
204 -Wno-protocol -Wselector -Wundeclared-selector}
206 @item Language Independent Options
207 @xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}.
208 @gccoptlist{-fmessage-length=@var{n} @gol
209 -fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]}}
211 @item Warning Options
212 @xref{Warning Options,,Options to Request or Suppress Warnings}.
213 @gccoptlist{-fsyntax-only -pedantic -pedantic-errors @gol
214 -w -Wextra -Wall -Waggregate-return @gol
215 -Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment @gol
216 -Wconversion -Wno-deprecated-declarations @gol
217 -Wdisabled-optimization -Wno-div-by-zero -Wno-endif-labels @gol
218 -Werror -Werror-implicit-function-declaration @gol
219 -Wfatal-errors -Wfloat-equal -Wformat -Wformat=2 @gol
220 -Wno-format-extra-args -Wformat-nonliteral @gol
221 -Wformat-security -Wformat-y2k @gol
222 -Wimplicit -Wimplicit-function-declaration -Wimplicit-int @gol
223 -Wimport -Wno-import -Winit-self -Winline @gol
224 -Wno-invalid-offsetof -Winvalid-pch @gol
225 -Wlarger-than-@var{len} -Wlong-long @gol
226 -Wmain -Wmissing-braces -Wmissing-field-initializers @gol
227 -Wmissing-format-attribute -Wmissing-include-dirs @gol
228 -Wmissing-noreturn @gol
229 -Wno-multichar -Wnonnull -Wpacked -Wpadded @gol
230 -Wparentheses -Wpointer-arith -Wredundant-decls @gol
231 -Wreturn-type -Wsequence-point -Wshadow @gol
232 -Wsign-compare -Wstrict-aliasing -Wstrict-aliasing=2 @gol
233 -Wswitch -Wswitch-default -Wswitch-enum @gol
234 -Wsystem-headers -Wtrigraphs -Wundef -Wuninitialized @gol
235 -Wunknown-pragmas -Wunreachable-code @gol
236 -Wunused -Wunused-function -Wunused-label -Wunused-parameter @gol
237 -Wunused-value -Wunused-variable -Wwrite-strings @gol
240 @item C-only Warning Options
241 @gccoptlist{-Wbad-function-cast -Wmissing-declarations @gol
242 -Wmissing-prototypes -Wnested-externs -Wold-style-definition @gol
243 -Wstrict-prototypes -Wtraditional @gol
244 -Wdeclaration-after-statement -Wno-pointer-sign}
246 @item Debugging Options
247 @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
248 @gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
249 -fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} @gol
250 -fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
251 -fdump-ipa-all -fdump-ipa-cgraph @gol
253 -fdump-tree-original@r{[}-@var{n}@r{]} @gol
254 -fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
255 -fdump-tree-inlined@r{[}-@var{n}@r{]} @gol
256 -fdump-tree-cfg -fdump-tree-vcg -fdump-tree-alias @gol
258 -fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol
259 -fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol
260 -fdump-tree-gimple@r{[}-raw@r{]} -fdump-tree-mudflap@r{[}-@var{n}@r{]} @gol
261 -fdump-tree-dom@r{[}-@var{n}@r{]} @gol
262 -fdump-tree-dse@r{[}-@var{n}@r{]} @gol
263 -fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol
264 -fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
265 -fdump-tree-copyrename@r{[}-@var{n}@r{]} @gol
266 -fdump-tree-nrv -fdump-tree-vect @gol
267 -fdump-tree-sink @gol
268 -fdump-tree-sra@r{[}-@var{n}@r{]} @gol
269 -fdump-tree-salias @gol
270 -fdump-tree-fre@r{[}-@var{n}@r{]} @gol
271 -ftree-vectorizer-verbose=@var{n} @gol
272 -fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol
273 -feliminate-dwarf2-dups -feliminate-unused-debug-types @gol
274 -feliminate-unused-debug-symbols -fmem-report -fprofile-arcs -ftree-based-profiling @gol
275 -frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
276 -ftest-coverage -ftime-report -fvar-tracking @gol
277 -g -g@var{level} -gcoff -gdwarf-2 @gol
278 -ggdb -gstabs -gstabs+ -gvms -gxcoff -gxcoff+ @gol
279 -p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol
280 -print-multi-directory -print-multi-lib @gol
281 -print-prog-name=@var{program} -print-search-dirs -Q @gol
284 @item Optimization Options
285 @xref{Optimize Options,,Options that Control Optimization}.
286 @gccoptlist{-falign-functions=@var{n} -falign-jumps=@var{n} @gol
287 -falign-labels=@var{n} -falign-loops=@var{n} @gol
288 -fbounds-check -fmudflap -fmudflapth -fmudflapir @gol
289 -fbranch-probabilities -fprofile-values -fvpt -fbranch-target-load-optimize @gol
290 -fbranch-target-load-optimize2 -fbtr-bb-exclusive @gol
291 -fcaller-saves -fcprop-registers -fcse-follow-jumps @gol
292 -fcse-skip-blocks -fcx-limited-range -fdata-sections @gol
293 -fdelayed-branch -fdelete-null-pointer-checks @gol
294 -fexpensive-optimizations -ffast-math -ffloat-store @gol
295 -fforce-addr -fforce-mem -ffunction-sections @gol
296 -fgcse -fgcse-lm -fgcse-sm -fgcse-las -fgcse-after-reload @gol
297 -floop-optimize -fcrossjumping -fif-conversion -fif-conversion2 @gol
298 -finline-functions -finline-limit=@var{n} -fkeep-inline-functions @gol
299 -fkeep-static-consts -fmerge-constants -fmerge-all-constants @gol
300 -fmodulo-sched -fno-branch-count-reg @gol
301 -fno-default-inline -fno-defer-pop -floop-optimize2 -fmove-loop-invariants @gol
302 -fno-function-cse -fno-guess-branch-probability @gol
303 -fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol
304 -funsafe-math-optimizations -ffinite-math-only @gol
305 -fno-trapping-math -fno-zero-initialized-in-bss @gol
306 -fomit-frame-pointer -foptimize-register-move @gol
307 -foptimize-sibling-calls -fprefetch-loop-arrays @gol
308 -fprofile-generate -fprofile-use @gol
309 -fregmove -frename-registers @gol
310 -freorder-blocks -freorder-blocks-and-partition -freorder-functions @gol
311 -frerun-cse-after-loop -frerun-loop-opt @gol
312 -frounding-math -fschedule-insns -fschedule-insns2 @gol
313 -fno-sched-interblock -fno-sched-spec -fsched-spec-load @gol
314 -fsched-spec-load-dangerous @gol
315 -fsched-stalled-insns=@var{n} -sched-stalled-insns-dep=@var{n} @gol
316 -fsched2-use-superblocks @gol
317 -fsched2-use-traces -freschedule-modulo-scheduled-loops @gol
318 -fsignaling-nans -fsingle-precision-constant -fspeculative-prefetching @gol
319 -fstrength-reduce -fstrict-aliasing -ftracer -fthread-jumps @gol
320 -funroll-all-loops -funroll-loops -fpeel-loops @gol
321 -fsplit-ivs-in-unroller -funswitch-loops @gol
322 -fvariable-expansion-in-unroller @gol
323 -ftree-pre -ftree-ccp -ftree-dce -ftree-loop-optimize @gol
324 -ftree-loop-linear -ftree-loop-im -ftree-loop-ivcanon -fivopts @gol
325 -ftree-dominator-opts -ftree-dse -ftree-copyrename -ftree-sink @gol
326 -ftree-ch -ftree-sra -ftree-ter -ftree-lrs -ftree-fre -ftree-vectorize @gol
327 -ftree-salias -fweb @gol
328 -ftree-copy-prop -ftree-store-ccp -ftree-store-copy-prop @gol
329 --param @var{name}=@var{value}
330 -O -O0 -O1 -O2 -O3 -Os}
332 @item Preprocessor Options
333 @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
334 @gccoptlist{-A@var{question}=@var{answer} @gol
335 -A-@var{question}@r{[}=@var{answer}@r{]} @gol
336 -C -dD -dI -dM -dN @gol
337 -D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol
338 -idirafter @var{dir} @gol
339 -include @var{file} -imacros @var{file} @gol
340 -iprefix @var{file} -iwithprefix @var{dir} @gol
341 -iwithprefixbefore @var{dir} -isystem @var{dir} @gol
342 -M -MM -MF -MG -MP -MQ -MT -nostdinc @gol
343 -P -fworking-directory -remap @gol
344 -trigraphs -undef -U@var{macro} -Wp,@var{option} @gol
345 -Xpreprocessor @var{option}}
347 @item Assembler Option
348 @xref{Assembler Options,,Passing Options to the Assembler}.
349 @gccoptlist{-Wa,@var{option} -Xassembler @var{option}}
352 @xref{Link Options,,Options for Linking}.
353 @gccoptlist{@var{object-file-name} -l@var{library} @gol
354 -nostartfiles -nodefaultlibs -nostdlib -pie @gol
355 -s -static -static-libgcc -shared -shared-libgcc -symbolic @gol
356 -Wl,@var{option} -Xlinker @var{option} @gol
359 @item Directory Options
360 @xref{Directory Options,,Options for Directory Search}.
361 @gccoptlist{-B@var{prefix} -I@var{dir} -iquote@var{dir} -L@var{dir} -specs=@var{file} -I-}
364 @c I wrote this xref this way to avoid overfull hbox. -- rms
365 @xref{Target Options}.
366 @gccoptlist{-V @var{version} -b @var{machine}}
368 @item Machine Dependent Options
369 @xref{Submodel Options,,Hardware Models and Configurations}.
370 @c This list is ordered alphanumerically by subsection name.
371 @c Try and put the significant identifier (CPU or system) first,
372 @c so users have a clue at guessing where the ones they want will be.
375 @gccoptlist{-EB -EL @gol
376 -mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text-section} @gol
377 -mdata=@var{data-section} -mrodata=@var{readonly-data-section}}
380 @gccoptlist{-mapcs-frame -mno-apcs-frame @gol
381 -mabi=@var{name} @gol
382 -mapcs-stack-check -mno-apcs-stack-check @gol
383 -mapcs-float -mno-apcs-float @gol
384 -mapcs-reentrant -mno-apcs-reentrant @gol
385 -msched-prolog -mno-sched-prolog @gol
386 -mlittle-endian -mbig-endian -mwords-little-endian @gol
387 -mfloat-abi=@var{name} -msoft-float -mhard-float -mfpe @gol
388 -mthumb-interwork -mno-thumb-interwork @gol
389 -mcpu=@var{name} -march=@var{name} -mfpu=@var{name} @gol
390 -mstructure-size-boundary=@var{n} @gol
391 -mabort-on-noreturn @gol
392 -mlong-calls -mno-long-calls @gol
393 -msingle-pic-base -mno-single-pic-base @gol
394 -mpic-register=@var{reg} @gol
395 -mnop-fun-dllimport @gol
396 -mcirrus-fix-invalid-insns -mno-cirrus-fix-invalid-insns @gol
397 -mpoke-function-name @gol
399 -mtpcs-frame -mtpcs-leaf-frame @gol
400 -mcaller-super-interworking -mcallee-super-interworking}
403 @gccoptlist{-mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts @gol
404 -mcall-prologues -mno-tablejump -mtiny-stack -mint8}
406 @emph{Blackfin Options}
407 @gccoptlist{-momit-leaf-frame-pointer -mno-omit-leaf-frame-pointer -mcsync @gol
408 -mno-csync -mlow-64k -mno-low64k -mid-shared-library @gol
409 -mno-id-shared-library -mshared-library-id=@var{n} @gol}
412 @gccoptlist{-mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol
413 -mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol
414 -metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol
415 -mstack-align -mdata-align -mconst-align @gol
416 -m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol
417 -melf -maout -melinux -mlinux -sim -sim2 @gol
418 -mmul-bug-workaround -mno-mul-bug-workaround}
420 @emph{Darwin Options}
421 @gccoptlist{-all_load -allowable_client -arch -arch_errors_fatal @gol
422 -arch_only -bind_at_load -bundle -bundle_loader @gol
423 -client_name -compatibility_version -current_version @gol
425 -dependency-file -dylib_file -dylinker_install_name @gol
426 -dynamic -dynamiclib -exported_symbols_list @gol
427 -filelist -flat_namespace -force_cpusubtype_ALL @gol
428 -force_flat_namespace -headerpad_max_install_names @gol
429 -image_base -init -install_name -keep_private_externs @gol
430 -multi_module -multiply_defined -multiply_defined_unused @gol
431 -noall_load -no_dead_strip_inits_and_terms @gol
432 -nofixprebinding -nomultidefs -noprebind -noseglinkedit @gol
433 -pagezero_size -prebind -prebind_all_twolevel_modules @gol
434 -private_bundle -read_only_relocs -sectalign @gol
435 -sectobjectsymbols -whyload -seg1addr @gol
436 -sectcreate -sectobjectsymbols -sectorder @gol
437 -segaddr -segs_read_only_addr -segs_read_write_addr @gol
438 -seg_addr_table -seg_addr_table_filename -seglinkedit @gol
439 -segprot -segs_read_only_addr -segs_read_write_addr @gol
440 -single_module -static -sub_library -sub_umbrella @gol
441 -twolevel_namespace -umbrella -undefined @gol
442 -unexported_symbols_list -weak_reference_mismatches @gol
443 -whatsloaded -F -gused -gfull -mone-byte-bool}
445 @emph{DEC Alpha Options}
446 @gccoptlist{-mno-fp-regs -msoft-float -malpha-as -mgas @gol
447 -mieee -mieee-with-inexact -mieee-conformant @gol
448 -mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} @gol
449 -mtrap-precision=@var{mode} -mbuild-constants @gol
450 -mcpu=@var{cpu-type} -mtune=@var{cpu-type} @gol
451 -mbwx -mmax -mfix -mcix @gol
452 -mfloat-vax -mfloat-ieee @gol
453 -mexplicit-relocs -msmall-data -mlarge-data @gol
454 -msmall-text -mlarge-text @gol
455 -mmemory-latency=@var{time}}
457 @emph{DEC Alpha/VMS Options}
458 @gccoptlist{-mvms-return-codes}
461 @gccoptlist{-mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 @gol
462 -mhard-float -msoft-float @gol
463 -malloc-cc -mfixed-cc -mdword -mno-dword @gol
464 -mdouble -mno-double @gol
465 -mmedia -mno-media -mmuladd -mno-muladd @gol
466 -mfdpic -minline-plt -mgprel-ro -multilib-library-pic @gol
467 -mlinked-fp -mlong-calls -malign-labels @gol
468 -mlibrary-pic -macc-4 -macc-8 @gol
469 -mpack -mno-pack -mno-eflags -mcond-move -mno-cond-move @gol
470 -mscc -mno-scc -mcond-exec -mno-cond-exec @gol
471 -mvliw-branch -mno-vliw-branch @gol
472 -mmulti-cond-exec -mno-multi-cond-exec -mnested-cond-exec @gol
473 -mno-nested-cond-exec -mtomcat-stats @gol
477 @emph{H8/300 Options}
478 @gccoptlist{-mrelax -mh -ms -mn -mint32 -malign-300}
481 @gccoptlist{-march=@var{architecture-type} @gol
482 -mbig-switch -mdisable-fpregs -mdisable-indexing @gol
483 -mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol
484 -mfixed-range=@var{register-range} @gol
485 -mjump-in-delay -mlinker-opt -mlong-calls @gol
486 -mlong-load-store -mno-big-switch -mno-disable-fpregs @gol
487 -mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol
488 -mno-jump-in-delay -mno-long-load-store @gol
489 -mno-portable-runtime -mno-soft-float @gol
490 -mno-space-regs -msoft-float -mpa-risc-1-0 @gol
491 -mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime @gol
492 -mschedule=@var{cpu-type} -mspace-regs -msio -mwsio @gol
493 -munix=@var{unix-std} -nolibdld -static -threads}
495 @emph{i386 and x86-64 Options}
496 @gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
497 -mfpmath=@var{unit} @gol
498 -masm=@var{dialect} -mno-fancy-math-387 @gol
499 -mno-fp-ret-in-387 -msoft-float -msvr3-shlib @gol
500 -mno-wide-multiply -mrtd -malign-double @gol
501 -mpreferred-stack-boundary=@var{num} @gol
502 -mmmx -msse -msse2 -msse3 -m3dnow @gol
503 -mthreads -mno-align-stringops -minline-all-stringops @gol
504 -mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol
505 -m96bit-long-double -mregparm=@var{num} -momit-leaf-frame-pointer @gol
506 -mno-red-zone -mno-tls-direct-seg-refs @gol
507 -mcmodel=@var{code-model} @gol
511 @gccoptlist{-mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol
512 -mvolatile-asm-stop -mregister-names -mno-sdata @gol
513 -mconstant-gp -mauto-pic -minline-float-divide-min-latency @gol
514 -minline-float-divide-max-throughput @gol
515 -minline-int-divide-min-latency @gol
516 -minline-int-divide-max-throughput @gol
517 -minline-sqrt-min-latency -minline-sqrt-max-throughput @gol
518 -mno-dwarf2-asm -mearly-stop-bits @gol
519 -mfixed-range=@var{register-range} -mtls-size=@var{tls-size} @gol
520 -mtune=@var{cpu-type} -mt -pthread -milp32 -mlp64}
522 @emph{M32R/D Options}
523 @gccoptlist{-m32r2 -m32rx -m32r @gol
525 -malign-loops -mno-align-loops @gol
526 -missue-rate=@var{number} @gol
527 -mbranch-cost=@var{number} @gol
528 -mmodel=@var{code-size-model-type} @gol
529 -msdata=@var{sdata-type} @gol
530 -mno-flush-func -mflush-func=@var{name} @gol
531 -mno-flush-trap -mflush-trap=@var{number} @gol
534 @emph{M680x0 Options}
535 @gccoptlist{-m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol
536 -m68060 -mcpu32 -m5200 -m68881 -mbitfield -mc68000 -mc68020 @gol
537 -mnobitfield -mrtd -mshort -msoft-float -mpcrel @gol
538 -malign-int -mstrict-align -msep-data -mno-sep-data @gol
539 -mshared-library-id=n -mid-shared-library -mno-id-shared-library}
541 @emph{M68hc1x Options}
542 @gccoptlist{-m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 @gol
543 -mauto-incdec -minmax -mlong-calls -mshort @gol
544 -msoft-reg-count=@var{count}}
547 @gccoptlist{-mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol
548 -mno-relax-immediates -mwide-bitfields -mno-wide-bitfields @gol
549 -m4byte-functions -mno-4byte-functions -mcallgraph-data @gol
550 -mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim @gol
551 -mlittle-endian -mbig-endian -m210 -m340 -mstack-increment}
554 @gccoptlist{-EL -EB -march=@var{arch} -mtune=@var{arch} @gol
555 -mips1 -mips2 -mips3 -mips4 -mips32 -mips32r2 -mips64 @gol
556 -mips16 -mno-mips16 -mabi=@var{abi} -mabicalls -mno-abicalls @gol
557 -mxgot -mno-xgot -mgp32 -mgp64 -mfp32 -mfp64 @gol
558 -mhard-float -msoft-float -msingle-float -mdouble-float @gol
559 -mpaired-single -mips3d @gol
560 -mint64 -mlong64 -mlong32 -msym32 -mno-sym32 @gol
561 -G@var{num} -membedded-data -mno-embedded-data @gol
562 -muninit-const-in-rodata -mno-uninit-const-in-rodata @gol
563 -msplit-addresses -mno-split-addresses @gol
564 -mexplicit-relocs -mno-explicit-relocs @gol
565 -mcheck-zero-division -mno-check-zero-division @gol
566 -mdivide-traps -mdivide-breaks @gol
567 -mmemcpy -mno-memcpy -mlong-calls -mno-long-calls @gol
568 -mmad -mno-mad -mfused-madd -mno-fused-madd -nocpp @gol
569 -mfix-r4000 -mno-fix-r4000 -mfix-r4400 -mno-fix-r4400 @gol
570 -mfix-vr4120 -mno-fix-vr4120 -mfix-vr4130 @gol
571 -mfix-sb1 -mno-fix-sb1 @gol
572 -mflush-func=@var{func} -mno-flush-func @gol
573 -mbranch-likely -mno-branch-likely @gol
574 -mfp-exceptions -mno-fp-exceptions @gol
575 -mvr4130-align -mno-vr4130-align}
578 @gccoptlist{-mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol
579 -mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol
580 -melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol
581 -mno-base-addresses -msingle-exit -mno-single-exit}
583 @emph{MN10300 Options}
584 @gccoptlist{-mmult-bug -mno-mult-bug @gol
585 -mam33 -mno-am33 @gol
586 -mam33-2 -mno-am33-2 @gol
590 @gccoptlist{-m32032 -m32332 -m32532 -m32081 -m32381 @gol
591 -mmult-add -mnomult-add -msoft-float -mrtd -mnortd @gol
592 -mregparam -mnoregparam -msb -mnosb @gol
593 -mbitfield -mnobitfield -mhimem -mnohimem}
595 @emph{PDP-11 Options}
596 @gccoptlist{-mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol
597 -mbcopy -mbcopy-builtin -mint32 -mno-int16 @gol
598 -mint16 -mno-int32 -mfloat32 -mno-float64 @gol
599 -mfloat64 -mno-float32 -mabshi -mno-abshi @gol
600 -mbranch-expensive -mbranch-cheap @gol
601 -msplit -mno-split -munix-asm -mdec-asm}
603 @emph{PowerPC Options}
604 See RS/6000 and PowerPC Options.
606 @emph{RS/6000 and PowerPC Options}
607 @gccoptlist{-mcpu=@var{cpu-type} @gol
608 -mtune=@var{cpu-type} @gol
609 -mpower -mno-power -mpower2 -mno-power2 @gol
610 -mpowerpc -mpowerpc64 -mno-powerpc @gol
611 -maltivec -mno-altivec @gol
612 -mpowerpc-gpopt -mno-powerpc-gpopt @gol
613 -mpowerpc-gfxopt -mno-powerpc-gfxopt @gol
614 -mnew-mnemonics -mold-mnemonics @gol
615 -mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc @gol
616 -m64 -m32 -mxl-compat -mno-xl-compat -mpe @gol
617 -malign-power -malign-natural @gol
618 -msoft-float -mhard-float -mmultiple -mno-multiple @gol
619 -mstring -mno-string -mupdate -mno-update @gol
620 -mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol
621 -mstrict-align -mno-strict-align -mrelocatable @gol
622 -mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol
623 -mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol
624 -mdynamic-no-pic @gol
625 -mprioritize-restricted-insns=@var{priority} @gol
626 -msched-costly-dep=@var{dependence_type} @gol
627 -minsert-sched-nops=@var{scheme} @gol
628 -mcall-sysv -mcall-netbsd @gol
629 -maix-struct-return -msvr4-struct-return @gol
630 -mabi=altivec -mabi=no-altivec @gol
631 -mabi=spe -mabi=no-spe @gol
632 -misel=yes -misel=no @gol
633 -mspe=yes -mspe=no @gol
634 -mfloat-gprs=yes -mfloat-gprs=no -mfloat-gprs=single -mfloat-gprs=double @gol
635 -mprototype -mno-prototype @gol
636 -msim -mmvme -mads -myellowknife -memb -msdata @gol
637 -msdata=@var{opt} -mvxworks -mwindiss -G @var{num} -pthread}
639 @emph{S/390 and zSeries Options}
640 @gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
641 -mhard-float -msoft-float -mbackchain -mno-backchain @gol
642 -mpacked-stack -mno-packed-stack @gol
643 -msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol
644 -m64 -m31 -mdebug -mno-debug -mesa -mzarch @gol
645 -mtpf-trace -mno-tpf-trace -mfused-madd -mno-fused-madd @gol
646 -mwarn-framesize -mwarn-dynamicstack -mstack-size -mstack-guard}
649 @gccoptlist{-m1 -m2 -m2e -m3 -m3e @gol
650 -m4-nofpu -m4-single-only -m4-single -m4 @gol
651 -m4a-nofpu -m4a-single-only -m4a-single -m4a -m4al @gol
652 -m5-64media -m5-64media-nofpu @gol
653 -m5-32media -m5-32media-nofpu @gol
654 -m5-compact -m5-compact-nofpu @gol
655 -mb -ml -mdalign -mrelax @gol
656 -mbigtable -mfmovd -mhitachi -mrenesas -mno-renesas -mnomacsave @gol
657 -mieee -misize -mpadstruct -mspace @gol
658 -mprefergot -musermode}
661 @gccoptlist{-mcpu=@var{cpu-type} @gol
662 -mtune=@var{cpu-type} @gol
663 -mcmodel=@var{code-model} @gol
664 -m32 -m64 -mapp-regs -mno-app-regs @gol
665 -mfaster-structs -mno-faster-structs @gol
666 -mfpu -mno-fpu -mhard-float -msoft-float @gol
667 -mhard-quad-float -msoft-quad-float @gol
668 -mimpure-text -mno-impure-text -mlittle-endian @gol
669 -mstack-bias -mno-stack-bias @gol
670 -munaligned-doubles -mno-unaligned-doubles @gol
671 -mv8plus -mno-v8plus -mvis -mno-vis
674 @emph{System V Options}
675 @gccoptlist{-Qy -Qn -YP,@var{paths} -Ym,@var{dir}}
677 @emph{TMS320C3x/C4x Options}
678 @gccoptlist{-mcpu=@var{cpu} -mbig -msmall -mregparm -mmemparm @gol
679 -mfast-fix -mmpyi -mbk -mti -mdp-isr-reload @gol
680 -mrpts=@var{count} -mrptb -mdb -mloop-unsigned @gol
681 -mparallel-insns -mparallel-mpy -mpreserve-float}
684 @gccoptlist{-mlong-calls -mno-long-calls -mep -mno-ep @gol
685 -mprolog-function -mno-prolog-function -mspace @gol
686 -mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol
687 -mapp-regs -mno-app-regs @gol
688 -mdisable-callt -mno-disable-callt @gol
694 @gccoptlist{-mg -mgnu -munix}
696 @emph{x86-64 Options}
697 See i386 and x86-64 Options.
699 @emph{Xstormy16 Options}
702 @emph{Xtensa Options}
703 @gccoptlist{-mconst16 -mno-const16 @gol
704 -mfused-madd -mno-fused-madd @gol
705 -mtext-section-literals -mno-text-section-literals @gol
706 -mtarget-align -mno-target-align @gol
707 -mlongcalls -mno-longcalls}
709 @emph{zSeries Options}
710 See S/390 and zSeries Options.
712 @item Code Generation Options
713 @xref{Code Gen Options,,Options for Code Generation Conventions}.
714 @gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol
715 -ffixed-@var{reg} -fexceptions @gol
716 -fnon-call-exceptions -funwind-tables @gol
717 -fasynchronous-unwind-tables @gol
718 -finhibit-size-directive -finstrument-functions @gol
719 -fno-common -fno-ident @gol
720 -fpcc-struct-return -fpic -fPIC -fpie -fPIE @gol
721 -freg-struct-return -fshared-data -fshort-enums @gol
722 -fshort-double -fshort-wchar @gol
723 -fverbose-asm -fpack-struct[=@var{n}] -fstack-check @gol
724 -fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
725 -fargument-alias -fargument-noalias @gol
726 -fargument-noalias-global -fleading-underscore @gol
727 -ftls-model=@var{model} @gol
728 -ftrapv -fwrapv -fbounds-check @gol
733 * Overall Options:: Controlling the kind of output:
734 an executable, object files, assembler files,
735 or preprocessed source.
736 * C Dialect Options:: Controlling the variant of C language compiled.
737 * C++ Dialect Options:: Variations on C++.
738 * Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
740 * Language Independent Options:: Controlling how diagnostics should be
742 * Warning Options:: How picky should the compiler be?
743 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
744 * Optimize Options:: How much optimization?
745 * Preprocessor Options:: Controlling header files and macro definitions.
746 Also, getting dependency information for Make.
747 * Assembler Options:: Passing options to the assembler.
748 * Link Options:: Specifying libraries and so on.
749 * Directory Options:: Where to find header files and libraries.
750 Where to find the compiler executable files.
751 * Spec Files:: How to pass switches to sub-processes.
752 * Target Options:: Running a cross-compiler, or an old version of GCC.
755 @node Overall Options
756 @section Options Controlling the Kind of Output
758 Compilation can involve up to four stages: preprocessing, compilation
759 proper, assembly and linking, always in that order. GCC is capable of
760 preprocessing and compiling several files either into several
761 assembler input files, or into one assembler input file; then each
762 assembler input file produces an object file, and linking combines all
763 the object files (those newly compiled, and those specified as input)
764 into an executable file.
766 @cindex file name suffix
767 For any given input file, the file name suffix determines what kind of
772 C source code which must be preprocessed.
775 C source code which should not be preprocessed.
778 C++ source code which should not be preprocessed.
781 Objective-C source code. Note that you must link with the @file{libobjc}
782 library to make an Objective-C program work.
785 Objective-C source code which should not be preprocessed.
789 Objective-C++ source code. Note that you must link with the @file{libobjc}
790 library to make an Objective-C++ program work. Note that @samp{.M} refers
791 to a literal capital M@.
794 Objective-C++ source code which should not be preprocessed.
797 C, C++, Objective-C or Objective-C++ header file to be turned into a
802 @itemx @var{file}.cxx
803 @itemx @var{file}.cpp
804 @itemx @var{file}.CPP
805 @itemx @var{file}.c++
807 C++ source code which must be preprocessed. Note that in @samp{.cxx},
808 the last two letters must both be literally @samp{x}. Likewise,
809 @samp{.C} refers to a literal capital C@.
813 C++ header file to be turned into a precompiled header.
816 @itemx @var{file}.for
817 @itemx @var{file}.FOR
818 Fortran source code which should not be preprocessed.
821 @itemx @var{file}.fpp
822 @itemx @var{file}.FPP
823 Fortran source code which must be preprocessed (with the traditional
827 Fortran source code which must be preprocessed with a RATFOR
828 preprocessor (not included with GCC)@.
831 @itemx @var{file}.f95
832 Fortran 90/95 source code which should not be preprocessed.
834 @c FIXME: Descriptions of Java file types.
841 Ada source code file which contains a library unit declaration (a
842 declaration of a package, subprogram, or generic, or a generic
843 instantiation), or a library unit renaming declaration (a package,
844 generic, or subprogram renaming declaration). Such files are also
847 @itemx @var{file}.adb
848 Ada source code file containing a library unit body (a subprogram or
849 package body). Such files are also called @dfn{bodies}.
851 @c GCC also knows about some suffixes for languages not yet included:
860 Assembler code which must be preprocessed.
863 An object file to be fed straight into linking.
864 Any file name with no recognized suffix is treated this way.
868 You can specify the input language explicitly with the @option{-x} option:
871 @item -x @var{language}
872 Specify explicitly the @var{language} for the following input files
873 (rather than letting the compiler choose a default based on the file
874 name suffix). This option applies to all following input files until
875 the next @option{-x} option. Possible values for @var{language} are:
877 c c-header c-cpp-output
878 c++ c++-header c++-cpp-output
879 objective-c objective-c-header objective-c-cpp-output
880 objective-c++ objective-c++-header objective-c++-cpp-output
881 assembler assembler-with-cpp
883 f77 f77-cpp-input ratfor
890 Turn off any specification of a language, so that subsequent files are
891 handled according to their file name suffixes (as they are if @option{-x}
892 has not been used at all).
894 @item -pass-exit-codes
895 @opindex pass-exit-codes
896 Normally the @command{gcc} program will exit with the code of 1 if any
897 phase of the compiler returns a non-success return code. If you specify
898 @option{-pass-exit-codes}, the @command{gcc} program will instead return with
899 numerically highest error produced by any phase that returned an error
903 If you only want some of the stages of compilation, you can use
904 @option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
905 one of the options @option{-c}, @option{-S}, or @option{-E} to say where
906 @command{gcc} is to stop. Note that some combinations (for example,
907 @samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
912 Compile or assemble the source files, but do not link. The linking
913 stage simply is not done. The ultimate output is in the form of an
914 object file for each source file.
916 By default, the object file name for a source file is made by replacing
917 the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
919 Unrecognized input files, not requiring compilation or assembly, are
924 Stop after the stage of compilation proper; do not assemble. The output
925 is in the form of an assembler code file for each non-assembler input
928 By default, the assembler file name for a source file is made by
929 replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
931 Input files that don't require compilation are ignored.
935 Stop after the preprocessing stage; do not run the compiler proper. The
936 output is in the form of preprocessed source code, which is sent to the
939 Input files which don't require preprocessing are ignored.
941 @cindex output file option
944 Place output in file @var{file}. This applies regardless to whatever
945 sort of output is being produced, whether it be an executable file,
946 an object file, an assembler file or preprocessed C code.
948 If @option{-o} is not specified, the default is to put an executable
949 file in @file{a.out}, the object file for
950 @file{@var{source}.@var{suffix}} in @file{@var{source}.o}, its
951 assembler file in @file{@var{source}.s}, a precompiled header file in
952 @file{@var{source}.@var{suffix}.gch}, and all preprocessed C source on
957 Print (on standard error output) the commands executed to run the stages
958 of compilation. Also print the version number of the compiler driver
959 program and of the preprocessor and the compiler proper.
963 Like @option{-v} except the commands are not executed and all command
964 arguments are quoted. This is useful for shell scripts to capture the
965 driver-generated command lines.
969 Use pipes rather than temporary files for communication between the
970 various stages of compilation. This fails to work on some systems where
971 the assembler is unable to read from a pipe; but the GNU assembler has
976 If you are compiling multiple source files, this option tells the driver
977 to pass all the source files to the compiler at once (for those
978 languages for which the compiler can handle this). This will allow
979 intermodule analysis (IMA) to be performed by the compiler. Currently the only
980 language for which this is supported is C@. If you pass source files for
981 multiple languages to the driver, using this option, the driver will invoke
982 the compiler(s) that support IMA once each, passing each compiler all the
983 source files appropriate for it. For those languages that do not support
984 IMA this option will be ignored, and the compiler will be invoked once for
985 each source file in that language. If you use this option in conjunction
986 with @option{-save-temps}, the compiler will generate multiple
988 (one for each source file), but only one (combined) @file{.o} or
993 Print (on the standard output) a description of the command line options
994 understood by @command{gcc}. If the @option{-v} option is also specified
995 then @option{--help} will also be passed on to the various processes
996 invoked by @command{gcc}, so that they can display the command line options
997 they accept. If the @option{-Wextra} option is also specified then command
998 line options which have no documentation associated with them will also
1002 @opindex target-help
1003 Print (on the standard output) a description of target specific command
1004 line options for each tool.
1008 Display the version number and copyrights of the invoked GCC@.
1012 @section Compiling C++ Programs
1014 @cindex suffixes for C++ source
1015 @cindex C++ source file suffixes
1016 C++ source files conventionally use one of the suffixes @samp{.C},
1017 @samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or
1018 @samp{.cxx}; C++ header files often use @samp{.hh} or @samp{.H}; and
1019 preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes
1020 files with these names and compiles them as C++ programs even if you
1021 call the compiler the same way as for compiling C programs (usually
1022 with the name @command{gcc}).
1026 However, C++ programs often require class libraries as well as a
1027 compiler that understands the C++ language---and under some
1028 circumstances, you might want to compile programs or header files from
1029 standard input, or otherwise without a suffix that flags them as C++
1030 programs. You might also like to precompile a C header file with a
1031 @samp{.h} extension to be used in C++ compilations. @command{g++} is a
1032 program that calls GCC with the default language set to C++, and
1033 automatically specifies linking against the C++ library. On many
1034 systems, @command{g++} is also installed with the name @command{c++}.
1036 @cindex invoking @command{g++}
1037 When you compile C++ programs, you may specify many of the same
1038 command-line options that you use for compiling programs in any
1039 language; or command-line options meaningful for C and related
1040 languages; or options that are meaningful only for C++ programs.
1041 @xref{C Dialect Options,,Options Controlling C Dialect}, for
1042 explanations of options for languages related to C@.
1043 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
1044 explanations of options that are meaningful only for C++ programs.
1046 @node C Dialect Options
1047 @section Options Controlling C Dialect
1048 @cindex dialect options
1049 @cindex language dialect options
1050 @cindex options, dialect
1052 The following options control the dialect of C (or languages derived
1053 from C, such as C++, Objective-C and Objective-C++) that the compiler
1057 @cindex ANSI support
1061 In C mode, support all ISO C90 programs. In C++ mode,
1062 remove GNU extensions that conflict with ISO C++.
1064 This turns off certain features of GCC that are incompatible with ISO
1065 C90 (when compiling C code), or of standard C++ (when compiling C++ code),
1066 such as the @code{asm} and @code{typeof} keywords, and
1067 predefined macros such as @code{unix} and @code{vax} that identify the
1068 type of system you are using. It also enables the undesirable and
1069 rarely used ISO trigraph feature. For the C compiler,
1070 it disables recognition of C++ style @samp{//} comments as well as
1071 the @code{inline} keyword.
1073 The alternate keywords @code{__asm__}, @code{__extension__},
1074 @code{__inline__} and @code{__typeof__} continue to work despite
1075 @option{-ansi}. You would not want to use them in an ISO C program, of
1076 course, but it is useful to put them in header files that might be included
1077 in compilations done with @option{-ansi}. Alternate predefined macros
1078 such as @code{__unix__} and @code{__vax__} are also available, with or
1079 without @option{-ansi}.
1081 The @option{-ansi} option does not cause non-ISO programs to be
1082 rejected gratuitously. For that, @option{-pedantic} is required in
1083 addition to @option{-ansi}. @xref{Warning Options}.
1085 The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
1086 option is used. Some header files may notice this macro and refrain
1087 from declaring certain functions or defining certain macros that the
1088 ISO standard doesn't call for; this is to avoid interfering with any
1089 programs that might use these names for other things.
1091 Functions which would normally be built in but do not have semantics
1092 defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
1093 functions with @option{-ansi} is used. @xref{Other Builtins,,Other
1094 built-in functions provided by GCC}, for details of the functions
1099 Determine the language standard. This option is currently only
1100 supported when compiling C or C++. A value for this option must be
1101 provided; possible values are
1106 ISO C90 (same as @option{-ansi}).
1108 @item iso9899:199409
1109 ISO C90 as modified in amendment 1.
1115 ISO C99. Note that this standard is not yet fully supported; see
1116 @w{@uref{http://gcc.gnu.org/c99status.html}} for more information. The
1117 names @samp{c9x} and @samp{iso9899:199x} are deprecated.
1120 Default, ISO C90 plus GNU extensions (including some C99 features).
1124 ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC,
1125 this will become the default. The name @samp{gnu9x} is deprecated.
1128 The 1998 ISO C++ standard plus amendments.
1131 The same as @option{-std=c++98} plus GNU extensions. This is the
1132 default for C++ code.
1135 Even when this option is not specified, you can still use some of the
1136 features of newer standards in so far as they do not conflict with
1137 previous C standards. For example, you may use @code{__restrict__} even
1138 when @option{-std=c99} is not specified.
1140 The @option{-std} options specifying some version of ISO C have the same
1141 effects as @option{-ansi}, except that features that were not in ISO C90
1142 but are in the specified version (for example, @samp{//} comments and
1143 the @code{inline} keyword in ISO C99) are not disabled.
1145 @xref{Standards,,Language Standards Supported by GCC}, for details of
1146 these standard versions.
1148 @item -aux-info @var{filename}
1150 Output to the given filename prototyped declarations for all functions
1151 declared and/or defined in a translation unit, including those in header
1152 files. This option is silently ignored in any language other than C@.
1154 Besides declarations, the file indicates, in comments, the origin of
1155 each declaration (source file and line), whether the declaration was
1156 implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
1157 @samp{O} for old, respectively, in the first character after the line
1158 number and the colon), and whether it came from a declaration or a
1159 definition (@samp{C} or @samp{F}, respectively, in the following
1160 character). In the case of function definitions, a K&R-style list of
1161 arguments followed by their declarations is also provided, inside
1162 comments, after the declaration.
1166 Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1167 keyword, so that code can use these words as identifiers. You can use
1168 the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
1169 instead. @option{-ansi} implies @option{-fno-asm}.
1171 In C++, this switch only affects the @code{typeof} keyword, since
1172 @code{asm} and @code{inline} are standard keywords. You may want to
1173 use the @option{-fno-gnu-keywords} flag instead, which has the same
1174 effect. In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
1175 switch only affects the @code{asm} and @code{typeof} keywords, since
1176 @code{inline} is a standard keyword in ISO C99.
1179 @itemx -fno-builtin-@var{function}
1180 @opindex fno-builtin
1181 @cindex built-in functions
1182 Don't recognize built-in functions that do not begin with
1183 @samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in
1184 functions provided by GCC}, for details of the functions affected,
1185 including those which are not built-in functions when @option{-ansi} or
1186 @option{-std} options for strict ISO C conformance are used because they
1187 do not have an ISO standard meaning.
1189 GCC normally generates special code to handle certain built-in functions
1190 more efficiently; for instance, calls to @code{alloca} may become single
1191 instructions that adjust the stack directly, and calls to @code{memcpy}
1192 may become inline copy loops. The resulting code is often both smaller
1193 and faster, but since the function calls no longer appear as such, you
1194 cannot set a breakpoint on those calls, nor can you change the behavior
1195 of the functions by linking with a different library. In addition,
1196 when a function is recognized as a built-in function, GCC may use
1197 information about that function to warn about problems with calls to
1198 that function, or to generate more efficient code, even if the
1199 resulting code still contains calls to that function. For example,
1200 warnings are given with @option{-Wformat} for bad calls to
1201 @code{printf}, when @code{printf} is built in, and @code{strlen} is
1202 known not to modify global memory.
1204 With the @option{-fno-builtin-@var{function}} option
1205 only the built-in function @var{function} is
1206 disabled. @var{function} must not begin with @samp{__builtin_}. If a
1207 function is named this is not built-in in this version of GCC, this
1208 option is ignored. There is no corresponding
1209 @option{-fbuiltin-@var{function}} option; if you wish to enable
1210 built-in functions selectively when using @option{-fno-builtin} or
1211 @option{-ffreestanding}, you may define macros such as:
1214 #define abs(n) __builtin_abs ((n))
1215 #define strcpy(d, s) __builtin_strcpy ((d), (s))
1220 @cindex hosted environment
1222 Assert that compilation takes place in a hosted environment. This implies
1223 @option{-fbuiltin}. A hosted environment is one in which the
1224 entire standard library is available, and in which @code{main} has a return
1225 type of @code{int}. Examples are nearly everything except a kernel.
1226 This is equivalent to @option{-fno-freestanding}.
1228 @item -ffreestanding
1229 @opindex ffreestanding
1230 @cindex hosted environment
1232 Assert that compilation takes place in a freestanding environment. This
1233 implies @option{-fno-builtin}. A freestanding environment
1234 is one in which the standard library may not exist, and program startup may
1235 not necessarily be at @code{main}. The most obvious example is an OS kernel.
1236 This is equivalent to @option{-fno-hosted}.
1238 @xref{Standards,,Language Standards Supported by GCC}, for details of
1239 freestanding and hosted environments.
1241 @item -fms-extensions
1242 @opindex fms-extensions
1243 Accept some non-standard constructs used in Microsoft header files.
1245 Some cases of unnamed fields in structures and unions are only
1246 accepted with this option. @xref{Unnamed Fields,,Unnamed struct/union
1247 fields within structs/unions}, for details.
1251 Support ISO C trigraphs. The @option{-ansi} option (and @option{-std}
1252 options for strict ISO C conformance) implies @option{-trigraphs}.
1254 @item -no-integrated-cpp
1255 @opindex no-integrated-cpp
1256 Performs a compilation in two passes: preprocessing and compiling. This
1257 option allows a user supplied "cc1", "cc1plus", or "cc1obj" via the
1258 @option{-B} option. The user supplied compilation step can then add in
1259 an additional preprocessing step after normal preprocessing but before
1260 compiling. The default is to use the integrated cpp (internal cpp)
1262 The semantics of this option will change if "cc1", "cc1plus", and
1263 "cc1obj" are merged.
1265 @cindex traditional C language
1266 @cindex C language, traditional
1268 @itemx -traditional-cpp
1269 @opindex traditional-cpp
1270 @opindex traditional
1271 Formerly, these options caused GCC to attempt to emulate a pre-standard
1272 C compiler. They are now only supported with the @option{-E} switch.
1273 The preprocessor continues to support a pre-standard mode. See the GNU
1274 CPP manual for details.
1276 @item -fcond-mismatch
1277 @opindex fcond-mismatch
1278 Allow conditional expressions with mismatched types in the second and
1279 third arguments. The value of such an expression is void. This option
1280 is not supported for C++.
1282 @item -funsigned-char
1283 @opindex funsigned-char
1284 Let the type @code{char} be unsigned, like @code{unsigned char}.
1286 Each kind of machine has a default for what @code{char} should
1287 be. It is either like @code{unsigned char} by default or like
1288 @code{signed char} by default.
1290 Ideally, a portable program should always use @code{signed char} or
1291 @code{unsigned char} when it depends on the signedness of an object.
1292 But many programs have been written to use plain @code{char} and
1293 expect it to be signed, or expect it to be unsigned, depending on the
1294 machines they were written for. This option, and its inverse, let you
1295 make such a program work with the opposite default.
1297 The type @code{char} is always a distinct type from each of
1298 @code{signed char} or @code{unsigned char}, even though its behavior
1299 is always just like one of those two.
1302 @opindex fsigned-char
1303 Let the type @code{char} be signed, like @code{signed char}.
1305 Note that this is equivalent to @option{-fno-unsigned-char}, which is
1306 the negative form of @option{-funsigned-char}. Likewise, the option
1307 @option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
1309 @item -fsigned-bitfields
1310 @itemx -funsigned-bitfields
1311 @itemx -fno-signed-bitfields
1312 @itemx -fno-unsigned-bitfields
1313 @opindex fsigned-bitfields
1314 @opindex funsigned-bitfields
1315 @opindex fno-signed-bitfields
1316 @opindex fno-unsigned-bitfields
1317 These options control whether a bit-field is signed or unsigned, when the
1318 declaration does not use either @code{signed} or @code{unsigned}. By
1319 default, such a bit-field is signed, because this is consistent: the
1320 basic integer types such as @code{int} are signed types.
1323 @node C++ Dialect Options
1324 @section Options Controlling C++ Dialect
1326 @cindex compiler options, C++
1327 @cindex C++ options, command line
1328 @cindex options, C++
1329 This section describes the command-line options that are only meaningful
1330 for C++ programs; but you can also use most of the GNU compiler options
1331 regardless of what language your program is in. For example, you
1332 might compile a file @code{firstClass.C} like this:
1335 g++ -g -frepo -O -c firstClass.C
1339 In this example, only @option{-frepo} is an option meant
1340 only for C++ programs; you can use the other options with any
1341 language supported by GCC@.
1343 Here is a list of options that are @emph{only} for compiling C++ programs:
1347 @item -fabi-version=@var{n}
1348 @opindex fabi-version
1349 Use version @var{n} of the C++ ABI@. Version 2 is the version of the
1350 C++ ABI that first appeared in G++ 3.4. Version 1 is the version of
1351 the C++ ABI that first appeared in G++ 3.2. Version 0 will always be
1352 the version that conforms most closely to the C++ ABI specification.
1353 Therefore, the ABI obtained using version 0 will change as ABI bugs
1356 The default is version 2.
1358 @item -fno-access-control
1359 @opindex fno-access-control
1360 Turn off all access checking. This switch is mainly useful for working
1361 around bugs in the access control code.
1365 Check that the pointer returned by @code{operator new} is non-null
1366 before attempting to modify the storage allocated. This check is
1367 normally unnecessary because the C++ standard specifies that
1368 @code{operator new} will only return @code{0} if it is declared
1369 @samp{throw()}, in which case the compiler will always check the
1370 return value even without this option. In all other cases, when
1371 @code{operator new} has a non-empty exception specification, memory
1372 exhaustion is signalled by throwing @code{std::bad_alloc}. See also
1373 @samp{new (nothrow)}.
1375 @item -fconserve-space
1376 @opindex fconserve-space
1377 Put uninitialized or runtime-initialized global variables into the
1378 common segment, as C does. This saves space in the executable at the
1379 cost of not diagnosing duplicate definitions. If you compile with this
1380 flag and your program mysteriously crashes after @code{main()} has
1381 completed, you may have an object that is being destroyed twice because
1382 two definitions were merged.
1384 This option is no longer useful on most targets, now that support has
1385 been added for putting variables into BSS without making them common.
1387 @item -fno-const-strings
1388 @opindex fno-const-strings
1389 Give string constants type @code{char *} instead of type @code{const
1390 char *}. By default, G++ uses type @code{const char *} as required by
1391 the standard. Even if you use @option{-fno-const-strings}, you cannot
1392 actually modify the value of a string constant.
1394 This option might be removed in a future release of G++. For maximum
1395 portability, you should structure your code so that it works with
1396 string constants that have type @code{const char *}.
1398 @item -fno-elide-constructors
1399 @opindex fno-elide-constructors
1400 The C++ standard allows an implementation to omit creating a temporary
1401 which is only used to initialize another object of the same type.
1402 Specifying this option disables that optimization, and forces G++ to
1403 call the copy constructor in all cases.
1405 @item -fno-enforce-eh-specs
1406 @opindex fno-enforce-eh-specs
1407 Don't check for violation of exception specifications at runtime. This
1408 option violates the C++ standard, but may be useful for reducing code
1409 size in production builds, much like defining @samp{NDEBUG}. The compiler
1410 will still optimize based on the exception specifications.
1413 @itemx -fno-for-scope
1415 @opindex fno-for-scope
1416 If @option{-ffor-scope} is specified, the scope of variables declared in
1417 a @i{for-init-statement} is limited to the @samp{for} loop itself,
1418 as specified by the C++ standard.
1419 If @option{-fno-for-scope} is specified, the scope of variables declared in
1420 a @i{for-init-statement} extends to the end of the enclosing scope,
1421 as was the case in old versions of G++, and other (traditional)
1422 implementations of C++.
1424 The default if neither flag is given to follow the standard,
1425 but to allow and give a warning for old-style code that would
1426 otherwise be invalid, or have different behavior.
1428 @item -fno-gnu-keywords
1429 @opindex fno-gnu-keywords
1430 Do not recognize @code{typeof} as a keyword, so that code can use this
1431 word as an identifier. You can use the keyword @code{__typeof__} instead.
1432 @option{-ansi} implies @option{-fno-gnu-keywords}.
1434 @item -fno-implicit-templates
1435 @opindex fno-implicit-templates
1436 Never emit code for non-inline templates which are instantiated
1437 implicitly (i.e.@: by use); only emit code for explicit instantiations.
1438 @xref{Template Instantiation}, for more information.
1440 @item -fno-implicit-inline-templates
1441 @opindex fno-implicit-inline-templates
1442 Don't emit code for implicit instantiations of inline templates, either.
1443 The default is to handle inlines differently so that compiles with and
1444 without optimization will need the same set of explicit instantiations.
1446 @item -fno-implement-inlines
1447 @opindex fno-implement-inlines
1448 To save space, do not emit out-of-line copies of inline functions
1449 controlled by @samp{#pragma implementation}. This will cause linker
1450 errors if these functions are not inlined everywhere they are called.
1452 @item -fms-extensions
1453 @opindex fms-extensions
1454 Disable pedantic warnings about constructs used in MFC, such as implicit
1455 int and getting a pointer to member function via non-standard syntax.
1457 @item -fno-nonansi-builtins
1458 @opindex fno-nonansi-builtins
1459 Disable built-in declarations of functions that are not mandated by
1460 ANSI/ISO C@. These include @code{ffs}, @code{alloca}, @code{_exit},
1461 @code{index}, @code{bzero}, @code{conjf}, and other related functions.
1463 @item -fno-operator-names
1464 @opindex fno-operator-names
1465 Do not treat the operator name keywords @code{and}, @code{bitand},
1466 @code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1467 synonyms as keywords.
1469 @item -fno-optional-diags
1470 @opindex fno-optional-diags
1471 Disable diagnostics that the standard says a compiler does not need to
1472 issue. Currently, the only such diagnostic issued by G++ is the one for
1473 a name having multiple meanings within a class.
1476 @opindex fpermissive
1477 Downgrade some diagnostics about nonconformant code from errors to
1478 warnings. Thus, using @option{-fpermissive} will allow some
1479 nonconforming code to compile.
1483 Enable automatic template instantiation at link time. This option also
1484 implies @option{-fno-implicit-templates}. @xref{Template
1485 Instantiation}, for more information.
1489 Disable generation of information about every class with virtual
1490 functions for use by the C++ runtime type identification features
1491 (@samp{dynamic_cast} and @samp{typeid}). If you don't use those parts
1492 of the language, you can save some space by using this flag. Note that
1493 exception handling uses the same information, but it will generate it as
1498 Emit statistics about front-end processing at the end of the compilation.
1499 This information is generally only useful to the G++ development team.
1501 @item -ftemplate-depth-@var{n}
1502 @opindex ftemplate-depth
1503 Set the maximum instantiation depth for template classes to @var{n}.
1504 A limit on the template instantiation depth is needed to detect
1505 endless recursions during template class instantiation. ANSI/ISO C++
1506 conforming programs must not rely on a maximum depth greater than 17.
1508 @item -fno-threadsafe-statics
1509 @opindex fno-threadsafe-statics
1510 Do not emit the extra code to use the routines specified in the C++
1511 ABI for thread-safe initialization of local statics. You can use this
1512 option to reduce code size slightly in code that doesn't need to be
1515 @item -fuse-cxa-atexit
1516 @opindex fuse-cxa-atexit
1517 Register destructors for objects with static storage duration with the
1518 @code{__cxa_atexit} function rather than the @code{atexit} function.
1519 This option is required for fully standards-compliant handling of static
1520 destructors, but will only work if your C library supports
1521 @code{__cxa_atexit}.
1523 @item -fvisibility-inlines-hidden
1524 @opindex fvisibility-inlines-hidden
1525 Causes all inlined methods to be marked with
1526 @code{__attribute__ ((visibility ("hidden")))} so that they do not
1527 appear in the export table of a DSO and do not require a PLT indirection
1528 when used within the DSO@. Enabling this option can have a dramatic effect
1529 on load and link times of a DSO as it massively reduces the size of the
1530 dynamic export table when the library makes heavy use of templates. While
1531 it can cause bloating through duplication of code within each DSO where
1532 it is used, often the wastage is less than the considerable space occupied
1533 by a long symbol name in the export table which is typical when using
1534 templates and namespaces. For even more savings, combine with the
1535 @option{-fvisibility=hidden} switch.
1539 Do not use weak symbol support, even if it is provided by the linker.
1540 By default, G++ will use weak symbols if they are available. This
1541 option exists only for testing, and should not be used by end-users;
1542 it will result in inferior code and has no benefits. This option may
1543 be removed in a future release of G++.
1547 Do not search for header files in the standard directories specific to
1548 C++, but do still search the other standard directories. (This option
1549 is used when building the C++ library.)
1552 In addition, these optimization, warning, and code generation options
1553 have meanings only for C++ programs:
1556 @item -fno-default-inline
1557 @opindex fno-default-inline
1558 Do not assume @samp{inline} for functions defined inside a class scope.
1559 @xref{Optimize Options,,Options That Control Optimization}. Note that these
1560 functions will have linkage like inline functions; they just won't be
1563 @item -Wabi @r{(C++ only)}
1565 Warn when G++ generates code that is probably not compatible with the
1566 vendor-neutral C++ ABI@. Although an effort has been made to warn about
1567 all such cases, there are probably some cases that are not warned about,
1568 even though G++ is generating incompatible code. There may also be
1569 cases where warnings are emitted even though the code that is generated
1572 You should rewrite your code to avoid these warnings if you are
1573 concerned about the fact that code generated by G++ may not be binary
1574 compatible with code generated by other compilers.
1576 The known incompatibilities at this point include:
1581 Incorrect handling of tail-padding for bit-fields. G++ may attempt to
1582 pack data into the same byte as a base class. For example:
1585 struct A @{ virtual void f(); int f1 : 1; @};
1586 struct B : public A @{ int f2 : 1; @};
1590 In this case, G++ will place @code{B::f2} into the same byte
1591 as@code{A::f1}; other compilers will not. You can avoid this problem
1592 by explicitly padding @code{A} so that its size is a multiple of the
1593 byte size on your platform; that will cause G++ and other compilers to
1594 layout @code{B} identically.
1597 Incorrect handling of tail-padding for virtual bases. G++ does not use
1598 tail padding when laying out virtual bases. For example:
1601 struct A @{ virtual void f(); char c1; @};
1602 struct B @{ B(); char c2; @};
1603 struct C : public A, public virtual B @{@};
1607 In this case, G++ will not place @code{B} into the tail-padding for
1608 @code{A}; other compilers will. You can avoid this problem by
1609 explicitly padding @code{A} so that its size is a multiple of its
1610 alignment (ignoring virtual base classes); that will cause G++ and other
1611 compilers to layout @code{C} identically.
1614 Incorrect handling of bit-fields with declared widths greater than that
1615 of their underlying types, when the bit-fields appear in a union. For
1619 union U @{ int i : 4096; @};
1623 Assuming that an @code{int} does not have 4096 bits, G++ will make the
1624 union too small by the number of bits in an @code{int}.
1627 Empty classes can be placed at incorrect offsets. For example:
1637 struct C : public B, public A @{@};
1641 G++ will place the @code{A} base class of @code{C} at a nonzero offset;
1642 it should be placed at offset zero. G++ mistakenly believes that the
1643 @code{A} data member of @code{B} is already at offset zero.
1646 Names of template functions whose types involve @code{typename} or
1647 template template parameters can be mangled incorrectly.
1650 template <typename Q>
1651 void f(typename Q::X) @{@}
1653 template <template <typename> class Q>
1654 void f(typename Q<int>::X) @{@}
1658 Instantiations of these templates may be mangled incorrectly.
1662 @item -Wctor-dtor-privacy @r{(C++ only)}
1663 @opindex Wctor-dtor-privacy
1664 Warn when a class seems unusable because all the constructors or
1665 destructors in that class are private, and it has neither friends nor
1666 public static member functions.
1668 @item -Wnon-virtual-dtor @r{(C++ only)}
1669 @opindex Wnon-virtual-dtor
1670 Warn when a class appears to be polymorphic, thereby requiring a virtual
1671 destructor, yet it declares a non-virtual one.
1672 This warning is enabled by @option{-Wall}.
1674 @item -Wreorder @r{(C++ only)}
1676 @cindex reordering, warning
1677 @cindex warning for reordering of member initializers
1678 Warn when the order of member initializers given in the code does not
1679 match the order in which they must be executed. For instance:
1685 A(): j (0), i (1) @{ @}
1689 The compiler will rearrange the member initializers for @samp{i}
1690 and @samp{j} to match the declaration order of the members, emitting
1691 a warning to that effect. This warning is enabled by @option{-Wall}.
1694 The following @option{-W@dots{}} options are not affected by @option{-Wall}.
1697 @item -Weffc++ @r{(C++ only)}
1699 Warn about violations of the following style guidelines from Scott Meyers'
1700 @cite{Effective C++} book:
1704 Item 11: Define a copy constructor and an assignment operator for classes
1705 with dynamically allocated memory.
1708 Item 12: Prefer initialization to assignment in constructors.
1711 Item 14: Make destructors virtual in base classes.
1714 Item 15: Have @code{operator=} return a reference to @code{*this}.
1717 Item 23: Don't try to return a reference when you must return an object.
1721 Also warn about violations of the following style guidelines from
1722 Scott Meyers' @cite{More Effective C++} book:
1726 Item 6: Distinguish between prefix and postfix forms of increment and
1727 decrement operators.
1730 Item 7: Never overload @code{&&}, @code{||}, or @code{,}.
1734 When selecting this option, be aware that the standard library
1735 headers do not obey all of these guidelines; use @samp{grep -v}
1736 to filter out those warnings.
1738 @item -Wno-deprecated @r{(C++ only)}
1739 @opindex Wno-deprecated
1740 Do not warn about usage of deprecated features. @xref{Deprecated Features}.
1742 @item -Wno-non-template-friend @r{(C++ only)}
1743 @opindex Wno-non-template-friend
1744 Disable warnings when non-templatized friend functions are declared
1745 within a template. Since the advent of explicit template specification
1746 support in G++, if the name of the friend is an unqualified-id (i.e.,
1747 @samp{friend foo(int)}), the C++ language specification demands that the
1748 friend declare or define an ordinary, nontemplate function. (Section
1749 14.5.3). Before G++ implemented explicit specification, unqualified-ids
1750 could be interpreted as a particular specialization of a templatized
1751 function. Because this non-conforming behavior is no longer the default
1752 behavior for G++, @option{-Wnon-template-friend} allows the compiler to
1753 check existing code for potential trouble spots and is on by default.
1754 This new compiler behavior can be turned off with
1755 @option{-Wno-non-template-friend} which keeps the conformant compiler code
1756 but disables the helpful warning.
1758 @item -Wold-style-cast @r{(C++ only)}
1759 @opindex Wold-style-cast
1760 Warn if an old-style (C-style) cast to a non-void type is used within
1761 a C++ program. The new-style casts (@samp{static_cast},
1762 @samp{reinterpret_cast}, and @samp{const_cast}) are less vulnerable to
1763 unintended effects and much easier to search for.
1765 @item -Woverloaded-virtual @r{(C++ only)}
1766 @opindex Woverloaded-virtual
1767 @cindex overloaded virtual fn, warning
1768 @cindex warning for overloaded virtual fn
1769 Warn when a function declaration hides virtual functions from a
1770 base class. For example, in:
1777 struct B: public A @{
1782 the @code{A} class version of @code{f} is hidden in @code{B}, and code
1790 will fail to compile.
1792 @item -Wno-pmf-conversions @r{(C++ only)}
1793 @opindex Wno-pmf-conversions
1794 Disable the diagnostic for converting a bound pointer to member function
1797 @item -Wsign-promo @r{(C++ only)}
1798 @opindex Wsign-promo
1799 Warn when overload resolution chooses a promotion from unsigned or
1800 enumerated type to a signed type, over a conversion to an unsigned type of
1801 the same size. Previous versions of G++ would try to preserve
1802 unsignedness, but the standard mandates the current behavior.
1807 A& operator = (int);
1817 In this example, G++ will synthesize a default @samp{A& operator =
1818 (const A&);}, while cfront will use the user-defined @samp{operator =}.
1821 @node Objective-C and Objective-C++ Dialect Options
1822 @section Options Controlling Objective-C and Objective-C++ Dialects
1824 @cindex compiler options, Objective-C and Objective-C++
1825 @cindex Objective-C and Objective-C++ options, command line
1826 @cindex options, Objective-C and Objective-C++
1827 (NOTE: This manual does not describe the Objective-C and Objective-C++
1828 languages themselves. See @xref{Standards,,Language Standards
1829 Supported by GCC}, for references.)
1831 This section describes the command-line options that are only meaningful
1832 for Objective-C and Objective-C++ programs, but you can also use most of
1833 the language-independent GNU compiler options.
1834 For example, you might compile a file @code{some_class.m} like this:
1837 gcc -g -fgnu-runtime -O -c some_class.m
1841 In this example, @option{-fgnu-runtime} is an option meant only for
1842 Objective-C and Objective-C++ programs; you can use the other options with
1843 any language supported by GCC@.
1845 Note that since Objective-C is an extension of the C language, Objective-C
1846 compilations may also use options specific to the C front-end (e.g.,
1847 @option{-Wtraditional}). Similarly, Objective-C++ compilations may use
1848 C++-specific options (e.g., @option{-Wabi}).
1850 Here is a list of options that are @emph{only} for compiling Objective-C
1851 and Objective-C++ programs:
1854 @item -fconstant-string-class=@var{class-name}
1855 @opindex fconstant-string-class
1856 Use @var{class-name} as the name of the class to instantiate for each
1857 literal string specified with the syntax @code{@@"@dots{}"}. The default
1858 class name is @code{NXConstantString} if the GNU runtime is being used, and
1859 @code{NSConstantString} if the NeXT runtime is being used (see below). The
1860 @option{-fconstant-cfstrings} option, if also present, will override the
1861 @option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} literals
1862 to be laid out as constant CoreFoundation strings.
1865 @opindex fgnu-runtime
1866 Generate object code compatible with the standard GNU Objective-C
1867 runtime. This is the default for most types of systems.
1869 @item -fnext-runtime
1870 @opindex fnext-runtime
1871 Generate output compatible with the NeXT runtime. This is the default
1872 for NeXT-based systems, including Darwin and Mac OS X@. The macro
1873 @code{__NEXT_RUNTIME__} is predefined if (and only if) this option is
1876 @item -fno-nil-receivers
1877 @opindex fno-nil-receivers
1878 Assume that all Objective-C message dispatches (e.g.,
1879 @code{[receiver message:arg]}) in this translation unit ensure that the receiver
1880 is not @code{nil}. This allows for more efficient entry points in the runtime
1881 to be used. Currently, this option is only available in conjunction with
1882 the NeXT runtime on Mac OS X 10.3 and later.
1884 @item -fobjc-exceptions
1885 @opindex fobjc-exceptions
1886 Enable syntactic support for structured exception handling in Objective-C,
1887 similar to what is offered by C++ and Java. Currently, this option is only
1888 available in conjunction with the NeXT runtime on Mac OS X 10.3 and later.
1896 @@catch (AnObjCClass *exc) @{
1903 @@catch (AnotherClass *exc) @{
1906 @@catch (id allOthers) @{
1916 The @code{@@throw} statement may appear anywhere in an Objective-C or
1917 Objective-C++ program; when used inside of a @code{@@catch} block, the
1918 @code{@@throw} may appear without an argument (as shown above), in which case
1919 the object caught by the @code{@@catch} will be rethrown.
1921 Note that only (pointers to) Objective-C objects may be thrown and
1922 caught using this scheme. When an object is thrown, it will be caught
1923 by the nearest @code{@@catch} clause capable of handling objects of that type,
1924 analogously to how @code{catch} blocks work in C++ and Java. A
1925 @code{@@catch(id @dots{})} clause (as shown above) may also be provided to catch
1926 any and all Objective-C exceptions not caught by previous @code{@@catch}
1929 The @code{@@finally} clause, if present, will be executed upon exit from the
1930 immediately preceding @code{@@try @dots{} @@catch} section. This will happen
1931 regardless of whether any exceptions are thrown, caught or rethrown
1932 inside the @code{@@try @dots{} @@catch} section, analogously to the behavior
1933 of the @code{finally} clause in Java.
1935 There are several caveats to using the new exception mechanism:
1939 Although currently designed to be binary compatible with @code{NS_HANDLER}-style
1940 idioms provided by the @code{NSException} class, the new
1941 exceptions can only be used on Mac OS X 10.3 (Panther) and later
1942 systems, due to additional functionality needed in the (NeXT) Objective-C
1946 As mentioned above, the new exceptions do not support handling
1947 types other than Objective-C objects. Furthermore, when used from
1948 Objective-C++, the Objective-C exception model does not interoperate with C++
1949 exceptions at this time. This means you cannot @code{@@throw} an exception
1950 from Objective-C and @code{catch} it in C++, or vice versa
1951 (i.e., @code{throw @dots{} @@catch}).
1954 The @option{-fobjc-exceptions} switch also enables the use of synchronization
1955 blocks for thread-safe execution:
1958 @@synchronized (ObjCClass *guard) @{
1963 Upon entering the @code{@@synchronized} block, a thread of execution shall
1964 first check whether a lock has been placed on the corresponding @code{guard}
1965 object by another thread. If it has, the current thread shall wait until
1966 the other thread relinquishes its lock. Once @code{guard} becomes available,
1967 the current thread will place its own lock on it, execute the code contained in
1968 the @code{@@synchronized} block, and finally relinquish the lock (thereby
1969 making @code{guard} available to other threads).
1971 Unlike Java, Objective-C does not allow for entire methods to be marked
1972 @code{@@synchronized}. Note that throwing exceptions out of
1973 @code{@@synchronized} blocks is allowed, and will cause the guarding object
1974 to be unlocked properly.
1976 @item -freplace-objc-classes
1977 @opindex freplace-objc-classes
1978 Emit a special marker instructing @command{ld(1)} not to statically link in
1979 the resulting object file, and allow @command{dyld(1)} to load it in at
1980 run time instead. This is used in conjunction with the Fix-and-Continue
1981 debugging mode, where the object file in question may be recompiled and
1982 dynamically reloaded in the course of program execution, without the need
1983 to restart the program itself. Currently, Fix-and-Continue functionality
1984 is only available in conjunction with the NeXT runtime on Mac OS X 10.3
1989 When compiling for the NeXT runtime, the compiler ordinarily replaces calls
1990 to @code{objc_getClass("@dots{}")} (when the name of the class is known at
1991 compile time) with static class references that get initialized at load time,
1992 which improves run-time performance. Specifying the @option{-fzero-link} flag
1993 suppresses this behavior and causes calls to @code{objc_getClass("@dots{}")}
1994 to be retained. This is useful in Zero-Link debugging mode, since it allows
1995 for individual class implementations to be modified during program execution.
1999 Dump interface declarations for all classes seen in the source file to a
2000 file named @file{@var{sourcename}.decl}.
2003 @opindex Wno-protocol
2004 If a class is declared to implement a protocol, a warning is issued for
2005 every method in the protocol that is not implemented by the class. The
2006 default behavior is to issue a warning for every method not explicitly
2007 implemented in the class, even if a method implementation is inherited
2008 from the superclass. If you use the @option{-Wno-protocol} option, then
2009 methods inherited from the superclass are considered to be implemented,
2010 and no warning is issued for them.
2014 Warn if multiple methods of different types for the same selector are
2015 found during compilation. The check is performed on the list of methods
2016 in the final stage of compilation. Additionally, a check is performed
2017 for each selector appearing in a @code{@@selector(@dots{})}
2018 expression, and a corresponding method for that selector has been found
2019 during compilation. Because these checks scan the method table only at
2020 the end of compilation, these warnings are not produced if the final
2021 stage of compilation is not reached, for example because an error is
2022 found during compilation, or because the @option{-fsyntax-only} option is
2025 @item -Wundeclared-selector
2026 @opindex Wundeclared-selector
2027 Warn if a @code{@@selector(@dots{})} expression referring to an
2028 undeclared selector is found. A selector is considered undeclared if no
2029 method with that name has been declared before the
2030 @code{@@selector(@dots{})} expression, either explicitly in an
2031 @code{@@interface} or @code{@@protocol} declaration, or implicitly in
2032 an @code{@@implementation} section. This option always performs its
2033 checks as soon as a @code{@@selector(@dots{})} expression is found,
2034 while @option{-Wselector} only performs its checks in the final stage of
2035 compilation. This also enforces the coding style convention
2036 that methods and selectors must be declared before being used.
2038 @item -print-objc-runtime-info
2039 @opindex print-objc-runtime-info
2040 Generate C header describing the largest structure that is passed by
2045 @node Language Independent Options
2046 @section Options to Control Diagnostic Messages Formatting
2047 @cindex options to control diagnostics formatting
2048 @cindex diagnostic messages
2049 @cindex message formatting
2051 Traditionally, diagnostic messages have been formatted irrespective of
2052 the output device's aspect (e.g.@: its width, @dots{}). The options described
2053 below can be used to control the diagnostic messages formatting
2054 algorithm, e.g.@: how many characters per line, how often source location
2055 information should be reported. Right now, only the C++ front end can
2056 honor these options. However it is expected, in the near future, that
2057 the remaining front ends would be able to digest them correctly.
2060 @item -fmessage-length=@var{n}
2061 @opindex fmessage-length
2062 Try to format error messages so that they fit on lines of about @var{n}
2063 characters. The default is 72 characters for @command{g++} and 0 for the rest of
2064 the front ends supported by GCC@. If @var{n} is zero, then no
2065 line-wrapping will be done; each error message will appear on a single
2068 @opindex fdiagnostics-show-location
2069 @item -fdiagnostics-show-location=once
2070 Only meaningful in line-wrapping mode. Instructs the diagnostic messages
2071 reporter to emit @emph{once} source location information; that is, in
2072 case the message is too long to fit on a single physical line and has to
2073 be wrapped, the source location won't be emitted (as prefix) again,
2074 over and over, in subsequent continuation lines. This is the default
2077 @item -fdiagnostics-show-location=every-line
2078 Only meaningful in line-wrapping mode. Instructs the diagnostic
2079 messages reporter to emit the same source location information (as
2080 prefix) for physical lines that result from the process of breaking
2081 a message which is too long to fit on a single line.
2085 @node Warning Options
2086 @section Options to Request or Suppress Warnings
2087 @cindex options to control warnings
2088 @cindex warning messages
2089 @cindex messages, warning
2090 @cindex suppressing warnings
2092 Warnings are diagnostic messages that report constructions which
2093 are not inherently erroneous but which are risky or suggest there
2094 may have been an error.
2096 You can request many specific warnings with options beginning @samp{-W},
2097 for example @option{-Wimplicit} to request warnings on implicit
2098 declarations. Each of these specific warning options also has a
2099 negative form beginning @samp{-Wno-} to turn off warnings;
2100 for example, @option{-Wno-implicit}. This manual lists only one of the
2101 two forms, whichever is not the default.
2103 The following options control the amount and kinds of warnings produced
2104 by GCC; for further, language-specific options also refer to
2105 @ref{C++ Dialect Options} and @ref{Objective-C and Objective-C++ Dialect
2109 @cindex syntax checking
2111 @opindex fsyntax-only
2112 Check the code for syntax errors, but don't do anything beyond that.
2116 Issue all the warnings demanded by strict ISO C and ISO C++;
2117 reject all programs that use forbidden extensions, and some other
2118 programs that do not follow ISO C and ISO C++. For ISO C, follows the
2119 version of the ISO C standard specified by any @option{-std} option used.
2121 Valid ISO C and ISO C++ programs should compile properly with or without
2122 this option (though a rare few will require @option{-ansi} or a
2123 @option{-std} option specifying the required version of ISO C)@. However,
2124 without this option, certain GNU extensions and traditional C and C++
2125 features are supported as well. With this option, they are rejected.
2127 @option{-pedantic} does not cause warning messages for use of the
2128 alternate keywords whose names begin and end with @samp{__}. Pedantic
2129 warnings are also disabled in the expression that follows
2130 @code{__extension__}. However, only system header files should use
2131 these escape routes; application programs should avoid them.
2132 @xref{Alternate Keywords}.
2134 Some users try to use @option{-pedantic} to check programs for strict ISO
2135 C conformance. They soon find that it does not do quite what they want:
2136 it finds some non-ISO practices, but not all---only those for which
2137 ISO C @emph{requires} a diagnostic, and some others for which
2138 diagnostics have been added.
2140 A feature to report any failure to conform to ISO C might be useful in
2141 some instances, but would require considerable additional work and would
2142 be quite different from @option{-pedantic}. We don't have plans to
2143 support such a feature in the near future.
2145 Where the standard specified with @option{-std} represents a GNU
2146 extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
2147 corresponding @dfn{base standard}, the version of ISO C on which the GNU
2148 extended dialect is based. Warnings from @option{-pedantic} are given
2149 where they are required by the base standard. (It would not make sense
2150 for such warnings to be given only for features not in the specified GNU
2151 C dialect, since by definition the GNU dialects of C include all
2152 features the compiler supports with the given option, and there would be
2153 nothing to warn about.)
2155 @item -pedantic-errors
2156 @opindex pedantic-errors
2157 Like @option{-pedantic}, except that errors are produced rather than
2162 Inhibit all warning messages.
2166 Inhibit warning messages about the use of @samp{#import}.
2168 @item -Wchar-subscripts
2169 @opindex Wchar-subscripts
2170 Warn if an array subscript has type @code{char}. This is a common cause
2171 of error, as programmers often forget that this type is signed on some
2173 This warning is enabled by @option{-Wall}.
2177 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
2178 comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
2179 This warning is enabled by @option{-Wall}.
2181 @item -Wfatal-errors
2182 @opindex Wfatal-errors
2183 This option causes the compiler to abort compilation on the first error
2184 occurred rather than trying to keep going and printing further error
2189 @opindex ffreestanding
2190 @opindex fno-builtin
2191 Check calls to @code{printf} and @code{scanf}, etc., to make sure that
2192 the arguments supplied have types appropriate to the format string
2193 specified, and that the conversions specified in the format string make
2194 sense. This includes standard functions, and others specified by format
2195 attributes (@pxref{Function Attributes}), in the @code{printf},
2196 @code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
2197 not in the C standard) families (or other target-specific families).
2198 Which functions are checked without format attributes having been
2199 specified depends on the standard version selected, and such checks of
2200 functions without the attribute specified are disabled by
2201 @option{-ffreestanding} or @option{-fno-builtin}.
2203 The formats are checked against the format features supported by GNU
2204 libc version 2.2. These include all ISO C90 and C99 features, as well
2205 as features from the Single Unix Specification and some BSD and GNU
2206 extensions. Other library implementations may not support all these
2207 features; GCC does not support warning about features that go beyond a
2208 particular library's limitations. However, if @option{-pedantic} is used
2209 with @option{-Wformat}, warnings will be given about format features not
2210 in the selected standard version (but not for @code{strfmon} formats,
2211 since those are not in any version of the C standard). @xref{C Dialect
2212 Options,,Options Controlling C Dialect}.
2214 Since @option{-Wformat} also checks for null format arguments for
2215 several functions, @option{-Wformat} also implies @option{-Wnonnull}.
2217 @option{-Wformat} is included in @option{-Wall}. For more control over some
2218 aspects of format checking, the options @option{-Wformat-y2k},
2219 @option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
2220 @option{-Wformat-nonliteral}, @option{-Wformat-security}, and
2221 @option{-Wformat=2} are available, but are not included in @option{-Wall}.
2224 @opindex Wformat-y2k
2225 If @option{-Wformat} is specified, also warn about @code{strftime}
2226 formats which may yield only a two-digit year.
2228 @item -Wno-format-extra-args
2229 @opindex Wno-format-extra-args
2230 If @option{-Wformat} is specified, do not warn about excess arguments to a
2231 @code{printf} or @code{scanf} format function. The C standard specifies
2232 that such arguments are ignored.
2234 Where the unused arguments lie between used arguments that are
2235 specified with @samp{$} operand number specifications, normally
2236 warnings are still given, since the implementation could not know what
2237 type to pass to @code{va_arg} to skip the unused arguments. However,
2238 in the case of @code{scanf} formats, this option will suppress the
2239 warning if the unused arguments are all pointers, since the Single
2240 Unix Specification says that such unused arguments are allowed.
2242 @item -Wno-format-zero-length
2243 @opindex Wno-format-zero-length
2244 If @option{-Wformat} is specified, do not warn about zero-length formats.
2245 The C standard specifies that zero-length formats are allowed.
2247 @item -Wformat-nonliteral
2248 @opindex Wformat-nonliteral
2249 If @option{-Wformat} is specified, also warn if the format string is not a
2250 string literal and so cannot be checked, unless the format function
2251 takes its format arguments as a @code{va_list}.
2253 @item -Wformat-security
2254 @opindex Wformat-security
2255 If @option{-Wformat} is specified, also warn about uses of format
2256 functions that represent possible security problems. At present, this
2257 warns about calls to @code{printf} and @code{scanf} functions where the
2258 format string is not a string literal and there are no format arguments,
2259 as in @code{printf (foo);}. This may be a security hole if the format
2260 string came from untrusted input and contains @samp{%n}. (This is
2261 currently a subset of what @option{-Wformat-nonliteral} warns about, but
2262 in future warnings may be added to @option{-Wformat-security} that are not
2263 included in @option{-Wformat-nonliteral}.)
2267 Enable @option{-Wformat} plus format checks not included in
2268 @option{-Wformat}. Currently equivalent to @samp{-Wformat
2269 -Wformat-nonliteral -Wformat-security -Wformat-y2k}.
2273 Warn about passing a null pointer for arguments marked as
2274 requiring a non-null value by the @code{nonnull} function attribute.
2276 @option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It
2277 can be disabled with the @option{-Wno-nonnull} option.
2279 @item -Winit-self @r{(C, C++, Objective-C and Objective-C++ only)}
2281 Warn about uninitialized variables which are initialized with themselves.
2282 Note this option can only be used with the @option{-Wuninitialized} option,
2283 which in turn only works with @option{-O1} and above.
2285 For example, GCC will warn about @code{i} being uninitialized in the
2286 following snippet only when @option{-Winit-self} has been specified:
2297 @item -Wimplicit-int
2298 @opindex Wimplicit-int
2299 Warn when a declaration does not specify a type.
2300 This warning is enabled by @option{-Wall}.
2302 @item -Wimplicit-function-declaration
2303 @itemx -Werror-implicit-function-declaration
2304 @opindex Wimplicit-function-declaration
2305 @opindex Werror-implicit-function-declaration
2306 Give a warning (or error) whenever a function is used before being
2307 declared. The form @option{-Wno-error-implicit-function-declaration}
2309 This warning is enabled by @option{-Wall} (as a warning, not an error).
2313 Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
2314 This warning is enabled by @option{-Wall}.
2318 Warn if the type of @samp{main} is suspicious. @samp{main} should be a
2319 function with external linkage, returning int, taking either zero
2320 arguments, two, or three arguments of appropriate types.
2321 This warning is enabled by @option{-Wall}.
2323 @item -Wmissing-braces
2324 @opindex Wmissing-braces
2325 Warn if an aggregate or union initializer is not fully bracketed. In
2326 the following example, the initializer for @samp{a} is not fully
2327 bracketed, but that for @samp{b} is fully bracketed.
2330 int a[2][2] = @{ 0, 1, 2, 3 @};
2331 int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
2334 This warning is enabled by @option{-Wall}.
2336 @item -Wmissing-include-dirs @r{(C, C++, Objective-C and Objective-C++ only)}
2337 @opindex Wmissing-include-dirs
2338 Warn if a user-supplied include directory does not exist.
2341 @opindex Wparentheses
2342 Warn if parentheses are omitted in certain contexts, such
2343 as when there is an assignment in a context where a truth value
2344 is expected, or when operators are nested whose precedence people
2345 often get confused about. Only the warning for an assignment used as
2346 a truth value is supported when compiling C++; the other warnings are
2347 only supported when compiling C@.
2349 Also warn if a comparison like @samp{x<=y<=z} appears; this is
2350 equivalent to @samp{(x<=y ? 1 : 0) <= z}, which is a different
2351 interpretation from that of ordinary mathematical notation.
2353 Also warn about constructions where there may be confusion to which
2354 @code{if} statement an @code{else} branch belongs. Here is an example of
2369 In C, every @code{else} branch belongs to the innermost possible @code{if}
2370 statement, which in this example is @code{if (b)}. This is often not
2371 what the programmer expected, as illustrated in the above example by
2372 indentation the programmer chose. When there is the potential for this
2373 confusion, GCC will issue a warning when this flag is specified.
2374 To eliminate the warning, add explicit braces around the innermost
2375 @code{if} statement so there is no way the @code{else} could belong to
2376 the enclosing @code{if}. The resulting code would look like this:
2392 This warning is enabled by @option{-Wall}.
2394 @item -Wsequence-point
2395 @opindex Wsequence-point
2396 Warn about code that may have undefined semantics because of violations
2397 of sequence point rules in the C standard.
2399 The C standard defines the order in which expressions in a C program are
2400 evaluated in terms of @dfn{sequence points}, which represent a partial
2401 ordering between the execution of parts of the program: those executed
2402 before the sequence point, and those executed after it. These occur
2403 after the evaluation of a full expression (one which is not part of a
2404 larger expression), after the evaluation of the first operand of a
2405 @code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
2406 function is called (but after the evaluation of its arguments and the
2407 expression denoting the called function), and in certain other places.
2408 Other than as expressed by the sequence point rules, the order of
2409 evaluation of subexpressions of an expression is not specified. All
2410 these rules describe only a partial order rather than a total order,
2411 since, for example, if two functions are called within one expression
2412 with no sequence point between them, the order in which the functions
2413 are called is not specified. However, the standards committee have
2414 ruled that function calls do not overlap.
2416 It is not specified when between sequence points modifications to the
2417 values of objects take effect. Programs whose behavior depends on this
2418 have undefined behavior; the C standard specifies that ``Between the
2419 previous and next sequence point an object shall have its stored value
2420 modified at most once by the evaluation of an expression. Furthermore,
2421 the prior value shall be read only to determine the value to be
2422 stored.''. If a program breaks these rules, the results on any
2423 particular implementation are entirely unpredictable.
2425 Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
2426 = b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
2427 diagnosed by this option, and it may give an occasional false positive
2428 result, but in general it has been found fairly effective at detecting
2429 this sort of problem in programs.
2431 The present implementation of this option only works for C programs. A
2432 future implementation may also work for C++ programs.
2434 The C standard is worded confusingly, therefore there is some debate
2435 over the precise meaning of the sequence point rules in subtle cases.
2436 Links to discussions of the problem, including proposed formal
2437 definitions, may be found on the GCC readings page, at
2438 @w{@uref{http://gcc.gnu.org/readings.html}}.
2440 This warning is enabled by @option{-Wall}.
2443 @opindex Wreturn-type
2444 Warn whenever a function is defined with a return-type that defaults to
2445 @code{int}. Also warn about any @code{return} statement with no
2446 return-value in a function whose return-type is not @code{void}.
2448 For C, also warn if the return type of a function has a type qualifier
2449 such as @code{const}. Such a type qualifier has no effect, since the
2450 value returned by a function is not an lvalue. ISO C prohibits
2451 qualified @code{void} return types on function definitions, so such
2452 return types always receive a warning even without this option.
2454 For C++, a function without return type always produces a diagnostic
2455 message, even when @option{-Wno-return-type} is specified. The only
2456 exceptions are @samp{main} and functions defined in system headers.
2458 This warning is enabled by @option{-Wall}.
2462 Warn whenever a @code{switch} statement has an index of enumerated type
2463 and lacks a @code{case} for one or more of the named codes of that
2464 enumeration. (The presence of a @code{default} label prevents this
2465 warning.) @code{case} labels outside the enumeration range also
2466 provoke warnings when this option is used.
2467 This warning is enabled by @option{-Wall}.
2469 @item -Wswitch-default
2470 @opindex Wswitch-switch
2471 Warn whenever a @code{switch} statement does not have a @code{default}
2475 @opindex Wswitch-enum
2476 Warn whenever a @code{switch} statement has an index of enumerated type
2477 and lacks a @code{case} for one or more of the named codes of that
2478 enumeration. @code{case} labels outside the enumeration range also
2479 provoke warnings when this option is used.
2483 Warn if any trigraphs are encountered that might change the meaning of
2484 the program (trigraphs within comments are not warned about).
2485 This warning is enabled by @option{-Wall}.
2487 @item -Wunused-function
2488 @opindex Wunused-function
2489 Warn whenever a static function is declared but not defined or a
2490 non\-inline static function is unused.
2491 This warning is enabled by @option{-Wall}.
2493 @item -Wunused-label
2494 @opindex Wunused-label
2495 Warn whenever a label is declared but not used.
2496 This warning is enabled by @option{-Wall}.
2498 To suppress this warning use the @samp{unused} attribute
2499 (@pxref{Variable Attributes}).
2501 @item -Wunused-parameter
2502 @opindex Wunused-parameter
2503 Warn whenever a function parameter is unused aside from its declaration.
2505 To suppress this warning use the @samp{unused} attribute
2506 (@pxref{Variable Attributes}).
2508 @item -Wunused-variable
2509 @opindex Wunused-variable
2510 Warn whenever a local variable or non-constant static variable is unused
2511 aside from its declaration
2512 This warning is enabled by @option{-Wall}.
2514 To suppress this warning use the @samp{unused} attribute
2515 (@pxref{Variable Attributes}).
2517 @item -Wunused-value
2518 @opindex Wunused-value
2519 Warn whenever a statement computes a result that is explicitly not used.
2520 This warning is enabled by @option{-Wall}.
2522 To suppress this warning cast the expression to @samp{void}.
2526 All the above @option{-Wunused} options combined.
2528 In order to get a warning about an unused function parameter, you must
2529 either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
2530 @samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
2532 @item -Wuninitialized
2533 @opindex Wuninitialized
2534 Warn if an automatic variable is used without first being initialized or
2535 if a variable may be clobbered by a @code{setjmp} call.
2537 These warnings are possible only in optimizing compilation,
2538 because they require data flow information that is computed only
2539 when optimizing. If you don't specify @option{-O}, you simply won't
2542 If you want to warn about code which uses the uninitialized value of the
2543 variable in its own initializer, use the @option{-Winit-self} option.
2545 These warnings occur only for variables that are candidates for
2546 register allocation. Therefore, they do not occur for a variable that
2547 is declared @code{volatile}, or whose address is taken, or whose size
2548 is other than 1, 2, 4 or 8 bytes. Also, they do not occur for
2549 structures, unions or arrays, even when they are in registers.
2551 Note that there may be no warning about a variable that is used only
2552 to compute a value that itself is never used, because such
2553 computations may be deleted by data flow analysis before the warnings
2556 These warnings are made optional because GCC is not smart
2557 enough to see all the reasons why the code might be correct
2558 despite appearing to have an error. Here is one example of how
2579 If the value of @code{y} is always 1, 2 or 3, then @code{x} is
2580 always initialized, but GCC doesn't know this. Here is
2581 another common case:
2586 if (change_y) save_y = y, y = new_y;
2588 if (change_y) y = save_y;
2593 This has no bug because @code{save_y} is used only if it is set.
2595 @cindex @code{longjmp} warnings
2596 This option also warns when a non-volatile automatic variable might be
2597 changed by a call to @code{longjmp}. These warnings as well are possible
2598 only in optimizing compilation.
2600 The compiler sees only the calls to @code{setjmp}. It cannot know
2601 where @code{longjmp} will be called; in fact, a signal handler could
2602 call it at any point in the code. As a result, you may get a warning
2603 even when there is in fact no problem because @code{longjmp} cannot
2604 in fact be called at the place which would cause a problem.
2606 Some spurious warnings can be avoided if you declare all the functions
2607 you use that never return as @code{noreturn}. @xref{Function
2610 This warning is enabled by @option{-Wall}.
2612 @item -Wunknown-pragmas
2613 @opindex Wunknown-pragmas
2614 @cindex warning for unknown pragmas
2615 @cindex unknown pragmas, warning
2616 @cindex pragmas, warning of unknown
2617 Warn when a #pragma directive is encountered which is not understood by
2618 GCC@. If this command line option is used, warnings will even be issued
2619 for unknown pragmas in system header files. This is not the case if
2620 the warnings were only enabled by the @option{-Wall} command line option.
2622 @item -Wstrict-aliasing
2623 @opindex Wstrict-aliasing
2624 This option is only active when @option{-fstrict-aliasing} is active.
2625 It warns about code which might break the strict aliasing rules that the
2626 compiler is using for optimization. The warning does not catch all
2627 cases, but does attempt to catch the more common pitfalls. It is
2628 included in @option{-Wall}.
2630 @item -Wstrict-aliasing=2
2631 @opindex Wstrict-aliasing=2
2632 This option is only active when @option{-fstrict-aliasing} is active.
2633 It warns about all code which might break the strict aliasing rules that the
2634 compiler is using for optimization. This warning catches all cases, but
2635 it will also give a warning for some ambiguous cases that are safe.
2639 All of the above @samp{-W} options combined. This enables all the
2640 warnings about constructions that some users consider questionable, and
2641 that are easy to avoid (or modify to prevent the warning), even in
2642 conjunction with macros. This also enables some language-specific
2643 warnings described in @ref{C++ Dialect Options} and
2644 @ref{Objective-C and Objective-C++ Dialect Options}.
2647 The following @option{-W@dots{}} options are not implied by @option{-Wall}.
2648 Some of them warn about constructions that users generally do not
2649 consider questionable, but which occasionally you might wish to check
2650 for; others warn about constructions that are necessary or hard to avoid
2651 in some cases, and there is no simple way to modify the code to suppress
2658 (This option used to be called @option{-W}. The older name is still
2659 supported, but the newer name is more descriptive.) Print extra warning
2660 messages for these events:
2664 A function can return either with or without a value. (Falling
2665 off the end of the function body is considered returning without
2666 a value.) For example, this function would evoke such a
2680 An expression-statement or the left-hand side of a comma expression
2681 contains no side effects.
2682 To suppress the warning, cast the unused expression to void.
2683 For example, an expression such as @samp{x[i,j]} will cause a warning,
2684 but @samp{x[(void)i,j]} will not.
2687 An unsigned value is compared against zero with @samp{<} or @samp{>=}.
2690 Storage-class specifiers like @code{static} are not the first things in
2691 a declaration. According to the C Standard, this usage is obsolescent.
2694 If @option{-Wall} or @option{-Wunused} is also specified, warn about unused
2698 A comparison between signed and unsigned values could produce an
2699 incorrect result when the signed value is converted to unsigned.
2700 (But don't warn if @option{-Wno-sign-compare} is also specified.)
2703 An aggregate has an initializer which does not initialize all members.
2704 This warning can be independently controlled by
2705 @option{-Wmissing-field-initializers}.
2708 A function parameter is declared without a type specifier in K&R-style
2716 An empty body occurs in an @samp{if} or @samp{else} statement.
2719 A pointer is compared against integer zero with @samp{<}, @samp{<=},
2720 @samp{>}, or @samp{>=}.
2723 A variable might be changed by @samp{longjmp} or @samp{vfork}.
2726 Any of several floating-point events that often indicate errors, such as
2727 overflow, underflow, loss of precision, etc.
2729 @item @r{(C++ only)}
2730 An enumerator and a non-enumerator both appear in a conditional expression.
2732 @item @r{(C++ only)}
2733 A non-static reference or non-static @samp{const} member appears in a
2734 class without constructors.
2736 @item @r{(C++ only)}
2737 Ambiguous virtual bases.
2739 @item @r{(C++ only)}
2740 Subscripting an array which has been declared @samp{register}.
2742 @item @r{(C++ only)}
2743 Taking the address of a variable which has been declared @samp{register}.
2745 @item @r{(C++ only)}
2746 A base class is not initialized in a derived class' copy constructor.
2749 @item -Wno-div-by-zero
2750 @opindex Wno-div-by-zero
2751 @opindex Wdiv-by-zero
2752 Do not warn about compile-time integer division by zero. Floating point
2753 division by zero is not warned about, as it can be a legitimate way of
2754 obtaining infinities and NaNs.
2756 @item -Wsystem-headers
2757 @opindex Wsystem-headers
2758 @cindex warnings from system headers
2759 @cindex system headers, warnings from
2760 Print warning messages for constructs found in system header files.
2761 Warnings from system headers are normally suppressed, on the assumption
2762 that they usually do not indicate real problems and would only make the
2763 compiler output harder to read. Using this command line option tells
2764 GCC to emit warnings from system headers as if they occurred in user
2765 code. However, note that using @option{-Wall} in conjunction with this
2766 option will @emph{not} warn about unknown pragmas in system
2767 headers---for that, @option{-Wunknown-pragmas} must also be used.
2770 @opindex Wfloat-equal
2771 Warn if floating point values are used in equality comparisons.
2773 The idea behind this is that sometimes it is convenient (for the
2774 programmer) to consider floating-point values as approximations to
2775 infinitely precise real numbers. If you are doing this, then you need
2776 to compute (by analyzing the code, or in some other way) the maximum or
2777 likely maximum error that the computation introduces, and allow for it
2778 when performing comparisons (and when producing output, but that's a
2779 different problem). In particular, instead of testing for equality, you
2780 would check to see whether the two values have ranges that overlap; and
2781 this is done with the relational operators, so equality comparisons are
2784 @item -Wtraditional @r{(C only)}
2785 @opindex Wtraditional
2786 Warn about certain constructs that behave differently in traditional and
2787 ISO C@. Also warn about ISO C constructs that have no traditional C
2788 equivalent, and/or problematic constructs which should be avoided.
2792 Macro parameters that appear within string literals in the macro body.
2793 In traditional C macro replacement takes place within string literals,
2794 but does not in ISO C@.
2797 In traditional C, some preprocessor directives did not exist.
2798 Traditional preprocessors would only consider a line to be a directive
2799 if the @samp{#} appeared in column 1 on the line. Therefore
2800 @option{-Wtraditional} warns about directives that traditional C
2801 understands but would ignore because the @samp{#} does not appear as the
2802 first character on the line. It also suggests you hide directives like
2803 @samp{#pragma} not understood by traditional C by indenting them. Some
2804 traditional implementations would not recognize @samp{#elif}, so it
2805 suggests avoiding it altogether.
2808 A function-like macro that appears without arguments.
2811 The unary plus operator.
2814 The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
2815 constant suffixes. (Traditional C does support the @samp{L} suffix on integer
2816 constants.) Note, these suffixes appear in macros defined in the system
2817 headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
2818 Use of these macros in user code might normally lead to spurious
2819 warnings, however GCC's integrated preprocessor has enough context to
2820 avoid warning in these cases.
2823 A function declared external in one block and then used after the end of
2827 A @code{switch} statement has an operand of type @code{long}.
2830 A non-@code{static} function declaration follows a @code{static} one.
2831 This construct is not accepted by some traditional C compilers.
2834 The ISO type of an integer constant has a different width or
2835 signedness from its traditional type. This warning is only issued if
2836 the base of the constant is ten. I.e.@: hexadecimal or octal values, which
2837 typically represent bit patterns, are not warned about.
2840 Usage of ISO string concatenation is detected.
2843 Initialization of automatic aggregates.
2846 Identifier conflicts with labels. Traditional C lacks a separate
2847 namespace for labels.
2850 Initialization of unions. If the initializer is zero, the warning is
2851 omitted. This is done under the assumption that the zero initializer in
2852 user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
2853 initializer warnings and relies on default initialization to zero in the
2857 Conversions by prototypes between fixed/floating point values and vice
2858 versa. The absence of these prototypes when compiling with traditional
2859 C would cause serious problems. This is a subset of the possible
2860 conversion warnings, for the full set use @option{-Wconversion}.
2863 Use of ISO C style function definitions. This warning intentionally is
2864 @emph{not} issued for prototype declarations or variadic functions
2865 because these ISO C features will appear in your code when using
2866 libiberty's traditional C compatibility macros, @code{PARAMS} and
2867 @code{VPARAMS}. This warning is also bypassed for nested functions
2868 because that feature is already a GCC extension and thus not relevant to
2869 traditional C compatibility.
2872 @item -Wdeclaration-after-statement @r{(C only)}
2873 @opindex Wdeclaration-after-statement
2874 Warn when a declaration is found after a statement in a block. This
2875 construct, known from C++, was introduced with ISO C99 and is by default
2876 allowed in GCC@. It is not supported by ISO C90 and was not supported by
2877 GCC versions before GCC 3.0. @xref{Mixed Declarations}.
2881 Warn if an undefined identifier is evaluated in an @samp{#if} directive.
2883 @item -Wno-endif-labels
2884 @opindex Wno-endif-labels
2885 @opindex Wendif-labels
2886 Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
2890 Warn whenever a local variable shadows another local variable, parameter or
2891 global variable or whenever a built-in function is shadowed.
2893 @item -Wlarger-than-@var{len}
2894 @opindex Wlarger-than
2895 Warn whenever an object of larger than @var{len} bytes is defined.
2897 @item -Wpointer-arith
2898 @opindex Wpointer-arith
2899 Warn about anything that depends on the ``size of'' a function type or
2900 of @code{void}. GNU C assigns these types a size of 1, for
2901 convenience in calculations with @code{void *} pointers and pointers
2904 @item -Wbad-function-cast @r{(C only)}
2905 @opindex Wbad-function-cast
2906 Warn whenever a function call is cast to a non-matching type.
2907 For example, warn if @code{int malloc()} is cast to @code{anything *}.
2911 Warn whenever a pointer is cast so as to remove a type qualifier from
2912 the target type. For example, warn if a @code{const char *} is cast
2913 to an ordinary @code{char *}.
2916 @opindex Wcast-align
2917 Warn whenever a pointer is cast such that the required alignment of the
2918 target is increased. For example, warn if a @code{char *} is cast to
2919 an @code{int *} on machines where integers can only be accessed at
2920 two- or four-byte boundaries.
2922 @item -Wwrite-strings
2923 @opindex Wwrite-strings
2924 When compiling C, give string constants the type @code{const
2925 char[@var{length}]} so that
2926 copying the address of one into a non-@code{const} @code{char *}
2927 pointer will get a warning; when compiling C++, warn about the
2928 deprecated conversion from string constants to @code{char *}.
2929 These warnings will help you find at
2930 compile time code that can try to write into a string constant, but
2931 only if you have been very careful about using @code{const} in
2932 declarations and prototypes. Otherwise, it will just be a nuisance;
2933 this is why we did not make @option{-Wall} request these warnings.
2936 @opindex Wconversion
2937 Warn if a prototype causes a type conversion that is different from what
2938 would happen to the same argument in the absence of a prototype. This
2939 includes conversions of fixed point to floating and vice versa, and
2940 conversions changing the width or signedness of a fixed point argument
2941 except when the same as the default promotion.
2943 Also, warn if a negative integer constant expression is implicitly
2944 converted to an unsigned type. For example, warn about the assignment
2945 @code{x = -1} if @code{x} is unsigned. But do not warn about explicit
2946 casts like @code{(unsigned) -1}.
2948 @item -Wsign-compare
2949 @opindex Wsign-compare
2950 @cindex warning for comparison of signed and unsigned values
2951 @cindex comparison of signed and unsigned values, warning
2952 @cindex signed and unsigned values, comparison warning
2953 Warn when a comparison between signed and unsigned values could produce
2954 an incorrect result when the signed value is converted to unsigned.
2955 This warning is also enabled by @option{-Wextra}; to get the other warnings
2956 of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
2958 @item -Waggregate-return
2959 @opindex Waggregate-return
2960 Warn if any functions that return structures or unions are defined or
2961 called. (In languages where you can return an array, this also elicits
2964 @item -Wstrict-prototypes @r{(C only)}
2965 @opindex Wstrict-prototypes
2966 Warn if a function is declared or defined without specifying the
2967 argument types. (An old-style function definition is permitted without
2968 a warning if preceded by a declaration which specifies the argument
2971 @item -Wold-style-definition @r{(C only)}
2972 @opindex Wold-style-definition
2973 Warn if an old-style function definition is used. A warning is given
2974 even if there is a previous prototype.
2976 @item -Wmissing-prototypes @r{(C only)}
2977 @opindex Wmissing-prototypes
2978 Warn if a global function is defined without a previous prototype
2979 declaration. This warning is issued even if the definition itself
2980 provides a prototype. The aim is to detect global functions that fail
2981 to be declared in header files.
2983 @item -Wmissing-declarations @r{(C only)}
2984 @opindex Wmissing-declarations
2985 Warn if a global function is defined without a previous declaration.
2986 Do so even if the definition itself provides a prototype.
2987 Use this option to detect global functions that are not declared in
2990 @item -Wmissing-field-initializers
2991 @opindex Wmissing-field-initializers
2994 Warn if a structure's initializer has some fields missing. For
2995 example, the following code would cause such a warning, because
2996 @code{x.h} is implicitly zero:
2999 struct s @{ int f, g, h; @};
3000 struct s x = @{ 3, 4 @};
3003 This option does not warn about designated initializers, so the following
3004 modification would not trigger a warning:
3007 struct s @{ int f, g, h; @};
3008 struct s x = @{ .f = 3, .g = 4 @};
3011 This warning is included in @option{-Wextra}. To get other @option{-Wextra}
3012 warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
3014 @item -Wmissing-noreturn
3015 @opindex Wmissing-noreturn
3016 Warn about functions which might be candidates for attribute @code{noreturn}.
3017 Note these are only possible candidates, not absolute ones. Care should
3018 be taken to manually verify functions actually do not ever return before
3019 adding the @code{noreturn} attribute, otherwise subtle code generation
3020 bugs could be introduced. You will not get a warning for @code{main} in
3021 hosted C environments.
3023 @item -Wmissing-format-attribute
3024 @opindex Wmissing-format-attribute
3026 If @option{-Wformat} is enabled, also warn about functions which might be
3027 candidates for @code{format} attributes. Note these are only possible
3028 candidates, not absolute ones. GCC will guess that @code{format}
3029 attributes might be appropriate for any function that calls a function
3030 like @code{vprintf} or @code{vscanf}, but this might not always be the
3031 case, and some functions for which @code{format} attributes are
3032 appropriate may not be detected. This option has no effect unless
3033 @option{-Wformat} is enabled (possibly by @option{-Wall}).
3035 @item -Wno-multichar
3036 @opindex Wno-multichar
3038 Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
3039 Usually they indicate a typo in the user's code, as they have
3040 implementation-defined values, and should not be used in portable code.
3042 @item -Wnormalized=<none|id|nfc|nfkc>
3043 @opindex Wnormalized
3046 @cindex character set, input normalization
3047 In ISO C and ISO C++, two identifiers are different if they are
3048 different sequences of characters. However, sometimes when characters
3049 outside the basic ASCII character set are used, you can have two
3050 different character sequences that look the same. To avoid confusion,
3051 the ISO 10646 standard sets out some @dfn{normalization rules} which
3052 when applied ensure that two sequences that look the same are turned into
3053 the same sequence. GCC can warn you if you are using identifiers which
3054 have not been normalized; this option controls that warning.
3056 There are four levels of warning that GCC supports. The default is
3057 @option{-Wnormalized=nfc}, which warns about any identifier which is
3058 not in the ISO 10646 ``C'' normalized form, @dfn{NFC}. NFC is the
3059 recommended form for most uses.
3061 Unfortunately, there are some characters which ISO C and ISO C++ allow
3062 in identifiers that when turned into NFC aren't allowable as
3063 identifiers. That is, there's no way to use these symbols in portable
3064 ISO C or C++ and have all your identifiers in NFC.
3065 @option{-Wnormalized=id} suppresses the warning for these characters.
3066 It is hoped that future versions of the standards involved will correct
3067 this, which is why this option is not the default.
3069 You can switch the warning off for all characters by writing
3070 @option{-Wnormalized=none}. You would only want to do this if you
3071 were using some other normalization scheme (like ``D''), because
3072 otherwise you can easily create bugs that are literally impossible to see.
3074 Some characters in ISO 10646 have distinct meanings but look identical
3075 in some fonts or display methodologies, especially once formatting has
3076 been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
3077 LETTER N'', will display just like a regular @code{n} which has been
3078 placed in a superscript. ISO 10646 defines the @dfn{NFKC}
3079 normalisation scheme to convert all these into a standard form as
3080 well, and GCC will warn if your code is not in NFKC if you use
3081 @option{-Wnormalized=nfkc}. This warning is comparable to warning
3082 about every identifier that contains the letter O because it might be
3083 confused with the digit 0, and so is not the default, but may be
3084 useful as a local coding convention if the programming environment is
3085 unable to be fixed to display these characters distinctly.
3087 @item -Wno-deprecated-declarations
3088 @opindex Wno-deprecated-declarations
3089 Do not warn about uses of functions, variables, and types marked as
3090 deprecated by using the @code{deprecated} attribute.
3091 (@pxref{Function Attributes}, @pxref{Variable Attributes},
3092 @pxref{Type Attributes}.)
3096 Warn if a structure is given the packed attribute, but the packed
3097 attribute has no effect on the layout or size of the structure.
3098 Such structures may be mis-aligned for little benefit. For
3099 instance, in this code, the variable @code{f.x} in @code{struct bar}
3100 will be misaligned even though @code{struct bar} does not itself
3101 have the packed attribute:
3108 @} __attribute__((packed));
3118 Warn if padding is included in a structure, either to align an element
3119 of the structure or to align the whole structure. Sometimes when this
3120 happens it is possible to rearrange the fields of the structure to
3121 reduce the padding and so make the structure smaller.
3123 @item -Wredundant-decls
3124 @opindex Wredundant-decls
3125 Warn if anything is declared more than once in the same scope, even in
3126 cases where multiple declaration is valid and changes nothing.
3128 @item -Wnested-externs @r{(C only)}
3129 @opindex Wnested-externs
3130 Warn if an @code{extern} declaration is encountered within a function.
3132 @item -Wunreachable-code
3133 @opindex Wunreachable-code
3134 Warn if the compiler detects that code will never be executed.
3136 This option is intended to warn when the compiler detects that at
3137 least a whole line of source code will never be executed, because
3138 some condition is never satisfied or because it is after a
3139 procedure that never returns.
3141 It is possible for this option to produce a warning even though there
3142 are circumstances under which part of the affected line can be executed,
3143 so care should be taken when removing apparently-unreachable code.
3145 For instance, when a function is inlined, a warning may mean that the
3146 line is unreachable in only one inlined copy of the function.
3148 This option is not made part of @option{-Wall} because in a debugging
3149 version of a program there is often substantial code which checks
3150 correct functioning of the program and is, hopefully, unreachable
3151 because the program does work. Another common use of unreachable
3152 code is to provide behavior which is selectable at compile-time.
3156 Warn if a function can not be inlined and it was declared as inline.
3157 Even with this option, the compiler will not warn about failures to
3158 inline functions declared in system headers.
3160 The compiler uses a variety of heuristics to determine whether or not
3161 to inline a function. For example, the compiler takes into account
3162 the size of the function being inlined and the the amount of inlining
3163 that has already been done in the current function. Therefore,
3164 seemingly insignificant changes in the source program can cause the
3165 warnings produced by @option{-Winline} to appear or disappear.
3167 @item -Wno-invalid-offsetof @r{(C++ only)}
3168 @opindex Wno-invalid-offsetof
3169 Suppress warnings from applying the @samp{offsetof} macro to a non-POD
3170 type. According to the 1998 ISO C++ standard, applying @samp{offsetof}
3171 to a non-POD type is undefined. In existing C++ implementations,
3172 however, @samp{offsetof} typically gives meaningful results even when
3173 applied to certain kinds of non-POD types. (Such as a simple
3174 @samp{struct} that fails to be a POD type only by virtue of having a
3175 constructor.) This flag is for users who are aware that they are
3176 writing nonportable code and who have deliberately chosen to ignore the
3179 The restrictions on @samp{offsetof} may be relaxed in a future version
3180 of the C++ standard.
3183 @opindex Winvalid-pch
3184 Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
3185 the search path but can't be used.
3189 @opindex Wno-long-long
3190 Warn if @samp{long long} type is used. This is default. To inhibit
3191 the warning messages, use @option{-Wno-long-long}. Flags
3192 @option{-Wlong-long} and @option{-Wno-long-long} are taken into account
3193 only when @option{-pedantic} flag is used.
3195 @item -Wvariadic-macros
3196 @opindex Wvariadic-macros
3197 @opindex Wno-variadic-macros
3198 Warn if variadic macros are used in pedantic ISO C90 mode, or the GNU
3199 alternate syntax when in pedantic ISO C99 mode. This is default.
3200 To inhibit the warning messages, use @option{-Wno-variadic-macros}.
3202 @item -Wdisabled-optimization
3203 @opindex Wdisabled-optimization
3204 Warn if a requested optimization pass is disabled. This warning does
3205 not generally indicate that there is anything wrong with your code; it
3206 merely indicates that GCC's optimizers were unable to handle the code
3207 effectively. Often, the problem is that your code is too big or too
3208 complex; GCC will refuse to optimize programs when the optimization
3209 itself is likely to take inordinate amounts of time.
3211 @item -Wno-pointer-sign
3212 @opindex Wno-pointer-sign
3213 Don't warn for pointer argument passing or assignment with different signedness.
3214 Only useful in the negative form since this warning is enabled by default.
3215 This option is only supported for C and Objective-C@.
3219 Make all warnings into errors.
3222 @node Debugging Options
3223 @section Options for Debugging Your Program or GCC
3224 @cindex options, debugging
3225 @cindex debugging information options
3227 GCC has various special options that are used for debugging
3228 either your program or GCC:
3233 Produce debugging information in the operating system's native format
3234 (stabs, COFF, XCOFF, or DWARF 2)@. GDB can work with this debugging
3237 On most systems that use stabs format, @option{-g} enables use of extra
3238 debugging information that only GDB can use; this extra information
3239 makes debugging work better in GDB but will probably make other debuggers
3241 refuse to read the program. If you want to control for certain whether
3242 to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
3243 @option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
3245 GCC allows you to use @option{-g} with
3246 @option{-O}. The shortcuts taken by optimized code may occasionally
3247 produce surprising results: some variables you declared may not exist
3248 at all; flow of control may briefly move where you did not expect it;
3249 some statements may not be executed because they compute constant
3250 results or their values were already at hand; some statements may
3251 execute in different places because they were moved out of loops.
3253 Nevertheless it proves possible to debug optimized output. This makes
3254 it reasonable to use the optimizer for programs that might have bugs.
3256 The following options are useful when GCC is generated with the
3257 capability for more than one debugging format.
3261 Produce debugging information for use by GDB@. This means to use the
3262 most expressive format available (DWARF 2, stabs, or the native format
3263 if neither of those are supported), including GDB extensions if at all
3268 Produce debugging information in stabs format (if that is supported),
3269 without GDB extensions. This is the format used by DBX on most BSD
3270 systems. On MIPS, Alpha and System V Release 4 systems this option
3271 produces stabs debugging output which is not understood by DBX or SDB@.
3272 On System V Release 4 systems this option requires the GNU assembler.
3274 @item -feliminate-unused-debug-symbols
3275 @opindex feliminate-unused-debug-symbols
3276 Produce debugging information in stabs format (if that is supported),
3277 for only symbols that are actually used.
3281 Produce debugging information in stabs format (if that is supported),
3282 using GNU extensions understood only by the GNU debugger (GDB)@. The
3283 use of these extensions is likely to make other debuggers crash or
3284 refuse to read the program.
3288 Produce debugging information in COFF format (if that is supported).
3289 This is the format used by SDB on most System V systems prior to
3294 Produce debugging information in XCOFF format (if that is supported).
3295 This is the format used by the DBX debugger on IBM RS/6000 systems.
3299 Produce debugging information in XCOFF format (if that is supported),
3300 using GNU extensions understood only by the GNU debugger (GDB)@. The
3301 use of these extensions is likely to make other debuggers crash or
3302 refuse to read the program, and may cause assemblers other than the GNU
3303 assembler (GAS) to fail with an error.
3307 Produce debugging information in DWARF version 2 format (if that is
3308 supported). This is the format used by DBX on IRIX 6. With this
3309 option, GCC uses features of DWARF version 3 when they are useful;
3310 version 3 is upward compatible with version 2, but may still cause
3311 problems for older debuggers.
3315 Produce debugging information in VMS debug format (if that is
3316 supported). This is the format used by DEBUG on VMS systems.
3319 @itemx -ggdb@var{level}
3320 @itemx -gstabs@var{level}
3321 @itemx -gcoff@var{level}
3322 @itemx -gxcoff@var{level}
3323 @itemx -gvms@var{level}
3324 Request debugging information and also use @var{level} to specify how
3325 much information. The default level is 2.
3327 Level 1 produces minimal information, enough for making backtraces in
3328 parts of the program that you don't plan to debug. This includes
3329 descriptions of functions and external variables, but no information
3330 about local variables and no line numbers.
3332 Level 3 includes extra information, such as all the macro definitions
3333 present in the program. Some debuggers support macro expansion when
3334 you use @option{-g3}.
3336 @option{-gdwarf-2} does not accept a concatenated debug level, because
3337 GCC used to support an option @option{-gdwarf} that meant to generate
3338 debug information in version 1 of the DWARF format (which is very
3339 different from version 2), and it would have been too confusing. That
3340 debug format is long obsolete, but the option cannot be changed now.
3341 Instead use an additional @option{-g@var{level}} option to change the
3342 debug level for DWARF2.
3344 @item -feliminate-dwarf2-dups
3345 @opindex feliminate-dwarf2-dups
3346 Compress DWARF2 debugging information by eliminating duplicated
3347 information about each symbol. This option only makes sense when
3348 generating DWARF2 debugging information with @option{-gdwarf-2}.
3350 @cindex @command{prof}
3353 Generate extra code to write profile information suitable for the
3354 analysis program @command{prof}. You must use this option when compiling
3355 the source files you want data about, and you must also use it when
3358 @cindex @command{gprof}
3361 Generate extra code to write profile information suitable for the
3362 analysis program @command{gprof}. You must use this option when compiling
3363 the source files you want data about, and you must also use it when
3368 Makes the compiler print out each function name as it is compiled, and
3369 print some statistics about each pass when it finishes.
3372 @opindex ftime-report
3373 Makes the compiler print some statistics about the time consumed by each
3374 pass when it finishes.
3377 @opindex fmem-report
3378 Makes the compiler print some statistics about permanent memory
3379 allocation when it finishes.
3381 @item -fprofile-arcs
3382 @opindex fprofile-arcs
3383 Add code so that program flow @dfn{arcs} are instrumented. During
3384 execution the program records how many times each branch and call is
3385 executed and how many times it is taken or returns. When the compiled
3386 program exits it saves this data to a file called
3387 @file{@var{auxname}.gcda} for each source file. The data may be used for
3388 profile-directed optimizations (@option{-fbranch-probabilities}), or for
3389 test coverage analysis (@option{-ftest-coverage}). Each object file's
3390 @var{auxname} is generated from the name of the output file, if
3391 explicitly specified and it is not the final executable, otherwise it is
3392 the basename of the source file. In both cases any suffix is removed
3393 (e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
3394 @file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
3396 @cindex @command{gcov}
3400 This option is used to compile and link code instrumented for coverage
3401 analysis. The option is a synonym for @option{-fprofile-arcs}
3402 @option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
3403 linking). See the documentation for those options for more details.
3408 Compile the source files with @option{-fprofile-arcs} plus optimization
3409 and code generation options. For test coverage analysis, use the
3410 additional @option{-ftest-coverage} option. You do not need to profile
3411 every source file in a program.
3414 Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
3415 (the latter implies the former).
3418 Run the program on a representative workload to generate the arc profile
3419 information. This may be repeated any number of times. You can run
3420 concurrent instances of your program, and provided that the file system
3421 supports locking, the data files will be correctly updated. Also
3422 @code{fork} calls are detected and correctly handled (double counting
3426 For profile-directed optimizations, compile the source files again with
3427 the same optimization and code generation options plus
3428 @option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
3429 Control Optimization}).
3432 For test coverage analysis, use @command{gcov} to produce human readable
3433 information from the @file{.gcno} and @file{.gcda} files. Refer to the
3434 @command{gcov} documentation for further information.
3438 With @option{-fprofile-arcs}, for each function of your program GCC
3439 creates a program flow graph, then finds a spanning tree for the graph.
3440 Only arcs that are not on the spanning tree have to be instrumented: the
3441 compiler adds code to count the number of times that these arcs are
3442 executed. When an arc is the only exit or only entrance to a block, the
3443 instrumentation code can be added to the block; otherwise, a new basic
3444 block must be created to hold the instrumentation code.
3446 @item -ftree-based-profiling
3447 @opindex ftree-based-profiling
3448 This option is used in addition to @option{-fprofile-arcs} or
3449 @option{-fbranch-probabilities} to control whether those optimizations
3450 are performed on a tree-based or rtl-based internal representation.
3451 If you use this option when compiling with @option{-fprofile-arcs},
3452 you must also use it when compiling later with @option{-fbranch-probabilities}.
3453 Currently the tree-based optimization is in an early stage of
3454 development, and this option is recommended only for those people
3455 working on improving it.
3458 @item -ftest-coverage
3459 @opindex ftest-coverage
3460 Produce a notes file that the @command{gcov} code-coverage utility
3461 (@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
3462 show program coverage. Each source file's note file is called
3463 @file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
3464 above for a description of @var{auxname} and instructions on how to
3465 generate test coverage data. Coverage data will match the source files
3466 more closely, if you do not optimize.
3468 @item -d@var{letters}
3469 @item -fdump-rtl-@var{pass}
3471 Says to make debugging dumps during compilation at times specified by
3472 @var{letters}. This is used for debugging the RTL-based passes of the
3473 compiler. The file names for most of the dumps are made by appending a
3474 pass number and a word to the @var{dumpname}. @var{dumpname} is generated
3475 from the name of the output file, if explicitly specified and it is not
3476 an executable, otherwise it is the basename of the source file.
3478 Most debug dumps can be enabled either passing a letter to the @option{-d}
3479 option, or with a long @option{-fdump-rtl} switch; here are the possible
3480 letters for use in @var{letters} and @var{pass}, and their meanings:
3485 Annotate the assembler output with miscellaneous debugging information.
3488 @itemx -fdump-rtl-bp
3490 @opindex fdump-rtl-bp
3491 Dump after computing branch probabilities, to @file{@var{file}.09.bp}.
3494 @itemx -fdump-rtl-bbro
3496 @opindex fdump-rtl-bbro
3497 Dump after block reordering, to @file{@var{file}.30.bbro}.
3500 @itemx -fdump-rtl-combine
3502 @opindex fdump-rtl-combine
3503 Dump after instruction combination, to the file @file{@var{file}.17.combine}.
3506 @itemx -fdump-rtl-ce1
3507 @itemx -fdump-rtl-ce2
3509 @opindex fdump-rtl-ce1
3510 @opindex fdump-rtl-ce2
3511 @option{-dC} and @option{-fdump-rtl-ce1} enable dumping after the
3512 first if conversion, to the file @file{@var{file}.11.ce1}. @option{-dC}
3513 and @option{-fdump-rtl-ce2} enable dumping after the second if
3514 conversion, to the file @file{@var{file}.18.ce2}.
3517 @itemx -fdump-rtl-btl
3518 @itemx -fdump-rtl-dbr
3520 @opindex fdump-rtl-btl
3521 @opindex fdump-rtl-dbr
3522 @option{-dd} and @option{-fdump-rtl-btl} enable dumping after branch
3523 target load optimization, to to @file{@var{file}.31.btl}. @option{-dd}
3524 and @option{-fdump-rtl-dbr} enable dumping after delayed branch
3525 scheduling, to @file{@var{file}.36.dbr}.
3529 Dump all macro definitions, at the end of preprocessing, in addition to
3533 @itemx -fdump-rtl-ce3
3535 @opindex fdump-rtl-ce3
3536 Dump after the third if conversion, to @file{@var{file}.28.ce3}.
3539 @itemx -fdump-rtl-cfg
3540 @itemx -fdump-rtl-life
3542 @opindex fdump-rtl-cfg
3543 @opindex fdump-rtl-life
3544 @option{-df} and @option{-fdump-rtl-cfg} enable dumping after control
3545 and data flow analysis, to @file{@var{file}.08.cfg}. @option{-df}
3546 and @option{-fdump-rtl-cfg} enable dumping dump after life analysis,
3547 to @file{@var{file}.16.life}.
3550 @itemx -fdump-rtl-greg
3552 @opindex fdump-rtl-greg
3553 Dump after global register allocation, to @file{@var{file}.23.greg}.
3556 @itemx -fdump-rtl-gcse
3557 @itemx -fdump-rtl-bypass
3559 @opindex fdump-rtl-gcse
3560 @opindex fdump-rtl-bypass
3561 @option{-dG} and @option{-fdump-rtl-gcse} enable dumping after GCSE, to
3562 @file{@var{file}.05.gcse}. @option{-dG} and @option{-fdump-rtl-bypass}
3563 enable dumping after jump bypassing and control flow optimizations, to
3564 @file{@var{file}.07.bypass}.
3567 @itemx -fdump-rtl-eh
3569 @opindex fdump-rtl-eh
3570 Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
3573 @itemx -fdump-rtl-sibling
3575 @opindex fdump-rtl-sibling
3576 Dump after sibling call optimizations, to @file{@var{file}.01.sibling}.
3579 @itemx -fdump-rtl-jump
3581 @opindex fdump-rtl-jump
3582 Dump after the first jump optimization, to @file{@var{file}.03.jump}.
3585 @itemx -fdump-rtl-stack
3587 @opindex fdump-rtl-stack
3588 Dump after conversion from registers to stack, to @file{@var{file}.33.stack}.
3591 @itemx -fdump-rtl-lreg
3593 @opindex fdump-rtl-lreg
3594 Dump after local register allocation, to @file{@var{file}.22.lreg}.
3597 @itemx -fdump-rtl-loop
3598 @itemx -fdump-rtl-loop2
3600 @opindex fdump-rtl-loop
3601 @opindex fdump-rtl-loop2
3602 @option{-dL} and @option{-fdump-rtl-loop} enable dumping after the first
3603 loop optimization pass, to @file{@var{file}.06.loop}. @option{-dL} and
3604 @option{-fdump-rtl-loop2} enable dumping after the second pass, to
3605 @file{@var{file}.13.loop2}.
3608 @itemx -fdump-rtl-sms
3610 @opindex fdump-rtl-sms
3611 Dump after modulo scheduling, to @file{@var{file}.20.sms}.
3614 @itemx -fdump-rtl-mach
3616 @opindex fdump-rtl-mach
3617 Dump after performing the machine dependent reorganization pass, to
3618 @file{@var{file}.35.mach}.
3621 @itemx -fdump-rtl-rnreg
3623 @opindex fdump-rtl-rnreg
3624 Dump after register renumbering, to @file{@var{file}.29.rnreg}.
3627 @itemx -fdump-rtl-regmove
3629 @opindex fdump-rtl-regmove
3630 Dump after the register move pass, to @file{@var{file}.19.regmove}.
3633 @itemx -fdump-rtl-postreload
3635 @opindex fdump-rtl-postreload
3636 Dump after post-reload optimizations, to @file{@var{file}.24.postreload}.
3639 @itemx -fdump-rtl-expand
3641 @opindex fdump-rtl-expand
3642 Dump after RTL generation, to @file{@var{file}.00.expand}.
3645 @itemx -fdump-rtl-sched2
3647 @opindex fdump-rtl-sched2
3648 Dump after the second scheduling pass, to @file{@var{file}.32.sched2}.
3651 @itemx -fdump-rtl-cse
3653 @opindex fdump-rtl-cse
3654 Dump after CSE (including the jump optimization that sometimes follows
3655 CSE), to @file{@var{file}.04.cse}.
3658 @itemx -fdump-rtl-sched
3660 @opindex fdump-rtl-sched
3661 Dump after the first scheduling pass, to @file{@var{file}.21.sched}.
3664 @itemx -fdump-rtl-cse2
3666 @opindex fdump-rtl-cse2
3667 Dump after the second CSE pass (including the jump optimization that
3668 sometimes follows CSE), to @file{@var{file}.15.cse2}.
3671 @itemx -fdump-rtl-tracer
3673 @opindex fdump-rtl-tracer
3674 Dump after running tracer, to @file{@var{file}.12.tracer}.
3677 @itemx -fdump-rtl-vpt
3678 @itemx -fdump-rtl-vartrack
3680 @opindex fdump-rtl-vpt
3681 @opindex fdump-rtl-vartrack
3682 @option{-dV} and @option{-fdump-rtl-vpt} enable dumping after the value
3683 profile transformations, to @file{@var{file}.10.vpt}. @option{-dV}
3684 and @option{-fdump-rtl-vartrack} enable dumping after variable tracking,
3685 to @file{@var{file}.34.vartrack}.
3688 @itemx -fdump-rtl-flow2
3690 @opindex fdump-rtl-flow2
3691 Dump after the second flow pass, to @file{@var{file}.26.flow2}.
3694 @itemx -fdump-rtl-peephole2
3696 @opindex fdump-rtl-peephole2
3697 Dump after the peephole pass, to @file{@var{file}.27.peephole2}.
3700 @itemx -fdump-rtl-web
3702 @opindex fdump-rtl-web
3703 Dump after live range splitting, to @file{@var{file}.14.web}.
3706 @itemx -fdump-rtl-all
3708 @opindex fdump-rtl-all
3709 Produce all the dumps listed above.
3713 Produce a core dump whenever an error occurs.
3717 Print statistics on memory usage, at the end of the run, to
3722 Annotate the assembler output with a comment indicating which
3723 pattern and alternative was used. The length of each instruction is
3728 Dump the RTL in the assembler output as a comment before each instruction.
3729 Also turns on @option{-dp} annotation.
3733 For each of the other indicated dump files (either with @option{-d} or
3734 @option{-fdump-rtl-@var{pass}}), dump a representation of the control flow
3735 graph suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
3739 Just generate RTL for a function instead of compiling it. Usually used
3740 with @samp{r} (@option{-fdump-rtl-expand}).
3744 Dump debugging information during parsing, to standard error.
3747 @item -fdump-unnumbered
3748 @opindex fdump-unnumbered
3749 When doing debugging dumps (see @option{-d} option above), suppress instruction
3750 numbers and line number note output. This makes it more feasible to
3751 use diff on debugging dumps for compiler invocations with different
3752 options, in particular with and without @option{-g}.
3754 @item -fdump-translation-unit @r{(C and C++ only)}
3755 @itemx -fdump-translation-unit-@var{options} @r{(C and C++ only)}
3756 @opindex fdump-translation-unit
3757 Dump a representation of the tree structure for the entire translation
3758 unit to a file. The file name is made by appending @file{.tu} to the
3759 source file name. If the @samp{-@var{options}} form is used, @var{options}
3760 controls the details of the dump as described for the
3761 @option{-fdump-tree} options.
3763 @item -fdump-class-hierarchy @r{(C++ only)}
3764 @itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
3765 @opindex fdump-class-hierarchy
3766 Dump a representation of each class's hierarchy and virtual function
3767 table layout to a file. The file name is made by appending @file{.class}
3768 to the source file name. If the @samp{-@var{options}} form is used,
3769 @var{options} controls the details of the dump as described for the
3770 @option{-fdump-tree} options.
3772 @item -fdump-ipa-@var{switch}
3774 Control the dumping at various stages of inter-procedural analysis
3775 language tree to a file. The file name is generated by appending a switch
3776 specific suffix to the source file name. The following dumps are possible:
3780 Enables all inter-procedural analysis dumps; currently the only produced
3781 dump is the @samp{cgraph} dump.
3784 Dumps information about call-graph optimization, unused function removal,
3785 and inlining decisions.
3788 @item -fdump-tree-@var{switch} @r{(C and C++ only)}
3789 @itemx -fdump-tree-@var{switch}-@var{options} @r{(C and C++ only)}
3791 Control the dumping at various stages of processing the intermediate
3792 language tree to a file. The file name is generated by appending a switch
3793 specific suffix to the source file name. If the @samp{-@var{options}}
3794 form is used, @var{options} is a list of @samp{-} separated options that
3795 control the details of the dump. Not all options are applicable to all
3796 dumps, those which are not meaningful will be ignored. The following
3797 options are available
3801 Print the address of each node. Usually this is not meaningful as it
3802 changes according to the environment and source file. Its primary use
3803 is for tying up a dump file with a debug environment.
3805 Inhibit dumping of members of a scope or body of a function merely
3806 because that scope has been reached. Only dump such items when they
3807 are directly reachable by some other path. When dumping pretty-printed
3808 trees, this option inhibits dumping the bodies of control structures.
3810 Print a raw representation of the tree. By default, trees are
3811 pretty-printed into a C-like representation.
3813 Enable more detailed dumps (not honored by every dump option).
3815 Enable dumping various statistics about the pass (not honored by every dump
3818 Enable showing basic block boundaries (disabled in raw dumps).
3820 Enable showing virtual operands for every statement.
3822 Enable showing line numbers for statements.
3824 Enable showing the unique ID (@code{DECL_UID}) for each variable.
3826 Turn on all options, except @option{raw}, @option{slim} and @option{lineno}.
3829 The following tree dumps are possible:
3833 Dump before any tree based optimization, to @file{@var{file}.original}.
3836 Dump after all tree based optimization, to @file{@var{file}.optimized}.
3839 Dump after function inlining, to @file{@var{file}.inlined}.
3842 @opindex fdump-tree-gimple
3843 Dump each function before and after the gimplification pass to a file. The
3844 file name is made by appending @file{.gimple} to the source file name.
3847 @opindex fdump-tree-cfg
3848 Dump the control flow graph of each function to a file. The file name is
3849 made by appending @file{.cfg} to the source file name.
3852 @opindex fdump-tree-vcg
3853 Dump the control flow graph of each function to a file in VCG format. The
3854 file name is made by appending @file{.vcg} to the source file name. Note
3855 that if the file contains more than one function, the generated file cannot
3856 be used directly by VCG@. You will need to cut and paste each function's
3857 graph into its own separate file first.
3860 @opindex fdump-tree-ch
3861 Dump each function after copying loop headers. The file name is made by
3862 appending @file{.ch} to the source file name.
3865 @opindex fdump-tree-ssa
3866 Dump SSA related information to a file. The file name is made by appending
3867 @file{.ssa} to the source file name.
3870 @opindex fdump-tree-salias
3871 Dump structure aliasing variable information to a file. This file name
3872 is made by appending @file{.salias} to the source file name.
3875 @opindex fdump-tree-alias
3876 Dump aliasing information for each function. The file name is made by
3877 appending @file{.alias} to the source file name.
3880 @opindex fdump-tree-ccp
3881 Dump each function after CCP@. The file name is made by appending
3882 @file{.ccp} to the source file name.
3885 @opindex fdump-tree-storeccp
3886 Dump each function after STORE-CCP. The file name is made by appending
3887 @file{.storeccp} to the source file name.
3890 @opindex fdump-tree-pre
3891 Dump trees after partial redundancy elimination. The file name is made
3892 by appending @file{.pre} to the source file name.
3895 @opindex fdump-tree-fre
3896 Dump trees after full redundancy elimination. The file name is made
3897 by appending @file{.fre} to the source file name.
3900 @opindex fdump-tree-copyprop
3901 Dump trees after copy propagation. The file name is made
3902 by appending @file{.copyprop} to the source file name.
3904 @item store_copyprop
3905 @opindex fdump-tree-store_copyprop
3906 Dump trees after store copy-propagation. The file name is made
3907 by appending @file{.store_copyprop} to the source file name.
3910 @opindex fdump-tree-dce
3911 Dump each function after dead code elimination. The file name is made by
3912 appending @file{.dce} to the source file name.
3915 @opindex fdump-tree-mudflap
3916 Dump each function after adding mudflap instrumentation. The file name is
3917 made by appending @file{.mudflap} to the source file name.
3920 @opindex fdump-tree-sra
3921 Dump each function after performing scalar replacement of aggregates. The
3922 file name is made by appending @file{.sra} to the source file name.
3925 @opindex fdump-tree-sink
3926 Dump each function after performing code sinking. The file name is made
3927 by appending @file{.sink} to the source file name.
3930 @opindex fdump-tree-dom
3931 Dump each function after applying dominator tree optimizations. The file
3932 name is made by appending @file{.dom} to the source file name.
3935 @opindex fdump-tree-dse
3936 Dump each function after applying dead store elimination. The file
3937 name is made by appending @file{.dse} to the source file name.
3940 @opindex fdump-tree-phiopt
3941 Dump each function after optimizing PHI nodes into straightline code. The file
3942 name is made by appending @file{.phiopt} to the source file name.
3945 @opindex fdump-tree-forwprop
3946 Dump each function after forward propagating single use variables. The file
3947 name is made by appending @file{.forwprop} to the source file name.
3950 @opindex fdump-tree-copyrename
3951 Dump each function after applying the copy rename optimization. The file
3952 name is made by appending @file{.copyrename} to the source file name.
3955 @opindex fdump-tree-nrv
3956 Dump each function after applying the named return value optimization on
3957 generic trees. The file name is made by appending @file{.nrv} to the source
3961 @opindex fdump-tree-vect
3962 Dump each function after applying vectorization of loops. The file name is
3963 made by appending @file{.vect} to the source file name.
3966 @opindex fdump-tree-all
3967 Enable all the available tree dumps with the flags provided in this option.
3970 @item -ftree-vectorizer-verbose=@var{n}
3971 @opindex ftree-vectorizer-verbose
3972 This option controls the amount of debugging output the vectorizer prints.
3973 This information is written to standard error, unless @option{-fdump-tree-all}
3974 or @option{-fdump-tree-vect} is specified, in which case it is output to the
3975 usual dump listing file, @file{.vect}.
3977 @item -frandom-seed=@var{string}
3978 @opindex frandom-string
3979 This option provides a seed that GCC uses when it would otherwise use
3980 random numbers. It is used to generate certain symbol names
3981 that have to be different in every compiled file. It is also used to
3982 place unique stamps in coverage data files and the object files that
3983 produce them. You can use the @option{-frandom-seed} option to produce
3984 reproducibly identical object files.
3986 The @var{string} should be different for every file you compile.
3988 @item -fsched-verbose=@var{n}
3989 @opindex fsched-verbose
3990 On targets that use instruction scheduling, this option controls the
3991 amount of debugging output the scheduler prints. This information is
3992 written to standard error, unless @option{-dS} or @option{-dR} is
3993 specified, in which case it is output to the usual dump
3994 listing file, @file{.sched} or @file{.sched2} respectively. However
3995 for @var{n} greater than nine, the output is always printed to standard
3998 For @var{n} greater than zero, @option{-fsched-verbose} outputs the
3999 same information as @option{-dRS}. For @var{n} greater than one, it
4000 also output basic block probabilities, detailed ready list information
4001 and unit/insn info. For @var{n} greater than two, it includes RTL
4002 at abort point, control-flow and regions info. And for @var{n} over
4003 four, @option{-fsched-verbose} also includes dependence info.
4007 Store the usual ``temporary'' intermediate files permanently; place them
4008 in the current directory and name them based on the source file. Thus,
4009 compiling @file{foo.c} with @samp{-c -save-temps} would produce files
4010 @file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
4011 preprocessed @file{foo.i} output file even though the compiler now
4012 normally uses an integrated preprocessor.
4014 When used in combination with the @option{-x} command line option,
4015 @option{-save-temps} is sensible enough to avoid over writing an
4016 input source file with the same extension as an intermediate file.
4017 The corresponding intermediate file may be obtained by renaming the
4018 source file before using @option{-save-temps}.
4022 Report the CPU time taken by each subprocess in the compilation
4023 sequence. For C source files, this is the compiler proper and assembler
4024 (plus the linker if linking is done). The output looks like this:
4031 The first number on each line is the ``user time'', that is time spent
4032 executing the program itself. The second number is ``system time'',
4033 time spent executing operating system routines on behalf of the program.
4034 Both numbers are in seconds.
4036 @item -fvar-tracking
4037 @opindex fvar-tracking
4038 Run variable tracking pass. It computes where variables are stored at each
4039 position in code. Better debugging information is then generated
4040 (if the debugging information format supports this information).
4042 It is enabled by default when compiling with optimization (@option{-Os},
4043 @option{-O}, @option{-O2}, ...), debugging information (@option{-g}) and
4044 the debug info format supports it.
4046 @item -print-file-name=@var{library}
4047 @opindex print-file-name
4048 Print the full absolute name of the library file @var{library} that
4049 would be used when linking---and don't do anything else. With this
4050 option, GCC does not compile or link anything; it just prints the
4053 @item -print-multi-directory
4054 @opindex print-multi-directory
4055 Print the directory name corresponding to the multilib selected by any
4056 other switches present in the command line. This directory is supposed
4057 to exist in @env{GCC_EXEC_PREFIX}.
4059 @item -print-multi-lib
4060 @opindex print-multi-lib
4061 Print the mapping from multilib directory names to compiler switches
4062 that enable them. The directory name is separated from the switches by
4063 @samp{;}, and each switch starts with an @samp{@@} instead of the
4064 @samp{-}, without spaces between multiple switches. This is supposed to
4065 ease shell-processing.
4067 @item -print-prog-name=@var{program}
4068 @opindex print-prog-name
4069 Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
4071 @item -print-libgcc-file-name
4072 @opindex print-libgcc-file-name
4073 Same as @option{-print-file-name=libgcc.a}.
4075 This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
4076 but you do want to link with @file{libgcc.a}. You can do
4079 gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
4082 @item -print-search-dirs
4083 @opindex print-search-dirs
4084 Print the name of the configured installation directory and a list of
4085 program and library directories @command{gcc} will search---and don't do anything else.
4087 This is useful when @command{gcc} prints the error message
4088 @samp{installation problem, cannot exec cpp0: No such file or directory}.
4089 To resolve this you either need to put @file{cpp0} and the other compiler
4090 components where @command{gcc} expects to find them, or you can set the environment
4091 variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
4092 Don't forget the trailing @samp{/}.
4093 @xref{Environment Variables}.
4096 @opindex dumpmachine
4097 Print the compiler's target machine (for example,
4098 @samp{i686-pc-linux-gnu})---and don't do anything else.
4101 @opindex dumpversion
4102 Print the compiler version (for example, @samp{3.0})---and don't do
4107 Print the compiler's built-in specs---and don't do anything else. (This
4108 is used when GCC itself is being built.) @xref{Spec Files}.
4110 @item -feliminate-unused-debug-types
4111 @opindex feliminate-unused-debug-types
4112 Normally, when producing DWARF2 output, GCC will emit debugging
4113 information for all types declared in a compilation
4114 unit, regardless of whether or not they are actually used
4115 in that compilation unit. Sometimes this is useful, such as
4116 if, in the debugger, you want to cast a value to a type that is
4117 not actually used in your program (but is declared). More often,
4118 however, this results in a significant amount of wasted space.
4119 With this option, GCC will avoid producing debug symbol output
4120 for types that are nowhere used in the source file being compiled.
4123 @node Optimize Options
4124 @section Options That Control Optimization
4125 @cindex optimize options
4126 @cindex options, optimization
4128 These options control various sorts of optimizations.
4130 Without any optimization option, the compiler's goal is to reduce the
4131 cost of compilation and to make debugging produce the expected
4132 results. Statements are independent: if you stop the program with a
4133 breakpoint between statements, you can then assign a new value to any
4134 variable or change the program counter to any other statement in the
4135 function and get exactly the results you would expect from the source
4138 Turning on optimization flags makes the compiler attempt to improve
4139 the performance and/or code size at the expense of compilation time
4140 and possibly the ability to debug the program.
4142 The compiler performs optimization based on the knowledge it has of
4143 the program. Optimization levels @option{-O2} and above, in
4144 particular, enable @emph{unit-at-a-time} mode, which allows the
4145 compiler to consider information gained from later functions in
4146 the file when compiling a function. Compiling multiple files at
4147 once to a single output file in @emph{unit-at-a-time} mode allows
4148 the compiler to use information gained from all of the files when
4149 compiling each of them.
4151 Not all optimizations are controlled directly by a flag. Only
4152 optimizations that have a flag are listed.
4159 Optimize. Optimizing compilation takes somewhat more time, and a lot
4160 more memory for a large function.
4162 With @option{-O}, the compiler tries to reduce code size and execution
4163 time, without performing any optimizations that take a great deal of
4166 @option{-O} turns on the following optimization flags:
4167 @gccoptlist{-fdefer-pop @gol
4168 -fdelayed-branch @gol
4169 -fguess-branch-probability @gol
4170 -fcprop-registers @gol
4171 -floop-optimize @gol
4172 -fif-conversion @gol
4173 -fif-conversion2 @gol
4181 -ftree-copyrename @gol
4186 @option{-O} also turns on @option{-fomit-frame-pointer} on machines
4187 where doing so does not interfere with debugging.
4191 Optimize even more. GCC performs nearly all supported optimizations
4192 that do not involve a space-speed tradeoff. The compiler does not
4193 perform loop unrolling or function inlining when you specify @option{-O2}.
4194 As compared to @option{-O}, this option increases both compilation time
4195 and the performance of the generated code.
4197 @option{-O2} turns on all optimization flags specified by @option{-O}. It
4198 also turns on the following optimization flags:
4199 @gccoptlist{-fthread-jumps @gol
4201 -foptimize-sibling-calls @gol
4202 -fcse-follow-jumps -fcse-skip-blocks @gol
4203 -fgcse -fgcse-lm @gol
4204 -fexpensive-optimizations @gol
4205 -fstrength-reduce @gol
4206 -frerun-cse-after-loop -frerun-loop-opt @gol
4210 -fschedule-insns -fschedule-insns2 @gol
4211 -fsched-interblock -fsched-spec @gol
4213 -fstrict-aliasing @gol
4214 -fdelete-null-pointer-checks @gol
4215 -freorder-blocks -freorder-functions @gol
4216 -funit-at-a-time @gol
4217 -falign-functions -falign-jumps @gol
4218 -falign-loops -falign-labels @gol
4221 Please note the warning under @option{-fgcse} about
4222 invoking @option{-O2} on programs that use computed gotos.
4226 Optimize yet more. @option{-O3} turns on all optimizations specified by
4227 @option{-O2} and also turns on the @option{-finline-functions},
4228 @option{-funswitch-loops} and @option{-fgcse-after-reload} options.
4232 Do not optimize. This is the default.
4236 Optimize for size. @option{-Os} enables all @option{-O2} optimizations that
4237 do not typically increase code size. It also performs further
4238 optimizations designed to reduce code size.
4240 @option{-Os} disables the following optimization flags:
4241 @gccoptlist{-falign-functions -falign-jumps -falign-loops @gol
4242 -falign-labels -freorder-blocks -freorder-blocks-and-partition -fprefetch-loop-arrays}
4244 If you use multiple @option{-O} options, with or without level numbers,
4245 the last such option is the one that is effective.
4248 Options of the form @option{-f@var{flag}} specify machine-independent
4249 flags. Most flags have both positive and negative forms; the negative
4250 form of @option{-ffoo} would be @option{-fno-foo}. In the table
4251 below, only one of the forms is listed---the one you typically will
4252 use. You can figure out the other form by either removing @samp{no-}
4255 The following options control specific optimizations. They are either
4256 activated by @option{-O} options or are related to ones that are. You
4257 can use the following flags in the rare cases when ``fine-tuning'' of
4258 optimizations to be performed is desired.
4261 @item -fno-default-inline
4262 @opindex fno-default-inline
4263 Do not make member functions inline by default merely because they are
4264 defined inside the class scope (C++ only). Otherwise, when you specify
4265 @w{@option{-O}}, member functions defined inside class scope are compiled
4266 inline by default; i.e., you don't need to add @samp{inline} in front of
4267 the member function name.
4269 @item -fno-defer-pop
4270 @opindex fno-defer-pop
4271 Always pop the arguments to each function call as soon as that function
4272 returns. For machines which must pop arguments after a function call,
4273 the compiler normally lets arguments accumulate on the stack for several
4274 function calls and pops them all at once.
4276 Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4280 Force memory operands to be copied into registers before doing
4281 arithmetic on them. This produces better code by making all memory
4282 references potential common subexpressions. When they are not common
4283 subexpressions, instruction combination should eliminate the separate
4286 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4289 @opindex fforce-addr
4290 Force memory address constants to be copied into registers before
4291 doing arithmetic on them. This may produce better code just as
4292 @option{-fforce-mem} may.
4294 @item -fomit-frame-pointer
4295 @opindex fomit-frame-pointer
4296 Don't keep the frame pointer in a register for functions that
4297 don't need one. This avoids the instructions to save, set up and
4298 restore frame pointers; it also makes an extra register available
4299 in many functions. @strong{It also makes debugging impossible on
4302 On some machines, such as the VAX, this flag has no effect, because
4303 the standard calling sequence automatically handles the frame pointer
4304 and nothing is saved by pretending it doesn't exist. The
4305 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
4306 whether a target machine supports this flag. @xref{Registers,,Register
4307 Usage, gccint, GNU Compiler Collection (GCC) Internals}.
4309 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4311 @item -foptimize-sibling-calls
4312 @opindex foptimize-sibling-calls
4313 Optimize sibling and tail recursive calls.
4315 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4319 Don't pay attention to the @code{inline} keyword. Normally this option
4320 is used to keep the compiler from expanding any functions inline.
4321 Note that if you are not optimizing, no functions can be expanded inline.
4323 @item -finline-functions
4324 @opindex finline-functions
4325 Integrate all simple functions into their callers. The compiler
4326 heuristically decides which functions are simple enough to be worth
4327 integrating in this way.
4329 If all calls to a given function are integrated, and the function is
4330 declared @code{static}, then the function is normally not output as
4331 assembler code in its own right.
4333 Enabled at level @option{-O3}.
4335 @item -finline-limit=@var{n}
4336 @opindex finline-limit
4337 By default, GCC limits the size of functions that can be inlined. This flag
4338 allows the control of this limit for functions that are explicitly marked as
4339 inline (i.e., marked with the inline keyword or defined within the class
4340 definition in c++). @var{n} is the size of functions that can be inlined in
4341 number of pseudo instructions (not counting parameter handling). The default
4342 value of @var{n} is 600.
4343 Increasing this value can result in more inlined code at
4344 the cost of compilation time and memory consumption. Decreasing usually makes
4345 the compilation faster and less code will be inlined (which presumably
4346 means slower programs). This option is particularly useful for programs that
4347 use inlining heavily such as those based on recursive templates with C++.
4349 Inlining is actually controlled by a number of parameters, which may be
4350 specified individually by using @option{--param @var{name}=@var{value}}.
4351 The @option{-finline-limit=@var{n}} option sets some of these parameters
4355 @item max-inline-insns-single
4356 is set to @var{n}/2.
4357 @item max-inline-insns-auto
4358 is set to @var{n}/2.
4359 @item min-inline-insns
4360 is set to 130 or @var{n}/4, whichever is smaller.
4361 @item max-inline-insns-rtl
4365 See below for a documentation of the individual
4366 parameters controlling inlining.
4368 @emph{Note:} pseudo instruction represents, in this particular context, an
4369 abstract measurement of function's size. In no way, it represents a count
4370 of assembly instructions and as such its exact meaning might change from one
4371 release to an another.
4373 @item -fkeep-inline-functions
4374 @opindex fkeep-inline-functions
4375 In C, emit @code{static} functions that are declared @code{inline}
4376 into the object file, even if the function has been inlined into all
4377 of its callers. This switch does not affect functions using the
4378 @code{extern inline} extension in GNU C@. In C++, emit any and all
4379 inline functions into the object file.
4381 @item -fkeep-static-consts
4382 @opindex fkeep-static-consts
4383 Emit variables declared @code{static const} when optimization isn't turned
4384 on, even if the variables aren't referenced.
4386 GCC enables this option by default. If you want to force the compiler to
4387 check if the variable was referenced, regardless of whether or not
4388 optimization is turned on, use the @option{-fno-keep-static-consts} option.
4390 @item -fmerge-constants
4391 Attempt to merge identical constants (string constants and floating point
4392 constants) across compilation units.
4394 This option is the default for optimized compilation if the assembler and
4395 linker support it. Use @option{-fno-merge-constants} to inhibit this
4398 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4400 @item -fmerge-all-constants
4401 Attempt to merge identical constants and identical variables.
4403 This option implies @option{-fmerge-constants}. In addition to
4404 @option{-fmerge-constants} this considers e.g.@: even constant initialized
4405 arrays or initialized constant variables with integral or floating point
4406 types. Languages like C or C++ require each non-automatic variable to
4407 have distinct location, so using this option will result in non-conforming
4410 @item -fmodulo-sched
4411 @opindex fmodulo-sched
4412 Perform swing modulo scheduling immediately before the first scheduling
4413 pass. This pass looks at innermost loops and reorders their
4414 instructions by overlapping different iterations.
4416 @item -fno-branch-count-reg
4417 @opindex fno-branch-count-reg
4418 Do not use ``decrement and branch'' instructions on a count register,
4419 but instead generate a sequence of instructions that decrement a
4420 register, compare it against zero, then branch based upon the result.
4421 This option is only meaningful on architectures that support such
4422 instructions, which include x86, PowerPC, IA-64 and S/390.
4424 The default is @option{-fbranch-count-reg}, enabled when
4425 @option{-fstrength-reduce} is enabled.
4427 @item -fno-function-cse
4428 @opindex fno-function-cse
4429 Do not put function addresses in registers; make each instruction that
4430 calls a constant function contain the function's address explicitly.
4432 This option results in less efficient code, but some strange hacks
4433 that alter the assembler output may be confused by the optimizations
4434 performed when this option is not used.
4436 The default is @option{-ffunction-cse}
4438 @item -fno-zero-initialized-in-bss
4439 @opindex fno-zero-initialized-in-bss
4440 If the target supports a BSS section, GCC by default puts variables that
4441 are initialized to zero into BSS@. This can save space in the resulting
4444 This option turns off this behavior because some programs explicitly
4445 rely on variables going to the data section. E.g., so that the
4446 resulting executable can find the beginning of that section and/or make
4447 assumptions based on that.
4449 The default is @option{-fzero-initialized-in-bss}.
4451 @item -fbounds-check
4452 @opindex fbounds-check
4453 For front-ends that support it, generate additional code to check that
4454 indices used to access arrays are within the declared range. This is
4455 currently only supported by the Java and Fortran front-ends, where
4456 this option defaults to true and false respectively.
4458 @item -fmudflap -fmudflapth -fmudflapir
4462 @cindex bounds checking
4464 For front-ends that support it (C and C++), instrument all risky
4465 pointer/array dereferencing operations, some standard library
4466 string/heap functions, and some other associated constructs with
4467 range/validity tests. Modules so instrumented should be immune to
4468 buffer overflows, invalid heap use, and some other classes of C/C++
4469 programming errors. The instrumentation relies on a separate runtime
4470 library (@file{libmudflap}), which will be linked into a program if
4471 @option{-fmudflap} is given at link time. Run-time behavior of the
4472 instrumented program is controlled by the @env{MUDFLAP_OPTIONS}
4473 environment variable. See @code{env MUDFLAP_OPTIONS=-help a.out}
4476 Use @option{-fmudflapth} instead of @option{-fmudflap} to compile and to
4477 link if your program is multi-threaded. Use @option{-fmudflapir}, in
4478 addition to @option{-fmudflap} or @option{-fmudflapth}, if
4479 instrumentation should ignore pointer reads. This produces less
4480 instrumentation (and therefore faster execution) and still provides
4481 some protection against outright memory corrupting writes, but allows
4482 erroneously read data to propagate within a program.
4484 @item -fstrength-reduce
4485 @opindex fstrength-reduce
4486 Perform the optimizations of loop strength reduction and
4487 elimination of iteration variables.
4489 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4491 @item -fthread-jumps
4492 @opindex fthread-jumps
4493 Perform optimizations where we check to see if a jump branches to a
4494 location where another comparison subsumed by the first is found. If
4495 so, the first branch is redirected to either the destination of the
4496 second branch or a point immediately following it, depending on whether
4497 the condition is known to be true or false.
4499 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4501 @item -fcse-follow-jumps
4502 @opindex fcse-follow-jumps
4503 In common subexpression elimination, scan through jump instructions
4504 when the target of the jump is not reached by any other path. For
4505 example, when CSE encounters an @code{if} statement with an
4506 @code{else} clause, CSE will follow the jump when the condition
4509 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4511 @item -fcse-skip-blocks
4512 @opindex fcse-skip-blocks
4513 This is similar to @option{-fcse-follow-jumps}, but causes CSE to
4514 follow jumps which conditionally skip over blocks. When CSE
4515 encounters a simple @code{if} statement with no else clause,
4516 @option{-fcse-skip-blocks} causes CSE to follow the jump around the
4517 body of the @code{if}.
4519 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4521 @item -frerun-cse-after-loop
4522 @opindex frerun-cse-after-loop
4523 Re-run common subexpression elimination after loop optimizations has been
4526 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4528 @item -frerun-loop-opt
4529 @opindex frerun-loop-opt
4530 Run the loop optimizer twice.
4532 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4536 Perform a global common subexpression elimination pass.
4537 This pass also performs global constant and copy propagation.
4539 @emph{Note:} When compiling a program using computed gotos, a GCC
4540 extension, you may get better runtime performance if you disable
4541 the global common subexpression elimination pass by adding
4542 @option{-fno-gcse} to the command line.
4544 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4548 When @option{-fgcse-lm} is enabled, global common subexpression elimination will
4549 attempt to move loads which are only killed by stores into themselves. This
4550 allows a loop containing a load/store sequence to be changed to a load outside
4551 the loop, and a copy/store within the loop.
4553 Enabled by default when gcse is enabled.
4557 When @option{-fgcse-sm} is enabled, a store motion pass is run after
4558 global common subexpression elimination. This pass will attempt to move
4559 stores out of loops. When used in conjunction with @option{-fgcse-lm},
4560 loops containing a load/store sequence can be changed to a load before
4561 the loop and a store after the loop.
4563 Not enabled at any optimization level.
4567 When @option{-fgcse-las} is enabled, the global common subexpression
4568 elimination pass eliminates redundant loads that come after stores to the
4569 same memory location (both partial and full redundancies).
4571 Not enabled at any optimization level.
4573 @item -fgcse-after-reload
4574 @opindex fgcse-after-reload
4575 When @option{-fgcse-after-reload} is enabled, a redundant load elimination
4576 pass is performed after reload. The purpose of this pass is to cleanup
4579 @item -floop-optimize
4580 @opindex floop-optimize
4581 Perform loop optimizations: move constant expressions out of loops, simplify
4582 exit test conditions and optionally do strength-reduction as well.
4584 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4586 @item -floop-optimize2
4587 @opindex floop-optimize2
4588 Perform loop optimizations using the new loop optimizer. The optimizations
4589 (loop unrolling, peeling and unswitching, loop invariant motion) are enabled
4592 @item -fcrossjumping
4593 @opindex crossjumping
4594 Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
4595 resulting code may or may not perform better than without cross-jumping.
4597 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4599 @item -fif-conversion
4600 @opindex if-conversion
4601 Attempt to transform conditional jumps into branch-less equivalents. This
4602 include use of conditional moves, min, max, set flags and abs instructions, and
4603 some tricks doable by standard arithmetics. The use of conditional execution
4604 on chips where it is available is controlled by @code{if-conversion2}.
4606 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4608 @item -fif-conversion2
4609 @opindex if-conversion2
4610 Use conditional execution (where available) to transform conditional jumps into
4611 branch-less equivalents.
4613 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4615 @item -fdelete-null-pointer-checks
4616 @opindex fdelete-null-pointer-checks
4617 Use global dataflow analysis to identify and eliminate useless checks
4618 for null pointers. The compiler assumes that dereferencing a null
4619 pointer would have halted the program. If a pointer is checked after
4620 it has already been dereferenced, it cannot be null.
4622 In some environments, this assumption is not true, and programs can
4623 safely dereference null pointers. Use
4624 @option{-fno-delete-null-pointer-checks} to disable this optimization
4625 for programs which depend on that behavior.
4627 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4629 @item -fexpensive-optimizations
4630 @opindex fexpensive-optimizations
4631 Perform a number of minor optimizations that are relatively expensive.
4633 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4635 @item -foptimize-register-move
4637 @opindex foptimize-register-move
4639 Attempt to reassign register numbers in move instructions and as
4640 operands of other simple instructions in order to maximize the amount of
4641 register tying. This is especially helpful on machines with two-operand
4644 Note @option{-fregmove} and @option{-foptimize-register-move} are the same
4647 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4649 @item -fdelayed-branch
4650 @opindex fdelayed-branch
4651 If supported for the target machine, attempt to reorder instructions
4652 to exploit instruction slots available after delayed branch
4655 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4657 @item -fschedule-insns
4658 @opindex fschedule-insns
4659 If supported for the target machine, attempt to reorder instructions to
4660 eliminate execution stalls due to required data being unavailable. This
4661 helps machines that have slow floating point or memory load instructions
4662 by allowing other instructions to be issued until the result of the load
4663 or floating point instruction is required.
4665 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4667 @item -fschedule-insns2
4668 @opindex fschedule-insns2
4669 Similar to @option{-fschedule-insns}, but requests an additional pass of
4670 instruction scheduling after register allocation has been done. This is
4671 especially useful on machines with a relatively small number of
4672 registers and where memory load instructions take more than one cycle.
4674 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4676 @item -fno-sched-interblock
4677 @opindex fno-sched-interblock
4678 Don't schedule instructions across basic blocks. This is normally
4679 enabled by default when scheduling before register allocation, i.e.@:
4680 with @option{-fschedule-insns} or at @option{-O2} or higher.
4682 @item -fno-sched-spec
4683 @opindex fno-sched-spec
4684 Don't allow speculative motion of non-load instructions. This is normally
4685 enabled by default when scheduling before register allocation, i.e.@:
4686 with @option{-fschedule-insns} or at @option{-O2} or higher.
4688 @item -fsched-spec-load
4689 @opindex fsched-spec-load
4690 Allow speculative motion of some load instructions. This only makes
4691 sense when scheduling before register allocation, i.e.@: with
4692 @option{-fschedule-insns} or at @option{-O2} or higher.
4694 @item -fsched-spec-load-dangerous
4695 @opindex fsched-spec-load-dangerous
4696 Allow speculative motion of more load instructions. This only makes
4697 sense when scheduling before register allocation, i.e.@: with
4698 @option{-fschedule-insns} or at @option{-O2} or higher.
4700 @item -fsched-stalled-insns=@var{n}
4701 @opindex fsched-stalled-insns
4702 Define how many insns (if any) can be moved prematurely from the queue
4703 of stalled insns into the ready list, during the second scheduling pass.
4705 @item -fsched-stalled-insns-dep=@var{n}
4706 @opindex fsched-stalled-insns-dep
4707 Define how many insn groups (cycles) will be examined for a dependency
4708 on a stalled insn that is candidate for premature removal from the queue
4709 of stalled insns. Has an effect only during the second scheduling pass,
4710 and only if @option{-fsched-stalled-insns} is used and its value is not zero.
4712 @item -fsched2-use-superblocks
4713 @opindex fsched2-use-superblocks
4714 When scheduling after register allocation, do use superblock scheduling
4715 algorithm. Superblock scheduling allows motion across basic block boundaries
4716 resulting on faster schedules. This option is experimental, as not all machine
4717 descriptions used by GCC model the CPU closely enough to avoid unreliable
4718 results from the algorithm.
4720 This only makes sense when scheduling after register allocation, i.e.@: with
4721 @option{-fschedule-insns2} or at @option{-O2} or higher.
4723 @item -fsched2-use-traces
4724 @opindex fsched2-use-traces
4725 Use @option{-fsched2-use-superblocks} algorithm when scheduling after register
4726 allocation and additionally perform code duplication in order to increase the
4727 size of superblocks using tracer pass. See @option{-ftracer} for details on
4730 This mode should produce faster but significantly longer programs. Also
4731 without @option{-fbranch-probabilities} the traces constructed may not
4732 match the reality and hurt the performance. This only makes
4733 sense when scheduling after register allocation, i.e.@: with
4734 @option{-fschedule-insns2} or at @option{-O2} or higher.
4736 @item -freschedule-modulo-scheduled-loops
4737 @opindex fscheduling-in-modulo-scheduled-loops
4738 The modulo scheduling comes before the traditional scheduling, if a loop was modulo scheduled
4739 we may want to prevent the later scheduling passes from changing its schedule, we use this
4740 option to control that.
4742 @item -fcaller-saves
4743 @opindex fcaller-saves
4744 Enable values to be allocated in registers that will be clobbered by
4745 function calls, by emitting extra instructions to save and restore the
4746 registers around such calls. Such allocation is done only when it
4747 seems to result in better code than would otherwise be produced.
4749 This option is always enabled by default on certain machines, usually
4750 those which have no call-preserved registers to use instead.
4752 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4755 Perform Partial Redundancy Elimination (PRE) on trees. This flag is
4756 enabled by default at @option{-O2} and @option{-O3}.
4759 Perform Full Redundancy Elimination (FRE) on trees. The difference
4760 between FRE and PRE is that FRE only considers expressions
4761 that are computed on all paths leading to the redundant computation.
4762 This analysis faster than PRE, though it exposes fewer redundancies.
4763 This flag is enabled by default at @option{-O} and higher.
4765 @item -ftree-copy-prop
4766 Perform copy propagation on trees. This pass eliminates unnecessary
4767 copy operations. This flag is enabled by default at @option{-O} and
4770 @item -ftree-store-copy-prop
4771 Perform copy propagation of memory loads and stores. This pass
4772 eliminates unnecessary copy operations in memory references
4773 (structures, global variables, arrays, etc). This flag is enabled by
4774 default at @option{-O2} and higher.
4777 Perform structural alias analysis on trees. This flag
4778 is enabled by default at @option{-O} and higher.
4781 Perform forward store motion on trees. This flag is
4782 enabled by default at @option{-O} and higher.
4785 Perform sparse conditional constant propagation (CCP) on trees. This
4786 pass only operates on local scalar variables and is enabled by default
4787 at @option{-O} and higher.
4789 @item -ftree-store-ccp
4790 Perform sparse conditional constant propagation (CCP) on trees. This
4791 pass operates on both local scalar variables and memory stores and
4792 loads (global variables, structures, arrays, etc). This flag is
4793 enabled by default at @option{-O2} and higher.
4796 Perform dead code elimination (DCE) on trees. This flag is enabled by
4797 default at @option{-O} and higher.
4799 @item -ftree-dominator-opts
4800 Perform dead code elimination (DCE) on trees. This flag is enabled by
4801 default at @option{-O} and higher.
4804 Perform loop header copying on trees. This is beneficial since it increases
4805 effectiveness of code motion optimizations. It also saves one jump. This flag
4806 is enabled by default at @option{-O} and higher. It is not enabled
4807 for @option{-Os}, since it usually increases code size.
4809 @item -ftree-loop-optimize
4810 Perform loop optimizations on trees. This flag is enabled by default
4811 at @option{-O} and higher.
4813 @item -ftree-loop-linear
4814 Perform linear loop transformations on tree. This flag can improve cache
4815 performance and allow further loop optimizations to take place.
4817 @item -ftree-loop-im
4818 Perform loop invariant motion on trees. This pass moves only invariants that
4819 would be hard to handle on rtl level (function calls, operations that expand to
4820 nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
4821 operands of conditions that are invariant out of the loop, so that we can use
4822 just trivial invariantness analysis in loop unswitching. The pass also includes
4825 @item -ftree-loop-ivcanon
4826 Create a canonical counter for number of iterations in the loop for that
4827 determining number of iterations requires complicated analysis. Later
4828 optimizations then may determine the number easily. Useful especially
4829 in connection with unrolling.
4832 Perform induction variable optimizations (strength reduction, induction
4833 variable merging and induction variable elimination) on trees.
4836 Perform scalar replacement of aggregates. This pass replaces structure
4837 references with scalars to prevent committing structures to memory too
4838 early. This flag is enabled by default at @option{-O} and higher.
4840 @item -ftree-copyrename
4841 Perform copy renaming on trees. This pass attempts to rename compiler
4842 temporaries to other variables at copy locations, usually resulting in
4843 variable names which more closely resemble the original variables. This flag
4844 is enabled by default at @option{-O} and higher.
4847 Perform temporary expression replacement during the SSA->normal phase. Single
4848 use/single def temporaries are replaced at their use location with their
4849 defining expression. This results in non-GIMPLE code, but gives the expanders
4850 much more complex trees to work on resulting in better RTL generation. This is
4851 enabled by default at @option{-O} and higher.
4854 Perform live range splitting during the SSA->normal phase. Distinct live
4855 ranges of a variable are split into unique variables, allowing for better
4856 optimization later. This is enabled by default at @option{-O} and higher.
4858 @item -ftree-vectorize
4859 Perform loop vectorization on trees.
4863 Perform tail duplication to enlarge superblock size. This transformation
4864 simplifies the control flow of the function allowing other optimizations to do
4867 @item -funroll-loops
4868 @opindex funroll-loops
4869 Unroll loops whose number of iterations can be determined at compile
4870 time or upon entry to the loop. @option{-funroll-loops} implies both
4871 @option{-fstrength-reduce} and @option{-frerun-cse-after-loop}. This
4872 option makes code larger, and may or may not make it run faster.
4874 @item -funroll-all-loops
4875 @opindex funroll-all-loops
4876 Unroll all loops, even if their number of iterations is uncertain when
4877 the loop is entered. This usually makes programs run more slowly.
4878 @option{-funroll-all-loops} implies the same options as
4879 @option{-funroll-loops},
4881 @item -fsplit-ivs-in-unroller
4882 @opindex -fsplit-ivs-in-unroller
4883 Enables expressing of values of induction variables in later iterations
4884 of the unrolled loop using the value in the first iteration. This breaks
4885 long dependency chains, thus improving efficiency of the scheduling passes
4886 (for best results, @option{-fweb} should be used as well).
4888 Combination of @option{-fweb} and CSE is often sufficient to obtain the
4889 same effect. However in cases the loop body is more complicated than
4890 a single basic block, this is not reliable. It also does not work at all
4891 on some of the architectures due to restrictions in the CSE pass.
4893 This optimization is enabled by default.
4895 @item -fvariable-expansion-in-unroller
4896 @opindex -fvariable-expansion-in-unroller
4897 With this option, the compiler will create multiple copies of some
4898 local variables when unrolling a loop which can result in superior code.
4900 @item -fprefetch-loop-arrays
4901 @opindex fprefetch-loop-arrays
4902 If supported by the target machine, generate instructions to prefetch
4903 memory to improve the performance of loops that access large arrays.
4905 These options may generate better or worse code; results are highly
4906 dependent on the structure of loops within the source code.
4909 @itemx -fno-peephole2
4910 @opindex fno-peephole
4911 @opindex fno-peephole2
4912 Disable any machine-specific peephole optimizations. The difference
4913 between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
4914 are implemented in the compiler; some targets use one, some use the
4915 other, a few use both.
4917 @option{-fpeephole} is enabled by default.
4918 @option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4920 @item -fno-guess-branch-probability
4921 @opindex fno-guess-branch-probability
4922 Do not guess branch probabilities using heuristics.
4924 GCC will use heuristics to guess branch probabilities if they are
4925 not provided by profiling feedback (@option{-fprofile-arcs}). These
4926 heuristics are based on the control flow graph. If some branch probabilities
4927 are specified by @samp{__builtin_expect}, then the heuristics will be
4928 used to guess branch probabilities for the rest of the control flow graph,
4929 taking the @samp{__builtin_expect} info into account. The interactions
4930 between the heuristics and @samp{__builtin_expect} can be complex, and in
4931 some cases, it may be useful to disable the heuristics so that the effects
4932 of @samp{__builtin_expect} are easier to understand.
4934 The default is @option{-fguess-branch-probability} at levels
4935 @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4937 @item -freorder-blocks
4938 @opindex freorder-blocks
4939 Reorder basic blocks in the compiled function in order to reduce number of
4940 taken branches and improve code locality.
4942 Enabled at levels @option{-O2}, @option{-O3}.
4944 @item -freorder-blocks-and-partition
4945 @opindex freorder-blocks-and-partition
4946 In addition to reordering basic blocks in the compiled function, in order
4947 to reduce number of taken branches, partitions hot and cold basic blocks
4948 into separate sections of the assembly and .o files, to improve
4949 paging and cache locality performance.
4951 This optimization is automatically turned off in the presence of
4952 exception handling, for linkonce sections, for functions with a user-defined
4953 section attribute and on any architecture that does not support named
4956 @item -freorder-functions
4957 @opindex freorder-functions
4958 Reorder functions in the object file in order to
4959 improve code locality. This is implemented by using special
4960 subsections @code{.text.hot} for most frequently executed functions and
4961 @code{.text.unlikely} for unlikely executed functions. Reordering is done by
4962 the linker so object file format must support named sections and linker must
4963 place them in a reasonable way.
4965 Also profile feedback must be available in to make this option effective. See
4966 @option{-fprofile-arcs} for details.
4968 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4970 @item -fstrict-aliasing
4971 @opindex fstrict-aliasing
4972 Allows the compiler to assume the strictest aliasing rules applicable to
4973 the language being compiled. For C (and C++), this activates
4974 optimizations based on the type of expressions. In particular, an
4975 object of one type is assumed never to reside at the same address as an
4976 object of a different type, unless the types are almost the same. For
4977 example, an @code{unsigned int} can alias an @code{int}, but not a
4978 @code{void*} or a @code{double}. A character type may alias any other
4981 Pay special attention to code like this:
4994 The practice of reading from a different union member than the one most
4995 recently written to (called ``type-punning'') is common. Even with
4996 @option{-fstrict-aliasing}, type-punning is allowed, provided the memory
4997 is accessed through the union type. So, the code above will work as
4998 expected. However, this code might not:
5009 Every language that wishes to perform language-specific alias analysis
5010 should define a function that computes, given an @code{tree}
5011 node, an alias set for the node. Nodes in different alias sets are not
5012 allowed to alias. For an example, see the C front-end function
5013 @code{c_get_alias_set}.
5015 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5017 @item -falign-functions
5018 @itemx -falign-functions=@var{n}
5019 @opindex falign-functions
5020 Align the start of functions to the next power-of-two greater than
5021 @var{n}, skipping up to @var{n} bytes. For instance,
5022 @option{-falign-functions=32} aligns functions to the next 32-byte
5023 boundary, but @option{-falign-functions=24} would align to the next
5024 32-byte boundary only if this can be done by skipping 23 bytes or less.
5026 @option{-fno-align-functions} and @option{-falign-functions=1} are
5027 equivalent and mean that functions will not be aligned.
5029 Some assemblers only support this flag when @var{n} is a power of two;
5030 in that case, it is rounded up.
5032 If @var{n} is not specified or is zero, use a machine-dependent default.
5034 Enabled at levels @option{-O2}, @option{-O3}.
5036 @item -falign-labels
5037 @itemx -falign-labels=@var{n}
5038 @opindex falign-labels
5039 Align all branch targets to a power-of-two boundary, skipping up to
5040 @var{n} bytes like @option{-falign-functions}. This option can easily
5041 make code slower, because it must insert dummy operations for when the
5042 branch target is reached in the usual flow of the code.
5044 @option{-fno-align-labels} and @option{-falign-labels=1} are
5045 equivalent and mean that labels will not be aligned.
5047 If @option{-falign-loops} or @option{-falign-jumps} are applicable and
5048 are greater than this value, then their values are used instead.
5050 If @var{n} is not specified or is zero, use a machine-dependent default
5051 which is very likely to be @samp{1}, meaning no alignment.
5053 Enabled at levels @option{-O2}, @option{-O3}.
5056 @itemx -falign-loops=@var{n}
5057 @opindex falign-loops
5058 Align loops to a power-of-two boundary, skipping up to @var{n} bytes
5059 like @option{-falign-functions}. The hope is that the loop will be
5060 executed many times, which will make up for any execution of the dummy
5063 @option{-fno-align-loops} and @option{-falign-loops=1} are
5064 equivalent and mean that loops will not be aligned.
5066 If @var{n} is not specified or is zero, use a machine-dependent default.
5068 Enabled at levels @option{-O2}, @option{-O3}.
5071 @itemx -falign-jumps=@var{n}
5072 @opindex falign-jumps
5073 Align branch targets to a power-of-two boundary, for branch targets
5074 where the targets can only be reached by jumping, skipping up to @var{n}
5075 bytes like @option{-falign-functions}. In this case, no dummy operations
5078 @option{-fno-align-jumps} and @option{-falign-jumps=1} are
5079 equivalent and mean that loops will not be aligned.
5081 If @var{n} is not specified or is zero, use a machine-dependent default.
5083 Enabled at levels @option{-O2}, @option{-O3}.
5085 @item -funit-at-a-time
5086 @opindex funit-at-a-time
5087 Parse the whole compilation unit before starting to produce code.
5088 This allows some extra optimizations to take place but consumes
5089 more memory (in general). There are some compatibility issues
5090 with @emph{unit-at-at-time} mode:
5093 enabling @emph{unit-at-a-time} mode may change the order
5094 in which functions, variables, and top-level @code{asm} statements
5095 are emitted, and will likely break code relying on some particular
5096 ordering. The majority of such top-level @code{asm} statements,
5097 though, can be replaced by @code{section} attributes.
5100 @emph{unit-at-a-time} mode removes unreferenced static variables
5101 and functions are removed. This may result in undefined references
5102 when an @code{asm} statement refers directly to variables or functions
5103 that are otherwise unused. In that case either the variable/function
5104 shall be listed as an operand of the @code{asm} statement operand or,
5105 in the case of top-level @code{asm} statements the attribute @code{used}
5106 shall be used on the declaration.
5109 Static functions now can use non-standard passing conventions that
5110 may break @code{asm} statements calling functions directly. Again,
5111 attribute @code{used} will prevent this behavior.
5114 As a temporary workaround, @option{-fno-unit-at-a-time} can be used,
5115 but this scheme may not be supported by future releases of GCC@.
5117 Enabled at levels @option{-O2}, @option{-O3}.
5121 Constructs webs as commonly used for register allocation purposes and assign
5122 each web individual pseudo register. This allows the register allocation pass
5123 to operate on pseudos directly, but also strengthens several other optimization
5124 passes, such as CSE, loop optimizer and trivial dead code remover. It can,
5125 however, make debugging impossible, since variables will no longer stay in a
5128 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os},
5129 on targets where the default format for debugging information supports
5132 @item -fno-cprop-registers
5133 @opindex fno-cprop-registers
5134 After register allocation and post-register allocation instruction splitting,
5135 we perform a copy-propagation pass to try to reduce scheduling dependencies
5136 and occasionally eliminate the copy.
5138 Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5140 @item -fprofile-generate
5141 @opindex fprofile-generate
5143 Enable options usually used for instrumenting application to produce
5144 profile useful for later recompilation with profile feedback based
5145 optimization. You must use @option{-fprofile-generate} both when
5146 compiling and when linking your program.
5148 The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
5151 @opindex fprofile-use
5152 Enable profile feedback directed optimizations, and optimizations
5153 generally profitable only with profile feedback available.
5155 The following options are enabled: @code{-fbranch-probabilities},
5156 @code{-fvpt}, @code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}.
5160 The following options control compiler behavior regarding floating
5161 point arithmetic. These options trade off between speed and
5162 correctness. All must be specifically enabled.
5166 @opindex ffloat-store
5167 Do not store floating point variables in registers, and inhibit other
5168 options that might change whether a floating point value is taken from a
5171 @cindex floating point precision
5172 This option prevents undesirable excess precision on machines such as
5173 the 68000 where the floating registers (of the 68881) keep more
5174 precision than a @code{double} is supposed to have. Similarly for the
5175 x86 architecture. For most programs, the excess precision does only
5176 good, but a few programs rely on the precise definition of IEEE floating
5177 point. Use @option{-ffloat-store} for such programs, after modifying
5178 them to store all pertinent intermediate computations into variables.
5182 Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
5183 @option{-fno-trapping-math}, @option{-ffinite-math-only},
5184 @option{-fno-rounding-math}, @option{-fno-signaling-nans}
5185 and @option{fcx-limited-range}.
5187 This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
5189 This option should never be turned on by any @option{-O} option since
5190 it can result in incorrect output for programs which depend on
5191 an exact implementation of IEEE or ISO rules/specifications for
5194 @item -fno-math-errno
5195 @opindex fno-math-errno
5196 Do not set ERRNO after calling math functions that are executed
5197 with a single instruction, e.g., sqrt. A program that relies on
5198 IEEE exceptions for math error handling may want to use this flag
5199 for speed while maintaining IEEE arithmetic compatibility.
5201 This option should never be turned on by any @option{-O} option since
5202 it can result in incorrect output for programs which depend on
5203 an exact implementation of IEEE or ISO rules/specifications for
5206 The default is @option{-fmath-errno}.
5208 @item -funsafe-math-optimizations
5209 @opindex funsafe-math-optimizations
5210 Allow optimizations for floating-point arithmetic that (a) assume
5211 that arguments and results are valid and (b) may violate IEEE or
5212 ANSI standards. When used at link-time, it may include libraries
5213 or startup files that change the default FPU control word or other
5214 similar optimizations.
5216 This option should never be turned on by any @option{-O} option since
5217 it can result in incorrect output for programs which depend on
5218 an exact implementation of IEEE or ISO rules/specifications for
5221 The default is @option{-fno-unsafe-math-optimizations}.
5223 @item -ffinite-math-only
5224 @opindex ffinite-math-only
5225 Allow optimizations for floating-point arithmetic that assume
5226 that arguments and results are not NaNs or +-Infs.
5228 This option should never be turned on by any @option{-O} option since
5229 it can result in incorrect output for programs which depend on
5230 an exact implementation of IEEE or ISO rules/specifications.
5232 The default is @option{-fno-finite-math-only}.
5234 @item -fno-trapping-math
5235 @opindex fno-trapping-math
5236 Compile code assuming that floating-point operations cannot generate
5237 user-visible traps. These traps include division by zero, overflow,
5238 underflow, inexact result and invalid operation. This option implies
5239 @option{-fno-signaling-nans}. Setting this option may allow faster
5240 code if one relies on ``non-stop'' IEEE arithmetic, for example.
5242 This option should never be turned on by any @option{-O} option since
5243 it can result in incorrect output for programs which depend on
5244 an exact implementation of IEEE or ISO rules/specifications for
5247 The default is @option{-ftrapping-math}.
5249 @item -frounding-math
5250 @opindex frounding-math
5251 Disable transformations and optimizations that assume default floating
5252 point rounding behavior. This is round-to-zero for all floating point
5253 to integer conversions, and round-to-nearest for all other arithmetic
5254 truncations. This option should be specified for programs that change
5255 the FP rounding mode dynamically, or that may be executed with a
5256 non-default rounding mode. This option disables constant folding of
5257 floating point expressions at compile-time (which may be affected by
5258 rounding mode) and arithmetic transformations that are unsafe in the
5259 presence of sign-dependent rounding modes.
5261 The default is @option{-fno-rounding-math}.
5263 This option is experimental and does not currently guarantee to
5264 disable all GCC optimizations that are affected by rounding mode.
5265 Future versions of GCC may provide finer control of this setting
5266 using C99's @code{FENV_ACCESS} pragma. This command line option
5267 will be used to specify the default state for @code{FENV_ACCESS}.
5269 @item -fsignaling-nans
5270 @opindex fsignaling-nans
5271 Compile code assuming that IEEE signaling NaNs may generate user-visible
5272 traps during floating-point operations. Setting this option disables
5273 optimizations that may change the number of exceptions visible with
5274 signaling NaNs. This option implies @option{-ftrapping-math}.
5276 This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
5279 The default is @option{-fno-signaling-nans}.
5281 This option is experimental and does not currently guarantee to
5282 disable all GCC optimizations that affect signaling NaN behavior.
5284 @item -fsingle-precision-constant
5285 @opindex fsingle-precision-constant
5286 Treat floating point constant as single precision constant instead of
5287 implicitly converting it to double precision constant.
5289 @item -fcx-limited-range
5290 @itemx -fno-cx-limited-range
5291 @opindex fcx-limited-range
5292 @opindex fno-cx-limited-range
5293 When enabled, this option states that a range reduction step is not
5294 needed when performing complex division. The default is
5295 @option{-fno-cx-limited-range}, but is enabled by @option{-ffast-math}.
5297 This option controls the default setting of the ISO C99
5298 @code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to
5303 The following options control optimizations that may improve
5304 performance, but are not enabled by any @option{-O} options. This
5305 section includes experimental options that may produce broken code.
5308 @item -fbranch-probabilities
5309 @opindex fbranch-probabilities
5310 After running a program compiled with @option{-fprofile-arcs}
5311 (@pxref{Debugging Options,, Options for Debugging Your Program or
5312 @command{gcc}}), you can compile it a second time using
5313 @option{-fbranch-probabilities}, to improve optimizations based on
5314 the number of times each branch was taken. When the program
5315 compiled with @option{-fprofile-arcs} exits it saves arc execution
5316 counts to a file called @file{@var{sourcename}.gcda} for each source
5317 file The information in this data file is very dependent on the
5318 structure of the generated code, so you must use the same source code
5319 and the same optimization options for both compilations.
5321 With @option{-fbranch-probabilities}, GCC puts a
5322 @samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
5323 These can be used to improve optimization. Currently, they are only
5324 used in one place: in @file{reorg.c}, instead of guessing which path a
5325 branch is mostly to take, the @samp{REG_BR_PROB} values are used to
5326 exactly determine which path is taken more often.
5328 @item -fprofile-values
5329 @opindex fprofile-values
5330 If combined with @option{-fprofile-arcs}, it adds code so that some
5331 data about values of expressions in the program is gathered.
5333 With @option{-fbranch-probabilities}, it reads back the data gathered
5334 from profiling values of expressions and adds @samp{REG_VALUE_PROFILE}
5335 notes to instructions for their later usage in optimizations.
5337 Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
5341 If combined with @option{-fprofile-arcs}, it instructs the compiler to add
5342 a code to gather information about values of expressions.
5344 With @option{-fbranch-probabilities}, it reads back the data gathered
5345 and actually performs the optimizations based on them.
5346 Currently the optimizations include specialization of division operation
5347 using the knowledge about the value of the denominator.
5349 @item -fspeculative-prefetching
5350 @opindex fspeculative-prefetching
5351 If combined with @option{-fprofile-arcs}, it instructs the compiler to add
5352 a code to gather information about addresses of memory references in the
5355 With @option{-fbranch-probabilities}, it reads back the data gathered
5356 and issues prefetch instructions according to them. In addition to the opportunities
5357 noticed by @option{-fprefetch-loop-arrays}, it also notices more complicated
5358 memory access patterns---for example accesses to the data stored in linked
5359 list whose elements are usually allocated sequentially.
5361 In order to prevent issuing double prefetches, usage of
5362 @option{-fspeculative-prefetching} implies @option{-fno-prefetch-loop-arrays}.
5364 Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
5366 @item -frename-registers
5367 @opindex frename-registers
5368 Attempt to avoid false dependencies in scheduled code by making use
5369 of registers left over after register allocation. This optimization
5370 will most benefit processors with lots of registers. Depending on the
5371 debug information format adopted by the target, however, it can
5372 make debugging impossible, since variables will no longer stay in
5373 a ``home register''.
5375 Not enabled by default at any level because it has known bugs.
5379 Perform tail duplication to enlarge superblock size. This transformation
5380 simplifies the control flow of the function allowing other optimizations to do
5383 Enabled with @option{-fprofile-use}.
5385 @item -funroll-loops
5386 @opindex funroll-loops
5387 Unroll loops whose number of iterations can be determined at compile time or
5388 upon entry to the loop. @option{-funroll-loops} implies
5389 @option{-frerun-cse-after-loop}. It also turns on complete loop peeling
5390 (i.e.@: complete removal of loops with small constant number of iterations).
5391 This option makes code larger, and may or may not make it run faster.
5393 Enabled with @option{-fprofile-use}.
5395 @item -funroll-all-loops
5396 @opindex funroll-all-loops
5397 Unroll all loops, even if their number of iterations is uncertain when
5398 the loop is entered. This usually makes programs run more slowly.
5399 @option{-funroll-all-loops} implies the same options as
5400 @option{-funroll-loops}.
5403 @opindex fpeel-loops
5404 Peels the loops for that there is enough information that they do not
5405 roll much (from profile feedback). It also turns on complete loop peeling
5406 (i.e.@: complete removal of loops with small constant number of iterations).
5408 Enabled with @option{-fprofile-use}.
5410 @item -fmove-loop-invariants
5411 @opindex fmove-loop-invariants
5412 Enables the loop invariant motion pass in the new loop optimizer. Enabled
5413 at level @option{-O1}
5415 @item -funswitch-loops
5416 @opindex funswitch-loops
5417 Move branches with loop invariant conditions out of the loop, with duplicates
5418 of the loop on both branches (modified according to result of the condition).
5420 @item -fprefetch-loop-arrays
5421 @opindex fprefetch-loop-arrays
5422 If supported by the target machine, generate instructions to prefetch
5423 memory to improve the performance of loops that access large arrays.
5425 Disabled at level @option{-Os}.
5427 @item -ffunction-sections
5428 @itemx -fdata-sections
5429 @opindex ffunction-sections
5430 @opindex fdata-sections
5431 Place each function or data item into its own section in the output
5432 file if the target supports arbitrary sections. The name of the
5433 function or the name of the data item determines the section's name
5436 Use these options on systems where the linker can perform optimizations
5437 to improve locality of reference in the instruction space. Most systems
5438 using the ELF object format and SPARC processors running Solaris 2 have
5439 linkers with such optimizations. AIX may have these optimizations in
5442 Only use these options when there are significant benefits from doing
5443 so. When you specify these options, the assembler and linker will
5444 create larger object and executable files and will also be slower.
5445 You will not be able to use @code{gprof} on all systems if you
5446 specify this option and you may have problems with debugging if
5447 you specify both this option and @option{-g}.
5449 @item -fbranch-target-load-optimize
5450 @opindex fbranch-target-load-optimize
5451 Perform branch target register load optimization before prologue / epilogue
5453 The use of target registers can typically be exposed only during reload,
5454 thus hoisting loads out of loops and doing inter-block scheduling needs
5455 a separate optimization pass.
5457 @item -fbranch-target-load-optimize2
5458 @opindex fbranch-target-load-optimize2
5459 Perform branch target register load optimization after prologue / epilogue
5462 @item -fbtr-bb-exclusive
5463 @opindex fbtr-bb-exclusive
5464 When performing branch target register load optimization, don't reuse
5465 branch target registers in within any basic block.
5467 @item --param @var{name}=@var{value}
5469 In some places, GCC uses various constants to control the amount of
5470 optimization that is done. For example, GCC will not inline functions
5471 that contain more that a certain number of instructions. You can
5472 control some of these constants on the command-line using the
5473 @option{--param} option.
5475 The names of specific parameters, and the meaning of the values, are
5476 tied to the internals of the compiler, and are subject to change
5477 without notice in future releases.
5479 In each case, the @var{value} is an integer. The allowable choices for
5480 @var{name} are given in the following table:
5483 @item salias-max-implicit-fields
5484 The maximum number of fields in a variable without direct
5485 structure accesses for which structure aliasing will consider trying
5486 to track each field. The default is 5
5488 @item sra-max-structure-size
5489 The maximum structure size, in bytes, at which the scalar replacement
5490 of aggregates (SRA) optimization will perform block copies. The
5491 default value, 0, implies that GCC will select the most appropriate
5494 @item sra-field-structure-ratio
5495 The threshold ratio (as a percentage) between instantiated fields and
5496 the complete structure size. We say that if the ratio of the number
5497 of bytes in instantiated fields to the number of bytes in the complete
5498 structure exceeds this parameter, then block copies are not used. The
5501 @item max-crossjump-edges
5502 The maximum number of incoming edges to consider for crossjumping.
5503 The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
5504 the number of edges incoming to each block. Increasing values mean
5505 more aggressive optimization, making the compile time increase with
5506 probably small improvement in executable size.
5508 @item min-crossjump-insns
5509 The minimum number of instructions which must be matched at the end
5510 of two blocks before crossjumping will be performed on them. This
5511 value is ignored in the case where all instructions in the block being
5512 crossjumped from are matched. The default value is 5.
5514 @item max-goto-duplication-insns
5515 The maximum number of instructions to duplicate to a block that jumps
5516 to a computed goto. To avoid @math{O(N^2)} behavior in a number of
5517 passes, GCC factors computed gotos early in the compilation process,
5518 and unfactors them as late as possible. Only computed jumps at the
5519 end of a basic blocks with no more than max-goto-duplication-insns are
5520 unfactored. The default value is 8.
5522 @item max-delay-slot-insn-search
5523 The maximum number of instructions to consider when looking for an
5524 instruction to fill a delay slot. If more than this arbitrary number of
5525 instructions is searched, the time savings from filling the delay slot
5526 will be minimal so stop searching. Increasing values mean more
5527 aggressive optimization, making the compile time increase with probably
5528 small improvement in executable run time.
5530 @item max-delay-slot-live-search
5531 When trying to fill delay slots, the maximum number of instructions to
5532 consider when searching for a block with valid live register
5533 information. Increasing this arbitrarily chosen value means more
5534 aggressive optimization, increasing the compile time. This parameter
5535 should be removed when the delay slot code is rewritten to maintain the
5538 @item max-gcse-memory
5539 The approximate maximum amount of memory that will be allocated in
5540 order to perform the global common subexpression elimination
5541 optimization. If more memory than specified is required, the
5542 optimization will not be done.
5544 @item max-gcse-passes
5545 The maximum number of passes of GCSE to run. The default is 1.
5547 @item max-pending-list-length
5548 The maximum number of pending dependencies scheduling will allow
5549 before flushing the current state and starting over. Large functions
5550 with few branches or calls can create excessively large lists which
5551 needlessly consume memory and resources.
5553 @item max-inline-insns-single
5554 Several parameters control the tree inliner used in gcc.
5555 This number sets the maximum number of instructions (counted in GCC's
5556 internal representation) in a single function that the tree inliner
5557 will consider for inlining. This only affects functions declared
5558 inline and methods implemented in a class declaration (C++).
5559 The default value is 450.
5561 @item max-inline-insns-auto
5562 When you use @option{-finline-functions} (included in @option{-O3}),
5563 a lot of functions that would otherwise not be considered for inlining
5564 by the compiler will be investigated. To those functions, a different
5565 (more restrictive) limit compared to functions declared inline can
5567 The default value is 90.
5569 @item large-function-insns
5570 The limit specifying really large functions. For functions larger than this
5571 limit after inlining inlining is constrained by
5572 @option{--param large-function-growth}. This parameter is useful primarily
5573 to avoid extreme compilation time caused by non-linear algorithms used by the
5575 This parameter is ignored when @option{-funit-at-a-time} is not used.
5576 The default value is 2700.
5578 @item large-function-growth
5579 Specifies maximal growth of large function caused by inlining in percents.
5580 This parameter is ignored when @option{-funit-at-a-time} is not used.
5581 The default value is 100 which limits large function growth to 2.0 times
5584 @item inline-unit-growth
5585 Specifies maximal overall growth of the compilation unit caused by inlining.
5586 This parameter is ignored when @option{-funit-at-a-time} is not used.
5587 The default value is 50 which limits unit growth to 1.5 times the original
5590 @item max-inline-insns-recursive
5591 @itemx max-inline-insns-recursive-auto
5592 Specifies maximum number of instructions out-of-line copy of self recursive inline
5593 function can grow into by performing recursive inlining.
5595 For functions declared inline @option{--param max-inline-insns-recursive} is
5596 taken into acount. For function not declared inline, recursive inlining
5597 happens only when @option{-finline-functions} (included in @option{-O3}) is
5598 enabled and @option{--param max-inline-insns-recursive-auto} is used. The
5599 default value is 450.
5601 @item max-inline-recursive-depth
5602 @itemx max-inline-recursive-depth-auto
5603 Specifies maximum recursion depth used by the recursive inlining.
5605 For functions declared inline @option{--param max-inline-recursive-depth} is
5606 taken into acount. For function not declared inline, recursive inlining
5607 happens only when @option{-finline-functions} (included in @option{-O3}) is
5608 enabled and @option{--param max-inline-recursive-depth-auto} is used. The
5609 default value is 450.
5611 @item inline-call-cost
5612 Specify cost of call instruction relative to simple arithmetics operations
5613 (having cost of 1). Increasing this cost disqualifies inlining of non-leaf
5614 functions and at the same time increases size of leaf function that is believed to
5615 reduce function size by being inlined. In effect it increases amount of
5616 inlining for code having large abstraction penalty (many functions that just
5617 pass the arguments to other functions) and decrease inlining for code with low
5618 abstraction penalty. The default value is 16.
5620 @item max-unrolled-insns
5621 The maximum number of instructions that a loop should have if that loop
5622 is unrolled, and if the loop is unrolled, it determines how many times
5623 the loop code is unrolled.
5625 @item max-average-unrolled-insns
5626 The maximum number of instructions biased by probabilities of their execution
5627 that a loop should have if that loop is unrolled, and if the loop is unrolled,
5628 it determines how many times the loop code is unrolled.
5630 @item max-unroll-times
5631 The maximum number of unrollings of a single loop.
5633 @item max-peeled-insns
5634 The maximum number of instructions that a loop should have if that loop
5635 is peeled, and if the loop is peeled, it determines how many times
5636 the loop code is peeled.
5638 @item max-peel-times
5639 The maximum number of peelings of a single loop.
5641 @item max-completely-peeled-insns
5642 The maximum number of insns of a completely peeled loop.
5644 @item max-completely-peel-times
5645 The maximum number of iterations of a loop to be suitable for complete peeling.
5647 @item max-unswitch-insns
5648 The maximum number of insns of an unswitched loop.
5650 @item max-unswitch-level
5651 The maximum number of branches unswitched in a single loop.
5654 The minimum cost of an expensive expression in the loop invariant motion.
5656 @item iv-consider-all-candidates-bound
5657 Bound on number of candidates for induction variables below that
5658 all candidates are considered for each use in induction variable
5659 optimizations. Only the most relevant candidates are considered
5660 if there are more candidates, to avoid quadratic time complexity.
5662 @item iv-max-considered-uses
5663 The induction variable optimizations give up on loops that contain more
5664 induction variable uses.
5666 @item iv-always-prune-cand-set-bound
5667 If number of candidates in the set is smaller than this value,
5668 we always try to remove unnecessary ivs from the set during its
5669 optimization when a new iv is added to the set.
5671 @item max-iterations-to-track
5673 The maximum number of iterations of a loop the brute force algorithm
5674 for analysis of # of iterations of the loop tries to evaluate.
5676 @item hot-bb-count-fraction
5677 Select fraction of the maximal count of repetitions of basic block in program
5678 given basic block needs to have to be considered hot.
5680 @item hot-bb-frequency-fraction
5681 Select fraction of the maximal frequency of executions of basic block in
5682 function given basic block needs to have to be considered hot
5684 @item tracer-dynamic-coverage
5685 @itemx tracer-dynamic-coverage-feedback
5687 This value is used to limit superblock formation once the given percentage of
5688 executed instructions is covered. This limits unnecessary code size
5691 The @option{tracer-dynamic-coverage-feedback} is used only when profile
5692 feedback is available. The real profiles (as opposed to statically estimated
5693 ones) are much less balanced allowing the threshold to be larger value.
5695 @item tracer-max-code-growth
5696 Stop tail duplication once code growth has reached given percentage. This is
5697 rather hokey argument, as most of the duplicates will be eliminated later in
5698 cross jumping, so it may be set to much higher values than is the desired code
5701 @item tracer-min-branch-ratio
5703 Stop reverse growth when the reverse probability of best edge is less than this
5704 threshold (in percent).
5706 @item tracer-min-branch-ratio
5707 @itemx tracer-min-branch-ratio-feedback
5709 Stop forward growth if the best edge do have probability lower than this
5712 Similarly to @option{tracer-dynamic-coverage} two values are present, one for
5713 compilation for profile feedback and one for compilation without. The value
5714 for compilation with profile feedback needs to be more conservative (higher) in
5715 order to make tracer effective.
5717 @item max-cse-path-length
5719 Maximum number of basic blocks on path that cse considers. The default is 10.
5721 @item global-var-threshold
5723 Counts the number of function calls (@var{n}) and the number of
5724 call-clobbered variables (@var{v}). If @var{n}x@var{v} is larger than this limit, a
5725 single artificial variable will be created to represent all the
5726 call-clobbered variables at function call sites. This artificial
5727 variable will then be made to alias every call-clobbered variable.
5728 (done as @code{int * size_t} on the host machine; beware overflow).
5730 @item max-aliased-vops
5732 Maximum number of virtual operands allowed to represent aliases
5733 before triggering the alias grouping heuristic. Alias grouping
5734 reduces compile times and memory consumption needed for aliasing at
5735 the expense of precision loss in alias information.
5737 @item ggc-min-expand
5739 GCC uses a garbage collector to manage its own memory allocation. This
5740 parameter specifies the minimum percentage by which the garbage
5741 collector's heap should be allowed to expand between collections.
5742 Tuning this may improve compilation speed; it has no effect on code
5745 The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
5746 RAM >= 1GB@. If @code{getrlimit} is available, the notion of "RAM" is
5747 the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If
5748 GCC is not able to calculate RAM on a particular platform, the lower
5749 bound of 30% is used. Setting this parameter and
5750 @option{ggc-min-heapsize} to zero causes a full collection to occur at
5751 every opportunity. This is extremely slow, but can be useful for
5754 @item ggc-min-heapsize
5756 Minimum size of the garbage collector's heap before it begins bothering
5757 to collect garbage. The first collection occurs after the heap expands
5758 by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again,
5759 tuning this may improve compilation speed, and has no effect on code
5762 The default is the smaller of RAM/8, RLIMIT_RSS, or a limit which
5763 tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
5764 with a lower bound of 4096 (four megabytes) and an upper bound of
5765 131072 (128 megabytes). If GCC is not able to calculate RAM on a
5766 particular platform, the lower bound is used. Setting this parameter
5767 very large effectively disables garbage collection. Setting this
5768 parameter and @option{ggc-min-expand} to zero causes a full collection
5769 to occur at every opportunity.
5771 @item max-reload-search-insns
5772 The maximum number of instruction reload should look backward for equivalent
5773 register. Increasing values mean more aggressive optimization, making the
5774 compile time increase with probably slightly better performance. The default
5777 @item max-cselib-memory-location
5778 The maximum number of memory locations cselib should take into acount.
5779 Increasing values mean more aggressive optimization, making the compile time
5780 increase with probably slightly better performance. The default value is 500.
5782 @item reorder-blocks-duplicate
5783 @itemx reorder-blocks-duplicate-feedback
5785 Used by basic block reordering pass to decide whether to use unconditional
5786 branch or duplicate the code on its destination. Code is duplicated when its
5787 estimated size is smaller than this value multiplied by the estimated size of
5788 unconditional jump in the hot spots of the program.
5790 The @option{reorder-block-duplicate-feedback} is used only when profile
5791 feedback is available and may be set to higher values than
5792 @option{reorder-block-duplicate} since information about the hot spots is more
5795 @item max-sched-region-blocks
5796 The maximum number of blocks in a region to be considered for
5797 interblock scheduling. The default value is 10.
5799 @item max-sched-region-insns
5800 The maximum number of insns in a region to be considered for
5801 interblock scheduling. The default value is 100.
5803 @item max-last-value-rtl
5805 The maximum size measured as number of RTLs that can be recorded in an expression
5806 in combiner for a pseudo register as last known value of that register. The default
5809 @item integer-share-limit
5810 Small integer constants can use a shared data structure, reducing the
5811 compiler's memory usage and increasing its speed. This sets the maximum
5812 value of a shared integer constant's. The default value is 256.
5817 @node Preprocessor Options
5818 @section Options Controlling the Preprocessor
5819 @cindex preprocessor options
5820 @cindex options, preprocessor
5822 These options control the C preprocessor, which is run on each C source
5823 file before actual compilation.
5825 If you use the @option{-E} option, nothing is done except preprocessing.
5826 Some of these options make sense only together with @option{-E} because
5827 they cause the preprocessor output to be unsuitable for actual
5832 You can use @option{-Wp,@var{option}} to bypass the compiler driver
5833 and pass @var{option} directly through to the preprocessor. If
5834 @var{option} contains commas, it is split into multiple options at the
5835 commas. However, many options are modified, translated or interpreted
5836 by the compiler driver before being passed to the preprocessor, and
5837 @option{-Wp} forcibly bypasses this phase. The preprocessor's direct
5838 interface is undocumented and subject to change, so whenever possible
5839 you should avoid using @option{-Wp} and let the driver handle the
5842 @item -Xpreprocessor @var{option}
5843 @opindex preprocessor
5844 Pass @var{option} as an option to the preprocessor. You can use this to
5845 supply system-specific preprocessor options which GCC does not know how to
5848 If you want to pass an option that takes an argument, you must use
5849 @option{-Xpreprocessor} twice, once for the option and once for the argument.
5852 @include cppopts.texi
5854 @node Assembler Options
5855 @section Passing Options to the Assembler
5857 @c prevent bad page break with this line
5858 You can pass options to the assembler.
5861 @item -Wa,@var{option}
5863 Pass @var{option} as an option to the assembler. If @var{option}
5864 contains commas, it is split into multiple options at the commas.
5866 @item -Xassembler @var{option}
5868 Pass @var{option} as an option to the assembler. You can use this to
5869 supply system-specific assembler options which GCC does not know how to
5872 If you want to pass an option that takes an argument, you must use
5873 @option{-Xassembler} twice, once for the option and once for the argument.
5878 @section Options for Linking
5879 @cindex link options
5880 @cindex options, linking
5882 These options come into play when the compiler links object files into
5883 an executable output file. They are meaningless if the compiler is
5884 not doing a link step.
5888 @item @var{object-file-name}
5889 A file name that does not end in a special recognized suffix is
5890 considered to name an object file or library. (Object files are
5891 distinguished from libraries by the linker according to the file
5892 contents.) If linking is done, these object files are used as input
5901 If any of these options is used, then the linker is not run, and
5902 object file names should not be used as arguments. @xref{Overall
5906 @item -l@var{library}
5907 @itemx -l @var{library}
5909 Search the library named @var{library} when linking. (The second
5910 alternative with the library as a separate argument is only for
5911 POSIX compliance and is not recommended.)
5913 It makes a difference where in the command you write this option; the
5914 linker searches and processes libraries and object files in the order they
5915 are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
5916 after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
5917 to functions in @samp{z}, those functions may not be loaded.
5919 The linker searches a standard list of directories for the library,
5920 which is actually a file named @file{lib@var{library}.a}. The linker
5921 then uses this file as if it had been specified precisely by name.
5923 The directories searched include several standard system directories
5924 plus any that you specify with @option{-L}.
5926 Normally the files found this way are library files---archive files
5927 whose members are object files. The linker handles an archive file by
5928 scanning through it for members which define symbols that have so far
5929 been referenced but not defined. But if the file that is found is an
5930 ordinary object file, it is linked in the usual fashion. The only
5931 difference between using an @option{-l} option and specifying a file name
5932 is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
5933 and searches several directories.
5937 You need this special case of the @option{-l} option in order to
5938 link an Objective-C or Objective-C++ program.
5941 @opindex nostartfiles
5942 Do not use the standard system startup files when linking.
5943 The standard system libraries are used normally, unless @option{-nostdlib}
5944 or @option{-nodefaultlibs} is used.
5946 @item -nodefaultlibs
5947 @opindex nodefaultlibs
5948 Do not use the standard system libraries when linking.
5949 Only the libraries you specify will be passed to the linker.
5950 The standard startup files are used normally, unless @option{-nostartfiles}
5951 is used. The compiler may generate calls to @code{memcmp},
5952 @code{memset}, @code{memcpy} and @code{memmove}.
5953 These entries are usually resolved by entries in
5954 libc. These entry points should be supplied through some other
5955 mechanism when this option is specified.
5959 Do not use the standard system startup files or libraries when linking.
5960 No startup files and only the libraries you specify will be passed to
5961 the linker. The compiler may generate calls to @code{memcmp}, @code{memset},
5962 @code{memcpy} and @code{memmove}.
5963 These entries are usually resolved by entries in
5964 libc. These entry points should be supplied through some other
5965 mechanism when this option is specified.
5967 @cindex @option{-lgcc}, use with @option{-nostdlib}
5968 @cindex @option{-nostdlib} and unresolved references
5969 @cindex unresolved references and @option{-nostdlib}
5970 @cindex @option{-lgcc}, use with @option{-nodefaultlibs}
5971 @cindex @option{-nodefaultlibs} and unresolved references
5972 @cindex unresolved references and @option{-nodefaultlibs}
5973 One of the standard libraries bypassed by @option{-nostdlib} and
5974 @option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
5975 that GCC uses to overcome shortcomings of particular machines, or special
5976 needs for some languages.
5977 (@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
5978 Collection (GCC) Internals},
5979 for more discussion of @file{libgcc.a}.)
5980 In most cases, you need @file{libgcc.a} even when you want to avoid
5981 other standard libraries. In other words, when you specify @option{-nostdlib}
5982 or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
5983 This ensures that you have no unresolved references to internal GCC
5984 library subroutines. (For example, @samp{__main}, used to ensure C++
5985 constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
5986 GNU Compiler Collection (GCC) Internals}.)
5990 Produce a position independent executable on targets which support it.
5991 For predictable results, you must also specify the same set of options
5992 that were used to generate code (@option{-fpie}, @option{-fPIE},
5993 or model suboptions) when you specify this option.
5997 Remove all symbol table and relocation information from the executable.
6001 On systems that support dynamic linking, this prevents linking with the shared
6002 libraries. On other systems, this option has no effect.
6006 Produce a shared object which can then be linked with other objects to
6007 form an executable. Not all systems support this option. For predictable
6008 results, you must also specify the same set of options that were used to
6009 generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
6010 when you specify this option.@footnote{On some systems, @samp{gcc -shared}
6011 needs to build supplementary stub code for constructors to work. On
6012 multi-libbed systems, @samp{gcc -shared} must select the correct support
6013 libraries to link against. Failing to supply the correct flags may lead
6014 to subtle defects. Supplying them in cases where they are not necessary
6017 @item -shared-libgcc
6018 @itemx -static-libgcc
6019 @opindex shared-libgcc
6020 @opindex static-libgcc
6021 On systems that provide @file{libgcc} as a shared library, these options
6022 force the use of either the shared or static version respectively.
6023 If no shared version of @file{libgcc} was built when the compiler was
6024 configured, these options have no effect.
6026 There are several situations in which an application should use the
6027 shared @file{libgcc} instead of the static version. The most common
6028 of these is when the application wishes to throw and catch exceptions
6029 across different shared libraries. In that case, each of the libraries
6030 as well as the application itself should use the shared @file{libgcc}.
6032 Therefore, the G++ and GCJ drivers automatically add
6033 @option{-shared-libgcc} whenever you build a shared library or a main
6034 executable, because C++ and Java programs typically use exceptions, so
6035 this is the right thing to do.
6037 If, instead, you use the GCC driver to create shared libraries, you may
6038 find that they will not always be linked with the shared @file{libgcc}.
6039 If GCC finds, at its configuration time, that you have a non-GNU linker
6040 or a GNU linker that does not support option @option{--eh-frame-hdr},
6041 it will link the shared version of @file{libgcc} into shared libraries
6042 by default. Otherwise, it will take advantage of the linker and optimize
6043 away the linking with the shared version of @file{libgcc}, linking with
6044 the static version of libgcc by default. This allows exceptions to
6045 propagate through such shared libraries, without incurring relocation
6046 costs at library load time.
6048 However, if a library or main executable is supposed to throw or catch
6049 exceptions, you must link it using the G++ or GCJ driver, as appropriate
6050 for the languages used in the program, or using the option
6051 @option{-shared-libgcc}, such that it is linked with the shared
6056 Bind references to global symbols when building a shared object. Warn
6057 about any unresolved references (unless overridden by the link editor
6058 option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
6061 @item -Xlinker @var{option}
6063 Pass @var{option} as an option to the linker. You can use this to
6064 supply system-specific linker options which GCC does not know how to
6067 If you want to pass an option that takes an argument, you must use
6068 @option{-Xlinker} twice, once for the option and once for the argument.
6069 For example, to pass @option{-assert definitions}, you must write
6070 @samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
6071 @option{-Xlinker "-assert definitions"}, because this passes the entire
6072 string as a single argument, which is not what the linker expects.
6074 @item -Wl,@var{option}
6076 Pass @var{option} as an option to the linker. If @var{option} contains
6077 commas, it is split into multiple options at the commas.
6079 @item -u @var{symbol}
6081 Pretend the symbol @var{symbol} is undefined, to force linking of
6082 library modules to define it. You can use @option{-u} multiple times with
6083 different symbols to force loading of additional library modules.
6086 @node Directory Options
6087 @section Options for Directory Search
6088 @cindex directory options
6089 @cindex options, directory search
6092 These options specify directories to search for header files, for
6093 libraries and for parts of the compiler:
6098 Add the directory @var{dir} to the head of the list of directories to be
6099 searched for header files. This can be used to override a system header
6100 file, substituting your own version, since these directories are
6101 searched before the system header file directories. However, you should
6102 not use this option to add directories that contain vendor-supplied
6103 system header files (use @option{-isystem} for that). If you use more than
6104 one @option{-I} option, the directories are scanned in left-to-right
6105 order; the standard system directories come after.
6107 If a standard system include directory, or a directory specified with
6108 @option{-isystem}, is also specified with @option{-I}, the @option{-I}
6109 option will be ignored. The directory will still be searched but as a
6110 system directory at its normal position in the system include chain.
6111 This is to ensure that GCC's procedure to fix buggy system headers and
6112 the ordering for the include_next directive are not inadvertently changed.
6113 If you really need to change the search order for system directories,
6114 use the @option{-nostdinc} and/or @option{-isystem} options.
6116 @item -iquote@var{dir}
6118 Add the directory @var{dir} to the head of the list of directories to
6119 be searched for header files only for the case of @samp{#include
6120 "@var{file}"}; they are not searched for @samp{#include <@var{file}>},
6121 otherwise just like @option{-I}.
6125 Add directory @var{dir} to the list of directories to be searched
6128 @item -B@var{prefix}
6130 This option specifies where to find the executables, libraries,
6131 include files, and data files of the compiler itself.
6133 The compiler driver program runs one or more of the subprograms
6134 @file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
6135 @var{prefix} as a prefix for each program it tries to run, both with and
6136 without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
6138 For each subprogram to be run, the compiler driver first tries the
6139 @option{-B} prefix, if any. If that name is not found, or if @option{-B}
6140 was not specified, the driver tries two standard prefixes, which are
6141 @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of
6142 those results in a file name that is found, the unmodified program
6143 name is searched for using the directories specified in your
6144 @env{PATH} environment variable.
6146 The compiler will check to see if the path provided by the @option{-B}
6147 refers to a directory, and if necessary it will add a directory
6148 separator character at the end of the path.
6150 @option{-B} prefixes that effectively specify directory names also apply
6151 to libraries in the linker, because the compiler translates these
6152 options into @option{-L} options for the linker. They also apply to
6153 includes files in the preprocessor, because the compiler translates these
6154 options into @option{-isystem} options for the preprocessor. In this case,
6155 the compiler appends @samp{include} to the prefix.
6157 The run-time support file @file{libgcc.a} can also be searched for using
6158 the @option{-B} prefix, if needed. If it is not found there, the two
6159 standard prefixes above are tried, and that is all. The file is left
6160 out of the link if it is not found by those means.
6162 Another way to specify a prefix much like the @option{-B} prefix is to use
6163 the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
6166 As a special kludge, if the path provided by @option{-B} is
6167 @file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
6168 9, then it will be replaced by @file{[dir/]include}. This is to help
6169 with boot-strapping the compiler.
6171 @item -specs=@var{file}
6173 Process @var{file} after the compiler reads in the standard @file{specs}
6174 file, in order to override the defaults that the @file{gcc} driver
6175 program uses when determining what switches to pass to @file{cc1},
6176 @file{cc1plus}, @file{as}, @file{ld}, etc. More than one
6177 @option{-specs=@var{file}} can be specified on the command line, and they
6178 are processed in order, from left to right.
6182 This option has been deprecated. Please use @option{-iquote} instead for
6183 @option{-I} directories before the @option{-I-} and remove the @option{-I-}.
6184 Any directories you specify with @option{-I} options before the @option{-I-}
6185 option are searched only for the case of @samp{#include "@var{file}"};
6186 they are not searched for @samp{#include <@var{file}>}.
6188 If additional directories are specified with @option{-I} options after
6189 the @option{-I-}, these directories are searched for all @samp{#include}
6190 directives. (Ordinarily @emph{all} @option{-I} directories are used
6193 In addition, the @option{-I-} option inhibits the use of the current
6194 directory (where the current input file came from) as the first search
6195 directory for @samp{#include "@var{file}"}. There is no way to
6196 override this effect of @option{-I-}. With @option{-I.} you can specify
6197 searching the directory which was current when the compiler was
6198 invoked. That is not exactly the same as what the preprocessor does
6199 by default, but it is often satisfactory.
6201 @option{-I-} does not inhibit the use of the standard system directories
6202 for header files. Thus, @option{-I-} and @option{-nostdinc} are
6209 @section Specifying subprocesses and the switches to pass to them
6212 @command{gcc} is a driver program. It performs its job by invoking a
6213 sequence of other programs to do the work of compiling, assembling and
6214 linking. GCC interprets its command-line parameters and uses these to
6215 deduce which programs it should invoke, and which command-line options
6216 it ought to place on their command lines. This behavior is controlled
6217 by @dfn{spec strings}. In most cases there is one spec string for each
6218 program that GCC can invoke, but a few programs have multiple spec
6219 strings to control their behavior. The spec strings built into GCC can
6220 be overridden by using the @option{-specs=} command-line switch to specify
6223 @dfn{Spec files} are plaintext files that are used to construct spec
6224 strings. They consist of a sequence of directives separated by blank
6225 lines. The type of directive is determined by the first non-whitespace
6226 character on the line and it can be one of the following:
6229 @item %@var{command}
6230 Issues a @var{command} to the spec file processor. The commands that can
6234 @item %include <@var{file}>
6236 Search for @var{file} and insert its text at the current point in the
6239 @item %include_noerr <@var{file}>
6240 @cindex %include_noerr
6241 Just like @samp{%include}, but do not generate an error message if the include
6242 file cannot be found.
6244 @item %rename @var{old_name} @var{new_name}
6246 Rename the spec string @var{old_name} to @var{new_name}.
6250 @item *[@var{spec_name}]:
6251 This tells the compiler to create, override or delete the named spec
6252 string. All lines after this directive up to the next directive or
6253 blank line are considered to be the text for the spec string. If this
6254 results in an empty string then the spec will be deleted. (Or, if the
6255 spec did not exist, then nothing will happened.) Otherwise, if the spec
6256 does not currently exist a new spec will be created. If the spec does
6257 exist then its contents will be overridden by the text of this
6258 directive, unless the first character of that text is the @samp{+}
6259 character, in which case the text will be appended to the spec.
6261 @item [@var{suffix}]:
6262 Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
6263 and up to the next directive or blank line are considered to make up the
6264 spec string for the indicated suffix. When the compiler encounters an
6265 input file with the named suffix, it will processes the spec string in
6266 order to work out how to compile that file. For example:
6273 This says that any input file whose name ends in @samp{.ZZ} should be
6274 passed to the program @samp{z-compile}, which should be invoked with the
6275 command-line switch @option{-input} and with the result of performing the
6276 @samp{%i} substitution. (See below.)
6278 As an alternative to providing a spec string, the text that follows a
6279 suffix directive can be one of the following:
6282 @item @@@var{language}
6283 This says that the suffix is an alias for a known @var{language}. This is
6284 similar to using the @option{-x} command-line switch to GCC to specify a
6285 language explicitly. For example:
6292 Says that .ZZ files are, in fact, C++ source files.
6295 This causes an error messages saying:
6298 @var{name} compiler not installed on this system.
6302 GCC already has an extensive list of suffixes built into it.
6303 This directive will add an entry to the end of the list of suffixes, but
6304 since the list is searched from the end backwards, it is effectively
6305 possible to override earlier entries using this technique.
6309 GCC has the following spec strings built into it. Spec files can
6310 override these strings or create their own. Note that individual
6311 targets can also add their own spec strings to this list.
6314 asm Options to pass to the assembler
6315 asm_final Options to pass to the assembler post-processor
6316 cpp Options to pass to the C preprocessor
6317 cc1 Options to pass to the C compiler
6318 cc1plus Options to pass to the C++ compiler
6319 endfile Object files to include at the end of the link
6320 link Options to pass to the linker
6321 lib Libraries to include on the command line to the linker
6322 libgcc Decides which GCC support library to pass to the linker
6323 linker Sets the name of the linker
6324 predefines Defines to be passed to the C preprocessor
6325 signed_char Defines to pass to CPP to say whether @code{char} is signed
6327 startfile Object files to include at the start of the link
6330 Here is a small example of a spec file:
6336 --start-group -lgcc -lc -leval1 --end-group %(old_lib)
6339 This example renames the spec called @samp{lib} to @samp{old_lib} and
6340 then overrides the previous definition of @samp{lib} with a new one.
6341 The new definition adds in some extra command-line options before
6342 including the text of the old definition.
6344 @dfn{Spec strings} are a list of command-line options to be passed to their
6345 corresponding program. In addition, the spec strings can contain
6346 @samp{%}-prefixed sequences to substitute variable text or to
6347 conditionally insert text into the command line. Using these constructs
6348 it is possible to generate quite complex command lines.
6350 Here is a table of all defined @samp{%}-sequences for spec
6351 strings. Note that spaces are not generated automatically around the
6352 results of expanding these sequences. Therefore you can concatenate them
6353 together or combine them with constant text in a single argument.
6357 Substitute one @samp{%} into the program name or argument.
6360 Substitute the name of the input file being processed.
6363 Substitute the basename of the input file being processed.
6364 This is the substring up to (and not including) the last period
6365 and not including the directory.
6368 This is the same as @samp{%b}, but include the file suffix (text after
6372 Marks the argument containing or following the @samp{%d} as a
6373 temporary file name, so that that file will be deleted if GCC exits
6374 successfully. Unlike @samp{%g}, this contributes no text to the
6377 @item %g@var{suffix}
6378 Substitute a file name that has suffix @var{suffix} and is chosen
6379 once per compilation, and mark the argument in the same way as
6380 @samp{%d}. To reduce exposure to denial-of-service attacks, the file
6381 name is now chosen in a way that is hard to predict even when previously
6382 chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
6383 might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
6384 the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
6385 treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
6386 was simply substituted with a file name chosen once per compilation,
6387 without regard to any appended suffix (which was therefore treated
6388 just like ordinary text), making such attacks more likely to succeed.
6390 @item %u@var{suffix}
6391 Like @samp{%g}, but generates a new temporary file name even if
6392 @samp{%u@var{suffix}} was already seen.
6394 @item %U@var{suffix}
6395 Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
6396 new one if there is no such last file name. In the absence of any
6397 @samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
6398 the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
6399 would involve the generation of two distinct file names, one
6400 for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
6401 simply substituted with a file name chosen for the previous @samp{%u},
6402 without regard to any appended suffix.
6404 @item %j@var{suffix}
6405 Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
6406 writable, and if save-temps is off; otherwise, substitute the name
6407 of a temporary file, just like @samp{%u}. This temporary file is not
6408 meant for communication between processes, but rather as a junk
6411 @item %|@var{suffix}
6412 @itemx %m@var{suffix}
6413 Like @samp{%g}, except if @option{-pipe} is in effect. In that case
6414 @samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
6415 all. These are the two most common ways to instruct a program that it
6416 should read from standard input or write to standard output. If you
6417 need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
6418 construct: see for example @file{f/lang-specs.h}.
6420 @item %.@var{SUFFIX}
6421 Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
6422 when it is subsequently output with @samp{%*}. @var{SUFFIX} is
6423 terminated by the next space or %.
6426 Marks the argument containing or following the @samp{%w} as the
6427 designated output file of this compilation. This puts the argument
6428 into the sequence of arguments that @samp{%o} will substitute later.
6431 Substitutes the names of all the output files, with spaces
6432 automatically placed around them. You should write spaces
6433 around the @samp{%o} as well or the results are undefined.
6434 @samp{%o} is for use in the specs for running the linker.
6435 Input files whose names have no recognized suffix are not compiled
6436 at all, but they are included among the output files, so they will
6440 Substitutes the suffix for object files. Note that this is
6441 handled specially when it immediately follows @samp{%g, %u, or %U},
6442 because of the need for those to form complete file names. The
6443 handling is such that @samp{%O} is treated exactly as if it had already
6444 been substituted, except that @samp{%g, %u, and %U} do not currently
6445 support additional @var{suffix} characters following @samp{%O} as they would
6446 following, for example, @samp{.o}.
6449 Substitutes the standard macro predefinitions for the
6450 current target machine. Use this when running @code{cpp}.
6453 Like @samp{%p}, but puts @samp{__} before and after the name of each
6454 predefined macro, except for macros that start with @samp{__} or with
6455 @samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
6459 Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
6460 @option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}), and
6461 @option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
6465 Current argument is the name of a library or startup file of some sort.
6466 Search for that file in a standard list of directories and substitute
6467 the full name found.
6470 Print @var{str} as an error message. @var{str} is terminated by a newline.
6471 Use this when inconsistent options are detected.
6474 Substitute the contents of spec string @var{name} at this point.
6477 Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
6479 @item %x@{@var{option}@}
6480 Accumulate an option for @samp{%X}.
6483 Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
6487 Output the accumulated assembler options specified by @option{-Wa}.
6490 Output the accumulated preprocessor options specified by @option{-Wp}.
6493 Process the @code{asm} spec. This is used to compute the
6494 switches to be passed to the assembler.
6497 Process the @code{asm_final} spec. This is a spec string for
6498 passing switches to an assembler post-processor, if such a program is
6502 Process the @code{link} spec. This is the spec for computing the
6503 command line passed to the linker. Typically it will make use of the
6504 @samp{%L %G %S %D and %E} sequences.
6507 Dump out a @option{-L} option for each directory that GCC believes might
6508 contain startup files. If the target supports multilibs then the
6509 current multilib directory will be prepended to each of these paths.
6512 Process the @code{lib} spec. This is a spec string for deciding which
6513 libraries should be included on the command line to the linker.
6516 Process the @code{libgcc} spec. This is a spec string for deciding
6517 which GCC support library should be included on the command line to the linker.
6520 Process the @code{startfile} spec. This is a spec for deciding which
6521 object files should be the first ones passed to the linker. Typically
6522 this might be a file named @file{crt0.o}.
6525 Process the @code{endfile} spec. This is a spec string that specifies
6526 the last object files that will be passed to the linker.
6529 Process the @code{cpp} spec. This is used to construct the arguments
6530 to be passed to the C preprocessor.
6533 Process the @code{cc1} spec. This is used to construct the options to be
6534 passed to the actual C compiler (@samp{cc1}).
6537 Process the @code{cc1plus} spec. This is used to construct the options to be
6538 passed to the actual C++ compiler (@samp{cc1plus}).
6541 Substitute the variable part of a matched option. See below.
6542 Note that each comma in the substituted string is replaced by
6546 Remove all occurrences of @code{-S} from the command line. Note---this
6547 command is position dependent. @samp{%} commands in the spec string
6548 before this one will see @code{-S}, @samp{%} commands in the spec string
6549 after this one will not.
6551 @item %:@var{function}(@var{args})
6552 Call the named function @var{function}, passing it @var{args}.
6553 @var{args} is first processed as a nested spec string, then split
6554 into an argument vector in the usual fashion. The function returns
6555 a string which is processed as if it had appeared literally as part
6556 of the current spec.
6558 The following built-in spec functions are provided:
6561 @item @code{if-exists}
6562 The @code{if-exists} spec function takes one argument, an absolute
6563 pathname to a file. If the file exists, @code{if-exists} returns the
6564 pathname. Here is a small example of its usage:
6568 crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
6571 @item @code{if-exists-else}
6572 The @code{if-exists-else} spec function is similar to the @code{if-exists}
6573 spec function, except that it takes two arguments. The first argument is
6574 an absolute pathname to a file. If the file exists, @code{if-exists-else}
6575 returns the pathname. If it does not exist, it returns the second argument.
6576 This way, @code{if-exists-else} can be used to select one file or another,
6577 based on the existence of the first. Here is a small example of its usage:
6581 crt0%O%s %:if-exists(crti%O%s) \
6582 %:if-exists-else(crtbeginT%O%s crtbegin%O%s)
6585 @item @code{replace-outfile}
6586 The @code{replace-outfile} spec function takes two arguments. It looks for the
6587 first argument in the outfiles array and replaces it with the second argument. Here
6588 is a small example of its usage:
6591 %@{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)@}
6597 Substitutes the @code{-S} switch, if that switch was given to GCC@.
6598 If that switch was not specified, this substitutes nothing. Note that
6599 the leading dash is omitted when specifying this option, and it is
6600 automatically inserted if the substitution is performed. Thus the spec
6601 string @samp{%@{foo@}} would match the command-line option @option{-foo}
6602 and would output the command line option @option{-foo}.
6604 @item %W@{@code{S}@}
6605 Like %@{@code{S}@} but mark last argument supplied within as a file to be
6608 @item %@{@code{S}*@}
6609 Substitutes all the switches specified to GCC whose names start
6610 with @code{-S}, but which also take an argument. This is used for
6611 switches like @option{-o}, @option{-D}, @option{-I}, etc.
6612 GCC considers @option{-o foo} as being
6613 one switch whose names starts with @samp{o}. %@{o*@} would substitute this
6614 text, including the space. Thus two arguments would be generated.
6616 @item %@{@code{S}*&@code{T}*@}
6617 Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
6618 (the order of @code{S} and @code{T} in the spec is not significant).
6619 There can be any number of ampersand-separated variables; for each the
6620 wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
6622 @item %@{@code{S}:@code{X}@}
6623 Substitutes @code{X}, if the @samp{-S} switch was given to GCC@.
6625 @item %@{!@code{S}:@code{X}@}
6626 Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@.
6628 @item %@{@code{S}*:@code{X}@}
6629 Substitutes @code{X} if one or more switches whose names start with
6630 @code{-S} are specified to GCC@. Normally @code{X} is substituted only
6631 once, no matter how many such switches appeared. However, if @code{%*}
6632 appears somewhere in @code{X}, then @code{X} will be substituted once
6633 for each matching switch, with the @code{%*} replaced by the part of
6634 that switch that matched the @code{*}.
6636 @item %@{.@code{S}:@code{X}@}
6637 Substitutes @code{X}, if processing a file with suffix @code{S}.
6639 @item %@{!.@code{S}:@code{X}@}
6640 Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
6642 @item %@{@code{S}|@code{P}:@code{X}@}
6643 Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@.
6644 This may be combined with @samp{!}, @samp{.}, and @code{*} sequences as well,
6645 although they have a stronger binding than the @samp{|}. If @code{%*}
6646 appears in @code{X}, all of the alternatives must be starred, and only
6647 the first matching alternative is substituted.
6649 For example, a spec string like this:
6652 %@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
6655 will output the following command-line options from the following input
6656 command-line options:
6661 -d fred.c -foo -baz -boggle
6662 -d jim.d -bar -baz -boggle
6665 @item %@{S:X; T:Y; :D@}
6667 If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was
6668 given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
6669 be as many clauses as you need. This may be combined with @code{.},
6670 @code{!}, @code{|}, and @code{*} as needed.
6675 The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
6676 construct may contain other nested @samp{%} constructs or spaces, or
6677 even newlines. They are processed as usual, as described above.
6678 Trailing white space in @code{X} is ignored. White space may also
6679 appear anywhere on the left side of the colon in these constructs,
6680 except between @code{.} or @code{*} and the corresponding word.
6682 The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
6683 handled specifically in these constructs. If another value of
6684 @option{-O} or the negated form of a @option{-f}, @option{-m}, or
6685 @option{-W} switch is found later in the command line, the earlier
6686 switch value is ignored, except with @{@code{S}*@} where @code{S} is
6687 just one letter, which passes all matching options.
6689 The character @samp{|} at the beginning of the predicate text is used to
6690 indicate that a command should be piped to the following command, but
6691 only if @option{-pipe} is specified.
6693 It is built into GCC which switches take arguments and which do not.
6694 (You might think it would be useful to generalize this to allow each
6695 compiler's spec to say which switches take arguments. But this cannot
6696 be done in a consistent fashion. GCC cannot even decide which input
6697 files have been specified without knowing which switches take arguments,
6698 and it must know which input files to compile in order to tell which
6701 GCC also knows implicitly that arguments starting in @option{-l} are to be
6702 treated as compiler output files, and passed to the linker in their
6703 proper position among the other output files.
6705 @c man begin OPTIONS
6707 @node Target Options
6708 @section Specifying Target Machine and Compiler Version
6709 @cindex target options
6710 @cindex cross compiling
6711 @cindex specifying machine version
6712 @cindex specifying compiler version and target machine
6713 @cindex compiler version, specifying
6714 @cindex target machine, specifying
6716 The usual way to run GCC is to run the executable called @file{gcc}, or
6717 @file{<machine>-gcc} when cross-compiling, or
6718 @file{<machine>-gcc-<version>} to run a version other than the one that
6719 was installed last. Sometimes this is inconvenient, so GCC provides
6720 options that will switch to another cross-compiler or version.
6723 @item -b @var{machine}
6725 The argument @var{machine} specifies the target machine for compilation.
6727 The value to use for @var{machine} is the same as was specified as the
6728 machine type when configuring GCC as a cross-compiler. For
6729 example, if a cross-compiler was configured with @samp{configure
6730 i386v}, meaning to compile for an 80386 running System V, then you
6731 would specify @option{-b i386v} to run that cross compiler.
6733 @item -V @var{version}
6735 The argument @var{version} specifies which version of GCC to run.
6736 This is useful when multiple versions are installed. For example,
6737 @var{version} might be @samp{2.0}, meaning to run GCC version 2.0.
6740 The @option{-V} and @option{-b} options work by running the
6741 @file{<machine>-gcc-<version>} executable, so there's no real reason to
6742 use them if you can just run that directly.
6744 @node Submodel Options
6745 @section Hardware Models and Configurations
6746 @cindex submodel options
6747 @cindex specifying hardware config
6748 @cindex hardware models and configurations, specifying
6749 @cindex machine dependent options
6751 Earlier we discussed the standard option @option{-b} which chooses among
6752 different installed compilers for completely different target
6753 machines, such as VAX vs.@: 68000 vs.@: 80386.
6755 In addition, each of these target machine types can have its own
6756 special options, starting with @samp{-m}, to choose among various
6757 hardware models or configurations---for example, 68010 vs 68020,
6758 floating coprocessor or none. A single installed version of the
6759 compiler can compile for any model or configuration, according to the
6762 Some configurations of the compiler also support additional special
6763 options, usually for compatibility with other compilers on the same
6766 These options are defined by the macro @code{TARGET_SWITCHES} in the
6767 machine description. The default for the options is also defined by
6768 that macro, which enables you to change the defaults.
6770 @c This list is ordered alphanumerically by subsection name.
6771 @c It should be the same order and spelling as these options are listed
6772 @c in Machine Dependent Options
6778 * Blackfin Options::
6781 * DEC Alpha Options::
6782 * DEC Alpha/VMS Options::
6786 * i386 and x86-64 Options::
6798 * RS/6000 and PowerPC Options::
6799 * S/390 and zSeries Options::
6802 * System V Options::
6803 * TMS320C3x/C4x Options::
6807 * Xstormy16 Options::
6813 @subsection ARC Options
6816 These options are defined for ARC implementations:
6821 Compile code for little endian mode. This is the default.
6825 Compile code for big endian mode.
6828 @opindex mmangle-cpu
6829 Prepend the name of the cpu to all public symbol names.
6830 In multiple-processor systems, there are many ARC variants with different
6831 instruction and register set characteristics. This flag prevents code
6832 compiled for one cpu to be linked with code compiled for another.
6833 No facility exists for handling variants that are ``almost identical''.
6834 This is an all or nothing option.
6836 @item -mcpu=@var{cpu}
6838 Compile code for ARC variant @var{cpu}.
6839 Which variants are supported depend on the configuration.
6840 All variants support @option{-mcpu=base}, this is the default.
6842 @item -mtext=@var{text-section}
6843 @itemx -mdata=@var{data-section}
6844 @itemx -mrodata=@var{readonly-data-section}
6848 Put functions, data, and readonly data in @var{text-section},
6849 @var{data-section}, and @var{readonly-data-section} respectively
6850 by default. This can be overridden with the @code{section} attribute.
6851 @xref{Variable Attributes}.
6856 @subsection ARM Options
6859 These @samp{-m} options are defined for Advanced RISC Machines (ARM)
6863 @item -mabi=@var{name}
6865 Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu},
6866 @samp{atpcs}, @samp{aapcs} and @samp{iwmmxt}.
6869 @opindex mapcs-frame
6870 Generate a stack frame that is compliant with the ARM Procedure Call
6871 Standard for all functions, even if this is not strictly necessary for
6872 correct execution of the code. Specifying @option{-fomit-frame-pointer}
6873 with this option will cause the stack frames not to be generated for
6874 leaf functions. The default is @option{-mno-apcs-frame}.
6878 This is a synonym for @option{-mapcs-frame}.
6881 @c not currently implemented
6882 @item -mapcs-stack-check
6883 @opindex mapcs-stack-check
6884 Generate code to check the amount of stack space available upon entry to
6885 every function (that actually uses some stack space). If there is
6886 insufficient space available then either the function
6887 @samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
6888 called, depending upon the amount of stack space required. The run time
6889 system is required to provide these functions. The default is
6890 @option{-mno-apcs-stack-check}, since this produces smaller code.
6892 @c not currently implemented
6894 @opindex mapcs-float
6895 Pass floating point arguments using the float point registers. This is
6896 one of the variants of the APCS@. This option is recommended if the
6897 target hardware has a floating point unit or if a lot of floating point
6898 arithmetic is going to be performed by the code. The default is
6899 @option{-mno-apcs-float}, since integer only code is slightly increased in
6900 size if @option{-mapcs-float} is used.
6902 @c not currently implemented
6903 @item -mapcs-reentrant
6904 @opindex mapcs-reentrant
6905 Generate reentrant, position independent code. The default is
6906 @option{-mno-apcs-reentrant}.
6909 @item -mthumb-interwork
6910 @opindex mthumb-interwork
6911 Generate code which supports calling between the ARM and Thumb
6912 instruction sets. Without this option the two instruction sets cannot
6913 be reliably used inside one program. The default is
6914 @option{-mno-thumb-interwork}, since slightly larger code is generated
6915 when @option{-mthumb-interwork} is specified.
6917 @item -mno-sched-prolog
6918 @opindex mno-sched-prolog
6919 Prevent the reordering of instructions in the function prolog, or the
6920 merging of those instruction with the instructions in the function's
6921 body. This means that all functions will start with a recognizable set
6922 of instructions (or in fact one of a choice from a small set of
6923 different function prologues), and this information can be used to
6924 locate the start if functions inside an executable piece of code. The
6925 default is @option{-msched-prolog}.
6928 @opindex mhard-float
6929 Generate output containing floating point instructions. This is the
6933 @opindex msoft-float
6934 Generate output containing library calls for floating point.
6935 @strong{Warning:} the requisite libraries are not available for all ARM
6936 targets. Normally the facilities of the machine's usual C compiler are
6937 used, but this cannot be done directly in cross-compilation. You must make
6938 your own arrangements to provide suitable library functions for
6941 @option{-msoft-float} changes the calling convention in the output file;
6942 therefore, it is only useful if you compile @emph{all} of a program with
6943 this option. In particular, you need to compile @file{libgcc.a}, the
6944 library that comes with GCC, with @option{-msoft-float} in order for
6947 @item -mfloat-abi=@var{name}
6949 Specifies which ABI to use for floating point values. Permissible values
6950 are: @samp{soft}, @samp{softfp} and @samp{hard}.
6952 @samp{soft} and @samp{hard} are equivalent to @option{-msoft-float}
6953 and @option{-mhard-float} respectively. @samp{softfp} allows the generation
6954 of floating point instructions, but still uses the soft-float calling
6957 @item -mlittle-endian
6958 @opindex mlittle-endian
6959 Generate code for a processor running in little-endian mode. This is
6960 the default for all standard configurations.
6963 @opindex mbig-endian
6964 Generate code for a processor running in big-endian mode; the default is
6965 to compile code for a little-endian processor.
6967 @item -mwords-little-endian
6968 @opindex mwords-little-endian
6969 This option only applies when generating code for big-endian processors.
6970 Generate code for a little-endian word order but a big-endian byte
6971 order. That is, a byte order of the form @samp{32107654}. Note: this
6972 option should only be used if you require compatibility with code for
6973 big-endian ARM processors generated by versions of the compiler prior to
6976 @item -mcpu=@var{name}
6978 This specifies the name of the target ARM processor. GCC uses this name
6979 to determine what kind of instructions it can emit when generating
6980 assembly code. Permissible names are: @samp{arm2}, @samp{arm250},
6981 @samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
6982 @samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
6983 @samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
6984 @samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
6985 @samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},
6986 @samp{arm8}, @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
6987 @samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
6988 @samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},
6989 @samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},
6990 @samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},
6991 @samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
6992 @samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
6993 @samp{arm1176jz-s}, @samp{arm1176jzf-s}, @samp{xscale}, @samp{iwmmxt},
6996 @itemx -mtune=@var{name}
6998 This option is very similar to the @option{-mcpu=} option, except that
6999 instead of specifying the actual target processor type, and hence
7000 restricting which instructions can be used, it specifies that GCC should
7001 tune the performance of the code as if the target were of the type
7002 specified in this option, but still choosing the instructions that it
7003 will generate based on the cpu specified by a @option{-mcpu=} option.
7004 For some ARM implementations better performance can be obtained by using
7007 @item -march=@var{name}
7009 This specifies the name of the target ARM architecture. GCC uses this
7010 name to determine what kind of instructions it can emit when generating
7011 assembly code. This option can be used in conjunction with or instead
7012 of the @option{-mcpu=} option. Permissible names are: @samp{armv2},
7013 @samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
7014 @samp{armv5}, @samp{armv5t}, @samp{armv5te}, @samp{armv6}, @samp{armv6j},
7015 @samp{iwmmxt}, @samp{ep9312}.
7017 @item -mfpu=@var{name}
7018 @itemx -mfpe=@var{number}
7019 @itemx -mfp=@var{number}
7023 This specifies what floating point hardware (or hardware emulation) is
7024 available on the target. Permissible names are: @samp{fpa}, @samp{fpe2},
7025 @samp{fpe3}, @samp{maverick}, @samp{vfp}. @option{-mfp} and @option{-mfpe}
7026 are synonyms for @option{-mfpu}=@samp{fpe}@var{number}, for compatibility
7027 with older versions of GCC@.
7029 If @option{-msoft-float} is specified this specifies the format of
7030 floating point values.
7032 @item -mstructure-size-boundary=@var{n}
7033 @opindex mstructure-size-boundary
7034 The size of all structures and unions will be rounded up to a multiple
7035 of the number of bits set by this option. Permissible values are 8, 32
7036 and 64. The default value varies for different toolchains. For the COFF
7037 targeted toolchain the default value is 8. A value of 64 is only allowed
7038 if the underlying ABI supports it.
7040 Specifying the larger number can produce faster, more efficient code, but
7041 can also increase the size of the program. Different values are potentially
7042 incompatible. Code compiled with one value cannot necessarily expect to
7043 work with code or libraries compiled with another value, if they exchange
7044 information using structures or unions.
7046 @item -mabort-on-noreturn
7047 @opindex mabort-on-noreturn
7048 Generate a call to the function @code{abort} at the end of a
7049 @code{noreturn} function. It will be executed if the function tries to
7053 @itemx -mno-long-calls
7054 @opindex mlong-calls
7055 @opindex mno-long-calls
7056 Tells the compiler to perform function calls by first loading the
7057 address of the function into a register and then performing a subroutine
7058 call on this register. This switch is needed if the target function
7059 will lie outside of the 64 megabyte addressing range of the offset based
7060 version of subroutine call instruction.
7062 Even if this switch is enabled, not all function calls will be turned
7063 into long calls. The heuristic is that static functions, functions
7064 which have the @samp{short-call} attribute, functions that are inside
7065 the scope of a @samp{#pragma no_long_calls} directive and functions whose
7066 definitions have already been compiled within the current compilation
7067 unit, will not be turned into long calls. The exception to this rule is
7068 that weak function definitions, functions with the @samp{long-call}
7069 attribute or the @samp{section} attribute, and functions that are within
7070 the scope of a @samp{#pragma long_calls} directive, will always be
7071 turned into long calls.
7073 This feature is not enabled by default. Specifying
7074 @option{-mno-long-calls} will restore the default behavior, as will
7075 placing the function calls within the scope of a @samp{#pragma
7076 long_calls_off} directive. Note these switches have no effect on how
7077 the compiler generates code to handle function calls via function
7080 @item -mnop-fun-dllimport
7081 @opindex mnop-fun-dllimport
7082 Disable support for the @code{dllimport} attribute.
7084 @item -msingle-pic-base
7085 @opindex msingle-pic-base
7086 Treat the register used for PIC addressing as read-only, rather than
7087 loading it in the prologue for each function. The run-time system is
7088 responsible for initializing this register with an appropriate value
7089 before execution begins.
7091 @item -mpic-register=@var{reg}
7092 @opindex mpic-register
7093 Specify the register to be used for PIC addressing. The default is R10
7094 unless stack-checking is enabled, when R9 is used.
7096 @item -mcirrus-fix-invalid-insns
7097 @opindex mcirrus-fix-invalid-insns
7098 @opindex mno-cirrus-fix-invalid-insns
7099 Insert NOPs into the instruction stream to in order to work around
7100 problems with invalid Maverick instruction combinations. This option
7101 is only valid if the @option{-mcpu=ep9312} option has been used to
7102 enable generation of instructions for the Cirrus Maverick floating
7103 point co-processor. This option is not enabled by default, since the
7104 problem is only present in older Maverick implementations. The default
7105 can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns}
7108 @item -mpoke-function-name
7109 @opindex mpoke-function-name
7110 Write the name of each function into the text section, directly
7111 preceding the function prologue. The generated code is similar to this:
7115 .ascii "arm_poke_function_name", 0
7118 .word 0xff000000 + (t1 - t0)
7119 arm_poke_function_name
7121 stmfd sp!, @{fp, ip, lr, pc@}
7125 When performing a stack backtrace, code can inspect the value of
7126 @code{pc} stored at @code{fp + 0}. If the trace function then looks at
7127 location @code{pc - 12} and the top 8 bits are set, then we know that
7128 there is a function name embedded immediately preceding this location
7129 and has length @code{((pc[-3]) & 0xff000000)}.
7133 Generate code for the 16-bit Thumb instruction set. The default is to
7134 use the 32-bit ARM instruction set.
7137 @opindex mtpcs-frame
7138 Generate a stack frame that is compliant with the Thumb Procedure Call
7139 Standard for all non-leaf functions. (A leaf function is one that does
7140 not call any other functions.) The default is @option{-mno-tpcs-frame}.
7142 @item -mtpcs-leaf-frame
7143 @opindex mtpcs-leaf-frame
7144 Generate a stack frame that is compliant with the Thumb Procedure Call
7145 Standard for all leaf functions. (A leaf function is one that does
7146 not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
7148 @item -mcallee-super-interworking
7149 @opindex mcallee-super-interworking
7150 Gives all externally visible functions in the file being compiled an ARM
7151 instruction set header which switches to Thumb mode before executing the
7152 rest of the function. This allows these functions to be called from
7153 non-interworking code.
7155 @item -mcaller-super-interworking
7156 @opindex mcaller-super-interworking
7157 Allows calls via function pointers (including virtual functions) to
7158 execute correctly regardless of whether the target code has been
7159 compiled for interworking or not. There is a small overhead in the cost
7160 of executing a function pointer if this option is enabled.
7165 @subsection AVR Options
7168 These options are defined for AVR implementations:
7171 @item -mmcu=@var{mcu}
7173 Specify ATMEL AVR instruction set or MCU type.
7175 Instruction set avr1 is for the minimal AVR core, not supported by the C
7176 compiler, only for assembler programs (MCU types: at90s1200, attiny10,
7177 attiny11, attiny12, attiny15, attiny28).
7179 Instruction set avr2 (default) is for the classic AVR core with up to
7180 8K program memory space (MCU types: at90s2313, at90s2323, attiny22,
7181 at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
7182 at90c8534, at90s8535).
7184 Instruction set avr3 is for the classic AVR core with up to 128K program
7185 memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
7187 Instruction set avr4 is for the enhanced AVR core with up to 8K program
7188 memory space (MCU types: atmega8, atmega83, atmega85).
7190 Instruction set avr5 is for the enhanced AVR core with up to 128K program
7191 memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
7192 atmega64, atmega128, at43usb355, at94k).
7196 Output instruction sizes to the asm file.
7198 @item -minit-stack=@var{N}
7199 @opindex minit-stack
7200 Specify the initial stack address, which may be a symbol or numeric value,
7201 @samp{__stack} is the default.
7203 @item -mno-interrupts
7204 @opindex mno-interrupts
7205 Generated code is not compatible with hardware interrupts.
7206 Code size will be smaller.
7208 @item -mcall-prologues
7209 @opindex mcall-prologues
7210 Functions prologues/epilogues expanded as call to appropriate
7211 subroutines. Code size will be smaller.
7213 @item -mno-tablejump
7214 @opindex mno-tablejump
7215 Do not generate tablejump insns which sometimes increase code size.
7218 @opindex mtiny-stack
7219 Change only the low 8 bits of the stack pointer.
7223 Assume int to be 8 bit integer. This affects the sizes of all types: A
7224 char will be 1 byte, an int will be 1 byte, an long will be 2 bytes
7225 and long long will be 4 bytes. Please note that this option does not
7226 comply to the C standards, but it will provide you with smaller code
7230 @node Blackfin Options
7231 @subsection Blackfin Options
7232 @cindex Blackfin Options
7235 @item -momit-leaf-frame-pointer
7236 @opindex momit-leaf-frame-pointer
7237 Don't keep the frame pointer in a register for leaf functions. This
7238 avoids the instructions to save, set up and restore frame pointers and
7239 makes an extra register available in leaf functions. The option
7240 @option{-fomit-frame-pointer} removes the frame pointer for all functions
7241 which might make debugging harder.
7245 When enabled, the compiler will ensure that the generated code does not
7246 contain speculative loads after jump instructions. This option is enabled
7251 Don't generate extra code to prevent speculative loads from occurring.
7255 When enabled, the compiler is free to take advantage of the knowledge that
7256 the entire program fits into the low 64k of memory.
7259 @opindex mno-low-64k
7260 Assume that the program is arbitrarily large. This is the default.
7262 @item -mid-shared-library
7263 @opindex mid-shared-library
7264 Generate code that supports shared libraries via the library ID method.
7265 This allows for execute in place and shared libraries in an environment
7266 without virtual memory management. This option implies @option{-fPIC}.
7268 @item -mno-id-shared-library
7269 @opindex mno-id-shared-library
7270 Generate code that doesn't assume ID based shared libraries are being used.
7271 This is the default.
7273 @item -mshared-library-id=n
7274 @opindex mshared-library-id
7275 Specified the identification number of the ID based shared library being
7276 compiled. Specifying a value of 0 will generate more compact code, specifying
7277 other values will force the allocation of that number to the current
7278 library but is no more space or time efficient than omitting this option.
7282 @subsection CRIS Options
7283 @cindex CRIS Options
7285 These options are defined specifically for the CRIS ports.
7288 @item -march=@var{architecture-type}
7289 @itemx -mcpu=@var{architecture-type}
7292 Generate code for the specified architecture. The choices for
7293 @var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
7294 respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
7295 Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
7298 @item -mtune=@var{architecture-type}
7300 Tune to @var{architecture-type} everything applicable about the generated
7301 code, except for the ABI and the set of available instructions. The
7302 choices for @var{architecture-type} are the same as for
7303 @option{-march=@var{architecture-type}}.
7305 @item -mmax-stack-frame=@var{n}
7306 @opindex mmax-stack-frame
7307 Warn when the stack frame of a function exceeds @var{n} bytes.
7309 @item -melinux-stacksize=@var{n}
7310 @opindex melinux-stacksize
7311 Only available with the @samp{cris-axis-aout} target. Arranges for
7312 indications in the program to the kernel loader that the stack of the
7313 program should be set to @var{n} bytes.
7319 The options @option{-metrax4} and @option{-metrax100} are synonyms for
7320 @option{-march=v3} and @option{-march=v8} respectively.
7322 @item -mmul-bug-workaround
7323 @itemx -mno-mul-bug-workaround
7324 @opindex mmul-bug-workaround
7325 @opindex mno-mul-bug-workaround
7326 Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
7327 models where it applies. This option is active by default.
7331 Enable CRIS-specific verbose debug-related information in the assembly
7332 code. This option also has the effect to turn off the @samp{#NO_APP}
7333 formatted-code indicator to the assembler at the beginning of the
7338 Do not use condition-code results from previous instruction; always emit
7339 compare and test instructions before use of condition codes.
7341 @item -mno-side-effects
7342 @opindex mno-side-effects
7343 Do not emit instructions with side-effects in addressing modes other than
7347 @itemx -mno-stack-align
7349 @itemx -mno-data-align
7350 @itemx -mconst-align
7351 @itemx -mno-const-align
7352 @opindex mstack-align
7353 @opindex mno-stack-align
7354 @opindex mdata-align
7355 @opindex mno-data-align
7356 @opindex mconst-align
7357 @opindex mno-const-align
7358 These options (no-options) arranges (eliminate arrangements) for the
7359 stack-frame, individual data and constants to be aligned for the maximum
7360 single data access size for the chosen CPU model. The default is to
7361 arrange for 32-bit alignment. ABI details such as structure layout are
7362 not affected by these options.
7370 Similar to the stack- data- and const-align options above, these options
7371 arrange for stack-frame, writable data and constants to all be 32-bit,
7372 16-bit or 8-bit aligned. The default is 32-bit alignment.
7374 @item -mno-prologue-epilogue
7375 @itemx -mprologue-epilogue
7376 @opindex mno-prologue-epilogue
7377 @opindex mprologue-epilogue
7378 With @option{-mno-prologue-epilogue}, the normal function prologue and
7379 epilogue that sets up the stack-frame are omitted and no return
7380 instructions or return sequences are generated in the code. Use this
7381 option only together with visual inspection of the compiled code: no
7382 warnings or errors are generated when call-saved registers must be saved,
7383 or storage for local variable needs to be allocated.
7389 With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
7390 instruction sequences that load addresses for functions from the PLT part
7391 of the GOT rather than (traditional on other architectures) calls to the
7392 PLT@. The default is @option{-mgotplt}.
7396 Legacy no-op option only recognized with the cris-axis-aout target.
7400 Legacy no-op option only recognized with the cris-axis-elf and
7401 cris-axis-linux-gnu targets.
7405 Only recognized with the cris-axis-aout target, where it selects a
7406 GNU/linux-like multilib, include files and instruction set for
7411 Legacy no-op option only recognized with the cris-axis-linux-gnu target.
7415 This option, recognized for the cris-axis-aout and cris-axis-elf arranges
7416 to link with input-output functions from a simulator library. Code,
7417 initialized data and zero-initialized data are allocated consecutively.
7421 Like @option{-sim}, but pass linker options to locate initialized data at
7422 0x40000000 and zero-initialized data at 0x80000000.
7425 @node Darwin Options
7426 @subsection Darwin Options
7427 @cindex Darwin options
7429 These options are defined for all architectures running the Darwin operating
7432 FSF GCC on Darwin does not create ``fat'' object files; it will create
7433 an object file for the single architecture that it was built to
7434 target. Apple's GCC on Darwin does create ``fat'' files if multiple
7435 @option{-arch} options are used; it does so by running the compiler or
7436 linker multiple times and joining the results together with
7439 The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
7440 @samp{i686}) is determined by the flags that specify the ISA
7441 that GCC is targetting, like @option{-mcpu} or @option{-march}. The
7442 @option{-force_cpusubtype_ALL} option can be used to override this.
7444 The Darwin tools vary in their behavior when presented with an ISA
7445 mismatch. The assembler, @file{as}, will only permit instructions to
7446 be used that are valid for the subtype of the file it is generating,
7447 so you cannot put 64-bit instructions in an @samp{ppc750} object file.
7448 The linker for shared libraries, @file{/usr/bin/libtool}, will fail
7449 and print an error if asked to create a shared library with a less
7450 restrictive subtype than its input files (for instance, trying to put
7451 a @samp{ppc970} object file in a @samp{ppc7400} library). The linker
7452 for executables, @file{ld}, will quietly give the executable the most
7453 restrictive subtype of any of its input files.
7458 Add the framework directory @var{dir} to the head of the list of
7459 directories to be searched for header files. These directories are
7460 interleaved with those specified by @option{-I} options and are
7461 scanned in a left-to-right order.
7463 A framework directory is a directory with frameworks in it. A
7464 framework is a directory with a @samp{"Headers"} and/or
7465 @samp{"PrivateHeaders"} directory contained directly in it that ends
7466 in @samp{".framework"}. The name of a framework is the name of this
7467 directory excluding the @samp{".framework"}. Headers associated with
7468 the framework are found in one of those two directories, with
7469 @samp{"Headers"} being searched first. A subframework is a framework
7470 directory that is in a framework's @samp{"Frameworks"} directory.
7471 Includes of subframework headers can only appear in a header of a
7472 framework that contains the subframework, or in a sibling subframework
7473 header. Two subframeworks are siblings if they occur in the same
7474 framework. A subframework should not have the same name as a
7475 framework, a warning will be issued if this is violated. Currently a
7476 subframework cannot have subframeworks, in the future, the mechanism
7477 may be extended to support this. The standard frameworks can be found
7478 in @samp{"/System/Library/Frameworks"} and
7479 @samp{"/Library/Frameworks"}. An example include looks like
7480 @code{#include <Framework/header.h>}, where @samp{Framework} denotes
7481 the name of the framework and header.h is found in the
7482 @samp{"PrivateHeaders"} or @samp{"Headers"} directory.
7486 Emit debugging information for symbols that are used. For STABS
7487 debugging format, this enables @option{-feliminate-unused-debug-symbols}.
7488 This is by default ON@.
7492 Emit debugging information for all symbols and types.
7494 @item -mone-byte-bool
7495 @opindex -mone-byte-bool
7496 Override the defaults for @samp{bool} so that @samp{sizeof(bool)==1}.
7497 By default @samp{sizeof(bool)} is @samp{4} when compiling for
7498 Darwin/PowerPC and @samp{1} when compiling for Darwin/x86, so this
7499 option has no effect on x86.
7501 @strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
7502 to generate code that is not binary compatible with code generated
7503 without that switch. Using this switch may require recompiling all
7504 other modules in a program, including system libraries. Use this
7505 switch to conform to a non-default data model.
7507 @item -mfix-and-continue
7508 @itemx -ffix-and-continue
7509 @itemx -findirect-data
7510 @opindex mfix-and-continue
7511 @opindex ffix-and-continue
7512 @opindex findirect-data
7513 Generate code suitable for fast turn around development. Needed to
7514 enable gdb to dynamically load @code{.o} files into already running
7515 programs. @option{-findirect-data} and @option{-ffix-and-continue}
7516 are provided for backwards compatibility.
7520 Loads all members of static archive libraries.
7521 See man ld(1) for more information.
7523 @item -arch_errors_fatal
7524 @opindex arch_errors_fatal
7525 Cause the errors having to do with files that have the wrong architecture
7529 @opindex bind_at_load
7530 Causes the output file to be marked such that the dynamic linker will
7531 bind all undefined references when the file is loaded or launched.
7535 Produce a Mach-o bundle format file.
7536 See man ld(1) for more information.
7538 @item -bundle_loader @var{executable}
7539 @opindex bundle_loader
7540 This option specifies the @var{executable} that will be loading the build
7541 output file being linked. See man ld(1) for more information.
7544 @opindex -dynamiclib
7545 When passed this option, GCC will produce a dynamic library instead of
7546 an executable when linking, using the Darwin @file{libtool} command.
7548 @item -force_cpusubtype_ALL
7549 @opindex -force_cpusubtype_ALL
7550 This causes GCC's output file to have the @var{ALL} subtype, instead of
7551 one controlled by the @option{-mcpu} or @option{-march} option.
7553 @item -allowable_client @var{client_name}
7555 @itemx -compatibility_version
7556 @itemx -current_version
7558 @itemx -dependency-file
7560 @itemx -dylinker_install_name
7562 @itemx -exported_symbols_list
7564 @itemx -flat_namespace
7565 @itemx -force_flat_namespace
7566 @itemx -headerpad_max_install_names
7569 @itemx -install_name
7570 @itemx -keep_private_externs
7571 @itemx -multi_module
7572 @itemx -multiply_defined
7573 @itemx -multiply_defined_unused
7575 @itemx -no_dead_strip_inits_and_terms
7576 @itemx -nofixprebinding
7579 @itemx -noseglinkedit
7580 @itemx -pagezero_size
7582 @itemx -prebind_all_twolevel_modules
7583 @itemx -private_bundle
7584 @itemx -read_only_relocs
7586 @itemx -sectobjectsymbols
7590 @itemx -sectobjectsymbols
7593 @itemx -segs_read_only_addr
7594 @itemx -segs_read_write_addr
7595 @itemx -seg_addr_table
7596 @itemx -seg_addr_table_filename
7599 @itemx -segs_read_only_addr
7600 @itemx -segs_read_write_addr
7601 @itemx -single_module
7604 @itemx -sub_umbrella
7605 @itemx -twolevel_namespace
7608 @itemx -unexported_symbols_list
7609 @itemx -weak_reference_mismatches
7612 @opindex allowable_client
7613 @opindex client_name
7614 @opindex compatibility_version
7615 @opindex current_version
7617 @opindex dependency-file
7619 @opindex dylinker_install_name
7621 @opindex exported_symbols_list
7623 @opindex flat_namespace
7624 @opindex force_flat_namespace
7625 @opindex headerpad_max_install_names
7628 @opindex install_name
7629 @opindex keep_private_externs
7630 @opindex multi_module
7631 @opindex multiply_defined
7632 @opindex multiply_defined_unused
7634 @opindex no_dead_strip_inits_and_terms
7635 @opindex nofixprebinding
7636 @opindex nomultidefs
7638 @opindex noseglinkedit
7639 @opindex pagezero_size
7641 @opindex prebind_all_twolevel_modules
7642 @opindex private_bundle
7643 @opindex read_only_relocs
7645 @opindex sectobjectsymbols
7649 @opindex sectobjectsymbols
7652 @opindex segs_read_only_addr
7653 @opindex segs_read_write_addr
7654 @opindex seg_addr_table
7655 @opindex seg_addr_table_filename
7656 @opindex seglinkedit
7658 @opindex segs_read_only_addr
7659 @opindex segs_read_write_addr
7660 @opindex single_module
7662 @opindex sub_library
7663 @opindex sub_umbrella
7664 @opindex twolevel_namespace
7667 @opindex unexported_symbols_list
7668 @opindex weak_reference_mismatches
7669 @opindex whatsloaded
7671 These options are passed to the Darwin linker. The Darwin linker man page
7672 describes them in detail.
7675 @node DEC Alpha Options
7676 @subsection DEC Alpha Options
7678 These @samp{-m} options are defined for the DEC Alpha implementations:
7681 @item -mno-soft-float
7683 @opindex mno-soft-float
7684 @opindex msoft-float
7685 Use (do not use) the hardware floating-point instructions for
7686 floating-point operations. When @option{-msoft-float} is specified,
7687 functions in @file{libgcc.a} will be used to perform floating-point
7688 operations. Unless they are replaced by routines that emulate the
7689 floating-point operations, or compiled in such a way as to call such
7690 emulations routines, these routines will issue floating-point
7691 operations. If you are compiling for an Alpha without floating-point
7692 operations, you must ensure that the library is built so as not to call
7695 Note that Alpha implementations without floating-point operations are
7696 required to have floating-point registers.
7701 @opindex mno-fp-regs
7702 Generate code that uses (does not use) the floating-point register set.
7703 @option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
7704 register set is not used, floating point operands are passed in integer
7705 registers as if they were integers and floating-point results are passed
7706 in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
7707 so any function with a floating-point argument or return value called by code
7708 compiled with @option{-mno-fp-regs} must also be compiled with that
7711 A typical use of this option is building a kernel that does not use,
7712 and hence need not save and restore, any floating-point registers.
7716 The Alpha architecture implements floating-point hardware optimized for
7717 maximum performance. It is mostly compliant with the IEEE floating
7718 point standard. However, for full compliance, software assistance is
7719 required. This option generates code fully IEEE compliant code
7720 @emph{except} that the @var{inexact-flag} is not maintained (see below).
7721 If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
7722 defined during compilation. The resulting code is less efficient but is
7723 able to correctly support denormalized numbers and exceptional IEEE
7724 values such as not-a-number and plus/minus infinity. Other Alpha
7725 compilers call this option @option{-ieee_with_no_inexact}.
7727 @item -mieee-with-inexact
7728 @opindex mieee-with-inexact
7729 This is like @option{-mieee} except the generated code also maintains
7730 the IEEE @var{inexact-flag}. Turning on this option causes the
7731 generated code to implement fully-compliant IEEE math. In addition to
7732 @code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
7733 macro. On some Alpha implementations the resulting code may execute
7734 significantly slower than the code generated by default. Since there is
7735 very little code that depends on the @var{inexact-flag}, you should
7736 normally not specify this option. Other Alpha compilers call this
7737 option @option{-ieee_with_inexact}.
7739 @item -mfp-trap-mode=@var{trap-mode}
7740 @opindex mfp-trap-mode
7741 This option controls what floating-point related traps are enabled.
7742 Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
7743 The trap mode can be set to one of four values:
7747 This is the default (normal) setting. The only traps that are enabled
7748 are the ones that cannot be disabled in software (e.g., division by zero
7752 In addition to the traps enabled by @samp{n}, underflow traps are enabled
7756 Like @samp{su}, but the instructions are marked to be safe for software
7757 completion (see Alpha architecture manual for details).
7760 Like @samp{su}, but inexact traps are enabled as well.
7763 @item -mfp-rounding-mode=@var{rounding-mode}
7764 @opindex mfp-rounding-mode
7765 Selects the IEEE rounding mode. Other Alpha compilers call this option
7766 @option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
7771 Normal IEEE rounding mode. Floating point numbers are rounded towards
7772 the nearest machine number or towards the even machine number in case
7776 Round towards minus infinity.
7779 Chopped rounding mode. Floating point numbers are rounded towards zero.
7782 Dynamic rounding mode. A field in the floating point control register
7783 (@var{fpcr}, see Alpha architecture reference manual) controls the
7784 rounding mode in effect. The C library initializes this register for
7785 rounding towards plus infinity. Thus, unless your program modifies the
7786 @var{fpcr}, @samp{d} corresponds to round towards plus infinity.
7789 @item -mtrap-precision=@var{trap-precision}
7790 @opindex mtrap-precision
7791 In the Alpha architecture, floating point traps are imprecise. This
7792 means without software assistance it is impossible to recover from a
7793 floating trap and program execution normally needs to be terminated.
7794 GCC can generate code that can assist operating system trap handlers
7795 in determining the exact location that caused a floating point trap.
7796 Depending on the requirements of an application, different levels of
7797 precisions can be selected:
7801 Program precision. This option is the default and means a trap handler
7802 can only identify which program caused a floating point exception.
7805 Function precision. The trap handler can determine the function that
7806 caused a floating point exception.
7809 Instruction precision. The trap handler can determine the exact
7810 instruction that caused a floating point exception.
7813 Other Alpha compilers provide the equivalent options called
7814 @option{-scope_safe} and @option{-resumption_safe}.
7816 @item -mieee-conformant
7817 @opindex mieee-conformant
7818 This option marks the generated code as IEEE conformant. You must not
7819 use this option unless you also specify @option{-mtrap-precision=i} and either
7820 @option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
7821 is to emit the line @samp{.eflag 48} in the function prologue of the
7822 generated assembly file. Under DEC Unix, this has the effect that
7823 IEEE-conformant math library routines will be linked in.
7825 @item -mbuild-constants
7826 @opindex mbuild-constants
7827 Normally GCC examines a 32- or 64-bit integer constant to
7828 see if it can construct it from smaller constants in two or three
7829 instructions. If it cannot, it will output the constant as a literal and
7830 generate code to load it from the data segment at runtime.
7832 Use this option to require GCC to construct @emph{all} integer constants
7833 using code, even if it takes more instructions (the maximum is six).
7835 You would typically use this option to build a shared library dynamic
7836 loader. Itself a shared library, it must relocate itself in memory
7837 before it can find the variables and constants in its own data segment.
7843 Select whether to generate code to be assembled by the vendor-supplied
7844 assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
7862 Indicate whether GCC should generate code to use the optional BWX,
7863 CIX, FIX and MAX instruction sets. The default is to use the instruction
7864 sets supported by the CPU type specified via @option{-mcpu=} option or that
7865 of the CPU on which GCC was built if none was specified.
7870 @opindex mfloat-ieee
7871 Generate code that uses (does not use) VAX F and G floating point
7872 arithmetic instead of IEEE single and double precision.
7874 @item -mexplicit-relocs
7875 @itemx -mno-explicit-relocs
7876 @opindex mexplicit-relocs
7877 @opindex mno-explicit-relocs
7878 Older Alpha assemblers provided no way to generate symbol relocations
7879 except via assembler macros. Use of these macros does not allow
7880 optimal instruction scheduling. GNU binutils as of version 2.12
7881 supports a new syntax that allows the compiler to explicitly mark
7882 which relocations should apply to which instructions. This option
7883 is mostly useful for debugging, as GCC detects the capabilities of
7884 the assembler when it is built and sets the default accordingly.
7888 @opindex msmall-data
7889 @opindex mlarge-data
7890 When @option{-mexplicit-relocs} is in effect, static data is
7891 accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
7892 is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
7893 (the @code{.sdata} and @code{.sbss} sections) and are accessed via
7894 16-bit relocations off of the @code{$gp} register. This limits the
7895 size of the small data area to 64KB, but allows the variables to be
7896 directly accessed via a single instruction.
7898 The default is @option{-mlarge-data}. With this option the data area
7899 is limited to just below 2GB@. Programs that require more than 2GB of
7900 data must use @code{malloc} or @code{mmap} to allocate the data in the
7901 heap instead of in the program's data segment.
7903 When generating code for shared libraries, @option{-fpic} implies
7904 @option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
7908 @opindex msmall-text
7909 @opindex mlarge-text
7910 When @option{-msmall-text} is used, the compiler assumes that the
7911 code of the entire program (or shared library) fits in 4MB, and is
7912 thus reachable with a branch instruction. When @option{-msmall-data}
7913 is used, the compiler can assume that all local symbols share the
7914 same @code{$gp} value, and thus reduce the number of instructions
7915 required for a function call from 4 to 1.
7917 The default is @option{-mlarge-text}.
7919 @item -mcpu=@var{cpu_type}
7921 Set the instruction set and instruction scheduling parameters for
7922 machine type @var{cpu_type}. You can specify either the @samp{EV}
7923 style name or the corresponding chip number. GCC supports scheduling
7924 parameters for the EV4, EV5 and EV6 family of processors and will
7925 choose the default values for the instruction set from the processor
7926 you specify. If you do not specify a processor type, GCC will default
7927 to the processor on which the compiler was built.
7929 Supported values for @var{cpu_type} are
7935 Schedules as an EV4 and has no instruction set extensions.
7939 Schedules as an EV5 and has no instruction set extensions.
7943 Schedules as an EV5 and supports the BWX extension.
7948 Schedules as an EV5 and supports the BWX and MAX extensions.
7952 Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
7956 Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
7959 @item -mtune=@var{cpu_type}
7961 Set only the instruction scheduling parameters for machine type
7962 @var{cpu_type}. The instruction set is not changed.
7964 @item -mmemory-latency=@var{time}
7965 @opindex mmemory-latency
7966 Sets the latency the scheduler should assume for typical memory
7967 references as seen by the application. This number is highly
7968 dependent on the memory access patterns used by the application
7969 and the size of the external cache on the machine.
7971 Valid options for @var{time} are
7975 A decimal number representing clock cycles.
7981 The compiler contains estimates of the number of clock cycles for
7982 ``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
7983 (also called Dcache, Scache, and Bcache), as well as to main memory.
7984 Note that L3 is only valid for EV5.
7989 @node DEC Alpha/VMS Options
7990 @subsection DEC Alpha/VMS Options
7992 These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
7995 @item -mvms-return-codes
7996 @opindex mvms-return-codes
7997 Return VMS condition codes from main. The default is to return POSIX
7998 style condition (e.g.@ error) codes.
8002 @subsection FRV Options
8009 Only use the first 32 general purpose registers.
8014 Use all 64 general purpose registers.
8019 Use only the first 32 floating point registers.
8024 Use all 64 floating point registers
8027 @opindex mhard-float
8029 Use hardware instructions for floating point operations.
8032 @opindex msoft-float
8034 Use library routines for floating point operations.
8039 Dynamically allocate condition code registers.
8044 Do not try to dynamically allocate condition code registers, only
8045 use @code{icc0} and @code{fcc0}.
8050 Change ABI to use double word insns.
8055 Do not use double word instructions.
8060 Use floating point double instructions.
8065 Do not use floating point double instructions.
8070 Use media instructions.
8075 Do not use media instructions.
8080 Use multiply and add/subtract instructions.
8085 Do not use multiply and add/subtract instructions.
8090 Select the FDPIC ABI, that uses function descriptors to represent
8091 pointers to functions. Without any PIC/PIE-related options, it
8092 implies @option{-fPIE}. With @option{-fpic} or @option{-fpie}, it
8093 assumes GOT entries and small data are within a 12-bit range from the
8094 GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
8095 are computed with 32 bits.
8098 @opindex minline-plt
8100 Enable inlining of PLT entries in function calls to functions that are
8101 not known to bind locally. It has no effect without @option{-mfdpic}.
8102 It's enabled by default if optimizing for speed and compiling for
8103 shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
8104 optimization option such as @option{-O3} or above is present in the
8110 Assume a large TLS segment when generating thread-local code.
8115 Do not assume a large TLS segment when generating thread-local code.
8120 Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
8121 that is known to be in read-only sections. It's enabled by default,
8122 except for @option{-fpic} or @option{-fpie}: even though it may help
8123 make the global offset table smaller, it trades 1 instruction for 4.
8124 With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
8125 one of which may be shared by multiple symbols, and it avoids the need
8126 for a GOT entry for the referenced symbol, so it's more likely to be a
8127 win. If it is not, @option{-mno-gprel-ro} can be used to disable it.
8129 @item -multilib-library-pic
8130 @opindex multilib-library-pic
8132 Link with the (library, not FD) pic libraries. It's implied by
8133 @option{-mlibrary-pic}, as well as by @option{-fPIC} and
8134 @option{-fpic} without @option{-mfdpic}. You should never have to use
8140 Follow the EABI requirement of always creating a frame pointer whenever
8141 a stack frame is allocated. This option is enabled by default and can
8142 be disabled with @option{-mno-linked-fp}.
8145 @opindex mlong-calls
8147 Use indirect addressing to call functions outside the current
8148 compilation unit. This allows the functions to be placed anywhere
8149 within the 32-bit address space.
8151 @item -malign-labels
8152 @opindex malign-labels
8154 Try to align labels to an 8-byte boundary by inserting nops into the
8155 previous packet. This option only has an effect when VLIW packing
8156 is enabled. It doesn't create new packets; it merely adds nops to
8160 @opindex mlibrary-pic
8162 Generate position-independent EABI code.
8167 Use only the first four media accumulator registers.
8172 Use all eight media accumulator registers.
8177 Pack VLIW instructions.
8182 Do not pack VLIW instructions.
8187 Do not mark ABI switches in e_flags.
8192 Enable the use of conditional-move instructions (default).
8194 This switch is mainly for debugging the compiler and will likely be removed
8195 in a future version.
8197 @item -mno-cond-move
8198 @opindex mno-cond-move
8200 Disable the use of conditional-move instructions.
8202 This switch is mainly for debugging the compiler and will likely be removed
8203 in a future version.
8208 Enable the use of conditional set instructions (default).
8210 This switch is mainly for debugging the compiler and will likely be removed
8211 in a future version.
8216 Disable the use of conditional set instructions.
8218 This switch is mainly for debugging the compiler and will likely be removed
8219 in a future version.
8224 Enable the use of conditional execution (default).
8226 This switch is mainly for debugging the compiler and will likely be removed
8227 in a future version.
8229 @item -mno-cond-exec
8230 @opindex mno-cond-exec
8232 Disable the use of conditional execution.
8234 This switch is mainly for debugging the compiler and will likely be removed
8235 in a future version.
8238 @opindex mvliw-branch
8240 Run a pass to pack branches into VLIW instructions (default).
8242 This switch is mainly for debugging the compiler and will likely be removed
8243 in a future version.
8245 @item -mno-vliw-branch
8246 @opindex mno-vliw-branch
8248 Do not run a pass to pack branches into VLIW instructions.
8250 This switch is mainly for debugging the compiler and will likely be removed
8251 in a future version.
8253 @item -mmulti-cond-exec
8254 @opindex mmulti-cond-exec
8256 Enable optimization of @code{&&} and @code{||} in conditional execution
8259 This switch is mainly for debugging the compiler and will likely be removed
8260 in a future version.
8262 @item -mno-multi-cond-exec
8263 @opindex mno-multi-cond-exec
8265 Disable optimization of @code{&&} and @code{||} in conditional execution.
8267 This switch is mainly for debugging the compiler and will likely be removed
8268 in a future version.
8270 @item -mnested-cond-exec
8271 @opindex mnested-cond-exec
8273 Enable nested conditional execution optimizations (default).
8275 This switch is mainly for debugging the compiler and will likely be removed
8276 in a future version.
8278 @item -mno-nested-cond-exec
8279 @opindex mno-nested-cond-exec
8281 Disable nested conditional execution optimizations.
8283 This switch is mainly for debugging the compiler and will likely be removed
8284 in a future version.
8286 @item -mtomcat-stats
8287 @opindex mtomcat-stats
8289 Cause gas to print out tomcat statistics.
8291 @item -mcpu=@var{cpu}
8294 Select the processor type for which to generate code. Possible values are
8295 @samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
8296 @samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
8300 @node H8/300 Options
8301 @subsection H8/300 Options
8303 These @samp{-m} options are defined for the H8/300 implementations:
8308 Shorten some address references at link time, when possible; uses the
8309 linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
8310 ld, Using ld}, for a fuller description.
8314 Generate code for the H8/300H@.
8318 Generate code for the H8S@.
8322 Generate code for the H8S and H8/300H in the normal mode. This switch
8323 must be used either with @option{-mh} or @option{-ms}.
8327 Generate code for the H8S/2600. This switch must be used with @option{-ms}.
8331 Make @code{int} data 32 bits by default.
8335 On the H8/300H and H8S, use the same alignment rules as for the H8/300.
8336 The default for the H8/300H and H8S is to align longs and floats on 4
8338 @option{-malign-300} causes them to be aligned on 2 byte boundaries.
8339 This option has no effect on the H8/300.
8343 @subsection HPPA Options
8344 @cindex HPPA Options
8346 These @samp{-m} options are defined for the HPPA family of computers:
8349 @item -march=@var{architecture-type}
8351 Generate code for the specified architecture. The choices for
8352 @var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
8353 1.1, and @samp{2.0} for PA 2.0 processors. Refer to
8354 @file{/usr/lib/sched.models} on an HP-UX system to determine the proper
8355 architecture option for your machine. Code compiled for lower numbered
8356 architectures will run on higher numbered architectures, but not the
8360 @itemx -mpa-risc-1-1
8361 @itemx -mpa-risc-2-0
8362 @opindex mpa-risc-1-0
8363 @opindex mpa-risc-1-1
8364 @opindex mpa-risc-2-0
8365 Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
8368 @opindex mbig-switch
8369 Generate code suitable for big switch tables. Use this option only if
8370 the assembler/linker complain about out of range branches within a switch
8373 @item -mjump-in-delay
8374 @opindex mjump-in-delay
8375 Fill delay slots of function calls with unconditional jump instructions
8376 by modifying the return pointer for the function call to be the target
8377 of the conditional jump.
8379 @item -mdisable-fpregs
8380 @opindex mdisable-fpregs
8381 Prevent floating point registers from being used in any manner. This is
8382 necessary for compiling kernels which perform lazy context switching of
8383 floating point registers. If you use this option and attempt to perform
8384 floating point operations, the compiler will abort.
8386 @item -mdisable-indexing
8387 @opindex mdisable-indexing
8388 Prevent the compiler from using indexing address modes. This avoids some
8389 rather obscure problems when compiling MIG generated code under MACH@.
8391 @item -mno-space-regs
8392 @opindex mno-space-regs
8393 Generate code that assumes the target has no space registers. This allows
8394 GCC to generate faster indirect calls and use unscaled index address modes.
8396 Such code is suitable for level 0 PA systems and kernels.
8398 @item -mfast-indirect-calls
8399 @opindex mfast-indirect-calls
8400 Generate code that assumes calls never cross space boundaries. This
8401 allows GCC to emit code which performs faster indirect calls.
8403 This option will not work in the presence of shared libraries or nested
8406 @item -mfixed-range=@var{register-range}
8407 @opindex mfixed-range
8408 Generate code treating the given register range as fixed registers.
8409 A fixed register is one that the register allocator can not use. This is
8410 useful when compiling kernel code. A register range is specified as
8411 two registers separated by a dash. Multiple register ranges can be
8412 specified separated by a comma.
8414 @item -mlong-load-store
8415 @opindex mlong-load-store
8416 Generate 3-instruction load and store sequences as sometimes required by
8417 the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
8420 @item -mportable-runtime
8421 @opindex mportable-runtime
8422 Use the portable calling conventions proposed by HP for ELF systems.
8426 Enable the use of assembler directives only GAS understands.
8428 @item -mschedule=@var{cpu-type}
8430 Schedule code according to the constraints for the machine type
8431 @var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
8432 @samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer
8433 to @file{/usr/lib/sched.models} on an HP-UX system to determine the
8434 proper scheduling option for your machine. The default scheduling is
8438 @opindex mlinker-opt
8439 Enable the optimization pass in the HP-UX linker. Note this makes symbolic
8440 debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9
8441 linkers in which they give bogus error messages when linking some programs.
8444 @opindex msoft-float
8445 Generate output containing library calls for floating point.
8446 @strong{Warning:} the requisite libraries are not available for all HPPA
8447 targets. Normally the facilities of the machine's usual C compiler are
8448 used, but this cannot be done directly in cross-compilation. You must make
8449 your own arrangements to provide suitable library functions for
8450 cross-compilation. The embedded target @samp{hppa1.1-*-pro}
8451 does provide software floating point support.
8453 @option{-msoft-float} changes the calling convention in the output file;
8454 therefore, it is only useful if you compile @emph{all} of a program with
8455 this option. In particular, you need to compile @file{libgcc.a}, the
8456 library that comes with GCC, with @option{-msoft-float} in order for
8461 Generate the predefine, @code{_SIO}, for server IO@. The default is
8462 @option{-mwsio}. This generates the predefines, @code{__hp9000s700},
8463 @code{__hp9000s700__} and @code{_WSIO}, for workstation IO@. These
8464 options are available under HP-UX and HI-UX@.
8468 Use GNU ld specific options. This passes @option{-shared} to ld when
8469 building a shared library. It is the default when GCC is configured,
8470 explicitly or implicitly, with the GNU linker. This option does not
8471 have any affect on which ld is called, it only changes what parameters
8472 are passed to that ld. The ld that is called is determined by the
8473 @option{--with-ld} configure option, GCC's program search path, and
8474 finally by the user's @env{PATH}. The linker used by GCC can be printed
8475 using @samp{which `gcc -print-prog-name=ld`}.
8479 Use HP ld specific options. This passes @option{-b} to ld when building
8480 a shared library and passes @option{+Accept TypeMismatch} to ld on all
8481 links. It is the default when GCC is configured, explicitly or
8482 implicitly, with the HP linker. This option does not have any affect on
8483 which ld is called, it only changes what parameters are passed to that
8484 ld. The ld that is called is determined by the @option{--with-ld}
8485 configure option, GCC's program search path, and finally by the user's
8486 @env{PATH}. The linker used by GCC can be printed using @samp{which
8487 `gcc -print-prog-name=ld`}.
8490 @opindex mno-long-calls
8491 Generate code that uses long call sequences. This ensures that a call
8492 is always able to reach linker generated stubs. The default is to generate
8493 long calls only when the distance from the call site to the beginning
8494 of the function or translation unit, as the case may be, exceeds a
8495 predefined limit set by the branch type being used. The limits for
8496 normal calls are 7,600,000 and 240,000 bytes, respectively for the
8497 PA 2.0 and PA 1.X architectures. Sibcalls are always limited at
8500 Distances are measured from the beginning of functions when using the
8501 @option{-ffunction-sections} option, or when using the @option{-mgas}
8502 and @option{-mno-portable-runtime} options together under HP-UX with
8505 It is normally not desirable to use this option as it will degrade
8506 performance. However, it may be useful in large applications,
8507 particularly when partial linking is used to build the application.
8509 The types of long calls used depends on the capabilities of the
8510 assembler and linker, and the type of code being generated. The
8511 impact on systems that support long absolute calls, and long pic
8512 symbol-difference or pc-relative calls should be relatively small.
8513 However, an indirect call is used on 32-bit ELF systems in pic code
8514 and it is quite long.
8516 @item -munix=@var{unix-std}
8518 Generate compiler predefines and select a startfile for the specified
8519 UNIX standard. The choices for @var{unix-std} are @samp{93}, @samp{95}
8520 and @samp{98}. @samp{93} is supported on all HP-UX versions. @samp{95}
8521 is available on HP-UX 10.10 and later. @samp{98} is available on HP-UX
8522 11.11 and later. The default values are @samp{93} for HP-UX 10.00,
8523 @samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
8526 @option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
8527 @option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
8528 and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
8529 @option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
8530 @code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
8531 @code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
8533 It is @emph{important} to note that this option changes the interfaces
8534 for various library routines. It also affects the operational behavior
8535 of the C library. Thus, @emph{extreme} care is needed in using this
8538 Library code that is intended to operate with more than one UNIX
8539 standard must test, set and restore the variable @var{__xpg4_extended_mask}
8540 as appropriate. Most GNU software doesn't provide this capability.
8544 Suppress the generation of link options to search libdld.sl when the
8545 @option{-static} option is specified on HP-UX 10 and later.
8549 The HP-UX implementation of setlocale in libc has a dependency on
8550 libdld.sl. There isn't an archive version of libdld.sl. Thus,
8551 when the @option{-static} option is specified, special link options
8552 are needed to resolve this dependency.
8554 On HP-UX 10 and later, the GCC driver adds the necessary options to
8555 link with libdld.sl when the @option{-static} option is specified.
8556 This causes the resulting binary to be dynamic. On the 64-bit port,
8557 the linkers generate dynamic binaries by default in any case. The
8558 @option{-nolibdld} option can be used to prevent the GCC driver from
8559 adding these link options.
8563 Add support for multithreading with the @dfn{dce thread} library
8564 under HP-UX@. This option sets flags for both the preprocessor and
8568 @node i386 and x86-64 Options
8569 @subsection Intel 386 and AMD x86-64 Options
8570 @cindex i386 Options
8571 @cindex x86-64 Options
8572 @cindex Intel 386 Options
8573 @cindex AMD x86-64 Options
8575 These @samp{-m} options are defined for the i386 and x86-64 family of
8579 @item -mtune=@var{cpu-type}
8581 Tune to @var{cpu-type} everything applicable about the generated code, except
8582 for the ABI and the set of available instructions. The choices for
8586 Original Intel's i386 CPU@.
8588 Intel's i486 CPU@. (No scheduling is implemented for this chip.)
8590 Intel Pentium CPU with no MMX support.
8592 Intel PentiumMMX CPU based on Pentium core with MMX instruction set support.
8593 @item i686, pentiumpro
8594 Intel PentiumPro CPU@.
8596 Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support.
8597 @item pentium3, pentium3m
8598 Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set
8601 Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set
8602 support. Used by Centrino notebooks.
8603 @item pentium4, pentium4m
8604 Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support.
8606 Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction
8609 Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE,
8610 SSE2 and SSE3 instruction set support.
8612 AMD K6 CPU with MMX instruction set support.
8614 Improved versions of AMD K6 CPU with MMX and 3dNOW! instruction set support.
8615 @item athlon, athlon-tbird
8616 AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and SSE prefetch instructions
8618 @item athlon-4, athlon-xp, athlon-mp
8619 Improved AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and full SSE
8620 instruction set support.
8621 @item k8, opteron, athlon64, athlon-fx
8622 AMD K8 core based CPUs with x86-64 instruction set support. (This supersets
8623 MMX, SSE, SSE2, 3dNOW!, enhanced 3dNOW! and 64-bit instruction set extensions.)
8625 IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction
8628 IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3dNOW!
8629 instruction set support.
8631 Via C3 CPU with MMX and 3dNOW! instruction set support. (No scheduling is
8632 implemented for this chip.)
8634 Via C3-2 CPU with MMX and SSE instruction set support. (No scheduling is
8635 implemented for this chip.)
8638 While picking a specific @var{cpu-type} will schedule things appropriately
8639 for that particular chip, the compiler will not generate any code that
8640 does not run on the i386 without the @option{-march=@var{cpu-type}} option
8643 @item -march=@var{cpu-type}
8645 Generate instructions for the machine type @var{cpu-type}. The choices
8646 for @var{cpu-type} are the same as for @option{-mtune}. Moreover,
8647 specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}.
8649 @item -mcpu=@var{cpu-type}
8651 A deprecated synonym for @option{-mtune}.
8660 @opindex mpentiumpro
8661 These options are synonyms for @option{-mtune=i386}, @option{-mtune=i486},
8662 @option{-mtune=pentium}, and @option{-mtune=pentiumpro} respectively.
8663 These synonyms are deprecated.
8665 @item -mfpmath=@var{unit}
8667 Generate floating point arithmetics for selected unit @var{unit}. The choices
8672 Use the standard 387 floating point coprocessor present majority of chips and
8673 emulated otherwise. Code compiled with this option will run almost everywhere.
8674 The temporary results are computed in 80bit precision instead of precision
8675 specified by the type resulting in slightly different results compared to most
8676 of other chips. See @option{-ffloat-store} for more detailed description.
8678 This is the default choice for i386 compiler.
8681 Use scalar floating point instructions present in the SSE instruction set.
8682 This instruction set is supported by Pentium3 and newer chips, in the AMD line
8683 by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE
8684 instruction set supports only single precision arithmetics, thus the double and
8685 extended precision arithmetics is still done using 387. Later version, present
8686 only in Pentium4 and the future AMD x86-64 chips supports double precision
8689 For the i386 compiler, you need to use @option{-march=@var{cpu-type}}, @option{-msse}
8690 or @option{-msse2} switches to enable SSE extensions and make this option
8691 effective. For the x86-64 compiler, these extensions are enabled by default.
8693 The resulting code should be considerably faster in the majority of cases and avoid
8694 the numerical instability problems of 387 code, but may break some existing
8695 code that expects temporaries to be 80bit.
8697 This is the default choice for the x86-64 compiler.
8700 Attempt to utilize both instruction sets at once. This effectively double the
8701 amount of available registers and on chips with separate execution units for
8702 387 and SSE the execution resources too. Use this option with care, as it is
8703 still experimental, because the GCC register allocator does not model separate
8704 functional units well resulting in instable performance.
8707 @item -masm=@var{dialect}
8708 @opindex masm=@var{dialect}
8709 Output asm instructions using selected @var{dialect}. Supported choices are
8710 @samp{intel} or @samp{att} (the default one).
8715 @opindex mno-ieee-fp
8716 Control whether or not the compiler uses IEEE floating point
8717 comparisons. These handle correctly the case where the result of a
8718 comparison is unordered.
8721 @opindex msoft-float
8722 Generate output containing library calls for floating point.
8723 @strong{Warning:} the requisite libraries are not part of GCC@.
8724 Normally the facilities of the machine's usual C compiler are used, but
8725 this can't be done directly in cross-compilation. You must make your
8726 own arrangements to provide suitable library functions for
8729 On machines where a function returns floating point results in the 80387
8730 register stack, some floating point opcodes may be emitted even if
8731 @option{-msoft-float} is used.
8733 @item -mno-fp-ret-in-387
8734 @opindex mno-fp-ret-in-387
8735 Do not use the FPU registers for return values of functions.
8737 The usual calling convention has functions return values of types
8738 @code{float} and @code{double} in an FPU register, even if there
8739 is no FPU@. The idea is that the operating system should emulate
8742 The option @option{-mno-fp-ret-in-387} causes such values to be returned
8743 in ordinary CPU registers instead.
8745 @item -mno-fancy-math-387
8746 @opindex mno-fancy-math-387
8747 Some 387 emulators do not support the @code{sin}, @code{cos} and
8748 @code{sqrt} instructions for the 387. Specify this option to avoid
8749 generating those instructions. This option is the default on FreeBSD,
8750 OpenBSD and NetBSD@. This option is overridden when @option{-march}
8751 indicates that the target cpu will always have an FPU and so the
8752 instruction will not need emulation. As of revision 2.6.1, these
8753 instructions are not generated unless you also use the
8754 @option{-funsafe-math-optimizations} switch.
8756 @item -malign-double
8757 @itemx -mno-align-double
8758 @opindex malign-double
8759 @opindex mno-align-double
8760 Control whether GCC aligns @code{double}, @code{long double}, and
8761 @code{long long} variables on a two word boundary or a one word
8762 boundary. Aligning @code{double} variables on a two word boundary will
8763 produce code that runs somewhat faster on a @samp{Pentium} at the
8764 expense of more memory.
8766 @strong{Warning:} if you use the @option{-malign-double} switch,
8767 structures containing the above types will be aligned differently than
8768 the published application binary interface specifications for the 386
8769 and will not be binary compatible with structures in code compiled
8770 without that switch.
8772 @item -m96bit-long-double
8773 @itemx -m128bit-long-double
8774 @opindex m96bit-long-double
8775 @opindex m128bit-long-double
8776 These switches control the size of @code{long double} type. The i386
8777 application binary interface specifies the size to be 96 bits,
8778 so @option{-m96bit-long-double} is the default in 32 bit mode.
8780 Modern architectures (Pentium and newer) would prefer @code{long double}
8781 to be aligned to an 8 or 16 byte boundary. In arrays or structures
8782 conforming to the ABI, this would not be possible. So specifying a
8783 @option{-m128bit-long-double} will align @code{long double}
8784 to a 16 byte boundary by padding the @code{long double} with an additional
8787 In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
8788 its ABI specifies that @code{long double} is to be aligned on 16 byte boundary.
8790 Notice that neither of these options enable any extra precision over the x87
8791 standard of 80 bits for a @code{long double}.
8793 @strong{Warning:} if you override the default value for your target ABI, the
8794 structures and arrays containing @code{long double} variables will change
8795 their size as well as function calling convention for function taking
8796 @code{long double} will be modified. Hence they will not be binary
8797 compatible with arrays or structures in code compiled without that switch.
8801 @itemx -mno-svr3-shlib
8802 @opindex msvr3-shlib
8803 @opindex mno-svr3-shlib
8804 Control whether GCC places uninitialized local variables into the
8805 @code{bss} or @code{data} segments. @option{-msvr3-shlib} places them
8806 into @code{bss}. These options are meaningful only on System V Release 3.
8810 Use a different function-calling convention, in which functions that
8811 take a fixed number of arguments return with the @code{ret} @var{num}
8812 instruction, which pops their arguments while returning. This saves one
8813 instruction in the caller since there is no need to pop the arguments
8816 You can specify that an individual function is called with this calling
8817 sequence with the function attribute @samp{stdcall}. You can also
8818 override the @option{-mrtd} option by using the function attribute
8819 @samp{cdecl}. @xref{Function Attributes}.
8821 @strong{Warning:} this calling convention is incompatible with the one
8822 normally used on Unix, so you cannot use it if you need to call
8823 libraries compiled with the Unix compiler.
8825 Also, you must provide function prototypes for all functions that
8826 take variable numbers of arguments (including @code{printf});
8827 otherwise incorrect code will be generated for calls to those
8830 In addition, seriously incorrect code will result if you call a
8831 function with too many arguments. (Normally, extra arguments are
8832 harmlessly ignored.)
8834 @item -mregparm=@var{num}
8836 Control how many registers are used to pass integer arguments. By
8837 default, no registers are used to pass arguments, and at most 3
8838 registers can be used. You can control this behavior for a specific
8839 function by using the function attribute @samp{regparm}.
8840 @xref{Function Attributes}.
8842 @strong{Warning:} if you use this switch, and
8843 @var{num} is nonzero, then you must build all modules with the same
8844 value, including any libraries. This includes the system libraries and
8847 @item -mpreferred-stack-boundary=@var{num}
8848 @opindex mpreferred-stack-boundary
8849 Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
8850 byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
8851 the default is 4 (16 bytes or 128 bits), except when optimizing for code
8852 size (@option{-Os}), in which case the default is the minimum correct
8853 alignment (4 bytes for x86, and 8 bytes for x86-64).
8855 On Pentium and PentiumPro, @code{double} and @code{long double} values
8856 should be aligned to an 8 byte boundary (see @option{-malign-double}) or
8857 suffer significant run time performance penalties. On Pentium III, the
8858 Streaming SIMD Extension (SSE) data type @code{__m128} suffers similar
8859 penalties if it is not 16 byte aligned.
8861 To ensure proper alignment of this values on the stack, the stack boundary
8862 must be as aligned as that required by any value stored on the stack.
8863 Further, every function must be generated such that it keeps the stack
8864 aligned. Thus calling a function compiled with a higher preferred
8865 stack boundary from a function compiled with a lower preferred stack
8866 boundary will most likely misalign the stack. It is recommended that
8867 libraries that use callbacks always use the default setting.
8869 This extra alignment does consume extra stack space, and generally
8870 increases code size. Code that is sensitive to stack space usage, such
8871 as embedded systems and operating system kernels, may want to reduce the
8872 preferred alignment to @option{-mpreferred-stack-boundary=2}.
8890 These switches enable or disable the use of built-in functions that allow
8891 direct access to the MMX, SSE, SSE2, SSE3 and 3Dnow extensions of the
8894 @xref{X86 Built-in Functions}, for details of the functions enabled
8895 and disabled by these switches.
8897 To have SSE/SSE2 instructions generated automatically from floating-point
8898 code, see @option{-mfpmath=sse}.
8901 @itemx -mno-push-args
8903 @opindex mno-push-args
8904 Use PUSH operations to store outgoing parameters. This method is shorter
8905 and usually equally fast as method using SUB/MOV operations and is enabled
8906 by default. In some cases disabling it may improve performance because of
8907 improved scheduling and reduced dependencies.
8909 @item -maccumulate-outgoing-args
8910 @opindex maccumulate-outgoing-args
8911 If enabled, the maximum amount of space required for outgoing arguments will be
8912 computed in the function prologue. This is faster on most modern CPUs
8913 because of reduced dependencies, improved scheduling and reduced stack usage
8914 when preferred stack boundary is not equal to 2. The drawback is a notable
8915 increase in code size. This switch implies @option{-mno-push-args}.
8919 Support thread-safe exception handling on @samp{Mingw32}. Code that relies
8920 on thread-safe exception handling must compile and link all code with the
8921 @option{-mthreads} option. When compiling, @option{-mthreads} defines
8922 @option{-D_MT}; when linking, it links in a special thread helper library
8923 @option{-lmingwthrd} which cleans up per thread exception handling data.
8925 @item -mno-align-stringops
8926 @opindex mno-align-stringops
8927 Do not align destination of inlined string operations. This switch reduces
8928 code size and improves performance in case the destination is already aligned,
8929 but GCC doesn't know about it.
8931 @item -minline-all-stringops
8932 @opindex minline-all-stringops
8933 By default GCC inlines string operations only when destination is known to be
8934 aligned at least to 4 byte boundary. This enables more inlining, increase code
8935 size, but may improve performance of code that depends on fast memcpy, strlen
8936 and memset for short lengths.
8938 @item -momit-leaf-frame-pointer
8939 @opindex momit-leaf-frame-pointer
8940 Don't keep the frame pointer in a register for leaf functions. This
8941 avoids the instructions to save, set up and restore frame pointers and
8942 makes an extra register available in leaf functions. The option
8943 @option{-fomit-frame-pointer} removes the frame pointer for all functions
8944 which might make debugging harder.
8946 @item -mtls-direct-seg-refs
8947 @itemx -mno-tls-direct-seg-refs
8948 @opindex mtls-direct-seg-refs
8949 Controls whether TLS variables may be accessed with offsets from the
8950 TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
8951 or whether the thread base pointer must be added. Whether or not this
8952 is legal depends on the operating system, and whether it maps the
8953 segment to cover the entire TLS area.
8955 For systems that use GNU libc, the default is on.
8958 These @samp{-m} switches are supported in addition to the above
8959 on AMD x86-64 processors in 64-bit environments.
8966 Generate code for a 32-bit or 64-bit environment.
8967 The 32-bit environment sets int, long and pointer to 32 bits and
8968 generates code that runs on any i386 system.
8969 The 64-bit environment sets int to 32 bits and long and pointer
8970 to 64 bits and generates code for AMD's x86-64 architecture.
8973 @opindex no-red-zone
8974 Do not use a so called red zone for x86-64 code. The red zone is mandated
8975 by the x86-64 ABI, it is a 128-byte area beyond the location of the
8976 stack pointer that will not be modified by signal or interrupt handlers
8977 and therefore can be used for temporary data without adjusting the stack
8978 pointer. The flag @option{-mno-red-zone} disables this red zone.
8980 @item -mcmodel=small
8981 @opindex mcmodel=small
8982 Generate code for the small code model: the program and its symbols must
8983 be linked in the lower 2 GB of the address space. Pointers are 64 bits.
8984 Programs can be statically or dynamically linked. This is the default
8987 @item -mcmodel=kernel
8988 @opindex mcmodel=kernel
8989 Generate code for the kernel code model. The kernel runs in the
8990 negative 2 GB of the address space.
8991 This model has to be used for Linux kernel code.
8993 @item -mcmodel=medium
8994 @opindex mcmodel=medium
8995 Generate code for the medium model: The program is linked in the lower 2
8996 GB of the address space but symbols can be located anywhere in the
8997 address space. Programs can be statically or dynamically linked, but
8998 building of shared libraries are not supported with the medium model.
9000 @item -mcmodel=large
9001 @opindex mcmodel=large
9002 Generate code for the large model: This model makes no assumptions
9003 about addresses and sizes of sections. Currently GCC does not implement
9008 @subsection IA-64 Options
9009 @cindex IA-64 Options
9011 These are the @samp{-m} options defined for the Intel IA-64 architecture.
9015 @opindex mbig-endian
9016 Generate code for a big endian target. This is the default for HP-UX@.
9018 @item -mlittle-endian
9019 @opindex mlittle-endian
9020 Generate code for a little endian target. This is the default for AIX5
9027 Generate (or don't) code for the GNU assembler. This is the default.
9028 @c Also, this is the default if the configure option @option{--with-gnu-as}
9035 Generate (or don't) code for the GNU linker. This is the default.
9036 @c Also, this is the default if the configure option @option{--with-gnu-ld}
9041 Generate code that does not use a global pointer register. The result
9042 is not position independent code, and violates the IA-64 ABI@.
9044 @item -mvolatile-asm-stop
9045 @itemx -mno-volatile-asm-stop
9046 @opindex mvolatile-asm-stop
9047 @opindex mno-volatile-asm-stop
9048 Generate (or don't) a stop bit immediately before and after volatile asm
9051 @item -mregister-names
9052 @itemx -mno-register-names
9053 @opindex mregister-names
9054 @opindex mno-register-names
9055 Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
9056 the stacked registers. This may make assembler output more readable.
9062 Disable (or enable) optimizations that use the small data section. This may
9063 be useful for working around optimizer bugs.
9066 @opindex mconstant-gp
9067 Generate code that uses a single constant global pointer value. This is
9068 useful when compiling kernel code.
9072 Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
9073 This is useful when compiling firmware code.
9075 @item -minline-float-divide-min-latency
9076 @opindex minline-float-divide-min-latency
9077 Generate code for inline divides of floating point values
9078 using the minimum latency algorithm.
9080 @item -minline-float-divide-max-throughput
9081 @opindex minline-float-divide-max-throughput
9082 Generate code for inline divides of floating point values
9083 using the maximum throughput algorithm.
9085 @item -minline-int-divide-min-latency
9086 @opindex minline-int-divide-min-latency
9087 Generate code for inline divides of integer values
9088 using the minimum latency algorithm.
9090 @item -minline-int-divide-max-throughput
9091 @opindex minline-int-divide-max-throughput
9092 Generate code for inline divides of integer values
9093 using the maximum throughput algorithm.
9095 @item -minline-sqrt-min-latency
9096 @opindex minline-sqrt-min-latency
9097 Generate code for inline square roots
9098 using the minimum latency algorithm.
9100 @item -minline-sqrt-max-throughput
9101 @opindex minline-sqrt-max-throughput
9102 Generate code for inline square roots
9103 using the maximum throughput algorithm.
9105 @item -mno-dwarf2-asm
9107 @opindex mno-dwarf2-asm
9108 @opindex mdwarf2-asm
9109 Don't (or do) generate assembler code for the DWARF2 line number debugging
9110 info. This may be useful when not using the GNU assembler.
9112 @item -mearly-stop-bits
9113 @itemx -mno-early-stop-bits
9114 @opindex mearly-stop-bits
9115 @opindex mno-early-stop-bits
9116 Allow stop bits to be placed earlier than immediately preceding the
9117 instruction that triggered the stop bit. This can improve instruction
9118 scheduling, but does not always do so.
9120 @item -mfixed-range=@var{register-range}
9121 @opindex mfixed-range
9122 Generate code treating the given register range as fixed registers.
9123 A fixed register is one that the register allocator can not use. This is
9124 useful when compiling kernel code. A register range is specified as
9125 two registers separated by a dash. Multiple register ranges can be
9126 specified separated by a comma.
9128 @item -mtls-size=@var{tls-size}
9130 Specify bit size of immediate TLS offsets. Valid values are 14, 22, and
9133 @item -mtune-arch=@var{cpu-type}
9135 Tune the instruction scheduling for a particular CPU, Valid values are
9136 itanium, itanium1, merced, itanium2, and mckinley.
9142 Add support for multithreading using the POSIX threads library. This
9143 option sets flags for both the preprocessor and linker. It does
9144 not affect the thread safety of object code produced by the compiler or
9145 that of libraries supplied with it. These are HP-UX specific flags.
9151 Generate code for a 32-bit or 64-bit environment.
9152 The 32-bit environment sets int, long and pointer to 32 bits.
9153 The 64-bit environment sets int to 32 bits and long and pointer
9154 to 64 bits. These are HP-UX specific flags.
9158 @node M32R/D Options
9159 @subsection M32R/D Options
9160 @cindex M32R/D options
9162 These @option{-m} options are defined for Renesas M32R/D architectures:
9167 Generate code for the M32R/2@.
9171 Generate code for the M32R/X@.
9175 Generate code for the M32R@. This is the default.
9178 @opindex mmodel=small
9179 Assume all objects live in the lower 16MB of memory (so that their addresses
9180 can be loaded with the @code{ld24} instruction), and assume all subroutines
9181 are reachable with the @code{bl} instruction.
9182 This is the default.
9184 The addressability of a particular object can be set with the
9185 @code{model} attribute.
9187 @item -mmodel=medium
9188 @opindex mmodel=medium
9189 Assume objects may be anywhere in the 32-bit address space (the compiler
9190 will generate @code{seth/add3} instructions to load their addresses), and
9191 assume all subroutines are reachable with the @code{bl} instruction.
9194 @opindex mmodel=large
9195 Assume objects may be anywhere in the 32-bit address space (the compiler
9196 will generate @code{seth/add3} instructions to load their addresses), and
9197 assume subroutines may not be reachable with the @code{bl} instruction
9198 (the compiler will generate the much slower @code{seth/add3/jl}
9199 instruction sequence).
9202 @opindex msdata=none
9203 Disable use of the small data area. Variables will be put into
9204 one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
9205 @code{section} attribute has been specified).
9206 This is the default.
9208 The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
9209 Objects may be explicitly put in the small data area with the
9210 @code{section} attribute using one of these sections.
9213 @opindex msdata=sdata
9214 Put small global and static data in the small data area, but do not
9215 generate special code to reference them.
9219 Put small global and static data in the small data area, and generate
9220 special instructions to reference them.
9224 @cindex smaller data references
9225 Put global and static objects less than or equal to @var{num} bytes
9226 into the small data or bss sections instead of the normal data or bss
9227 sections. The default value of @var{num} is 8.
9228 The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
9229 for this option to have any effect.
9231 All modules should be compiled with the same @option{-G @var{num}} value.
9232 Compiling with different values of @var{num} may or may not work; if it
9233 doesn't the linker will give an error message---incorrect code will not be
9238 Makes the M32R specific code in the compiler display some statistics
9239 that might help in debugging programs.
9242 @opindex malign-loops
9243 Align all loops to a 32-byte boundary.
9245 @item -mno-align-loops
9246 @opindex mno-align-loops
9247 Do not enforce a 32-byte alignment for loops. This is the default.
9249 @item -missue-rate=@var{number}
9250 @opindex missue-rate=@var{number}
9251 Issue @var{number} instructions per cycle. @var{number} can only be 1
9254 @item -mbranch-cost=@var{number}
9255 @opindex mbranch-cost=@var{number}
9256 @var{number} can only be 1 or 2. If it is 1 then branches will be
9257 preferred over conditional code, if it is 2, then the opposite will
9260 @item -mflush-trap=@var{number}
9261 @opindex mflush-trap=@var{number}
9262 Specifies the trap number to use to flush the cache. The default is
9263 12. Valid numbers are between 0 and 15 inclusive.
9265 @item -mno-flush-trap
9266 @opindex mno-flush-trap
9267 Specifies that the cache cannot be flushed by using a trap.
9269 @item -mflush-func=@var{name}
9270 @opindex mflush-func=@var{name}
9271 Specifies the name of the operating system function to call to flush
9272 the cache. The default is @emph{_flush_cache}, but a function call
9273 will only be used if a trap is not available.
9275 @item -mno-flush-func
9276 @opindex mno-flush-func
9277 Indicates that there is no OS function for flushing the cache.
9281 @node M680x0 Options
9282 @subsection M680x0 Options
9283 @cindex M680x0 options
9285 These are the @samp{-m} options defined for the 68000 series. The default
9286 values for these options depends on which style of 68000 was selected when
9287 the compiler was configured; the defaults for the most common choices are
9295 Generate output for a 68000. This is the default
9296 when the compiler is configured for 68000-based systems.
9298 Use this option for microcontrollers with a 68000 or EC000 core,
9299 including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
9305 Generate output for a 68020. This is the default
9306 when the compiler is configured for 68020-based systems.
9310 Generate output containing 68881 instructions for floating point.
9311 This is the default for most 68020 systems unless @option{--nfp} was
9312 specified when the compiler was configured.
9316 Generate output for a 68030. This is the default when the compiler is
9317 configured for 68030-based systems.
9321 Generate output for a 68040. This is the default when the compiler is
9322 configured for 68040-based systems.
9324 This option inhibits the use of 68881/68882 instructions that have to be
9325 emulated by software on the 68040. Use this option if your 68040 does not
9326 have code to emulate those instructions.
9330 Generate output for a 68060. This is the default when the compiler is
9331 configured for 68060-based systems.
9333 This option inhibits the use of 68020 and 68881/68882 instructions that
9334 have to be emulated by software on the 68060. Use this option if your 68060
9335 does not have code to emulate those instructions.
9339 Generate output for a CPU32. This is the default
9340 when the compiler is configured for CPU32-based systems.
9342 Use this option for microcontrollers with a
9343 CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
9344 68336, 68340, 68341, 68349 and 68360.
9348 Generate output for a 520X ``coldfire'' family cpu. This is the default
9349 when the compiler is configured for 520X-based systems.
9351 Use this option for microcontroller with a 5200 core, including
9352 the MCF5202, MCF5203, MCF5204 and MCF5202.
9357 Generate output for a 68040, without using any of the new instructions.
9358 This results in code which can run relatively efficiently on either a
9359 68020/68881 or a 68030 or a 68040. The generated code does use the
9360 68881 instructions that are emulated on the 68040.
9364 Generate output for a 68060, without using any of the new instructions.
9365 This results in code which can run relatively efficiently on either a
9366 68020/68881 or a 68030 or a 68040. The generated code does use the
9367 68881 instructions that are emulated on the 68060.
9370 @opindex msoft-float
9371 Generate output containing library calls for floating point.
9372 @strong{Warning:} the requisite libraries are not available for all m68k
9373 targets. Normally the facilities of the machine's usual C compiler are
9374 used, but this can't be done directly in cross-compilation. You must
9375 make your own arrangements to provide suitable library functions for
9376 cross-compilation. The embedded targets @samp{m68k-*-aout} and
9377 @samp{m68k-*-coff} do provide software floating point support.
9381 Consider type @code{int} to be 16 bits wide, like @code{short int}.
9382 Additionally, parameters passed on the stack are also aligned to a
9383 16-bit boundary even on targets whose API mandates promotion to 32-bit.
9386 @opindex mnobitfield
9387 Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
9388 and @option{-m5200} options imply @w{@option{-mnobitfield}}.
9392 Do use the bit-field instructions. The @option{-m68020} option implies
9393 @option{-mbitfield}. This is the default if you use a configuration
9394 designed for a 68020.
9398 Use a different function-calling convention, in which functions
9399 that take a fixed number of arguments return with the @code{rtd}
9400 instruction, which pops their arguments while returning. This
9401 saves one instruction in the caller since there is no need to pop
9402 the arguments there.
9404 This calling convention is incompatible with the one normally
9405 used on Unix, so you cannot use it if you need to call libraries
9406 compiled with the Unix compiler.
9408 Also, you must provide function prototypes for all functions that
9409 take variable numbers of arguments (including @code{printf});
9410 otherwise incorrect code will be generated for calls to those
9413 In addition, seriously incorrect code will result if you call a
9414 function with too many arguments. (Normally, extra arguments are
9415 harmlessly ignored.)
9417 The @code{rtd} instruction is supported by the 68010, 68020, 68030,
9418 68040, 68060 and CPU32 processors, but not by the 68000 or 5200.
9421 @itemx -mno-align-int
9423 @opindex mno-align-int
9424 Control whether GCC aligns @code{int}, @code{long}, @code{long long},
9425 @code{float}, @code{double}, and @code{long double} variables on a 32-bit
9426 boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
9427 Aligning variables on 32-bit boundaries produces code that runs somewhat
9428 faster on processors with 32-bit busses at the expense of more memory.
9430 @strong{Warning:} if you use the @option{-malign-int} switch, GCC will
9431 align structures containing the above types differently than
9432 most published application binary interface specifications for the m68k.
9436 Use the pc-relative addressing mode of the 68000 directly, instead of
9437 using a global offset table. At present, this option implies @option{-fpic},
9438 allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
9439 not presently supported with @option{-mpcrel}, though this could be supported for
9440 68020 and higher processors.
9442 @item -mno-strict-align
9443 @itemx -mstrict-align
9444 @opindex mno-strict-align
9445 @opindex mstrict-align
9446 Do not (do) assume that unaligned memory references will be handled by
9450 Generate code that allows the data segment to be located in a different
9451 area of memory from the text segment. This allows for execute in place in
9452 an environment without virtual memory management. This option implies
9456 Generate code that assumes that the data segment follows the text segment.
9457 This is the default.
9459 @item -mid-shared-library
9460 Generate code that supports shared libraries via the library ID method.
9461 This allows for execute in place and shared libraries in an environment
9462 without virtual memory management. This option implies @option{-fPIC}.
9464 @item -mno-id-shared-library
9465 Generate code that doesn't assume ID based shared libraries are being used.
9466 This is the default.
9468 @item -mshared-library-id=n
9469 Specified the identification number of the ID based shared library being
9470 compiled. Specifying a value of 0 will generate more compact code, specifying
9471 other values will force the allocation of that number to the current
9472 library but is no more space or time efficient than omitting this option.
9476 @node M68hc1x Options
9477 @subsection M68hc1x Options
9478 @cindex M68hc1x options
9480 These are the @samp{-m} options defined for the 68hc11 and 68hc12
9481 microcontrollers. The default values for these options depends on
9482 which style of microcontroller was selected when the compiler was configured;
9483 the defaults for the most common choices are given below.
9490 Generate output for a 68HC11. This is the default
9491 when the compiler is configured for 68HC11-based systems.
9497 Generate output for a 68HC12. This is the default
9498 when the compiler is configured for 68HC12-based systems.
9504 Generate output for a 68HCS12.
9507 @opindex mauto-incdec
9508 Enable the use of 68HC12 pre and post auto-increment and auto-decrement
9515 Enable the use of 68HC12 min and max instructions.
9518 @itemx -mno-long-calls
9519 @opindex mlong-calls
9520 @opindex mno-long-calls
9521 Treat all calls as being far away (near). If calls are assumed to be
9522 far away, the compiler will use the @code{call} instruction to
9523 call a function and the @code{rtc} instruction for returning.
9527 Consider type @code{int} to be 16 bits wide, like @code{short int}.
9529 @item -msoft-reg-count=@var{count}
9530 @opindex msoft-reg-count
9531 Specify the number of pseudo-soft registers which are used for the
9532 code generation. The maximum number is 32. Using more pseudo-soft
9533 register may or may not result in better code depending on the program.
9534 The default is 4 for 68HC11 and 2 for 68HC12.
9539 @subsection MCore Options
9540 @cindex MCore options
9542 These are the @samp{-m} options defined for the Motorola M*Core
9550 @opindex mno-hardlit
9551 Inline constants into the code stream if it can be done in two
9552 instructions or less.
9558 Use the divide instruction. (Enabled by default).
9560 @item -mrelax-immediate
9561 @itemx -mno-relax-immediate
9562 @opindex mrelax-immediate
9563 @opindex mno-relax-immediate
9564 Allow arbitrary sized immediates in bit operations.
9566 @item -mwide-bitfields
9567 @itemx -mno-wide-bitfields
9568 @opindex mwide-bitfields
9569 @opindex mno-wide-bitfields
9570 Always treat bit-fields as int-sized.
9572 @item -m4byte-functions
9573 @itemx -mno-4byte-functions
9574 @opindex m4byte-functions
9575 @opindex mno-4byte-functions
9576 Force all functions to be aligned to a four byte boundary.
9578 @item -mcallgraph-data
9579 @itemx -mno-callgraph-data
9580 @opindex mcallgraph-data
9581 @opindex mno-callgraph-data
9582 Emit callgraph information.
9585 @itemx -mno-slow-bytes
9586 @opindex mslow-bytes
9587 @opindex mno-slow-bytes
9588 Prefer word access when reading byte quantities.
9590 @item -mlittle-endian
9592 @opindex mlittle-endian
9593 @opindex mbig-endian
9594 Generate code for a little endian target.
9600 Generate code for the 210 processor.
9604 @subsection MIPS Options
9605 @cindex MIPS options
9611 Generate big-endian code.
9615 Generate little-endian code. This is the default for @samp{mips*el-*-*}
9618 @item -march=@var{arch}
9620 Generate code that will run on @var{arch}, which can be the name of a
9621 generic MIPS ISA, or the name of a particular processor.
9623 @samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
9624 @samp{mips32}, @samp{mips32r2}, and @samp{mips64}.
9625 The processor names are:
9626 @samp{4kc}, @samp{4kp}, @samp{5kc}, @samp{20kc},
9628 @samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
9629 @samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000}, @samp{rm7000},
9633 @samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
9634 @samp{vr5000}, @samp{vr5400} and @samp{vr5500}.
9635 The special value @samp{from-abi} selects the
9636 most compatible architecture for the selected ABI (that is,
9637 @samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
9639 In processor names, a final @samp{000} can be abbreviated as @samp{k}
9640 (for example, @samp{-march=r2k}). Prefixes are optional, and
9641 @samp{vr} may be written @samp{r}.
9643 GCC defines two macros based on the value of this option. The first
9644 is @samp{_MIPS_ARCH}, which gives the name of target architecture, as
9645 a string. The second has the form @samp{_MIPS_ARCH_@var{foo}},
9646 where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@.
9647 For example, @samp{-march=r2000} will set @samp{_MIPS_ARCH}
9648 to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}.
9650 Note that the @samp{_MIPS_ARCH} macro uses the processor names given
9651 above. In other words, it will have the full prefix and will not
9652 abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},
9653 the macro names the resolved architecture (either @samp{"mips1"} or
9654 @samp{"mips3"}). It names the default architecture when no
9655 @option{-march} option is given.
9657 @item -mtune=@var{arch}
9659 Optimize for @var{arch}. Among other things, this option controls
9660 the way instructions are scheduled, and the perceived cost of arithmetic
9661 operations. The list of @var{arch} values is the same as for
9664 When this option is not used, GCC will optimize for the processor
9665 specified by @option{-march}. By using @option{-march} and
9666 @option{-mtune} together, it is possible to generate code that will
9667 run on a family of processors, but optimize the code for one
9668 particular member of that family.
9670 @samp{-mtune} defines the macros @samp{_MIPS_TUNE} and
9671 @samp{_MIPS_TUNE_@var{foo}}, which work in the same way as the
9672 @samp{-march} ones described above.
9676 Equivalent to @samp{-march=mips1}.
9680 Equivalent to @samp{-march=mips2}.
9684 Equivalent to @samp{-march=mips3}.
9688 Equivalent to @samp{-march=mips4}.
9692 Equivalent to @samp{-march=mips32}.
9696 Equivalent to @samp{-march=mips32r2}.
9700 Equivalent to @samp{-march=mips64}.
9706 Use (do not use) the MIPS16 ISA@.
9718 Generate code for the given ABI@.
9720 Note that the EABI has a 32-bit and a 64-bit variant. GCC normally
9721 generates 64-bit code when you select a 64-bit architecture, but you
9722 can use @option{-mgp32} to get 32-bit code instead.
9724 For information about the O64 ABI, see
9725 @w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
9728 @itemx -mno-abicalls
9730 @opindex mno-abicalls
9731 Generate (do not generate) SVR4-style position-independent code.
9732 @option{-mabicalls} is the default for SVR4-based systems.
9738 Lift (do not lift) the usual restrictions on the size of the global
9741 GCC normally uses a single instruction to load values from the GOT@.
9742 While this is relatively efficient, it will only work if the GOT
9743 is smaller than about 64k. Anything larger will cause the linker
9744 to report an error such as:
9746 @cindex relocation truncated to fit (MIPS)
9748 relocation truncated to fit: R_MIPS_GOT16 foobar
9751 If this happens, you should recompile your code with @option{-mxgot}.
9752 It should then work with very large GOTs, although it will also be
9753 less efficient, since it will take three instructions to fetch the
9754 value of a global symbol.
9756 Note that some linkers can create multiple GOTs. If you have such a
9757 linker, you should only need to use @option{-mxgot} when a single object
9758 file accesses more than 64k's worth of GOT entries. Very few do.
9760 These options have no effect unless GCC is generating position
9765 Assume that general-purpose registers are 32 bits wide.
9769 Assume that general-purpose registers are 64 bits wide.
9773 Assume that floating-point registers are 32 bits wide.
9777 Assume that floating-point registers are 64 bits wide.
9780 @opindex mhard-float
9781 Use floating-point coprocessor instructions.
9784 @opindex msoft-float
9785 Do not use floating-point coprocessor instructions. Implement
9786 floating-point calculations using library calls instead.
9788 @item -msingle-float
9789 @opindex msingle-float
9790 Assume that the floating-point coprocessor only supports single-precision
9793 @itemx -mdouble-float
9794 @opindex mdouble-float
9795 Assume that the floating-point coprocessor supports double-precision
9796 operations. This is the default.
9798 @itemx -mpaired-single
9799 @itemx -mno-paired-single
9800 @opindex mpaired-single
9801 @opindex mno-paired-single
9802 Use (do not use) paired-single floating-point instructions.
9803 @xref{MIPS Paired-Single Support}. This option can only be used
9804 when generating 64-bit code and requires hardware floating-point
9805 support to be enabled.
9811 Use (do not use) the MIPS-3D ASE@. @xref{MIPS-3D Built-in Functions}.
9812 The option @option{-mips3d} implies @option{-mpaired-single}.
9816 Force @code{int} and @code{long} types to be 64 bits wide. See
9817 @option{-mlong32} for an explanation of the default and the way
9818 that the pointer size is determined.
9820 This option has been deprecated and will be removed in a future release.
9824 Force @code{long} types to be 64 bits wide. See @option{-mlong32} for
9825 an explanation of the default and the way that the pointer size is
9830 Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
9832 The default size of @code{int}s, @code{long}s and pointers depends on
9833 the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI
9834 uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
9835 32-bit @code{long}s. Pointers are the same size as @code{long}s,
9836 or the same size as integer registers, whichever is smaller.
9842 Assume (do not assume) that all symbols have 32-bit values, regardless
9843 of the selected ABI@. This option is useful in combination with
9844 @option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
9845 to generate shorter and faster references to symbolic addresses.
9849 @cindex smaller data references (MIPS)
9850 @cindex gp-relative references (MIPS)
9851 Put global and static items less than or equal to @var{num} bytes into
9852 the small data or bss section instead of the normal data or bss section.
9853 This allows the data to be accessed using a single instruction.
9855 All modules should be compiled with the same @option{-G @var{num}}
9858 @item -membedded-data
9859 @itemx -mno-embedded-data
9860 @opindex membedded-data
9861 @opindex mno-embedded-data
9862 Allocate variables to the read-only data section first if possible, then
9863 next in the small data section if possible, otherwise in data. This gives
9864 slightly slower code than the default, but reduces the amount of RAM required
9865 when executing, and thus may be preferred for some embedded systems.
9867 @item -muninit-const-in-rodata
9868 @itemx -mno-uninit-const-in-rodata
9869 @opindex muninit-const-in-rodata
9870 @opindex mno-uninit-const-in-rodata
9871 Put uninitialized @code{const} variables in the read-only data section.
9872 This option is only meaningful in conjunction with @option{-membedded-data}.
9874 @item -msplit-addresses
9875 @itemx -mno-split-addresses
9876 @opindex msplit-addresses
9877 @opindex mno-split-addresses
9878 Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
9879 relocation operators. This option has been superseded by
9880 @option{-mexplicit-relocs} but is retained for backwards compatibility.
9882 @item -mexplicit-relocs
9883 @itemx -mno-explicit-relocs
9884 @opindex mexplicit-relocs
9885 @opindex mno-explicit-relocs
9886 Use (do not use) assembler relocation operators when dealing with symbolic
9887 addresses. The alternative, selected by @option{-mno-explicit-relocs},
9888 is to use assembler macros instead.
9890 @option{-mexplicit-relocs} is the default if GCC was configured
9891 to use an assembler that supports relocation operators.
9893 @item -mcheck-zero-division
9894 @itemx -mno-check-zero-division
9895 @opindex mcheck-zero-division
9896 @opindex mno-check-zero-division
9897 Trap (do not trap) on integer division by zero. The default is
9898 @option{-mcheck-zero-division}.
9900 @item -mdivide-traps
9901 @itemx -mdivide-breaks
9902 @opindex mdivide-traps
9903 @opindex mdivide-breaks
9904 MIPS systems check for division by zero by generating either a
9905 conditional trap or a break instruction. Using traps results in
9906 smaller code, but is only supported on MIPS II and later. Also, some
9907 versions of the Linux kernel have a bug that prevents trap from
9908 generating the proper signal (@code{SIGFPE}). Use @option{-mdivide-traps} to
9909 allow conditional traps on architectures that support them and
9910 @option{-mdivide-breaks} to force the use of breaks.
9912 The default is usually @option{-mdivide-traps}, but this can be
9913 overridden at configure time using @option{--with-divide=breaks}.
9914 Divide-by-zero checks can be completely disabled using
9915 @option{-mno-check-zero-division}.
9921 Force (do not force) the use of @code{memcpy()} for non-trivial block
9922 moves. The default is @option{-mno-memcpy}, which allows GCC to inline
9923 most constant-sized copies.
9926 @itemx -mno-long-calls
9927 @opindex mlong-calls
9928 @opindex mno-long-calls
9929 Disable (do not disable) use of the @code{jal} instruction. Calling
9930 functions using @code{jal} is more efficient but requires the caller
9931 and callee to be in the same 256 megabyte segment.
9933 This option has no effect on abicalls code. The default is
9934 @option{-mno-long-calls}.
9940 Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
9941 instructions, as provided by the R4650 ISA@.
9944 @itemx -mno-fused-madd
9945 @opindex mfused-madd
9946 @opindex mno-fused-madd
9947 Enable (disable) use of the floating point multiply-accumulate
9948 instructions, when they are available. The default is
9949 @option{-mfused-madd}.
9951 When multiply-accumulate instructions are used, the intermediate
9952 product is calculated to infinite precision and is not subject to
9953 the FCSR Flush to Zero bit. This may be undesirable in some
9958 Tell the MIPS assembler to not run its preprocessor over user
9959 assembler files (with a @samp{.s} suffix) when assembling them.
9962 @itemx -mno-fix-r4000
9964 @opindex mno-fix-r4000
9965 Work around certain R4000 CPU errata:
9968 A double-word or a variable shift may give an incorrect result if executed
9969 immediately after starting an integer division.
9971 A double-word or a variable shift may give an incorrect result if executed
9972 while an integer multiplication is in progress.
9974 An integer division may give an incorrect result if started in a delay slot
9975 of a taken branch or a jump.
9979 @itemx -mno-fix-r4400
9981 @opindex mno-fix-r4400
9982 Work around certain R4400 CPU errata:
9985 A double-word or a variable shift may give an incorrect result if executed
9986 immediately after starting an integer division.
9990 @itemx -mno-fix-vr4120
9991 @opindex mfix-vr4120
9992 Work around certain VR4120 errata:
9995 @code{dmultu} does not always produce the correct result.
9997 @code{div} and @code{ddiv} do not always produce the correct result if one
9998 of the operands is negative.
10000 The workarounds for the division errata rely on special functions in
10001 @file{libgcc.a}. At present, these functions are only provided by
10002 the @code{mips64vr*-elf} configurations.
10004 Other VR4120 errata require a nop to be inserted between certain pairs of
10005 instructions. These errata are handled by the assembler, not by GCC itself.
10008 @opindex mfix-vr4130
10009 Work around the VR4130 @code{mflo}/@code{mfhi} errata. The
10010 workarounds are implemented by the assembler rather than by GCC,
10011 although GCC will avoid using @code{mflo} and @code{mfhi} if the
10012 VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
10013 instructions are available instead.
10016 @itemx -mno-fix-sb1
10018 Work around certain SB-1 CPU core errata.
10019 (This flag currently works around the SB-1 revision 2
10020 ``F1'' and ``F2'' floating point errata.)
10022 @item -mflush-func=@var{func}
10023 @itemx -mno-flush-func
10024 @opindex mflush-func
10025 Specifies the function to call to flush the I and D caches, or to not
10026 call any such function. If called, the function must take the same
10027 arguments as the common @code{_flush_func()}, that is, the address of the
10028 memory range for which the cache is being flushed, the size of the
10029 memory range, and the number 3 (to flush both caches). The default
10030 depends on the target GCC was configured for, but commonly is either
10031 @samp{_flush_func} or @samp{__cpu_flush}.
10033 @item -mbranch-likely
10034 @itemx -mno-branch-likely
10035 @opindex mbranch-likely
10036 @opindex mno-branch-likely
10037 Enable or disable use of Branch Likely instructions, regardless of the
10038 default for the selected architecture. By default, Branch Likely
10039 instructions may be generated if they are supported by the selected
10040 architecture. An exception is for the MIPS32 and MIPS64 architectures
10041 and processors which implement those architectures; for those, Branch
10042 Likely instructions will not be generated by default because the MIPS32
10043 and MIPS64 architectures specifically deprecate their use.
10045 @item -mfp-exceptions
10046 @itemx -mno-fp-exceptions
10047 @opindex mfp-exceptions
10048 Specifies whether FP exceptions are enabled. This affects how we schedule
10049 FP instructions for some processors. The default is that FP exceptions are
10052 For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
10053 64-bit code, then we can use both FP pipes. Otherwise, we can only use one
10056 @item -mvr4130-align
10057 @itemx -mno-vr4130-align
10058 @opindex mvr4130-align
10059 The VR4130 pipeline is two-way superscalar, but can only issue two
10060 instructions together if the first one is 8-byte aligned. When this
10061 option is enabled, GCC will align pairs of instructions that it
10062 thinks should execute in parallel.
10064 This option only has an effect when optimizing for the VR4130.
10065 It normally makes code faster, but at the expense of making it bigger.
10066 It is enabled by default at optimization level @option{-O3}.
10070 @subsection MMIX Options
10071 @cindex MMIX Options
10073 These options are defined for the MMIX:
10077 @itemx -mno-libfuncs
10079 @opindex mno-libfuncs
10080 Specify that intrinsic library functions are being compiled, passing all
10081 values in registers, no matter the size.
10084 @itemx -mno-epsilon
10086 @opindex mno-epsilon
10087 Generate floating-point comparison instructions that compare with respect
10088 to the @code{rE} epsilon register.
10090 @item -mabi=mmixware
10092 @opindex mabi-mmixware
10094 Generate code that passes function parameters and return values that (in
10095 the called function) are seen as registers @code{$0} and up, as opposed to
10096 the GNU ABI which uses global registers @code{$231} and up.
10098 @item -mzero-extend
10099 @itemx -mno-zero-extend
10100 @opindex mzero-extend
10101 @opindex mno-zero-extend
10102 When reading data from memory in sizes shorter than 64 bits, use (do not
10103 use) zero-extending load instructions by default, rather than
10104 sign-extending ones.
10107 @itemx -mno-knuthdiv
10109 @opindex mno-knuthdiv
10110 Make the result of a division yielding a remainder have the same sign as
10111 the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
10112 remainder follows the sign of the dividend. Both methods are
10113 arithmetically valid, the latter being almost exclusively used.
10115 @item -mtoplevel-symbols
10116 @itemx -mno-toplevel-symbols
10117 @opindex mtoplevel-symbols
10118 @opindex mno-toplevel-symbols
10119 Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
10120 code can be used with the @code{PREFIX} assembly directive.
10124 Generate an executable in the ELF format, rather than the default
10125 @samp{mmo} format used by the @command{mmix} simulator.
10127 @item -mbranch-predict
10128 @itemx -mno-branch-predict
10129 @opindex mbranch-predict
10130 @opindex mno-branch-predict
10131 Use (do not use) the probable-branch instructions, when static branch
10132 prediction indicates a probable branch.
10134 @item -mbase-addresses
10135 @itemx -mno-base-addresses
10136 @opindex mbase-addresses
10137 @opindex mno-base-addresses
10138 Generate (do not generate) code that uses @emph{base addresses}. Using a
10139 base address automatically generates a request (handled by the assembler
10140 and the linker) for a constant to be set up in a global register. The
10141 register is used for one or more base address requests within the range 0
10142 to 255 from the value held in the register. The generally leads to short
10143 and fast code, but the number of different data items that can be
10144 addressed is limited. This means that a program that uses lots of static
10145 data may require @option{-mno-base-addresses}.
10147 @item -msingle-exit
10148 @itemx -mno-single-exit
10149 @opindex msingle-exit
10150 @opindex mno-single-exit
10151 Force (do not force) generated code to have a single exit point in each
10155 @node MN10300 Options
10156 @subsection MN10300 Options
10157 @cindex MN10300 options
10159 These @option{-m} options are defined for Matsushita MN10300 architectures:
10164 Generate code to avoid bugs in the multiply instructions for the MN10300
10165 processors. This is the default.
10167 @item -mno-mult-bug
10168 @opindex mno-mult-bug
10169 Do not generate code to avoid bugs in the multiply instructions for the
10170 MN10300 processors.
10174 Generate code which uses features specific to the AM33 processor.
10178 Do not generate code which uses features specific to the AM33 processor. This
10183 Do not link in the C run-time initialization object file.
10187 Indicate to the linker that it should perform a relaxation optimization pass
10188 to shorten branches, calls and absolute memory addresses. This option only
10189 has an effect when used on the command line for the final link step.
10191 This option makes symbolic debugging impossible.
10194 @node NS32K Options
10195 @subsection NS32K Options
10196 @cindex NS32K options
10198 These are the @samp{-m} options defined for the 32000 series. The default
10199 values for these options depends on which style of 32000 was selected when
10200 the compiler was configured; the defaults for the most common choices are
10208 Generate output for a 32032. This is the default
10209 when the compiler is configured for 32032 and 32016 based systems.
10215 Generate output for a 32332. This is the default
10216 when the compiler is configured for 32332-based systems.
10222 Generate output for a 32532. This is the default
10223 when the compiler is configured for 32532-based systems.
10227 Generate output containing 32081 instructions for floating point.
10228 This is the default for all systems.
10232 Generate output containing 32381 instructions for floating point. This
10233 also implies @option{-m32081}. The 32381 is only compatible with the 32332
10234 and 32532 cpus. This is the default for the pc532-netbsd configuration.
10237 @opindex mmulti-add
10238 Try and generate multiply-add floating point instructions @code{polyF}
10239 and @code{dotF}. This option is only available if the @option{-m32381}
10240 option is in effect. Using these instructions requires changes to
10241 register allocation which generally has a negative impact on
10242 performance. This option should only be enabled when compiling code
10243 particularly likely to make heavy use of multiply-add instructions.
10245 @item -mnomulti-add
10246 @opindex mnomulti-add
10247 Do not try and generate multiply-add floating point instructions
10248 @code{polyF} and @code{dotF}. This is the default on all platforms.
10251 @opindex msoft-float
10252 Generate output containing library calls for floating point.
10253 @strong{Warning:} the requisite libraries may not be available.
10255 @item -mieee-compare
10256 @itemx -mno-ieee-compare
10257 @opindex mieee-compare
10258 @opindex mno-ieee-compare
10259 Control whether or not the compiler uses IEEE floating point
10260 comparisons. These handle correctly the case where the result of a
10261 comparison is unordered.
10262 @strong{Warning:} the requisite kernel support may not be available.
10265 @opindex mnobitfield
10266 Do not use the bit-field instructions. On some machines it is faster to
10267 use shifting and masking operations. This is the default for the pc532.
10271 Do use the bit-field instructions. This is the default for all platforms
10276 Use a different function-calling convention, in which functions
10277 that take a fixed number of arguments return pop their
10278 arguments on return with the @code{ret} instruction.
10280 This calling convention is incompatible with the one normally
10281 used on Unix, so you cannot use it if you need to call libraries
10282 compiled with the Unix compiler.
10284 Also, you must provide function prototypes for all functions that
10285 take variable numbers of arguments (including @code{printf});
10286 otherwise incorrect code will be generated for calls to those
10289 In addition, seriously incorrect code will result if you call a
10290 function with too many arguments. (Normally, extra arguments are
10291 harmlessly ignored.)
10293 This option takes its name from the 680x0 @code{rtd} instruction.
10298 Use a different function-calling convention where the first two arguments
10299 are passed in registers.
10301 This calling convention is incompatible with the one normally
10302 used on Unix, so you cannot use it if you need to call libraries
10303 compiled with the Unix compiler.
10306 @opindex mnoregparam
10307 Do not pass any arguments in registers. This is the default for all
10312 It is OK to use the sb as an index register which is always loaded with
10313 zero. This is the default for the pc532-netbsd target.
10317 The sb register is not available for use or has not been initialized to
10318 zero by the run time system. This is the default for all targets except
10319 the pc532-netbsd. It is also implied whenever @option{-mhimem} or
10320 @option{-fpic} is set.
10324 Many ns32000 series addressing modes use displacements of up to 512MB@.
10325 If an address is above 512MB then displacements from zero can not be used.
10326 This option causes code to be generated which can be loaded above 512MB@.
10327 This may be useful for operating systems or ROM code.
10331 Assume code will be loaded in the first 512MB of virtual address space.
10332 This is the default for all platforms.
10336 @node PDP-11 Options
10337 @subsection PDP-11 Options
10338 @cindex PDP-11 Options
10340 These options are defined for the PDP-11:
10345 Use hardware FPP floating point. This is the default. (FIS floating
10346 point on the PDP-11/40 is not supported.)
10349 @opindex msoft-float
10350 Do not use hardware floating point.
10354 Return floating-point results in ac0 (fr0 in Unix assembler syntax).
10358 Return floating-point results in memory. This is the default.
10362 Generate code for a PDP-11/40.
10366 Generate code for a PDP-11/45. This is the default.
10370 Generate code for a PDP-11/10.
10372 @item -mbcopy-builtin
10373 @opindex bcopy-builtin
10374 Use inline @code{movmemhi} patterns for copying memory. This is the
10379 Do not use inline @code{movmemhi} patterns for copying memory.
10385 Use 16-bit @code{int}. This is the default.
10391 Use 32-bit @code{int}.
10394 @itemx -mno-float32
10396 @opindex mno-float32
10397 Use 64-bit @code{float}. This is the default.
10400 @itemx -mno-float64
10402 @opindex mno-float64
10403 Use 32-bit @code{float}.
10407 Use @code{abshi2} pattern. This is the default.
10411 Do not use @code{abshi2} pattern.
10413 @item -mbranch-expensive
10414 @opindex mbranch-expensive
10415 Pretend that branches are expensive. This is for experimenting with
10416 code generation only.
10418 @item -mbranch-cheap
10419 @opindex mbranch-cheap
10420 Do not pretend that branches are expensive. This is the default.
10424 Generate code for a system with split I&D@.
10428 Generate code for a system without split I&D@. This is the default.
10432 Use Unix assembler syntax. This is the default when configured for
10433 @samp{pdp11-*-bsd}.
10437 Use DEC assembler syntax. This is the default when configured for any
10438 PDP-11 target other than @samp{pdp11-*-bsd}.
10441 @node PowerPC Options
10442 @subsection PowerPC Options
10443 @cindex PowerPC options
10445 These are listed under @xref{RS/6000 and PowerPC Options}.
10447 @node RS/6000 and PowerPC Options
10448 @subsection IBM RS/6000 and PowerPC Options
10449 @cindex RS/6000 and PowerPC Options
10450 @cindex IBM RS/6000 and PowerPC Options
10452 These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
10459 @itemx -mno-powerpc
10460 @itemx -mpowerpc-gpopt
10461 @itemx -mno-powerpc-gpopt
10462 @itemx -mpowerpc-gfxopt
10463 @itemx -mno-powerpc-gfxopt
10465 @itemx -mno-powerpc64
10469 @opindex mno-power2
10471 @opindex mno-powerpc
10472 @opindex mpowerpc-gpopt
10473 @opindex mno-powerpc-gpopt
10474 @opindex mpowerpc-gfxopt
10475 @opindex mno-powerpc-gfxopt
10476 @opindex mpowerpc64
10477 @opindex mno-powerpc64
10478 GCC supports two related instruction set architectures for the
10479 RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those
10480 instructions supported by the @samp{rios} chip set used in the original
10481 RS/6000 systems and the @dfn{PowerPC} instruction set is the
10482 architecture of the Motorola MPC5xx, MPC6xx, MPC8xx microprocessors, and
10483 the IBM 4xx microprocessors.
10485 Neither architecture is a subset of the other. However there is a
10486 large common subset of instructions supported by both. An MQ
10487 register is included in processors supporting the POWER architecture.
10489 You use these options to specify which instructions are available on the
10490 processor you are using. The default value of these options is
10491 determined when configuring GCC@. Specifying the
10492 @option{-mcpu=@var{cpu_type}} overrides the specification of these
10493 options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
10494 rather than the options listed above.
10496 The @option{-mpower} option allows GCC to generate instructions that
10497 are found only in the POWER architecture and to use the MQ register.
10498 Specifying @option{-mpower2} implies @option{-power} and also allows GCC
10499 to generate instructions that are present in the POWER2 architecture but
10500 not the original POWER architecture.
10502 The @option{-mpowerpc} option allows GCC to generate instructions that
10503 are found only in the 32-bit subset of the PowerPC architecture.
10504 Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
10505 GCC to use the optional PowerPC architecture instructions in the
10506 General Purpose group, including floating-point square root. Specifying
10507 @option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
10508 use the optional PowerPC architecture instructions in the Graphics
10509 group, including floating-point select.
10511 The @option{-mpowerpc64} option allows GCC to generate the additional
10512 64-bit instructions that are found in the full PowerPC64 architecture
10513 and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
10514 @option{-mno-powerpc64}.
10516 If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
10517 will use only the instructions in the common subset of both
10518 architectures plus some special AIX common-mode calls, and will not use
10519 the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
10520 permits GCC to use any instruction from either architecture and to
10521 allow use of the MQ register; specify this for the Motorola MPC601.
10523 @item -mnew-mnemonics
10524 @itemx -mold-mnemonics
10525 @opindex mnew-mnemonics
10526 @opindex mold-mnemonics
10527 Select which mnemonics to use in the generated assembler code. With
10528 @option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
10529 the PowerPC architecture. With @option{-mold-mnemonics} it uses the
10530 assembler mnemonics defined for the POWER architecture. Instructions
10531 defined in only one architecture have only one mnemonic; GCC uses that
10532 mnemonic irrespective of which of these options is specified.
10534 GCC defaults to the mnemonics appropriate for the architecture in
10535 use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
10536 value of these option. Unless you are building a cross-compiler, you
10537 should normally not specify either @option{-mnew-mnemonics} or
10538 @option{-mold-mnemonics}, but should instead accept the default.
10540 @item -mcpu=@var{cpu_type}
10542 Set architecture type, register usage, choice of mnemonics, and
10543 instruction scheduling parameters for machine type @var{cpu_type}.
10544 Supported values for @var{cpu_type} are @samp{401}, @samp{403},
10545 @samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{505},
10546 @samp{601}, @samp{602}, @samp{603}, @samp{603e}, @samp{604},
10547 @samp{604e}, @samp{620}, @samp{630}, @samp{740}, @samp{7400},
10548 @samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
10549 @samp{860}, @samp{970}, @samp{8540}, @samp{common}, @samp{ec603e}, @samp{G3},
10550 @samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3},
10551 @samp{power4}, @samp{power5}, @samp{powerpc}, @samp{powerpc64},
10552 @samp{rios}, @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64a}.
10554 @option{-mcpu=common} selects a completely generic processor. Code
10555 generated under this option will run on any POWER or PowerPC processor.
10556 GCC will use only the instructions in the common subset of both
10557 architectures, and will not use the MQ register. GCC assumes a generic
10558 processor model for scheduling purposes.
10560 @option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
10561 @option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
10562 PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
10563 types, with an appropriate, generic processor model assumed for
10564 scheduling purposes.
10566 The other options specify a specific processor. Code generated under
10567 those options will run best on that processor, and may not run at all on
10570 The @option{-mcpu} options automatically enable or disable the
10571 following options: @option{-maltivec}, @option{-mhard-float},
10572 @option{-mmfcrf}, @option{-mmultiple}, @option{-mnew-mnemonics},
10573 @option{-mpower}, @option{-mpower2}, @option{-mpowerpc64},
10574 @option{-mpowerpc-gpopt}, @option{-mpowerpc-gfxopt},
10575 @option{-mstring}. The particular options set for any particular CPU
10576 will vary between compiler versions, depending on what setting seems
10577 to produce optimal code for that CPU; it doesn't necessarily reflect
10578 the actual hardware's capabilities. If you wish to set an individual
10579 option to a particular value, you may specify it after the
10580 @option{-mcpu} option, like @samp{-mcpu=970 -mno-altivec}.
10582 On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
10583 not enabled or disabled by the @option{-mcpu} option at present, since
10584 AIX does not have full support for these options. You may still
10585 enable or disable them individually if you're sure it'll work in your
10588 @item -mtune=@var{cpu_type}
10590 Set the instruction scheduling parameters for machine type
10591 @var{cpu_type}, but do not set the architecture type, register usage, or
10592 choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
10593 values for @var{cpu_type} are used for @option{-mtune} as for
10594 @option{-mcpu}. If both are specified, the code generated will use the
10595 architecture, registers, and mnemonics set by @option{-mcpu}, but the
10596 scheduling parameters set by @option{-mtune}.
10599 @itemx -mno-altivec
10601 @opindex mno-altivec
10602 Generate code that uses (does not use) AltiVec instructions, and also
10603 enable the use of built-in functions that allow more direct access to
10604 the AltiVec instruction set. You may also need to set
10605 @option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
10610 Extend the current ABI with SPE ABI extensions. This does not change
10611 the default ABI, instead it adds the SPE ABI extensions to the current
10615 @opindex mabi=no-spe
10616 Disable Booke SPE ABI extensions for the current ABI@.
10618 @item -misel=@var{yes/no}
10621 This switch enables or disables the generation of ISEL instructions.
10623 @item -mspe=@var{yes/no}
10626 This switch enables or disables the generation of SPE simd
10629 @item -mfloat-gprs=@var{yes/single/double/no}
10630 @itemx -mfloat-gprs
10631 @opindex mfloat-gprs
10632 This switch enables or disables the generation of floating point
10633 operations on the general purpose registers for architectures that
10636 The argument @var{yes} or @var{single} enables the use of
10637 single-precision floating point operations.
10639 The argument @var{double} enables the use of single and
10640 double-precision floating point operations.
10642 The argument @var{no} disables floating point operations on the
10643 general purpose registers.
10645 This option is currently only available on the MPC854x.
10651 Generate code for 32-bit or 64-bit environments of Darwin and SVR4
10652 targets (including GNU/Linux). The 32-bit environment sets int, long
10653 and pointer to 32 bits and generates code that runs on any PowerPC
10654 variant. The 64-bit environment sets int to 32 bits and long and
10655 pointer to 64 bits, and generates code for PowerPC64, as for
10656 @option{-mpowerpc64}.
10659 @itemx -mno-fp-in-toc
10660 @itemx -mno-sum-in-toc
10661 @itemx -mminimal-toc
10663 @opindex mno-fp-in-toc
10664 @opindex mno-sum-in-toc
10665 @opindex mminimal-toc
10666 Modify generation of the TOC (Table Of Contents), which is created for
10667 every executable file. The @option{-mfull-toc} option is selected by
10668 default. In that case, GCC will allocate at least one TOC entry for
10669 each unique non-automatic variable reference in your program. GCC
10670 will also place floating-point constants in the TOC@. However, only
10671 16,384 entries are available in the TOC@.
10673 If you receive a linker error message that saying you have overflowed
10674 the available TOC space, you can reduce the amount of TOC space used
10675 with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
10676 @option{-mno-fp-in-toc} prevents GCC from putting floating-point
10677 constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
10678 generate code to calculate the sum of an address and a constant at
10679 run-time instead of putting that sum into the TOC@. You may specify one
10680 or both of these options. Each causes GCC to produce very slightly
10681 slower and larger code at the expense of conserving TOC space.
10683 If you still run out of space in the TOC even when you specify both of
10684 these options, specify @option{-mminimal-toc} instead. This option causes
10685 GCC to make only one TOC entry for every file. When you specify this
10686 option, GCC will produce code that is slower and larger but which
10687 uses extremely little TOC space. You may wish to use this option
10688 only on files that contain less frequently executed code.
10694 Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
10695 @code{long} type, and the infrastructure needed to support them.
10696 Specifying @option{-maix64} implies @option{-mpowerpc64} and
10697 @option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
10698 implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
10701 @itemx -mno-xl-compat
10702 @opindex mxl-compat
10703 @opindex mno-xl-compat
10704 Produce code that conforms more closely to IBM XLC semantics when using
10705 AIX-compatible ABI. Pass floating-point arguments to prototyped
10706 functions beyond the register save area (RSA) on the stack in addition
10707 to argument FPRs. Do not assume that most significant double in 128
10708 bit long double value is properly rounded when comparing values.
10710 The AIX calling convention was extended but not initially documented to
10711 handle an obscure K&R C case of calling a function that takes the
10712 address of its arguments with fewer arguments than declared. AIX XL
10713 compilers access floating point arguments which do not fit in the
10714 RSA from the stack when a subroutine is compiled without
10715 optimization. Because always storing floating-point arguments on the
10716 stack is inefficient and rarely needed, this option is not enabled by
10717 default and only is necessary when calling subroutines compiled by AIX
10718 XL compilers without optimization.
10722 Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
10723 application written to use message passing with special startup code to
10724 enable the application to run. The system must have PE installed in the
10725 standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
10726 must be overridden with the @option{-specs=} option to specify the
10727 appropriate directory location. The Parallel Environment does not
10728 support threads, so the @option{-mpe} option and the @option{-pthread}
10729 option are incompatible.
10731 @item -malign-natural
10732 @itemx -malign-power
10733 @opindex malign-natural
10734 @opindex malign-power
10735 On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
10736 @option{-malign-natural} overrides the ABI-defined alignment of larger
10737 types, such as floating-point doubles, on their natural size-based boundary.
10738 The option @option{-malign-power} instructs GCC to follow the ABI-specified
10739 alignment rules. GCC defaults to the standard alignment defined in the ABI@.
10741 On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
10745 @itemx -mhard-float
10746 @opindex msoft-float
10747 @opindex mhard-float
10748 Generate code that does not use (uses) the floating-point register set.
10749 Software floating point emulation is provided if you use the
10750 @option{-msoft-float} option, and pass the option to GCC when linking.
10753 @itemx -mno-multiple
10755 @opindex mno-multiple
10756 Generate code that uses (does not use) the load multiple word
10757 instructions and the store multiple word instructions. These
10758 instructions are generated by default on POWER systems, and not
10759 generated on PowerPC systems. Do not use @option{-mmultiple} on little
10760 endian PowerPC systems, since those instructions do not work when the
10761 processor is in little endian mode. The exceptions are PPC740 and
10762 PPC750 which permit the instructions usage in little endian mode.
10767 @opindex mno-string
10768 Generate code that uses (does not use) the load string instructions
10769 and the store string word instructions to save multiple registers and
10770 do small block moves. These instructions are generated by default on
10771 POWER systems, and not generated on PowerPC systems. Do not use
10772 @option{-mstring} on little endian PowerPC systems, since those
10773 instructions do not work when the processor is in little endian mode.
10774 The exceptions are PPC740 and PPC750 which permit the instructions
10775 usage in little endian mode.
10780 @opindex mno-update
10781 Generate code that uses (does not use) the load or store instructions
10782 that update the base register to the address of the calculated memory
10783 location. These instructions are generated by default. If you use
10784 @option{-mno-update}, there is a small window between the time that the
10785 stack pointer is updated and the address of the previous frame is
10786 stored, which means code that walks the stack frame across interrupts or
10787 signals may get corrupted data.
10790 @itemx -mno-fused-madd
10791 @opindex mfused-madd
10792 @opindex mno-fused-madd
10793 Generate code that uses (does not use) the floating point multiply and
10794 accumulate instructions. These instructions are generated by default if
10795 hardware floating is used.
10797 @item -mno-bit-align
10799 @opindex mno-bit-align
10800 @opindex mbit-align
10801 On System V.4 and embedded PowerPC systems do not (do) force structures
10802 and unions that contain bit-fields to be aligned to the base type of the
10805 For example, by default a structure containing nothing but 8
10806 @code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
10807 boundary and have a size of 4 bytes. By using @option{-mno-bit-align},
10808 the structure would be aligned to a 1 byte boundary and be one byte in
10811 @item -mno-strict-align
10812 @itemx -mstrict-align
10813 @opindex mno-strict-align
10814 @opindex mstrict-align
10815 On System V.4 and embedded PowerPC systems do not (do) assume that
10816 unaligned memory references will be handled by the system.
10818 @item -mrelocatable
10819 @itemx -mno-relocatable
10820 @opindex mrelocatable
10821 @opindex mno-relocatable
10822 On embedded PowerPC systems generate code that allows (does not allow)
10823 the program to be relocated to a different address at runtime. If you
10824 use @option{-mrelocatable} on any module, all objects linked together must
10825 be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
10827 @item -mrelocatable-lib
10828 @itemx -mno-relocatable-lib
10829 @opindex mrelocatable-lib
10830 @opindex mno-relocatable-lib
10831 On embedded PowerPC systems generate code that allows (does not allow)
10832 the program to be relocated to a different address at runtime. Modules
10833 compiled with @option{-mrelocatable-lib} can be linked with either modules
10834 compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
10835 with modules compiled with the @option{-mrelocatable} options.
10841 On System V.4 and embedded PowerPC systems do not (do) assume that
10842 register 2 contains a pointer to a global area pointing to the addresses
10843 used in the program.
10846 @itemx -mlittle-endian
10848 @opindex mlittle-endian
10849 On System V.4 and embedded PowerPC systems compile code for the
10850 processor in little endian mode. The @option{-mlittle-endian} option is
10851 the same as @option{-mlittle}.
10854 @itemx -mbig-endian
10856 @opindex mbig-endian
10857 On System V.4 and embedded PowerPC systems compile code for the
10858 processor in big endian mode. The @option{-mbig-endian} option is
10859 the same as @option{-mbig}.
10861 @item -mdynamic-no-pic
10862 @opindex mdynamic-no-pic
10863 On Darwin and Mac OS X systems, compile code so that it is not
10864 relocatable, but that its external references are relocatable. The
10865 resulting code is suitable for applications, but not shared
10868 @item -mprioritize-restricted-insns=@var{priority}
10869 @opindex mprioritize-restricted-insns
10870 This option controls the priority that is assigned to
10871 dispatch-slot restricted instructions during the second scheduling
10872 pass. The argument @var{priority} takes the value @var{0/1/2} to assign
10873 @var{no/highest/second-highest} priority to dispatch slot restricted
10876 @item -msched-costly-dep=@var{dependence_type}
10877 @opindex msched-costly-dep
10878 This option controls which dependences are considered costly
10879 by the target during instruction scheduling. The argument
10880 @var{dependence_type} takes one of the following values:
10881 @var{no}: no dependence is costly,
10882 @var{all}: all dependences are costly,
10883 @var{true_store_to_load}: a true dependence from store to load is costly,
10884 @var{store_to_load}: any dependence from store to load is costly,
10885 @var{number}: any dependence which latency >= @var{number} is costly.
10887 @item -minsert-sched-nops=@var{scheme}
10888 @opindex minsert-sched-nops
10889 This option controls which nop insertion scheme will be used during
10890 the second scheduling pass. The argument @var{scheme} takes one of the
10892 @var{no}: Don't insert nops.
10893 @var{pad}: Pad with nops any dispatch group which has vacant issue slots,
10894 according to the scheduler's grouping.
10895 @var{regroup_exact}: Insert nops to force costly dependent insns into
10896 separate groups. Insert exactly as many nops as needed to force an insn
10897 to a new group, according to the estimated processor grouping.
10898 @var{number}: Insert nops to force costly dependent insns into
10899 separate groups. Insert @var{number} nops to force an insn to a new group.
10902 @opindex mcall-sysv
10903 On System V.4 and embedded PowerPC systems compile code using calling
10904 conventions that adheres to the March 1995 draft of the System V
10905 Application Binary Interface, PowerPC processor supplement. This is the
10906 default unless you configured GCC using @samp{powerpc-*-eabiaix}.
10908 @item -mcall-sysv-eabi
10909 @opindex mcall-sysv-eabi
10910 Specify both @option{-mcall-sysv} and @option{-meabi} options.
10912 @item -mcall-sysv-noeabi
10913 @opindex mcall-sysv-noeabi
10914 Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
10916 @item -mcall-solaris
10917 @opindex mcall-solaris
10918 On System V.4 and embedded PowerPC systems compile code for the Solaris
10922 @opindex mcall-linux
10923 On System V.4 and embedded PowerPC systems compile code for the
10924 Linux-based GNU system.
10928 On System V.4 and embedded PowerPC systems compile code for the
10929 Hurd-based GNU system.
10931 @item -mcall-netbsd
10932 @opindex mcall-netbsd
10933 On System V.4 and embedded PowerPC systems compile code for the
10934 NetBSD operating system.
10936 @item -maix-struct-return
10937 @opindex maix-struct-return
10938 Return all structures in memory (as specified by the AIX ABI)@.
10940 @item -msvr4-struct-return
10941 @opindex msvr4-struct-return
10942 Return structures smaller than 8 bytes in registers (as specified by the
10945 @item -mabi=altivec
10946 @opindex mabi=altivec
10947 Extend the current ABI with AltiVec ABI extensions. This does not
10948 change the default ABI, instead it adds the AltiVec ABI extensions to
10951 @item -mabi=no-altivec
10952 @opindex mabi=no-altivec
10953 Disable AltiVec ABI extensions for the current ABI@.
10956 @itemx -mno-prototype
10957 @opindex mprototype
10958 @opindex mno-prototype
10959 On System V.4 and embedded PowerPC systems assume that all calls to
10960 variable argument functions are properly prototyped. Otherwise, the
10961 compiler must insert an instruction before every non prototyped call to
10962 set or clear bit 6 of the condition code register (@var{CR}) to
10963 indicate whether floating point values were passed in the floating point
10964 registers in case the function takes a variable arguments. With
10965 @option{-mprototype}, only calls to prototyped variable argument functions
10966 will set or clear the bit.
10970 On embedded PowerPC systems, assume that the startup module is called
10971 @file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
10972 @file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
10977 On embedded PowerPC systems, assume that the startup module is called
10978 @file{crt0.o} and the standard C libraries are @file{libmvme.a} and
10983 On embedded PowerPC systems, assume that the startup module is called
10984 @file{crt0.o} and the standard C libraries are @file{libads.a} and
10987 @item -myellowknife
10988 @opindex myellowknife
10989 On embedded PowerPC systems, assume that the startup module is called
10990 @file{crt0.o} and the standard C libraries are @file{libyk.a} and
10995 On System V.4 and embedded PowerPC systems, specify that you are
10996 compiling for a VxWorks system.
11000 Specify that you are compiling for the WindISS simulation environment.
11004 On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
11005 header to indicate that @samp{eabi} extended relocations are used.
11011 On System V.4 and embedded PowerPC systems do (do not) adhere to the
11012 Embedded Applications Binary Interface (eabi) which is a set of
11013 modifications to the System V.4 specifications. Selecting @option{-meabi}
11014 means that the stack is aligned to an 8 byte boundary, a function
11015 @code{__eabi} is called to from @code{main} to set up the eabi
11016 environment, and the @option{-msdata} option can use both @code{r2} and
11017 @code{r13} to point to two separate small data areas. Selecting
11018 @option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
11019 do not call an initialization function from @code{main}, and the
11020 @option{-msdata} option will only use @code{r13} to point to a single
11021 small data area. The @option{-meabi} option is on by default if you
11022 configured GCC using one of the @samp{powerpc*-*-eabi*} options.
11025 @opindex msdata=eabi
11026 On System V.4 and embedded PowerPC systems, put small initialized
11027 @code{const} global and static data in the @samp{.sdata2} section, which
11028 is pointed to by register @code{r2}. Put small initialized
11029 non-@code{const} global and static data in the @samp{.sdata} section,
11030 which is pointed to by register @code{r13}. Put small uninitialized
11031 global and static data in the @samp{.sbss} section, which is adjacent to
11032 the @samp{.sdata} section. The @option{-msdata=eabi} option is
11033 incompatible with the @option{-mrelocatable} option. The
11034 @option{-msdata=eabi} option also sets the @option{-memb} option.
11037 @opindex msdata=sysv
11038 On System V.4 and embedded PowerPC systems, put small global and static
11039 data in the @samp{.sdata} section, which is pointed to by register
11040 @code{r13}. Put small uninitialized global and static data in the
11041 @samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
11042 The @option{-msdata=sysv} option is incompatible with the
11043 @option{-mrelocatable} option.
11045 @item -msdata=default
11047 @opindex msdata=default
11049 On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
11050 compile code the same as @option{-msdata=eabi}, otherwise compile code the
11051 same as @option{-msdata=sysv}.
11054 @opindex msdata-data
11055 On System V.4 and embedded PowerPC systems, put small global and static
11056 data in the @samp{.sdata} section. Put small uninitialized global and
11057 static data in the @samp{.sbss} section. Do not use register @code{r13}
11058 to address small data however. This is the default behavior unless
11059 other @option{-msdata} options are used.
11063 @opindex msdata=none
11065 On embedded PowerPC systems, put all initialized global and static data
11066 in the @samp{.data} section, and all uninitialized data in the
11067 @samp{.bss} section.
11071 @cindex smaller data references (PowerPC)
11072 @cindex .sdata/.sdata2 references (PowerPC)
11073 On embedded PowerPC systems, put global and static items less than or
11074 equal to @var{num} bytes into the small data or bss sections instead of
11075 the normal data or bss section. By default, @var{num} is 8. The
11076 @option{-G @var{num}} switch is also passed to the linker.
11077 All modules should be compiled with the same @option{-G @var{num}} value.
11080 @itemx -mno-regnames
11082 @opindex mno-regnames
11083 On System V.4 and embedded PowerPC systems do (do not) emit register
11084 names in the assembly language output using symbolic forms.
11087 @itemx -mno-longcall
11089 @opindex mno-longcall
11090 Default to making all function calls indirectly, using a register, so
11091 that functions which reside further than 32 megabytes (33,554,432
11092 bytes) from the current location can be called. This setting can be
11093 overridden by the @code{shortcall} function attribute, or by
11094 @code{#pragma longcall(0)}.
11096 Some linkers are capable of detecting out-of-range calls and generating
11097 glue code on the fly. On these systems, long calls are unnecessary and
11098 generate slower code. As of this writing, the AIX linker can do this,
11099 as can the GNU linker for PowerPC/64. It is planned to add this feature
11100 to the GNU linker for 32-bit PowerPC systems as well.
11102 On Darwin/PPC systems, @code{#pragma longcall} will generate ``jbsr
11103 callee, L42'', plus a ``branch island'' (glue code). The two target
11104 addresses represent the callee and the ``branch island''. The
11105 Darwin/PPC linker will prefer the first address and generate a ``bl
11106 callee'' if the PPC ``bl'' instruction will reach the callee directly;
11107 otherwise, the linker will generate ``bl L42'' to call the ``branch
11108 island''. The ``branch island'' is appended to the body of the
11109 calling function; it computes the full 32-bit address of the callee
11112 On Mach-O (Darwin) systems, this option directs the compiler emit to
11113 the glue for every direct call, and the Darwin linker decides whether
11114 to use or discard it.
11116 In the future, we may cause GCC to ignore all longcall specifications
11117 when the linker is known to generate glue.
11121 Adds support for multithreading with the @dfn{pthreads} library.
11122 This option sets flags for both the preprocessor and linker.
11126 @node S/390 and zSeries Options
11127 @subsection S/390 and zSeries Options
11128 @cindex S/390 and zSeries Options
11130 These are the @samp{-m} options defined for the S/390 and zSeries architecture.
11134 @itemx -msoft-float
11135 @opindex mhard-float
11136 @opindex msoft-float
11137 Use (do not use) the hardware floating-point instructions and registers
11138 for floating-point operations. When @option{-msoft-float} is specified,
11139 functions in @file{libgcc.a} will be used to perform floating-point
11140 operations. When @option{-mhard-float} is specified, the compiler
11141 generates IEEE floating-point instructions. This is the default.
11144 @itemx -mno-backchain
11145 @opindex mbackchain
11146 @opindex mno-backchain
11147 Store (do not store) the address of the caller's frame as backchain pointer
11148 into the callee's stack frame.
11149 A backchain may be needed to allow debugging using tools that do not understand
11150 DWARF-2 call frame information.
11151 When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
11152 at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
11153 the backchain is placed into the topmost word of the 96/160 byte register
11156 In general, code compiled with @option{-mbackchain} is call-compatible with
11157 code compiled with @option{-mmo-backchain}; however, use of the backchain
11158 for debugging purposes usually requires that the whole binary is built with
11159 @option{-mbackchain}. Note that the combination of @option{-mbackchain},
11160 @option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
11161 to build a linux kernel use @option{-msoft-float}.
11163 The default is to not maintain the backchain.
11165 @item -mpacked-stack
11166 @item -mno-packed-stack
11167 @opindex mpacked-stack
11168 @opindex mno-packed-stack
11169 Use (do not use) the packed stack layout. When @option{-mno-packed-stack} is
11170 specified, the compiler uses the all fields of the 96/160 byte register save
11171 area only for their default purpose; unused fields still take up stack space.
11172 When @option{-mpacked-stack} is specified, register save slots are densely
11173 packed at the top of the register save area; unused space is reused for other
11174 purposes, allowing for more efficient use of the available stack space.
11175 However, when @option{-mbackchain} is also in effect, the topmost word of
11176 the save area is always used to store the backchain, and the return address
11177 register is always saved two words below the backchain.
11179 As long as the stack frame backchain is not used, code generated with
11180 @option{-mpacked-stack} is call-compatible with code generated with
11181 @option{-mno-packed-stack}. Note that some non-FSF releases of GCC 2.95 for
11182 S/390 or zSeries generated code that uses the stack frame backchain at run
11183 time, not just for debugging purposes. Such code is not call-compatible
11184 with code compiled with @option{-mpacked-stack}. Also, note that the
11185 combination of @option{-mbackchain},
11186 @option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
11187 to build a linux kernel use @option{-msoft-float}.
11189 The default is to not use the packed stack layout.
11192 @itemx -mno-small-exec
11193 @opindex msmall-exec
11194 @opindex mno-small-exec
11195 Generate (or do not generate) code using the @code{bras} instruction
11196 to do subroutine calls.
11197 This only works reliably if the total executable size does not
11198 exceed 64k. The default is to use the @code{basr} instruction instead,
11199 which does not have this limitation.
11205 When @option{-m31} is specified, generate code compliant to the
11206 GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate
11207 code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in
11208 particular to generate 64-bit instructions. For the @samp{s390}
11209 targets, the default is @option{-m31}, while the @samp{s390x}
11210 targets default to @option{-m64}.
11216 When @option{-mzarch} is specified, generate code using the
11217 instructions available on z/Architecture.
11218 When @option{-mesa} is specified, generate code using the
11219 instructions available on ESA/390. Note that @option{-mesa} is
11220 not possible with @option{-m64}.
11221 When generating code compliant to the GNU/Linux for S/390 ABI,
11222 the default is @option{-mesa}. When generating code compliant
11223 to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
11229 Generate (or do not generate) code using the @code{mvcle} instruction
11230 to perform block moves. When @option{-mno-mvcle} is specified,
11231 use a @code{mvc} loop instead. This is the default.
11237 Print (or do not print) additional debug information when compiling.
11238 The default is to not print debug information.
11240 @item -march=@var{cpu-type}
11242 Generate code that will run on @var{cpu-type}, which is the name of a system
11243 representing a certain processor type. Possible values for
11244 @var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, and @samp{z990}.
11245 When generating code using the instructions available on z/Architecture,
11246 the default is @option{-march=z900}. Otherwise, the default is
11247 @option{-march=g5}.
11249 @item -mtune=@var{cpu-type}
11251 Tune to @var{cpu-type} everything applicable about the generated code,
11252 except for the ABI and the set of available instructions.
11253 The list of @var{cpu-type} values is the same as for @option{-march}.
11254 The default is the value used for @option{-march}.
11257 @itemx -mno-tpf-trace
11258 @opindex mtpf-trace
11259 @opindex mno-tpf-trace
11260 Generate code that adds (does not add) in TPF OS specific branches to trace
11261 routines in the operating system. This option is off by default, even
11262 when compiling for the TPF OS@.
11265 @itemx -mno-fused-madd
11266 @opindex mfused-madd
11267 @opindex mno-fused-madd
11268 Generate code that uses (does not use) the floating point multiply and
11269 accumulate instructions. These instructions are generated by default if
11270 hardware floating point is used.
11272 @item -mwarn-framesize=@var{framesize}
11273 @opindex mwarn-framesize
11274 Emit a warning if the current function exceeds the given frame size. Because
11275 this is a compile time check it doesn't need to be a real problem when the program
11276 runs. It is intended to identify functions which most probably cause
11277 a stack overflow. It is useful to be used in an environment with limited stack
11278 size e.g.@: the linux kernel.
11280 @item -mwarn-dynamicstack
11281 @opindex mwarn-dynamicstack
11282 Emit a warning if the function calls alloca or uses dynamically
11283 sized arrays. This is generally a bad idea with a limited stack size.
11285 @item -mstack-guard=@var{stack-guard}
11286 @item -mstack-size=@var{stack-size}
11287 @opindex mstack-guard
11288 @opindex mstack-size
11289 These arguments always have to be used in conjunction. If they are present the s390
11290 back end emits additional instructions in the function prologue which trigger a trap
11291 if the stack size is @var{stack-guard} bytes above the @var{stack-size}
11292 (remember that the stack on s390 grows downward). These options are intended to
11293 be used to help debugging stack overflow problems. The additionally emitted code
11294 cause only little overhead and hence can also be used in production like systems
11295 without greater performance degradation. The given values have to be exact
11296 powers of 2 and @var{stack-size} has to be greater than @var{stack-guard}.
11297 In order to be efficient the extra code makes the assumption that the stack starts
11298 at an address aligned to the value given by @var{stack-size}.
11302 @subsection SH Options
11304 These @samp{-m} options are defined for the SH implementations:
11309 Generate code for the SH1.
11313 Generate code for the SH2.
11316 Generate code for the SH2e.
11320 Generate code for the SH3.
11324 Generate code for the SH3e.
11328 Generate code for the SH4 without a floating-point unit.
11330 @item -m4-single-only
11331 @opindex m4-single-only
11332 Generate code for the SH4 with a floating-point unit that only
11333 supports single-precision arithmetic.
11337 Generate code for the SH4 assuming the floating-point unit is in
11338 single-precision mode by default.
11342 Generate code for the SH4.
11346 Generate code for the SH4al-dsp, or for a SH4a in such a way that the
11347 floating-point unit is not used.
11349 @item -m4a-single-only
11350 @opindex m4a-single-only
11351 Generate code for the SH4a, in such a way that no double-precision
11352 floating point operations are used.
11355 @opindex m4a-single
11356 Generate code for the SH4a assuming the floating-point unit is in
11357 single-precision mode by default.
11361 Generate code for the SH4a.
11365 Same as @option{-m4a-nofpu}, except that it implicitly passes
11366 @option{-dsp} to the assembler. GCC doesn't generate any DSP
11367 instructions at the moment.
11371 Compile code for the processor in big endian mode.
11375 Compile code for the processor in little endian mode.
11379 Align doubles at 64-bit boundaries. Note that this changes the calling
11380 conventions, and thus some functions from the standard C library will
11381 not work unless you recompile it first with @option{-mdalign}.
11385 Shorten some address references at link time, when possible; uses the
11386 linker option @option{-relax}.
11390 Use 32-bit offsets in @code{switch} tables. The default is to use
11395 Enable the use of the instruction @code{fmovd}.
11399 Comply with the calling conventions defined by Renesas.
11403 Comply with the calling conventions defined by Renesas.
11407 Comply with the calling conventions defined for GCC before the Renesas
11408 conventions were available. This option is the default for all
11409 targets of the SH toolchain except for @samp{sh-symbianelf}.
11412 @opindex mnomacsave
11413 Mark the @code{MAC} register as call-clobbered, even if
11414 @option{-mhitachi} is given.
11418 Increase IEEE-compliance of floating-point code.
11422 Dump instruction size and location in the assembly code.
11425 @opindex mpadstruct
11426 This option is deprecated. It pads structures to multiple of 4 bytes,
11427 which is incompatible with the SH ABI@.
11431 Optimize for space instead of speed. Implied by @option{-Os}.
11434 @opindex mprefergot
11435 When generating position-independent code, emit function calls using
11436 the Global Offset Table instead of the Procedure Linkage Table.
11440 Generate a library function call to invalidate instruction cache
11441 entries, after fixing up a trampoline. This library function call
11442 doesn't assume it can write to the whole memory address space. This
11443 is the default when the target is @code{sh-*-linux*}.
11446 @node SPARC Options
11447 @subsection SPARC Options
11448 @cindex SPARC options
11450 These @samp{-m} options are supported on the SPARC:
11453 @item -mno-app-regs
11455 @opindex mno-app-regs
11457 Specify @option{-mapp-regs} to generate output using the global registers
11458 2 through 4, which the SPARC SVR4 ABI reserves for applications. This
11461 To be fully SVR4 ABI compliant at the cost of some performance loss,
11462 specify @option{-mno-app-regs}. You should compile libraries and system
11463 software with this option.
11466 @itemx -mhard-float
11468 @opindex mhard-float
11469 Generate output containing floating point instructions. This is the
11473 @itemx -msoft-float
11475 @opindex msoft-float
11476 Generate output containing library calls for floating point.
11477 @strong{Warning:} the requisite libraries are not available for all SPARC
11478 targets. Normally the facilities of the machine's usual C compiler are
11479 used, but this cannot be done directly in cross-compilation. You must make
11480 your own arrangements to provide suitable library functions for
11481 cross-compilation. The embedded targets @samp{sparc-*-aout} and
11482 @samp{sparclite-*-*} do provide software floating point support.
11484 @option{-msoft-float} changes the calling convention in the output file;
11485 therefore, it is only useful if you compile @emph{all} of a program with
11486 this option. In particular, you need to compile @file{libgcc.a}, the
11487 library that comes with GCC, with @option{-msoft-float} in order for
11490 @item -mhard-quad-float
11491 @opindex mhard-quad-float
11492 Generate output containing quad-word (long double) floating point
11495 @item -msoft-quad-float
11496 @opindex msoft-quad-float
11497 Generate output containing library calls for quad-word (long double)
11498 floating point instructions. The functions called are those specified
11499 in the SPARC ABI@. This is the default.
11501 As of this writing, there are no SPARC implementations that have hardware
11502 support for the quad-word floating point instructions. They all invoke
11503 a trap handler for one of these instructions, and then the trap handler
11504 emulates the effect of the instruction. Because of the trap handler overhead,
11505 this is much slower than calling the ABI library routines. Thus the
11506 @option{-msoft-quad-float} option is the default.
11508 @item -mno-unaligned-doubles
11509 @itemx -munaligned-doubles
11510 @opindex mno-unaligned-doubles
11511 @opindex munaligned-doubles
11512 Assume that doubles have 8 byte alignment. This is the default.
11514 With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
11515 alignment only if they are contained in another type, or if they have an
11516 absolute address. Otherwise, it assumes they have 4 byte alignment.
11517 Specifying this option avoids some rare compatibility problems with code
11518 generated by other compilers. It is not the default because it results
11519 in a performance loss, especially for floating point code.
11521 @item -mno-faster-structs
11522 @itemx -mfaster-structs
11523 @opindex mno-faster-structs
11524 @opindex mfaster-structs
11525 With @option{-mfaster-structs}, the compiler assumes that structures
11526 should have 8 byte alignment. This enables the use of pairs of
11527 @code{ldd} and @code{std} instructions for copies in structure
11528 assignment, in place of twice as many @code{ld} and @code{st} pairs.
11529 However, the use of this changed alignment directly violates the SPARC
11530 ABI@. Thus, it's intended only for use on targets where the developer
11531 acknowledges that their resulting code will not be directly in line with
11532 the rules of the ABI@.
11534 @item -mimpure-text
11535 @opindex mimpure-text
11536 @option{-mimpure-text}, used in addition to @option{-shared}, tells
11537 the compiler to not pass @option{-z text} to the linker when linking a
11538 shared object. Using this option, you can link position-dependent
11539 code into a shared object.
11541 @option{-mimpure-text} suppresses the ``relocations remain against
11542 allocatable but non-writable sections'' linker error message.
11543 However, the necessary relocations will trigger copy-on-write, and the
11544 shared object is not actually shared across processes. Instead of
11545 using @option{-mimpure-text}, you should compile all source code with
11546 @option{-fpic} or @option{-fPIC}.
11548 This option is only available on SunOS and Solaris.
11550 @item -mcpu=@var{cpu_type}
11552 Set the instruction set, register set, and instruction scheduling parameters
11553 for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
11554 @samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
11555 @samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x},
11556 @samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc}, and
11557 @samp{ultrasparc3}.
11559 Default instruction scheduling parameters are used for values that select
11560 an architecture and not an implementation. These are @samp{v7}, @samp{v8},
11561 @samp{sparclite}, @samp{sparclet}, @samp{v9}.
11563 Here is a list of each supported architecture and their supported
11568 v8: supersparc, hypersparc
11569 sparclite: f930, f934, sparclite86x
11571 v9: ultrasparc, ultrasparc3
11574 By default (unless configured otherwise), GCC generates code for the V7
11575 variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler
11576 additionally optimizes it for the Cypress CY7C602 chip, as used in the
11577 SPARCStation/SPARCServer 3xx series. This is also appropriate for the older
11578 SPARCStation 1, 2, IPX etc.
11580 With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
11581 architecture. The only difference from V7 code is that the compiler emits
11582 the integer multiply and integer divide instructions which exist in SPARC-V8
11583 but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally
11584 optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
11587 With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
11588 the SPARC architecture. This adds the integer multiply, integer divide step
11589 and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
11590 With @option{-mcpu=f930}, the compiler additionally optimizes it for the
11591 Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@. With
11592 @option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
11593 MB86934 chip, which is the more recent SPARClite with FPU@.
11595 With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
11596 the SPARC architecture. This adds the integer multiply, multiply/accumulate,
11597 integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
11598 but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally
11599 optimizes it for the TEMIC SPARClet chip.
11601 With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
11602 architecture. This adds 64-bit integer and floating-point move instructions,
11603 3 additional floating-point condition code registers and conditional move
11604 instructions. With @option{-mcpu=ultrasparc}, the compiler additionally
11605 optimizes it for the Sun UltraSPARC I/II chips. With
11606 @option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
11607 Sun UltraSPARC III chip.
11609 @item -mtune=@var{cpu_type}
11611 Set the instruction scheduling parameters for machine type
11612 @var{cpu_type}, but do not set the instruction set or register set that the
11613 option @option{-mcpu=@var{cpu_type}} would.
11615 The same values for @option{-mcpu=@var{cpu_type}} can be used for
11616 @option{-mtune=@var{cpu_type}}, but the only useful values are those
11617 that select a particular cpu implementation. Those are @samp{cypress},
11618 @samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
11619 @samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc}, and
11620 @samp{ultrasparc3}.
11625 @opindex mno-v8plus
11626 With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@. The
11627 difference from the V8 ABI is that the global and out registers are
11628 considered 64-bit wide. This is enabled by default on Solaris in 32-bit
11629 mode for all SPARC-V9 processors.
11635 With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
11636 Visual Instruction Set extensions. The default is @option{-mno-vis}.
11639 These @samp{-m} options are supported in addition to the above
11640 on SPARC-V9 processors in 64-bit environments:
11643 @item -mlittle-endian
11644 @opindex mlittle-endian
11645 Generate code for a processor running in little-endian mode. It is only
11646 available for a few configurations and most notably not on Solaris and Linux.
11652 Generate code for a 32-bit or 64-bit environment.
11653 The 32-bit environment sets int, long and pointer to 32 bits.
11654 The 64-bit environment sets int to 32 bits and long and pointer
11657 @item -mcmodel=medlow
11658 @opindex mcmodel=medlow
11659 Generate code for the Medium/Low code model: 64-bit addresses, programs
11660 must be linked in the low 32 bits of memory. Programs can be statically
11661 or dynamically linked.
11663 @item -mcmodel=medmid
11664 @opindex mcmodel=medmid
11665 Generate code for the Medium/Middle code model: 64-bit addresses, programs
11666 must be linked in the low 44 bits of memory, the text and data segments must
11667 be less than 2GB in size and the data segment must be located within 2GB of
11670 @item -mcmodel=medany
11671 @opindex mcmodel=medany
11672 Generate code for the Medium/Anywhere code model: 64-bit addresses, programs
11673 may be linked anywhere in memory, the text and data segments must be less
11674 than 2GB in size and the data segment must be located within 2GB of the
11677 @item -mcmodel=embmedany
11678 @opindex mcmodel=embmedany
11679 Generate code for the Medium/Anywhere code model for embedded systems:
11680 64-bit addresses, the text and data segments must be less than 2GB in
11681 size, both starting anywhere in memory (determined at link time). The
11682 global register %g4 points to the base of the data segment. Programs
11683 are statically linked and PIC is not supported.
11686 @itemx -mno-stack-bias
11687 @opindex mstack-bias
11688 @opindex mno-stack-bias
11689 With @option{-mstack-bias}, GCC assumes that the stack pointer, and
11690 frame pointer if present, are offset by @minus{}2047 which must be added back
11691 when making stack frame references. This is the default in 64-bit mode.
11692 Otherwise, assume no such offset is present.
11695 These switches are supported in addition to the above on Solaris:
11700 Add support for multithreading using the Solaris threads library. This
11701 option sets flags for both the preprocessor and linker. This option does
11702 not affect the thread safety of object code produced by the compiler or
11703 that of libraries supplied with it.
11707 Add support for multithreading using the POSIX threads library. This
11708 option sets flags for both the preprocessor and linker. This option does
11709 not affect the thread safety of object code produced by the compiler or
11710 that of libraries supplied with it.
11713 @node System V Options
11714 @subsection Options for System V
11716 These additional options are available on System V Release 4 for
11717 compatibility with other compilers on those systems:
11722 Create a shared object.
11723 It is recommended that @option{-symbolic} or @option{-shared} be used instead.
11727 Identify the versions of each tool used by the compiler, in a
11728 @code{.ident} assembler directive in the output.
11732 Refrain from adding @code{.ident} directives to the output file (this is
11735 @item -YP,@var{dirs}
11737 Search the directories @var{dirs}, and no others, for libraries
11738 specified with @option{-l}.
11740 @item -Ym,@var{dir}
11742 Look in the directory @var{dir} to find the M4 preprocessor.
11743 The assembler uses this option.
11744 @c This is supposed to go with a -Yd for predefined M4 macro files, but
11745 @c the generic assembler that comes with Solaris takes just -Ym.
11748 @node TMS320C3x/C4x Options
11749 @subsection TMS320C3x/C4x Options
11750 @cindex TMS320C3x/C4x Options
11752 These @samp{-m} options are defined for TMS320C3x/C4x implementations:
11756 @item -mcpu=@var{cpu_type}
11758 Set the instruction set, register set, and instruction scheduling
11759 parameters for machine type @var{cpu_type}. Supported values for
11760 @var{cpu_type} are @samp{c30}, @samp{c31}, @samp{c32}, @samp{c40}, and
11761 @samp{c44}. The default is @samp{c40} to generate code for the
11766 @itemx -msmall-memory
11768 @opindex mbig-memory
11770 @opindex msmall-memory
11772 Generates code for the big or small memory model. The small memory
11773 model assumed that all data fits into one 64K word page. At run-time
11774 the data page (DP) register must be set to point to the 64K page
11775 containing the .bss and .data program sections. The big memory model is
11776 the default and requires reloading of the DP register for every direct
11783 Allow (disallow) allocation of general integer operands into the block
11784 count register BK@.
11790 Enable (disable) generation of code using decrement and branch,
11791 DBcond(D), instructions. This is enabled by default for the C4x. To be
11792 on the safe side, this is disabled for the C3x, since the maximum
11793 iteration count on the C3x is @math{2^{23} + 1} (but who iterates loops more than
11794 @math{2^{23}} times on the C3x?). Note that GCC will try to reverse a loop so
11795 that it can utilize the decrement and branch instruction, but will give
11796 up if there is more than one memory reference in the loop. Thus a loop
11797 where the loop counter is decremented can generate slightly more
11798 efficient code, in cases where the RPTB instruction cannot be utilized.
11800 @item -mdp-isr-reload
11802 @opindex mdp-isr-reload
11804 Force the DP register to be saved on entry to an interrupt service
11805 routine (ISR), reloaded to point to the data section, and restored on
11806 exit from the ISR@. This should not be required unless someone has
11807 violated the small memory model by modifying the DP register, say within
11814 For the C3x use the 24-bit MPYI instruction for integer multiplies
11815 instead of a library call to guarantee 32-bit results. Note that if one
11816 of the operands is a constant, then the multiplication will be performed
11817 using shifts and adds. If the @option{-mmpyi} option is not specified for the C3x,
11818 then squaring operations are performed inline instead of a library call.
11821 @itemx -mno-fast-fix
11823 @opindex mno-fast-fix
11824 The C3x/C4x FIX instruction to convert a floating point value to an
11825 integer value chooses the nearest integer less than or equal to the
11826 floating point value rather than to the nearest integer. Thus if the
11827 floating point number is negative, the result will be incorrectly
11828 truncated an additional code is necessary to detect and correct this
11829 case. This option can be used to disable generation of the additional
11830 code required to correct the result.
11836 Enable (disable) generation of repeat block sequences using the RPTB
11837 instruction for zero overhead looping. The RPTB construct is only used
11838 for innermost loops that do not call functions or jump across the loop
11839 boundaries. There is no advantage having nested RPTB loops due to the
11840 overhead required to save and restore the RC, RS, and RE registers.
11841 This is enabled by default with @option{-O2}.
11843 @item -mrpts=@var{count}
11847 Enable (disable) the use of the single instruction repeat instruction
11848 RPTS@. If a repeat block contains a single instruction, and the loop
11849 count can be guaranteed to be less than the value @var{count}, GCC will
11850 emit a RPTS instruction instead of a RPTB@. If no value is specified,
11851 then a RPTS will be emitted even if the loop count cannot be determined
11852 at compile time. Note that the repeated instruction following RPTS does
11853 not have to be reloaded from memory each iteration, thus freeing up the
11854 CPU buses for operands. However, since interrupts are blocked by this
11855 instruction, it is disabled by default.
11857 @item -mloop-unsigned
11858 @itemx -mno-loop-unsigned
11859 @opindex mloop-unsigned
11860 @opindex mno-loop-unsigned
11861 The maximum iteration count when using RPTS and RPTB (and DB on the C40)
11862 is @math{2^{31} + 1} since these instructions test if the iteration count is
11863 negative to terminate the loop. If the iteration count is unsigned
11864 there is a possibility than the @math{2^{31} + 1} maximum iteration count may be
11865 exceeded. This switch allows an unsigned iteration count.
11869 Try to emit an assembler syntax that the TI assembler (asm30) is happy
11870 with. This also enforces compatibility with the API employed by the TI
11871 C3x C compiler. For example, long doubles are passed as structures
11872 rather than in floating point registers.
11878 Generate code that uses registers (stack) for passing arguments to functions.
11879 By default, arguments are passed in registers where possible rather
11880 than by pushing arguments on to the stack.
11882 @item -mparallel-insns
11883 @itemx -mno-parallel-insns
11884 @opindex mparallel-insns
11885 @opindex mno-parallel-insns
11886 Allow the generation of parallel instructions. This is enabled by
11887 default with @option{-O2}.
11889 @item -mparallel-mpy
11890 @itemx -mno-parallel-mpy
11891 @opindex mparallel-mpy
11892 @opindex mno-parallel-mpy
11893 Allow the generation of MPY||ADD and MPY||SUB parallel instructions,
11894 provided @option{-mparallel-insns} is also specified. These instructions have
11895 tight register constraints which can pessimize the code generation
11896 of large functions.
11901 @subsection V850 Options
11902 @cindex V850 Options
11904 These @samp{-m} options are defined for V850 implementations:
11908 @itemx -mno-long-calls
11909 @opindex mlong-calls
11910 @opindex mno-long-calls
11911 Treat all calls as being far away (near). If calls are assumed to be
11912 far away, the compiler will always load the functions address up into a
11913 register, and call indirect through the pointer.
11919 Do not optimize (do optimize) basic blocks that use the same index
11920 pointer 4 or more times to copy pointer into the @code{ep} register, and
11921 use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
11922 option is on by default if you optimize.
11924 @item -mno-prolog-function
11925 @itemx -mprolog-function
11926 @opindex mno-prolog-function
11927 @opindex mprolog-function
11928 Do not use (do use) external functions to save and restore registers
11929 at the prologue and epilogue of a function. The external functions
11930 are slower, but use less code space if more than one function saves
11931 the same number of registers. The @option{-mprolog-function} option
11932 is on by default if you optimize.
11936 Try to make the code as small as possible. At present, this just turns
11937 on the @option{-mep} and @option{-mprolog-function} options.
11939 @item -mtda=@var{n}
11941 Put static or global variables whose size is @var{n} bytes or less into
11942 the tiny data area that register @code{ep} points to. The tiny data
11943 area can hold up to 256 bytes in total (128 bytes for byte references).
11945 @item -msda=@var{n}
11947 Put static or global variables whose size is @var{n} bytes or less into
11948 the small data area that register @code{gp} points to. The small data
11949 area can hold up to 64 kilobytes.
11951 @item -mzda=@var{n}
11953 Put static or global variables whose size is @var{n} bytes or less into
11954 the first 32 kilobytes of memory.
11958 Specify that the target processor is the V850.
11961 @opindex mbig-switch
11962 Generate code suitable for big switch tables. Use this option only if
11963 the assembler/linker complain about out of range branches within a switch
11968 This option will cause r2 and r5 to be used in the code generated by
11969 the compiler. This setting is the default.
11971 @item -mno-app-regs
11972 @opindex mno-app-regs
11973 This option will cause r2 and r5 to be treated as fixed registers.
11977 Specify that the target processor is the V850E1. The preprocessor
11978 constants @samp{__v850e1__} and @samp{__v850e__} will be defined if
11979 this option is used.
11983 Specify that the target processor is the V850E@. The preprocessor
11984 constant @samp{__v850e__} will be defined if this option is used.
11986 If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
11987 are defined then a default target processor will be chosen and the
11988 relevant @samp{__v850*__} preprocessor constant will be defined.
11990 The preprocessor constants @samp{__v850} and @samp{__v851__} are always
11991 defined, regardless of which processor variant is the target.
11993 @item -mdisable-callt
11994 @opindex mdisable-callt
11995 This option will suppress generation of the CALLT instruction for the
11996 v850e and v850e1 flavors of the v850 architecture. The default is
11997 @option{-mno-disable-callt} which allows the CALLT instruction to be used.
12002 @subsection VAX Options
12003 @cindex VAX options
12005 These @samp{-m} options are defined for the VAX:
12010 Do not output certain jump instructions (@code{aobleq} and so on)
12011 that the Unix assembler for the VAX cannot handle across long
12016 Do output those jump instructions, on the assumption that you
12017 will assemble with the GNU assembler.
12021 Output code for g-format floating point numbers instead of d-format.
12024 @node x86-64 Options
12025 @subsection x86-64 Options
12026 @cindex x86-64 options
12028 These are listed under @xref{i386 and x86-64 Options}.
12030 @node Xstormy16 Options
12031 @subsection Xstormy16 Options
12032 @cindex Xstormy16 Options
12034 These options are defined for Xstormy16:
12039 Choose startup files and linker script suitable for the simulator.
12042 @node Xtensa Options
12043 @subsection Xtensa Options
12044 @cindex Xtensa Options
12046 These options are supported for Xtensa targets:
12050 @itemx -mno-const16
12052 @opindex mno-const16
12053 Enable or disable use of @code{CONST16} instructions for loading
12054 constant values. The @code{CONST16} instruction is currently not a
12055 standard option from Tensilica. When enabled, @code{CONST16}
12056 instructions are always used in place of the standard @code{L32R}
12057 instructions. The use of @code{CONST16} is enabled by default only if
12058 the @code{L32R} instruction is not available.
12061 @itemx -mno-fused-madd
12062 @opindex mfused-madd
12063 @opindex mno-fused-madd
12064 Enable or disable use of fused multiply/add and multiply/subtract
12065 instructions in the floating-point option. This has no effect if the
12066 floating-point option is not also enabled. Disabling fused multiply/add
12067 and multiply/subtract instructions forces the compiler to use separate
12068 instructions for the multiply and add/subtract operations. This may be
12069 desirable in some cases where strict IEEE 754-compliant results are
12070 required: the fused multiply add/subtract instructions do not round the
12071 intermediate result, thereby producing results with @emph{more} bits of
12072 precision than specified by the IEEE standard. Disabling fused multiply
12073 add/subtract instructions also ensures that the program output is not
12074 sensitive to the compiler's ability to combine multiply and add/subtract
12077 @item -mtext-section-literals
12078 @itemx -mno-text-section-literals
12079 @opindex mtext-section-literals
12080 @opindex mno-text-section-literals
12081 Control the treatment of literal pools. The default is
12082 @option{-mno-text-section-literals}, which places literals in a separate
12083 section in the output file. This allows the literal pool to be placed
12084 in a data RAM/ROM, and it also allows the linker to combine literal
12085 pools from separate object files to remove redundant literals and
12086 improve code size. With @option{-mtext-section-literals}, the literals
12087 are interspersed in the text section in order to keep them as close as
12088 possible to their references. This may be necessary for large assembly
12091 @item -mtarget-align
12092 @itemx -mno-target-align
12093 @opindex mtarget-align
12094 @opindex mno-target-align
12095 When this option is enabled, GCC instructs the assembler to
12096 automatically align instructions to reduce branch penalties at the
12097 expense of some code density. The assembler attempts to widen density
12098 instructions to align branch targets and the instructions following call
12099 instructions. If there are not enough preceding safe density
12100 instructions to align a target, no widening will be performed. The
12101 default is @option{-mtarget-align}. These options do not affect the
12102 treatment of auto-aligned instructions like @code{LOOP}, which the
12103 assembler will always align, either by widening density instructions or
12104 by inserting no-op instructions.
12107 @itemx -mno-longcalls
12108 @opindex mlongcalls
12109 @opindex mno-longcalls
12110 When this option is enabled, GCC instructs the assembler to translate
12111 direct calls to indirect calls unless it can determine that the target
12112 of a direct call is in the range allowed by the call instruction. This
12113 translation typically occurs for calls to functions in other source
12114 files. Specifically, the assembler translates a direct @code{CALL}
12115 instruction into an @code{L32R} followed by a @code{CALLX} instruction.
12116 The default is @option{-mno-longcalls}. This option should be used in
12117 programs where the call target can potentially be out of range. This
12118 option is implemented in the assembler, not the compiler, so the
12119 assembly code generated by GCC will still show direct call
12120 instructions---look at the disassembled object code to see the actual
12121 instructions. Note that the assembler will use an indirect call for
12122 every cross-file call, not just those that really will be out of range.
12125 @node zSeries Options
12126 @subsection zSeries Options
12127 @cindex zSeries options
12129 These are listed under @xref{S/390 and zSeries Options}.
12131 @node Code Gen Options
12132 @section Options for Code Generation Conventions
12133 @cindex code generation conventions
12134 @cindex options, code generation
12135 @cindex run-time options
12137 These machine-independent options control the interface conventions
12138 used in code generation.
12140 Most of them have both positive and negative forms; the negative form
12141 of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
12142 one of the forms is listed---the one which is not the default. You
12143 can figure out the other form by either removing @samp{no-} or adding
12147 @item -fbounds-check
12148 @opindex fbounds-check
12149 For front-ends that support it, generate additional code to check that
12150 indices used to access arrays are within the declared range. This is
12151 currently only supported by the Java and Fortran 77 front-ends, where
12152 this option defaults to true and false respectively.
12156 This option generates traps for signed overflow on addition, subtraction,
12157 multiplication operations.
12161 This option instructs the compiler to assume that signed arithmetic
12162 overflow of addition, subtraction and multiplication wraps around
12163 using twos-complement representation. This flag enables some optimizations
12164 and disables other. This option is enabled by default for the Java
12165 front-end, as required by the Java language specification.
12168 @opindex fexceptions
12169 Enable exception handling. Generates extra code needed to propagate
12170 exceptions. For some targets, this implies GCC will generate frame
12171 unwind information for all functions, which can produce significant data
12172 size overhead, although it does not affect execution. If you do not
12173 specify this option, GCC will enable it by default for languages like
12174 C++ which normally require exception handling, and disable it for
12175 languages like C that do not normally require it. However, you may need
12176 to enable this option when compiling C code that needs to interoperate
12177 properly with exception handlers written in C++. You may also wish to
12178 disable this option if you are compiling older C++ programs that don't
12179 use exception handling.
12181 @item -fnon-call-exceptions
12182 @opindex fnon-call-exceptions
12183 Generate code that allows trapping instructions to throw exceptions.
12184 Note that this requires platform-specific runtime support that does
12185 not exist everywhere. Moreover, it only allows @emph{trapping}
12186 instructions to throw exceptions, i.e.@: memory references or floating
12187 point instructions. It does not allow exceptions to be thrown from
12188 arbitrary signal handlers such as @code{SIGALRM}.
12190 @item -funwind-tables
12191 @opindex funwind-tables
12192 Similar to @option{-fexceptions}, except that it will just generate any needed
12193 static data, but will not affect the generated code in any other way.
12194 You will normally not enable this option; instead, a language processor
12195 that needs this handling would enable it on your behalf.
12197 @item -fasynchronous-unwind-tables
12198 @opindex fasynchronous-unwind-tables
12199 Generate unwind table in dwarf2 format, if supported by target machine. The
12200 table is exact at each instruction boundary, so it can be used for stack
12201 unwinding from asynchronous events (such as debugger or garbage collector).
12203 @item -fpcc-struct-return
12204 @opindex fpcc-struct-return
12205 Return ``short'' @code{struct} and @code{union} values in memory like
12206 longer ones, rather than in registers. This convention is less
12207 efficient, but it has the advantage of allowing intercallability between
12208 GCC-compiled files and files compiled with other compilers, particularly
12209 the Portable C Compiler (pcc).
12211 The precise convention for returning structures in memory depends
12212 on the target configuration macros.
12214 Short structures and unions are those whose size and alignment match
12215 that of some integer type.
12217 @strong{Warning:} code compiled with the @option{-fpcc-struct-return}
12218 switch is not binary compatible with code compiled with the
12219 @option{-freg-struct-return} switch.
12220 Use it to conform to a non-default application binary interface.
12222 @item -freg-struct-return
12223 @opindex freg-struct-return
12224 Return @code{struct} and @code{union} values in registers when possible.
12225 This is more efficient for small structures than
12226 @option{-fpcc-struct-return}.
12228 If you specify neither @option{-fpcc-struct-return} nor
12229 @option{-freg-struct-return}, GCC defaults to whichever convention is
12230 standard for the target. If there is no standard convention, GCC
12231 defaults to @option{-fpcc-struct-return}, except on targets where GCC is
12232 the principal compiler. In those cases, we can choose the standard, and
12233 we chose the more efficient register return alternative.
12235 @strong{Warning:} code compiled with the @option{-freg-struct-return}
12236 switch is not binary compatible with code compiled with the
12237 @option{-fpcc-struct-return} switch.
12238 Use it to conform to a non-default application binary interface.
12240 @item -fshort-enums
12241 @opindex fshort-enums
12242 Allocate to an @code{enum} type only as many bytes as it needs for the
12243 declared range of possible values. Specifically, the @code{enum} type
12244 will be equivalent to the smallest integer type which has enough room.
12246 @strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
12247 code that is not binary compatible with code generated without that switch.
12248 Use it to conform to a non-default application binary interface.
12250 @item -fshort-double
12251 @opindex fshort-double
12252 Use the same size for @code{double} as for @code{float}.
12254 @strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
12255 code that is not binary compatible with code generated without that switch.
12256 Use it to conform to a non-default application binary interface.
12258 @item -fshort-wchar
12259 @opindex fshort-wchar
12260 Override the underlying type for @samp{wchar_t} to be @samp{short
12261 unsigned int} instead of the default for the target. This option is
12262 useful for building programs to run under WINE@.
12264 @strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
12265 code that is not binary compatible with code generated without that switch.
12266 Use it to conform to a non-default application binary interface.
12268 @item -fshared-data
12269 @opindex fshared-data
12270 Requests that the data and non-@code{const} variables of this
12271 compilation be shared data rather than private data. The distinction
12272 makes sense only on certain operating systems, where shared data is
12273 shared between processes running the same program, while private data
12274 exists in one copy per process.
12277 @opindex fno-common
12278 In C, allocate even uninitialized global variables in the data section of the
12279 object file, rather than generating them as common blocks. This has the
12280 effect that if the same variable is declared (without @code{extern}) in
12281 two different compilations, you will get an error when you link them.
12282 The only reason this might be useful is if you wish to verify that the
12283 program will work on other systems which always work this way.
12287 Ignore the @samp{#ident} directive.
12289 @item -finhibit-size-directive
12290 @opindex finhibit-size-directive
12291 Don't output a @code{.size} assembler directive, or anything else that
12292 would cause trouble if the function is split in the middle, and the
12293 two halves are placed at locations far apart in memory. This option is
12294 used when compiling @file{crtstuff.c}; you should not need to use it
12297 @item -fverbose-asm
12298 @opindex fverbose-asm
12299 Put extra commentary information in the generated assembly code to
12300 make it more readable. This option is generally only of use to those
12301 who actually need to read the generated assembly code (perhaps while
12302 debugging the compiler itself).
12304 @option{-fno-verbose-asm}, the default, causes the
12305 extra information to be omitted and is useful when comparing two assembler
12310 @cindex global offset table
12312 Generate position-independent code (PIC) suitable for use in a shared
12313 library, if supported for the target machine. Such code accesses all
12314 constant addresses through a global offset table (GOT)@. The dynamic
12315 loader resolves the GOT entries when the program starts (the dynamic
12316 loader is not part of GCC; it is part of the operating system). If
12317 the GOT size for the linked executable exceeds a machine-specific
12318 maximum size, you get an error message from the linker indicating that
12319 @option{-fpic} does not work; in that case, recompile with @option{-fPIC}
12320 instead. (These maximums are 8k on the SPARC and 32k
12321 on the m68k and RS/6000. The 386 has no such limit.)
12323 Position-independent code requires special support, and therefore works
12324 only on certain machines. For the 386, GCC supports PIC for System V
12325 but not for the Sun 386i. Code generated for the IBM RS/6000 is always
12326 position-independent.
12330 If supported for the target machine, emit position-independent code,
12331 suitable for dynamic linking and avoiding any limit on the size of the
12332 global offset table. This option makes a difference on the m68k,
12333 PowerPC and SPARC@.
12335 Position-independent code requires special support, and therefore works
12336 only on certain machines.
12342 These options are similar to @option{-fpic} and @option{-fPIC}, but
12343 generated position independent code can be only linked into executables.
12344 Usually these options are used when @option{-pie} GCC option will be
12345 used during linking.
12347 @item -ffixed-@var{reg}
12349 Treat the register named @var{reg} as a fixed register; generated code
12350 should never refer to it (except perhaps as a stack pointer, frame
12351 pointer or in some other fixed role).
12353 @var{reg} must be the name of a register. The register names accepted
12354 are machine-specific and are defined in the @code{REGISTER_NAMES}
12355 macro in the machine description macro file.
12357 This flag does not have a negative form, because it specifies a
12360 @item -fcall-used-@var{reg}
12361 @opindex fcall-used
12362 Treat the register named @var{reg} as an allocable register that is
12363 clobbered by function calls. It may be allocated for temporaries or
12364 variables that do not live across a call. Functions compiled this way
12365 will not save and restore the register @var{reg}.
12367 It is an error to used this flag with the frame pointer or stack pointer.
12368 Use of this flag for other registers that have fixed pervasive roles in
12369 the machine's execution model will produce disastrous results.
12371 This flag does not have a negative form, because it specifies a
12374 @item -fcall-saved-@var{reg}
12375 @opindex fcall-saved
12376 Treat the register named @var{reg} as an allocable register saved by
12377 functions. It may be allocated even for temporaries or variables that
12378 live across a call. Functions compiled this way will save and restore
12379 the register @var{reg} if they use it.
12381 It is an error to used this flag with the frame pointer or stack pointer.
12382 Use of this flag for other registers that have fixed pervasive roles in
12383 the machine's execution model will produce disastrous results.
12385 A different sort of disaster will result from the use of this flag for
12386 a register in which function values may be returned.
12388 This flag does not have a negative form, because it specifies a
12391 @item -fpack-struct[=@var{n}]
12392 @opindex fpack-struct
12393 Without a value specified, pack all structure members together without
12394 holes. When a value is specified (which must be a small power of two), pack
12395 structure members according to this value, representing the maximum
12396 alignment (that is, objects with default alignment requirements larger than
12397 this will be output potentially unaligned at the next fitting location.
12399 @strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
12400 code that is not binary compatible with code generated without that switch.
12401 Additionally, it makes the code suboptimal.
12402 Use it to conform to a non-default application binary interface.
12404 @item -finstrument-functions
12405 @opindex finstrument-functions
12406 Generate instrumentation calls for entry and exit to functions. Just
12407 after function entry and just before function exit, the following
12408 profiling functions will be called with the address of the current
12409 function and its call site. (On some platforms,
12410 @code{__builtin_return_address} does not work beyond the current
12411 function, so the call site information may not be available to the
12412 profiling functions otherwise.)
12415 void __cyg_profile_func_enter (void *this_fn,
12417 void __cyg_profile_func_exit (void *this_fn,
12421 The first argument is the address of the start of the current function,
12422 which may be looked up exactly in the symbol table.
12424 This instrumentation is also done for functions expanded inline in other
12425 functions. The profiling calls will indicate where, conceptually, the
12426 inline function is entered and exited. This means that addressable
12427 versions of such functions must be available. If all your uses of a
12428 function are expanded inline, this may mean an additional expansion of
12429 code size. If you use @samp{extern inline} in your C code, an
12430 addressable version of such functions must be provided. (This is
12431 normally the case anyways, but if you get lucky and the optimizer always
12432 expands the functions inline, you might have gotten away without
12433 providing static copies.)
12435 A function may be given the attribute @code{no_instrument_function}, in
12436 which case this instrumentation will not be done. This can be used, for
12437 example, for the profiling functions listed above, high-priority
12438 interrupt routines, and any functions from which the profiling functions
12439 cannot safely be called (perhaps signal handlers, if the profiling
12440 routines generate output or allocate memory).
12442 @item -fstack-check
12443 @opindex fstack-check
12444 Generate code to verify that you do not go beyond the boundary of the
12445 stack. You should specify this flag if you are running in an
12446 environment with multiple threads, but only rarely need to specify it in
12447 a single-threaded environment since stack overflow is automatically
12448 detected on nearly all systems if there is only one stack.
12450 Note that this switch does not actually cause checking to be done; the
12451 operating system must do that. The switch causes generation of code
12452 to ensure that the operating system sees the stack being extended.
12454 @item -fstack-limit-register=@var{reg}
12455 @itemx -fstack-limit-symbol=@var{sym}
12456 @itemx -fno-stack-limit
12457 @opindex fstack-limit-register
12458 @opindex fstack-limit-symbol
12459 @opindex fno-stack-limit
12460 Generate code to ensure that the stack does not grow beyond a certain value,
12461 either the value of a register or the address of a symbol. If the stack
12462 would grow beyond the value, a signal is raised. For most targets,
12463 the signal is raised before the stack overruns the boundary, so
12464 it is possible to catch the signal without taking special precautions.
12466 For instance, if the stack starts at absolute address @samp{0x80000000}
12467 and grows downwards, you can use the flags
12468 @option{-fstack-limit-symbol=__stack_limit} and
12469 @option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
12470 of 128KB@. Note that this may only work with the GNU linker.
12472 @cindex aliasing of parameters
12473 @cindex parameters, aliased
12474 @item -fargument-alias
12475 @itemx -fargument-noalias
12476 @itemx -fargument-noalias-global
12477 @opindex fargument-alias
12478 @opindex fargument-noalias
12479 @opindex fargument-noalias-global
12480 Specify the possible relationships among parameters and between
12481 parameters and global data.
12483 @option{-fargument-alias} specifies that arguments (parameters) may
12484 alias each other and may alias global storage.@*
12485 @option{-fargument-noalias} specifies that arguments do not alias
12486 each other, but may alias global storage.@*
12487 @option{-fargument-noalias-global} specifies that arguments do not
12488 alias each other and do not alias global storage.
12490 Each language will automatically use whatever option is required by
12491 the language standard. You should not need to use these options yourself.
12493 @item -fleading-underscore
12494 @opindex fleading-underscore
12495 This option and its counterpart, @option{-fno-leading-underscore}, forcibly
12496 change the way C symbols are represented in the object file. One use
12497 is to help link with legacy assembly code.
12499 @strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
12500 generate code that is not binary compatible with code generated without that
12501 switch. Use it to conform to a non-default application binary interface.
12502 Not all targets provide complete support for this switch.
12504 @item -ftls-model=@var{model}
12505 Alter the thread-local storage model to be used (@pxref{Thread-Local}).
12506 The @var{model} argument should be one of @code{global-dynamic},
12507 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
12509 The default without @option{-fpic} is @code{initial-exec}; with
12510 @option{-fpic} the default is @code{global-dynamic}.
12512 @item -fvisibility=@var{default|internal|hidden|protected}
12513 @opindex fvisibility
12514 Set the default ELF image symbol visibility to the specified option---all
12515 symbols will be marked with this unless overridden within the code.
12516 Using this feature can very substantially improve linking and
12517 load times of shared object libraries, produce more optimized
12518 code, provide near-perfect API export and prevent symbol clashes.
12519 It is @strong{strongly} recommended that you use this in any shared objects
12522 Despite the nomenclature, @code{default} always means public ie;
12523 available to be linked against from outside the shared object.
12524 @code{protected} and @code{internal} are pretty useless in real-world
12525 usage so the only other commonly used option will be @code{hidden}.
12526 The default if @option{-fvisibility} isn't specified is
12527 @code{default}, i.e., make every
12528 symbol public---this causes the same behavior as previous versions of
12531 A good explanation of the benefits offered by ensuring ELF
12532 symbols have the correct visibility is given by ``How To Write
12533 Shared Libraries'' by Ulrich Drepper (which can be found at
12534 @w{@uref{http://people.redhat.com/~drepper/}})---however a superior
12535 solution made possible by this option to marking things hidden when
12536 the default is public is to make the default hidden and mark things
12537 public. This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
12538 and @code{__attribute__ ((visibility("default")))} instead of
12539 @code{__declspec(dllexport)} you get almost identical semantics with
12540 identical syntax. This is a great boon to those working with
12541 cross-platform projects.
12543 For those adding visibility support to existing code, you may find
12544 @samp{#pragma GCC visibility} of use. This works by you enclosing
12545 the declarations you wish to set visibility for with (for example)
12546 @samp{#pragma GCC visibility push(hidden)} and
12547 @samp{#pragma GCC visibility pop}. These can be nested up to sixteen
12548 times. Bear in mind that symbol visibility should be viewed @strong{as
12549 part of the API interface contract} and thus all new code should
12550 always specify visibility when it is not the default ie; declarations
12551 only for use within the local DSO should @strong{always} be marked explicitly
12552 as hidden as so to avoid PLT indirection overheads---making this
12553 abundantly clear also aids readability and self-documentation of the code.
12554 Note that due to ISO C++ specification requirements, operator new and
12555 operator delete must always be of default visibility.
12557 An overview of these techniques, their benefits and how to use them
12558 is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
12564 @node Environment Variables
12565 @section Environment Variables Affecting GCC
12566 @cindex environment variables
12568 @c man begin ENVIRONMENT
12569 This section describes several environment variables that affect how GCC
12570 operates. Some of them work by specifying directories or prefixes to use
12571 when searching for various kinds of files. Some are used to specify other
12572 aspects of the compilation environment.
12574 Note that you can also specify places to search using options such as
12575 @option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
12576 take precedence over places specified using environment variables, which
12577 in turn take precedence over those specified by the configuration of GCC@.
12578 @xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
12579 GNU Compiler Collection (GCC) Internals}.
12584 @c @itemx LC_COLLATE
12586 @c @itemx LC_MONETARY
12587 @c @itemx LC_NUMERIC
12592 @c @findex LC_COLLATE
12593 @findex LC_MESSAGES
12594 @c @findex LC_MONETARY
12595 @c @findex LC_NUMERIC
12599 These environment variables control the way that GCC uses
12600 localization information that allow GCC to work with different
12601 national conventions. GCC inspects the locale categories
12602 @env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
12603 so. These locale categories can be set to any value supported by your
12604 installation. A typical value is @samp{en_GB.UTF-8} for English in the United
12605 Kingdom encoded in UTF-8.
12607 The @env{LC_CTYPE} environment variable specifies character
12608 classification. GCC uses it to determine the character boundaries in
12609 a string; this is needed for some multibyte encodings that contain quote
12610 and escape characters that would otherwise be interpreted as a string
12613 The @env{LC_MESSAGES} environment variable specifies the language to
12614 use in diagnostic messages.
12616 If the @env{LC_ALL} environment variable is set, it overrides the value
12617 of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
12618 and @env{LC_MESSAGES} default to the value of the @env{LANG}
12619 environment variable. If none of these variables are set, GCC
12620 defaults to traditional C English behavior.
12624 If @env{TMPDIR} is set, it specifies the directory to use for temporary
12625 files. GCC uses temporary files to hold the output of one stage of
12626 compilation which is to be used as input to the next stage: for example,
12627 the output of the preprocessor, which is the input to the compiler
12630 @item GCC_EXEC_PREFIX
12631 @findex GCC_EXEC_PREFIX
12632 If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
12633 names of the subprograms executed by the compiler. No slash is added
12634 when this prefix is combined with the name of a subprogram, but you can
12635 specify a prefix that ends with a slash if you wish.
12637 If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
12638 an appropriate prefix to use based on the pathname it was invoked with.
12640 If GCC cannot find the subprogram using the specified prefix, it
12641 tries looking in the usual places for the subprogram.
12643 The default value of @env{GCC_EXEC_PREFIX} is
12644 @file{@var{prefix}/lib/gcc/} where @var{prefix} is the value
12645 of @code{prefix} when you ran the @file{configure} script.
12647 Other prefixes specified with @option{-B} take precedence over this prefix.
12649 This prefix is also used for finding files such as @file{crt0.o} that are
12652 In addition, the prefix is used in an unusual way in finding the
12653 directories to search for header files. For each of the standard
12654 directories whose name normally begins with @samp{/usr/local/lib/gcc}
12655 (more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
12656 replacing that beginning with the specified prefix to produce an
12657 alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
12658 @file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
12659 These alternate directories are searched first; the standard directories
12662 @item COMPILER_PATH
12663 @findex COMPILER_PATH
12664 The value of @env{COMPILER_PATH} is a colon-separated list of
12665 directories, much like @env{PATH}. GCC tries the directories thus
12666 specified when searching for subprograms, if it can't find the
12667 subprograms using @env{GCC_EXEC_PREFIX}.
12670 @findex LIBRARY_PATH
12671 The value of @env{LIBRARY_PATH} is a colon-separated list of
12672 directories, much like @env{PATH}. When configured as a native compiler,
12673 GCC tries the directories thus specified when searching for special
12674 linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking
12675 using GCC also uses these directories when searching for ordinary
12676 libraries for the @option{-l} option (but directories specified with
12677 @option{-L} come first).
12681 @cindex locale definition
12682 This variable is used to pass locale information to the compiler. One way in
12683 which this information is used is to determine the character set to be used
12684 when character literals, string literals and comments are parsed in C and C++.
12685 When the compiler is configured to allow multibyte characters,
12686 the following values for @env{LANG} are recognized:
12690 Recognize JIS characters.
12692 Recognize SJIS characters.
12694 Recognize EUCJP characters.
12697 If @env{LANG} is not defined, or if it has some other value, then the
12698 compiler will use mblen and mbtowc as defined by the default locale to
12699 recognize and translate multibyte characters.
12703 Some additional environments variables affect the behavior of the
12706 @include cppenv.texi
12710 @node Precompiled Headers
12711 @section Using Precompiled Headers
12712 @cindex precompiled headers
12713 @cindex speed of compilation
12715 Often large projects have many header files that are included in every
12716 source file. The time the compiler takes to process these header files
12717 over and over again can account for nearly all of the time required to
12718 build the project. To make builds faster, GCC allows users to
12719 `precompile' a header file; then, if builds can use the precompiled
12720 header file they will be much faster.
12722 @strong{Caution:} There are a few known situations where GCC will
12723 crash when trying to use a precompiled header. If you have trouble
12724 with a precompiled header, you should remove the precompiled header
12725 and compile without it. In addition, please use GCC's on-line
12726 defect-tracking system to report any problems you encounter with
12727 precompiled headers. @xref{Bugs}.
12729 To create a precompiled header file, simply compile it as you would any
12730 other file, if necessary using the @option{-x} option to make the driver
12731 treat it as a C or C++ header file. You will probably want to use a
12732 tool like @command{make} to keep the precompiled header up-to-date when
12733 the headers it contains change.
12735 A precompiled header file will be searched for when @code{#include} is
12736 seen in the compilation. As it searches for the included file
12737 (@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
12738 compiler looks for a precompiled header in each directory just before it
12739 looks for the include file in that directory. The name searched for is
12740 the name specified in the @code{#include} with @samp{.gch} appended. If
12741 the precompiled header file can't be used, it is ignored.
12743 For instance, if you have @code{#include "all.h"}, and you have
12744 @file{all.h.gch} in the same directory as @file{all.h}, then the
12745 precompiled header file will be used if possible, and the original
12746 header will be used otherwise.
12748 Alternatively, you might decide to put the precompiled header file in a
12749 directory and use @option{-I} to ensure that directory is searched
12750 before (or instead of) the directory containing the original header.
12751 Then, if you want to check that the precompiled header file is always
12752 used, you can put a file of the same name as the original header in this
12753 directory containing an @code{#error} command.
12755 This also works with @option{-include}. So yet another way to use
12756 precompiled headers, good for projects not designed with precompiled
12757 header files in mind, is to simply take most of the header files used by
12758 a project, include them from another header file, precompile that header
12759 file, and @option{-include} the precompiled header. If the header files
12760 have guards against multiple inclusion, they will be skipped because
12761 they've already been included (in the precompiled header).
12763 If you need to precompile the same header file for different
12764 languages, targets, or compiler options, you can instead make a
12765 @emph{directory} named like @file{all.h.gch}, and put each precompiled
12766 header in the directory, perhaps using @option{-o}. It doesn't matter
12767 what you call the files in the directory, every precompiled header in
12768 the directory will be considered. The first precompiled header
12769 encountered in the directory that is valid for this compilation will
12770 be used; they're searched in no particular order.
12772 There are many other possibilities, limited only by your imagination,
12773 good sense, and the constraints of your build system.
12775 A precompiled header file can be used only when these conditions apply:
12779 Only one precompiled header can be used in a particular compilation.
12782 A precompiled header can't be used once the first C token is seen. You
12783 can have preprocessor directives before a precompiled header; you can
12784 even include a precompiled header from inside another header, so long as
12785 there are no C tokens before the @code{#include}.
12788 The precompiled header file must be produced for the same language as
12789 the current compilation. You can't use a C precompiled header for a C++
12793 The precompiled header file must be produced by the same compiler
12794 version and configuration as the current compilation is using.
12795 The easiest way to guarantee this is to use the same compiler binary
12796 for creating and using precompiled headers.
12799 Any macros defined before the precompiled header is included must
12800 either be defined in the same way as when the precompiled header was
12801 generated, or must not affect the precompiled header, which usually
12802 means that the they don't appear in the precompiled header at all.
12804 The @option{-D} option is one way to define a macro before a
12805 precompiled header is included; using a @code{#define} can also do it.
12806 There are also some options that define macros implicitly, like
12807 @option{-O} and @option{-Wdeprecated}; the same rule applies to macros
12810 @item If debugging information is output when using the precompiled
12811 header, using @option{-g} or similar, the same kind of debugging information
12812 must have been output when building the precompiled header. However,
12813 a precompiled header built using @option{-g} can be used in a compilation
12814 when no debugging information is being output.
12816 @item The same @option{-m} options must generally be used when building
12817 and using the precompiled header. @xref{Submodel Options},
12818 for any cases where this rule is relaxed.
12820 @item Each of the following options must be the same when building and using
12821 the precompiled header:
12823 @gccoptlist{-fexceptions -funit-at-a-time}
12826 Some other command-line options starting with @option{-f},
12827 @option{-p}, or @option{-O} must be defined in the same way as when
12828 the precompiled header was generated. At present, it's not clear
12829 which options are safe to change and which are not; the safest choice
12830 is to use exactly the same options when generating and using the
12831 precompiled header. The following are known to be safe:
12833 @gccoptlist{-fpreprocessed -pedantic-errors}
12837 For all of these except the last, the compiler will automatically
12838 ignore the precompiled header if the conditions aren't met. If you
12839 find an option combination that doesn't work and doesn't cause the
12840 precompiled header to be ignored, please consider filing a bug report,
12843 If you do use differing options when generating and using the
12844 precompiled header, the actual behavior will be a mixture of the
12845 behavior for the options. For instance, if you use @option{-g} to
12846 generate the precompiled header but not when using it, you may or may
12847 not get debugging information for routines in the precompiled header.
12849 @node Running Protoize
12850 @section Running Protoize
12852 The program @code{protoize} is an optional part of GCC@. You can use
12853 it to add prototypes to a program, thus converting the program to ISO
12854 C in one respect. The companion program @code{unprotoize} does the
12855 reverse: it removes argument types from any prototypes that are found.
12857 When you run these programs, you must specify a set of source files as
12858 command line arguments. The conversion programs start out by compiling
12859 these files to see what functions they define. The information gathered
12860 about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
12862 After scanning comes actual conversion. The specified files are all
12863 eligible to be converted; any files they include (whether sources or
12864 just headers) are eligible as well.
12866 But not all the eligible files are converted. By default,
12867 @code{protoize} and @code{unprotoize} convert only source and header
12868 files in the current directory. You can specify additional directories
12869 whose files should be converted with the @option{-d @var{directory}}
12870 option. You can also specify particular files to exclude with the
12871 @option{-x @var{file}} option. A file is converted if it is eligible, its
12872 directory name matches one of the specified directory names, and its
12873 name within the directory has not been excluded.
12875 Basic conversion with @code{protoize} consists of rewriting most
12876 function definitions and function declarations to specify the types of
12877 the arguments. The only ones not rewritten are those for varargs
12880 @code{protoize} optionally inserts prototype declarations at the
12881 beginning of the source file, to make them available for any calls that
12882 precede the function's definition. Or it can insert prototype
12883 declarations with block scope in the blocks where undeclared functions
12886 Basic conversion with @code{unprotoize} consists of rewriting most
12887 function declarations to remove any argument types, and rewriting
12888 function definitions to the old-style pre-ISO form.
12890 Both conversion programs print a warning for any function declaration or
12891 definition that they can't convert. You can suppress these warnings
12894 The output from @code{protoize} or @code{unprotoize} replaces the
12895 original source file. The original file is renamed to a name ending
12896 with @samp{.save} (for DOS, the saved filename ends in @samp{.sav}
12897 without the original @samp{.c} suffix). If the @samp{.save} (@samp{.sav}
12898 for DOS) file already exists, then the source file is simply discarded.
12900 @code{protoize} and @code{unprotoize} both depend on GCC itself to
12901 scan the program and collect information about the functions it uses.
12902 So neither of these programs will work until GCC is installed.
12904 Here is a table of the options you can use with @code{protoize} and
12905 @code{unprotoize}. Each option works with both programs unless
12909 @item -B @var{directory}
12910 Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
12911 usual directory (normally @file{/usr/local/lib}). This file contains
12912 prototype information about standard system functions. This option
12913 applies only to @code{protoize}.
12915 @item -c @var{compilation-options}
12916 Use @var{compilation-options} as the options when running @command{gcc} to
12917 produce the @samp{.X} files. The special option @option{-aux-info} is
12918 always passed in addition, to tell @command{gcc} to write a @samp{.X} file.
12920 Note that the compilation options must be given as a single argument to
12921 @code{protoize} or @code{unprotoize}. If you want to specify several
12922 @command{gcc} options, you must quote the entire set of compilation options
12923 to make them a single word in the shell.
12925 There are certain @command{gcc} arguments that you cannot use, because they
12926 would produce the wrong kind of output. These include @option{-g},
12927 @option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in
12928 the @var{compilation-options}, they are ignored.
12931 Rename files to end in @samp{.C} (@samp{.cc} for DOS-based file
12932 systems) instead of @samp{.c}. This is convenient if you are converting
12933 a C program to C++. This option applies only to @code{protoize}.
12936 Add explicit global declarations. This means inserting explicit
12937 declarations at the beginning of each source file for each function
12938 that is called in the file and was not declared. These declarations
12939 precede the first function definition that contains a call to an
12940 undeclared function. This option applies only to @code{protoize}.
12942 @item -i @var{string}
12943 Indent old-style parameter declarations with the string @var{string}.
12944 This option applies only to @code{protoize}.
12946 @code{unprotoize} converts prototyped function definitions to old-style
12947 function definitions, where the arguments are declared between the
12948 argument list and the initial @samp{@{}. By default, @code{unprotoize}
12949 uses five spaces as the indentation. If you want to indent with just
12950 one space instead, use @option{-i " "}.
12953 Keep the @samp{.X} files. Normally, they are deleted after conversion
12957 Add explicit local declarations. @code{protoize} with @option{-l} inserts
12958 a prototype declaration for each function in each block which calls the
12959 function without any declaration. This option applies only to
12963 Make no real changes. This mode just prints information about the conversions
12964 that would have been done without @option{-n}.
12967 Make no @samp{.save} files. The original files are simply deleted.
12968 Use this option with caution.
12970 @item -p @var{program}
12971 Use the program @var{program} as the compiler. Normally, the name
12972 @file{gcc} is used.
12975 Work quietly. Most warnings are suppressed.
12978 Print the version number, just like @option{-v} for @command{gcc}.
12981 If you need special compiler options to compile one of your program's
12982 source files, then you should generate that file's @samp{.X} file
12983 specially, by running @command{gcc} on that source file with the
12984 appropriate options and the option @option{-aux-info}. Then run
12985 @code{protoize} on the entire set of files. @code{protoize} will use
12986 the existing @samp{.X} file because it is newer than the source file.
12990 gcc -Dfoo=bar file1.c -aux-info file1.X
12995 You need to include the special files along with the rest in the
12996 @code{protoize} command, even though their @samp{.X} files already
12997 exist, because otherwise they won't get converted.
12999 @xref{Protoize Caveats}, for more information on how to use
13000 @code{protoize} successfully.