1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2 @c 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi.
11 @c man begin COPYRIGHT
12 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
13 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
15 Permission is granted to copy, distribute and/or modify this document
16 under the terms of the GNU Free Documentation License, Version 1.2 or
17 any later version published by the Free Software Foundation; with the
18 Invariant Sections being ``GNU General Public License'' and ``Funding
19 Free Software'', the Front-Cover texts being (a) (see below), and with
20 the Back-Cover Texts being (b) (see below). A copy of the license is
21 included in the gfdl(7) man page.
23 (a) The FSF's Front-Cover Text is:
27 (b) The FSF's Back-Cover Text is:
29 You have freedom to copy and modify this GNU Manual, like GNU
30 software. Copies published by the Free Software Foundation raise
31 funds for GNU development.
33 @c Set file name and title for the man page.
35 @settitle GNU project C and C++ compiler
37 gcc [@option{-c}|@option{-S}|@option{-E}] [@option{-std=}@var{standard}]
38 [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
39 [@option{-W}@var{warn}@dots{}] [@option{-pedantic}]
40 [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
41 [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
42 [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
43 [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}
45 Only the most useful options are listed here; see below for the
46 remainder. @samp{g++} accepts mostly the same options as @samp{gcc}.
49 gpl(7), gfdl(7), fsf-funding(7),
50 cpp(1), gcov(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1)
51 and the Info entries for @file{gcc}, @file{cpp}, @file{as},
52 @file{ld}, @file{binutils} and @file{gdb}.
55 For instructions on reporting bugs, see
56 @w{@uref{http://gcc.gnu.org/bugs.html}}.
59 See the Info entry for @command{gcc}, or
60 @w{@uref{http://gcc.gnu.org/onlinedocs/gcc/Contributors.html}},
61 for contributors to GCC@.
66 @chapter GCC Command Options
67 @cindex GCC command options
68 @cindex command options
69 @cindex options, GCC command
71 @c man begin DESCRIPTION
72 When you invoke GCC, it normally does preprocessing, compilation,
73 assembly and linking. The ``overall options'' allow you to stop this
74 process at an intermediate stage. For example, the @option{-c} option
75 says not to run the linker. Then the output consists of object files
76 output by the assembler.
78 Other options are passed on to one stage of processing. Some options
79 control the preprocessor and others the compiler itself. Yet other
80 options control the assembler and linker; most of these are not
81 documented here, since you rarely need to use any of them.
83 @cindex C compilation options
84 Most of the command line options that you can use with GCC are useful
85 for C programs; when an option is only useful with another language
86 (usually C++), the explanation says so explicitly. If the description
87 for a particular option does not mention a source language, you can use
88 that option with all supported languages.
90 @cindex C++ compilation options
91 @xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
92 options for compiling C++ programs.
94 @cindex grouping options
95 @cindex options, grouping
96 The @command{gcc} program accepts options and file names as operands. Many
97 options have multi-letter names; therefore multiple single-letter options
98 may @emph{not} be grouped: @option{-dr} is very different from @w{@samp{-d
101 @cindex order of options
102 @cindex options, order
103 You can mix options and other arguments. For the most part, the order
104 you use doesn't matter. Order does matter when you use several options
105 of the same kind; for example, if you specify @option{-L} more than once,
106 the directories are searched in the order specified.
108 Many options have long names starting with @samp{-f} or with
109 @samp{-W}---for example,
110 @option{-fmove-loop-invariants}, @option{-Wformat} and so on. Most of
111 these have both positive and negative forms; the negative form of
112 @option{-ffoo} would be @option{-fno-foo}. This manual documents
113 only one of these two forms, whichever one is not the default.
117 @xref{Option Index}, for an index to GCC's options.
120 * Option Summary:: Brief list of all options, without explanations.
121 * Overall Options:: Controlling the kind of output:
122 an executable, object files, assembler files,
123 or preprocessed source.
124 * Invoking G++:: Compiling C++ programs.
125 * C Dialect Options:: Controlling the variant of C language compiled.
126 * C++ Dialect Options:: Variations on C++.
127 * Language Independent Options:: Controlling how diagnostics should be
129 * Warning Options:: How picky should the compiler be?
130 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
131 * Optimize Options:: How much optimization?
132 * Preprocessor Options:: Controlling header files and macro definitions.
133 Also, getting dependency information for Make.
134 * Assembler Options:: Passing options to the assembler.
135 * Link Options:: Specifying libraries and so on.
136 * Directory Options:: Where to find header files and libraries.
137 Where to find the compiler executable files.
138 * Spec Files:: How to pass switches to sub-processes.
139 * Target Options:: Running a cross-compiler, or an old version of GCC.
140 * Submodel Options:: Specifying minor hardware or convention variations,
141 such as 68010 vs 68020.
142 * Code Gen Options:: Specifying conventions for function calls, data layout
144 * Environment Variables:: Env vars that affect GCC.
145 * Precompiled Headers:: Compiling a header once, and using it many times.
146 * Running Protoize:: Automatically adding or removing function prototypes.
152 @section Option Summary
154 Here is a summary of all the options, grouped by type. Explanations are
155 in the following sections.
158 @item Overall Options
159 @xref{Overall Options,,Options Controlling the Kind of Output}.
160 @gccoptlist{-c -S -E -o @var{file} -combine -pipe -pass-exit-codes @gol
161 -x @var{language} -v -### --help --target-help --version @@@var{file}}
163 @item C Language Options
164 @xref{C Dialect Options,,Options Controlling C Dialect}.
165 @gccoptlist{-ansi -std=@var{standard} -fgnu89-inline @gol
166 -aux-info @var{filename} @gol
167 -fno-asm -fno-builtin -fno-builtin-@var{function} @gol
168 -fhosted -ffreestanding -fopenmp -fms-extensions @gol
169 -trigraphs -no-integrated-cpp -traditional -traditional-cpp @gol
170 -fallow-single-precision -fcond-mismatch @gol
171 -fsigned-bitfields -fsigned-char @gol
172 -funsigned-bitfields -funsigned-char}
174 @item C++ Language Options
175 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
176 @gccoptlist{-fabi-version=@var{n} -fno-access-control -fcheck-new @gol
177 -fconserve-space -ffriend-injection @gol
178 -fno-elide-constructors @gol
179 -fno-enforce-eh-specs @gol
180 -ffor-scope -fno-for-scope -fno-gnu-keywords @gol
181 -fno-implicit-templates @gol
182 -fno-implicit-inline-templates @gol
183 -fno-implement-inlines -fms-extensions @gol
184 -fno-nonansi-builtins -fno-operator-names @gol
185 -fno-optional-diags -fpermissive @gol
186 -frepo -fno-rtti -fstats -ftemplate-depth-@var{n} @gol
187 -fno-threadsafe-statics -fuse-cxa-atexit -fno-weak -nostdinc++ @gol
188 -fno-default-inline -fvisibility-inlines-hidden @gol
189 -Wabi -Wctor-dtor-privacy @gol
190 -Wnon-virtual-dtor -Wreorder @gol
191 -Weffc++ -Wno-deprecated -Wstrict-null-sentinel @gol
192 -Wno-non-template-friend -Wold-style-cast @gol
193 -Woverloaded-virtual -Wno-pmf-conversions @gol
196 @item Language Independent Options
197 @xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}.
198 @gccoptlist{-fmessage-length=@var{n} @gol
199 -fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]} @gol
200 -fdiagnostics-show-option}
202 @item Warning Options
203 @xref{Warning Options,,Options to Request or Suppress Warnings}.
204 @gccoptlist{-fsyntax-only -pedantic -pedantic-errors @gol
205 -w -Wextra -Wall -Waddress -Waggregate-return -Wno-attributes @gol
206 -Wc++-compat -Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment @gol
207 -Wconversion -Wno-deprecated-declarations @gol
208 -Wdisabled-optimization -Wno-div-by-zero -Wno-endif-labels @gol
209 -Werror -Werror=* -Werror-implicit-function-declaration @gol
210 -Wfatal-errors -Wfloat-equal -Wformat -Wformat=2 @gol
211 -Wno-format-extra-args -Wformat-nonliteral @gol
212 -Wformat-security -Wformat-y2k @gol
213 -Wimplicit -Wimplicit-function-declaration -Wimplicit-int @gol
214 -Wimport -Wno-import -Winit-self -Winline @gol
215 -Wno-int-to-pointer-cast @gol
216 -Wno-invalid-offsetof -Winvalid-pch @gol
217 -Wlarger-than-@var{len} -Wunsafe-loop-optimizations -Wlong-long @gol
218 -Wmain -Wmissing-braces -Wmissing-field-initializers @gol
219 -Wmissing-format-attribute -Wmissing-include-dirs @gol
220 -Wmissing-noreturn @gol
221 -Wno-multichar -Wnonnull -Wno-overflow @gol
222 -Woverlength-strings -Wpacked -Wpadded @gol
223 -Wparentheses -Wpointer-arith -Wno-pointer-to-int-cast @gol
224 -Wredundant-decls @gol
225 -Wreturn-type -Wsequence-point -Wshadow @gol
226 -Wsign-compare -Wstack-protector @gol
227 -Wstrict-aliasing -Wstrict-aliasing=2 @gol
228 -Wstrict-overflow -Wstrict-overflow=@var{n} @gol
229 -Wswitch -Wswitch-default -Wswitch-enum @gol
230 -Wsystem-headers -Wtrigraphs -Wundef -Wuninitialized @gol
231 -Wunknown-pragmas -Wno-pragmas -Wunreachable-code @gol
232 -Wunused -Wunused-function -Wunused-label -Wunused-parameter @gol
233 -Wunused-value -Wunused-variable @gol
234 -Wvariadic-macros -Wvla @gol
235 -Wvolatile-register-var -Wwrite-strings}
237 @item C-only Warning Options
238 @gccoptlist{-Wbad-function-cast -Wmissing-declarations @gol
239 -Wmissing-prototypes -Wnested-externs -Wold-style-definition @gol
240 -Wstrict-prototypes -Wtraditional @gol
241 -Wdeclaration-after-statement -Wpointer-sign}
243 @item Debugging Options
244 @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
245 @gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
246 -fdump-noaddr -fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} @gol
247 -fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
248 -fdump-ipa-all -fdump-ipa-cgraph @gol
250 -fdump-tree-original@r{[}-@var{n}@r{]} @gol
251 -fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
252 -fdump-tree-inlined@r{[}-@var{n}@r{]} @gol
253 -fdump-tree-cfg -fdump-tree-vcg -fdump-tree-alias @gol
255 -fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol
256 -fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol
257 -fdump-tree-gimple@r{[}-raw@r{]} -fdump-tree-mudflap@r{[}-@var{n}@r{]} @gol
258 -fdump-tree-dom@r{[}-@var{n}@r{]} @gol
259 -fdump-tree-dse@r{[}-@var{n}@r{]} @gol
260 -fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol
261 -fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
262 -fdump-tree-copyrename@r{[}-@var{n}@r{]} @gol
263 -fdump-tree-nrv -fdump-tree-vect @gol
264 -fdump-tree-sink @gol
265 -fdump-tree-sra@r{[}-@var{n}@r{]} @gol
266 -fdump-tree-salias @gol
267 -fdump-tree-fre@r{[}-@var{n}@r{]} @gol
268 -fdump-tree-vrp@r{[}-@var{n}@r{]} @gol
269 -ftree-vectorizer-verbose=@var{n} @gol
270 -fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol
271 -feliminate-dwarf2-dups -feliminate-unused-debug-types @gol
272 -feliminate-unused-debug-symbols -femit-class-debug-always @gol
273 -fmem-report -fprofile-arcs @gol
274 -frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
275 -ftest-coverage -ftime-report -fvar-tracking @gol
276 -g -g@var{level} -gcoff -gdwarf-2 @gol
277 -ggdb -gstabs -gstabs+ -gvms -gxcoff -gxcoff+ @gol
278 -femit-struct-debug-baseonly -femit-struct-debug-reduced @gol
279 -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} @gol
280 -p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol
281 -print-multi-directory -print-multi-lib @gol
282 -print-prog-name=@var{program} -print-search-dirs -Q @gol
285 @item Optimization Options
286 @xref{Optimize Options,,Options that Control Optimization}.
287 @gccoptlist{-falign-functions=@var{n} -falign-jumps=@var{n} @gol
288 -falign-labels=@var{n} -falign-loops=@var{n} @gol
289 -fbounds-check -fmudflap -fmudflapth -fmudflapir @gol
290 -fbranch-probabilities -fprofile-values -fvpt -fbranch-target-load-optimize @gol
291 -fbranch-target-load-optimize2 -fbtr-bb-exclusive @gol
292 -fcaller-saves -fcprop-registers -fcse-follow-jumps @gol
293 -fcse-skip-blocks -fcx-limited-range -fdata-sections @gol
294 -fdelayed-branch -fdelete-null-pointer-checks -fearly-inlining @gol
295 -fexpensive-optimizations -ffast-math -ffloat-store @gol
296 -fforce-addr -ffunction-sections @gol
297 -fgcse -fgcse-lm -fgcse-sm -fgcse-las -fgcse-after-reload @gol
298 -fcrossjumping -fif-conversion -fif-conversion2 @gol
299 -finline-functions -finline-functions-called-once @gol
300 -finline-limit=@var{n} -fkeep-inline-functions @gol
301 -fkeep-static-consts -fmerge-constants -fmerge-all-constants @gol
302 -fmodulo-sched -fno-branch-count-reg @gol
303 -fno-default-inline -fno-defer-pop -fmove-loop-invariants @gol
304 -fno-function-cse -fno-guess-branch-probability @gol
305 -fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol
306 -funsafe-math-optimizations -funsafe-loop-optimizations -ffinite-math-only @gol
307 -fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol
308 -fomit-frame-pointer -foptimize-register-move @gol
309 -foptimize-sibling-calls -fprefetch-loop-arrays @gol
310 -fprofile-generate -fprofile-use @gol
311 -fregmove -frename-registers @gol
312 -freorder-blocks -freorder-blocks-and-partition -freorder-functions @gol
313 -frerun-cse-after-loop @gol
314 -frounding-math -frtl-abstract-sequences @gol
315 -fschedule-insns -fschedule-insns2 @gol
316 -fno-sched-interblock -fno-sched-spec -fsched-spec-load @gol
317 -fsched-spec-load-dangerous @gol
318 -fsched-stalled-insns=@var{n} -fsched-stalled-insns-dep=@var{n} @gol
319 -fsched2-use-superblocks @gol
320 -fsched2-use-traces -fsee -freschedule-modulo-scheduled-loops @gol
321 -fsection-anchors -fsignaling-nans -fsingle-precision-constant @gol
322 -fstack-protector -fstack-protector-all @gol
323 -fstrict-aliasing -fstrict-overflow -ftracer -fthread-jumps @gol
324 -funroll-all-loops -funroll-loops -fpeel-loops @gol
325 -fsplit-ivs-in-unroller -funswitch-loops @gol
326 -fvariable-expansion-in-unroller @gol
327 -ftree-pre -ftree-ccp -ftree-dce -ftree-loop-optimize @gol
328 -ftree-loop-linear -ftree-loop-im -ftree-loop-ivcanon -fivopts @gol
329 -ftree-dominator-opts -ftree-dse -ftree-copyrename -ftree-sink @gol
330 -ftree-ch -ftree-sra -ftree-ter -ftree-lrs -ftree-fre -ftree-vectorize @gol
331 -ftree-vect-loop-version -ftree-salias -fipa-pta -fweb @gol
332 -ftree-copy-prop -ftree-store-ccp -ftree-store-copy-prop -fwhole-program @gol
333 --param @var{name}=@var{value}
334 -O -O0 -O1 -O2 -O3 -Os}
336 @item Preprocessor Options
337 @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
338 @gccoptlist{-A@var{question}=@var{answer} @gol
339 -A-@var{question}@r{[}=@var{answer}@r{]} @gol
340 -C -dD -dI -dM -dN @gol
341 -D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol
342 -idirafter @var{dir} @gol
343 -include @var{file} -imacros @var{file} @gol
344 -iprefix @var{file} -iwithprefix @var{dir} @gol
345 -iwithprefixbefore @var{dir} -isystem @var{dir} @gol
346 -imultilib @var{dir} -isysroot @var{dir} @gol
347 -M -MM -MF -MG -MP -MQ -MT -nostdinc @gol
348 -P -fworking-directory -remap @gol
349 -trigraphs -undef -U@var{macro} -Wp,@var{option} @gol
350 -Xpreprocessor @var{option}}
352 @item Assembler Option
353 @xref{Assembler Options,,Passing Options to the Assembler}.
354 @gccoptlist{-Wa,@var{option} -Xassembler @var{option}}
357 @xref{Link Options,,Options for Linking}.
358 @gccoptlist{@var{object-file-name} -l@var{library} @gol
359 -nostartfiles -nodefaultlibs -nostdlib -pie -rdynamic @gol
360 -s -static -static-libgcc -shared -shared-libgcc -symbolic @gol
361 -Wl,@var{option} -Xlinker @var{option} @gol
364 @item Directory Options
365 @xref{Directory Options,,Options for Directory Search}.
366 @gccoptlist{-B@var{prefix} -I@var{dir} -iquote@var{dir} -L@var{dir}
367 -specs=@var{file} -I- --sysroot=@var{dir}}
370 @c I wrote this xref this way to avoid overfull hbox. -- rms
371 @xref{Target Options}.
372 @gccoptlist{-V @var{version} -b @var{machine}}
374 @item Machine Dependent Options
375 @xref{Submodel Options,,Hardware Models and Configurations}.
376 @c This list is ordered alphanumerically by subsection name.
377 @c Try and put the significant identifier (CPU or system) first,
378 @c so users have a clue at guessing where the ones they want will be.
381 @gccoptlist{-EB -EL @gol
382 -mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text-section} @gol
383 -mdata=@var{data-section} -mrodata=@var{readonly-data-section}}
386 @gccoptlist{-mapcs-frame -mno-apcs-frame @gol
387 -mabi=@var{name} @gol
388 -mapcs-stack-check -mno-apcs-stack-check @gol
389 -mapcs-float -mno-apcs-float @gol
390 -mapcs-reentrant -mno-apcs-reentrant @gol
391 -msched-prolog -mno-sched-prolog @gol
392 -mlittle-endian -mbig-endian -mwords-little-endian @gol
393 -mfloat-abi=@var{name} -msoft-float -mhard-float -mfpe @gol
394 -mthumb-interwork -mno-thumb-interwork @gol
395 -mcpu=@var{name} -march=@var{name} -mfpu=@var{name} @gol
396 -mstructure-size-boundary=@var{n} @gol
397 -mabort-on-noreturn @gol
398 -mlong-calls -mno-long-calls @gol
399 -msingle-pic-base -mno-single-pic-base @gol
400 -mpic-register=@var{reg} @gol
401 -mnop-fun-dllimport @gol
402 -mcirrus-fix-invalid-insns -mno-cirrus-fix-invalid-insns @gol
403 -mpoke-function-name @gol
405 -mtpcs-frame -mtpcs-leaf-frame @gol
406 -mcaller-super-interworking -mcallee-super-interworking @gol
410 @gccoptlist{-mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts @gol
411 -mcall-prologues -mno-tablejump -mtiny-stack -mint8}
413 @emph{Blackfin Options}
414 @gccoptlist{-momit-leaf-frame-pointer -mno-omit-leaf-frame-pointer @gol
415 -mspecld-anomaly -mno-specld-anomaly -mcsync-anomaly -mno-csync-anomaly @gol
416 -mlow-64k -mno-low64k -mid-shared-library @gol
417 -mno-id-shared-library -mshared-library-id=@var{n} @gol
418 -mlong-calls -mno-long-calls}
421 @gccoptlist{-mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol
422 -mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol
423 -metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol
424 -mstack-align -mdata-align -mconst-align @gol
425 -m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol
426 -melf -maout -melinux -mlinux -sim -sim2 @gol
427 -mmul-bug-workaround -mno-mul-bug-workaround}
430 @gccoptlist{-mmac -mpush-args}
432 @emph{Darwin Options}
433 @gccoptlist{-all_load -allowable_client -arch -arch_errors_fatal @gol
434 -arch_only -bind_at_load -bundle -bundle_loader @gol
435 -client_name -compatibility_version -current_version @gol
437 -dependency-file -dylib_file -dylinker_install_name @gol
438 -dynamic -dynamiclib -exported_symbols_list @gol
439 -filelist -flat_namespace -force_cpusubtype_ALL @gol
440 -force_flat_namespace -headerpad_max_install_names @gol
441 -image_base -init -install_name -keep_private_externs @gol
442 -multi_module -multiply_defined -multiply_defined_unused @gol
443 -noall_load -no_dead_strip_inits_and_terms @gol
444 -nofixprebinding -nomultidefs -noprebind -noseglinkedit @gol
445 -pagezero_size -prebind -prebind_all_twolevel_modules @gol
446 -private_bundle -read_only_relocs -sectalign @gol
447 -sectobjectsymbols -whyload -seg1addr @gol
448 -sectcreate -sectobjectsymbols -sectorder @gol
449 -segaddr -segs_read_only_addr -segs_read_write_addr @gol
450 -seg_addr_table -seg_addr_table_filename -seglinkedit @gol
451 -segprot -segs_read_only_addr -segs_read_write_addr @gol
452 -single_module -static -sub_library -sub_umbrella @gol
453 -twolevel_namespace -umbrella -undefined @gol
454 -unexported_symbols_list -weak_reference_mismatches @gol
455 -whatsloaded -F -gused -gfull -mmacosx-version-min=@var{version} @gol
456 -mkernel -mone-byte-bool}
458 @emph{DEC Alpha Options}
459 @gccoptlist{-mno-fp-regs -msoft-float -malpha-as -mgas @gol
460 -mieee -mieee-with-inexact -mieee-conformant @gol
461 -mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} @gol
462 -mtrap-precision=@var{mode} -mbuild-constants @gol
463 -mcpu=@var{cpu-type} -mtune=@var{cpu-type} @gol
464 -mbwx -mmax -mfix -mcix @gol
465 -mfloat-vax -mfloat-ieee @gol
466 -mexplicit-relocs -msmall-data -mlarge-data @gol
467 -msmall-text -mlarge-text @gol
468 -mmemory-latency=@var{time}}
470 @emph{DEC Alpha/VMS Options}
471 @gccoptlist{-mvms-return-codes}
474 @gccoptlist{-mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 @gol
475 -mhard-float -msoft-float @gol
476 -malloc-cc -mfixed-cc -mdword -mno-dword @gol
477 -mdouble -mno-double @gol
478 -mmedia -mno-media -mmuladd -mno-muladd @gol
479 -mfdpic -minline-plt -mgprel-ro -multilib-library-pic @gol
480 -mlinked-fp -mlong-calls -malign-labels @gol
481 -mlibrary-pic -macc-4 -macc-8 @gol
482 -mpack -mno-pack -mno-eflags -mcond-move -mno-cond-move @gol
483 -moptimize-membar -mno-optimize-membar @gol
484 -mscc -mno-scc -mcond-exec -mno-cond-exec @gol
485 -mvliw-branch -mno-vliw-branch @gol
486 -mmulti-cond-exec -mno-multi-cond-exec -mnested-cond-exec @gol
487 -mno-nested-cond-exec -mtomcat-stats @gol
491 @emph{GNU/Linux Options}
492 @gccoptlist{-muclibc}
494 @emph{H8/300 Options}
495 @gccoptlist{-mrelax -mh -ms -mn -mint32 -malign-300}
498 @gccoptlist{-march=@var{architecture-type} @gol
499 -mbig-switch -mdisable-fpregs -mdisable-indexing @gol
500 -mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol
501 -mfixed-range=@var{register-range} @gol
502 -mjump-in-delay -mlinker-opt -mlong-calls @gol
503 -mlong-load-store -mno-big-switch -mno-disable-fpregs @gol
504 -mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol
505 -mno-jump-in-delay -mno-long-load-store @gol
506 -mno-portable-runtime -mno-soft-float @gol
507 -mno-space-regs -msoft-float -mpa-risc-1-0 @gol
508 -mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime @gol
509 -mschedule=@var{cpu-type} -mspace-regs -msio -mwsio @gol
510 -munix=@var{unix-std} -nolibdld -static -threads}
512 @emph{i386 and x86-64 Options}
513 @gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
514 -mfpmath=@var{unit} @gol
515 -masm=@var{dialect} -mno-fancy-math-387 @gol
516 -mno-fp-ret-in-387 -msoft-float -msvr3-shlib @gol
517 -mno-wide-multiply -mrtd -malign-double @gol
518 -mpreferred-stack-boundary=@var{num} @gol
519 -mmmx -msse -msse2 -msse3 -mssse3 -msse4a -m3dnow -mpopcnt -mabm -maes @gol
520 -mthreads -mno-align-stringops -minline-all-stringops @gol
521 -mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol
522 -m96bit-long-double -mregparm=@var{num} -msseregparm @gol
524 -momit-leaf-frame-pointer -mno-red-zone -mno-tls-direct-seg-refs @gol
525 -mcmodel=@var{code-model} @gol
526 -m32 -m64 -mlarge-data-threshold=@var{num}}
529 @gccoptlist{-mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol
530 -mvolatile-asm-stop -mregister-names -mno-sdata @gol
531 -mconstant-gp -mauto-pic -minline-float-divide-min-latency @gol
532 -minline-float-divide-max-throughput @gol
533 -minline-int-divide-min-latency @gol
534 -minline-int-divide-max-throughput @gol
535 -minline-sqrt-min-latency -minline-sqrt-max-throughput @gol
536 -mno-dwarf2-asm -mearly-stop-bits @gol
537 -mfixed-range=@var{register-range} -mtls-size=@var{tls-size} @gol
538 -mtune=@var{cpu-type} -mt -pthread -milp32 -mlp64 @gol
539 -mno-sched-br-data-spec -msched-ar-data-spec -mno-sched-control-spec @gol
540 -msched-br-in-data-spec -msched-ar-in-data-spec -msched-in-control-spec @gol
541 -msched-ldc -mno-sched-control-ldc -mno-sched-spec-verbose @gol
542 -mno-sched-prefer-non-data-spec-insns @gol
543 -mno-sched-prefer-non-control-spec-insns @gol
544 -mno-sched-count-spec-in-critical-path}
546 @emph{M32R/D Options}
547 @gccoptlist{-m32r2 -m32rx -m32r @gol
549 -malign-loops -mno-align-loops @gol
550 -missue-rate=@var{number} @gol
551 -mbranch-cost=@var{number} @gol
552 -mmodel=@var{code-size-model-type} @gol
553 -msdata=@var{sdata-type} @gol
554 -mno-flush-func -mflush-func=@var{name} @gol
555 -mno-flush-trap -mflush-trap=@var{number} @gol
559 @gccoptlist{-mcpu=@var{cpu} -msim -memregs=@var{number}}
561 @emph{M680x0 Options}
562 @gccoptlist{-m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol
563 -m68060 -mcpu32 -m5200 -mcfv4e -m68881 -mbitfield @gol
564 -mc68000 -mc68020 @gol
565 -mnobitfield -mrtd -mshort -msoft-float -mpcrel @gol
566 -malign-int -mstrict-align -msep-data -mno-sep-data @gol
567 -mshared-library-id=n -mid-shared-library -mno-id-shared-library}
569 @emph{M68hc1x Options}
570 @gccoptlist{-m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 @gol
571 -mauto-incdec -minmax -mlong-calls -mshort @gol
572 -msoft-reg-count=@var{count}}
575 @gccoptlist{-mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol
576 -mno-relax-immediates -mwide-bitfields -mno-wide-bitfields @gol
577 -m4byte-functions -mno-4byte-functions -mcallgraph-data @gol
578 -mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim @gol
579 -mlittle-endian -mbig-endian -m210 -m340 -mstack-increment}
582 @gccoptlist{-EL -EB -march=@var{arch} -mtune=@var{arch} @gol
583 -mips1 -mips2 -mips3 -mips4 -mips32 -mips32r2 -mips64 @gol
584 -mips16 -mno-mips16 -mabi=@var{abi} -mabicalls -mno-abicalls @gol
585 -mshared -mno-shared -mxgot -mno-xgot -mgp32 -mgp64 @gol
586 -mfp32 -mfp64 -mhard-float -msoft-float @gol
587 -msingle-float -mdouble-float -mdsp -mpaired-single -mips3d @gol
588 -mlong64 -mlong32 -msym32 -mno-sym32 @gol
589 -G@var{num} -membedded-data -mno-embedded-data @gol
590 -muninit-const-in-rodata -mno-uninit-const-in-rodata @gol
591 -msplit-addresses -mno-split-addresses @gol
592 -mexplicit-relocs -mno-explicit-relocs @gol
593 -mcheck-zero-division -mno-check-zero-division @gol
594 -mdivide-traps -mdivide-breaks @gol
595 -mmemcpy -mno-memcpy -mlong-calls -mno-long-calls @gol
596 -mmad -mno-mad -mfused-madd -mno-fused-madd -nocpp @gol
597 -mfix-r4000 -mno-fix-r4000 -mfix-r4400 -mno-fix-r4400 @gol
598 -mfix-vr4120 -mno-fix-vr4120 -mfix-vr4130 @gol
599 -mfix-sb1 -mno-fix-sb1 @gol
600 -mflush-func=@var{func} -mno-flush-func @gol
601 -mbranch-likely -mno-branch-likely @gol
602 -mfp-exceptions -mno-fp-exceptions @gol
603 -mvr4130-align -mno-vr4130-align}
606 @gccoptlist{-mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol
607 -mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol
608 -melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol
609 -mno-base-addresses -msingle-exit -mno-single-exit}
611 @emph{MN10300 Options}
612 @gccoptlist{-mmult-bug -mno-mult-bug @gol
613 -mam33 -mno-am33 @gol
614 -mam33-2 -mno-am33-2 @gol
615 -mreturn-pointer-on-d0 @gol
619 @gccoptlist{-mno-crt0 -mbacc -msim @gol
620 -march=@var{cpu-type} }
622 @emph{PDP-11 Options}
623 @gccoptlist{-mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol
624 -mbcopy -mbcopy-builtin -mint32 -mno-int16 @gol
625 -mint16 -mno-int32 -mfloat32 -mno-float64 @gol
626 -mfloat64 -mno-float32 -mabshi -mno-abshi @gol
627 -mbranch-expensive -mbranch-cheap @gol
628 -msplit -mno-split -munix-asm -mdec-asm}
630 @emph{PowerPC Options}
631 See RS/6000 and PowerPC Options.
633 @emph{RS/6000 and PowerPC Options}
634 @gccoptlist{-mcpu=@var{cpu-type} @gol
635 -mtune=@var{cpu-type} @gol
636 -mpower -mno-power -mpower2 -mno-power2 @gol
637 -mpowerpc -mpowerpc64 -mno-powerpc @gol
638 -maltivec -mno-altivec @gol
639 -mpowerpc-gpopt -mno-powerpc-gpopt @gol
640 -mpowerpc-gfxopt -mno-powerpc-gfxopt @gol
641 -mmfcrf -mno-mfcrf -mpopcntb -mno-popcntb -mfprnd -mno-fprnd @gol
642 -mnew-mnemonics -mold-mnemonics @gol
643 -mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc @gol
644 -m64 -m32 -mxl-compat -mno-xl-compat -mpe @gol
645 -malign-power -malign-natural @gol
646 -msoft-float -mhard-float -mmultiple -mno-multiple @gol
647 -mstring -mno-string -mupdate -mno-update @gol
648 -mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol
649 -mstrict-align -mno-strict-align -mrelocatable @gol
650 -mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol
651 -mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol
652 -mdynamic-no-pic -maltivec -mswdiv @gol
653 -mprioritize-restricted-insns=@var{priority} @gol
654 -msched-costly-dep=@var{dependence_type} @gol
655 -minsert-sched-nops=@var{scheme} @gol
656 -mcall-sysv -mcall-netbsd @gol
657 -maix-struct-return -msvr4-struct-return @gol
658 -mabi=@var{abi-type} -msecure-plt -mbss-plt @gol
659 -misel -mno-isel @gol
660 -misel=yes -misel=no @gol
662 -mspe=yes -mspe=no @gol
663 -mvrsave -mno-vrsave @gol
664 -mmulhw -mno-mulhw @gol
665 -mdlmzb -mno-dlmzb @gol
666 -mfloat-gprs=yes -mfloat-gprs=no -mfloat-gprs=single -mfloat-gprs=double @gol
667 -mprototype -mno-prototype @gol
668 -msim -mmvme -mads -myellowknife -memb -msdata @gol
669 -msdata=@var{opt} -mvxworks -mwindiss -G @var{num} -pthread}
671 @emph{S/390 and zSeries Options}
672 @gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
673 -mhard-float -msoft-float -mlong-double-64 -mlong-double-128 @gol
674 -mbackchain -mno-backchain -mpacked-stack -mno-packed-stack @gol
675 -msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol
676 -m64 -m31 -mdebug -mno-debug -mesa -mzarch @gol
677 -mtpf-trace -mno-tpf-trace -mfused-madd -mno-fused-madd @gol
678 -mwarn-framesize -mwarn-dynamicstack -mstack-size -mstack-guard}
681 @gccoptlist{-meb -mel @gol
685 -mscore5 -mscore5u -mscore7 -mscore7d}
688 @gccoptlist{-m1 -m2 -m2e -m3 -m3e @gol
689 -m4-nofpu -m4-single-only -m4-single -m4 @gol
690 -m4a-nofpu -m4a-single-only -m4a-single -m4a -m4al @gol
691 -m5-64media -m5-64media-nofpu @gol
692 -m5-32media -m5-32media-nofpu @gol
693 -m5-compact -m5-compact-nofpu @gol
694 -mb -ml -mdalign -mrelax @gol
695 -mbigtable -mfmovd -mhitachi -mrenesas -mno-renesas -mnomacsave @gol
696 -mieee -misize -mpadstruct -mspace @gol
697 -mprefergot -musermode -multcost=@var{number} -mdiv=@var{strategy} @gol
698 -mdivsi3_libfunc=@var{name} @gol
699 -madjust-unroll -mindexed-addressing -mgettrcost=@var{number} -mpt-fixed @gol
703 @gccoptlist{-mcpu=@var{cpu-type} @gol
704 -mtune=@var{cpu-type} @gol
705 -mcmodel=@var{code-model} @gol
706 -m32 -m64 -mapp-regs -mno-app-regs @gol
707 -mfaster-structs -mno-faster-structs @gol
708 -mfpu -mno-fpu -mhard-float -msoft-float @gol
709 -mhard-quad-float -msoft-quad-float @gol
710 -mimpure-text -mno-impure-text -mlittle-endian @gol
711 -mstack-bias -mno-stack-bias @gol
712 -munaligned-doubles -mno-unaligned-doubles @gol
713 -mv8plus -mno-v8plus -mvis -mno-vis
714 -threads -pthreads -pthread}
716 @emph{System V Options}
717 @gccoptlist{-Qy -Qn -YP,@var{paths} -Ym,@var{dir}}
719 @emph{TMS320C3x/C4x Options}
720 @gccoptlist{-mcpu=@var{cpu} -mbig -msmall -mregparm -mmemparm @gol
721 -mfast-fix -mmpyi -mbk -mti -mdp-isr-reload @gol
722 -mrpts=@var{count} -mrptb -mdb -mloop-unsigned @gol
723 -mparallel-insns -mparallel-mpy -mpreserve-float}
726 @gccoptlist{-mlong-calls -mno-long-calls -mep -mno-ep @gol
727 -mprolog-function -mno-prolog-function -mspace @gol
728 -mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol
729 -mapp-regs -mno-app-regs @gol
730 -mdisable-callt -mno-disable-callt @gol
736 @gccoptlist{-mg -mgnu -munix}
738 @emph{x86-64 Options}
739 See i386 and x86-64 Options.
741 @emph{Xstormy16 Options}
744 @emph{Xtensa Options}
745 @gccoptlist{-mconst16 -mno-const16 @gol
746 -mfused-madd -mno-fused-madd @gol
747 -mtext-section-literals -mno-text-section-literals @gol
748 -mtarget-align -mno-target-align @gol
749 -mlongcalls -mno-longcalls}
751 @emph{zSeries Options}
752 See S/390 and zSeries Options.
754 @item Code Generation Options
755 @xref{Code Gen Options,,Options for Code Generation Conventions}.
756 @gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol
757 -ffixed-@var{reg} -fexceptions @gol
758 -fnon-call-exceptions -funwind-tables @gol
759 -fasynchronous-unwind-tables @gol
760 -finhibit-size-directive -finstrument-functions @gol
761 -fno-common -fno-ident @gol
762 -fpcc-struct-return -fpic -fPIC -fpie -fPIE @gol
763 -fno-jump-tables @gol
764 -freg-struct-return -fshort-enums @gol
765 -fshort-double -fshort-wchar @gol
766 -fverbose-asm -fpack-struct[=@var{n}] -fstack-check @gol
767 -fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
768 -fargument-alias -fargument-noalias @gol
769 -fargument-noalias-global -fargument-noalias-anything
770 -fleading-underscore -ftls-model=@var{model} @gol
771 -ftrapv -fwrapv -fbounds-check @gol
776 * Overall Options:: Controlling the kind of output:
777 an executable, object files, assembler files,
778 or preprocessed source.
779 * C Dialect Options:: Controlling the variant of C language compiled.
780 * C++ Dialect Options:: Variations on C++.
781 * Language Independent Options:: Controlling how diagnostics should be
783 * Warning Options:: How picky should the compiler be?
784 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
785 * Optimize Options:: How much optimization?
786 * Preprocessor Options:: Controlling header files and macro definitions.
787 Also, getting dependency information for Make.
788 * Assembler Options:: Passing options to the assembler.
789 * Link Options:: Specifying libraries and so on.
790 * Directory Options:: Where to find header files and libraries.
791 Where to find the compiler executable files.
792 * Spec Files:: How to pass switches to sub-processes.
793 * Target Options:: Running a cross-compiler, or an old version of GCC.
796 @node Overall Options
797 @section Options Controlling the Kind of Output
799 Compilation can involve up to four stages: preprocessing, compilation
800 proper, assembly and linking, always in that order. GCC is capable of
801 preprocessing and compiling several files either into several
802 assembler input files, or into one assembler input file; then each
803 assembler input file produces an object file, and linking combines all
804 the object files (those newly compiled, and those specified as input)
805 into an executable file.
807 @cindex file name suffix
808 For any given input file, the file name suffix determines what kind of
813 C source code which must be preprocessed.
816 C source code which should not be preprocessed.
819 C++ source code which should not be preprocessed.
822 C, or C++ header file to be turned into a precompiled header.
826 @itemx @var{file}.cxx
827 @itemx @var{file}.cpp
828 @itemx @var{file}.CPP
829 @itemx @var{file}.c++
831 C++ source code which must be preprocessed. Note that in @samp{.cxx},
832 the last two letters must both be literally @samp{x}. Likewise,
833 @samp{.C} refers to a literal capital C@.
837 C++ header file to be turned into a precompiled header.
840 @itemx @var{file}.for
841 @itemx @var{file}.FOR
842 Fixed form Fortran source code which should not be preprocessed.
845 @itemx @var{file}.fpp
846 @itemx @var{file}.FPP
847 Fixed form Fortran source code which must be preprocessed (with the traditional
851 @itemx @var{file}.f95
852 Free form Fortran source code which should not be preprocessed.
855 @itemx @var{file}.F95
856 Free form Fortran source code which must be preprocessed (with the
857 traditional preprocessor).
859 @c FIXME: Descriptions of Java file types.
866 Ada source code file which contains a library unit declaration (a
867 declaration of a package, subprogram, or generic, or a generic
868 instantiation), or a library unit renaming declaration (a package,
869 generic, or subprogram renaming declaration). Such files are also
872 @itemx @var{file}.adb
873 Ada source code file containing a library unit body (a subprogram or
874 package body). Such files are also called @dfn{bodies}.
876 @c GCC also knows about some suffixes for languages not yet included:
887 Assembler code which must be preprocessed.
890 An object file to be fed straight into linking.
891 Any file name with no recognized suffix is treated this way.
895 You can specify the input language explicitly with the @option{-x} option:
898 @item -x @var{language}
899 Specify explicitly the @var{language} for the following input files
900 (rather than letting the compiler choose a default based on the file
901 name suffix). This option applies to all following input files until
902 the next @option{-x} option. Possible values for @var{language} are:
904 c c-header c-cpp-output
905 c++ c++-header c++-cpp-output
906 assembler assembler-with-cpp
914 Turn off any specification of a language, so that subsequent files are
915 handled according to their file name suffixes (as they are if @option{-x}
916 has not been used at all).
918 @item -pass-exit-codes
919 @opindex pass-exit-codes
920 Normally the @command{gcc} program will exit with the code of 1 if any
921 phase of the compiler returns a non-success return code. If you specify
922 @option{-pass-exit-codes}, the @command{gcc} program will instead return with
923 numerically highest error produced by any phase that returned an error
924 indication. The C, C++, and Fortran frontends return 4, if an internal
925 compiler error is encountered.
928 If you only want some of the stages of compilation, you can use
929 @option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
930 one of the options @option{-c}, @option{-S}, or @option{-E} to say where
931 @command{gcc} is to stop. Note that some combinations (for example,
932 @samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
937 Compile or assemble the source files, but do not link. The linking
938 stage simply is not done. The ultimate output is in the form of an
939 object file for each source file.
941 By default, the object file name for a source file is made by replacing
942 the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
944 Unrecognized input files, not requiring compilation or assembly, are
949 Stop after the stage of compilation proper; do not assemble. The output
950 is in the form of an assembler code file for each non-assembler input
953 By default, the assembler file name for a source file is made by
954 replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
956 Input files that don't require compilation are ignored.
960 Stop after the preprocessing stage; do not run the compiler proper. The
961 output is in the form of preprocessed source code, which is sent to the
964 Input files which don't require preprocessing are ignored.
966 @cindex output file option
969 Place output in file @var{file}. This applies regardless to whatever
970 sort of output is being produced, whether it be an executable file,
971 an object file, an assembler file or preprocessed C code.
973 If @option{-o} is not specified, the default is to put an executable
974 file in @file{a.out}, the object file for
975 @file{@var{source}.@var{suffix}} in @file{@var{source}.o}, its
976 assembler file in @file{@var{source}.s}, a precompiled header file in
977 @file{@var{source}.@var{suffix}.gch}, and all preprocessed C source on
982 Print (on standard error output) the commands executed to run the stages
983 of compilation. Also print the version number of the compiler driver
984 program and of the preprocessor and the compiler proper.
988 Like @option{-v} except the commands are not executed and all command
989 arguments are quoted. This is useful for shell scripts to capture the
990 driver-generated command lines.
994 Use pipes rather than temporary files for communication between the
995 various stages of compilation. This fails to work on some systems where
996 the assembler is unable to read from a pipe; but the GNU assembler has
1001 If you are compiling multiple source files, this option tells the driver
1002 to pass all the source files to the compiler at once (for those
1003 languages for which the compiler can handle this). This will allow
1004 intermodule analysis (IMA) to be performed by the compiler. Currently the only
1005 language for which this is supported is C@. If you pass source files for
1006 multiple languages to the driver, using this option, the driver will invoke
1007 the compiler(s) that support IMA once each, passing each compiler all the
1008 source files appropriate for it. For those languages that do not support
1009 IMA this option will be ignored, and the compiler will be invoked once for
1010 each source file in that language. If you use this option in conjunction
1011 with @option{-save-temps}, the compiler will generate multiple
1013 (one for each source file), but only one (combined) @file{.o} or
1018 Print (on the standard output) a description of the command line options
1019 understood by @command{gcc}. If the @option{-v} option is also specified
1020 then @option{--help} will also be passed on to the various processes
1021 invoked by @command{gcc}, so that they can display the command line options
1022 they accept. If the @option{-Wextra} option is also specified then command
1023 line options which have no documentation associated with them will also
1027 @opindex target-help
1028 Print (on the standard output) a description of target specific command
1029 line options for each tool.
1033 Display the version number and copyrights of the invoked GCC@.
1035 @include @value{srcdir}/../libiberty/at-file.texi
1039 @section Compiling C++ Programs
1041 @cindex suffixes for C++ source
1042 @cindex C++ source file suffixes
1043 C++ source files conventionally use one of the suffixes @samp{.C},
1044 @samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or
1045 @samp{.cxx}; C++ header files often use @samp{.hh} or @samp{.H}; and
1046 preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes
1047 files with these names and compiles them as C++ programs even if you
1048 call the compiler the same way as for compiling C programs (usually
1049 with the name @command{gcc}).
1053 However, the use of @command{gcc} does not add the C++ library.
1054 @command{g++} is a program that calls GCC and treats @samp{.c},
1055 @samp{.h} and @samp{.i} files as C++ source files instead of C source
1056 files unless @option{-x} is used, and automatically specifies linking
1057 against the C++ library. This program is also useful when
1058 precompiling a C header file with a @samp{.h} extension for use in C++
1059 compilations. On many systems, @command{g++} is also installed with
1060 the name @command{c++}.
1062 @cindex invoking @command{g++}
1063 When you compile C++ programs, you may specify many of the same
1064 command-line options that you use for compiling programs in any
1065 language; or command-line options meaningful for C and related
1066 languages; or options that are meaningful only for C++ programs.
1067 @xref{C Dialect Options,,Options Controlling C Dialect}, for
1068 explanations of options for languages related to C@.
1069 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
1070 explanations of options that are meaningful only for C++ programs.
1072 @node C Dialect Options
1073 @section Options Controlling C Dialect
1074 @cindex dialect options
1075 @cindex language dialect options
1076 @cindex options, dialect
1078 The following options control the dialect of C (or languages derived
1079 from C, such as C++) that the compiler accepts:
1082 @cindex ANSI support
1086 In C mode, support all ISO C90 programs. In C++ mode,
1087 remove GNU extensions that conflict with ISO C++.
1089 This turns off certain features of GCC that are incompatible with ISO
1090 C90 (when compiling C code), or of standard C++ (when compiling C++ code),
1091 such as the @code{asm} and @code{typeof} keywords, and
1092 predefined macros such as @code{unix} and @code{vax} that identify the
1093 type of system you are using. It also enables the undesirable and
1094 rarely used ISO trigraph feature. For the C compiler,
1095 it disables recognition of C++ style @samp{//} comments as well as
1096 the @code{inline} keyword.
1098 The alternate keywords @code{__asm__}, @code{__extension__},
1099 @code{__inline__} and @code{__typeof__} continue to work despite
1100 @option{-ansi}. You would not want to use them in an ISO C program, of
1101 course, but it is useful to put them in header files that might be included
1102 in compilations done with @option{-ansi}. Alternate predefined macros
1103 such as @code{__unix__} and @code{__vax__} are also available, with or
1104 without @option{-ansi}.
1106 The @option{-ansi} option does not cause non-ISO programs to be
1107 rejected gratuitously. For that, @option{-pedantic} is required in
1108 addition to @option{-ansi}. @xref{Warning Options}.
1110 The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
1111 option is used. Some header files may notice this macro and refrain
1112 from declaring certain functions or defining certain macros that the
1113 ISO standard doesn't call for; this is to avoid interfering with any
1114 programs that might use these names for other things.
1116 Functions which would normally be built in but do not have semantics
1117 defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
1118 functions with @option{-ansi} is used. @xref{Other Builtins,,Other
1119 built-in functions provided by GCC}, for details of the functions
1124 Determine the language standard. This option is currently only
1125 supported when compiling C or C++. A value for this option must be
1126 provided; possible values are
1131 ISO C90 (same as @option{-ansi}).
1133 @item iso9899:199409
1134 ISO C90 as modified in amendment 1.
1140 ISO C99. Note that this standard is not yet fully supported; see
1141 @w{@uref{http://gcc.gnu.org/gcc-4.2/c99status.html}} for more information. The
1142 names @samp{c9x} and @samp{iso9899:199x} are deprecated.
1145 Default, ISO C90 plus GNU extensions (including some C99 features).
1149 ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC,
1150 this will become the default. The name @samp{gnu9x} is deprecated.
1153 The 1998 ISO C++ standard plus amendments.
1156 The same as @option{-std=c++98} plus GNU extensions. This is the
1157 default for C++ code.
1160 Even when this option is not specified, you can still use some of the
1161 features of newer standards in so far as they do not conflict with
1162 previous C standards. For example, you may use @code{__restrict__} even
1163 when @option{-std=c99} is not specified.
1165 The @option{-std} options specifying some version of ISO C have the same
1166 effects as @option{-ansi}, except that features that were not in ISO C90
1167 but are in the specified version (for example, @samp{//} comments and
1168 the @code{inline} keyword in ISO C99) are not disabled.
1170 @xref{Standards,,Language Standards Supported by GCC}, for details of
1171 these standard versions.
1173 @item -fgnu89-inline
1174 @opindex fgnu89-inline
1175 The option @option{-fgnu89-inline} tells GCC to use the traditional
1176 GNU semantics for @code{inline} functions when in C99 mode.
1177 @xref{Inline,,An Inline Function is As Fast As a Macro}. Using this
1178 option is roughly equivalent to adding the @code{gnu_inline} function
1179 attribute to all inline functions (@pxref{Function Attributes}).
1181 This option is accepted by GCC versions 4.1.3 and up. In GCC versions
1182 prior to 4.3, C99 inline semantics are not supported, and thus this
1183 option is effectively assumed to be present regardless of whether or not
1184 it is specified; the only effect of specifying it explicitly is to
1185 disable warnings about using inline functions in C99 mode. Likewise,
1186 the option @option{-fno-gnu89-inline} is not supported in versions of
1187 GCC before 4.3. It will be supported only in C99 or gnu99 mode, not in
1190 The preprocesor macros @code{__GNUC_GNU_INLINE__} and
1191 @code{__GNUC_STDC_INLINE__} may be used to check which semantics are
1192 in effect for @code{inline} functions. @xref{Common Predefined
1193 Macros,,,cpp,The C Preprocessor}.
1195 @item -aux-info @var{filename}
1197 Output to the given filename prototyped declarations for all functions
1198 declared and/or defined in a translation unit, including those in header
1199 files. This option is silently ignored in any language other than C@.
1201 Besides declarations, the file indicates, in comments, the origin of
1202 each declaration (source file and line), whether the declaration was
1203 implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
1204 @samp{O} for old, respectively, in the first character after the line
1205 number and the colon), and whether it came from a declaration or a
1206 definition (@samp{C} or @samp{F}, respectively, in the following
1207 character). In the case of function definitions, a K&R-style list of
1208 arguments followed by their declarations is also provided, inside
1209 comments, after the declaration.
1213 Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1214 keyword, so that code can use these words as identifiers. You can use
1215 the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
1216 instead. @option{-ansi} implies @option{-fno-asm}.
1218 In C++, this switch only affects the @code{typeof} keyword, since
1219 @code{asm} and @code{inline} are standard keywords. You may want to
1220 use the @option{-fno-gnu-keywords} flag instead, which has the same
1221 effect. In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
1222 switch only affects the @code{asm} and @code{typeof} keywords, since
1223 @code{inline} is a standard keyword in ISO C99.
1226 @itemx -fno-builtin-@var{function}
1227 @opindex fno-builtin
1228 @cindex built-in functions
1229 Don't recognize built-in functions that do not begin with
1230 @samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in
1231 functions provided by GCC}, for details of the functions affected,
1232 including those which are not built-in functions when @option{-ansi} or
1233 @option{-std} options for strict ISO C conformance are used because they
1234 do not have an ISO standard meaning.
1236 GCC normally generates special code to handle certain built-in functions
1237 more efficiently; for instance, calls to @code{alloca} may become single
1238 instructions that adjust the stack directly, and calls to @code{memcpy}
1239 may become inline copy loops. The resulting code is often both smaller
1240 and faster, but since the function calls no longer appear as such, you
1241 cannot set a breakpoint on those calls, nor can you change the behavior
1242 of the functions by linking with a different library. In addition,
1243 when a function is recognized as a built-in function, GCC may use
1244 information about that function to warn about problems with calls to
1245 that function, or to generate more efficient code, even if the
1246 resulting code still contains calls to that function. For example,
1247 warnings are given with @option{-Wformat} for bad calls to
1248 @code{printf}, when @code{printf} is built in, and @code{strlen} is
1249 known not to modify global memory.
1251 With the @option{-fno-builtin-@var{function}} option
1252 only the built-in function @var{function} is
1253 disabled. @var{function} must not begin with @samp{__builtin_}. If a
1254 function is named this is not built-in in this version of GCC, this
1255 option is ignored. There is no corresponding
1256 @option{-fbuiltin-@var{function}} option; if you wish to enable
1257 built-in functions selectively when using @option{-fno-builtin} or
1258 @option{-ffreestanding}, you may define macros such as:
1261 #define abs(n) __builtin_abs ((n))
1262 #define strcpy(d, s) __builtin_strcpy ((d), (s))
1267 @cindex hosted environment
1269 Assert that compilation takes place in a hosted environment. This implies
1270 @option{-fbuiltin}. A hosted environment is one in which the
1271 entire standard library is available, and in which @code{main} has a return
1272 type of @code{int}. Examples are nearly everything except a kernel.
1273 This is equivalent to @option{-fno-freestanding}.
1275 @item -ffreestanding
1276 @opindex ffreestanding
1277 @cindex hosted environment
1279 Assert that compilation takes place in a freestanding environment. This
1280 implies @option{-fno-builtin}. A freestanding environment
1281 is one in which the standard library may not exist, and program startup may
1282 not necessarily be at @code{main}. The most obvious example is an OS kernel.
1283 This is equivalent to @option{-fno-hosted}.
1285 @xref{Standards,,Language Standards Supported by GCC}, for details of
1286 freestanding and hosted environments.
1290 @cindex openmp parallel
1291 Enable handling of OpenMP directives @code{#pragma omp} in C/C++ and
1292 @code{!$omp} in Fortran. When @option{-fopenmp} is specified, the
1293 compiler generates parallel code according to the OpenMP Application
1294 Program Interface v2.5 @w{@uref{http://www.openmp.org/}}.
1296 @item -fms-extensions
1297 @opindex fms-extensions
1298 Accept some non-standard constructs used in Microsoft header files.
1300 Some cases of unnamed fields in structures and unions are only
1301 accepted with this option. @xref{Unnamed Fields,,Unnamed struct/union
1302 fields within structs/unions}, for details.
1306 Support ISO C trigraphs. The @option{-ansi} option (and @option{-std}
1307 options for strict ISO C conformance) implies @option{-trigraphs}.
1309 @item -no-integrated-cpp
1310 @opindex no-integrated-cpp
1311 Performs a compilation in two passes: preprocessing and compiling. This
1312 option allows a user supplied "cc1", "cc1plus", or "cc1obj" via the
1313 @option{-B} option. The user supplied compilation step can then add in
1314 an additional preprocessing step after normal preprocessing but before
1315 compiling. The default is to use the integrated cpp (internal cpp)
1317 The semantics of this option will change if "cc1", "cc1plus", and
1318 "cc1obj" are merged.
1320 @cindex traditional C language
1321 @cindex C language, traditional
1323 @itemx -traditional-cpp
1324 @opindex traditional-cpp
1325 @opindex traditional
1326 Formerly, these options caused GCC to attempt to emulate a pre-standard
1327 C compiler. They are now only supported with the @option{-E} switch.
1328 The preprocessor continues to support a pre-standard mode. See the GNU
1329 CPP manual for details.
1331 @item -fcond-mismatch
1332 @opindex fcond-mismatch
1333 Allow conditional expressions with mismatched types in the second and
1334 third arguments. The value of such an expression is void. This option
1335 is not supported for C++.
1337 @item -funsigned-char
1338 @opindex funsigned-char
1339 Let the type @code{char} be unsigned, like @code{unsigned char}.
1341 Each kind of machine has a default for what @code{char} should
1342 be. It is either like @code{unsigned char} by default or like
1343 @code{signed char} by default.
1345 Ideally, a portable program should always use @code{signed char} or
1346 @code{unsigned char} when it depends on the signedness of an object.
1347 But many programs have been written to use plain @code{char} and
1348 expect it to be signed, or expect it to be unsigned, depending on the
1349 machines they were written for. This option, and its inverse, let you
1350 make such a program work with the opposite default.
1352 The type @code{char} is always a distinct type from each of
1353 @code{signed char} or @code{unsigned char}, even though its behavior
1354 is always just like one of those two.
1357 @opindex fsigned-char
1358 Let the type @code{char} be signed, like @code{signed char}.
1360 Note that this is equivalent to @option{-fno-unsigned-char}, which is
1361 the negative form of @option{-funsigned-char}. Likewise, the option
1362 @option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
1364 @item -fsigned-bitfields
1365 @itemx -funsigned-bitfields
1366 @itemx -fno-signed-bitfields
1367 @itemx -fno-unsigned-bitfields
1368 @opindex fsigned-bitfields
1369 @opindex funsigned-bitfields
1370 @opindex fno-signed-bitfields
1371 @opindex fno-unsigned-bitfields
1372 These options control whether a bit-field is signed or unsigned, when the
1373 declaration does not use either @code{signed} or @code{unsigned}. By
1374 default, such a bit-field is signed, because this is consistent: the
1375 basic integer types such as @code{int} are signed types.
1378 @node C++ Dialect Options
1379 @section Options Controlling C++ Dialect
1381 @cindex compiler options, C++
1382 @cindex C++ options, command line
1383 @cindex options, C++
1384 This section describes the command-line options that are only meaningful
1385 for C++ programs; but you can also use most of the GNU compiler options
1386 regardless of what language your program is in. For example, you
1387 might compile a file @code{firstClass.C} like this:
1390 g++ -g -frepo -O -c firstClass.C
1394 In this example, only @option{-frepo} is an option meant
1395 only for C++ programs; you can use the other options with any
1396 language supported by GCC@.
1398 Here is a list of options that are @emph{only} for compiling C++ programs:
1402 @item -fabi-version=@var{n}
1403 @opindex fabi-version
1404 Use version @var{n} of the C++ ABI@. Version 2 is the version of the
1405 C++ ABI that first appeared in G++ 3.4. Version 1 is the version of
1406 the C++ ABI that first appeared in G++ 3.2. Version 0 will always be
1407 the version that conforms most closely to the C++ ABI specification.
1408 Therefore, the ABI obtained using version 0 will change as ABI bugs
1411 The default is version 2.
1413 @item -fno-access-control
1414 @opindex fno-access-control
1415 Turn off all access checking. This switch is mainly useful for working
1416 around bugs in the access control code.
1420 Check that the pointer returned by @code{operator new} is non-null
1421 before attempting to modify the storage allocated. This check is
1422 normally unnecessary because the C++ standard specifies that
1423 @code{operator new} will only return @code{0} if it is declared
1424 @samp{throw()}, in which case the compiler will always check the
1425 return value even without this option. In all other cases, when
1426 @code{operator new} has a non-empty exception specification, memory
1427 exhaustion is signalled by throwing @code{std::bad_alloc}. See also
1428 @samp{new (nothrow)}.
1430 @item -fconserve-space
1431 @opindex fconserve-space
1432 Put uninitialized or runtime-initialized global variables into the
1433 common segment, as C does. This saves space in the executable at the
1434 cost of not diagnosing duplicate definitions. If you compile with this
1435 flag and your program mysteriously crashes after @code{main()} has
1436 completed, you may have an object that is being destroyed twice because
1437 two definitions were merged.
1439 This option is no longer useful on most targets, now that support has
1440 been added for putting variables into BSS without making them common.
1442 @item -ffriend-injection
1443 @opindex ffriend-injection
1444 Inject friend functions into the enclosing namespace, so that they are
1445 visible outside the scope of the class in which they are declared.
1446 Friend functions were documented to work this way in the old Annotated
1447 C++ Reference Manual, and versions of G++ before 4.1 always worked
1448 that way. However, in ISO C++ a friend function which is not declared
1449 in an enclosing scope can only be found using argument dependent
1450 lookup. This option causes friends to be injected as they were in
1453 This option is for compatibility, and may be removed in a future
1456 @item -fno-elide-constructors
1457 @opindex fno-elide-constructors
1458 The C++ standard allows an implementation to omit creating a temporary
1459 which is only used to initialize another object of the same type.
1460 Specifying this option disables that optimization, and forces G++ to
1461 call the copy constructor in all cases.
1463 @item -fno-enforce-eh-specs
1464 @opindex fno-enforce-eh-specs
1465 Don't generate code to check for violation of exception specifications
1466 at runtime. This option violates the C++ standard, but may be useful
1467 for reducing code size in production builds, much like defining
1468 @samp{NDEBUG}. This does not give user code permission to throw
1469 exceptions in violation of the exception specifications; the compiler
1470 will still optimize based on the specifications, so throwing an
1471 unexpected exception will result in undefined behavior.
1474 @itemx -fno-for-scope
1476 @opindex fno-for-scope
1477 If @option{-ffor-scope} is specified, the scope of variables declared in
1478 a @i{for-init-statement} is limited to the @samp{for} loop itself,
1479 as specified by the C++ standard.
1480 If @option{-fno-for-scope} is specified, the scope of variables declared in
1481 a @i{for-init-statement} extends to the end of the enclosing scope,
1482 as was the case in old versions of G++, and other (traditional)
1483 implementations of C++.
1485 The default if neither flag is given to follow the standard,
1486 but to allow and give a warning for old-style code that would
1487 otherwise be invalid, or have different behavior.
1489 @item -fno-gnu-keywords
1490 @opindex fno-gnu-keywords
1491 Do not recognize @code{typeof} as a keyword, so that code can use this
1492 word as an identifier. You can use the keyword @code{__typeof__} instead.
1493 @option{-ansi} implies @option{-fno-gnu-keywords}.
1495 @item -fno-implicit-templates
1496 @opindex fno-implicit-templates
1497 Never emit code for non-inline templates which are instantiated
1498 implicitly (i.e.@: by use); only emit code for explicit instantiations.
1499 @xref{Template Instantiation}, for more information.
1501 @item -fno-implicit-inline-templates
1502 @opindex fno-implicit-inline-templates
1503 Don't emit code for implicit instantiations of inline templates, either.
1504 The default is to handle inlines differently so that compiles with and
1505 without optimization will need the same set of explicit instantiations.
1507 @item -fno-implement-inlines
1508 @opindex fno-implement-inlines
1509 To save space, do not emit out-of-line copies of inline functions
1510 controlled by @samp{#pragma implementation}. This will cause linker
1511 errors if these functions are not inlined everywhere they are called.
1513 @item -fms-extensions
1514 @opindex fms-extensions
1515 Disable pedantic warnings about constructs used in MFC, such as implicit
1516 int and getting a pointer to member function via non-standard syntax.
1518 @item -fno-nonansi-builtins
1519 @opindex fno-nonansi-builtins
1520 Disable built-in declarations of functions that are not mandated by
1521 ANSI/ISO C@. These include @code{ffs}, @code{alloca}, @code{_exit},
1522 @code{index}, @code{bzero}, @code{conjf}, and other related functions.
1524 @item -fno-operator-names
1525 @opindex fno-operator-names
1526 Do not treat the operator name keywords @code{and}, @code{bitand},
1527 @code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1528 synonyms as keywords.
1530 @item -fno-optional-diags
1531 @opindex fno-optional-diags
1532 Disable diagnostics that the standard says a compiler does not need to
1533 issue. Currently, the only such diagnostic issued by G++ is the one for
1534 a name having multiple meanings within a class.
1537 @opindex fpermissive
1538 Downgrade some diagnostics about nonconformant code from errors to
1539 warnings. Thus, using @option{-fpermissive} will allow some
1540 nonconforming code to compile.
1544 Enable automatic template instantiation at link time. This option also
1545 implies @option{-fno-implicit-templates}. @xref{Template
1546 Instantiation}, for more information.
1550 Disable generation of information about every class with virtual
1551 functions for use by the C++ runtime type identification features
1552 (@samp{dynamic_cast} and @samp{typeid}). If you don't use those parts
1553 of the language, you can save some space by using this flag. Note that
1554 exception handling uses the same information, but it will generate it as
1555 needed. The @samp{dynamic_cast} operator can still be used for casts that
1556 do not require runtime type information, i.e. casts to @code{void *} or to
1557 unambiguous base classes.
1561 Emit statistics about front-end processing at the end of the compilation.
1562 This information is generally only useful to the G++ development team.
1564 @item -ftemplate-depth-@var{n}
1565 @opindex ftemplate-depth
1566 Set the maximum instantiation depth for template classes to @var{n}.
1567 A limit on the template instantiation depth is needed to detect
1568 endless recursions during template class instantiation. ANSI/ISO C++
1569 conforming programs must not rely on a maximum depth greater than 17.
1571 @item -fno-threadsafe-statics
1572 @opindex fno-threadsafe-statics
1573 Do not emit the extra code to use the routines specified in the C++
1574 ABI for thread-safe initialization of local statics. You can use this
1575 option to reduce code size slightly in code that doesn't need to be
1578 @item -fuse-cxa-atexit
1579 @opindex fuse-cxa-atexit
1580 Register destructors for objects with static storage duration with the
1581 @code{__cxa_atexit} function rather than the @code{atexit} function.
1582 This option is required for fully standards-compliant handling of static
1583 destructors, but will only work if your C library supports
1584 @code{__cxa_atexit}.
1586 @item -fno-use-cxa-get-exception-ptr
1587 @opindex fno-use-cxa-get-exception-ptr
1588 Don't use the @code{__cxa_get_exception_ptr} runtime routine. This
1589 will cause @code{std::uncaught_exception} to be incorrect, but is necessary
1590 if the runtime routine is not available.
1592 @item -fvisibility-inlines-hidden
1593 @opindex fvisibility-inlines-hidden
1594 This switch declares that the user does not attempt to compare
1595 pointers to inline methods where the addresses of the two functions
1596 were taken in different shared objects.
1598 The effect of this is that GCC may, effectively, mark inline methods with
1599 @code{__attribute__ ((visibility ("hidden")))} so that they do not
1600 appear in the export table of a DSO and do not require a PLT indirection
1601 when used within the DSO@. Enabling this option can have a dramatic effect
1602 on load and link times of a DSO as it massively reduces the size of the
1603 dynamic export table when the library makes heavy use of templates.
1605 The behaviour of this switch is not quite the same as marking the
1606 methods as hidden directly, because it does not affect static variables
1607 local to the function or cause the compiler to deduce that
1608 the function is defined in only one shared object.
1610 You may mark a method as having a visibility explicitly to negate the
1611 effect of the switch for that method. For example, if you do want to
1612 compare pointers to a particular inline method, you might mark it as
1613 having default visibility. Marking the enclosing class with explicit
1614 visibility will have no effect.
1616 Explicitly instantiated inline methods are unaffected by this option
1617 as their linkage might otherwise cross a shared library boundary.
1618 @xref{Template Instantiation}.
1622 Do not use weak symbol support, even if it is provided by the linker.
1623 By default, G++ will use weak symbols if they are available. This
1624 option exists only for testing, and should not be used by end-users;
1625 it will result in inferior code and has no benefits. This option may
1626 be removed in a future release of G++.
1630 Do not search for header files in the standard directories specific to
1631 C++, but do still search the other standard directories. (This option
1632 is used when building the C++ library.)
1635 In addition, these optimization, warning, and code generation options
1636 have meanings only for C++ programs:
1639 @item -fno-default-inline
1640 @opindex fno-default-inline
1641 Do not assume @samp{inline} for functions defined inside a class scope.
1642 @xref{Optimize Options,,Options That Control Optimization}. Note that these
1643 functions will have linkage like inline functions; they just won't be
1646 @item -Wabi @r{(C++ only)}
1648 Warn when G++ generates code that is probably not compatible with the
1649 vendor-neutral C++ ABI@. Although an effort has been made to warn about
1650 all such cases, there are probably some cases that are not warned about,
1651 even though G++ is generating incompatible code. There may also be
1652 cases where warnings are emitted even though the code that is generated
1655 You should rewrite your code to avoid these warnings if you are
1656 concerned about the fact that code generated by G++ may not be binary
1657 compatible with code generated by other compilers.
1659 The known incompatibilities at this point include:
1664 Incorrect handling of tail-padding for bit-fields. G++ may attempt to
1665 pack data into the same byte as a base class. For example:
1668 struct A @{ virtual void f(); int f1 : 1; @};
1669 struct B : public A @{ int f2 : 1; @};
1673 In this case, G++ will place @code{B::f2} into the same byte
1674 as@code{A::f1}; other compilers will not. You can avoid this problem
1675 by explicitly padding @code{A} so that its size is a multiple of the
1676 byte size on your platform; that will cause G++ and other compilers to
1677 layout @code{B} identically.
1680 Incorrect handling of tail-padding for virtual bases. G++ does not use
1681 tail padding when laying out virtual bases. For example:
1684 struct A @{ virtual void f(); char c1; @};
1685 struct B @{ B(); char c2; @};
1686 struct C : public A, public virtual B @{@};
1690 In this case, G++ will not place @code{B} into the tail-padding for
1691 @code{A}; other compilers will. You can avoid this problem by
1692 explicitly padding @code{A} so that its size is a multiple of its
1693 alignment (ignoring virtual base classes); that will cause G++ and other
1694 compilers to layout @code{C} identically.
1697 Incorrect handling of bit-fields with declared widths greater than that
1698 of their underlying types, when the bit-fields appear in a union. For
1702 union U @{ int i : 4096; @};
1706 Assuming that an @code{int} does not have 4096 bits, G++ will make the
1707 union too small by the number of bits in an @code{int}.
1710 Empty classes can be placed at incorrect offsets. For example:
1720 struct C : public B, public A @{@};
1724 G++ will place the @code{A} base class of @code{C} at a nonzero offset;
1725 it should be placed at offset zero. G++ mistakenly believes that the
1726 @code{A} data member of @code{B} is already at offset zero.
1729 Names of template functions whose types involve @code{typename} or
1730 template template parameters can be mangled incorrectly.
1733 template <typename Q>
1734 void f(typename Q::X) @{@}
1736 template <template <typename> class Q>
1737 void f(typename Q<int>::X) @{@}
1741 Instantiations of these templates may be mangled incorrectly.
1745 @item -Wctor-dtor-privacy @r{(C++ only)}
1746 @opindex Wctor-dtor-privacy
1747 Warn when a class seems unusable because all the constructors or
1748 destructors in that class are private, and it has neither friends nor
1749 public static member functions.
1751 @item -Wnon-virtual-dtor @r{(C++ only)}
1752 @opindex Wnon-virtual-dtor
1753 Warn when a class appears to be polymorphic, thereby requiring a virtual
1754 destructor, yet it declares a non-virtual one. This warning is also
1755 enabled if -Weffc++ is specified.
1757 @item -Wreorder @r{(C++ only)}
1759 @cindex reordering, warning
1760 @cindex warning for reordering of member initializers
1761 Warn when the order of member initializers given in the code does not
1762 match the order in which they must be executed. For instance:
1768 A(): j (0), i (1) @{ @}
1772 The compiler will rearrange the member initializers for @samp{i}
1773 and @samp{j} to match the declaration order of the members, emitting
1774 a warning to that effect. This warning is enabled by @option{-Wall}.
1777 The following @option{-W@dots{}} options are not affected by @option{-Wall}.
1780 @item -Weffc++ @r{(C++ only)}
1782 Warn about violations of the following style guidelines from Scott Meyers'
1783 @cite{Effective C++} book:
1787 Item 11: Define a copy constructor and an assignment operator for classes
1788 with dynamically allocated memory.
1791 Item 12: Prefer initialization to assignment in constructors.
1794 Item 14: Make destructors virtual in base classes.
1797 Item 15: Have @code{operator=} return a reference to @code{*this}.
1800 Item 23: Don't try to return a reference when you must return an object.
1804 Also warn about violations of the following style guidelines from
1805 Scott Meyers' @cite{More Effective C++} book:
1809 Item 6: Distinguish between prefix and postfix forms of increment and
1810 decrement operators.
1813 Item 7: Never overload @code{&&}, @code{||}, or @code{,}.
1817 When selecting this option, be aware that the standard library
1818 headers do not obey all of these guidelines; use @samp{grep -v}
1819 to filter out those warnings.
1821 @item -Wno-deprecated @r{(C++ only)}
1822 @opindex Wno-deprecated
1823 Do not warn about usage of deprecated features. @xref{Deprecated Features}.
1825 @item -Wstrict-null-sentinel @r{(C++ only)}
1826 @opindex Wstrict-null-sentinel
1827 Warn also about the use of an uncasted @code{NULL} as sentinel. When
1828 compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
1829 to @code{__null}. Although it is a null pointer constant not a null pointer,
1830 it is guaranteed to of the same size as a pointer. But this use is
1831 not portable across different compilers.
1833 @item -Wno-non-template-friend @r{(C++ only)}
1834 @opindex Wno-non-template-friend
1835 Disable warnings when non-templatized friend functions are declared
1836 within a template. Since the advent of explicit template specification
1837 support in G++, if the name of the friend is an unqualified-id (i.e.,
1838 @samp{friend foo(int)}), the C++ language specification demands that the
1839 friend declare or define an ordinary, nontemplate function. (Section
1840 14.5.3). Before G++ implemented explicit specification, unqualified-ids
1841 could be interpreted as a particular specialization of a templatized
1842 function. Because this non-conforming behavior is no longer the default
1843 behavior for G++, @option{-Wnon-template-friend} allows the compiler to
1844 check existing code for potential trouble spots and is on by default.
1845 This new compiler behavior can be turned off with
1846 @option{-Wno-non-template-friend} which keeps the conformant compiler code
1847 but disables the helpful warning.
1849 @item -Wold-style-cast @r{(C++ only)}
1850 @opindex Wold-style-cast
1851 Warn if an old-style (C-style) cast to a non-void type is used within
1852 a C++ program. The new-style casts (@samp{dynamic_cast},
1853 @samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are
1854 less vulnerable to unintended effects and much easier to search for.
1856 @item -Woverloaded-virtual @r{(C++ only)}
1857 @opindex Woverloaded-virtual
1858 @cindex overloaded virtual fn, warning
1859 @cindex warning for overloaded virtual fn
1860 Warn when a function declaration hides virtual functions from a
1861 base class. For example, in:
1868 struct B: public A @{
1873 the @code{A} class version of @code{f} is hidden in @code{B}, and code
1881 will fail to compile.
1883 @item -Wno-pmf-conversions @r{(C++ only)}
1884 @opindex Wno-pmf-conversions
1885 Disable the diagnostic for converting a bound pointer to member function
1888 @item -Wsign-promo @r{(C++ only)}
1889 @opindex Wsign-promo
1890 Warn when overload resolution chooses a promotion from unsigned or
1891 enumerated type to a signed type, over a conversion to an unsigned type of
1892 the same size. Previous versions of G++ would try to preserve
1893 unsignedness, but the standard mandates the current behavior.
1898 A& operator = (int);
1908 In this example, G++ will synthesize a default @samp{A& operator =
1909 (const A&);}, while cfront will use the user-defined @samp{operator =}.
1912 @node Language Independent Options
1913 @section Options to Control Diagnostic Messages Formatting
1914 @cindex options to control diagnostics formatting
1915 @cindex diagnostic messages
1916 @cindex message formatting
1918 Traditionally, diagnostic messages have been formatted irrespective of
1919 the output device's aspect (e.g.@: its width, @dots{}). The options described
1920 below can be used to control the diagnostic messages formatting
1921 algorithm, e.g.@: how many characters per line, how often source location
1922 information should be reported. Right now, only the C++ front end can
1923 honor these options. However it is expected, in the near future, that
1924 the remaining front ends would be able to digest them correctly.
1927 @item -fmessage-length=@var{n}
1928 @opindex fmessage-length
1929 Try to format error messages so that they fit on lines of about @var{n}
1930 characters. The default is 72 characters for @command{g++} and 0 for the rest of
1931 the front ends supported by GCC@. If @var{n} is zero, then no
1932 line-wrapping will be done; each error message will appear on a single
1935 @opindex fdiagnostics-show-location
1936 @item -fdiagnostics-show-location=once
1937 Only meaningful in line-wrapping mode. Instructs the diagnostic messages
1938 reporter to emit @emph{once} source location information; that is, in
1939 case the message is too long to fit on a single physical line and has to
1940 be wrapped, the source location won't be emitted (as prefix) again,
1941 over and over, in subsequent continuation lines. This is the default
1944 @item -fdiagnostics-show-location=every-line
1945 Only meaningful in line-wrapping mode. Instructs the diagnostic
1946 messages reporter to emit the same source location information (as
1947 prefix) for physical lines that result from the process of breaking
1948 a message which is too long to fit on a single line.
1950 @item -fdiagnostics-show-option
1951 @opindex fdiagnostics-show-option
1952 This option instructs the diagnostic machinery to add text to each
1953 diagnostic emitted, which indicates which command line option directly
1954 controls that diagnostic, when such an option is known to the
1955 diagnostic machinery.
1959 @node Warning Options
1960 @section Options to Request or Suppress Warnings
1961 @cindex options to control warnings
1962 @cindex warning messages
1963 @cindex messages, warning
1964 @cindex suppressing warnings
1966 Warnings are diagnostic messages that report constructions which
1967 are not inherently erroneous but which are risky or suggest there
1968 may have been an error.
1970 You can request many specific warnings with options beginning @samp{-W},
1971 for example @option{-Wimplicit} to request warnings on implicit
1972 declarations. Each of these specific warning options also has a
1973 negative form beginning @samp{-Wno-} to turn off warnings;
1974 for example, @option{-Wno-implicit}. This manual lists only one of the
1975 two forms, whichever is not the default.
1977 The following options control the amount and kinds of warnings produced
1978 by GCC; for further, language-specific options also refer to
1979 @ref{C++ Dialect Options}.
1982 @cindex syntax checking
1984 @opindex fsyntax-only
1985 Check the code for syntax errors, but don't do anything beyond that.
1989 Issue all the warnings demanded by strict ISO C and ISO C++;
1990 reject all programs that use forbidden extensions, and some other
1991 programs that do not follow ISO C and ISO C++. For ISO C, follows the
1992 version of the ISO C standard specified by any @option{-std} option used.
1994 Valid ISO C and ISO C++ programs should compile properly with or without
1995 this option (though a rare few will require @option{-ansi} or a
1996 @option{-std} option specifying the required version of ISO C)@. However,
1997 without this option, certain GNU extensions and traditional C and C++
1998 features are supported as well. With this option, they are rejected.
2000 @option{-pedantic} does not cause warning messages for use of the
2001 alternate keywords whose names begin and end with @samp{__}. Pedantic
2002 warnings are also disabled in the expression that follows
2003 @code{__extension__}. However, only system header files should use
2004 these escape routes; application programs should avoid them.
2005 @xref{Alternate Keywords}.
2007 Some users try to use @option{-pedantic} to check programs for strict ISO
2008 C conformance. They soon find that it does not do quite what they want:
2009 it finds some non-ISO practices, but not all---only those for which
2010 ISO C @emph{requires} a diagnostic, and some others for which
2011 diagnostics have been added.
2013 A feature to report any failure to conform to ISO C might be useful in
2014 some instances, but would require considerable additional work and would
2015 be quite different from @option{-pedantic}. We don't have plans to
2016 support such a feature in the near future.
2018 Where the standard specified with @option{-std} represents a GNU
2019 extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
2020 corresponding @dfn{base standard}, the version of ISO C on which the GNU
2021 extended dialect is based. Warnings from @option{-pedantic} are given
2022 where they are required by the base standard. (It would not make sense
2023 for such warnings to be given only for features not in the specified GNU
2024 C dialect, since by definition the GNU dialects of C include all
2025 features the compiler supports with the given option, and there would be
2026 nothing to warn about.)
2028 @item -pedantic-errors
2029 @opindex pedantic-errors
2030 Like @option{-pedantic}, except that errors are produced rather than
2035 Inhibit all warning messages.
2039 Inhibit warning messages about the use of @samp{#import}.
2041 @item -Wchar-subscripts
2042 @opindex Wchar-subscripts
2043 Warn if an array subscript has type @code{char}. This is a common cause
2044 of error, as programmers often forget that this type is signed on some
2046 This warning is enabled by @option{-Wall}.
2050 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
2051 comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
2052 This warning is enabled by @option{-Wall}.
2054 @item -Wfatal-errors
2055 @opindex Wfatal-errors
2056 This option causes the compiler to abort compilation on the first error
2057 occurred rather than trying to keep going and printing further error
2062 @opindex ffreestanding
2063 @opindex fno-builtin
2064 Check calls to @code{printf} and @code{scanf}, etc., to make sure that
2065 the arguments supplied have types appropriate to the format string
2066 specified, and that the conversions specified in the format string make
2067 sense. This includes standard functions, and others specified by format
2068 attributes (@pxref{Function Attributes}), in the @code{printf},
2069 @code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
2070 not in the C standard) families (or other target-specific families).
2071 Which functions are checked without format attributes having been
2072 specified depends on the standard version selected, and such checks of
2073 functions without the attribute specified are disabled by
2074 @option{-ffreestanding} or @option{-fno-builtin}.
2076 The formats are checked against the format features supported by GNU
2077 libc version 2.2. These include all ISO C90 and C99 features, as well
2078 as features from the Single Unix Specification and some BSD and GNU
2079 extensions. Other library implementations may not support all these
2080 features; GCC does not support warning about features that go beyond a
2081 particular library's limitations. However, if @option{-pedantic} is used
2082 with @option{-Wformat}, warnings will be given about format features not
2083 in the selected standard version (but not for @code{strfmon} formats,
2084 since those are not in any version of the C standard). @xref{C Dialect
2085 Options,,Options Controlling C Dialect}.
2087 Since @option{-Wformat} also checks for null format arguments for
2088 several functions, @option{-Wformat} also implies @option{-Wnonnull}.
2090 @option{-Wformat} is included in @option{-Wall}. For more control over some
2091 aspects of format checking, the options @option{-Wformat-y2k},
2092 @option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
2093 @option{-Wformat-nonliteral}, @option{-Wformat-security}, and
2094 @option{-Wformat=2} are available, but are not included in @option{-Wall}.
2097 @opindex Wformat-y2k
2098 If @option{-Wformat} is specified, also warn about @code{strftime}
2099 formats which may yield only a two-digit year.
2101 @item -Wno-format-extra-args
2102 @opindex Wno-format-extra-args
2103 If @option{-Wformat} is specified, do not warn about excess arguments to a
2104 @code{printf} or @code{scanf} format function. The C standard specifies
2105 that such arguments are ignored.
2107 Where the unused arguments lie between used arguments that are
2108 specified with @samp{$} operand number specifications, normally
2109 warnings are still given, since the implementation could not know what
2110 type to pass to @code{va_arg} to skip the unused arguments. However,
2111 in the case of @code{scanf} formats, this option will suppress the
2112 warning if the unused arguments are all pointers, since the Single
2113 Unix Specification says that such unused arguments are allowed.
2115 @item -Wno-format-zero-length
2116 @opindex Wno-format-zero-length
2117 If @option{-Wformat} is specified, do not warn about zero-length formats.
2118 The C standard specifies that zero-length formats are allowed.
2120 @item -Wformat-nonliteral
2121 @opindex Wformat-nonliteral
2122 If @option{-Wformat} is specified, also warn if the format string is not a
2123 string literal and so cannot be checked, unless the format function
2124 takes its format arguments as a @code{va_list}.
2126 @item -Wformat-security
2127 @opindex Wformat-security
2128 If @option{-Wformat} is specified, also warn about uses of format
2129 functions that represent possible security problems. At present, this
2130 warns about calls to @code{printf} and @code{scanf} functions where the
2131 format string is not a string literal and there are no format arguments,
2132 as in @code{printf (foo);}. This may be a security hole if the format
2133 string came from untrusted input and contains @samp{%n}. (This is
2134 currently a subset of what @option{-Wformat-nonliteral} warns about, but
2135 in future warnings may be added to @option{-Wformat-security} that are not
2136 included in @option{-Wformat-nonliteral}.)
2140 Enable @option{-Wformat} plus format checks not included in
2141 @option{-Wformat}. Currently equivalent to @samp{-Wformat
2142 -Wformat-nonliteral -Wformat-security -Wformat-y2k}.
2146 Warn about passing a null pointer for arguments marked as
2147 requiring a non-null value by the @code{nonnull} function attribute.
2149 @option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It
2150 can be disabled with the @option{-Wno-nonnull} option.
2152 @item -Winit-self @r{(C and C++ only)}
2154 Warn about uninitialized variables which are initialized with themselves.
2155 Note this option can only be used with the @option{-Wuninitialized} option,
2156 which in turn only works with @option{-O1} and above.
2158 For example, GCC will warn about @code{i} being uninitialized in the
2159 following snippet only when @option{-Winit-self} has been specified:
2170 @item -Wimplicit-int
2171 @opindex Wimplicit-int
2172 Warn when a declaration does not specify a type.
2173 This warning is enabled by @option{-Wall}.
2175 @item -Wimplicit-function-declaration
2176 @itemx -Werror-implicit-function-declaration
2177 @opindex Wimplicit-function-declaration
2178 @opindex Werror-implicit-function-declaration
2179 Give a warning (or error) whenever a function is used before being
2180 declared. The form @option{-Wno-error-implicit-function-declaration}
2182 This warning is enabled by @option{-Wall} (as a warning, not an error).
2186 Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
2187 This warning is enabled by @option{-Wall}.
2191 Warn if the type of @samp{main} is suspicious. @samp{main} should be a
2192 function with external linkage, returning int, taking either zero
2193 arguments, two, or three arguments of appropriate types.
2194 This warning is enabled by @option{-Wall}.
2196 @item -Wmissing-braces
2197 @opindex Wmissing-braces
2198 Warn if an aggregate or union initializer is not fully bracketed. In
2199 the following example, the initializer for @samp{a} is not fully
2200 bracketed, but that for @samp{b} is fully bracketed.
2203 int a[2][2] = @{ 0, 1, 2, 3 @};
2204 int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
2207 This warning is enabled by @option{-Wall}.
2209 @item -Wmissing-include-dirs @r{(C and C++ only)}
2210 @opindex Wmissing-include-dirs
2211 Warn if a user-supplied include directory does not exist.
2214 @opindex Wparentheses
2215 Warn if parentheses are omitted in certain contexts, such
2216 as when there is an assignment in a context where a truth value
2217 is expected, or when operators are nested whose precedence people
2218 often get confused about.
2220 Also warn if a comparison like @samp{x<=y<=z} appears; this is
2221 equivalent to @samp{(x<=y ? 1 : 0) <= z}, which is a different
2222 interpretation from that of ordinary mathematical notation.
2224 Also warn about constructions where there may be confusion to which
2225 @code{if} statement an @code{else} branch belongs. Here is an example of
2240 In C/C++, every @code{else} branch belongs to the innermost possible
2241 @code{if} statement, which in this example is @code{if (b)}. This is
2242 often not what the programmer expected, as illustrated in the above
2243 example by indentation the programmer chose. When there is the
2244 potential for this confusion, GCC will issue a warning when this flag
2245 is specified. To eliminate the warning, add explicit braces around
2246 the innermost @code{if} statement so there is no way the @code{else}
2247 could belong to the enclosing @code{if}. The resulting code would
2264 This warning is enabled by @option{-Wall}.
2266 @item -Wsequence-point
2267 @opindex Wsequence-point
2268 Warn about code that may have undefined semantics because of violations
2269 of sequence point rules in the C and C++ standards.
2271 The C and C++ standards defines the order in which expressions in a C/C++
2272 program are evaluated in terms of @dfn{sequence points}, which represent
2273 a partial ordering between the execution of parts of the program: those
2274 executed before the sequence point, and those executed after it. These
2275 occur after the evaluation of a full expression (one which is not part
2276 of a larger expression), after the evaluation of the first operand of a
2277 @code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
2278 function is called (but after the evaluation of its arguments and the
2279 expression denoting the called function), and in certain other places.
2280 Other than as expressed by the sequence point rules, the order of
2281 evaluation of subexpressions of an expression is not specified. All
2282 these rules describe only a partial order rather than a total order,
2283 since, for example, if two functions are called within one expression
2284 with no sequence point between them, the order in which the functions
2285 are called is not specified. However, the standards committee have
2286 ruled that function calls do not overlap.
2288 It is not specified when between sequence points modifications to the
2289 values of objects take effect. Programs whose behavior depends on this
2290 have undefined behavior; the C and C++ standards specify that ``Between
2291 the previous and next sequence point an object shall have its stored
2292 value modified at most once by the evaluation of an expression.
2293 Furthermore, the prior value shall be read only to determine the value
2294 to be stored.''. If a program breaks these rules, the results on any
2295 particular implementation are entirely unpredictable.
2297 Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
2298 = b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
2299 diagnosed by this option, and it may give an occasional false positive
2300 result, but in general it has been found fairly effective at detecting
2301 this sort of problem in programs.
2303 The standard is worded confusingly, therefore there is some debate
2304 over the precise meaning of the sequence point rules in subtle cases.
2305 Links to discussions of the problem, including proposed formal
2306 definitions, may be found on the GCC readings page, at
2307 @w{@uref{http://gcc.gnu.org/readings.html}}.
2309 This warning is enabled by @option{-Wall} for C and C++.
2312 @opindex Wreturn-type
2313 Warn whenever a function is defined with a return-type that defaults to
2314 @code{int}. Also warn about any @code{return} statement with no
2315 return-value in a function whose return-type is not @code{void}.
2317 For C, also warn if the return type of a function has a type qualifier
2318 such as @code{const}. Such a type qualifier has no effect, since the
2319 value returned by a function is not an lvalue. ISO C prohibits
2320 qualified @code{void} return types on function definitions, so such
2321 return types always receive a warning even without this option.
2323 For C++, a function without return type always produces a diagnostic
2324 message, even when @option{-Wno-return-type} is specified. The only
2325 exceptions are @samp{main} and functions defined in system headers.
2327 This warning is enabled by @option{-Wall}.
2331 Warn whenever a @code{switch} statement has an index of enumerated type
2332 and lacks a @code{case} for one or more of the named codes of that
2333 enumeration. (The presence of a @code{default} label prevents this
2334 warning.) @code{case} labels outside the enumeration range also
2335 provoke warnings when this option is used.
2336 This warning is enabled by @option{-Wall}.
2338 @item -Wswitch-default
2339 @opindex Wswitch-switch
2340 Warn whenever a @code{switch} statement does not have a @code{default}
2344 @opindex Wswitch-enum
2345 Warn whenever a @code{switch} statement has an index of enumerated type
2346 and lacks a @code{case} for one or more of the named codes of that
2347 enumeration. @code{case} labels outside the enumeration range also
2348 provoke warnings when this option is used.
2352 Warn if any trigraphs are encountered that might change the meaning of
2353 the program (trigraphs within comments are not warned about).
2354 This warning is enabled by @option{-Wall}.
2356 @item -Wunused-function
2357 @opindex Wunused-function
2358 Warn whenever a static function is declared but not defined or a
2359 non-inline static function is unused.
2360 This warning is enabled by @option{-Wall}.
2362 @item -Wunused-label
2363 @opindex Wunused-label
2364 Warn whenever a label is declared but not used.
2365 This warning is enabled by @option{-Wall}.
2367 To suppress this warning use the @samp{unused} attribute
2368 (@pxref{Variable Attributes}).
2370 @item -Wunused-parameter
2371 @opindex Wunused-parameter
2372 Warn whenever a function parameter is unused aside from its declaration.
2374 To suppress this warning use the @samp{unused} attribute
2375 (@pxref{Variable Attributes}).
2377 @item -Wunused-variable
2378 @opindex Wunused-variable
2379 Warn whenever a local variable or non-constant static variable is unused
2380 aside from its declaration.
2381 This warning is enabled by @option{-Wall}.
2383 To suppress this warning use the @samp{unused} attribute
2384 (@pxref{Variable Attributes}).
2386 @item -Wunused-value
2387 @opindex Wunused-value
2388 Warn whenever a statement computes a result that is explicitly not used.
2389 This warning is enabled by @option{-Wall}.
2391 To suppress this warning cast the expression to @samp{void}.
2395 All the above @option{-Wunused} options combined.
2397 In order to get a warning about an unused function parameter, you must
2398 either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
2399 @samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
2401 @item -Wuninitialized
2402 @opindex Wuninitialized
2403 Warn if an automatic variable is used without first being initialized or
2404 if a variable may be clobbered by a @code{setjmp} call.
2406 These warnings are possible only in optimizing compilation,
2407 because they require data flow information that is computed only
2408 when optimizing. If you do not specify @option{-O}, you will not get
2409 these warnings. Instead, GCC will issue a warning about @option{-Wuninitialized}
2410 requiring @option{-O}.
2412 If you want to warn about code which uses the uninitialized value of the
2413 variable in its own initializer, use the @option{-Winit-self} option.
2415 These warnings occur for individual uninitialized or clobbered
2416 elements of structure, union or array variables as well as for
2417 variables which are uninitialized or clobbered as a whole. They do
2418 not occur for variables or elements declared @code{volatile}. Because
2419 these warnings depend on optimization, the exact variables or elements
2420 for which there are warnings will depend on the precise optimization
2421 options and version of GCC used.
2423 Note that there may be no warning about a variable that is used only
2424 to compute a value that itself is never used, because such
2425 computations may be deleted by data flow analysis before the warnings
2428 These warnings are made optional because GCC is not smart
2429 enough to see all the reasons why the code might be correct
2430 despite appearing to have an error. Here is one example of how
2451 If the value of @code{y} is always 1, 2 or 3, then @code{x} is
2452 always initialized, but GCC doesn't know this. Here is
2453 another common case:
2458 if (change_y) save_y = y, y = new_y;
2460 if (change_y) y = save_y;
2465 This has no bug because @code{save_y} is used only if it is set.
2467 @cindex @code{longjmp} warnings
2468 This option also warns when a non-volatile automatic variable might be
2469 changed by a call to @code{longjmp}. These warnings as well are possible
2470 only in optimizing compilation.
2472 The compiler sees only the calls to @code{setjmp}. It cannot know
2473 where @code{longjmp} will be called; in fact, a signal handler could
2474 call it at any point in the code. As a result, you may get a warning
2475 even when there is in fact no problem because @code{longjmp} cannot
2476 in fact be called at the place which would cause a problem.
2478 Some spurious warnings can be avoided if you declare all the functions
2479 you use that never return as @code{noreturn}. @xref{Function
2482 This warning is enabled by @option{-Wall}.
2484 @item -Wunknown-pragmas
2485 @opindex Wunknown-pragmas
2486 @cindex warning for unknown pragmas
2487 @cindex unknown pragmas, warning
2488 @cindex pragmas, warning of unknown
2489 Warn when a #pragma directive is encountered which is not understood by
2490 GCC@. If this command line option is used, warnings will even be issued
2491 for unknown pragmas in system header files. This is not the case if
2492 the warnings were only enabled by the @option{-Wall} command line option.
2495 @opindex Wno-pragmas
2497 Do not warn about misuses of pragmas, such as incorrect parameters,
2498 invalid syntax, or conflicts between pragmas. See also
2499 @samp{-Wunknown-pragmas}.
2501 @item -Wstrict-aliasing
2502 @opindex Wstrict-aliasing
2503 This option is only active when @option{-fstrict-aliasing} is active.
2504 It warns about code which might break the strict aliasing rules that the
2505 compiler is using for optimization. The warning does not catch all
2506 cases, but does attempt to catch the more common pitfalls. It is
2507 included in @option{-Wall}.
2509 @item -Wstrict-aliasing=2
2510 @opindex Wstrict-aliasing=2
2511 This option is only active when @option{-fstrict-aliasing} is active.
2512 It warns about code which might break the strict aliasing rules that the
2513 compiler is using for optimization. This warning catches more cases than
2514 @option{-Wstrict-aliasing}, but it will also give a warning for some ambiguous
2515 cases that are safe.
2517 @item -Wstrict-overflow
2518 @item -Wstrict-overflow=@var{n}
2519 @opindex Wstrict-overflow
2520 This option is only active when @option{-fstrict-overflow} is active.
2521 It warns about cases where the compiler optimizes based on the
2522 assumption that signed overflow does not occur. Note that it does not
2523 warn about all cases where the code might overflow: it only warns
2524 about cases where the compiler implements some optimization. Thus
2525 this warning depends on the optimization level.
2527 An optimization which assumes that signed overflow does not occur is
2528 perfectly safe if the values of the variables involved are such that
2529 overflow never does, in fact, occur. Therefore this warning can
2530 easily give a false positive: a warning about code which is not
2531 actually a problem. To help focus on important issues, several
2532 warning levels are defined. No warnings are issued for the use of
2533 undefined signed overflow when estimating how many iterations a loop
2534 will require, in particular when determining whether a loop will be
2538 @item -Wstrict-overflow=1
2539 Warn about cases which are both questionable and easy to avoid. For
2540 example: @code{x + 1 > x}; with @option{-fstrict-overflow}, the
2541 compiler will simplify this to @code{1}. This level of
2542 @option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
2543 are not, and must be explicitly requested.
2545 @item -Wstrict-overflow=2
2546 Also warn about other cases where a comparison is simplified to a
2547 constant. For example: @code{abs (x) >= 0}. This can only be
2548 simplified when @option{-fstrict-overflow} is in effect, because
2549 @code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
2550 zero. @option{-Wstrict-overflow} (with no level) is the same as
2551 @option{-Wstrict-overflow=2}.
2553 @item -Wstrict-overflow=3
2554 Also warn about other cases where a comparison is simplified. For
2555 example: @code{x + 1 > 1} will be simplified to @code{x > 0}.
2557 @item -Wstrict-overflow=4
2558 Also warn about other simplifications not covered by the above cases.
2559 For example: @code{(x * 10) / 5} will be simplified to @code{x * 2}.
2561 @item -Wstrict-overflow=5
2562 Also warn about cases where the compiler reduces the magnitude of a
2563 constant involved in a comparison. For example: @code{x + 2 > y} will
2564 be simplified to @code{x + 1 >= y}. This is reported only at the
2565 highest warning level because this simplification applies to many
2566 comparisons, so this warning level will give a very large number of
2572 All of the above @samp{-W} options combined. This enables all the
2573 warnings about constructions that some users consider questionable, and
2574 that are easy to avoid (or modify to prevent the warning), even in
2575 conjunction with macros. This also enables some language-specific
2576 warnings described in @ref{C++ Dialect Options}.
2579 The following @option{-W@dots{}} options are not implied by @option{-Wall}.
2580 Some of them warn about constructions that users generally do not
2581 consider questionable, but which occasionally you might wish to check
2582 for; others warn about constructions that are necessary or hard to avoid
2583 in some cases, and there is no simple way to modify the code to suppress
2590 (This option used to be called @option{-W}. The older name is still
2591 supported, but the newer name is more descriptive.) Print extra warning
2592 messages for these events:
2596 A function can return either with or without a value. (Falling
2597 off the end of the function body is considered returning without
2598 a value.) For example, this function would evoke such a
2612 An expression-statement or the left-hand side of a comma expression
2613 contains no side effects.
2614 To suppress the warning, cast the unused expression to void.
2615 For example, an expression such as @samp{x[i,j]} will cause a warning,
2616 but @samp{x[(void)i,j]} will not.
2619 An unsigned value is compared against zero with @samp{<} or @samp{>=}.
2622 Storage-class specifiers like @code{static} are not the first things in
2623 a declaration. According to the C Standard, this usage is obsolescent.
2626 If @option{-Wall} or @option{-Wunused} is also specified, warn about unused
2630 A comparison between signed and unsigned values could produce an
2631 incorrect result when the signed value is converted to unsigned.
2632 (But don't warn if @option{-Wno-sign-compare} is also specified.)
2635 An aggregate has an initializer which does not initialize all members.
2636 This warning can be independently controlled by
2637 @option{-Wmissing-field-initializers}.
2640 An initialized field without side effects is overridden when using
2641 designated initializers (@pxref{Designated Inits, , Designated
2642 Initializers}). This warning can be independently controlled by
2643 @option{-Woverride-init}.
2646 A function parameter is declared without a type specifier in K&R-style
2654 An empty body occurs in an @samp{if} or @samp{else} statement.
2657 A pointer is compared against integer zero with @samp{<}, @samp{<=},
2658 @samp{>}, or @samp{>=}.
2661 A variable might be changed by @samp{longjmp} or @samp{vfork}.
2663 @item @r{(C++ only)}
2664 An enumerator and a non-enumerator both appear in a conditional expression.
2666 @item @r{(C++ only)}
2667 A non-static reference or non-static @samp{const} member appears in a
2668 class without constructors.
2670 @item @r{(C++ only)}
2671 Ambiguous virtual bases.
2673 @item @r{(C++ only)}
2674 Subscripting an array which has been declared @samp{register}.
2676 @item @r{(C++ only)}
2677 Taking the address of a variable which has been declared @samp{register}.
2679 @item @r{(C++ only)}
2680 A base class is not initialized in a derived class' copy constructor.
2683 @item -Wno-div-by-zero
2684 @opindex Wno-div-by-zero
2685 @opindex Wdiv-by-zero
2686 Do not warn about compile-time integer division by zero. Floating point
2687 division by zero is not warned about, as it can be a legitimate way of
2688 obtaining infinities and NaNs.
2690 @item -Wsystem-headers
2691 @opindex Wsystem-headers
2692 @cindex warnings from system headers
2693 @cindex system headers, warnings from
2694 Print warning messages for constructs found in system header files.
2695 Warnings from system headers are normally suppressed, on the assumption
2696 that they usually do not indicate real problems and would only make the
2697 compiler output harder to read. Using this command line option tells
2698 GCC to emit warnings from system headers as if they occurred in user
2699 code. However, note that using @option{-Wall} in conjunction with this
2700 option will @emph{not} warn about unknown pragmas in system
2701 headers---for that, @option{-Wunknown-pragmas} must also be used.
2704 @opindex Wfloat-equal
2705 Warn if floating point values are used in equality comparisons.
2707 The idea behind this is that sometimes it is convenient (for the
2708 programmer) to consider floating-point values as approximations to
2709 infinitely precise real numbers. If you are doing this, then you need
2710 to compute (by analyzing the code, or in some other way) the maximum or
2711 likely maximum error that the computation introduces, and allow for it
2712 when performing comparisons (and when producing output, but that's a
2713 different problem). In particular, instead of testing for equality, you
2714 would check to see whether the two values have ranges that overlap; and
2715 this is done with the relational operators, so equality comparisons are
2718 @item -Wtraditional @r{(C only)}
2719 @opindex Wtraditional
2720 Warn about certain constructs that behave differently in traditional and
2721 ISO C@. Also warn about ISO C constructs that have no traditional C
2722 equivalent, and/or problematic constructs which should be avoided.
2726 Macro parameters that appear within string literals in the macro body.
2727 In traditional C macro replacement takes place within string literals,
2728 but does not in ISO C@.
2731 In traditional C, some preprocessor directives did not exist.
2732 Traditional preprocessors would only consider a line to be a directive
2733 if the @samp{#} appeared in column 1 on the line. Therefore
2734 @option{-Wtraditional} warns about directives that traditional C
2735 understands but would ignore because the @samp{#} does not appear as the
2736 first character on the line. It also suggests you hide directives like
2737 @samp{#pragma} not understood by traditional C by indenting them. Some
2738 traditional implementations would not recognize @samp{#elif}, so it
2739 suggests avoiding it altogether.
2742 A function-like macro that appears without arguments.
2745 The unary plus operator.
2748 The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
2749 constant suffixes. (Traditional C does support the @samp{L} suffix on integer
2750 constants.) Note, these suffixes appear in macros defined in the system
2751 headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
2752 Use of these macros in user code might normally lead to spurious
2753 warnings, however GCC's integrated preprocessor has enough context to
2754 avoid warning in these cases.
2757 A function declared external in one block and then used after the end of
2761 A @code{switch} statement has an operand of type @code{long}.
2764 A non-@code{static} function declaration follows a @code{static} one.
2765 This construct is not accepted by some traditional C compilers.
2768 The ISO type of an integer constant has a different width or
2769 signedness from its traditional type. This warning is only issued if
2770 the base of the constant is ten. I.e.@: hexadecimal or octal values, which
2771 typically represent bit patterns, are not warned about.
2774 Usage of ISO string concatenation is detected.
2777 Initialization of automatic aggregates.
2780 Identifier conflicts with labels. Traditional C lacks a separate
2781 namespace for labels.
2784 Initialization of unions. If the initializer is zero, the warning is
2785 omitted. This is done under the assumption that the zero initializer in
2786 user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
2787 initializer warnings and relies on default initialization to zero in the
2791 Conversions by prototypes between fixed/floating point values and vice
2792 versa. The absence of these prototypes when compiling with traditional
2793 C would cause serious problems. This is a subset of the possible
2794 conversion warnings, for the full set use @option{-Wconversion}.
2797 Use of ISO C style function definitions. This warning intentionally is
2798 @emph{not} issued for prototype declarations or variadic functions
2799 because these ISO C features will appear in your code when using
2800 libiberty's traditional C compatibility macros, @code{PARAMS} and
2801 @code{VPARAMS}. This warning is also bypassed for nested functions
2802 because that feature is already a GCC extension and thus not relevant to
2803 traditional C compatibility.
2806 @item -Wdeclaration-after-statement @r{(C only)}
2807 @opindex Wdeclaration-after-statement
2808 Warn when a declaration is found after a statement in a block. This
2809 construct, known from C++, was introduced with ISO C99 and is by default
2810 allowed in GCC@. It is not supported by ISO C90 and was not supported by
2811 GCC versions before GCC 3.0. @xref{Mixed Declarations}.
2815 Warn if an undefined identifier is evaluated in an @samp{#if} directive.
2817 @item -Wno-endif-labels
2818 @opindex Wno-endif-labels
2819 @opindex Wendif-labels
2820 Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
2824 Warn whenever a local variable shadows another local variable, parameter or
2825 global variable or whenever a built-in function is shadowed.
2827 @item -Wlarger-than-@var{len}
2828 @opindex Wlarger-than
2829 Warn whenever an object of larger than @var{len} bytes is defined.
2831 @item -Wunsafe-loop-optimizations
2832 @opindex Wunsafe-loop-optimizations
2833 Warn if the loop cannot be optimized because the compiler could not
2834 assume anything on the bounds of the loop indices. With
2835 @option{-funsafe-loop-optimizations} warn if the compiler made
2838 @item -Wpointer-arith
2839 @opindex Wpointer-arith
2840 Warn about anything that depends on the ``size of'' a function type or
2841 of @code{void}. GNU C assigns these types a size of 1, for
2842 convenience in calculations with @code{void *} pointers and pointers
2845 @item -Wbad-function-cast @r{(C only)}
2846 @opindex Wbad-function-cast
2847 Warn whenever a function call is cast to a non-matching type.
2848 For example, warn if @code{int malloc()} is cast to @code{anything *}.
2851 Warn about ISO C constructs that are outside of the common subset of
2852 ISO C and ISO C++, e.g.@: request for implicit conversion from
2853 @code{void *} to a pointer to non-@code{void} type.
2857 Warn whenever a pointer is cast so as to remove a type qualifier from
2858 the target type. For example, warn if a @code{const char *} is cast
2859 to an ordinary @code{char *}.
2862 @opindex Wcast-align
2863 Warn whenever a pointer is cast such that the required alignment of the
2864 target is increased. For example, warn if a @code{char *} is cast to
2865 an @code{int *} on machines where integers can only be accessed at
2866 two- or four-byte boundaries.
2868 @item -Wwrite-strings
2869 @opindex Wwrite-strings
2870 When compiling C, give string constants the type @code{const
2871 char[@var{length}]} so that
2872 copying the address of one into a non-@code{const} @code{char *}
2873 pointer will get a warning; when compiling C++, warn about the
2874 deprecated conversion from string literals to @code{char *}. This
2875 warning, by default, is enabled for C++ programs.
2876 These warnings will help you find at
2877 compile time code that can try to write into a string constant, but
2878 only if you have been very careful about using @code{const} in
2879 declarations and prototypes. Otherwise, it will just be a nuisance;
2880 this is why we did not make @option{-Wall} request these warnings.
2883 @opindex Wconversion
2884 Warn if a prototype causes a type conversion that is different from what
2885 would happen to the same argument in the absence of a prototype. This
2886 includes conversions of fixed point to floating and vice versa, and
2887 conversions changing the width or signedness of a fixed point argument
2888 except when the same as the default promotion.
2890 Also, warn if a negative integer constant expression is implicitly
2891 converted to an unsigned type. For example, warn about the assignment
2892 @code{x = -1} if @code{x} is unsigned. But do not warn about explicit
2893 casts like @code{(unsigned) -1}.
2895 @item -Wsign-compare
2896 @opindex Wsign-compare
2897 @cindex warning for comparison of signed and unsigned values
2898 @cindex comparison of signed and unsigned values, warning
2899 @cindex signed and unsigned values, comparison warning
2900 Warn when a comparison between signed and unsigned values could produce
2901 an incorrect result when the signed value is converted to unsigned.
2902 This warning is also enabled by @option{-Wextra}; to get the other warnings
2903 of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
2907 @opindex Wno-address
2908 Warn about suspicious uses of memory addresses. These include using
2909 the address of a function in a conditional expression, such as
2910 @code{void func(void); if (func)}, and comparisons against the memory
2911 address of a string literal, such as @code{if (x == "abc")}. Such
2912 uses typically indicate a programmer error: the address of a function
2913 always evaluates to true, so their use in a conditional usually
2914 indicate that the programmer forgot the parentheses in a function
2915 call; and comparisons against string literals result in unspecified
2916 behavior and are not portable in C, so they usually indicate that the
2917 programmer intended to use @code{strcmp}. This warning is enabled by
2920 @item -Waggregate-return
2921 @opindex Waggregate-return
2922 Warn if any functions that return structures or unions are defined or
2923 called. (In languages where you can return an array, this also elicits
2926 @item -Wno-attributes
2927 @opindex Wno-attributes
2928 @opindex Wattributes
2929 Do not warn if an unexpected @code{__attribute__} is used, such as
2930 unrecognized attributes, function attributes applied to variables,
2931 etc. This will not stop errors for incorrect use of supported
2934 @item -Wstrict-prototypes @r{(C only)}
2935 @opindex Wstrict-prototypes
2936 Warn if a function is declared or defined without specifying the
2937 argument types. (An old-style function definition is permitted without
2938 a warning if preceded by a declaration which specifies the argument
2941 @item -Wold-style-definition @r{(C only)}
2942 @opindex Wold-style-definition
2943 Warn if an old-style function definition is used. A warning is given
2944 even if there is a previous prototype.
2946 @item -Wmissing-prototypes @r{(C only)}
2947 @opindex Wmissing-prototypes
2948 Warn if a global function is defined without a previous prototype
2949 declaration. This warning is issued even if the definition itself
2950 provides a prototype. The aim is to detect global functions that fail
2951 to be declared in header files.
2953 @item -Wmissing-declarations @r{(C only)}
2954 @opindex Wmissing-declarations
2955 Warn if a global function is defined without a previous declaration.
2956 Do so even if the definition itself provides a prototype.
2957 Use this option to detect global functions that are not declared in
2960 @item -Wmissing-field-initializers
2961 @opindex Wmissing-field-initializers
2964 Warn if a structure's initializer has some fields missing. For
2965 example, the following code would cause such a warning, because
2966 @code{x.h} is implicitly zero:
2969 struct s @{ int f, g, h; @};
2970 struct s x = @{ 3, 4 @};
2973 This option does not warn about designated initializers, so the following
2974 modification would not trigger a warning:
2977 struct s @{ int f, g, h; @};
2978 struct s x = @{ .f = 3, .g = 4 @};
2981 This warning is included in @option{-Wextra}. To get other @option{-Wextra}
2982 warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
2984 @item -Wmissing-noreturn
2985 @opindex Wmissing-noreturn
2986 Warn about functions which might be candidates for attribute @code{noreturn}.
2987 Note these are only possible candidates, not absolute ones. Care should
2988 be taken to manually verify functions actually do not ever return before
2989 adding the @code{noreturn} attribute, otherwise subtle code generation
2990 bugs could be introduced. You will not get a warning for @code{main} in
2991 hosted C environments.
2993 @item -Wmissing-format-attribute
2994 @opindex Wmissing-format-attribute
2996 Warn about function pointers which might be candidates for @code{format}
2997 attributes. Note these are only possible candidates, not absolute ones.
2998 GCC will guess that function pointers with @code{format} attributes that
2999 are used in assignment, initialization, parameter passing or return
3000 statements should have a corresponding @code{format} attribute in the
3001 resulting type. I.e.@: the left-hand side of the assignment or
3002 initialization, the type of the parameter variable, or the return type
3003 of the containing function respectively should also have a @code{format}
3004 attribute to avoid the warning.
3006 GCC will also warn about function definitions which might be
3007 candidates for @code{format} attributes. Again, these are only
3008 possible candidates. GCC will guess that @code{format} attributes
3009 might be appropriate for any function that calls a function like
3010 @code{vprintf} or @code{vscanf}, but this might not always be the
3011 case, and some functions for which @code{format} attributes are
3012 appropriate may not be detected.
3014 @item -Wno-multichar
3015 @opindex Wno-multichar
3017 Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
3018 Usually they indicate a typo in the user's code, as they have
3019 implementation-defined values, and should not be used in portable code.
3021 @item -Wnormalized=<none|id|nfc|nfkc>
3022 @opindex Wnormalized
3025 @cindex character set, input normalization
3026 In ISO C and ISO C++, two identifiers are different if they are
3027 different sequences of characters. However, sometimes when characters
3028 outside the basic ASCII character set are used, you can have two
3029 different character sequences that look the same. To avoid confusion,
3030 the ISO 10646 standard sets out some @dfn{normalization rules} which
3031 when applied ensure that two sequences that look the same are turned into
3032 the same sequence. GCC can warn you if you are using identifiers which
3033 have not been normalized; this option controls that warning.
3035 There are four levels of warning that GCC supports. The default is
3036 @option{-Wnormalized=nfc}, which warns about any identifier which is
3037 not in the ISO 10646 ``C'' normalized form, @dfn{NFC}. NFC is the
3038 recommended form for most uses.
3040 Unfortunately, there are some characters which ISO C and ISO C++ allow
3041 in identifiers that when turned into NFC aren't allowable as
3042 identifiers. That is, there's no way to use these symbols in portable
3043 ISO C or C++ and have all your identifiers in NFC.
3044 @option{-Wnormalized=id} suppresses the warning for these characters.
3045 It is hoped that future versions of the standards involved will correct
3046 this, which is why this option is not the default.
3048 You can switch the warning off for all characters by writing
3049 @option{-Wnormalized=none}. You would only want to do this if you
3050 were using some other normalization scheme (like ``D''), because
3051 otherwise you can easily create bugs that are literally impossible to see.
3053 Some characters in ISO 10646 have distinct meanings but look identical
3054 in some fonts or display methodologies, especially once formatting has
3055 been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
3056 LETTER N'', will display just like a regular @code{n} which has been
3057 placed in a superscript. ISO 10646 defines the @dfn{NFKC}
3058 normalization scheme to convert all these into a standard form as
3059 well, and GCC will warn if your code is not in NFKC if you use
3060 @option{-Wnormalized=nfkc}. This warning is comparable to warning
3061 about every identifier that contains the letter O because it might be
3062 confused with the digit 0, and so is not the default, but may be
3063 useful as a local coding convention if the programming environment is
3064 unable to be fixed to display these characters distinctly.
3066 @item -Wno-deprecated-declarations
3067 @opindex Wno-deprecated-declarations
3068 Do not warn about uses of functions (@pxref{Function Attributes}),
3069 variables (@pxref{Variable Attributes}), and types (@pxref{Type
3070 Attributes}) marked as deprecated by using the @code{deprecated}
3074 @opindex Wno-overflow
3075 Do not warn about compile-time overflow in constant expressions.
3077 @item -Woverride-init
3078 @opindex Woverride-init
3081 Warn if an initialized field without side effects is overridden when
3082 using designated initializers (@pxref{Designated Inits, , Designated
3085 This warning is included in @option{-Wextra}. To get other
3086 @option{-Wextra} warnings without this one, use @samp{-Wextra
3087 -Wno-override-init}.
3091 Warn if a structure is given the packed attribute, but the packed
3092 attribute has no effect on the layout or size of the structure.
3093 Such structures may be mis-aligned for little benefit. For
3094 instance, in this code, the variable @code{f.x} in @code{struct bar}
3095 will be misaligned even though @code{struct bar} does not itself
3096 have the packed attribute:
3103 @} __attribute__((packed));
3113 Warn if padding is included in a structure, either to align an element
3114 of the structure or to align the whole structure. Sometimes when this
3115 happens it is possible to rearrange the fields of the structure to
3116 reduce the padding and so make the structure smaller.
3118 @item -Wredundant-decls
3119 @opindex Wredundant-decls
3120 Warn if anything is declared more than once in the same scope, even in
3121 cases where multiple declaration is valid and changes nothing.
3123 @item -Wnested-externs @r{(C only)}
3124 @opindex Wnested-externs
3125 Warn if an @code{extern} declaration is encountered within a function.
3127 @item -Wunreachable-code
3128 @opindex Wunreachable-code
3129 Warn if the compiler detects that code will never be executed.
3131 This option is intended to warn when the compiler detects that at
3132 least a whole line of source code will never be executed, because
3133 some condition is never satisfied or because it is after a
3134 procedure that never returns.
3136 It is possible for this option to produce a warning even though there
3137 are circumstances under which part of the affected line can be executed,
3138 so care should be taken when removing apparently-unreachable code.
3140 For instance, when a function is inlined, a warning may mean that the
3141 line is unreachable in only one inlined copy of the function.
3143 This option is not made part of @option{-Wall} because in a debugging
3144 version of a program there is often substantial code which checks
3145 correct functioning of the program and is, hopefully, unreachable
3146 because the program does work. Another common use of unreachable
3147 code is to provide behavior which is selectable at compile-time.
3151 Warn if a function can not be inlined and it was declared as inline.
3152 Even with this option, the compiler will not warn about failures to
3153 inline functions declared in system headers.
3155 The compiler uses a variety of heuristics to determine whether or not
3156 to inline a function. For example, the compiler takes into account
3157 the size of the function being inlined and the amount of inlining
3158 that has already been done in the current function. Therefore,
3159 seemingly insignificant changes in the source program can cause the
3160 warnings produced by @option{-Winline} to appear or disappear.
3162 @item -Wno-invalid-offsetof @r{(C++ only)}
3163 @opindex Wno-invalid-offsetof
3164 Suppress warnings from applying the @samp{offsetof} macro to a non-POD
3165 type. According to the 1998 ISO C++ standard, applying @samp{offsetof}
3166 to a non-POD type is undefined. In existing C++ implementations,
3167 however, @samp{offsetof} typically gives meaningful results even when
3168 applied to certain kinds of non-POD types. (Such as a simple
3169 @samp{struct} that fails to be a POD type only by virtue of having a
3170 constructor.) This flag is for users who are aware that they are
3171 writing nonportable code and who have deliberately chosen to ignore the
3174 The restrictions on @samp{offsetof} may be relaxed in a future version
3175 of the C++ standard.
3177 @item -Wno-int-to-pointer-cast @r{(C only)}
3178 @opindex Wno-int-to-pointer-cast
3179 Suppress warnings from casts to pointer type of an integer of a
3182 @item -Wno-pointer-to-int-cast @r{(C only)}
3183 @opindex Wno-pointer-to-int-cast
3184 Suppress warnings from casts from a pointer to an integer type of a
3188 @opindex Winvalid-pch
3189 Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
3190 the search path but can't be used.
3194 @opindex Wno-long-long
3195 Warn if @samp{long long} type is used. This is default. To inhibit
3196 the warning messages, use @option{-Wno-long-long}. Flags
3197 @option{-Wlong-long} and @option{-Wno-long-long} are taken into account
3198 only when @option{-pedantic} flag is used.
3200 @item -Wvariadic-macros
3201 @opindex Wvariadic-macros
3202 @opindex Wno-variadic-macros
3203 Warn if variadic macros are used in pedantic ISO C90 mode, or the GNU
3204 alternate syntax when in pedantic ISO C99 mode. This is default.
3205 To inhibit the warning messages, use @option{-Wno-variadic-macros}.
3210 Warn if variable length array is used in the code.
3211 @option{-Wno-vla} will prevent the @option{-pedantic} warning of
3212 the variable length array.
3214 @item -Wvolatile-register-var
3215 @opindex Wvolatile-register-var
3216 @opindex Wno-volatile-register-var
3217 Warn if a register variable is declared volatile. The volatile
3218 modifier does not inhibit all optimizations that may eliminate reads
3219 and/or writes to register variables.
3221 @item -Wdisabled-optimization
3222 @opindex Wdisabled-optimization
3223 Warn if a requested optimization pass is disabled. This warning does
3224 not generally indicate that there is anything wrong with your code; it
3225 merely indicates that GCC's optimizers were unable to handle the code
3226 effectively. Often, the problem is that your code is too big or too
3227 complex; GCC will refuse to optimize programs when the optimization
3228 itself is likely to take inordinate amounts of time.
3230 @item -Wpointer-sign
3231 @opindex Wpointer-sign
3232 @opindex Wno-pointer-sign
3233 Warn for pointer argument passing or assignment with different signedness.
3234 This option is only supported for C. It is implied by @option{-Wall}
3235 and by @option{-pedantic}, which can be disabled with
3236 @option{-Wno-pointer-sign}.
3240 Make all warnings into errors.
3244 Make the specified warning into an errors. The specifier for a
3245 warning is appended, for example @option{-Werror=switch} turns the
3246 warnings controlled by @option{-Wswitch} into errors. This switch
3247 takes a negative form, to be used to negate @option{-Werror} for
3248 specific warnings, for example @option{-Wno-error=switch} makes
3249 @option{-Wswitch} warnings not be errors, even when @option{-Werror}
3250 is in effect. You can use the @option{-fdiagnostics-show-option}
3251 option to have each controllable warning amended with the option which
3252 controls it, to determine what to use with this option.
3254 Note that specifying @option{-Werror=}@var{foo} automatically implies
3255 @option{-W}@var{foo}. However, @option{-Wno-error=}@var{foo} does not
3258 @item -Wstack-protector
3259 @opindex Wstack-protector
3260 This option is only active when @option{-fstack-protector} is active. It
3261 warns about functions that will not be protected against stack smashing.
3263 @item -Woverlength-strings
3264 @opindex Woverlength-strings
3265 Warn about string constants which are longer than the ``minimum
3266 maximum'' length specified in the C standard. Modern compilers
3267 generally allow string constants which are much longer than the
3268 standard's minimum limit, but very portable programs should avoid
3269 using longer strings.
3271 The limit applies @emph{after} string constant concatenation, and does
3272 not count the trailing NUL@. In C89, the limit was 509 characters; in
3273 C99, it was raised to 4095. C++98 does not specify a normative
3274 minimum maximum, so we do not diagnose overlength strings in C++@.
3276 This option is implied by @option{-pedantic}, and can be disabled with
3277 @option{-Wno-overlength-strings}.
3280 @node Debugging Options
3281 @section Options for Debugging Your Program or GCC
3282 @cindex options, debugging
3283 @cindex debugging information options
3285 GCC has various special options that are used for debugging
3286 either your program or GCC:
3291 Produce debugging information in the operating system's native format
3292 (stabs, COFF, XCOFF, or DWARF 2)@. GDB can work with this debugging
3295 On most systems that use stabs format, @option{-g} enables use of extra
3296 debugging information that only GDB can use; this extra information
3297 makes debugging work better in GDB but will probably make other debuggers
3299 refuse to read the program. If you want to control for certain whether
3300 to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
3301 @option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
3303 GCC allows you to use @option{-g} with
3304 @option{-O}. The shortcuts taken by optimized code may occasionally
3305 produce surprising results: some variables you declared may not exist
3306 at all; flow of control may briefly move where you did not expect it;
3307 some statements may not be executed because they compute constant
3308 results or their values were already at hand; some statements may
3309 execute in different places because they were moved out of loops.
3311 Nevertheless it proves possible to debug optimized output. This makes
3312 it reasonable to use the optimizer for programs that might have bugs.
3314 The following options are useful when GCC is generated with the
3315 capability for more than one debugging format.
3319 Produce debugging information for use by GDB@. This means to use the
3320 most expressive format available (DWARF 2, stabs, or the native format
3321 if neither of those are supported), including GDB extensions if at all
3326 Produce debugging information in stabs format (if that is supported),
3327 without GDB extensions. This is the format used by DBX on most BSD
3328 systems. On MIPS, Alpha and System V Release 4 systems this option
3329 produces stabs debugging output which is not understood by DBX or SDB@.
3330 On System V Release 4 systems this option requires the GNU assembler.
3332 @item -feliminate-unused-debug-symbols
3333 @opindex feliminate-unused-debug-symbols
3334 Produce debugging information in stabs format (if that is supported),
3335 for only symbols that are actually used.
3337 @item -femit-class-debug-always
3338 Instead of emitting debugging information for a C++ class in only one
3339 object file, emit it in all object files using the class. This option
3340 should be used only with debuggers that are unable to handle the way GCC
3341 normally emits debugging information for classes because using this
3342 option will increase the size of debugging information by as much as a
3347 Produce debugging information in stabs format (if that is supported),
3348 using GNU extensions understood only by the GNU debugger (GDB)@. The
3349 use of these extensions is likely to make other debuggers crash or
3350 refuse to read the program.
3354 Produce debugging information in COFF format (if that is supported).
3355 This is the format used by SDB on most System V systems prior to
3360 Produce debugging information in XCOFF format (if that is supported).
3361 This is the format used by the DBX debugger on IBM RS/6000 systems.
3365 Produce debugging information in XCOFF format (if that is supported),
3366 using GNU extensions understood only by the GNU debugger (GDB)@. The
3367 use of these extensions is likely to make other debuggers crash or
3368 refuse to read the program, and may cause assemblers other than the GNU
3369 assembler (GAS) to fail with an error.
3373 Produce debugging information in DWARF version 2 format (if that is
3374 supported). This is the format used by DBX on IRIX 6. With this
3375 option, GCC uses features of DWARF version 3 when they are useful;
3376 version 3 is upward compatible with version 2, but may still cause
3377 problems for older debuggers.
3381 Produce debugging information in VMS debug format (if that is
3382 supported). This is the format used by DEBUG on VMS systems.
3385 @itemx -ggdb@var{level}
3386 @itemx -gstabs@var{level}
3387 @itemx -gcoff@var{level}
3388 @itemx -gxcoff@var{level}
3389 @itemx -gvms@var{level}
3390 Request debugging information and also use @var{level} to specify how
3391 much information. The default level is 2.
3393 Level 1 produces minimal information, enough for making backtraces in
3394 parts of the program that you don't plan to debug. This includes
3395 descriptions of functions and external variables, but no information
3396 about local variables and no line numbers.
3398 Level 3 includes extra information, such as all the macro definitions
3399 present in the program. Some debuggers support macro expansion when
3400 you use @option{-g3}.
3402 @option{-gdwarf-2} does not accept a concatenated debug level, because
3403 GCC used to support an option @option{-gdwarf} that meant to generate
3404 debug information in version 1 of the DWARF format (which is very
3405 different from version 2), and it would have been too confusing. That
3406 debug format is long obsolete, but the option cannot be changed now.
3407 Instead use an additional @option{-g@var{level}} option to change the
3408 debug level for DWARF2.
3410 @item -feliminate-dwarf2-dups
3411 @opindex feliminate-dwarf2-dups
3412 Compress DWARF2 debugging information by eliminating duplicated
3413 information about each symbol. This option only makes sense when
3414 generating DWARF2 debugging information with @option{-gdwarf-2}.
3416 @item -femit-struct-debug-baseonly
3417 Emit debug information for struct-like types
3418 only when the base name of the compilation source file
3419 matches the base name of file in which the struct was defined.
3421 This option substantially reduces the size of debugging information,
3422 but at significant potential loss in type information to the debugger.
3423 See @option{-femit-struct-debug-reduced} for a less aggressive option.
3424 See @option{-femit-struct-debug-detailed} for more detailed control.
3426 This option works only with DWARF 2.
3428 @item -femit-struct-debug-reduced
3429 Emit debug information for struct-like types
3430 only when the base name of the compilation source file
3431 matches the base name of file in which the type was defined,
3432 unless the struct is a template or defined in a system header.
3434 This option significantly reduces the size of debugging information,
3435 with some potential loss in type information to the debugger.
3436 See @option{-femit-struct-debug-baseonly} for a more aggressive option.
3437 See @option{-femit-struct-debug-detailed} for more detailed control.
3439 This option works only with DWARF 2.
3441 @item -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]}
3442 Specify the struct-like types
3443 for which the compiler will generate debug information.
3444 The intent is to reduce duplicate struct debug information
3445 between different object files within the same program.
3447 This option is a detailed version of
3448 @option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly},
3449 which will serve for most needs.
3451 A specification has the syntax
3452 [@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none})
3454 The optional first word limits the specification to
3455 structs that are used directly (@samp{dir:}) or used indirectly (@samp{ind:}).
3456 A struct type is used directly when it is the type of a variable, member.
3457 Indirect uses arise through pointers to structs.
3458 That is, when use of an incomplete struct would be legal, the use is indirect.
3460 @samp{struct one direct; struct two * indirect;}.
3462 The optional second word limits the specification to
3463 ordinary structs (@samp{ord:}) or generic structs (@samp{gen:}).
3464 Generic structs are a bit complicated to explain.
3465 For C++, these are non-explicit specializations of template classes,
3466 or non-template classes within the above.
3467 Other programming languages have generics,
3468 but @samp{-femit-struct-debug-detailed} does not yet implement them.
3470 The third word specifies the source files for those
3471 structs for which the compiler will emit debug information.
3472 The values @samp{none} and @samp{any} have the normal meaning.
3473 The value @samp{base} means that
3474 the base of name of the file in which the type declaration appears
3475 must match the base of the name of the main compilation file.
3476 In practice, this means that
3477 types declared in @file{foo.c} and @file{foo.h} will have debug information,
3478 but types declared in other header will not.
3479 The value @samp{sys} means those types satisfying @samp{base}
3480 or declared in system or compiler headers.
3482 You may need to experiment to determine the best settings for your application.
3484 The default is @samp{-femit-struct-debug-detailed=all}.
3486 This option works only with DWARF 2.
3488 @cindex @command{prof}
3491 Generate extra code to write profile information suitable for the
3492 analysis program @command{prof}. You must use this option when compiling
3493 the source files you want data about, and you must also use it when
3496 @cindex @command{gprof}
3499 Generate extra code to write profile information suitable for the
3500 analysis program @command{gprof}. You must use this option when compiling
3501 the source files you want data about, and you must also use it when
3506 Makes the compiler print out each function name as it is compiled, and
3507 print some statistics about each pass when it finishes.
3510 @opindex ftime-report
3511 Makes the compiler print some statistics about the time consumed by each
3512 pass when it finishes.
3515 @opindex fmem-report
3516 Makes the compiler print some statistics about permanent memory
3517 allocation when it finishes.
3519 @item -fprofile-arcs
3520 @opindex fprofile-arcs
3521 Add code so that program flow @dfn{arcs} are instrumented. During
3522 execution the program records how many times each branch and call is
3523 executed and how many times it is taken or returns. When the compiled
3524 program exits it saves this data to a file called
3525 @file{@var{auxname}.gcda} for each source file. The data may be used for
3526 profile-directed optimizations (@option{-fbranch-probabilities}), or for
3527 test coverage analysis (@option{-ftest-coverage}). Each object file's
3528 @var{auxname} is generated from the name of the output file, if
3529 explicitly specified and it is not the final executable, otherwise it is
3530 the basename of the source file. In both cases any suffix is removed
3531 (e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
3532 @file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
3533 @xref{Cross-profiling}.
3535 @cindex @command{gcov}
3539 This option is used to compile and link code instrumented for coverage
3540 analysis. The option is a synonym for @option{-fprofile-arcs}
3541 @option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
3542 linking). See the documentation for those options for more details.
3547 Compile the source files with @option{-fprofile-arcs} plus optimization
3548 and code generation options. For test coverage analysis, use the
3549 additional @option{-ftest-coverage} option. You do not need to profile
3550 every source file in a program.
3553 Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
3554 (the latter implies the former).
3557 Run the program on a representative workload to generate the arc profile
3558 information. This may be repeated any number of times. You can run
3559 concurrent instances of your program, and provided that the file system
3560 supports locking, the data files will be correctly updated. Also
3561 @code{fork} calls are detected and correctly handled (double counting
3565 For profile-directed optimizations, compile the source files again with
3566 the same optimization and code generation options plus
3567 @option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
3568 Control Optimization}).
3571 For test coverage analysis, use @command{gcov} to produce human readable
3572 information from the @file{.gcno} and @file{.gcda} files. Refer to the
3573 @command{gcov} documentation for further information.
3577 With @option{-fprofile-arcs}, for each function of your program GCC
3578 creates a program flow graph, then finds a spanning tree for the graph.
3579 Only arcs that are not on the spanning tree have to be instrumented: the
3580 compiler adds code to count the number of times that these arcs are
3581 executed. When an arc is the only exit or only entrance to a block, the
3582 instrumentation code can be added to the block; otherwise, a new basic
3583 block must be created to hold the instrumentation code.
3586 @item -ftest-coverage
3587 @opindex ftest-coverage
3588 Produce a notes file that the @command{gcov} code-coverage utility
3589 (@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
3590 show program coverage. Each source file's note file is called
3591 @file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
3592 above for a description of @var{auxname} and instructions on how to
3593 generate test coverage data. Coverage data will match the source files
3594 more closely, if you do not optimize.
3596 @item -d@var{letters}
3597 @item -fdump-rtl-@var{pass}
3599 Says to make debugging dumps during compilation at times specified by
3600 @var{letters}. This is used for debugging the RTL-based passes of the
3601 compiler. The file names for most of the dumps are made by appending a
3602 pass number and a word to the @var{dumpname}. @var{dumpname} is generated
3603 from the name of the output file, if explicitly specified and it is not
3604 an executable, otherwise it is the basename of the source file.
3606 Most debug dumps can be enabled either passing a letter to the @option{-d}
3607 option, or with a long @option{-fdump-rtl} switch; here are the possible
3608 letters for use in @var{letters} and @var{pass}, and their meanings:
3613 Annotate the assembler output with miscellaneous debugging information.
3616 @itemx -fdump-rtl-bbro
3618 @opindex fdump-rtl-bbro
3619 Dump after block reordering, to @file{@var{file}.148r.bbro}.
3622 @itemx -fdump-rtl-combine
3624 @opindex fdump-rtl-combine
3625 Dump after instruction combination, to the file @file{@var{file}.129r.combine}.
3628 @itemx -fdump-rtl-ce1
3629 @itemx -fdump-rtl-ce2
3631 @opindex fdump-rtl-ce1
3632 @opindex fdump-rtl-ce2
3633 @option{-dC} and @option{-fdump-rtl-ce1} enable dumping after the
3634 first if conversion, to the file @file{@var{file}.117r.ce1}. @option{-dC}
3635 and @option{-fdump-rtl-ce2} enable dumping after the second if
3636 conversion, to the file @file{@var{file}.130r.ce2}.
3639 @itemx -fdump-rtl-btl
3640 @itemx -fdump-rtl-dbr
3642 @opindex fdump-rtl-btl
3643 @opindex fdump-rtl-dbr
3644 @option{-dd} and @option{-fdump-rtl-btl} enable dumping after branch
3645 target load optimization, to @file{@var{file}.31.btl}. @option{-dd}
3646 and @option{-fdump-rtl-dbr} enable dumping after delayed branch
3647 scheduling, to @file{@var{file}.36.dbr}.
3651 Dump all macro definitions, at the end of preprocessing, in addition to
3655 @itemx -fdump-rtl-ce3
3657 @opindex fdump-rtl-ce3
3658 Dump after the third if conversion, to @file{@var{file}.146r.ce3}.
3661 @itemx -fdump-rtl-cfg
3662 @itemx -fdump-rtl-life
3664 @opindex fdump-rtl-cfg
3665 @opindex fdump-rtl-life
3666 @option{-df} and @option{-fdump-rtl-cfg} enable dumping after control
3667 and data flow analysis, to @file{@var{file}.116r.cfg}. @option{-df}
3668 and @option{-fdump-rtl-cfg} enable dumping dump after life analysis,
3669 to @file{@var{file}.128r.life1} and @file{@var{file}.135r.life2}.
3672 @itemx -fdump-rtl-greg
3674 @opindex fdump-rtl-greg
3675 Dump after global register allocation, to @file{@var{file}.139r.greg}.
3678 @itemx -fdump-rtl-gcse
3679 @itemx -fdump-rtl-bypass
3681 @opindex fdump-rtl-gcse
3682 @opindex fdump-rtl-bypass
3683 @option{-dG} and @option{-fdump-rtl-gcse} enable dumping after GCSE, to
3684 @file{@var{file}.114r.gcse}. @option{-dG} and @option{-fdump-rtl-bypass}
3685 enable dumping after jump bypassing and control flow optimizations, to
3686 @file{@var{file}.115r.bypass}.
3689 @itemx -fdump-rtl-eh
3691 @opindex fdump-rtl-eh
3692 Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
3695 @itemx -fdump-rtl-sibling
3697 @opindex fdump-rtl-sibling
3698 Dump after sibling call optimizations, to @file{@var{file}.106r.sibling}.
3701 @itemx -fdump-rtl-jump
3703 @opindex fdump-rtl-jump
3704 Dump after the first jump optimization, to @file{@var{file}.112r.jump}.
3707 @itemx -fdump-rtl-stack
3709 @opindex fdump-rtl-stack
3710 Dump after conversion from registers to stack, to @file{@var{file}.152r.stack}.
3713 @itemx -fdump-rtl-lreg
3715 @opindex fdump-rtl-lreg
3716 Dump after local register allocation, to @file{@var{file}.138r.lreg}.
3719 @itemx -fdump-rtl-loop2
3721 @opindex fdump-rtl-loop2
3722 @option{-dL} and @option{-fdump-rtl-loop2} enable dumping after the
3723 loop optimization pass, to @file{@var{file}.119r.loop2},
3724 @file{@var{file}.120r.loop2_init},
3725 @file{@var{file}.121r.loop2_invariant}, and
3726 @file{@var{file}.125r.loop2_done}.
3729 @itemx -fdump-rtl-sms
3731 @opindex fdump-rtl-sms
3732 Dump after modulo scheduling, to @file{@var{file}.136r.sms}.
3735 @itemx -fdump-rtl-mach
3737 @opindex fdump-rtl-mach
3738 Dump after performing the machine dependent reorganization pass, to
3739 @file{@var{file}.155r.mach}.
3742 @itemx -fdump-rtl-rnreg
3744 @opindex fdump-rtl-rnreg
3745 Dump after register renumbering, to @file{@var{file}.147r.rnreg}.
3748 @itemx -fdump-rtl-regmove
3750 @opindex fdump-rtl-regmove
3751 Dump after the register move pass, to @file{@var{file}.132r.regmove}.
3754 @itemx -fdump-rtl-postreload
3756 @opindex fdump-rtl-postreload
3757 Dump after post-reload optimizations, to @file{@var{file}.24.postreload}.
3760 @itemx -fdump-rtl-expand
3762 @opindex fdump-rtl-expand
3763 Dump after RTL generation, to @file{@var{file}.104r.expand}.
3766 @itemx -fdump-rtl-sched2
3768 @opindex fdump-rtl-sched2
3769 Dump after the second scheduling pass, to @file{@var{file}.150r.sched2}.
3772 @itemx -fdump-rtl-cse
3774 @opindex fdump-rtl-cse
3775 Dump after CSE (including the jump optimization that sometimes follows
3776 CSE), to @file{@var{file}.113r.cse}.
3779 @itemx -fdump-rtl-sched
3781 @opindex fdump-rtl-sched
3782 Dump after the first scheduling pass, to @file{@var{file}.21.sched}.
3785 @itemx -fdump-rtl-cse2
3787 @opindex fdump-rtl-cse2
3788 Dump after the second CSE pass (including the jump optimization that
3789 sometimes follows CSE), to @file{@var{file}.127r.cse2}.
3792 @itemx -fdump-rtl-tracer
3794 @opindex fdump-rtl-tracer
3795 Dump after running tracer, to @file{@var{file}.118r.tracer}.
3798 @itemx -fdump-rtl-vpt
3799 @itemx -fdump-rtl-vartrack
3801 @opindex fdump-rtl-vpt
3802 @opindex fdump-rtl-vartrack
3803 @option{-dV} and @option{-fdump-rtl-vpt} enable dumping after the value
3804 profile transformations, to @file{@var{file}.10.vpt}. @option{-dV}
3805 and @option{-fdump-rtl-vartrack} enable dumping after variable tracking,
3806 to @file{@var{file}.154r.vartrack}.
3809 @itemx -fdump-rtl-flow2
3811 @opindex fdump-rtl-flow2
3812 Dump after the second flow pass, to @file{@var{file}.142r.flow2}.
3815 @itemx -fdump-rtl-peephole2
3817 @opindex fdump-rtl-peephole2
3818 Dump after the peephole pass, to @file{@var{file}.145r.peephole2}.
3821 @itemx -fdump-rtl-web
3823 @opindex fdump-rtl-web
3824 Dump after live range splitting, to @file{@var{file}.126r.web}.
3827 @itemx -fdump-rtl-all
3829 @opindex fdump-rtl-all
3830 Produce all the dumps listed above.
3834 Produce a core dump whenever an error occurs.
3838 Print statistics on memory usage, at the end of the run, to
3843 Annotate the assembler output with a comment indicating which
3844 pattern and alternative was used. The length of each instruction is
3849 Dump the RTL in the assembler output as a comment before each instruction.
3850 Also turns on @option{-dp} annotation.
3854 For each of the other indicated dump files (either with @option{-d} or
3855 @option{-fdump-rtl-@var{pass}}), dump a representation of the control flow
3856 graph suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
3860 Just generate RTL for a function instead of compiling it. Usually used
3861 with @samp{r} (@option{-fdump-rtl-expand}).
3865 Dump debugging information during parsing, to standard error.
3869 @opindex fdump-noaddr
3870 When doing debugging dumps (see @option{-d} option above), suppress
3871 address output. This makes it more feasible to use diff on debugging
3872 dumps for compiler invocations with different compiler binaries and/or
3873 different text / bss / data / heap / stack / dso start locations.
3875 @item -fdump-unnumbered
3876 @opindex fdump-unnumbered
3877 When doing debugging dumps (see @option{-d} option above), suppress instruction
3878 numbers, line number note and address output. This makes it more feasible to
3879 use diff on debugging dumps for compiler invocations with different
3880 options, in particular with and without @option{-g}.
3882 @item -fdump-translation-unit @r{(C++ only)}
3883 @itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
3884 @opindex fdump-translation-unit
3885 Dump a representation of the tree structure for the entire translation
3886 unit to a file. The file name is made by appending @file{.tu} to the
3887 source file name. If the @samp{-@var{options}} form is used, @var{options}
3888 controls the details of the dump as described for the
3889 @option{-fdump-tree} options.
3891 @item -fdump-class-hierarchy @r{(C++ only)}
3892 @itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
3893 @opindex fdump-class-hierarchy
3894 Dump a representation of each class's hierarchy and virtual function
3895 table layout to a file. The file name is made by appending @file{.class}
3896 to the source file name. If the @samp{-@var{options}} form is used,
3897 @var{options} controls the details of the dump as described for the
3898 @option{-fdump-tree} options.
3900 @item -fdump-ipa-@var{switch}
3902 Control the dumping at various stages of inter-procedural analysis
3903 language tree to a file. The file name is generated by appending a switch
3904 specific suffix to the source file name. The following dumps are possible:
3908 Enables all inter-procedural analysis dumps; currently the only produced
3909 dump is the @samp{cgraph} dump.
3912 Dumps information about call-graph optimization, unused function removal,
3913 and inlining decisions.
3916 @item -fdump-tree-@var{switch}
3917 @itemx -fdump-tree-@var{switch}-@var{options}
3919 Control the dumping at various stages of processing the intermediate
3920 language tree to a file. The file name is generated by appending a switch
3921 specific suffix to the source file name. If the @samp{-@var{options}}
3922 form is used, @var{options} is a list of @samp{-} separated options that
3923 control the details of the dump. Not all options are applicable to all
3924 dumps, those which are not meaningful will be ignored. The following
3925 options are available
3929 Print the address of each node. Usually this is not meaningful as it
3930 changes according to the environment and source file. Its primary use
3931 is for tying up a dump file with a debug environment.
3933 Inhibit dumping of members of a scope or body of a function merely
3934 because that scope has been reached. Only dump such items when they
3935 are directly reachable by some other path. When dumping pretty-printed
3936 trees, this option inhibits dumping the bodies of control structures.
3938 Print a raw representation of the tree. By default, trees are
3939 pretty-printed into a C-like representation.
3941 Enable more detailed dumps (not honored by every dump option).
3943 Enable dumping various statistics about the pass (not honored by every dump
3946 Enable showing basic block boundaries (disabled in raw dumps).
3948 Enable showing virtual operands for every statement.
3950 Enable showing line numbers for statements.
3952 Enable showing the unique ID (@code{DECL_UID}) for each variable.
3954 Turn on all options, except @option{raw}, @option{slim} and @option{lineno}.
3957 The following tree dumps are possible:
3961 Dump before any tree based optimization, to @file{@var{file}.original}.
3964 Dump after all tree based optimization, to @file{@var{file}.optimized}.
3967 Dump after function inlining, to @file{@var{file}.inlined}.
3970 @opindex fdump-tree-gimple
3971 Dump each function before and after the gimplification pass to a file. The
3972 file name is made by appending @file{.gimple} to the source file name.
3975 @opindex fdump-tree-cfg
3976 Dump the control flow graph of each function to a file. The file name is
3977 made by appending @file{.cfg} to the source file name.
3980 @opindex fdump-tree-vcg
3981 Dump the control flow graph of each function to a file in VCG format. The
3982 file name is made by appending @file{.vcg} to the source file name. Note
3983 that if the file contains more than one function, the generated file cannot
3984 be used directly by VCG@. You will need to cut and paste each function's
3985 graph into its own separate file first.
3988 @opindex fdump-tree-ch
3989 Dump each function after copying loop headers. The file name is made by
3990 appending @file{.ch} to the source file name.
3993 @opindex fdump-tree-ssa
3994 Dump SSA related information to a file. The file name is made by appending
3995 @file{.ssa} to the source file name.
3998 @opindex fdump-tree-salias
3999 Dump structure aliasing variable information to a file. This file name
4000 is made by appending @file{.salias} to the source file name.
4003 @opindex fdump-tree-alias
4004 Dump aliasing information for each function. The file name is made by
4005 appending @file{.alias} to the source file name.
4008 @opindex fdump-tree-ccp
4009 Dump each function after CCP@. The file name is made by appending
4010 @file{.ccp} to the source file name.
4013 @opindex fdump-tree-storeccp
4014 Dump each function after STORE-CCP. The file name is made by appending
4015 @file{.storeccp} to the source file name.
4018 @opindex fdump-tree-pre
4019 Dump trees after partial redundancy elimination. The file name is made
4020 by appending @file{.pre} to the source file name.
4023 @opindex fdump-tree-fre
4024 Dump trees after full redundancy elimination. The file name is made
4025 by appending @file{.fre} to the source file name.
4028 @opindex fdump-tree-copyprop
4029 Dump trees after copy propagation. The file name is made
4030 by appending @file{.copyprop} to the source file name.
4032 @item store_copyprop
4033 @opindex fdump-tree-store_copyprop
4034 Dump trees after store copy-propagation. The file name is made
4035 by appending @file{.store_copyprop} to the source file name.
4038 @opindex fdump-tree-dce
4039 Dump each function after dead code elimination. The file name is made by
4040 appending @file{.dce} to the source file name.
4043 @opindex fdump-tree-mudflap
4044 Dump each function after adding mudflap instrumentation. The file name is
4045 made by appending @file{.mudflap} to the source file name.
4048 @opindex fdump-tree-sra
4049 Dump each function after performing scalar replacement of aggregates. The
4050 file name is made by appending @file{.sra} to the source file name.
4053 @opindex fdump-tree-sink
4054 Dump each function after performing code sinking. The file name is made
4055 by appending @file{.sink} to the source file name.
4058 @opindex fdump-tree-dom
4059 Dump each function after applying dominator tree optimizations. The file
4060 name is made by appending @file{.dom} to the source file name.
4063 @opindex fdump-tree-dse
4064 Dump each function after applying dead store elimination. The file
4065 name is made by appending @file{.dse} to the source file name.
4068 @opindex fdump-tree-phiopt
4069 Dump each function after optimizing PHI nodes into straightline code. The file
4070 name is made by appending @file{.phiopt} to the source file name.
4073 @opindex fdump-tree-forwprop
4074 Dump each function after forward propagating single use variables. The file
4075 name is made by appending @file{.forwprop} to the source file name.
4078 @opindex fdump-tree-copyrename
4079 Dump each function after applying the copy rename optimization. The file
4080 name is made by appending @file{.copyrename} to the source file name.
4083 @opindex fdump-tree-nrv
4084 Dump each function after applying the named return value optimization on
4085 generic trees. The file name is made by appending @file{.nrv} to the source
4089 @opindex fdump-tree-vect
4090 Dump each function after applying vectorization of loops. The file name is
4091 made by appending @file{.vect} to the source file name.
4094 @opindex fdump-tree-vrp
4095 Dump each function after Value Range Propagation (VRP). The file name
4096 is made by appending @file{.vrp} to the source file name.
4099 @opindex fdump-tree-all
4100 Enable all the available tree dumps with the flags provided in this option.
4103 @item -ftree-vectorizer-verbose=@var{n}
4104 @opindex ftree-vectorizer-verbose
4105 This option controls the amount of debugging output the vectorizer prints.
4106 This information is written to standard error, unless
4107 @option{-fdump-tree-all} or @option{-fdump-tree-vect} is specified,
4108 in which case it is output to the usual dump listing file, @file{.vect}.
4109 For @var{n}=0 no diagnostic information is reported.
4110 If @var{n}=1 the vectorizer reports each loop that got vectorized,
4111 and the total number of loops that got vectorized.
4112 If @var{n}=2 the vectorizer also reports non-vectorized loops that passed
4113 the first analysis phase (vect_analyze_loop_form) - i.e. countable,
4114 inner-most, single-bb, single-entry/exit loops. This is the same verbosity
4115 level that @option{-fdump-tree-vect-stats} uses.
4116 Higher verbosity levels mean either more information dumped for each
4117 reported loop, or same amount of information reported for more loops:
4118 If @var{n}=3, alignment related information is added to the reports.
4119 If @var{n}=4, data-references related information (e.g. memory dependences,
4120 memory access-patterns) is added to the reports.
4121 If @var{n}=5, the vectorizer reports also non-vectorized inner-most loops
4122 that did not pass the first analysis phase (i.e. may not be countable, or
4123 may have complicated control-flow).
4124 If @var{n}=6, the vectorizer reports also non-vectorized nested loops.
4125 For @var{n}=7, all the information the vectorizer generates during its
4126 analysis and transformation is reported. This is the same verbosity level
4127 that @option{-fdump-tree-vect-details} uses.
4129 @item -frandom-seed=@var{string}
4130 @opindex frandom-string
4131 This option provides a seed that GCC uses when it would otherwise use
4132 random numbers. It is used to generate certain symbol names
4133 that have to be different in every compiled file. It is also used to
4134 place unique stamps in coverage data files and the object files that
4135 produce them. You can use the @option{-frandom-seed} option to produce
4136 reproducibly identical object files.
4138 The @var{string} should be different for every file you compile.
4140 @item -fsched-verbose=@var{n}
4141 @opindex fsched-verbose
4142 On targets that use instruction scheduling, this option controls the
4143 amount of debugging output the scheduler prints. This information is
4144 written to standard error, unless @option{-dS} or @option{-dR} is
4145 specified, in which case it is output to the usual dump
4146 listing file, @file{.sched} or @file{.sched2} respectively. However
4147 for @var{n} greater than nine, the output is always printed to standard
4150 For @var{n} greater than zero, @option{-fsched-verbose} outputs the
4151 same information as @option{-dRS}. For @var{n} greater than one, it
4152 also output basic block probabilities, detailed ready list information
4153 and unit/insn info. For @var{n} greater than two, it includes RTL
4154 at abort point, control-flow and regions info. And for @var{n} over
4155 four, @option{-fsched-verbose} also includes dependence info.
4159 Store the usual ``temporary'' intermediate files permanently; place them
4160 in the current directory and name them based on the source file. Thus,
4161 compiling @file{foo.c} with @samp{-c -save-temps} would produce files
4162 @file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
4163 preprocessed @file{foo.i} output file even though the compiler now
4164 normally uses an integrated preprocessor.
4166 When used in combination with the @option{-x} command line option,
4167 @option{-save-temps} is sensible enough to avoid over writing an
4168 input source file with the same extension as an intermediate file.
4169 The corresponding intermediate file may be obtained by renaming the
4170 source file before using @option{-save-temps}.
4174 Report the CPU time taken by each subprocess in the compilation
4175 sequence. For C source files, this is the compiler proper and assembler
4176 (plus the linker if linking is done). The output looks like this:
4183 The first number on each line is the ``user time'', that is time spent
4184 executing the program itself. The second number is ``system time'',
4185 time spent executing operating system routines on behalf of the program.
4186 Both numbers are in seconds.
4188 @item -fvar-tracking
4189 @opindex fvar-tracking
4190 Run variable tracking pass. It computes where variables are stored at each
4191 position in code. Better debugging information is then generated
4192 (if the debugging information format supports this information).
4194 It is enabled by default when compiling with optimization (@option{-Os},
4195 @option{-O}, @option{-O2}, ...), debugging information (@option{-g}) and
4196 the debug info format supports it.
4198 @item -print-file-name=@var{library}
4199 @opindex print-file-name
4200 Print the full absolute name of the library file @var{library} that
4201 would be used when linking---and don't do anything else. With this
4202 option, GCC does not compile or link anything; it just prints the
4205 @item -print-multi-directory
4206 @opindex print-multi-directory
4207 Print the directory name corresponding to the multilib selected by any
4208 other switches present in the command line. This directory is supposed
4209 to exist in @env{GCC_EXEC_PREFIX}.
4211 @item -print-multi-lib
4212 @opindex print-multi-lib
4213 Print the mapping from multilib directory names to compiler switches
4214 that enable them. The directory name is separated from the switches by
4215 @samp{;}, and each switch starts with an @samp{@@} instead of the
4216 @samp{-}, without spaces between multiple switches. This is supposed to
4217 ease shell-processing.
4219 @item -print-prog-name=@var{program}
4220 @opindex print-prog-name
4221 Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
4223 @item -print-libgcc-file-name
4224 @opindex print-libgcc-file-name
4225 Same as @option{-print-file-name=libgcc.a}.
4227 This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
4228 but you do want to link with @file{libgcc.a}. You can do
4231 gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
4234 @item -print-search-dirs
4235 @opindex print-search-dirs
4236 Print the name of the configured installation directory and a list of
4237 program and library directories @command{gcc} will search---and don't do anything else.
4239 This is useful when @command{gcc} prints the error message
4240 @samp{installation problem, cannot exec cpp0: No such file or directory}.
4241 To resolve this you either need to put @file{cpp0} and the other compiler
4242 components where @command{gcc} expects to find them, or you can set the environment
4243 variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
4244 Don't forget the trailing @samp{/}.
4245 @xref{Environment Variables}.
4248 @opindex dumpmachine
4249 Print the compiler's target machine (for example,
4250 @samp{i686-pc-linux-gnu})---and don't do anything else.
4253 @opindex dumpversion
4254 Print the compiler version (for example, @samp{3.0})---and don't do
4259 Print the compiler's built-in specs---and don't do anything else. (This
4260 is used when GCC itself is being built.) @xref{Spec Files}.
4262 @item -feliminate-unused-debug-types
4263 @opindex feliminate-unused-debug-types
4264 Normally, when producing DWARF2 output, GCC will emit debugging
4265 information for all types declared in a compilation
4266 unit, regardless of whether or not they are actually used
4267 in that compilation unit. Sometimes this is useful, such as
4268 if, in the debugger, you want to cast a value to a type that is
4269 not actually used in your program (but is declared). More often,
4270 however, this results in a significant amount of wasted space.
4271 With this option, GCC will avoid producing debug symbol output
4272 for types that are nowhere used in the source file being compiled.
4275 @node Optimize Options
4276 @section Options That Control Optimization
4277 @cindex optimize options
4278 @cindex options, optimization
4280 These options control various sorts of optimizations.
4282 Without any optimization option, the compiler's goal is to reduce the
4283 cost of compilation and to make debugging produce the expected
4284 results. Statements are independent: if you stop the program with a
4285 breakpoint between statements, you can then assign a new value to any
4286 variable or change the program counter to any other statement in the
4287 function and get exactly the results you would expect from the source
4290 Turning on optimization flags makes the compiler attempt to improve
4291 the performance and/or code size at the expense of compilation time
4292 and possibly the ability to debug the program.
4294 The compiler performs optimization based on the knowledge it has of
4295 the program. Optimization levels @option{-O} and above, in
4296 particular, enable @emph{unit-at-a-time} mode, which allows the
4297 compiler to consider information gained from later functions in
4298 the file when compiling a function. Compiling multiple files at
4299 once to a single output file in @emph{unit-at-a-time} mode allows
4300 the compiler to use information gained from all of the files when
4301 compiling each of them.
4303 Not all optimizations are controlled directly by a flag. Only
4304 optimizations that have a flag are listed.
4311 Optimize. Optimizing compilation takes somewhat more time, and a lot
4312 more memory for a large function.
4314 With @option{-O}, the compiler tries to reduce code size and execution
4315 time, without performing any optimizations that take a great deal of
4318 @option{-O} turns on the following optimization flags:
4319 @gccoptlist{-fdefer-pop @gol
4320 -fdelayed-branch @gol
4321 -fguess-branch-probability @gol
4322 -fcprop-registers @gol
4323 -fif-conversion @gol
4324 -fif-conversion2 @gol
4327 -ftree-dominator-opts @gol
4332 -ftree-copyrename @gol
4335 -funit-at-a-time @gol
4338 @option{-O} also turns on @option{-fomit-frame-pointer} on machines
4339 where doing so does not interfere with debugging.
4343 Optimize even more. GCC performs nearly all supported optimizations
4344 that do not involve a space-speed tradeoff. The compiler does not
4345 perform loop unrolling or function inlining when you specify @option{-O2}.
4346 As compared to @option{-O}, this option increases both compilation time
4347 and the performance of the generated code.
4349 @option{-O2} turns on all optimization flags specified by @option{-O}. It
4350 also turns on the following optimization flags:
4351 @gccoptlist{-fthread-jumps @gol
4353 -foptimize-sibling-calls @gol
4354 -fcse-follow-jumps -fcse-skip-blocks @gol
4355 -fgcse -fgcse-lm @gol
4356 -fexpensive-optimizations @gol
4357 -frerun-cse-after-loop @gol
4360 -fschedule-insns -fschedule-insns2 @gol
4361 -fsched-interblock -fsched-spec @gol
4363 -fstrict-aliasing -fstrict-overflow @gol
4364 -fdelete-null-pointer-checks @gol
4365 -freorder-blocks -freorder-functions @gol
4366 -falign-functions -falign-jumps @gol
4367 -falign-loops -falign-labels @gol
4371 Please note the warning under @option{-fgcse} about
4372 invoking @option{-O2} on programs that use computed gotos.
4374 @option{-O2} doesn't turn on @option{-ftree-vrp} for the Ada compiler.
4375 This option must be explicitly specified on the command line to be
4376 enabled for the Ada compiler.
4380 Optimize yet more. @option{-O3} turns on all optimizations specified by
4381 @option{-O2} and also turns on the @option{-finline-functions},
4382 @option{-funswitch-loops} and @option{-fgcse-after-reload} options.
4386 Do not optimize. This is the default.
4390 Optimize for size. @option{-Os} enables all @option{-O2} optimizations that
4391 do not typically increase code size. It also performs further
4392 optimizations designed to reduce code size.
4394 @option{-Os} disables the following optimization flags:
4395 @gccoptlist{-falign-functions -falign-jumps -falign-loops @gol
4396 -falign-labels -freorder-blocks -freorder-blocks-and-partition @gol
4397 -fprefetch-loop-arrays -ftree-vect-loop-version}
4399 If you use multiple @option{-O} options, with or without level numbers,
4400 the last such option is the one that is effective.
4403 Options of the form @option{-f@var{flag}} specify machine-independent
4404 flags. Most flags have both positive and negative forms; the negative
4405 form of @option{-ffoo} would be @option{-fno-foo}. In the table
4406 below, only one of the forms is listed---the one you typically will
4407 use. You can figure out the other form by either removing @samp{no-}
4410 The following options control specific optimizations. They are either
4411 activated by @option{-O} options or are related to ones that are. You
4412 can use the following flags in the rare cases when ``fine-tuning'' of
4413 optimizations to be performed is desired.
4416 @item -fno-default-inline
4417 @opindex fno-default-inline
4418 Do not make member functions inline by default merely because they are
4419 defined inside the class scope (C++ only). Otherwise, when you specify
4420 @w{@option{-O}}, member functions defined inside class scope are compiled
4421 inline by default; i.e., you don't need to add @samp{inline} in front of
4422 the member function name.
4424 @item -fno-defer-pop
4425 @opindex fno-defer-pop
4426 Always pop the arguments to each function call as soon as that function
4427 returns. For machines which must pop arguments after a function call,
4428 the compiler normally lets arguments accumulate on the stack for several
4429 function calls and pops them all at once.
4431 Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4435 Force memory operands to be copied into registers before doing
4436 arithmetic on them. This produces better code by making all memory
4437 references potential common subexpressions. When they are not common
4438 subexpressions, instruction combination should eliminate the separate
4439 register-load. This option is now a nop and will be removed in 4.3.
4442 @opindex fforce-addr
4443 Force memory address constants to be copied into registers before
4444 doing arithmetic on them.
4446 @item -fomit-frame-pointer
4447 @opindex fomit-frame-pointer
4448 Don't keep the frame pointer in a register for functions that
4449 don't need one. This avoids the instructions to save, set up and
4450 restore frame pointers; it also makes an extra register available
4451 in many functions. @strong{It also makes debugging impossible on
4454 On some machines, such as the VAX, this flag has no effect, because
4455 the standard calling sequence automatically handles the frame pointer
4456 and nothing is saved by pretending it doesn't exist. The
4457 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
4458 whether a target machine supports this flag. @xref{Registers,,Register
4459 Usage, gccint, GNU Compiler Collection (GCC) Internals}.
4461 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4463 @item -foptimize-sibling-calls
4464 @opindex foptimize-sibling-calls
4465 Optimize sibling and tail recursive calls.
4467 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4471 Don't pay attention to the @code{inline} keyword. Normally this option
4472 is used to keep the compiler from expanding any functions inline.
4473 Note that if you are not optimizing, no functions can be expanded inline.
4475 @item -finline-functions
4476 @opindex finline-functions
4477 Integrate all simple functions into their callers. The compiler
4478 heuristically decides which functions are simple enough to be worth
4479 integrating in this way.
4481 If all calls to a given function are integrated, and the function is
4482 declared @code{static}, then the function is normally not output as
4483 assembler code in its own right.
4485 Enabled at level @option{-O3}.
4487 @item -finline-functions-called-once
4488 @opindex finline-functions-called-once
4489 Consider all @code{static} functions called once for inlining into their
4490 caller even if they are not marked @code{inline}. If a call to a given
4491 function is integrated, then the function is not output as assembler code
4494 Enabled if @option{-funit-at-a-time} is enabled.
4496 @item -fearly-inlining
4497 @opindex fearly-inlining
4498 Inline functions marked by @code{always_inline} and functions whose body seems
4499 smaller than the function call overhead early before doing
4500 @option{-fprofile-generate} instrumentation and real inlining pass. Doing so
4501 makes profiling significantly cheaper and usually inlining faster on programs
4502 having large chains of nested wrapper functions.
4506 @item -finline-limit=@var{n}
4507 @opindex finline-limit
4508 By default, GCC limits the size of functions that can be inlined. This flag
4509 allows the control of this limit for functions that are explicitly marked as
4510 inline (i.e., marked with the inline keyword or defined within the class
4511 definition in c++). @var{n} is the size of functions that can be inlined in
4512 number of pseudo instructions (not counting parameter handling). The default
4513 value of @var{n} is 600.
4514 Increasing this value can result in more inlined code at
4515 the cost of compilation time and memory consumption. Decreasing usually makes
4516 the compilation faster and less code will be inlined (which presumably
4517 means slower programs). This option is particularly useful for programs that
4518 use inlining heavily such as those based on recursive templates with C++.
4520 Inlining is actually controlled by a number of parameters, which may be
4521 specified individually by using @option{--param @var{name}=@var{value}}.
4522 The @option{-finline-limit=@var{n}} option sets some of these parameters
4526 @item max-inline-insns-single
4527 is set to @var{n}/2.
4528 @item max-inline-insns-auto
4529 is set to @var{n}/2.
4530 @item min-inline-insns
4531 is set to 130 or @var{n}/4, whichever is smaller.
4532 @item max-inline-insns-rtl
4536 See below for a documentation of the individual
4537 parameters controlling inlining.
4539 @emph{Note:} pseudo instruction represents, in this particular context, an
4540 abstract measurement of function's size. In no way does it represent a count
4541 of assembly instructions and as such its exact meaning might change from one
4542 release to an another.
4544 @item -fkeep-inline-functions
4545 @opindex fkeep-inline-functions
4546 In C, emit @code{static} functions that are declared @code{inline}
4547 into the object file, even if the function has been inlined into all
4548 of its callers. This switch does not affect functions using the
4549 @code{extern inline} extension in GNU C@. In C++, emit any and all
4550 inline functions into the object file.
4552 @item -fkeep-static-consts
4553 @opindex fkeep-static-consts
4554 Emit variables declared @code{static const} when optimization isn't turned
4555 on, even if the variables aren't referenced.
4557 GCC enables this option by default. If you want to force the compiler to
4558 check if the variable was referenced, regardless of whether or not
4559 optimization is turned on, use the @option{-fno-keep-static-consts} option.
4561 @item -fmerge-constants
4562 Attempt to merge identical constants (string constants and floating point
4563 constants) across compilation units.
4565 This option is the default for optimized compilation if the assembler and
4566 linker support it. Use @option{-fno-merge-constants} to inhibit this
4569 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4571 @item -fmerge-all-constants
4572 Attempt to merge identical constants and identical variables.
4574 This option implies @option{-fmerge-constants}. In addition to
4575 @option{-fmerge-constants} this considers e.g.@: even constant initialized
4576 arrays or initialized constant variables with integral or floating point
4577 types. Languages like C or C++ require each non-automatic variable to
4578 have distinct location, so using this option will result in non-conforming
4581 @item -fmodulo-sched
4582 @opindex fmodulo-sched
4583 Perform swing modulo scheduling immediately before the first scheduling
4584 pass. This pass looks at innermost loops and reorders their
4585 instructions by overlapping different iterations.
4587 @item -fno-branch-count-reg
4588 @opindex fno-branch-count-reg
4589 Do not use ``decrement and branch'' instructions on a count register,
4590 but instead generate a sequence of instructions that decrement a
4591 register, compare it against zero, then branch based upon the result.
4592 This option is only meaningful on architectures that support such
4593 instructions, which include x86, PowerPC, IA-64 and S/390.
4595 The default is @option{-fbranch-count-reg}.
4597 @item -fno-function-cse
4598 @opindex fno-function-cse
4599 Do not put function addresses in registers; make each instruction that
4600 calls a constant function contain the function's address explicitly.
4602 This option results in less efficient code, but some strange hacks
4603 that alter the assembler output may be confused by the optimizations
4604 performed when this option is not used.
4606 The default is @option{-ffunction-cse}
4608 @item -fno-zero-initialized-in-bss
4609 @opindex fno-zero-initialized-in-bss
4610 If the target supports a BSS section, GCC by default puts variables that
4611 are initialized to zero into BSS@. This can save space in the resulting
4614 This option turns off this behavior because some programs explicitly
4615 rely on variables going to the data section. E.g., so that the
4616 resulting executable can find the beginning of that section and/or make
4617 assumptions based on that.
4619 The default is @option{-fzero-initialized-in-bss}.
4621 @item -fbounds-check
4622 @opindex fbounds-check
4623 For front-ends that support it, generate additional code to check that
4624 indices used to access arrays are within the declared range. This is
4625 currently only supported by the Java and Fortran front-ends, where
4626 this option defaults to true and false respectively.
4628 @item -fmudflap -fmudflapth -fmudflapir
4632 @cindex bounds checking
4634 For front-ends that support it (C and C++), instrument all risky
4635 pointer/array dereferencing operations, some standard library
4636 string/heap functions, and some other associated constructs with
4637 range/validity tests. Modules so instrumented should be immune to
4638 buffer overflows, invalid heap use, and some other classes of C/C++
4639 programming errors. The instrumentation relies on a separate runtime
4640 library (@file{libmudflap}), which will be linked into a program if
4641 @option{-fmudflap} is given at link time. Run-time behavior of the
4642 instrumented program is controlled by the @env{MUDFLAP_OPTIONS}
4643 environment variable. See @code{env MUDFLAP_OPTIONS=-help a.out}
4646 Use @option{-fmudflapth} instead of @option{-fmudflap} to compile and to
4647 link if your program is multi-threaded. Use @option{-fmudflapir}, in
4648 addition to @option{-fmudflap} or @option{-fmudflapth}, if
4649 instrumentation should ignore pointer reads. This produces less
4650 instrumentation (and therefore faster execution) and still provides
4651 some protection against outright memory corrupting writes, but allows
4652 erroneously read data to propagate within a program.
4654 @item -fthread-jumps
4655 @opindex fthread-jumps
4656 Perform optimizations where we check to see if a jump branches to a
4657 location where another comparison subsumed by the first is found. If
4658 so, the first branch is redirected to either the destination of the
4659 second branch or a point immediately following it, depending on whether
4660 the condition is known to be true or false.
4662 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4664 @item -fcse-follow-jumps
4665 @opindex fcse-follow-jumps
4666 In common subexpression elimination, scan through jump instructions
4667 when the target of the jump is not reached by any other path. For
4668 example, when CSE encounters an @code{if} statement with an
4669 @code{else} clause, CSE will follow the jump when the condition
4672 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4674 @item -fcse-skip-blocks
4675 @opindex fcse-skip-blocks
4676 This is similar to @option{-fcse-follow-jumps}, but causes CSE to
4677 follow jumps which conditionally skip over blocks. When CSE
4678 encounters a simple @code{if} statement with no else clause,
4679 @option{-fcse-skip-blocks} causes CSE to follow the jump around the
4680 body of the @code{if}.
4682 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4684 @item -frerun-cse-after-loop
4685 @opindex frerun-cse-after-loop
4686 Re-run common subexpression elimination after loop optimizations has been
4689 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4693 Perform a global common subexpression elimination pass.
4694 This pass also performs global constant and copy propagation.
4696 @emph{Note:} When compiling a program using computed gotos, a GCC
4697 extension, you may get better runtime performance if you disable
4698 the global common subexpression elimination pass by adding
4699 @option{-fno-gcse} to the command line.
4701 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4705 When @option{-fgcse-lm} is enabled, global common subexpression elimination will
4706 attempt to move loads which are only killed by stores into themselves. This
4707 allows a loop containing a load/store sequence to be changed to a load outside
4708 the loop, and a copy/store within the loop.
4710 Enabled by default when gcse is enabled.
4714 When @option{-fgcse-sm} is enabled, a store motion pass is run after
4715 global common subexpression elimination. This pass will attempt to move
4716 stores out of loops. When used in conjunction with @option{-fgcse-lm},
4717 loops containing a load/store sequence can be changed to a load before
4718 the loop and a store after the loop.
4720 Not enabled at any optimization level.
4724 When @option{-fgcse-las} is enabled, the global common subexpression
4725 elimination pass eliminates redundant loads that come after stores to the
4726 same memory location (both partial and full redundancies).
4728 Not enabled at any optimization level.
4730 @item -fgcse-after-reload
4731 @opindex fgcse-after-reload
4732 When @option{-fgcse-after-reload} is enabled, a redundant load elimination
4733 pass is performed after reload. The purpose of this pass is to cleanup
4736 @item -funsafe-loop-optimizations
4737 @opindex funsafe-loop-optimizations
4738 If given, the loop optimizer will assume that loop indices do not
4739 overflow, and that the loops with nontrivial exit condition are not
4740 infinite. This enables a wider range of loop optimizations even if
4741 the loop optimizer itself cannot prove that these assumptions are valid.
4742 Using @option{-Wunsafe-loop-optimizations}, the compiler will warn you
4743 if it finds this kind of loop.
4745 @item -fcrossjumping
4746 @opindex crossjumping
4747 Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
4748 resulting code may or may not perform better than without cross-jumping.
4750 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4752 @item -fif-conversion
4753 @opindex if-conversion
4754 Attempt to transform conditional jumps into branch-less equivalents. This
4755 include use of conditional moves, min, max, set flags and abs instructions, and
4756 some tricks doable by standard arithmetics. The use of conditional execution
4757 on chips where it is available is controlled by @code{if-conversion2}.
4759 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4761 @item -fif-conversion2
4762 @opindex if-conversion2
4763 Use conditional execution (where available) to transform conditional jumps into
4764 branch-less equivalents.
4766 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4768 @item -fdelete-null-pointer-checks
4769 @opindex fdelete-null-pointer-checks
4770 Use global dataflow analysis to identify and eliminate useless checks
4771 for null pointers. The compiler assumes that dereferencing a null
4772 pointer would have halted the program. If a pointer is checked after
4773 it has already been dereferenced, it cannot be null.
4775 In some environments, this assumption is not true, and programs can
4776 safely dereference null pointers. Use
4777 @option{-fno-delete-null-pointer-checks} to disable this optimization
4778 for programs which depend on that behavior.
4780 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4782 @item -fexpensive-optimizations
4783 @opindex fexpensive-optimizations
4784 Perform a number of minor optimizations that are relatively expensive.
4786 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4788 @item -foptimize-register-move
4790 @opindex foptimize-register-move
4792 Attempt to reassign register numbers in move instructions and as
4793 operands of other simple instructions in order to maximize the amount of
4794 register tying. This is especially helpful on machines with two-operand
4797 Note @option{-fregmove} and @option{-foptimize-register-move} are the same
4800 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4802 @item -fdelayed-branch
4803 @opindex fdelayed-branch
4804 If supported for the target machine, attempt to reorder instructions
4805 to exploit instruction slots available after delayed branch
4808 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4810 @item -fschedule-insns
4811 @opindex fschedule-insns
4812 If supported for the target machine, attempt to reorder instructions to
4813 eliminate execution stalls due to required data being unavailable. This
4814 helps machines that have slow floating point or memory load instructions
4815 by allowing other instructions to be issued until the result of the load
4816 or floating point instruction is required.
4818 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4820 @item -fschedule-insns2
4821 @opindex fschedule-insns2
4822 Similar to @option{-fschedule-insns}, but requests an additional pass of
4823 instruction scheduling after register allocation has been done. This is
4824 especially useful on machines with a relatively small number of
4825 registers and where memory load instructions take more than one cycle.
4827 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4829 @item -fno-sched-interblock
4830 @opindex fno-sched-interblock
4831 Don't schedule instructions across basic blocks. This is normally
4832 enabled by default when scheduling before register allocation, i.e.@:
4833 with @option{-fschedule-insns} or at @option{-O2} or higher.
4835 @item -fno-sched-spec
4836 @opindex fno-sched-spec
4837 Don't allow speculative motion of non-load instructions. This is normally
4838 enabled by default when scheduling before register allocation, i.e.@:
4839 with @option{-fschedule-insns} or at @option{-O2} or higher.
4841 @item -fsched-spec-load
4842 @opindex fsched-spec-load
4843 Allow speculative motion of some load instructions. This only makes
4844 sense when scheduling before register allocation, i.e.@: with
4845 @option{-fschedule-insns} or at @option{-O2} or higher.
4847 @item -fsched-spec-load-dangerous
4848 @opindex fsched-spec-load-dangerous
4849 Allow speculative motion of more load instructions. This only makes
4850 sense when scheduling before register allocation, i.e.@: with
4851 @option{-fschedule-insns} or at @option{-O2} or higher.
4853 @item -fsched-stalled-insns=@var{n}
4854 @opindex fsched-stalled-insns
4855 Define how many insns (if any) can be moved prematurely from the queue
4856 of stalled insns into the ready list, during the second scheduling pass.
4858 @item -fsched-stalled-insns-dep=@var{n}
4859 @opindex fsched-stalled-insns-dep
4860 Define how many insn groups (cycles) will be examined for a dependency
4861 on a stalled insn that is candidate for premature removal from the queue
4862 of stalled insns. Has an effect only during the second scheduling pass,
4863 and only if @option{-fsched-stalled-insns} is used and its value is not zero.
4865 @item -fsched2-use-superblocks
4866 @opindex fsched2-use-superblocks
4867 When scheduling after register allocation, do use superblock scheduling
4868 algorithm. Superblock scheduling allows motion across basic block boundaries
4869 resulting on faster schedules. This option is experimental, as not all machine
4870 descriptions used by GCC model the CPU closely enough to avoid unreliable
4871 results from the algorithm.
4873 This only makes sense when scheduling after register allocation, i.e.@: with
4874 @option{-fschedule-insns2} or at @option{-O2} or higher.
4876 @item -fsched2-use-traces
4877 @opindex fsched2-use-traces
4878 Use @option{-fsched2-use-superblocks} algorithm when scheduling after register
4879 allocation and additionally perform code duplication in order to increase the
4880 size of superblocks using tracer pass. See @option{-ftracer} for details on
4883 This mode should produce faster but significantly longer programs. Also
4884 without @option{-fbranch-probabilities} the traces constructed may not
4885 match the reality and hurt the performance. This only makes
4886 sense when scheduling after register allocation, i.e.@: with
4887 @option{-fschedule-insns2} or at @option{-O2} or higher.
4891 Eliminates redundant extension instructions and move the non redundant
4892 ones to optimal placement using LCM.
4894 @item -freschedule-modulo-scheduled-loops
4895 @opindex fscheduling-in-modulo-scheduled-loops
4896 The modulo scheduling comes before the traditional scheduling, if a loop was modulo scheduled
4897 we may want to prevent the later scheduling passes from changing its schedule, we use this
4898 option to control that.
4900 @item -fcaller-saves
4901 @opindex fcaller-saves
4902 Enable values to be allocated in registers that will be clobbered by
4903 function calls, by emitting extra instructions to save and restore the
4904 registers around such calls. Such allocation is done only when it
4905 seems to result in better code than would otherwise be produced.
4907 This option is always enabled by default on certain machines, usually
4908 those which have no call-preserved registers to use instead.
4910 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4913 Perform Partial Redundancy Elimination (PRE) on trees. This flag is
4914 enabled by default at @option{-O2} and @option{-O3}.
4917 Perform Full Redundancy Elimination (FRE) on trees. The difference
4918 between FRE and PRE is that FRE only considers expressions
4919 that are computed on all paths leading to the redundant computation.
4920 This analysis faster than PRE, though it exposes fewer redundancies.
4921 This flag is enabled by default at @option{-O} and higher.
4923 @item -ftree-copy-prop
4924 Perform copy propagation on trees. This pass eliminates unnecessary
4925 copy operations. This flag is enabled by default at @option{-O} and
4928 @item -ftree-store-copy-prop
4929 Perform copy propagation of memory loads and stores. This pass
4930 eliminates unnecessary copy operations in memory references
4931 (structures, global variables, arrays, etc). This flag is enabled by
4932 default at @option{-O2} and higher.
4935 Perform structural alias analysis on trees. This flag
4936 is enabled by default at @option{-O} and higher.
4939 Perform interprocedural pointer analysis.
4942 Perform forward store motion on trees. This flag is
4943 enabled by default at @option{-O} and higher.
4946 Perform sparse conditional constant propagation (CCP) on trees. This
4947 pass only operates on local scalar variables and is enabled by default
4948 at @option{-O} and higher.
4950 @item -ftree-store-ccp
4951 Perform sparse conditional constant propagation (CCP) on trees. This
4952 pass operates on both local scalar variables and memory stores and
4953 loads (global variables, structures, arrays, etc). This flag is
4954 enabled by default at @option{-O2} and higher.
4957 Perform dead code elimination (DCE) on trees. This flag is enabled by
4958 default at @option{-O} and higher.
4960 @item -ftree-dominator-opts
4961 Perform a variety of simple scalar cleanups (constant/copy
4962 propagation, redundancy elimination, range propagation and expression
4963 simplification) based on a dominator tree traversal. This also
4964 performs jump threading (to reduce jumps to jumps). This flag is
4965 enabled by default at @option{-O} and higher.
4968 Perform loop header copying on trees. This is beneficial since it increases
4969 effectiveness of code motion optimizations. It also saves one jump. This flag
4970 is enabled by default at @option{-O} and higher. It is not enabled
4971 for @option{-Os}, since it usually increases code size.
4973 @item -ftree-loop-optimize
4974 Perform loop optimizations on trees. This flag is enabled by default
4975 at @option{-O} and higher.
4977 @item -ftree-loop-linear
4978 Perform linear loop transformations on tree. This flag can improve cache
4979 performance and allow further loop optimizations to take place.
4981 @item -ftree-loop-im
4982 Perform loop invariant motion on trees. This pass moves only invariants that
4983 would be hard to handle at RTL level (function calls, operations that expand to
4984 nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
4985 operands of conditions that are invariant out of the loop, so that we can use
4986 just trivial invariantness analysis in loop unswitching. The pass also includes
4989 @item -ftree-loop-ivcanon
4990 Create a canonical counter for number of iterations in the loop for that
4991 determining number of iterations requires complicated analysis. Later
4992 optimizations then may determine the number easily. Useful especially
4993 in connection with unrolling.
4996 Perform induction variable optimizations (strength reduction, induction
4997 variable merging and induction variable elimination) on trees.
5000 Perform scalar replacement of aggregates. This pass replaces structure
5001 references with scalars to prevent committing structures to memory too
5002 early. This flag is enabled by default at @option{-O} and higher.
5004 @item -ftree-copyrename
5005 Perform copy renaming on trees. This pass attempts to rename compiler
5006 temporaries to other variables at copy locations, usually resulting in
5007 variable names which more closely resemble the original variables. This flag
5008 is enabled by default at @option{-O} and higher.
5011 Perform temporary expression replacement during the SSA->normal phase. Single
5012 use/single def temporaries are replaced at their use location with their
5013 defining expression. This results in non-GIMPLE code, but gives the expanders
5014 much more complex trees to work on resulting in better RTL generation. This is
5015 enabled by default at @option{-O} and higher.
5018 Perform live range splitting during the SSA->normal phase. Distinct live
5019 ranges of a variable are split into unique variables, allowing for better
5020 optimization later. This is enabled by default at @option{-O} and higher.
5022 @item -ftree-vectorize
5023 Perform loop vectorization on trees.
5025 @item -ftree-vect-loop-version
5026 @opindex ftree-vect-loop-version
5027 Perform loop versioning when doing loop vectorization on trees. When a loop
5028 appears to be vectorizable except that data alignment or data dependence cannot
5029 be determined at compile time then vectorized and non-vectorized versions of
5030 the loop are generated along with runtime checks for alignment or dependence
5031 to control which version is executed. This option is enabled by default
5032 except at level @option{-Os} where it is disabled.
5035 Perform Value Range Propagation on trees. This is similar to the
5036 constant propagation pass, but instead of values, ranges of values are
5037 propagated. This allows the optimizers to remove unnecessary range
5038 checks like array bound checks and null pointer checks. This is
5039 enabled by default at @option{-O2} and higher. Null pointer check
5040 elimination is only done if @option{-fdelete-null-pointer-checks} is
5045 Perform tail duplication to enlarge superblock size. This transformation
5046 simplifies the control flow of the function allowing other optimizations to do
5049 @item -funroll-loops
5050 @opindex funroll-loops
5051 Unroll loops whose number of iterations can be determined at compile
5052 time or upon entry to the loop. @option{-funroll-loops} implies
5053 @option{-frerun-cse-after-loop}. This option makes code larger,
5054 and may or may not make it run faster.
5056 @item -funroll-all-loops
5057 @opindex funroll-all-loops
5058 Unroll all loops, even if their number of iterations is uncertain when
5059 the loop is entered. This usually makes programs run more slowly.
5060 @option{-funroll-all-loops} implies the same options as
5061 @option{-funroll-loops},
5063 @item -fsplit-ivs-in-unroller
5064 @opindex fsplit-ivs-in-unroller
5065 Enables expressing of values of induction variables in later iterations
5066 of the unrolled loop using the value in the first iteration. This breaks
5067 long dependency chains, thus improving efficiency of the scheduling passes.
5069 Combination of @option{-fweb} and CSE is often sufficient to obtain the
5070 same effect. However in cases the loop body is more complicated than
5071 a single basic block, this is not reliable. It also does not work at all
5072 on some of the architectures due to restrictions in the CSE pass.
5074 This optimization is enabled by default.
5076 @item -fvariable-expansion-in-unroller
5077 @opindex fvariable-expansion-in-unroller
5078 With this option, the compiler will create multiple copies of some
5079 local variables when unrolling a loop which can result in superior code.
5081 @item -fprefetch-loop-arrays
5082 @opindex fprefetch-loop-arrays
5083 If supported by the target machine, generate instructions to prefetch
5084 memory to improve the performance of loops that access large arrays.
5086 This option may generate better or worse code; results are highly
5087 dependent on the structure of loops within the source code.
5089 Disabled at level @option{-Os}.
5092 @itemx -fno-peephole2
5093 @opindex fno-peephole
5094 @opindex fno-peephole2
5095 Disable any machine-specific peephole optimizations. The difference
5096 between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
5097 are implemented in the compiler; some targets use one, some use the
5098 other, a few use both.
5100 @option{-fpeephole} is enabled by default.
5101 @option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5103 @item -fno-guess-branch-probability
5104 @opindex fno-guess-branch-probability
5105 Do not guess branch probabilities using heuristics.
5107 GCC will use heuristics to guess branch probabilities if they are
5108 not provided by profiling feedback (@option{-fprofile-arcs}). These
5109 heuristics are based on the control flow graph. If some branch probabilities
5110 are specified by @samp{__builtin_expect}, then the heuristics will be
5111 used to guess branch probabilities for the rest of the control flow graph,
5112 taking the @samp{__builtin_expect} info into account. The interactions
5113 between the heuristics and @samp{__builtin_expect} can be complex, and in
5114 some cases, it may be useful to disable the heuristics so that the effects
5115 of @samp{__builtin_expect} are easier to understand.
5117 The default is @option{-fguess-branch-probability} at levels
5118 @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5120 @item -freorder-blocks
5121 @opindex freorder-blocks
5122 Reorder basic blocks in the compiled function in order to reduce number of
5123 taken branches and improve code locality.
5125 Enabled at levels @option{-O2}, @option{-O3}.
5127 @item -freorder-blocks-and-partition
5128 @opindex freorder-blocks-and-partition
5129 In addition to reordering basic blocks in the compiled function, in order
5130 to reduce number of taken branches, partitions hot and cold basic blocks
5131 into separate sections of the assembly and .o files, to improve
5132 paging and cache locality performance.
5134 This optimization is automatically turned off in the presence of
5135 exception handling, for linkonce sections, for functions with a user-defined
5136 section attribute and on any architecture that does not support named
5139 @item -freorder-functions
5140 @opindex freorder-functions
5141 Reorder functions in the object file in order to
5142 improve code locality. This is implemented by using special
5143 subsections @code{.text.hot} for most frequently executed functions and
5144 @code{.text.unlikely} for unlikely executed functions. Reordering is done by
5145 the linker so object file format must support named sections and linker must
5146 place them in a reasonable way.
5148 Also profile feedback must be available in to make this option effective. See
5149 @option{-fprofile-arcs} for details.
5151 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5153 @item -fstrict-aliasing
5154 @opindex fstrict-aliasing
5155 Allows the compiler to assume the strictest aliasing rules applicable to
5156 the language being compiled. For C (and C++), this activates
5157 optimizations based on the type of expressions. In particular, an
5158 object of one type is assumed never to reside at the same address as an
5159 object of a different type, unless the types are almost the same. For
5160 example, an @code{unsigned int} can alias an @code{int}, but not a
5161 @code{void*} or a @code{double}. A character type may alias any other
5164 Pay special attention to code like this:
5177 The practice of reading from a different union member than the one most
5178 recently written to (called ``type-punning'') is common. Even with
5179 @option{-fstrict-aliasing}, type-punning is allowed, provided the memory
5180 is accessed through the union type. So, the code above will work as
5181 expected. However, this code might not:
5192 Every language that wishes to perform language-specific alias analysis
5193 should define a function that computes, given an @code{tree}
5194 node, an alias set for the node. Nodes in different alias sets are not
5195 allowed to alias. For an example, see the C front-end function
5196 @code{c_get_alias_set}.
5198 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5200 @item -fstrict-overflow
5201 @opindex fstrict-overflow
5202 Allow the compiler to assume strict signed overflow rules, depending
5203 on the language being compiled. For C (and C++) this means that
5204 overflow when doing arithmetic with signed numbers is undefined, which
5205 means that the compiler may assume that it will not happen. This
5206 permits various optimizations. For example, the compiler will assume
5207 that an expression like @code{i + 10 > i} will always be true for
5208 signed @code{i}. This assumption is only valid if signed overflow is
5209 undefined, as the expression is false if @code{i + 10} overflows when
5210 using twos complement arithmetic. When this option is in effect any
5211 attempt to determine whether an operation on signed numbers will
5212 overflow must be written carefully to not actually involve overflow.
5214 See also the @option{-fwrapv} option. Using @option{-fwrapv} means
5215 that signed overflow is fully defined: it wraps. When
5216 @option{-fwrapv} is used, there is no difference between
5217 @option{-fstrict-overflow} and @option{-fno-strict-overflow}. With
5218 @option{-fwrapv} certain types of overflow are permitted. For
5219 example, if the compiler gets an overflow when doing arithmetic on
5220 constants, the overflowed value can still be used with
5221 @option{-fwrapv}, but not otherwise.
5223 The @option{-fstrict-overflow} option is enabled at levels
5224 @option{-O2}, @option{-O3}, @option{-Os}.
5226 @item -falign-functions
5227 @itemx -falign-functions=@var{n}
5228 @opindex falign-functions
5229 Align the start of functions to the next power-of-two greater than
5230 @var{n}, skipping up to @var{n} bytes. For instance,
5231 @option{-falign-functions=32} aligns functions to the next 32-byte
5232 boundary, but @option{-falign-functions=24} would align to the next
5233 32-byte boundary only if this can be done by skipping 23 bytes or less.
5235 @option{-fno-align-functions} and @option{-falign-functions=1} are
5236 equivalent and mean that functions will not be aligned.
5238 Some assemblers only support this flag when @var{n} is a power of two;
5239 in that case, it is rounded up.
5241 If @var{n} is not specified or is zero, use a machine-dependent default.
5243 Enabled at levels @option{-O2}, @option{-O3}.
5245 @item -falign-labels
5246 @itemx -falign-labels=@var{n}
5247 @opindex falign-labels
5248 Align all branch targets to a power-of-two boundary, skipping up to
5249 @var{n} bytes like @option{-falign-functions}. This option can easily
5250 make code slower, because it must insert dummy operations for when the
5251 branch target is reached in the usual flow of the code.
5253 @option{-fno-align-labels} and @option{-falign-labels=1} are
5254 equivalent and mean that labels will not be aligned.
5256 If @option{-falign-loops} or @option{-falign-jumps} are applicable and
5257 are greater than this value, then their values are used instead.
5259 If @var{n} is not specified or is zero, use a machine-dependent default
5260 which is very likely to be @samp{1}, meaning no alignment.
5262 Enabled at levels @option{-O2}, @option{-O3}.
5265 @itemx -falign-loops=@var{n}
5266 @opindex falign-loops
5267 Align loops to a power-of-two boundary, skipping up to @var{n} bytes
5268 like @option{-falign-functions}. The hope is that the loop will be
5269 executed many times, which will make up for any execution of the dummy
5272 @option{-fno-align-loops} and @option{-falign-loops=1} are
5273 equivalent and mean that loops will not be aligned.
5275 If @var{n} is not specified or is zero, use a machine-dependent default.
5277 Enabled at levels @option{-O2}, @option{-O3}.
5280 @itemx -falign-jumps=@var{n}
5281 @opindex falign-jumps
5282 Align branch targets to a power-of-two boundary, for branch targets
5283 where the targets can only be reached by jumping, skipping up to @var{n}
5284 bytes like @option{-falign-functions}. In this case, no dummy operations
5287 @option{-fno-align-jumps} and @option{-falign-jumps=1} are
5288 equivalent and mean that loops will not be aligned.
5290 If @var{n} is not specified or is zero, use a machine-dependent default.
5292 Enabled at levels @option{-O2}, @option{-O3}.
5294 @item -funit-at-a-time
5295 @opindex funit-at-a-time
5296 Parse the whole compilation unit before starting to produce code.
5297 This allows some extra optimizations to take place but consumes
5298 more memory (in general). There are some compatibility issues
5299 with @emph{unit-at-a-time} mode:
5302 enabling @emph{unit-at-a-time} mode may change the order
5303 in which functions, variables, and top-level @code{asm} statements
5304 are emitted, and will likely break code relying on some particular
5305 ordering. The majority of such top-level @code{asm} statements,
5306 though, can be replaced by @code{section} attributes. The
5307 @option{fno-toplevel-reorder} option may be used to keep the ordering
5308 used in the input file, at the cost of some optimizations.
5311 @emph{unit-at-a-time} mode removes unreferenced static variables
5312 and functions. This may result in undefined references
5313 when an @code{asm} statement refers directly to variables or functions
5314 that are otherwise unused. In that case either the variable/function
5315 shall be listed as an operand of the @code{asm} statement operand or,
5316 in the case of top-level @code{asm} statements the attribute @code{used}
5317 shall be used on the declaration.
5320 Static functions now can use non-standard passing conventions that
5321 may break @code{asm} statements calling functions directly. Again,
5322 attribute @code{used} will prevent this behavior.
5325 As a temporary workaround, @option{-fno-unit-at-a-time} can be used,
5326 but this scheme may not be supported by future releases of GCC@.
5328 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5330 @item -fno-toplevel-reorder
5331 Do not reorder top-level functions, variables, and @code{asm}
5332 statements. Output them in the same order that they appear in the
5333 input file. When this option is used, unreferenced static variables
5334 will not be removed. This option is intended to support existing code
5335 which relies on a particular ordering. For new code, it is better to
5340 Constructs webs as commonly used for register allocation purposes and assign
5341 each web individual pseudo register. This allows the register allocation pass
5342 to operate on pseudos directly, but also strengthens several other optimization
5343 passes, such as CSE, loop optimizer and trivial dead code remover. It can,
5344 however, make debugging impossible, since variables will no longer stay in a
5347 Enabled by default with @option{-funroll-loops}.
5349 @item -fwhole-program
5350 @opindex fwhole-program
5351 Assume that the current compilation unit represents whole program being
5352 compiled. All public functions and variables with the exception of @code{main}
5353 and those merged by attribute @code{externally_visible} become static functions
5354 and in a affect gets more aggressively optimized by interprocedural optimizers.
5355 While this option is equivalent to proper use of @code{static} keyword for
5356 programs consisting of single file, in combination with option
5357 @option{--combine} this flag can be used to compile most of smaller scale C
5358 programs since the functions and variables become local for the whole combined
5359 compilation unit, not for the single source file itself.
5362 @item -fno-cprop-registers
5363 @opindex fno-cprop-registers
5364 After register allocation and post-register allocation instruction splitting,
5365 we perform a copy-propagation pass to try to reduce scheduling dependencies
5366 and occasionally eliminate the copy.
5368 Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5370 @item -fprofile-generate
5371 @opindex fprofile-generate
5373 Enable options usually used for instrumenting application to produce
5374 profile useful for later recompilation with profile feedback based
5375 optimization. You must use @option{-fprofile-generate} both when
5376 compiling and when linking your program.
5378 The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
5381 @opindex fprofile-use
5382 Enable profile feedback directed optimizations, and optimizations
5383 generally profitable only with profile feedback available.
5385 The following options are enabled: @code{-fbranch-probabilities}, @code{-fvpt},
5386 @code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}
5390 The following options control compiler behavior regarding floating
5391 point arithmetic. These options trade off between speed and
5392 correctness. All must be specifically enabled.
5396 @opindex ffloat-store
5397 Do not store floating point variables in registers, and inhibit other
5398 options that might change whether a floating point value is taken from a
5401 @cindex floating point precision
5402 This option prevents undesirable excess precision on machines such as
5403 the 68000 where the floating registers (of the 68881) keep more
5404 precision than a @code{double} is supposed to have. Similarly for the
5405 x86 architecture. For most programs, the excess precision does only
5406 good, but a few programs rely on the precise definition of IEEE floating
5407 point. Use @option{-ffloat-store} for such programs, after modifying
5408 them to store all pertinent intermediate computations into variables.
5412 Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
5413 @option{-fno-trapping-math}, @option{-ffinite-math-only},
5414 @option{-fno-rounding-math}, @option{-fno-signaling-nans}
5415 and @option{fcx-limited-range}.
5417 This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
5419 This option should never be turned on by any @option{-O} option since
5420 it can result in incorrect output for programs which depend on
5421 an exact implementation of IEEE or ISO rules/specifications for
5424 @item -fno-math-errno
5425 @opindex fno-math-errno
5426 Do not set ERRNO after calling math functions that are executed
5427 with a single instruction, e.g., sqrt. A program that relies on
5428 IEEE exceptions for math error handling may want to use this flag
5429 for speed while maintaining IEEE arithmetic compatibility.
5431 This option should never be turned on by any @option{-O} option since
5432 it can result in incorrect output for programs which depend on
5433 an exact implementation of IEEE or ISO rules/specifications for
5436 The default is @option{-fmath-errno}.
5438 On Darwin and FreeBSD systems, the math library never sets @code{errno}.
5440 no reason for the compiler to consider the possibility that it might,
5441 and @option{-fno-math-errno} is the default.
5443 @item -funsafe-math-optimizations
5444 @opindex funsafe-math-optimizations
5445 Allow optimizations for floating-point arithmetic that (a) assume
5446 that arguments and results are valid and (b) may violate IEEE or
5447 ANSI standards. When used at link-time, it may include libraries
5448 or startup files that change the default FPU control word or other
5449 similar optimizations.
5451 This option should never be turned on by any @option{-O} option since
5452 it can result in incorrect output for programs which depend on
5453 an exact implementation of IEEE or ISO rules/specifications for
5456 The default is @option{-fno-unsafe-math-optimizations}.
5458 @item -ffinite-math-only
5459 @opindex ffinite-math-only
5460 Allow optimizations for floating-point arithmetic that assume
5461 that arguments and results are not NaNs or +-Infs.
5463 This option should never be turned on by any @option{-O} option since
5464 it can result in incorrect output for programs which depend on
5465 an exact implementation of IEEE or ISO rules/specifications.
5467 The default is @option{-fno-finite-math-only}.
5469 @item -fno-trapping-math
5470 @opindex fno-trapping-math
5471 Compile code assuming that floating-point operations cannot generate
5472 user-visible traps. These traps include division by zero, overflow,
5473 underflow, inexact result and invalid operation. This option implies
5474 @option{-fno-signaling-nans}. Setting this option may allow faster
5475 code if one relies on ``non-stop'' IEEE arithmetic, for example.
5477 This option should never be turned on by any @option{-O} option since
5478 it can result in incorrect output for programs which depend on
5479 an exact implementation of IEEE or ISO rules/specifications for
5482 The default is @option{-ftrapping-math}.
5484 @item -frounding-math
5485 @opindex frounding-math
5486 Disable transformations and optimizations that assume default floating
5487 point rounding behavior. This is round-to-zero for all floating point
5488 to integer conversions, and round-to-nearest for all other arithmetic
5489 truncations. This option should be specified for programs that change
5490 the FP rounding mode dynamically, or that may be executed with a
5491 non-default rounding mode. This option disables constant folding of
5492 floating point expressions at compile-time (which may be affected by
5493 rounding mode) and arithmetic transformations that are unsafe in the
5494 presence of sign-dependent rounding modes.
5496 The default is @option{-fno-rounding-math}.
5498 This option is experimental and does not currently guarantee to
5499 disable all GCC optimizations that are affected by rounding mode.
5500 Future versions of GCC may provide finer control of this setting
5501 using C99's @code{FENV_ACCESS} pragma. This command line option
5502 will be used to specify the default state for @code{FENV_ACCESS}.
5504 @item -frtl-abstract-sequences
5505 @opindex frtl-abstract-sequences
5506 It is a size optimization method. This option is to find identical
5507 sequences of code, which can be turned into pseudo-procedures and
5508 then replace all occurrences with calls to the newly created
5509 subroutine. It is kind of an opposite of @option{-finline-functions}.
5510 This optimization runs at RTL level.
5512 @item -fsignaling-nans
5513 @opindex fsignaling-nans
5514 Compile code assuming that IEEE signaling NaNs may generate user-visible
5515 traps during floating-point operations. Setting this option disables
5516 optimizations that may change the number of exceptions visible with
5517 signaling NaNs. This option implies @option{-ftrapping-math}.
5519 This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
5522 The default is @option{-fno-signaling-nans}.
5524 This option is experimental and does not currently guarantee to
5525 disable all GCC optimizations that affect signaling NaN behavior.
5527 @item -fsingle-precision-constant
5528 @opindex fsingle-precision-constant
5529 Treat floating point constant as single precision constant instead of
5530 implicitly converting it to double precision constant.
5532 @item -fcx-limited-range
5533 @itemx -fno-cx-limited-range
5534 @opindex fcx-limited-range
5535 @opindex fno-cx-limited-range
5536 When enabled, this option states that a range reduction step is not
5537 needed when performing complex division. The default is
5538 @option{-fno-cx-limited-range}, but is enabled by @option{-ffast-math}.
5540 This option controls the default setting of the ISO C99
5541 @code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to
5546 The following options control optimizations that may improve
5547 performance, but are not enabled by any @option{-O} options. This
5548 section includes experimental options that may produce broken code.
5551 @item -fbranch-probabilities
5552 @opindex fbranch-probabilities
5553 After running a program compiled with @option{-fprofile-arcs}
5554 (@pxref{Debugging Options,, Options for Debugging Your Program or
5555 @command{gcc}}), you can compile it a second time using
5556 @option{-fbranch-probabilities}, to improve optimizations based on
5557 the number of times each branch was taken. When the program
5558 compiled with @option{-fprofile-arcs} exits it saves arc execution
5559 counts to a file called @file{@var{sourcename}.gcda} for each source
5560 file The information in this data file is very dependent on the
5561 structure of the generated code, so you must use the same source code
5562 and the same optimization options for both compilations.
5564 With @option{-fbranch-probabilities}, GCC puts a
5565 @samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
5566 These can be used to improve optimization. Currently, they are only
5567 used in one place: in @file{reorg.c}, instead of guessing which path a
5568 branch is mostly to take, the @samp{REG_BR_PROB} values are used to
5569 exactly determine which path is taken more often.
5571 @item -fprofile-values
5572 @opindex fprofile-values
5573 If combined with @option{-fprofile-arcs}, it adds code so that some
5574 data about values of expressions in the program is gathered.
5576 With @option{-fbranch-probabilities}, it reads back the data gathered
5577 from profiling values of expressions and adds @samp{REG_VALUE_PROFILE}
5578 notes to instructions for their later usage in optimizations.
5580 Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
5584 If combined with @option{-fprofile-arcs}, it instructs the compiler to add
5585 a code to gather information about values of expressions.
5587 With @option{-fbranch-probabilities}, it reads back the data gathered
5588 and actually performs the optimizations based on them.
5589 Currently the optimizations include specialization of division operation
5590 using the knowledge about the value of the denominator.
5592 @item -frename-registers
5593 @opindex frename-registers
5594 Attempt to avoid false dependencies in scheduled code by making use
5595 of registers left over after register allocation. This optimization
5596 will most benefit processors with lots of registers. Depending on the
5597 debug information format adopted by the target, however, it can
5598 make debugging impossible, since variables will no longer stay in
5599 a ``home register''.
5601 Enabled by default with @option{-funroll-loops}.
5605 Perform tail duplication to enlarge superblock size. This transformation
5606 simplifies the control flow of the function allowing other optimizations to do
5609 Enabled with @option{-fprofile-use}.
5611 @item -funroll-loops
5612 @opindex funroll-loops
5613 Unroll loops whose number of iterations can be determined at compile time or
5614 upon entry to the loop. @option{-funroll-loops} implies
5615 @option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.
5616 It also turns on complete loop peeling (i.e.@: complete removal of loops with
5617 small constant number of iterations). This option makes code larger, and may
5618 or may not make it run faster.
5620 Enabled with @option{-fprofile-use}.
5622 @item -funroll-all-loops
5623 @opindex funroll-all-loops
5624 Unroll all loops, even if their number of iterations is uncertain when
5625 the loop is entered. This usually makes programs run more slowly.
5626 @option{-funroll-all-loops} implies the same options as
5627 @option{-funroll-loops}.
5630 @opindex fpeel-loops
5631 Peels the loops for that there is enough information that they do not
5632 roll much (from profile feedback). It also turns on complete loop peeling
5633 (i.e.@: complete removal of loops with small constant number of iterations).
5635 Enabled with @option{-fprofile-use}.
5637 @item -fmove-loop-invariants
5638 @opindex fmove-loop-invariants
5639 Enables the loop invariant motion pass in the RTL loop optimizer. Enabled
5640 at level @option{-O1}
5642 @item -funswitch-loops
5643 @opindex funswitch-loops
5644 Move branches with loop invariant conditions out of the loop, with duplicates
5645 of the loop on both branches (modified according to result of the condition).
5647 @item -ffunction-sections
5648 @itemx -fdata-sections
5649 @opindex ffunction-sections
5650 @opindex fdata-sections
5651 Place each function or data item into its own section in the output
5652 file if the target supports arbitrary sections. The name of the
5653 function or the name of the data item determines the section's name
5656 Use these options on systems where the linker can perform optimizations
5657 to improve locality of reference in the instruction space. Most systems
5658 using the ELF object format and SPARC processors running Solaris 2 have
5659 linkers with such optimizations. AIX may have these optimizations in
5662 Only use these options when there are significant benefits from doing
5663 so. When you specify these options, the assembler and linker will
5664 create larger object and executable files and will also be slower.
5665 You will not be able to use @code{gprof} on all systems if you
5666 specify this option and you may have problems with debugging if
5667 you specify both this option and @option{-g}.
5669 @item -fbranch-target-load-optimize
5670 @opindex fbranch-target-load-optimize
5671 Perform branch target register load optimization before prologue / epilogue
5673 The use of target registers can typically be exposed only during reload,
5674 thus hoisting loads out of loops and doing inter-block scheduling needs
5675 a separate optimization pass.
5677 @item -fbranch-target-load-optimize2
5678 @opindex fbranch-target-load-optimize2
5679 Perform branch target register load optimization after prologue / epilogue
5682 @item -fbtr-bb-exclusive
5683 @opindex fbtr-bb-exclusive
5684 When performing branch target register load optimization, don't reuse
5685 branch target registers in within any basic block.
5687 @item -fstack-protector
5688 Emit extra code to check for buffer overflows, such as stack smashing
5689 attacks. This is done by adding a guard variable to functions with
5690 vulnerable objects. This includes functions that call alloca, and
5691 functions with buffers larger than 8 bytes. The guards are initialized
5692 when a function is entered and then checked when the function exits.
5693 If a guard check fails, an error message is printed and the program exits.
5695 @item -fstack-protector-all
5696 Like @option{-fstack-protector} except that all functions are protected.
5698 @item -fsection-anchors
5699 @opindex fsection-anchors
5700 Try to reduce the number of symbolic address calculations by using
5701 shared ``anchor'' symbols to address nearby objects. This transformation
5702 can help to reduce the number of GOT entries and GOT accesses on some
5705 For example, the implementation of the following function @code{foo}:
5709 int foo (void) @{ return a + b + c; @}
5712 would usually calculate the addresses of all three variables, but if you
5713 compile it with @option{-fsection-anchors}, it will access the variables
5714 from a common anchor point instead. The effect is similar to the
5715 following pseudocode (which isn't valid C):
5720 register int *xr = &x;
5721 return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
5725 Not all targets support this option.
5727 @item --param @var{name}=@var{value}
5729 In some places, GCC uses various constants to control the amount of
5730 optimization that is done. For example, GCC will not inline functions
5731 that contain more that a certain number of instructions. You can
5732 control some of these constants on the command-line using the
5733 @option{--param} option.
5735 The names of specific parameters, and the meaning of the values, are
5736 tied to the internals of the compiler, and are subject to change
5737 without notice in future releases.
5739 In each case, the @var{value} is an integer. The allowable choices for
5740 @var{name} are given in the following table:
5743 @item salias-max-implicit-fields
5744 The maximum number of fields in a variable without direct
5745 structure accesses for which structure aliasing will consider trying
5746 to track each field. The default is 5
5748 @item salias-max-array-elements
5749 The maximum number of elements an array can have and its elements
5750 still be tracked individually by structure aliasing. The default is 4
5752 @item sra-max-structure-size
5753 The maximum structure size, in bytes, at which the scalar replacement
5754 of aggregates (SRA) optimization will perform block copies. The
5755 default value, 0, implies that GCC will select the most appropriate
5758 @item sra-field-structure-ratio
5759 The threshold ratio (as a percentage) between instantiated fields and
5760 the complete structure size. We say that if the ratio of the number
5761 of bytes in instantiated fields to the number of bytes in the complete
5762 structure exceeds this parameter, then block copies are not used. The
5765 @item max-crossjump-edges
5766 The maximum number of incoming edges to consider for crossjumping.
5767 The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
5768 the number of edges incoming to each block. Increasing values mean
5769 more aggressive optimization, making the compile time increase with
5770 probably small improvement in executable size.
5772 @item min-crossjump-insns
5773 The minimum number of instructions which must be matched at the end
5774 of two blocks before crossjumping will be performed on them. This
5775 value is ignored in the case where all instructions in the block being
5776 crossjumped from are matched. The default value is 5.
5778 @item max-grow-copy-bb-insns
5779 The maximum code size expansion factor when copying basic blocks
5780 instead of jumping. The expansion is relative to a jump instruction.
5781 The default value is 8.
5783 @item max-goto-duplication-insns
5784 The maximum number of instructions to duplicate to a block that jumps
5785 to a computed goto. To avoid @math{O(N^2)} behavior in a number of
5786 passes, GCC factors computed gotos early in the compilation process,
5787 and unfactors them as late as possible. Only computed jumps at the
5788 end of a basic blocks with no more than max-goto-duplication-insns are
5789 unfactored. The default value is 8.
5791 @item max-delay-slot-insn-search
5792 The maximum number of instructions to consider when looking for an
5793 instruction to fill a delay slot. If more than this arbitrary number of
5794 instructions is searched, the time savings from filling the delay slot
5795 will be minimal so stop searching. Increasing values mean more
5796 aggressive optimization, making the compile time increase with probably
5797 small improvement in executable run time.
5799 @item max-delay-slot-live-search
5800 When trying to fill delay slots, the maximum number of instructions to
5801 consider when searching for a block with valid live register
5802 information. Increasing this arbitrarily chosen value means more
5803 aggressive optimization, increasing the compile time. This parameter
5804 should be removed when the delay slot code is rewritten to maintain the
5807 @item max-gcse-memory
5808 The approximate maximum amount of memory that will be allocated in
5809 order to perform the global common subexpression elimination
5810 optimization. If more memory than specified is required, the
5811 optimization will not be done.
5813 @item max-gcse-passes
5814 The maximum number of passes of GCSE to run. The default is 1.
5816 @item max-pending-list-length
5817 The maximum number of pending dependencies scheduling will allow
5818 before flushing the current state and starting over. Large functions
5819 with few branches or calls can create excessively large lists which
5820 needlessly consume memory and resources.
5822 @item max-inline-insns-single
5823 Several parameters control the tree inliner used in gcc.
5824 This number sets the maximum number of instructions (counted in GCC's
5825 internal representation) in a single function that the tree inliner
5826 will consider for inlining. This only affects functions declared
5827 inline and methods implemented in a class declaration (C++).
5828 The default value is 450.
5830 @item max-inline-insns-auto
5831 When you use @option{-finline-functions} (included in @option{-O3}),
5832 a lot of functions that would otherwise not be considered for inlining
5833 by the compiler will be investigated. To those functions, a different
5834 (more restrictive) limit compared to functions declared inline can
5836 The default value is 90.
5838 @item large-function-insns
5839 The limit specifying really large functions. For functions larger than this
5840 limit after inlining inlining is constrained by
5841 @option{--param large-function-growth}. This parameter is useful primarily
5842 to avoid extreme compilation time caused by non-linear algorithms used by the
5844 This parameter is ignored when @option{-funit-at-a-time} is not used.
5845 The default value is 2700.
5847 @item large-function-growth
5848 Specifies maximal growth of large function caused by inlining in percents.
5849 This parameter is ignored when @option{-funit-at-a-time} is not used.
5850 The default value is 100 which limits large function growth to 2.0 times
5853 @item large-unit-insns
5854 The limit specifying large translation unit. Growth caused by inlining of
5855 units larger than this limit is limited by @option{--param inline-unit-growth}.
5856 For small units this might be too tight (consider unit consisting of function A
5857 that is inline and B that just calls A three time. If B is small relative to
5858 A, the growth of unit is 300\% and yet such inlining is very sane. For very
5859 large units consisting of small inlininable functions however the overall unit
5860 growth limit is needed to avoid exponential explosion of code size. Thus for
5861 smaller units, the size is increased to @option{--param large-unit-insns}
5862 before applying @option{--param inline-unit-growth}. The default is 10000
5864 @item inline-unit-growth
5865 Specifies maximal overall growth of the compilation unit caused by inlining.
5866 This parameter is ignored when @option{-funit-at-a-time} is not used.
5867 The default value is 50 which limits unit growth to 1.5 times the original
5870 @item max-inline-insns-recursive
5871 @itemx max-inline-insns-recursive-auto
5872 Specifies maximum number of instructions out-of-line copy of self recursive inline
5873 function can grow into by performing recursive inlining.
5875 For functions declared inline @option{--param max-inline-insns-recursive} is
5876 taken into account. For function not declared inline, recursive inlining
5877 happens only when @option{-finline-functions} (included in @option{-O3}) is
5878 enabled and @option{--param max-inline-insns-recursive-auto} is used. The
5879 default value is 450.
5881 @item max-inline-recursive-depth
5882 @itemx max-inline-recursive-depth-auto
5883 Specifies maximum recursion depth used by the recursive inlining.
5885 For functions declared inline @option{--param max-inline-recursive-depth} is
5886 taken into account. For function not declared inline, recursive inlining
5887 happens only when @option{-finline-functions} (included in @option{-O3}) is
5888 enabled and @option{--param max-inline-recursive-depth-auto} is used. The
5889 default value is 450.
5891 @item min-inline-recursive-probability
5892 Recursive inlining is profitable only for function having deep recursion
5893 in average and can hurt for function having little recursion depth by
5894 increasing the prologue size or complexity of function body to other
5897 When profile feedback is available (see @option{-fprofile-generate}) the actual
5898 recursion depth can be guessed from probability that function will recurse via
5899 given call expression. This parameter limits inlining only to call expression
5900 whose probability exceeds given threshold (in percents). The default value is
5903 @item inline-call-cost
5904 Specify cost of call instruction relative to simple arithmetics operations
5905 (having cost of 1). Increasing this cost disqualifies inlining of non-leaf
5906 functions and at the same time increases size of leaf function that is believed to
5907 reduce function size by being inlined. In effect it increases amount of
5908 inlining for code having large abstraction penalty (many functions that just
5909 pass the arguments to other functions) and decrease inlining for code with low
5910 abstraction penalty. The default value is 16.
5912 @item max-unrolled-insns
5913 The maximum number of instructions that a loop should have if that loop
5914 is unrolled, and if the loop is unrolled, it determines how many times
5915 the loop code is unrolled.
5917 @item max-average-unrolled-insns
5918 The maximum number of instructions biased by probabilities of their execution
5919 that a loop should have if that loop is unrolled, and if the loop is unrolled,
5920 it determines how many times the loop code is unrolled.
5922 @item max-unroll-times
5923 The maximum number of unrollings of a single loop.
5925 @item max-peeled-insns
5926 The maximum number of instructions that a loop should have if that loop
5927 is peeled, and if the loop is peeled, it determines how many times
5928 the loop code is peeled.
5930 @item max-peel-times
5931 The maximum number of peelings of a single loop.
5933 @item max-completely-peeled-insns
5934 The maximum number of insns of a completely peeled loop.
5936 @item max-completely-peel-times
5937 The maximum number of iterations of a loop to be suitable for complete peeling.
5939 @item max-unswitch-insns
5940 The maximum number of insns of an unswitched loop.
5942 @item max-unswitch-level
5943 The maximum number of branches unswitched in a single loop.
5946 The minimum cost of an expensive expression in the loop invariant motion.
5948 @item iv-consider-all-candidates-bound
5949 Bound on number of candidates for induction variables below that
5950 all candidates are considered for each use in induction variable
5951 optimizations. Only the most relevant candidates are considered
5952 if there are more candidates, to avoid quadratic time complexity.
5954 @item iv-max-considered-uses
5955 The induction variable optimizations give up on loops that contain more
5956 induction variable uses.
5958 @item iv-always-prune-cand-set-bound
5959 If number of candidates in the set is smaller than this value,
5960 we always try to remove unnecessary ivs from the set during its
5961 optimization when a new iv is added to the set.
5963 @item scev-max-expr-size
5964 Bound on size of expressions used in the scalar evolutions analyzer.
5965 Large expressions slow the analyzer.
5967 @item vect-max-version-checks
5968 The maximum number of runtime checks that can be performed when doing
5969 loop versioning in the vectorizer. See option ftree-vect-loop-version
5970 for more information.
5972 @item max-iterations-to-track
5974 The maximum number of iterations of a loop the brute force algorithm
5975 for analysis of # of iterations of the loop tries to evaluate.
5977 @item hot-bb-count-fraction
5978 Select fraction of the maximal count of repetitions of basic block in program
5979 given basic block needs to have to be considered hot.
5981 @item hot-bb-frequency-fraction
5982 Select fraction of the maximal frequency of executions of basic block in
5983 function given basic block needs to have to be considered hot
5985 @item max-predicted-iterations
5986 The maximum number of loop iterations we predict statically. This is useful
5987 in cases where function contain single loop with known bound and other loop
5988 with unknown. We predict the known number of iterations correctly, while
5989 the unknown number of iterations average to roughly 10. This means that the
5990 loop without bounds would appear artificially cold relative to the other one.
5992 @item tracer-dynamic-coverage
5993 @itemx tracer-dynamic-coverage-feedback
5995 This value is used to limit superblock formation once the given percentage of
5996 executed instructions is covered. This limits unnecessary code size
5999 The @option{tracer-dynamic-coverage-feedback} is used only when profile
6000 feedback is available. The real profiles (as opposed to statically estimated
6001 ones) are much less balanced allowing the threshold to be larger value.
6003 @item tracer-max-code-growth
6004 Stop tail duplication once code growth has reached given percentage. This is
6005 rather hokey argument, as most of the duplicates will be eliminated later in
6006 cross jumping, so it may be set to much higher values than is the desired code
6009 @item tracer-min-branch-ratio
6011 Stop reverse growth when the reverse probability of best edge is less than this
6012 threshold (in percent).
6014 @item tracer-min-branch-ratio
6015 @itemx tracer-min-branch-ratio-feedback
6017 Stop forward growth if the best edge do have probability lower than this
6020 Similarly to @option{tracer-dynamic-coverage} two values are present, one for
6021 compilation for profile feedback and one for compilation without. The value
6022 for compilation with profile feedback needs to be more conservative (higher) in
6023 order to make tracer effective.
6025 @item max-cse-path-length
6027 Maximum number of basic blocks on path that cse considers. The default is 10.
6030 The maximum instructions CSE process before flushing. The default is 1000.
6032 @item global-var-threshold
6034 Counts the number of function calls (@var{n}) and the number of
6035 call-clobbered variables (@var{v}). If @var{n}x@var{v} is larger than this limit, a
6036 single artificial variable will be created to represent all the
6037 call-clobbered variables at function call sites. This artificial
6038 variable will then be made to alias every call-clobbered variable.
6039 (done as @code{int * size_t} on the host machine; beware overflow).
6041 @item max-aliased-vops
6043 Maximum number of virtual operands allowed to represent aliases
6044 before triggering the alias grouping heuristic. Alias grouping
6045 reduces compile times and memory consumption needed for aliasing at
6046 the expense of precision loss in alias information.
6048 @item ggc-min-expand
6050 GCC uses a garbage collector to manage its own memory allocation. This
6051 parameter specifies the minimum percentage by which the garbage
6052 collector's heap should be allowed to expand between collections.
6053 Tuning this may improve compilation speed; it has no effect on code
6056 The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
6057 RAM >= 1GB@. If @code{getrlimit} is available, the notion of "RAM" is
6058 the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If
6059 GCC is not able to calculate RAM on a particular platform, the lower
6060 bound of 30% is used. Setting this parameter and
6061 @option{ggc-min-heapsize} to zero causes a full collection to occur at
6062 every opportunity. This is extremely slow, but can be useful for
6065 @item ggc-min-heapsize
6067 Minimum size of the garbage collector's heap before it begins bothering
6068 to collect garbage. The first collection occurs after the heap expands
6069 by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again,
6070 tuning this may improve compilation speed, and has no effect on code
6073 The default is the smaller of RAM/8, RLIMIT_RSS, or a limit which
6074 tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
6075 with a lower bound of 4096 (four megabytes) and an upper bound of
6076 131072 (128 megabytes). If GCC is not able to calculate RAM on a
6077 particular platform, the lower bound is used. Setting this parameter
6078 very large effectively disables garbage collection. Setting this
6079 parameter and @option{ggc-min-expand} to zero causes a full collection
6080 to occur at every opportunity.
6082 @item max-reload-search-insns
6083 The maximum number of instruction reload should look backward for equivalent
6084 register. Increasing values mean more aggressive optimization, making the
6085 compile time increase with probably slightly better performance. The default
6088 @item max-cselib-memory-locations
6089 The maximum number of memory locations cselib should take into account.
6090 Increasing values mean more aggressive optimization, making the compile time
6091 increase with probably slightly better performance. The default value is 500.
6093 @item max-flow-memory-locations
6094 Similar as @option{max-cselib-memory-locations} but for dataflow liveness.
6095 The default value is 100.
6097 @item reorder-blocks-duplicate
6098 @itemx reorder-blocks-duplicate-feedback
6100 Used by basic block reordering pass to decide whether to use unconditional
6101 branch or duplicate the code on its destination. Code is duplicated when its
6102 estimated size is smaller than this value multiplied by the estimated size of
6103 unconditional jump in the hot spots of the program.
6105 The @option{reorder-block-duplicate-feedback} is used only when profile
6106 feedback is available and may be set to higher values than
6107 @option{reorder-block-duplicate} since information about the hot spots is more
6110 @item max-sched-ready-insns
6111 The maximum number of instructions ready to be issued the scheduler should
6112 consider at any given time during the first scheduling pass. Increasing
6113 values mean more thorough searches, making the compilation time increase
6114 with probably little benefit. The default value is 100.
6116 @item max-sched-region-blocks
6117 The maximum number of blocks in a region to be considered for
6118 interblock scheduling. The default value is 10.
6120 @item max-sched-region-insns
6121 The maximum number of insns in a region to be considered for
6122 interblock scheduling. The default value is 100.
6125 The minimum probability (in percents) of reaching a source block
6126 for interblock speculative scheduling. The default value is 40.
6128 @item max-sched-extend-regions-iters
6129 The maximum number of iterations through CFG to extend regions.
6130 0 - disable region extension,
6131 N - do at most N iterations.
6132 The default value is 0.
6134 @item max-sched-insn-conflict-delay
6135 The maximum conflict delay for an insn to be considered for speculative motion.
6136 The default value is 3.
6138 @item sched-spec-prob-cutoff
6139 The minimal probability of speculation success (in percents), so that
6140 speculative insn will be scheduled.
6141 The default value is 40.
6143 @item max-last-value-rtl
6145 The maximum size measured as number of RTLs that can be recorded in an expression
6146 in combiner for a pseudo register as last known value of that register. The default
6149 @item integer-share-limit
6150 Small integer constants can use a shared data structure, reducing the
6151 compiler's memory usage and increasing its speed. This sets the maximum
6152 value of a shared integer constant's. The default value is 256.
6154 @item min-virtual-mappings
6155 Specifies the minimum number of virtual mappings in the incremental
6156 SSA updater that should be registered to trigger the virtual mappings
6157 heuristic defined by virtual-mappings-ratio. The default value is
6160 @item virtual-mappings-ratio
6161 If the number of virtual mappings is virtual-mappings-ratio bigger
6162 than the number of virtual symbols to be updated, then the incremental
6163 SSA updater switches to a full update for those symbols. The default
6166 @item ssp-buffer-size
6167 The minimum size of buffers (i.e. arrays) that will receive stack smashing
6168 protection when @option{-fstack-protection} is used.
6170 @item max-jump-thread-duplication-stmts
6171 Maximum number of statements allowed in a block that needs to be
6172 duplicated when threading jumps.
6174 @item max-fields-for-field-sensitive
6175 Maximum number of fields in a structure we will treat in
6176 a field sensitive manner during pointer analysis.
6181 @node Preprocessor Options
6182 @section Options Controlling the Preprocessor
6183 @cindex preprocessor options
6184 @cindex options, preprocessor
6186 These options control the C preprocessor, which is run on each C source
6187 file before actual compilation.
6189 If you use the @option{-E} option, nothing is done except preprocessing.
6190 Some of these options make sense only together with @option{-E} because
6191 they cause the preprocessor output to be unsuitable for actual
6196 You can use @option{-Wp,@var{option}} to bypass the compiler driver
6197 and pass @var{option} directly through to the preprocessor. If
6198 @var{option} contains commas, it is split into multiple options at the
6199 commas. However, many options are modified, translated or interpreted
6200 by the compiler driver before being passed to the preprocessor, and
6201 @option{-Wp} forcibly bypasses this phase. The preprocessor's direct
6202 interface is undocumented and subject to change, so whenever possible
6203 you should avoid using @option{-Wp} and let the driver handle the
6206 @item -Xpreprocessor @var{option}
6207 @opindex preprocessor
6208 Pass @var{option} as an option to the preprocessor. You can use this to
6209 supply system-specific preprocessor options which GCC does not know how to
6212 If you want to pass an option that takes an argument, you must use
6213 @option{-Xpreprocessor} twice, once for the option and once for the argument.
6216 @include cppopts.texi
6218 @node Assembler Options
6219 @section Passing Options to the Assembler
6221 @c prevent bad page break with this line
6222 You can pass options to the assembler.
6225 @item -Wa,@var{option}
6227 Pass @var{option} as an option to the assembler. If @var{option}
6228 contains commas, it is split into multiple options at the commas.
6230 @item -Xassembler @var{option}
6232 Pass @var{option} as an option to the assembler. You can use this to
6233 supply system-specific assembler options which GCC does not know how to
6236 If you want to pass an option that takes an argument, you must use
6237 @option{-Xassembler} twice, once for the option and once for the argument.
6242 @section Options for Linking
6243 @cindex link options
6244 @cindex options, linking
6246 These options come into play when the compiler links object files into
6247 an executable output file. They are meaningless if the compiler is
6248 not doing a link step.
6252 @item @var{object-file-name}
6253 A file name that does not end in a special recognized suffix is
6254 considered to name an object file or library. (Object files are
6255 distinguished from libraries by the linker according to the file
6256 contents.) If linking is done, these object files are used as input
6265 If any of these options is used, then the linker is not run, and
6266 object file names should not be used as arguments. @xref{Overall
6270 @item -l@var{library}
6271 @itemx -l @var{library}
6273 Search the library named @var{library} when linking. (The second
6274 alternative with the library as a separate argument is only for
6275 POSIX compliance and is not recommended.)
6277 It makes a difference where in the command you write this option; the
6278 linker searches and processes libraries and object files in the order they
6279 are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
6280 after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
6281 to functions in @samp{z}, those functions may not be loaded.
6283 The linker searches a standard list of directories for the library,
6284 which is actually a file named @file{lib@var{library}.a}. The linker
6285 then uses this file as if it had been specified precisely by name.
6287 The directories searched include several standard system directories
6288 plus any that you specify with @option{-L}.
6290 Normally the files found this way are library files---archive files
6291 whose members are object files. The linker handles an archive file by
6292 scanning through it for members which define symbols that have so far
6293 been referenced but not defined. But if the file that is found is an
6294 ordinary object file, it is linked in the usual fashion. The only
6295 difference between using an @option{-l} option and specifying a file name
6296 is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
6297 and searches several directories.
6300 @opindex nostartfiles
6301 Do not use the standard system startup files when linking.
6302 The standard system libraries are used normally, unless @option{-nostdlib}
6303 or @option{-nodefaultlibs} is used.
6305 @item -nodefaultlibs
6306 @opindex nodefaultlibs
6307 Do not use the standard system libraries when linking.
6308 Only the libraries you specify will be passed to the linker.
6309 The standard startup files are used normally, unless @option{-nostartfiles}
6310 is used. The compiler may generate calls to @code{memcmp},
6311 @code{memset}, @code{memcpy} and @code{memmove}.
6312 These entries are usually resolved by entries in
6313 libc. These entry points should be supplied through some other
6314 mechanism when this option is specified.
6318 Do not use the standard system startup files or libraries when linking.
6319 No startup files and only the libraries you specify will be passed to
6320 the linker. The compiler may generate calls to @code{memcmp}, @code{memset},
6321 @code{memcpy} and @code{memmove}.
6322 These entries are usually resolved by entries in
6323 libc. These entry points should be supplied through some other
6324 mechanism when this option is specified.
6326 @cindex @option{-lgcc}, use with @option{-nostdlib}
6327 @cindex @option{-nostdlib} and unresolved references
6328 @cindex unresolved references and @option{-nostdlib}
6329 @cindex @option{-lgcc}, use with @option{-nodefaultlibs}
6330 @cindex @option{-nodefaultlibs} and unresolved references
6331 @cindex unresolved references and @option{-nodefaultlibs}
6332 One of the standard libraries bypassed by @option{-nostdlib} and
6333 @option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
6334 that GCC uses to overcome shortcomings of particular machines, or special
6335 needs for some languages.
6336 (@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
6337 Collection (GCC) Internals},
6338 for more discussion of @file{libgcc.a}.)
6339 In most cases, you need @file{libgcc.a} even when you want to avoid
6340 other standard libraries. In other words, when you specify @option{-nostdlib}
6341 or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
6342 This ensures that you have no unresolved references to internal GCC
6343 library subroutines. (For example, @samp{__main}, used to ensure C++
6344 constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
6345 GNU Compiler Collection (GCC) Internals}.)
6349 Produce a position independent executable on targets which support it.
6350 For predictable results, you must also specify the same set of options
6351 that were used to generate code (@option{-fpie}, @option{-fPIE},
6352 or model suboptions) when you specify this option.
6356 Pass the flag @option{-export-dynamic} to the ELF linker, on targets
6357 that support it. This instructs the linker to add all symbols, not
6358 only used ones, to the dynamic symbol table. This option is needed
6359 for some uses of @code{dlopen} or to allow obtaining backtraces
6360 from within a program.
6364 Remove all symbol table and relocation information from the executable.
6368 On systems that support dynamic linking, this prevents linking with the shared
6369 libraries. On other systems, this option has no effect.
6373 Produce a shared object which can then be linked with other objects to
6374 form an executable. Not all systems support this option. For predictable
6375 results, you must also specify the same set of options that were used to
6376 generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
6377 when you specify this option.@footnote{On some systems, @samp{gcc -shared}
6378 needs to build supplementary stub code for constructors to work. On
6379 multi-libbed systems, @samp{gcc -shared} must select the correct support
6380 libraries to link against. Failing to supply the correct flags may lead
6381 to subtle defects. Supplying them in cases where they are not necessary
6384 @item -shared-libgcc
6385 @itemx -static-libgcc
6386 @opindex shared-libgcc
6387 @opindex static-libgcc
6388 On systems that provide @file{libgcc} as a shared library, these options
6389 force the use of either the shared or static version respectively.
6390 If no shared version of @file{libgcc} was built when the compiler was
6391 configured, these options have no effect.
6393 There are several situations in which an application should use the
6394 shared @file{libgcc} instead of the static version. The most common
6395 of these is when the application wishes to throw and catch exceptions
6396 across different shared libraries. In that case, each of the libraries
6397 as well as the application itself should use the shared @file{libgcc}.
6399 Therefore, the G++ and GCJ drivers automatically add
6400 @option{-shared-libgcc} whenever you build a shared library or a main
6401 executable, because C++ and Java programs typically use exceptions, so
6402 this is the right thing to do.
6404 If, instead, you use the GCC driver to create shared libraries, you may
6405 find that they will not always be linked with the shared @file{libgcc}.
6406 If GCC finds, at its configuration time, that you have a non-GNU linker
6407 or a GNU linker that does not support option @option{--eh-frame-hdr},
6408 it will link the shared version of @file{libgcc} into shared libraries
6409 by default. Otherwise, it will take advantage of the linker and optimize
6410 away the linking with the shared version of @file{libgcc}, linking with
6411 the static version of libgcc by default. This allows exceptions to
6412 propagate through such shared libraries, without incurring relocation
6413 costs at library load time.
6415 However, if a library or main executable is supposed to throw or catch
6416 exceptions, you must link it using the G++ or GCJ driver, as appropriate
6417 for the languages used in the program, or using the option
6418 @option{-shared-libgcc}, such that it is linked with the shared
6423 Bind references to global symbols when building a shared object. Warn
6424 about any unresolved references (unless overridden by the link editor
6425 option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
6428 @item -Xlinker @var{option}
6430 Pass @var{option} as an option to the linker. You can use this to
6431 supply system-specific linker options which GCC does not know how to
6434 If you want to pass an option that takes an argument, you must use
6435 @option{-Xlinker} twice, once for the option and once for the argument.
6436 For example, to pass @option{-assert definitions}, you must write
6437 @samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
6438 @option{-Xlinker "-assert definitions"}, because this passes the entire
6439 string as a single argument, which is not what the linker expects.
6441 @item -Wl,@var{option}
6443 Pass @var{option} as an option to the linker. If @var{option} contains
6444 commas, it is split into multiple options at the commas.
6446 @item -u @var{symbol}
6448 Pretend the symbol @var{symbol} is undefined, to force linking of
6449 library modules to define it. You can use @option{-u} multiple times with
6450 different symbols to force loading of additional library modules.
6453 @node Directory Options
6454 @section Options for Directory Search
6455 @cindex directory options
6456 @cindex options, directory search
6459 These options specify directories to search for header files, for
6460 libraries and for parts of the compiler:
6465 Add the directory @var{dir} to the head of the list of directories to be
6466 searched for header files. This can be used to override a system header
6467 file, substituting your own version, since these directories are
6468 searched before the system header file directories. However, you should
6469 not use this option to add directories that contain vendor-supplied
6470 system header files (use @option{-isystem} for that). If you use more than
6471 one @option{-I} option, the directories are scanned in left-to-right
6472 order; the standard system directories come after.
6474 If a standard system include directory, or a directory specified with
6475 @option{-isystem}, is also specified with @option{-I}, the @option{-I}
6476 option will be ignored. The directory will still be searched but as a
6477 system directory at its normal position in the system include chain.
6478 This is to ensure that GCC's procedure to fix buggy system headers and
6479 the ordering for the include_next directive are not inadvertently changed.
6480 If you really need to change the search order for system directories,
6481 use the @option{-nostdinc} and/or @option{-isystem} options.
6483 @item -iquote@var{dir}
6485 Add the directory @var{dir} to the head of the list of directories to
6486 be searched for header files only for the case of @samp{#include
6487 "@var{file}"}; they are not searched for @samp{#include <@var{file}>},
6488 otherwise just like @option{-I}.
6492 Add directory @var{dir} to the list of directories to be searched
6495 @item -B@var{prefix}
6497 This option specifies where to find the executables, libraries,
6498 include files, and data files of the compiler itself.
6500 The compiler driver program runs one or more of the subprograms
6501 @file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
6502 @var{prefix} as a prefix for each program it tries to run, both with and
6503 without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
6505 For each subprogram to be run, the compiler driver first tries the
6506 @option{-B} prefix, if any. If that name is not found, or if @option{-B}
6507 was not specified, the driver tries two standard prefixes, which are
6508 @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of
6509 those results in a file name that is found, the unmodified program
6510 name is searched for using the directories specified in your
6511 @env{PATH} environment variable.
6513 The compiler will check to see if the path provided by the @option{-B}
6514 refers to a directory, and if necessary it will add a directory
6515 separator character at the end of the path.
6517 @option{-B} prefixes that effectively specify directory names also apply
6518 to libraries in the linker, because the compiler translates these
6519 options into @option{-L} options for the linker. They also apply to
6520 includes files in the preprocessor, because the compiler translates these
6521 options into @option{-isystem} options for the preprocessor. In this case,
6522 the compiler appends @samp{include} to the prefix.
6524 The run-time support file @file{libgcc.a} can also be searched for using
6525 the @option{-B} prefix, if needed. If it is not found there, the two
6526 standard prefixes above are tried, and that is all. The file is left
6527 out of the link if it is not found by those means.
6529 Another way to specify a prefix much like the @option{-B} prefix is to use
6530 the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
6533 As a special kludge, if the path provided by @option{-B} is
6534 @file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
6535 9, then it will be replaced by @file{[dir/]include}. This is to help
6536 with boot-strapping the compiler.
6538 @item -specs=@var{file}
6540 Process @var{file} after the compiler reads in the standard @file{specs}
6541 file, in order to override the defaults that the @file{gcc} driver
6542 program uses when determining what switches to pass to @file{cc1},
6543 @file{cc1plus}, @file{as}, @file{ld}, etc. More than one
6544 @option{-specs=@var{file}} can be specified on the command line, and they
6545 are processed in order, from left to right.
6547 @item --sysroot=@var{dir}
6549 Use @var{dir} as the logical root directory for headers and libraries.
6550 For example, if the compiler would normally search for headers in
6551 @file{/usr/include} and libraries in @file{/usr/lib}, it will instead
6552 search @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
6554 If you use both this option and the @option{-isysroot} option, then
6555 the @option{--sysroot} option will apply to libraries, but the
6556 @option{-isysroot} option will apply to header files.
6558 The GNU linker (beginning with version 2.16) has the necessary support
6559 for this option. If your linker does not support this option, the
6560 header file aspect of @option{--sysroot} will still work, but the
6561 library aspect will not.
6565 This option has been deprecated. Please use @option{-iquote} instead for
6566 @option{-I} directories before the @option{-I-} and remove the @option{-I-}.
6567 Any directories you specify with @option{-I} options before the @option{-I-}
6568 option are searched only for the case of @samp{#include "@var{file}"};
6569 they are not searched for @samp{#include <@var{file}>}.
6571 If additional directories are specified with @option{-I} options after
6572 the @option{-I-}, these directories are searched for all @samp{#include}
6573 directives. (Ordinarily @emph{all} @option{-I} directories are used
6576 In addition, the @option{-I-} option inhibits the use of the current
6577 directory (where the current input file came from) as the first search
6578 directory for @samp{#include "@var{file}"}. There is no way to
6579 override this effect of @option{-I-}. With @option{-I.} you can specify
6580 searching the directory which was current when the compiler was
6581 invoked. That is not exactly the same as what the preprocessor does
6582 by default, but it is often satisfactory.
6584 @option{-I-} does not inhibit the use of the standard system directories
6585 for header files. Thus, @option{-I-} and @option{-nostdinc} are
6592 @section Specifying subprocesses and the switches to pass to them
6595 @command{gcc} is a driver program. It performs its job by invoking a
6596 sequence of other programs to do the work of compiling, assembling and
6597 linking. GCC interprets its command-line parameters and uses these to
6598 deduce which programs it should invoke, and which command-line options
6599 it ought to place on their command lines. This behavior is controlled
6600 by @dfn{spec strings}. In most cases there is one spec string for each
6601 program that GCC can invoke, but a few programs have multiple spec
6602 strings to control their behavior. The spec strings built into GCC can
6603 be overridden by using the @option{-specs=} command-line switch to specify
6606 @dfn{Spec files} are plaintext files that are used to construct spec
6607 strings. They consist of a sequence of directives separated by blank
6608 lines. The type of directive is determined by the first non-whitespace
6609 character on the line and it can be one of the following:
6612 @item %@var{command}
6613 Issues a @var{command} to the spec file processor. The commands that can
6617 @item %include <@var{file}>
6619 Search for @var{file} and insert its text at the current point in the
6622 @item %include_noerr <@var{file}>
6623 @cindex %include_noerr
6624 Just like @samp{%include}, but do not generate an error message if the include
6625 file cannot be found.
6627 @item %rename @var{old_name} @var{new_name}
6629 Rename the spec string @var{old_name} to @var{new_name}.
6633 @item *[@var{spec_name}]:
6634 This tells the compiler to create, override or delete the named spec
6635 string. All lines after this directive up to the next directive or
6636 blank line are considered to be the text for the spec string. If this
6637 results in an empty string then the spec will be deleted. (Or, if the
6638 spec did not exist, then nothing will happened.) Otherwise, if the spec
6639 does not currently exist a new spec will be created. If the spec does
6640 exist then its contents will be overridden by the text of this
6641 directive, unless the first character of that text is the @samp{+}
6642 character, in which case the text will be appended to the spec.
6644 @item [@var{suffix}]:
6645 Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
6646 and up to the next directive or blank line are considered to make up the
6647 spec string for the indicated suffix. When the compiler encounters an
6648 input file with the named suffix, it will processes the spec string in
6649 order to work out how to compile that file. For example:
6656 This says that any input file whose name ends in @samp{.ZZ} should be
6657 passed to the program @samp{z-compile}, which should be invoked with the
6658 command-line switch @option{-input} and with the result of performing the
6659 @samp{%i} substitution. (See below.)
6661 As an alternative to providing a spec string, the text that follows a
6662 suffix directive can be one of the following:
6665 @item @@@var{language}
6666 This says that the suffix is an alias for a known @var{language}. This is
6667 similar to using the @option{-x} command-line switch to GCC to specify a
6668 language explicitly. For example:
6675 Says that .ZZ files are, in fact, C++ source files.
6678 This causes an error messages saying:
6681 @var{name} compiler not installed on this system.
6685 GCC already has an extensive list of suffixes built into it.
6686 This directive will add an entry to the end of the list of suffixes, but
6687 since the list is searched from the end backwards, it is effectively
6688 possible to override earlier entries using this technique.
6692 GCC has the following spec strings built into it. Spec files can
6693 override these strings or create their own. Note that individual
6694 targets can also add their own spec strings to this list.
6697 asm Options to pass to the assembler
6698 asm_final Options to pass to the assembler post-processor
6699 cpp Options to pass to the C preprocessor
6700 cc1 Options to pass to the C compiler
6701 cc1plus Options to pass to the C++ compiler
6702 endfile Object files to include at the end of the link
6703 link Options to pass to the linker
6704 lib Libraries to include on the command line to the linker
6705 libgcc Decides which GCC support library to pass to the linker
6706 linker Sets the name of the linker
6707 predefines Defines to be passed to the C preprocessor
6708 signed_char Defines to pass to CPP to say whether @code{char} is signed
6710 startfile Object files to include at the start of the link
6713 Here is a small example of a spec file:
6719 --start-group -lgcc -lc -leval1 --end-group %(old_lib)
6722 This example renames the spec called @samp{lib} to @samp{old_lib} and
6723 then overrides the previous definition of @samp{lib} with a new one.
6724 The new definition adds in some extra command-line options before
6725 including the text of the old definition.
6727 @dfn{Spec strings} are a list of command-line options to be passed to their
6728 corresponding program. In addition, the spec strings can contain
6729 @samp{%}-prefixed sequences to substitute variable text or to
6730 conditionally insert text into the command line. Using these constructs
6731 it is possible to generate quite complex command lines.
6733 Here is a table of all defined @samp{%}-sequences for spec
6734 strings. Note that spaces are not generated automatically around the
6735 results of expanding these sequences. Therefore you can concatenate them
6736 together or combine them with constant text in a single argument.
6740 Substitute one @samp{%} into the program name or argument.
6743 Substitute the name of the input file being processed.
6746 Substitute the basename of the input file being processed.
6747 This is the substring up to (and not including) the last period
6748 and not including the directory.
6751 This is the same as @samp{%b}, but include the file suffix (text after
6755 Marks the argument containing or following the @samp{%d} as a
6756 temporary file name, so that that file will be deleted if GCC exits
6757 successfully. Unlike @samp{%g}, this contributes no text to the
6760 @item %g@var{suffix}
6761 Substitute a file name that has suffix @var{suffix} and is chosen
6762 once per compilation, and mark the argument in the same way as
6763 @samp{%d}. To reduce exposure to denial-of-service attacks, the file
6764 name is now chosen in a way that is hard to predict even when previously
6765 chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
6766 might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
6767 the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
6768 treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
6769 was simply substituted with a file name chosen once per compilation,
6770 without regard to any appended suffix (which was therefore treated
6771 just like ordinary text), making such attacks more likely to succeed.
6773 @item %u@var{suffix}
6774 Like @samp{%g}, but generates a new temporary file name even if
6775 @samp{%u@var{suffix}} was already seen.
6777 @item %U@var{suffix}
6778 Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
6779 new one if there is no such last file name. In the absence of any
6780 @samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
6781 the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
6782 would involve the generation of two distinct file names, one
6783 for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
6784 simply substituted with a file name chosen for the previous @samp{%u},
6785 without regard to any appended suffix.
6787 @item %j@var{suffix}
6788 Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
6789 writable, and if save-temps is off; otherwise, substitute the name
6790 of a temporary file, just like @samp{%u}. This temporary file is not
6791 meant for communication between processes, but rather as a junk
6794 @item %|@var{suffix}
6795 @itemx %m@var{suffix}
6796 Like @samp{%g}, except if @option{-pipe} is in effect. In that case
6797 @samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
6798 all. These are the two most common ways to instruct a program that it
6799 should read from standard input or write to standard output. If you
6800 need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
6801 construct: see for example @file{f/lang-specs.h}.
6803 @item %.@var{SUFFIX}
6804 Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
6805 when it is subsequently output with @samp{%*}. @var{SUFFIX} is
6806 terminated by the next space or %.
6809 Marks the argument containing or following the @samp{%w} as the
6810 designated output file of this compilation. This puts the argument
6811 into the sequence of arguments that @samp{%o} will substitute later.
6814 Substitutes the names of all the output files, with spaces
6815 automatically placed around them. You should write spaces
6816 around the @samp{%o} as well or the results are undefined.
6817 @samp{%o} is for use in the specs for running the linker.
6818 Input files whose names have no recognized suffix are not compiled
6819 at all, but they are included among the output files, so they will
6823 Substitutes the suffix for object files. Note that this is
6824 handled specially when it immediately follows @samp{%g, %u, or %U},
6825 because of the need for those to form complete file names. The
6826 handling is such that @samp{%O} is treated exactly as if it had already
6827 been substituted, except that @samp{%g, %u, and %U} do not currently
6828 support additional @var{suffix} characters following @samp{%O} as they would
6829 following, for example, @samp{.o}.
6832 Substitutes the standard macro predefinitions for the
6833 current target machine. Use this when running @code{cpp}.
6836 Like @samp{%p}, but puts @samp{__} before and after the name of each
6837 predefined macro, except for macros that start with @samp{__} or with
6838 @samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
6842 Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
6843 @option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
6844 @option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
6845 and @option{-imultilib} as necessary.
6848 Current argument is the name of a library or startup file of some sort.
6849 Search for that file in a standard list of directories and substitute
6850 the full name found.
6853 Print @var{str} as an error message. @var{str} is terminated by a newline.
6854 Use this when inconsistent options are detected.
6857 Substitute the contents of spec string @var{name} at this point.
6860 Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
6862 @item %x@{@var{option}@}
6863 Accumulate an option for @samp{%X}.
6866 Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
6870 Output the accumulated assembler options specified by @option{-Wa}.
6873 Output the accumulated preprocessor options specified by @option{-Wp}.
6876 Process the @code{asm} spec. This is used to compute the
6877 switches to be passed to the assembler.
6880 Process the @code{asm_final} spec. This is a spec string for
6881 passing switches to an assembler post-processor, if such a program is
6885 Process the @code{link} spec. This is the spec for computing the
6886 command line passed to the linker. Typically it will make use of the
6887 @samp{%L %G %S %D and %E} sequences.
6890 Dump out a @option{-L} option for each directory that GCC believes might
6891 contain startup files. If the target supports multilibs then the
6892 current multilib directory will be prepended to each of these paths.
6895 Process the @code{lib} spec. This is a spec string for deciding which
6896 libraries should be included on the command line to the linker.
6899 Process the @code{libgcc} spec. This is a spec string for deciding
6900 which GCC support library should be included on the command line to the linker.
6903 Process the @code{startfile} spec. This is a spec for deciding which
6904 object files should be the first ones passed to the linker. Typically
6905 this might be a file named @file{crt0.o}.
6908 Process the @code{endfile} spec. This is a spec string that specifies
6909 the last object files that will be passed to the linker.
6912 Process the @code{cpp} spec. This is used to construct the arguments
6913 to be passed to the C preprocessor.
6916 Process the @code{cc1} spec. This is used to construct the options to be
6917 passed to the actual C compiler (@samp{cc1}).
6920 Process the @code{cc1plus} spec. This is used to construct the options to be
6921 passed to the actual C++ compiler (@samp{cc1plus}).
6924 Substitute the variable part of a matched option. See below.
6925 Note that each comma in the substituted string is replaced by
6929 Remove all occurrences of @code{-S} from the command line. Note---this
6930 command is position dependent. @samp{%} commands in the spec string
6931 before this one will see @code{-S}, @samp{%} commands in the spec string
6932 after this one will not.
6934 @item %:@var{function}(@var{args})
6935 Call the named function @var{function}, passing it @var{args}.
6936 @var{args} is first processed as a nested spec string, then split
6937 into an argument vector in the usual fashion. The function returns
6938 a string which is processed as if it had appeared literally as part
6939 of the current spec.
6941 The following built-in spec functions are provided:
6944 @item @code{if-exists}
6945 The @code{if-exists} spec function takes one argument, an absolute
6946 pathname to a file. If the file exists, @code{if-exists} returns the
6947 pathname. Here is a small example of its usage:
6951 crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
6954 @item @code{if-exists-else}
6955 The @code{if-exists-else} spec function is similar to the @code{if-exists}
6956 spec function, except that it takes two arguments. The first argument is
6957 an absolute pathname to a file. If the file exists, @code{if-exists-else}
6958 returns the pathname. If it does not exist, it returns the second argument.
6959 This way, @code{if-exists-else} can be used to select one file or another,
6960 based on the existence of the first. Here is a small example of its usage:
6964 crt0%O%s %:if-exists(crti%O%s) \
6965 %:if-exists-else(crtbeginT%O%s crtbegin%O%s)
6968 @item @code{replace-outfile}
6969 The @code{replace-outfile} spec function takes two arguments. It looks for the
6970 first argument in the outfiles array and replaces it with the second argument. Here
6971 is a small example of its usage:
6974 %@{static|static-libgcc|static-libstdc++:%:replace-outfile(-lstdc++ \
6982 Substitutes the @code{-S} switch, if that switch was given to GCC@.
6983 If that switch was not specified, this substitutes nothing. Note that
6984 the leading dash is omitted when specifying this option, and it is
6985 automatically inserted if the substitution is performed. Thus the spec
6986 string @samp{%@{foo@}} would match the command-line option @option{-foo}
6987 and would output the command line option @option{-foo}.
6989 @item %W@{@code{S}@}
6990 Like %@{@code{S}@} but mark last argument supplied within as a file to be
6993 @item %@{@code{S}*@}
6994 Substitutes all the switches specified to GCC whose names start
6995 with @code{-S}, but which also take an argument. This is used for
6996 switches like @option{-o}, @option{-D}, @option{-I}, etc.
6997 GCC considers @option{-o foo} as being
6998 one switch whose names starts with @samp{o}. %@{o*@} would substitute this
6999 text, including the space. Thus two arguments would be generated.
7001 @item %@{@code{S}*&@code{T}*@}
7002 Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
7003 (the order of @code{S} and @code{T} in the spec is not significant).
7004 There can be any number of ampersand-separated variables; for each the
7005 wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
7007 @item %@{@code{S}:@code{X}@}
7008 Substitutes @code{X}, if the @samp{-S} switch was given to GCC@.
7010 @item %@{!@code{S}:@code{X}@}
7011 Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@.
7013 @item %@{@code{S}*:@code{X}@}
7014 Substitutes @code{X} if one or more switches whose names start with
7015 @code{-S} are specified to GCC@. Normally @code{X} is substituted only
7016 once, no matter how many such switches appeared. However, if @code{%*}
7017 appears somewhere in @code{X}, then @code{X} will be substituted once
7018 for each matching switch, with the @code{%*} replaced by the part of
7019 that switch that matched the @code{*}.
7021 @item %@{.@code{S}:@code{X}@}
7022 Substitutes @code{X}, if processing a file with suffix @code{S}.
7024 @item %@{!.@code{S}:@code{X}@}
7025 Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
7027 @item %@{@code{S}|@code{P}:@code{X}@}
7028 Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@.
7029 This may be combined with @samp{!}, @samp{.}, and @code{*} sequences as well,
7030 although they have a stronger binding than the @samp{|}. If @code{%*}
7031 appears in @code{X}, all of the alternatives must be starred, and only
7032 the first matching alternative is substituted.
7034 For example, a spec string like this:
7037 %@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
7040 will output the following command-line options from the following input
7041 command-line options:
7046 -d fred.c -foo -baz -boggle
7047 -d jim.d -bar -baz -boggle
7050 @item %@{S:X; T:Y; :D@}
7052 If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was
7053 given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
7054 be as many clauses as you need. This may be combined with @code{.},
7055 @code{!}, @code{|}, and @code{*} as needed.
7060 The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
7061 construct may contain other nested @samp{%} constructs or spaces, or
7062 even newlines. They are processed as usual, as described above.
7063 Trailing white space in @code{X} is ignored. White space may also
7064 appear anywhere on the left side of the colon in these constructs,
7065 except between @code{.} or @code{*} and the corresponding word.
7067 The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
7068 handled specifically in these constructs. If another value of
7069 @option{-O} or the negated form of a @option{-f}, @option{-m}, or
7070 @option{-W} switch is found later in the command line, the earlier
7071 switch value is ignored, except with @{@code{S}*@} where @code{S} is
7072 just one letter, which passes all matching options.
7074 The character @samp{|} at the beginning of the predicate text is used to
7075 indicate that a command should be piped to the following command, but
7076 only if @option{-pipe} is specified.
7078 It is built into GCC which switches take arguments and which do not.
7079 (You might think it would be useful to generalize this to allow each
7080 compiler's spec to say which switches take arguments. But this cannot
7081 be done in a consistent fashion. GCC cannot even decide which input
7082 files have been specified without knowing which switches take arguments,
7083 and it must know which input files to compile in order to tell which
7086 GCC also knows implicitly that arguments starting in @option{-l} are to be
7087 treated as compiler output files, and passed to the linker in their
7088 proper position among the other output files.
7090 @c man begin OPTIONS
7092 @node Target Options
7093 @section Specifying Target Machine and Compiler Version
7094 @cindex target options
7095 @cindex cross compiling
7096 @cindex specifying machine version
7097 @cindex specifying compiler version and target machine
7098 @cindex compiler version, specifying
7099 @cindex target machine, specifying
7101 The usual way to run GCC is to run the executable called @file{gcc}, or
7102 @file{<machine>-gcc} when cross-compiling, or
7103 @file{<machine>-gcc-<version>} to run a version other than the one that
7104 was installed last. Sometimes this is inconvenient, so GCC provides
7105 options that will switch to another cross-compiler or version.
7108 @item -b @var{machine}
7110 The argument @var{machine} specifies the target machine for compilation.
7112 The value to use for @var{machine} is the same as was specified as the
7113 machine type when configuring GCC as a cross-compiler. For
7114 example, if a cross-compiler was configured with @samp{configure
7115 arm-elf}, meaning to compile for an arm processor with elf binaries,
7116 then you would specify @option{-b arm-elf} to run that cross compiler.
7117 Because there are other options beginning with @option{-b}, the
7118 configuration must contain a hyphen.
7120 @item -V @var{version}
7122 The argument @var{version} specifies which version of GCC to run.
7123 This is useful when multiple versions are installed. For example,
7124 @var{version} might be @samp{4.0}, meaning to run GCC version 4.0.
7127 The @option{-V} and @option{-b} options work by running the
7128 @file{<machine>-gcc-<version>} executable, so there's no real reason to
7129 use them if you can just run that directly.
7131 @node Submodel Options
7132 @section Hardware Models and Configurations
7133 @cindex submodel options
7134 @cindex specifying hardware config
7135 @cindex hardware models and configurations, specifying
7136 @cindex machine dependent options
7138 Earlier we discussed the standard option @option{-b} which chooses among
7139 different installed compilers for completely different target
7140 machines, such as VAX vs.@: 68000 vs.@: 80386.
7142 In addition, each of these target machine types can have its own
7143 special options, starting with @samp{-m}, to choose among various
7144 hardware models or configurations---for example, 68010 vs 68020,
7145 floating coprocessor or none. A single installed version of the
7146 compiler can compile for any model or configuration, according to the
7149 Some configurations of the compiler also support additional special
7150 options, usually for compatibility with other compilers on the same
7153 @c This list is ordered alphanumerically by subsection name.
7154 @c It should be the same order and spelling as these options are listed
7155 @c in Machine Dependent Options
7161 * Blackfin Options::
7165 * DEC Alpha Options::
7166 * DEC Alpha/VMS Options::
7168 * GNU/Linux Options::
7171 * i386 and x86-64 Options::
7184 * RS/6000 and PowerPC Options::
7185 * S/390 and zSeries Options::
7189 * System V Options::
7190 * TMS320C3x/C4x Options::
7194 * Xstormy16 Options::
7200 @subsection ARC Options
7203 These options are defined for ARC implementations:
7208 Compile code for little endian mode. This is the default.
7212 Compile code for big endian mode.
7215 @opindex mmangle-cpu
7216 Prepend the name of the cpu to all public symbol names.
7217 In multiple-processor systems, there are many ARC variants with different
7218 instruction and register set characteristics. This flag prevents code
7219 compiled for one cpu to be linked with code compiled for another.
7220 No facility exists for handling variants that are ``almost identical''.
7221 This is an all or nothing option.
7223 @item -mcpu=@var{cpu}
7225 Compile code for ARC variant @var{cpu}.
7226 Which variants are supported depend on the configuration.
7227 All variants support @option{-mcpu=base}, this is the default.
7229 @item -mtext=@var{text-section}
7230 @itemx -mdata=@var{data-section}
7231 @itemx -mrodata=@var{readonly-data-section}
7235 Put functions, data, and readonly data in @var{text-section},
7236 @var{data-section}, and @var{readonly-data-section} respectively
7237 by default. This can be overridden with the @code{section} attribute.
7238 @xref{Variable Attributes}.
7243 @subsection ARM Options
7246 These @samp{-m} options are defined for Advanced RISC Machines (ARM)
7250 @item -mabi=@var{name}
7252 Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu},
7253 @samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.
7256 @opindex mapcs-frame
7257 Generate a stack frame that is compliant with the ARM Procedure Call
7258 Standard for all functions, even if this is not strictly necessary for
7259 correct execution of the code. Specifying @option{-fomit-frame-pointer}
7260 with this option will cause the stack frames not to be generated for
7261 leaf functions. The default is @option{-mno-apcs-frame}.
7265 This is a synonym for @option{-mapcs-frame}.
7268 @c not currently implemented
7269 @item -mapcs-stack-check
7270 @opindex mapcs-stack-check
7271 Generate code to check the amount of stack space available upon entry to
7272 every function (that actually uses some stack space). If there is
7273 insufficient space available then either the function
7274 @samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
7275 called, depending upon the amount of stack space required. The run time
7276 system is required to provide these functions. The default is
7277 @option{-mno-apcs-stack-check}, since this produces smaller code.
7279 @c not currently implemented
7281 @opindex mapcs-float
7282 Pass floating point arguments using the float point registers. This is
7283 one of the variants of the APCS@. This option is recommended if the
7284 target hardware has a floating point unit or if a lot of floating point
7285 arithmetic is going to be performed by the code. The default is
7286 @option{-mno-apcs-float}, since integer only code is slightly increased in
7287 size if @option{-mapcs-float} is used.
7289 @c not currently implemented
7290 @item -mapcs-reentrant
7291 @opindex mapcs-reentrant
7292 Generate reentrant, position independent code. The default is
7293 @option{-mno-apcs-reentrant}.
7296 @item -mthumb-interwork
7297 @opindex mthumb-interwork
7298 Generate code which supports calling between the ARM and Thumb
7299 instruction sets. Without this option the two instruction sets cannot
7300 be reliably used inside one program. The default is
7301 @option{-mno-thumb-interwork}, since slightly larger code is generated
7302 when @option{-mthumb-interwork} is specified.
7304 @item -mno-sched-prolog
7305 @opindex mno-sched-prolog
7306 Prevent the reordering of instructions in the function prolog, or the
7307 merging of those instruction with the instructions in the function's
7308 body. This means that all functions will start with a recognizable set
7309 of instructions (or in fact one of a choice from a small set of
7310 different function prologues), and this information can be used to
7311 locate the start if functions inside an executable piece of code. The
7312 default is @option{-msched-prolog}.
7315 @opindex mhard-float
7316 Generate output containing floating point instructions. This is the
7320 @opindex msoft-float
7321 Generate output containing library calls for floating point.
7322 @strong{Warning:} the requisite libraries are not available for all ARM
7323 targets. Normally the facilities of the machine's usual C compiler are
7324 used, but this cannot be done directly in cross-compilation. You must make
7325 your own arrangements to provide suitable library functions for
7328 @option{-msoft-float} changes the calling convention in the output file;
7329 therefore, it is only useful if you compile @emph{all} of a program with
7330 this option. In particular, you need to compile @file{libgcc.a}, the
7331 library that comes with GCC, with @option{-msoft-float} in order for
7334 @item -mfloat-abi=@var{name}
7336 Specifies which ABI to use for floating point values. Permissible values
7337 are: @samp{soft}, @samp{softfp} and @samp{hard}.
7339 @samp{soft} and @samp{hard} are equivalent to @option{-msoft-float}
7340 and @option{-mhard-float} respectively. @samp{softfp} allows the generation
7341 of floating point instructions, but still uses the soft-float calling
7344 @item -mlittle-endian
7345 @opindex mlittle-endian
7346 Generate code for a processor running in little-endian mode. This is
7347 the default for all standard configurations.
7350 @opindex mbig-endian
7351 Generate code for a processor running in big-endian mode; the default is
7352 to compile code for a little-endian processor.
7354 @item -mwords-little-endian
7355 @opindex mwords-little-endian
7356 This option only applies when generating code for big-endian processors.
7357 Generate code for a little-endian word order but a big-endian byte
7358 order. That is, a byte order of the form @samp{32107654}. Note: this
7359 option should only be used if you require compatibility with code for
7360 big-endian ARM processors generated by versions of the compiler prior to
7363 @item -mcpu=@var{name}
7365 This specifies the name of the target ARM processor. GCC uses this name
7366 to determine what kind of instructions it can emit when generating
7367 assembly code. Permissible names are: @samp{arm2}, @samp{arm250},
7368 @samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
7369 @samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
7370 @samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
7371 @samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
7372 @samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},
7373 @samp{arm8}, @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
7374 @samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
7375 @samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},
7376 @samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},
7377 @samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},
7378 @samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
7379 @samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
7380 @samp{arm1176jz-s}, @samp{arm1176jzf-s}, @samp{xscale}, @samp{iwmmxt},
7383 @itemx -mtune=@var{name}
7385 This option is very similar to the @option{-mcpu=} option, except that
7386 instead of specifying the actual target processor type, and hence
7387 restricting which instructions can be used, it specifies that GCC should
7388 tune the performance of the code as if the target were of the type
7389 specified in this option, but still choosing the instructions that it
7390 will generate based on the cpu specified by a @option{-mcpu=} option.
7391 For some ARM implementations better performance can be obtained by using
7394 @item -march=@var{name}
7396 This specifies the name of the target ARM architecture. GCC uses this
7397 name to determine what kind of instructions it can emit when generating
7398 assembly code. This option can be used in conjunction with or instead
7399 of the @option{-mcpu=} option. Permissible names are: @samp{armv2},
7400 @samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
7401 @samp{armv5}, @samp{armv5t}, @samp{armv5te}, @samp{armv6}, @samp{armv6j},
7402 @samp{iwmmxt}, @samp{ep9312}.
7404 @item -mfpu=@var{name}
7405 @itemx -mfpe=@var{number}
7406 @itemx -mfp=@var{number}
7410 This specifies what floating point hardware (or hardware emulation) is
7411 available on the target. Permissible names are: @samp{fpa}, @samp{fpe2},
7412 @samp{fpe3}, @samp{maverick}, @samp{vfp}. @option{-mfp} and @option{-mfpe}
7413 are synonyms for @option{-mfpu}=@samp{fpe}@var{number}, for compatibility
7414 with older versions of GCC@.
7416 If @option{-msoft-float} is specified this specifies the format of
7417 floating point values.
7419 @item -mstructure-size-boundary=@var{n}
7420 @opindex mstructure-size-boundary
7421 The size of all structures and unions will be rounded up to a multiple
7422 of the number of bits set by this option. Permissible values are 8, 32
7423 and 64. The default value varies for different toolchains. For the COFF
7424 targeted toolchain the default value is 8. A value of 64 is only allowed
7425 if the underlying ABI supports it.
7427 Specifying the larger number can produce faster, more efficient code, but
7428 can also increase the size of the program. Different values are potentially
7429 incompatible. Code compiled with one value cannot necessarily expect to
7430 work with code or libraries compiled with another value, if they exchange
7431 information using structures or unions.
7433 @item -mabort-on-noreturn
7434 @opindex mabort-on-noreturn
7435 Generate a call to the function @code{abort} at the end of a
7436 @code{noreturn} function. It will be executed if the function tries to
7440 @itemx -mno-long-calls
7441 @opindex mlong-calls
7442 @opindex mno-long-calls
7443 Tells the compiler to perform function calls by first loading the
7444 address of the function into a register and then performing a subroutine
7445 call on this register. This switch is needed if the target function
7446 will lie outside of the 64 megabyte addressing range of the offset based
7447 version of subroutine call instruction.
7449 Even if this switch is enabled, not all function calls will be turned
7450 into long calls. The heuristic is that static functions, functions
7451 which have the @samp{short-call} attribute, functions that are inside
7452 the scope of a @samp{#pragma no_long_calls} directive and functions whose
7453 definitions have already been compiled within the current compilation
7454 unit, will not be turned into long calls. The exception to this rule is
7455 that weak function definitions, functions with the @samp{long-call}
7456 attribute or the @samp{section} attribute, and functions that are within
7457 the scope of a @samp{#pragma long_calls} directive, will always be
7458 turned into long calls.
7460 This feature is not enabled by default. Specifying
7461 @option{-mno-long-calls} will restore the default behavior, as will
7462 placing the function calls within the scope of a @samp{#pragma
7463 long_calls_off} directive. Note these switches have no effect on how
7464 the compiler generates code to handle function calls via function
7467 @item -mnop-fun-dllimport
7468 @opindex mnop-fun-dllimport
7469 Disable support for the @code{dllimport} attribute.
7471 @item -msingle-pic-base
7472 @opindex msingle-pic-base
7473 Treat the register used for PIC addressing as read-only, rather than
7474 loading it in the prologue for each function. The run-time system is
7475 responsible for initializing this register with an appropriate value
7476 before execution begins.
7478 @item -mpic-register=@var{reg}
7479 @opindex mpic-register
7480 Specify the register to be used for PIC addressing. The default is R10
7481 unless stack-checking is enabled, when R9 is used.
7483 @item -mcirrus-fix-invalid-insns
7484 @opindex mcirrus-fix-invalid-insns
7485 @opindex mno-cirrus-fix-invalid-insns
7486 Insert NOPs into the instruction stream to in order to work around
7487 problems with invalid Maverick instruction combinations. This option
7488 is only valid if the @option{-mcpu=ep9312} option has been used to
7489 enable generation of instructions for the Cirrus Maverick floating
7490 point co-processor. This option is not enabled by default, since the
7491 problem is only present in older Maverick implementations. The default
7492 can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns}
7495 @item -mpoke-function-name
7496 @opindex mpoke-function-name
7497 Write the name of each function into the text section, directly
7498 preceding the function prologue. The generated code is similar to this:
7502 .ascii "arm_poke_function_name", 0
7505 .word 0xff000000 + (t1 - t0)
7506 arm_poke_function_name
7508 stmfd sp!, @{fp, ip, lr, pc@}
7512 When performing a stack backtrace, code can inspect the value of
7513 @code{pc} stored at @code{fp + 0}. If the trace function then looks at
7514 location @code{pc - 12} and the top 8 bits are set, then we know that
7515 there is a function name embedded immediately preceding this location
7516 and has length @code{((pc[-3]) & 0xff000000)}.
7520 Generate code for the 16-bit Thumb instruction set. The default is to
7521 use the 32-bit ARM instruction set.
7524 @opindex mtpcs-frame
7525 Generate a stack frame that is compliant with the Thumb Procedure Call
7526 Standard for all non-leaf functions. (A leaf function is one that does
7527 not call any other functions.) The default is @option{-mno-tpcs-frame}.
7529 @item -mtpcs-leaf-frame
7530 @opindex mtpcs-leaf-frame
7531 Generate a stack frame that is compliant with the Thumb Procedure Call
7532 Standard for all leaf functions. (A leaf function is one that does
7533 not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
7535 @item -mcallee-super-interworking
7536 @opindex mcallee-super-interworking
7537 Gives all externally visible functions in the file being compiled an ARM
7538 instruction set header which switches to Thumb mode before executing the
7539 rest of the function. This allows these functions to be called from
7540 non-interworking code.
7542 @item -mcaller-super-interworking
7543 @opindex mcaller-super-interworking
7544 Allows calls via function pointers (including virtual functions) to
7545 execute correctly regardless of whether the target code has been
7546 compiled for interworking or not. There is a small overhead in the cost
7547 of executing a function pointer if this option is enabled.
7549 @item -mtp=@var{name}
7551 Specify the access model for the thread local storage pointer. The valid
7552 models are @option{soft}, which generates calls to @code{__aeabi_read_tp},
7553 @option{cp15}, which fetches the thread pointer from @code{cp15} directly
7554 (supported in the arm6k architecture), and @option{auto}, which uses the
7555 best available method for the selected processor. The default setting is
7561 @subsection AVR Options
7564 These options are defined for AVR implementations:
7567 @item -mmcu=@var{mcu}
7569 Specify ATMEL AVR instruction set or MCU type.
7571 Instruction set avr1 is for the minimal AVR core, not supported by the C
7572 compiler, only for assembler programs (MCU types: at90s1200, attiny10,
7573 attiny11, attiny12, attiny15, attiny28).
7575 Instruction set avr2 (default) is for the classic AVR core with up to
7576 8K program memory space (MCU types: at90s2313, at90s2323, attiny22,
7577 at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
7578 at90c8534, at90s8535).
7580 Instruction set avr3 is for the classic AVR core with up to 128K program
7581 memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
7583 Instruction set avr4 is for the enhanced AVR core with up to 8K program
7584 memory space (MCU types: atmega8, atmega83, atmega85).
7586 Instruction set avr5 is for the enhanced AVR core with up to 128K program
7587 memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
7588 atmega64, atmega128, at43usb355, at94k).
7592 Output instruction sizes to the asm file.
7594 @item -minit-stack=@var{N}
7595 @opindex minit-stack
7596 Specify the initial stack address, which may be a symbol or numeric value,
7597 @samp{__stack} is the default.
7599 @item -mno-interrupts
7600 @opindex mno-interrupts
7601 Generated code is not compatible with hardware interrupts.
7602 Code size will be smaller.
7604 @item -mcall-prologues
7605 @opindex mcall-prologues
7606 Functions prologues/epilogues expanded as call to appropriate
7607 subroutines. Code size will be smaller.
7609 @item -mno-tablejump
7610 @opindex mno-tablejump
7611 Do not generate tablejump insns which sometimes increase code size.
7614 @opindex mtiny-stack
7615 Change only the low 8 bits of the stack pointer.
7619 Assume int to be 8 bit integer. This affects the sizes of all types: A
7620 char will be 1 byte, an int will be 1 byte, an long will be 2 bytes
7621 and long long will be 4 bytes. Please note that this option does not
7622 comply to the C standards, but it will provide you with smaller code
7626 @node Blackfin Options
7627 @subsection Blackfin Options
7628 @cindex Blackfin Options
7631 @item -momit-leaf-frame-pointer
7632 @opindex momit-leaf-frame-pointer
7633 Don't keep the frame pointer in a register for leaf functions. This
7634 avoids the instructions to save, set up and restore frame pointers and
7635 makes an extra register available in leaf functions. The option
7636 @option{-fomit-frame-pointer} removes the frame pointer for all functions
7637 which might make debugging harder.
7639 @item -mspecld-anomaly
7640 @opindex mspecld-anomaly
7641 When enabled, the compiler will ensure that the generated code does not
7642 contain speculative loads after jump instructions. This option is enabled
7645 @item -mno-specld-anomaly
7646 @opindex mno-specld-anomaly
7647 Don't generate extra code to prevent speculative loads from occurring.
7649 @item -mcsync-anomaly
7650 @opindex mcsync-anomaly
7651 When enabled, the compiler will ensure that the generated code does not
7652 contain CSYNC or SSYNC instructions too soon after conditional branches.
7653 This option is enabled by default.
7655 @item -mno-csync-anomaly
7656 @opindex mno-csync-anomaly
7657 Don't generate extra code to prevent CSYNC or SSYNC instructions from
7658 occurring too soon after a conditional branch.
7662 When enabled, the compiler is free to take advantage of the knowledge that
7663 the entire program fits into the low 64k of memory.
7666 @opindex mno-low-64k
7667 Assume that the program is arbitrarily large. This is the default.
7669 @item -mid-shared-library
7670 @opindex mid-shared-library
7671 Generate code that supports shared libraries via the library ID method.
7672 This allows for execute in place and shared libraries in an environment
7673 without virtual memory management. This option implies @option{-fPIC}.
7675 @item -mno-id-shared-library
7676 @opindex mno-id-shared-library
7677 Generate code that doesn't assume ID based shared libraries are being used.
7678 This is the default.
7680 @item -mshared-library-id=n
7681 @opindex mshared-library-id
7682 Specified the identification number of the ID based shared library being
7683 compiled. Specifying a value of 0 will generate more compact code, specifying
7684 other values will force the allocation of that number to the current
7685 library but is no more space or time efficient than omitting this option.
7688 @itemx -mno-long-calls
7689 @opindex mlong-calls
7690 @opindex mno-long-calls
7691 Tells the compiler to perform function calls by first loading the
7692 address of the function into a register and then performing a subroutine
7693 call on this register. This switch is needed if the target function
7694 will lie outside of the 24 bit addressing range of the offset based
7695 version of subroutine call instruction.
7697 This feature is not enabled by default. Specifying
7698 @option{-mno-long-calls} will restore the default behavior. Note these
7699 switches have no effect on how the compiler generates code to handle
7700 function calls via function pointers.
7704 @subsection CRIS Options
7705 @cindex CRIS Options
7707 These options are defined specifically for the CRIS ports.
7710 @item -march=@var{architecture-type}
7711 @itemx -mcpu=@var{architecture-type}
7714 Generate code for the specified architecture. The choices for
7715 @var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
7716 respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
7717 Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
7720 @item -mtune=@var{architecture-type}
7722 Tune to @var{architecture-type} everything applicable about the generated
7723 code, except for the ABI and the set of available instructions. The
7724 choices for @var{architecture-type} are the same as for
7725 @option{-march=@var{architecture-type}}.
7727 @item -mmax-stack-frame=@var{n}
7728 @opindex mmax-stack-frame
7729 Warn when the stack frame of a function exceeds @var{n} bytes.
7731 @item -melinux-stacksize=@var{n}
7732 @opindex melinux-stacksize
7733 Only available with the @samp{cris-axis-aout} target. Arranges for
7734 indications in the program to the kernel loader that the stack of the
7735 program should be set to @var{n} bytes.
7741 The options @option{-metrax4} and @option{-metrax100} are synonyms for
7742 @option{-march=v3} and @option{-march=v8} respectively.
7744 @item -mmul-bug-workaround
7745 @itemx -mno-mul-bug-workaround
7746 @opindex mmul-bug-workaround
7747 @opindex mno-mul-bug-workaround
7748 Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
7749 models where it applies. This option is active by default.
7753 Enable CRIS-specific verbose debug-related information in the assembly
7754 code. This option also has the effect to turn off the @samp{#NO_APP}
7755 formatted-code indicator to the assembler at the beginning of the
7760 Do not use condition-code results from previous instruction; always emit
7761 compare and test instructions before use of condition codes.
7763 @item -mno-side-effects
7764 @opindex mno-side-effects
7765 Do not emit instructions with side-effects in addressing modes other than
7769 @itemx -mno-stack-align
7771 @itemx -mno-data-align
7772 @itemx -mconst-align
7773 @itemx -mno-const-align
7774 @opindex mstack-align
7775 @opindex mno-stack-align
7776 @opindex mdata-align
7777 @opindex mno-data-align
7778 @opindex mconst-align
7779 @opindex mno-const-align
7780 These options (no-options) arranges (eliminate arrangements) for the
7781 stack-frame, individual data and constants to be aligned for the maximum
7782 single data access size for the chosen CPU model. The default is to
7783 arrange for 32-bit alignment. ABI details such as structure layout are
7784 not affected by these options.
7792 Similar to the stack- data- and const-align options above, these options
7793 arrange for stack-frame, writable data and constants to all be 32-bit,
7794 16-bit or 8-bit aligned. The default is 32-bit alignment.
7796 @item -mno-prologue-epilogue
7797 @itemx -mprologue-epilogue
7798 @opindex mno-prologue-epilogue
7799 @opindex mprologue-epilogue
7800 With @option{-mno-prologue-epilogue}, the normal function prologue and
7801 epilogue that sets up the stack-frame are omitted and no return
7802 instructions or return sequences are generated in the code. Use this
7803 option only together with visual inspection of the compiled code: no
7804 warnings or errors are generated when call-saved registers must be saved,
7805 or storage for local variable needs to be allocated.
7811 With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
7812 instruction sequences that load addresses for functions from the PLT part
7813 of the GOT rather than (traditional on other architectures) calls to the
7814 PLT@. The default is @option{-mgotplt}.
7818 Legacy no-op option only recognized with the cris-axis-aout target.
7822 Legacy no-op option only recognized with the cris-axis-elf and
7823 cris-axis-linux-gnu targets.
7827 Only recognized with the cris-axis-aout target, where it selects a
7828 GNU/linux-like multilib, include files and instruction set for
7833 Legacy no-op option only recognized with the cris-axis-linux-gnu target.
7837 This option, recognized for the cris-axis-aout and cris-axis-elf arranges
7838 to link with input-output functions from a simulator library. Code,
7839 initialized data and zero-initialized data are allocated consecutively.
7843 Like @option{-sim}, but pass linker options to locate initialized data at
7844 0x40000000 and zero-initialized data at 0x80000000.
7848 @subsection CRX Options
7851 These options are defined specifically for the CRX ports.
7857 Enable the use of multiply-accumulate instructions. Disabled by default.
7861 Push instructions will be used to pass outgoing arguments when functions
7862 are called. Enabled by default.
7865 @node Darwin Options
7866 @subsection Darwin Options
7867 @cindex Darwin options
7869 These options are defined for all architectures running the Darwin operating
7872 FSF GCC on Darwin does not create ``fat'' object files; it will create
7873 an object file for the single architecture that it was built to
7874 target. Apple's GCC on Darwin does create ``fat'' files if multiple
7875 @option{-arch} options are used; it does so by running the compiler or
7876 linker multiple times and joining the results together with
7879 The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
7880 @samp{i686}) is determined by the flags that specify the ISA
7881 that GCC is targetting, like @option{-mcpu} or @option{-march}. The
7882 @option{-force_cpusubtype_ALL} option can be used to override this.
7884 The Darwin tools vary in their behavior when presented with an ISA
7885 mismatch. The assembler, @file{as}, will only permit instructions to
7886 be used that are valid for the subtype of the file it is generating,
7887 so you cannot put 64-bit instructions in an @samp{ppc750} object file.
7888 The linker for shared libraries, @file{/usr/bin/libtool}, will fail
7889 and print an error if asked to create a shared library with a less
7890 restrictive subtype than its input files (for instance, trying to put
7891 a @samp{ppc970} object file in a @samp{ppc7400} library). The linker
7892 for executables, @file{ld}, will quietly give the executable the most
7893 restrictive subtype of any of its input files.
7898 Add the framework directory @var{dir} to the head of the list of
7899 directories to be searched for header files. These directories are
7900 interleaved with those specified by @option{-I} options and are
7901 scanned in a left-to-right order.
7903 A framework directory is a directory with frameworks in it. A
7904 framework is a directory with a @samp{"Headers"} and/or
7905 @samp{"PrivateHeaders"} directory contained directly in it that ends
7906 in @samp{".framework"}. The name of a framework is the name of this
7907 directory excluding the @samp{".framework"}. Headers associated with
7908 the framework are found in one of those two directories, with
7909 @samp{"Headers"} being searched first. A subframework is a framework
7910 directory that is in a framework's @samp{"Frameworks"} directory.
7911 Includes of subframework headers can only appear in a header of a
7912 framework that contains the subframework, or in a sibling subframework
7913 header. Two subframeworks are siblings if they occur in the same
7914 framework. A subframework should not have the same name as a
7915 framework, a warning will be issued if this is violated. Currently a
7916 subframework cannot have subframeworks, in the future, the mechanism
7917 may be extended to support this. The standard frameworks can be found
7918 in @samp{"/System/Library/Frameworks"} and
7919 @samp{"/Library/Frameworks"}. An example include looks like
7920 @code{#include <Framework/header.h>}, where @samp{Framework} denotes
7921 the name of the framework and header.h is found in the
7922 @samp{"PrivateHeaders"} or @samp{"Headers"} directory.
7926 Emit debugging information for symbols that are used. For STABS
7927 debugging format, this enables @option{-feliminate-unused-debug-symbols}.
7928 This is by default ON@.
7932 Emit debugging information for all symbols and types.
7934 @item -mmacosx-version-min=@var{version}
7935 The earliest version of MacOS X that this executable will run on
7936 is @var{version}. Typical values of @var{version} include @code{10.1},
7937 @code{10.2}, and @code{10.3.9}.
7939 The default for this option is to make choices that seem to be most
7944 Enable kernel development mode. The @option{-mkernel} option sets
7945 @option{-static}, @option{-fno-common}, @option{-fno-cxa-atexit},
7946 @option{-fno-exceptions}, @option{-fno-non-call-exceptions},
7947 @option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where
7948 applicable. This mode also sets @option{-mno-altivec},
7949 @option{-msoft-float}, @option{-fno-builtin} and
7950 @option{-mlong-branch} for PowerPC targets.
7952 @item -mone-byte-bool
7953 @opindex mone-byte-bool
7954 Override the defaults for @samp{bool} so that @samp{sizeof(bool)==1}.
7955 By default @samp{sizeof(bool)} is @samp{4} when compiling for
7956 Darwin/PowerPC and @samp{1} when compiling for Darwin/x86, so this
7957 option has no effect on x86.
7959 @strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
7960 to generate code that is not binary compatible with code generated
7961 without that switch. Using this switch may require recompiling all
7962 other modules in a program, including system libraries. Use this
7963 switch to conform to a non-default data model.
7965 @item -mfix-and-continue
7966 @itemx -ffix-and-continue
7967 @itemx -findirect-data
7968 @opindex mfix-and-continue
7969 @opindex ffix-and-continue
7970 @opindex findirect-data
7971 Generate code suitable for fast turn around development. Needed to
7972 enable gdb to dynamically load @code{.o} files into already running
7973 programs. @option{-findirect-data} and @option{-ffix-and-continue}
7974 are provided for backwards compatibility.
7978 Loads all members of static archive libraries.
7979 See man ld(1) for more information.
7981 @item -arch_errors_fatal
7982 @opindex arch_errors_fatal
7983 Cause the errors having to do with files that have the wrong architecture
7987 @opindex bind_at_load
7988 Causes the output file to be marked such that the dynamic linker will
7989 bind all undefined references when the file is loaded or launched.
7993 Produce a Mach-o bundle format file.
7994 See man ld(1) for more information.
7996 @item -bundle_loader @var{executable}
7997 @opindex bundle_loader
7998 This option specifies the @var{executable} that will be loading the build
7999 output file being linked. See man ld(1) for more information.
8003 When passed this option, GCC will produce a dynamic library instead of
8004 an executable when linking, using the Darwin @file{libtool} command.
8006 @item -force_cpusubtype_ALL
8007 @opindex force_cpusubtype_ALL
8008 This causes GCC's output file to have the @var{ALL} subtype, instead of
8009 one controlled by the @option{-mcpu} or @option{-march} option.
8011 @item -allowable_client @var{client_name}
8013 @itemx -compatibility_version
8014 @itemx -current_version
8016 @itemx -dependency-file
8018 @itemx -dylinker_install_name
8020 @itemx -exported_symbols_list
8022 @itemx -flat_namespace
8023 @itemx -force_flat_namespace
8024 @itemx -headerpad_max_install_names
8027 @itemx -install_name
8028 @itemx -keep_private_externs
8029 @itemx -multi_module
8030 @itemx -multiply_defined
8031 @itemx -multiply_defined_unused
8033 @itemx -no_dead_strip_inits_and_terms
8034 @itemx -nofixprebinding
8037 @itemx -noseglinkedit
8038 @itemx -pagezero_size
8040 @itemx -prebind_all_twolevel_modules
8041 @itemx -private_bundle
8042 @itemx -read_only_relocs
8044 @itemx -sectobjectsymbols
8048 @itemx -sectobjectsymbols
8051 @itemx -segs_read_only_addr
8052 @itemx -segs_read_write_addr
8053 @itemx -seg_addr_table
8054 @itemx -seg_addr_table_filename
8057 @itemx -segs_read_only_addr
8058 @itemx -segs_read_write_addr
8059 @itemx -single_module
8062 @itemx -sub_umbrella
8063 @itemx -twolevel_namespace
8066 @itemx -unexported_symbols_list
8067 @itemx -weak_reference_mismatches
8070 @opindex allowable_client
8071 @opindex client_name
8072 @opindex compatibility_version
8073 @opindex current_version
8075 @opindex dependency-file
8077 @opindex dylinker_install_name
8079 @opindex exported_symbols_list
8081 @opindex flat_namespace
8082 @opindex force_flat_namespace
8083 @opindex headerpad_max_install_names
8086 @opindex install_name
8087 @opindex keep_private_externs
8088 @opindex multi_module
8089 @opindex multiply_defined
8090 @opindex multiply_defined_unused
8092 @opindex no_dead_strip_inits_and_terms
8093 @opindex nofixprebinding
8094 @opindex nomultidefs
8096 @opindex noseglinkedit
8097 @opindex pagezero_size
8099 @opindex prebind_all_twolevel_modules
8100 @opindex private_bundle
8101 @opindex read_only_relocs
8103 @opindex sectobjectsymbols
8107 @opindex sectobjectsymbols
8110 @opindex segs_read_only_addr
8111 @opindex segs_read_write_addr
8112 @opindex seg_addr_table
8113 @opindex seg_addr_table_filename
8114 @opindex seglinkedit
8116 @opindex segs_read_only_addr
8117 @opindex segs_read_write_addr
8118 @opindex single_module
8120 @opindex sub_library
8121 @opindex sub_umbrella
8122 @opindex twolevel_namespace
8125 @opindex unexported_symbols_list
8126 @opindex weak_reference_mismatches
8127 @opindex whatsloaded
8129 These options are passed to the Darwin linker. The Darwin linker man page
8130 describes them in detail.
8133 @node DEC Alpha Options
8134 @subsection DEC Alpha Options
8136 These @samp{-m} options are defined for the DEC Alpha implementations:
8139 @item -mno-soft-float
8141 @opindex mno-soft-float
8142 @opindex msoft-float
8143 Use (do not use) the hardware floating-point instructions for
8144 floating-point operations. When @option{-msoft-float} is specified,
8145 functions in @file{libgcc.a} will be used to perform floating-point
8146 operations. Unless they are replaced by routines that emulate the
8147 floating-point operations, or compiled in such a way as to call such
8148 emulations routines, these routines will issue floating-point
8149 operations. If you are compiling for an Alpha without floating-point
8150 operations, you must ensure that the library is built so as not to call
8153 Note that Alpha implementations without floating-point operations are
8154 required to have floating-point registers.
8159 @opindex mno-fp-regs
8160 Generate code that uses (does not use) the floating-point register set.
8161 @option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
8162 register set is not used, floating point operands are passed in integer
8163 registers as if they were integers and floating-point results are passed
8164 in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
8165 so any function with a floating-point argument or return value called by code
8166 compiled with @option{-mno-fp-regs} must also be compiled with that
8169 A typical use of this option is building a kernel that does not use,
8170 and hence need not save and restore, any floating-point registers.
8174 The Alpha architecture implements floating-point hardware optimized for
8175 maximum performance. It is mostly compliant with the IEEE floating
8176 point standard. However, for full compliance, software assistance is
8177 required. This option generates code fully IEEE compliant code
8178 @emph{except} that the @var{inexact-flag} is not maintained (see below).
8179 If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
8180 defined during compilation. The resulting code is less efficient but is
8181 able to correctly support denormalized numbers and exceptional IEEE
8182 values such as not-a-number and plus/minus infinity. Other Alpha
8183 compilers call this option @option{-ieee_with_no_inexact}.
8185 @item -mieee-with-inexact
8186 @opindex mieee-with-inexact
8187 This is like @option{-mieee} except the generated code also maintains
8188 the IEEE @var{inexact-flag}. Turning on this option causes the
8189 generated code to implement fully-compliant IEEE math. In addition to
8190 @code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
8191 macro. On some Alpha implementations the resulting code may execute
8192 significantly slower than the code generated by default. Since there is
8193 very little code that depends on the @var{inexact-flag}, you should
8194 normally not specify this option. Other Alpha compilers call this
8195 option @option{-ieee_with_inexact}.
8197 @item -mfp-trap-mode=@var{trap-mode}
8198 @opindex mfp-trap-mode
8199 This option controls what floating-point related traps are enabled.
8200 Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
8201 The trap mode can be set to one of four values:
8205 This is the default (normal) setting. The only traps that are enabled
8206 are the ones that cannot be disabled in software (e.g., division by zero
8210 In addition to the traps enabled by @samp{n}, underflow traps are enabled
8214 Like @samp{u}, but the instructions are marked to be safe for software
8215 completion (see Alpha architecture manual for details).
8218 Like @samp{su}, but inexact traps are enabled as well.
8221 @item -mfp-rounding-mode=@var{rounding-mode}
8222 @opindex mfp-rounding-mode
8223 Selects the IEEE rounding mode. Other Alpha compilers call this option
8224 @option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
8229 Normal IEEE rounding mode. Floating point numbers are rounded towards
8230 the nearest machine number or towards the even machine number in case
8234 Round towards minus infinity.
8237 Chopped rounding mode. Floating point numbers are rounded towards zero.
8240 Dynamic rounding mode. A field in the floating point control register
8241 (@var{fpcr}, see Alpha architecture reference manual) controls the
8242 rounding mode in effect. The C library initializes this register for
8243 rounding towards plus infinity. Thus, unless your program modifies the
8244 @var{fpcr}, @samp{d} corresponds to round towards plus infinity.
8247 @item -mtrap-precision=@var{trap-precision}
8248 @opindex mtrap-precision
8249 In the Alpha architecture, floating point traps are imprecise. This
8250 means without software assistance it is impossible to recover from a
8251 floating trap and program execution normally needs to be terminated.
8252 GCC can generate code that can assist operating system trap handlers
8253 in determining the exact location that caused a floating point trap.
8254 Depending on the requirements of an application, different levels of
8255 precisions can be selected:
8259 Program precision. This option is the default and means a trap handler
8260 can only identify which program caused a floating point exception.
8263 Function precision. The trap handler can determine the function that
8264 caused a floating point exception.
8267 Instruction precision. The trap handler can determine the exact
8268 instruction that caused a floating point exception.
8271 Other Alpha compilers provide the equivalent options called
8272 @option{-scope_safe} and @option{-resumption_safe}.
8274 @item -mieee-conformant
8275 @opindex mieee-conformant
8276 This option marks the generated code as IEEE conformant. You must not
8277 use this option unless you also specify @option{-mtrap-precision=i} and either
8278 @option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
8279 is to emit the line @samp{.eflag 48} in the function prologue of the
8280 generated assembly file. Under DEC Unix, this has the effect that
8281 IEEE-conformant math library routines will be linked in.
8283 @item -mbuild-constants
8284 @opindex mbuild-constants
8285 Normally GCC examines a 32- or 64-bit integer constant to
8286 see if it can construct it from smaller constants in two or three
8287 instructions. If it cannot, it will output the constant as a literal and
8288 generate code to load it from the data segment at runtime.
8290 Use this option to require GCC to construct @emph{all} integer constants
8291 using code, even if it takes more instructions (the maximum is six).
8293 You would typically use this option to build a shared library dynamic
8294 loader. Itself a shared library, it must relocate itself in memory
8295 before it can find the variables and constants in its own data segment.
8301 Select whether to generate code to be assembled by the vendor-supplied
8302 assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
8320 Indicate whether GCC should generate code to use the optional BWX,
8321 CIX, FIX and MAX instruction sets. The default is to use the instruction
8322 sets supported by the CPU type specified via @option{-mcpu=} option or that
8323 of the CPU on which GCC was built if none was specified.
8328 @opindex mfloat-ieee
8329 Generate code that uses (does not use) VAX F and G floating point
8330 arithmetic instead of IEEE single and double precision.
8332 @item -mexplicit-relocs
8333 @itemx -mno-explicit-relocs
8334 @opindex mexplicit-relocs
8335 @opindex mno-explicit-relocs
8336 Older Alpha assemblers provided no way to generate symbol relocations
8337 except via assembler macros. Use of these macros does not allow
8338 optimal instruction scheduling. GNU binutils as of version 2.12
8339 supports a new syntax that allows the compiler to explicitly mark
8340 which relocations should apply to which instructions. This option
8341 is mostly useful for debugging, as GCC detects the capabilities of
8342 the assembler when it is built and sets the default accordingly.
8346 @opindex msmall-data
8347 @opindex mlarge-data
8348 When @option{-mexplicit-relocs} is in effect, static data is
8349 accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
8350 is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
8351 (the @code{.sdata} and @code{.sbss} sections) and are accessed via
8352 16-bit relocations off of the @code{$gp} register. This limits the
8353 size of the small data area to 64KB, but allows the variables to be
8354 directly accessed via a single instruction.
8356 The default is @option{-mlarge-data}. With this option the data area
8357 is limited to just below 2GB@. Programs that require more than 2GB of
8358 data must use @code{malloc} or @code{mmap} to allocate the data in the
8359 heap instead of in the program's data segment.
8361 When generating code for shared libraries, @option{-fpic} implies
8362 @option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
8366 @opindex msmall-text
8367 @opindex mlarge-text
8368 When @option{-msmall-text} is used, the compiler assumes that the
8369 code of the entire program (or shared library) fits in 4MB, and is
8370 thus reachable with a branch instruction. When @option{-msmall-data}
8371 is used, the compiler can assume that all local symbols share the
8372 same @code{$gp} value, and thus reduce the number of instructions
8373 required for a function call from 4 to 1.
8375 The default is @option{-mlarge-text}.
8377 @item -mcpu=@var{cpu_type}
8379 Set the instruction set and instruction scheduling parameters for
8380 machine type @var{cpu_type}. You can specify either the @samp{EV}
8381 style name or the corresponding chip number. GCC supports scheduling
8382 parameters for the EV4, EV5 and EV6 family of processors and will
8383 choose the default values for the instruction set from the processor
8384 you specify. If you do not specify a processor type, GCC will default
8385 to the processor on which the compiler was built.
8387 Supported values for @var{cpu_type} are
8393 Schedules as an EV4 and has no instruction set extensions.
8397 Schedules as an EV5 and has no instruction set extensions.
8401 Schedules as an EV5 and supports the BWX extension.
8406 Schedules as an EV5 and supports the BWX and MAX extensions.
8410 Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
8414 Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
8417 @item -mtune=@var{cpu_type}
8419 Set only the instruction scheduling parameters for machine type
8420 @var{cpu_type}. The instruction set is not changed.
8422 @item -mmemory-latency=@var{time}
8423 @opindex mmemory-latency
8424 Sets the latency the scheduler should assume for typical memory
8425 references as seen by the application. This number is highly
8426 dependent on the memory access patterns used by the application
8427 and the size of the external cache on the machine.
8429 Valid options for @var{time} are
8433 A decimal number representing clock cycles.
8439 The compiler contains estimates of the number of clock cycles for
8440 ``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
8441 (also called Dcache, Scache, and Bcache), as well as to main memory.
8442 Note that L3 is only valid for EV5.
8447 @node DEC Alpha/VMS Options
8448 @subsection DEC Alpha/VMS Options
8450 These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
8453 @item -mvms-return-codes
8454 @opindex mvms-return-codes
8455 Return VMS condition codes from main. The default is to return POSIX
8456 style condition (e.g.@ error) codes.
8460 @subsection FRV Options
8467 Only use the first 32 general purpose registers.
8472 Use all 64 general purpose registers.
8477 Use only the first 32 floating point registers.
8482 Use all 64 floating point registers
8485 @opindex mhard-float
8487 Use hardware instructions for floating point operations.
8490 @opindex msoft-float
8492 Use library routines for floating point operations.
8497 Dynamically allocate condition code registers.
8502 Do not try to dynamically allocate condition code registers, only
8503 use @code{icc0} and @code{fcc0}.
8508 Change ABI to use double word insns.
8513 Do not use double word instructions.
8518 Use floating point double instructions.
8523 Do not use floating point double instructions.
8528 Use media instructions.
8533 Do not use media instructions.
8538 Use multiply and add/subtract instructions.
8543 Do not use multiply and add/subtract instructions.
8548 Select the FDPIC ABI, that uses function descriptors to represent
8549 pointers to functions. Without any PIC/PIE-related options, it
8550 implies @option{-fPIE}. With @option{-fpic} or @option{-fpie}, it
8551 assumes GOT entries and small data are within a 12-bit range from the
8552 GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
8553 are computed with 32 bits.
8556 @opindex minline-plt
8558 Enable inlining of PLT entries in function calls to functions that are
8559 not known to bind locally. It has no effect without @option{-mfdpic}.
8560 It's enabled by default if optimizing for speed and compiling for
8561 shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
8562 optimization option such as @option{-O3} or above is present in the
8568 Assume a large TLS segment when generating thread-local code.
8573 Do not assume a large TLS segment when generating thread-local code.
8578 Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
8579 that is known to be in read-only sections. It's enabled by default,
8580 except for @option{-fpic} or @option{-fpie}: even though it may help
8581 make the global offset table smaller, it trades 1 instruction for 4.
8582 With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
8583 one of which may be shared by multiple symbols, and it avoids the need
8584 for a GOT entry for the referenced symbol, so it's more likely to be a
8585 win. If it is not, @option{-mno-gprel-ro} can be used to disable it.
8587 @item -multilib-library-pic
8588 @opindex multilib-library-pic
8590 Link with the (library, not FD) pic libraries. It's implied by
8591 @option{-mlibrary-pic}, as well as by @option{-fPIC} and
8592 @option{-fpic} without @option{-mfdpic}. You should never have to use
8598 Follow the EABI requirement of always creating a frame pointer whenever
8599 a stack frame is allocated. This option is enabled by default and can
8600 be disabled with @option{-mno-linked-fp}.
8603 @opindex mlong-calls
8605 Use indirect addressing to call functions outside the current
8606 compilation unit. This allows the functions to be placed anywhere
8607 within the 32-bit address space.
8609 @item -malign-labels
8610 @opindex malign-labels
8612 Try to align labels to an 8-byte boundary by inserting nops into the
8613 previous packet. This option only has an effect when VLIW packing
8614 is enabled. It doesn't create new packets; it merely adds nops to
8618 @opindex mlibrary-pic
8620 Generate position-independent EABI code.
8625 Use only the first four media accumulator registers.
8630 Use all eight media accumulator registers.
8635 Pack VLIW instructions.
8640 Do not pack VLIW instructions.
8645 Do not mark ABI switches in e_flags.
8650 Enable the use of conditional-move instructions (default).
8652 This switch is mainly for debugging the compiler and will likely be removed
8653 in a future version.
8655 @item -mno-cond-move
8656 @opindex mno-cond-move
8658 Disable the use of conditional-move instructions.
8660 This switch is mainly for debugging the compiler and will likely be removed
8661 in a future version.
8666 Enable the use of conditional set instructions (default).
8668 This switch is mainly for debugging the compiler and will likely be removed
8669 in a future version.
8674 Disable the use of conditional set instructions.
8676 This switch is mainly for debugging the compiler and will likely be removed
8677 in a future version.
8682 Enable the use of conditional execution (default).
8684 This switch is mainly for debugging the compiler and will likely be removed
8685 in a future version.
8687 @item -mno-cond-exec
8688 @opindex mno-cond-exec
8690 Disable the use of conditional execution.
8692 This switch is mainly for debugging the compiler and will likely be removed
8693 in a future version.
8696 @opindex mvliw-branch
8698 Run a pass to pack branches into VLIW instructions (default).
8700 This switch is mainly for debugging the compiler and will likely be removed
8701 in a future version.
8703 @item -mno-vliw-branch
8704 @opindex mno-vliw-branch
8706 Do not run a pass to pack branches into VLIW instructions.
8708 This switch is mainly for debugging the compiler and will likely be removed
8709 in a future version.
8711 @item -mmulti-cond-exec
8712 @opindex mmulti-cond-exec
8714 Enable optimization of @code{&&} and @code{||} in conditional execution
8717 This switch is mainly for debugging the compiler and will likely be removed
8718 in a future version.
8720 @item -mno-multi-cond-exec
8721 @opindex mno-multi-cond-exec
8723 Disable optimization of @code{&&} and @code{||} in conditional execution.
8725 This switch is mainly for debugging the compiler and will likely be removed
8726 in a future version.
8728 @item -mnested-cond-exec
8729 @opindex mnested-cond-exec
8731 Enable nested conditional execution optimizations (default).
8733 This switch is mainly for debugging the compiler and will likely be removed
8734 in a future version.
8736 @item -mno-nested-cond-exec
8737 @opindex mno-nested-cond-exec
8739 Disable nested conditional execution optimizations.
8741 This switch is mainly for debugging the compiler and will likely be removed
8742 in a future version.
8744 @item -moptimize-membar
8745 @opindex moptimize-membar
8747 This switch removes redundant @code{membar} instructions from the
8748 compiler generated code. It is enabled by default.
8750 @item -mno-optimize-membar
8751 @opindex mno-optimize-membar
8753 This switch disables the automatic removal of redundant @code{membar}
8754 instructions from the generated code.
8756 @item -mtomcat-stats
8757 @opindex mtomcat-stats
8759 Cause gas to print out tomcat statistics.
8761 @item -mcpu=@var{cpu}
8764 Select the processor type for which to generate code. Possible values are
8765 @samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
8766 @samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
8770 @node GNU/Linux Options
8771 @subsection GNU/Linux Options
8773 These @samp{-m} options are defined for GNU/Linux targets:
8778 Use the GNU C library instead of uClibc. This is the default except
8779 on @samp{*-*-linux-*uclibc*} targets.
8783 Use uClibc instead of the GNU C library. This is the default on
8784 @samp{*-*-linux-*uclibc*} targets.
8787 @node H8/300 Options
8788 @subsection H8/300 Options
8790 These @samp{-m} options are defined for the H8/300 implementations:
8795 Shorten some address references at link time, when possible; uses the
8796 linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
8797 ld, Using ld}, for a fuller description.
8801 Generate code for the H8/300H@.
8805 Generate code for the H8S@.
8809 Generate code for the H8S and H8/300H in the normal mode. This switch
8810 must be used either with @option{-mh} or @option{-ms}.
8814 Generate code for the H8S/2600. This switch must be used with @option{-ms}.
8818 Make @code{int} data 32 bits by default.
8822 On the H8/300H and H8S, use the same alignment rules as for the H8/300.
8823 The default for the H8/300H and H8S is to align longs and floats on 4
8825 @option{-malign-300} causes them to be aligned on 2 byte boundaries.
8826 This option has no effect on the H8/300.
8830 @subsection HPPA Options
8831 @cindex HPPA Options
8833 These @samp{-m} options are defined for the HPPA family of computers:
8836 @item -march=@var{architecture-type}
8838 Generate code for the specified architecture. The choices for
8839 @var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
8840 1.1, and @samp{2.0} for PA 2.0 processors. Refer to
8841 @file{/usr/lib/sched.models} on an HP-UX system to determine the proper
8842 architecture option for your machine. Code compiled for lower numbered
8843 architectures will run on higher numbered architectures, but not the
8847 @itemx -mpa-risc-1-1
8848 @itemx -mpa-risc-2-0
8849 @opindex mpa-risc-1-0
8850 @opindex mpa-risc-1-1
8851 @opindex mpa-risc-2-0
8852 Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
8855 @opindex mbig-switch
8856 Generate code suitable for big switch tables. Use this option only if
8857 the assembler/linker complain about out of range branches within a switch
8860 @item -mjump-in-delay
8861 @opindex mjump-in-delay
8862 Fill delay slots of function calls with unconditional jump instructions
8863 by modifying the return pointer for the function call to be the target
8864 of the conditional jump.
8866 @item -mdisable-fpregs
8867 @opindex mdisable-fpregs
8868 Prevent floating point registers from being used in any manner. This is
8869 necessary for compiling kernels which perform lazy context switching of
8870 floating point registers. If you use this option and attempt to perform
8871 floating point operations, the compiler will abort.
8873 @item -mdisable-indexing
8874 @opindex mdisable-indexing
8875 Prevent the compiler from using indexing address modes. This avoids some
8876 rather obscure problems when compiling MIG generated code under MACH@.
8878 @item -mno-space-regs
8879 @opindex mno-space-regs
8880 Generate code that assumes the target has no space registers. This allows
8881 GCC to generate faster indirect calls and use unscaled index address modes.
8883 Such code is suitable for level 0 PA systems and kernels.
8885 @item -mfast-indirect-calls
8886 @opindex mfast-indirect-calls
8887 Generate code that assumes calls never cross space boundaries. This
8888 allows GCC to emit code which performs faster indirect calls.
8890 This option will not work in the presence of shared libraries or nested
8893 @item -mfixed-range=@var{register-range}
8894 @opindex mfixed-range
8895 Generate code treating the given register range as fixed registers.
8896 A fixed register is one that the register allocator can not use. This is
8897 useful when compiling kernel code. A register range is specified as
8898 two registers separated by a dash. Multiple register ranges can be
8899 specified separated by a comma.
8901 @item -mlong-load-store
8902 @opindex mlong-load-store
8903 Generate 3-instruction load and store sequences as sometimes required by
8904 the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
8907 @item -mportable-runtime
8908 @opindex mportable-runtime
8909 Use the portable calling conventions proposed by HP for ELF systems.
8913 Enable the use of assembler directives only GAS understands.
8915 @item -mschedule=@var{cpu-type}
8917 Schedule code according to the constraints for the machine type
8918 @var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
8919 @samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer
8920 to @file{/usr/lib/sched.models} on an HP-UX system to determine the
8921 proper scheduling option for your machine. The default scheduling is
8925 @opindex mlinker-opt
8926 Enable the optimization pass in the HP-UX linker. Note this makes symbolic
8927 debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9
8928 linkers in which they give bogus error messages when linking some programs.
8931 @opindex msoft-float
8932 Generate output containing library calls for floating point.
8933 @strong{Warning:} the requisite libraries are not available for all HPPA
8934 targets. Normally the facilities of the machine's usual C compiler are
8935 used, but this cannot be done directly in cross-compilation. You must make
8936 your own arrangements to provide suitable library functions for
8937 cross-compilation. The embedded target @samp{hppa1.1-*-pro}
8938 does provide software floating point support.
8940 @option{-msoft-float} changes the calling convention in the output file;
8941 therefore, it is only useful if you compile @emph{all} of a program with
8942 this option. In particular, you need to compile @file{libgcc.a}, the
8943 library that comes with GCC, with @option{-msoft-float} in order for
8948 Generate the predefine, @code{_SIO}, for server IO@. The default is
8949 @option{-mwsio}. This generates the predefines, @code{__hp9000s700},
8950 @code{__hp9000s700__} and @code{_WSIO}, for workstation IO@. These
8951 options are available under HP-UX and HI-UX@.
8955 Use GNU ld specific options. This passes @option{-shared} to ld when
8956 building a shared library. It is the default when GCC is configured,
8957 explicitly or implicitly, with the GNU linker. This option does not
8958 have any affect on which ld is called, it only changes what parameters
8959 are passed to that ld. The ld that is called is determined by the
8960 @option{--with-ld} configure option, GCC's program search path, and
8961 finally by the user's @env{PATH}. The linker used by GCC can be printed
8962 using @samp{which `gcc -print-prog-name=ld`}. This option is only available
8963 on the 64 bit HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
8967 Use HP ld specific options. This passes @option{-b} to ld when building
8968 a shared library and passes @option{+Accept TypeMismatch} to ld on all
8969 links. It is the default when GCC is configured, explicitly or
8970 implicitly, with the HP linker. This option does not have any affect on
8971 which ld is called, it only changes what parameters are passed to that
8972 ld. The ld that is called is determined by the @option{--with-ld}
8973 configure option, GCC's program search path, and finally by the user's
8974 @env{PATH}. The linker used by GCC can be printed using @samp{which
8975 `gcc -print-prog-name=ld`}. This option is only available on the 64 bit
8976 HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
8979 @opindex mno-long-calls
8980 Generate code that uses long call sequences. This ensures that a call
8981 is always able to reach linker generated stubs. The default is to generate
8982 long calls only when the distance from the call site to the beginning
8983 of the function or translation unit, as the case may be, exceeds a
8984 predefined limit set by the branch type being used. The limits for
8985 normal calls are 7,600,000 and 240,000 bytes, respectively for the
8986 PA 2.0 and PA 1.X architectures. Sibcalls are always limited at
8989 Distances are measured from the beginning of functions when using the
8990 @option{-ffunction-sections} option, or when using the @option{-mgas}
8991 and @option{-mno-portable-runtime} options together under HP-UX with
8994 It is normally not desirable to use this option as it will degrade
8995 performance. However, it may be useful in large applications,
8996 particularly when partial linking is used to build the application.
8998 The types of long calls used depends on the capabilities of the
8999 assembler and linker, and the type of code being generated. The
9000 impact on systems that support long absolute calls, and long pic
9001 symbol-difference or pc-relative calls should be relatively small.
9002 However, an indirect call is used on 32-bit ELF systems in pic code
9003 and it is quite long.
9005 @item -munix=@var{unix-std}
9007 Generate compiler predefines and select a startfile for the specified
9008 UNIX standard. The choices for @var{unix-std} are @samp{93}, @samp{95}
9009 and @samp{98}. @samp{93} is supported on all HP-UX versions. @samp{95}
9010 is available on HP-UX 10.10 and later. @samp{98} is available on HP-UX
9011 11.11 and later. The default values are @samp{93} for HP-UX 10.00,
9012 @samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
9015 @option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
9016 @option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
9017 and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
9018 @option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
9019 @code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
9020 @code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
9022 It is @emph{important} to note that this option changes the interfaces
9023 for various library routines. It also affects the operational behavior
9024 of the C library. Thus, @emph{extreme} care is needed in using this
9027 Library code that is intended to operate with more than one UNIX
9028 standard must test, set and restore the variable @var{__xpg4_extended_mask}
9029 as appropriate. Most GNU software doesn't provide this capability.
9033 Suppress the generation of link options to search libdld.sl when the
9034 @option{-static} option is specified on HP-UX 10 and later.
9038 The HP-UX implementation of setlocale in libc has a dependency on
9039 libdld.sl. There isn't an archive version of libdld.sl. Thus,
9040 when the @option{-static} option is specified, special link options
9041 are needed to resolve this dependency.
9043 On HP-UX 10 and later, the GCC driver adds the necessary options to
9044 link with libdld.sl when the @option{-static} option is specified.
9045 This causes the resulting binary to be dynamic. On the 64-bit port,
9046 the linkers generate dynamic binaries by default in any case. The
9047 @option{-nolibdld} option can be used to prevent the GCC driver from
9048 adding these link options.
9052 Add support for multithreading with the @dfn{dce thread} library
9053 under HP-UX@. This option sets flags for both the preprocessor and
9057 @node i386 and x86-64 Options
9058 @subsection Intel 386 and AMD x86-64 Options
9059 @cindex i386 Options
9060 @cindex x86-64 Options
9061 @cindex Intel 386 Options
9062 @cindex AMD x86-64 Options
9064 These @samp{-m} options are defined for the i386 and x86-64 family of
9068 @item -mtune=@var{cpu-type}
9070 Tune to @var{cpu-type} everything applicable about the generated code, except
9071 for the ABI and the set of available instructions. The choices for
9075 Produce code optimized for the most common IA32/AMD64/EM64T processors.
9076 If you know the CPU on which your code will run, then you should use
9077 the corresponding @option{-mtune} option instead of
9078 @option{-mtune=generic}. But, if you do not know exactly what CPU users
9079 of your application will have, then you should use this option.
9081 As new processors are deployed in the marketplace, the behavior of this
9082 option will change. Therefore, if you upgrade to a newer version of
9083 GCC, the code generated option will change to reflect the processors
9084 that were most common when that version of GCC was released.
9086 There is no @option{-march=generic} option because @option{-march}
9087 indicates the instruction set the compiler can use, and there is no
9088 generic instruction set applicable to all processors. In contrast,
9089 @option{-mtune} indicates the processor (or, in this case, collection of
9090 processors) for which the code is optimized.
9092 This selects the CPU to tune for at compilation time by determining
9093 the processor type of the compiling machine. Using @option{-mtune=native}
9094 will produce code optimized for the local machine under the constraints
9095 of the selected instruction set. Using @option{-march=native} will
9096 enable all instruction subsets supported by the local machine (hence
9097 the result might not run on different machines).
9099 Original Intel's i386 CPU@.
9101 Intel's i486 CPU@. (No scheduling is implemented for this chip.)
9103 Intel Pentium CPU with no MMX support.
9105 Intel PentiumMMX CPU based on Pentium core with MMX instruction set support.
9107 Intel PentiumPro CPU@.
9109 Same as @code{generic}, but when used as @code{march} option, PentiumPro
9110 instruction set will be used, so the code will run on all i686 family chips.
9112 Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support.
9113 @item pentium3, pentium3m
9114 Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set
9117 Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set
9118 support. Used by Centrino notebooks.
9119 @item pentium4, pentium4m
9120 Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support.
9122 Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction
9125 Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE,
9126 SSE2 and SSE3 instruction set support.
9128 Intel Core2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3
9129 instruction set support.
9131 AMD K6 CPU with MMX instruction set support.
9133 Improved versions of AMD K6 CPU with MMX and 3dNOW! instruction set support.
9134 @item athlon, athlon-tbird
9135 AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and SSE prefetch instructions
9137 @item athlon-4, athlon-xp, athlon-mp
9138 Improved AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and full SSE
9139 instruction set support.
9140 @item k8, opteron, athlon64, athlon-fx
9141 AMD K8 core based CPUs with x86-64 instruction set support. (This supersets
9142 MMX, SSE, SSE2, 3dNOW!, enhanced 3dNOW! and 64-bit instruction set extensions.)
9143 @item k8-sse3, opteron-sse3, athlon64-sse3
9144 Improved versions of k8, opteron and athlon64 with SSE3 instruction set support.
9145 @item amdfam10, barcelona
9146 AMD Family 10h core based CPUs with x86-64 instruction set support. (This
9147 supersets MMX, SSE, SSE2, SSE3, SSE4A, 3dNOW!, enhanced 3dNOW!, ABM and 64-bit
9148 instruction set extensions.)
9150 IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction
9153 IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3dNOW!
9154 instruction set support.
9156 Via C3 CPU with MMX and 3dNOW! instruction set support. (No scheduling is
9157 implemented for this chip.)
9159 Via C3-2 CPU with MMX and SSE instruction set support. (No scheduling is
9160 implemented for this chip.)
9162 Embedded AMD CPU with MMX and 3dNOW! instruction set support.
9165 While picking a specific @var{cpu-type} will schedule things appropriately
9166 for that particular chip, the compiler will not generate any code that
9167 does not run on the i386 without the @option{-march=@var{cpu-type}} option
9170 @item -march=@var{cpu-type}
9172 Generate instructions for the machine type @var{cpu-type}. The choices
9173 for @var{cpu-type} are the same as for @option{-mtune}. Moreover,
9174 specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}.
9176 @item -mcpu=@var{cpu-type}
9178 A deprecated synonym for @option{-mtune}.
9187 @opindex mpentiumpro
9188 These options are synonyms for @option{-mtune=i386}, @option{-mtune=i486},
9189 @option{-mtune=pentium}, and @option{-mtune=pentiumpro} respectively.
9190 These synonyms are deprecated.
9192 @item -mfpmath=@var{unit}
9194 Generate floating point arithmetics for selected unit @var{unit}. The choices
9199 Use the standard 387 floating point coprocessor present majority of chips and
9200 emulated otherwise. Code compiled with this option will run almost everywhere.
9201 The temporary results are computed in 80bit precision instead of precision
9202 specified by the type resulting in slightly different results compared to most
9203 of other chips. See @option{-ffloat-store} for more detailed description.
9205 This is the default choice for i386 compiler.
9208 Use scalar floating point instructions present in the SSE instruction set.
9209 This instruction set is supported by Pentium3 and newer chips, in the AMD line
9210 by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE
9211 instruction set supports only single precision arithmetics, thus the double and
9212 extended precision arithmetics is still done using 387. Later version, present
9213 only in Pentium4 and the future AMD x86-64 chips supports double precision
9216 For the i386 compiler, you need to use @option{-march=@var{cpu-type}}, @option{-msse}
9217 or @option{-msse2} switches to enable SSE extensions and make this option
9218 effective. For the x86-64 compiler, these extensions are enabled by default.
9220 The resulting code should be considerably faster in the majority of cases and avoid
9221 the numerical instability problems of 387 code, but may break some existing
9222 code that expects temporaries to be 80bit.
9224 This is the default choice for the x86-64 compiler.
9227 Attempt to utilize both instruction sets at once. This effectively double the
9228 amount of available registers and on chips with separate execution units for
9229 387 and SSE the execution resources too. Use this option with care, as it is
9230 still experimental, because the GCC register allocator does not model separate
9231 functional units well resulting in instable performance.
9234 @item -masm=@var{dialect}
9235 @opindex masm=@var{dialect}
9236 Output asm instructions using selected @var{dialect}. Supported
9237 choices are @samp{intel} or @samp{att} (the default one). Darwin does
9238 not support @samp{intel}.
9243 @opindex mno-ieee-fp
9244 Control whether or not the compiler uses IEEE floating point
9245 comparisons. These handle correctly the case where the result of a
9246 comparison is unordered.
9249 @opindex msoft-float
9250 Generate output containing library calls for floating point.
9251 @strong{Warning:} the requisite libraries are not part of GCC@.
9252 Normally the facilities of the machine's usual C compiler are used, but
9253 this can't be done directly in cross-compilation. You must make your
9254 own arrangements to provide suitable library functions for
9257 On machines where a function returns floating point results in the 80387
9258 register stack, some floating point opcodes may be emitted even if
9259 @option{-msoft-float} is used.
9261 @item -mno-fp-ret-in-387
9262 @opindex mno-fp-ret-in-387
9263 Do not use the FPU registers for return values of functions.
9265 The usual calling convention has functions return values of types
9266 @code{float} and @code{double} in an FPU register, even if there
9267 is no FPU@. The idea is that the operating system should emulate
9270 The option @option{-mno-fp-ret-in-387} causes such values to be returned
9271 in ordinary CPU registers instead.
9273 @item -mno-fancy-math-387
9274 @opindex mno-fancy-math-387
9275 Some 387 emulators do not support the @code{sin}, @code{cos} and
9276 @code{sqrt} instructions for the 387. Specify this option to avoid
9277 generating those instructions. This option is the default on
9278 OpenBSD and NetBSD@. This option is overridden when @option{-march}
9279 indicates that the target cpu will always have an FPU and so the
9280 instruction will not need emulation. As of revision 2.6.1, these
9281 instructions are not generated unless you also use the
9282 @option{-funsafe-math-optimizations} switch.
9284 @item -malign-double
9285 @itemx -mno-align-double
9286 @opindex malign-double
9287 @opindex mno-align-double
9288 Control whether GCC aligns @code{double}, @code{long double}, and
9289 @code{long long} variables on a two word boundary or a one word
9290 boundary. Aligning @code{double} variables on a two word boundary will
9291 produce code that runs somewhat faster on a @samp{Pentium} at the
9292 expense of more memory.
9294 On x86-64, @option{-malign-double} is enabled by default.
9296 @strong{Warning:} if you use the @option{-malign-double} switch,
9297 structures containing the above types will be aligned differently than
9298 the published application binary interface specifications for the 386
9299 and will not be binary compatible with structures in code compiled
9300 without that switch.
9302 @item -m96bit-long-double
9303 @itemx -m128bit-long-double
9304 @opindex m96bit-long-double
9305 @opindex m128bit-long-double
9306 These switches control the size of @code{long double} type. The i386
9307 application binary interface specifies the size to be 96 bits,
9308 so @option{-m96bit-long-double} is the default in 32 bit mode.
9310 Modern architectures (Pentium and newer) would prefer @code{long double}
9311 to be aligned to an 8 or 16 byte boundary. In arrays or structures
9312 conforming to the ABI, this would not be possible. So specifying a
9313 @option{-m128bit-long-double} will align @code{long double}
9314 to a 16 byte boundary by padding the @code{long double} with an additional
9317 In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
9318 its ABI specifies that @code{long double} is to be aligned on 16 byte boundary.
9320 Notice that neither of these options enable any extra precision over the x87
9321 standard of 80 bits for a @code{long double}.
9323 @strong{Warning:} if you override the default value for your target ABI, the
9324 structures and arrays containing @code{long double} variables will change
9325 their size as well as function calling convention for function taking
9326 @code{long double} will be modified. Hence they will not be binary
9327 compatible with arrays or structures in code compiled without that switch.
9329 @item -mmlarge-data-threshold=@var{number}
9330 @opindex mlarge-data-threshold=@var{number}
9331 When @option{-mcmodel=medium} is specified, the data greater than
9332 @var{threshold} are placed in large data section. This value must be the
9333 same across all object linked into the binary and defaults to 65535.
9336 @itemx -mno-svr3-shlib
9337 @opindex msvr3-shlib
9338 @opindex mno-svr3-shlib
9339 Control whether GCC places uninitialized local variables into the
9340 @code{bss} or @code{data} segments. @option{-msvr3-shlib} places them
9341 into @code{bss}. These options are meaningful only on System V Release 3.
9345 Use a different function-calling convention, in which functions that
9346 take a fixed number of arguments return with the @code{ret} @var{num}
9347 instruction, which pops their arguments while returning. This saves one
9348 instruction in the caller since there is no need to pop the arguments
9351 You can specify that an individual function is called with this calling
9352 sequence with the function attribute @samp{stdcall}. You can also
9353 override the @option{-mrtd} option by using the function attribute
9354 @samp{cdecl}. @xref{Function Attributes}.
9356 @strong{Warning:} this calling convention is incompatible with the one
9357 normally used on Unix, so you cannot use it if you need to call
9358 libraries compiled with the Unix compiler.
9360 Also, you must provide function prototypes for all functions that
9361 take variable numbers of arguments (including @code{printf});
9362 otherwise incorrect code will be generated for calls to those
9365 In addition, seriously incorrect code will result if you call a
9366 function with too many arguments. (Normally, extra arguments are
9367 harmlessly ignored.)
9369 @item -mregparm=@var{num}
9371 Control how many registers are used to pass integer arguments. By
9372 default, no registers are used to pass arguments, and at most 3
9373 registers can be used. You can control this behavior for a specific
9374 function by using the function attribute @samp{regparm}.
9375 @xref{Function Attributes}.
9377 @strong{Warning:} if you use this switch, and
9378 @var{num} is nonzero, then you must build all modules with the same
9379 value, including any libraries. This includes the system libraries and
9383 @opindex msseregparm
9384 Use SSE register passing conventions for float and double arguments
9385 and return values. You can control this behavior for a specific
9386 function by using the function attribute @samp{sseregparm}.
9387 @xref{Function Attributes}.
9389 @strong{Warning:} if you use this switch then you must build all
9390 modules with the same value, including any libraries. This includes
9391 the system libraries and startup modules.
9393 @item -mstackrealign
9394 @opindex mstackrealign
9395 Realign the stack at entry. On the Intel x86, the
9396 @option{-mstackrealign} option will generate an alternate prologue and
9397 epilogue that realigns the runtime stack. This supports mixing legacy
9398 codes that keep a 4-byte aligned stack with modern codes that keep a
9399 16-byte stack for SSE compatibility. The alternate prologue and
9400 epilogue are slower and bigger than the regular ones, and the
9401 alternate prologue requires an extra scratch register; this lowers the
9402 number of registers available if used in conjunction with the
9403 @code{regparm} attribute. The @option{-mstackrealign} option is
9404 incompatible with the nested function prologue; this is considered a
9405 hard error. See also the attribute @code{force_align_arg_pointer},
9406 applicable to individual functions.
9408 @item -mpreferred-stack-boundary=@var{num}
9409 @opindex mpreferred-stack-boundary
9410 Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
9411 byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
9412 the default is 4 (16 bytes or 128 bits).
9414 On Pentium and PentiumPro, @code{double} and @code{long double} values
9415 should be aligned to an 8 byte boundary (see @option{-malign-double}) or
9416 suffer significant run time performance penalties. On Pentium III, the
9417 Streaming SIMD Extension (SSE) data type @code{__m128} may not work
9418 properly if it is not 16 byte aligned.
9420 To ensure proper alignment of this values on the stack, the stack boundary
9421 must be as aligned as that required by any value stored on the stack.
9422 Further, every function must be generated such that it keeps the stack
9423 aligned. Thus calling a function compiled with a higher preferred
9424 stack boundary from a function compiled with a lower preferred stack
9425 boundary will most likely misalign the stack. It is recommended that
9426 libraries that use callbacks always use the default setting.
9428 This extra alignment does consume extra stack space, and generally
9429 increases code size. Code that is sensitive to stack space usage, such
9430 as embedded systems and operating system kernels, may want to reduce the
9431 preferred alignment to @option{-mpreferred-stack-boundary=2}.
9459 These switches enable or disable the use of instructions in the MMX,
9460 SSE, SSE2, SSE3, SSSE3, SSE4A, ABM, AES or 3DNow! extended
9461 instruction sets. These extensions are also available as built-in
9462 functions: see @ref{X86 Built-in Functions}, for details of the functions
9463 enabled and disabled by these switches.
9465 To have SSE/SSE2 instructions generated automatically from floating-point
9466 code (as opposed to 387 instructions), see @option{-mfpmath=sse}.
9468 These options will enable GCC to use these extended instructions in
9469 generated code, even without @option{-mfpmath=sse}. Applications which
9470 perform runtime CPU detection must compile separate files for each
9471 supported architecture, using the appropriate flags. In particular,
9472 the file containing the CPU detection code should be compiled without
9476 @itemx -mno-push-args
9478 @opindex mno-push-args
9479 Use PUSH operations to store outgoing parameters. This method is shorter
9480 and usually equally fast as method using SUB/MOV operations and is enabled
9481 by default. In some cases disabling it may improve performance because of
9482 improved scheduling and reduced dependencies.
9484 @item -maccumulate-outgoing-args
9485 @opindex maccumulate-outgoing-args
9486 If enabled, the maximum amount of space required for outgoing arguments will be
9487 computed in the function prologue. This is faster on most modern CPUs
9488 because of reduced dependencies, improved scheduling and reduced stack usage
9489 when preferred stack boundary is not equal to 2. The drawback is a notable
9490 increase in code size. This switch implies @option{-mno-push-args}.
9494 Support thread-safe exception handling on @samp{Mingw32}. Code that relies
9495 on thread-safe exception handling must compile and link all code with the
9496 @option{-mthreads} option. When compiling, @option{-mthreads} defines
9497 @option{-D_MT}; when linking, it links in a special thread helper library
9498 @option{-lmingwthrd} which cleans up per thread exception handling data.
9500 @item -mno-align-stringops
9501 @opindex mno-align-stringops
9502 Do not align destination of inlined string operations. This switch reduces
9503 code size and improves performance in case the destination is already aligned,
9504 but GCC doesn't know about it.
9506 @item -minline-all-stringops
9507 @opindex minline-all-stringops
9508 By default GCC inlines string operations only when destination is known to be
9509 aligned at least to 4 byte boundary. This enables more inlining, increase code
9510 size, but may improve performance of code that depends on fast memcpy, strlen
9511 and memset for short lengths.
9513 @item -momit-leaf-frame-pointer
9514 @opindex momit-leaf-frame-pointer
9515 Don't keep the frame pointer in a register for leaf functions. This
9516 avoids the instructions to save, set up and restore frame pointers and
9517 makes an extra register available in leaf functions. The option
9518 @option{-fomit-frame-pointer} removes the frame pointer for all functions
9519 which might make debugging harder.
9521 @item -mtls-direct-seg-refs
9522 @itemx -mno-tls-direct-seg-refs
9523 @opindex mtls-direct-seg-refs
9524 Controls whether TLS variables may be accessed with offsets from the
9525 TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
9526 or whether the thread base pointer must be added. Whether or not this
9527 is legal depends on the operating system, and whether it maps the
9528 segment to cover the entire TLS area.
9530 For systems that use GNU libc, the default is on.
9533 These @samp{-m} switches are supported in addition to the above
9534 on AMD x86-64 processors in 64-bit environments.
9541 Generate code for a 32-bit or 64-bit environment.
9542 The 32-bit environment sets int, long and pointer to 32 bits and
9543 generates code that runs on any i386 system.
9544 The 64-bit environment sets int to 32 bits and long and pointer
9545 to 64 bits and generates code for AMD's x86-64 architecture. For
9546 darwin only the -m64 option turns off the @option{-fno-pic} and
9547 @option{-mdynamic-no-pic} options.
9550 @opindex no-red-zone
9551 Do not use a so called red zone for x86-64 code. The red zone is mandated
9552 by the x86-64 ABI, it is a 128-byte area beyond the location of the
9553 stack pointer that will not be modified by signal or interrupt handlers
9554 and therefore can be used for temporary data without adjusting the stack
9555 pointer. The flag @option{-mno-red-zone} disables this red zone.
9557 @item -mcmodel=small
9558 @opindex mcmodel=small
9559 Generate code for the small code model: the program and its symbols must
9560 be linked in the lower 2 GB of the address space. Pointers are 64 bits.
9561 Programs can be statically or dynamically linked. This is the default
9564 @item -mcmodel=kernel
9565 @opindex mcmodel=kernel
9566 Generate code for the kernel code model. The kernel runs in the
9567 negative 2 GB of the address space.
9568 This model has to be used for Linux kernel code.
9570 @item -mcmodel=medium
9571 @opindex mcmodel=medium
9572 Generate code for the medium model: The program is linked in the lower 2
9573 GB of the address space but symbols can be located anywhere in the
9574 address space. Programs can be statically or dynamically linked, but
9575 building of shared libraries are not supported with the medium model.
9577 @item -mcmodel=large
9578 @opindex mcmodel=large
9579 Generate code for the large model: This model makes no assumptions
9580 about addresses and sizes of sections. Currently GCC does not implement
9585 @subsection IA-64 Options
9586 @cindex IA-64 Options
9588 These are the @samp{-m} options defined for the Intel IA-64 architecture.
9592 @opindex mbig-endian
9593 Generate code for a big endian target. This is the default for HP-UX@.
9595 @item -mlittle-endian
9596 @opindex mlittle-endian
9597 Generate code for a little endian target. This is the default for AIX5
9604 Generate (or don't) code for the GNU assembler. This is the default.
9605 @c Also, this is the default if the configure option @option{--with-gnu-as}
9612 Generate (or don't) code for the GNU linker. This is the default.
9613 @c Also, this is the default if the configure option @option{--with-gnu-ld}
9618 Generate code that does not use a global pointer register. The result
9619 is not position independent code, and violates the IA-64 ABI@.
9621 @item -mvolatile-asm-stop
9622 @itemx -mno-volatile-asm-stop
9623 @opindex mvolatile-asm-stop
9624 @opindex mno-volatile-asm-stop
9625 Generate (or don't) a stop bit immediately before and after volatile asm
9628 @item -mregister-names
9629 @itemx -mno-register-names
9630 @opindex mregister-names
9631 @opindex mno-register-names
9632 Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
9633 the stacked registers. This may make assembler output more readable.
9639 Disable (or enable) optimizations that use the small data section. This may
9640 be useful for working around optimizer bugs.
9643 @opindex mconstant-gp
9644 Generate code that uses a single constant global pointer value. This is
9645 useful when compiling kernel code.
9649 Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
9650 This is useful when compiling firmware code.
9652 @item -minline-float-divide-min-latency
9653 @opindex minline-float-divide-min-latency
9654 Generate code for inline divides of floating point values
9655 using the minimum latency algorithm.
9657 @item -minline-float-divide-max-throughput
9658 @opindex minline-float-divide-max-throughput
9659 Generate code for inline divides of floating point values
9660 using the maximum throughput algorithm.
9662 @item -minline-int-divide-min-latency
9663 @opindex minline-int-divide-min-latency
9664 Generate code for inline divides of integer values
9665 using the minimum latency algorithm.
9667 @item -minline-int-divide-max-throughput
9668 @opindex minline-int-divide-max-throughput
9669 Generate code for inline divides of integer values
9670 using the maximum throughput algorithm.
9672 @item -minline-sqrt-min-latency
9673 @opindex minline-sqrt-min-latency
9674 Generate code for inline square roots
9675 using the minimum latency algorithm.
9677 @item -minline-sqrt-max-throughput
9678 @opindex minline-sqrt-max-throughput
9679 Generate code for inline square roots
9680 using the maximum throughput algorithm.
9682 @item -mno-dwarf2-asm
9684 @opindex mno-dwarf2-asm
9685 @opindex mdwarf2-asm
9686 Don't (or do) generate assembler code for the DWARF2 line number debugging
9687 info. This may be useful when not using the GNU assembler.
9689 @item -mearly-stop-bits
9690 @itemx -mno-early-stop-bits
9691 @opindex mearly-stop-bits
9692 @opindex mno-early-stop-bits
9693 Allow stop bits to be placed earlier than immediately preceding the
9694 instruction that triggered the stop bit. This can improve instruction
9695 scheduling, but does not always do so.
9697 @item -mfixed-range=@var{register-range}
9698 @opindex mfixed-range
9699 Generate code treating the given register range as fixed registers.
9700 A fixed register is one that the register allocator can not use. This is
9701 useful when compiling kernel code. A register range is specified as
9702 two registers separated by a dash. Multiple register ranges can be
9703 specified separated by a comma.
9705 @item -mtls-size=@var{tls-size}
9707 Specify bit size of immediate TLS offsets. Valid values are 14, 22, and
9710 @item -mtune=@var{cpu-type}
9712 Tune the instruction scheduling for a particular CPU, Valid values are
9713 itanium, itanium1, merced, itanium2, and mckinley.
9719 Add support for multithreading using the POSIX threads library. This
9720 option sets flags for both the preprocessor and linker. It does
9721 not affect the thread safety of object code produced by the compiler or
9722 that of libraries supplied with it. These are HP-UX specific flags.
9728 Generate code for a 32-bit or 64-bit environment.
9729 The 32-bit environment sets int, long and pointer to 32 bits.
9730 The 64-bit environment sets int to 32 bits and long and pointer
9731 to 64 bits. These are HP-UX specific flags.
9733 @item -mno-sched-br-data-spec
9734 @itemx -msched-br-data-spec
9735 @opindex mno-sched-br-data-spec
9736 @opindex msched-br-data-spec
9737 (Dis/En)able data speculative scheduling before reload.
9738 This will result in generation of the ld.a instructions and
9739 the corresponding check instructions (ld.c / chk.a).
9740 The default is 'disable'.
9742 @item -msched-ar-data-spec
9743 @itemx -mno-sched-ar-data-spec
9744 @opindex msched-ar-data-spec
9745 @opindex mno-sched-ar-data-spec
9746 (En/Dis)able data speculative scheduling after reload.
9747 This will result in generation of the ld.a instructions and
9748 the corresponding check instructions (ld.c / chk.a).
9749 The default is 'enable'.
9751 @item -mno-sched-control-spec
9752 @itemx -msched-control-spec
9753 @opindex mno-sched-control-spec
9754 @opindex msched-control-spec
9755 (Dis/En)able control speculative scheduling. This feature is
9756 available only during region scheduling (i.e. before reload).
9757 This will result in generation of the ld.s instructions and
9758 the corresponding check instructions chk.s .
9759 The default is 'disable'.
9761 @item -msched-br-in-data-spec
9762 @itemx -mno-sched-br-in-data-spec
9763 @opindex msched-br-in-data-spec
9764 @opindex mno-sched-br-in-data-spec
9765 (En/Dis)able speculative scheduling of the instructions that
9766 are dependent on the data speculative loads before reload.
9767 This is effective only with @option{-msched-br-data-spec} enabled.
9768 The default is 'enable'.
9770 @item -msched-ar-in-data-spec
9771 @itemx -mno-sched-ar-in-data-spec
9772 @opindex msched-ar-in-data-spec
9773 @opindex mno-sched-ar-in-data-spec
9774 (En/Dis)able speculative scheduling of the instructions that
9775 are dependent on the data speculative loads after reload.
9776 This is effective only with @option{-msched-ar-data-spec} enabled.
9777 The default is 'enable'.
9779 @item -msched-in-control-spec
9780 @itemx -mno-sched-in-control-spec
9781 @opindex msched-in-control-spec
9782 @opindex mno-sched-in-control-spec
9783 (En/Dis)able speculative scheduling of the instructions that
9784 are dependent on the control speculative loads.
9785 This is effective only with @option{-msched-control-spec} enabled.
9786 The default is 'enable'.
9789 @itemx -mno-sched-ldc
9791 @opindex mno-sched-ldc
9792 (En/Dis)able use of simple data speculation checks ld.c .
9793 If disabled, only chk.a instructions will be emitted to check
9794 data speculative loads.
9795 The default is 'enable'.
9797 @item -mno-sched-control-ldc
9798 @itemx -msched-control-ldc
9799 @opindex mno-sched-control-ldc
9800 @opindex msched-control-ldc
9801 (Dis/En)able use of ld.c instructions to check control speculative loads.
9802 If enabled, in case of control speculative load with no speculatively
9803 scheduled dependent instructions this load will be emitted as ld.sa and
9804 ld.c will be used to check it.
9805 The default is 'disable'.
9807 @item -mno-sched-spec-verbose
9808 @itemx -msched-spec-verbose
9809 @opindex mno-sched-spec-verbose
9810 @opindex msched-spec-verbose
9811 (Dis/En)able printing of the information about speculative motions.
9813 @item -mno-sched-prefer-non-data-spec-insns
9814 @itemx -msched-prefer-non-data-spec-insns
9815 @opindex mno-sched-prefer-non-data-spec-insns
9816 @opindex msched-prefer-non-data-spec-insns
9817 If enabled, data speculative instructions will be chosen for schedule
9818 only if there are no other choices at the moment. This will make
9819 the use of the data speculation much more conservative.
9820 The default is 'disable'.
9822 @item -mno-sched-prefer-non-control-spec-insns
9823 @itemx -msched-prefer-non-control-spec-insns
9824 @opindex mno-sched-prefer-non-control-spec-insns
9825 @opindex msched-prefer-non-control-spec-insns
9826 If enabled, control speculative instructions will be chosen for schedule
9827 only if there are no other choices at the moment. This will make
9828 the use of the control speculation much more conservative.
9829 The default is 'disable'.
9831 @item -mno-sched-count-spec-in-critical-path
9832 @itemx -msched-count-spec-in-critical-path
9833 @opindex mno-sched-count-spec-in-critical-path
9834 @opindex msched-count-spec-in-critical-path
9835 If enabled, speculative dependencies will be considered during
9836 computation of the instructions priorities. This will make the use of the
9837 speculation a bit more conservative.
9838 The default is 'disable'.
9843 @subsection M32C Options
9844 @cindex M32C options
9847 @item -mcpu=@var{name}
9849 Select the CPU for which code is generated. @var{name} may be one of
9850 @samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to
9851 /60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for
9856 Specifies that the program will be run on the simulator. This causes
9857 an alternate runtime library to be linked in which supports, for
9858 example, file I/O. You must not use this option when generating
9859 programs that will run on real hardware; you must provide your own
9860 runtime library for whatever I/O functions are needed.
9862 @item -memregs=@var{number}
9864 Specifies the number of memory-based pseudo-registers GCC will use
9865 during code generation. These pseudo-registers will be used like real
9866 registers, so there is a tradeoff between GCC's ability to fit the
9867 code into available registers, and the performance penalty of using
9868 memory instead of registers. Note that all modules in a program must
9869 be compiled with the same value for this option. Because of that, you
9870 must not use this option with the default runtime libraries gcc
9875 @node M32R/D Options
9876 @subsection M32R/D Options
9877 @cindex M32R/D options
9879 These @option{-m} options are defined for Renesas M32R/D architectures:
9884 Generate code for the M32R/2@.
9888 Generate code for the M32R/X@.
9892 Generate code for the M32R@. This is the default.
9895 @opindex mmodel=small
9896 Assume all objects live in the lower 16MB of memory (so that their addresses
9897 can be loaded with the @code{ld24} instruction), and assume all subroutines
9898 are reachable with the @code{bl} instruction.
9899 This is the default.
9901 The addressability of a particular object can be set with the
9902 @code{model} attribute.
9904 @item -mmodel=medium
9905 @opindex mmodel=medium
9906 Assume objects may be anywhere in the 32-bit address space (the compiler
9907 will generate @code{seth/add3} instructions to load their addresses), and
9908 assume all subroutines are reachable with the @code{bl} instruction.
9911 @opindex mmodel=large
9912 Assume objects may be anywhere in the 32-bit address space (the compiler
9913 will generate @code{seth/add3} instructions to load their addresses), and
9914 assume subroutines may not be reachable with the @code{bl} instruction
9915 (the compiler will generate the much slower @code{seth/add3/jl}
9916 instruction sequence).
9919 @opindex msdata=none
9920 Disable use of the small data area. Variables will be put into
9921 one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
9922 @code{section} attribute has been specified).
9923 This is the default.
9925 The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
9926 Objects may be explicitly put in the small data area with the
9927 @code{section} attribute using one of these sections.
9930 @opindex msdata=sdata
9931 Put small global and static data in the small data area, but do not
9932 generate special code to reference them.
9936 Put small global and static data in the small data area, and generate
9937 special instructions to reference them.
9941 @cindex smaller data references
9942 Put global and static objects less than or equal to @var{num} bytes
9943 into the small data or bss sections instead of the normal data or bss
9944 sections. The default value of @var{num} is 8.
9945 The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
9946 for this option to have any effect.
9948 All modules should be compiled with the same @option{-G @var{num}} value.
9949 Compiling with different values of @var{num} may or may not work; if it
9950 doesn't the linker will give an error message---incorrect code will not be
9955 Makes the M32R specific code in the compiler display some statistics
9956 that might help in debugging programs.
9959 @opindex malign-loops
9960 Align all loops to a 32-byte boundary.
9962 @item -mno-align-loops
9963 @opindex mno-align-loops
9964 Do not enforce a 32-byte alignment for loops. This is the default.
9966 @item -missue-rate=@var{number}
9967 @opindex missue-rate=@var{number}
9968 Issue @var{number} instructions per cycle. @var{number} can only be 1
9971 @item -mbranch-cost=@var{number}
9972 @opindex mbranch-cost=@var{number}
9973 @var{number} can only be 1 or 2. If it is 1 then branches will be
9974 preferred over conditional code, if it is 2, then the opposite will
9977 @item -mflush-trap=@var{number}
9978 @opindex mflush-trap=@var{number}
9979 Specifies the trap number to use to flush the cache. The default is
9980 12. Valid numbers are between 0 and 15 inclusive.
9982 @item -mno-flush-trap
9983 @opindex mno-flush-trap
9984 Specifies that the cache cannot be flushed by using a trap.
9986 @item -mflush-func=@var{name}
9987 @opindex mflush-func=@var{name}
9988 Specifies the name of the operating system function to call to flush
9989 the cache. The default is @emph{_flush_cache}, but a function call
9990 will only be used if a trap is not available.
9992 @item -mno-flush-func
9993 @opindex mno-flush-func
9994 Indicates that there is no OS function for flushing the cache.
9998 @node M680x0 Options
9999 @subsection M680x0 Options
10000 @cindex M680x0 options
10002 These are the @samp{-m} options defined for the 68000 series. The default
10003 values for these options depends on which style of 68000 was selected when
10004 the compiler was configured; the defaults for the most common choices are
10012 Generate output for a 68000. This is the default
10013 when the compiler is configured for 68000-based systems.
10015 Use this option for microcontrollers with a 68000 or EC000 core,
10016 including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
10022 Generate output for a 68020. This is the default
10023 when the compiler is configured for 68020-based systems.
10027 Generate output containing 68881 instructions for floating point.
10028 This is the default for most 68020 systems unless @option{--nfp} was
10029 specified when the compiler was configured.
10033 Generate output for a 68030. This is the default when the compiler is
10034 configured for 68030-based systems.
10038 Generate output for a 68040. This is the default when the compiler is
10039 configured for 68040-based systems.
10041 This option inhibits the use of 68881/68882 instructions that have to be
10042 emulated by software on the 68040. Use this option if your 68040 does not
10043 have code to emulate those instructions.
10047 Generate output for a 68060. This is the default when the compiler is
10048 configured for 68060-based systems.
10050 This option inhibits the use of 68020 and 68881/68882 instructions that
10051 have to be emulated by software on the 68060. Use this option if your 68060
10052 does not have code to emulate those instructions.
10056 Generate output for a CPU32. This is the default
10057 when the compiler is configured for CPU32-based systems.
10059 Use this option for microcontrollers with a
10060 CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
10061 68336, 68340, 68341, 68349 and 68360.
10065 Generate output for a 520X ``coldfire'' family cpu. This is the default
10066 when the compiler is configured for 520X-based systems.
10068 Use this option for microcontroller with a 5200 core, including
10069 the MCF5202, MCF5203, MCF5204 and MCF5202.
10073 Generate output for a ColdFire V4e family cpu (e.g.@: 547x/548x).
10074 This includes use of hardware floating point instructions.
10078 Generate output for a 68040, without using any of the new instructions.
10079 This results in code which can run relatively efficiently on either a
10080 68020/68881 or a 68030 or a 68040. The generated code does use the
10081 68881 instructions that are emulated on the 68040.
10085 Generate output for a 68060, without using any of the new instructions.
10086 This results in code which can run relatively efficiently on either a
10087 68020/68881 or a 68030 or a 68040. The generated code does use the
10088 68881 instructions that are emulated on the 68060.
10091 @opindex msoft-float
10092 Generate output containing library calls for floating point.
10093 @strong{Warning:} the requisite libraries are not available for all m68k
10094 targets. Normally the facilities of the machine's usual C compiler are
10095 used, but this can't be done directly in cross-compilation. You must
10096 make your own arrangements to provide suitable library functions for
10097 cross-compilation. The embedded targets @samp{m68k-*-aout} and
10098 @samp{m68k-*-coff} do provide software floating point support.
10102 Consider type @code{int} to be 16 bits wide, like @code{short int}.
10103 Additionally, parameters passed on the stack are also aligned to a
10104 16-bit boundary even on targets whose API mandates promotion to 32-bit.
10107 @opindex mnobitfield
10108 Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
10109 and @option{-m5200} options imply @w{@option{-mnobitfield}}.
10113 Do use the bit-field instructions. The @option{-m68020} option implies
10114 @option{-mbitfield}. This is the default if you use a configuration
10115 designed for a 68020.
10119 Use a different function-calling convention, in which functions
10120 that take a fixed number of arguments return with the @code{rtd}
10121 instruction, which pops their arguments while returning. This
10122 saves one instruction in the caller since there is no need to pop
10123 the arguments there.
10125 This calling convention is incompatible with the one normally
10126 used on Unix, so you cannot use it if you need to call libraries
10127 compiled with the Unix compiler.
10129 Also, you must provide function prototypes for all functions that
10130 take variable numbers of arguments (including @code{printf});
10131 otherwise incorrect code will be generated for calls to those
10134 In addition, seriously incorrect code will result if you call a
10135 function with too many arguments. (Normally, extra arguments are
10136 harmlessly ignored.)
10138 The @code{rtd} instruction is supported by the 68010, 68020, 68030,
10139 68040, 68060 and CPU32 processors, but not by the 68000 or 5200.
10142 @itemx -mno-align-int
10143 @opindex malign-int
10144 @opindex mno-align-int
10145 Control whether GCC aligns @code{int}, @code{long}, @code{long long},
10146 @code{float}, @code{double}, and @code{long double} variables on a 32-bit
10147 boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
10148 Aligning variables on 32-bit boundaries produces code that runs somewhat
10149 faster on processors with 32-bit busses at the expense of more memory.
10151 @strong{Warning:} if you use the @option{-malign-int} switch, GCC will
10152 align structures containing the above types differently than
10153 most published application binary interface specifications for the m68k.
10157 Use the pc-relative addressing mode of the 68000 directly, instead of
10158 using a global offset table. At present, this option implies @option{-fpic},
10159 allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
10160 not presently supported with @option{-mpcrel}, though this could be supported for
10161 68020 and higher processors.
10163 @item -mno-strict-align
10164 @itemx -mstrict-align
10165 @opindex mno-strict-align
10166 @opindex mstrict-align
10167 Do not (do) assume that unaligned memory references will be handled by
10171 Generate code that allows the data segment to be located in a different
10172 area of memory from the text segment. This allows for execute in place in
10173 an environment without virtual memory management. This option implies
10176 @item -mno-sep-data
10177 Generate code that assumes that the data segment follows the text segment.
10178 This is the default.
10180 @item -mid-shared-library
10181 Generate code that supports shared libraries via the library ID method.
10182 This allows for execute in place and shared libraries in an environment
10183 without virtual memory management. This option implies @option{-fPIC}.
10185 @item -mno-id-shared-library
10186 Generate code that doesn't assume ID based shared libraries are being used.
10187 This is the default.
10189 @item -mshared-library-id=n
10190 Specified the identification number of the ID based shared library being
10191 compiled. Specifying a value of 0 will generate more compact code, specifying
10192 other values will force the allocation of that number to the current
10193 library but is no more space or time efficient than omitting this option.
10197 @node M68hc1x Options
10198 @subsection M68hc1x Options
10199 @cindex M68hc1x options
10201 These are the @samp{-m} options defined for the 68hc11 and 68hc12
10202 microcontrollers. The default values for these options depends on
10203 which style of microcontroller was selected when the compiler was configured;
10204 the defaults for the most common choices are given below.
10211 Generate output for a 68HC11. This is the default
10212 when the compiler is configured for 68HC11-based systems.
10218 Generate output for a 68HC12. This is the default
10219 when the compiler is configured for 68HC12-based systems.
10225 Generate output for a 68HCS12.
10227 @item -mauto-incdec
10228 @opindex mauto-incdec
10229 Enable the use of 68HC12 pre and post auto-increment and auto-decrement
10236 Enable the use of 68HC12 min and max instructions.
10239 @itemx -mno-long-calls
10240 @opindex mlong-calls
10241 @opindex mno-long-calls
10242 Treat all calls as being far away (near). If calls are assumed to be
10243 far away, the compiler will use the @code{call} instruction to
10244 call a function and the @code{rtc} instruction for returning.
10248 Consider type @code{int} to be 16 bits wide, like @code{short int}.
10250 @item -msoft-reg-count=@var{count}
10251 @opindex msoft-reg-count
10252 Specify the number of pseudo-soft registers which are used for the
10253 code generation. The maximum number is 32. Using more pseudo-soft
10254 register may or may not result in better code depending on the program.
10255 The default is 4 for 68HC11 and 2 for 68HC12.
10259 @node MCore Options
10260 @subsection MCore Options
10261 @cindex MCore options
10263 These are the @samp{-m} options defined for the Motorola M*Core
10269 @itemx -mno-hardlit
10271 @opindex mno-hardlit
10272 Inline constants into the code stream if it can be done in two
10273 instructions or less.
10279 Use the divide instruction. (Enabled by default).
10281 @item -mrelax-immediate
10282 @itemx -mno-relax-immediate
10283 @opindex mrelax-immediate
10284 @opindex mno-relax-immediate
10285 Allow arbitrary sized immediates in bit operations.
10287 @item -mwide-bitfields
10288 @itemx -mno-wide-bitfields
10289 @opindex mwide-bitfields
10290 @opindex mno-wide-bitfields
10291 Always treat bit-fields as int-sized.
10293 @item -m4byte-functions
10294 @itemx -mno-4byte-functions
10295 @opindex m4byte-functions
10296 @opindex mno-4byte-functions
10297 Force all functions to be aligned to a four byte boundary.
10299 @item -mcallgraph-data
10300 @itemx -mno-callgraph-data
10301 @opindex mcallgraph-data
10302 @opindex mno-callgraph-data
10303 Emit callgraph information.
10306 @itemx -mno-slow-bytes
10307 @opindex mslow-bytes
10308 @opindex mno-slow-bytes
10309 Prefer word access when reading byte quantities.
10311 @item -mlittle-endian
10312 @itemx -mbig-endian
10313 @opindex mlittle-endian
10314 @opindex mbig-endian
10315 Generate code for a little endian target.
10321 Generate code for the 210 processor.
10325 @subsection MIPS Options
10326 @cindex MIPS options
10332 Generate big-endian code.
10336 Generate little-endian code. This is the default for @samp{mips*el-*-*}
10339 @item -march=@var{arch}
10341 Generate code that will run on @var{arch}, which can be the name of a
10342 generic MIPS ISA, or the name of a particular processor.
10344 @samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
10345 @samp{mips32}, @samp{mips32r2}, and @samp{mips64}.
10346 The processor names are:
10347 @samp{4kc}, @samp{4km}, @samp{4kp},
10348 @samp{5kc}, @samp{5kf},
10350 @samp{24k}, @samp{24kc}, @samp{24kf}, @samp{24kx},
10353 @samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
10354 @samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000},
10355 @samp{rm7000}, @samp{rm9000},
10358 @samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
10359 @samp{vr5000}, @samp{vr5400} and @samp{vr5500}.
10360 The special value @samp{from-abi} selects the
10361 most compatible architecture for the selected ABI (that is,
10362 @samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
10364 In processor names, a final @samp{000} can be abbreviated as @samp{k}
10365 (for example, @samp{-march=r2k}). Prefixes are optional, and
10366 @samp{vr} may be written @samp{r}.
10368 GCC defines two macros based on the value of this option. The first
10369 is @samp{_MIPS_ARCH}, which gives the name of target architecture, as
10370 a string. The second has the form @samp{_MIPS_ARCH_@var{foo}},
10371 where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@.
10372 For example, @samp{-march=r2000} will set @samp{_MIPS_ARCH}
10373 to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}.
10375 Note that the @samp{_MIPS_ARCH} macro uses the processor names given
10376 above. In other words, it will have the full prefix and will not
10377 abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},
10378 the macro names the resolved architecture (either @samp{"mips1"} or
10379 @samp{"mips3"}). It names the default architecture when no
10380 @option{-march} option is given.
10382 @item -mtune=@var{arch}
10384 Optimize for @var{arch}. Among other things, this option controls
10385 the way instructions are scheduled, and the perceived cost of arithmetic
10386 operations. The list of @var{arch} values is the same as for
10389 When this option is not used, GCC will optimize for the processor
10390 specified by @option{-march}. By using @option{-march} and
10391 @option{-mtune} together, it is possible to generate code that will
10392 run on a family of processors, but optimize the code for one
10393 particular member of that family.
10395 @samp{-mtune} defines the macros @samp{_MIPS_TUNE} and
10396 @samp{_MIPS_TUNE_@var{foo}}, which work in the same way as the
10397 @samp{-march} ones described above.
10401 Equivalent to @samp{-march=mips1}.
10405 Equivalent to @samp{-march=mips2}.
10409 Equivalent to @samp{-march=mips3}.
10413 Equivalent to @samp{-march=mips4}.
10417 Equivalent to @samp{-march=mips32}.
10421 Equivalent to @samp{-march=mips32r2}.
10425 Equivalent to @samp{-march=mips64}.
10430 @opindex mno-mips16
10431 Generate (do not generate) MIPS16 code. If GCC is targetting a
10432 MIPS32 or MIPS64 architecture, it will make use of the MIPS16e ASE@.
10444 Generate code for the given ABI@.
10446 Note that the EABI has a 32-bit and a 64-bit variant. GCC normally
10447 generates 64-bit code when you select a 64-bit architecture, but you
10448 can use @option{-mgp32} to get 32-bit code instead.
10450 For information about the O64 ABI, see
10451 @w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
10454 @itemx -mno-abicalls
10456 @opindex mno-abicalls
10457 Generate (do not generate) code that is suitable for SVR4-style
10458 dynamic objects. @option{-mabicalls} is the default for SVR4-based
10463 Generate (do not generate) code that is fully position-independent,
10464 and that can therefore be linked into shared libraries. This option
10465 only affects @option{-mabicalls}.
10467 All @option{-mabicalls} code has traditionally been position-independent,
10468 regardless of options like @option{-fPIC} and @option{-fpic}. However,
10469 as an extension, the GNU toolchain allows executables to use absolute
10470 accesses for locally-binding symbols. It can also use shorter GP
10471 initialization sequences and generate direct calls to locally-defined
10472 functions. This mode is selected by @option{-mno-shared}.
10474 @option{-mno-shared} depends on binutils 2.16 or higher and generates
10475 objects that can only be linked by the GNU linker. However, the option
10476 does not affect the ABI of the final executable; it only affects the ABI
10477 of relocatable objects. Using @option{-mno-shared} will generally make
10478 executables both smaller and quicker.
10480 @option{-mshared} is the default.
10486 Lift (do not lift) the usual restrictions on the size of the global
10489 GCC normally uses a single instruction to load values from the GOT@.
10490 While this is relatively efficient, it will only work if the GOT
10491 is smaller than about 64k. Anything larger will cause the linker
10492 to report an error such as:
10494 @cindex relocation truncated to fit (MIPS)
10496 relocation truncated to fit: R_MIPS_GOT16 foobar
10499 If this happens, you should recompile your code with @option{-mxgot}.
10500 It should then work with very large GOTs, although it will also be
10501 less efficient, since it will take three instructions to fetch the
10502 value of a global symbol.
10504 Note that some linkers can create multiple GOTs. If you have such a
10505 linker, you should only need to use @option{-mxgot} when a single object
10506 file accesses more than 64k's worth of GOT entries. Very few do.
10508 These options have no effect unless GCC is generating position
10513 Assume that general-purpose registers are 32 bits wide.
10517 Assume that general-purpose registers are 64 bits wide.
10521 Assume that floating-point registers are 32 bits wide.
10525 Assume that floating-point registers are 64 bits wide.
10528 @opindex mhard-float
10529 Use floating-point coprocessor instructions.
10532 @opindex msoft-float
10533 Do not use floating-point coprocessor instructions. Implement
10534 floating-point calculations using library calls instead.
10536 @item -msingle-float
10537 @opindex msingle-float
10538 Assume that the floating-point coprocessor only supports single-precision
10541 @itemx -mdouble-float
10542 @opindex mdouble-float
10543 Assume that the floating-point coprocessor supports double-precision
10544 operations. This is the default.
10550 Use (do not use) the MIPS DSP ASE. @xref{MIPS DSP Built-in Functions}.
10552 @itemx -mpaired-single
10553 @itemx -mno-paired-single
10554 @opindex mpaired-single
10555 @opindex mno-paired-single
10556 Use (do not use) paired-single floating-point instructions.
10557 @xref{MIPS Paired-Single Support}. This option can only be used
10558 when generating 64-bit code and requires hardware floating-point
10559 support to be enabled.
10564 @opindex mno-mips3d
10565 Use (do not use) the MIPS-3D ASE@. @xref{MIPS-3D Built-in Functions}.
10566 The option @option{-mips3d} implies @option{-mpaired-single}.
10570 Force @code{long} types to be 64 bits wide. See @option{-mlong32} for
10571 an explanation of the default and the way that the pointer size is
10576 Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
10578 The default size of @code{int}s, @code{long}s and pointers depends on
10579 the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI
10580 uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
10581 32-bit @code{long}s. Pointers are the same size as @code{long}s,
10582 or the same size as integer registers, whichever is smaller.
10588 Assume (do not assume) that all symbols have 32-bit values, regardless
10589 of the selected ABI@. This option is useful in combination with
10590 @option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
10591 to generate shorter and faster references to symbolic addresses.
10595 @cindex smaller data references (MIPS)
10596 @cindex gp-relative references (MIPS)
10597 Put global and static items less than or equal to @var{num} bytes into
10598 the small data or bss section instead of the normal data or bss section.
10599 This allows the data to be accessed using a single instruction.
10601 All modules should be compiled with the same @option{-G @var{num}}
10604 @item -membedded-data
10605 @itemx -mno-embedded-data
10606 @opindex membedded-data
10607 @opindex mno-embedded-data
10608 Allocate variables to the read-only data section first if possible, then
10609 next in the small data section if possible, otherwise in data. This gives
10610 slightly slower code than the default, but reduces the amount of RAM required
10611 when executing, and thus may be preferred for some embedded systems.
10613 @item -muninit-const-in-rodata
10614 @itemx -mno-uninit-const-in-rodata
10615 @opindex muninit-const-in-rodata
10616 @opindex mno-uninit-const-in-rodata
10617 Put uninitialized @code{const} variables in the read-only data section.
10618 This option is only meaningful in conjunction with @option{-membedded-data}.
10620 @item -msplit-addresses
10621 @itemx -mno-split-addresses
10622 @opindex msplit-addresses
10623 @opindex mno-split-addresses
10624 Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
10625 relocation operators. This option has been superseded by
10626 @option{-mexplicit-relocs} but is retained for backwards compatibility.
10628 @item -mexplicit-relocs
10629 @itemx -mno-explicit-relocs
10630 @opindex mexplicit-relocs
10631 @opindex mno-explicit-relocs
10632 Use (do not use) assembler relocation operators when dealing with symbolic
10633 addresses. The alternative, selected by @option{-mno-explicit-relocs},
10634 is to use assembler macros instead.
10636 @option{-mexplicit-relocs} is the default if GCC was configured
10637 to use an assembler that supports relocation operators.
10639 @item -mcheck-zero-division
10640 @itemx -mno-check-zero-division
10641 @opindex mcheck-zero-division
10642 @opindex mno-check-zero-division
10643 Trap (do not trap) on integer division by zero. The default is
10644 @option{-mcheck-zero-division}.
10646 @item -mdivide-traps
10647 @itemx -mdivide-breaks
10648 @opindex mdivide-traps
10649 @opindex mdivide-breaks
10650 MIPS systems check for division by zero by generating either a
10651 conditional trap or a break instruction. Using traps results in
10652 smaller code, but is only supported on MIPS II and later. Also, some
10653 versions of the Linux kernel have a bug that prevents trap from
10654 generating the proper signal (@code{SIGFPE}). Use @option{-mdivide-traps} to
10655 allow conditional traps on architectures that support them and
10656 @option{-mdivide-breaks} to force the use of breaks.
10658 The default is usually @option{-mdivide-traps}, but this can be
10659 overridden at configure time using @option{--with-divide=breaks}.
10660 Divide-by-zero checks can be completely disabled using
10661 @option{-mno-check-zero-division}.
10666 @opindex mno-memcpy
10667 Force (do not force) the use of @code{memcpy()} for non-trivial block
10668 moves. The default is @option{-mno-memcpy}, which allows GCC to inline
10669 most constant-sized copies.
10672 @itemx -mno-long-calls
10673 @opindex mlong-calls
10674 @opindex mno-long-calls
10675 Disable (do not disable) use of the @code{jal} instruction. Calling
10676 functions using @code{jal} is more efficient but requires the caller
10677 and callee to be in the same 256 megabyte segment.
10679 This option has no effect on abicalls code. The default is
10680 @option{-mno-long-calls}.
10686 Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
10687 instructions, as provided by the R4650 ISA@.
10690 @itemx -mno-fused-madd
10691 @opindex mfused-madd
10692 @opindex mno-fused-madd
10693 Enable (disable) use of the floating point multiply-accumulate
10694 instructions, when they are available. The default is
10695 @option{-mfused-madd}.
10697 When multiply-accumulate instructions are used, the intermediate
10698 product is calculated to infinite precision and is not subject to
10699 the FCSR Flush to Zero bit. This may be undesirable in some
10704 Tell the MIPS assembler to not run its preprocessor over user
10705 assembler files (with a @samp{.s} suffix) when assembling them.
10708 @itemx -mno-fix-r4000
10709 @opindex mfix-r4000
10710 @opindex mno-fix-r4000
10711 Work around certain R4000 CPU errata:
10714 A double-word or a variable shift may give an incorrect result if executed
10715 immediately after starting an integer division.
10717 A double-word or a variable shift may give an incorrect result if executed
10718 while an integer multiplication is in progress.
10720 An integer division may give an incorrect result if started in a delay slot
10721 of a taken branch or a jump.
10725 @itemx -mno-fix-r4400
10726 @opindex mfix-r4400
10727 @opindex mno-fix-r4400
10728 Work around certain R4400 CPU errata:
10731 A double-word or a variable shift may give an incorrect result if executed
10732 immediately after starting an integer division.
10736 @itemx -mno-fix-vr4120
10737 @opindex mfix-vr4120
10738 Work around certain VR4120 errata:
10741 @code{dmultu} does not always produce the correct result.
10743 @code{div} and @code{ddiv} do not always produce the correct result if one
10744 of the operands is negative.
10746 The workarounds for the division errata rely on special functions in
10747 @file{libgcc.a}. At present, these functions are only provided by
10748 the @code{mips64vr*-elf} configurations.
10750 Other VR4120 errata require a nop to be inserted between certain pairs of
10751 instructions. These errata are handled by the assembler, not by GCC itself.
10754 @opindex mfix-vr4130
10755 Work around the VR4130 @code{mflo}/@code{mfhi} errata. The
10756 workarounds are implemented by the assembler rather than by GCC,
10757 although GCC will avoid using @code{mflo} and @code{mfhi} if the
10758 VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
10759 instructions are available instead.
10762 @itemx -mno-fix-sb1
10764 Work around certain SB-1 CPU core errata.
10765 (This flag currently works around the SB-1 revision 2
10766 ``F1'' and ``F2'' floating point errata.)
10768 @item -mflush-func=@var{func}
10769 @itemx -mno-flush-func
10770 @opindex mflush-func
10771 Specifies the function to call to flush the I and D caches, or to not
10772 call any such function. If called, the function must take the same
10773 arguments as the common @code{_flush_func()}, that is, the address of the
10774 memory range for which the cache is being flushed, the size of the
10775 memory range, and the number 3 (to flush both caches). The default
10776 depends on the target GCC was configured for, but commonly is either
10777 @samp{_flush_func} or @samp{__cpu_flush}.
10779 @item -mbranch-likely
10780 @itemx -mno-branch-likely
10781 @opindex mbranch-likely
10782 @opindex mno-branch-likely
10783 Enable or disable use of Branch Likely instructions, regardless of the
10784 default for the selected architecture. By default, Branch Likely
10785 instructions may be generated if they are supported by the selected
10786 architecture. An exception is for the MIPS32 and MIPS64 architectures
10787 and processors which implement those architectures; for those, Branch
10788 Likely instructions will not be generated by default because the MIPS32
10789 and MIPS64 architectures specifically deprecate their use.
10791 @item -mfp-exceptions
10792 @itemx -mno-fp-exceptions
10793 @opindex mfp-exceptions
10794 Specifies whether FP exceptions are enabled. This affects how we schedule
10795 FP instructions for some processors. The default is that FP exceptions are
10798 For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
10799 64-bit code, then we can use both FP pipes. Otherwise, we can only use one
10802 @item -mvr4130-align
10803 @itemx -mno-vr4130-align
10804 @opindex mvr4130-align
10805 The VR4130 pipeline is two-way superscalar, but can only issue two
10806 instructions together if the first one is 8-byte aligned. When this
10807 option is enabled, GCC will align pairs of instructions that it
10808 thinks should execute in parallel.
10810 This option only has an effect when optimizing for the VR4130.
10811 It normally makes code faster, but at the expense of making it bigger.
10812 It is enabled by default at optimization level @option{-O3}.
10816 @subsection MMIX Options
10817 @cindex MMIX Options
10819 These options are defined for the MMIX:
10823 @itemx -mno-libfuncs
10825 @opindex mno-libfuncs
10826 Specify that intrinsic library functions are being compiled, passing all
10827 values in registers, no matter the size.
10830 @itemx -mno-epsilon
10832 @opindex mno-epsilon
10833 Generate floating-point comparison instructions that compare with respect
10834 to the @code{rE} epsilon register.
10836 @item -mabi=mmixware
10838 @opindex mabi-mmixware
10840 Generate code that passes function parameters and return values that (in
10841 the called function) are seen as registers @code{$0} and up, as opposed to
10842 the GNU ABI which uses global registers @code{$231} and up.
10844 @item -mzero-extend
10845 @itemx -mno-zero-extend
10846 @opindex mzero-extend
10847 @opindex mno-zero-extend
10848 When reading data from memory in sizes shorter than 64 bits, use (do not
10849 use) zero-extending load instructions by default, rather than
10850 sign-extending ones.
10853 @itemx -mno-knuthdiv
10855 @opindex mno-knuthdiv
10856 Make the result of a division yielding a remainder have the same sign as
10857 the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
10858 remainder follows the sign of the dividend. Both methods are
10859 arithmetically valid, the latter being almost exclusively used.
10861 @item -mtoplevel-symbols
10862 @itemx -mno-toplevel-symbols
10863 @opindex mtoplevel-symbols
10864 @opindex mno-toplevel-symbols
10865 Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
10866 code can be used with the @code{PREFIX} assembly directive.
10870 Generate an executable in the ELF format, rather than the default
10871 @samp{mmo} format used by the @command{mmix} simulator.
10873 @item -mbranch-predict
10874 @itemx -mno-branch-predict
10875 @opindex mbranch-predict
10876 @opindex mno-branch-predict
10877 Use (do not use) the probable-branch instructions, when static branch
10878 prediction indicates a probable branch.
10880 @item -mbase-addresses
10881 @itemx -mno-base-addresses
10882 @opindex mbase-addresses
10883 @opindex mno-base-addresses
10884 Generate (do not generate) code that uses @emph{base addresses}. Using a
10885 base address automatically generates a request (handled by the assembler
10886 and the linker) for a constant to be set up in a global register. The
10887 register is used for one or more base address requests within the range 0
10888 to 255 from the value held in the register. The generally leads to short
10889 and fast code, but the number of different data items that can be
10890 addressed is limited. This means that a program that uses lots of static
10891 data may require @option{-mno-base-addresses}.
10893 @item -msingle-exit
10894 @itemx -mno-single-exit
10895 @opindex msingle-exit
10896 @opindex mno-single-exit
10897 Force (do not force) generated code to have a single exit point in each
10901 @node MN10300 Options
10902 @subsection MN10300 Options
10903 @cindex MN10300 options
10905 These @option{-m} options are defined for Matsushita MN10300 architectures:
10910 Generate code to avoid bugs in the multiply instructions for the MN10300
10911 processors. This is the default.
10913 @item -mno-mult-bug
10914 @opindex mno-mult-bug
10915 Do not generate code to avoid bugs in the multiply instructions for the
10916 MN10300 processors.
10920 Generate code which uses features specific to the AM33 processor.
10924 Do not generate code which uses features specific to the AM33 processor. This
10927 @item -mreturn-pointer-on-d0
10928 @opindex mreturn-pointer-on-d0
10929 When generating a function which returns a pointer, return the pointer
10930 in both @code{a0} and @code{d0}. Otherwise, the pointer is returned
10931 only in a0, and attempts to call such functions without a prototype
10932 would result in errors. Note that this option is on by default; use
10933 @option{-mno-return-pointer-on-d0} to disable it.
10937 Do not link in the C run-time initialization object file.
10941 Indicate to the linker that it should perform a relaxation optimization pass
10942 to shorten branches, calls and absolute memory addresses. This option only
10943 has an effect when used on the command line for the final link step.
10945 This option makes symbolic debugging impossible.
10949 @subsection MT Options
10952 These @option{-m} options are defined for Morpho MT architectures:
10956 @item -march=@var{cpu-type}
10958 Generate code that will run on @var{cpu-type}, which is the name of a system
10959 representing a certain processor type. Possible values for
10960 @var{cpu-type} are @samp{ms1-64-001}, @samp{ms1-16-002},
10961 @samp{ms1-16-003} and @samp{ms2}.
10963 When this option is not used, the default is @option{-march=ms1-16-002}.
10967 Use byte loads and stores when generating code.
10971 Do not use byte loads and stores when generating code.
10975 Use simulator runtime
10979 Do not link in the C run-time initialization object file
10980 @file{crti.o}. Other run-time initialization and termination files
10981 such as @file{startup.o} and @file{exit.o} are still included on the
10982 linker command line.
10986 @node PDP-11 Options
10987 @subsection PDP-11 Options
10988 @cindex PDP-11 Options
10990 These options are defined for the PDP-11:
10995 Use hardware FPP floating point. This is the default. (FIS floating
10996 point on the PDP-11/40 is not supported.)
10999 @opindex msoft-float
11000 Do not use hardware floating point.
11004 Return floating-point results in ac0 (fr0 in Unix assembler syntax).
11008 Return floating-point results in memory. This is the default.
11012 Generate code for a PDP-11/40.
11016 Generate code for a PDP-11/45. This is the default.
11020 Generate code for a PDP-11/10.
11022 @item -mbcopy-builtin
11023 @opindex bcopy-builtin
11024 Use inline @code{movmemhi} patterns for copying memory. This is the
11029 Do not use inline @code{movmemhi} patterns for copying memory.
11035 Use 16-bit @code{int}. This is the default.
11041 Use 32-bit @code{int}.
11044 @itemx -mno-float32
11046 @opindex mno-float32
11047 Use 64-bit @code{float}. This is the default.
11050 @itemx -mno-float64
11052 @opindex mno-float64
11053 Use 32-bit @code{float}.
11057 Use @code{abshi2} pattern. This is the default.
11061 Do not use @code{abshi2} pattern.
11063 @item -mbranch-expensive
11064 @opindex mbranch-expensive
11065 Pretend that branches are expensive. This is for experimenting with
11066 code generation only.
11068 @item -mbranch-cheap
11069 @opindex mbranch-cheap
11070 Do not pretend that branches are expensive. This is the default.
11074 Generate code for a system with split I&D@.
11078 Generate code for a system without split I&D@. This is the default.
11082 Use Unix assembler syntax. This is the default when configured for
11083 @samp{pdp11-*-bsd}.
11087 Use DEC assembler syntax. This is the default when configured for any
11088 PDP-11 target other than @samp{pdp11-*-bsd}.
11091 @node PowerPC Options
11092 @subsection PowerPC Options
11093 @cindex PowerPC options
11095 These are listed under @xref{RS/6000 and PowerPC Options}.
11097 @node RS/6000 and PowerPC Options
11098 @subsection IBM RS/6000 and PowerPC Options
11099 @cindex RS/6000 and PowerPC Options
11100 @cindex IBM RS/6000 and PowerPC Options
11102 These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
11109 @itemx -mno-powerpc
11110 @itemx -mpowerpc-gpopt
11111 @itemx -mno-powerpc-gpopt
11112 @itemx -mpowerpc-gfxopt
11113 @itemx -mno-powerpc-gfxopt
11115 @itemx -mno-powerpc64
11119 @itemx -mno-popcntb
11125 @opindex mno-power2
11127 @opindex mno-powerpc
11128 @opindex mpowerpc-gpopt
11129 @opindex mno-powerpc-gpopt
11130 @opindex mpowerpc-gfxopt
11131 @opindex mno-powerpc-gfxopt
11132 @opindex mpowerpc64
11133 @opindex mno-powerpc64
11137 @opindex mno-popcntb
11140 GCC supports two related instruction set architectures for the
11141 RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those
11142 instructions supported by the @samp{rios} chip set used in the original
11143 RS/6000 systems and the @dfn{PowerPC} instruction set is the
11144 architecture of the Freescale MPC5xx, MPC6xx, MPC8xx microprocessors, and
11145 the IBM 4xx, 6xx, and follow-on microprocessors.
11147 Neither architecture is a subset of the other. However there is a
11148 large common subset of instructions supported by both. An MQ
11149 register is included in processors supporting the POWER architecture.
11151 You use these options to specify which instructions are available on the
11152 processor you are using. The default value of these options is
11153 determined when configuring GCC@. Specifying the
11154 @option{-mcpu=@var{cpu_type}} overrides the specification of these
11155 options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
11156 rather than the options listed above.
11158 The @option{-mpower} option allows GCC to generate instructions that
11159 are found only in the POWER architecture and to use the MQ register.
11160 Specifying @option{-mpower2} implies @option{-power} and also allows GCC
11161 to generate instructions that are present in the POWER2 architecture but
11162 not the original POWER architecture.
11164 The @option{-mpowerpc} option allows GCC to generate instructions that
11165 are found only in the 32-bit subset of the PowerPC architecture.
11166 Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
11167 GCC to use the optional PowerPC architecture instructions in the
11168 General Purpose group, including floating-point square root. Specifying
11169 @option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
11170 use the optional PowerPC architecture instructions in the Graphics
11171 group, including floating-point select.
11173 The @option{-mmfcrf} option allows GCC to generate the move from
11174 condition register field instruction implemented on the POWER4
11175 processor and other processors that support the PowerPC V2.01
11177 The @option{-mpopcntb} option allows GCC to generate the popcount and
11178 double precision FP reciprocal estimate instruction implemented on the
11179 POWER5 processor and other processors that support the PowerPC V2.02
11181 The @option{-mfprnd} option allows GCC to generate the FP round to
11182 integer instructions implemented on the POWER5+ processor and other
11183 processors that support the PowerPC V2.03 architecture.
11185 The @option{-mpowerpc64} option allows GCC to generate the additional
11186 64-bit instructions that are found in the full PowerPC64 architecture
11187 and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
11188 @option{-mno-powerpc64}.
11190 If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
11191 will use only the instructions in the common subset of both
11192 architectures plus some special AIX common-mode calls, and will not use
11193 the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
11194 permits GCC to use any instruction from either architecture and to
11195 allow use of the MQ register; specify this for the Motorola MPC601.
11197 @item -mnew-mnemonics
11198 @itemx -mold-mnemonics
11199 @opindex mnew-mnemonics
11200 @opindex mold-mnemonics
11201 Select which mnemonics to use in the generated assembler code. With
11202 @option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
11203 the PowerPC architecture. With @option{-mold-mnemonics} it uses the
11204 assembler mnemonics defined for the POWER architecture. Instructions
11205 defined in only one architecture have only one mnemonic; GCC uses that
11206 mnemonic irrespective of which of these options is specified.
11208 GCC defaults to the mnemonics appropriate for the architecture in
11209 use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
11210 value of these option. Unless you are building a cross-compiler, you
11211 should normally not specify either @option{-mnew-mnemonics} or
11212 @option{-mold-mnemonics}, but should instead accept the default.
11214 @item -mcpu=@var{cpu_type}
11216 Set architecture type, register usage, choice of mnemonics, and
11217 instruction scheduling parameters for machine type @var{cpu_type}.
11218 Supported values for @var{cpu_type} are @samp{401}, @samp{403},
11219 @samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{505},
11220 @samp{601}, @samp{602}, @samp{603}, @samp{603e}, @samp{604},
11221 @samp{604e}, @samp{620}, @samp{630}, @samp{740}, @samp{7400},
11222 @samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
11223 @samp{860}, @samp{970}, @samp{8540}, @samp{ec603e}, @samp{G3},
11224 @samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3},
11225 @samp{power4}, @samp{power5}, @samp{power5+}, @samp{power6},
11226 @samp{common}, @samp{powerpc}, @samp{powerpc64},
11227 @samp{rios}, @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64}.
11229 @option{-mcpu=common} selects a completely generic processor. Code
11230 generated under this option will run on any POWER or PowerPC processor.
11231 GCC will use only the instructions in the common subset of both
11232 architectures, and will not use the MQ register. GCC assumes a generic
11233 processor model for scheduling purposes.
11235 @option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
11236 @option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
11237 PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
11238 types, with an appropriate, generic processor model assumed for
11239 scheduling purposes.
11241 The other options specify a specific processor. Code generated under
11242 those options will run best on that processor, and may not run at all on
11245 The @option{-mcpu} options automatically enable or disable the
11246 following options: @option{-maltivec}, @option{-mfprnd},
11247 @option{-mhard-float}, @option{-mmfcrf}, @option{-mmultiple},
11248 @option{-mnew-mnemonics}, @option{-mpopcntb}, @option{-mpower},
11249 @option{-mpower2}, @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
11250 @option{-mpowerpc-gfxopt}, @option{-mstring}, @option{-mmulhw}, @option{-mdlmzb}.
11251 The particular options
11252 set for any particular CPU will vary between compiler versions,
11253 depending on what setting seems to produce optimal code for that CPU;
11254 it doesn't necessarily reflect the actual hardware's capabilities. If
11255 you wish to set an individual option to a particular value, you may
11256 specify it after the @option{-mcpu} option, like @samp{-mcpu=970
11259 On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
11260 not enabled or disabled by the @option{-mcpu} option at present because
11261 AIX does not have full support for these options. You may still
11262 enable or disable them individually if you're sure it'll work in your
11265 @item -mtune=@var{cpu_type}
11267 Set the instruction scheduling parameters for machine type
11268 @var{cpu_type}, but do not set the architecture type, register usage, or
11269 choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
11270 values for @var{cpu_type} are used for @option{-mtune} as for
11271 @option{-mcpu}. If both are specified, the code generated will use the
11272 architecture, registers, and mnemonics set by @option{-mcpu}, but the
11273 scheduling parameters set by @option{-mtune}.
11279 Generate code to compute division as reciprocal estimate and iterative
11280 refinement, creating opportunities for increased throughput. This
11281 feature requires: optional PowerPC Graphics instruction set for single
11282 precision and FRE instruction for double precision, assuming divides
11283 cannot generate user-visible traps, and the domain values not include
11284 Infinities, denormals or zero denominator.
11287 @itemx -mno-altivec
11289 @opindex mno-altivec
11290 Generate code that uses (does not use) AltiVec instructions, and also
11291 enable the use of built-in functions that allow more direct access to
11292 the AltiVec instruction set. You may also need to set
11293 @option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
11299 @opindex mno-vrsave
11300 Generate VRSAVE instructions when generating AltiVec code.
11303 @opindex msecure-plt
11304 Generate code that allows ld and ld.so to build executables and shared
11305 libraries with non-exec .plt and .got sections. This is a PowerPC
11306 32-bit SYSV ABI option.
11310 Generate code that uses a BSS .plt section that ld.so fills in, and
11311 requires .plt and .got sections that are both writable and executable.
11312 This is a PowerPC 32-bit SYSV ABI option.
11318 This switch enables or disables the generation of ISEL instructions.
11320 @item -misel=@var{yes/no}
11321 This switch has been deprecated. Use @option{-misel} and
11322 @option{-mno-isel} instead.
11328 This switch enables or disables the generation of SPE simd
11331 @item -mspe=@var{yes/no}
11332 This option has been deprecated. Use @option{-mspe} and
11333 @option{-mno-spe} instead.
11335 @item -mfloat-gprs=@var{yes/single/double/no}
11336 @itemx -mfloat-gprs
11337 @opindex mfloat-gprs
11338 This switch enables or disables the generation of floating point
11339 operations on the general purpose registers for architectures that
11342 The argument @var{yes} or @var{single} enables the use of
11343 single-precision floating point operations.
11345 The argument @var{double} enables the use of single and
11346 double-precision floating point operations.
11348 The argument @var{no} disables floating point operations on the
11349 general purpose registers.
11351 This option is currently only available on the MPC854x.
11357 Generate code for 32-bit or 64-bit environments of Darwin and SVR4
11358 targets (including GNU/Linux). The 32-bit environment sets int, long
11359 and pointer to 32 bits and generates code that runs on any PowerPC
11360 variant. The 64-bit environment sets int to 32 bits and long and
11361 pointer to 64 bits, and generates code for PowerPC64, as for
11362 @option{-mpowerpc64}.
11365 @itemx -mno-fp-in-toc
11366 @itemx -mno-sum-in-toc
11367 @itemx -mminimal-toc
11369 @opindex mno-fp-in-toc
11370 @opindex mno-sum-in-toc
11371 @opindex mminimal-toc
11372 Modify generation of the TOC (Table Of Contents), which is created for
11373 every executable file. The @option{-mfull-toc} option is selected by
11374 default. In that case, GCC will allocate at least one TOC entry for
11375 each unique non-automatic variable reference in your program. GCC
11376 will also place floating-point constants in the TOC@. However, only
11377 16,384 entries are available in the TOC@.
11379 If you receive a linker error message that saying you have overflowed
11380 the available TOC space, you can reduce the amount of TOC space used
11381 with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
11382 @option{-mno-fp-in-toc} prevents GCC from putting floating-point
11383 constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
11384 generate code to calculate the sum of an address and a constant at
11385 run-time instead of putting that sum into the TOC@. You may specify one
11386 or both of these options. Each causes GCC to produce very slightly
11387 slower and larger code at the expense of conserving TOC space.
11389 If you still run out of space in the TOC even when you specify both of
11390 these options, specify @option{-mminimal-toc} instead. This option causes
11391 GCC to make only one TOC entry for every file. When you specify this
11392 option, GCC will produce code that is slower and larger but which
11393 uses extremely little TOC space. You may wish to use this option
11394 only on files that contain less frequently executed code.
11400 Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
11401 @code{long} type, and the infrastructure needed to support them.
11402 Specifying @option{-maix64} implies @option{-mpowerpc64} and
11403 @option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
11404 implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
11407 @itemx -mno-xl-compat
11408 @opindex mxl-compat
11409 @opindex mno-xl-compat
11410 Produce code that conforms more closely to IBM XL compiler semantics
11411 when using AIX-compatible ABI. Pass floating-point arguments to
11412 prototyped functions beyond the register save area (RSA) on the stack
11413 in addition to argument FPRs. Do not assume that most significant
11414 double in 128-bit long double value is properly rounded when comparing
11415 values and converting to double. Use XL symbol names for long double
11418 The AIX calling convention was extended but not initially documented to
11419 handle an obscure K&R C case of calling a function that takes the
11420 address of its arguments with fewer arguments than declared. IBM XL
11421 compilers access floating point arguments which do not fit in the
11422 RSA from the stack when a subroutine is compiled without
11423 optimization. Because always storing floating-point arguments on the
11424 stack is inefficient and rarely needed, this option is not enabled by
11425 default and only is necessary when calling subroutines compiled by IBM
11426 XL compilers without optimization.
11430 Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
11431 application written to use message passing with special startup code to
11432 enable the application to run. The system must have PE installed in the
11433 standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
11434 must be overridden with the @option{-specs=} option to specify the
11435 appropriate directory location. The Parallel Environment does not
11436 support threads, so the @option{-mpe} option and the @option{-pthread}
11437 option are incompatible.
11439 @item -malign-natural
11440 @itemx -malign-power
11441 @opindex malign-natural
11442 @opindex malign-power
11443 On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
11444 @option{-malign-natural} overrides the ABI-defined alignment of larger
11445 types, such as floating-point doubles, on their natural size-based boundary.
11446 The option @option{-malign-power} instructs GCC to follow the ABI-specified
11447 alignment rules. GCC defaults to the standard alignment defined in the ABI@.
11449 On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
11453 @itemx -mhard-float
11454 @opindex msoft-float
11455 @opindex mhard-float
11456 Generate code that does not use (uses) the floating-point register set.
11457 Software floating point emulation is provided if you use the
11458 @option{-msoft-float} option, and pass the option to GCC when linking.
11461 @itemx -mno-multiple
11463 @opindex mno-multiple
11464 Generate code that uses (does not use) the load multiple word
11465 instructions and the store multiple word instructions. These
11466 instructions are generated by default on POWER systems, and not
11467 generated on PowerPC systems. Do not use @option{-mmultiple} on little
11468 endian PowerPC systems, since those instructions do not work when the
11469 processor is in little endian mode. The exceptions are PPC740 and
11470 PPC750 which permit the instructions usage in little endian mode.
11475 @opindex mno-string
11476 Generate code that uses (does not use) the load string instructions
11477 and the store string word instructions to save multiple registers and
11478 do small block moves. These instructions are generated by default on
11479 POWER systems, and not generated on PowerPC systems. Do not use
11480 @option{-mstring} on little endian PowerPC systems, since those
11481 instructions do not work when the processor is in little endian mode.
11482 The exceptions are PPC740 and PPC750 which permit the instructions
11483 usage in little endian mode.
11488 @opindex mno-update
11489 Generate code that uses (does not use) the load or store instructions
11490 that update the base register to the address of the calculated memory
11491 location. These instructions are generated by default. If you use
11492 @option{-mno-update}, there is a small window between the time that the
11493 stack pointer is updated and the address of the previous frame is
11494 stored, which means code that walks the stack frame across interrupts or
11495 signals may get corrupted data.
11498 @itemx -mno-fused-madd
11499 @opindex mfused-madd
11500 @opindex mno-fused-madd
11501 Generate code that uses (does not use) the floating point multiply and
11502 accumulate instructions. These instructions are generated by default if
11503 hardware floating is used.
11509 Generate code that uses (does not use) the half-word multiply and
11510 multiply-accumulate instructions on the IBM 405 and 440 processors.
11511 These instructions are generated by default when targetting those
11518 Generate code that uses (does not use) the string-search @samp{dlmzb}
11519 instruction on the IBM 405 and 440 processors. This instruction is
11520 generated by default when targetting those processors.
11522 @item -mno-bit-align
11524 @opindex mno-bit-align
11525 @opindex mbit-align
11526 On System V.4 and embedded PowerPC systems do not (do) force structures
11527 and unions that contain bit-fields to be aligned to the base type of the
11530 For example, by default a structure containing nothing but 8
11531 @code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
11532 boundary and have a size of 4 bytes. By using @option{-mno-bit-align},
11533 the structure would be aligned to a 1 byte boundary and be one byte in
11536 @item -mno-strict-align
11537 @itemx -mstrict-align
11538 @opindex mno-strict-align
11539 @opindex mstrict-align
11540 On System V.4 and embedded PowerPC systems do not (do) assume that
11541 unaligned memory references will be handled by the system.
11543 @item -mrelocatable
11544 @itemx -mno-relocatable
11545 @opindex mrelocatable
11546 @opindex mno-relocatable
11547 On embedded PowerPC systems generate code that allows (does not allow)
11548 the program to be relocated to a different address at runtime. If you
11549 use @option{-mrelocatable} on any module, all objects linked together must
11550 be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
11552 @item -mrelocatable-lib
11553 @itemx -mno-relocatable-lib
11554 @opindex mrelocatable-lib
11555 @opindex mno-relocatable-lib
11556 On embedded PowerPC systems generate code that allows (does not allow)
11557 the program to be relocated to a different address at runtime. Modules
11558 compiled with @option{-mrelocatable-lib} can be linked with either modules
11559 compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
11560 with modules compiled with the @option{-mrelocatable} options.
11566 On System V.4 and embedded PowerPC systems do not (do) assume that
11567 register 2 contains a pointer to a global area pointing to the addresses
11568 used in the program.
11571 @itemx -mlittle-endian
11573 @opindex mlittle-endian
11574 On System V.4 and embedded PowerPC systems compile code for the
11575 processor in little endian mode. The @option{-mlittle-endian} option is
11576 the same as @option{-mlittle}.
11579 @itemx -mbig-endian
11581 @opindex mbig-endian
11582 On System V.4 and embedded PowerPC systems compile code for the
11583 processor in big endian mode. The @option{-mbig-endian} option is
11584 the same as @option{-mbig}.
11586 @item -mdynamic-no-pic
11587 @opindex mdynamic-no-pic
11588 On Darwin and Mac OS X systems, compile code so that it is not
11589 relocatable, but that its external references are relocatable. The
11590 resulting code is suitable for applications, but not shared
11593 @item -mprioritize-restricted-insns=@var{priority}
11594 @opindex mprioritize-restricted-insns
11595 This option controls the priority that is assigned to
11596 dispatch-slot restricted instructions during the second scheduling
11597 pass. The argument @var{priority} takes the value @var{0/1/2} to assign
11598 @var{no/highest/second-highest} priority to dispatch slot restricted
11601 @item -msched-costly-dep=@var{dependence_type}
11602 @opindex msched-costly-dep
11603 This option controls which dependences are considered costly
11604 by the target during instruction scheduling. The argument
11605 @var{dependence_type} takes one of the following values:
11606 @var{no}: no dependence is costly,
11607 @var{all}: all dependences are costly,
11608 @var{true_store_to_load}: a true dependence from store to load is costly,
11609 @var{store_to_load}: any dependence from store to load is costly,
11610 @var{number}: any dependence which latency >= @var{number} is costly.
11612 @item -minsert-sched-nops=@var{scheme}
11613 @opindex minsert-sched-nops
11614 This option controls which nop insertion scheme will be used during
11615 the second scheduling pass. The argument @var{scheme} takes one of the
11617 @var{no}: Don't insert nops.
11618 @var{pad}: Pad with nops any dispatch group which has vacant issue slots,
11619 according to the scheduler's grouping.
11620 @var{regroup_exact}: Insert nops to force costly dependent insns into
11621 separate groups. Insert exactly as many nops as needed to force an insn
11622 to a new group, according to the estimated processor grouping.
11623 @var{number}: Insert nops to force costly dependent insns into
11624 separate groups. Insert @var{number} nops to force an insn to a new group.
11627 @opindex mcall-sysv
11628 On System V.4 and embedded PowerPC systems compile code using calling
11629 conventions that adheres to the March 1995 draft of the System V
11630 Application Binary Interface, PowerPC processor supplement. This is the
11631 default unless you configured GCC using @samp{powerpc-*-eabiaix}.
11633 @item -mcall-sysv-eabi
11634 @opindex mcall-sysv-eabi
11635 Specify both @option{-mcall-sysv} and @option{-meabi} options.
11637 @item -mcall-sysv-noeabi
11638 @opindex mcall-sysv-noeabi
11639 Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
11641 @item -mcall-solaris
11642 @opindex mcall-solaris
11643 On System V.4 and embedded PowerPC systems compile code for the Solaris
11647 @opindex mcall-linux
11648 On System V.4 and embedded PowerPC systems compile code for the
11649 Linux-based GNU system.
11653 On System V.4 and embedded PowerPC systems compile code for the
11654 Hurd-based GNU system.
11656 @item -mcall-netbsd
11657 @opindex mcall-netbsd
11658 On System V.4 and embedded PowerPC systems compile code for the
11659 NetBSD operating system.
11661 @item -maix-struct-return
11662 @opindex maix-struct-return
11663 Return all structures in memory (as specified by the AIX ABI)@.
11665 @item -msvr4-struct-return
11666 @opindex msvr4-struct-return
11667 Return structures smaller than 8 bytes in registers (as specified by the
11670 @item -mabi=@var{abi-type}
11672 Extend the current ABI with a particular extension, or remove such extension.
11673 Valid values are @var{altivec}, @var{no-altivec}, @var{spe},
11674 @var{no-spe}, @var{ibmlongdouble}, @var{ieeelongdouble}@.
11678 Extend the current ABI with SPE ABI extensions. This does not change
11679 the default ABI, instead it adds the SPE ABI extensions to the current
11683 @opindex mabi=no-spe
11684 Disable Booke SPE ABI extensions for the current ABI@.
11686 @item -mabi=ibmlongdouble
11687 @opindex mabi=ibmlongdouble
11688 Change the current ABI to use IBM extended precision long double.
11689 This is a PowerPC 32-bit SYSV ABI option.
11691 @item -mabi=ieeelongdouble
11692 @opindex mabi=ieeelongdouble
11693 Change the current ABI to use IEEE extended precision long double.
11694 This is a PowerPC 32-bit Linux ABI option.
11697 @itemx -mno-prototype
11698 @opindex mprototype
11699 @opindex mno-prototype
11700 On System V.4 and embedded PowerPC systems assume that all calls to
11701 variable argument functions are properly prototyped. Otherwise, the
11702 compiler must insert an instruction before every non prototyped call to
11703 set or clear bit 6 of the condition code register (@var{CR}) to
11704 indicate whether floating point values were passed in the floating point
11705 registers in case the function takes a variable arguments. With
11706 @option{-mprototype}, only calls to prototyped variable argument functions
11707 will set or clear the bit.
11711 On embedded PowerPC systems, assume that the startup module is called
11712 @file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
11713 @file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
11718 On embedded PowerPC systems, assume that the startup module is called
11719 @file{crt0.o} and the standard C libraries are @file{libmvme.a} and
11724 On embedded PowerPC systems, assume that the startup module is called
11725 @file{crt0.o} and the standard C libraries are @file{libads.a} and
11728 @item -myellowknife
11729 @opindex myellowknife
11730 On embedded PowerPC systems, assume that the startup module is called
11731 @file{crt0.o} and the standard C libraries are @file{libyk.a} and
11736 On System V.4 and embedded PowerPC systems, specify that you are
11737 compiling for a VxWorks system.
11741 Specify that you are compiling for the WindISS simulation environment.
11745 On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
11746 header to indicate that @samp{eabi} extended relocations are used.
11752 On System V.4 and embedded PowerPC systems do (do not) adhere to the
11753 Embedded Applications Binary Interface (eabi) which is a set of
11754 modifications to the System V.4 specifications. Selecting @option{-meabi}
11755 means that the stack is aligned to an 8 byte boundary, a function
11756 @code{__eabi} is called to from @code{main} to set up the eabi
11757 environment, and the @option{-msdata} option can use both @code{r2} and
11758 @code{r13} to point to two separate small data areas. Selecting
11759 @option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
11760 do not call an initialization function from @code{main}, and the
11761 @option{-msdata} option will only use @code{r13} to point to a single
11762 small data area. The @option{-meabi} option is on by default if you
11763 configured GCC using one of the @samp{powerpc*-*-eabi*} options.
11766 @opindex msdata=eabi
11767 On System V.4 and embedded PowerPC systems, put small initialized
11768 @code{const} global and static data in the @samp{.sdata2} section, which
11769 is pointed to by register @code{r2}. Put small initialized
11770 non-@code{const} global and static data in the @samp{.sdata} section,
11771 which is pointed to by register @code{r13}. Put small uninitialized
11772 global and static data in the @samp{.sbss} section, which is adjacent to
11773 the @samp{.sdata} section. The @option{-msdata=eabi} option is
11774 incompatible with the @option{-mrelocatable} option. The
11775 @option{-msdata=eabi} option also sets the @option{-memb} option.
11778 @opindex msdata=sysv
11779 On System V.4 and embedded PowerPC systems, put small global and static
11780 data in the @samp{.sdata} section, which is pointed to by register
11781 @code{r13}. Put small uninitialized global and static data in the
11782 @samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
11783 The @option{-msdata=sysv} option is incompatible with the
11784 @option{-mrelocatable} option.
11786 @item -msdata=default
11788 @opindex msdata=default
11790 On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
11791 compile code the same as @option{-msdata=eabi}, otherwise compile code the
11792 same as @option{-msdata=sysv}.
11795 @opindex msdata-data
11796 On System V.4 and embedded PowerPC systems, put small global
11797 data in the @samp{.sdata} section. Put small uninitialized global
11798 data in the @samp{.sbss} section. Do not use register @code{r13}
11799 to address small data however. This is the default behavior unless
11800 other @option{-msdata} options are used.
11804 @opindex msdata=none
11806 On embedded PowerPC systems, put all initialized global and static data
11807 in the @samp{.data} section, and all uninitialized data in the
11808 @samp{.bss} section.
11812 @cindex smaller data references (PowerPC)
11813 @cindex .sdata/.sdata2 references (PowerPC)
11814 On embedded PowerPC systems, put global and static items less than or
11815 equal to @var{num} bytes into the small data or bss sections instead of
11816 the normal data or bss section. By default, @var{num} is 8. The
11817 @option{-G @var{num}} switch is also passed to the linker.
11818 All modules should be compiled with the same @option{-G @var{num}} value.
11821 @itemx -mno-regnames
11823 @opindex mno-regnames
11824 On System V.4 and embedded PowerPC systems do (do not) emit register
11825 names in the assembly language output using symbolic forms.
11828 @itemx -mno-longcall
11830 @opindex mno-longcall
11831 By default assume that all calls are far away so that a longer more
11832 expensive calling sequence is required. This is required for calls
11833 further than 32 megabytes (33,554,432 bytes) from the current location.
11834 A short call will be generated if the compiler knows
11835 the call cannot be that far away. This setting can be overridden by
11836 the @code{shortcall} function attribute, or by @code{#pragma
11839 Some linkers are capable of detecting out-of-range calls and generating
11840 glue code on the fly. On these systems, long calls are unnecessary and
11841 generate slower code. As of this writing, the AIX linker can do this,
11842 as can the GNU linker for PowerPC/64. It is planned to add this feature
11843 to the GNU linker for 32-bit PowerPC systems as well.
11845 On Darwin/PPC systems, @code{#pragma longcall} will generate ``jbsr
11846 callee, L42'', plus a ``branch island'' (glue code). The two target
11847 addresses represent the callee and the ``branch island''. The
11848 Darwin/PPC linker will prefer the first address and generate a ``bl
11849 callee'' if the PPC ``bl'' instruction will reach the callee directly;
11850 otherwise, the linker will generate ``bl L42'' to call the ``branch
11851 island''. The ``branch island'' is appended to the body of the
11852 calling function; it computes the full 32-bit address of the callee
11855 On Mach-O (Darwin) systems, this option directs the compiler emit to
11856 the glue for every direct call, and the Darwin linker decides whether
11857 to use or discard it.
11859 In the future, we may cause GCC to ignore all longcall specifications
11860 when the linker is known to generate glue.
11864 Adds support for multithreading with the @dfn{pthreads} library.
11865 This option sets flags for both the preprocessor and linker.
11869 @node S/390 and zSeries Options
11870 @subsection S/390 and zSeries Options
11871 @cindex S/390 and zSeries Options
11873 These are the @samp{-m} options defined for the S/390 and zSeries architecture.
11877 @itemx -msoft-float
11878 @opindex mhard-float
11879 @opindex msoft-float
11880 Use (do not use) the hardware floating-point instructions and registers
11881 for floating-point operations. When @option{-msoft-float} is specified,
11882 functions in @file{libgcc.a} will be used to perform floating-point
11883 operations. When @option{-mhard-float} is specified, the compiler
11884 generates IEEE floating-point instructions. This is the default.
11886 @item -mlong-double-64
11887 @itemx -mlong-double-128
11888 @opindex mlong-double-64
11889 @opindex mlong-double-128
11890 These switches control the size of @code{long double} type. A size
11891 of 64bit makes the @code{long double} type equivalent to the @code{double}
11892 type. This is the default.
11895 @itemx -mno-backchain
11896 @opindex mbackchain
11897 @opindex mno-backchain
11898 Store (do not store) the address of the caller's frame as backchain pointer
11899 into the callee's stack frame.
11900 A backchain may be needed to allow debugging using tools that do not understand
11901 DWARF-2 call frame information.
11902 When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
11903 at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
11904 the backchain is placed into the topmost word of the 96/160 byte register
11907 In general, code compiled with @option{-mbackchain} is call-compatible with
11908 code compiled with @option{-mmo-backchain}; however, use of the backchain
11909 for debugging purposes usually requires that the whole binary is built with
11910 @option{-mbackchain}. Note that the combination of @option{-mbackchain},
11911 @option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
11912 to build a linux kernel use @option{-msoft-float}.
11914 The default is to not maintain the backchain.
11916 @item -mpacked-stack
11917 @item -mno-packed-stack
11918 @opindex mpacked-stack
11919 @opindex mno-packed-stack
11920 Use (do not use) the packed stack layout. When @option{-mno-packed-stack} is
11921 specified, the compiler uses the all fields of the 96/160 byte register save
11922 area only for their default purpose; unused fields still take up stack space.
11923 When @option{-mpacked-stack} is specified, register save slots are densely
11924 packed at the top of the register save area; unused space is reused for other
11925 purposes, allowing for more efficient use of the available stack space.
11926 However, when @option{-mbackchain} is also in effect, the topmost word of
11927 the save area is always used to store the backchain, and the return address
11928 register is always saved two words below the backchain.
11930 As long as the stack frame backchain is not used, code generated with
11931 @option{-mpacked-stack} is call-compatible with code generated with
11932 @option{-mno-packed-stack}. Note that some non-FSF releases of GCC 2.95 for
11933 S/390 or zSeries generated code that uses the stack frame backchain at run
11934 time, not just for debugging purposes. Such code is not call-compatible
11935 with code compiled with @option{-mpacked-stack}. Also, note that the
11936 combination of @option{-mbackchain},
11937 @option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
11938 to build a linux kernel use @option{-msoft-float}.
11940 The default is to not use the packed stack layout.
11943 @itemx -mno-small-exec
11944 @opindex msmall-exec
11945 @opindex mno-small-exec
11946 Generate (or do not generate) code using the @code{bras} instruction
11947 to do subroutine calls.
11948 This only works reliably if the total executable size does not
11949 exceed 64k. The default is to use the @code{basr} instruction instead,
11950 which does not have this limitation.
11956 When @option{-m31} is specified, generate code compliant to the
11957 GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate
11958 code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in
11959 particular to generate 64-bit instructions. For the @samp{s390}
11960 targets, the default is @option{-m31}, while the @samp{s390x}
11961 targets default to @option{-m64}.
11967 When @option{-mzarch} is specified, generate code using the
11968 instructions available on z/Architecture.
11969 When @option{-mesa} is specified, generate code using the
11970 instructions available on ESA/390. Note that @option{-mesa} is
11971 not possible with @option{-m64}.
11972 When generating code compliant to the GNU/Linux for S/390 ABI,
11973 the default is @option{-mesa}. When generating code compliant
11974 to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
11980 Generate (or do not generate) code using the @code{mvcle} instruction
11981 to perform block moves. When @option{-mno-mvcle} is specified,
11982 use a @code{mvc} loop instead. This is the default unless optimizing for
11989 Print (or do not print) additional debug information when compiling.
11990 The default is to not print debug information.
11992 @item -march=@var{cpu-type}
11994 Generate code that will run on @var{cpu-type}, which is the name of a system
11995 representing a certain processor type. Possible values for
11996 @var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, and @samp{z990}.
11997 When generating code using the instructions available on z/Architecture,
11998 the default is @option{-march=z900}. Otherwise, the default is
11999 @option{-march=g5}.
12001 @item -mtune=@var{cpu-type}
12003 Tune to @var{cpu-type} everything applicable about the generated code,
12004 except for the ABI and the set of available instructions.
12005 The list of @var{cpu-type} values is the same as for @option{-march}.
12006 The default is the value used for @option{-march}.
12009 @itemx -mno-tpf-trace
12010 @opindex mtpf-trace
12011 @opindex mno-tpf-trace
12012 Generate code that adds (does not add) in TPF OS specific branches to trace
12013 routines in the operating system. This option is off by default, even
12014 when compiling for the TPF OS@.
12017 @itemx -mno-fused-madd
12018 @opindex mfused-madd
12019 @opindex mno-fused-madd
12020 Generate code that uses (does not use) the floating point multiply and
12021 accumulate instructions. These instructions are generated by default if
12022 hardware floating point is used.
12024 @item -mwarn-framesize=@var{framesize}
12025 @opindex mwarn-framesize
12026 Emit a warning if the current function exceeds the given frame size. Because
12027 this is a compile time check it doesn't need to be a real problem when the program
12028 runs. It is intended to identify functions which most probably cause
12029 a stack overflow. It is useful to be used in an environment with limited stack
12030 size e.g.@: the linux kernel.
12032 @item -mwarn-dynamicstack
12033 @opindex mwarn-dynamicstack
12034 Emit a warning if the function calls alloca or uses dynamically
12035 sized arrays. This is generally a bad idea with a limited stack size.
12037 @item -mstack-guard=@var{stack-guard}
12038 @item -mstack-size=@var{stack-size}
12039 @opindex mstack-guard
12040 @opindex mstack-size
12041 These arguments always have to be used in conjunction. If they are present the s390
12042 back end emits additional instructions in the function prologue which trigger a trap
12043 if the stack size is @var{stack-guard} bytes above the @var{stack-size}
12044 (remember that the stack on s390 grows downward). These options are intended to
12045 be used to help debugging stack overflow problems. The additionally emitted code
12046 causes only little overhead and hence can also be used in production like systems
12047 without greater performance degradation. The given values have to be exact
12048 powers of 2 and @var{stack-size} has to be greater than @var{stack-guard} without
12050 In order to be efficient the extra code makes the assumption that the stack starts
12051 at an address aligned to the value given by @var{stack-size}.
12054 @node Score Options
12055 @subsection Score Options
12056 @cindex Score Options
12058 These options are defined for Score implementations:
12063 Compile code for big endian mode. This is the default.
12067 Compile code for little endian mode.
12071 Disable generate bcnz instruction.
12075 Enable generate unaligned load and store instruction.
12079 Enable the use of multiply-accumulate instructions. Disabled by default.
12083 Specify the SCORE5 as the target architecture.
12087 Specify the SCORE5U of the target architecture.
12091 Specify the SCORE7 as the target architecture. This is the default.
12095 Specify the SCORE7D as the target architecture.
12099 @subsection SH Options
12101 These @samp{-m} options are defined for the SH implementations:
12106 Generate code for the SH1.
12110 Generate code for the SH2.
12113 Generate code for the SH2e.
12117 Generate code for the SH3.
12121 Generate code for the SH3e.
12125 Generate code for the SH4 without a floating-point unit.
12127 @item -m4-single-only
12128 @opindex m4-single-only
12129 Generate code for the SH4 with a floating-point unit that only
12130 supports single-precision arithmetic.
12134 Generate code for the SH4 assuming the floating-point unit is in
12135 single-precision mode by default.
12139 Generate code for the SH4.
12143 Generate code for the SH4al-dsp, or for a SH4a in such a way that the
12144 floating-point unit is not used.
12146 @item -m4a-single-only
12147 @opindex m4a-single-only
12148 Generate code for the SH4a, in such a way that no double-precision
12149 floating point operations are used.
12152 @opindex m4a-single
12153 Generate code for the SH4a assuming the floating-point unit is in
12154 single-precision mode by default.
12158 Generate code for the SH4a.
12162 Same as @option{-m4a-nofpu}, except that it implicitly passes
12163 @option{-dsp} to the assembler. GCC doesn't generate any DSP
12164 instructions at the moment.
12168 Compile code for the processor in big endian mode.
12172 Compile code for the processor in little endian mode.
12176 Align doubles at 64-bit boundaries. Note that this changes the calling
12177 conventions, and thus some functions from the standard C library will
12178 not work unless you recompile it first with @option{-mdalign}.
12182 Shorten some address references at link time, when possible; uses the
12183 linker option @option{-relax}.
12187 Use 32-bit offsets in @code{switch} tables. The default is to use
12192 Enable the use of the instruction @code{fmovd}.
12196 Comply with the calling conventions defined by Renesas.
12200 Comply with the calling conventions defined by Renesas.
12204 Comply with the calling conventions defined for GCC before the Renesas
12205 conventions were available. This option is the default for all
12206 targets of the SH toolchain except for @samp{sh-symbianelf}.
12209 @opindex mnomacsave
12210 Mark the @code{MAC} register as call-clobbered, even if
12211 @option{-mhitachi} is given.
12215 Increase IEEE-compliance of floating-point code.
12216 At the moment, this is equivalent to @option{-fno-finite-math-only}.
12217 When generating 16 bit SH opcodes, getting IEEE-conforming results for
12218 comparisons of NANs / infinities incurs extra overhead in every
12219 floating point comparison, therefore the default is set to
12220 @option{-ffinite-math-only}.
12224 Dump instruction size and location in the assembly code.
12227 @opindex mpadstruct
12228 This option is deprecated. It pads structures to multiple of 4 bytes,
12229 which is incompatible with the SH ABI@.
12233 Optimize for space instead of speed. Implied by @option{-Os}.
12236 @opindex mprefergot
12237 When generating position-independent code, emit function calls using
12238 the Global Offset Table instead of the Procedure Linkage Table.
12242 Generate a library function call to invalidate instruction cache
12243 entries, after fixing up a trampoline. This library function call
12244 doesn't assume it can write to the whole memory address space. This
12245 is the default when the target is @code{sh-*-linux*}.
12247 @item -multcost=@var{number}
12248 @opindex multcost=@var{number}
12249 Set the cost to assume for a multiply insn.
12251 @item -mdiv=@var{strategy}
12252 @opindex mdiv=@var{strategy}
12253 Set the division strategy to use for SHmedia code. @var{strategy} must be
12254 one of: call, call2, fp, inv, inv:minlat, inv20u, inv20l, inv:call,
12255 inv:call2, inv:fp .
12256 "fp" performs the operation in floating point. This has a very high latency,
12257 but needs only a few instructions, so it might be a good choice if
12258 your code has enough easily exploitable ILP to allow the compiler to
12259 schedule the floating point instructions together with other instructions.
12260 Division by zero causes a floating point exception.
12261 "inv" uses integer operations to calculate the inverse of the divisor,
12262 and then multiplies the dividend with the inverse. This strategy allows
12263 cse and hoisting of the inverse calculation. Division by zero calculates
12264 an unspecified result, but does not trap.
12265 "inv:minlat" is a variant of "inv" where if no cse / hoisting opportunities
12266 have been found, or if the entire operation has been hoisted to the same
12267 place, the last stages of the inverse calculation are intertwined with the
12268 final multiply to reduce the overall latency, at the expense of using a few
12269 more instructions, and thus offering fewer scheduling opportunities with
12271 "call" calls a library function that usually implements the inv:minlat
12273 This gives high code density for m5-*media-nofpu compilations.
12274 "call2" uses a different entry point of the same library function, where it
12275 assumes that a pointer to a lookup table has already been set up, which
12276 exposes the pointer load to cse / code hoisting optimizations.
12277 "inv:call", "inv:call2" and "inv:fp" all use the "inv" algorithm for initial
12278 code generation, but if the code stays unoptimized, revert to the "call",
12279 "call2", or "fp" strategies, respectively. Note that the
12280 potentially-trapping side effect of division by zero is carried by a
12281 separate instruction, so it is possible that all the integer instructions
12282 are hoisted out, but the marker for the side effect stays where it is.
12283 A recombination to fp operations or a call is not possible in that case.
12284 "inv20u" and "inv20l" are variants of the "inv:minlat" strategy. In the case
12285 that the inverse calculation was nor separated from the multiply, they speed
12286 up division where the dividend fits into 20 bits (plus sign where applicable),
12287 by inserting a test to skip a number of operations in this case; this test
12288 slows down the case of larger dividends. inv20u assumes the case of a such
12289 a small dividend to be unlikely, and inv20l assumes it to be likely.
12291 @item -mdivsi3_libfunc=@var{name}
12292 @opindex mdivsi3_libfunc=@var{name}
12293 Set the name of the library function used for 32 bit signed division to
12294 @var{name}. This only affect the name used in the call and inv:call
12295 division strategies, and the compiler will still expect the same
12296 sets of input/output/clobbered registers as if this option was not present.
12298 @item -madjust-unroll
12299 @opindex madjust-unroll
12300 Throttle unrolling to avoid thrashing target registers.
12301 This option only has an effect if the gcc code base supports the
12302 TARGET_ADJUST_UNROLL_MAX target hook.
12304 @item -mindexed-addressing
12305 @opindex mindexed-addressing
12306 Enable the use of the indexed addressing mode for SHmedia32/SHcompact.
12307 This is only safe if the hardware and/or OS implement 32 bit wrap-around
12308 semantics for the indexed addressing mode. The architecture allows the
12309 implementation of processors with 64 bit MMU, which the OS could use to
12310 get 32 bit addressing, but since no current hardware implementation supports
12311 this or any other way to make the indexed addressing mode safe to use in
12312 the 32 bit ABI, the default is -mno-indexed-addressing.
12314 @item -mgettrcost=@var{number}
12315 @opindex mgettrcost=@var{number}
12316 Set the cost assumed for the gettr instruction to @var{number}.
12317 The default is 2 if @option{-mpt-fixed} is in effect, 100 otherwise.
12321 Assume pt* instructions won't trap. This will generally generate better
12322 scheduled code, but is unsafe on current hardware. The current architecture
12323 definition says that ptabs and ptrel trap when the target anded with 3 is 3.
12324 This has the unintentional effect of making it unsafe to schedule ptabs /
12325 ptrel before a branch, or hoist it out of a loop. For example,
12326 __do_global_ctors, a part of libgcc that runs constructors at program
12327 startup, calls functions in a list which is delimited by -1. With the
12328 -mpt-fixed option, the ptabs will be done before testing against -1.
12329 That means that all the constructors will be run a bit quicker, but when
12330 the loop comes to the end of the list, the program crashes because ptabs
12331 loads -1 into a target register. Since this option is unsafe for any
12332 hardware implementing the current architecture specification, the default
12333 is -mno-pt-fixed. Unless the user specifies a specific cost with
12334 @option{-mgettrcost}, -mno-pt-fixed also implies @option{-mgettrcost=100};
12335 this deters register allocation using target registers for storing
12338 @item -minvalid-symbols
12339 @opindex minvalid-symbols
12340 Assume symbols might be invalid. Ordinary function symbols generated by
12341 the compiler will always be valid to load with movi/shori/ptabs or
12342 movi/shori/ptrel, but with assembler and/or linker tricks it is possible
12343 to generate symbols that will cause ptabs / ptrel to trap.
12344 This option is only meaningful when @option{-mno-pt-fixed} is in effect.
12345 It will then prevent cross-basic-block cse, hoisting and most scheduling
12346 of symbol loads. The default is @option{-mno-invalid-symbols}.
12349 @node SPARC Options
12350 @subsection SPARC Options
12351 @cindex SPARC options
12353 These @samp{-m} options are supported on the SPARC:
12356 @item -mno-app-regs
12358 @opindex mno-app-regs
12360 Specify @option{-mapp-regs} to generate output using the global registers
12361 2 through 4, which the SPARC SVR4 ABI reserves for applications. This
12364 To be fully SVR4 ABI compliant at the cost of some performance loss,
12365 specify @option{-mno-app-regs}. You should compile libraries and system
12366 software with this option.
12369 @itemx -mhard-float
12371 @opindex mhard-float
12372 Generate output containing floating point instructions. This is the
12376 @itemx -msoft-float
12378 @opindex msoft-float
12379 Generate output containing library calls for floating point.
12380 @strong{Warning:} the requisite libraries are not available for all SPARC
12381 targets. Normally the facilities of the machine's usual C compiler are
12382 used, but this cannot be done directly in cross-compilation. You must make
12383 your own arrangements to provide suitable library functions for
12384 cross-compilation. The embedded targets @samp{sparc-*-aout} and
12385 @samp{sparclite-*-*} do provide software floating point support.
12387 @option{-msoft-float} changes the calling convention in the output file;
12388 therefore, it is only useful if you compile @emph{all} of a program with
12389 this option. In particular, you need to compile @file{libgcc.a}, the
12390 library that comes with GCC, with @option{-msoft-float} in order for
12393 @item -mhard-quad-float
12394 @opindex mhard-quad-float
12395 Generate output containing quad-word (long double) floating point
12398 @item -msoft-quad-float
12399 @opindex msoft-quad-float
12400 Generate output containing library calls for quad-word (long double)
12401 floating point instructions. The functions called are those specified
12402 in the SPARC ABI@. This is the default.
12404 As of this writing, there are no SPARC implementations that have hardware
12405 support for the quad-word floating point instructions. They all invoke
12406 a trap handler for one of these instructions, and then the trap handler
12407 emulates the effect of the instruction. Because of the trap handler overhead,
12408 this is much slower than calling the ABI library routines. Thus the
12409 @option{-msoft-quad-float} option is the default.
12411 @item -mno-unaligned-doubles
12412 @itemx -munaligned-doubles
12413 @opindex mno-unaligned-doubles
12414 @opindex munaligned-doubles
12415 Assume that doubles have 8 byte alignment. This is the default.
12417 With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
12418 alignment only if they are contained in another type, or if they have an
12419 absolute address. Otherwise, it assumes they have 4 byte alignment.
12420 Specifying this option avoids some rare compatibility problems with code
12421 generated by other compilers. It is not the default because it results
12422 in a performance loss, especially for floating point code.
12424 @item -mno-faster-structs
12425 @itemx -mfaster-structs
12426 @opindex mno-faster-structs
12427 @opindex mfaster-structs
12428 With @option{-mfaster-structs}, the compiler assumes that structures
12429 should have 8 byte alignment. This enables the use of pairs of
12430 @code{ldd} and @code{std} instructions for copies in structure
12431 assignment, in place of twice as many @code{ld} and @code{st} pairs.
12432 However, the use of this changed alignment directly violates the SPARC
12433 ABI@. Thus, it's intended only for use on targets where the developer
12434 acknowledges that their resulting code will not be directly in line with
12435 the rules of the ABI@.
12437 @item -mimpure-text
12438 @opindex mimpure-text
12439 @option{-mimpure-text}, used in addition to @option{-shared}, tells
12440 the compiler to not pass @option{-z text} to the linker when linking a
12441 shared object. Using this option, you can link position-dependent
12442 code into a shared object.
12444 @option{-mimpure-text} suppresses the ``relocations remain against
12445 allocatable but non-writable sections'' linker error message.
12446 However, the necessary relocations will trigger copy-on-write, and the
12447 shared object is not actually shared across processes. Instead of
12448 using @option{-mimpure-text}, you should compile all source code with
12449 @option{-fpic} or @option{-fPIC}.
12451 This option is only available on SunOS and Solaris.
12453 @item -mcpu=@var{cpu_type}
12455 Set the instruction set, register set, and instruction scheduling parameters
12456 for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
12457 @samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
12458 @samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x},
12459 @samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc},
12460 @samp{ultrasparc3}, and @samp{niagara}.
12462 Default instruction scheduling parameters are used for values that select
12463 an architecture and not an implementation. These are @samp{v7}, @samp{v8},
12464 @samp{sparclite}, @samp{sparclet}, @samp{v9}.
12466 Here is a list of each supported architecture and their supported
12471 v8: supersparc, hypersparc
12472 sparclite: f930, f934, sparclite86x
12474 v9: ultrasparc, ultrasparc3, niagara
12477 By default (unless configured otherwise), GCC generates code for the V7
12478 variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler
12479 additionally optimizes it for the Cypress CY7C602 chip, as used in the
12480 SPARCStation/SPARCServer 3xx series. This is also appropriate for the older
12481 SPARCStation 1, 2, IPX etc.
12483 With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
12484 architecture. The only difference from V7 code is that the compiler emits
12485 the integer multiply and integer divide instructions which exist in SPARC-V8
12486 but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally
12487 optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
12490 With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
12491 the SPARC architecture. This adds the integer multiply, integer divide step
12492 and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
12493 With @option{-mcpu=f930}, the compiler additionally optimizes it for the
12494 Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@. With
12495 @option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
12496 MB86934 chip, which is the more recent SPARClite with FPU@.
12498 With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
12499 the SPARC architecture. This adds the integer multiply, multiply/accumulate,
12500 integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
12501 but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally
12502 optimizes it for the TEMIC SPARClet chip.
12504 With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
12505 architecture. This adds 64-bit integer and floating-point move instructions,
12506 3 additional floating-point condition code registers and conditional move
12507 instructions. With @option{-mcpu=ultrasparc}, the compiler additionally
12508 optimizes it for the Sun UltraSPARC I/II/IIi chips. With
12509 @option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
12510 Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips. With
12511 @option{-mcpu=niagara}, the compiler additionally optimizes it for
12512 Sun UltraSPARC T1 chips.
12514 @item -mtune=@var{cpu_type}
12516 Set the instruction scheduling parameters for machine type
12517 @var{cpu_type}, but do not set the instruction set or register set that the
12518 option @option{-mcpu=@var{cpu_type}} would.
12520 The same values for @option{-mcpu=@var{cpu_type}} can be used for
12521 @option{-mtune=@var{cpu_type}}, but the only useful values are those
12522 that select a particular cpu implementation. Those are @samp{cypress},
12523 @samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
12524 @samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc},
12525 @samp{ultrasparc3}, and @samp{niagara}.
12530 @opindex mno-v8plus
12531 With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@. The
12532 difference from the V8 ABI is that the global and out registers are
12533 considered 64-bit wide. This is enabled by default on Solaris in 32-bit
12534 mode for all SPARC-V9 processors.
12540 With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
12541 Visual Instruction Set extensions. The default is @option{-mno-vis}.
12544 These @samp{-m} options are supported in addition to the above
12545 on SPARC-V9 processors in 64-bit environments:
12548 @item -mlittle-endian
12549 @opindex mlittle-endian
12550 Generate code for a processor running in little-endian mode. It is only
12551 available for a few configurations and most notably not on Solaris and Linux.
12557 Generate code for a 32-bit or 64-bit environment.
12558 The 32-bit environment sets int, long and pointer to 32 bits.
12559 The 64-bit environment sets int to 32 bits and long and pointer
12562 @item -mcmodel=medlow
12563 @opindex mcmodel=medlow
12564 Generate code for the Medium/Low code model: 64-bit addresses, programs
12565 must be linked in the low 32 bits of memory. Programs can be statically
12566 or dynamically linked.
12568 @item -mcmodel=medmid
12569 @opindex mcmodel=medmid
12570 Generate code for the Medium/Middle code model: 64-bit addresses, programs
12571 must be linked in the low 44 bits of memory, the text and data segments must
12572 be less than 2GB in size and the data segment must be located within 2GB of
12575 @item -mcmodel=medany
12576 @opindex mcmodel=medany
12577 Generate code for the Medium/Anywhere code model: 64-bit addresses, programs
12578 may be linked anywhere in memory, the text and data segments must be less
12579 than 2GB in size and the data segment must be located within 2GB of the
12582 @item -mcmodel=embmedany
12583 @opindex mcmodel=embmedany
12584 Generate code for the Medium/Anywhere code model for embedded systems:
12585 64-bit addresses, the text and data segments must be less than 2GB in
12586 size, both starting anywhere in memory (determined at link time). The
12587 global register %g4 points to the base of the data segment. Programs
12588 are statically linked and PIC is not supported.
12591 @itemx -mno-stack-bias
12592 @opindex mstack-bias
12593 @opindex mno-stack-bias
12594 With @option{-mstack-bias}, GCC assumes that the stack pointer, and
12595 frame pointer if present, are offset by @minus{}2047 which must be added back
12596 when making stack frame references. This is the default in 64-bit mode.
12597 Otherwise, assume no such offset is present.
12600 These switches are supported in addition to the above on Solaris:
12605 Add support for multithreading using the Solaris threads library. This
12606 option sets flags for both the preprocessor and linker. This option does
12607 not affect the thread safety of object code produced by the compiler or
12608 that of libraries supplied with it.
12612 Add support for multithreading using the POSIX threads library. This
12613 option sets flags for both the preprocessor and linker. This option does
12614 not affect the thread safety of object code produced by the compiler or
12615 that of libraries supplied with it.
12619 This is a synonym for @option{-pthreads}.
12622 @node System V Options
12623 @subsection Options for System V
12625 These additional options are available on System V Release 4 for
12626 compatibility with other compilers on those systems:
12631 Create a shared object.
12632 It is recommended that @option{-symbolic} or @option{-shared} be used instead.
12636 Identify the versions of each tool used by the compiler, in a
12637 @code{.ident} assembler directive in the output.
12641 Refrain from adding @code{.ident} directives to the output file (this is
12644 @item -YP,@var{dirs}
12646 Search the directories @var{dirs}, and no others, for libraries
12647 specified with @option{-l}.
12649 @item -Ym,@var{dir}
12651 Look in the directory @var{dir} to find the M4 preprocessor.
12652 The assembler uses this option.
12653 @c This is supposed to go with a -Yd for predefined M4 macro files, but
12654 @c the generic assembler that comes with Solaris takes just -Ym.
12657 @node TMS320C3x/C4x Options
12658 @subsection TMS320C3x/C4x Options
12659 @cindex TMS320C3x/C4x Options
12661 These @samp{-m} options are defined for TMS320C3x/C4x implementations:
12665 @item -mcpu=@var{cpu_type}
12667 Set the instruction set, register set, and instruction scheduling
12668 parameters for machine type @var{cpu_type}. Supported values for
12669 @var{cpu_type} are @samp{c30}, @samp{c31}, @samp{c32}, @samp{c40}, and
12670 @samp{c44}. The default is @samp{c40} to generate code for the
12675 @itemx -msmall-memory
12677 @opindex mbig-memory
12679 @opindex msmall-memory
12681 Generates code for the big or small memory model. The small memory
12682 model assumed that all data fits into one 64K word page. At run-time
12683 the data page (DP) register must be set to point to the 64K page
12684 containing the .bss and .data program sections. The big memory model is
12685 the default and requires reloading of the DP register for every direct
12692 Allow (disallow) allocation of general integer operands into the block
12693 count register BK@.
12699 Enable (disable) generation of code using decrement and branch,
12700 DBcond(D), instructions. This is enabled by default for the C4x. To be
12701 on the safe side, this is disabled for the C3x, since the maximum
12702 iteration count on the C3x is @math{2^{23} + 1} (but who iterates loops more than
12703 @math{2^{23}} times on the C3x?). Note that GCC will try to reverse a loop so
12704 that it can utilize the decrement and branch instruction, but will give
12705 up if there is more than one memory reference in the loop. Thus a loop
12706 where the loop counter is decremented can generate slightly more
12707 efficient code, in cases where the RPTB instruction cannot be utilized.
12709 @item -mdp-isr-reload
12711 @opindex mdp-isr-reload
12713 Force the DP register to be saved on entry to an interrupt service
12714 routine (ISR), reloaded to point to the data section, and restored on
12715 exit from the ISR@. This should not be required unless someone has
12716 violated the small memory model by modifying the DP register, say within
12723 For the C3x use the 24-bit MPYI instruction for integer multiplies
12724 instead of a library call to guarantee 32-bit results. Note that if one
12725 of the operands is a constant, then the multiplication will be performed
12726 using shifts and adds. If the @option{-mmpyi} option is not specified for the C3x,
12727 then squaring operations are performed inline instead of a library call.
12730 @itemx -mno-fast-fix
12732 @opindex mno-fast-fix
12733 The C3x/C4x FIX instruction to convert a floating point value to an
12734 integer value chooses the nearest integer less than or equal to the
12735 floating point value rather than to the nearest integer. Thus if the
12736 floating point number is negative, the result will be incorrectly
12737 truncated an additional code is necessary to detect and correct this
12738 case. This option can be used to disable generation of the additional
12739 code required to correct the result.
12745 Enable (disable) generation of repeat block sequences using the RPTB
12746 instruction for zero overhead looping. The RPTB construct is only used
12747 for innermost loops that do not call functions or jump across the loop
12748 boundaries. There is no advantage having nested RPTB loops due to the
12749 overhead required to save and restore the RC, RS, and RE registers.
12750 This is enabled by default with @option{-O2}.
12752 @item -mrpts=@var{count}
12756 Enable (disable) the use of the single instruction repeat instruction
12757 RPTS@. If a repeat block contains a single instruction, and the loop
12758 count can be guaranteed to be less than the value @var{count}, GCC will
12759 emit a RPTS instruction instead of a RPTB@. If no value is specified,
12760 then a RPTS will be emitted even if the loop count cannot be determined
12761 at compile time. Note that the repeated instruction following RPTS does
12762 not have to be reloaded from memory each iteration, thus freeing up the
12763 CPU buses for operands. However, since interrupts are blocked by this
12764 instruction, it is disabled by default.
12766 @item -mloop-unsigned
12767 @itemx -mno-loop-unsigned
12768 @opindex mloop-unsigned
12769 @opindex mno-loop-unsigned
12770 The maximum iteration count when using RPTS and RPTB (and DB on the C40)
12771 is @math{2^{31} + 1} since these instructions test if the iteration count is
12772 negative to terminate the loop. If the iteration count is unsigned
12773 there is a possibility than the @math{2^{31} + 1} maximum iteration count may be
12774 exceeded. This switch allows an unsigned iteration count.
12778 Try to emit an assembler syntax that the TI assembler (asm30) is happy
12779 with. This also enforces compatibility with the API employed by the TI
12780 C3x C compiler. For example, long doubles are passed as structures
12781 rather than in floating point registers.
12787 Generate code that uses registers (stack) for passing arguments to functions.
12788 By default, arguments are passed in registers where possible rather
12789 than by pushing arguments on to the stack.
12791 @item -mparallel-insns
12792 @itemx -mno-parallel-insns
12793 @opindex mparallel-insns
12794 @opindex mno-parallel-insns
12795 Allow the generation of parallel instructions. This is enabled by
12796 default with @option{-O2}.
12798 @item -mparallel-mpy
12799 @itemx -mno-parallel-mpy
12800 @opindex mparallel-mpy
12801 @opindex mno-parallel-mpy
12802 Allow the generation of MPY||ADD and MPY||SUB parallel instructions,
12803 provided @option{-mparallel-insns} is also specified. These instructions have
12804 tight register constraints which can pessimize the code generation
12805 of large functions.
12810 @subsection V850 Options
12811 @cindex V850 Options
12813 These @samp{-m} options are defined for V850 implementations:
12817 @itemx -mno-long-calls
12818 @opindex mlong-calls
12819 @opindex mno-long-calls
12820 Treat all calls as being far away (near). If calls are assumed to be
12821 far away, the compiler will always load the functions address up into a
12822 register, and call indirect through the pointer.
12828 Do not optimize (do optimize) basic blocks that use the same index
12829 pointer 4 or more times to copy pointer into the @code{ep} register, and
12830 use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
12831 option is on by default if you optimize.
12833 @item -mno-prolog-function
12834 @itemx -mprolog-function
12835 @opindex mno-prolog-function
12836 @opindex mprolog-function
12837 Do not use (do use) external functions to save and restore registers
12838 at the prologue and epilogue of a function. The external functions
12839 are slower, but use less code space if more than one function saves
12840 the same number of registers. The @option{-mprolog-function} option
12841 is on by default if you optimize.
12845 Try to make the code as small as possible. At present, this just turns
12846 on the @option{-mep} and @option{-mprolog-function} options.
12848 @item -mtda=@var{n}
12850 Put static or global variables whose size is @var{n} bytes or less into
12851 the tiny data area that register @code{ep} points to. The tiny data
12852 area can hold up to 256 bytes in total (128 bytes for byte references).
12854 @item -msda=@var{n}
12856 Put static or global variables whose size is @var{n} bytes or less into
12857 the small data area that register @code{gp} points to. The small data
12858 area can hold up to 64 kilobytes.
12860 @item -mzda=@var{n}
12862 Put static or global variables whose size is @var{n} bytes or less into
12863 the first 32 kilobytes of memory.
12867 Specify that the target processor is the V850.
12870 @opindex mbig-switch
12871 Generate code suitable for big switch tables. Use this option only if
12872 the assembler/linker complain about out of range branches within a switch
12877 This option will cause r2 and r5 to be used in the code generated by
12878 the compiler. This setting is the default.
12880 @item -mno-app-regs
12881 @opindex mno-app-regs
12882 This option will cause r2 and r5 to be treated as fixed registers.
12886 Specify that the target processor is the V850E1. The preprocessor
12887 constants @samp{__v850e1__} and @samp{__v850e__} will be defined if
12888 this option is used.
12892 Specify that the target processor is the V850E@. The preprocessor
12893 constant @samp{__v850e__} will be defined if this option is used.
12895 If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
12896 are defined then a default target processor will be chosen and the
12897 relevant @samp{__v850*__} preprocessor constant will be defined.
12899 The preprocessor constants @samp{__v850} and @samp{__v851__} are always
12900 defined, regardless of which processor variant is the target.
12902 @item -mdisable-callt
12903 @opindex mdisable-callt
12904 This option will suppress generation of the CALLT instruction for the
12905 v850e and v850e1 flavors of the v850 architecture. The default is
12906 @option{-mno-disable-callt} which allows the CALLT instruction to be used.
12911 @subsection VAX Options
12912 @cindex VAX options
12914 These @samp{-m} options are defined for the VAX:
12919 Do not output certain jump instructions (@code{aobleq} and so on)
12920 that the Unix assembler for the VAX cannot handle across long
12925 Do output those jump instructions, on the assumption that you
12926 will assemble with the GNU assembler.
12930 Output code for g-format floating point numbers instead of d-format.
12933 @node x86-64 Options
12934 @subsection x86-64 Options
12935 @cindex x86-64 options
12937 These are listed under @xref{i386 and x86-64 Options}.
12939 @node Xstormy16 Options
12940 @subsection Xstormy16 Options
12941 @cindex Xstormy16 Options
12943 These options are defined for Xstormy16:
12948 Choose startup files and linker script suitable for the simulator.
12951 @node Xtensa Options
12952 @subsection Xtensa Options
12953 @cindex Xtensa Options
12955 These options are supported for Xtensa targets:
12959 @itemx -mno-const16
12961 @opindex mno-const16
12962 Enable or disable use of @code{CONST16} instructions for loading
12963 constant values. The @code{CONST16} instruction is currently not a
12964 standard option from Tensilica. When enabled, @code{CONST16}
12965 instructions are always used in place of the standard @code{L32R}
12966 instructions. The use of @code{CONST16} is enabled by default only if
12967 the @code{L32R} instruction is not available.
12970 @itemx -mno-fused-madd
12971 @opindex mfused-madd
12972 @opindex mno-fused-madd
12973 Enable or disable use of fused multiply/add and multiply/subtract
12974 instructions in the floating-point option. This has no effect if the
12975 floating-point option is not also enabled. Disabling fused multiply/add
12976 and multiply/subtract instructions forces the compiler to use separate
12977 instructions for the multiply and add/subtract operations. This may be
12978 desirable in some cases where strict IEEE 754-compliant results are
12979 required: the fused multiply add/subtract instructions do not round the
12980 intermediate result, thereby producing results with @emph{more} bits of
12981 precision than specified by the IEEE standard. Disabling fused multiply
12982 add/subtract instructions also ensures that the program output is not
12983 sensitive to the compiler's ability to combine multiply and add/subtract
12986 @item -mtext-section-literals
12987 @itemx -mno-text-section-literals
12988 @opindex mtext-section-literals
12989 @opindex mno-text-section-literals
12990 Control the treatment of literal pools. The default is
12991 @option{-mno-text-section-literals}, which places literals in a separate
12992 section in the output file. This allows the literal pool to be placed
12993 in a data RAM/ROM, and it also allows the linker to combine literal
12994 pools from separate object files to remove redundant literals and
12995 improve code size. With @option{-mtext-section-literals}, the literals
12996 are interspersed in the text section in order to keep them as close as
12997 possible to their references. This may be necessary for large assembly
13000 @item -mtarget-align
13001 @itemx -mno-target-align
13002 @opindex mtarget-align
13003 @opindex mno-target-align
13004 When this option is enabled, GCC instructs the assembler to
13005 automatically align instructions to reduce branch penalties at the
13006 expense of some code density. The assembler attempts to widen density
13007 instructions to align branch targets and the instructions following call
13008 instructions. If there are not enough preceding safe density
13009 instructions to align a target, no widening will be performed. The
13010 default is @option{-mtarget-align}. These options do not affect the
13011 treatment of auto-aligned instructions like @code{LOOP}, which the
13012 assembler will always align, either by widening density instructions or
13013 by inserting no-op instructions.
13016 @itemx -mno-longcalls
13017 @opindex mlongcalls
13018 @opindex mno-longcalls
13019 When this option is enabled, GCC instructs the assembler to translate
13020 direct calls to indirect calls unless it can determine that the target
13021 of a direct call is in the range allowed by the call instruction. This
13022 translation typically occurs for calls to functions in other source
13023 files. Specifically, the assembler translates a direct @code{CALL}
13024 instruction into an @code{L32R} followed by a @code{CALLX} instruction.
13025 The default is @option{-mno-longcalls}. This option should be used in
13026 programs where the call target can potentially be out of range. This
13027 option is implemented in the assembler, not the compiler, so the
13028 assembly code generated by GCC will still show direct call
13029 instructions---look at the disassembled object code to see the actual
13030 instructions. Note that the assembler will use an indirect call for
13031 every cross-file call, not just those that really will be out of range.
13034 @node zSeries Options
13035 @subsection zSeries Options
13036 @cindex zSeries options
13038 These are listed under @xref{S/390 and zSeries Options}.
13040 @node Code Gen Options
13041 @section Options for Code Generation Conventions
13042 @cindex code generation conventions
13043 @cindex options, code generation
13044 @cindex run-time options
13046 These machine-independent options control the interface conventions
13047 used in code generation.
13049 Most of them have both positive and negative forms; the negative form
13050 of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
13051 one of the forms is listed---the one which is not the default. You
13052 can figure out the other form by either removing @samp{no-} or adding
13056 @item -fbounds-check
13057 @opindex fbounds-check
13058 For front-ends that support it, generate additional code to check that
13059 indices used to access arrays are within the declared range. This is
13060 currently only supported by the Java and Fortran front-ends, where
13061 this option defaults to true and false respectively.
13065 This option generates traps for signed overflow on addition, subtraction,
13066 multiplication operations.
13070 This option instructs the compiler to assume that signed arithmetic
13071 overflow of addition, subtraction and multiplication wraps around
13072 using twos-complement representation. This flag enables some optimizations
13073 and disables others. This option is enabled by default for the Java
13074 front-end, as required by the Java language specification.
13077 @opindex fexceptions
13078 Enable exception handling. Generates extra code needed to propagate
13079 exceptions. For some targets, this implies GCC will generate frame
13080 unwind information for all functions, which can produce significant data
13081 size overhead, although it does not affect execution. If you do not
13082 specify this option, GCC will enable it by default for languages like
13083 C++ which normally require exception handling, and disable it for
13084 languages like C that do not normally require it. However, you may need
13085 to enable this option when compiling C code that needs to interoperate
13086 properly with exception handlers written in C++. You may also wish to
13087 disable this option if you are compiling older C++ programs that don't
13088 use exception handling.
13090 @item -fnon-call-exceptions
13091 @opindex fnon-call-exceptions
13092 Generate code that allows trapping instructions to throw exceptions.
13093 Note that this requires platform-specific runtime support that does
13094 not exist everywhere. Moreover, it only allows @emph{trapping}
13095 instructions to throw exceptions, i.e.@: memory references or floating
13096 point instructions. It does not allow exceptions to be thrown from
13097 arbitrary signal handlers such as @code{SIGALRM}.
13099 @item -funwind-tables
13100 @opindex funwind-tables
13101 Similar to @option{-fexceptions}, except that it will just generate any needed
13102 static data, but will not affect the generated code in any other way.
13103 You will normally not enable this option; instead, a language processor
13104 that needs this handling would enable it on your behalf.
13106 @item -fasynchronous-unwind-tables
13107 @opindex fasynchronous-unwind-tables
13108 Generate unwind table in dwarf2 format, if supported by target machine. The
13109 table is exact at each instruction boundary, so it can be used for stack
13110 unwinding from asynchronous events (such as debugger or garbage collector).
13112 @item -fpcc-struct-return
13113 @opindex fpcc-struct-return
13114 Return ``short'' @code{struct} and @code{union} values in memory like
13115 longer ones, rather than in registers. This convention is less
13116 efficient, but it has the advantage of allowing intercallability between
13117 GCC-compiled files and files compiled with other compilers, particularly
13118 the Portable C Compiler (pcc).
13120 The precise convention for returning structures in memory depends
13121 on the target configuration macros.
13123 Short structures and unions are those whose size and alignment match
13124 that of some integer type.
13126 @strong{Warning:} code compiled with the @option{-fpcc-struct-return}
13127 switch is not binary compatible with code compiled with the
13128 @option{-freg-struct-return} switch.
13129 Use it to conform to a non-default application binary interface.
13131 @item -freg-struct-return
13132 @opindex freg-struct-return
13133 Return @code{struct} and @code{union} values in registers when possible.
13134 This is more efficient for small structures than
13135 @option{-fpcc-struct-return}.
13137 If you specify neither @option{-fpcc-struct-return} nor
13138 @option{-freg-struct-return}, GCC defaults to whichever convention is
13139 standard for the target. If there is no standard convention, GCC
13140 defaults to @option{-fpcc-struct-return}, except on targets where GCC is
13141 the principal compiler. In those cases, we can choose the standard, and
13142 we chose the more efficient register return alternative.
13144 @strong{Warning:} code compiled with the @option{-freg-struct-return}
13145 switch is not binary compatible with code compiled with the
13146 @option{-fpcc-struct-return} switch.
13147 Use it to conform to a non-default application binary interface.
13149 @item -fshort-enums
13150 @opindex fshort-enums
13151 Allocate to an @code{enum} type only as many bytes as it needs for the
13152 declared range of possible values. Specifically, the @code{enum} type
13153 will be equivalent to the smallest integer type which has enough room.
13155 @strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
13156 code that is not binary compatible with code generated without that switch.
13157 Use it to conform to a non-default application binary interface.
13159 @item -fshort-double
13160 @opindex fshort-double
13161 Use the same size for @code{double} as for @code{float}.
13163 @strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
13164 code that is not binary compatible with code generated without that switch.
13165 Use it to conform to a non-default application binary interface.
13167 @item -fshort-wchar
13168 @opindex fshort-wchar
13169 Override the underlying type for @samp{wchar_t} to be @samp{short
13170 unsigned int} instead of the default for the target. This option is
13171 useful for building programs to run under WINE@.
13173 @strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
13174 code that is not binary compatible with code generated without that switch.
13175 Use it to conform to a non-default application binary interface.
13178 @opindex fno-common
13179 In C, allocate even uninitialized global variables in the data section of the
13180 object file, rather than generating them as common blocks. This has the
13181 effect that if the same variable is declared (without @code{extern}) in
13182 two different compilations, you will get an error when you link them.
13183 The only reason this might be useful is if you wish to verify that the
13184 program will work on other systems which always work this way.
13188 Ignore the @samp{#ident} directive.
13190 @item -finhibit-size-directive
13191 @opindex finhibit-size-directive
13192 Don't output a @code{.size} assembler directive, or anything else that
13193 would cause trouble if the function is split in the middle, and the
13194 two halves are placed at locations far apart in memory. This option is
13195 used when compiling @file{crtstuff.c}; you should not need to use it
13198 @item -fverbose-asm
13199 @opindex fverbose-asm
13200 Put extra commentary information in the generated assembly code to
13201 make it more readable. This option is generally only of use to those
13202 who actually need to read the generated assembly code (perhaps while
13203 debugging the compiler itself).
13205 @option{-fno-verbose-asm}, the default, causes the
13206 extra information to be omitted and is useful when comparing two assembler
13211 @cindex global offset table
13213 Generate position-independent code (PIC) suitable for use in a shared
13214 library, if supported for the target machine. Such code accesses all
13215 constant addresses through a global offset table (GOT)@. The dynamic
13216 loader resolves the GOT entries when the program starts (the dynamic
13217 loader is not part of GCC; it is part of the operating system). If
13218 the GOT size for the linked executable exceeds a machine-specific
13219 maximum size, you get an error message from the linker indicating that
13220 @option{-fpic} does not work; in that case, recompile with @option{-fPIC}
13221 instead. (These maximums are 8k on the SPARC and 32k
13222 on the m68k and RS/6000. The 386 has no such limit.)
13224 Position-independent code requires special support, and therefore works
13225 only on certain machines. For the 386, GCC supports PIC for System V
13226 but not for the Sun 386i. Code generated for the IBM RS/6000 is always
13227 position-independent.
13229 When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13234 If supported for the target machine, emit position-independent code,
13235 suitable for dynamic linking and avoiding any limit on the size of the
13236 global offset table. This option makes a difference on the m68k,
13237 PowerPC and SPARC@.
13239 Position-independent code requires special support, and therefore works
13240 only on certain machines.
13242 When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13249 These options are similar to @option{-fpic} and @option{-fPIC}, but
13250 generated position independent code can be only linked into executables.
13251 Usually these options are used when @option{-pie} GCC option will be
13252 used during linking.
13254 @item -fno-jump-tables
13255 @opindex fno-jump-tables
13256 Do not use jump tables for switch statements even where it would be
13257 more efficient than other code generation strategies. This option is
13258 of use in conjunction with @option{-fpic} or @option{-fPIC} for
13259 building code which forms part of a dynamic linker and cannot
13260 reference the address of a jump table. On some targets, jump tables
13261 do not require a GOT and this option is not needed.
13263 @item -ffixed-@var{reg}
13265 Treat the register named @var{reg} as a fixed register; generated code
13266 should never refer to it (except perhaps as a stack pointer, frame
13267 pointer or in some other fixed role).
13269 @var{reg} must be the name of a register. The register names accepted
13270 are machine-specific and are defined in the @code{REGISTER_NAMES}
13271 macro in the machine description macro file.
13273 This flag does not have a negative form, because it specifies a
13276 @item -fcall-used-@var{reg}
13277 @opindex fcall-used
13278 Treat the register named @var{reg} as an allocable register that is
13279 clobbered by function calls. It may be allocated for temporaries or
13280 variables that do not live across a call. Functions compiled this way
13281 will not save and restore the register @var{reg}.
13283 It is an error to used this flag with the frame pointer or stack pointer.
13284 Use of this flag for other registers that have fixed pervasive roles in
13285 the machine's execution model will produce disastrous results.
13287 This flag does not have a negative form, because it specifies a
13290 @item -fcall-saved-@var{reg}
13291 @opindex fcall-saved
13292 Treat the register named @var{reg} as an allocable register saved by
13293 functions. It may be allocated even for temporaries or variables that
13294 live across a call. Functions compiled this way will save and restore
13295 the register @var{reg} if they use it.
13297 It is an error to used this flag with the frame pointer or stack pointer.
13298 Use of this flag for other registers that have fixed pervasive roles in
13299 the machine's execution model will produce disastrous results.
13301 A different sort of disaster will result from the use of this flag for
13302 a register in which function values may be returned.
13304 This flag does not have a negative form, because it specifies a
13307 @item -fpack-struct[=@var{n}]
13308 @opindex fpack-struct
13309 Without a value specified, pack all structure members together without
13310 holes. When a value is specified (which must be a small power of two), pack
13311 structure members according to this value, representing the maximum
13312 alignment (that is, objects with default alignment requirements larger than
13313 this will be output potentially unaligned at the next fitting location.
13315 @strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
13316 code that is not binary compatible with code generated without that switch.
13317 Additionally, it makes the code suboptimal.
13318 Use it to conform to a non-default application binary interface.
13320 @item -finstrument-functions
13321 @opindex finstrument-functions
13322 Generate instrumentation calls for entry and exit to functions. Just
13323 after function entry and just before function exit, the following
13324 profiling functions will be called with the address of the current
13325 function and its call site. (On some platforms,
13326 @code{__builtin_return_address} does not work beyond the current
13327 function, so the call site information may not be available to the
13328 profiling functions otherwise.)
13331 void __cyg_profile_func_enter (void *this_fn,
13333 void __cyg_profile_func_exit (void *this_fn,
13337 The first argument is the address of the start of the current function,
13338 which may be looked up exactly in the symbol table.
13340 This instrumentation is also done for functions expanded inline in other
13341 functions. The profiling calls will indicate where, conceptually, the
13342 inline function is entered and exited. This means that addressable
13343 versions of such functions must be available. If all your uses of a
13344 function are expanded inline, this may mean an additional expansion of
13345 code size. If you use @samp{extern inline} in your C code, an
13346 addressable version of such functions must be provided. (This is
13347 normally the case anyways, but if you get lucky and the optimizer always
13348 expands the functions inline, you might have gotten away without
13349 providing static copies.)
13351 A function may be given the attribute @code{no_instrument_function}, in
13352 which case this instrumentation will not be done. This can be used, for
13353 example, for the profiling functions listed above, high-priority
13354 interrupt routines, and any functions from which the profiling functions
13355 cannot safely be called (perhaps signal handlers, if the profiling
13356 routines generate output or allocate memory).
13358 @item -fstack-check
13359 @opindex fstack-check
13360 Generate code to verify that you do not go beyond the boundary of the
13361 stack. You should specify this flag if you are running in an
13362 environment with multiple threads, but only rarely need to specify it in
13363 a single-threaded environment since stack overflow is automatically
13364 detected on nearly all systems if there is only one stack.
13366 Note that this switch does not actually cause checking to be done; the
13367 operating system must do that. The switch causes generation of code
13368 to ensure that the operating system sees the stack being extended.
13370 @item -fstack-limit-register=@var{reg}
13371 @itemx -fstack-limit-symbol=@var{sym}
13372 @itemx -fno-stack-limit
13373 @opindex fstack-limit-register
13374 @opindex fstack-limit-symbol
13375 @opindex fno-stack-limit
13376 Generate code to ensure that the stack does not grow beyond a certain value,
13377 either the value of a register or the address of a symbol. If the stack
13378 would grow beyond the value, a signal is raised. For most targets,
13379 the signal is raised before the stack overruns the boundary, so
13380 it is possible to catch the signal without taking special precautions.
13382 For instance, if the stack starts at absolute address @samp{0x80000000}
13383 and grows downwards, you can use the flags
13384 @option{-fstack-limit-symbol=__stack_limit} and
13385 @option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
13386 of 128KB@. Note that this may only work with the GNU linker.
13388 @cindex aliasing of parameters
13389 @cindex parameters, aliased
13390 @item -fargument-alias
13391 @itemx -fargument-noalias
13392 @itemx -fargument-noalias-global
13393 @itemx -fargument-noalias-anything
13394 @opindex fargument-alias
13395 @opindex fargument-noalias
13396 @opindex fargument-noalias-global
13397 @opindex fargument-noalias-anything
13398 Specify the possible relationships among parameters and between
13399 parameters and global data.
13401 @option{-fargument-alias} specifies that arguments (parameters) may
13402 alias each other and may alias global storage.@*
13403 @option{-fargument-noalias} specifies that arguments do not alias
13404 each other, but may alias global storage.@*
13405 @option{-fargument-noalias-global} specifies that arguments do not
13406 alias each other and do not alias global storage.
13407 @option{-fargument-noalias-anything} specifies that arguments do not
13408 alias any other storage.
13410 Each language will automatically use whatever option is required by
13411 the language standard. You should not need to use these options yourself.
13413 @item -fleading-underscore
13414 @opindex fleading-underscore
13415 This option and its counterpart, @option{-fno-leading-underscore}, forcibly
13416 change the way C symbols are represented in the object file. One use
13417 is to help link with legacy assembly code.
13419 @strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
13420 generate code that is not binary compatible with code generated without that
13421 switch. Use it to conform to a non-default application binary interface.
13422 Not all targets provide complete support for this switch.
13424 @item -ftls-model=@var{model}
13425 Alter the thread-local storage model to be used (@pxref{Thread-Local}).
13426 The @var{model} argument should be one of @code{global-dynamic},
13427 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
13429 The default without @option{-fpic} is @code{initial-exec}; with
13430 @option{-fpic} the default is @code{global-dynamic}.
13432 @item -fvisibility=@var{default|internal|hidden|protected}
13433 @opindex fvisibility
13434 Set the default ELF image symbol visibility to the specified option---all
13435 symbols will be marked with this unless overridden within the code.
13436 Using this feature can very substantially improve linking and
13437 load times of shared object libraries, produce more optimized
13438 code, provide near-perfect API export and prevent symbol clashes.
13439 It is @strong{strongly} recommended that you use this in any shared objects
13442 Despite the nomenclature, @code{default} always means public ie;
13443 available to be linked against from outside the shared object.
13444 @code{protected} and @code{internal} are pretty useless in real-world
13445 usage so the only other commonly used option will be @code{hidden}.
13446 The default if @option{-fvisibility} isn't specified is
13447 @code{default}, i.e., make every
13448 symbol public---this causes the same behavior as previous versions of
13451 A good explanation of the benefits offered by ensuring ELF
13452 symbols have the correct visibility is given by ``How To Write
13453 Shared Libraries'' by Ulrich Drepper (which can be found at
13454 @w{@uref{http://people.redhat.com/~drepper/}})---however a superior
13455 solution made possible by this option to marking things hidden when
13456 the default is public is to make the default hidden and mark things
13457 public. This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
13458 and @code{__attribute__ ((visibility("default")))} instead of
13459 @code{__declspec(dllexport)} you get almost identical semantics with
13460 identical syntax. This is a great boon to those working with
13461 cross-platform projects.
13463 For those adding visibility support to existing code, you may find
13464 @samp{#pragma GCC visibility} of use. This works by you enclosing
13465 the declarations you wish to set visibility for with (for example)
13466 @samp{#pragma GCC visibility push(hidden)} and
13467 @samp{#pragma GCC visibility pop}.
13468 Bear in mind that symbol visibility should be viewed @strong{as
13469 part of the API interface contract} and thus all new code should
13470 always specify visibility when it is not the default ie; declarations
13471 only for use within the local DSO should @strong{always} be marked explicitly
13472 as hidden as so to avoid PLT indirection overheads---making this
13473 abundantly clear also aids readability and self-documentation of the code.
13474 Note that due to ISO C++ specification requirements, operator new and
13475 operator delete must always be of default visibility.
13477 Be aware that headers from outside your project, in particular system
13478 headers and headers from any other library you use, may not be
13479 expecting to be compiled with visibility other than the default. You
13480 may need to explicitly say @samp{#pragma GCC visibility push(default)}
13481 before including any such headers.
13483 @samp{extern} declarations are not affected by @samp{-fvisibility}, so
13484 a lot of code can be recompiled with @samp{-fvisibility=hidden} with
13485 no modifications. However, this means that calls to @samp{extern}
13486 functions with no explicit visibility will use the PLT, so it is more
13487 effective to use @samp{__attribute ((visibility))} and/or
13488 @samp{#pragma GCC visibility} to tell the compiler which @samp{extern}
13489 declarations should be treated as hidden.
13491 Note that @samp{-fvisibility} does affect C++ vague linkage
13492 entities. This means that, for instance, an exception class that will
13493 be thrown between DSOs must be explicitly marked with default
13494 visibility so that the @samp{type_info} nodes will be unified between
13497 An overview of these techniques, their benefits and how to use them
13498 is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
13504 @node Environment Variables
13505 @section Environment Variables Affecting GCC
13506 @cindex environment variables
13508 @c man begin ENVIRONMENT
13509 This section describes several environment variables that affect how GCC
13510 operates. Some of them work by specifying directories or prefixes to use
13511 when searching for various kinds of files. Some are used to specify other
13512 aspects of the compilation environment.
13514 Note that you can also specify places to search using options such as
13515 @option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
13516 take precedence over places specified using environment variables, which
13517 in turn take precedence over those specified by the configuration of GCC@.
13518 @xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
13519 GNU Compiler Collection (GCC) Internals}.
13524 @c @itemx LC_COLLATE
13526 @c @itemx LC_MONETARY
13527 @c @itemx LC_NUMERIC
13532 @c @findex LC_COLLATE
13533 @findex LC_MESSAGES
13534 @c @findex LC_MONETARY
13535 @c @findex LC_NUMERIC
13539 These environment variables control the way that GCC uses
13540 localization information that allow GCC to work with different
13541 national conventions. GCC inspects the locale categories
13542 @env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
13543 so. These locale categories can be set to any value supported by your
13544 installation. A typical value is @samp{en_GB.UTF-8} for English in the United
13545 Kingdom encoded in UTF-8.
13547 The @env{LC_CTYPE} environment variable specifies character
13548 classification. GCC uses it to determine the character boundaries in
13549 a string; this is needed for some multibyte encodings that contain quote
13550 and escape characters that would otherwise be interpreted as a string
13553 The @env{LC_MESSAGES} environment variable specifies the language to
13554 use in diagnostic messages.
13556 If the @env{LC_ALL} environment variable is set, it overrides the value
13557 of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
13558 and @env{LC_MESSAGES} default to the value of the @env{LANG}
13559 environment variable. If none of these variables are set, GCC
13560 defaults to traditional C English behavior.
13564 If @env{TMPDIR} is set, it specifies the directory to use for temporary
13565 files. GCC uses temporary files to hold the output of one stage of
13566 compilation which is to be used as input to the next stage: for example,
13567 the output of the preprocessor, which is the input to the compiler
13570 @item GCC_EXEC_PREFIX
13571 @findex GCC_EXEC_PREFIX
13572 If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
13573 names of the subprograms executed by the compiler. No slash is added
13574 when this prefix is combined with the name of a subprogram, but you can
13575 specify a prefix that ends with a slash if you wish.
13577 If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
13578 an appropriate prefix to use based on the pathname it was invoked with.
13580 If GCC cannot find the subprogram using the specified prefix, it
13581 tries looking in the usual places for the subprogram.
13583 The default value of @env{GCC_EXEC_PREFIX} is
13584 @file{@var{prefix}/lib/gcc/} where @var{prefix} is the value
13585 of @code{prefix} when you ran the @file{configure} script.
13587 Other prefixes specified with @option{-B} take precedence over this prefix.
13589 This prefix is also used for finding files such as @file{crt0.o} that are
13592 In addition, the prefix is used in an unusual way in finding the
13593 directories to search for header files. For each of the standard
13594 directories whose name normally begins with @samp{/usr/local/lib/gcc}
13595 (more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
13596 replacing that beginning with the specified prefix to produce an
13597 alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
13598 @file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
13599 These alternate directories are searched first; the standard directories
13602 @item COMPILER_PATH
13603 @findex COMPILER_PATH
13604 The value of @env{COMPILER_PATH} is a colon-separated list of
13605 directories, much like @env{PATH}. GCC tries the directories thus
13606 specified when searching for subprograms, if it can't find the
13607 subprograms using @env{GCC_EXEC_PREFIX}.
13610 @findex LIBRARY_PATH
13611 The value of @env{LIBRARY_PATH} is a colon-separated list of
13612 directories, much like @env{PATH}. When configured as a native compiler,
13613 GCC tries the directories thus specified when searching for special
13614 linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking
13615 using GCC also uses these directories when searching for ordinary
13616 libraries for the @option{-l} option (but directories specified with
13617 @option{-L} come first).
13621 @cindex locale definition
13622 This variable is used to pass locale information to the compiler. One way in
13623 which this information is used is to determine the character set to be used
13624 when character literals, string literals and comments are parsed in C and C++.
13625 When the compiler is configured to allow multibyte characters,
13626 the following values for @env{LANG} are recognized:
13630 Recognize JIS characters.
13632 Recognize SJIS characters.
13634 Recognize EUCJP characters.
13637 If @env{LANG} is not defined, or if it has some other value, then the
13638 compiler will use mblen and mbtowc as defined by the default locale to
13639 recognize and translate multibyte characters.
13643 Some additional environments variables affect the behavior of the
13646 @include cppenv.texi
13650 @node Precompiled Headers
13651 @section Using Precompiled Headers
13652 @cindex precompiled headers
13653 @cindex speed of compilation
13655 Often large projects have many header files that are included in every
13656 source file. The time the compiler takes to process these header files
13657 over and over again can account for nearly all of the time required to
13658 build the project. To make builds faster, GCC allows users to
13659 `precompile' a header file; then, if builds can use the precompiled
13660 header file they will be much faster.
13662 To create a precompiled header file, simply compile it as you would any
13663 other file, if necessary using the @option{-x} option to make the driver
13664 treat it as a C or C++ header file. You will probably want to use a
13665 tool like @command{make} to keep the precompiled header up-to-date when
13666 the headers it contains change.
13668 A precompiled header file will be searched for when @code{#include} is
13669 seen in the compilation. As it searches for the included file
13670 (@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
13671 compiler looks for a precompiled header in each directory just before it
13672 looks for the include file in that directory. The name searched for is
13673 the name specified in the @code{#include} with @samp{.gch} appended. If
13674 the precompiled header file can't be used, it is ignored.
13676 For instance, if you have @code{#include "all.h"}, and you have
13677 @file{all.h.gch} in the same directory as @file{all.h}, then the
13678 precompiled header file will be used if possible, and the original
13679 header will be used otherwise.
13681 Alternatively, you might decide to put the precompiled header file in a
13682 directory and use @option{-I} to ensure that directory is searched
13683 before (or instead of) the directory containing the original header.
13684 Then, if you want to check that the precompiled header file is always
13685 used, you can put a file of the same name as the original header in this
13686 directory containing an @code{#error} command.
13688 This also works with @option{-include}. So yet another way to use
13689 precompiled headers, good for projects not designed with precompiled
13690 header files in mind, is to simply take most of the header files used by
13691 a project, include them from another header file, precompile that header
13692 file, and @option{-include} the precompiled header. If the header files
13693 have guards against multiple inclusion, they will be skipped because
13694 they've already been included (in the precompiled header).
13696 If you need to precompile the same header file for different
13697 languages, targets, or compiler options, you can instead make a
13698 @emph{directory} named like @file{all.h.gch}, and put each precompiled
13699 header in the directory, perhaps using @option{-o}. It doesn't matter
13700 what you call the files in the directory, every precompiled header in
13701 the directory will be considered. The first precompiled header
13702 encountered in the directory that is valid for this compilation will
13703 be used; they're searched in no particular order.
13705 There are many other possibilities, limited only by your imagination,
13706 good sense, and the constraints of your build system.
13708 A precompiled header file can be used only when these conditions apply:
13712 Only one precompiled header can be used in a particular compilation.
13715 A precompiled header can't be used once the first C token is seen. You
13716 can have preprocessor directives before a precompiled header; you can
13717 even include a precompiled header from inside another header, so long as
13718 there are no C tokens before the @code{#include}.
13721 The precompiled header file must be produced for the same language as
13722 the current compilation. You can't use a C precompiled header for a C++
13726 The precompiled header file must have been produced by the same compiler
13727 binary as the current compilation is using.
13730 Any macros defined before the precompiled header is included must
13731 either be defined in the same way as when the precompiled header was
13732 generated, or must not affect the precompiled header, which usually
13733 means that they don't appear in the precompiled header at all.
13735 The @option{-D} option is one way to define a macro before a
13736 precompiled header is included; using a @code{#define} can also do it.
13737 There are also some options that define macros implicitly, like
13738 @option{-O} and @option{-Wdeprecated}; the same rule applies to macros
13741 @item If debugging information is output when using the precompiled
13742 header, using @option{-g} or similar, the same kind of debugging information
13743 must have been output when building the precompiled header. However,
13744 a precompiled header built using @option{-g} can be used in a compilation
13745 when no debugging information is being output.
13747 @item The same @option{-m} options must generally be used when building
13748 and using the precompiled header. @xref{Submodel Options},
13749 for any cases where this rule is relaxed.
13751 @item Each of the following options must be the same when building and using
13752 the precompiled header:
13754 @gccoptlist{-fexceptions -funit-at-a-time}
13757 Some other command-line options starting with @option{-f},
13758 @option{-p}, or @option{-O} must be defined in the same way as when
13759 the precompiled header was generated. At present, it's not clear
13760 which options are safe to change and which are not; the safest choice
13761 is to use exactly the same options when generating and using the
13762 precompiled header. The following are known to be safe:
13764 @gccoptlist{-fmessage-length= -fpreprocessed
13765 -fsched-interblock -fsched-spec -fsched-spec-load -fsched-spec-load-dangerous
13766 -fsched-verbose=<number> -fschedule-insns -fvisibility=
13771 For all of these except the last, the compiler will automatically
13772 ignore the precompiled header if the conditions aren't met. If you
13773 find an option combination that doesn't work and doesn't cause the
13774 precompiled header to be ignored, please consider filing a bug report,
13777 If you do use differing options when generating and using the
13778 precompiled header, the actual behavior will be a mixture of the
13779 behavior for the options. For instance, if you use @option{-g} to
13780 generate the precompiled header but not when using it, you may or may
13781 not get debugging information for routines in the precompiled header.
13783 @node Running Protoize
13784 @section Running Protoize
13786 The program @code{protoize} is an optional part of GCC@. You can use
13787 it to add prototypes to a program, thus converting the program to ISO
13788 C in one respect. The companion program @code{unprotoize} does the
13789 reverse: it removes argument types from any prototypes that are found.
13791 When you run these programs, you must specify a set of source files as
13792 command line arguments. The conversion programs start out by compiling
13793 these files to see what functions they define. The information gathered
13794 about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
13796 After scanning comes actual conversion. The specified files are all
13797 eligible to be converted; any files they include (whether sources or
13798 just headers) are eligible as well.
13800 But not all the eligible files are converted. By default,
13801 @code{protoize} and @code{unprotoize} convert only source and header
13802 files in the current directory. You can specify additional directories
13803 whose files should be converted with the @option{-d @var{directory}}
13804 option. You can also specify particular files to exclude with the
13805 @option{-x @var{file}} option. A file is converted if it is eligible, its
13806 directory name matches one of the specified directory names, and its
13807 name within the directory has not been excluded.
13809 Basic conversion with @code{protoize} consists of rewriting most
13810 function definitions and function declarations to specify the types of
13811 the arguments. The only ones not rewritten are those for varargs
13814 @code{protoize} optionally inserts prototype declarations at the
13815 beginning of the source file, to make them available for any calls that
13816 precede the function's definition. Or it can insert prototype
13817 declarations with block scope in the blocks where undeclared functions
13820 Basic conversion with @code{unprotoize} consists of rewriting most
13821 function declarations to remove any argument types, and rewriting
13822 function definitions to the old-style pre-ISO form.
13824 Both conversion programs print a warning for any function declaration or
13825 definition that they can't convert. You can suppress these warnings
13828 The output from @code{protoize} or @code{unprotoize} replaces the
13829 original source file. The original file is renamed to a name ending
13830 with @samp{.save} (for DOS, the saved filename ends in @samp{.sav}
13831 without the original @samp{.c} suffix). If the @samp{.save} (@samp{.sav}
13832 for DOS) file already exists, then the source file is simply discarded.
13834 @code{protoize} and @code{unprotoize} both depend on GCC itself to
13835 scan the program and collect information about the functions it uses.
13836 So neither of these programs will work until GCC is installed.
13838 Here is a table of the options you can use with @code{protoize} and
13839 @code{unprotoize}. Each option works with both programs unless
13843 @item -B @var{directory}
13844 Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
13845 usual directory (normally @file{/usr/local/lib}). This file contains
13846 prototype information about standard system functions. This option
13847 applies only to @code{protoize}.
13849 @item -c @var{compilation-options}
13850 Use @var{compilation-options} as the options when running @command{gcc} to
13851 produce the @samp{.X} files. The special option @option{-aux-info} is
13852 always passed in addition, to tell @command{gcc} to write a @samp{.X} file.
13854 Note that the compilation options must be given as a single argument to
13855 @code{protoize} or @code{unprotoize}. If you want to specify several
13856 @command{gcc} options, you must quote the entire set of compilation options
13857 to make them a single word in the shell.
13859 There are certain @command{gcc} arguments that you cannot use, because they
13860 would produce the wrong kind of output. These include @option{-g},
13861 @option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in
13862 the @var{compilation-options}, they are ignored.
13865 Rename files to end in @samp{.C} (@samp{.cc} for DOS-based file
13866 systems) instead of @samp{.c}. This is convenient if you are converting
13867 a C program to C++. This option applies only to @code{protoize}.
13870 Add explicit global declarations. This means inserting explicit
13871 declarations at the beginning of each source file for each function
13872 that is called in the file and was not declared. These declarations
13873 precede the first function definition that contains a call to an
13874 undeclared function. This option applies only to @code{protoize}.
13876 @item -i @var{string}
13877 Indent old-style parameter declarations with the string @var{string}.
13878 This option applies only to @code{protoize}.
13880 @code{unprotoize} converts prototyped function definitions to old-style
13881 function definitions, where the arguments are declared between the
13882 argument list and the initial @samp{@{}. By default, @code{unprotoize}
13883 uses five spaces as the indentation. If you want to indent with just
13884 one space instead, use @option{-i " "}.
13887 Keep the @samp{.X} files. Normally, they are deleted after conversion
13891 Add explicit local declarations. @code{protoize} with @option{-l} inserts
13892 a prototype declaration for each function in each block which calls the
13893 function without any declaration. This option applies only to
13897 Make no real changes. This mode just prints information about the conversions
13898 that would have been done without @option{-n}.
13901 Make no @samp{.save} files. The original files are simply deleted.
13902 Use this option with caution.
13904 @item -p @var{program}
13905 Use the program @var{program} as the compiler. Normally, the name
13906 @file{gcc} is used.
13909 Work quietly. Most warnings are suppressed.
13912 Print the version number, just like @option{-v} for @command{gcc}.
13915 If you need special compiler options to compile one of your program's
13916 source files, then you should generate that file's @samp{.X} file
13917 specially, by running @command{gcc} on that source file with the
13918 appropriate options and the option @option{-aux-info}. Then run
13919 @code{protoize} on the entire set of files. @code{protoize} will use
13920 the existing @samp{.X} file because it is newer than the source file.
13924 gcc -Dfoo=bar file1.c -aux-info file1.X
13929 You need to include the special files along with the rest in the
13930 @code{protoize} command, even though their @samp{.X} files already
13931 exist, because otherwise they won't get converted.
13933 @xref{Protoize Caveats}, for more information on how to use
13934 @code{protoize} successfully.