Relocation (= move+destroy)
[official-gcc.git] / gcc / doc / invoke.texi
blob57491f1033cf0ce6e1439c0c03b7503c198597ce
1 @c Copyright (C) 1988-2018 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
5 @ignore
6 @c man begin INCLUDE
7 @include gcc-vers.texi
8 @c man end
10 @c man begin COPYRIGHT
11 Copyright @copyright{} 1988-2018 Free Software Foundation, Inc.
13 Permission is granted to copy, distribute and/or modify this document
14 under the terms of the GNU Free Documentation License, Version 1.3 or
15 any later version published by the Free Software Foundation; with the
16 Invariant Sections being ``GNU General Public License'' and ``Funding
17 Free Software'', the Front-Cover texts being (a) (see below), and with
18 the Back-Cover Texts being (b) (see below).  A copy of the license is
19 included in the gfdl(7) man page.
21 (a) The FSF's Front-Cover Text is:
23      A GNU Manual
25 (b) The FSF's Back-Cover Text is:
27      You have freedom to copy and modify this GNU Manual, like GNU
28      software.  Copies published by the Free Software Foundation raise
29      funds for GNU development.
30 @c man end
31 @c Set file name and title for the man page.
32 @setfilename gcc
33 @settitle GNU project C and C++ compiler
34 @c man begin SYNOPSIS
35 gcc [@option{-c}|@option{-S}|@option{-E}] [@option{-std=}@var{standard}]
36     [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
37     [@option{-W}@var{warn}@dots{}] [@option{-Wpedantic}]
38     [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
39     [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
40     [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
41     [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}
43 Only the most useful options are listed here; see below for the
44 remainder.  @command{g++} accepts mostly the same options as @command{gcc}.
45 @c man end
46 @c man begin SEEALSO
47 gpl(7), gfdl(7), fsf-funding(7),
48 cpp(1), gcov(1), as(1), ld(1), gdb(1), dbx(1)
49 and the Info entries for @file{gcc}, @file{cpp}, @file{as},
50 @file{ld}, @file{binutils} and @file{gdb}.
51 @c man end
52 @c man begin BUGS
53 For instructions on reporting bugs, see
54 @w{@value{BUGURL}}.
55 @c man end
56 @c man begin AUTHOR
57 See the Info entry for @command{gcc}, or
58 @w{@uref{http://gcc.gnu.org/onlinedocs/gcc/Contributors.html}},
59 for contributors to GCC@.
60 @c man end
61 @end ignore
63 @node Invoking GCC
64 @chapter GCC Command Options
65 @cindex GCC command options
66 @cindex command options
67 @cindex options, GCC command
69 @c man begin DESCRIPTION
70 When you invoke GCC, it normally does preprocessing, compilation,
71 assembly and linking.  The ``overall options'' allow you to stop this
72 process at an intermediate stage.  For example, the @option{-c} option
73 says not to run the linker.  Then the output consists of object files
74 output by the assembler.
75 @xref{Overall Options,,Options Controlling the Kind of Output}.
77 Other options are passed on to one or more stages of processing.  Some options
78 control the preprocessor and others the compiler itself.  Yet other
79 options control the assembler and linker; most of these are not
80 documented here, since you rarely need to use any of them.
82 @cindex C compilation options
83 Most of the command-line options that you can use with GCC are useful
84 for C programs; when an option is only useful with another language
85 (usually C++), the explanation says so explicitly.  If the description
86 for a particular option does not mention a source language, you can use
87 that option with all supported languages.
89 @cindex cross compiling
90 @cindex specifying machine version
91 @cindex specifying compiler version and target machine
92 @cindex compiler version, specifying
93 @cindex target machine, specifying
94 The usual way to run GCC is to run the executable called @command{gcc}, or
95 @command{@var{machine}-gcc} when cross-compiling, or
96 @command{@var{machine}-gcc-@var{version}} to run a specific version of GCC.
97 When you compile C++ programs, you should invoke GCC as @command{g++} 
98 instead.  @xref{Invoking G++,,Compiling C++ Programs}, 
99 for information about the differences in behavior between @command{gcc} 
100 and @code{g++} when compiling C++ programs.
102 @cindex grouping options
103 @cindex options, grouping
104 The @command{gcc} program accepts options and file names as operands.  Many
105 options have multi-letter names; therefore multiple single-letter options
106 may @emph{not} be grouped: @option{-dv} is very different from @w{@samp{-d
107 -v}}.
109 @cindex order of options
110 @cindex options, order
111 You can mix options and other arguments.  For the most part, the order
112 you use doesn't matter.  Order does matter when you use several
113 options of the same kind; for example, if you specify @option{-L} more
114 than once, the directories are searched in the order specified.  Also,
115 the placement of the @option{-l} option is significant.
117 Many options have long names starting with @samp{-f} or with
118 @samp{-W}---for example,
119 @option{-fmove-loop-invariants}, @option{-Wformat} and so on.  Most of
120 these have both positive and negative forms; the negative form of
121 @option{-ffoo} is @option{-fno-foo}.  This manual documents
122 only one of these two forms, whichever one is not the default.
124 Some options take one or more arguments typically separated either
125 by a space or by the equals sign (@samp{=}) from the option name.
126 Unless documented otherwise, an argument can be either numeric or
127 a string.  Numeric arguments must typically be small unsigned decimal
128 or hexadecimal integers.  Hexadecimal arguments must begin with
129 the @samp{0x} prefix.  Arguments to options that specify a size
130 threshold of some sort may be arbitrarily large decimal or hexadecimal
131 integers followed by a byte size suffix designating a multiple of bytes
132 such as @code{kB} and @code{KiB} for kilobyte and kibibyte, respectively,
133 @code{MB} and @code{MiB} for megabyte and mebibyte, @code{GB} and
134 @code{GiB} for gigabyte and gigibyte, and so on.  Such arguments are
135 designated by @var{byte-size} in the following text.  Refer to the NIST,
136 IEC, and other relevant national and international standards for the full
137 listing and explanation of the binary and decimal byte size prefixes.
139 @c man end
141 @xref{Option Index}, for an index to GCC's options.
143 @menu
144 * Option Summary::      Brief list of all options, without explanations.
145 * Overall Options::     Controlling the kind of output:
146                         an executable, object files, assembler files,
147                         or preprocessed source.
148 * Invoking G++::        Compiling C++ programs.
149 * C Dialect Options::   Controlling the variant of C language compiled.
150 * C++ Dialect Options:: Variations on C++.
151 * Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
152                         and Objective-C++.
153 * Diagnostic Message Formatting Options:: Controlling how diagnostics should
154                         be formatted.
155 * Warning Options::     How picky should the compiler be?
156 * Debugging Options::   Producing debuggable code.
157 * Optimize Options::    How much optimization?
158 * Instrumentation Options:: Enabling profiling and extra run-time error checking.
159 * Preprocessor Options:: Controlling header files and macro definitions.
160                          Also, getting dependency information for Make.
161 * Assembler Options::   Passing options to the assembler.
162 * Link Options::        Specifying libraries and so on.
163 * Directory Options::   Where to find header files and libraries.
164                         Where to find the compiler executable files.
165 * Code Gen Options::    Specifying conventions for function calls, data layout
166                         and register usage.
167 * Developer Options::   Printing GCC configuration info, statistics, and
168                         debugging dumps.
169 * Submodel Options::    Target-specific options, such as compiling for a
170                         specific processor variant.
171 * Spec Files::          How to pass switches to sub-processes.
172 * Environment Variables:: Env vars that affect GCC.
173 * Precompiled Headers:: Compiling a header once, and using it many times.
174 @end menu
176 @c man begin OPTIONS
178 @node Option Summary
179 @section Option Summary
181 Here is a summary of all the options, grouped by type.  Explanations are
182 in the following sections.
184 @table @emph
185 @item Overall Options
186 @xref{Overall Options,,Options Controlling the Kind of Output}.
187 @gccoptlist{-c  -S  -E  -o @var{file}  -x @var{language}  @gol
188 -v  -###  --help@r{[}=@var{class}@r{[},@dots{}@r{]]}  --target-help  --version @gol
189 -pass-exit-codes  -pipe  -specs=@var{file}  -wrapper  @gol
190 @@@var{file}  -ffile-prefix-map=@var{old}=@var{new}  @gol
191 -fplugin=@var{file}  -fplugin-arg-@var{name}=@var{arg}  @gol
192 -fdump-ada-spec@r{[}-slim@r{]}  -fada-spec-parent=@var{unit}  -fdump-go-spec=@var{file}}
194 @item C Language Options
195 @xref{C Dialect Options,,Options Controlling C Dialect}.
196 @gccoptlist{-ansi  -std=@var{standard}  -fgnu89-inline @gol
197 -fpermitted-flt-eval-methods=@var{standard} @gol
198 -aux-info @var{filename}  -fallow-parameterless-variadic-functions @gol
199 -fno-asm  -fno-builtin  -fno-builtin-@var{function}  -fgimple@gol
200 -fhosted  -ffreestanding  -fopenacc  -fopenmp  -fopenmp-simd @gol
201 -fms-extensions  -fplan9-extensions  -fsso-struct=@var{endianness} @gol
202 -fallow-single-precision  -fcond-mismatch  -flax-vector-conversions @gol
203 -fsigned-bitfields  -fsigned-char @gol
204 -funsigned-bitfields  -funsigned-char}
206 @item C++ Language Options
207 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
208 @gccoptlist{-fabi-version=@var{n}  -fno-access-control @gol
209 -faligned-new=@var{n}  -fargs-in-order=@var{n}  -fcheck-new @gol
210 -fconstexpr-depth=@var{n}  -fconstexpr-loop-limit=@var{n} @gol
211 -fno-elide-constructors @gol
212 -fno-enforce-eh-specs @gol
213 -fno-gnu-keywords @gol
214 -fno-implicit-templates @gol
215 -fno-implicit-inline-templates @gol
216 -fno-implement-inlines  -fms-extensions @gol
217 -fnew-inheriting-ctors @gol
218 -fnew-ttp-matching @gol
219 -fno-nonansi-builtins  -fnothrow-opt  -fno-operator-names @gol
220 -fno-optional-diags  -fpermissive @gol
221 -fno-pretty-templates @gol
222 -frepo  -fno-rtti  -fsized-deallocation @gol
223 -ftemplate-backtrace-limit=@var{n} @gol
224 -ftemplate-depth=@var{n} @gol
225 -fno-threadsafe-statics  -fuse-cxa-atexit @gol
226 -fno-weak  -nostdinc++ @gol
227 -fvisibility-inlines-hidden @gol
228 -fvisibility-ms-compat @gol
229 -fext-numeric-literals @gol
230 -Wabi=@var{n}  -Wabi-tag  -Wconversion-null  -Wctor-dtor-privacy @gol
231 -Wdelete-non-virtual-dtor -Wdeprecated-copy  -Wliteral-suffix @gol
232 -Wmultiple-inheritance -Wno-init-list-lifetime @gol
233 -Wnamespaces  -Wnarrowing @gol
234 -Wpessimizing-move  -Wredundant-move @gol
235 -Wnoexcept  -Wnoexcept-type  -Wclass-memaccess @gol
236 -Wnon-virtual-dtor  -Wreorder  -Wregister @gol
237 -Weffc++  -Wstrict-null-sentinel  -Wtemplates @gol
238 -Wno-non-template-friend  -Wold-style-cast @gol
239 -Woverloaded-virtual  -Wno-pmf-conversions @gol
240 -Wno-class-conversion  -Wno-terminate @gol
241 -Wsign-promo  -Wvirtual-inheritance}
243 @item Objective-C and Objective-C++ Language Options
244 @xref{Objective-C and Objective-C++ Dialect Options,,Options Controlling
245 Objective-C and Objective-C++ Dialects}.
246 @gccoptlist{-fconstant-string-class=@var{class-name} @gol
247 -fgnu-runtime  -fnext-runtime @gol
248 -fno-nil-receivers @gol
249 -fobjc-abi-version=@var{n} @gol
250 -fobjc-call-cxx-cdtors @gol
251 -fobjc-direct-dispatch @gol
252 -fobjc-exceptions @gol
253 -fobjc-gc @gol
254 -fobjc-nilcheck @gol
255 -fobjc-std=objc1 @gol
256 -fno-local-ivars @gol
257 -fivar-visibility=@r{[}public@r{|}protected@r{|}private@r{|}package@r{]} @gol
258 -freplace-objc-classes @gol
259 -fzero-link @gol
260 -gen-decls @gol
261 -Wassign-intercept @gol
262 -Wno-protocol  -Wselector @gol
263 -Wstrict-selector-match @gol
264 -Wundeclared-selector}
266 @item Diagnostic Message Formatting Options
267 @xref{Diagnostic Message Formatting Options,,Options to Control Diagnostic Messages Formatting}.
268 @gccoptlist{-fmessage-length=@var{n}  @gol
269 -fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]}  @gol
270 -fdiagnostics-color=@r{[}auto@r{|}never@r{|}always@r{]}  @gol
271 -fno-diagnostics-show-option  -fno-diagnostics-show-caret @gol
272 -fno-diagnostics-show-labels -fno-diagnostics-show-line-numbers @gol
273 -fdiagnostics-minimum-margin-width=@var{width} @gol
274 -fdiagnostics-parseable-fixits  -fdiagnostics-generate-patch @gol
275 -fdiagnostics-show-template-tree -fno-elide-type @gol
276 -fno-show-column}
278 @item Warning Options
279 @xref{Warning Options,,Options to Request or Suppress Warnings}.
280 @gccoptlist{-fsyntax-only  -fmax-errors=@var{n}  -Wpedantic @gol
281 -pedantic-errors @gol
282 -w  -Wextra  -Wall  -Waddress  -Waggregate-return  -Waligned-new @gol
283 -Walloc-zero  -Walloc-size-larger-than=@var{byte-size}
284 -Walloca  -Walloca-larger-than=@var{byte-size} @gol
285 -Wno-aggressive-loop-optimizations  -Warray-bounds  -Warray-bounds=@var{n} @gol
286 -Wno-attributes  -Wbool-compare  -Wbool-operation @gol
287 -Wno-builtin-declaration-mismatch @gol
288 -Wno-builtin-macro-redefined  -Wc90-c99-compat  -Wc99-c11-compat @gol
289 -Wc++-compat  -Wc++11-compat  -Wc++14-compat  -Wc++17-compat  @gol
290 -Wcast-align  -Wcast-align=strict  -Wcast-function-type  -Wcast-qual  @gol
291 -Wchar-subscripts  -Wcatch-value  -Wcatch-value=@var{n} @gol
292 -Wclobbered  -Wcomment  -Wconditionally-supported @gol
293 -Wconversion  -Wcoverage-mismatch  -Wno-cpp  -Wdangling-else  -Wdate-time @gol
294 -Wdelete-incomplete @gol
295 -Wno-deprecated  -Wno-deprecated-declarations  -Wno-designated-init @gol
296 -Wdisabled-optimization @gol
297 -Wno-discarded-qualifiers  -Wno-discarded-array-qualifiers @gol
298 -Wno-div-by-zero  -Wdouble-promotion @gol
299 -Wduplicated-branches  -Wduplicated-cond @gol
300 -Wempty-body  -Wenum-compare  -Wno-endif-labels  -Wexpansion-to-defined @gol
301 -Werror  -Werror=*  -Wextra-semi  -Wfatal-errors @gol
302 -Wfloat-equal  -Wformat  -Wformat=2 @gol
303 -Wno-format-contains-nul  -Wno-format-extra-args  @gol
304 -Wformat-nonliteral -Wformat-overflow=@var{n} @gol
305 -Wformat-security  -Wformat-signedness  -Wformat-truncation=@var{n} @gol
306 -Wformat-y2k  -Wframe-address @gol
307 -Wframe-larger-than=@var{byte-size}  -Wno-free-nonheap-object @gol
308 -Wjump-misses-init @gol
309 -Wif-not-aligned @gol
310 -Wignored-qualifiers  -Wignored-attributes  -Wincompatible-pointer-types @gol
311 -Wimplicit  -Wimplicit-fallthrough  -Wimplicit-fallthrough=@var{n} @gol
312 -Wimplicit-function-declaration  -Wimplicit-int @gol
313 -Winit-self  -Winline  -Wno-int-conversion  -Wint-in-bool-context @gol
314 -Wno-int-to-pointer-cast  -Winvalid-memory-model  -Wno-invalid-offsetof @gol
315 -Winvalid-pch  -Wlarger-than=@var{byte-size} @gol
316 -Wlogical-op  -Wlogical-not-parentheses  -Wlong-long @gol
317 -Wmain  -Wmaybe-uninitialized  -Wmemset-elt-size  -Wmemset-transposed-args @gol
318 -Wmisleading-indentation  -Wmissing-attributes -Wmissing-braces @gol
319 -Wmissing-field-initializers  -Wmissing-include-dirs  -Wmissing-profile @gol
320 -Wno-multichar  -Wmultistatement-macros  -Wnonnull  -Wnonnull-compare @gol
321 -Wnormalized=@r{[}none@r{|}id@r{|}nfc@r{|}nfkc@r{]} @gol
322 -Wnull-dereference  -Wodr  -Wno-overflow  -Wopenmp-simd  @gol
323 -Woverride-init-side-effects  -Woverlength-strings @gol
324 -Wpacked  -Wpacked-bitfield-compat -Wpacked-not-aligned -Wpadded @gol
325 -Wparentheses  -Wno-pedantic-ms-format @gol
326 -Wplacement-new  -Wplacement-new=@var{n} @gol
327 -Wpointer-arith  -Wpointer-compare  -Wno-pointer-to-int-cast @gol
328 -Wno-pragmas  -Wno-prio-ctor-dtor -Wredundant-decls @gol
329 -Wrestrict  -Wno-return-local-addr @gol
330 -Wreturn-type  -Wsequence-point  -Wshadow  -Wno-shadow-ivar @gol
331 -Wshadow=global,  -Wshadow=local,  -Wshadow=compatible-local @gol
332 -Wshift-overflow  -Wshift-overflow=@var{n} @gol
333 -Wshift-count-negative  -Wshift-count-overflow  -Wshift-negative-value @gol
334 -Wsign-compare  -Wsign-conversion  -Wfloat-conversion @gol
335 -Wno-scalar-storage-order  -Wsizeof-pointer-div @gol
336 -Wsizeof-pointer-memaccess  -Wsizeof-array-argument @gol
337 -Wstack-protector  -Wstack-usage=@var{byte-size}  -Wstrict-aliasing @gol
338 -Wstrict-aliasing=n  -Wstrict-overflow  -Wstrict-overflow=@var{n} @gol
339 -Wstringop-overflow=@var{n} -Wstringop-truncation @gol
340 -Wsuggest-attribute=@r{[}pure@r{|}const@r{|}noreturn@r{|}format@r{|}malloc@r{]} @gol
341 -Wsuggest-final-types @gol  -Wsuggest-final-methods  -Wsuggest-override @gol
342 -Wmissing-format-attribute  -Wsubobject-linkage @gol
343 -Wswitch  -Wswitch-bool  -Wswitch-default  -Wswitch-enum @gol
344 -Wswitch-unreachable  -Wsync-nand @gol
345 -Wsystem-headers  -Wtautological-compare  -Wtrampolines  -Wtrigraphs @gol
346 -Wtype-limits  -Wundef @gol
347 -Wuninitialized  -Wunknown-pragmas @gol
348 -Wunsuffixed-float-constants  -Wunused  -Wunused-function @gol
349 -Wunused-label  -Wunused-local-typedefs  -Wunused-macros @gol
350 -Wunused-parameter  -Wno-unused-result @gol
351 -Wunused-value  -Wunused-variable @gol
352 -Wunused-const-variable  -Wunused-const-variable=@var{n} @gol
353 -Wunused-but-set-parameter  -Wunused-but-set-variable @gol
354 -Wuseless-cast  -Wvariadic-macros  -Wvector-operation-performance @gol
355 -Wvla  -Wvla-larger-than=@var{byte-size}  -Wvolatile-register-var @gol
356 -Wwrite-strings @gol
357 -Wzero-as-null-pointer-constant  -Whsa}
359 @item C and Objective-C-only Warning Options
360 @gccoptlist{-Wbad-function-cast  -Wmissing-declarations @gol
361 -Wmissing-parameter-type  -Wmissing-prototypes  -Wnested-externs @gol
362 -Wold-style-declaration  -Wold-style-definition @gol
363 -Wstrict-prototypes  -Wtraditional  -Wtraditional-conversion @gol
364 -Wdeclaration-after-statement  -Wpointer-sign}
366 @item Debugging Options
367 @xref{Debugging Options,,Options for Debugging Your Program}.
368 @gccoptlist{-g  -g@var{level}  -gdwarf  -gdwarf-@var{version} @gol
369 -ggdb  -grecord-gcc-switches  -gno-record-gcc-switches @gol
370 -gstabs  -gstabs+  -gstrict-dwarf  -gno-strict-dwarf @gol
371 -gas-loc-support  -gno-as-loc-support @gol
372 -gas-locview-support  -gno-as-locview-support @gol
373 -gcolumn-info  -gno-column-info @gol
374 -gstatement-frontiers  -gno-statement-frontiers @gol
375 -gvariable-location-views  -gno-variable-location-views @gol
376 -ginternal-reset-location-views  -gno-internal-reset-location-views @gol
377 -ginline-points  -gno-inline-points @gol
378 -gvms  -gxcoff  -gxcoff+  -gz@r{[}=@var{type}@r{]} @gol
379 -gsplit-dwarf -gdescribe-dies -gno-describe-dies @gol
380 -fdebug-prefix-map=@var{old}=@var{new}  -fdebug-types-section @gol
381 -fno-eliminate-unused-debug-types @gol
382 -femit-struct-debug-baseonly  -femit-struct-debug-reduced @gol
383 -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} @gol
384 -feliminate-unused-debug-symbols  -femit-class-debug-always @gol
385 -fno-merge-debug-strings  -fno-dwarf2-cfi-asm @gol
386 -fvar-tracking  -fvar-tracking-assignments}
388 @item Optimization Options
389 @xref{Optimize Options,,Options that Control Optimization}.
390 @gccoptlist{-faggressive-loop-optimizations @gol
391 -falign-functions[=@var{n}[:@var{m}:[@var{n2}[:@var{m2}]]]] @gol
392 -falign-jumps[=@var{n}[:@var{m}:[@var{n2}[:@var{m2}]]]] @gol
393 -falign-labels[=@var{n}[:@var{m}:[@var{n2}[:@var{m2}]]]] @gol
394 -falign-loops[=@var{n}[:@var{m}:[@var{n2}[:@var{m2}]]]] @gol
395 -fassociative-math  -fauto-profile  -fauto-profile[=@var{path}] @gol
396 -fauto-inc-dec  -fbranch-probabilities @gol
397 -fbranch-target-load-optimize  -fbranch-target-load-optimize2 @gol
398 -fbtr-bb-exclusive  -fcaller-saves @gol
399 -fcombine-stack-adjustments  -fconserve-stack @gol
400 -fcompare-elim  -fcprop-registers  -fcrossjumping @gol
401 -fcse-follow-jumps  -fcse-skip-blocks  -fcx-fortran-rules @gol
402 -fcx-limited-range @gol
403 -fdata-sections  -fdce  -fdelayed-branch @gol
404 -fdelete-null-pointer-checks  -fdevirtualize  -fdevirtualize-speculatively @gol
405 -fdevirtualize-at-ltrans  -fdse @gol
406 -fearly-inlining  -fipa-sra  -fexpensive-optimizations  -ffat-lto-objects @gol
407 -ffast-math  -ffinite-math-only  -ffloat-store  -fexcess-precision=@var{style} @gol
408 -fforward-propagate  -ffp-contract=@var{style}  -ffunction-sections @gol
409 -fgcse  -fgcse-after-reload  -fgcse-las  -fgcse-lm  -fgraphite-identity @gol
410 -fgcse-sm  -fhoist-adjacent-loads  -fif-conversion @gol
411 -fif-conversion2  -findirect-inlining @gol
412 -finline-functions  -finline-functions-called-once  -finline-limit=@var{n} @gol
413 -finline-small-functions  -fipa-cp  -fipa-cp-clone @gol
414 -fipa-bit-cp -fipa-vrp @gol
415 -fipa-pta  -fipa-profile  -fipa-pure-const  -fipa-reference  -fipa-icf @gol
416 -fira-algorithm=@var{algorithm} @gol
417 -fira-region=@var{region}  -fira-hoist-pressure @gol
418 -fira-loop-pressure  -fno-ira-share-save-slots @gol
419 -fno-ira-share-spill-slots @gol
420 -fisolate-erroneous-paths-dereference  -fisolate-erroneous-paths-attribute @gol
421 -fivopts  -fkeep-inline-functions  -fkeep-static-functions @gol
422 -fkeep-static-consts  -flimit-function-alignment  -flive-range-shrinkage @gol
423 -floop-block  -floop-interchange  -floop-strip-mine @gol
424 -floop-unroll-and-jam  -floop-nest-optimize @gol
425 -floop-parallelize-all  -flra-remat  -flto  -flto-compression-level @gol
426 -flto-partition=@var{alg}  -fmerge-all-constants @gol
427 -fmerge-constants  -fmodulo-sched  -fmodulo-sched-allow-regmoves @gol
428 -fmove-loop-invariants  -fno-branch-count-reg @gol
429 -fno-defer-pop  -fno-fp-int-builtin-inexact  -fno-function-cse @gol
430 -fno-guess-branch-probability  -fno-inline  -fno-math-errno  -fno-peephole @gol
431 -fno-peephole2  -fno-printf-return-value  -fno-sched-interblock @gol
432 -fno-sched-spec  -fno-signed-zeros @gol
433 -fno-toplevel-reorder  -fno-trapping-math  -fno-zero-initialized-in-bss @gol
434 -fomit-frame-pointer  -foptimize-sibling-calls @gol
435 -fpartial-inlining  -fpeel-loops  -fpredictive-commoning @gol
436 -fprefetch-loop-arrays @gol
437 -fprofile-correction @gol
438 -fprofile-use  -fprofile-use=@var{path}  -fprofile-values @gol
439 -fprofile-reorder-functions @gol
440 -freciprocal-math  -free  -frename-registers  -freorder-blocks @gol
441 -freorder-blocks-algorithm=@var{algorithm} @gol
442 -freorder-blocks-and-partition  -freorder-functions @gol
443 -frerun-cse-after-loop  -freschedule-modulo-scheduled-loops @gol
444 -frounding-math  -fsave-optimization-record @gol
445 -fsched2-use-superblocks  -fsched-pressure @gol
446 -fsched-spec-load  -fsched-spec-load-dangerous @gol
447 -fsched-stalled-insns-dep[=@var{n}]  -fsched-stalled-insns[=@var{n}] @gol
448 -fsched-group-heuristic  -fsched-critical-path-heuristic @gol
449 -fsched-spec-insn-heuristic  -fsched-rank-heuristic @gol
450 -fsched-last-insn-heuristic  -fsched-dep-count-heuristic @gol
451 -fschedule-fusion @gol
452 -fschedule-insns  -fschedule-insns2  -fsection-anchors @gol
453 -fselective-scheduling  -fselective-scheduling2 @gol
454 -fsel-sched-pipelining  -fsel-sched-pipelining-outer-loops @gol
455 -fsemantic-interposition  -fshrink-wrap  -fshrink-wrap-separate @gol
456 -fsignaling-nans @gol
457 -fsingle-precision-constant  -fsplit-ivs-in-unroller  -fsplit-loops@gol
458 -fsplit-paths @gol
459 -fsplit-wide-types  -fssa-backprop  -fssa-phiopt @gol
460 -fstdarg-opt  -fstore-merging  -fstrict-aliasing @gol
461 -fthread-jumps  -ftracer  -ftree-bit-ccp @gol
462 -ftree-builtin-call-dce  -ftree-ccp  -ftree-ch @gol
463 -ftree-coalesce-vars  -ftree-copy-prop  -ftree-dce  -ftree-dominator-opts @gol
464 -ftree-dse  -ftree-forwprop  -ftree-fre  -fcode-hoisting @gol
465 -ftree-loop-if-convert  -ftree-loop-im @gol
466 -ftree-phiprop  -ftree-loop-distribution  -ftree-loop-distribute-patterns @gol
467 -ftree-loop-ivcanon  -ftree-loop-linear  -ftree-loop-optimize @gol
468 -ftree-loop-vectorize @gol
469 -ftree-parallelize-loops=@var{n}  -ftree-pre  -ftree-partial-pre  -ftree-pta @gol
470 -ftree-reassoc  -ftree-scev-cprop  -ftree-sink  -ftree-slsr  -ftree-sra @gol
471 -ftree-switch-conversion  -ftree-tail-merge @gol
472 -ftree-ter  -ftree-vectorize  -ftree-vrp  -funconstrained-commons @gol
473 -funit-at-a-time  -funroll-all-loops  -funroll-loops @gol
474 -funsafe-math-optimizations  -funswitch-loops @gol
475 -fipa-ra  -fvariable-expansion-in-unroller  -fvect-cost-model  -fvpt @gol
476 -fweb  -fwhole-program  -fwpa  -fuse-linker-plugin @gol
477 --param @var{name}=@var{value}
478 -O  -O0  -O1  -O2  -O3  -Os  -Ofast  -Og}
480 @item Program Instrumentation Options
481 @xref{Instrumentation Options,,Program Instrumentation Options}.
482 @gccoptlist{-p  -pg  -fprofile-arcs  --coverage  -ftest-coverage @gol
483 -fprofile-abs-path @gol
484 -fprofile-dir=@var{path}  -fprofile-generate  -fprofile-generate=@var{path} @gol
485 -fsanitize=@var{style}  -fsanitize-recover  -fsanitize-recover=@var{style} @gol
486 -fasan-shadow-offset=@var{number}  -fsanitize-sections=@var{s1},@var{s2},... @gol
487 -fsanitize-undefined-trap-on-error  -fbounds-check @gol
488 -fcf-protection=@r{[}full@r{|}branch@r{|}return@r{|}none@r{]} @gol
489 -fstack-protector  -fstack-protector-all  -fstack-protector-strong @gol
490 -fstack-protector-explicit  -fstack-check @gol
491 -fstack-limit-register=@var{reg}  -fstack-limit-symbol=@var{sym} @gol
492 -fno-stack-limit  -fsplit-stack @gol
493 -fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]} @gol
494 -fvtv-counts  -fvtv-debug @gol
495 -finstrument-functions @gol
496 -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} @gol
497 -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}}
499 @item Preprocessor Options
500 @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
501 @gccoptlist{-A@var{question}=@var{answer} @gol
502 -A-@var{question}@r{[}=@var{answer}@r{]} @gol
503 -C  -CC  -D@var{macro}@r{[}=@var{defn}@r{]} @gol
504 -dD  -dI  -dM  -dN  -dU @gol
505 -fdebug-cpp  -fdirectives-only  -fdollars-in-identifiers  @gol
506 -fexec-charset=@var{charset}  -fextended-identifiers  @gol
507 -finput-charset=@var{charset} -fmacro-prefix-map=@var{old}=@var{new}  @gol
508 -fno-canonical-system-headers @gol -fpch-deps  -fpch-preprocess  @gol
509 -fpreprocessed -ftabstop=@var{width}  -ftrack-macro-expansion  @gol
510 -fwide-exec-charset=@var{charset}  -fworking-directory @gol
511 -H  -imacros @var{file}  -include @var{file} @gol
512 -M  -MD  -MF  -MG  -MM  -MMD  -MP  -MQ  -MT @gol
513 -no-integrated-cpp  -P  -pthread  -remap @gol
514 -traditional  -traditional-cpp  -trigraphs @gol
515 -U@var{macro}  -undef  @gol
516 -Wp,@var{option}  -Xpreprocessor @var{option}}
518 @item Assembler Options
519 @xref{Assembler Options,,Passing Options to the Assembler}.
520 @gccoptlist{-Wa,@var{option}  -Xassembler @var{option}}
522 @item Linker Options
523 @xref{Link Options,,Options for Linking}.
524 @gccoptlist{@var{object-file-name}  -fuse-ld=@var{linker}  -l@var{library} @gol
525 -nostartfiles  -nodefaultlibs  -nolibc  -nostdlib @gol
526 -pie  -pthread  -r  -rdynamic @gol
527 -s  -static -static-pie -static-libgcc  -static-libstdc++ @gol
528 -static-libasan  -static-libtsan  -static-liblsan  -static-libubsan @gol
529 -shared  -shared-libgcc  -symbolic @gol
530 -T @var{script}  -Wl,@var{option}  -Xlinker @var{option} @gol
531 -u @var{symbol}  -z @var{keyword}}
533 @item Directory Options
534 @xref{Directory Options,,Options for Directory Search}.
535 @gccoptlist{-B@var{prefix}  -I@var{dir}  -I- @gol
536 -idirafter @var{dir} @gol
537 -imacros @var{file}  -imultilib @var{dir} @gol
538 -iplugindir=@var{dir}  -iprefix @var{file} @gol
539 -iquote @var{dir}  -isysroot @var{dir}  -isystem @var{dir} @gol
540 -iwithprefix @var{dir}  -iwithprefixbefore @var{dir}  @gol
541 -L@var{dir}  -no-canonical-prefixes  --no-sysroot-suffix @gol
542 -nostdinc  -nostdinc++  --sysroot=@var{dir}}
544 @item Code Generation Options
545 @xref{Code Gen Options,,Options for Code Generation Conventions}.
546 @gccoptlist{-fcall-saved-@var{reg}  -fcall-used-@var{reg} @gol
547 -ffixed-@var{reg}  -fexceptions @gol
548 -fnon-call-exceptions  -fdelete-dead-exceptions  -funwind-tables @gol
549 -fasynchronous-unwind-tables @gol
550 -fno-gnu-unique @gol
551 -finhibit-size-directive  -fno-common  -fno-ident @gol
552 -fpcc-struct-return  -fpic  -fPIC  -fpie  -fPIE  -fno-plt @gol
553 -fno-jump-tables @gol
554 -frecord-gcc-switches @gol
555 -freg-struct-return  -fshort-enums  -fshort-wchar @gol
556 -fverbose-asm  -fpack-struct[=@var{n}]  @gol
557 -fleading-underscore  -ftls-model=@var{model} @gol
558 -fstack-reuse=@var{reuse_level} @gol
559 -ftrampolines  -ftrapv  -fwrapv @gol
560 -fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]} @gol
561 -fstrict-volatile-bitfields  -fsync-libcalls}
563 @item Developer Options
564 @xref{Developer Options,,GCC Developer Options}.
565 @gccoptlist{-d@var{letters}  -dumpspecs  -dumpmachine  -dumpversion @gol
566 -dumpfullversion  -fchecking  -fchecking=@var{n}  -fdbg-cnt-list @gol
567 -fdbg-cnt=@var{counter-value-list} @gol
568 -fdisable-ipa-@var{pass_name} @gol
569 -fdisable-rtl-@var{pass_name} @gol
570 -fdisable-rtl-@var{pass-name}=@var{range-list} @gol
571 -fdisable-tree-@var{pass_name} @gol
572 -fdisable-tree-@var{pass-name}=@var{range-list} @gol
573 -fdump-debug -fdump-earlydebug @gol
574 -fdump-noaddr  -fdump-unnumbered  -fdump-unnumbered-links @gol
575 -fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
576 -fdump-final-insns@r{[}=@var{file}@r{]} @gol
577 -fdump-ipa-all  -fdump-ipa-cgraph  -fdump-ipa-inline @gol
578 -fdump-lang-all @gol
579 -fdump-lang-@var{switch} @gol
580 -fdump-lang-@var{switch}-@var{options} @gol
581 -fdump-lang-@var{switch}-@var{options}=@var{filename} @gol
582 -fdump-passes @gol
583 -fdump-rtl-@var{pass}  -fdump-rtl-@var{pass}=@var{filename} @gol
584 -fdump-statistics @gol
585 -fdump-tree-all @gol
586 -fdump-tree-@var{switch} @gol
587 -fdump-tree-@var{switch}-@var{options} @gol
588 -fdump-tree-@var{switch}-@var{options}=@var{filename} @gol
589 -fcompare-debug@r{[}=@var{opts}@r{]}  -fcompare-debug-second @gol
590 -fenable-@var{kind}-@var{pass} @gol
591 -fenable-@var{kind}-@var{pass}=@var{range-list} @gol
592 -fira-verbose=@var{n} @gol
593 -flto-report  -flto-report-wpa  -fmem-report-wpa @gol
594 -fmem-report  -fpre-ipa-mem-report  -fpost-ipa-mem-report @gol
595 -fopt-info  -fopt-info-@var{options}@r{[}=@var{file}@r{]} @gol
596 -fprofile-report @gol
597 -frandom-seed=@var{string}  -fsched-verbose=@var{n} @gol
598 -fsel-sched-verbose  -fsel-sched-dump-cfg  -fsel-sched-pipelining-verbose @gol
599 -fstats  -fstack-usage  -ftime-report  -ftime-report-details @gol
600 -fvar-tracking-assignments-toggle  -gtoggle @gol
601 -print-file-name=@var{library}  -print-libgcc-file-name @gol
602 -print-multi-directory  -print-multi-lib  -print-multi-os-directory @gol
603 -print-prog-name=@var{program}  -print-search-dirs  -Q @gol
604 -print-sysroot  -print-sysroot-headers-suffix @gol
605 -save-temps  -save-temps=cwd  -save-temps=obj  -time@r{[}=@var{file}@r{]}}
607 @item Machine-Dependent Options
608 @xref{Submodel Options,,Machine-Dependent Options}.
609 @c This list is ordered alphanumerically by subsection name.
610 @c Try and put the significant identifier (CPU or system) first,
611 @c so users have a clue at guessing where the ones they want will be.
613 @emph{AArch64 Options}
614 @gccoptlist{-mabi=@var{name}  -mbig-endian  -mlittle-endian @gol
615 -mgeneral-regs-only @gol
616 -mcmodel=tiny  -mcmodel=small  -mcmodel=large @gol
617 -mstrict-align -mno-strict-align @gol
618 -momit-leaf-frame-pointer @gol
619 -mtls-dialect=desc  -mtls-dialect=traditional @gol
620 -mtls-size=@var{size} @gol
621 -mfix-cortex-a53-835769  -mfix-cortex-a53-843419 @gol
622 -mlow-precision-recip-sqrt  -mlow-precision-sqrt  -mlow-precision-div @gol
623 -mpc-relative-literal-loads @gol
624 -msign-return-address=@var{scope} @gol
625 -march=@var{name}  -mcpu=@var{name}  -mtune=@var{name}  @gol
626 -moverride=@var{string}  -mverbose-cost-dump -mtrack-speculation} 
628 @emph{Adapteva Epiphany Options}
629 @gccoptlist{-mhalf-reg-file  -mprefer-short-insn-regs @gol
630 -mbranch-cost=@var{num}  -mcmove  -mnops=@var{num}  -msoft-cmpsf @gol
631 -msplit-lohi  -mpost-inc  -mpost-modify  -mstack-offset=@var{num} @gol
632 -mround-nearest  -mlong-calls  -mshort-calls  -msmall16 @gol
633 -mfp-mode=@var{mode}  -mvect-double  -max-vect-align=@var{num} @gol
634 -msplit-vecmove-early  -m1reg-@var{reg}}
636 @emph{ARC Options}
637 @gccoptlist{-mbarrel-shifter -mjli-always @gol
638 -mcpu=@var{cpu}  -mA6  -mARC600  -mA7  -mARC700 @gol
639 -mdpfp  -mdpfp-compact  -mdpfp-fast  -mno-dpfp-lrsr @gol
640 -mea  -mno-mpy  -mmul32x16  -mmul64  -matomic @gol
641 -mnorm  -mspfp  -mspfp-compact  -mspfp-fast  -msimd  -msoft-float  -mswap @gol
642 -mcrc  -mdsp-packa  -mdvbf  -mlock  -mmac-d16  -mmac-24  -mrtsc  -mswape @gol
643 -mtelephony  -mxy  -misize  -mannotate-align  -marclinux  -marclinux_prof @gol
644 -mlong-calls  -mmedium-calls  -msdata -mirq-ctrl-saved @gol
645 -mrgf-banked-regs -mlpc-width=@var{width} -G @var{num} @gol
646 -mvolatile-cache  -mtp-regno=@var{regno} @gol
647 -malign-call  -mauto-modify-reg  -mbbit-peephole  -mno-brcc @gol
648 -mcase-vector-pcrel  -mcompact-casesi  -mno-cond-exec  -mearly-cbranchsi @gol
649 -mexpand-adddi  -mindexed-loads  -mlra  -mlra-priority-none @gol
650 -mlra-priority-compact mlra-priority-noncompact  -mno-millicode @gol
651 -mmixed-code  -mq-class  -mRcq  -mRcw  -msize-level=@var{level} @gol
652 -mtune=@var{cpu}  -mmultcost=@var{num} @gol
653 -munalign-prob-threshold=@var{probability}  -mmpy-option=@var{multo} @gol
654 -mdiv-rem  -mcode-density  -mll64  -mfpu=@var{fpu} -mrf16}
656 @emph{ARM Options}
657 @gccoptlist{-mapcs-frame  -mno-apcs-frame @gol
658 -mabi=@var{name} @gol
659 -mapcs-stack-check  -mno-apcs-stack-check @gol
660 -mapcs-reentrant  -mno-apcs-reentrant @gol
661 -msched-prolog  -mno-sched-prolog @gol
662 -mlittle-endian  -mbig-endian @gol
663 -mbe8 -mbe32 @gol
664 -mfloat-abi=@var{name} @gol
665 -mfp16-format=@var{name}
666 -mthumb-interwork  -mno-thumb-interwork @gol
667 -mcpu=@var{name}  -march=@var{name}  -mfpu=@var{name}  @gol
668 -mtune=@var{name}  -mprint-tune-info @gol
669 -mstructure-size-boundary=@var{n} @gol
670 -mabort-on-noreturn @gol
671 -mlong-calls  -mno-long-calls @gol
672 -msingle-pic-base  -mno-single-pic-base @gol
673 -mpic-register=@var{reg} @gol
674 -mnop-fun-dllimport @gol
675 -mpoke-function-name @gol
676 -mthumb  -marm  -mflip-thumb @gol
677 -mtpcs-frame  -mtpcs-leaf-frame @gol
678 -mcaller-super-interworking  -mcallee-super-interworking @gol
679 -mtp=@var{name}  -mtls-dialect=@var{dialect} @gol
680 -mword-relocations @gol
681 -mfix-cortex-m3-ldrd @gol
682 -munaligned-access @gol
683 -mneon-for-64bits @gol
684 -mslow-flash-data @gol
685 -masm-syntax-unified @gol
686 -mrestrict-it @gol
687 -mverbose-cost-dump @gol
688 -mpure-code @gol
689 -mcmse}
691 @emph{AVR Options}
692 @gccoptlist{-mmcu=@var{mcu}  -mabsdata  -maccumulate-args @gol
693 -mbranch-cost=@var{cost} @gol
694 -mcall-prologues  -mgas-isr-prologues  -mint8 @gol
695 -mn_flash=@var{size}  -mno-interrupts @gol
696 -mmain-is-OS_task -mrelax  -mrmw  -mstrict-X  -mtiny-stack @gol
697 -mfract-convert-truncate @gol
698 -mshort-calls  -nodevicelib @gol
699 -Waddr-space-convert  -Wmisspelled-isr}
701 @emph{Blackfin Options}
702 @gccoptlist{-mcpu=@var{cpu}@r{[}-@var{sirevision}@r{]} @gol
703 -msim  -momit-leaf-frame-pointer  -mno-omit-leaf-frame-pointer @gol
704 -mspecld-anomaly  -mno-specld-anomaly  -mcsync-anomaly  -mno-csync-anomaly @gol
705 -mlow-64k  -mno-low64k  -mstack-check-l1  -mid-shared-library @gol
706 -mno-id-shared-library  -mshared-library-id=@var{n} @gol
707 -mleaf-id-shared-library  -mno-leaf-id-shared-library @gol
708 -msep-data  -mno-sep-data  -mlong-calls  -mno-long-calls @gol
709 -mfast-fp  -minline-plt  -mmulticore  -mcorea  -mcoreb  -msdram @gol
710 -micplb}
712 @emph{C6X Options}
713 @gccoptlist{-mbig-endian  -mlittle-endian  -march=@var{cpu} @gol
714 -msim  -msdata=@var{sdata-type}}
716 @emph{CRIS Options}
717 @gccoptlist{-mcpu=@var{cpu}  -march=@var{cpu}  -mtune=@var{cpu} @gol
718 -mmax-stack-frame=@var{n}  -melinux-stacksize=@var{n} @gol
719 -metrax4  -metrax100  -mpdebug  -mcc-init  -mno-side-effects @gol
720 -mstack-align  -mdata-align  -mconst-align @gol
721 -m32-bit  -m16-bit  -m8-bit  -mno-prologue-epilogue  -mno-gotplt @gol
722 -melf  -maout  -melinux  -mlinux  -sim  -sim2 @gol
723 -mmul-bug-workaround  -mno-mul-bug-workaround}
725 @emph{CR16 Options}
726 @gccoptlist{-mmac @gol
727 -mcr16cplus  -mcr16c @gol
728 -msim  -mint32  -mbit-ops
729 -mdata-model=@var{model}}
731 @emph{C-SKY Options}
732 @gccoptlist{-march=@var{arch}  -mcpu=@var{cpu} @gol
733 -mbig-endian  -EB  -mlittle-endian  -EL @gol
734 -mhard-float  -msoft-float  -mfpu=@var{fpu}  -mdouble-float  -mfdivdu @gol
735 -melrw  -mistack  -mmp  -mcp  -mcache  -msecurity  -mtrust @gol
736 -mdsp  -medsp  -mvdsp @gol
737 -mdiv  -msmart  -mhigh-registers  -manchor @gol
738 -mpushpop  -mmultiple-stld  -mconstpool  -mstack-size  -mccrt @gol
739 -mbranch-cost=@var{n}  -mcse-cc  -msched-prolog}
741 @emph{Darwin Options}
742 @gccoptlist{-all_load  -allowable_client  -arch  -arch_errors_fatal @gol
743 -arch_only  -bind_at_load  -bundle  -bundle_loader @gol
744 -client_name  -compatibility_version  -current_version @gol
745 -dead_strip @gol
746 -dependency-file  -dylib_file  -dylinker_install_name @gol
747 -dynamic  -dynamiclib  -exported_symbols_list @gol
748 -filelist  -flat_namespace  -force_cpusubtype_ALL @gol
749 -force_flat_namespace  -headerpad_max_install_names @gol
750 -iframework @gol
751 -image_base  -init  -install_name  -keep_private_externs @gol
752 -multi_module  -multiply_defined  -multiply_defined_unused @gol
753 -noall_load   -no_dead_strip_inits_and_terms @gol
754 -nofixprebinding  -nomultidefs  -noprebind  -noseglinkedit @gol
755 -pagezero_size  -prebind  -prebind_all_twolevel_modules @gol
756 -private_bundle  -read_only_relocs  -sectalign @gol
757 -sectobjectsymbols  -whyload  -seg1addr @gol
758 -sectcreate  -sectobjectsymbols  -sectorder @gol
759 -segaddr  -segs_read_only_addr  -segs_read_write_addr @gol
760 -seg_addr_table  -seg_addr_table_filename  -seglinkedit @gol
761 -segprot  -segs_read_only_addr  -segs_read_write_addr @gol
762 -single_module  -static  -sub_library  -sub_umbrella @gol
763 -twolevel_namespace  -umbrella  -undefined @gol
764 -unexported_symbols_list  -weak_reference_mismatches @gol
765 -whatsloaded  -F  -gused  -gfull  -mmacosx-version-min=@var{version} @gol
766 -mkernel  -mone-byte-bool}
768 @emph{DEC Alpha Options}
769 @gccoptlist{-mno-fp-regs  -msoft-float @gol
770 -mieee  -mieee-with-inexact  -mieee-conformant @gol
771 -mfp-trap-mode=@var{mode}  -mfp-rounding-mode=@var{mode} @gol
772 -mtrap-precision=@var{mode}  -mbuild-constants @gol
773 -mcpu=@var{cpu-type}  -mtune=@var{cpu-type} @gol
774 -mbwx  -mmax  -mfix  -mcix @gol
775 -mfloat-vax  -mfloat-ieee @gol
776 -mexplicit-relocs  -msmall-data  -mlarge-data @gol
777 -msmall-text  -mlarge-text @gol
778 -mmemory-latency=@var{time}}
780 @emph{FR30 Options}
781 @gccoptlist{-msmall-model  -mno-lsim}
783 @emph{FT32 Options}
784 @gccoptlist{-msim  -mlra  -mnodiv  -mft32b  -mcompress  -mnopm}
786 @emph{FRV Options}
787 @gccoptlist{-mgpr-32  -mgpr-64  -mfpr-32  -mfpr-64 @gol
788 -mhard-float  -msoft-float @gol
789 -malloc-cc  -mfixed-cc  -mdword  -mno-dword @gol
790 -mdouble  -mno-double @gol
791 -mmedia  -mno-media  -mmuladd  -mno-muladd @gol
792 -mfdpic  -minline-plt  -mgprel-ro  -multilib-library-pic @gol
793 -mlinked-fp  -mlong-calls  -malign-labels @gol
794 -mlibrary-pic  -macc-4  -macc-8 @gol
795 -mpack  -mno-pack  -mno-eflags  -mcond-move  -mno-cond-move @gol
796 -moptimize-membar  -mno-optimize-membar @gol
797 -mscc  -mno-scc  -mcond-exec  -mno-cond-exec @gol
798 -mvliw-branch  -mno-vliw-branch @gol
799 -mmulti-cond-exec  -mno-multi-cond-exec  -mnested-cond-exec @gol
800 -mno-nested-cond-exec  -mtomcat-stats @gol
801 -mTLS  -mtls @gol
802 -mcpu=@var{cpu}}
804 @emph{GNU/Linux Options}
805 @gccoptlist{-mglibc  -muclibc  -mmusl  -mbionic  -mandroid @gol
806 -tno-android-cc  -tno-android-ld}
808 @emph{H8/300 Options}
809 @gccoptlist{-mrelax  -mh  -ms  -mn  -mexr  -mno-exr  -mint32  -malign-300}
811 @emph{HPPA Options}
812 @gccoptlist{-march=@var{architecture-type} @gol
813 -mcaller-copies  -mdisable-fpregs  -mdisable-indexing @gol
814 -mfast-indirect-calls  -mgas  -mgnu-ld   -mhp-ld @gol
815 -mfixed-range=@var{register-range} @gol
816 -mjump-in-delay  -mlinker-opt  -mlong-calls @gol
817 -mlong-load-store  -mno-disable-fpregs @gol
818 -mno-disable-indexing  -mno-fast-indirect-calls  -mno-gas @gol
819 -mno-jump-in-delay  -mno-long-load-store @gol
820 -mno-portable-runtime  -mno-soft-float @gol
821 -mno-space-regs  -msoft-float  -mpa-risc-1-0 @gol
822 -mpa-risc-1-1  -mpa-risc-2-0  -mportable-runtime @gol
823 -mschedule=@var{cpu-type}  -mspace-regs  -msio  -mwsio @gol
824 -munix=@var{unix-std}  -nolibdld  -static  -threads}
826 @emph{IA-64 Options}
827 @gccoptlist{-mbig-endian  -mlittle-endian  -mgnu-as  -mgnu-ld  -mno-pic @gol
828 -mvolatile-asm-stop  -mregister-names  -msdata  -mno-sdata @gol
829 -mconstant-gp  -mauto-pic  -mfused-madd @gol
830 -minline-float-divide-min-latency @gol
831 -minline-float-divide-max-throughput @gol
832 -mno-inline-float-divide @gol
833 -minline-int-divide-min-latency @gol
834 -minline-int-divide-max-throughput  @gol
835 -mno-inline-int-divide @gol
836 -minline-sqrt-min-latency  -minline-sqrt-max-throughput @gol
837 -mno-inline-sqrt @gol
838 -mdwarf2-asm  -mearly-stop-bits @gol
839 -mfixed-range=@var{register-range}  -mtls-size=@var{tls-size} @gol
840 -mtune=@var{cpu-type}  -milp32  -mlp64 @gol
841 -msched-br-data-spec  -msched-ar-data-spec  -msched-control-spec @gol
842 -msched-br-in-data-spec  -msched-ar-in-data-spec  -msched-in-control-spec @gol
843 -msched-spec-ldc  -msched-spec-control-ldc @gol
844 -msched-prefer-non-data-spec-insns  -msched-prefer-non-control-spec-insns @gol
845 -msched-stop-bits-after-every-cycle  -msched-count-spec-in-critical-path @gol
846 -msel-sched-dont-check-control-spec  -msched-fp-mem-deps-zero-cost @gol
847 -msched-max-memory-insns-hard-limit  -msched-max-memory-insns=@var{max-insns}}
849 @emph{LM32 Options}
850 @gccoptlist{-mbarrel-shift-enabled  -mdivide-enabled  -mmultiply-enabled @gol
851 -msign-extend-enabled  -muser-enabled}
853 @emph{M32R/D Options}
854 @gccoptlist{-m32r2  -m32rx  -m32r @gol
855 -mdebug @gol
856 -malign-loops  -mno-align-loops @gol
857 -missue-rate=@var{number} @gol
858 -mbranch-cost=@var{number} @gol
859 -mmodel=@var{code-size-model-type} @gol
860 -msdata=@var{sdata-type} @gol
861 -mno-flush-func  -mflush-func=@var{name} @gol
862 -mno-flush-trap  -mflush-trap=@var{number} @gol
863 -G @var{num}}
865 @emph{M32C Options}
866 @gccoptlist{-mcpu=@var{cpu}  -msim  -memregs=@var{number}}
868 @emph{M680x0 Options}
869 @gccoptlist{-march=@var{arch}  -mcpu=@var{cpu}  -mtune=@var{tune} @gol
870 -m68000  -m68020  -m68020-40  -m68020-60  -m68030  -m68040 @gol
871 -m68060  -mcpu32  -m5200  -m5206e  -m528x  -m5307  -m5407 @gol
872 -mcfv4e  -mbitfield  -mno-bitfield  -mc68000  -mc68020 @gol
873 -mnobitfield  -mrtd  -mno-rtd  -mdiv  -mno-div  -mshort @gol
874 -mno-short  -mhard-float  -m68881  -msoft-float  -mpcrel @gol
875 -malign-int  -mstrict-align  -msep-data  -mno-sep-data @gol
876 -mshared-library-id=n  -mid-shared-library  -mno-id-shared-library @gol
877 -mxgot  -mno-xgot  -mlong-jump-table-offsets}
879 @emph{MCore Options}
880 @gccoptlist{-mhardlit  -mno-hardlit  -mdiv  -mno-div  -mrelax-immediates @gol
881 -mno-relax-immediates  -mwide-bitfields  -mno-wide-bitfields @gol
882 -m4byte-functions  -mno-4byte-functions  -mcallgraph-data @gol
883 -mno-callgraph-data  -mslow-bytes  -mno-slow-bytes  -mno-lsim @gol
884 -mlittle-endian  -mbig-endian  -m210  -m340  -mstack-increment}
886 @emph{MeP Options}
887 @gccoptlist{-mabsdiff  -mall-opts  -maverage  -mbased=@var{n}  -mbitops @gol
888 -mc=@var{n}  -mclip  -mconfig=@var{name}  -mcop  -mcop32  -mcop64  -mivc2 @gol
889 -mdc  -mdiv  -meb  -mel  -mio-volatile  -ml  -mleadz  -mm  -mminmax @gol
890 -mmult  -mno-opts  -mrepeat  -ms  -msatur  -msdram  -msim  -msimnovec  -mtf @gol
891 -mtiny=@var{n}}
893 @emph{MicroBlaze Options}
894 @gccoptlist{-msoft-float  -mhard-float  -msmall-divides  -mcpu=@var{cpu} @gol
895 -mmemcpy  -mxl-soft-mul  -mxl-soft-div  -mxl-barrel-shift @gol
896 -mxl-pattern-compare  -mxl-stack-check  -mxl-gp-opt  -mno-clearbss @gol
897 -mxl-multiply-high  -mxl-float-convert  -mxl-float-sqrt @gol
898 -mbig-endian  -mlittle-endian  -mxl-reorder  -mxl-mode-@var{app-model}
899 -mpic-data-is-text-relative}
901 @emph{MIPS Options}
902 @gccoptlist{-EL  -EB  -march=@var{arch}  -mtune=@var{arch} @gol
903 -mips1  -mips2  -mips3  -mips4  -mips32  -mips32r2  -mips32r3  -mips32r5 @gol
904 -mips32r6  -mips64  -mips64r2  -mips64r3  -mips64r5  -mips64r6 @gol
905 -mips16  -mno-mips16  -mflip-mips16 @gol
906 -minterlink-compressed  -mno-interlink-compressed @gol
907 -minterlink-mips16  -mno-interlink-mips16 @gol
908 -mabi=@var{abi}  -mabicalls  -mno-abicalls @gol
909 -mshared  -mno-shared  -mplt  -mno-plt  -mxgot  -mno-xgot @gol
910 -mgp32  -mgp64  -mfp32  -mfpxx  -mfp64  -mhard-float  -msoft-float @gol
911 -mno-float  -msingle-float  -mdouble-float @gol
912 -modd-spreg  -mno-odd-spreg @gol
913 -mabs=@var{mode}  -mnan=@var{encoding} @gol
914 -mdsp  -mno-dsp  -mdspr2  -mno-dspr2 @gol
915 -mmcu  -mmno-mcu @gol
916 -meva  -mno-eva @gol
917 -mvirt  -mno-virt @gol
918 -mxpa  -mno-xpa @gol
919 -mcrc -mno-crc @gol
920 -mginv -mno-ginv @gol
921 -mmicromips  -mno-micromips @gol
922 -mmsa  -mno-msa @gol
923 -mfpu=@var{fpu-type} @gol
924 -msmartmips  -mno-smartmips @gol
925 -mpaired-single  -mno-paired-single  -mdmx  -mno-mdmx @gol
926 -mips3d  -mno-mips3d  -mmt  -mno-mt  -mllsc  -mno-llsc @gol
927 -mlong64  -mlong32  -msym32  -mno-sym32 @gol
928 -G@var{num}  -mlocal-sdata  -mno-local-sdata @gol
929 -mextern-sdata  -mno-extern-sdata  -mgpopt  -mno-gopt @gol
930 -membedded-data  -mno-embedded-data @gol
931 -muninit-const-in-rodata  -mno-uninit-const-in-rodata @gol
932 -mcode-readable=@var{setting} @gol
933 -msplit-addresses  -mno-split-addresses @gol
934 -mexplicit-relocs  -mno-explicit-relocs @gol
935 -mcheck-zero-division  -mno-check-zero-division @gol
936 -mdivide-traps  -mdivide-breaks @gol
937 -mload-store-pairs  -mno-load-store-pairs @gol
938 -mmemcpy  -mno-memcpy  -mlong-calls  -mno-long-calls @gol
939 -mmad  -mno-mad  -mimadd  -mno-imadd  -mfused-madd  -mno-fused-madd  -nocpp @gol
940 -mfix-24k  -mno-fix-24k @gol
941 -mfix-r4000  -mno-fix-r4000  -mfix-r4400  -mno-fix-r4400 @gol
942 -mfix-r10000  -mno-fix-r10000  -mfix-rm7000  -mno-fix-rm7000 @gol
943 -mfix-vr4120  -mno-fix-vr4120 @gol
944 -mfix-vr4130  -mno-fix-vr4130  -mfix-sb1  -mno-fix-sb1 @gol
945 -mflush-func=@var{func}  -mno-flush-func @gol
946 -mbranch-cost=@var{num}  -mbranch-likely  -mno-branch-likely @gol
947 -mcompact-branches=@var{policy} @gol
948 -mfp-exceptions  -mno-fp-exceptions @gol
949 -mvr4130-align  -mno-vr4130-align  -msynci  -mno-synci @gol
950 -mlxc1-sxc1 -mno-lxc1-sxc1 -mmadd4 -mno-madd4 @gol
951 -mrelax-pic-calls  -mno-relax-pic-calls  -mmcount-ra-address @gol
952 -mframe-header-opt  -mno-frame-header-opt}
954 @emph{MMIX Options}
955 @gccoptlist{-mlibfuncs  -mno-libfuncs  -mepsilon  -mno-epsilon  -mabi=gnu @gol
956 -mabi=mmixware  -mzero-extend  -mknuthdiv  -mtoplevel-symbols @gol
957 -melf  -mbranch-predict  -mno-branch-predict  -mbase-addresses @gol
958 -mno-base-addresses  -msingle-exit  -mno-single-exit}
960 @emph{MN10300 Options}
961 @gccoptlist{-mmult-bug  -mno-mult-bug @gol
962 -mno-am33  -mam33  -mam33-2  -mam34 @gol
963 -mtune=@var{cpu-type} @gol
964 -mreturn-pointer-on-d0 @gol
965 -mno-crt0  -mrelax  -mliw  -msetlb}
967 @emph{Moxie Options}
968 @gccoptlist{-meb  -mel  -mmul.x  -mno-crt0}
970 @emph{MSP430 Options}
971 @gccoptlist{-msim  -masm-hex  -mmcu=  -mcpu=  -mlarge  -msmall  -mrelax @gol
972 -mwarn-mcu @gol
973 -mcode-region=  -mdata-region= @gol
974 -msilicon-errata=  -msilicon-errata-warn= @gol
975 -mhwmult=  -minrt}
977 @emph{NDS32 Options}
978 @gccoptlist{-mbig-endian  -mlittle-endian @gol
979 -mreduced-regs  -mfull-regs @gol
980 -mcmov  -mno-cmov @gol
981 -mext-perf  -mno-ext-perf @gol
982 -mext-perf2  -mno-ext-perf2 @gol
983 -mext-string  -mno-ext-string @gol
984 -mv3push  -mno-v3push @gol
985 -m16bit  -mno-16bit @gol
986 -misr-vector-size=@var{num} @gol
987 -mcache-block-size=@var{num} @gol
988 -march=@var{arch} @gol
989 -mcmodel=@var{code-model} @gol
990 -mctor-dtor  -mrelax}
992 @emph{Nios II Options}
993 @gccoptlist{-G @var{num}  -mgpopt=@var{option}  -mgpopt  -mno-gpopt @gol
994 -mgprel-sec=@var{regexp} -mr0rel-sec=@var{regexp} @gol
995 -mel  -meb @gol
996 -mno-bypass-cache  -mbypass-cache @gol
997 -mno-cache-volatile  -mcache-volatile @gol
998 -mno-fast-sw-div  -mfast-sw-div @gol
999 -mhw-mul  -mno-hw-mul  -mhw-mulx  -mno-hw-mulx  -mno-hw-div  -mhw-div @gol
1000 -mcustom-@var{insn}=@var{N}  -mno-custom-@var{insn} @gol
1001 -mcustom-fpu-cfg=@var{name} @gol
1002 -mhal  -msmallc  -msys-crt0=@var{name}  -msys-lib=@var{name} @gol
1003 -march=@var{arch}  -mbmx  -mno-bmx  -mcdx  -mno-cdx}
1005 @emph{Nvidia PTX Options}
1006 @gccoptlist{-m32  -m64  -mmainkernel  -moptimize}
1008 @emph{PDP-11 Options}
1009 @gccoptlist{-mfpu  -msoft-float  -mac0  -mno-ac0  -m40  -m45  -m10 @gol
1010 -mint32  -mno-int16 -mint16  -mno-int32 @gol
1011 -msplit -munix-asm  -mdec-asm -mgnu-asm -mlra}
1013 @emph{picoChip Options}
1014 @gccoptlist{-mae=@var{ae_type}  -mvliw-lookahead=@var{N} @gol
1015 -msymbol-as-address  -mno-inefficient-warnings}
1017 @emph{PowerPC Options}
1018 See RS/6000 and PowerPC Options.
1020 @emph{PowerPC SPE Options}
1021 @gccoptlist{-mcpu=@var{cpu-type} @gol
1022 -mtune=@var{cpu-type} @gol
1023 -mmfcrf  -mno-mfcrf  -mpopcntb  -mno-popcntb @gol
1024 -mfull-toc   -mminimal-toc  -mno-fp-in-toc  -mno-sum-in-toc @gol
1025 -m32  -mxl-compat  -mno-xl-compat @gol
1026 -malign-power  -malign-natural @gol
1027 -msoft-float  -mhard-float  -mmultiple  -mno-multiple @gol
1028 -msingle-float  -mdouble-float @gol
1029 -mupdate  -mno-update @gol
1030 -mavoid-indexed-addresses  -mno-avoid-indexed-addresses @gol
1031 -mstrict-align  -mno-strict-align  -mrelocatable @gol
1032 -mno-relocatable  -mrelocatable-lib  -mno-relocatable-lib @gol
1033 -mtoc  -mno-toc  -mlittle  -mlittle-endian  -mbig  -mbig-endian @gol
1034 -msingle-pic-base @gol
1035 -mprioritize-restricted-insns=@var{priority} @gol
1036 -msched-costly-dep=@var{dependence_type} @gol
1037 -minsert-sched-nops=@var{scheme} @gol
1038 -mcall-sysv  -mcall-netbsd @gol
1039 -maix-struct-return  -msvr4-struct-return @gol
1040 -mabi=@var{abi-type}  -msecure-plt  -mbss-plt @gol
1041 -mblock-move-inline-limit=@var{num} @gol
1042 -misel  -mno-isel @gol
1043 -misel=yes  -misel=no @gol
1044 -mspe  -mno-spe @gol
1045 -mspe=yes  -mspe=no @gol
1046 -mfloat-gprs=yes  -mfloat-gprs=no  -mfloat-gprs=single  -mfloat-gprs=double @gol
1047 -mprototype  -mno-prototype @gol
1048 -msim  -mmvme  -mads  -myellowknife  -memb  -msdata @gol
1049 -msdata=@var{opt}  -mvxworks  -G @var{num} @gol
1050 -mrecip  -mrecip=@var{opt}  -mno-recip  -mrecip-precision @gol
1051 -mno-recip-precision @gol
1052 -mpointers-to-nested-functions  -mno-pointers-to-nested-functions @gol
1053 -msave-toc-indirect  -mno-save-toc-indirect @gol
1054 -mcompat-align-parm  -mno-compat-align-parm @gol
1055 -mfloat128  -mno-float128 @gol
1056 -mgnu-attribute  -mno-gnu-attribute @gol
1057 -mstack-protector-guard=@var{guard} -mstack-protector-guard-reg=@var{reg} @gol
1058 -mstack-protector-guard-offset=@var{offset}}
1060 @emph{RISC-V Options}
1061 @gccoptlist{-mbranch-cost=@var{N-instruction} @gol
1062 -mplt  -mno-plt @gol
1063 -mabi=@var{ABI-string} @gol
1064 -mfdiv  -mno-fdiv @gol
1065 -mdiv  -mno-div @gol
1066 -march=@var{ISA-string} @gol
1067 -mtune=@var{processor-string} @gol
1068 -mpreferred-stack-boundary=@var{num} @gol
1069 -msmall-data-limit=@var{N-bytes} @gol
1070 -msave-restore  -mno-save-restore @gol
1071 -mstrict-align -mno-strict-align @gol
1072 -mcmodel=medlow -mcmodel=medany @gol
1073 -mexplicit-relocs  -mno-explicit-relocs @gol
1074 -mrelax -mno-relax @gol}
1076 @emph{RL78 Options}
1077 @gccoptlist{-msim  -mmul=none  -mmul=g13  -mmul=g14  -mallregs @gol
1078 -mcpu=g10  -mcpu=g13  -mcpu=g14  -mg10  -mg13  -mg14 @gol
1079 -m64bit-doubles  -m32bit-doubles  -msave-mduc-in-interrupts}
1081 @emph{RS/6000 and PowerPC Options}
1082 @gccoptlist{-mcpu=@var{cpu-type} @gol
1083 -mtune=@var{cpu-type} @gol
1084 -mcmodel=@var{code-model} @gol
1085 -mpowerpc64 @gol
1086 -maltivec  -mno-altivec @gol
1087 -mpowerpc-gpopt  -mno-powerpc-gpopt @gol
1088 -mpowerpc-gfxopt  -mno-powerpc-gfxopt @gol
1089 -mmfcrf  -mno-mfcrf  -mpopcntb  -mno-popcntb  -mpopcntd  -mno-popcntd @gol
1090 -mfprnd  -mno-fprnd @gol
1091 -mcmpb  -mno-cmpb  -mmfpgpr  -mno-mfpgpr  -mhard-dfp  -mno-hard-dfp @gol
1092 -mfull-toc   -mminimal-toc  -mno-fp-in-toc  -mno-sum-in-toc @gol
1093 -m64  -m32  -mxl-compat  -mno-xl-compat  -mpe @gol
1094 -malign-power  -malign-natural @gol
1095 -msoft-float  -mhard-float  -mmultiple  -mno-multiple @gol
1096 -mupdate  -mno-update @gol
1097 -mavoid-indexed-addresses  -mno-avoid-indexed-addresses @gol
1098 -mfused-madd  -mno-fused-madd  -mbit-align  -mno-bit-align @gol
1099 -mstrict-align  -mno-strict-align  -mrelocatable @gol
1100 -mno-relocatable  -mrelocatable-lib  -mno-relocatable-lib @gol
1101 -mtoc  -mno-toc  -mlittle  -mlittle-endian  -mbig  -mbig-endian @gol
1102 -mdynamic-no-pic  -maltivec  -mswdiv  -msingle-pic-base @gol
1103 -mprioritize-restricted-insns=@var{priority} @gol
1104 -msched-costly-dep=@var{dependence_type} @gol
1105 -minsert-sched-nops=@var{scheme} @gol
1106 -mcall-aixdesc  -mcall-eabi  -mcall-freebsd  @gol
1107 -mcall-linux  -mcall-netbsd  -mcall-openbsd  @gol
1108 -mcall-sysv  -mcall-sysv-eabi  -mcall-sysv-noeabi @gol
1109 -mtraceback=@var{traceback_type} @gol
1110 -maix-struct-return  -msvr4-struct-return @gol
1111 -mabi=@var{abi-type}  -msecure-plt  -mbss-plt @gol
1112 -mblock-move-inline-limit=@var{num} @gol
1113 -mblock-compare-inline-limit=@var{num} @gol
1114 -mblock-compare-inline-loop-limit=@var{num} @gol
1115 -mstring-compare-inline-limit=@var{num} @gol
1116 -misel  -mno-isel @gol
1117 -mvrsave  -mno-vrsave @gol
1118 -mmulhw  -mno-mulhw @gol
1119 -mdlmzb  -mno-dlmzb @gol
1120 -mprototype  -mno-prototype @gol
1121 -msim  -mmvme  -mads  -myellowknife  -memb  -msdata @gol
1122 -msdata=@var{opt}  -mreadonly-in-sdata  -mvxworks  -G @var{num} @gol
1123 -mrecip  -mrecip=@var{opt}  -mno-recip  -mrecip-precision @gol
1124 -mno-recip-precision @gol
1125 -mveclibabi=@var{type}  -mfriz  -mno-friz @gol
1126 -mpointers-to-nested-functions  -mno-pointers-to-nested-functions @gol
1127 -msave-toc-indirect  -mno-save-toc-indirect @gol
1128 -mpower8-fusion  -mno-mpower8-fusion  -mpower8-vector  -mno-power8-vector @gol
1129 -mcrypto  -mno-crypto  -mhtm  -mno-htm @gol
1130 -mquad-memory  -mno-quad-memory @gol
1131 -mquad-memory-atomic  -mno-quad-memory-atomic @gol
1132 -mcompat-align-parm  -mno-compat-align-parm @gol
1133 -mfloat128  -mno-float128  -mfloat128-hardware  -mno-float128-hardware @gol
1134 -mgnu-attribute  -mno-gnu-attribute @gol
1135 -mstack-protector-guard=@var{guard} -mstack-protector-guard-reg=@var{reg} @gol
1136 -mstack-protector-guard-offset=@var{offset}}
1138 @emph{RX Options}
1139 @gccoptlist{-m64bit-doubles  -m32bit-doubles  -fpu  -nofpu@gol
1140 -mcpu=@gol
1141 -mbig-endian-data  -mlittle-endian-data @gol
1142 -msmall-data @gol
1143 -msim  -mno-sim@gol
1144 -mas100-syntax  -mno-as100-syntax@gol
1145 -mrelax@gol
1146 -mmax-constant-size=@gol
1147 -mint-register=@gol
1148 -mpid@gol
1149 -mallow-string-insns  -mno-allow-string-insns@gol
1150 -mjsr@gol
1151 -mno-warn-multiple-fast-interrupts@gol
1152 -msave-acc-in-interrupts}
1154 @emph{S/390 and zSeries Options}
1155 @gccoptlist{-mtune=@var{cpu-type}  -march=@var{cpu-type} @gol
1156 -mhard-float  -msoft-float  -mhard-dfp  -mno-hard-dfp @gol
1157 -mlong-double-64  -mlong-double-128 @gol
1158 -mbackchain  -mno-backchain  -mpacked-stack  -mno-packed-stack @gol
1159 -msmall-exec  -mno-small-exec  -mmvcle  -mno-mvcle @gol
1160 -m64  -m31  -mdebug  -mno-debug  -mesa  -mzarch @gol
1161 -mhtm  -mvx  -mzvector @gol
1162 -mtpf-trace  -mno-tpf-trace  -mfused-madd  -mno-fused-madd @gol
1163 -mwarn-framesize  -mwarn-dynamicstack  -mstack-size  -mstack-guard @gol
1164 -mhotpatch=@var{halfwords},@var{halfwords}}
1166 @emph{Score Options}
1167 @gccoptlist{-meb  -mel @gol
1168 -mnhwloop @gol
1169 -muls @gol
1170 -mmac @gol
1171 -mscore5  -mscore5u  -mscore7  -mscore7d}
1173 @emph{SH Options}
1174 @gccoptlist{-m1  -m2  -m2e @gol
1175 -m2a-nofpu  -m2a-single-only  -m2a-single  -m2a @gol
1176 -m3  -m3e @gol
1177 -m4-nofpu  -m4-single-only  -m4-single  -m4 @gol
1178 -m4a-nofpu  -m4a-single-only  -m4a-single  -m4a  -m4al @gol
1179 -mb  -ml  -mdalign  -mrelax @gol
1180 -mbigtable  -mfmovd  -mrenesas  -mno-renesas  -mnomacsave @gol
1181 -mieee  -mno-ieee  -mbitops  -misize  -minline-ic_invalidate  -mpadstruct @gol
1182 -mprefergot  -musermode  -multcost=@var{number}  -mdiv=@var{strategy} @gol
1183 -mdivsi3_libfunc=@var{name}  -mfixed-range=@var{register-range} @gol
1184 -maccumulate-outgoing-args @gol
1185 -matomic-model=@var{atomic-model} @gol
1186 -mbranch-cost=@var{num}  -mzdcbranch  -mno-zdcbranch @gol
1187 -mcbranch-force-delay-slot @gol
1188 -mfused-madd  -mno-fused-madd  -mfsca  -mno-fsca  -mfsrra  -mno-fsrra @gol
1189 -mpretend-cmove  -mtas}
1191 @emph{Solaris 2 Options}
1192 @gccoptlist{-mclear-hwcap  -mno-clear-hwcap  -mimpure-text  -mno-impure-text @gol
1193 -pthreads}
1195 @emph{SPARC Options}
1196 @gccoptlist{-mcpu=@var{cpu-type} @gol
1197 -mtune=@var{cpu-type} @gol
1198 -mcmodel=@var{code-model} @gol
1199 -mmemory-model=@var{mem-model} @gol
1200 -m32  -m64  -mapp-regs  -mno-app-regs @gol
1201 -mfaster-structs  -mno-faster-structs  -mflat  -mno-flat @gol
1202 -mfpu  -mno-fpu  -mhard-float  -msoft-float @gol
1203 -mhard-quad-float  -msoft-quad-float @gol
1204 -mstack-bias  -mno-stack-bias @gol
1205 -mstd-struct-return  -mno-std-struct-return @gol
1206 -munaligned-doubles  -mno-unaligned-doubles @gol
1207 -muser-mode  -mno-user-mode @gol
1208 -mv8plus  -mno-v8plus  -mvis  -mno-vis @gol
1209 -mvis2  -mno-vis2  -mvis3  -mno-vis3 @gol
1210 -mvis4 -mno-vis4 -mvis4b -mno-vis4b @gol
1211 -mcbcond  -mno-cbcond  -mfmaf  -mno-fmaf  -mfsmuld  -mno-fsmuld  @gol
1212 -mpopc  -mno-popc  -msubxc  -mno-subxc @gol
1213 -mfix-at697f  -mfix-ut699  -mfix-ut700  -mfix-gr712rc @gol
1214 -mlra  -mno-lra}
1216 @emph{SPU Options}
1217 @gccoptlist{-mwarn-reloc  -merror-reloc @gol
1218 -msafe-dma  -munsafe-dma @gol
1219 -mbranch-hints @gol
1220 -msmall-mem  -mlarge-mem  -mstdmain @gol
1221 -mfixed-range=@var{register-range} @gol
1222 -mea32  -mea64 @gol
1223 -maddress-space-conversion  -mno-address-space-conversion @gol
1224 -mcache-size=@var{cache-size} @gol
1225 -matomic-updates  -mno-atomic-updates}
1227 @emph{System V Options}
1228 @gccoptlist{-Qy  -Qn  -YP,@var{paths}  -Ym,@var{dir}}
1230 @emph{TILE-Gx Options}
1231 @gccoptlist{-mcpu=CPU  -m32  -m64  -mbig-endian  -mlittle-endian @gol
1232 -mcmodel=@var{code-model}}
1234 @emph{TILEPro Options}
1235 @gccoptlist{-mcpu=@var{cpu}  -m32}
1237 @emph{V850 Options}
1238 @gccoptlist{-mlong-calls  -mno-long-calls  -mep  -mno-ep @gol
1239 -mprolog-function  -mno-prolog-function  -mspace @gol
1240 -mtda=@var{n}  -msda=@var{n}  -mzda=@var{n} @gol
1241 -mapp-regs  -mno-app-regs @gol
1242 -mdisable-callt  -mno-disable-callt @gol
1243 -mv850e2v3  -mv850e2  -mv850e1  -mv850es @gol
1244 -mv850e  -mv850  -mv850e3v5 @gol
1245 -mloop @gol
1246 -mrelax @gol
1247 -mlong-jumps @gol
1248 -msoft-float @gol
1249 -mhard-float @gol
1250 -mgcc-abi @gol
1251 -mrh850-abi @gol
1252 -mbig-switch}
1254 @emph{VAX Options}
1255 @gccoptlist{-mg  -mgnu  -munix}
1257 @emph{Visium Options}
1258 @gccoptlist{-mdebug  -msim  -mfpu  -mno-fpu  -mhard-float  -msoft-float @gol
1259 -mcpu=@var{cpu-type}  -mtune=@var{cpu-type}  -msv-mode  -muser-mode}
1261 @emph{VMS Options}
1262 @gccoptlist{-mvms-return-codes  -mdebug-main=@var{prefix}  -mmalloc64 @gol
1263 -mpointer-size=@var{size}}
1265 @emph{VxWorks Options}
1266 @gccoptlist{-mrtp  -non-static  -Bstatic  -Bdynamic @gol
1267 -Xbind-lazy  -Xbind-now}
1269 @emph{x86 Options}
1270 @gccoptlist{-mtune=@var{cpu-type}  -march=@var{cpu-type} @gol
1271 -mtune-ctrl=@var{feature-list}  -mdump-tune-features  -mno-default @gol
1272 -mfpmath=@var{unit} @gol
1273 -masm=@var{dialect}  -mno-fancy-math-387 @gol
1274 -mno-fp-ret-in-387  -m80387  -mhard-float  -msoft-float @gol
1275 -mno-wide-multiply  -mrtd  -malign-double @gol
1276 -mpreferred-stack-boundary=@var{num} @gol
1277 -mincoming-stack-boundary=@var{num} @gol
1278 -mcld  -mcx16  -msahf  -mmovbe  -mcrc32 @gol
1279 -mrecip  -mrecip=@var{opt} @gol
1280 -mvzeroupper  -mprefer-avx128 -mprefer-vector-width=@var{opt} @gol
1281 -mmmx  -msse  -msse2  -msse3  -mssse3  -msse4.1  -msse4.2  -msse4  -mavx @gol
1282 -mavx2  -mavx512f  -mavx512pf  -mavx512er  -mavx512cd  -mavx512vl @gol
1283 -mavx512bw  -mavx512dq  -mavx512ifma  -mavx512vbmi  -msha  -maes @gol
1284 -mpclmul  -mfsgsbase  -mrdrnd  -mf16c  -mfma -mpconfig -mwbnoinvd @gol
1285 -mprefetchwt1  -mclflushopt  -mxsavec  -mxsaves @gol
1286 -msse4a  -m3dnow  -m3dnowa  -mpopcnt  -mabm  -mbmi  -mtbm  -mfma4  -mxop @gol
1287 -mlzcnt  -mbmi2  -mfxsr  -mxsave  -mxsaveopt  -mrtm  -mlwp @gol
1288 -mmwaitx  -mclzero  -mpku  -mthreads -mgfni  -mvaes  -mwaitpkg @gol
1289 -mshstk -mforce-indirect-call -mavx512vbmi2 @gol
1290 -mvpclmulqdq -mavx512bitalg -mmovdiri -mmovdir64b -mavx512vpopcntdq
1291 -mcldemote @gol
1292 -mms-bitfields  -mno-align-stringops  -minline-all-stringops @gol
1293 -minline-stringops-dynamically  -mstringop-strategy=@var{alg} @gol
1294 -mmemcpy-strategy=@var{strategy}  -mmemset-strategy=@var{strategy} @gol
1295 -mpush-args  -maccumulate-outgoing-args  -m128bit-long-double @gol
1296 -m96bit-long-double  -mlong-double-64  -mlong-double-80  -mlong-double-128 @gol
1297 -mregparm=@var{num}  -msseregparm @gol
1298 -mveclibabi=@var{type}  -mvect8-ret-in-mem @gol
1299 -mpc32  -mpc64  -mpc80  -mstackrealign @gol
1300 -momit-leaf-frame-pointer  -mno-red-zone  -mno-tls-direct-seg-refs @gol
1301 -mcmodel=@var{code-model}  -mabi=@var{name}  -maddress-mode=@var{mode} @gol
1302 -m32  -m64  -mx32  -m16  -miamcu  -mlarge-data-threshold=@var{num} @gol
1303 -msse2avx  -mfentry  -mrecord-mcount  -mnop-mcount  -m8bit-idiv @gol
1304 -mavx256-split-unaligned-load  -mavx256-split-unaligned-store @gol
1305 -malign-data=@var{type}  -mstack-protector-guard=@var{guard} @gol
1306 -mstack-protector-guard-reg=@var{reg} @gol
1307 -mstack-protector-guard-offset=@var{offset} @gol
1308 -mstack-protector-guard-symbol=@var{symbol} @gol
1309 -mgeneral-regs-only -mcall-ms2sysv-xlogues @gol
1310 -mindirect-branch=@var{choice} -mfunction-return=@var{choice} @gol
1311 -mindirect-branch-register}
1313 @emph{x86 Windows Options}
1314 @gccoptlist{-mconsole  -mcygwin  -mno-cygwin  -mdll @gol
1315 -mnop-fun-dllimport  -mthread @gol
1316 -municode  -mwin32  -mwindows  -fno-set-stack-executable}
1318 @emph{Xstormy16 Options}
1319 @gccoptlist{-msim}
1321 @emph{Xtensa Options}
1322 @gccoptlist{-mconst16  -mno-const16 @gol
1323 -mfused-madd  -mno-fused-madd @gol
1324 -mforce-no-pic @gol
1325 -mserialize-volatile  -mno-serialize-volatile @gol
1326 -mtext-section-literals  -mno-text-section-literals @gol
1327 -mauto-litpools  -mno-auto-litpools @gol
1328 -mtarget-align  -mno-target-align @gol
1329 -mlongcalls  -mno-longcalls}
1331 @emph{zSeries Options}
1332 See S/390 and zSeries Options.
1333 @end table
1336 @node Overall Options
1337 @section Options Controlling the Kind of Output
1339 Compilation can involve up to four stages: preprocessing, compilation
1340 proper, assembly and linking, always in that order.  GCC is capable of
1341 preprocessing and compiling several files either into several
1342 assembler input files, or into one assembler input file; then each
1343 assembler input file produces an object file, and linking combines all
1344 the object files (those newly compiled, and those specified as input)
1345 into an executable file.
1347 @cindex file name suffix
1348 For any given input file, the file name suffix determines what kind of
1349 compilation is done:
1351 @table @gcctabopt
1352 @item @var{file}.c
1353 C source code that must be preprocessed.
1355 @item @var{file}.i
1356 C source code that should not be preprocessed.
1358 @item @var{file}.ii
1359 C++ source code that should not be preprocessed.
1361 @item @var{file}.m
1362 Objective-C source code.  Note that you must link with the @file{libobjc}
1363 library to make an Objective-C program work.
1365 @item @var{file}.mi
1366 Objective-C source code that should not be preprocessed.
1368 @item @var{file}.mm
1369 @itemx @var{file}.M
1370 Objective-C++ source code.  Note that you must link with the @file{libobjc}
1371 library to make an Objective-C++ program work.  Note that @samp{.M} refers
1372 to a literal capital M@.
1374 @item @var{file}.mii
1375 Objective-C++ source code that should not be preprocessed.
1377 @item @var{file}.h
1378 C, C++, Objective-C or Objective-C++ header file to be turned into a
1379 precompiled header (default), or C, C++ header file to be turned into an
1380 Ada spec (via the @option{-fdump-ada-spec} switch).
1382 @item @var{file}.cc
1383 @itemx @var{file}.cp
1384 @itemx @var{file}.cxx
1385 @itemx @var{file}.cpp
1386 @itemx @var{file}.CPP
1387 @itemx @var{file}.c++
1388 @itemx @var{file}.C
1389 C++ source code that must be preprocessed.  Note that in @samp{.cxx},
1390 the last two letters must both be literally @samp{x}.  Likewise,
1391 @samp{.C} refers to a literal capital C@.
1393 @item @var{file}.mm
1394 @itemx @var{file}.M
1395 Objective-C++ source code that must be preprocessed.
1397 @item @var{file}.mii
1398 Objective-C++ source code that should not be preprocessed.
1400 @item @var{file}.hh
1401 @itemx @var{file}.H
1402 @itemx @var{file}.hp
1403 @itemx @var{file}.hxx
1404 @itemx @var{file}.hpp
1405 @itemx @var{file}.HPP
1406 @itemx @var{file}.h++
1407 @itemx @var{file}.tcc
1408 C++ header file to be turned into a precompiled header or Ada spec.
1410 @item @var{file}.f
1411 @itemx @var{file}.for
1412 @itemx @var{file}.ftn
1413 Fixed form Fortran source code that should not be preprocessed.
1415 @item @var{file}.F
1416 @itemx @var{file}.FOR
1417 @itemx @var{file}.fpp
1418 @itemx @var{file}.FPP
1419 @itemx @var{file}.FTN
1420 Fixed form Fortran source code that must be preprocessed (with the traditional
1421 preprocessor).
1423 @item @var{file}.f90
1424 @itemx @var{file}.f95
1425 @itemx @var{file}.f03
1426 @itemx @var{file}.f08
1427 Free form Fortran source code that should not be preprocessed.
1429 @item @var{file}.F90
1430 @itemx @var{file}.F95
1431 @itemx @var{file}.F03
1432 @itemx @var{file}.F08
1433 Free form Fortran source code that must be preprocessed (with the
1434 traditional preprocessor).
1436 @item @var{file}.go
1437 Go source code.
1439 @item @var{file}.brig
1440 BRIG files (binary representation of HSAIL).
1442 @item @var{file}.ads
1443 Ada source code file that contains a library unit declaration (a
1444 declaration of a package, subprogram, or generic, or a generic
1445 instantiation), or a library unit renaming declaration (a package,
1446 generic, or subprogram renaming declaration).  Such files are also
1447 called @dfn{specs}.
1449 @item @var{file}.adb
1450 Ada source code file containing a library unit body (a subprogram or
1451 package body).  Such files are also called @dfn{bodies}.
1453 @c GCC also knows about some suffixes for languages not yet included:
1454 @c Ratfor:
1455 @c @var{file}.r
1457 @item @var{file}.s
1458 Assembler code.
1460 @item @var{file}.S
1461 @itemx @var{file}.sx
1462 Assembler code that must be preprocessed.
1464 @item @var{other}
1465 An object file to be fed straight into linking.
1466 Any file name with no recognized suffix is treated this way.
1467 @end table
1469 @opindex x
1470 You can specify the input language explicitly with the @option{-x} option:
1472 @table @gcctabopt
1473 @item -x @var{language}
1474 Specify explicitly the @var{language} for the following input files
1475 (rather than letting the compiler choose a default based on the file
1476 name suffix).  This option applies to all following input files until
1477 the next @option{-x} option.  Possible values for @var{language} are:
1478 @smallexample
1479 c  c-header  cpp-output
1480 c++  c++-header  c++-cpp-output
1481 objective-c  objective-c-header  objective-c-cpp-output
1482 objective-c++ objective-c++-header objective-c++-cpp-output
1483 assembler  assembler-with-cpp
1485 f77  f77-cpp-input f95  f95-cpp-input
1487 brig
1488 @end smallexample
1490 @item -x none
1491 Turn off any specification of a language, so that subsequent files are
1492 handled according to their file name suffixes (as they are if @option{-x}
1493 has not been used at all).
1494 @end table
1496 If you only want some of the stages of compilation, you can use
1497 @option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
1498 one of the options @option{-c}, @option{-S}, or @option{-E} to say where
1499 @command{gcc} is to stop.  Note that some combinations (for example,
1500 @samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
1502 @table @gcctabopt
1503 @item -c
1504 @opindex c
1505 Compile or assemble the source files, but do not link.  The linking
1506 stage simply is not done.  The ultimate output is in the form of an
1507 object file for each source file.
1509 By default, the object file name for a source file is made by replacing
1510 the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
1512 Unrecognized input files, not requiring compilation or assembly, are
1513 ignored.
1515 @item -S
1516 @opindex S
1517 Stop after the stage of compilation proper; do not assemble.  The output
1518 is in the form of an assembler code file for each non-assembler input
1519 file specified.
1521 By default, the assembler file name for a source file is made by
1522 replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
1524 Input files that don't require compilation are ignored.
1526 @item -E
1527 @opindex E
1528 Stop after the preprocessing stage; do not run the compiler proper.  The
1529 output is in the form of preprocessed source code, which is sent to the
1530 standard output.
1532 Input files that don't require preprocessing are ignored.
1534 @cindex output file option
1535 @item -o @var{file}
1536 @opindex o
1537 Place output in file @var{file}.  This applies to whatever
1538 sort of output is being produced, whether it be an executable file,
1539 an object file, an assembler file or preprocessed C code.
1541 If @option{-o} is not specified, the default is to put an executable
1542 file in @file{a.out}, the object file for
1543 @file{@var{source}.@var{suffix}} in @file{@var{source}.o}, its
1544 assembler file in @file{@var{source}.s}, a precompiled header file in
1545 @file{@var{source}.@var{suffix}.gch}, and all preprocessed C source on
1546 standard output.
1548 @item -v
1549 @opindex v
1550 Print (on standard error output) the commands executed to run the stages
1551 of compilation.  Also print the version number of the compiler driver
1552 program and of the preprocessor and the compiler proper.
1554 @item -###
1555 @opindex ###
1556 Like @option{-v} except the commands are not executed and arguments
1557 are quoted unless they contain only alphanumeric characters or @code{./-_}.
1558 This is useful for shell scripts to capture the driver-generated command lines.
1560 @item --help
1561 @opindex help
1562 Print (on the standard output) a description of the command-line options
1563 understood by @command{gcc}.  If the @option{-v} option is also specified
1564 then @option{--help} is also passed on to the various processes
1565 invoked by @command{gcc}, so that they can display the command-line options
1566 they accept.  If the @option{-Wextra} option has also been specified
1567 (prior to the @option{--help} option), then command-line options that
1568 have no documentation associated with them are also displayed.
1570 @item --target-help
1571 @opindex target-help
1572 Print (on the standard output) a description of target-specific command-line
1573 options for each tool.  For some targets extra target-specific
1574 information may also be printed.
1576 @item --help=@{@var{class}@r{|[}^@r{]}@var{qualifier}@}@r{[},@dots{}@r{]}
1577 Print (on the standard output) a description of the command-line
1578 options understood by the compiler that fit into all specified classes
1579 and qualifiers.  These are the supported classes:
1581 @table @asis
1582 @item @samp{optimizers}
1583 Display all of the optimization options supported by the
1584 compiler.
1586 @item @samp{warnings}
1587 Display all of the options controlling warning messages
1588 produced by the compiler.
1590 @item @samp{target}
1591 Display target-specific options.  Unlike the
1592 @option{--target-help} option however, target-specific options of the
1593 linker and assembler are not displayed.  This is because those
1594 tools do not currently support the extended @option{--help=} syntax.
1596 @item @samp{params}
1597 Display the values recognized by the @option{--param}
1598 option.
1600 @item @var{language}
1601 Display the options supported for @var{language}, where
1602 @var{language} is the name of one of the languages supported in this
1603 version of GCC@.
1605 @item @samp{common}
1606 Display the options that are common to all languages.
1607 @end table
1609 These are the supported qualifiers:
1611 @table @asis
1612 @item @samp{undocumented}
1613 Display only those options that are undocumented.
1615 @item @samp{joined}
1616 Display options taking an argument that appears after an equal
1617 sign in the same continuous piece of text, such as:
1618 @samp{--help=target}.
1620 @item @samp{separate}
1621 Display options taking an argument that appears as a separate word
1622 following the original option, such as: @samp{-o output-file}.
1623 @end table
1625 Thus for example to display all the undocumented target-specific
1626 switches supported by the compiler, use:
1628 @smallexample
1629 --help=target,undocumented
1630 @end smallexample
1632 The sense of a qualifier can be inverted by prefixing it with the
1633 @samp{^} character, so for example to display all binary warning
1634 options (i.e., ones that are either on or off and that do not take an
1635 argument) that have a description, use:
1637 @smallexample
1638 --help=warnings,^joined,^undocumented
1639 @end smallexample
1641 The argument to @option{--help=} should not consist solely of inverted
1642 qualifiers.
1644 Combining several classes is possible, although this usually
1645 restricts the output so much that there is nothing to display.  One
1646 case where it does work, however, is when one of the classes is
1647 @var{target}.  For example, to display all the target-specific
1648 optimization options, use:
1650 @smallexample
1651 --help=target,optimizers
1652 @end smallexample
1654 The @option{--help=} option can be repeated on the command line.  Each
1655 successive use displays its requested class of options, skipping
1656 those that have already been displayed.
1658 If the @option{-Q} option appears on the command line before the
1659 @option{--help=} option, then the descriptive text displayed by
1660 @option{--help=} is changed.  Instead of describing the displayed
1661 options, an indication is given as to whether the option is enabled,
1662 disabled or set to a specific value (assuming that the compiler
1663 knows this at the point where the @option{--help=} option is used).
1665 Here is a truncated example from the ARM port of @command{gcc}:
1667 @smallexample
1668   % gcc -Q -mabi=2 --help=target -c
1669   The following options are target specific:
1670   -mabi=                                2
1671   -mabort-on-noreturn                   [disabled]
1672   -mapcs                                [disabled]
1673 @end smallexample
1675 The output is sensitive to the effects of previous command-line
1676 options, so for example it is possible to find out which optimizations
1677 are enabled at @option{-O2} by using:
1679 @smallexample
1680 -Q -O2 --help=optimizers
1681 @end smallexample
1683 Alternatively you can discover which binary optimizations are enabled
1684 by @option{-O3} by using:
1686 @smallexample
1687 gcc -c -Q -O3 --help=optimizers > /tmp/O3-opts
1688 gcc -c -Q -O2 --help=optimizers > /tmp/O2-opts
1689 diff /tmp/O2-opts /tmp/O3-opts | grep enabled
1690 @end smallexample
1692 @item --version
1693 @opindex version
1694 Display the version number and copyrights of the invoked GCC@.
1696 @item -pass-exit-codes
1697 @opindex pass-exit-codes
1698 Normally the @command{gcc} program exits with the code of 1 if any
1699 phase of the compiler returns a non-success return code.  If you specify
1700 @option{-pass-exit-codes}, the @command{gcc} program instead returns with
1701 the numerically highest error produced by any phase returning an error
1702 indication.  The C, C++, and Fortran front ends return 4 if an internal
1703 compiler error is encountered.
1705 @item -pipe
1706 @opindex pipe
1707 Use pipes rather than temporary files for communication between the
1708 various stages of compilation.  This fails to work on some systems where
1709 the assembler is unable to read from a pipe; but the GNU assembler has
1710 no trouble.
1712 @item -specs=@var{file}
1713 @opindex specs
1714 Process @var{file} after the compiler reads in the standard @file{specs}
1715 file, in order to override the defaults which the @command{gcc} driver
1716 program uses when determining what switches to pass to @command{cc1},
1717 @command{cc1plus}, @command{as}, @command{ld}, etc.  More than one
1718 @option{-specs=@var{file}} can be specified on the command line, and they
1719 are processed in order, from left to right.  @xref{Spec Files}, for
1720 information about the format of the @var{file}.
1722 @item -wrapper
1723 @opindex wrapper
1724 Invoke all subcommands under a wrapper program.  The name of the
1725 wrapper program and its parameters are passed as a comma separated
1726 list.
1728 @smallexample
1729 gcc -c t.c -wrapper gdb,--args
1730 @end smallexample
1732 @noindent
1733 This invokes all subprograms of @command{gcc} under
1734 @samp{gdb --args}, thus the invocation of @command{cc1} is
1735 @samp{gdb --args cc1 @dots{}}.
1737 @item -ffile-prefix-map=@var{old}=@var{new}
1738 @opindex ffile-prefix-map
1739 When compiling files residing in directory @file{@var{old}}, record
1740 any references to them in the result of the compilation as if the
1741 files resided in directory @file{@var{new}} instead.  Specifying this
1742 option is equivalent to specifying all the individual
1743 @option{-f*-prefix-map} options.  This can be used to make reproducible
1744 builds that are location independent.  See also
1745 @option{-fmacro-prefix-map} and @option{-fdebug-prefix-map}.
1747 @item -fplugin=@var{name}.so
1748 @opindex fplugin
1749 Load the plugin code in file @var{name}.so, assumed to be a
1750 shared object to be dlopen'd by the compiler.  The base name of
1751 the shared object file is used to identify the plugin for the
1752 purposes of argument parsing (See
1753 @option{-fplugin-arg-@var{name}-@var{key}=@var{value}} below).
1754 Each plugin should define the callback functions specified in the
1755 Plugins API.
1757 @item -fplugin-arg-@var{name}-@var{key}=@var{value}
1758 @opindex fplugin-arg
1759 Define an argument called @var{key} with a value of @var{value}
1760 for the plugin called @var{name}.
1762 @item -fdump-ada-spec@r{[}-slim@r{]}
1763 @opindex fdump-ada-spec
1764 For C and C++ source and include files, generate corresponding Ada specs.
1765 @xref{Generating Ada Bindings for C and C++ headers,,, gnat_ugn,
1766 GNAT User's Guide}, which provides detailed documentation on this feature.
1768 @item -fada-spec-parent=@var{unit}
1769 @opindex fada-spec-parent
1770 In conjunction with @option{-fdump-ada-spec@r{[}-slim@r{]}} above, generate
1771 Ada specs as child units of parent @var{unit}.
1773 @item -fdump-go-spec=@var{file}
1774 @opindex fdump-go-spec
1775 For input files in any language, generate corresponding Go
1776 declarations in @var{file}.  This generates Go @code{const},
1777 @code{type}, @code{var}, and @code{func} declarations which may be a
1778 useful way to start writing a Go interface to code written in some
1779 other language.
1781 @include @value{srcdir}/../libiberty/at-file.texi
1782 @end table
1784 @node Invoking G++
1785 @section Compiling C++ Programs
1787 @cindex suffixes for C++ source
1788 @cindex C++ source file suffixes
1789 C++ source files conventionally use one of the suffixes @samp{.C},
1790 @samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or
1791 @samp{.cxx}; C++ header files often use @samp{.hh}, @samp{.hpp},
1792 @samp{.H}, or (for shared template code) @samp{.tcc}; and
1793 preprocessed C++ files use the suffix @samp{.ii}.  GCC recognizes
1794 files with these names and compiles them as C++ programs even if you
1795 call the compiler the same way as for compiling C programs (usually
1796 with the name @command{gcc}).
1798 @findex g++
1799 @findex c++
1800 However, the use of @command{gcc} does not add the C++ library.
1801 @command{g++} is a program that calls GCC and automatically specifies linking
1802 against the C++ library.  It treats @samp{.c},
1803 @samp{.h} and @samp{.i} files as C++ source files instead of C source
1804 files unless @option{-x} is used.  This program is also useful when
1805 precompiling a C header file with a @samp{.h} extension for use in C++
1806 compilations.  On many systems, @command{g++} is also installed with
1807 the name @command{c++}.
1809 @cindex invoking @command{g++}
1810 When you compile C++ programs, you may specify many of the same
1811 command-line options that you use for compiling programs in any
1812 language; or command-line options meaningful for C and related
1813 languages; or options that are meaningful only for C++ programs.
1814 @xref{C Dialect Options,,Options Controlling C Dialect}, for
1815 explanations of options for languages related to C@.
1816 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
1817 explanations of options that are meaningful only for C++ programs.
1819 @node C Dialect Options
1820 @section Options Controlling C Dialect
1821 @cindex dialect options
1822 @cindex language dialect options
1823 @cindex options, dialect
1825 The following options control the dialect of C (or languages derived
1826 from C, such as C++, Objective-C and Objective-C++) that the compiler
1827 accepts:
1829 @table @gcctabopt
1830 @cindex ANSI support
1831 @cindex ISO support
1832 @item -ansi
1833 @opindex ansi
1834 In C mode, this is equivalent to @option{-std=c90}. In C++ mode, it is
1835 equivalent to @option{-std=c++98}.
1837 This turns off certain features of GCC that are incompatible with ISO
1838 C90 (when compiling C code), or of standard C++ (when compiling C++ code),
1839 such as the @code{asm} and @code{typeof} keywords, and
1840 predefined macros such as @code{unix} and @code{vax} that identify the
1841 type of system you are using.  It also enables the undesirable and
1842 rarely used ISO trigraph feature.  For the C compiler,
1843 it disables recognition of C++ style @samp{//} comments as well as
1844 the @code{inline} keyword.
1846 The alternate keywords @code{__asm__}, @code{__extension__},
1847 @code{__inline__} and @code{__typeof__} continue to work despite
1848 @option{-ansi}.  You would not want to use them in an ISO C program, of
1849 course, but it is useful to put them in header files that might be included
1850 in compilations done with @option{-ansi}.  Alternate predefined macros
1851 such as @code{__unix__} and @code{__vax__} are also available, with or
1852 without @option{-ansi}.
1854 The @option{-ansi} option does not cause non-ISO programs to be
1855 rejected gratuitously.  For that, @option{-Wpedantic} is required in
1856 addition to @option{-ansi}.  @xref{Warning Options}.
1858 The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
1859 option is used.  Some header files may notice this macro and refrain
1860 from declaring certain functions or defining certain macros that the
1861 ISO standard doesn't call for; this is to avoid interfering with any
1862 programs that might use these names for other things.
1864 Functions that are normally built in but do not have semantics
1865 defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
1866 functions when @option{-ansi} is used.  @xref{Other Builtins,,Other
1867 built-in functions provided by GCC}, for details of the functions
1868 affected.
1870 @item -std=
1871 @opindex std
1872 Determine the language standard. @xref{Standards,,Language Standards
1873 Supported by GCC}, for details of these standard versions.  This option
1874 is currently only supported when compiling C or C++.
1876 The compiler can accept several base standards, such as @samp{c90} or
1877 @samp{c++98}, and GNU dialects of those standards, such as
1878 @samp{gnu90} or @samp{gnu++98}.  When a base standard is specified, the
1879 compiler accepts all programs following that standard plus those
1880 using GNU extensions that do not contradict it.  For example,
1881 @option{-std=c90} turns off certain features of GCC that are
1882 incompatible with ISO C90, such as the @code{asm} and @code{typeof}
1883 keywords, but not other GNU extensions that do not have a meaning in
1884 ISO C90, such as omitting the middle term of a @code{?:}
1885 expression. On the other hand, when a GNU dialect of a standard is
1886 specified, all features supported by the compiler are enabled, even when
1887 those features change the meaning of the base standard.  As a result, some
1888 strict-conforming programs may be rejected.  The particular standard
1889 is used by @option{-Wpedantic} to identify which features are GNU
1890 extensions given that version of the standard. For example
1891 @option{-std=gnu90 -Wpedantic} warns about C++ style @samp{//}
1892 comments, while @option{-std=gnu99 -Wpedantic} does not.
1894 A value for this option must be provided; possible values are
1896 @table @samp
1897 @item c90
1898 @itemx c89
1899 @itemx iso9899:1990
1900 Support all ISO C90 programs (certain GNU extensions that conflict
1901 with ISO C90 are disabled). Same as @option{-ansi} for C code.
1903 @item iso9899:199409
1904 ISO C90 as modified in amendment 1.
1906 @item c99
1907 @itemx c9x
1908 @itemx iso9899:1999
1909 @itemx iso9899:199x
1910 ISO C99.  This standard is substantially completely supported, modulo
1911 bugs and floating-point issues
1912 (mainly but not entirely relating to optional C99 features from
1913 Annexes F and G).  See
1914 @w{@uref{http://gcc.gnu.org/c99status.html}} for more information.  The
1915 names @samp{c9x} and @samp{iso9899:199x} are deprecated.
1917 @item c11
1918 @itemx c1x
1919 @itemx iso9899:2011
1920 ISO C11, the 2011 revision of the ISO C standard.  This standard is
1921 substantially completely supported, modulo bugs, floating-point issues
1922 (mainly but not entirely relating to optional C11 features from
1923 Annexes F and G) and the optional Annexes K (Bounds-checking
1924 interfaces) and L (Analyzability).  The name @samp{c1x} is deprecated.
1926 @item c17
1927 @itemx c18
1928 @itemx iso9899:2017
1929 @itemx iso9899:2018
1930 ISO C17, the 2017 revision of the ISO C standard
1931 (published in 2018).  This standard is
1932 same as C11 except for corrections of defects (all of which are also
1933 applied with @option{-std=c11}) and a new value of
1934 @code{__STDC_VERSION__}, and so is supported to the same extent as C11.
1936 @item c2x
1937 The next version of the ISO C standard, still under development.  The
1938 support for this version is experimental and incomplete.
1940 @item gnu90
1941 @itemx gnu89
1942 GNU dialect of ISO C90 (including some C99 features).
1944 @item gnu99
1945 @itemx gnu9x
1946 GNU dialect of ISO C99.  The name @samp{gnu9x} is deprecated.
1948 @item gnu11
1949 @itemx gnu1x
1950 GNU dialect of ISO C11.
1951 The name @samp{gnu1x} is deprecated.
1953 @item gnu17
1954 @itemx gnu18
1955 GNU dialect of ISO C17.  This is the default for C code.
1957 @item gnu2x
1958 The next version of the ISO C standard, still under development, plus
1959 GNU extensions.  The support for this version is experimental and
1960 incomplete.
1962 @item c++98
1963 @itemx c++03
1964 The 1998 ISO C++ standard plus the 2003 technical corrigendum and some
1965 additional defect reports. Same as @option{-ansi} for C++ code.
1967 @item gnu++98
1968 @itemx gnu++03
1969 GNU dialect of @option{-std=c++98}.
1971 @item c++11
1972 @itemx c++0x
1973 The 2011 ISO C++ standard plus amendments.
1974 The name @samp{c++0x} is deprecated.
1976 @item gnu++11
1977 @itemx gnu++0x
1978 GNU dialect of @option{-std=c++11}.
1979 The name @samp{gnu++0x} is deprecated.
1981 @item c++14
1982 @itemx c++1y
1983 The 2014 ISO C++ standard plus amendments.
1984 The name @samp{c++1y} is deprecated.
1986 @item gnu++14
1987 @itemx gnu++1y
1988 GNU dialect of @option{-std=c++14}.
1989 This is the default for C++ code.
1990 The name @samp{gnu++1y} is deprecated.
1992 @item c++17
1993 @itemx c++1z
1994 The 2017 ISO C++ standard plus amendments.
1995 The name @samp{c++1z} is deprecated.
1997 @item gnu++17
1998 @itemx gnu++1z
1999 GNU dialect of @option{-std=c++17}.
2000 The name @samp{gnu++1z} is deprecated.
2002 @item c++2a
2003 The next revision of the ISO C++ standard, tentatively planned for
2004 2020.  Support is highly experimental, and will almost certainly
2005 change in incompatible ways in future releases.
2007 @item gnu++2a
2008 GNU dialect of @option{-std=c++2a}.  Support is highly experimental,
2009 and will almost certainly change in incompatible ways in future
2010 releases.
2011 @end table
2013 @item -fgnu89-inline
2014 @opindex fgnu89-inline
2015 The option @option{-fgnu89-inline} tells GCC to use the traditional
2016 GNU semantics for @code{inline} functions when in C99 mode.
2017 @xref{Inline,,An Inline Function is As Fast As a Macro}.
2018 Using this option is roughly equivalent to adding the
2019 @code{gnu_inline} function attribute to all inline functions
2020 (@pxref{Function Attributes}).
2022 The option @option{-fno-gnu89-inline} explicitly tells GCC to use the
2023 C99 semantics for @code{inline} when in C99 or gnu99 mode (i.e., it
2024 specifies the default behavior).
2025 This option is not supported in @option{-std=c90} or
2026 @option{-std=gnu90} mode.
2028 The preprocessor macros @code{__GNUC_GNU_INLINE__} and
2029 @code{__GNUC_STDC_INLINE__} may be used to check which semantics are
2030 in effect for @code{inline} functions.  @xref{Common Predefined
2031 Macros,,,cpp,The C Preprocessor}.
2033 @item -fpermitted-flt-eval-methods=@var{style}
2034 @opindex fpermitted-flt-eval-methods
2035 @opindex fpermitted-flt-eval-methods=c11
2036 @opindex fpermitted-flt-eval-methods=ts-18661-3
2037 ISO/IEC TS 18661-3 defines new permissible values for
2038 @code{FLT_EVAL_METHOD} that indicate that operations and constants with
2039 a semantic type that is an interchange or extended format should be
2040 evaluated to the precision and range of that type.  These new values are
2041 a superset of those permitted under C99/C11, which does not specify the
2042 meaning of other positive values of @code{FLT_EVAL_METHOD}.  As such, code
2043 conforming to C11 may not have been written expecting the possibility of
2044 the new values.
2046 @option{-fpermitted-flt-eval-methods} specifies whether the compiler
2047 should allow only the values of @code{FLT_EVAL_METHOD} specified in C99/C11,
2048 or the extended set of values specified in ISO/IEC TS 18661-3.
2050 @var{style} is either @code{c11} or @code{ts-18661-3} as appropriate.
2052 The default when in a standards compliant mode (@option{-std=c11} or similar)
2053 is @option{-fpermitted-flt-eval-methods=c11}.  The default when in a GNU
2054 dialect (@option{-std=gnu11} or similar) is
2055 @option{-fpermitted-flt-eval-methods=ts-18661-3}.
2057 @item -aux-info @var{filename}
2058 @opindex aux-info
2059 Output to the given filename prototyped declarations for all functions
2060 declared and/or defined in a translation unit, including those in header
2061 files.  This option is silently ignored in any language other than C@.
2063 Besides declarations, the file indicates, in comments, the origin of
2064 each declaration (source file and line), whether the declaration was
2065 implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
2066 @samp{O} for old, respectively, in the first character after the line
2067 number and the colon), and whether it came from a declaration or a
2068 definition (@samp{C} or @samp{F}, respectively, in the following
2069 character).  In the case of function definitions, a K&R-style list of
2070 arguments followed by their declarations is also provided, inside
2071 comments, after the declaration.
2073 @item -fallow-parameterless-variadic-functions
2074 @opindex fallow-parameterless-variadic-functions
2075 Accept variadic functions without named parameters.
2077 Although it is possible to define such a function, this is not very
2078 useful as it is not possible to read the arguments.  This is only
2079 supported for C as this construct is allowed by C++.
2081 @item -fno-asm
2082 @opindex fno-asm
2083 Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
2084 keyword, so that code can use these words as identifiers.  You can use
2085 the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
2086 instead.  @option{-ansi} implies @option{-fno-asm}.
2088 In C++, this switch only affects the @code{typeof} keyword, since
2089 @code{asm} and @code{inline} are standard keywords.  You may want to
2090 use the @option{-fno-gnu-keywords} flag instead, which has the same
2091 effect.  In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
2092 switch only affects the @code{asm} and @code{typeof} keywords, since
2093 @code{inline} is a standard keyword in ISO C99.
2095 @item -fno-builtin
2096 @itemx -fno-builtin-@var{function}
2097 @opindex fno-builtin
2098 @cindex built-in functions
2099 Don't recognize built-in functions that do not begin with
2100 @samp{__builtin_} as prefix.  @xref{Other Builtins,,Other built-in
2101 functions provided by GCC}, for details of the functions affected,
2102 including those which are not built-in functions when @option{-ansi} or
2103 @option{-std} options for strict ISO C conformance are used because they
2104 do not have an ISO standard meaning.
2106 GCC normally generates special code to handle certain built-in functions
2107 more efficiently; for instance, calls to @code{alloca} may become single
2108 instructions which adjust the stack directly, and calls to @code{memcpy}
2109 may become inline copy loops.  The resulting code is often both smaller
2110 and faster, but since the function calls no longer appear as such, you
2111 cannot set a breakpoint on those calls, nor can you change the behavior
2112 of the functions by linking with a different library.  In addition,
2113 when a function is recognized as a built-in function, GCC may use
2114 information about that function to warn about problems with calls to
2115 that function, or to generate more efficient code, even if the
2116 resulting code still contains calls to that function.  For example,
2117 warnings are given with @option{-Wformat} for bad calls to
2118 @code{printf} when @code{printf} is built in and @code{strlen} is
2119 known not to modify global memory.
2121 With the @option{-fno-builtin-@var{function}} option
2122 only the built-in function @var{function} is
2123 disabled.  @var{function} must not begin with @samp{__builtin_}.  If a
2124 function is named that is not built-in in this version of GCC, this
2125 option is ignored.  There is no corresponding
2126 @option{-fbuiltin-@var{function}} option; if you wish to enable
2127 built-in functions selectively when using @option{-fno-builtin} or
2128 @option{-ffreestanding}, you may define macros such as:
2130 @smallexample
2131 #define abs(n)          __builtin_abs ((n))
2132 #define strcpy(d, s)    __builtin_strcpy ((d), (s))
2133 @end smallexample
2135 @item -fgimple
2136 @opindex fgimple
2138 Enable parsing of function definitions marked with @code{__GIMPLE}.
2139 This is an experimental feature that allows unit testing of GIMPLE
2140 passes.
2142 @item -fhosted
2143 @opindex fhosted
2144 @cindex hosted environment
2146 Assert that compilation targets a hosted environment.  This implies
2147 @option{-fbuiltin}.  A hosted environment is one in which the
2148 entire standard library is available, and in which @code{main} has a return
2149 type of @code{int}.  Examples are nearly everything except a kernel.
2150 This is equivalent to @option{-fno-freestanding}.
2152 @item -ffreestanding
2153 @opindex ffreestanding
2154 @cindex hosted environment
2156 Assert that compilation targets a freestanding environment.  This
2157 implies @option{-fno-builtin}.  A freestanding environment
2158 is one in which the standard library may not exist, and program startup may
2159 not necessarily be at @code{main}.  The most obvious example is an OS kernel.
2160 This is equivalent to @option{-fno-hosted}.
2162 @xref{Standards,,Language Standards Supported by GCC}, for details of
2163 freestanding and hosted environments.
2165 @item -fopenacc
2166 @opindex fopenacc
2167 @cindex OpenACC accelerator programming
2168 Enable handling of OpenACC directives @code{#pragma acc} in C/C++ and
2169 @code{!$acc} in Fortran.  When @option{-fopenacc} is specified, the
2170 compiler generates accelerated code according to the OpenACC Application
2171 Programming Interface v2.0 @w{@uref{https://www.openacc.org}}.  This option
2172 implies @option{-pthread}, and thus is only supported on targets that
2173 have support for @option{-pthread}.
2175 @item -fopenacc-dim=@var{geom}
2176 @opindex fopenacc-dim
2177 @cindex OpenACC accelerator programming
2178 Specify default compute dimensions for parallel offload regions that do
2179 not explicitly specify.  The @var{geom} value is a triple of
2180 ':'-separated sizes, in order 'gang', 'worker' and, 'vector'.  A size
2181 can be omitted, to use a target-specific default value.
2183 @item -fopenmp
2184 @opindex fopenmp
2185 @cindex OpenMP parallel
2186 Enable handling of OpenMP directives @code{#pragma omp} in C/C++ and
2187 @code{!$omp} in Fortran.  When @option{-fopenmp} is specified, the
2188 compiler generates parallel code according to the OpenMP Application
2189 Program Interface v4.5 @w{@uref{https://www.openmp.org}}.  This option
2190 implies @option{-pthread}, and thus is only supported on targets that
2191 have support for @option{-pthread}. @option{-fopenmp} implies
2192 @option{-fopenmp-simd}.
2194 @item -fopenmp-simd
2195 @opindex fopenmp-simd
2196 @cindex OpenMP SIMD
2197 @cindex SIMD
2198 Enable handling of OpenMP's SIMD directives with @code{#pragma omp}
2199 in C/C++ and @code{!$omp} in Fortran. Other OpenMP directives
2200 are ignored.
2202 @item -fgnu-tm
2203 @opindex fgnu-tm
2204 When the option @option{-fgnu-tm} is specified, the compiler
2205 generates code for the Linux variant of Intel's current Transactional
2206 Memory ABI specification document (Revision 1.1, May 6 2009).  This is
2207 an experimental feature whose interface may change in future versions
2208 of GCC, as the official specification changes.  Please note that not
2209 all architectures are supported for this feature.
2211 For more information on GCC's support for transactional memory,
2212 @xref{Enabling libitm,,The GNU Transactional Memory Library,libitm,GNU
2213 Transactional Memory Library}.
2215 Note that the transactional memory feature is not supported with
2216 non-call exceptions (@option{-fnon-call-exceptions}).
2218 @item -fms-extensions
2219 @opindex fms-extensions
2220 Accept some non-standard constructs used in Microsoft header files.
2222 In C++ code, this allows member names in structures to be similar
2223 to previous types declarations.
2225 @smallexample
2226 typedef int UOW;
2227 struct ABC @{
2228   UOW UOW;
2230 @end smallexample
2232 Some cases of unnamed fields in structures and unions are only
2233 accepted with this option.  @xref{Unnamed Fields,,Unnamed struct/union
2234 fields within structs/unions}, for details.
2236 Note that this option is off for all targets but x86 
2237 targets using ms-abi.
2239 @item -fplan9-extensions
2240 @opindex fplan9-extensions
2241 Accept some non-standard constructs used in Plan 9 code.
2243 This enables @option{-fms-extensions}, permits passing pointers to
2244 structures with anonymous fields to functions that expect pointers to
2245 elements of the type of the field, and permits referring to anonymous
2246 fields declared using a typedef.  @xref{Unnamed Fields,,Unnamed
2247 struct/union fields within structs/unions}, for details.  This is only
2248 supported for C, not C++.
2250 @item -fcond-mismatch
2251 @opindex fcond-mismatch
2252 Allow conditional expressions with mismatched types in the second and
2253 third arguments.  The value of such an expression is void.  This option
2254 is not supported for C++.
2256 @item -flax-vector-conversions
2257 @opindex flax-vector-conversions
2258 Allow implicit conversions between vectors with differing numbers of
2259 elements and/or incompatible element types.  This option should not be
2260 used for new code.
2262 @item -funsigned-char
2263 @opindex funsigned-char
2264 Let the type @code{char} be unsigned, like @code{unsigned char}.
2266 Each kind of machine has a default for what @code{char} should
2267 be.  It is either like @code{unsigned char} by default or like
2268 @code{signed char} by default.
2270 Ideally, a portable program should always use @code{signed char} or
2271 @code{unsigned char} when it depends on the signedness of an object.
2272 But many programs have been written to use plain @code{char} and
2273 expect it to be signed, or expect it to be unsigned, depending on the
2274 machines they were written for.  This option, and its inverse, let you
2275 make such a program work with the opposite default.
2277 The type @code{char} is always a distinct type from each of
2278 @code{signed char} or @code{unsigned char}, even though its behavior
2279 is always just like one of those two.
2281 @item -fsigned-char
2282 @opindex fsigned-char
2283 Let the type @code{char} be signed, like @code{signed char}.
2285 Note that this is equivalent to @option{-fno-unsigned-char}, which is
2286 the negative form of @option{-funsigned-char}.  Likewise, the option
2287 @option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
2289 @item -fsigned-bitfields
2290 @itemx -funsigned-bitfields
2291 @itemx -fno-signed-bitfields
2292 @itemx -fno-unsigned-bitfields
2293 @opindex fsigned-bitfields
2294 @opindex funsigned-bitfields
2295 @opindex fno-signed-bitfields
2296 @opindex fno-unsigned-bitfields
2297 These options control whether a bit-field is signed or unsigned, when the
2298 declaration does not use either @code{signed} or @code{unsigned}.  By
2299 default, such a bit-field is signed, because this is consistent: the
2300 basic integer types such as @code{int} are signed types.
2302 @item -fsso-struct=@var{endianness}
2303 @opindex fsso-struct
2304 Set the default scalar storage order of structures and unions to the
2305 specified endianness.  The accepted values are @samp{big-endian},
2306 @samp{little-endian} and @samp{native} for the native endianness of
2307 the target (the default).  This option is not supported for C++.
2309 @strong{Warning:} the @option{-fsso-struct} switch causes GCC to generate
2310 code that is not binary compatible with code generated without it if the
2311 specified endianness is not the native endianness of the target.
2312 @end table
2314 @node C++ Dialect Options
2315 @section Options Controlling C++ Dialect
2317 @cindex compiler options, C++
2318 @cindex C++ options, command-line
2319 @cindex options, C++
2320 This section describes the command-line options that are only meaningful
2321 for C++ programs.  You can also use most of the GNU compiler options
2322 regardless of what language your program is in.  For example, you
2323 might compile a file @file{firstClass.C} like this:
2325 @smallexample
2326 g++ -g -fstrict-enums -O -c firstClass.C
2327 @end smallexample
2329 @noindent
2330 In this example, only @option{-fstrict-enums} is an option meant
2331 only for C++ programs; you can use the other options with any
2332 language supported by GCC@.
2334 Some options for compiling C programs, such as @option{-std}, are also
2335 relevant for C++ programs.
2336 @xref{C Dialect Options,,Options Controlling C Dialect}.
2338 Here is a list of options that are @emph{only} for compiling C++ programs:
2340 @table @gcctabopt
2342 @item -fabi-version=@var{n}
2343 @opindex fabi-version
2344 Use version @var{n} of the C++ ABI@.  The default is version 0.
2346 Version 0 refers to the version conforming most closely to
2347 the C++ ABI specification.  Therefore, the ABI obtained using version 0
2348 will change in different versions of G++ as ABI bugs are fixed.
2350 Version 1 is the version of the C++ ABI that first appeared in G++ 3.2.
2352 Version 2 is the version of the C++ ABI that first appeared in G++
2353 3.4, and was the default through G++ 4.9.
2355 Version 3 corrects an error in mangling a constant address as a
2356 template argument.
2358 Version 4, which first appeared in G++ 4.5, implements a standard
2359 mangling for vector types.
2361 Version 5, which first appeared in G++ 4.6, corrects the mangling of
2362 attribute const/volatile on function pointer types, decltype of a
2363 plain decl, and use of a function parameter in the declaration of
2364 another parameter.
2366 Version 6, which first appeared in G++ 4.7, corrects the promotion
2367 behavior of C++11 scoped enums and the mangling of template argument
2368 packs, const/static_cast, prefix ++ and --, and a class scope function
2369 used as a template argument.
2371 Version 7, which first appeared in G++ 4.8, that treats nullptr_t as a
2372 builtin type and corrects the mangling of lambdas in default argument
2373 scope.
2375 Version 8, which first appeared in G++ 4.9, corrects the substitution
2376 behavior of function types with function-cv-qualifiers.
2378 Version 9, which first appeared in G++ 5.2, corrects the alignment of
2379 @code{nullptr_t}.
2381 Version 10, which first appeared in G++ 6.1, adds mangling of
2382 attributes that affect type identity, such as ia32 calling convention
2383 attributes (e.g. @samp{stdcall}).
2385 Version 11, which first appeared in G++ 7, corrects the mangling of
2386 sizeof... expressions and operator names.  For multiple entities with
2387 the same name within a function, that are declared in different scopes,
2388 the mangling now changes starting with the twelfth occurrence.  It also
2389 implies @option{-fnew-inheriting-ctors}.
2391 Version 12, which first appeared in G++ 8, corrects the calling
2392 conventions for empty classes on the x86_64 target and for classes
2393 with only deleted copy/move constructors.  It accidentally changes the
2394 calling convention for classes with a deleted copy constructor and a
2395 trivial move constructor.
2397 Version 13, which first appeared in G++ 8.2, fixes the accidental
2398 change in version 12.
2400 See also @option{-Wabi}.
2402 @item -fabi-compat-version=@var{n}
2403 @opindex fabi-compat-version
2404 On targets that support strong aliases, G++
2405 works around mangling changes by creating an alias with the correct
2406 mangled name when defining a symbol with an incorrect mangled name.
2407 This switch specifies which ABI version to use for the alias.
2409 With @option{-fabi-version=0} (the default), this defaults to 11 (GCC 7
2410 compatibility).  If another ABI version is explicitly selected, this
2411 defaults to 0.  For compatibility with GCC versions 3.2 through 4.9,
2412 use @option{-fabi-compat-version=2}.
2414 If this option is not provided but @option{-Wabi=@var{n}} is, that
2415 version is used for compatibility aliases.  If this option is provided
2416 along with @option{-Wabi} (without the version), the version from this
2417 option is used for the warning.
2419 @item -fno-access-control
2420 @opindex fno-access-control
2421 Turn off all access checking.  This switch is mainly useful for working
2422 around bugs in the access control code.
2424 @item -faligned-new
2425 @opindex faligned-new
2426 Enable support for C++17 @code{new} of types that require more
2427 alignment than @code{void* ::operator new(std::size_t)} provides.  A
2428 numeric argument such as @code{-faligned-new=32} can be used to
2429 specify how much alignment (in bytes) is provided by that function,
2430 but few users will need to override the default of
2431 @code{alignof(std::max_align_t)}.
2433 This flag is enabled by default for @option{-std=c++17}.
2435 @item -fcheck-new
2436 @opindex fcheck-new
2437 Check that the pointer returned by @code{operator new} is non-null
2438 before attempting to modify the storage allocated.  This check is
2439 normally unnecessary because the C++ standard specifies that
2440 @code{operator new} only returns @code{0} if it is declared
2441 @code{throw()}, in which case the compiler always checks the
2442 return value even without this option.  In all other cases, when
2443 @code{operator new} has a non-empty exception specification, memory
2444 exhaustion is signalled by throwing @code{std::bad_alloc}.  See also
2445 @samp{new (nothrow)}.
2447 @item -fconcepts
2448 @opindex fconcepts
2449 Enable support for the C++ Extensions for Concepts Technical
2450 Specification, ISO 19217 (2015), which allows code like
2452 @smallexample
2453 template <class T> concept bool Addable = requires (T t) @{ t + t; @};
2454 template <Addable T> T add (T a, T b) @{ return a + b; @}
2455 @end smallexample
2457 @item -fconstexpr-depth=@var{n}
2458 @opindex fconstexpr-depth
2459 Set the maximum nested evaluation depth for C++11 constexpr functions
2460 to @var{n}.  A limit is needed to detect endless recursion during
2461 constant expression evaluation.  The minimum specified by the standard
2462 is 512.
2464 @item -fconstexpr-loop-limit=@var{n}
2465 @opindex fconstexpr-loop-limit
2466 Set the maximum number of iterations for a loop in C++14 constexpr functions
2467 to @var{n}.  A limit is needed to detect infinite loops during
2468 constant expression evaluation.  The default is 262144 (1<<18).
2470 @item -fdeduce-init-list
2471 @opindex fdeduce-init-list
2472 Enable deduction of a template type parameter as
2473 @code{std::initializer_list} from a brace-enclosed initializer list, i.e.@:
2475 @smallexample
2476 template <class T> auto forward(T t) -> decltype (realfn (t))
2478   return realfn (t);
2481 void f()
2483   forward(@{1,2@}); // call forward<std::initializer_list<int>>
2485 @end smallexample
2487 This deduction was implemented as a possible extension to the
2488 originally proposed semantics for the C++11 standard, but was not part
2489 of the final standard, so it is disabled by default.  This option is
2490 deprecated, and may be removed in a future version of G++.
2492 @item -fno-elide-constructors
2493 @opindex fno-elide-constructors
2494 The C++ standard allows an implementation to omit creating a temporary
2495 that is only used to initialize another object of the same type.
2496 Specifying this option disables that optimization, and forces G++ to
2497 call the copy constructor in all cases.  This option also causes G++
2498 to call trivial member functions which otherwise would be expanded inline.
2500 In C++17, the compiler is required to omit these temporaries, but this
2501 option still affects trivial member functions.
2503 @item -fno-enforce-eh-specs
2504 @opindex fno-enforce-eh-specs
2505 Don't generate code to check for violation of exception specifications
2506 at run time.  This option violates the C++ standard, but may be useful
2507 for reducing code size in production builds, much like defining
2508 @code{NDEBUG}.  This does not give user code permission to throw
2509 exceptions in violation of the exception specifications; the compiler
2510 still optimizes based on the specifications, so throwing an
2511 unexpected exception results in undefined behavior at run time.
2513 @item -fextern-tls-init
2514 @itemx -fno-extern-tls-init
2515 @opindex fextern-tls-init
2516 @opindex fno-extern-tls-init
2517 The C++11 and OpenMP standards allow @code{thread_local} and
2518 @code{threadprivate} variables to have dynamic (runtime)
2519 initialization.  To support this, any use of such a variable goes
2520 through a wrapper function that performs any necessary initialization.
2521 When the use and definition of the variable are in the same
2522 translation unit, this overhead can be optimized away, but when the
2523 use is in a different translation unit there is significant overhead
2524 even if the variable doesn't actually need dynamic initialization.  If
2525 the programmer can be sure that no use of the variable in a
2526 non-defining TU needs to trigger dynamic initialization (either
2527 because the variable is statically initialized, or a use of the
2528 variable in the defining TU will be executed before any uses in
2529 another TU), they can avoid this overhead with the
2530 @option{-fno-extern-tls-init} option.
2532 On targets that support symbol aliases, the default is
2533 @option{-fextern-tls-init}.  On targets that do not support symbol
2534 aliases, the default is @option{-fno-extern-tls-init}.
2536 @item -fno-gnu-keywords
2537 @opindex fno-gnu-keywords
2538 Do not recognize @code{typeof} as a keyword, so that code can use this
2539 word as an identifier.  You can use the keyword @code{__typeof__} instead.
2540 This option is implied by the strict ISO C++ dialects: @option{-ansi},
2541 @option{-std=c++98}, @option{-std=c++11}, etc.
2543 @item -fno-implicit-templates
2544 @opindex fno-implicit-templates
2545 Never emit code for non-inline templates that are instantiated
2546 implicitly (i.e.@: by use); only emit code for explicit instantiations.
2547 @xref{Template Instantiation}, for more information.
2549 @item -fno-implicit-inline-templates
2550 @opindex fno-implicit-inline-templates
2551 Don't emit code for implicit instantiations of inline templates, either.
2552 The default is to handle inlines differently so that compiles with and
2553 without optimization need the same set of explicit instantiations.
2555 @item -fno-implement-inlines
2556 @opindex fno-implement-inlines
2557 To save space, do not emit out-of-line copies of inline functions
2558 controlled by @code{#pragma implementation}.  This causes linker
2559 errors if these functions are not inlined everywhere they are called.
2561 @item -fms-extensions
2562 @opindex fms-extensions
2563 Disable Wpedantic warnings about constructs used in MFC, such as implicit
2564 int and getting a pointer to member function via non-standard syntax.
2566 @item -fnew-inheriting-ctors
2567 @opindex fnew-inheriting-ctors
2568 Enable the P0136 adjustment to the semantics of C++11 constructor
2569 inheritance.  This is part of C++17 but also considered to be a Defect
2570 Report against C++11 and C++14.  This flag is enabled by default
2571 unless @option{-fabi-version=10} or lower is specified.
2573 @item -fnew-ttp-matching
2574 @opindex fnew-ttp-matching
2575 Enable the P0522 resolution to Core issue 150, template template
2576 parameters and default arguments: this allows a template with default
2577 template arguments as an argument for a template template parameter
2578 with fewer template parameters.  This flag is enabled by default for
2579 @option{-std=c++17}.
2581 @item -fno-nonansi-builtins
2582 @opindex fno-nonansi-builtins
2583 Disable built-in declarations of functions that are not mandated by
2584 ANSI/ISO C@.  These include @code{ffs}, @code{alloca}, @code{_exit},
2585 @code{index}, @code{bzero}, @code{conjf}, and other related functions.
2587 @item -fnothrow-opt
2588 @opindex fnothrow-opt
2589 Treat a @code{throw()} exception specification as if it were a
2590 @code{noexcept} specification to reduce or eliminate the text size
2591 overhead relative to a function with no exception specification.  If
2592 the function has local variables of types with non-trivial
2593 destructors, the exception specification actually makes the
2594 function smaller because the EH cleanups for those variables can be
2595 optimized away.  The semantic effect is that an exception thrown out of
2596 a function with such an exception specification results in a call
2597 to @code{terminate} rather than @code{unexpected}.
2599 @item -fno-operator-names
2600 @opindex fno-operator-names
2601 Do not treat the operator name keywords @code{and}, @code{bitand},
2602 @code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
2603 synonyms as keywords.
2605 @item -fno-optional-diags
2606 @opindex fno-optional-diags
2607 Disable diagnostics that the standard says a compiler does not need to
2608 issue.  Currently, the only such diagnostic issued by G++ is the one for
2609 a name having multiple meanings within a class.
2611 @item -fpermissive
2612 @opindex fpermissive
2613 Downgrade some diagnostics about nonconformant code from errors to
2614 warnings.  Thus, using @option{-fpermissive} allows some
2615 nonconforming code to compile.
2617 @item -fno-pretty-templates
2618 @opindex fno-pretty-templates
2619 When an error message refers to a specialization of a function
2620 template, the compiler normally prints the signature of the
2621 template followed by the template arguments and any typedefs or
2622 typenames in the signature (e.g. @code{void f(T) [with T = int]}
2623 rather than @code{void f(int)}) so that it's clear which template is
2624 involved.  When an error message refers to a specialization of a class
2625 template, the compiler omits any template arguments that match
2626 the default template arguments for that template.  If either of these
2627 behaviors make it harder to understand the error message rather than
2628 easier, you can use @option{-fno-pretty-templates} to disable them.
2630 @item -frepo
2631 @opindex frepo
2632 Enable automatic template instantiation at link time.  This option also
2633 implies @option{-fno-implicit-templates}.  @xref{Template
2634 Instantiation}, for more information.
2636 @item -fno-rtti
2637 @opindex fno-rtti
2638 Disable generation of information about every class with virtual
2639 functions for use by the C++ run-time type identification features
2640 (@code{dynamic_cast} and @code{typeid}).  If you don't use those parts
2641 of the language, you can save some space by using this flag.  Note that
2642 exception handling uses the same information, but G++ generates it as
2643 needed. The @code{dynamic_cast} operator can still be used for casts that
2644 do not require run-time type information, i.e.@: casts to @code{void *} or to
2645 unambiguous base classes.
2647 @item -fsized-deallocation
2648 @opindex fsized-deallocation
2649 Enable the built-in global declarations
2650 @smallexample
2651 void operator delete (void *, std::size_t) noexcept;
2652 void operator delete[] (void *, std::size_t) noexcept;
2653 @end smallexample
2654 as introduced in C++14.  This is useful for user-defined replacement
2655 deallocation functions that, for example, use the size of the object
2656 to make deallocation faster.  Enabled by default under
2657 @option{-std=c++14} and above.  The flag @option{-Wsized-deallocation}
2658 warns about places that might want to add a definition.
2660 @item -fstrict-enums
2661 @opindex fstrict-enums
2662 Allow the compiler to optimize using the assumption that a value of
2663 enumerated type can only be one of the values of the enumeration (as
2664 defined in the C++ standard; basically, a value that can be
2665 represented in the minimum number of bits needed to represent all the
2666 enumerators).  This assumption may not be valid if the program uses a
2667 cast to convert an arbitrary integer value to the enumerated type.
2669 @item -fstrong-eval-order
2670 @opindex fstrong-eval-order
2671 Evaluate member access, array subscripting, and shift expressions in
2672 left-to-right order, and evaluate assignment in right-to-left order,
2673 as adopted for C++17.  Enabled by default with @option{-std=c++17}.
2674 @option{-fstrong-eval-order=some} enables just the ordering of member
2675 access and shift expressions, and is the default without
2676 @option{-std=c++17}.
2678 @item -ftemplate-backtrace-limit=@var{n}
2679 @opindex ftemplate-backtrace-limit
2680 Set the maximum number of template instantiation notes for a single
2681 warning or error to @var{n}.  The default value is 10.
2683 @item -ftemplate-depth=@var{n}
2684 @opindex ftemplate-depth
2685 Set the maximum instantiation depth for template classes to @var{n}.
2686 A limit on the template instantiation depth is needed to detect
2687 endless recursions during template class instantiation.  ANSI/ISO C++
2688 conforming programs must not rely on a maximum depth greater than 17
2689 (changed to 1024 in C++11).  The default value is 900, as the compiler
2690 can run out of stack space before hitting 1024 in some situations.
2692 @item -fno-threadsafe-statics
2693 @opindex fno-threadsafe-statics
2694 Do not emit the extra code to use the routines specified in the C++
2695 ABI for thread-safe initialization of local statics.  You can use this
2696 option to reduce code size slightly in code that doesn't need to be
2697 thread-safe.
2699 @item -fuse-cxa-atexit
2700 @opindex fuse-cxa-atexit
2701 Register destructors for objects with static storage duration with the
2702 @code{__cxa_atexit} function rather than the @code{atexit} function.
2703 This option is required for fully standards-compliant handling of static
2704 destructors, but only works if your C library supports
2705 @code{__cxa_atexit}.
2707 @item -fno-use-cxa-get-exception-ptr
2708 @opindex fno-use-cxa-get-exception-ptr
2709 Don't use the @code{__cxa_get_exception_ptr} runtime routine.  This
2710 causes @code{std::uncaught_exception} to be incorrect, but is necessary
2711 if the runtime routine is not available.
2713 @item -fvisibility-inlines-hidden
2714 @opindex fvisibility-inlines-hidden
2715 This switch declares that the user does not attempt to compare
2716 pointers to inline functions or methods where the addresses of the two functions
2717 are taken in different shared objects.
2719 The effect of this is that GCC may, effectively, mark inline methods with
2720 @code{__attribute__ ((visibility ("hidden")))} so that they do not
2721 appear in the export table of a DSO and do not require a PLT indirection
2722 when used within the DSO@.  Enabling this option can have a dramatic effect
2723 on load and link times of a DSO as it massively reduces the size of the
2724 dynamic export table when the library makes heavy use of templates.
2726 The behavior of this switch is not quite the same as marking the
2727 methods as hidden directly, because it does not affect static variables
2728 local to the function or cause the compiler to deduce that
2729 the function is defined in only one shared object.
2731 You may mark a method as having a visibility explicitly to negate the
2732 effect of the switch for that method.  For example, if you do want to
2733 compare pointers to a particular inline method, you might mark it as
2734 having default visibility.  Marking the enclosing class with explicit
2735 visibility has no effect.
2737 Explicitly instantiated inline methods are unaffected by this option
2738 as their linkage might otherwise cross a shared library boundary.
2739 @xref{Template Instantiation}.
2741 @item -fvisibility-ms-compat
2742 @opindex fvisibility-ms-compat
2743 This flag attempts to use visibility settings to make GCC's C++
2744 linkage model compatible with that of Microsoft Visual Studio.
2746 The flag makes these changes to GCC's linkage model:
2748 @enumerate
2749 @item
2750 It sets the default visibility to @code{hidden}, like
2751 @option{-fvisibility=hidden}.
2753 @item
2754 Types, but not their members, are not hidden by default.
2756 @item
2757 The One Definition Rule is relaxed for types without explicit
2758 visibility specifications that are defined in more than one
2759 shared object: those declarations are permitted if they are
2760 permitted when this option is not used.
2761 @end enumerate
2763 In new code it is better to use @option{-fvisibility=hidden} and
2764 export those classes that are intended to be externally visible.
2765 Unfortunately it is possible for code to rely, perhaps accidentally,
2766 on the Visual Studio behavior.
2768 Among the consequences of these changes are that static data members
2769 of the same type with the same name but defined in different shared
2770 objects are different, so changing one does not change the other;
2771 and that pointers to function members defined in different shared
2772 objects may not compare equal.  When this flag is given, it is a
2773 violation of the ODR to define types with the same name differently.
2775 @item -fno-weak
2776 @opindex fno-weak
2777 Do not use weak symbol support, even if it is provided by the linker.
2778 By default, G++ uses weak symbols if they are available.  This
2779 option exists only for testing, and should not be used by end-users;
2780 it results in inferior code and has no benefits.  This option may
2781 be removed in a future release of G++.
2783 @item -nostdinc++
2784 @opindex nostdinc++
2785 Do not search for header files in the standard directories specific to
2786 C++, but do still search the other standard directories.  (This option
2787 is used when building the C++ library.)
2788 @end table
2790 In addition, these optimization, warning, and code generation options
2791 have meanings only for C++ programs:
2793 @table @gcctabopt
2794 @item -Wabi @r{(C, Objective-C, C++ and Objective-C++ only)}
2795 @opindex Wabi
2796 @opindex Wno-abi
2797 Warn when G++ it generates code that is probably not compatible with
2798 the vendor-neutral C++ ABI@.  Since G++ now defaults to updating the
2799 ABI with each major release, normally @option{-Wabi} will warn only if
2800 there is a check added later in a release series for an ABI issue
2801 discovered since the initial release.  @option{-Wabi} will warn about
2802 more things if an older ABI version is selected (with
2803 @option{-fabi-version=@var{n}}).
2805 @option{-Wabi} can also be used with an explicit version number to
2806 warn about compatibility with a particular @option{-fabi-version}
2807 level, e.g. @option{-Wabi=2} to warn about changes relative to
2808 @option{-fabi-version=2}.
2810 If an explicit version number is provided and
2811 @option{-fabi-compat-version} is not specified, the version number
2812 from this option is used for compatibility aliases.  If no explicit
2813 version number is provided with this option, but
2814 @option{-fabi-compat-version} is specified, that version number is
2815 used for ABI warnings.
2817 Although an effort has been made to warn about
2818 all such cases, there are probably some cases that are not warned about,
2819 even though G++ is generating incompatible code.  There may also be
2820 cases where warnings are emitted even though the code that is generated
2821 is compatible.
2823 You should rewrite your code to avoid these warnings if you are
2824 concerned about the fact that code generated by G++ may not be binary
2825 compatible with code generated by other compilers.
2827 Known incompatibilities in @option{-fabi-version=2} (which was the
2828 default from GCC 3.4 to 4.9) include:
2830 @itemize @bullet
2832 @item
2833 A template with a non-type template parameter of reference type was
2834 mangled incorrectly:
2835 @smallexample
2836 extern int N;
2837 template <int &> struct S @{@};
2838 void n (S<N>) @{2@}
2839 @end smallexample
2841 This was fixed in @option{-fabi-version=3}.
2843 @item
2844 SIMD vector types declared using @code{__attribute ((vector_size))} were
2845 mangled in a non-standard way that does not allow for overloading of
2846 functions taking vectors of different sizes.
2848 The mangling was changed in @option{-fabi-version=4}.
2850 @item
2851 @code{__attribute ((const))} and @code{noreturn} were mangled as type
2852 qualifiers, and @code{decltype} of a plain declaration was folded away.
2854 These mangling issues were fixed in @option{-fabi-version=5}.
2856 @item
2857 Scoped enumerators passed as arguments to a variadic function are
2858 promoted like unscoped enumerators, causing @code{va_arg} to complain.
2859 On most targets this does not actually affect the parameter passing
2860 ABI, as there is no way to pass an argument smaller than @code{int}.
2862 Also, the ABI changed the mangling of template argument packs,
2863 @code{const_cast}, @code{static_cast}, prefix increment/decrement, and
2864 a class scope function used as a template argument.
2866 These issues were corrected in @option{-fabi-version=6}.
2868 @item
2869 Lambdas in default argument scope were mangled incorrectly, and the
2870 ABI changed the mangling of @code{nullptr_t}.
2872 These issues were corrected in @option{-fabi-version=7}.
2874 @item
2875 When mangling a function type with function-cv-qualifiers, the
2876 un-qualified function type was incorrectly treated as a substitution
2877 candidate.
2879 This was fixed in @option{-fabi-version=8}, the default for GCC 5.1.
2881 @item
2882 @code{decltype(nullptr)} incorrectly had an alignment of 1, leading to
2883 unaligned accesses.  Note that this did not affect the ABI of a
2884 function with a @code{nullptr_t} parameter, as parameters have a
2885 minimum alignment.
2887 This was fixed in @option{-fabi-version=9}, the default for GCC 5.2.
2889 @item
2890 Target-specific attributes that affect the identity of a type, such as
2891 ia32 calling conventions on a function type (stdcall, regparm, etc.),
2892 did not affect the mangled name, leading to name collisions when
2893 function pointers were used as template arguments.
2895 This was fixed in @option{-fabi-version=10}, the default for GCC 6.1.
2897 @end itemize
2899 It also warns about psABI-related changes.  The known psABI changes at this
2900 point include:
2902 @itemize @bullet
2904 @item
2905 For SysV/x86-64, unions with @code{long double} members are 
2906 passed in memory as specified in psABI.  For example:
2908 @smallexample
2909 union U @{
2910   long double ld;
2911   int i;
2913 @end smallexample
2915 @noindent
2916 @code{union U} is always passed in memory.
2918 @end itemize
2920 @item -Wabi-tag @r{(C++ and Objective-C++ only)}
2921 @opindex Wabi-tag
2922 @opindex -Wabi-tag
2923 Warn when a type with an ABI tag is used in a context that does not
2924 have that ABI tag.  See @ref{C++ Attributes} for more information
2925 about ABI tags.
2927 @item -Wctor-dtor-privacy @r{(C++ and Objective-C++ only)}
2928 @opindex Wctor-dtor-privacy
2929 @opindex Wno-ctor-dtor-privacy
2930 Warn when a class seems unusable because all the constructors or
2931 destructors in that class are private, and it has neither friends nor
2932 public static member functions.  Also warn if there are no non-private
2933 methods, and there's at least one private member function that isn't
2934 a constructor or destructor.
2936 @item -Wdelete-non-virtual-dtor @r{(C++ and Objective-C++ only)}
2937 @opindex Wdelete-non-virtual-dtor
2938 @opindex Wno-delete-non-virtual-dtor
2939 Warn when @code{delete} is used to destroy an instance of a class that
2940 has virtual functions and non-virtual destructor. It is unsafe to delete
2941 an instance of a derived class through a pointer to a base class if the
2942 base class does not have a virtual destructor.  This warning is enabled
2943 by @option{-Wall}.
2945 @item -Wdeprecated-copy @r{(C++ and Objective-C++ only)}
2946 @opindex Wdeprecated-copy
2947 @opindex Wno-deprecated-copy
2948 Warn that the implicit declaration of a copy constructor or copy
2949 assignment operator is deprecated if the class has a user-provided
2950 copy constructor, copy assignment operator, or destructor, in C++11
2951 and up.  This warning is enabled by @option{-Wall}.
2953 @item -Wno-init-list-lifetime @r{(C++ and Objective-C++ only)}
2954 @opindex Winit-list-lifetime
2955 @opindex Wno-init-list-lifetime
2956 Do not warn about uses of @code{std::initializer_list} that are likely
2957 to result in dangling pointers.  Since the underlying array for an
2958 @code{initializer_list} is handled like a normal C++ temporary object,
2959 it is easy to inadvertently keep a pointer to the array past the end
2960 of the array's lifetime.  For example:
2962 @itemize @bullet
2963 @item
2964 If a function returns a temporary @code{initializer_list}, or a local
2965 @code{initializer_list} variable, the array's lifetime ends at the end
2966 of the return statement, so the value returned has a dangling pointer.
2968 @item
2969 If a new-expression creates an @code{initializer_list}, the array only
2970 lives until the end of the enclosing full-expression, so the
2971 @code{initializer_list} in the heap has a dangling pointer.
2973 @item
2974 When an @code{initializer_list} variable is assigned from a
2975 brace-enclosed initializer list, the temporary array created for the
2976 right side of the assignment only lives until the end of the
2977 full-expression, so at the next statement the @code{initializer_list}
2978 variable has a dangling pointer.
2980 @smallexample
2981 // li's initial underlying array lives as long as li
2982 std::initializer_list<int> li = @{ 1,2,3 @};
2983 // assignment changes li to point to a temporary array
2984 li = @{ 4, 5 @};
2985 // now the temporary is gone and li has a dangling pointer
2986 int i = li.begin()[0] // undefined behavior
2987 @end smallexample
2989 @item
2990 When a list constructor stores the @code{begin} pointer from the
2991 @code{initializer_list} argument, this doesn't extend the lifetime of
2992 the array, so if a class variable is constructed from a temporary
2993 @code{initializer_list}, the pointer is left dangling by the end of
2994 the variable declaration statement.
2996 @end itemize
2998 @item -Wliteral-suffix @r{(C++ and Objective-C++ only)}
2999 @opindex Wliteral-suffix
3000 @opindex Wno-literal-suffix
3001 Warn when a string or character literal is followed by a ud-suffix which does
3002 not begin with an underscore.  As a conforming extension, GCC treats such
3003 suffixes as separate preprocessing tokens in order to maintain backwards
3004 compatibility with code that uses formatting macros from @code{<inttypes.h>}.
3005 For example:
3007 @smallexample
3008 #define __STDC_FORMAT_MACROS
3009 #include <inttypes.h>
3010 #include <stdio.h>
3012 int main() @{
3013   int64_t i64 = 123;
3014   printf("My int64: %" PRId64"\n", i64);
3016 @end smallexample
3018 In this case, @code{PRId64} is treated as a separate preprocessing token.
3020 Additionally, warn when a user-defined literal operator is declared with
3021 a literal suffix identifier that doesn't begin with an underscore. Literal
3022 suffix identifiers that don't begin with an underscore are reserved for
3023 future standardization.
3025 This warning is enabled by default.
3027 @item -Wlto-type-mismatch
3028 @opindex Wlto-type-mismatch
3029 @opindex Wno-lto-type-mismatch
3031 During the link-time optimization warn about type mismatches in
3032 global declarations from different compilation units.
3033 Requires @option{-flto} to be enabled.  Enabled by default.
3035 @item -Wno-narrowing @r{(C++ and Objective-C++ only)}
3036 @opindex Wnarrowing
3037 @opindex Wno-narrowing
3038 For C++11 and later standards, narrowing conversions are diagnosed by default,
3039 as required by the standard.  A narrowing conversion from a constant produces
3040 an error, and a narrowing conversion from a non-constant produces a warning,
3041 but @option{-Wno-narrowing} suppresses the diagnostic.
3042 Note that this does not affect the meaning of well-formed code;
3043 narrowing conversions are still considered ill-formed in SFINAE contexts.
3045 With @option{-Wnarrowing} in C++98, warn when a narrowing
3046 conversion prohibited by C++11 occurs within
3047 @samp{@{ @}}, e.g.
3049 @smallexample
3050 int i = @{ 2.2 @}; // error: narrowing from double to int
3051 @end smallexample
3053 This flag is included in @option{-Wall} and @option{-Wc++11-compat}.
3055 @item -Wnoexcept @r{(C++ and Objective-C++ only)}
3056 @opindex Wnoexcept
3057 @opindex Wno-noexcept
3058 Warn when a noexcept-expression evaluates to false because of a call
3059 to a function that does not have a non-throwing exception
3060 specification (i.e. @code{throw()} or @code{noexcept}) but is known by
3061 the compiler to never throw an exception.
3063 @item -Wnoexcept-type @r{(C++ and Objective-C++ only)}
3064 @opindex Wnoexcept-type
3065 @opindex Wno-noexcept-type
3066 Warn if the C++17 feature making @code{noexcept} part of a function
3067 type changes the mangled name of a symbol relative to C++14.  Enabled
3068 by @option{-Wabi} and @option{-Wc++17-compat}.
3070 As an example:
3072 @smallexample
3073 template <class T> void f(T t) @{ t(); @};
3074 void g() noexcept;
3075 void h() @{ f(g); @} 
3076 @end smallexample
3078 @noindent
3079 In C++14, @code{f} calls @code{f<void(*)()>}, but in
3080 C++17 it calls @code{f<void(*)()noexcept>}.
3082 @item -Wclass-memaccess @r{(C++ and Objective-C++ only)}
3083 @opindex Wclass-memaccess
3084 @opindex Wno-class-memaccess
3085 Warn when the destination of a call to a raw memory function such as
3086 @code{memset} or @code{memcpy} is an object of class type, and when writing
3087 into such an object might bypass the class non-trivial or deleted constructor
3088 or copy assignment, violate const-correctness or encapsulation, or corrupt
3089 virtual table pointers.  Modifying the representation of such objects may
3090 violate invariants maintained by member functions of the class.  For example,
3091 the call to @code{memset} below is undefined because it modifies a non-trivial
3092 class object and is, therefore, diagnosed.  The safe way to either initialize
3093 or clear the storage of objects of such types is by using the appropriate
3094 constructor or assignment operator, if one is available.
3095 @smallexample
3096 std::string str = "abc";
3097 memset (&str, 0, sizeof str);
3098 @end smallexample
3099 The @option{-Wclass-memaccess} option is enabled by @option{-Wall}.
3100 Explicitly casting the pointer to the class object to @code{void *} or
3101 to a type that can be safely accessed by the raw memory function suppresses
3102 the warning.
3104 @item -Wnon-virtual-dtor @r{(C++ and Objective-C++ only)}
3105 @opindex Wnon-virtual-dtor
3106 @opindex Wno-non-virtual-dtor
3107 Warn when a class has virtual functions and an accessible non-virtual
3108 destructor itself or in an accessible polymorphic base class, in which
3109 case it is possible but unsafe to delete an instance of a derived
3110 class through a pointer to the class itself or base class.  This
3111 warning is automatically enabled if @option{-Weffc++} is specified.
3113 @item -Wregister @r{(C++ and Objective-C++ only)}
3114 @opindex Wregister
3115 @opindex Wno-register
3116 Warn on uses of the @code{register} storage class specifier, except
3117 when it is part of the GNU @ref{Explicit Register Variables} extension.
3118 The use of the @code{register} keyword as storage class specifier has
3119 been deprecated in C++11 and removed in C++17.
3120 Enabled by default with @option{-std=c++17}.
3122 @item -Wreorder @r{(C++ and Objective-C++ only)}
3123 @opindex Wreorder
3124 @opindex Wno-reorder
3125 @cindex reordering, warning
3126 @cindex warning for reordering of member initializers
3127 Warn when the order of member initializers given in the code does not
3128 match the order in which they must be executed.  For instance:
3130 @smallexample
3131 struct A @{
3132   int i;
3133   int j;
3134   A(): j (0), i (1) @{ @}
3136 @end smallexample
3138 @noindent
3139 The compiler rearranges the member initializers for @code{i}
3140 and @code{j} to match the declaration order of the members, emitting
3141 a warning to that effect.  This warning is enabled by @option{-Wall}.
3143 @item -Wno-pessimizing-move @r{(C++ and Objective-C++ only)}
3144 @opindex Wpessimizing-move
3145 @opindex Wno-pessimizing-move
3146 This warning warns when a call to @code{std::move} prevents copy
3147 elision.  A typical scenario when copy elision can occur is when returning in
3148 a function with a class return type, when the expression being returned is the
3149 name of a non-volatile automatic object, and is not a function parameter, and
3150 has the same type as the function return type.
3152 @smallexample
3153 struct T @{
3154 @dots{}
3156 T fn()
3158   T t;
3159   @dots{}
3160   return std::move (t);
3162 @end smallexample
3164 But in this example, the @code{std::move} call prevents copy elision.
3166 This warning is enabled by @option{-Wall}.
3168 @item -Wno-redundant-move @r{(C++ and Objective-C++ only)}
3169 @opindex Wredundant-move
3170 @opindex Wno-redundant-move
3171 This warning warns about redundant calls to @code{std::move}; that is, when
3172 a move operation would have been performed even without the @code{std::move}
3173 call.  This happens because the compiler is forced to treat the object as if
3174 it were an rvalue in certain situations such as returning a local variable,
3175 where copy elision isn't applicable.  Consider:
3177 @smallexample
3178 struct T @{
3179 @dots{}
3181 T fn(T t)
3183   @dots{}
3184   return std::move (t);
3186 @end smallexample
3188 Here, the @code{std::move} call is redundant.  Because G++ implements Core
3189 Issue 1579, another example is:
3191 @smallexample
3192 struct T @{ // convertible to U
3193 @dots{}
3195 struct U @{
3196 @dots{}
3198 U fn()
3200   T t;
3201   @dots{}
3202   return std::move (t);
3204 @end smallexample
3205 In this example, copy elision isn't applicable because the type of the
3206 expression being returned and the function return type differ, yet G++
3207 treats the return value as if it were designated by an rvalue.
3209 This warning is enabled by @option{-Wextra}.
3211 @item -fext-numeric-literals @r{(C++ and Objective-C++ only)}
3212 @opindex fext-numeric-literals
3213 @opindex fno-ext-numeric-literals
3214 Accept imaginary, fixed-point, or machine-defined
3215 literal number suffixes as GNU extensions.
3216 When this option is turned off these suffixes are treated
3217 as C++11 user-defined literal numeric suffixes.
3218 This is on by default for all pre-C++11 dialects and all GNU dialects:
3219 @option{-std=c++98}, @option{-std=gnu++98}, @option{-std=gnu++11},
3220 @option{-std=gnu++14}.
3221 This option is off by default
3222 for ISO C++11 onwards (@option{-std=c++11}, ...).
3223 @end table
3225 The following @option{-W@dots{}} options are not affected by @option{-Wall}.
3227 @table @gcctabopt
3228 @item -Weffc++ @r{(C++ and Objective-C++ only)}
3229 @opindex Weffc++
3230 @opindex Wno-effc++
3231 Warn about violations of the following style guidelines from Scott Meyers'
3232 @cite{Effective C++} series of books:
3234 @itemize @bullet
3235 @item
3236 Define a copy constructor and an assignment operator for classes
3237 with dynamically-allocated memory.
3239 @item
3240 Prefer initialization to assignment in constructors.
3242 @item
3243 Have @code{operator=} return a reference to @code{*this}.
3245 @item
3246 Don't try to return a reference when you must return an object.
3248 @item
3249 Distinguish between prefix and postfix forms of increment and
3250 decrement operators.
3252 @item
3253 Never overload @code{&&}, @code{||}, or @code{,}.
3255 @end itemize
3257 This option also enables @option{-Wnon-virtual-dtor}, which is also
3258 one of the effective C++ recommendations.  However, the check is
3259 extended to warn about the lack of virtual destructor in accessible
3260 non-polymorphic bases classes too.
3262 When selecting this option, be aware that the standard library
3263 headers do not obey all of these guidelines; use @samp{grep -v}
3264 to filter out those warnings.
3266 @item -Wstrict-null-sentinel @r{(C++ and Objective-C++ only)}
3267 @opindex Wstrict-null-sentinel
3268 @opindex Wno-strict-null-sentinel
3269 Warn about the use of an uncasted @code{NULL} as sentinel.  When
3270 compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
3271 to @code{__null}.  Although it is a null pointer constant rather than a
3272 null pointer, it is guaranteed to be of the same size as a pointer.
3273 But this use is not portable across different compilers.
3275 @item -Wno-non-template-friend @r{(C++ and Objective-C++ only)}
3276 @opindex Wno-non-template-friend
3277 @opindex Wnon-template-friend
3278 Disable warnings when non-template friend functions are declared
3279 within a template.  In very old versions of GCC that predate implementation
3280 of the ISO standard, declarations such as 
3281 @samp{friend int foo(int)}, where the name of the friend is an unqualified-id,
3282 could be interpreted as a particular specialization of a template
3283 function; the warning exists to diagnose compatibility problems, 
3284 and is enabled by default.
3286 @item -Wold-style-cast @r{(C++ and Objective-C++ only)}
3287 @opindex Wold-style-cast
3288 @opindex Wno-old-style-cast
3289 Warn if an old-style (C-style) cast to a non-void type is used within
3290 a C++ program.  The new-style casts (@code{dynamic_cast},
3291 @code{static_cast}, @code{reinterpret_cast}, and @code{const_cast}) are
3292 less vulnerable to unintended effects and much easier to search for.
3294 @item -Woverloaded-virtual @r{(C++ and Objective-C++ only)}
3295 @opindex Woverloaded-virtual
3296 @opindex Wno-overloaded-virtual
3297 @cindex overloaded virtual function, warning
3298 @cindex warning for overloaded virtual function
3299 Warn when a function declaration hides virtual functions from a
3300 base class.  For example, in:
3302 @smallexample
3303 struct A @{
3304   virtual void f();
3307 struct B: public A @{
3308   void f(int);
3310 @end smallexample
3312 the @code{A} class version of @code{f} is hidden in @code{B}, and code
3313 like:
3315 @smallexample
3316 B* b;
3317 b->f();
3318 @end smallexample
3320 @noindent
3321 fails to compile.
3323 @item -Wno-pmf-conversions @r{(C++ and Objective-C++ only)}
3324 @opindex Wno-pmf-conversions
3325 @opindex Wpmf-conversions
3326 Disable the diagnostic for converting a bound pointer to member function
3327 to a plain pointer.
3329 @item -Wsign-promo @r{(C++ and Objective-C++ only)}
3330 @opindex Wsign-promo
3331 @opindex Wno-sign-promo
3332 Warn when overload resolution chooses a promotion from unsigned or
3333 enumerated type to a signed type, over a conversion to an unsigned type of
3334 the same size.  Previous versions of G++ tried to preserve
3335 unsignedness, but the standard mandates the current behavior.
3337 @item -Wtemplates @r{(C++ and Objective-C++ only)}
3338 @opindex Wtemplates
3339 @opindex Wno-templates
3340 Warn when a primary template declaration is encountered.  Some coding
3341 rules disallow templates, and this may be used to enforce that rule.
3342 The warning is inactive inside a system header file, such as the STL, so
3343 one can still use the STL.  One may also instantiate or specialize
3344 templates.
3346 @item -Wmultiple-inheritance @r{(C++ and Objective-C++ only)}
3347 @opindex Wmultiple-inheritance
3348 @opindex Wno-multiple-inheritance
3349 Warn when a class is defined with multiple direct base classes.  Some
3350 coding rules disallow multiple inheritance, and this may be used to
3351 enforce that rule.  The warning is inactive inside a system header file,
3352 such as the STL, so one can still use the STL.  One may also define
3353 classes that indirectly use multiple inheritance.
3355 @item -Wvirtual-inheritance
3356 @opindex Wvirtual-inheritance
3357 @opindex Wno-virtual-inheritance
3358 Warn when a class is defined with a virtual direct base class.  Some
3359 coding rules disallow multiple inheritance, and this may be used to
3360 enforce that rule.  The warning is inactive inside a system header file,
3361 such as the STL, so one can still use the STL.  One may also define
3362 classes that indirectly use virtual inheritance.
3364 @item -Wnamespaces
3365 @opindex Wnamespaces
3366 @opindex Wno-namespaces
3367 Warn when a namespace definition is opened.  Some coding rules disallow
3368 namespaces, and this may be used to enforce that rule.  The warning is
3369 inactive inside a system header file, such as the STL, so one can still
3370 use the STL.  One may also use using directives and qualified names.
3372 @item -Wno-terminate @r{(C++ and Objective-C++ only)}
3373 @opindex Wterminate
3374 @opindex Wno-terminate
3375 Disable the warning about a throw-expression that will immediately
3376 result in a call to @code{terminate}.
3378 @item -Wno-class-conversion @r{(C++ and Objective-C++ only)}
3379 @opindex Wno-class-conversion
3380 @opindex Wclass-conversion
3381 Disable the warning about the case when a conversion function converts an
3382 object to the same type, to a base class of that type, or to void; such
3383 a conversion function will never be called.
3384 @end table
3386 @node Objective-C and Objective-C++ Dialect Options
3387 @section Options Controlling Objective-C and Objective-C++ Dialects
3389 @cindex compiler options, Objective-C and Objective-C++
3390 @cindex Objective-C and Objective-C++ options, command-line
3391 @cindex options, Objective-C and Objective-C++
3392 (NOTE: This manual does not describe the Objective-C and Objective-C++
3393 languages themselves.  @xref{Standards,,Language Standards
3394 Supported by GCC}, for references.)
3396 This section describes the command-line options that are only meaningful
3397 for Objective-C and Objective-C++ programs.  You can also use most of
3398 the language-independent GNU compiler options.
3399 For example, you might compile a file @file{some_class.m} like this:
3401 @smallexample
3402 gcc -g -fgnu-runtime -O -c some_class.m
3403 @end smallexample
3405 @noindent
3406 In this example, @option{-fgnu-runtime} is an option meant only for
3407 Objective-C and Objective-C++ programs; you can use the other options with
3408 any language supported by GCC@.
3410 Note that since Objective-C is an extension of the C language, Objective-C
3411 compilations may also use options specific to the C front-end (e.g.,
3412 @option{-Wtraditional}).  Similarly, Objective-C++ compilations may use
3413 C++-specific options (e.g., @option{-Wabi}).
3415 Here is a list of options that are @emph{only} for compiling Objective-C
3416 and Objective-C++ programs:
3418 @table @gcctabopt
3419 @item -fconstant-string-class=@var{class-name}
3420 @opindex fconstant-string-class
3421 Use @var{class-name} as the name of the class to instantiate for each
3422 literal string specified with the syntax @code{@@"@dots{}"}.  The default
3423 class name is @code{NXConstantString} if the GNU runtime is being used, and
3424 @code{NSConstantString} if the NeXT runtime is being used (see below).  The
3425 @option{-fconstant-cfstrings} option, if also present, overrides the
3426 @option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} literals
3427 to be laid out as constant CoreFoundation strings.
3429 @item -fgnu-runtime
3430 @opindex fgnu-runtime
3431 Generate object code compatible with the standard GNU Objective-C
3432 runtime.  This is the default for most types of systems.
3434 @item -fnext-runtime
3435 @opindex fnext-runtime
3436 Generate output compatible with the NeXT runtime.  This is the default
3437 for NeXT-based systems, including Darwin and Mac OS X@.  The macro
3438 @code{__NEXT_RUNTIME__} is predefined if (and only if) this option is
3439 used.
3441 @item -fno-nil-receivers
3442 @opindex fno-nil-receivers
3443 Assume that all Objective-C message dispatches (@code{[receiver
3444 message:arg]}) in this translation unit ensure that the receiver is
3445 not @code{nil}.  This allows for more efficient entry points in the
3446 runtime to be used.  This option is only available in conjunction with
3447 the NeXT runtime and ABI version 0 or 1.
3449 @item -fobjc-abi-version=@var{n}
3450 @opindex fobjc-abi-version
3451 Use version @var{n} of the Objective-C ABI for the selected runtime.
3452 This option is currently supported only for the NeXT runtime.  In that
3453 case, Version 0 is the traditional (32-bit) ABI without support for
3454 properties and other Objective-C 2.0 additions.  Version 1 is the
3455 traditional (32-bit) ABI with support for properties and other
3456 Objective-C 2.0 additions.  Version 2 is the modern (64-bit) ABI.  If
3457 nothing is specified, the default is Version 0 on 32-bit target
3458 machines, and Version 2 on 64-bit target machines.
3460 @item -fobjc-call-cxx-cdtors
3461 @opindex fobjc-call-cxx-cdtors
3462 For each Objective-C class, check if any of its instance variables is a
3463 C++ object with a non-trivial default constructor.  If so, synthesize a
3464 special @code{- (id) .cxx_construct} instance method which runs
3465 non-trivial default constructors on any such instance variables, in order,
3466 and then return @code{self}.  Similarly, check if any instance variable
3467 is a C++ object with a non-trivial destructor, and if so, synthesize a
3468 special @code{- (void) .cxx_destruct} method which runs
3469 all such default destructors, in reverse order.
3471 The @code{- (id) .cxx_construct} and @code{- (void) .cxx_destruct}
3472 methods thusly generated only operate on instance variables
3473 declared in the current Objective-C class, and not those inherited
3474 from superclasses.  It is the responsibility of the Objective-C
3475 runtime to invoke all such methods in an object's inheritance
3476 hierarchy.  The @code{- (id) .cxx_construct} methods are invoked
3477 by the runtime immediately after a new object instance is allocated;
3478 the @code{- (void) .cxx_destruct} methods are invoked immediately
3479 before the runtime deallocates an object instance.
3481 As of this writing, only the NeXT runtime on Mac OS X 10.4 and later has
3482 support for invoking the @code{- (id) .cxx_construct} and
3483 @code{- (void) .cxx_destruct} methods.
3485 @item -fobjc-direct-dispatch
3486 @opindex fobjc-direct-dispatch
3487 Allow fast jumps to the message dispatcher.  On Darwin this is
3488 accomplished via the comm page.
3490 @item -fobjc-exceptions
3491 @opindex fobjc-exceptions
3492 Enable syntactic support for structured exception handling in
3493 Objective-C, similar to what is offered by C++.  This option
3494 is required to use the Objective-C keywords @code{@@try},
3495 @code{@@throw}, @code{@@catch}, @code{@@finally} and
3496 @code{@@synchronized}.  This option is available with both the GNU
3497 runtime and the NeXT runtime (but not available in conjunction with
3498 the NeXT runtime on Mac OS X 10.2 and earlier).
3500 @item -fobjc-gc
3501 @opindex fobjc-gc
3502 Enable garbage collection (GC) in Objective-C and Objective-C++
3503 programs.  This option is only available with the NeXT runtime; the
3504 GNU runtime has a different garbage collection implementation that
3505 does not require special compiler flags.
3507 @item -fobjc-nilcheck
3508 @opindex fobjc-nilcheck
3509 For the NeXT runtime with version 2 of the ABI, check for a nil
3510 receiver in method invocations before doing the actual method call.
3511 This is the default and can be disabled using
3512 @option{-fno-objc-nilcheck}.  Class methods and super calls are never
3513 checked for nil in this way no matter what this flag is set to.
3514 Currently this flag does nothing when the GNU runtime, or an older
3515 version of the NeXT runtime ABI, is used.
3517 @item -fobjc-std=objc1
3518 @opindex fobjc-std
3519 Conform to the language syntax of Objective-C 1.0, the language
3520 recognized by GCC 4.0.  This only affects the Objective-C additions to
3521 the C/C++ language; it does not affect conformance to C/C++ standards,
3522 which is controlled by the separate C/C++ dialect option flags.  When
3523 this option is used with the Objective-C or Objective-C++ compiler,
3524 any Objective-C syntax that is not recognized by GCC 4.0 is rejected.
3525 This is useful if you need to make sure that your Objective-C code can
3526 be compiled with older versions of GCC@.
3528 @item -freplace-objc-classes
3529 @opindex freplace-objc-classes
3530 Emit a special marker instructing @command{ld(1)} not to statically link in
3531 the resulting object file, and allow @command{dyld(1)} to load it in at
3532 run time instead.  This is used in conjunction with the Fix-and-Continue
3533 debugging mode, where the object file in question may be recompiled and
3534 dynamically reloaded in the course of program execution, without the need
3535 to restart the program itself.  Currently, Fix-and-Continue functionality
3536 is only available in conjunction with the NeXT runtime on Mac OS X 10.3
3537 and later.
3539 @item -fzero-link
3540 @opindex fzero-link
3541 When compiling for the NeXT runtime, the compiler ordinarily replaces calls
3542 to @code{objc_getClass("@dots{}")} (when the name of the class is known at
3543 compile time) with static class references that get initialized at load time,
3544 which improves run-time performance.  Specifying the @option{-fzero-link} flag
3545 suppresses this behavior and causes calls to @code{objc_getClass("@dots{}")}
3546 to be retained.  This is useful in Zero-Link debugging mode, since it allows
3547 for individual class implementations to be modified during program execution.
3548 The GNU runtime currently always retains calls to @code{objc_get_class("@dots{}")}
3549 regardless of command-line options.
3551 @item -fno-local-ivars
3552 @opindex fno-local-ivars
3553 @opindex flocal-ivars
3554 By default instance variables in Objective-C can be accessed as if
3555 they were local variables from within the methods of the class they're
3556 declared in.  This can lead to shadowing between instance variables
3557 and other variables declared either locally inside a class method or
3558 globally with the same name.  Specifying the @option{-fno-local-ivars}
3559 flag disables this behavior thus avoiding variable shadowing issues.
3561 @item -fivar-visibility=@r{[}public@r{|}protected@r{|}private@r{|}package@r{]}
3562 @opindex fivar-visibility
3563 Set the default instance variable visibility to the specified option
3564 so that instance variables declared outside the scope of any access
3565 modifier directives default to the specified visibility.
3567 @item -gen-decls
3568 @opindex gen-decls
3569 Dump interface declarations for all classes seen in the source file to a
3570 file named @file{@var{sourcename}.decl}.
3572 @item -Wassign-intercept @r{(Objective-C and Objective-C++ only)}
3573 @opindex Wassign-intercept
3574 @opindex Wno-assign-intercept
3575 Warn whenever an Objective-C assignment is being intercepted by the
3576 garbage collector.
3578 @item -Wno-protocol @r{(Objective-C and Objective-C++ only)}
3579 @opindex Wno-protocol
3580 @opindex Wprotocol
3581 If a class is declared to implement a protocol, a warning is issued for
3582 every method in the protocol that is not implemented by the class.  The
3583 default behavior is to issue a warning for every method not explicitly
3584 implemented in the class, even if a method implementation is inherited
3585 from the superclass.  If you use the @option{-Wno-protocol} option, then
3586 methods inherited from the superclass are considered to be implemented,
3587 and no warning is issued for them.
3589 @item -Wselector @r{(Objective-C and Objective-C++ only)}
3590 @opindex Wselector
3591 @opindex Wno-selector
3592 Warn if multiple methods of different types for the same selector are
3593 found during compilation.  The check is performed on the list of methods
3594 in the final stage of compilation.  Additionally, a check is performed
3595 for each selector appearing in a @code{@@selector(@dots{})}
3596 expression, and a corresponding method for that selector has been found
3597 during compilation.  Because these checks scan the method table only at
3598 the end of compilation, these warnings are not produced if the final
3599 stage of compilation is not reached, for example because an error is
3600 found during compilation, or because the @option{-fsyntax-only} option is
3601 being used.
3603 @item -Wstrict-selector-match @r{(Objective-C and Objective-C++ only)}
3604 @opindex Wstrict-selector-match
3605 @opindex Wno-strict-selector-match
3606 Warn if multiple methods with differing argument and/or return types are
3607 found for a given selector when attempting to send a message using this
3608 selector to a receiver of type @code{id} or @code{Class}.  When this flag
3609 is off (which is the default behavior), the compiler omits such warnings
3610 if any differences found are confined to types that share the same size
3611 and alignment.
3613 @item -Wundeclared-selector @r{(Objective-C and Objective-C++ only)}
3614 @opindex Wundeclared-selector
3615 @opindex Wno-undeclared-selector
3616 Warn if a @code{@@selector(@dots{})} expression referring to an
3617 undeclared selector is found.  A selector is considered undeclared if no
3618 method with that name has been declared before the
3619 @code{@@selector(@dots{})} expression, either explicitly in an
3620 @code{@@interface} or @code{@@protocol} declaration, or implicitly in
3621 an @code{@@implementation} section.  This option always performs its
3622 checks as soon as a @code{@@selector(@dots{})} expression is found,
3623 while @option{-Wselector} only performs its checks in the final stage of
3624 compilation.  This also enforces the coding style convention
3625 that methods and selectors must be declared before being used.
3627 @item -print-objc-runtime-info
3628 @opindex print-objc-runtime-info
3629 Generate C header describing the largest structure that is passed by
3630 value, if any.
3632 @end table
3634 @node Diagnostic Message Formatting Options
3635 @section Options to Control Diagnostic Messages Formatting
3636 @cindex options to control diagnostics formatting
3637 @cindex diagnostic messages
3638 @cindex message formatting
3640 Traditionally, diagnostic messages have been formatted irrespective of
3641 the output device's aspect (e.g.@: its width, @dots{}).  You can use the
3642 options described below
3643 to control the formatting algorithm for diagnostic messages, 
3644 e.g.@: how many characters per line, how often source location
3645 information should be reported.  Note that some language front ends may not
3646 honor these options.
3648 @table @gcctabopt
3649 @item -fmessage-length=@var{n}
3650 @opindex fmessage-length
3651 Try to format error messages so that they fit on lines of about
3652 @var{n} characters.  If @var{n} is zero, then no line-wrapping is
3653 done; each error message appears on a single line.  This is the
3654 default for all front ends.
3656 Note - this option also affects the display of the @samp{#error} and
3657 @samp{#warning} pre-processor directives, and the @samp{deprecated}
3658 function/type/variable attribute.  It does not however affect the
3659 @samp{pragma GCC warning} and @samp{pragma GCC error} pragmas.
3661 @item -fdiagnostics-show-location=once
3662 @opindex fdiagnostics-show-location
3663 Only meaningful in line-wrapping mode.  Instructs the diagnostic messages
3664 reporter to emit source location information @emph{once}; that is, in
3665 case the message is too long to fit on a single physical line and has to
3666 be wrapped, the source location won't be emitted (as prefix) again,
3667 over and over, in subsequent continuation lines.  This is the default
3668 behavior.
3670 @item -fdiagnostics-show-location=every-line
3671 Only meaningful in line-wrapping mode.  Instructs the diagnostic
3672 messages reporter to emit the same source location information (as
3673 prefix) for physical lines that result from the process of breaking
3674 a message which is too long to fit on a single line.
3676 @item -fdiagnostics-color[=@var{WHEN}]
3677 @itemx -fno-diagnostics-color
3678 @opindex fdiagnostics-color
3679 @cindex highlight, color
3680 @vindex GCC_COLORS @r{environment variable}
3681 Use color in diagnostics.  @var{WHEN} is @samp{never}, @samp{always},
3682 or @samp{auto}.  The default depends on how the compiler has been configured,
3683 it can be any of the above @var{WHEN} options or also @samp{never}
3684 if @env{GCC_COLORS} environment variable isn't present in the environment,
3685 and @samp{auto} otherwise.
3686 @samp{auto} means to use color only when the standard error is a terminal.
3687 The forms @option{-fdiagnostics-color} and @option{-fno-diagnostics-color} are
3688 aliases for @option{-fdiagnostics-color=always} and
3689 @option{-fdiagnostics-color=never}, respectively.
3691 The colors are defined by the environment variable @env{GCC_COLORS}.
3692 Its value is a colon-separated list of capabilities and Select Graphic
3693 Rendition (SGR) substrings. SGR commands are interpreted by the
3694 terminal or terminal emulator.  (See the section in the documentation
3695 of your text terminal for permitted values and their meanings as
3696 character attributes.)  These substring values are integers in decimal
3697 representation and can be concatenated with semicolons.
3698 Common values to concatenate include
3699 @samp{1} for bold,
3700 @samp{4} for underline,
3701 @samp{5} for blink,
3702 @samp{7} for inverse,
3703 @samp{39} for default foreground color,
3704 @samp{30} to @samp{37} for foreground colors,
3705 @samp{90} to @samp{97} for 16-color mode foreground colors,
3706 @samp{38;5;0} to @samp{38;5;255}
3707 for 88-color and 256-color modes foreground colors,
3708 @samp{49} for default background color,
3709 @samp{40} to @samp{47} for background colors,
3710 @samp{100} to @samp{107} for 16-color mode background colors,
3711 and @samp{48;5;0} to @samp{48;5;255}
3712 for 88-color and 256-color modes background colors.
3714 The default @env{GCC_COLORS} is
3715 @smallexample
3716 error=01;31:warning=01;35:note=01;36:range1=32:range2=34:locus=01:\
3717 quote=01:fixit-insert=32:fixit-delete=31:\
3718 diff-filename=01:diff-hunk=32:diff-delete=31:diff-insert=32:\
3719 type-diff=01;32
3720 @end smallexample
3721 @noindent
3722 where @samp{01;31} is bold red, @samp{01;35} is bold magenta,
3723 @samp{01;36} is bold cyan, @samp{32} is green, @samp{34} is blue,
3724 @samp{01} is bold, and @samp{31} is red.
3725 Setting @env{GCC_COLORS} to the empty string disables colors.
3726 Supported capabilities are as follows.
3728 @table @code
3729 @item error=
3730 @vindex error GCC_COLORS @r{capability}
3731 SGR substring for error: markers.
3733 @item warning=
3734 @vindex warning GCC_COLORS @r{capability}
3735 SGR substring for warning: markers.
3737 @item note=
3738 @vindex note GCC_COLORS @r{capability}
3739 SGR substring for note: markers.
3741 @item range1=
3742 @vindex range1 GCC_COLORS @r{capability}
3743 SGR substring for first additional range.
3745 @item range2=
3746 @vindex range2 GCC_COLORS @r{capability}
3747 SGR substring for second additional range.
3749 @item locus=
3750 @vindex locus GCC_COLORS @r{capability}
3751 SGR substring for location information, @samp{file:line} or
3752 @samp{file:line:column} etc.
3754 @item quote=
3755 @vindex quote GCC_COLORS @r{capability}
3756 SGR substring for information printed within quotes.
3758 @item fixit-insert=
3759 @vindex fixit-insert GCC_COLORS @r{capability}
3760 SGR substring for fix-it hints suggesting text to
3761 be inserted or replaced.
3763 @item fixit-delete=
3764 @vindex fixit-delete GCC_COLORS @r{capability}
3765 SGR substring for fix-it hints suggesting text to
3766 be deleted.
3768 @item diff-filename=
3769 @vindex diff-filename GCC_COLORS @r{capability}
3770 SGR substring for filename headers within generated patches.
3772 @item diff-hunk=
3773 @vindex diff-hunk GCC_COLORS @r{capability}
3774 SGR substring for the starts of hunks within generated patches.
3776 @item diff-delete=
3777 @vindex diff-delete GCC_COLORS @r{capability}
3778 SGR substring for deleted lines within generated patches.
3780 @item diff-insert=
3781 @vindex diff-insert GCC_COLORS @r{capability}
3782 SGR substring for inserted lines within generated patches.
3784 @item type-diff=
3785 @vindex type-diff GCC_COLORS @r{capability}
3786 SGR substring for highlighting mismatching types within template
3787 arguments in the C++ frontend.
3788 @end table
3790 @item -fno-diagnostics-show-option
3791 @opindex fno-diagnostics-show-option
3792 @opindex fdiagnostics-show-option
3793 By default, each diagnostic emitted includes text indicating the
3794 command-line option that directly controls the diagnostic (if such an
3795 option is known to the diagnostic machinery).  Specifying the
3796 @option{-fno-diagnostics-show-option} flag suppresses that behavior.
3798 @item -fno-diagnostics-show-caret
3799 @opindex fno-diagnostics-show-caret
3800 @opindex fdiagnostics-show-caret
3801 By default, each diagnostic emitted includes the original source line
3802 and a caret @samp{^} indicating the column.  This option suppresses this
3803 information.  The source line is truncated to @var{n} characters, if
3804 the @option{-fmessage-length=n} option is given.  When the output is done
3805 to the terminal, the width is limited to the width given by the
3806 @env{COLUMNS} environment variable or, if not set, to the terminal width.
3808 @item -fno-diagnostics-show-labels
3809 @opindex fno-diagnostics-show-labels
3810 @opindex fdiagnostics-show-labels
3811 By default, when printing source code (via @option{-fdiagnostics-show-caret}),
3812 diagnostics can label ranges of source code with pertinent information, such
3813 as the types of expressions:
3815 @smallexample
3816     printf ("foo %s bar", long_i + long_j);
3817                  ~^       ~~~~~~~~~~~~~~~
3818                   |              |
3819                   char *         long int
3820 @end smallexample
3822 This option suppresses the printing of these labels (in the example above,
3823 the vertical bars and the ``char *'' and ``long int'' text).
3825 @item -fno-diagnostics-show-line-numbers
3826 @opindex fno-diagnostics-show-line-numbers
3827 @opindex fdiagnostics-show-line-numbers
3828 By default, when printing source code (via @option{-fdiagnostics-show-caret}),
3829 a left margin is printed, showing line numbers.  This option suppresses this
3830 left margin.
3832 @item -fdiagnostics-minimum-margin-width=@var{width}
3833 @opindex -fdiagnostics-minimum-margin-width
3834 This option controls the minimum width of the left margin printed by
3835 @option{-fdiagnostics-show-line-numbers}.  It defaults to 6.
3837 @item -fdiagnostics-parseable-fixits
3838 @opindex fdiagnostics-parseable-fixits
3839 Emit fix-it hints in a machine-parseable format, suitable for consumption
3840 by IDEs.  For each fix-it, a line will be printed after the relevant
3841 diagnostic, starting with the string ``fix-it:''.  For example:
3843 @smallexample
3844 fix-it:"test.c":@{45:3-45:21@}:"gtk_widget_show_all"
3845 @end smallexample
3847 The location is expressed as a half-open range, expressed as a count of
3848 bytes, starting at byte 1 for the initial column.  In the above example,
3849 bytes 3 through 20 of line 45 of ``test.c'' are to be replaced with the
3850 given string:
3852 @smallexample
3853 00000000011111111112222222222
3854 12345678901234567890123456789
3855   gtk_widget_showall (dlg);
3856   ^^^^^^^^^^^^^^^^^^
3857   gtk_widget_show_all
3858 @end smallexample
3860 The filename and replacement string escape backslash as ``\\", tab as ``\t'',
3861 newline as ``\n'', double quotes as ``\"'', non-printable characters as octal
3862 (e.g. vertical tab as ``\013'').
3864 An empty replacement string indicates that the given range is to be removed.
3865 An empty range (e.g. ``45:3-45:3'') indicates that the string is to
3866 be inserted at the given position.
3868 @item -fdiagnostics-generate-patch
3869 @opindex fdiagnostics-generate-patch
3870 Print fix-it hints to stderr in unified diff format, after any diagnostics
3871 are printed.  For example:
3873 @smallexample
3874 --- test.c
3875 +++ test.c
3876 @@ -42,5 +42,5 @@
3878  void show_cb(GtkDialog *dlg)
3879  @{
3880 -  gtk_widget_showall(dlg);
3881 +  gtk_widget_show_all(dlg);
3882  @}
3884 @end smallexample
3886 The diff may or may not be colorized, following the same rules
3887 as for diagnostics (see @option{-fdiagnostics-color}).
3889 @item -fdiagnostics-show-template-tree
3890 @opindex fdiagnostics-show-template-tree
3892 In the C++ frontend, when printing diagnostics showing mismatching
3893 template types, such as:
3895 @smallexample
3896   could not convert 'std::map<int, std::vector<double> >()'
3897     from 'map<[...],vector<double>>' to 'map<[...],vector<float>>
3898 @end smallexample
3900 the @option{-fdiagnostics-show-template-tree} flag enables printing a
3901 tree-like structure showing the common and differing parts of the types,
3902 such as:
3904 @smallexample
3905   map<
3906     [...],
3907     vector<
3908       [double != float]>>
3909 @end smallexample
3911 The parts that differ are highlighted with color (``double'' and
3912 ``float'' in this case).
3914 @item -fno-elide-type
3915 @opindex fno-elide-type
3916 @opindex felide-type
3917 By default when the C++ frontend prints diagnostics showing mismatching
3918 template types, common parts of the types are printed as ``[...]'' to
3919 simplify the error message.  For example:
3921 @smallexample
3922   could not convert 'std::map<int, std::vector<double> >()'
3923     from 'map<[...],vector<double>>' to 'map<[...],vector<float>>
3924 @end smallexample
3926 Specifying the @option{-fno-elide-type} flag suppresses that behavior.
3927 This flag also affects the output of the
3928 @option{-fdiagnostics-show-template-tree} flag.
3930 @item -fno-show-column
3931 @opindex fno-show-column
3932 Do not print column numbers in diagnostics.  This may be necessary if
3933 diagnostics are being scanned by a program that does not understand the
3934 column numbers, such as @command{dejagnu}.
3936 @end table
3938 @node Warning Options
3939 @section Options to Request or Suppress Warnings
3940 @cindex options to control warnings
3941 @cindex warning messages
3942 @cindex messages, warning
3943 @cindex suppressing warnings
3945 Warnings are diagnostic messages that report constructions that
3946 are not inherently erroneous but that are risky or suggest there
3947 may have been an error.
3949 The following language-independent options do not enable specific
3950 warnings but control the kinds of diagnostics produced by GCC@.
3952 @table @gcctabopt
3953 @cindex syntax checking
3954 @item -fsyntax-only
3955 @opindex fsyntax-only
3956 Check the code for syntax errors, but don't do anything beyond that.
3958 @item -fmax-errors=@var{n}
3959 @opindex fmax-errors
3960 Limits the maximum number of error messages to @var{n}, at which point
3961 GCC bails out rather than attempting to continue processing the source
3962 code.  If @var{n} is 0 (the default), there is no limit on the number
3963 of error messages produced.  If @option{-Wfatal-errors} is also
3964 specified, then @option{-Wfatal-errors} takes precedence over this
3965 option.
3967 @item -w
3968 @opindex w
3969 Inhibit all warning messages.
3971 @item -Werror
3972 @opindex Werror
3973 @opindex Wno-error
3974 Make all warnings into errors.
3976 @item -Werror=
3977 @opindex Werror=
3978 @opindex Wno-error=
3979 Make the specified warning into an error.  The specifier for a warning
3980 is appended; for example @option{-Werror=switch} turns the warnings
3981 controlled by @option{-Wswitch} into errors.  This switch takes a
3982 negative form, to be used to negate @option{-Werror} for specific
3983 warnings; for example @option{-Wno-error=switch} makes
3984 @option{-Wswitch} warnings not be errors, even when @option{-Werror}
3985 is in effect.
3987 The warning message for each controllable warning includes the
3988 option that controls the warning.  That option can then be used with
3989 @option{-Werror=} and @option{-Wno-error=} as described above.
3990 (Printing of the option in the warning message can be disabled using the
3991 @option{-fno-diagnostics-show-option} flag.)
3993 Note that specifying @option{-Werror=}@var{foo} automatically implies
3994 @option{-W}@var{foo}.  However, @option{-Wno-error=}@var{foo} does not
3995 imply anything.
3997 @item -Wfatal-errors
3998 @opindex Wfatal-errors
3999 @opindex Wno-fatal-errors
4000 This option causes the compiler to abort compilation on the first error
4001 occurred rather than trying to keep going and printing further error
4002 messages.
4004 @end table
4006 You can request many specific warnings with options beginning with
4007 @samp{-W}, for example @option{-Wimplicit} to request warnings on
4008 implicit declarations.  Each of these specific warning options also
4009 has a negative form beginning @samp{-Wno-} to turn off warnings; for
4010 example, @option{-Wno-implicit}.  This manual lists only one of the
4011 two forms, whichever is not the default.  For further
4012 language-specific options also refer to @ref{C++ Dialect Options} and
4013 @ref{Objective-C and Objective-C++ Dialect Options}.
4015 Some options, such as @option{-Wall} and @option{-Wextra}, turn on other
4016 options, such as @option{-Wunused}, which may turn on further options,
4017 such as @option{-Wunused-value}. The combined effect of positive and
4018 negative forms is that more specific options have priority over less
4019 specific ones, independently of their position in the command-line. For
4020 options of the same specificity, the last one takes effect. Options
4021 enabled or disabled via pragmas (@pxref{Diagnostic Pragmas}) take effect
4022 as if they appeared at the end of the command-line.
4024 When an unrecognized warning option is requested (e.g.,
4025 @option{-Wunknown-warning}), GCC emits a diagnostic stating
4026 that the option is not recognized.  However, if the @option{-Wno-} form
4027 is used, the behavior is slightly different: no diagnostic is
4028 produced for @option{-Wno-unknown-warning} unless other diagnostics
4029 are being produced.  This allows the use of new @option{-Wno-} options
4030 with old compilers, but if something goes wrong, the compiler
4031 warns that an unrecognized option is present.
4033 @table @gcctabopt
4034 @item -Wpedantic
4035 @itemx -pedantic
4036 @opindex pedantic
4037 @opindex Wpedantic
4038 @opindex Wno-pedantic
4039 Issue all the warnings demanded by strict ISO C and ISO C++;
4040 reject all programs that use forbidden extensions, and some other
4041 programs that do not follow ISO C and ISO C++.  For ISO C, follows the
4042 version of the ISO C standard specified by any @option{-std} option used.
4044 Valid ISO C and ISO C++ programs should compile properly with or without
4045 this option (though a rare few require @option{-ansi} or a
4046 @option{-std} option specifying the required version of ISO C)@.  However,
4047 without this option, certain GNU extensions and traditional C and C++
4048 features are supported as well.  With this option, they are rejected.
4050 @option{-Wpedantic} does not cause warning messages for use of the
4051 alternate keywords whose names begin and end with @samp{__}.  Pedantic
4052 warnings are also disabled in the expression that follows
4053 @code{__extension__}.  However, only system header files should use
4054 these escape routes; application programs should avoid them.
4055 @xref{Alternate Keywords}.
4057 Some users try to use @option{-Wpedantic} to check programs for strict ISO
4058 C conformance.  They soon find that it does not do quite what they want:
4059 it finds some non-ISO practices, but not all---only those for which
4060 ISO C @emph{requires} a diagnostic, and some others for which
4061 diagnostics have been added.
4063 A feature to report any failure to conform to ISO C might be useful in
4064 some instances, but would require considerable additional work and would
4065 be quite different from @option{-Wpedantic}.  We don't have plans to
4066 support such a feature in the near future.
4068 Where the standard specified with @option{-std} represents a GNU
4069 extended dialect of C, such as @samp{gnu90} or @samp{gnu99}, there is a
4070 corresponding @dfn{base standard}, the version of ISO C on which the GNU
4071 extended dialect is based.  Warnings from @option{-Wpedantic} are given
4072 where they are required by the base standard.  (It does not make sense
4073 for such warnings to be given only for features not in the specified GNU
4074 C dialect, since by definition the GNU dialects of C include all
4075 features the compiler supports with the given option, and there would be
4076 nothing to warn about.)
4078 @item -pedantic-errors
4079 @opindex pedantic-errors
4080 Give an error whenever the @dfn{base standard} (see @option{-Wpedantic})
4081 requires a diagnostic, in some cases where there is undefined behavior
4082 at compile-time and in some other cases that do not prevent compilation
4083 of programs that are valid according to the standard. This is not
4084 equivalent to @option{-Werror=pedantic}, since there are errors enabled
4085 by this option and not enabled by the latter and vice versa.
4087 @item -Wall
4088 @opindex Wall
4089 @opindex Wno-all
4090 This enables all the warnings about constructions that some users
4091 consider questionable, and that are easy to avoid (or modify to
4092 prevent the warning), even in conjunction with macros.  This also
4093 enables some language-specific warnings described in @ref{C++ Dialect
4094 Options} and @ref{Objective-C and Objective-C++ Dialect Options}.
4096 @option{-Wall} turns on the following warning flags:
4098 @gccoptlist{-Waddress   @gol
4099 -Warray-bounds=1 @r{(only with} @option{-O2}@r{)}  @gol
4100 -Wbool-compare  @gol
4101 -Wbool-operation  @gol
4102 -Wc++11-compat  -Wc++14-compat  @gol
4103 -Wcatch-value @r{(C++ and Objective-C++ only)}  @gol
4104 -Wchar-subscripts  @gol
4105 -Wcomment  @gol
4106 -Wduplicate-decl-specifier @r{(C and Objective-C only)} @gol
4107 -Wenum-compare @r{(in C/ObjC; this is on by default in C++)} @gol
4108 -Wformat   @gol
4109 -Wint-in-bool-context  @gol
4110 -Wimplicit @r{(C and Objective-C only)} @gol
4111 -Wimplicit-int @r{(C and Objective-C only)} @gol
4112 -Wimplicit-function-declaration @r{(C and Objective-C only)} @gol
4113 -Winit-self @r{(only for C++)} @gol
4114 -Wlogical-not-parentheses @gol
4115 -Wmain @r{(only for C/ObjC and unless} @option{-ffreestanding}@r{)}  @gol
4116 -Wmaybe-uninitialized @gol
4117 -Wmemset-elt-size @gol
4118 -Wmemset-transposed-args @gol
4119 -Wmisleading-indentation @r{(only for C/C++)} @gol
4120 -Wmissing-attributes @gol
4121 -Wmissing-braces @r{(only for C/ObjC)} @gol
4122 -Wmultistatement-macros  @gol
4123 -Wnarrowing @r{(only for C++)}  @gol
4124 -Wnonnull  @gol
4125 -Wnonnull-compare  @gol
4126 -Wopenmp-simd @gol
4127 -Wparentheses  @gol
4128 -Wpessimizing-move @r{(only for C++)}  @gol
4129 -Wpointer-sign  @gol
4130 -Wreorder   @gol
4131 -Wrestrict   @gol
4132 -Wreturn-type  @gol
4133 -Wsequence-point  @gol
4134 -Wsign-compare @r{(only in C++)}  @gol
4135 -Wsizeof-pointer-div @gol
4136 -Wsizeof-pointer-memaccess @gol
4137 -Wstrict-aliasing  @gol
4138 -Wstrict-overflow=1  @gol
4139 -Wswitch  @gol
4140 -Wtautological-compare  @gol
4141 -Wtrigraphs  @gol
4142 -Wuninitialized  @gol
4143 -Wunknown-pragmas  @gol
4144 -Wunused-function  @gol
4145 -Wunused-label     @gol
4146 -Wunused-value     @gol
4147 -Wunused-variable  @gol
4148 -Wvolatile-register-var @gol
4151 Note that some warning flags are not implied by @option{-Wall}.  Some of
4152 them warn about constructions that users generally do not consider
4153 questionable, but which occasionally you might wish to check for;
4154 others warn about constructions that are necessary or hard to avoid in
4155 some cases, and there is no simple way to modify the code to suppress
4156 the warning. Some of them are enabled by @option{-Wextra} but many of
4157 them must be enabled individually.
4159 @item -Wextra
4160 @opindex W
4161 @opindex Wextra
4162 @opindex Wno-extra
4163 This enables some extra warning flags that are not enabled by
4164 @option{-Wall}. (This option used to be called @option{-W}.  The older
4165 name is still supported, but the newer name is more descriptive.)
4167 @gccoptlist{-Wclobbered  @gol
4168 -Wcast-function-type  @gol
4169 -Wempty-body  @gol
4170 -Wignored-qualifiers @gol
4171 -Wimplicit-fallthrough=3 @gol
4172 -Wmissing-field-initializers  @gol
4173 -Wmissing-parameter-type @r{(C only)}  @gol
4174 -Wold-style-declaration @r{(C only)}  @gol
4175 -Woverride-init  @gol
4176 -Wsign-compare @r{(C only)} @gol
4177 -Wredundant-move @r{(only for C++)}  @gol
4178 -Wtype-limits  @gol
4179 -Wuninitialized  @gol
4180 -Wshift-negative-value @r{(in C++03 and in C99 and newer)}  @gol
4181 -Wunused-parameter @r{(only with} @option{-Wunused} @r{or} @option{-Wall}@r{)} @gol
4182 -Wunused-but-set-parameter @r{(only with} @option{-Wunused} @r{or} @option{-Wall}@r{)}  @gol
4185 The option @option{-Wextra} also prints warning messages for the
4186 following cases:
4188 @itemize @bullet
4190 @item
4191 A pointer is compared against integer zero with @code{<}, @code{<=},
4192 @code{>}, or @code{>=}.
4194 @item
4195 (C++ only) An enumerator and a non-enumerator both appear in a
4196 conditional expression.
4198 @item
4199 (C++ only) Ambiguous virtual bases.
4201 @item
4202 (C++ only) Subscripting an array that has been declared @code{register}.
4204 @item
4205 (C++ only) Taking the address of a variable that has been declared
4206 @code{register}.
4208 @item
4209 (C++ only) A base class is not initialized in the copy constructor
4210 of a derived class.
4212 @end itemize
4214 @item -Wchar-subscripts
4215 @opindex Wchar-subscripts
4216 @opindex Wno-char-subscripts
4217 Warn if an array subscript has type @code{char}.  This is a common cause
4218 of error, as programmers often forget that this type is signed on some
4219 machines.
4220 This warning is enabled by @option{-Wall}.
4222 @item -Wchkp
4223 @opindex Wchkp
4224 @opindex Wno-chkp
4225 Warn about an invalid memory access that is found by Pointer Bounds Checker
4226 (@option{-fcheck-pointer-bounds}).
4228 @item -Wno-coverage-mismatch
4229 @opindex Wno-coverage-mismatch
4230 @opindex Wcoverage-mismatch
4231 Warn if feedback profiles do not match when using the
4232 @option{-fprofile-use} option.
4233 If a source file is changed between compiling with @option{-fprofile-generate}
4234 and with @option{-fprofile-use}, the files with the profile feedback can fail
4235 to match the source file and GCC cannot use the profile feedback
4236 information.  By default, this warning is enabled and is treated as an
4237 error.  @option{-Wno-coverage-mismatch} can be used to disable the
4238 warning or @option{-Wno-error=coverage-mismatch} can be used to
4239 disable the error.  Disabling the error for this warning can result in
4240 poorly optimized code and is useful only in the
4241 case of very minor changes such as bug fixes to an existing code-base.
4242 Completely disabling the warning is not recommended.
4244 @item -Wno-cpp
4245 @r{(C, Objective-C, C++, Objective-C++ and Fortran only)}
4247 Suppress warning messages emitted by @code{#warning} directives.
4249 @item -Wdouble-promotion @r{(C, C++, Objective-C and Objective-C++ only)}
4250 @opindex Wdouble-promotion
4251 @opindex Wno-double-promotion
4252 Give a warning when a value of type @code{float} is implicitly
4253 promoted to @code{double}.  CPUs with a 32-bit ``single-precision''
4254 floating-point unit implement @code{float} in hardware, but emulate
4255 @code{double} in software.  On such a machine, doing computations
4256 using @code{double} values is much more expensive because of the
4257 overhead required for software emulation.
4259 It is easy to accidentally do computations with @code{double} because
4260 floating-point literals are implicitly of type @code{double}.  For
4261 example, in:
4262 @smallexample
4263 @group
4264 float area(float radius)
4266    return 3.14159 * radius * radius;
4268 @end group
4269 @end smallexample
4270 the compiler performs the entire computation with @code{double}
4271 because the floating-point literal is a @code{double}.
4273 @item -Wduplicate-decl-specifier @r{(C and Objective-C only)}
4274 @opindex Wduplicate-decl-specifier
4275 @opindex Wno-duplicate-decl-specifier
4276 Warn if a declaration has duplicate @code{const}, @code{volatile},
4277 @code{restrict} or @code{_Atomic} specifier.  This warning is enabled by
4278 @option{-Wall}.
4280 @item -Wformat
4281 @itemx -Wformat=@var{n}
4282 @opindex Wformat
4283 @opindex Wno-format
4284 @opindex ffreestanding
4285 @opindex fno-builtin
4286 @opindex Wformat=
4287 Check calls to @code{printf} and @code{scanf}, etc., to make sure that
4288 the arguments supplied have types appropriate to the format string
4289 specified, and that the conversions specified in the format string make
4290 sense.  This includes standard functions, and others specified by format
4291 attributes (@pxref{Function Attributes}), in the @code{printf},
4292 @code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
4293 not in the C standard) families (or other target-specific families).
4294 Which functions are checked without format attributes having been
4295 specified depends on the standard version selected, and such checks of
4296 functions without the attribute specified are disabled by
4297 @option{-ffreestanding} or @option{-fno-builtin}.
4299 The formats are checked against the format features supported by GNU
4300 libc version 2.2.  These include all ISO C90 and C99 features, as well
4301 as features from the Single Unix Specification and some BSD and GNU
4302 extensions.  Other library implementations may not support all these
4303 features; GCC does not support warning about features that go beyond a
4304 particular library's limitations.  However, if @option{-Wpedantic} is used
4305 with @option{-Wformat}, warnings are given about format features not
4306 in the selected standard version (but not for @code{strfmon} formats,
4307 since those are not in any version of the C standard).  @xref{C Dialect
4308 Options,,Options Controlling C Dialect}.
4310 @table @gcctabopt
4311 @item -Wformat=1
4312 @itemx -Wformat
4313 @opindex Wformat
4314 @opindex Wformat=1
4315 Option @option{-Wformat} is equivalent to @option{-Wformat=1}, and
4316 @option{-Wno-format} is equivalent to @option{-Wformat=0}.  Since
4317 @option{-Wformat} also checks for null format arguments for several
4318 functions, @option{-Wformat} also implies @option{-Wnonnull}.  Some
4319 aspects of this level of format checking can be disabled by the
4320 options: @option{-Wno-format-contains-nul},
4321 @option{-Wno-format-extra-args}, and @option{-Wno-format-zero-length}.
4322 @option{-Wformat} is enabled by @option{-Wall}.
4324 @item -Wno-format-contains-nul
4325 @opindex Wno-format-contains-nul
4326 @opindex Wformat-contains-nul
4327 If @option{-Wformat} is specified, do not warn about format strings that
4328 contain NUL bytes.
4330 @item -Wno-format-extra-args
4331 @opindex Wno-format-extra-args
4332 @opindex Wformat-extra-args
4333 If @option{-Wformat} is specified, do not warn about excess arguments to a
4334 @code{printf} or @code{scanf} format function.  The C standard specifies
4335 that such arguments are ignored.
4337 Where the unused arguments lie between used arguments that are
4338 specified with @samp{$} operand number specifications, normally
4339 warnings are still given, since the implementation could not know what
4340 type to pass to @code{va_arg} to skip the unused arguments.  However,
4341 in the case of @code{scanf} formats, this option suppresses the
4342 warning if the unused arguments are all pointers, since the Single
4343 Unix Specification says that such unused arguments are allowed.
4345 @item -Wformat-overflow
4346 @itemx -Wformat-overflow=@var{level}
4347 @opindex Wformat-overflow
4348 @opindex Wno-format-overflow
4349 Warn about calls to formatted input/output functions such as @code{sprintf}
4350 and @code{vsprintf} that might overflow the destination buffer.  When the
4351 exact number of bytes written by a format directive cannot be determined
4352 at compile-time it is estimated based on heuristics that depend on the
4353 @var{level} argument and on optimization.  While enabling optimization
4354 will in most cases improve the accuracy of the warning, it may also
4355 result in false positives.
4357 @table @gcctabopt
4358 @item -Wformat-overflow
4359 @itemx -Wformat-overflow=1
4360 @opindex Wformat-overflow
4361 @opindex Wno-format-overflow
4362 Level @var{1} of @option{-Wformat-overflow} enabled by @option{-Wformat}
4363 employs a conservative approach that warns only about calls that most
4364 likely overflow the buffer.  At this level, numeric arguments to format
4365 directives with unknown values are assumed to have the value of one, and
4366 strings of unknown length to be empty.  Numeric arguments that are known
4367 to be bounded to a subrange of their type, or string arguments whose output
4368 is bounded either by their directive's precision or by a finite set of
4369 string literals, are assumed to take on the value within the range that
4370 results in the most bytes on output.  For example, the call to @code{sprintf}
4371 below is diagnosed because even with both @var{a} and @var{b} equal to zero,
4372 the terminating NUL character (@code{'\0'}) appended by the function
4373 to the destination buffer will be written past its end.  Increasing
4374 the size of the buffer by a single byte is sufficient to avoid the
4375 warning, though it may not be sufficient to avoid the overflow.
4377 @smallexample
4378 void f (int a, int b)
4380   char buf [13];
4381   sprintf (buf, "a = %i, b = %i\n", a, b);
4383 @end smallexample
4385 @item -Wformat-overflow=2
4386 Level @var{2} warns also about calls that might overflow the destination
4387 buffer given an argument of sufficient length or magnitude.  At level
4388 @var{2}, unknown numeric arguments are assumed to have the minimum
4389 representable value for signed types with a precision greater than 1, and
4390 the maximum representable value otherwise.  Unknown string arguments whose
4391 length cannot be assumed to be bounded either by the directive's precision,
4392 or by a finite set of string literals they may evaluate to, or the character
4393 array they may point to, are assumed to be 1 character long.
4395 At level @var{2}, the call in the example above is again diagnosed, but
4396 this time because with @var{a} equal to a 32-bit @code{INT_MIN} the first
4397 @code{%i} directive will write some of its digits beyond the end of
4398 the destination buffer.  To make the call safe regardless of the values
4399 of the two variables, the size of the destination buffer must be increased
4400 to at least 34 bytes.  GCC includes the minimum size of the buffer in
4401 an informational note following the warning.
4403 An alternative to increasing the size of the destination buffer is to
4404 constrain the range of formatted values.  The maximum length of string
4405 arguments can be bounded by specifying the precision in the format
4406 directive.  When numeric arguments of format directives can be assumed
4407 to be bounded by less than the precision of their type, choosing
4408 an appropriate length modifier to the format specifier will reduce
4409 the required buffer size.  For example, if @var{a} and @var{b} in the
4410 example above can be assumed to be within the precision of
4411 the @code{short int} type then using either the @code{%hi} format
4412 directive or casting the argument to @code{short} reduces the maximum
4413 required size of the buffer to 24 bytes.
4415 @smallexample
4416 void f (int a, int b)
4418   char buf [23];
4419   sprintf (buf, "a = %hi, b = %i\n", a, (short)b);
4421 @end smallexample
4422 @end table
4424 @item -Wno-format-zero-length
4425 @opindex Wno-format-zero-length
4426 @opindex Wformat-zero-length
4427 If @option{-Wformat} is specified, do not warn about zero-length formats.
4428 The C standard specifies that zero-length formats are allowed.
4431 @item -Wformat=2
4432 @opindex Wformat=2
4433 Enable @option{-Wformat} plus additional format checks.  Currently
4434 equivalent to @option{-Wformat -Wformat-nonliteral -Wformat-security
4435 -Wformat-y2k}.
4437 @item -Wformat-nonliteral
4438 @opindex Wformat-nonliteral
4439 @opindex Wno-format-nonliteral
4440 If @option{-Wformat} is specified, also warn if the format string is not a
4441 string literal and so cannot be checked, unless the format function
4442 takes its format arguments as a @code{va_list}.
4444 @item -Wformat-security
4445 @opindex Wformat-security
4446 @opindex Wno-format-security
4447 If @option{-Wformat} is specified, also warn about uses of format
4448 functions that represent possible security problems.  At present, this
4449 warns about calls to @code{printf} and @code{scanf} functions where the
4450 format string is not a string literal and there are no format arguments,
4451 as in @code{printf (foo);}.  This may be a security hole if the format
4452 string came from untrusted input and contains @samp{%n}.  (This is
4453 currently a subset of what @option{-Wformat-nonliteral} warns about, but
4454 in future warnings may be added to @option{-Wformat-security} that are not
4455 included in @option{-Wformat-nonliteral}.)
4457 @item -Wformat-signedness
4458 @opindex Wformat-signedness
4459 @opindex Wno-format-signedness
4460 If @option{-Wformat} is specified, also warn if the format string
4461 requires an unsigned argument and the argument is signed and vice versa.
4463 @item -Wformat-truncation
4464 @itemx -Wformat-truncation=@var{level}
4465 @opindex Wformat-truncation
4466 @opindex Wno-format-truncation
4467 Warn about calls to formatted input/output functions such as @code{snprintf}
4468 and @code{vsnprintf} that might result in output truncation.  When the exact
4469 number of bytes written by a format directive cannot be determined at
4470 compile-time it is estimated based on heuristics that depend on
4471 the @var{level} argument and on optimization.  While enabling optimization
4472 will in most cases improve the accuracy of the warning, it may also result
4473 in false positives.  Except as noted otherwise, the option uses the same
4474 logic @option{-Wformat-overflow}.
4476 @table @gcctabopt
4477 @item -Wformat-truncation
4478 @itemx -Wformat-truncation=1
4479 @opindex Wformat-truncation
4480 @opindex Wno-format-truncation
4481 Level @var{1} of @option{-Wformat-truncation} enabled by @option{-Wformat}
4482 employs a conservative approach that warns only about calls to bounded
4483 functions whose return value is unused and that will most likely result
4484 in output truncation.
4486 @item -Wformat-truncation=2
4487 Level @var{2} warns also about calls to bounded functions whose return
4488 value is used and that might result in truncation given an argument of
4489 sufficient length or magnitude.
4490 @end table
4492 @item -Wformat-y2k
4493 @opindex Wformat-y2k
4494 @opindex Wno-format-y2k
4495 If @option{-Wformat} is specified, also warn about @code{strftime}
4496 formats that may yield only a two-digit year.
4497 @end table
4499 @item -Wnonnull
4500 @opindex Wnonnull
4501 @opindex Wno-nonnull
4502 Warn about passing a null pointer for arguments marked as
4503 requiring a non-null value by the @code{nonnull} function attribute.
4505 @option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}.  It
4506 can be disabled with the @option{-Wno-nonnull} option.
4508 @item -Wnonnull-compare
4509 @opindex Wnonnull-compare
4510 @opindex Wno-nonnull-compare
4511 Warn when comparing an argument marked with the @code{nonnull}
4512 function attribute against null inside the function.
4514 @option{-Wnonnull-compare} is included in @option{-Wall}.  It
4515 can be disabled with the @option{-Wno-nonnull-compare} option.
4517 @item -Wnull-dereference
4518 @opindex Wnull-dereference
4519 @opindex Wno-null-dereference
4520 Warn if the compiler detects paths that trigger erroneous or
4521 undefined behavior due to dereferencing a null pointer.  This option
4522 is only active when @option{-fdelete-null-pointer-checks} is active,
4523 which is enabled by optimizations in most targets.  The precision of
4524 the warnings depends on the optimization options used.
4526 @item -Winit-self @r{(C, C++, Objective-C and Objective-C++ only)}
4527 @opindex Winit-self
4528 @opindex Wno-init-self
4529 Warn about uninitialized variables that are initialized with themselves.
4530 Note this option can only be used with the @option{-Wuninitialized} option.
4532 For example, GCC warns about @code{i} being uninitialized in the
4533 following snippet only when @option{-Winit-self} has been specified:
4534 @smallexample
4535 @group
4536 int f()
4538   int i = i;
4539   return i;
4541 @end group
4542 @end smallexample
4544 This warning is enabled by @option{-Wall} in C++.
4546 @item -Wimplicit-int @r{(C and Objective-C only)}
4547 @opindex Wimplicit-int
4548 @opindex Wno-implicit-int
4549 Warn when a declaration does not specify a type.
4550 This warning is enabled by @option{-Wall}.
4552 @item -Wimplicit-function-declaration @r{(C and Objective-C only)}
4553 @opindex Wimplicit-function-declaration
4554 @opindex Wno-implicit-function-declaration
4555 Give a warning whenever a function is used before being declared. In
4556 C99 mode (@option{-std=c99} or @option{-std=gnu99}), this warning is
4557 enabled by default and it is made into an error by
4558 @option{-pedantic-errors}. This warning is also enabled by
4559 @option{-Wall}.
4561 @item -Wimplicit @r{(C and Objective-C only)}
4562 @opindex Wimplicit
4563 @opindex Wno-implicit
4564 Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
4565 This warning is enabled by @option{-Wall}.
4567 @item -Wimplicit-fallthrough
4568 @opindex Wimplicit-fallthrough
4569 @opindex Wno-implicit-fallthrough
4570 @option{-Wimplicit-fallthrough} is the same as @option{-Wimplicit-fallthrough=3}
4571 and @option{-Wno-implicit-fallthrough} is the same as
4572 @option{-Wimplicit-fallthrough=0}.
4574 @item -Wimplicit-fallthrough=@var{n}
4575 @opindex Wimplicit-fallthrough=
4576 Warn when a switch case falls through.  For example:
4578 @smallexample
4579 @group
4580 switch (cond)
4581   @{
4582   case 1:
4583     a = 1;
4584     break;
4585   case 2:
4586     a = 2;
4587   case 3:
4588     a = 3;
4589     break;
4590   @}
4591 @end group
4592 @end smallexample
4594 This warning does not warn when the last statement of a case cannot
4595 fall through, e.g. when there is a return statement or a call to function
4596 declared with the noreturn attribute.  @option{-Wimplicit-fallthrough=}
4597 also takes into account control flow statements, such as ifs, and only
4598 warns when appropriate.  E.g.@:
4600 @smallexample
4601 @group
4602 switch (cond)
4603   @{
4604   case 1:
4605     if (i > 3) @{
4606       bar (5);
4607       break;
4608     @} else if (i < 1) @{
4609       bar (0);
4610     @} else
4611       return;
4612   default:
4613     @dots{}
4614   @}
4615 @end group
4616 @end smallexample
4618 Since there are occasions where a switch case fall through is desirable,
4619 GCC provides an attribute, @code{__attribute__ ((fallthrough))}, that is
4620 to be used along with a null statement to suppress this warning that
4621 would normally occur:
4623 @smallexample
4624 @group
4625 switch (cond)
4626   @{
4627   case 1:
4628     bar (0);
4629     __attribute__ ((fallthrough));
4630   default:
4631     @dots{}
4632   @}
4633 @end group
4634 @end smallexample
4636 C++17 provides a standard way to suppress the @option{-Wimplicit-fallthrough}
4637 warning using @code{[[fallthrough]];} instead of the GNU attribute.  In C++11
4638 or C++14 users can use @code{[[gnu::fallthrough]];}, which is a GNU extension.
4639 Instead of these attributes, it is also possible to add a fallthrough comment
4640 to silence the warning.  The whole body of the C or C++ style comment should
4641 match the given regular expressions listed below.  The option argument @var{n}
4642 specifies what kind of comments are accepted:
4644 @itemize @bullet
4646 @item @option{-Wimplicit-fallthrough=0} disables the warning altogether.
4648 @item @option{-Wimplicit-fallthrough=1} matches @code{.*} regular
4649 expression, any comment is used as fallthrough comment.
4651 @item @option{-Wimplicit-fallthrough=2} case insensitively matches
4652 @code{.*falls?[ \t-]*thr(ough|u).*} regular expression.
4654 @item @option{-Wimplicit-fallthrough=3} case sensitively matches one of the
4655 following regular expressions:
4657 @itemize @bullet
4659 @item @code{-fallthrough}
4661 @item @code{@@fallthrough@@}
4663 @item @code{lint -fallthrough[ \t]*}
4665 @item @code{[ \t.!]*(ELSE,? |INTENTIONAL(LY)? )?@*FALL(S | |-)?THR(OUGH|U)[ \t.!]*(-[^\n\r]*)?}
4667 @item @code{[ \t.!]*(Else,? |Intentional(ly)? )?@*Fall((s | |-)[Tt]|t)hr(ough|u)[ \t.!]*(-[^\n\r]*)?}
4669 @item @code{[ \t.!]*([Ee]lse,? |[Ii]ntentional(ly)? )?@*fall(s | |-)?thr(ough|u)[ \t.!]*(-[^\n\r]*)?}
4671 @end itemize
4673 @item @option{-Wimplicit-fallthrough=4} case sensitively matches one of the
4674 following regular expressions:
4676 @itemize @bullet
4678 @item @code{-fallthrough}
4680 @item @code{@@fallthrough@@}
4682 @item @code{lint -fallthrough[ \t]*}
4684 @item @code{[ \t]*FALLTHR(OUGH|U)[ \t]*}
4686 @end itemize
4688 @item @option{-Wimplicit-fallthrough=5} doesn't recognize any comments as
4689 fallthrough comments, only attributes disable the warning.
4691 @end itemize
4693 The comment needs to be followed after optional whitespace and other comments
4694 by @code{case} or @code{default} keywords or by a user label that precedes some
4695 @code{case} or @code{default} label.
4697 @smallexample
4698 @group
4699 switch (cond)
4700   @{
4701   case 1:
4702     bar (0);
4703     /* FALLTHRU */
4704   default:
4705     @dots{}
4706   @}
4707 @end group
4708 @end smallexample
4710 The @option{-Wimplicit-fallthrough=3} warning is enabled by @option{-Wextra}.
4712 @item -Wif-not-aligned @r{(C, C++, Objective-C and Objective-C++ only)}
4713 @opindex Wif-not-aligned
4714 @opindex Wno-if-not-aligned
4715 Control if warning triggered by the @code{warn_if_not_aligned} attribute
4716 should be issued.  This is enabled by default.
4717 Use @option{-Wno-if-not-aligned} to disable it.
4719 @item -Wignored-qualifiers @r{(C and C++ only)}
4720 @opindex Wignored-qualifiers
4721 @opindex Wno-ignored-qualifiers
4722 Warn if the return type of a function has a type qualifier
4723 such as @code{const}.  For ISO C such a type qualifier has no effect,
4724 since the value returned by a function is not an lvalue.
4725 For C++, the warning is only emitted for scalar types or @code{void}.
4726 ISO C prohibits qualified @code{void} return types on function
4727 definitions, so such return types always receive a warning
4728 even without this option.
4730 This warning is also enabled by @option{-Wextra}.
4732 @item -Wignored-attributes @r{(C and C++ only)}
4733 @opindex Wignored-attributes
4734 @opindex Wno-ignored-attributes
4735 Warn when an attribute is ignored.  This is different from the
4736 @option{-Wattributes} option in that it warns whenever the compiler decides
4737 to drop an attribute, not that the attribute is either unknown, used in a
4738 wrong place, etc.  This warning is enabled by default.
4740 @item -Wmain
4741 @opindex Wmain
4742 @opindex Wno-main
4743 Warn if the type of @code{main} is suspicious.  @code{main} should be
4744 a function with external linkage, returning int, taking either zero
4745 arguments, two, or three arguments of appropriate types.  This warning
4746 is enabled by default in C++ and is enabled by either @option{-Wall}
4747 or @option{-Wpedantic}.
4749 @item -Wmisleading-indentation @r{(C and C++ only)}
4750 @opindex Wmisleading-indentation
4751 @opindex Wno-misleading-indentation
4752 Warn when the indentation of the code does not reflect the block structure.
4753 Specifically, a warning is issued for @code{if}, @code{else}, @code{while}, and
4754 @code{for} clauses with a guarded statement that does not use braces,
4755 followed by an unguarded statement with the same indentation.
4757 In the following example, the call to ``bar'' is misleadingly indented as
4758 if it were guarded by the ``if'' conditional.
4760 @smallexample
4761   if (some_condition ())
4762     foo ();
4763     bar ();  /* Gotcha: this is not guarded by the "if".  */
4764 @end smallexample
4766 In the case of mixed tabs and spaces, the warning uses the
4767 @option{-ftabstop=} option to determine if the statements line up
4768 (defaulting to 8).
4770 The warning is not issued for code involving multiline preprocessor logic
4771 such as the following example.
4773 @smallexample
4774   if (flagA)
4775     foo (0);
4776 #if SOME_CONDITION_THAT_DOES_NOT_HOLD
4777   if (flagB)
4778 #endif
4779     foo (1);
4780 @end smallexample
4782 The warning is not issued after a @code{#line} directive, since this
4783 typically indicates autogenerated code, and no assumptions can be made
4784 about the layout of the file that the directive references.
4786 This warning is enabled by @option{-Wall} in C and C++.
4788 @item -Wmissing-attributes
4789 @opindex Wmissing-attributes
4790 @opindex Wno-missing-attributes
4791 Warn when a declaration of a function is missing one or more attributes
4792 that a related function is declared with and whose absence may adversely
4793 affect the correctness or efficiency of generated code.  For example, in
4794 C++, the warning is issued when an explicit specialization of a primary
4795 template declared with attribute @code{alloc_align}, @code{alloc_size},
4796 @code{assume_aligned}, @code{format}, @code{format_arg}, @code{malloc},
4797 or @code{nonnull} is declared without it.  Attributes @code{deprecated},
4798 @code{error}, and @code{warning} suppress the warning.
4799 (@pxref{Function Attributes}).
4801 @option{-Wmissing-attributes} is enabled by @option{-Wall}.
4803 For example, since the declaration of the primary function template
4804 below makes use of both attribute @code{malloc} and @code{alloc_size}
4805 the declaration of the explicit specialization of the template is
4806 diagnosed because it is missing one of the attributes.
4808 @smallexample
4809 template <class T>
4810 T* __attribute__ ((malloc, alloc_size (1)))
4811 allocate (size_t);
4813 template <>
4814 void* __attribute__ ((malloc))   // missing alloc_size
4815 allocate<void> (size_t);
4816 @end smallexample
4818 @item -Wmissing-braces
4819 @opindex Wmissing-braces
4820 @opindex Wno-missing-braces
4821 Warn if an aggregate or union initializer is not fully bracketed.  In
4822 the following example, the initializer for @code{a} is not fully
4823 bracketed, but that for @code{b} is fully bracketed.  This warning is
4824 enabled by @option{-Wall} in C.
4826 @smallexample
4827 int a[2][2] = @{ 0, 1, 2, 3 @};
4828 int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
4829 @end smallexample
4831 This warning is enabled by @option{-Wall}.
4833 @item -Wmissing-include-dirs @r{(C, C++, Objective-C and Objective-C++ only)}
4834 @opindex Wmissing-include-dirs
4835 @opindex Wno-missing-include-dirs
4836 Warn if a user-supplied include directory does not exist.
4838 @item -Wmissing-profile
4839 @opindex Wmissing-profile
4840 @opindex Wno-missing-profile
4841 Warn if feedback profiles are missing when using the
4842 @option{-fprofile-use} option.
4843 This option diagnoses those cases where a new function or a new file is added
4844 to the user code between compiling with @option{-fprofile-generate} and with
4845 @option{-fprofile-use}, without regenerating the profiles.  In these cases, the
4846 profile feedback data files do not contain any profile feedback information for
4847 the newly added function or file respectively.  Also, in the case when profile
4848 count data (.gcda) files are removed, GCC cannot use any profile feedback
4849 information.  In all these cases, warnings are issued to inform the user that a
4850 profile generation step is due.  @option{-Wno-missing-profile} can be used to
4851 disable the warning.  Ignoring the warning can result in poorly optimized code.
4852 Completely disabling the warning is not recommended and should be done only
4853 when non-existent profile data is justified.
4855 @item -Wmultistatement-macros
4856 @opindex Wmultistatement-macros
4857 @opindex Wno-multistatement-macros
4858 Warn about unsafe multiple statement macros that appear to be guarded
4859 by a clause such as @code{if}, @code{else}, @code{for}, @code{switch}, or
4860 @code{while}, in which only the first statement is actually guarded after
4861 the macro is expanded.
4863 For example:
4865 @smallexample
4866 #define DOIT x++; y++
4867 if (c)
4868   DOIT;
4869 @end smallexample
4871 will increment @code{y} unconditionally, not just when @code{c} holds.
4872 The can usually be fixed by wrapping the macro in a do-while loop:
4873 @smallexample
4874 #define DOIT do @{ x++; y++; @} while (0)
4875 if (c)
4876   DOIT;
4877 @end smallexample
4879 This warning is enabled by @option{-Wall} in C and C++.
4881 @item -Wparentheses
4882 @opindex Wparentheses
4883 @opindex Wno-parentheses
4884 Warn if parentheses are omitted in certain contexts, such
4885 as when there is an assignment in a context where a truth value
4886 is expected, or when operators are nested whose precedence people
4887 often get confused about.
4889 Also warn if a comparison like @code{x<=y<=z} appears; this is
4890 equivalent to @code{(x<=y ? 1 : 0) <= z}, which is a different
4891 interpretation from that of ordinary mathematical notation.
4893 Also warn for dangerous uses of the GNU extension to
4894 @code{?:} with omitted middle operand. When the condition
4895 in the @code{?}: operator is a boolean expression, the omitted value is
4896 always 1.  Often programmers expect it to be a value computed
4897 inside the conditional expression instead.
4899 For C++ this also warns for some cases of unnecessary parentheses in
4900 declarations, which can indicate an attempt at a function call instead
4901 of a declaration:
4902 @smallexample
4904   // Declares a local variable called mymutex.
4905   std::unique_lock<std::mutex> (mymutex);
4906   // User meant std::unique_lock<std::mutex> lock (mymutex);
4908 @end smallexample
4910 This warning is enabled by @option{-Wall}.
4912 @item -Wsequence-point
4913 @opindex Wsequence-point
4914 @opindex Wno-sequence-point
4915 Warn about code that may have undefined semantics because of violations
4916 of sequence point rules in the C and C++ standards.
4918 The C and C++ standards define the order in which expressions in a C/C++
4919 program are evaluated in terms of @dfn{sequence points}, which represent
4920 a partial ordering between the execution of parts of the program: those
4921 executed before the sequence point, and those executed after it.  These
4922 occur after the evaluation of a full expression (one which is not part
4923 of a larger expression), after the evaluation of the first operand of a
4924 @code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
4925 function is called (but after the evaluation of its arguments and the
4926 expression denoting the called function), and in certain other places.
4927 Other than as expressed by the sequence point rules, the order of
4928 evaluation of subexpressions of an expression is not specified.  All
4929 these rules describe only a partial order rather than a total order,
4930 since, for example, if two functions are called within one expression
4931 with no sequence point between them, the order in which the functions
4932 are called is not specified.  However, the standards committee have
4933 ruled that function calls do not overlap.
4935 It is not specified when between sequence points modifications to the
4936 values of objects take effect.  Programs whose behavior depends on this
4937 have undefined behavior; the C and C++ standards specify that ``Between
4938 the previous and next sequence point an object shall have its stored
4939 value modified at most once by the evaluation of an expression.
4940 Furthermore, the prior value shall be read only to determine the value
4941 to be stored.''.  If a program breaks these rules, the results on any
4942 particular implementation are entirely unpredictable.
4944 Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
4945 = b[n++]} and @code{a[i++] = i;}.  Some more complicated cases are not
4946 diagnosed by this option, and it may give an occasional false positive
4947 result, but in general it has been found fairly effective at detecting
4948 this sort of problem in programs.
4950 The C++17 standard will define the order of evaluation of operands in
4951 more cases: in particular it requires that the right-hand side of an
4952 assignment be evaluated before the left-hand side, so the above
4953 examples are no longer undefined.  But this warning will still warn
4954 about them, to help people avoid writing code that is undefined in C
4955 and earlier revisions of C++.
4957 The standard is worded confusingly, therefore there is some debate
4958 over the precise meaning of the sequence point rules in subtle cases.
4959 Links to discussions of the problem, including proposed formal
4960 definitions, may be found on the GCC readings page, at
4961 @uref{http://gcc.gnu.org/@/readings.html}.
4963 This warning is enabled by @option{-Wall} for C and C++.
4965 @item -Wno-return-local-addr
4966 @opindex Wno-return-local-addr
4967 @opindex Wreturn-local-addr
4968 Do not warn about returning a pointer (or in C++, a reference) to a
4969 variable that goes out of scope after the function returns.
4971 @item -Wreturn-type
4972 @opindex Wreturn-type
4973 @opindex Wno-return-type
4974 Warn whenever a function is defined with a return type that defaults
4975 to @code{int}.  Also warn about any @code{return} statement with no
4976 return value in a function whose return type is not @code{void}
4977 (falling off the end of the function body is considered returning
4978 without a value).
4980 For C only, warn about a @code{return} statement with an expression in a
4981 function whose return type is @code{void}, unless the expression type is
4982 also @code{void}.  As a GNU extension, the latter case is accepted
4983 without a warning unless @option{-Wpedantic} is used.
4985 For C++, a function without return type always produces a diagnostic
4986 message, even when @option{-Wno-return-type} is specified.  The only
4987 exceptions are @code{main} and functions defined in system headers.
4989 This warning is enabled by default for C++ and is enabled by @option{-Wall}.
4991 @item -Wshift-count-negative
4992 @opindex Wshift-count-negative
4993 @opindex Wno-shift-count-negative
4994 Warn if shift count is negative. This warning is enabled by default.
4996 @item -Wshift-count-overflow
4997 @opindex Wshift-count-overflow
4998 @opindex Wno-shift-count-overflow
4999 Warn if shift count >= width of type. This warning is enabled by default.
5001 @item -Wshift-negative-value
5002 @opindex Wshift-negative-value
5003 @opindex Wno-shift-negative-value
5004 Warn if left shifting a negative value.  This warning is enabled by
5005 @option{-Wextra} in C99 and C++11 modes (and newer).
5007 @item -Wshift-overflow
5008 @itemx -Wshift-overflow=@var{n}
5009 @opindex Wshift-overflow
5010 @opindex Wno-shift-overflow
5011 Warn about left shift overflows.  This warning is enabled by
5012 default in C99 and C++11 modes (and newer).
5014 @table @gcctabopt
5015 @item -Wshift-overflow=1
5016 This is the warning level of @option{-Wshift-overflow} and is enabled
5017 by default in C99 and C++11 modes (and newer).  This warning level does
5018 not warn about left-shifting 1 into the sign bit.  (However, in C, such
5019 an overflow is still rejected in contexts where an integer constant expression
5020 is required.)
5022 @item -Wshift-overflow=2
5023 This warning level also warns about left-shifting 1 into the sign bit,
5024 unless C++14 mode is active.
5025 @end table
5027 @item -Wswitch
5028 @opindex Wswitch
5029 @opindex Wno-switch
5030 Warn whenever a @code{switch} statement has an index of enumerated type
5031 and lacks a @code{case} for one or more of the named codes of that
5032 enumeration.  (The presence of a @code{default} label prevents this
5033 warning.)  @code{case} labels outside the enumeration range also
5034 provoke warnings when this option is used (even if there is a
5035 @code{default} label).
5036 This warning is enabled by @option{-Wall}.
5038 @item -Wswitch-default
5039 @opindex Wswitch-default
5040 @opindex Wno-switch-default
5041 Warn whenever a @code{switch} statement does not have a @code{default}
5042 case.
5044 @item -Wswitch-enum
5045 @opindex Wswitch-enum
5046 @opindex Wno-switch-enum
5047 Warn whenever a @code{switch} statement has an index of enumerated type
5048 and lacks a @code{case} for one or more of the named codes of that
5049 enumeration.  @code{case} labels outside the enumeration range also
5050 provoke warnings when this option is used.  The only difference
5051 between @option{-Wswitch} and this option is that this option gives a
5052 warning about an omitted enumeration code even if there is a
5053 @code{default} label.
5055 @item -Wswitch-bool
5056 @opindex Wswitch-bool
5057 @opindex Wno-switch-bool
5058 Warn whenever a @code{switch} statement has an index of boolean type
5059 and the case values are outside the range of a boolean type.
5060 It is possible to suppress this warning by casting the controlling
5061 expression to a type other than @code{bool}.  For example:
5062 @smallexample
5063 @group
5064 switch ((int) (a == 4))
5065   @{
5066   @dots{}
5067   @}
5068 @end group
5069 @end smallexample
5070 This warning is enabled by default for C and C++ programs.
5072 @item -Wswitch-unreachable
5073 @opindex Wswitch-unreachable
5074 @opindex Wno-switch-unreachable
5075 Warn whenever a @code{switch} statement contains statements between the
5076 controlling expression and the first case label, which will never be
5077 executed.  For example:
5078 @smallexample
5079 @group
5080 switch (cond)
5081   @{
5082    i = 15;
5083   @dots{}
5084    case 5:
5085   @dots{}
5086   @}
5087 @end group
5088 @end smallexample
5089 @option{-Wswitch-unreachable} does not warn if the statement between the
5090 controlling expression and the first case label is just a declaration:
5091 @smallexample
5092 @group
5093 switch (cond)
5094   @{
5095    int i;
5096   @dots{}
5097    case 5:
5098    i = 5;
5099   @dots{}
5100   @}
5101 @end group
5102 @end smallexample
5103 This warning is enabled by default for C and C++ programs.
5105 @item -Wsync-nand @r{(C and C++ only)}
5106 @opindex Wsync-nand
5107 @opindex Wno-sync-nand
5108 Warn when @code{__sync_fetch_and_nand} and @code{__sync_nand_and_fetch}
5109 built-in functions are used.  These functions changed semantics in GCC 4.4.
5111 @item -Wunused-but-set-parameter
5112 @opindex Wunused-but-set-parameter
5113 @opindex Wno-unused-but-set-parameter
5114 Warn whenever a function parameter is assigned to, but otherwise unused
5115 (aside from its declaration).
5117 To suppress this warning use the @code{unused} attribute
5118 (@pxref{Variable Attributes}).
5120 This warning is also enabled by @option{-Wunused} together with
5121 @option{-Wextra}.
5123 @item -Wunused-but-set-variable
5124 @opindex Wunused-but-set-variable
5125 @opindex Wno-unused-but-set-variable
5126 Warn whenever a local variable is assigned to, but otherwise unused
5127 (aside from its declaration).
5128 This warning is enabled by @option{-Wall}.
5130 To suppress this warning use the @code{unused} attribute
5131 (@pxref{Variable Attributes}).
5133 This warning is also enabled by @option{-Wunused}, which is enabled
5134 by @option{-Wall}.
5136 @item -Wunused-function
5137 @opindex Wunused-function
5138 @opindex Wno-unused-function
5139 Warn whenever a static function is declared but not defined or a
5140 non-inline static function is unused.
5141 This warning is enabled by @option{-Wall}.
5143 @item -Wunused-label
5144 @opindex Wunused-label
5145 @opindex Wno-unused-label
5146 Warn whenever a label is declared but not used.
5147 This warning is enabled by @option{-Wall}.
5149 To suppress this warning use the @code{unused} attribute
5150 (@pxref{Variable Attributes}).
5152 @item -Wunused-local-typedefs @r{(C, Objective-C, C++ and Objective-C++ only)}
5153 @opindex Wunused-local-typedefs
5154 @opindex Wno-unused-local-typedefs
5155 Warn when a typedef locally defined in a function is not used.
5156 This warning is enabled by @option{-Wall}.
5158 @item -Wunused-parameter
5159 @opindex Wunused-parameter
5160 @opindex Wno-unused-parameter
5161 Warn whenever a function parameter is unused aside from its declaration.
5163 To suppress this warning use the @code{unused} attribute
5164 (@pxref{Variable Attributes}).
5166 @item -Wno-unused-result
5167 @opindex Wunused-result
5168 @opindex Wno-unused-result
5169 Do not warn if a caller of a function marked with attribute
5170 @code{warn_unused_result} (@pxref{Function Attributes}) does not use
5171 its return value. The default is @option{-Wunused-result}.
5173 @item -Wunused-variable
5174 @opindex Wunused-variable
5175 @opindex Wno-unused-variable
5176 Warn whenever a local or static variable is unused aside from its
5177 declaration. This option implies @option{-Wunused-const-variable=1} for C,
5178 but not for C++. This warning is enabled by @option{-Wall}.
5180 To suppress this warning use the @code{unused} attribute
5181 (@pxref{Variable Attributes}).
5183 @item -Wunused-const-variable
5184 @itemx -Wunused-const-variable=@var{n}
5185 @opindex Wunused-const-variable
5186 @opindex Wno-unused-const-variable
5187 Warn whenever a constant static variable is unused aside from its declaration.
5188 @option{-Wunused-const-variable=1} is enabled by @option{-Wunused-variable}
5189 for C, but not for C++. In C this declares variable storage, but in C++ this
5190 is not an error since const variables take the place of @code{#define}s.
5192 To suppress this warning use the @code{unused} attribute
5193 (@pxref{Variable Attributes}).
5195 @table @gcctabopt
5196 @item -Wunused-const-variable=1
5197 This is the warning level that is enabled by @option{-Wunused-variable} for
5198 C.  It warns only about unused static const variables defined in the main
5199 compilation unit, but not about static const variables declared in any
5200 header included.
5202 @item -Wunused-const-variable=2
5203 This warning level also warns for unused constant static variables in
5204 headers (excluding system headers).  This is the warning level of
5205 @option{-Wunused-const-variable} and must be explicitly requested since
5206 in C++ this isn't an error and in C it might be harder to clean up all
5207 headers included.
5208 @end table
5210 @item -Wunused-value
5211 @opindex Wunused-value
5212 @opindex Wno-unused-value
5213 Warn whenever a statement computes a result that is explicitly not
5214 used. To suppress this warning cast the unused expression to
5215 @code{void}. This includes an expression-statement or the left-hand
5216 side of a comma expression that contains no side effects. For example,
5217 an expression such as @code{x[i,j]} causes a warning, while
5218 @code{x[(void)i,j]} does not.
5220 This warning is enabled by @option{-Wall}.
5222 @item -Wunused
5223 @opindex Wunused
5224 @opindex Wno-unused
5225 All the above @option{-Wunused} options combined.
5227 In order to get a warning about an unused function parameter, you must
5228 either specify @option{-Wextra -Wunused} (note that @option{-Wall} implies
5229 @option{-Wunused}), or separately specify @option{-Wunused-parameter}.
5231 @item -Wuninitialized
5232 @opindex Wuninitialized
5233 @opindex Wno-uninitialized
5234 Warn if an automatic variable is used without first being initialized
5235 or if a variable may be clobbered by a @code{setjmp} call. In C++,
5236 warn if a non-static reference or non-static @code{const} member
5237 appears in a class without constructors.
5239 If you want to warn about code that uses the uninitialized value of the
5240 variable in its own initializer, use the @option{-Winit-self} option.
5242 These warnings occur for individual uninitialized or clobbered
5243 elements of structure, union or array variables as well as for
5244 variables that are uninitialized or clobbered as a whole.  They do
5245 not occur for variables or elements declared @code{volatile}.  Because
5246 these warnings depend on optimization, the exact variables or elements
5247 for which there are warnings depends on the precise optimization
5248 options and version of GCC used.
5250 Note that there may be no warning about a variable that is used only
5251 to compute a value that itself is never used, because such
5252 computations may be deleted by data flow analysis before the warnings
5253 are printed.
5255 @item -Winvalid-memory-model
5256 @opindex Winvalid-memory-model
5257 @opindex Wno-invalid-memory-model
5258 Warn for invocations of @ref{__atomic Builtins}, @ref{__sync Builtins},
5259 and the C11 atomic generic functions with a memory consistency argument
5260 that is either invalid for the operation or outside the range of values
5261 of the @code{memory_order} enumeration.  For example, since the
5262 @code{__atomic_store} and @code{__atomic_store_n} built-ins are only
5263 defined for the relaxed, release, and sequentially consistent memory
5264 orders the following code is diagnosed:
5266 @smallexample
5267 void store (int *i)
5269   __atomic_store_n (i, 0, memory_order_consume);
5271 @end smallexample
5273 @option{-Winvalid-memory-model} is enabled by default.
5275 @item -Wmaybe-uninitialized
5276 @opindex Wmaybe-uninitialized
5277 @opindex Wno-maybe-uninitialized
5278 For an automatic (i.e.@ local) variable, if there exists a path from the
5279 function entry to a use of the variable that is initialized, but there exist
5280 some other paths for which the variable is not initialized, the compiler
5281 emits a warning if it cannot prove the uninitialized paths are not
5282 executed at run time.
5284 These warnings are only possible in optimizing compilation, because otherwise
5285 GCC does not keep track of the state of variables.
5287 These warnings are made optional because GCC may not be able to determine when
5288 the code is correct in spite of appearing to have an error.  Here is one
5289 example of how this can happen:
5291 @smallexample
5292 @group
5294   int x;
5295   switch (y)
5296     @{
5297     case 1: x = 1;
5298       break;
5299     case 2: x = 4;
5300       break;
5301     case 3: x = 5;
5302     @}
5303   foo (x);
5305 @end group
5306 @end smallexample
5308 @noindent
5309 If the value of @code{y} is always 1, 2 or 3, then @code{x} is
5310 always initialized, but GCC doesn't know this. To suppress the
5311 warning, you need to provide a default case with assert(0) or
5312 similar code.
5314 @cindex @code{longjmp} warnings
5315 This option also warns when a non-volatile automatic variable might be
5316 changed by a call to @code{longjmp}.
5317 The compiler sees only the calls to @code{setjmp}.  It cannot know
5318 where @code{longjmp} will be called; in fact, a signal handler could
5319 call it at any point in the code.  As a result, you may get a warning
5320 even when there is in fact no problem because @code{longjmp} cannot
5321 in fact be called at the place that would cause a problem.
5323 Some spurious warnings can be avoided if you declare all the functions
5324 you use that never return as @code{noreturn}.  @xref{Function
5325 Attributes}.
5327 This warning is enabled by @option{-Wall} or @option{-Wextra}.
5329 @item -Wunknown-pragmas
5330 @opindex Wunknown-pragmas
5331 @opindex Wno-unknown-pragmas
5332 @cindex warning for unknown pragmas
5333 @cindex unknown pragmas, warning
5334 @cindex pragmas, warning of unknown
5335 Warn when a @code{#pragma} directive is encountered that is not understood by 
5336 GCC@.  If this command-line option is used, warnings are even issued
5337 for unknown pragmas in system header files.  This is not the case if
5338 the warnings are only enabled by the @option{-Wall} command-line option.
5340 @item -Wno-pragmas
5341 @opindex Wno-pragmas
5342 @opindex Wpragmas
5343 Do not warn about misuses of pragmas, such as incorrect parameters,
5344 invalid syntax, or conflicts between pragmas.  See also
5345 @option{-Wunknown-pragmas}.
5347 @item -Wno-prio-ctor-dtor
5348 @opindex Wno-prio-ctor-dtor
5349 @opindex Wprio-ctor-dtor
5350 Do not warn if a priority from 0 to 100 is used for constructor or destructor.
5351 The use of constructor and destructor attributes allow you to assign a
5352 priority to the constructor/destructor to control its order of execution
5353 before @code{main} is called or after it returns.  The priority values must be
5354 greater than 100 as the compiler reserves priority values between 0--100 for
5355 the implementation.
5357 @item -Wstrict-aliasing
5358 @opindex Wstrict-aliasing
5359 @opindex Wno-strict-aliasing
5360 This option is only active when @option{-fstrict-aliasing} is active.
5361 It warns about code that might break the strict aliasing rules that the
5362 compiler is using for optimization.  The warning does not catch all
5363 cases, but does attempt to catch the more common pitfalls.  It is
5364 included in @option{-Wall}.
5365 It is equivalent to @option{-Wstrict-aliasing=3}
5367 @item -Wstrict-aliasing=n
5368 @opindex Wstrict-aliasing=n
5369 This option is only active when @option{-fstrict-aliasing} is active.
5370 It warns about code that might break the strict aliasing rules that the
5371 compiler is using for optimization.
5372 Higher levels correspond to higher accuracy (fewer false positives).
5373 Higher levels also correspond to more effort, similar to the way @option{-O} 
5374 works.
5375 @option{-Wstrict-aliasing} is equivalent to @option{-Wstrict-aliasing=3}.
5377 Level 1: Most aggressive, quick, least accurate.
5378 Possibly useful when higher levels
5379 do not warn but @option{-fstrict-aliasing} still breaks the code, as it has very few
5380 false negatives.  However, it has many false positives.
5381 Warns for all pointer conversions between possibly incompatible types,
5382 even if never dereferenced.  Runs in the front end only.
5384 Level 2: Aggressive, quick, not too precise.
5385 May still have many false positives (not as many as level 1 though),
5386 and few false negatives (but possibly more than level 1).
5387 Unlike level 1, it only warns when an address is taken.  Warns about
5388 incomplete types.  Runs in the front end only.
5390 Level 3 (default for @option{-Wstrict-aliasing}):
5391 Should have very few false positives and few false
5392 negatives.  Slightly slower than levels 1 or 2 when optimization is enabled.
5393 Takes care of the common pun+dereference pattern in the front end:
5394 @code{*(int*)&some_float}.
5395 If optimization is enabled, it also runs in the back end, where it deals
5396 with multiple statement cases using flow-sensitive points-to information.
5397 Only warns when the converted pointer is dereferenced.
5398 Does not warn about incomplete types.
5400 @item -Wstrict-overflow
5401 @itemx -Wstrict-overflow=@var{n}
5402 @opindex Wstrict-overflow
5403 @opindex Wno-strict-overflow
5404 This option is only active when signed overflow is undefined.
5405 It warns about cases where the compiler optimizes based on the
5406 assumption that signed overflow does not occur.  Note that it does not
5407 warn about all cases where the code might overflow: it only warns
5408 about cases where the compiler implements some optimization.  Thus
5409 this warning depends on the optimization level.
5411 An optimization that assumes that signed overflow does not occur is
5412 perfectly safe if the values of the variables involved are such that
5413 overflow never does, in fact, occur.  Therefore this warning can
5414 easily give a false positive: a warning about code that is not
5415 actually a problem.  To help focus on important issues, several
5416 warning levels are defined.  No warnings are issued for the use of
5417 undefined signed overflow when estimating how many iterations a loop
5418 requires, in particular when determining whether a loop will be
5419 executed at all.
5421 @table @gcctabopt
5422 @item -Wstrict-overflow=1
5423 Warn about cases that are both questionable and easy to avoid.  For
5424 example the compiler simplifies
5425 @code{x + 1 > x} to @code{1}.  This level of
5426 @option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
5427 are not, and must be explicitly requested.
5429 @item -Wstrict-overflow=2
5430 Also warn about other cases where a comparison is simplified to a
5431 constant.  For example: @code{abs (x) >= 0}.  This can only be
5432 simplified when signed integer overflow is undefined, because
5433 @code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
5434 zero.  @option{-Wstrict-overflow} (with no level) is the same as
5435 @option{-Wstrict-overflow=2}.
5437 @item -Wstrict-overflow=3
5438 Also warn about other cases where a comparison is simplified.  For
5439 example: @code{x + 1 > 1} is simplified to @code{x > 0}.
5441 @item -Wstrict-overflow=4
5442 Also warn about other simplifications not covered by the above cases.
5443 For example: @code{(x * 10) / 5} is simplified to @code{x * 2}.
5445 @item -Wstrict-overflow=5
5446 Also warn about cases where the compiler reduces the magnitude of a
5447 constant involved in a comparison.  For example: @code{x + 2 > y} is
5448 simplified to @code{x + 1 >= y}.  This is reported only at the
5449 highest warning level because this simplification applies to many
5450 comparisons, so this warning level gives a very large number of
5451 false positives.
5452 @end table
5454 @item -Wstringop-overflow
5455 @itemx -Wstringop-overflow=@var{type}
5456 @opindex Wstringop-overflow
5457 @opindex Wno-stringop-overflow
5458 Warn for calls to string manipulation functions such as @code{memcpy} and
5459 @code{strcpy} that are determined to overflow the destination buffer.  The
5460 optional argument is one greater than the type of Object Size Checking to
5461 perform to determine the size of the destination.  @xref{Object Size Checking}.
5462 The argument is meaningful only for functions that operate on character arrays
5463 but not for raw memory functions like @code{memcpy} which always make use
5464 of Object Size type-0.  The option also warns for calls that specify a size
5465 in excess of the largest possible object or at most @code{SIZE_MAX / 2} bytes.
5466 The option produces the best results with optimization enabled but can detect
5467 a small subset of simple buffer overflows even without optimization in
5468 calls to the GCC built-in functions like @code{__builtin_memcpy} that
5469 correspond to the standard functions.  In any case, the option warns about
5470 just a subset of buffer overflows detected by the corresponding overflow
5471 checking built-ins.  For example, the option will issue a warning for
5472 the @code{strcpy} call below because it copies at least 5 characters
5473 (the string @code{"blue"} including the terminating NUL) into the buffer
5474 of size 4.
5476 @smallexample
5477 enum Color @{ blue, purple, yellow @};
5478 const char* f (enum Color clr)
5480   static char buf [4];
5481   const char *str;
5482   switch (clr)
5483     @{
5484       case blue: str = "blue"; break;
5485       case purple: str = "purple"; break;
5486       case yellow: str = "yellow"; break;
5487     @}
5489   return strcpy (buf, str);   // warning here
5491 @end smallexample
5493 Option @option{-Wstringop-overflow=2} is enabled by default.
5495 @table @gcctabopt
5496 @item -Wstringop-overflow
5497 @itemx -Wstringop-overflow=1
5498 @opindex Wstringop-overflow
5499 @opindex Wno-stringop-overflow
5500 The @option{-Wstringop-overflow=1} option uses type-zero Object Size Checking
5501 to determine the sizes of destination objects.  This is the default setting
5502 of the option.  At this setting the option will not warn for writes past
5503 the end of subobjects of larger objects accessed by pointers unless the
5504 size of the largest surrounding object is known.  When the destination may
5505 be one of several objects it is assumed to be the largest one of them.  On
5506 Linux systems, when optimization is enabled at this setting the option warns
5507 for the same code as when the @code{_FORTIFY_SOURCE} macro is defined to
5508 a non-zero value.
5510 @item -Wstringop-overflow=2
5511 The @option{-Wstringop-overflow=2} option uses type-one Object Size Checking
5512 to determine the sizes of destination objects.  At this setting the option
5513 will warn about overflows when writing to members of the largest complete
5514 objects whose exact size is known.  It will, however, not warn for excessive
5515 writes to the same members of unknown objects referenced by pointers since
5516 they may point to arrays containing unknown numbers of elements.
5518 @item -Wstringop-overflow=3
5519 The @option{-Wstringop-overflow=3} option uses type-two Object Size Checking
5520 to determine the sizes of destination objects.  At this setting the option
5521 warns about overflowing the smallest object or data member.  This is the
5522 most restrictive setting of the option that may result in warnings for safe
5523 code.
5525 @item -Wstringop-overflow=4
5526 The @option{-Wstringop-overflow=4} option uses type-three Object Size Checking
5527 to determine the sizes of destination objects.  At this setting the option
5528 will warn about overflowing any data members, and when the destination is
5529 one of several objects it uses the size of the largest of them to decide
5530 whether to issue a warning.  Similarly to @option{-Wstringop-overflow=3} this
5531 setting of the option may result in warnings for benign code.
5532 @end table
5534 @item -Wstringop-truncation
5535 @opindex Wstringop-truncation
5536 @opindex Wno-stringop-truncation
5537 Warn for calls to bounded string manipulation functions such as @code{strncat},
5538 @code{strncpy}, and @code{stpncpy} that may either truncate the copied string
5539 or leave the destination unchanged.
5541 In the following example, the call to @code{strncat} specifies a bound that
5542 is less than the length of the source string.  As a result, the copy of
5543 the source will be truncated and so the call is diagnosed.  To avoid the
5544 warning use @code{bufsize - strlen (buf) - 1)} as the bound.
5546 @smallexample
5547 void append (char *buf, size_t bufsize)
5549   strncat (buf, ".txt", 3);
5551 @end smallexample
5553 As another example, the following call to @code{strncpy} results in copying
5554 to @code{d} just the characters preceding the terminating NUL, without
5555 appending the NUL to the end.  Assuming the result of @code{strncpy} is
5556 necessarily a NUL-terminated string is a common mistake, and so the call
5557 is diagnosed.  To avoid the warning when the result is not expected to be
5558 NUL-terminated, call @code{memcpy} instead.
5560 @smallexample
5561 void copy (char *d, const char *s)
5563   strncpy (d, s, strlen (s));
5565 @end smallexample
5567 In the following example, the call to @code{strncpy} specifies the size
5568 of the destination buffer as the bound.  If the length of the source
5569 string is equal to or greater than this size the result of the copy will
5570 not be NUL-terminated.  Therefore, the call is also diagnosed.  To avoid
5571 the warning, specify @code{sizeof buf - 1} as the bound and set the last
5572 element of the buffer to @code{NUL}.
5574 @smallexample
5575 void copy (const char *s)
5577   char buf[80];
5578   strncpy (buf, s, sizeof buf);
5579   @dots{}
5581 @end smallexample
5583 In situations where a character array is intended to store a sequence
5584 of bytes with no terminating @code{NUL} such an array may be annotated
5585 with attribute @code{nonstring} to avoid this warning.  Such arrays,
5586 however, are not suitable arguments to functions that expect
5587 @code{NUL}-terminated strings.  To help detect accidental misuses of
5588 such arrays GCC issues warnings unless it can prove that the use is
5589 safe.  @xref{Common Variable Attributes}.
5591 @item -Wsuggest-attribute=@r{[}pure@r{|}const@r{|}noreturn@r{|}format@r{|}cold@r{|}malloc@r{]}
5592 @opindex Wsuggest-attribute=
5593 @opindex Wno-suggest-attribute=
5594 Warn for cases where adding an attribute may be beneficial. The
5595 attributes currently supported are listed below.
5597 @table @gcctabopt
5598 @item -Wsuggest-attribute=pure
5599 @itemx -Wsuggest-attribute=const
5600 @itemx -Wsuggest-attribute=noreturn
5601 @itemx -Wsuggest-attribute=malloc
5602 @opindex Wsuggest-attribute=pure
5603 @opindex Wno-suggest-attribute=pure
5604 @opindex Wsuggest-attribute=const
5605 @opindex Wno-suggest-attribute=const
5606 @opindex Wsuggest-attribute=noreturn
5607 @opindex Wno-suggest-attribute=noreturn
5608 @opindex Wsuggest-attribute=malloc
5609 @opindex Wno-suggest-attribute=malloc
5611 Warn about functions that might be candidates for attributes
5612 @code{pure}, @code{const} or @code{noreturn} or @code{malloc}. The compiler
5613 only warns for functions visible in other compilation units or (in the case of
5614 @code{pure} and @code{const}) if it cannot prove that the function returns
5615 normally. A function returns normally if it doesn't contain an infinite loop or
5616 return abnormally by throwing, calling @code{abort} or trapping.  This analysis
5617 requires option @option{-fipa-pure-const}, which is enabled by default at
5618 @option{-O} and higher.  Higher optimization levels improve the accuracy
5619 of the analysis.
5621 @item -Wsuggest-attribute=format
5622 @itemx -Wmissing-format-attribute
5623 @opindex Wsuggest-attribute=format
5624 @opindex Wmissing-format-attribute
5625 @opindex Wno-suggest-attribute=format
5626 @opindex Wno-missing-format-attribute
5627 @opindex Wformat
5628 @opindex Wno-format
5630 Warn about function pointers that might be candidates for @code{format}
5631 attributes.  Note these are only possible candidates, not absolute ones.
5632 GCC guesses that function pointers with @code{format} attributes that
5633 are used in assignment, initialization, parameter passing or return
5634 statements should have a corresponding @code{format} attribute in the
5635 resulting type.  I.e.@: the left-hand side of the assignment or
5636 initialization, the type of the parameter variable, or the return type
5637 of the containing function respectively should also have a @code{format}
5638 attribute to avoid the warning.
5640 GCC also warns about function definitions that might be
5641 candidates for @code{format} attributes.  Again, these are only
5642 possible candidates.  GCC guesses that @code{format} attributes
5643 might be appropriate for any function that calls a function like
5644 @code{vprintf} or @code{vscanf}, but this might not always be the
5645 case, and some functions for which @code{format} attributes are
5646 appropriate may not be detected.
5648 @item -Wsuggest-attribute=cold
5649 @opindex Wsuggest-attribute=cold
5650 @opindex Wno-suggest-attribute=cold
5652 Warn about functions that might be candidates for @code{cold} attribute.  This
5653 is based on static detection and generally will only warn about functions which
5654 always leads to a call to another @code{cold} function such as wrappers of
5655 C++ @code{throw} or fatal error reporting functions leading to @code{abort}.
5656 @end table
5658 @item -Wsuggest-final-types
5659 @opindex Wno-suggest-final-types
5660 @opindex Wsuggest-final-types
5661 Warn about types with virtual methods where code quality would be improved
5662 if the type were declared with the C++11 @code{final} specifier, 
5663 or, if possible,
5664 declared in an anonymous namespace. This allows GCC to more aggressively
5665 devirtualize the polymorphic calls. This warning is more effective with link
5666 time optimization, where the information about the class hierarchy graph is
5667 more complete.
5669 @item -Wsuggest-final-methods
5670 @opindex Wno-suggest-final-methods
5671 @opindex Wsuggest-final-methods
5672 Warn about virtual methods where code quality would be improved if the method
5673 were declared with the C++11 @code{final} specifier, 
5674 or, if possible, its type were
5675 declared in an anonymous namespace or with the @code{final} specifier.
5676 This warning is
5677 more effective with link-time optimization, where the information about the
5678 class hierarchy graph is more complete. It is recommended to first consider
5679 suggestions of @option{-Wsuggest-final-types} and then rebuild with new
5680 annotations.
5682 @item -Wsuggest-override
5683 Warn about overriding virtual functions that are not marked with the override
5684 keyword.
5686 @item -Walloc-zero
5687 @opindex Wno-alloc-zero
5688 @opindex Walloc-zero
5689 Warn about calls to allocation functions decorated with attribute
5690 @code{alloc_size} that specify zero bytes, including those to the built-in
5691 forms of the functions @code{aligned_alloc}, @code{alloca}, @code{calloc},
5692 @code{malloc}, and @code{realloc}.  Because the behavior of these functions
5693 when called with a zero size differs among implementations (and in the case
5694 of @code{realloc} has been deprecated) relying on it may result in subtle
5695 portability bugs and should be avoided.
5697 @item -Walloc-size-larger-than=@var{byte-size}
5698 @opindex Walloc-size-larger-than=
5699 @opindex Wno-alloc-size-larger-than
5700 Warn about calls to functions decorated with attribute @code{alloc_size}
5701 that attempt to allocate objects larger than the specified number of bytes,
5702 or where the result of the size computation in an integer type with infinite
5703 precision would exceed the value of @samp{PTRDIFF_MAX} on the target.
5704 @option{-Walloc-size-larger-than=}@samp{PTRDIFF_MAX} is enabled by default.
5705 Warnings controlled by the option can be disabled either by specifying
5706 @var{byte-size} of @samp{SIZE_MAX} or more or by
5707 @option{-Wno-alloc-size-larger-than}.
5708 @xref{Function Attributes}.
5710 @item -Wno-alloc-size-larger-than
5711 @opindex Wno-alloc-size-larger-than
5712 Disable @option{-Walloc-size-larger-than=} warnings.  The option is
5713 equivalent to @option{-Walloc-size-larger-than=}@samp{SIZE_MAX} or
5714 larger.
5716 @item -Walloca
5717 @opindex Wno-alloca
5718 @opindex Walloca
5719 This option warns on all uses of @code{alloca} in the source.
5721 @item -Walloca-larger-than=@var{byte-size}
5722 @opindex -Walloca-larger-than=
5723 @opindex -Wno-alloca-larger-than
5724 This option warns on calls to @code{alloca} with an integer argument whose
5725 value is either zero, or that is not bounded by a controlling predicate
5726 that limits its value to at most @var{byte-size}.  It also warns for calls
5727 to @code{alloca} where the bound value is unknown.  Arguments of non-integer
5728 types are considered unbounded even if they appear to be constrained to
5729 the expected range.
5731 For example, a bounded case of @code{alloca} could be:
5733 @smallexample
5734 void func (size_t n)
5736   void *p;
5737   if (n <= 1000)
5738     p = alloca (n);
5739   else
5740     p = malloc (n);
5741   f (p);
5743 @end smallexample
5745 In the above example, passing @code{-Walloca-larger-than=1000} would not
5746 issue a warning because the call to @code{alloca} is known to be at most
5747 1000 bytes.  However, if @code{-Walloca-larger-than=500} were passed,
5748 the compiler would emit a warning.
5750 Unbounded uses, on the other hand, are uses of @code{alloca} with no
5751 controlling predicate constraining its integer argument.  For example:
5753 @smallexample
5754 void func ()
5756   void *p = alloca (n);
5757   f (p);
5759 @end smallexample
5761 If @code{-Walloca-larger-than=500} were passed, the above would trigger
5762 a warning, but this time because of the lack of bounds checking.
5764 Note, that even seemingly correct code involving signed integers could
5765 cause a warning:
5767 @smallexample
5768 void func (signed int n)
5770   if (n < 500)
5771     @{
5772       p = alloca (n);
5773       f (p);
5774     @}
5776 @end smallexample
5778 In the above example, @var{n} could be negative, causing a larger than
5779 expected argument to be implicitly cast into the @code{alloca} call.
5781 This option also warns when @code{alloca} is used in a loop.
5783 @option{-Walloca-larger-than=}@samp{PTRDIFF_MAX} is enabled by default
5784 but is usually only effective  when @option{-ftree-vrp} is active (default
5785 for @option{-O2} and above).
5787 See also @option{-Wvla-larger-than=}@samp{byte-size}.
5789 @item -Wno-alloca-larger-than
5790 @opindex Wno-alloca-larger-than
5791 Disable @option{-Walloca-larger-than=} warnings.  The option is
5792 equivalent to @option{-Walloca-larger-than=}@samp{SIZE_MAX} or larger.
5794 @item -Warray-bounds
5795 @itemx -Warray-bounds=@var{n}
5796 @opindex Wno-array-bounds
5797 @opindex Warray-bounds
5798 This option is only active when @option{-ftree-vrp} is active
5799 (default for @option{-O2} and above). It warns about subscripts to arrays
5800 that are always out of bounds. This warning is enabled by @option{-Wall}.
5802 @table @gcctabopt
5803 @item -Warray-bounds=1
5804 This is the warning level of @option{-Warray-bounds} and is enabled
5805 by @option{-Wall}; higher levels are not, and must be explicitly requested.
5807 @item -Warray-bounds=2
5808 This warning level also warns about out of bounds access for
5809 arrays at the end of a struct and for arrays accessed through
5810 pointers. This warning level may give a larger number of
5811 false positives and is deactivated by default.
5812 @end table
5814 @item -Wattribute-alias
5815 Warn about declarations using the @code{alias} and similar attributes whose
5816 target is incompatible with the type of the alias.  @xref{Function Attributes,
5817 ,Declaring Attributes of Functions}.
5819 @item -Wbool-compare
5820 @opindex Wno-bool-compare
5821 @opindex Wbool-compare
5822 Warn about boolean expression compared with an integer value different from
5823 @code{true}/@code{false}.  For instance, the following comparison is
5824 always false:
5825 @smallexample
5826 int n = 5;
5827 @dots{}
5828 if ((n > 1) == 2) @{ @dots{} @}
5829 @end smallexample
5830 This warning is enabled by @option{-Wall}.
5832 @item -Wbool-operation
5833 @opindex Wno-bool-operation
5834 @opindex Wbool-operation
5835 Warn about suspicious operations on expressions of a boolean type.  For
5836 instance, bitwise negation of a boolean is very likely a bug in the program.
5837 For C, this warning also warns about incrementing or decrementing a boolean,
5838 which rarely makes sense.  (In C++, decrementing a boolean is always invalid.
5839 Incrementing a boolean is invalid in C++17, and deprecated otherwise.)
5841 This warning is enabled by @option{-Wall}.
5843 @item -Wduplicated-branches
5844 @opindex Wno-duplicated-branches
5845 @opindex Wduplicated-branches
5846 Warn when an if-else has identical branches.  This warning detects cases like
5847 @smallexample
5848 if (p != NULL)
5849   return 0;
5850 else
5851   return 0;
5852 @end smallexample
5853 It doesn't warn when both branches contain just a null statement.  This warning
5854 also warn for conditional operators:
5855 @smallexample
5856   int i = x ? *p : *p;
5857 @end smallexample
5859 @item -Wduplicated-cond
5860 @opindex Wno-duplicated-cond
5861 @opindex Wduplicated-cond
5862 Warn about duplicated conditions in an if-else-if chain.  For instance,
5863 warn for the following code:
5864 @smallexample
5865 if (p->q != NULL) @{ @dots{} @}
5866 else if (p->q != NULL) @{ @dots{} @}
5867 @end smallexample
5869 @item -Wframe-address
5870 @opindex Wno-frame-address
5871 @opindex Wframe-address
5872 Warn when the @samp{__builtin_frame_address} or @samp{__builtin_return_address}
5873 is called with an argument greater than 0.  Such calls may return indeterminate
5874 values or crash the program.  The warning is included in @option{-Wall}.
5876 @item -Wno-discarded-qualifiers @r{(C and Objective-C only)}
5877 @opindex Wno-discarded-qualifiers
5878 @opindex Wdiscarded-qualifiers
5879 Do not warn if type qualifiers on pointers are being discarded.
5880 Typically, the compiler warns if a @code{const char *} variable is
5881 passed to a function that takes a @code{char *} parameter.  This option
5882 can be used to suppress such a warning.
5884 @item -Wno-discarded-array-qualifiers @r{(C and Objective-C only)}
5885 @opindex Wno-discarded-array-qualifiers
5886 @opindex Wdiscarded-array-qualifiers
5887 Do not warn if type qualifiers on arrays which are pointer targets
5888 are being discarded. Typically, the compiler warns if a
5889 @code{const int (*)[]} variable is passed to a function that
5890 takes a @code{int (*)[]} parameter.  This option can be used to
5891 suppress such a warning.
5893 @item -Wno-incompatible-pointer-types @r{(C and Objective-C only)}
5894 @opindex Wno-incompatible-pointer-types
5895 @opindex Wincompatible-pointer-types
5896 Do not warn when there is a conversion between pointers that have incompatible
5897 types.  This warning is for cases not covered by @option{-Wno-pointer-sign},
5898 which warns for pointer argument passing or assignment with different
5899 signedness.
5901 @item -Wno-int-conversion @r{(C and Objective-C only)}
5902 @opindex Wno-int-conversion
5903 @opindex Wint-conversion
5904 Do not warn about incompatible integer to pointer and pointer to integer
5905 conversions.  This warning is about implicit conversions; for explicit
5906 conversions the warnings @option{-Wno-int-to-pointer-cast} and
5907 @option{-Wno-pointer-to-int-cast} may be used.
5909 @item -Wno-div-by-zero
5910 @opindex Wno-div-by-zero
5911 @opindex Wdiv-by-zero
5912 Do not warn about compile-time integer division by zero.  Floating-point
5913 division by zero is not warned about, as it can be a legitimate way of
5914 obtaining infinities and NaNs.
5916 @item -Wsystem-headers
5917 @opindex Wsystem-headers
5918 @opindex Wno-system-headers
5919 @cindex warnings from system headers
5920 @cindex system headers, warnings from
5921 Print warning messages for constructs found in system header files.
5922 Warnings from system headers are normally suppressed, on the assumption
5923 that they usually do not indicate real problems and would only make the
5924 compiler output harder to read.  Using this command-line option tells
5925 GCC to emit warnings from system headers as if they occurred in user
5926 code.  However, note that using @option{-Wall} in conjunction with this
5927 option does @emph{not} warn about unknown pragmas in system
5928 headers---for that, @option{-Wunknown-pragmas} must also be used.
5930 @item -Wtautological-compare
5931 @opindex Wtautological-compare
5932 @opindex Wno-tautological-compare
5933 Warn if a self-comparison always evaluates to true or false.  This
5934 warning detects various mistakes such as:
5935 @smallexample
5936 int i = 1;
5937 @dots{}
5938 if (i > i) @{ @dots{} @}
5939 @end smallexample
5941 This warning also warns about bitwise comparisons that always evaluate
5942 to true or false, for instance:
5943 @smallexample
5944 if ((a & 16) == 10) @{ @dots{} @}
5945 @end smallexample
5946 will always be false.
5948 This warning is enabled by @option{-Wall}.
5950 @item -Wtrampolines
5951 @opindex Wtrampolines
5952 @opindex Wno-trampolines
5953 Warn about trampolines generated for pointers to nested functions.
5954 A trampoline is a small piece of data or code that is created at run
5955 time on the stack when the address of a nested function is taken, and is
5956 used to call the nested function indirectly.  For some targets, it is
5957 made up of data only and thus requires no special treatment.  But, for
5958 most targets, it is made up of code and thus requires the stack to be
5959 made executable in order for the program to work properly.
5961 @item -Wfloat-equal
5962 @opindex Wfloat-equal
5963 @opindex Wno-float-equal
5964 Warn if floating-point values are used in equality comparisons.
5966 The idea behind this is that sometimes it is convenient (for the
5967 programmer) to consider floating-point values as approximations to
5968 infinitely precise real numbers.  If you are doing this, then you need
5969 to compute (by analyzing the code, or in some other way) the maximum or
5970 likely maximum error that the computation introduces, and allow for it
5971 when performing comparisons (and when producing output, but that's a
5972 different problem).  In particular, instead of testing for equality, you
5973 should check to see whether the two values have ranges that overlap; and
5974 this is done with the relational operators, so equality comparisons are
5975 probably mistaken.
5977 @item -Wtraditional @r{(C and Objective-C only)}
5978 @opindex Wtraditional
5979 @opindex Wno-traditional
5980 Warn about certain constructs that behave differently in traditional and
5981 ISO C@.  Also warn about ISO C constructs that have no traditional C
5982 equivalent, and/or problematic constructs that should be avoided.
5984 @itemize @bullet
5985 @item
5986 Macro parameters that appear within string literals in the macro body.
5987 In traditional C macro replacement takes place within string literals,
5988 but in ISO C it does not.
5990 @item
5991 In traditional C, some preprocessor directives did not exist.
5992 Traditional preprocessors only considered a line to be a directive
5993 if the @samp{#} appeared in column 1 on the line.  Therefore
5994 @option{-Wtraditional} warns about directives that traditional C
5995 understands but ignores because the @samp{#} does not appear as the
5996 first character on the line.  It also suggests you hide directives like
5997 @code{#pragma} not understood by traditional C by indenting them.  Some
5998 traditional implementations do not recognize @code{#elif}, so this option
5999 suggests avoiding it altogether.
6001 @item
6002 A function-like macro that appears without arguments.
6004 @item
6005 The unary plus operator.
6007 @item
6008 The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating-point
6009 constant suffixes.  (Traditional C does support the @samp{L} suffix on integer
6010 constants.)  Note, these suffixes appear in macros defined in the system
6011 headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
6012 Use of these macros in user code might normally lead to spurious
6013 warnings, however GCC's integrated preprocessor has enough context to
6014 avoid warning in these cases.
6016 @item
6017 A function declared external in one block and then used after the end of
6018 the block.
6020 @item
6021 A @code{switch} statement has an operand of type @code{long}.
6023 @item
6024 A non-@code{static} function declaration follows a @code{static} one.
6025 This construct is not accepted by some traditional C compilers.
6027 @item
6028 The ISO type of an integer constant has a different width or
6029 signedness from its traditional type.  This warning is only issued if
6030 the base of the constant is ten.  I.e.@: hexadecimal or octal values, which
6031 typically represent bit patterns, are not warned about.
6033 @item
6034 Usage of ISO string concatenation is detected.
6036 @item
6037 Initialization of automatic aggregates.
6039 @item
6040 Identifier conflicts with labels.  Traditional C lacks a separate
6041 namespace for labels.
6043 @item
6044 Initialization of unions.  If the initializer is zero, the warning is
6045 omitted.  This is done under the assumption that the zero initializer in
6046 user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
6047 initializer warnings and relies on default initialization to zero in the
6048 traditional C case.
6050 @item
6051 Conversions by prototypes between fixed/floating-point values and vice
6052 versa.  The absence of these prototypes when compiling with traditional
6053 C causes serious problems.  This is a subset of the possible
6054 conversion warnings; for the full set use @option{-Wtraditional-conversion}.
6056 @item
6057 Use of ISO C style function definitions.  This warning intentionally is
6058 @emph{not} issued for prototype declarations or variadic functions
6059 because these ISO C features appear in your code when using
6060 libiberty's traditional C compatibility macros, @code{PARAMS} and
6061 @code{VPARAMS}.  This warning is also bypassed for nested functions
6062 because that feature is already a GCC extension and thus not relevant to
6063 traditional C compatibility.
6064 @end itemize
6066 @item -Wtraditional-conversion @r{(C and Objective-C only)}
6067 @opindex Wtraditional-conversion
6068 @opindex Wno-traditional-conversion
6069 Warn if a prototype causes a type conversion that is different from what
6070 would happen to the same argument in the absence of a prototype.  This
6071 includes conversions of fixed point to floating and vice versa, and
6072 conversions changing the width or signedness of a fixed-point argument
6073 except when the same as the default promotion.
6075 @item -Wdeclaration-after-statement @r{(C and Objective-C only)}
6076 @opindex Wdeclaration-after-statement
6077 @opindex Wno-declaration-after-statement
6078 Warn when a declaration is found after a statement in a block.  This
6079 construct, known from C++, was introduced with ISO C99 and is by default
6080 allowed in GCC@.  It is not supported by ISO C90.  @xref{Mixed Declarations}.
6082 @item -Wshadow
6083 @opindex Wshadow
6084 @opindex Wno-shadow
6085 Warn whenever a local variable or type declaration shadows another
6086 variable, parameter, type, class member (in C++), or instance variable
6087 (in Objective-C) or whenever a built-in function is shadowed. Note
6088 that in C++, the compiler warns if a local variable shadows an
6089 explicit typedef, but not if it shadows a struct/class/enum.
6090 Same as @option{-Wshadow=global}.
6092 @item -Wno-shadow-ivar @r{(Objective-C only)}
6093 @opindex Wno-shadow-ivar
6094 @opindex Wshadow-ivar
6095 Do not warn whenever a local variable shadows an instance variable in an
6096 Objective-C method.
6098 @item -Wshadow=global
6099 @opindex Wshadow=local
6100 The default for @option{-Wshadow}. Warns for any (global) shadowing.
6102 @item -Wshadow=local
6103 @opindex Wshadow=local
6104 Warn when a local variable shadows another local variable or parameter.
6105 This warning is enabled by @option{-Wshadow=global}.
6107 @item -Wshadow=compatible-local
6108 @opindex Wshadow=compatible-local
6109 Warn when a local variable shadows another local variable or parameter
6110 whose type is compatible with that of the shadowing variable. In C++,
6111 type compatibility here means the type of the shadowing variable can be
6112 converted to that of the shadowed variable. The creation of this flag
6113 (in addition to @option{-Wshadow=local}) is based on the idea that when
6114 a local variable shadows another one of incompatible type, it is most
6115 likely intentional, not a bug or typo, as shown in the following example:
6117 @smallexample
6118 @group
6119 for (SomeIterator i = SomeObj.begin(); i != SomeObj.end(); ++i)
6121   for (int i = 0; i < N; ++i)
6122   @{
6123     ...
6124   @}
6125   ...
6127 @end group
6128 @end smallexample
6130 Since the two variable @code{i} in the example above have incompatible types,
6131 enabling only @option{-Wshadow=compatible-local} will not emit a warning.
6132 Because their types are incompatible, if a programmer accidentally uses one
6133 in place of the other, type checking will catch that and emit an error or
6134 warning. So not warning (about shadowing) in this case will not lead to
6135 undetected bugs. Use of this flag instead of @option{-Wshadow=local} can
6136 possibly reduce the number of warnings triggered by intentional shadowing.
6138 This warning is enabled by @option{-Wshadow=local}.
6140 @item -Wlarger-than=@var{byte-size}
6141 @opindex Wlarger-than=
6142 @opindex Wlarger-than-@var{byte-size}
6143 Warn whenever an object is defined whose size exceeds @var{byte-size}.
6144 @option{-Wlarger-than=}@samp{PTRDIFF_MAX} is enabled by default.
6145 Warnings controlled by the option can be disabled either by specifying
6146 @var{byte-size} of @samp{SIZE_MAX} or more or by
6147 @option{-Wno-larger-than}.
6149 @item -Wno-larger-than
6150 @opindex Wno-larger-than
6151 Disable @option{-Wlarger-than=} warnings.  The option is equivalent
6152 to @option{-Wlarger-than=}@samp{SIZE_MAX} or larger.
6154 @item -Wframe-larger-than=@var{byte-size}
6155 @opindex Wframe-larger-than=
6156 @opindex Wno-frame-larger-than
6157 Warn if the size of a function frame exceeds @var{byte-size}.
6158 The computation done to determine the stack frame size is approximate
6159 and not conservative.
6160 The actual requirements may be somewhat greater than @var{byte-size}
6161 even if you do not get a warning.  In addition, any space allocated
6162 via @code{alloca}, variable-length arrays, or related constructs
6163 is not included by the compiler when determining
6164 whether or not to issue a warning.
6165 @option{-Wframe-larger-than=}@samp{PTRDIFF_MAX} is enabled by default.
6166 Warnings controlled by the option can be disabled either by specifying
6167 @var{byte-size} of @samp{SIZE_MAX} or more or by
6168 @option{-Wno-frame-larger-than}.
6170 @item -Wno-frame-larger-than
6171 @opindex Wno-frame-larger-than
6172 Disable @option{-Wframe-larger-than=} warnings.  The option is equivalent
6173 to @option{-Wframe-larger-than=}@samp{SIZE_MAX} or larger.
6175 @item -Wno-free-nonheap-object
6176 @opindex Wno-free-nonheap-object
6177 @opindex Wfree-nonheap-object
6178 Do not warn when attempting to free an object that was not allocated
6179 on the heap.
6181 @item -Wstack-usage=@var{byte-size}
6182 @opindex Wstack-usage
6183 @opindex Wno-stack-usage
6184 Warn if the stack usage of a function might exceed @var{byte-size}.
6185 The computation done to determine the stack usage is conservative.
6186 Any space allocated via @code{alloca}, variable-length arrays, or related
6187 constructs is included by the compiler when determining whether or not to
6188 issue a warning.
6190 The message is in keeping with the output of @option{-fstack-usage}.
6192 @itemize
6193 @item
6194 If the stack usage is fully static but exceeds the specified amount, it's:
6196 @smallexample
6197   warning: stack usage is 1120 bytes
6198 @end smallexample
6199 @item
6200 If the stack usage is (partly) dynamic but bounded, it's:
6202 @smallexample
6203   warning: stack usage might be 1648 bytes
6204 @end smallexample
6205 @item
6206 If the stack usage is (partly) dynamic and not bounded, it's:
6208 @smallexample
6209   warning: stack usage might be unbounded
6210 @end smallexample
6211 @end itemize
6213 @option{-Wstack-usage=}@samp{PTRDIFF_MAX} is enabled by default.
6214 Warnings controlled by the option can be disabled either by specifying
6215 @var{byte-size} of @samp{SIZE_MAX} or more or by
6216 @option{-Wno-stack-usage}.
6218 @item -Wno-stack-usage
6219 @opindex Wno-stack-usage
6220 Disable @option{-Wstack-usage=} warnings.  The option is equivalent
6221 to @option{-Wstack-usage=}@samp{SIZE_MAX} or larger.
6223 @item -Wunsafe-loop-optimizations
6224 @opindex Wunsafe-loop-optimizations
6225 @opindex Wno-unsafe-loop-optimizations
6226 Warn if the loop cannot be optimized because the compiler cannot
6227 assume anything on the bounds of the loop indices.  With
6228 @option{-funsafe-loop-optimizations} warn if the compiler makes
6229 such assumptions.
6231 @item -Wno-pedantic-ms-format @r{(MinGW targets only)}
6232 @opindex Wno-pedantic-ms-format
6233 @opindex Wpedantic-ms-format
6234 When used in combination with @option{-Wformat}
6235 and @option{-pedantic} without GNU extensions, this option
6236 disables the warnings about non-ISO @code{printf} / @code{scanf} format
6237 width specifiers @code{I32}, @code{I64}, and @code{I} used on Windows targets,
6238 which depend on the MS runtime.
6240 @item -Waligned-new
6241 @opindex Waligned-new
6242 @opindex Wno-aligned-new
6243 Warn about a new-expression of a type that requires greater alignment
6244 than the @code{alignof(std::max_align_t)} but uses an allocation
6245 function without an explicit alignment parameter. This option is
6246 enabled by @option{-Wall}.
6248 Normally this only warns about global allocation functions, but
6249 @option{-Waligned-new=all} also warns about class member allocation
6250 functions.
6252 @item -Wplacement-new
6253 @itemx -Wplacement-new=@var{n}
6254 @opindex Wplacement-new
6255 @opindex Wno-placement-new
6256 Warn about placement new expressions with undefined behavior, such as
6257 constructing an object in a buffer that is smaller than the type of
6258 the object.  For example, the placement new expression below is diagnosed
6259 because it attempts to construct an array of 64 integers in a buffer only
6260 64 bytes large.
6261 @smallexample
6262 char buf [64];
6263 new (buf) int[64];
6264 @end smallexample
6265 This warning is enabled by default.
6267 @table @gcctabopt
6268 @item -Wplacement-new=1
6269 This is the default warning level of @option{-Wplacement-new}.  At this
6270 level the warning is not issued for some strictly undefined constructs that
6271 GCC allows as extensions for compatibility with legacy code.  For example,
6272 the following @code{new} expression is not diagnosed at this level even
6273 though it has undefined behavior according to the C++ standard because
6274 it writes past the end of the one-element array.
6275 @smallexample
6276 struct S @{ int n, a[1]; @};
6277 S *s = (S *)malloc (sizeof *s + 31 * sizeof s->a[0]);
6278 new (s->a)int [32]();
6279 @end smallexample
6281 @item -Wplacement-new=2
6282 At this level, in addition to diagnosing all the same constructs as at level
6283 1, a diagnostic is also issued for placement new expressions that construct
6284 an object in the last member of structure whose type is an array of a single
6285 element and whose size is less than the size of the object being constructed.
6286 While the previous example would be diagnosed, the following construct makes
6287 use of the flexible member array extension to avoid the warning at level 2.
6288 @smallexample
6289 struct S @{ int n, a[]; @};
6290 S *s = (S *)malloc (sizeof *s + 32 * sizeof s->a[0]);
6291 new (s->a)int [32]();
6292 @end smallexample
6294 @end table
6296 @item -Wpointer-arith
6297 @opindex Wpointer-arith
6298 @opindex Wno-pointer-arith
6299 Warn about anything that depends on the ``size of'' a function type or
6300 of @code{void}.  GNU C assigns these types a size of 1, for
6301 convenience in calculations with @code{void *} pointers and pointers
6302 to functions.  In C++, warn also when an arithmetic operation involves
6303 @code{NULL}.  This warning is also enabled by @option{-Wpedantic}.
6305 @item -Wpointer-compare
6306 @opindex Wpointer-compare
6307 @opindex Wno-pointer-compare
6308 Warn if a pointer is compared with a zero character constant.  This usually
6309 means that the pointer was meant to be dereferenced.  For example:
6311 @smallexample
6312 const char *p = foo ();
6313 if (p == '\0')
6314   return 42;
6315 @end smallexample
6317 Note that the code above is invalid in C++11.
6319 This warning is enabled by default.
6321 @item -Wtype-limits
6322 @opindex Wtype-limits
6323 @opindex Wno-type-limits
6324 Warn if a comparison is always true or always false due to the limited
6325 range of the data type, but do not warn for constant expressions.  For
6326 example, warn if an unsigned variable is compared against zero with
6327 @code{<} or @code{>=}.  This warning is also enabled by
6328 @option{-Wextra}.
6330 @item -Wabsolute-value @r{(C and Objective-C only)}
6331 @opindex Wabsolute-value
6332 @opindex Wno-absolute-value
6333 Warn when a wrong absolute value function seems to be used or when it
6334 does not have any effect because its argument is an unsigned type.
6335 This warning be suppressed with an explicit type cast and it is also
6336 enabled by @option{-Wextra}.
6338 @include cppwarnopts.texi
6340 @item -Wbad-function-cast @r{(C and Objective-C only)}
6341 @opindex Wbad-function-cast
6342 @opindex Wno-bad-function-cast
6343 Warn when a function call is cast to a non-matching type.
6344 For example, warn if a call to a function returning an integer type 
6345 is cast to a pointer type.
6347 @item -Wc90-c99-compat @r{(C and Objective-C only)}
6348 @opindex Wc90-c99-compat
6349 @opindex Wno-c90-c99-compat
6350 Warn about features not present in ISO C90, but present in ISO C99.
6351 For instance, warn about use of variable length arrays, @code{long long}
6352 type, @code{bool} type, compound literals, designated initializers, and so
6353 on.  This option is independent of the standards mode.  Warnings are disabled
6354 in the expression that follows @code{__extension__}.
6356 @item -Wc99-c11-compat @r{(C and Objective-C only)}
6357 @opindex Wc99-c11-compat
6358 @opindex Wno-c99-c11-compat
6359 Warn about features not present in ISO C99, but present in ISO C11.
6360 For instance, warn about use of anonymous structures and unions,
6361 @code{_Atomic} type qualifier, @code{_Thread_local} storage-class specifier,
6362 @code{_Alignas} specifier, @code{Alignof} operator, @code{_Generic} keyword,
6363 and so on.  This option is independent of the standards mode.  Warnings are
6364 disabled in the expression that follows @code{__extension__}.
6366 @item -Wc++-compat @r{(C and Objective-C only)}
6367 @opindex Wc++-compat
6368 @opindex Wno-c++-compat
6369 Warn about ISO C constructs that are outside of the common subset of
6370 ISO C and ISO C++, e.g.@: request for implicit conversion from
6371 @code{void *} to a pointer to non-@code{void} type.
6373 @item -Wc++11-compat @r{(C++ and Objective-C++ only)}
6374 @opindex Wc++11-compat
6375 @opindex Wno-c++11-compat
6376 Warn about C++ constructs whose meaning differs between ISO C++ 1998
6377 and ISO C++ 2011, e.g., identifiers in ISO C++ 1998 that are keywords
6378 in ISO C++ 2011.  This warning turns on @option{-Wnarrowing} and is
6379 enabled by @option{-Wall}.
6381 @item -Wc++14-compat @r{(C++ and Objective-C++ only)}
6382 @opindex Wc++14-compat
6383 @opindex Wno-c++14-compat
6384 Warn about C++ constructs whose meaning differs between ISO C++ 2011
6385 and ISO C++ 2014.  This warning is enabled by @option{-Wall}.
6387 @item -Wc++17-compat @r{(C++ and Objective-C++ only)}
6388 @opindex Wc++17-compat
6389 @opindex Wno-c++17-compat
6390 Warn about C++ constructs whose meaning differs between ISO C++ 2014
6391 and ISO C++ 2017.  This warning is enabled by @option{-Wall}.
6393 @item -Wcast-qual
6394 @opindex Wcast-qual
6395 @opindex Wno-cast-qual
6396 Warn whenever a pointer is cast so as to remove a type qualifier from
6397 the target type.  For example, warn if a @code{const char *} is cast
6398 to an ordinary @code{char *}.
6400 Also warn when making a cast that introduces a type qualifier in an
6401 unsafe way.  For example, casting @code{char **} to @code{const char **}
6402 is unsafe, as in this example:
6404 @smallexample
6405   /* p is char ** value.  */
6406   const char **q = (const char **) p;
6407   /* Assignment of readonly string to const char * is OK.  */
6408   *q = "string";
6409   /* Now char** pointer points to read-only memory.  */
6410   **p = 'b';
6411 @end smallexample
6413 @item -Wcast-align
6414 @opindex Wcast-align
6415 @opindex Wno-cast-align
6416 Warn whenever a pointer is cast such that the required alignment of the
6417 target is increased.  For example, warn if a @code{char *} is cast to
6418 an @code{int *} on machines where integers can only be accessed at
6419 two- or four-byte boundaries.
6421 @item -Wcast-align=strict
6422 @opindex Wcast-align=strict
6423 Warn whenever a pointer is cast such that the required alignment of the
6424 target is increased.  For example, warn if a @code{char *} is cast to
6425 an @code{int *} regardless of the target machine.
6427 @item -Wcast-function-type
6428 @opindex Wcast-function-type
6429 @opindex Wno-cast-function-type
6430 Warn when a function pointer is cast to an incompatible function pointer.
6431 In a cast involving function types with a variable argument list only
6432 the types of initial arguments that are provided are considered.
6433 Any parameter of pointer-type matches any other pointer-type.  Any benign
6434 differences in integral types are ignored, like @code{int} vs. @code{long}
6435 on ILP32 targets.  Likewise type qualifiers are ignored.  The function
6436 type @code{void (*) (void)} is special and matches everything, which can
6437 be used to suppress this warning.
6438 In a cast involving pointer to member types this warning warns whenever
6439 the type cast is changing the pointer to member type.
6440 This warning is enabled by @option{-Wextra}.
6442 @item -Wwrite-strings
6443 @opindex Wwrite-strings
6444 @opindex Wno-write-strings
6445 When compiling C, give string constants the type @code{const
6446 char[@var{length}]} so that copying the address of one into a
6447 non-@code{const} @code{char *} pointer produces a warning.  These
6448 warnings help you find at compile time code that can try to write
6449 into a string constant, but only if you have been very careful about
6450 using @code{const} in declarations and prototypes.  Otherwise, it is
6451 just a nuisance. This is why we did not make @option{-Wall} request
6452 these warnings.
6454 When compiling C++, warn about the deprecated conversion from string
6455 literals to @code{char *}.  This warning is enabled by default for C++
6456 programs.
6458 @item -Wcatch-value
6459 @itemx -Wcatch-value=@var{n} @r{(C++ and Objective-C++ only)}
6460 @opindex Wcatch-value
6461 @opindex Wno-catch-value
6462 Warn about catch handlers that do not catch via reference.
6463 With @option{-Wcatch-value=1} (or @option{-Wcatch-value} for short)
6464 warn about polymorphic class types that are caught by value.
6465 With @option{-Wcatch-value=2} warn about all class types that are caught
6466 by value. With @option{-Wcatch-value=3} warn about all types that are
6467 not caught by reference. @option{-Wcatch-value} is enabled by @option{-Wall}.
6469 @item -Wclobbered
6470 @opindex Wclobbered
6471 @opindex Wno-clobbered
6472 Warn for variables that might be changed by @code{longjmp} or
6473 @code{vfork}.  This warning is also enabled by @option{-Wextra}.
6475 @item -Wconditionally-supported @r{(C++ and Objective-C++ only)}
6476 @opindex Wconditionally-supported
6477 @opindex Wno-conditionally-supported
6478 Warn for conditionally-supported (C++11 [intro.defs]) constructs.
6480 @item -Wconversion
6481 @opindex Wconversion
6482 @opindex Wno-conversion
6483 Warn for implicit conversions that may alter a value. This includes
6484 conversions between real and integer, like @code{abs (x)} when
6485 @code{x} is @code{double}; conversions between signed and unsigned,
6486 like @code{unsigned ui = -1}; and conversions to smaller types, like
6487 @code{sqrtf (M_PI)}. Do not warn for explicit casts like @code{abs
6488 ((int) x)} and @code{ui = (unsigned) -1}, or if the value is not
6489 changed by the conversion like in @code{abs (2.0)}.  Warnings about
6490 conversions between signed and unsigned integers can be disabled by
6491 using @option{-Wno-sign-conversion}.
6493 For C++, also warn for confusing overload resolution for user-defined
6494 conversions; and conversions that never use a type conversion
6495 operator: conversions to @code{void}, the same type, a base class or a
6496 reference to them. Warnings about conversions between signed and
6497 unsigned integers are disabled by default in C++ unless
6498 @option{-Wsign-conversion} is explicitly enabled.
6500 @item -Wno-conversion-null @r{(C++ and Objective-C++ only)}
6501 @opindex Wconversion-null
6502 @opindex Wno-conversion-null
6503 Do not warn for conversions between @code{NULL} and non-pointer
6504 types. @option{-Wconversion-null} is enabled by default.
6506 @item -Wzero-as-null-pointer-constant @r{(C++ and Objective-C++ only)}
6507 @opindex Wzero-as-null-pointer-constant
6508 @opindex Wno-zero-as-null-pointer-constant
6509 Warn when a literal @samp{0} is used as null pointer constant.  This can
6510 be useful to facilitate the conversion to @code{nullptr} in C++11.
6512 @item -Wsubobject-linkage @r{(C++ and Objective-C++ only)}
6513 @opindex Wsubobject-linkage
6514 @opindex Wno-subobject-linkage
6515 Warn if a class type has a base or a field whose type uses the anonymous
6516 namespace or depends on a type with no linkage.  If a type A depends on
6517 a type B with no or internal linkage, defining it in multiple
6518 translation units would be an ODR violation because the meaning of B
6519 is different in each translation unit.  If A only appears in a single
6520 translation unit, the best way to silence the warning is to give it
6521 internal linkage by putting it in an anonymous namespace as well.  The
6522 compiler doesn't give this warning for types defined in the main .C
6523 file, as those are unlikely to have multiple definitions.
6524 @option{-Wsubobject-linkage} is enabled by default.
6526 @item -Wdangling-else
6527 @opindex Wdangling-else
6528 @opindex Wno-dangling-else
6529 Warn about constructions where there may be confusion to which
6530 @code{if} statement an @code{else} branch belongs.  Here is an example of
6531 such a case:
6533 @smallexample
6534 @group
6536   if (a)
6537     if (b)
6538       foo ();
6539   else
6540     bar ();
6542 @end group
6543 @end smallexample
6545 In C/C++, every @code{else} branch belongs to the innermost possible
6546 @code{if} statement, which in this example is @code{if (b)}.  This is
6547 often not what the programmer expected, as illustrated in the above
6548 example by indentation the programmer chose.  When there is the
6549 potential for this confusion, GCC issues a warning when this flag
6550 is specified.  To eliminate the warning, add explicit braces around
6551 the innermost @code{if} statement so there is no way the @code{else}
6552 can belong to the enclosing @code{if}.  The resulting code
6553 looks like this:
6555 @smallexample
6556 @group
6558   if (a)
6559     @{
6560       if (b)
6561         foo ();
6562       else
6563         bar ();
6564     @}
6566 @end group
6567 @end smallexample
6569 This warning is enabled by @option{-Wparentheses}.
6571 @item -Wdate-time
6572 @opindex Wdate-time
6573 @opindex Wno-date-time
6574 Warn when macros @code{__TIME__}, @code{__DATE__} or @code{__TIMESTAMP__}
6575 are encountered as they might prevent bit-wise-identical reproducible
6576 compilations.
6578 @item -Wdelete-incomplete @r{(C++ and Objective-C++ only)}
6579 @opindex Wdelete-incomplete
6580 @opindex Wno-delete-incomplete
6581 Warn when deleting a pointer to incomplete type, which may cause
6582 undefined behavior at runtime.  This warning is enabled by default.
6584 @item -Wuseless-cast @r{(C++ and Objective-C++ only)}
6585 @opindex Wuseless-cast
6586 @opindex Wno-useless-cast
6587 Warn when an expression is casted to its own type.
6589 @item -Wempty-body
6590 @opindex Wempty-body
6591 @opindex Wno-empty-body
6592 Warn if an empty body occurs in an @code{if}, @code{else} or @code{do
6593 while} statement.  This warning is also enabled by @option{-Wextra}.
6595 @item -Wenum-compare
6596 @opindex Wenum-compare
6597 @opindex Wno-enum-compare
6598 Warn about a comparison between values of different enumerated types.
6599 In C++ enumerated type mismatches in conditional expressions are also
6600 diagnosed and the warning is enabled by default.  In C this warning is 
6601 enabled by @option{-Wall}.
6603 @item -Wextra-semi @r{(C++, Objective-C++ only)}
6604 @opindex Wextra-semi
6605 @opindex Wno-extra-semi
6606 Warn about redundant semicolon after in-class function definition.
6608 @item -Wjump-misses-init @r{(C, Objective-C only)}
6609 @opindex Wjump-misses-init
6610 @opindex Wno-jump-misses-init
6611 Warn if a @code{goto} statement or a @code{switch} statement jumps
6612 forward across the initialization of a variable, or jumps backward to a
6613 label after the variable has been initialized.  This only warns about
6614 variables that are initialized when they are declared.  This warning is
6615 only supported for C and Objective-C; in C++ this sort of branch is an
6616 error in any case.
6618 @option{-Wjump-misses-init} is included in @option{-Wc++-compat}.  It
6619 can be disabled with the @option{-Wno-jump-misses-init} option.
6621 @item -Wsign-compare
6622 @opindex Wsign-compare
6623 @opindex Wno-sign-compare
6624 @cindex warning for comparison of signed and unsigned values
6625 @cindex comparison of signed and unsigned values, warning
6626 @cindex signed and unsigned values, comparison warning
6627 Warn when a comparison between signed and unsigned values could produce
6628 an incorrect result when the signed value is converted to unsigned.
6629 In C++, this warning is also enabled by @option{-Wall}.  In C, it is
6630 also enabled by @option{-Wextra}.
6632 @item -Wsign-conversion
6633 @opindex Wsign-conversion
6634 @opindex Wno-sign-conversion
6635 Warn for implicit conversions that may change the sign of an integer
6636 value, like assigning a signed integer expression to an unsigned
6637 integer variable. An explicit cast silences the warning. In C, this
6638 option is enabled also by @option{-Wconversion}.
6640 @item -Wfloat-conversion
6641 @opindex Wfloat-conversion
6642 @opindex Wno-float-conversion
6643 Warn for implicit conversions that reduce the precision of a real value.
6644 This includes conversions from real to integer, and from higher precision
6645 real to lower precision real values.  This option is also enabled by
6646 @option{-Wconversion}.
6648 @item -Wno-scalar-storage-order
6649 @opindex -Wno-scalar-storage-order
6650 @opindex -Wscalar-storage-order
6651 Do not warn on suspicious constructs involving reverse scalar storage order.
6653 @item -Wsized-deallocation @r{(C++ and Objective-C++ only)}
6654 @opindex Wsized-deallocation
6655 @opindex Wno-sized-deallocation
6656 Warn about a definition of an unsized deallocation function
6657 @smallexample
6658 void operator delete (void *) noexcept;
6659 void operator delete[] (void *) noexcept;
6660 @end smallexample
6661 without a definition of the corresponding sized deallocation function
6662 @smallexample
6663 void operator delete (void *, std::size_t) noexcept;
6664 void operator delete[] (void *, std::size_t) noexcept;
6665 @end smallexample
6666 or vice versa.  Enabled by @option{-Wextra} along with
6667 @option{-fsized-deallocation}.
6669 @item -Wsizeof-pointer-div
6670 @opindex Wsizeof-pointer-div
6671 @opindex Wno-sizeof-pointer-div
6672 Warn for suspicious divisions of two sizeof expressions that divide
6673 the pointer size by the element size, which is the usual way to compute
6674 the array size but won't work out correctly with pointers.  This warning
6675 warns e.g.@: about @code{sizeof (ptr) / sizeof (ptr[0])} if @code{ptr} is
6676 not an array, but a pointer.  This warning is enabled by @option{-Wall}.
6678 @item -Wsizeof-pointer-memaccess
6679 @opindex Wsizeof-pointer-memaccess
6680 @opindex Wno-sizeof-pointer-memaccess
6681 Warn for suspicious length parameters to certain string and memory built-in
6682 functions if the argument uses @code{sizeof}.  This warning triggers for
6683 example for @code{memset (ptr, 0, sizeof (ptr));} if @code{ptr} is not
6684 an array, but a pointer, and suggests a possible fix, or about
6685 @code{memcpy (&foo, ptr, sizeof (&foo));}.  @option{-Wsizeof-pointer-memaccess}
6686 also warns about calls to bounded string copy functions like @code{strncat}
6687 or @code{strncpy} that specify as the bound a @code{sizeof} expression of
6688 the source array.  For example, in the following function the call to
6689 @code{strncat} specifies the size of the source string as the bound.  That
6690 is almost certainly a mistake and so the call is diagnosed.
6691 @smallexample
6692 void make_file (const char *name)
6694   char path[PATH_MAX];
6695   strncpy (path, name, sizeof path - 1);
6696   strncat (path, ".text", sizeof ".text");
6697   @dots{}
6699 @end smallexample
6701 The @option{-Wsizeof-pointer-memaccess} option is enabled by @option{-Wall}.
6703 @item -Wsizeof-array-argument
6704 @opindex Wsizeof-array-argument
6705 @opindex Wno-sizeof-array-argument
6706 Warn when the @code{sizeof} operator is applied to a parameter that is
6707 declared as an array in a function definition.  This warning is enabled by
6708 default for C and C++ programs.
6710 @item -Wmemset-elt-size
6711 @opindex Wmemset-elt-size
6712 @opindex Wno-memset-elt-size
6713 Warn for suspicious calls to the @code{memset} built-in function, if the
6714 first argument references an array, and the third argument is a number
6715 equal to the number of elements, but not equal to the size of the array
6716 in memory.  This indicates that the user has omitted a multiplication by
6717 the element size.  This warning is enabled by @option{-Wall}.
6719 @item -Wmemset-transposed-args
6720 @opindex Wmemset-transposed-args
6721 @opindex Wno-memset-transposed-args
6722 Warn for suspicious calls to the @code{memset} built-in function, if the
6723 second argument is not zero and the third argument is zero.  This warns e.g.@
6724 about @code{memset (buf, sizeof buf, 0)} where most probably
6725 @code{memset (buf, 0, sizeof buf)} was meant instead.  The diagnostics
6726 is only emitted if the third argument is literal zero.  If it is some
6727 expression that is folded to zero, a cast of zero to some type, etc., 
6728 it is far less likely that the user has mistakenly exchanged the arguments 
6729 and no warning is emitted.  This warning is enabled by @option{-Wall}.
6731 @item -Waddress
6732 @opindex Waddress
6733 @opindex Wno-address
6734 Warn about suspicious uses of memory addresses. These include using
6735 the address of a function in a conditional expression, such as
6736 @code{void func(void); if (func)}, and comparisons against the memory
6737 address of a string literal, such as @code{if (x == "abc")}.  Such
6738 uses typically indicate a programmer error: the address of a function
6739 always evaluates to true, so their use in a conditional usually
6740 indicate that the programmer forgot the parentheses in a function
6741 call; and comparisons against string literals result in unspecified
6742 behavior and are not portable in C, so they usually indicate that the
6743 programmer intended to use @code{strcmp}.  This warning is enabled by
6744 @option{-Wall}.
6746 @item -Wlogical-op
6747 @opindex Wlogical-op
6748 @opindex Wno-logical-op
6749 Warn about suspicious uses of logical operators in expressions.
6750 This includes using logical operators in contexts where a
6751 bit-wise operator is likely to be expected.  Also warns when
6752 the operands of a logical operator are the same:
6753 @smallexample
6754 extern int a;
6755 if (a < 0 && a < 0) @{ @dots{} @}
6756 @end smallexample
6758 @item -Wlogical-not-parentheses
6759 @opindex Wlogical-not-parentheses
6760 @opindex Wno-logical-not-parentheses
6761 Warn about logical not used on the left hand side operand of a comparison.
6762 This option does not warn if the right operand is considered to be a boolean
6763 expression.  Its purpose is to detect suspicious code like the following:
6764 @smallexample
6765 int a;
6766 @dots{}
6767 if (!a > 1) @{ @dots{} @}
6768 @end smallexample
6770 It is possible to suppress the warning by wrapping the LHS into
6771 parentheses:
6772 @smallexample
6773 if ((!a) > 1) @{ @dots{} @}
6774 @end smallexample
6776 This warning is enabled by @option{-Wall}.
6778 @item -Waggregate-return
6779 @opindex Waggregate-return
6780 @opindex Wno-aggregate-return
6781 Warn if any functions that return structures or unions are defined or
6782 called.  (In languages where you can return an array, this also elicits
6783 a warning.)
6785 @item -Wno-aggressive-loop-optimizations
6786 @opindex Wno-aggressive-loop-optimizations
6787 @opindex Waggressive-loop-optimizations
6788 Warn if in a loop with constant number of iterations the compiler detects
6789 undefined behavior in some statement during one or more of the iterations.
6791 @item -Wno-attributes
6792 @opindex Wno-attributes
6793 @opindex Wattributes
6794 Do not warn if an unexpected @code{__attribute__} is used, such as
6795 unrecognized attributes, function attributes applied to variables,
6796 etc.  This does not stop errors for incorrect use of supported
6797 attributes.
6799 @item -Wno-builtin-declaration-mismatch
6800 @opindex Wno-builtin-declaration-mismatch
6801 @opindex Wbuiltin-declaration-mismatch
6802 Warn if a built-in function is declared with the wrong signature or 
6803 as non-function.
6804 This warning is enabled by default.
6806 @item -Wno-builtin-macro-redefined
6807 @opindex Wno-builtin-macro-redefined
6808 @opindex Wbuiltin-macro-redefined
6809 Do not warn if certain built-in macros are redefined.  This suppresses
6810 warnings for redefinition of @code{__TIMESTAMP__}, @code{__TIME__},
6811 @code{__DATE__}, @code{__FILE__}, and @code{__BASE_FILE__}.
6813 @item -Wstrict-prototypes @r{(C and Objective-C only)}
6814 @opindex Wstrict-prototypes
6815 @opindex Wno-strict-prototypes
6816 Warn if a function is declared or defined without specifying the
6817 argument types.  (An old-style function definition is permitted without
6818 a warning if preceded by a declaration that specifies the argument
6819 types.)
6821 @item -Wold-style-declaration @r{(C and Objective-C only)}
6822 @opindex Wold-style-declaration
6823 @opindex Wno-old-style-declaration
6824 Warn for obsolescent usages, according to the C Standard, in a
6825 declaration. For example, warn if storage-class specifiers like
6826 @code{static} are not the first things in a declaration.  This warning
6827 is also enabled by @option{-Wextra}.
6829 @item -Wold-style-definition @r{(C and Objective-C only)}
6830 @opindex Wold-style-definition
6831 @opindex Wno-old-style-definition
6832 Warn if an old-style function definition is used.  A warning is given
6833 even if there is a previous prototype.
6835 @item -Wmissing-parameter-type @r{(C and Objective-C only)}
6836 @opindex Wmissing-parameter-type
6837 @opindex Wno-missing-parameter-type
6838 A function parameter is declared without a type specifier in K&R-style
6839 functions:
6841 @smallexample
6842 void foo(bar) @{ @}
6843 @end smallexample
6845 This warning is also enabled by @option{-Wextra}.
6847 @item -Wmissing-prototypes @r{(C and Objective-C only)}
6848 @opindex Wmissing-prototypes
6849 @opindex Wno-missing-prototypes
6850 Warn if a global function is defined without a previous prototype
6851 declaration.  This warning is issued even if the definition itself
6852 provides a prototype.  Use this option to detect global functions
6853 that do not have a matching prototype declaration in a header file.
6854 This option is not valid for C++ because all function declarations
6855 provide prototypes and a non-matching declaration declares an
6856 overload rather than conflict with an earlier declaration.
6857 Use @option{-Wmissing-declarations} to detect missing declarations in C++.
6859 @item -Wmissing-declarations
6860 @opindex Wmissing-declarations
6861 @opindex Wno-missing-declarations
6862 Warn if a global function is defined without a previous declaration.
6863 Do so even if the definition itself provides a prototype.
6864 Use this option to detect global functions that are not declared in
6865 header files.  In C, no warnings are issued for functions with previous
6866 non-prototype declarations; use @option{-Wmissing-prototypes} to detect
6867 missing prototypes.  In C++, no warnings are issued for function templates,
6868 or for inline functions, or for functions in anonymous namespaces.
6870 @item -Wmissing-field-initializers
6871 @opindex Wmissing-field-initializers
6872 @opindex Wno-missing-field-initializers
6873 @opindex W
6874 @opindex Wextra
6875 @opindex Wno-extra
6876 Warn if a structure's initializer has some fields missing.  For
6877 example, the following code causes such a warning, because
6878 @code{x.h} is implicitly zero:
6880 @smallexample
6881 struct s @{ int f, g, h; @};
6882 struct s x = @{ 3, 4 @};
6883 @end smallexample
6885 This option does not warn about designated initializers, so the following
6886 modification does not trigger a warning:
6888 @smallexample
6889 struct s @{ int f, g, h; @};
6890 struct s x = @{ .f = 3, .g = 4 @};
6891 @end smallexample
6893 In C this option does not warn about the universal zero initializer
6894 @samp{@{ 0 @}}:
6896 @smallexample
6897 struct s @{ int f, g, h; @};
6898 struct s x = @{ 0 @};
6899 @end smallexample
6901 Likewise, in C++ this option does not warn about the empty @{ @}
6902 initializer, for example:
6904 @smallexample
6905 struct s @{ int f, g, h; @};
6906 s x = @{ @};
6907 @end smallexample
6909 This warning is included in @option{-Wextra}.  To get other @option{-Wextra}
6910 warnings without this one, use @option{-Wextra -Wno-missing-field-initializers}.
6912 @item -Wno-multichar
6913 @opindex Wno-multichar
6914 @opindex Wmultichar
6915 Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
6916 Usually they indicate a typo in the user's code, as they have
6917 implementation-defined values, and should not be used in portable code.
6919 @item -Wnormalized=@r{[}none@r{|}id@r{|}nfc@r{|}nfkc@r{]}
6920 @opindex Wnormalized=
6921 @opindex Wnormalized
6922 @opindex Wno-normalized
6923 @cindex NFC
6924 @cindex NFKC
6925 @cindex character set, input normalization
6926 In ISO C and ISO C++, two identifiers are different if they are
6927 different sequences of characters.  However, sometimes when characters
6928 outside the basic ASCII character set are used, you can have two
6929 different character sequences that look the same.  To avoid confusion,
6930 the ISO 10646 standard sets out some @dfn{normalization rules} which
6931 when applied ensure that two sequences that look the same are turned into
6932 the same sequence.  GCC can warn you if you are using identifiers that
6933 have not been normalized; this option controls that warning.
6935 There are four levels of warning supported by GCC@.  The default is
6936 @option{-Wnormalized=nfc}, which warns about any identifier that is
6937 not in the ISO 10646 ``C'' normalized form, @dfn{NFC}.  NFC is the
6938 recommended form for most uses.  It is equivalent to
6939 @option{-Wnormalized}.
6941 Unfortunately, there are some characters allowed in identifiers by
6942 ISO C and ISO C++ that, when turned into NFC, are not allowed in 
6943 identifiers.  That is, there's no way to use these symbols in portable
6944 ISO C or C++ and have all your identifiers in NFC@.
6945 @option{-Wnormalized=id} suppresses the warning for these characters.
6946 It is hoped that future versions of the standards involved will correct
6947 this, which is why this option is not the default.
6949 You can switch the warning off for all characters by writing
6950 @option{-Wnormalized=none} or @option{-Wno-normalized}.  You should
6951 only do this if you are using some other normalization scheme (like
6952 ``D''), because otherwise you can easily create bugs that are
6953 literally impossible to see.
6955 Some characters in ISO 10646 have distinct meanings but look identical
6956 in some fonts or display methodologies, especially once formatting has
6957 been applied.  For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
6958 LETTER N'', displays just like a regular @code{n} that has been
6959 placed in a superscript.  ISO 10646 defines the @dfn{NFKC}
6960 normalization scheme to convert all these into a standard form as
6961 well, and GCC warns if your code is not in NFKC if you use
6962 @option{-Wnormalized=nfkc}.  This warning is comparable to warning
6963 about every identifier that contains the letter O because it might be
6964 confused with the digit 0, and so is not the default, but may be
6965 useful as a local coding convention if the programming environment 
6966 cannot be fixed to display these characters distinctly.
6968 @item -Wno-deprecated
6969 @opindex Wno-deprecated
6970 @opindex Wdeprecated
6971 Do not warn about usage of deprecated features.  @xref{Deprecated Features}.
6973 @item -Wno-deprecated-declarations
6974 @opindex Wno-deprecated-declarations
6975 @opindex Wdeprecated-declarations
6976 Do not warn about uses of functions (@pxref{Function Attributes}),
6977 variables (@pxref{Variable Attributes}), and types (@pxref{Type
6978 Attributes}) marked as deprecated by using the @code{deprecated}
6979 attribute.
6981 @item -Wno-overflow
6982 @opindex Wno-overflow
6983 @opindex Woverflow
6984 Do not warn about compile-time overflow in constant expressions.
6986 @item -Wno-odr
6987 @opindex Wno-odr
6988 @opindex Wodr
6989 Warn about One Definition Rule violations during link-time optimization.
6990 Requires @option{-flto-odr-type-merging} to be enabled.  Enabled by default.
6992 @item -Wopenmp-simd
6993 @opindex Wopenmp-simd
6994 @opindex Wno-openmp-simd
6995 Warn if the vectorizer cost model overrides the OpenMP
6996 simd directive set by user.  The @option{-fsimd-cost-model=unlimited}
6997 option can be used to relax the cost model.
6999 @item -Woverride-init @r{(C and Objective-C only)}
7000 @opindex Woverride-init
7001 @opindex Wno-override-init
7002 @opindex W
7003 @opindex Wextra
7004 @opindex Wno-extra
7005 Warn if an initialized field without side effects is overridden when
7006 using designated initializers (@pxref{Designated Inits, , Designated
7007 Initializers}).
7009 This warning is included in @option{-Wextra}.  To get other
7010 @option{-Wextra} warnings without this one, use @option{-Wextra
7011 -Wno-override-init}.
7013 @item -Woverride-init-side-effects @r{(C and Objective-C only)}
7014 @opindex Woverride-init-side-effects
7015 @opindex Wno-override-init-side-effects
7016 Warn if an initialized field with side effects is overridden when
7017 using designated initializers (@pxref{Designated Inits, , Designated
7018 Initializers}).  This warning is enabled by default.
7020 @item -Wpacked
7021 @opindex Wpacked
7022 @opindex Wno-packed
7023 Warn if a structure is given the packed attribute, but the packed
7024 attribute has no effect on the layout or size of the structure.
7025 Such structures may be mis-aligned for little benefit.  For
7026 instance, in this code, the variable @code{f.x} in @code{struct bar}
7027 is misaligned even though @code{struct bar} does not itself
7028 have the packed attribute:
7030 @smallexample
7031 @group
7032 struct foo @{
7033   int x;
7034   char a, b, c, d;
7035 @} __attribute__((packed));
7036 struct bar @{
7037   char z;
7038   struct foo f;
7040 @end group
7041 @end smallexample
7043 @item -Wpacked-bitfield-compat
7044 @opindex Wpacked-bitfield-compat
7045 @opindex Wno-packed-bitfield-compat
7046 The 4.1, 4.2 and 4.3 series of GCC ignore the @code{packed} attribute
7047 on bit-fields of type @code{char}.  This has been fixed in GCC 4.4 but
7048 the change can lead to differences in the structure layout.  GCC
7049 informs you when the offset of such a field has changed in GCC 4.4.
7050 For example there is no longer a 4-bit padding between field @code{a}
7051 and @code{b} in this structure:
7053 @smallexample
7054 struct foo
7056   char a:4;
7057   char b:8;
7058 @} __attribute__ ((packed));
7059 @end smallexample
7061 This warning is enabled by default.  Use
7062 @option{-Wno-packed-bitfield-compat} to disable this warning.
7064 @item -Wpacked-not-aligned @r{(C, C++, Objective-C and Objective-C++ only)}
7065 @opindex Wpacked-not-aligned
7066 @opindex Wno-packed-not-aligned
7067 Warn if a structure field with explicitly specified alignment in a
7068 packed struct or union is misaligned.  For example, a warning will
7069 be issued on @code{struct S}, like, @code{warning: alignment 1 of
7070 'struct S' is less than 8}, in this code:
7072 @smallexample
7073 @group
7074 struct __attribute__ ((aligned (8))) S8 @{ char a[8]; @};
7075 struct __attribute__ ((packed)) S @{
7076   struct S8 s8;
7078 @end group
7079 @end smallexample
7081 This warning is enabled by @option{-Wall}.
7083 @item -Wpadded
7084 @opindex Wpadded
7085 @opindex Wno-padded
7086 Warn if padding is included in a structure, either to align an element
7087 of the structure or to align the whole structure.  Sometimes when this
7088 happens it is possible to rearrange the fields of the structure to
7089 reduce the padding and so make the structure smaller.
7091 @item -Wredundant-decls
7092 @opindex Wredundant-decls
7093 @opindex Wno-redundant-decls
7094 Warn if anything is declared more than once in the same scope, even in
7095 cases where multiple declaration is valid and changes nothing.
7097 @item -Wno-restrict
7098 @opindex Wrestrict
7099 @opindex Wno-restrict
7100 Warn when an object referenced by a @code{restrict}-qualified parameter
7101 (or, in C++, a @code{__restrict}-qualified parameter) is aliased by another
7102 argument, or when copies between such objects overlap.  For example,
7103 the call to the @code{strcpy} function below attempts to truncate the string
7104 by replacing its initial characters with the last four.  However, because
7105 the call writes the terminating NUL into @code{a[4]}, the copies overlap and
7106 the call is diagnosed.
7108 @smallexample
7109 void foo (void)
7111   char a[] = "abcd1234";
7112   strcpy (a, a + 4);
7113   @dots{}
7115 @end smallexample
7116 The @option{-Wrestrict} option detects some instances of simple overlap
7117 even without optimization but works best at @option{-O2} and above.  It
7118 is included in @option{-Wall}.
7120 @item -Wnested-externs @r{(C and Objective-C only)}
7121 @opindex Wnested-externs
7122 @opindex Wno-nested-externs
7123 Warn if an @code{extern} declaration is encountered within a function.
7125 @item -Wno-inherited-variadic-ctor
7126 @opindex Winherited-variadic-ctor
7127 @opindex Wno-inherited-variadic-ctor
7128 Suppress warnings about use of C++11 inheriting constructors when the
7129 base class inherited from has a C variadic constructor; the warning is
7130 on by default because the ellipsis is not inherited.
7132 @item -Winline
7133 @opindex Winline
7134 @opindex Wno-inline
7135 Warn if a function that is declared as inline cannot be inlined.
7136 Even with this option, the compiler does not warn about failures to
7137 inline functions declared in system headers.
7139 The compiler uses a variety of heuristics to determine whether or not
7140 to inline a function.  For example, the compiler takes into account
7141 the size of the function being inlined and the amount of inlining
7142 that has already been done in the current function.  Therefore,
7143 seemingly insignificant changes in the source program can cause the
7144 warnings produced by @option{-Winline} to appear or disappear.
7146 @item -Wno-invalid-offsetof @r{(C++ and Objective-C++ only)}
7147 @opindex Wno-invalid-offsetof
7148 @opindex Winvalid-offsetof
7149 Suppress warnings from applying the @code{offsetof} macro to a non-POD
7150 type.  According to the 2014 ISO C++ standard, applying @code{offsetof}
7151 to a non-standard-layout type is undefined.  In existing C++ implementations,
7152 however, @code{offsetof} typically gives meaningful results.
7153 This flag is for users who are aware that they are
7154 writing nonportable code and who have deliberately chosen to ignore the
7155 warning about it.
7157 The restrictions on @code{offsetof} may be relaxed in a future version
7158 of the C++ standard.
7160 @item -Wint-in-bool-context
7161 @opindex Wint-in-bool-context
7162 @opindex Wno-int-in-bool-context
7163 Warn for suspicious use of integer values where boolean values are expected,
7164 such as conditional expressions (?:) using non-boolean integer constants in
7165 boolean context, like @code{if (a <= b ? 2 : 3)}.  Or left shifting of signed
7166 integers in boolean context, like @code{for (a = 0; 1 << a; a++);}.  Likewise
7167 for all kinds of multiplications regardless of the data type.
7168 This warning is enabled by @option{-Wall}.
7170 @item -Wno-int-to-pointer-cast
7171 @opindex Wno-int-to-pointer-cast
7172 @opindex Wint-to-pointer-cast
7173 Suppress warnings from casts to pointer type of an integer of a
7174 different size. In C++, casting to a pointer type of smaller size is
7175 an error. @option{Wint-to-pointer-cast} is enabled by default.
7178 @item -Wno-pointer-to-int-cast @r{(C and Objective-C only)}
7179 @opindex Wno-pointer-to-int-cast
7180 @opindex Wpointer-to-int-cast
7181 Suppress warnings from casts from a pointer to an integer type of a
7182 different size.
7184 @item -Winvalid-pch
7185 @opindex Winvalid-pch
7186 @opindex Wno-invalid-pch
7187 Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
7188 the search path but cannot be used.
7190 @item -Wlong-long
7191 @opindex Wlong-long
7192 @opindex Wno-long-long
7193 Warn if @code{long long} type is used.  This is enabled by either
7194 @option{-Wpedantic} or @option{-Wtraditional} in ISO C90 and C++98
7195 modes.  To inhibit the warning messages, use @option{-Wno-long-long}.
7197 @item -Wvariadic-macros
7198 @opindex Wvariadic-macros
7199 @opindex Wno-variadic-macros
7200 Warn if variadic macros are used in ISO C90 mode, or if the GNU
7201 alternate syntax is used in ISO C99 mode.  This is enabled by either
7202 @option{-Wpedantic} or @option{-Wtraditional}.  To inhibit the warning
7203 messages, use @option{-Wno-variadic-macros}.
7205 @item -Wvarargs
7206 @opindex Wvarargs
7207 @opindex Wno-varargs
7208 Warn upon questionable usage of the macros used to handle variable
7209 arguments like @code{va_start}.  This is default.  To inhibit the
7210 warning messages, use @option{-Wno-varargs}.
7212 @item -Wvector-operation-performance
7213 @opindex Wvector-operation-performance
7214 @opindex Wno-vector-operation-performance
7215 Warn if vector operation is not implemented via SIMD capabilities of the
7216 architecture.  Mainly useful for the performance tuning.
7217 Vector operation can be implemented @code{piecewise}, which means that the
7218 scalar operation is performed on every vector element; 
7219 @code{in parallel}, which means that the vector operation is implemented
7220 using scalars of wider type, which normally is more performance efficient;
7221 and @code{as a single scalar}, which means that vector fits into a
7222 scalar type.
7224 @item -Wno-virtual-move-assign
7225 @opindex Wvirtual-move-assign
7226 @opindex Wno-virtual-move-assign
7227 Suppress warnings about inheriting from a virtual base with a
7228 non-trivial C++11 move assignment operator.  This is dangerous because
7229 if the virtual base is reachable along more than one path, it is
7230 moved multiple times, which can mean both objects end up in the
7231 moved-from state.  If the move assignment operator is written to avoid
7232 moving from a moved-from object, this warning can be disabled.
7234 @item -Wvla
7235 @opindex Wvla
7236 @opindex Wno-vla
7237 Warn if a variable-length array is used in the code.
7238 @option{-Wno-vla} prevents the @option{-Wpedantic} warning of
7239 the variable-length array.
7241 @item -Wvla-larger-than=@var{byte-size}
7242 @opindex -Wvla-larger-than=
7243 @opindex -Wno-vla-larger-than
7244 If this option is used, the compiler will warn for declarations of
7245 variable-length arrays whose size is either unbounded, or bounded
7246 by an argument that allows the array size to exceed @var{byte-size}
7247 bytes.  This is similar to how @option{-Walloca-larger-than=}@var{byte-size}
7248 works, but with variable-length arrays.
7250 Note that GCC may optimize small variable-length arrays of a known
7251 value into plain arrays, so this warning may not get triggered for
7252 such arrays.
7254 @option{-Wvla-larger-than=}@samp{PTRDIFF_MAX} is enabled by default but
7255 is typically only effective when @option{-ftree-vrp} is active (default
7256 for @option{-O2} and above).
7258 See also @option{-Walloca-larger-than=@var{byte-size}}.
7260 @item -Wno-vla-larger-than
7261 @opindex Wno-vla-larger-than
7262 Disable @option{-Wvla-larger-than=} warnings.  The option is equivalent
7263 to @option{-Wvla-larger-than=}@samp{SIZE_MAX} or larger.
7265 @item -Wvolatile-register-var
7266 @opindex Wvolatile-register-var
7267 @opindex Wno-volatile-register-var
7268 Warn if a register variable is declared volatile.  The volatile
7269 modifier does not inhibit all optimizations that may eliminate reads
7270 and/or writes to register variables.  This warning is enabled by
7271 @option{-Wall}.
7273 @item -Wdisabled-optimization
7274 @opindex Wdisabled-optimization
7275 @opindex Wno-disabled-optimization
7276 Warn if a requested optimization pass is disabled.  This warning does
7277 not generally indicate that there is anything wrong with your code; it
7278 merely indicates that GCC's optimizers are unable to handle the code
7279 effectively.  Often, the problem is that your code is too big or too
7280 complex; GCC refuses to optimize programs when the optimization
7281 itself is likely to take inordinate amounts of time.
7283 @item -Wpointer-sign @r{(C and Objective-C only)}
7284 @opindex Wpointer-sign
7285 @opindex Wno-pointer-sign
7286 Warn for pointer argument passing or assignment with different signedness.
7287 This option is only supported for C and Objective-C@.  It is implied by
7288 @option{-Wall} and by @option{-Wpedantic}, which can be disabled with
7289 @option{-Wno-pointer-sign}.
7291 @item -Wstack-protector
7292 @opindex Wstack-protector
7293 @opindex Wno-stack-protector
7294 This option is only active when @option{-fstack-protector} is active.  It
7295 warns about functions that are not protected against stack smashing.
7297 @item -Woverlength-strings
7298 @opindex Woverlength-strings
7299 @opindex Wno-overlength-strings
7300 Warn about string constants that are longer than the ``minimum
7301 maximum'' length specified in the C standard.  Modern compilers
7302 generally allow string constants that are much longer than the
7303 standard's minimum limit, but very portable programs should avoid
7304 using longer strings.
7306 The limit applies @emph{after} string constant concatenation, and does
7307 not count the trailing NUL@.  In C90, the limit was 509 characters; in
7308 C99, it was raised to 4095.  C++98 does not specify a normative
7309 minimum maximum, so we do not diagnose overlength strings in C++@.
7311 This option is implied by @option{-Wpedantic}, and can be disabled with
7312 @option{-Wno-overlength-strings}.
7314 @item -Wunsuffixed-float-constants @r{(C and Objective-C only)}
7315 @opindex Wunsuffixed-float-constants
7316 @opindex Wno-unsuffixed-float-constants
7318 Issue a warning for any floating constant that does not have
7319 a suffix.  When used together with @option{-Wsystem-headers} it
7320 warns about such constants in system header files.  This can be useful
7321 when preparing code to use with the @code{FLOAT_CONST_DECIMAL64} pragma
7322 from the decimal floating-point extension to C99.
7324 @item -Wno-designated-init @r{(C and Objective-C only)}
7325 Suppress warnings when a positional initializer is used to initialize
7326 a structure that has been marked with the @code{designated_init}
7327 attribute.
7329 @item -Whsa
7330 Issue a warning when HSAIL cannot be emitted for the compiled function or
7331 OpenMP construct.
7333 @end table
7335 @node Debugging Options
7336 @section Options for Debugging Your Program
7337 @cindex options, debugging
7338 @cindex debugging information options
7340 To tell GCC to emit extra information for use by a debugger, in almost 
7341 all cases you need only to add @option{-g} to your other options.
7343 GCC allows you to use @option{-g} with
7344 @option{-O}.  The shortcuts taken by optimized code may occasionally
7345 be surprising: some variables you declared may not exist
7346 at all; flow of control may briefly move where you did not expect it;
7347 some statements may not be executed because they compute constant
7348 results or their values are already at hand; some statements may
7349 execute in different places because they have been moved out of loops.
7350 Nevertheless it is possible to debug optimized output.  This makes
7351 it reasonable to use the optimizer for programs that might have bugs.
7353 If you are not using some other optimization option, consider
7354 using @option{-Og} (@pxref{Optimize Options}) with @option{-g}.  
7355 With no @option{-O} option at all, some compiler passes that collect
7356 information useful for debugging do not run at all, so that
7357 @option{-Og} may result in a better debugging experience.
7359 @table @gcctabopt
7360 @item -g
7361 @opindex g
7362 Produce debugging information in the operating system's native format
7363 (stabs, COFF, XCOFF, or DWARF)@.  GDB can work with this debugging
7364 information.
7366 On most systems that use stabs format, @option{-g} enables use of extra
7367 debugging information that only GDB can use; this extra information
7368 makes debugging work better in GDB but probably makes other debuggers
7369 crash or
7370 refuse to read the program.  If you want to control for certain whether
7371 to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
7372 @option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
7374 @item -ggdb
7375 @opindex ggdb
7376 Produce debugging information for use by GDB@.  This means to use the
7377 most expressive format available (DWARF, stabs, or the native format
7378 if neither of those are supported), including GDB extensions if at all
7379 possible.
7381 @item -gdwarf
7382 @itemx -gdwarf-@var{version}
7383 @opindex gdwarf
7384 Produce debugging information in DWARF format (if that is supported).
7385 The value of @var{version} may be either 2, 3, 4 or 5; the default version
7386 for most targets is 4.  DWARF Version 5 is only experimental.
7388 Note that with DWARF Version 2, some ports require and always
7389 use some non-conflicting DWARF 3 extensions in the unwind tables.
7391 Version 4 may require GDB 7.0 and @option{-fvar-tracking-assignments}
7392 for maximum benefit.
7394 GCC no longer supports DWARF Version 1, which is substantially
7395 different than Version 2 and later.  For historical reasons, some
7396 other DWARF-related options such as
7397 @option{-fno-dwarf2-cfi-asm}) retain a reference to DWARF Version 2
7398 in their names, but apply to all currently-supported versions of DWARF.
7400 @item -gstabs
7401 @opindex gstabs
7402 Produce debugging information in stabs format (if that is supported),
7403 without GDB extensions.  This is the format used by DBX on most BSD
7404 systems.  On MIPS, Alpha and System V Release 4 systems this option
7405 produces stabs debugging output that is not understood by DBX@.
7406 On System V Release 4 systems this option requires the GNU assembler.
7408 @item -gstabs+
7409 @opindex gstabs+
7410 Produce debugging information in stabs format (if that is supported),
7411 using GNU extensions understood only by the GNU debugger (GDB)@.  The
7412 use of these extensions is likely to make other debuggers crash or
7413 refuse to read the program.
7415 @item -gxcoff
7416 @opindex gxcoff
7417 Produce debugging information in XCOFF format (if that is supported).
7418 This is the format used by the DBX debugger on IBM RS/6000 systems.
7420 @item -gxcoff+
7421 @opindex gxcoff+
7422 Produce debugging information in XCOFF format (if that is supported),
7423 using GNU extensions understood only by the GNU debugger (GDB)@.  The
7424 use of these extensions is likely to make other debuggers crash or
7425 refuse to read the program, and may cause assemblers other than the GNU
7426 assembler (GAS) to fail with an error.
7428 @item -gvms
7429 @opindex gvms
7430 Produce debugging information in Alpha/VMS debug format (if that is
7431 supported).  This is the format used by DEBUG on Alpha/VMS systems.
7433 @item -g@var{level}
7434 @itemx -ggdb@var{level}
7435 @itemx -gstabs@var{level}
7436 @itemx -gxcoff@var{level}
7437 @itemx -gvms@var{level}
7438 Request debugging information and also use @var{level} to specify how
7439 much information.  The default level is 2.
7441 Level 0 produces no debug information at all.  Thus, @option{-g0} negates
7442 @option{-g}.
7444 Level 1 produces minimal information, enough for making backtraces in
7445 parts of the program that you don't plan to debug.  This includes
7446 descriptions of functions and external variables, and line number
7447 tables, but no information about local variables.
7449 Level 3 includes extra information, such as all the macro definitions
7450 present in the program.  Some debuggers support macro expansion when
7451 you use @option{-g3}.
7453 @option{-gdwarf} does not accept a concatenated debug level, to avoid
7454 confusion with @option{-gdwarf-@var{level}}.
7455 Instead use an additional @option{-g@var{level}} option to change the
7456 debug level for DWARF.
7458 @item -feliminate-unused-debug-symbols
7459 @opindex feliminate-unused-debug-symbols
7460 Produce debugging information in stabs format (if that is supported),
7461 for only symbols that are actually used.
7463 @item -femit-class-debug-always
7464 @opindex femit-class-debug-always
7465 Instead of emitting debugging information for a C++ class in only one
7466 object file, emit it in all object files using the class.  This option
7467 should be used only with debuggers that are unable to handle the way GCC
7468 normally emits debugging information for classes because using this
7469 option increases the size of debugging information by as much as a
7470 factor of two.
7472 @item -fno-merge-debug-strings
7473 @opindex fmerge-debug-strings
7474 @opindex fno-merge-debug-strings
7475 Direct the linker to not merge together strings in the debugging
7476 information that are identical in different object files.  Merging is
7477 not supported by all assemblers or linkers.  Merging decreases the size
7478 of the debug information in the output file at the cost of increasing
7479 link processing time.  Merging is enabled by default.
7481 @item -fdebug-prefix-map=@var{old}=@var{new}
7482 @opindex fdebug-prefix-map
7483 When compiling files residing in directory @file{@var{old}}, record
7484 debugging information describing them as if the files resided in
7485 directory @file{@var{new}} instead.  This can be used to replace a
7486 build-time path with an install-time path in the debug info.  It can
7487 also be used to change an absolute path to a relative path by using
7488 @file{.} for @var{new}.  This can give more reproducible builds, which
7489 are location independent, but may require an extra command to tell GDB
7490 where to find the source files. See also @option{-ffile-prefix-map}.
7492 @item -fvar-tracking
7493 @opindex fvar-tracking
7494 Run variable tracking pass.  It computes where variables are stored at each
7495 position in code.  Better debugging information is then generated
7496 (if the debugging information format supports this information).
7498 It is enabled by default when compiling with optimization (@option{-Os},
7499 @option{-O}, @option{-O2}, @dots{}), debugging information (@option{-g}) and
7500 the debug info format supports it.
7502 @item -fvar-tracking-assignments
7503 @opindex fvar-tracking-assignments
7504 @opindex fno-var-tracking-assignments
7505 Annotate assignments to user variables early in the compilation and
7506 attempt to carry the annotations over throughout the compilation all the
7507 way to the end, in an attempt to improve debug information while
7508 optimizing.  Use of @option{-gdwarf-4} is recommended along with it.
7510 It can be enabled even if var-tracking is disabled, in which case
7511 annotations are created and maintained, but discarded at the end.
7512 By default, this flag is enabled together with @option{-fvar-tracking},
7513 except when selective scheduling is enabled.
7515 @item -gsplit-dwarf
7516 @opindex gsplit-dwarf
7517 Separate as much DWARF debugging information as possible into a
7518 separate output file with the extension @file{.dwo}.  This option allows
7519 the build system to avoid linking files with debug information.  To
7520 be useful, this option requires a debugger capable of reading @file{.dwo}
7521 files.
7523 @item -gdescribe-dies
7524 @opindex gdescribe-dies
7525 Add description attributes to some DWARF DIEs that have no name attribute,
7526 such as artificial variables, external references and call site
7527 parameter DIEs.
7529 @item -gpubnames
7530 @opindex gpubnames
7531 Generate DWARF @code{.debug_pubnames} and @code{.debug_pubtypes} sections.
7533 @item -ggnu-pubnames
7534 @opindex ggnu-pubnames
7535 Generate @code{.debug_pubnames} and @code{.debug_pubtypes} sections in a format
7536 suitable for conversion into a GDB@ index.  This option is only useful
7537 with a linker that can produce GDB@ index version 7.
7539 @item -fdebug-types-section
7540 @opindex fdebug-types-section
7541 @opindex fno-debug-types-section
7542 When using DWARF Version 4 or higher, type DIEs can be put into
7543 their own @code{.debug_types} section instead of making them part of the
7544 @code{.debug_info} section.  It is more efficient to put them in a separate
7545 comdat section since the linker can then remove duplicates.
7546 But not all DWARF consumers support @code{.debug_types} sections yet
7547 and on some objects @code{.debug_types} produces larger instead of smaller
7548 debugging information.
7550 @item -grecord-gcc-switches
7551 @itemx -gno-record-gcc-switches
7552 @opindex grecord-gcc-switches
7553 @opindex gno-record-gcc-switches
7554 This switch causes the command-line options used to invoke the
7555 compiler that may affect code generation to be appended to the
7556 DW_AT_producer attribute in DWARF debugging information.  The options
7557 are concatenated with spaces separating them from each other and from
7558 the compiler version.  
7559 It is enabled by default.
7560 See also @option{-frecord-gcc-switches} for another
7561 way of storing compiler options into the object file.  
7563 @item -gstrict-dwarf
7564 @opindex gstrict-dwarf
7565 Disallow using extensions of later DWARF standard version than selected
7566 with @option{-gdwarf-@var{version}}.  On most targets using non-conflicting
7567 DWARF extensions from later standard versions is allowed.
7569 @item -gno-strict-dwarf
7570 @opindex gno-strict-dwarf
7571 Allow using extensions of later DWARF standard version than selected with
7572 @option{-gdwarf-@var{version}}.
7574 @item -gas-loc-support
7575 @opindex gas-loc-support
7576 Inform the compiler that the assembler supports @code{.loc} directives.
7577 It may then use them for the assembler to generate DWARF2+ line number
7578 tables.
7580 This is generally desirable, because assembler-generated line-number
7581 tables are a lot more compact than those the compiler can generate
7582 itself.
7584 This option will be enabled by default if, at GCC configure time, the
7585 assembler was found to support such directives.
7587 @item -gno-as-loc-support
7588 @opindex gno-as-loc-support
7589 Force GCC to generate DWARF2+ line number tables internally, if DWARF2+
7590 line number tables are to be generated.
7592 @item gas-locview-support
7593 @opindex gas-locview-support
7594 Inform the compiler that the assembler supports @code{view} assignment
7595 and reset assertion checking in @code{.loc} directives.
7597 This option will be enabled by default if, at GCC configure time, the
7598 assembler was found to support them.
7600 @item gno-as-locview-support
7601 Force GCC to assign view numbers internally, if
7602 @option{-gvariable-location-views} are explicitly requested.
7604 @item -gcolumn-info
7605 @itemx -gno-column-info
7606 @opindex gcolumn-info
7607 @opindex gno-column-info
7608 Emit location column information into DWARF debugging information, rather
7609 than just file and line.
7610 This option is enabled by default.
7612 @item -gstatement-frontiers
7613 @itemx -gno-statement-frontiers
7614 @opindex gstatement-frontiers
7615 @opindex gno-statement-frontiers
7616 This option causes GCC to create markers in the internal representation
7617 at the beginning of statements, and to keep them roughly in place
7618 throughout compilation, using them to guide the output of @code{is_stmt}
7619 markers in the line number table.  This is enabled by default when
7620 compiling with optimization (@option{-Os}, @option{-O}, @option{-O2},
7621 @dots{}), and outputting DWARF 2 debug information at the normal level.
7623 @item -gvariable-location-views
7624 @itemx -gvariable-location-views=incompat5
7625 @itemx -gno-variable-location-views
7626 @opindex gvariable-location-views
7627 @opindex gvariable-location-views=incompat5
7628 @opindex gno-variable-location-views
7629 Augment variable location lists with progressive view numbers implied
7630 from the line number table.  This enables debug information consumers to
7631 inspect state at certain points of the program, even if no instructions
7632 associated with the corresponding source locations are present at that
7633 point.  If the assembler lacks support for view numbers in line number
7634 tables, this will cause the compiler to emit the line number table,
7635 which generally makes them somewhat less compact.  The augmented line
7636 number tables and location lists are fully backward-compatible, so they
7637 can be consumed by debug information consumers that are not aware of
7638 these augmentations, but they won't derive any benefit from them either.
7640 This is enabled by default when outputting DWARF 2 debug information at
7641 the normal level, as long as there is assembler support,
7642 @option{-fvar-tracking-assignments} is enabled and
7643 @option{-gstrict-dwarf} is not.  When assembler support is not
7644 available, this may still be enabled, but it will force GCC to output
7645 internal line number tables, and if
7646 @option{-ginternal-reset-location-views} is not enabled, that will most
7647 certainly lead to silently mismatching location views.
7649 There is a proposed representation for view numbers that is not backward
7650 compatible with the location list format introduced in DWARF 5, that can
7651 be enabled with @option{-gvariable-location-views=incompat5}.  This
7652 option may be removed in the future, is only provided as a reference
7653 implementation of the proposed representation.  Debug information
7654 consumers are not expected to support this extended format, and they
7655 would be rendered unable to decode location lists using it.
7657 @item -ginternal-reset-location-views
7658 @itemx -gnointernal-reset-location-views
7659 @opindex ginternal-reset-location-views
7660 @opindex gno-internal-reset-location-views
7661 Attempt to determine location views that can be omitted from location
7662 view lists.  This requires the compiler to have very accurate insn
7663 length estimates, which isn't always the case, and it may cause
7664 incorrect view lists to be generated silently when using an assembler
7665 that does not support location view lists.  The GNU assembler will flag
7666 any such error as a @code{view number mismatch}.  This is only enabled
7667 on ports that define a reliable estimation function.
7669 @item -ginline-points
7670 @itemx -gno-inline-points
7671 @opindex ginline-points
7672 @opindex gno-inline-points
7673 Generate extended debug information for inlined functions.  Location
7674 view tracking markers are inserted at inlined entry points, so that
7675 address and view numbers can be computed and output in debug
7676 information.  This can be enabled independently of location views, in
7677 which case the view numbers won't be output, but it can only be enabled
7678 along with statement frontiers, and it is only enabled by default if
7679 location views are enabled.
7681 @item -gz@r{[}=@var{type}@r{]}
7682 @opindex gz
7683 Produce compressed debug sections in DWARF format, if that is supported.
7684 If @var{type} is not given, the default type depends on the capabilities
7685 of the assembler and linker used.  @var{type} may be one of
7686 @samp{none} (don't compress debug sections), @samp{zlib} (use zlib
7687 compression in ELF gABI format), or @samp{zlib-gnu} (use zlib
7688 compression in traditional GNU format).  If the linker doesn't support
7689 writing compressed debug sections, the option is rejected.  Otherwise,
7690 if the assembler does not support them, @option{-gz} is silently ignored
7691 when producing object files.
7693 @item -femit-struct-debug-baseonly
7694 @opindex femit-struct-debug-baseonly
7695 Emit debug information for struct-like types
7696 only when the base name of the compilation source file
7697 matches the base name of file in which the struct is defined.
7699 This option substantially reduces the size of debugging information,
7700 but at significant potential loss in type information to the debugger.
7701 See @option{-femit-struct-debug-reduced} for a less aggressive option.
7702 See @option{-femit-struct-debug-detailed} for more detailed control.
7704 This option works only with DWARF debug output.
7706 @item -femit-struct-debug-reduced
7707 @opindex femit-struct-debug-reduced
7708 Emit debug information for struct-like types
7709 only when the base name of the compilation source file
7710 matches the base name of file in which the type is defined,
7711 unless the struct is a template or defined in a system header.
7713 This option significantly reduces the size of debugging information,
7714 with some potential loss in type information to the debugger.
7715 See @option{-femit-struct-debug-baseonly} for a more aggressive option.
7716 See @option{-femit-struct-debug-detailed} for more detailed control.
7718 This option works only with DWARF debug output.
7720 @item -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]}
7721 @opindex femit-struct-debug-detailed
7722 Specify the struct-like types
7723 for which the compiler generates debug information.
7724 The intent is to reduce duplicate struct debug information
7725 between different object files within the same program.
7727 This option is a detailed version of
7728 @option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly},
7729 which serves for most needs.
7731 A specification has the syntax@*
7732 [@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none})
7734 The optional first word limits the specification to
7735 structs that are used directly (@samp{dir:}) or used indirectly (@samp{ind:}).
7736 A struct type is used directly when it is the type of a variable, member.
7737 Indirect uses arise through pointers to structs.
7738 That is, when use of an incomplete struct is valid, the use is indirect.
7739 An example is
7740 @samp{struct one direct; struct two * indirect;}.
7742 The optional second word limits the specification to
7743 ordinary structs (@samp{ord:}) or generic structs (@samp{gen:}).
7744 Generic structs are a bit complicated to explain.
7745 For C++, these are non-explicit specializations of template classes,
7746 or non-template classes within the above.
7747 Other programming languages have generics,
7748 but @option{-femit-struct-debug-detailed} does not yet implement them.
7750 The third word specifies the source files for those
7751 structs for which the compiler should emit debug information.
7752 The values @samp{none} and @samp{any} have the normal meaning.
7753 The value @samp{base} means that
7754 the base of name of the file in which the type declaration appears
7755 must match the base of the name of the main compilation file.
7756 In practice, this means that when compiling @file{foo.c}, debug information
7757 is generated for types declared in that file and @file{foo.h},
7758 but not other header files.
7759 The value @samp{sys} means those types satisfying @samp{base}
7760 or declared in system or compiler headers.
7762 You may need to experiment to determine the best settings for your application.
7764 The default is @option{-femit-struct-debug-detailed=all}.
7766 This option works only with DWARF debug output.
7768 @item -fno-dwarf2-cfi-asm
7769 @opindex fdwarf2-cfi-asm
7770 @opindex fno-dwarf2-cfi-asm
7771 Emit DWARF unwind info as compiler generated @code{.eh_frame} section
7772 instead of using GAS @code{.cfi_*} directives.
7774 @item -fno-eliminate-unused-debug-types
7775 @opindex feliminate-unused-debug-types
7776 @opindex fno-eliminate-unused-debug-types
7777 Normally, when producing DWARF output, GCC avoids producing debug symbol 
7778 output for types that are nowhere used in the source file being compiled.
7779 Sometimes it is useful to have GCC emit debugging
7780 information for all types declared in a compilation
7781 unit, regardless of whether or not they are actually used
7782 in that compilation unit, for example 
7783 if, in the debugger, you want to cast a value to a type that is
7784 not actually used in your program (but is declared).  More often,
7785 however, this results in a significant amount of wasted space.
7786 @end table
7788 @node Optimize Options
7789 @section Options That Control Optimization
7790 @cindex optimize options
7791 @cindex options, optimization
7793 These options control various sorts of optimizations.
7795 Without any optimization option, the compiler's goal is to reduce the
7796 cost of compilation and to make debugging produce the expected
7797 results.  Statements are independent: if you stop the program with a
7798 breakpoint between statements, you can then assign a new value to any
7799 variable or change the program counter to any other statement in the
7800 function and get exactly the results you expect from the source
7801 code.
7803 Turning on optimization flags makes the compiler attempt to improve
7804 the performance and/or code size at the expense of compilation time
7805 and possibly the ability to debug the program.
7807 The compiler performs optimization based on the knowledge it has of the
7808 program.  Compiling multiple files at once to a single output file mode allows
7809 the compiler to use information gained from all of the files when compiling
7810 each of them.
7812 Not all optimizations are controlled directly by a flag.  Only
7813 optimizations that have a flag are listed in this section.
7815 Most optimizations are only enabled if an @option{-O} level is set on
7816 the command line.  Otherwise they are disabled, even if individual
7817 optimization flags are specified.
7819 Depending on the target and how GCC was configured, a slightly different
7820 set of optimizations may be enabled at each @option{-O} level than
7821 those listed here.  You can invoke GCC with @option{-Q --help=optimizers}
7822 to find out the exact set of optimizations that are enabled at each level.
7823 @xref{Overall Options}, for examples.
7825 @table @gcctabopt
7826 @item -O
7827 @itemx -O1
7828 @opindex O
7829 @opindex O1
7830 Optimize.  Optimizing compilation takes somewhat more time, and a lot
7831 more memory for a large function.
7833 With @option{-O}, the compiler tries to reduce code size and execution
7834 time, without performing any optimizations that take a great deal of
7835 compilation time.
7837 @option{-O} turns on the following optimization flags:
7838 @gccoptlist{
7839 -fauto-inc-dec @gol
7840 -fbranch-count-reg @gol
7841 -fcombine-stack-adjustments @gol
7842 -fcompare-elim @gol
7843 -fcprop-registers @gol
7844 -fdce @gol
7845 -fdefer-pop @gol
7846 -fdelayed-branch @gol
7847 -fdse @gol
7848 -fforward-propagate @gol
7849 -fguess-branch-probability @gol
7850 -fif-conversion2 @gol
7851 -fif-conversion @gol
7852 -finline-functions-called-once @gol
7853 -fipa-pure-const @gol
7854 -fipa-profile @gol
7855 -fipa-reference @gol
7856 -fmerge-constants @gol
7857 -fmove-loop-invariants @gol
7858 -fomit-frame-pointer @gol
7859 -freorder-blocks @gol
7860 -fshrink-wrap @gol
7861 -fshrink-wrap-separate @gol
7862 -fsplit-wide-types @gol
7863 -fssa-backprop @gol
7864 -fssa-phiopt @gol
7865 -ftree-bit-ccp @gol
7866 -ftree-ccp @gol
7867 -ftree-ch @gol
7868 -ftree-coalesce-vars @gol
7869 -ftree-copy-prop @gol
7870 -ftree-dce @gol
7871 -ftree-dominator-opts @gol
7872 -ftree-dse @gol
7873 -ftree-forwprop @gol
7874 -ftree-fre @gol
7875 -ftree-phiprop @gol
7876 -ftree-scev-cprop @gol
7877 -ftree-sink @gol
7878 -ftree-slsr @gol
7879 -ftree-sra @gol
7880 -ftree-pta @gol
7881 -ftree-ter @gol
7882 -funit-at-a-time}
7884 @item -O2
7885 @opindex O2
7886 Optimize even more.  GCC performs nearly all supported optimizations
7887 that do not involve a space-speed tradeoff.
7888 As compared to @option{-O}, this option increases both compilation time
7889 and the performance of the generated code.
7891 @option{-O2} turns on all optimization flags specified by @option{-O}.  It
7892 also turns on the following optimization flags:
7893 @gccoptlist{-fthread-jumps @gol
7894 -falign-functions  -falign-jumps @gol
7895 -falign-loops  -falign-labels @gol
7896 -fcaller-saves @gol
7897 -fcrossjumping @gol
7898 -fcse-follow-jumps  -fcse-skip-blocks @gol
7899 -fdelete-null-pointer-checks @gol
7900 -fdevirtualize -fdevirtualize-speculatively @gol
7901 -fexpensive-optimizations @gol
7902 -fgcse  -fgcse-lm  @gol
7903 -fhoist-adjacent-loads @gol
7904 -finline-small-functions @gol
7905 -findirect-inlining @gol
7906 -fipa-cp @gol
7907 -fipa-bit-cp @gol
7908 -fipa-vrp @gol
7909 -fipa-sra @gol
7910 -fipa-icf @gol
7911 -fisolate-erroneous-paths-dereference @gol
7912 -flra-remat @gol
7913 -foptimize-sibling-calls @gol
7914 -foptimize-strlen @gol
7915 -fpartial-inlining @gol
7916 -fpeephole2 @gol
7917 -freorder-blocks-algorithm=stc @gol
7918 -freorder-blocks-and-partition -freorder-functions @gol
7919 -frerun-cse-after-loop  @gol
7920 -fsched-interblock  -fsched-spec @gol
7921 -fschedule-insns  -fschedule-insns2 @gol
7922 -fstore-merging @gol
7923 -fstrict-aliasing @gol
7924 -ftree-builtin-call-dce @gol
7925 -ftree-switch-conversion -ftree-tail-merge @gol
7926 -fcode-hoisting @gol
7927 -ftree-pre @gol
7928 -ftree-vrp @gol
7929 -fipa-ra}
7931 Please note the warning under @option{-fgcse} about
7932 invoking @option{-O2} on programs that use computed gotos.
7934 @item -O3
7935 @opindex O3
7936 Optimize yet more.  @option{-O3} turns on all optimizations specified
7937 by @option{-O2} and also turns on the following optimization flags:
7938 @gccoptlist{-finline-functions @gol
7939 -funswitch-loops @gol
7940 -fpredictive-commoning @gol
7941 -fgcse-after-reload @gol
7942 -ftree-loop-vectorize @gol
7943 -ftree-loop-distribution @gol
7944 -ftree-loop-distribute-patterns @gol
7945 -floop-interchange @gol
7946 -floop-unroll-and-jam @gol
7947 -fsplit-paths @gol
7948 -ftree-slp-vectorize @gol
7949 -fvect-cost-model @gol
7950 -ftree-partial-pre @gol
7951 -fpeel-loops @gol
7952 -fipa-cp-clone}
7954 @item -O0
7955 @opindex O0
7956 Reduce compilation time and make debugging produce the expected
7957 results.  This is the default.
7959 @item -Os
7960 @opindex Os
7961 Optimize for size.  @option{-Os} enables all @option{-O2} optimizations that
7962 do not typically increase code size.  It also performs further
7963 optimizations designed to reduce code size.
7965 @option{-Os} disables the following optimization flags:
7966 @gccoptlist{-falign-functions  -falign-jumps  -falign-loops @gol
7967 -falign-labels  -freorder-blocks  -freorder-blocks-algorithm=stc @gol
7968 -freorder-blocks-and-partition  -fprefetch-loop-arrays}
7970 @item -Ofast
7971 @opindex Ofast
7972 Disregard strict standards compliance.  @option{-Ofast} enables all
7973 @option{-O3} optimizations.  It also enables optimizations that are not
7974 valid for all standard-compliant programs.
7975 It turns on @option{-ffast-math} and the Fortran-specific
7976 @option{-fstack-arrays}, unless @option{-fmax-stack-var-size} is
7977 specified, and @option{-fno-protect-parens}.
7979 @item -Og
7980 @opindex Og
7981 Optimize debugging experience.  @option{-Og} enables optimizations
7982 that do not interfere with debugging. It should be the optimization
7983 level of choice for the standard edit-compile-debug cycle, offering
7984 a reasonable level of optimization while maintaining fast compilation
7985 and a good debugging experience.
7986 @end table
7988 If you use multiple @option{-O} options, with or without level numbers,
7989 the last such option is the one that is effective.
7991 Options of the form @option{-f@var{flag}} specify machine-independent
7992 flags.  Most flags have both positive and negative forms; the negative
7993 form of @option{-ffoo} is @option{-fno-foo}.  In the table
7994 below, only one of the forms is listed---the one you typically 
7995 use.  You can figure out the other form by either removing @samp{no-}
7996 or adding it.
7998 The following options control specific optimizations.  They are either
7999 activated by @option{-O} options or are related to ones that are.  You
8000 can use the following flags in the rare cases when ``fine-tuning'' of
8001 optimizations to be performed is desired.
8003 @table @gcctabopt
8004 @item -fno-defer-pop
8005 @opindex fno-defer-pop
8006 Always pop the arguments to each function call as soon as that function
8007 returns.  For machines that must pop arguments after a function call,
8008 the compiler normally lets arguments accumulate on the stack for several
8009 function calls and pops them all at once.
8011 Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
8013 @item -fforward-propagate
8014 @opindex fforward-propagate
8015 Perform a forward propagation pass on RTL@.  The pass tries to combine two
8016 instructions and checks if the result can be simplified.  If loop unrolling
8017 is active, two passes are performed and the second is scheduled after
8018 loop unrolling.
8020 This option is enabled by default at optimization levels @option{-O},
8021 @option{-O2}, @option{-O3}, @option{-Os}.
8023 @item -ffp-contract=@var{style}
8024 @opindex ffp-contract
8025 @option{-ffp-contract=off} disables floating-point expression contraction.
8026 @option{-ffp-contract=fast} enables floating-point expression contraction
8027 such as forming of fused multiply-add operations if the target has
8028 native support for them.
8029 @option{-ffp-contract=on} enables floating-point expression contraction
8030 if allowed by the language standard.  This is currently not implemented
8031 and treated equal to @option{-ffp-contract=off}.
8033 The default is @option{-ffp-contract=fast}.
8035 @item -fomit-frame-pointer
8036 @opindex fomit-frame-pointer
8037 Omit the frame pointer in functions that don't need one.  This avoids the
8038 instructions to save, set up and restore the frame pointer; on many targets
8039 it also makes an extra register available.
8041 On some targets this flag has no effect because the standard calling sequence
8042 always uses a frame pointer, so it cannot be omitted.
8044 Note that @option{-fno-omit-frame-pointer} doesn't guarantee the frame pointer
8045 is used in all functions.  Several targets always omit the frame pointer in
8046 leaf functions.
8048 Enabled by default at @option{-O} and higher.
8050 @item -foptimize-sibling-calls
8051 @opindex foptimize-sibling-calls
8052 Optimize sibling and tail recursive calls.
8054 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
8056 @item -foptimize-strlen
8057 @opindex foptimize-strlen
8058 Optimize various standard C string functions (e.g. @code{strlen},
8059 @code{strchr} or @code{strcpy}) and
8060 their @code{_FORTIFY_SOURCE} counterparts into faster alternatives.
8062 Enabled at levels @option{-O2}, @option{-O3}.
8064 @item -fno-inline
8065 @opindex fno-inline
8066 Do not expand any functions inline apart from those marked with
8067 the @code{always_inline} attribute.  This is the default when not
8068 optimizing.
8070 Single functions can be exempted from inlining by marking them
8071 with the @code{noinline} attribute.
8073 @item -finline-small-functions
8074 @opindex finline-small-functions
8075 Integrate functions into their callers when their body is smaller than expected
8076 function call code (so overall size of program gets smaller).  The compiler
8077 heuristically decides which functions are simple enough to be worth integrating
8078 in this way.  This inlining applies to all functions, even those not declared
8079 inline.
8081 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
8083 @item -findirect-inlining
8084 @opindex findirect-inlining
8085 Inline also indirect calls that are discovered to be known at compile
8086 time thanks to previous inlining.  This option has any effect only
8087 when inlining itself is turned on by the @option{-finline-functions}
8088 or @option{-finline-small-functions} options.
8090 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
8092 @item -finline-functions
8093 @opindex finline-functions
8094 Consider all functions for inlining, even if they are not declared inline.
8095 The compiler heuristically decides which functions are worth integrating
8096 in this way.
8098 If all calls to a given function are integrated, and the function is
8099 declared @code{static}, then the function is normally not output as
8100 assembler code in its own right.
8102 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
8104 @item -finline-functions-called-once
8105 @opindex finline-functions-called-once
8106 Consider all @code{static} functions called once for inlining into their
8107 caller even if they are not marked @code{inline}.  If a call to a given
8108 function is integrated, then the function is not output as assembler code
8109 in its own right.
8111 Enabled at levels @option{-O1}, @option{-O2}, @option{-O3} and @option{-Os}.
8113 @item -fearly-inlining
8114 @opindex fearly-inlining
8115 Inline functions marked by @code{always_inline} and functions whose body seems
8116 smaller than the function call overhead early before doing
8117 @option{-fprofile-generate} instrumentation and real inlining pass.  Doing so
8118 makes profiling significantly cheaper and usually inlining faster on programs
8119 having large chains of nested wrapper functions.
8121 Enabled by default.
8123 @item -fipa-sra
8124 @opindex fipa-sra
8125 Perform interprocedural scalar replacement of aggregates, removal of
8126 unused parameters and replacement of parameters passed by reference
8127 by parameters passed by value.
8129 Enabled at levels @option{-O2}, @option{-O3} and @option{-Os}.
8131 @item -finline-limit=@var{n}
8132 @opindex finline-limit
8133 By default, GCC limits the size of functions that can be inlined.  This flag
8134 allows coarse control of this limit.  @var{n} is the size of functions that
8135 can be inlined in number of pseudo instructions.
8137 Inlining is actually controlled by a number of parameters, which may be
8138 specified individually by using @option{--param @var{name}=@var{value}}.
8139 The @option{-finline-limit=@var{n}} option sets some of these parameters
8140 as follows:
8142 @table @gcctabopt
8143 @item max-inline-insns-single
8144 is set to @var{n}/2.
8145 @item max-inline-insns-auto
8146 is set to @var{n}/2.
8147 @end table
8149 See below for a documentation of the individual
8150 parameters controlling inlining and for the defaults of these parameters.
8152 @emph{Note:} there may be no value to @option{-finline-limit} that results
8153 in default behavior.
8155 @emph{Note:} pseudo instruction represents, in this particular context, an
8156 abstract measurement of function's size.  In no way does it represent a count
8157 of assembly instructions and as such its exact meaning might change from one
8158 release to an another.
8160 @item -fno-keep-inline-dllexport
8161 @opindex fno-keep-inline-dllexport
8162 This is a more fine-grained version of @option{-fkeep-inline-functions},
8163 which applies only to functions that are declared using the @code{dllexport}
8164 attribute or declspec.  @xref{Function Attributes,,Declaring Attributes of
8165 Functions}.
8167 @item -fkeep-inline-functions
8168 @opindex fkeep-inline-functions
8169 In C, emit @code{static} functions that are declared @code{inline}
8170 into the object file, even if the function has been inlined into all
8171 of its callers.  This switch does not affect functions using the
8172 @code{extern inline} extension in GNU C90@.  In C++, emit any and all
8173 inline functions into the object file.
8175 @item -fkeep-static-functions
8176 @opindex fkeep-static-functions
8177 Emit @code{static} functions into the object file, even if the function
8178 is never used.
8180 @item -fkeep-static-consts
8181 @opindex fkeep-static-consts
8182 Emit variables declared @code{static const} when optimization isn't turned
8183 on, even if the variables aren't referenced.
8185 GCC enables this option by default.  If you want to force the compiler to
8186 check if a variable is referenced, regardless of whether or not
8187 optimization is turned on, use the @option{-fno-keep-static-consts} option.
8189 @item -fmerge-constants
8190 @opindex fmerge-constants
8191 Attempt to merge identical constants (string constants and floating-point
8192 constants) across compilation units.
8194 This option is the default for optimized compilation if the assembler and
8195 linker support it.  Use @option{-fno-merge-constants} to inhibit this
8196 behavior.
8198 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
8200 @item -fmerge-all-constants
8201 @opindex fmerge-all-constants
8202 Attempt to merge identical constants and identical variables.
8204 This option implies @option{-fmerge-constants}.  In addition to
8205 @option{-fmerge-constants} this considers e.g.@: even constant initialized
8206 arrays or initialized constant variables with integral or floating-point
8207 types.  Languages like C or C++ require each variable, including multiple
8208 instances of the same variable in recursive calls, to have distinct locations,
8209 so using this option results in non-conforming
8210 behavior.
8212 @item -fmodulo-sched
8213 @opindex fmodulo-sched
8214 Perform swing modulo scheduling immediately before the first scheduling
8215 pass.  This pass looks at innermost loops and reorders their
8216 instructions by overlapping different iterations.
8218 @item -fmodulo-sched-allow-regmoves
8219 @opindex fmodulo-sched-allow-regmoves
8220 Perform more aggressive SMS-based modulo scheduling with register moves
8221 allowed.  By setting this flag certain anti-dependences edges are
8222 deleted, which triggers the generation of reg-moves based on the
8223 life-range analysis.  This option is effective only with
8224 @option{-fmodulo-sched} enabled.
8226 @item -fno-branch-count-reg
8227 @opindex fno-branch-count-reg
8228 Avoid running a pass scanning for opportunities to use ``decrement and
8229 branch'' instructions on a count register instead of generating sequences
8230 of instructions that decrement a register, compare it against zero, and
8231 then branch based upon the result.  This option is only meaningful on
8232 architectures that support such instructions, which include x86, PowerPC,
8233 IA-64 and S/390.  Note that the @option{-fno-branch-count-reg} option
8234 doesn't remove the decrement and branch instructions from the generated
8235 instruction stream introduced by other optimization passes.
8237 Enabled by default at @option{-O1} and higher.
8239 The default is @option{-fbranch-count-reg}.
8241 @item -fno-function-cse
8242 @opindex fno-function-cse
8243 Do not put function addresses in registers; make each instruction that
8244 calls a constant function contain the function's address explicitly.
8246 This option results in less efficient code, but some strange hacks
8247 that alter the assembler output may be confused by the optimizations
8248 performed when this option is not used.
8250 The default is @option{-ffunction-cse}
8252 @item -fno-zero-initialized-in-bss
8253 @opindex fno-zero-initialized-in-bss
8254 If the target supports a BSS section, GCC by default puts variables that
8255 are initialized to zero into BSS@.  This can save space in the resulting
8256 code.
8258 This option turns off this behavior because some programs explicitly
8259 rely on variables going to the data section---e.g., so that the
8260 resulting executable can find the beginning of that section and/or make
8261 assumptions based on that.
8263 The default is @option{-fzero-initialized-in-bss}.
8265 @item -fthread-jumps
8266 @opindex fthread-jumps
8267 Perform optimizations that check to see if a jump branches to a
8268 location where another comparison subsumed by the first is found.  If
8269 so, the first branch is redirected to either the destination of the
8270 second branch or a point immediately following it, depending on whether
8271 the condition is known to be true or false.
8273 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
8275 @item -fsplit-wide-types
8276 @opindex fsplit-wide-types
8277 When using a type that occupies multiple registers, such as @code{long
8278 long} on a 32-bit system, split the registers apart and allocate them
8279 independently.  This normally generates better code for those types,
8280 but may make debugging more difficult.
8282 Enabled at levels @option{-O}, @option{-O2}, @option{-O3},
8283 @option{-Os}.
8285 @item -fcse-follow-jumps
8286 @opindex fcse-follow-jumps
8287 In common subexpression elimination (CSE), scan through jump instructions
8288 when the target of the jump is not reached by any other path.  For
8289 example, when CSE encounters an @code{if} statement with an
8290 @code{else} clause, CSE follows the jump when the condition
8291 tested is false.
8293 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
8295 @item -fcse-skip-blocks
8296 @opindex fcse-skip-blocks
8297 This is similar to @option{-fcse-follow-jumps}, but causes CSE to
8298 follow jumps that conditionally skip over blocks.  When CSE
8299 encounters a simple @code{if} statement with no else clause,
8300 @option{-fcse-skip-blocks} causes CSE to follow the jump around the
8301 body of the @code{if}.
8303 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
8305 @item -frerun-cse-after-loop
8306 @opindex frerun-cse-after-loop
8307 Re-run common subexpression elimination after loop optimizations are
8308 performed.
8310 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
8312 @item -fgcse
8313 @opindex fgcse
8314 Perform a global common subexpression elimination pass.
8315 This pass also performs global constant and copy propagation.
8317 @emph{Note:} When compiling a program using computed gotos, a GCC
8318 extension, you may get better run-time performance if you disable
8319 the global common subexpression elimination pass by adding
8320 @option{-fno-gcse} to the command line.
8322 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
8324 @item -fgcse-lm
8325 @opindex fgcse-lm
8326 When @option{-fgcse-lm} is enabled, global common subexpression elimination
8327 attempts to move loads that are only killed by stores into themselves.  This
8328 allows a loop containing a load/store sequence to be changed to a load outside
8329 the loop, and a copy/store within the loop.
8331 Enabled by default when @option{-fgcse} is enabled.
8333 @item -fgcse-sm
8334 @opindex fgcse-sm
8335 When @option{-fgcse-sm} is enabled, a store motion pass is run after
8336 global common subexpression elimination.  This pass attempts to move
8337 stores out of loops.  When used in conjunction with @option{-fgcse-lm},
8338 loops containing a load/store sequence can be changed to a load before
8339 the loop and a store after the loop.
8341 Not enabled at any optimization level.
8343 @item -fgcse-las
8344 @opindex fgcse-las
8345 When @option{-fgcse-las} is enabled, the global common subexpression
8346 elimination pass eliminates redundant loads that come after stores to the
8347 same memory location (both partial and full redundancies).
8349 Not enabled at any optimization level.
8351 @item -fgcse-after-reload
8352 @opindex fgcse-after-reload
8353 When @option{-fgcse-after-reload} is enabled, a redundant load elimination
8354 pass is performed after reload.  The purpose of this pass is to clean up
8355 redundant spilling.
8357 @item -faggressive-loop-optimizations
8358 @opindex faggressive-loop-optimizations
8359 This option tells the loop optimizer to use language constraints to
8360 derive bounds for the number of iterations of a loop.  This assumes that
8361 loop code does not invoke undefined behavior by for example causing signed
8362 integer overflows or out-of-bound array accesses.  The bounds for the
8363 number of iterations of a loop are used to guide loop unrolling and peeling
8364 and loop exit test optimizations.
8365 This option is enabled by default.
8367 @item -funconstrained-commons
8368 @opindex funconstrained-commons
8369 This option tells the compiler that variables declared in common blocks
8370 (e.g. Fortran) may later be overridden with longer trailing arrays. This
8371 prevents certain optimizations that depend on knowing the array bounds.
8373 @item -fcrossjumping
8374 @opindex fcrossjumping
8375 Perform cross-jumping transformation.
8376 This transformation unifies equivalent code and saves code size.  The
8377 resulting code may or may not perform better than without cross-jumping.
8379 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
8381 @item -fauto-inc-dec
8382 @opindex fauto-inc-dec
8383 Combine increments or decrements of addresses with memory accesses.
8384 This pass is always skipped on architectures that do not have
8385 instructions to support this.  Enabled by default at @option{-O} and
8386 higher on architectures that support this.
8388 @item -fdce
8389 @opindex fdce
8390 Perform dead code elimination (DCE) on RTL@.
8391 Enabled by default at @option{-O} and higher.
8393 @item -fdse
8394 @opindex fdse
8395 Perform dead store elimination (DSE) on RTL@.
8396 Enabled by default at @option{-O} and higher.
8398 @item -fif-conversion
8399 @opindex fif-conversion
8400 Attempt to transform conditional jumps into branch-less equivalents.  This
8401 includes use of conditional moves, min, max, set flags and abs instructions, and
8402 some tricks doable by standard arithmetics.  The use of conditional execution
8403 on chips where it is available is controlled by @option{-fif-conversion2}.
8405 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
8407 @item -fif-conversion2
8408 @opindex fif-conversion2
8409 Use conditional execution (where available) to transform conditional jumps into
8410 branch-less equivalents.
8412 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
8414 @item -fdeclone-ctor-dtor
8415 @opindex fdeclone-ctor-dtor
8416 The C++ ABI requires multiple entry points for constructors and
8417 destructors: one for a base subobject, one for a complete object, and
8418 one for a virtual destructor that calls operator delete afterwards.
8419 For a hierarchy with virtual bases, the base and complete variants are
8420 clones, which means two copies of the function.  With this option, the
8421 base and complete variants are changed to be thunks that call a common
8422 implementation.
8424 Enabled by @option{-Os}.
8426 @item -fdelete-null-pointer-checks
8427 @opindex fdelete-null-pointer-checks
8428 Assume that programs cannot safely dereference null pointers, and that
8429 no code or data element resides at address zero.
8430 This option enables simple constant
8431 folding optimizations at all optimization levels.  In addition, other
8432 optimization passes in GCC use this flag to control global dataflow
8433 analyses that eliminate useless checks for null pointers; these assume
8434 that a memory access to address zero always results in a trap, so
8435 that if a pointer is checked after it has already been dereferenced,
8436 it cannot be null.
8438 Note however that in some environments this assumption is not true.
8439 Use @option{-fno-delete-null-pointer-checks} to disable this optimization
8440 for programs that depend on that behavior.
8442 This option is enabled by default on most targets.  On Nios II ELF, it
8443 defaults to off.  On AVR, CR16, and MSP430, this option is completely disabled.
8445 Passes that use the dataflow information
8446 are enabled independently at different optimization levels.
8448 @item -fdevirtualize
8449 @opindex fdevirtualize
8450 Attempt to convert calls to virtual functions to direct calls.  This
8451 is done both within a procedure and interprocedurally as part of
8452 indirect inlining (@option{-findirect-inlining}) and interprocedural constant
8453 propagation (@option{-fipa-cp}).
8454 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
8456 @item -fdevirtualize-speculatively
8457 @opindex fdevirtualize-speculatively
8458 Attempt to convert calls to virtual functions to speculative direct calls.
8459 Based on the analysis of the type inheritance graph, determine for a given call
8460 the set of likely targets. If the set is small, preferably of size 1, change
8461 the call into a conditional deciding between direct and indirect calls.  The
8462 speculative calls enable more optimizations, such as inlining.  When they seem
8463 useless after further optimization, they are converted back into original form.
8465 @item -fdevirtualize-at-ltrans
8466 @opindex fdevirtualize-at-ltrans
8467 Stream extra information needed for aggressive devirtualization when running
8468 the link-time optimizer in local transformation mode.  
8469 This option enables more devirtualization but
8470 significantly increases the size of streamed data. For this reason it is
8471 disabled by default.
8473 @item -fexpensive-optimizations
8474 @opindex fexpensive-optimizations
8475 Perform a number of minor optimizations that are relatively expensive.
8477 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
8479 @item -free
8480 @opindex free
8481 Attempt to remove redundant extension instructions.  This is especially
8482 helpful for the x86-64 architecture, which implicitly zero-extends in 64-bit
8483 registers after writing to their lower 32-bit half.
8485 Enabled for Alpha, AArch64 and x86 at levels @option{-O2},
8486 @option{-O3}, @option{-Os}.
8488 @item -fno-lifetime-dse
8489 @opindex fno-lifetime-dse
8490 In C++ the value of an object is only affected by changes within its
8491 lifetime: when the constructor begins, the object has an indeterminate
8492 value, and any changes during the lifetime of the object are dead when
8493 the object is destroyed.  Normally dead store elimination will take
8494 advantage of this; if your code relies on the value of the object
8495 storage persisting beyond the lifetime of the object, you can use this
8496 flag to disable this optimization.  To preserve stores before the
8497 constructor starts (e.g. because your operator new clears the object
8498 storage) but still treat the object as dead after the destructor you,
8499 can use @option{-flifetime-dse=1}.  The default behavior can be
8500 explicitly selected with @option{-flifetime-dse=2}.
8501 @option{-flifetime-dse=0} is equivalent to @option{-fno-lifetime-dse}.
8503 @item -flive-range-shrinkage
8504 @opindex flive-range-shrinkage
8505 Attempt to decrease register pressure through register live range
8506 shrinkage.  This is helpful for fast processors with small or moderate
8507 size register sets.
8509 @item -fira-algorithm=@var{algorithm}
8510 @opindex fira-algorithm
8511 Use the specified coloring algorithm for the integrated register
8512 allocator.  The @var{algorithm} argument can be @samp{priority}, which
8513 specifies Chow's priority coloring, or @samp{CB}, which specifies
8514 Chaitin-Briggs coloring.  Chaitin-Briggs coloring is not implemented
8515 for all architectures, but for those targets that do support it, it is
8516 the default because it generates better code.
8518 @item -fira-region=@var{region}
8519 @opindex fira-region
8520 Use specified regions for the integrated register allocator.  The
8521 @var{region} argument should be one of the following:
8523 @table @samp
8525 @item all
8526 Use all loops as register allocation regions.
8527 This can give the best results for machines with a small and/or
8528 irregular register set.
8530 @item mixed
8531 Use all loops except for loops with small register pressure 
8532 as the regions.  This value usually gives
8533 the best results in most cases and for most architectures,
8534 and is enabled by default when compiling with optimization for speed
8535 (@option{-O}, @option{-O2}, @dots{}).
8537 @item one
8538 Use all functions as a single region.  
8539 This typically results in the smallest code size, and is enabled by default for
8540 @option{-Os} or @option{-O0}.
8542 @end table
8544 @item -fira-hoist-pressure
8545 @opindex fira-hoist-pressure
8546 Use IRA to evaluate register pressure in the code hoisting pass for
8547 decisions to hoist expressions.  This option usually results in smaller
8548 code, but it can slow the compiler down.
8550 This option is enabled at level @option{-Os} for all targets.
8552 @item -fira-loop-pressure
8553 @opindex fira-loop-pressure
8554 Use IRA to evaluate register pressure in loops for decisions to move
8555 loop invariants.  This option usually results in generation
8556 of faster and smaller code on machines with large register files (>= 32
8557 registers), but it can slow the compiler down.
8559 This option is enabled at level @option{-O3} for some targets.
8561 @item -fno-ira-share-save-slots
8562 @opindex fno-ira-share-save-slots
8563 Disable sharing of stack slots used for saving call-used hard
8564 registers living through a call.  Each hard register gets a
8565 separate stack slot, and as a result function stack frames are
8566 larger.
8568 @item -fno-ira-share-spill-slots
8569 @opindex fno-ira-share-spill-slots
8570 Disable sharing of stack slots allocated for pseudo-registers.  Each
8571 pseudo-register that does not get a hard register gets a separate
8572 stack slot, and as a result function stack frames are larger.
8574 @item -flra-remat
8575 @opindex flra-remat
8576 Enable CFG-sensitive rematerialization in LRA.  Instead of loading
8577 values of spilled pseudos, LRA tries to rematerialize (recalculate)
8578 values if it is profitable.
8580 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
8582 @item -fdelayed-branch
8583 @opindex fdelayed-branch
8584 If supported for the target machine, attempt to reorder instructions
8585 to exploit instruction slots available after delayed branch
8586 instructions.
8588 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
8590 @item -fschedule-insns
8591 @opindex fschedule-insns
8592 If supported for the target machine, attempt to reorder instructions to
8593 eliminate execution stalls due to required data being unavailable.  This
8594 helps machines that have slow floating point or memory load instructions
8595 by allowing other instructions to be issued until the result of the load
8596 or floating-point instruction is required.
8598 Enabled at levels @option{-O2}, @option{-O3}.
8600 @item -fschedule-insns2
8601 @opindex fschedule-insns2
8602 Similar to @option{-fschedule-insns}, but requests an additional pass of
8603 instruction scheduling after register allocation has been done.  This is
8604 especially useful on machines with a relatively small number of
8605 registers and where memory load instructions take more than one cycle.
8607 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
8609 @item -fno-sched-interblock
8610 @opindex fno-sched-interblock
8611 Don't schedule instructions across basic blocks.  This is normally
8612 enabled by default when scheduling before register allocation, i.e.@:
8613 with @option{-fschedule-insns} or at @option{-O2} or higher.
8615 @item -fno-sched-spec
8616 @opindex fno-sched-spec
8617 Don't allow speculative motion of non-load instructions.  This is normally
8618 enabled by default when scheduling before register allocation, i.e.@:
8619 with @option{-fschedule-insns} or at @option{-O2} or higher.
8621 @item -fsched-pressure
8622 @opindex fsched-pressure
8623 Enable register pressure sensitive insn scheduling before register
8624 allocation.  This only makes sense when scheduling before register
8625 allocation is enabled, i.e.@: with @option{-fschedule-insns} or at
8626 @option{-O2} or higher.  Usage of this option can improve the
8627 generated code and decrease its size by preventing register pressure
8628 increase above the number of available hard registers and subsequent
8629 spills in register allocation.
8631 @item -fsched-spec-load
8632 @opindex fsched-spec-load
8633 Allow speculative motion of some load instructions.  This only makes
8634 sense when scheduling before register allocation, i.e.@: with
8635 @option{-fschedule-insns} or at @option{-O2} or higher.
8637 @item -fsched-spec-load-dangerous
8638 @opindex fsched-spec-load-dangerous
8639 Allow speculative motion of more load instructions.  This only makes
8640 sense when scheduling before register allocation, i.e.@: with
8641 @option{-fschedule-insns} or at @option{-O2} or higher.
8643 @item -fsched-stalled-insns
8644 @itemx -fsched-stalled-insns=@var{n}
8645 @opindex fsched-stalled-insns
8646 Define how many insns (if any) can be moved prematurely from the queue
8647 of stalled insns into the ready list during the second scheduling pass.
8648 @option{-fno-sched-stalled-insns} means that no insns are moved
8649 prematurely, @option{-fsched-stalled-insns=0} means there is no limit
8650 on how many queued insns can be moved prematurely.
8651 @option{-fsched-stalled-insns} without a value is equivalent to
8652 @option{-fsched-stalled-insns=1}.
8654 @item -fsched-stalled-insns-dep
8655 @itemx -fsched-stalled-insns-dep=@var{n}
8656 @opindex fsched-stalled-insns-dep
8657 Define how many insn groups (cycles) are examined for a dependency
8658 on a stalled insn that is a candidate for premature removal from the queue
8659 of stalled insns.  This has an effect only during the second scheduling pass,
8660 and only if @option{-fsched-stalled-insns} is used.
8661 @option{-fno-sched-stalled-insns-dep} is equivalent to
8662 @option{-fsched-stalled-insns-dep=0}.
8663 @option{-fsched-stalled-insns-dep} without a value is equivalent to
8664 @option{-fsched-stalled-insns-dep=1}.
8666 @item -fsched2-use-superblocks
8667 @opindex fsched2-use-superblocks
8668 When scheduling after register allocation, use superblock scheduling.
8669 This allows motion across basic block boundaries,
8670 resulting in faster schedules.  This option is experimental, as not all machine
8671 descriptions used by GCC model the CPU closely enough to avoid unreliable
8672 results from the algorithm.
8674 This only makes sense when scheduling after register allocation, i.e.@: with
8675 @option{-fschedule-insns2} or at @option{-O2} or higher.
8677 @item -fsched-group-heuristic
8678 @opindex fsched-group-heuristic
8679 Enable the group heuristic in the scheduler.  This heuristic favors
8680 the instruction that belongs to a schedule group.  This is enabled
8681 by default when scheduling is enabled, i.e.@: with @option{-fschedule-insns}
8682 or @option{-fschedule-insns2} or at @option{-O2} or higher.
8684 @item -fsched-critical-path-heuristic
8685 @opindex fsched-critical-path-heuristic
8686 Enable the critical-path heuristic in the scheduler.  This heuristic favors
8687 instructions on the critical path.  This is enabled by default when
8688 scheduling is enabled, i.e.@: with @option{-fschedule-insns}
8689 or @option{-fschedule-insns2} or at @option{-O2} or higher.
8691 @item -fsched-spec-insn-heuristic
8692 @opindex fsched-spec-insn-heuristic
8693 Enable the speculative instruction heuristic in the scheduler.  This
8694 heuristic favors speculative instructions with greater dependency weakness.
8695 This is enabled by default when scheduling is enabled, i.e.@:
8696 with @option{-fschedule-insns} or @option{-fschedule-insns2}
8697 or at @option{-O2} or higher.
8699 @item -fsched-rank-heuristic
8700 @opindex fsched-rank-heuristic
8701 Enable the rank heuristic in the scheduler.  This heuristic favors
8702 the instruction belonging to a basic block with greater size or frequency.
8703 This is enabled by default when scheduling is enabled, i.e.@:
8704 with @option{-fschedule-insns} or @option{-fschedule-insns2} or
8705 at @option{-O2} or higher.
8707 @item -fsched-last-insn-heuristic
8708 @opindex fsched-last-insn-heuristic
8709 Enable the last-instruction heuristic in the scheduler.  This heuristic
8710 favors the instruction that is less dependent on the last instruction
8711 scheduled.  This is enabled by default when scheduling is enabled,
8712 i.e.@: with @option{-fschedule-insns} or @option{-fschedule-insns2} or
8713 at @option{-O2} or higher.
8715 @item -fsched-dep-count-heuristic
8716 @opindex fsched-dep-count-heuristic
8717 Enable the dependent-count heuristic in the scheduler.  This heuristic
8718 favors the instruction that has more instructions depending on it.
8719 This is enabled by default when scheduling is enabled, i.e.@:
8720 with @option{-fschedule-insns} or @option{-fschedule-insns2} or
8721 at @option{-O2} or higher.
8723 @item -freschedule-modulo-scheduled-loops
8724 @opindex freschedule-modulo-scheduled-loops
8725 Modulo scheduling is performed before traditional scheduling.  If a loop
8726 is modulo scheduled, later scheduling passes may change its schedule.  
8727 Use this option to control that behavior.
8729 @item -fselective-scheduling
8730 @opindex fselective-scheduling
8731 Schedule instructions using selective scheduling algorithm.  Selective
8732 scheduling runs instead of the first scheduler pass.
8734 @item -fselective-scheduling2
8735 @opindex fselective-scheduling2
8736 Schedule instructions using selective scheduling algorithm.  Selective
8737 scheduling runs instead of the second scheduler pass.
8739 @item -fsel-sched-pipelining
8740 @opindex fsel-sched-pipelining
8741 Enable software pipelining of innermost loops during selective scheduling.
8742 This option has no effect unless one of @option{-fselective-scheduling} or
8743 @option{-fselective-scheduling2} is turned on.
8745 @item -fsel-sched-pipelining-outer-loops
8746 @opindex fsel-sched-pipelining-outer-loops
8747 When pipelining loops during selective scheduling, also pipeline outer loops.
8748 This option has no effect unless @option{-fsel-sched-pipelining} is turned on.
8750 @item -fsemantic-interposition
8751 @opindex fsemantic-interposition
8752 Some object formats, like ELF, allow interposing of symbols by the 
8753 dynamic linker.
8754 This means that for symbols exported from the DSO, the compiler cannot perform
8755 interprocedural propagation, inlining and other optimizations in anticipation
8756 that the function or variable in question may change. While this feature is
8757 useful, for example, to rewrite memory allocation functions by a debugging
8758 implementation, it is expensive in the terms of code quality.
8759 With @option{-fno-semantic-interposition} the compiler assumes that 
8760 if interposition happens for functions the overwriting function will have 
8761 precisely the same semantics (and side effects). 
8762 Similarly if interposition happens
8763 for variables, the constructor of the variable will be the same. The flag
8764 has no effect for functions explicitly declared inline 
8765 (where it is never allowed for interposition to change semantics) 
8766 and for symbols explicitly declared weak.
8768 @item -fshrink-wrap
8769 @opindex fshrink-wrap
8770 Emit function prologues only before parts of the function that need it,
8771 rather than at the top of the function.  This flag is enabled by default at
8772 @option{-O} and higher.
8774 @item -fshrink-wrap-separate
8775 @opindex fshrink-wrap-separate
8776 Shrink-wrap separate parts of the prologue and epilogue separately, so that
8777 those parts are only executed when needed.
8778 This option is on by default, but has no effect unless @option{-fshrink-wrap}
8779 is also turned on and the target supports this.
8781 @item -fcaller-saves
8782 @opindex fcaller-saves
8783 Enable allocation of values to registers that are clobbered by
8784 function calls, by emitting extra instructions to save and restore the
8785 registers around such calls.  Such allocation is done only when it
8786 seems to result in better code.
8788 This option is always enabled by default on certain machines, usually
8789 those which have no call-preserved registers to use instead.
8791 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
8793 @item -fcombine-stack-adjustments
8794 @opindex fcombine-stack-adjustments
8795 Tracks stack adjustments (pushes and pops) and stack memory references
8796 and then tries to find ways to combine them.
8798 Enabled by default at @option{-O1} and higher.
8800 @item -fipa-ra
8801 @opindex fipa-ra
8802 Use caller save registers for allocation if those registers are not used by
8803 any called function.  In that case it is not necessary to save and restore
8804 them around calls.  This is only possible if called functions are part of
8805 same compilation unit as current function and they are compiled before it.
8807 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}, however the option
8808 is disabled if generated code will be instrumented for profiling
8809 (@option{-p}, or @option{-pg}) or if callee's register usage cannot be known
8810 exactly (this happens on targets that do not expose prologues
8811 and epilogues in RTL).
8813 @item -fconserve-stack
8814 @opindex fconserve-stack
8815 Attempt to minimize stack usage.  The compiler attempts to use less
8816 stack space, even if that makes the program slower.  This option
8817 implies setting the @option{large-stack-frame} parameter to 100
8818 and the @option{large-stack-frame-growth} parameter to 400.
8820 @item -ftree-reassoc
8821 @opindex ftree-reassoc
8822 Perform reassociation on trees.  This flag is enabled by default
8823 at @option{-O} and higher.
8825 @item -fcode-hoisting
8826 @opindex fcode-hoisting
8827 Perform code hoisting.  Code hoisting tries to move the
8828 evaluation of expressions executed on all paths to the function exit
8829 as early as possible.  This is especially useful as a code size
8830 optimization, but it often helps for code speed as well.
8831 This flag is enabled by default at @option{-O2} and higher.
8833 @item -ftree-pre
8834 @opindex ftree-pre
8835 Perform partial redundancy elimination (PRE) on trees.  This flag is
8836 enabled by default at @option{-O2} and @option{-O3}.
8838 @item -ftree-partial-pre
8839 @opindex ftree-partial-pre
8840 Make partial redundancy elimination (PRE) more aggressive.  This flag is
8841 enabled by default at @option{-O3}.
8843 @item -ftree-forwprop
8844 @opindex ftree-forwprop
8845 Perform forward propagation on trees.  This flag is enabled by default
8846 at @option{-O} and higher.
8848 @item -ftree-fre
8849 @opindex ftree-fre
8850 Perform full redundancy elimination (FRE) on trees.  The difference
8851 between FRE and PRE is that FRE only considers expressions
8852 that are computed on all paths leading to the redundant computation.
8853 This analysis is faster than PRE, though it exposes fewer redundancies.
8854 This flag is enabled by default at @option{-O} and higher.
8856 @item -ftree-phiprop
8857 @opindex ftree-phiprop
8858 Perform hoisting of loads from conditional pointers on trees.  This
8859 pass is enabled by default at @option{-O} and higher.
8861 @item -fhoist-adjacent-loads
8862 @opindex fhoist-adjacent-loads
8863 Speculatively hoist loads from both branches of an if-then-else if the
8864 loads are from adjacent locations in the same structure and the target
8865 architecture has a conditional move instruction.  This flag is enabled
8866 by default at @option{-O2} and higher.
8868 @item -ftree-copy-prop
8869 @opindex ftree-copy-prop
8870 Perform copy propagation on trees.  This pass eliminates unnecessary
8871 copy operations.  This flag is enabled by default at @option{-O} and
8872 higher.
8874 @item -fipa-pure-const
8875 @opindex fipa-pure-const
8876 Discover which functions are pure or constant.
8877 Enabled by default at @option{-O} and higher.
8879 @item -fipa-reference
8880 @opindex fipa-reference
8881 Discover which static variables do not escape the
8882 compilation unit.
8883 Enabled by default at @option{-O} and higher.
8885 @item -fipa-pta
8886 @opindex fipa-pta
8887 Perform interprocedural pointer analysis and interprocedural modification
8888 and reference analysis.  This option can cause excessive memory and
8889 compile-time usage on large compilation units.  It is not enabled by
8890 default at any optimization level.
8892 @item -fipa-profile
8893 @opindex fipa-profile
8894 Perform interprocedural profile propagation.  The functions called only from
8895 cold functions are marked as cold. Also functions executed once (such as
8896 @code{cold}, @code{noreturn}, static constructors or destructors) are identified. Cold
8897 functions and loop less parts of functions executed once are then optimized for
8898 size.
8899 Enabled by default at @option{-O} and higher.
8901 @item -fipa-cp
8902 @opindex fipa-cp
8903 Perform interprocedural constant propagation.
8904 This optimization analyzes the program to determine when values passed
8905 to functions are constants and then optimizes accordingly.
8906 This optimization can substantially increase performance
8907 if the application has constants passed to functions.
8908 This flag is enabled by default at @option{-O2}, @option{-Os} and @option{-O3}.
8910 @item -fipa-cp-clone
8911 @opindex fipa-cp-clone
8912 Perform function cloning to make interprocedural constant propagation stronger.
8913 When enabled, interprocedural constant propagation performs function cloning
8914 when externally visible function can be called with constant arguments.
8915 Because this optimization can create multiple copies of functions,
8916 it may significantly increase code size
8917 (see @option{--param ipcp-unit-growth=@var{value}}).
8918 This flag is enabled by default at @option{-O3}.
8920 @item -fipa-bit-cp
8921 @opindex -fipa-bit-cp
8922 When enabled, perform interprocedural bitwise constant
8923 propagation. This flag is enabled by default at @option{-O2}. It
8924 requires that @option{-fipa-cp} is enabled.
8926 @item -fipa-vrp
8927 @opindex -fipa-vrp
8928 When enabled, perform interprocedural propagation of value
8929 ranges. This flag is enabled by default at @option{-O2}. It requires
8930 that @option{-fipa-cp} is enabled.
8932 @item -fipa-icf
8933 @opindex fipa-icf
8934 Perform Identical Code Folding for functions and read-only variables.
8935 The optimization reduces code size and may disturb unwind stacks by replacing
8936 a function by equivalent one with a different name. The optimization works
8937 more effectively with link-time optimization enabled.
8939 Nevertheless the behavior is similar to Gold Linker ICF optimization, GCC ICF
8940 works on different levels and thus the optimizations are not same - there are
8941 equivalences that are found only by GCC and equivalences found only by Gold.
8943 This flag is enabled by default at @option{-O2} and @option{-Os}.
8945 @item -fisolate-erroneous-paths-dereference
8946 @opindex fisolate-erroneous-paths-dereference
8947 Detect paths that trigger erroneous or undefined behavior due to
8948 dereferencing a null pointer.  Isolate those paths from the main control
8949 flow and turn the statement with erroneous or undefined behavior into a trap.
8950 This flag is enabled by default at @option{-O2} and higher and depends on
8951 @option{-fdelete-null-pointer-checks} also being enabled.
8953 @item -fisolate-erroneous-paths-attribute
8954 @opindex fisolate-erroneous-paths-attribute
8955 Detect paths that trigger erroneous or undefined behavior due to a null value
8956 being used in a way forbidden by a @code{returns_nonnull} or @code{nonnull}
8957 attribute.  Isolate those paths from the main control flow and turn the
8958 statement with erroneous or undefined behavior into a trap.  This is not
8959 currently enabled, but may be enabled by @option{-O2} in the future.
8961 @item -ftree-sink
8962 @opindex ftree-sink
8963 Perform forward store motion on trees.  This flag is
8964 enabled by default at @option{-O} and higher.
8966 @item -ftree-bit-ccp
8967 @opindex ftree-bit-ccp
8968 Perform sparse conditional bit constant propagation on trees and propagate
8969 pointer alignment information.
8970 This pass only operates on local scalar variables and is enabled by default
8971 at @option{-O} and higher.  It requires that @option{-ftree-ccp} is enabled.
8973 @item -ftree-ccp
8974 @opindex ftree-ccp
8975 Perform sparse conditional constant propagation (CCP) on trees.  This
8976 pass only operates on local scalar variables and is enabled by default
8977 at @option{-O} and higher.
8979 @item -fssa-backprop
8980 @opindex fssa-backprop
8981 Propagate information about uses of a value up the definition chain
8982 in order to simplify the definitions.  For example, this pass strips
8983 sign operations if the sign of a value never matters.  The flag is
8984 enabled by default at @option{-O} and higher.
8986 @item -fssa-phiopt
8987 @opindex fssa-phiopt
8988 Perform pattern matching on SSA PHI nodes to optimize conditional
8989 code.  This pass is enabled by default at @option{-O} and higher.
8991 @item -ftree-switch-conversion
8992 @opindex ftree-switch-conversion
8993 Perform conversion of simple initializations in a switch to
8994 initializations from a scalar array.  This flag is enabled by default
8995 at @option{-O2} and higher.
8997 @item -ftree-tail-merge
8998 @opindex ftree-tail-merge
8999 Look for identical code sequences.  When found, replace one with a jump to the
9000 other.  This optimization is known as tail merging or cross jumping.  This flag
9001 is enabled by default at @option{-O2} and higher.  The compilation time
9002 in this pass can
9003 be limited using @option{max-tail-merge-comparisons} parameter and
9004 @option{max-tail-merge-iterations} parameter.
9006 @item -ftree-dce
9007 @opindex ftree-dce
9008 Perform dead code elimination (DCE) on trees.  This flag is enabled by
9009 default at @option{-O} and higher.
9011 @item -ftree-builtin-call-dce
9012 @opindex ftree-builtin-call-dce
9013 Perform conditional dead code elimination (DCE) for calls to built-in functions
9014 that may set @code{errno} but are otherwise free of side effects.  This flag is
9015 enabled by default at @option{-O2} and higher if @option{-Os} is not also
9016 specified.
9018 @item -ftree-dominator-opts
9019 @opindex ftree-dominator-opts
9020 Perform a variety of simple scalar cleanups (constant/copy
9021 propagation, redundancy elimination, range propagation and expression
9022 simplification) based on a dominator tree traversal.  This also
9023 performs jump threading (to reduce jumps to jumps). This flag is
9024 enabled by default at @option{-O} and higher.
9026 @item -ftree-dse
9027 @opindex ftree-dse
9028 Perform dead store elimination (DSE) on trees.  A dead store is a store into
9029 a memory location that is later overwritten by another store without
9030 any intervening loads.  In this case the earlier store can be deleted.  This
9031 flag is enabled by default at @option{-O} and higher.
9033 @item -ftree-ch
9034 @opindex ftree-ch
9035 Perform loop header copying on trees.  This is beneficial since it increases
9036 effectiveness of code motion optimizations.  It also saves one jump.  This flag
9037 is enabled by default at @option{-O} and higher.  It is not enabled
9038 for @option{-Os}, since it usually increases code size.
9040 @item -ftree-loop-optimize
9041 @opindex ftree-loop-optimize
9042 Perform loop optimizations on trees.  This flag is enabled by default
9043 at @option{-O} and higher.
9045 @item -ftree-loop-linear
9046 @itemx -floop-strip-mine
9047 @itemx -floop-block
9048 @opindex ftree-loop-linear
9049 @opindex floop-strip-mine
9050 @opindex floop-block
9051 Perform loop nest optimizations.  Same as
9052 @option{-floop-nest-optimize}.  To use this code transformation, GCC has
9053 to be configured with @option{--with-isl} to enable the Graphite loop
9054 transformation infrastructure.
9056 @item -fgraphite-identity
9057 @opindex fgraphite-identity
9058 Enable the identity transformation for graphite.  For every SCoP we generate
9059 the polyhedral representation and transform it back to gimple.  Using
9060 @option{-fgraphite-identity} we can check the costs or benefits of the
9061 GIMPLE -> GRAPHITE -> GIMPLE transformation.  Some minimal optimizations
9062 are also performed by the code generator isl, like index splitting and
9063 dead code elimination in loops.
9065 @item -floop-nest-optimize
9066 @opindex floop-nest-optimize
9067 Enable the isl based loop nest optimizer.  This is a generic loop nest
9068 optimizer based on the Pluto optimization algorithms.  It calculates a loop
9069 structure optimized for data-locality and parallelism.  This option
9070 is experimental.
9072 @item -floop-parallelize-all
9073 @opindex floop-parallelize-all
9074 Use the Graphite data dependence analysis to identify loops that can
9075 be parallelized.  Parallelize all the loops that can be analyzed to
9076 not contain loop carried dependences without checking that it is
9077 profitable to parallelize the loops.
9079 @item -ftree-coalesce-vars
9080 @opindex ftree-coalesce-vars
9081 While transforming the program out of the SSA representation, attempt to
9082 reduce copying by coalescing versions of different user-defined
9083 variables, instead of just compiler temporaries.  This may severely
9084 limit the ability to debug an optimized program compiled with
9085 @option{-fno-var-tracking-assignments}.  In the negated form, this flag
9086 prevents SSA coalescing of user variables.  This option is enabled by
9087 default if optimization is enabled, and it does very little otherwise.
9089 @item -ftree-loop-if-convert
9090 @opindex ftree-loop-if-convert
9091 Attempt to transform conditional jumps in the innermost loops to
9092 branch-less equivalents.  The intent is to remove control-flow from
9093 the innermost loops in order to improve the ability of the
9094 vectorization pass to handle these loops.  This is enabled by default
9095 if vectorization is enabled.
9097 @item -ftree-loop-distribution
9098 @opindex ftree-loop-distribution
9099 Perform loop distribution.  This flag can improve cache performance on
9100 big loop bodies and allow further loop optimizations, like
9101 parallelization or vectorization, to take place.  For example, the loop
9102 @smallexample
9103 DO I = 1, N
9104   A(I) = B(I) + C
9105   D(I) = E(I) * F
9106 ENDDO
9107 @end smallexample
9108 is transformed to
9109 @smallexample
9110 DO I = 1, N
9111    A(I) = B(I) + C
9112 ENDDO
9113 DO I = 1, N
9114    D(I) = E(I) * F
9115 ENDDO
9116 @end smallexample
9118 @item -ftree-loop-distribute-patterns
9119 @opindex ftree-loop-distribute-patterns
9120 Perform loop distribution of patterns that can be code generated with
9121 calls to a library.  This flag is enabled by default at @option{-O3}.
9123 This pass distributes the initialization loops and generates a call to
9124 memset zero.  For example, the loop
9125 @smallexample
9126 DO I = 1, N
9127   A(I) = 0
9128   B(I) = A(I) + I
9129 ENDDO
9130 @end smallexample
9131 is transformed to
9132 @smallexample
9133 DO I = 1, N
9134    A(I) = 0
9135 ENDDO
9136 DO I = 1, N
9137    B(I) = A(I) + I
9138 ENDDO
9139 @end smallexample
9140 and the initialization loop is transformed into a call to memset zero.
9142 @item -floop-interchange
9143 @opindex floop-interchange
9144 Perform loop interchange outside of graphite.  This flag can improve cache
9145 performance on loop nest and allow further loop optimizations, like
9146 vectorization, to take place.  For example, the loop
9147 @smallexample
9148 for (int i = 0; i < N; i++)
9149   for (int j = 0; j < N; j++)
9150     for (int k = 0; k < N; k++)
9151       c[i][j] = c[i][j] + a[i][k]*b[k][j];
9152 @end smallexample
9153 is transformed to
9154 @smallexample
9155 for (int i = 0; i < N; i++)
9156   for (int k = 0; k < N; k++)
9157     for (int j = 0; j < N; j++)
9158       c[i][j] = c[i][j] + a[i][k]*b[k][j];
9159 @end smallexample
9160 This flag is enabled by default at @option{-O3}.
9162 @item -floop-unroll-and-jam
9163 @opindex floop-unroll-and-jam
9164 Apply unroll and jam transformations on feasible loops.  In a loop
9165 nest this unrolls the outer loop by some factor and fuses the resulting
9166 multiple inner loops.  This flag is enabled by default at @option{-O3}.
9168 @item -ftree-loop-im
9169 @opindex ftree-loop-im
9170 Perform loop invariant motion on trees.  This pass moves only invariants that
9171 are hard to handle at RTL level (function calls, operations that expand to
9172 nontrivial sequences of insns).  With @option{-funswitch-loops} it also moves
9173 operands of conditions that are invariant out of the loop, so that we can use
9174 just trivial invariantness analysis in loop unswitching.  The pass also includes
9175 store motion.
9177 @item -ftree-loop-ivcanon
9178 @opindex ftree-loop-ivcanon
9179 Create a canonical counter for number of iterations in loops for which
9180 determining number of iterations requires complicated analysis.  Later
9181 optimizations then may determine the number easily.  Useful especially
9182 in connection with unrolling.
9184 @item -ftree-scev-cprop
9185 @opindex ftree-scev-cprop
9186 Perform final value replacement.  If a variable is modified in a loop
9187 in such a way that its value when exiting the loop can be determined using
9188 only its initial value and the number of loop iterations, replace uses of
9189 the final value by such a computation, provided it is sufficiently cheap.
9190 This reduces data dependencies and may allow further simplifications.
9191 Enabled by default at @option{-O} and higher.
9193 @item -fivopts
9194 @opindex fivopts
9195 Perform induction variable optimizations (strength reduction, induction
9196 variable merging and induction variable elimination) on trees.
9198 @item -ftree-parallelize-loops=n
9199 @opindex ftree-parallelize-loops
9200 Parallelize loops, i.e., split their iteration space to run in n threads.
9201 This is only possible for loops whose iterations are independent
9202 and can be arbitrarily reordered.  The optimization is only
9203 profitable on multiprocessor machines, for loops that are CPU-intensive,
9204 rather than constrained e.g.@: by memory bandwidth.  This option
9205 implies @option{-pthread}, and thus is only supported on targets
9206 that have support for @option{-pthread}.
9208 @item -ftree-pta
9209 @opindex ftree-pta
9210 Perform function-local points-to analysis on trees.  This flag is
9211 enabled by default at @option{-O} and higher.
9213 @item -ftree-sra
9214 @opindex ftree-sra
9215 Perform scalar replacement of aggregates.  This pass replaces structure
9216 references with scalars to prevent committing structures to memory too
9217 early.  This flag is enabled by default at @option{-O} and higher.
9219 @item -fstore-merging
9220 @opindex fstore-merging
9221 Perform merging of narrow stores to consecutive memory addresses.  This pass
9222 merges contiguous stores of immediate values narrower than a word into fewer
9223 wider stores to reduce the number of instructions.  This is enabled by default
9224 at @option{-O2} and higher as well as @option{-Os}.
9226 @item -ftree-ter
9227 @opindex ftree-ter
9228 Perform temporary expression replacement during the SSA->normal phase.  Single
9229 use/single def temporaries are replaced at their use location with their
9230 defining expression.  This results in non-GIMPLE code, but gives the expanders
9231 much more complex trees to work on resulting in better RTL generation.  This is
9232 enabled by default at @option{-O} and higher.
9234 @item -ftree-slsr
9235 @opindex ftree-slsr
9236 Perform straight-line strength reduction on trees.  This recognizes related
9237 expressions involving multiplications and replaces them by less expensive
9238 calculations when possible.  This is enabled by default at @option{-O} and
9239 higher.
9241 @item -ftree-vectorize
9242 @opindex ftree-vectorize
9243 Perform vectorization on trees. This flag enables @option{-ftree-loop-vectorize}
9244 and @option{-ftree-slp-vectorize} if not explicitly specified.
9246 @item -ftree-loop-vectorize
9247 @opindex ftree-loop-vectorize
9248 Perform loop vectorization on trees. This flag is enabled by default at
9249 @option{-O3} and when @option{-ftree-vectorize} is enabled.
9251 @item -ftree-slp-vectorize
9252 @opindex ftree-slp-vectorize
9253 Perform basic block vectorization on trees. This flag is enabled by default at
9254 @option{-O3} and when @option{-ftree-vectorize} is enabled.
9256 @item -fvect-cost-model=@var{model}
9257 @opindex fvect-cost-model
9258 Alter the cost model used for vectorization.  The @var{model} argument
9259 should be one of @samp{unlimited}, @samp{dynamic} or @samp{cheap}.
9260 With the @samp{unlimited} model the vectorized code-path is assumed
9261 to be profitable while with the @samp{dynamic} model a runtime check
9262 guards the vectorized code-path to enable it only for iteration
9263 counts that will likely execute faster than when executing the original
9264 scalar loop.  The @samp{cheap} model disables vectorization of
9265 loops where doing so would be cost prohibitive for example due to
9266 required runtime checks for data dependence or alignment but otherwise
9267 is equal to the @samp{dynamic} model.
9268 The default cost model depends on other optimization flags and is
9269 either @samp{dynamic} or @samp{cheap}.
9271 @item -fsimd-cost-model=@var{model}
9272 @opindex fsimd-cost-model
9273 Alter the cost model used for vectorization of loops marked with the OpenMP
9274 simd directive.  The @var{model} argument should be one of
9275 @samp{unlimited}, @samp{dynamic}, @samp{cheap}.  All values of @var{model}
9276 have the same meaning as described in @option{-fvect-cost-model} and by
9277 default a cost model defined with @option{-fvect-cost-model} is used.
9279 @item -ftree-vrp
9280 @opindex ftree-vrp
9281 Perform Value Range Propagation on trees.  This is similar to the
9282 constant propagation pass, but instead of values, ranges of values are
9283 propagated.  This allows the optimizers to remove unnecessary range
9284 checks like array bound checks and null pointer checks.  This is
9285 enabled by default at @option{-O2} and higher.  Null pointer check
9286 elimination is only done if @option{-fdelete-null-pointer-checks} is
9287 enabled.
9289 @item -fsplit-paths
9290 @opindex fsplit-paths
9291 Split paths leading to loop backedges.  This can improve dead code
9292 elimination and common subexpression elimination.  This is enabled by
9293 default at @option{-O2} and above.
9295 @item -fsplit-ivs-in-unroller
9296 @opindex fsplit-ivs-in-unroller
9297 Enables expression of values of induction variables in later iterations
9298 of the unrolled loop using the value in the first iteration.  This breaks
9299 long dependency chains, thus improving efficiency of the scheduling passes.
9301 A combination of @option{-fweb} and CSE is often sufficient to obtain the
9302 same effect.  However, that is not reliable in cases where the loop body
9303 is more complicated than a single basic block.  It also does not work at all
9304 on some architectures due to restrictions in the CSE pass.
9306 This optimization is enabled by default.
9308 @item -fvariable-expansion-in-unroller
9309 @opindex fvariable-expansion-in-unroller
9310 With this option, the compiler creates multiple copies of some
9311 local variables when unrolling a loop, which can result in superior code.
9313 @item -fpartial-inlining
9314 @opindex fpartial-inlining
9315 Inline parts of functions.  This option has any effect only
9316 when inlining itself is turned on by the @option{-finline-functions}
9317 or @option{-finline-small-functions} options.
9319 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
9321 @item -fpredictive-commoning
9322 @opindex fpredictive-commoning
9323 Perform predictive commoning optimization, i.e., reusing computations
9324 (especially memory loads and stores) performed in previous
9325 iterations of loops.
9327 This option is enabled at level @option{-O3}.
9329 @item -fprefetch-loop-arrays
9330 @opindex fprefetch-loop-arrays
9331 If supported by the target machine, generate instructions to prefetch
9332 memory to improve the performance of loops that access large arrays.
9334 This option may generate better or worse code; results are highly
9335 dependent on the structure of loops within the source code.
9337 Disabled at level @option{-Os}.
9339 @item -fno-printf-return-value
9340 @opindex fno-printf-return-value
9341 Do not substitute constants for known return value of formatted output
9342 functions such as @code{sprintf}, @code{snprintf}, @code{vsprintf}, and
9343 @code{vsnprintf} (but not @code{printf} of @code{fprintf}).  This
9344 transformation allows GCC to optimize or even eliminate branches based
9345 on the known return value of these functions called with arguments that
9346 are either constant, or whose values are known to be in a range that
9347 makes determining the exact return value possible.  For example, when
9348 @option{-fprintf-return-value} is in effect, both the branch and the
9349 body of the @code{if} statement (but not the call to @code{snprint})
9350 can be optimized away when @code{i} is a 32-bit or smaller integer
9351 because the return value is guaranteed to be at most 8.
9353 @smallexample
9354 char buf[9];
9355 if (snprintf (buf, "%08x", i) >= sizeof buf)
9356   @dots{}
9357 @end smallexample
9359 The @option{-fprintf-return-value} option relies on other optimizations
9360 and yields best results with @option{-O2} and above.  It works in tandem
9361 with the @option{-Wformat-overflow} and @option{-Wformat-truncation}
9362 options.  The @option{-fprintf-return-value} option is enabled by default.
9364 @item -fno-peephole
9365 @itemx -fno-peephole2
9366 @opindex fno-peephole
9367 @opindex fno-peephole2
9368 Disable any machine-specific peephole optimizations.  The difference
9369 between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
9370 are implemented in the compiler; some targets use one, some use the
9371 other, a few use both.
9373 @option{-fpeephole} is enabled by default.
9374 @option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
9376 @item -fno-guess-branch-probability
9377 @opindex fno-guess-branch-probability
9378 Do not guess branch probabilities using heuristics.
9380 GCC uses heuristics to guess branch probabilities if they are
9381 not provided by profiling feedback (@option{-fprofile-arcs}).  These
9382 heuristics are based on the control flow graph.  If some branch probabilities
9383 are specified by @code{__builtin_expect}, then the heuristics are
9384 used to guess branch probabilities for the rest of the control flow graph,
9385 taking the @code{__builtin_expect} info into account.  The interactions
9386 between the heuristics and @code{__builtin_expect} can be complex, and in
9387 some cases, it may be useful to disable the heuristics so that the effects
9388 of @code{__builtin_expect} are easier to understand.
9390 It is also possible to specify expected probability of the expression
9391 with @code{__builtin_expect_with_probability} built-in function.
9393 The default is @option{-fguess-branch-probability} at levels
9394 @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
9396 @item -freorder-blocks
9397 @opindex freorder-blocks
9398 Reorder basic blocks in the compiled function in order to reduce number of
9399 taken branches and improve code locality.
9401 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
9403 @item -freorder-blocks-algorithm=@var{algorithm}
9404 @opindex freorder-blocks-algorithm
9405 Use the specified algorithm for basic block reordering.  The
9406 @var{algorithm} argument can be @samp{simple}, which does not increase
9407 code size (except sometimes due to secondary effects like alignment),
9408 or @samp{stc}, the ``software trace cache'' algorithm, which tries to
9409 put all often executed code together, minimizing the number of branches
9410 executed by making extra copies of code.
9412 The default is @samp{simple} at levels @option{-O}, @option{-Os}, and
9413 @samp{stc} at levels @option{-O2}, @option{-O3}.
9415 @item -freorder-blocks-and-partition
9416 @opindex freorder-blocks-and-partition
9417 In addition to reordering basic blocks in the compiled function, in order
9418 to reduce number of taken branches, partitions hot and cold basic blocks
9419 into separate sections of the assembly and @file{.o} files, to improve
9420 paging and cache locality performance.
9422 This optimization is automatically turned off in the presence of
9423 exception handling or unwind tables (on targets using setjump/longjump or target specific scheme), for linkonce sections, for functions with a user-defined
9424 section attribute and on any architecture that does not support named
9425 sections.  When @option{-fsplit-stack} is used this option is not
9426 enabled by default (to avoid linker errors), but may be enabled
9427 explicitly (if using a working linker).
9429 Enabled for x86 at levels @option{-O2}, @option{-O3}, @option{-Os}.
9431 @item -freorder-functions
9432 @opindex freorder-functions
9433 Reorder functions in the object file in order to
9434 improve code locality.  This is implemented by using special
9435 subsections @code{.text.hot} for most frequently executed functions and
9436 @code{.text.unlikely} for unlikely executed functions.  Reordering is done by
9437 the linker so object file format must support named sections and linker must
9438 place them in a reasonable way.
9440 Also profile feedback must be available to make this option effective.  See
9441 @option{-fprofile-arcs} for details.
9443 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
9445 @item -fstrict-aliasing
9446 @opindex fstrict-aliasing
9447 Allow the compiler to assume the strictest aliasing rules applicable to
9448 the language being compiled.  For C (and C++), this activates
9449 optimizations based on the type of expressions.  In particular, an
9450 object of one type is assumed never to reside at the same address as an
9451 object of a different type, unless the types are almost the same.  For
9452 example, an @code{unsigned int} can alias an @code{int}, but not a
9453 @code{void*} or a @code{double}.  A character type may alias any other
9454 type.
9456 @anchor{Type-punning}Pay special attention to code like this:
9457 @smallexample
9458 union a_union @{
9459   int i;
9460   double d;
9463 int f() @{
9464   union a_union t;
9465   t.d = 3.0;
9466   return t.i;
9468 @end smallexample
9469 The practice of reading from a different union member than the one most
9470 recently written to (called ``type-punning'') is common.  Even with
9471 @option{-fstrict-aliasing}, type-punning is allowed, provided the memory
9472 is accessed through the union type.  So, the code above works as
9473 expected.  @xref{Structures unions enumerations and bit-fields
9474 implementation}.  However, this code might not:
9475 @smallexample
9476 int f() @{
9477   union a_union t;
9478   int* ip;
9479   t.d = 3.0;
9480   ip = &t.i;
9481   return *ip;
9483 @end smallexample
9485 Similarly, access by taking the address, casting the resulting pointer
9486 and dereferencing the result has undefined behavior, even if the cast
9487 uses a union type, e.g.:
9488 @smallexample
9489 int f() @{
9490   double d = 3.0;
9491   return ((union a_union *) &d)->i;
9493 @end smallexample
9495 The @option{-fstrict-aliasing} option is enabled at levels
9496 @option{-O2}, @option{-O3}, @option{-Os}.
9498 @item -falign-functions
9499 @itemx -falign-functions=@var{n}
9500 @itemx -falign-functions=@var{n}:@var{m}
9501 @itemx -falign-functions=@var{n}:@var{m}:@var{n2}
9502 @itemx -falign-functions=@var{n}:@var{m}:@var{n2}:@var{m2}
9503 @opindex falign-functions
9504 Align the start of functions to the next power-of-two greater than
9505 @var{n}, skipping up to @var{m}-1 bytes.  This ensures that at least
9506 the first @var{m} bytes of the function can be fetched by the CPU
9507 without crossing an @var{n}-byte alignment boundary.
9509 If @var{m} is not specified, it defaults to @var{n}.
9511 Examples: @option{-falign-functions=32} aligns functions to the next
9512 32-byte boundary, @option{-falign-functions=24} aligns to the next
9513 32-byte boundary only if this can be done by skipping 23 bytes or less,
9514 @option{-falign-functions=32:7} aligns to the next
9515 32-byte boundary only if this can be done by skipping 6 bytes or less.
9517 The second pair of @var{n2}:@var{m2} values allows you to specify
9518 a secondary alignment: @option{-falign-functions=64:7:32:3} aligns to
9519 the next 64-byte boundary if this can be done by skipping 6 bytes or less,
9520 otherwise aligns to the next 32-byte boundary if this can be done
9521 by skipping 2 bytes or less.
9522 If @var{m2} is not specified, it defaults to @var{n2}.
9524 Some assemblers only support this flag when @var{n} is a power of two;
9525 in that case, it is rounded up.
9527 @option{-fno-align-functions} and @option{-falign-functions=1} are
9528 equivalent and mean that functions are not aligned.
9530 If @var{n} is not specified or is zero, use a machine-dependent default.
9531 The maximum allowed @var{n} option value is 65536.
9533 Enabled at levels @option{-O2}, @option{-O3}.
9535 @item -flimit-function-alignment
9536 If this option is enabled, the compiler tries to avoid unnecessarily
9537 overaligning functions. It attempts to instruct the assembler to align
9538 by the amount specified by @option{-falign-functions}, but not to
9539 skip more bytes than the size of the function.
9541 @item -falign-labels
9542 @itemx -falign-labels=@var{n}
9543 @itemx -falign-labels=@var{n}:@var{m}
9544 @itemx -falign-labels=@var{n}:@var{m}:@var{n2}
9545 @itemx -falign-labels=@var{n}:@var{m}:@var{n2}:@var{m2}
9546 @opindex falign-labels
9547 Align all branch targets to a power-of-two boundary.
9549 Parameters of this option are analogous to the @option{-falign-functions} option.
9550 @option{-fno-align-labels} and @option{-falign-labels=1} are
9551 equivalent and mean that labels are not aligned.
9553 If @option{-falign-loops} or @option{-falign-jumps} are applicable and
9554 are greater than this value, then their values are used instead.
9556 If @var{n} is not specified or is zero, use a machine-dependent default
9557 which is very likely to be @samp{1}, meaning no alignment.
9558 The maximum allowed @var{n} option value is 65536.
9560 Enabled at levels @option{-O2}, @option{-O3}.
9562 @item -falign-loops
9563 @itemx -falign-loops=@var{n}
9564 @itemx -falign-loops=@var{n}:@var{m}
9565 @itemx -falign-loops=@var{n}:@var{m}:@var{n2}
9566 @itemx -falign-loops=@var{n}:@var{m}:@var{n2}:@var{m2}
9567 @opindex falign-loops
9568 Align loops to a power-of-two boundary.  If the loops are executed
9569 many times, this makes up for any execution of the dummy padding
9570 instructions.
9572 Parameters of this option are analogous to the @option{-falign-functions} option.
9573 @option{-fno-align-loops} and @option{-falign-loops=1} are
9574 equivalent and mean that loops are not aligned.
9575 The maximum allowed @var{n} option value is 65536.
9577 If @var{n} is not specified or is zero, use a machine-dependent default.
9579 Enabled at levels @option{-O2}, @option{-O3}.
9581 @item -falign-jumps
9582 @itemx -falign-jumps=@var{n}
9583 @itemx -falign-jumps=@var{n}:@var{m}
9584 @itemx -falign-jumps=@var{n}:@var{m}:@var{n2}
9585 @itemx -falign-jumps=@var{n}:@var{m}:@var{n2}:@var{m2}
9586 @opindex falign-jumps
9587 Align branch targets to a power-of-two boundary, for branch targets
9588 where the targets can only be reached by jumping.  In this case,
9589 no dummy operations need be executed.
9591 Parameters of this option are analogous to the @option{-falign-functions} option.
9592 @option{-fno-align-jumps} and @option{-falign-jumps=1} are
9593 equivalent and mean that loops are not aligned.
9595 If @var{n} is not specified or is zero, use a machine-dependent default.
9596 The maximum allowed @var{n} option value is 65536.
9598 Enabled at levels @option{-O2}, @option{-O3}.
9600 @item -funit-at-a-time
9601 @opindex funit-at-a-time
9602 This option is left for compatibility reasons. @option{-funit-at-a-time}
9603 has no effect, while @option{-fno-unit-at-a-time} implies
9604 @option{-fno-toplevel-reorder} and @option{-fno-section-anchors}.
9606 Enabled by default.
9608 @item -fno-toplevel-reorder
9609 @opindex fno-toplevel-reorder
9610 Do not reorder top-level functions, variables, and @code{asm}
9611 statements.  Output them in the same order that they appear in the
9612 input file.  When this option is used, unreferenced static variables
9613 are not removed.  This option is intended to support existing code
9614 that relies on a particular ordering.  For new code, it is better to
9615 use attributes when possible.
9617 Enabled at level @option{-O0}.  When disabled explicitly, it also implies
9618 @option{-fno-section-anchors}, which is otherwise enabled at @option{-O0} on some
9619 targets.
9621 @item -fweb
9622 @opindex fweb
9623 Constructs webs as commonly used for register allocation purposes and assign
9624 each web individual pseudo register.  This allows the register allocation pass
9625 to operate on pseudos directly, but also strengthens several other optimization
9626 passes, such as CSE, loop optimizer and trivial dead code remover.  It can,
9627 however, make debugging impossible, since variables no longer stay in a
9628 ``home register''.
9630 Enabled by default with @option{-funroll-loops}.
9632 @item -fwhole-program
9633 @opindex fwhole-program
9634 Assume that the current compilation unit represents the whole program being
9635 compiled.  All public functions and variables with the exception of @code{main}
9636 and those merged by attribute @code{externally_visible} become static functions
9637 and in effect are optimized more aggressively by interprocedural optimizers.
9639 This option should not be used in combination with @option{-flto}.
9640 Instead relying on a linker plugin should provide safer and more precise
9641 information.
9643 @item -flto[=@var{n}]
9644 @opindex flto
9645 This option runs the standard link-time optimizer.  When invoked
9646 with source code, it generates GIMPLE (one of GCC's internal
9647 representations) and writes it to special ELF sections in the object
9648 file.  When the object files are linked together, all the function
9649 bodies are read from these ELF sections and instantiated as if they
9650 had been part of the same translation unit.
9652 To use the link-time optimizer, @option{-flto} and optimization
9653 options should be specified at compile time and during the final link.
9654 It is recommended that you compile all the files participating in the
9655 same link with the same options and also specify those options at
9656 link time.  
9657 For example:
9659 @smallexample
9660 gcc -c -O2 -flto foo.c
9661 gcc -c -O2 -flto bar.c
9662 gcc -o myprog -flto -O2 foo.o bar.o
9663 @end smallexample
9665 The first two invocations to GCC save a bytecode representation
9666 of GIMPLE into special ELF sections inside @file{foo.o} and
9667 @file{bar.o}.  The final invocation reads the GIMPLE bytecode from
9668 @file{foo.o} and @file{bar.o}, merges the two files into a single
9669 internal image, and compiles the result as usual.  Since both
9670 @file{foo.o} and @file{bar.o} are merged into a single image, this
9671 causes all the interprocedural analyses and optimizations in GCC to
9672 work across the two files as if they were a single one.  This means,
9673 for example, that the inliner is able to inline functions in
9674 @file{bar.o} into functions in @file{foo.o} and vice-versa.
9676 Another (simpler) way to enable link-time optimization is:
9678 @smallexample
9679 gcc -o myprog -flto -O2 foo.c bar.c
9680 @end smallexample
9682 The above generates bytecode for @file{foo.c} and @file{bar.c},
9683 merges them together into a single GIMPLE representation and optimizes
9684 them as usual to produce @file{myprog}.
9686 The only important thing to keep in mind is that to enable link-time
9687 optimizations you need to use the GCC driver to perform the link step.
9688 GCC then automatically performs link-time optimization if any of the
9689 objects involved were compiled with the @option{-flto} command-line option.  
9690 You generally
9691 should specify the optimization options to be used for link-time
9692 optimization though GCC tries to be clever at guessing an
9693 optimization level to use from the options used at compile time
9694 if you fail to specify one at link time.  You can always override
9695 the automatic decision to do link-time optimization
9696 by passing @option{-fno-lto} to the link command.
9698 To make whole program optimization effective, it is necessary to make
9699 certain whole program assumptions.  The compiler needs to know
9700 what functions and variables can be accessed by libraries and runtime
9701 outside of the link-time optimized unit.  When supported by the linker,
9702 the linker plugin (see @option{-fuse-linker-plugin}) passes information
9703 to the compiler about used and externally visible symbols.  When
9704 the linker plugin is not available, @option{-fwhole-program} should be
9705 used to allow the compiler to make these assumptions, which leads
9706 to more aggressive optimization decisions.
9708 When @option{-fuse-linker-plugin} is not enabled, when a file is
9709 compiled with @option{-flto}, the generated object file is larger than
9710 a regular object file because it contains GIMPLE bytecodes and the usual
9711 final code (see @option{-ffat-lto-objects}.  This means that
9712 object files with LTO information can be linked as normal object
9713 files; if @option{-fno-lto} is passed to the linker, no
9714 interprocedural optimizations are applied.  Note that when
9715 @option{-fno-fat-lto-objects} is enabled the compile stage is faster
9716 but you cannot perform a regular, non-LTO link on them.
9718 Additionally, the optimization flags used to compile individual files
9719 are not necessarily related to those used at link time.  For instance,
9721 @smallexample
9722 gcc -c -O0 -ffat-lto-objects -flto foo.c
9723 gcc -c -O0 -ffat-lto-objects -flto bar.c
9724 gcc -o myprog -O3 foo.o bar.o
9725 @end smallexample
9727 This produces individual object files with unoptimized assembler
9728 code, but the resulting binary @file{myprog} is optimized at
9729 @option{-O3}.  If, instead, the final binary is generated with
9730 @option{-fno-lto}, then @file{myprog} is not optimized.
9732 When producing the final binary, GCC only
9733 applies link-time optimizations to those files that contain bytecode.
9734 Therefore, you can mix and match object files and libraries with
9735 GIMPLE bytecodes and final object code.  GCC automatically selects
9736 which files to optimize in LTO mode and which files to link without
9737 further processing.
9739 There are some code generation flags preserved by GCC when
9740 generating bytecodes, as they need to be used during the final link
9741 stage.  Generally options specified at link time override those
9742 specified at compile time.
9744 If you do not specify an optimization level option @option{-O} at
9745 link time, then GCC uses the highest optimization level 
9746 used when compiling the object files.
9748 Currently, the following options and their settings are taken from
9749 the first object file that explicitly specifies them: 
9750 @option{-fPIC}, @option{-fpic}, @option{-fpie}, @option{-fcommon},
9751 @option{-fexceptions}, @option{-fnon-call-exceptions}, @option{-fgnu-tm}
9752 and all the @option{-m} target flags.
9754 Certain ABI-changing flags are required to match in all compilation units,
9755 and trying to override this at link time with a conflicting value
9756 is ignored.  This includes options such as @option{-freg-struct-return}
9757 and @option{-fpcc-struct-return}. 
9759 Other options such as @option{-ffp-contract}, @option{-fno-strict-overflow},
9760 @option{-fwrapv}, @option{-fno-trapv} or @option{-fno-strict-aliasing}
9761 are passed through to the link stage and merged conservatively for
9762 conflicting translation units.  Specifically
9763 @option{-fno-strict-overflow}, @option{-fwrapv} and @option{-fno-trapv} take
9764 precedence; and for example @option{-ffp-contract=off} takes precedence
9765 over @option{-ffp-contract=fast}.  You can override them at link time.
9767 If LTO encounters objects with C linkage declared with incompatible
9768 types in separate translation units to be linked together (undefined
9769 behavior according to ISO C99 6.2.7), a non-fatal diagnostic may be
9770 issued.  The behavior is still undefined at run time.  Similar
9771 diagnostics may be raised for other languages.
9773 Another feature of LTO is that it is possible to apply interprocedural
9774 optimizations on files written in different languages:
9776 @smallexample
9777 gcc -c -flto foo.c
9778 g++ -c -flto bar.cc
9779 gfortran -c -flto baz.f90
9780 g++ -o myprog -flto -O3 foo.o bar.o baz.o -lgfortran
9781 @end smallexample
9783 Notice that the final link is done with @command{g++} to get the C++
9784 runtime libraries and @option{-lgfortran} is added to get the Fortran
9785 runtime libraries.  In general, when mixing languages in LTO mode, you
9786 should use the same link command options as when mixing languages in a
9787 regular (non-LTO) compilation.
9789 If object files containing GIMPLE bytecode are stored in a library archive, say
9790 @file{libfoo.a}, it is possible to extract and use them in an LTO link if you
9791 are using a linker with plugin support.  To create static libraries suitable
9792 for LTO, use @command{gcc-ar} and @command{gcc-ranlib} instead of @command{ar}
9793 and @command{ranlib}; 
9794 to show the symbols of object files with GIMPLE bytecode, use
9795 @command{gcc-nm}.  Those commands require that @command{ar}, @command{ranlib}
9796 and @command{nm} have been compiled with plugin support.  At link time, use the
9797 flag @option{-fuse-linker-plugin} to ensure that the library participates in
9798 the LTO optimization process:
9800 @smallexample
9801 gcc -o myprog -O2 -flto -fuse-linker-plugin a.o b.o -lfoo
9802 @end smallexample
9804 With the linker plugin enabled, the linker extracts the needed
9805 GIMPLE files from @file{libfoo.a} and passes them on to the running GCC
9806 to make them part of the aggregated GIMPLE image to be optimized.
9808 If you are not using a linker with plugin support and/or do not
9809 enable the linker plugin, then the objects inside @file{libfoo.a}
9810 are extracted and linked as usual, but they do not participate
9811 in the LTO optimization process.  In order to make a static library suitable
9812 for both LTO optimization and usual linkage, compile its object files with
9813 @option{-flto} @option{-ffat-lto-objects}.
9815 Link-time optimizations do not require the presence of the whole program to
9816 operate.  If the program does not require any symbols to be exported, it is
9817 possible to combine @option{-flto} and @option{-fwhole-program} to allow
9818 the interprocedural optimizers to use more aggressive assumptions which may
9819 lead to improved optimization opportunities.
9820 Use of @option{-fwhole-program} is not needed when linker plugin is
9821 active (see @option{-fuse-linker-plugin}).
9823 The current implementation of LTO makes no
9824 attempt to generate bytecode that is portable between different
9825 types of hosts.  The bytecode files are versioned and there is a
9826 strict version check, so bytecode files generated in one version of
9827 GCC do not work with an older or newer version of GCC.
9829 Link-time optimization does not work well with generation of debugging
9830 information on systems other than those using a combination of ELF and
9831 DWARF.
9833 If you specify the optional @var{n}, the optimization and code
9834 generation done at link time is executed in parallel using @var{n}
9835 parallel jobs by utilizing an installed @command{make} program.  The
9836 environment variable @env{MAKE} may be used to override the program
9837 used.  The default value for @var{n} is 1.
9839 You can also specify @option{-flto=jobserver} to use GNU make's
9840 job server mode to determine the number of parallel jobs. This
9841 is useful when the Makefile calling GCC is already executing in parallel.
9842 You must prepend a @samp{+} to the command recipe in the parent Makefile
9843 for this to work.  This option likely only works if @env{MAKE} is
9844 GNU make.
9846 @item -flto-partition=@var{alg}
9847 @opindex flto-partition
9848 Specify the partitioning algorithm used by the link-time optimizer.
9849 The value is either @samp{1to1} to specify a partitioning mirroring
9850 the original source files or @samp{balanced} to specify partitioning
9851 into equally sized chunks (whenever possible) or @samp{max} to create
9852 new partition for every symbol where possible.  Specifying @samp{none}
9853 as an algorithm disables partitioning and streaming completely. 
9854 The default value is @samp{balanced}. While @samp{1to1} can be used
9855 as an workaround for various code ordering issues, the @samp{max}
9856 partitioning is intended for internal testing only.
9857 The value @samp{one} specifies that exactly one partition should be
9858 used while the value @samp{none} bypasses partitioning and executes
9859 the link-time optimization step directly from the WPA phase.
9861 @item -flto-odr-type-merging
9862 @opindex flto-odr-type-merging
9863 Enable streaming of mangled types names of C++ types and their unification
9864 at link time.  This increases size of LTO object files, but enables
9865 diagnostics about One Definition Rule violations.
9867 @item -flto-compression-level=@var{n}
9868 @opindex flto-compression-level
9869 This option specifies the level of compression used for intermediate
9870 language written to LTO object files, and is only meaningful in
9871 conjunction with LTO mode (@option{-flto}).  Valid
9872 values are 0 (no compression) to 9 (maximum compression).  Values
9873 outside this range are clamped to either 0 or 9.  If the option is not
9874 given, a default balanced compression setting is used.
9876 @item -fuse-linker-plugin
9877 @opindex fuse-linker-plugin
9878 Enables the use of a linker plugin during link-time optimization.  This
9879 option relies on plugin support in the linker, which is available in gold
9880 or in GNU ld 2.21 or newer.
9882 This option enables the extraction of object files with GIMPLE bytecode out
9883 of library archives. This improves the quality of optimization by exposing
9884 more code to the link-time optimizer.  This information specifies what
9885 symbols can be accessed externally (by non-LTO object or during dynamic
9886 linking).  Resulting code quality improvements on binaries (and shared
9887 libraries that use hidden visibility) are similar to @option{-fwhole-program}.
9888 See @option{-flto} for a description of the effect of this flag and how to
9889 use it.
9891 This option is enabled by default when LTO support in GCC is enabled
9892 and GCC was configured for use with
9893 a linker supporting plugins (GNU ld 2.21 or newer or gold).
9895 @item -ffat-lto-objects
9896 @opindex ffat-lto-objects
9897 Fat LTO objects are object files that contain both the intermediate language
9898 and the object code. This makes them usable for both LTO linking and normal
9899 linking. This option is effective only when compiling with @option{-flto}
9900 and is ignored at link time.
9902 @option{-fno-fat-lto-objects} improves compilation time over plain LTO, but
9903 requires the complete toolchain to be aware of LTO. It requires a linker with
9904 linker plugin support for basic functionality.  Additionally,
9905 @command{nm}, @command{ar} and @command{ranlib}
9906 need to support linker plugins to allow a full-featured build environment
9907 (capable of building static libraries etc).  GCC provides the @command{gcc-ar},
9908 @command{gcc-nm}, @command{gcc-ranlib} wrappers to pass the right options
9909 to these tools. With non fat LTO makefiles need to be modified to use them.
9911 Note that modern binutils provide plugin auto-load mechanism.
9912 Installing the linker plugin into @file{$libdir/bfd-plugins} has the same
9913 effect as usage of the command wrappers (@command{gcc-ar}, @command{gcc-nm} and
9914 @command{gcc-ranlib}).
9916 The default is @option{-fno-fat-lto-objects} on targets with linker plugin
9917 support.
9919 @item -fcompare-elim
9920 @opindex fcompare-elim
9921 After register allocation and post-register allocation instruction splitting,
9922 identify arithmetic instructions that compute processor flags similar to a
9923 comparison operation based on that arithmetic.  If possible, eliminate the
9924 explicit comparison operation.
9926 This pass only applies to certain targets that cannot explicitly represent
9927 the comparison operation before register allocation is complete.
9929 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
9931 @item -fcprop-registers
9932 @opindex fcprop-registers
9933 After register allocation and post-register allocation instruction splitting,
9934 perform a copy-propagation pass to try to reduce scheduling dependencies
9935 and occasionally eliminate the copy.
9937 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
9939 @item -fprofile-correction
9940 @opindex fprofile-correction
9941 Profiles collected using an instrumented binary for multi-threaded programs may
9942 be inconsistent due to missed counter updates. When this option is specified,
9943 GCC uses heuristics to correct or smooth out such inconsistencies. By
9944 default, GCC emits an error message when an inconsistent profile is detected.
9946 @item -fprofile-use
9947 @itemx -fprofile-use=@var{path}
9948 @opindex fprofile-use
9949 Enable profile feedback-directed optimizations, 
9950 and the following optimizations
9951 which are generally profitable only with profile feedback available:
9952 @option{-fbranch-probabilities}, @option{-fvpt},
9953 @option{-funroll-loops}, @option{-fpeel-loops}, @option{-ftracer}, 
9954 @option{-ftree-vectorize}, and @option{ftree-loop-distribute-patterns}.
9956 Before you can use this option, you must first generate profiling information.
9957 @xref{Instrumentation Options}, for information about the
9958 @option{-fprofile-generate} option.
9960 By default, GCC emits an error message if the feedback profiles do not
9961 match the source code.  This error can be turned into a warning by using
9962 @option{-Wno-error=coverage-mismatch}.  Note this may result in poorly
9963 optimized code.  Additionally, by default, GCC also emits a warning message if
9964 the feedback profiles do not exist (See @option{-Wmissing-profile}).
9966 If @var{path} is specified, GCC looks at the @var{path} to find
9967 the profile feedback data files. See @option{-fprofile-dir}.
9969 @item -fauto-profile
9970 @itemx -fauto-profile=@var{path}
9971 @opindex fauto-profile
9972 Enable sampling-based feedback-directed optimizations, 
9973 and the following optimizations
9974 which are generally profitable only with profile feedback available:
9975 @option{-fbranch-probabilities}, @option{-fvpt},
9976 @option{-funroll-loops}, @option{-fpeel-loops}, @option{-ftracer}, 
9977 @option{-ftree-vectorize},
9978 @option{-finline-functions}, @option{-fipa-cp}, @option{-fipa-cp-clone},
9979 @option{-fpredictive-commoning}, @option{-funswitch-loops},
9980 @option{-fgcse-after-reload}, and @option{-ftree-loop-distribute-patterns}.
9982 @var{path} is the name of a file containing AutoFDO profile information.
9983 If omitted, it defaults to @file{fbdata.afdo} in the current directory.
9985 Producing an AutoFDO profile data file requires running your program
9986 with the @command{perf} utility on a supported GNU/Linux target system.
9987 For more information, see @uref{https://perf.wiki.kernel.org/}.
9989 E.g.
9990 @smallexample
9991 perf record -e br_inst_retired:near_taken -b -o perf.data \
9992     -- your_program
9993 @end smallexample
9995 Then use the @command{create_gcov} tool to convert the raw profile data
9996 to a format that can be used by GCC.@  You must also supply the 
9997 unstripped binary for your program to this tool.  
9998 See @uref{https://github.com/google/autofdo}.
10000 E.g.
10001 @smallexample
10002 create_gcov --binary=your_program.unstripped --profile=perf.data \
10003     --gcov=profile.afdo
10004 @end smallexample
10005 @end table
10007 The following options control compiler behavior regarding floating-point 
10008 arithmetic.  These options trade off between speed and
10009 correctness.  All must be specifically enabled.
10011 @table @gcctabopt
10012 @item -ffloat-store
10013 @opindex ffloat-store
10014 Do not store floating-point variables in registers, and inhibit other
10015 options that might change whether a floating-point value is taken from a
10016 register or memory.
10018 @cindex floating-point precision
10019 This option prevents undesirable excess precision on machines such as
10020 the 68000 where the floating registers (of the 68881) keep more
10021 precision than a @code{double} is supposed to have.  Similarly for the
10022 x86 architecture.  For most programs, the excess precision does only
10023 good, but a few programs rely on the precise definition of IEEE floating
10024 point.  Use @option{-ffloat-store} for such programs, after modifying
10025 them to store all pertinent intermediate computations into variables.
10027 @item -fexcess-precision=@var{style}
10028 @opindex fexcess-precision
10029 This option allows further control over excess precision on machines
10030 where floating-point operations occur in a format with more precision or
10031 range than the IEEE standard and interchange floating-point types.  By
10032 default, @option{-fexcess-precision=fast} is in effect; this means that
10033 operations may be carried out in a wider precision than the types specified
10034 in the source if that would result in faster code, and it is unpredictable
10035 when rounding to the types specified in the source code takes place.
10036 When compiling C, if @option{-fexcess-precision=standard} is specified then
10037 excess precision follows the rules specified in ISO C99; in particular,
10038 both casts and assignments cause values to be rounded to their
10039 semantic types (whereas @option{-ffloat-store} only affects
10040 assignments).  This option is enabled by default for C if a strict
10041 conformance option such as @option{-std=c99} is used.
10042 @option{-ffast-math} enables @option{-fexcess-precision=fast} by default
10043 regardless of whether a strict conformance option is used.
10045 @opindex mfpmath
10046 @option{-fexcess-precision=standard} is not implemented for languages
10047 other than C.  On the x86, it has no effect if @option{-mfpmath=sse}
10048 or @option{-mfpmath=sse+387} is specified; in the former case, IEEE
10049 semantics apply without excess precision, and in the latter, rounding
10050 is unpredictable.
10052 @item -ffast-math
10053 @opindex ffast-math
10054 Sets the options @option{-fno-math-errno}, @option{-funsafe-math-optimizations},
10055 @option{-ffinite-math-only}, @option{-fno-rounding-math},
10056 @option{-fno-signaling-nans}, @option{-fcx-limited-range} and
10057 @option{-fexcess-precision=fast}.
10059 This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
10061 This option is not turned on by any @option{-O} option besides
10062 @option{-Ofast} since it can result in incorrect output for programs
10063 that depend on an exact implementation of IEEE or ISO rules/specifications
10064 for math functions. It may, however, yield faster code for programs
10065 that do not require the guarantees of these specifications.
10067 @item -fno-math-errno
10068 @opindex fno-math-errno
10069 Do not set @code{errno} after calling math functions that are executed
10070 with a single instruction, e.g., @code{sqrt}.  A program that relies on
10071 IEEE exceptions for math error handling may want to use this flag
10072 for speed while maintaining IEEE arithmetic compatibility.
10074 This option is not turned on by any @option{-O} option since
10075 it can result in incorrect output for programs that depend on
10076 an exact implementation of IEEE or ISO rules/specifications for
10077 math functions. It may, however, yield faster code for programs
10078 that do not require the guarantees of these specifications.
10080 The default is @option{-fmath-errno}.
10082 On Darwin systems, the math library never sets @code{errno}.  There is
10083 therefore no reason for the compiler to consider the possibility that
10084 it might, and @option{-fno-math-errno} is the default.
10086 @item -funsafe-math-optimizations
10087 @opindex funsafe-math-optimizations
10089 Allow optimizations for floating-point arithmetic that (a) assume
10090 that arguments and results are valid and (b) may violate IEEE or
10091 ANSI standards.  When used at link time, it may include libraries
10092 or startup files that change the default FPU control word or other
10093 similar optimizations.
10095 This option is not turned on by any @option{-O} option since
10096 it can result in incorrect output for programs that depend on
10097 an exact implementation of IEEE or ISO rules/specifications for
10098 math functions. It may, however, yield faster code for programs
10099 that do not require the guarantees of these specifications.
10100 Enables @option{-fno-signed-zeros}, @option{-fno-trapping-math},
10101 @option{-fassociative-math} and @option{-freciprocal-math}.
10103 The default is @option{-fno-unsafe-math-optimizations}.
10105 @item -fassociative-math
10106 @opindex fassociative-math
10108 Allow re-association of operands in series of floating-point operations.
10109 This violates the ISO C and C++ language standard by possibly changing
10110 computation result.  NOTE: re-ordering may change the sign of zero as
10111 well as ignore NaNs and inhibit or create underflow or overflow (and
10112 thus cannot be used on code that relies on rounding behavior like
10113 @code{(x + 2**52) - 2**52}.  May also reorder floating-point comparisons
10114 and thus may not be used when ordered comparisons are required.
10115 This option requires that both @option{-fno-signed-zeros} and
10116 @option{-fno-trapping-math} be in effect.  Moreover, it doesn't make
10117 much sense with @option{-frounding-math}. For Fortran the option
10118 is automatically enabled when both @option{-fno-signed-zeros} and
10119 @option{-fno-trapping-math} are in effect.
10121 The default is @option{-fno-associative-math}.
10123 @item -freciprocal-math
10124 @opindex freciprocal-math
10126 Allow the reciprocal of a value to be used instead of dividing by
10127 the value if this enables optimizations.  For example @code{x / y}
10128 can be replaced with @code{x * (1/y)}, which is useful if @code{(1/y)}
10129 is subject to common subexpression elimination.  Note that this loses
10130 precision and increases the number of flops operating on the value.
10132 The default is @option{-fno-reciprocal-math}.
10134 @item -ffinite-math-only
10135 @opindex ffinite-math-only
10136 Allow optimizations for floating-point arithmetic that assume
10137 that arguments and results are not NaNs or +-Infs.
10139 This option is not turned on by any @option{-O} option since
10140 it can result in incorrect output for programs that depend on
10141 an exact implementation of IEEE or ISO rules/specifications for
10142 math functions. It may, however, yield faster code for programs
10143 that do not require the guarantees of these specifications.
10145 The default is @option{-fno-finite-math-only}.
10147 @item -fno-signed-zeros
10148 @opindex fno-signed-zeros
10149 Allow optimizations for floating-point arithmetic that ignore the
10150 signedness of zero.  IEEE arithmetic specifies the behavior of
10151 distinct +0.0 and @minus{}0.0 values, which then prohibits simplification
10152 of expressions such as x+0.0 or 0.0*x (even with @option{-ffinite-math-only}).
10153 This option implies that the sign of a zero result isn't significant.
10155 The default is @option{-fsigned-zeros}.
10157 @item -fno-trapping-math
10158 @opindex fno-trapping-math
10159 Compile code assuming that floating-point operations cannot generate
10160 user-visible traps.  These traps include division by zero, overflow,
10161 underflow, inexact result and invalid operation.  This option requires
10162 that @option{-fno-signaling-nans} be in effect.  Setting this option may
10163 allow faster code if one relies on ``non-stop'' IEEE arithmetic, for example.
10165 This option should never be turned on by any @option{-O} option since
10166 it can result in incorrect output for programs that depend on
10167 an exact implementation of IEEE or ISO rules/specifications for
10168 math functions.
10170 The default is @option{-ftrapping-math}.
10172 @item -frounding-math
10173 @opindex frounding-math
10174 Disable transformations and optimizations that assume default floating-point
10175 rounding behavior.  This is round-to-zero for all floating point
10176 to integer conversions, and round-to-nearest for all other arithmetic
10177 truncations.  This option should be specified for programs that change
10178 the FP rounding mode dynamically, or that may be executed with a
10179 non-default rounding mode.  This option disables constant folding of
10180 floating-point expressions at compile time (which may be affected by
10181 rounding mode) and arithmetic transformations that are unsafe in the
10182 presence of sign-dependent rounding modes.
10184 The default is @option{-fno-rounding-math}.
10186 This option is experimental and does not currently guarantee to
10187 disable all GCC optimizations that are affected by rounding mode.
10188 Future versions of GCC may provide finer control of this setting
10189 using C99's @code{FENV_ACCESS} pragma.  This command-line option
10190 will be used to specify the default state for @code{FENV_ACCESS}.
10192 @item -fsignaling-nans
10193 @opindex fsignaling-nans
10194 Compile code assuming that IEEE signaling NaNs may generate user-visible
10195 traps during floating-point operations.  Setting this option disables
10196 optimizations that may change the number of exceptions visible with
10197 signaling NaNs.  This option implies @option{-ftrapping-math}.
10199 This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
10200 be defined.
10202 The default is @option{-fno-signaling-nans}.
10204 This option is experimental and does not currently guarantee to
10205 disable all GCC optimizations that affect signaling NaN behavior.
10207 @item -fno-fp-int-builtin-inexact
10208 @opindex fno-fp-int-builtin-inexact
10209 Do not allow the built-in functions @code{ceil}, @code{floor},
10210 @code{round} and @code{trunc}, and their @code{float} and @code{long
10211 double} variants, to generate code that raises the ``inexact''
10212 floating-point exception for noninteger arguments.  ISO C99 and C11
10213 allow these functions to raise the ``inexact'' exception, but ISO/IEC
10214 TS 18661-1:2014, the C bindings to IEEE 754-2008, does not allow these
10215 functions to do so.
10217 The default is @option{-ffp-int-builtin-inexact}, allowing the
10218 exception to be raised.  This option does nothing unless
10219 @option{-ftrapping-math} is in effect.
10221 Even if @option{-fno-fp-int-builtin-inexact} is used, if the functions
10222 generate a call to a library function then the ``inexact'' exception
10223 may be raised if the library implementation does not follow TS 18661.
10225 @item -fsingle-precision-constant
10226 @opindex fsingle-precision-constant
10227 Treat floating-point constants as single precision instead of
10228 implicitly converting them to double-precision constants.
10230 @item -fcx-limited-range
10231 @opindex fcx-limited-range
10232 When enabled, this option states that a range reduction step is not
10233 needed when performing complex division.  Also, there is no checking
10234 whether the result of a complex multiplication or division is @code{NaN
10235 + I*NaN}, with an attempt to rescue the situation in that case.  The
10236 default is @option{-fno-cx-limited-range}, but is enabled by
10237 @option{-ffast-math}.
10239 This option controls the default setting of the ISO C99
10240 @code{CX_LIMITED_RANGE} pragma.  Nevertheless, the option applies to
10241 all languages.
10243 @item -fcx-fortran-rules
10244 @opindex fcx-fortran-rules
10245 Complex multiplication and division follow Fortran rules.  Range
10246 reduction is done as part of complex division, but there is no checking
10247 whether the result of a complex multiplication or division is @code{NaN
10248 + I*NaN}, with an attempt to rescue the situation in that case.
10250 The default is @option{-fno-cx-fortran-rules}.
10252 @end table
10254 The following options control optimizations that may improve
10255 performance, but are not enabled by any @option{-O} options.  This
10256 section includes experimental options that may produce broken code.
10258 @table @gcctabopt
10259 @item -fbranch-probabilities
10260 @opindex fbranch-probabilities
10261 After running a program compiled with @option{-fprofile-arcs}
10262 (@pxref{Instrumentation Options}),
10263 you can compile it a second time using
10264 @option{-fbranch-probabilities}, to improve optimizations based on
10265 the number of times each branch was taken.  When a program
10266 compiled with @option{-fprofile-arcs} exits, it saves arc execution
10267 counts to a file called @file{@var{sourcename}.gcda} for each source
10268 file.  The information in this data file is very dependent on the
10269 structure of the generated code, so you must use the same source code
10270 and the same optimization options for both compilations.
10272 With @option{-fbranch-probabilities}, GCC puts a
10273 @samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
10274 These can be used to improve optimization.  Currently, they are only
10275 used in one place: in @file{reorg.c}, instead of guessing which path a
10276 branch is most likely to take, the @samp{REG_BR_PROB} values are used to
10277 exactly determine which path is taken more often.
10279 @item -fprofile-values
10280 @opindex fprofile-values
10281 If combined with @option{-fprofile-arcs}, it adds code so that some
10282 data about values of expressions in the program is gathered.
10284 With @option{-fbranch-probabilities}, it reads back the data gathered
10285 from profiling values of expressions for usage in optimizations.
10287 Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
10289 @item -fprofile-reorder-functions
10290 @opindex fprofile-reorder-functions
10291 Function reordering based on profile instrumentation collects
10292 first time of execution of a function and orders these functions
10293 in ascending order.
10295 Enabled with @option{-fprofile-use}.
10297 @item -fvpt
10298 @opindex fvpt
10299 If combined with @option{-fprofile-arcs}, this option instructs the compiler
10300 to add code to gather information about values of expressions.
10302 With @option{-fbranch-probabilities}, it reads back the data gathered
10303 and actually performs the optimizations based on them.
10304 Currently the optimizations include specialization of division operations
10305 using the knowledge about the value of the denominator.
10307 @item -frename-registers
10308 @opindex frename-registers
10309 Attempt to avoid false dependencies in scheduled code by making use
10310 of registers left over after register allocation.  This optimization
10311 most benefits processors with lots of registers.  Depending on the
10312 debug information format adopted by the target, however, it can
10313 make debugging impossible, since variables no longer stay in
10314 a ``home register''.
10316 Enabled by default with @option{-funroll-loops}.
10318 @item -fschedule-fusion
10319 @opindex fschedule-fusion
10320 Performs a target dependent pass over the instruction stream to schedule
10321 instructions of same type together because target machine can execute them
10322 more efficiently if they are adjacent to each other in the instruction flow.
10324 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
10326 @item -ftracer
10327 @opindex ftracer
10328 Perform tail duplication to enlarge superblock size.  This transformation
10329 simplifies the control flow of the function allowing other optimizations to do
10330 a better job.
10332 Enabled with @option{-fprofile-use}.
10334 @item -funroll-loops
10335 @opindex funroll-loops
10336 Unroll loops whose number of iterations can be determined at compile time or
10337 upon entry to the loop.  @option{-funroll-loops} implies
10338 @option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.
10339 It also turns on complete loop peeling (i.e.@: complete removal of loops with
10340 a small constant number of iterations).  This option makes code larger, and may
10341 or may not make it run faster.
10343 Enabled with @option{-fprofile-use}.
10345 @item -funroll-all-loops
10346 @opindex funroll-all-loops
10347 Unroll all loops, even if their number of iterations is uncertain when
10348 the loop is entered.  This usually makes programs run more slowly.
10349 @option{-funroll-all-loops} implies the same options as
10350 @option{-funroll-loops}.
10352 @item -fpeel-loops
10353 @opindex fpeel-loops
10354 Peels loops for which there is enough information that they do not
10355 roll much (from profile feedback or static analysis).  It also turns on
10356 complete loop peeling (i.e.@: complete removal of loops with small constant
10357 number of iterations).
10359 Enabled with @option{-O3} and/or @option{-fprofile-use}.
10361 @item -fmove-loop-invariants
10362 @opindex fmove-loop-invariants
10363 Enables the loop invariant motion pass in the RTL loop optimizer.  Enabled
10364 at level @option{-O1}
10366 @item -fsplit-loops
10367 @opindex fsplit-loops
10368 Split a loop into two if it contains a condition that's always true
10369 for one side of the iteration space and false for the other.
10371 @item -funswitch-loops
10372 @opindex funswitch-loops
10373 Move branches with loop invariant conditions out of the loop, with duplicates
10374 of the loop on both branches (modified according to result of the condition).
10376 @item -ffunction-sections
10377 @itemx -fdata-sections
10378 @opindex ffunction-sections
10379 @opindex fdata-sections
10380 Place each function or data item into its own section in the output
10381 file if the target supports arbitrary sections.  The name of the
10382 function or the name of the data item determines the section's name
10383 in the output file.
10385 Use these options on systems where the linker can perform optimizations to
10386 improve locality of reference in the instruction space.  Most systems using the
10387 ELF object format have linkers with such optimizations.  On AIX, the linker
10388 rearranges sections (CSECTs) based on the call graph.  The performance impact
10389 varies.
10391 Together with a linker garbage collection (linker @option{--gc-sections}
10392 option) these options may lead to smaller statically-linked executables (after
10393 stripping).
10395 On ELF/DWARF systems these options do not degenerate the quality of the debug
10396 information.  There could be issues with other object files/debug info formats.
10398 Only use these options when there are significant benefits from doing so.  When
10399 you specify these options, the assembler and linker create larger object and
10400 executable files and are also slower.  These options affect code generation.
10401 They prevent optimizations by the compiler and assembler using relative
10402 locations inside a translation unit since the locations are unknown until
10403 link time.  An example of such an optimization is relaxing calls to short call
10404 instructions.
10406 @item -fbranch-target-load-optimize
10407 @opindex fbranch-target-load-optimize
10408 Perform branch target register load optimization before prologue / epilogue
10409 threading.
10410 The use of target registers can typically be exposed only during reload,
10411 thus hoisting loads out of loops and doing inter-block scheduling needs
10412 a separate optimization pass.
10414 @item -fbranch-target-load-optimize2
10415 @opindex fbranch-target-load-optimize2
10416 Perform branch target register load optimization after prologue / epilogue
10417 threading.
10419 @item -fbtr-bb-exclusive
10420 @opindex fbtr-bb-exclusive
10421 When performing branch target register load optimization, don't reuse
10422 branch target registers within any basic block.
10424 @item -fstdarg-opt
10425 @opindex fstdarg-opt
10426 Optimize the prologue of variadic argument functions with respect to usage of
10427 those arguments.
10429 @item -fsection-anchors
10430 @opindex fsection-anchors
10431 Try to reduce the number of symbolic address calculations by using
10432 shared ``anchor'' symbols to address nearby objects.  This transformation
10433 can help to reduce the number of GOT entries and GOT accesses on some
10434 targets.
10436 For example, the implementation of the following function @code{foo}:
10438 @smallexample
10439 static int a, b, c;
10440 int foo (void) @{ return a + b + c; @}
10441 @end smallexample
10443 @noindent
10444 usually calculates the addresses of all three variables, but if you
10445 compile it with @option{-fsection-anchors}, it accesses the variables
10446 from a common anchor point instead.  The effect is similar to the
10447 following pseudocode (which isn't valid C):
10449 @smallexample
10450 int foo (void)
10452   register int *xr = &x;
10453   return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
10455 @end smallexample
10457 Not all targets support this option.
10459 @item --param @var{name}=@var{value}
10460 @opindex param
10461 In some places, GCC uses various constants to control the amount of
10462 optimization that is done.  For example, GCC does not inline functions
10463 that contain more than a certain number of instructions.  You can
10464 control some of these constants on the command line using the
10465 @option{--param} option.
10467 The names of specific parameters, and the meaning of the values, are
10468 tied to the internals of the compiler, and are subject to change
10469 without notice in future releases.
10471 In order to get minimal, maximal and default value of a parameter,
10472 one can use @option{--help=param -Q} options.
10474 In each case, the @var{value} is an integer.  The allowable choices for
10475 @var{name} are:
10477 @table @gcctabopt
10478 @item predictable-branch-outcome
10479 When branch is predicted to be taken with probability lower than this threshold
10480 (in percent), then it is considered well predictable.
10482 @item max-rtl-if-conversion-insns
10483 RTL if-conversion tries to remove conditional branches around a block and
10484 replace them with conditionally executed instructions.  This parameter
10485 gives the maximum number of instructions in a block which should be
10486 considered for if-conversion.  The compiler will
10487 also use other heuristics to decide whether if-conversion is likely to be
10488 profitable.
10490 @item max-rtl-if-conversion-predictable-cost
10491 @itemx max-rtl-if-conversion-unpredictable-cost
10492 RTL if-conversion will try to remove conditional branches around a block
10493 and replace them with conditionally executed instructions.  These parameters
10494 give the maximum permissible cost for the sequence that would be generated
10495 by if-conversion depending on whether the branch is statically determined
10496 to be predictable or not.  The units for this parameter are the same as
10497 those for the GCC internal seq_cost metric.  The compiler will try to
10498 provide a reasonable default for this parameter using the BRANCH_COST
10499 target macro.
10501 @item max-crossjump-edges
10502 The maximum number of incoming edges to consider for cross-jumping.
10503 The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
10504 the number of edges incoming to each block.  Increasing values mean
10505 more aggressive optimization, making the compilation time increase with
10506 probably small improvement in executable size.
10508 @item min-crossjump-insns
10509 The minimum number of instructions that must be matched at the end
10510 of two blocks before cross-jumping is performed on them.  This
10511 value is ignored in the case where all instructions in the block being
10512 cross-jumped from are matched.
10514 @item max-grow-copy-bb-insns
10515 The maximum code size expansion factor when copying basic blocks
10516 instead of jumping.  The expansion is relative to a jump instruction.
10518 @item max-goto-duplication-insns
10519 The maximum number of instructions to duplicate to a block that jumps
10520 to a computed goto.  To avoid @math{O(N^2)} behavior in a number of
10521 passes, GCC factors computed gotos early in the compilation process,
10522 and unfactors them as late as possible.  Only computed jumps at the
10523 end of a basic blocks with no more than max-goto-duplication-insns are
10524 unfactored.
10526 @item max-delay-slot-insn-search
10527 The maximum number of instructions to consider when looking for an
10528 instruction to fill a delay slot.  If more than this arbitrary number of
10529 instructions are searched, the time savings from filling the delay slot
10530 are minimal, so stop searching.  Increasing values mean more
10531 aggressive optimization, making the compilation time increase with probably
10532 small improvement in execution time.
10534 @item max-delay-slot-live-search
10535 When trying to fill delay slots, the maximum number of instructions to
10536 consider when searching for a block with valid live register
10537 information.  Increasing this arbitrarily chosen value means more
10538 aggressive optimization, increasing the compilation time.  This parameter
10539 should be removed when the delay slot code is rewritten to maintain the
10540 control-flow graph.
10542 @item max-gcse-memory
10543 The approximate maximum amount of memory that can be allocated in
10544 order to perform the global common subexpression elimination
10545 optimization.  If more memory than specified is required, the
10546 optimization is not done.
10548 @item max-gcse-insertion-ratio
10549 If the ratio of expression insertions to deletions is larger than this value
10550 for any expression, then RTL PRE inserts or removes the expression and thus
10551 leaves partially redundant computations in the instruction stream.
10553 @item max-pending-list-length
10554 The maximum number of pending dependencies scheduling allows
10555 before flushing the current state and starting over.  Large functions
10556 with few branches or calls can create excessively large lists which
10557 needlessly consume memory and resources.
10559 @item max-modulo-backtrack-attempts
10560 The maximum number of backtrack attempts the scheduler should make
10561 when modulo scheduling a loop.  Larger values can exponentially increase
10562 compilation time.
10564 @item max-inline-insns-single
10565 Several parameters control the tree inliner used in GCC@.
10566 This number sets the maximum number of instructions (counted in GCC's
10567 internal representation) in a single function that the tree inliner
10568 considers for inlining.  This only affects functions declared
10569 inline and methods implemented in a class declaration (C++).
10571 @item max-inline-insns-auto
10572 When you use @option{-finline-functions} (included in @option{-O3}),
10573 a lot of functions that would otherwise not be considered for inlining
10574 by the compiler are investigated.  To those functions, a different
10575 (more restrictive) limit compared to functions declared inline can
10576 be applied.
10578 @item inline-min-speedup
10579 When estimated performance improvement of caller + callee runtime exceeds this
10580 threshold (in percent), the function can be inlined regardless of the limit on
10581 @option{--param max-inline-insns-single} and @option{--param
10582 max-inline-insns-auto}.
10584 @item large-function-insns
10585 The limit specifying really large functions.  For functions larger than this
10586 limit after inlining, inlining is constrained by
10587 @option{--param large-function-growth}.  This parameter is useful primarily
10588 to avoid extreme compilation time caused by non-linear algorithms used by the
10589 back end.
10591 @item large-function-growth
10592 Specifies maximal growth of large function caused by inlining in percents.
10593 For example, parameter value 100 limits large function growth to 2.0 times
10594 the original size.
10596 @item large-unit-insns
10597 The limit specifying large translation unit.  Growth caused by inlining of
10598 units larger than this limit is limited by @option{--param inline-unit-growth}.
10599 For small units this might be too tight.
10600 For example, consider a unit consisting of function A
10601 that is inline and B that just calls A three times.  If B is small relative to
10602 A, the growth of unit is 300\% and yet such inlining is very sane.  For very
10603 large units consisting of small inlineable functions, however, the overall unit
10604 growth limit is needed to avoid exponential explosion of code size.  Thus for
10605 smaller units, the size is increased to @option{--param large-unit-insns}
10606 before applying @option{--param inline-unit-growth}.
10608 @item inline-unit-growth
10609 Specifies maximal overall growth of the compilation unit caused by inlining.
10610 For example, parameter value 20 limits unit growth to 1.2 times the original
10611 size. Cold functions (either marked cold via an attribute or by profile
10612 feedback) are not accounted into the unit size.
10614 @item ipcp-unit-growth
10615 Specifies maximal overall growth of the compilation unit caused by
10616 interprocedural constant propagation.  For example, parameter value 10 limits
10617 unit growth to 1.1 times the original size.
10619 @item large-stack-frame
10620 The limit specifying large stack frames.  While inlining the algorithm is trying
10621 to not grow past this limit too much.
10623 @item large-stack-frame-growth
10624 Specifies maximal growth of large stack frames caused by inlining in percents.
10625 For example, parameter value 1000 limits large stack frame growth to 11 times
10626 the original size.
10628 @item max-inline-insns-recursive
10629 @itemx max-inline-insns-recursive-auto
10630 Specifies the maximum number of instructions an out-of-line copy of a
10631 self-recursive inline
10632 function can grow into by performing recursive inlining.
10634 @option{--param max-inline-insns-recursive} applies to functions
10635 declared inline.
10636 For functions not declared inline, recursive inlining
10637 happens only when @option{-finline-functions} (included in @option{-O3}) is
10638 enabled; @option{--param max-inline-insns-recursive-auto} applies instead.
10640 @item max-inline-recursive-depth
10641 @itemx max-inline-recursive-depth-auto
10642 Specifies the maximum recursion depth used for recursive inlining.
10644 @option{--param max-inline-recursive-depth} applies to functions
10645 declared inline.  For functions not declared inline, recursive inlining
10646 happens only when @option{-finline-functions} (included in @option{-O3}) is
10647 enabled; @option{--param max-inline-recursive-depth-auto} applies instead.
10649 @item min-inline-recursive-probability
10650 Recursive inlining is profitable only for function having deep recursion
10651 in average and can hurt for function having little recursion depth by
10652 increasing the prologue size or complexity of function body to other
10653 optimizers.
10655 When profile feedback is available (see @option{-fprofile-generate}) the actual
10656 recursion depth can be guessed from the probability that function recurses
10657 via a given call expression.  This parameter limits inlining only to call
10658 expressions whose probability exceeds the given threshold (in percents).
10660 @item early-inlining-insns
10661 Specify growth that the early inliner can make.  In effect it increases
10662 the amount of inlining for code having a large abstraction penalty.
10664 @item max-early-inliner-iterations
10665 Limit of iterations of the early inliner.  This basically bounds
10666 the number of nested indirect calls the early inliner can resolve.
10667 Deeper chains are still handled by late inlining.
10669 @item comdat-sharing-probability
10670 Probability (in percent) that C++ inline function with comdat visibility
10671 are shared across multiple compilation units.
10673 @item profile-func-internal-id
10674 A parameter to control whether to use function internal id in profile
10675 database lookup. If the value is 0, the compiler uses an id that
10676 is based on function assembler name and filename, which makes old profile
10677 data more tolerant to source changes such as function reordering etc.
10679 @item min-vect-loop-bound
10680 The minimum number of iterations under which loops are not vectorized
10681 when @option{-ftree-vectorize} is used.  The number of iterations after
10682 vectorization needs to be greater than the value specified by this option
10683 to allow vectorization.
10685 @item gcse-cost-distance-ratio
10686 Scaling factor in calculation of maximum distance an expression
10687 can be moved by GCSE optimizations.  This is currently supported only in the
10688 code hoisting pass.  The bigger the ratio, the more aggressive code hoisting
10689 is with simple expressions, i.e., the expressions that have cost
10690 less than @option{gcse-unrestricted-cost}.  Specifying 0 disables
10691 hoisting of simple expressions.
10693 @item gcse-unrestricted-cost
10694 Cost, roughly measured as the cost of a single typical machine
10695 instruction, at which GCSE optimizations do not constrain
10696 the distance an expression can travel.  This is currently
10697 supported only in the code hoisting pass.  The lesser the cost,
10698 the more aggressive code hoisting is.  Specifying 0 
10699 allows all expressions to travel unrestricted distances.
10701 @item max-hoist-depth
10702 The depth of search in the dominator tree for expressions to hoist.
10703 This is used to avoid quadratic behavior in hoisting algorithm.
10704 The value of 0 does not limit on the search, but may slow down compilation
10705 of huge functions.
10707 @item max-tail-merge-comparisons
10708 The maximum amount of similar bbs to compare a bb with.  This is used to
10709 avoid quadratic behavior in tree tail merging.
10711 @item max-tail-merge-iterations
10712 The maximum amount of iterations of the pass over the function.  This is used to
10713 limit compilation time in tree tail merging.
10715 @item store-merging-allow-unaligned
10716 Allow the store merging pass to introduce unaligned stores if it is legal to
10717 do so.
10719 @item max-stores-to-merge
10720 The maximum number of stores to attempt to merge into wider stores in the store
10721 merging pass.
10723 @item max-unrolled-insns
10724 The maximum number of instructions that a loop may have to be unrolled.
10725 If a loop is unrolled, this parameter also determines how many times
10726 the loop code is unrolled.
10728 @item max-average-unrolled-insns
10729 The maximum number of instructions biased by probabilities of their execution
10730 that a loop may have to be unrolled.  If a loop is unrolled,
10731 this parameter also determines how many times the loop code is unrolled.
10733 @item max-unroll-times
10734 The maximum number of unrollings of a single loop.
10736 @item max-peeled-insns
10737 The maximum number of instructions that a loop may have to be peeled.
10738 If a loop is peeled, this parameter also determines how many times
10739 the loop code is peeled.
10741 @item max-peel-times
10742 The maximum number of peelings of a single loop.
10744 @item max-peel-branches
10745 The maximum number of branches on the hot path through the peeled sequence.
10747 @item max-completely-peeled-insns
10748 The maximum number of insns of a completely peeled loop.
10750 @item max-completely-peel-times
10751 The maximum number of iterations of a loop to be suitable for complete peeling.
10753 @item max-completely-peel-loop-nest-depth
10754 The maximum depth of a loop nest suitable for complete peeling.
10756 @item max-unswitch-insns
10757 The maximum number of insns of an unswitched loop.
10759 @item max-unswitch-level
10760 The maximum number of branches unswitched in a single loop.
10762 @item lim-expensive
10763 The minimum cost of an expensive expression in the loop invariant motion.
10765 @item iv-consider-all-candidates-bound
10766 Bound on number of candidates for induction variables, below which
10767 all candidates are considered for each use in induction variable
10768 optimizations.  If there are more candidates than this,
10769 only the most relevant ones are considered to avoid quadratic time complexity.
10771 @item iv-max-considered-uses
10772 The induction variable optimizations give up on loops that contain more
10773 induction variable uses.
10775 @item iv-always-prune-cand-set-bound
10776 If the number of candidates in the set is smaller than this value,
10777 always try to remove unnecessary ivs from the set
10778 when adding a new one.
10780 @item avg-loop-niter
10781 Average number of iterations of a loop.
10783 @item dse-max-object-size
10784 Maximum size (in bytes) of objects tracked bytewise by dead store elimination.
10785 Larger values may result in larger compilation times.
10787 @item dse-max-alias-queries-per-store
10788 Maximum number of queries into the alias oracle per store.
10789 Larger values result in larger compilation times and may result in more
10790 removed dead stores.
10792 @item scev-max-expr-size
10793 Bound on size of expressions used in the scalar evolutions analyzer.
10794 Large expressions slow the analyzer.
10796 @item scev-max-expr-complexity
10797 Bound on the complexity of the expressions in the scalar evolutions analyzer.
10798 Complex expressions slow the analyzer.
10800 @item max-tree-if-conversion-phi-args
10801 Maximum number of arguments in a PHI supported by TREE if conversion
10802 unless the loop is marked with simd pragma.
10804 @item vect-max-version-for-alignment-checks
10805 The maximum number of run-time checks that can be performed when
10806 doing loop versioning for alignment in the vectorizer.
10808 @item vect-max-version-for-alias-checks
10809 The maximum number of run-time checks that can be performed when
10810 doing loop versioning for alias in the vectorizer.
10812 @item vect-max-peeling-for-alignment
10813 The maximum number of loop peels to enhance access alignment
10814 for vectorizer. Value -1 means no limit.
10816 @item max-iterations-to-track
10817 The maximum number of iterations of a loop the brute-force algorithm
10818 for analysis of the number of iterations of the loop tries to evaluate.
10820 @item hot-bb-count-ws-permille
10821 A basic block profile count is considered hot if it contributes to 
10822 the given permillage (i.e. 0...1000) of the entire profiled execution.
10824 @item hot-bb-frequency-fraction
10825 Select fraction of the entry block frequency of executions of basic block in
10826 function given basic block needs to have to be considered hot.
10828 @item max-predicted-iterations
10829 The maximum number of loop iterations we predict statically.  This is useful
10830 in cases where a function contains a single loop with known bound and
10831 another loop with unknown bound.
10832 The known number of iterations is predicted correctly, while
10833 the unknown number of iterations average to roughly 10.  This means that the
10834 loop without bounds appears artificially cold relative to the other one.
10836 @item builtin-expect-probability
10837 Control the probability of the expression having the specified value. This
10838 parameter takes a percentage (i.e. 0 ... 100) as input.
10840 @item builtin-string-cmp-inline-length
10841 The maximum length of a constant string for a builtin string cmp call 
10842 eligible for inlining.
10844 @item align-threshold
10846 Select fraction of the maximal frequency of executions of a basic block in
10847 a function to align the basic block.
10849 @item align-loop-iterations
10851 A loop expected to iterate at least the selected number of iterations is
10852 aligned.
10854 @item tracer-dynamic-coverage
10855 @itemx tracer-dynamic-coverage-feedback
10857 This value is used to limit superblock formation once the given percentage of
10858 executed instructions is covered.  This limits unnecessary code size
10859 expansion.
10861 The @option{tracer-dynamic-coverage-feedback} parameter
10862 is used only when profile
10863 feedback is available.  The real profiles (as opposed to statically estimated
10864 ones) are much less balanced allowing the threshold to be larger value.
10866 @item tracer-max-code-growth
10867 Stop tail duplication once code growth has reached given percentage.  This is
10868 a rather artificial limit, as most of the duplicates are eliminated later in
10869 cross jumping, so it may be set to much higher values than is the desired code
10870 growth.
10872 @item tracer-min-branch-ratio
10874 Stop reverse growth when the reverse probability of best edge is less than this
10875 threshold (in percent).
10877 @item tracer-min-branch-probability
10878 @itemx tracer-min-branch-probability-feedback
10880 Stop forward growth if the best edge has probability lower than this
10881 threshold.
10883 Similarly to @option{tracer-dynamic-coverage} two parameters are
10884 provided.  @option{tracer-min-branch-probability-feedback} is used for
10885 compilation with profile feedback and @option{tracer-min-branch-probability}
10886 compilation without.  The value for compilation with profile feedback
10887 needs to be more conservative (higher) in order to make tracer
10888 effective.
10890 @item stack-clash-protection-guard-size
10891 Specify the size of the operating system provided stack guard as
10892 2 raised to @var{num} bytes.  Higher values may reduce the
10893 number of explicit probes, but a value larger than the operating system
10894 provided guard will leave code vulnerable to stack clash style attacks.
10896 @item stack-clash-protection-probe-interval
10897 Stack clash protection involves probing stack space as it is allocated.  This
10898 param controls the maximum distance between probes into the stack as 2 raised
10899 to @var{num} bytes.  Higher values may reduce the number of explicit probes, but a value
10900 larger than the operating system provided guard will leave code vulnerable to
10901 stack clash style attacks.
10903 @item max-cse-path-length
10905 The maximum number of basic blocks on path that CSE considers.
10907 @item max-cse-insns
10908 The maximum number of instructions CSE processes before flushing.
10910 @item ggc-min-expand
10912 GCC uses a garbage collector to manage its own memory allocation.  This
10913 parameter specifies the minimum percentage by which the garbage
10914 collector's heap should be allowed to expand between collections.
10915 Tuning this may improve compilation speed; it has no effect on code
10916 generation.
10918 The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
10919 RAM >= 1GB@.  If @code{getrlimit} is available, the notion of ``RAM'' is
10920 the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}.  If
10921 GCC is not able to calculate RAM on a particular platform, the lower
10922 bound of 30% is used.  Setting this parameter and
10923 @option{ggc-min-heapsize} to zero causes a full collection to occur at
10924 every opportunity.  This is extremely slow, but can be useful for
10925 debugging.
10927 @item ggc-min-heapsize
10929 Minimum size of the garbage collector's heap before it begins bothering
10930 to collect garbage.  The first collection occurs after the heap expands
10931 by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}.  Again,
10932 tuning this may improve compilation speed, and has no effect on code
10933 generation.
10935 The default is the smaller of RAM/8, RLIMIT_RSS, or a limit that
10936 tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
10937 with a lower bound of 4096 (four megabytes) and an upper bound of
10938 131072 (128 megabytes).  If GCC is not able to calculate RAM on a
10939 particular platform, the lower bound is used.  Setting this parameter
10940 very large effectively disables garbage collection.  Setting this
10941 parameter and @option{ggc-min-expand} to zero causes a full collection
10942 to occur at every opportunity.
10944 @item max-reload-search-insns
10945 The maximum number of instruction reload should look backward for equivalent
10946 register.  Increasing values mean more aggressive optimization, making the
10947 compilation time increase with probably slightly better performance.
10949 @item max-cselib-memory-locations
10950 The maximum number of memory locations cselib should take into account.
10951 Increasing values mean more aggressive optimization, making the compilation time
10952 increase with probably slightly better performance.
10954 @item max-sched-ready-insns
10955 The maximum number of instructions ready to be issued the scheduler should
10956 consider at any given time during the first scheduling pass.  Increasing
10957 values mean more thorough searches, making the compilation time increase
10958 with probably little benefit.
10960 @item max-sched-region-blocks
10961 The maximum number of blocks in a region to be considered for
10962 interblock scheduling.
10964 @item max-pipeline-region-blocks
10965 The maximum number of blocks in a region to be considered for
10966 pipelining in the selective scheduler.
10968 @item max-sched-region-insns
10969 The maximum number of insns in a region to be considered for
10970 interblock scheduling.
10972 @item max-pipeline-region-insns
10973 The maximum number of insns in a region to be considered for
10974 pipelining in the selective scheduler.
10976 @item min-spec-prob
10977 The minimum probability (in percents) of reaching a source block
10978 for interblock speculative scheduling.
10980 @item max-sched-extend-regions-iters
10981 The maximum number of iterations through CFG to extend regions.
10982 A value of 0 disables region extensions.
10984 @item max-sched-insn-conflict-delay
10985 The maximum conflict delay for an insn to be considered for speculative motion.
10987 @item sched-spec-prob-cutoff
10988 The minimal probability of speculation success (in percents), so that
10989 speculative insns are scheduled.
10991 @item sched-state-edge-prob-cutoff
10992 The minimum probability an edge must have for the scheduler to save its
10993 state across it.
10995 @item sched-mem-true-dep-cost
10996 Minimal distance (in CPU cycles) between store and load targeting same
10997 memory locations.
10999 @item selsched-max-lookahead
11000 The maximum size of the lookahead window of selective scheduling.  It is a
11001 depth of search for available instructions.
11003 @item selsched-max-sched-times
11004 The maximum number of times that an instruction is scheduled during
11005 selective scheduling.  This is the limit on the number of iterations
11006 through which the instruction may be pipelined.
11008 @item selsched-insns-to-rename
11009 The maximum number of best instructions in the ready list that are considered
11010 for renaming in the selective scheduler.
11012 @item sms-min-sc
11013 The minimum value of stage count that swing modulo scheduler
11014 generates.
11016 @item max-last-value-rtl
11017 The maximum size measured as number of RTLs that can be recorded in an expression
11018 in combiner for a pseudo register as last known value of that register.
11020 @item max-combine-insns
11021 The maximum number of instructions the RTL combiner tries to combine.
11023 @item integer-share-limit
11024 Small integer constants can use a shared data structure, reducing the
11025 compiler's memory usage and increasing its speed.  This sets the maximum
11026 value of a shared integer constant.
11028 @item ssp-buffer-size
11029 The minimum size of buffers (i.e.@: arrays) that receive stack smashing
11030 protection when @option{-fstack-protection} is used.
11032 @item min-size-for-stack-sharing
11033 The minimum size of variables taking part in stack slot sharing when not
11034 optimizing.
11036 @item max-jump-thread-duplication-stmts
11037 Maximum number of statements allowed in a block that needs to be
11038 duplicated when threading jumps.
11040 @item max-fields-for-field-sensitive
11041 Maximum number of fields in a structure treated in
11042 a field sensitive manner during pointer analysis.
11044 @item prefetch-latency
11045 Estimate on average number of instructions that are executed before
11046 prefetch finishes.  The distance prefetched ahead is proportional
11047 to this constant.  Increasing this number may also lead to less
11048 streams being prefetched (see @option{simultaneous-prefetches}).
11050 @item simultaneous-prefetches
11051 Maximum number of prefetches that can run at the same time.
11053 @item l1-cache-line-size
11054 The size of cache line in L1 cache, in bytes.
11056 @item l1-cache-size
11057 The size of L1 cache, in kilobytes.
11059 @item l2-cache-size
11060 The size of L2 cache, in kilobytes.
11062 @item prefetch-dynamic-strides
11063 Whether the loop array prefetch pass should issue software prefetch hints
11064 for strides that are non-constant.  In some cases this may be
11065 beneficial, though the fact the stride is non-constant may make it
11066 hard to predict when there is clear benefit to issuing these hints.
11068 Set to 1 if the prefetch hints should be issued for non-constant
11069 strides.  Set to 0 if prefetch hints should be issued only for strides that
11070 are known to be constant and below @option{prefetch-minimum-stride}.
11072 @item prefetch-minimum-stride
11073 Minimum constant stride, in bytes, to start using prefetch hints for.  If
11074 the stride is less than this threshold, prefetch hints will not be issued.
11076 This setting is useful for processors that have hardware prefetchers, in
11077 which case there may be conflicts between the hardware prefetchers and
11078 the software prefetchers.  If the hardware prefetchers have a maximum
11079 stride they can handle, it should be used here to improve the use of
11080 software prefetchers.
11082 A value of -1 means we don't have a threshold and therefore
11083 prefetch hints can be issued for any constant stride.
11085 This setting is only useful for strides that are known and constant.
11087 @item loop-interchange-max-num-stmts
11088 The maximum number of stmts in a loop to be interchanged.
11090 @item loop-interchange-stride-ratio
11091 The minimum ratio between stride of two loops for interchange to be profitable.
11093 @item min-insn-to-prefetch-ratio
11094 The minimum ratio between the number of instructions and the
11095 number of prefetches to enable prefetching in a loop.
11097 @item prefetch-min-insn-to-mem-ratio
11098 The minimum ratio between the number of instructions and the
11099 number of memory references to enable prefetching in a loop.
11101 @item use-canonical-types
11102 Whether the compiler should use the ``canonical'' type system.
11103 Should always be 1, which uses a more efficient internal
11104 mechanism for comparing types in C++ and Objective-C++.  However, if
11105 bugs in the canonical type system are causing compilation failures,
11106 set this value to 0 to disable canonical types.
11108 @item switch-conversion-max-branch-ratio
11109 Switch initialization conversion refuses to create arrays that are
11110 bigger than @option{switch-conversion-max-branch-ratio} times the number of
11111 branches in the switch.
11113 @item max-partial-antic-length
11114 Maximum length of the partial antic set computed during the tree
11115 partial redundancy elimination optimization (@option{-ftree-pre}) when
11116 optimizing at @option{-O3} and above.  For some sorts of source code
11117 the enhanced partial redundancy elimination optimization can run away,
11118 consuming all of the memory available on the host machine.  This
11119 parameter sets a limit on the length of the sets that are computed,
11120 which prevents the runaway behavior.  Setting a value of 0 for
11121 this parameter allows an unlimited set length.
11123 @item rpo-vn-max-loop-depth
11124 Maximum loop depth that is value-numbered optimistically.
11125 When the limit hits the innermost
11126 @var{rpo-vn-max-loop-depth} loops and the outermost loop in the
11127 loop nest are value-numbered optimistically and the remaining ones not.
11129 @item sccvn-max-alias-queries-per-access
11130 Maximum number of alias-oracle queries we perform when looking for
11131 redundancies for loads and stores.  If this limit is hit the search
11132 is aborted and the load or store is not considered redundant.  The
11133 number of queries is algorithmically limited to the number of
11134 stores on all paths from the load to the function entry.
11136 @item ira-max-loops-num
11137 IRA uses regional register allocation by default.  If a function
11138 contains more loops than the number given by this parameter, only at most
11139 the given number of the most frequently-executed loops form regions
11140 for regional register allocation.
11142 @item ira-max-conflict-table-size 
11143 Although IRA uses a sophisticated algorithm to compress the conflict
11144 table, the table can still require excessive amounts of memory for
11145 huge functions.  If the conflict table for a function could be more
11146 than the size in MB given by this parameter, the register allocator
11147 instead uses a faster, simpler, and lower-quality
11148 algorithm that does not require building a pseudo-register conflict table.  
11150 @item ira-loop-reserved-regs
11151 IRA can be used to evaluate more accurate register pressure in loops
11152 for decisions to move loop invariants (see @option{-O3}).  The number
11153 of available registers reserved for some other purposes is given
11154 by this parameter.  Default of the parameter
11155 is the best found from numerous experiments.
11157 @item lra-inheritance-ebb-probability-cutoff
11158 LRA tries to reuse values reloaded in registers in subsequent insns.
11159 This optimization is called inheritance.  EBB is used as a region to
11160 do this optimization.  The parameter defines a minimal fall-through
11161 edge probability in percentage used to add BB to inheritance EBB in
11162 LRA.  The default value was chosen
11163 from numerous runs of SPEC2000 on x86-64.
11165 @item loop-invariant-max-bbs-in-loop
11166 Loop invariant motion can be very expensive, both in compilation time and
11167 in amount of needed compile-time memory, with very large loops.  Loops
11168 with more basic blocks than this parameter won't have loop invariant
11169 motion optimization performed on them.
11171 @item loop-max-datarefs-for-datadeps
11172 Building data dependencies is expensive for very large loops.  This
11173 parameter limits the number of data references in loops that are
11174 considered for data dependence analysis.  These large loops are no
11175 handled by the optimizations using loop data dependencies.
11177 @item max-vartrack-size
11178 Sets a maximum number of hash table slots to use during variable
11179 tracking dataflow analysis of any function.  If this limit is exceeded
11180 with variable tracking at assignments enabled, analysis for that
11181 function is retried without it, after removing all debug insns from
11182 the function.  If the limit is exceeded even without debug insns, var
11183 tracking analysis is completely disabled for the function.  Setting
11184 the parameter to zero makes it unlimited.
11186 @item max-vartrack-expr-depth
11187 Sets a maximum number of recursion levels when attempting to map
11188 variable names or debug temporaries to value expressions.  This trades
11189 compilation time for more complete debug information.  If this is set too
11190 low, value expressions that are available and could be represented in
11191 debug information may end up not being used; setting this higher may
11192 enable the compiler to find more complex debug expressions, but compile
11193 time and memory use may grow.
11195 @item max-debug-marker-count
11196 Sets a threshold on the number of debug markers (e.g. begin stmt
11197 markers) to avoid complexity explosion at inlining or expanding to RTL.
11198 If a function has more such gimple stmts than the set limit, such stmts
11199 will be dropped from the inlined copy of a function, and from its RTL
11200 expansion.
11202 @item min-nondebug-insn-uid
11203 Use uids starting at this parameter for nondebug insns.  The range below
11204 the parameter is reserved exclusively for debug insns created by
11205 @option{-fvar-tracking-assignments}, but debug insns may get
11206 (non-overlapping) uids above it if the reserved range is exhausted.
11208 @item ipa-sra-ptr-growth-factor
11209 IPA-SRA replaces a pointer to an aggregate with one or more new
11210 parameters only when their cumulative size is less or equal to
11211 @option{ipa-sra-ptr-growth-factor} times the size of the original
11212 pointer parameter.
11214 @item sra-max-scalarization-size-Ospeed
11215 @itemx sra-max-scalarization-size-Osize
11216 The two Scalar Reduction of Aggregates passes (SRA and IPA-SRA) aim to
11217 replace scalar parts of aggregates with uses of independent scalar
11218 variables.  These parameters control the maximum size, in storage units,
11219 of aggregate which is considered for replacement when compiling for
11220 speed
11221 (@option{sra-max-scalarization-size-Ospeed}) or size
11222 (@option{sra-max-scalarization-size-Osize}) respectively.
11224 @item tm-max-aggregate-size
11225 When making copies of thread-local variables in a transaction, this
11226 parameter specifies the size in bytes after which variables are
11227 saved with the logging functions as opposed to save/restore code
11228 sequence pairs.  This option only applies when using
11229 @option{-fgnu-tm}.
11231 @item graphite-max-nb-scop-params
11232 To avoid exponential effects in the Graphite loop transforms, the
11233 number of parameters in a Static Control Part (SCoP) is bounded.
11234 A value of zero can be used to lift
11235 the bound.  A variable whose value is unknown at compilation time and
11236 defined outside a SCoP is a parameter of the SCoP.
11238 @item loop-block-tile-size
11239 Loop blocking or strip mining transforms, enabled with
11240 @option{-floop-block} or @option{-floop-strip-mine}, strip mine each
11241 loop in the loop nest by a given number of iterations.  The strip
11242 length can be changed using the @option{loop-block-tile-size}
11243 parameter.
11245 @item ipa-cp-value-list-size
11246 IPA-CP attempts to track all possible values and types passed to a function's
11247 parameter in order to propagate them and perform devirtualization.
11248 @option{ipa-cp-value-list-size} is the maximum number of values and types it
11249 stores per one formal parameter of a function.
11251 @item ipa-cp-eval-threshold
11252 IPA-CP calculates its own score of cloning profitability heuristics
11253 and performs those cloning opportunities with scores that exceed
11254 @option{ipa-cp-eval-threshold}.
11256 @item ipa-cp-recursion-penalty
11257 Percentage penalty the recursive functions will receive when they
11258 are evaluated for cloning.
11260 @item ipa-cp-single-call-penalty
11261 Percentage penalty functions containing a single call to another
11262 function will receive when they are evaluated for cloning.
11264 @item ipa-max-agg-items
11265 IPA-CP is also capable to propagate a number of scalar values passed
11266 in an aggregate. @option{ipa-max-agg-items} controls the maximum
11267 number of such values per one parameter.
11269 @item ipa-cp-loop-hint-bonus
11270 When IPA-CP determines that a cloning candidate would make the number
11271 of iterations of a loop known, it adds a bonus of
11272 @option{ipa-cp-loop-hint-bonus} to the profitability score of
11273 the candidate.
11275 @item ipa-cp-array-index-hint-bonus
11276 When IPA-CP determines that a cloning candidate would make the index of
11277 an array access known, it adds a bonus of
11278 @option{ipa-cp-array-index-hint-bonus} to the profitability
11279 score of the candidate.
11281 @item ipa-max-aa-steps
11282 During its analysis of function bodies, IPA-CP employs alias analysis
11283 in order to track values pointed to by function parameters.  In order
11284 not spend too much time analyzing huge functions, it gives up and
11285 consider all memory clobbered after examining
11286 @option{ipa-max-aa-steps} statements modifying memory.
11288 @item lto-partitions
11289 Specify desired number of partitions produced during WHOPR compilation.
11290 The number of partitions should exceed the number of CPUs used for compilation.
11292 @item lto-min-partition
11293 Size of minimal partition for WHOPR (in estimated instructions).
11294 This prevents expenses of splitting very small programs into too many
11295 partitions.
11297 @item lto-max-partition
11298 Size of max partition for WHOPR (in estimated instructions).
11299 to provide an upper bound for individual size of partition.
11300 Meant to be used only with balanced partitioning.
11302 @item cxx-max-namespaces-for-diagnostic-help
11303 The maximum number of namespaces to consult for suggestions when C++
11304 name lookup fails for an identifier.
11306 @item sink-frequency-threshold
11307 The maximum relative execution frequency (in percents) of the target block
11308 relative to a statement's original block to allow statement sinking of a
11309 statement.  Larger numbers result in more aggressive statement sinking.
11310 A small positive adjustment is applied for
11311 statements with memory operands as those are even more profitable so sink.
11313 @item max-stores-to-sink
11314 The maximum number of conditional store pairs that can be sunk.  Set to 0
11315 if either vectorization (@option{-ftree-vectorize}) or if-conversion
11316 (@option{-ftree-loop-if-convert}) is disabled.
11318 @item allow-store-data-races
11319 Allow optimizers to introduce new data races on stores.
11320 Set to 1 to allow, otherwise to 0.
11322 @item case-values-threshold
11323 The smallest number of different values for which it is best to use a
11324 jump-table instead of a tree of conditional branches.  If the value is
11325 0, use the default for the machine.
11327 @item tree-reassoc-width
11328 Set the maximum number of instructions executed in parallel in
11329 reassociated tree. This parameter overrides target dependent
11330 heuristics used by default if has non zero value.
11332 @item sched-pressure-algorithm
11333 Choose between the two available implementations of
11334 @option{-fsched-pressure}.  Algorithm 1 is the original implementation
11335 and is the more likely to prevent instructions from being reordered.
11336 Algorithm 2 was designed to be a compromise between the relatively
11337 conservative approach taken by algorithm 1 and the rather aggressive
11338 approach taken by the default scheduler.  It relies more heavily on
11339 having a regular register file and accurate register pressure classes.
11340 See @file{haifa-sched.c} in the GCC sources for more details.
11342 The default choice depends on the target.
11344 @item max-slsr-cand-scan
11345 Set the maximum number of existing candidates that are considered when
11346 seeking a basis for a new straight-line strength reduction candidate.
11348 @item asan-globals
11349 Enable buffer overflow detection for global objects.  This kind
11350 of protection is enabled by default if you are using
11351 @option{-fsanitize=address} option.
11352 To disable global objects protection use @option{--param asan-globals=0}.
11354 @item asan-stack
11355 Enable buffer overflow detection for stack objects.  This kind of
11356 protection is enabled by default when using @option{-fsanitize=address}.
11357 To disable stack protection use @option{--param asan-stack=0} option.
11359 @item asan-instrument-reads
11360 Enable buffer overflow detection for memory reads.  This kind of
11361 protection is enabled by default when using @option{-fsanitize=address}.
11362 To disable memory reads protection use
11363 @option{--param asan-instrument-reads=0}.
11365 @item asan-instrument-writes
11366 Enable buffer overflow detection for memory writes.  This kind of
11367 protection is enabled by default when using @option{-fsanitize=address}.
11368 To disable memory writes protection use
11369 @option{--param asan-instrument-writes=0} option.
11371 @item asan-memintrin
11372 Enable detection for built-in functions.  This kind of protection
11373 is enabled by default when using @option{-fsanitize=address}.
11374 To disable built-in functions protection use
11375 @option{--param asan-memintrin=0}.
11377 @item asan-use-after-return
11378 Enable detection of use-after-return.  This kind of protection
11379 is enabled by default when using the @option{-fsanitize=address} option.
11380 To disable it use @option{--param asan-use-after-return=0}.
11382 Note: By default the check is disabled at run time.  To enable it,
11383 add @code{detect_stack_use_after_return=1} to the environment variable
11384 @env{ASAN_OPTIONS}.
11386 @item asan-instrumentation-with-call-threshold
11387 If number of memory accesses in function being instrumented
11388 is greater or equal to this number, use callbacks instead of inline checks.
11389 E.g. to disable inline code use
11390 @option{--param asan-instrumentation-with-call-threshold=0}.
11392 @item use-after-scope-direct-emission-threshold
11393 If the size of a local variable in bytes is smaller or equal to this
11394 number, directly poison (or unpoison) shadow memory instead of using
11395 run-time callbacks.
11397 @item max-fsm-thread-path-insns
11398 Maximum number of instructions to copy when duplicating blocks on a
11399 finite state automaton jump thread path.
11401 @item max-fsm-thread-length
11402 Maximum number of basic blocks on a finite state automaton jump thread
11403 path.
11405 @item max-fsm-thread-paths
11406 Maximum number of new jump thread paths to create for a finite state
11407 automaton.
11409 @item parloops-chunk-size
11410 Chunk size of omp schedule for loops parallelized by parloops.
11412 @item parloops-schedule
11413 Schedule type of omp schedule for loops parallelized by parloops (static,
11414 dynamic, guided, auto, runtime).
11416 @item parloops-min-per-thread
11417 The minimum number of iterations per thread of an innermost parallelized
11418 loop for which the parallelized variant is preferred over the single threaded
11419 one.  Note that for a parallelized loop nest the
11420 minimum number of iterations of the outermost loop per thread is two.
11422 @item max-ssa-name-query-depth
11423 Maximum depth of recursion when querying properties of SSA names in things
11424 like fold routines.  One level of recursion corresponds to following a
11425 use-def chain.
11427 @item hsa-gen-debug-stores
11428 Enable emission of special debug stores within HSA kernels which are
11429 then read and reported by libgomp plugin.  Generation of these stores
11430 is disabled by default, use @option{--param hsa-gen-debug-stores=1} to
11431 enable it.
11433 @item max-speculative-devirt-maydefs
11434 The maximum number of may-defs we analyze when looking for a must-def
11435 specifying the dynamic type of an object that invokes a virtual call
11436 we may be able to devirtualize speculatively.
11438 @item max-vrp-switch-assertions
11439 The maximum number of assertions to add along the default edge of a switch
11440 statement during VRP.
11442 @item unroll-jam-min-percent
11443 The minimum percentage of memory references that must be optimized
11444 away for the unroll-and-jam transformation to be considered profitable.
11446 @item unroll-jam-max-unroll
11447 The maximum number of times the outer loop should be unrolled by
11448 the unroll-and-jam transformation.
11450 @item max-rtl-if-conversion-unpredictable-cost
11451 Maximum permissible cost for the sequence that would be generated
11452 by the RTL if-conversion pass for a branch that is considered unpredictable.
11454 @item max-variable-expansions-in-unroller
11455 If @option{-fvariable-expansion-in-unroller} is used, the maximum number
11456 of times that an individual variable will be expanded during loop unrolling.
11458 @item tracer-min-branch-probability-feedback
11459 Stop forward growth if the probability of best edge is less than
11460 this threshold (in percent). Used when profile feedback is available.
11462 @item partial-inlining-entry-probability
11463 Maximum probability of the entry BB of split region
11464 (in percent relative to entry BB of the function)
11465 to make partial inlining happen.
11467 @item max-tracked-strlens
11468 Maximum number of strings for which strlen optimization pass will
11469 track string lengths.
11471 @item gcse-after-reload-partial-fraction
11472 The threshold ratio for performing partial redundancy
11473 elimination after reload.
11475 @item gcse-after-reload-critical-fraction
11476 The threshold ratio of critical edges execution count that
11477 permit performing redundancy elimination after reload.
11479 @item max-loop-header-insns
11480 The maximum number of insns in loop header duplicated
11481 by the copy loop headers pass.
11483 @item vect-epilogues-nomask
11484 Enable loop epilogue vectorization using smaller vector size.
11486 @item slp-max-insns-in-bb
11487 Maximum number of instructions in basic block to be
11488 considered for SLP vectorization.
11490 @item avoid-fma-max-bits
11491 Maximum number of bits for which we avoid creating FMAs.
11493 @item sms-loop-average-count-threshold
11494 A threshold on the average loop count considered by the swing modulo scheduler.
11496 @item sms-dfa-history
11497 The number of cycles the swing modulo scheduler considers when checking
11498 conflicts using DFA.
11500 @item hot-bb-count-fraction
11501 Select fraction of the maximal count of repetitions of basic block
11502 in program given basic block needs
11503 to have to be considered hot (used in non-LTO mode)
11505 @item max-inline-insns-recursive-auto
11506 The maximum number of instructions non-inline function
11507 can grow to via recursive inlining.
11509 @item graphite-allow-codegen-errors
11510 Whether codegen errors should be ICEs when @option{-fchecking}.
11512 @item sms-max-ii-factor
11513 A factor for tuning the upper bound that swing modulo scheduler
11514 uses for scheduling a loop.
11516 @item lra-max-considered-reload-pseudos
11517 The max number of reload pseudos which are considered during
11518 spilling a non-reload pseudo.
11520 @item max-pow-sqrt-depth
11521 Maximum depth of sqrt chains to use when synthesizing exponentiation
11522 by a real constant.
11524 @item max-dse-active-local-stores
11525 Maximum number of active local stores in RTL dead store elimination.
11527 @item asan-instrument-allocas
11528 Enable asan allocas/VLAs protection.
11530 @item max-iterations-computation-cost
11531 Bound on the cost of an expression to compute the number of iterations.
11533 @item max-isl-operations
11534 Maximum number of isl operations, 0 means unlimited.
11536 @item graphite-max-arrays-per-scop
11537 Maximum number of arrays per scop.
11539 @item max-vartrack-reverse-op-size
11540 Max. size of loc list for which reverse ops should be added.
11542 @item unlikely-bb-count-fraction
11543 The minimum fraction of profile runs a given basic block execution count
11544 must be not to be considered unlikely.
11546 @item tracer-dynamic-coverage-feedback
11547 The percentage of function, weighted by execution frequency,
11548 that must be covered by trace formation.
11549 Used when profile feedback is available.
11551 @item max-inline-recursive-depth-auto
11552 The maximum depth of recursive inlining for non-inline functions.
11554 @item fsm-scale-path-stmts
11555 Scale factor to apply to the number of statements in a threading path
11556 when comparing to the number of (scaled) blocks.
11558 @item fsm-maximum-phi-arguments
11559 Maximum number of arguments a PHI may have before the FSM threader
11560 will not try to thread through its block.
11562 @item uninit-control-dep-attempts
11563 Maximum number of nested calls to search for control dependencies
11564 during uninitialized variable analysis.
11566 @item indir-call-topn-profile
11567 Track top N target addresses in indirect-call profile.
11569 @item max-once-peeled-insns
11570 The maximum number of insns of a peeled loop that rolls only once.
11572 @item sra-max-scalarization-size-Osize
11573 Maximum size, in storage units, of an aggregate
11574 which should be considered for scalarization when compiling for size.
11576 @item fsm-scale-path-blocks
11577 Scale factor to apply to the number of blocks in a threading path
11578 when comparing to the number of (scaled) statements.
11580 @item sched-autopref-queue-depth
11581 Hardware autoprefetcher scheduler model control flag.
11582 Number of lookahead cycles the model looks into; at '
11583 ' only enable instruction sorting heuristic.
11586 @end table
11587 @end table
11589 @node Instrumentation Options
11590 @section Program Instrumentation Options
11591 @cindex instrumentation options
11592 @cindex program instrumentation options
11593 @cindex run-time error checking options
11594 @cindex profiling options
11595 @cindex options, program instrumentation
11596 @cindex options, run-time error checking
11597 @cindex options, profiling
11599 GCC supports a number of command-line options that control adding
11600 run-time instrumentation to the code it normally generates.  
11601 For example, one purpose of instrumentation is collect profiling
11602 statistics for use in finding program hot spots, code coverage
11603 analysis, or profile-guided optimizations.
11604 Another class of program instrumentation is adding run-time checking 
11605 to detect programming errors like invalid pointer
11606 dereferences or out-of-bounds array accesses, as well as deliberately
11607 hostile attacks such as stack smashing or C++ vtable hijacking.
11608 There is also a general hook which can be used to implement other
11609 forms of tracing or function-level instrumentation for debug or
11610 program analysis purposes.
11612 @table @gcctabopt
11613 @cindex @command{prof}
11614 @item -p
11615 @opindex p
11616 Generate extra code to write profile information suitable for the
11617 analysis program @command{prof}.  You must use this option when compiling
11618 the source files you want data about, and you must also use it when
11619 linking.
11621 @cindex @command{gprof}
11622 @item -pg
11623 @opindex pg
11624 Generate extra code to write profile information suitable for the
11625 analysis program @command{gprof}.  You must use this option when compiling
11626 the source files you want data about, and you must also use it when
11627 linking.
11629 @item -fprofile-arcs
11630 @opindex fprofile-arcs
11631 Add code so that program flow @dfn{arcs} are instrumented.  During
11632 execution the program records how many times each branch and call is
11633 executed and how many times it is taken or returns.  On targets that support
11634 constructors with priority support, profiling properly handles constructors,
11635 destructors and C++ constructors (and destructors) of classes which are used
11636 as a type of a global variable.
11638 When the compiled
11639 program exits it saves this data to a file called
11640 @file{@var{auxname}.gcda} for each source file.  The data may be used for
11641 profile-directed optimizations (@option{-fbranch-probabilities}), or for
11642 test coverage analysis (@option{-ftest-coverage}).  Each object file's
11643 @var{auxname} is generated from the name of the output file, if
11644 explicitly specified and it is not the final executable, otherwise it is
11645 the basename of the source file.  In both cases any suffix is removed
11646 (e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
11647 @file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
11648 @xref{Cross-profiling}.
11650 @cindex @command{gcov}
11651 @item --coverage
11652 @opindex coverage
11654 This option is used to compile and link code instrumented for coverage
11655 analysis.  The option is a synonym for @option{-fprofile-arcs}
11656 @option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
11657 linking).  See the documentation for those options for more details.
11659 @itemize
11661 @item
11662 Compile the source files with @option{-fprofile-arcs} plus optimization
11663 and code generation options.  For test coverage analysis, use the
11664 additional @option{-ftest-coverage} option.  You do not need to profile
11665 every source file in a program.
11667 @item
11668 Compile the source files additionally with @option{-fprofile-abs-path}
11669 to create absolute path names in the @file{.gcno} files.  This allows
11670 @command{gcov} to find the correct sources in projects where compilations
11671 occur with different working directories.
11673 @item
11674 Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
11675 (the latter implies the former).
11677 @item
11678 Run the program on a representative workload to generate the arc profile
11679 information.  This may be repeated any number of times.  You can run
11680 concurrent instances of your program, and provided that the file system
11681 supports locking, the data files will be correctly updated.  Unless
11682 a strict ISO C dialect option is in effect, @code{fork} calls are
11683 detected and correctly handled without double counting.
11685 @item
11686 For profile-directed optimizations, compile the source files again with
11687 the same optimization and code generation options plus
11688 @option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
11689 Control Optimization}).
11691 @item
11692 For test coverage analysis, use @command{gcov} to produce human readable
11693 information from the @file{.gcno} and @file{.gcda} files.  Refer to the
11694 @command{gcov} documentation for further information.
11696 @end itemize
11698 With @option{-fprofile-arcs}, for each function of your program GCC
11699 creates a program flow graph, then finds a spanning tree for the graph.
11700 Only arcs that are not on the spanning tree have to be instrumented: the
11701 compiler adds code to count the number of times that these arcs are
11702 executed.  When an arc is the only exit or only entrance to a block, the
11703 instrumentation code can be added to the block; otherwise, a new basic
11704 block must be created to hold the instrumentation code.
11706 @need 2000
11707 @item -ftest-coverage
11708 @opindex ftest-coverage
11709 Produce a notes file that the @command{gcov} code-coverage utility
11710 (@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
11711 show program coverage.  Each source file's note file is called
11712 @file{@var{auxname}.gcno}.  Refer to the @option{-fprofile-arcs} option
11713 above for a description of @var{auxname} and instructions on how to
11714 generate test coverage data.  Coverage data matches the source files
11715 more closely if you do not optimize.
11717 @item -fprofile-abs-path
11718 @opindex fprofile-abs-path
11719 Automatically convert relative source file names to absolute path names
11720 in the @file{.gcno} files.  This allows @command{gcov} to find the correct
11721 sources in projects where compilations occur with different working
11722 directories.
11724 @item -fprofile-dir=@var{path}
11725 @opindex fprofile-dir
11727 Set the directory to search for the profile data files in to @var{path}.
11728 This option affects only the profile data generated by
11729 @option{-fprofile-generate}, @option{-ftest-coverage}, @option{-fprofile-arcs}
11730 and used by @option{-fprofile-use} and @option{-fbranch-probabilities}
11731 and its related options.  Both absolute and relative paths can be used.
11732 By default, GCC uses the current directory as @var{path}, thus the
11733 profile data file appears in the same directory as the object file.
11734 In order to prevent the file name clashing, if the object file name is
11735 not an absolute path, we mangle the absolute path of the
11736 @file{@var{sourcename}.gcda} file and use it as the file name of a
11737 @file{.gcda} file.
11739 When an executable is run in a massive parallel environment, it is recommended
11740 to save profile to different folders.  That can be done with variables
11741 in @var{path} that are exported during run-time:
11743 @table @gcctabopt
11745 @item %p
11746 process ID.
11748 @item %q@{VAR@}
11749 value of environment variable @var{VAR}
11751 @end table
11753 @item -fprofile-generate
11754 @itemx -fprofile-generate=@var{path}
11755 @opindex fprofile-generate
11757 Enable options usually used for instrumenting application to produce
11758 profile useful for later recompilation with profile feedback based
11759 optimization.  You must use @option{-fprofile-generate} both when
11760 compiling and when linking your program.
11762 The following options are enabled: @option{-fprofile-arcs}, @option{-fprofile-values}, @option{-fvpt}.
11764 If @var{path} is specified, GCC looks at the @var{path} to find
11765 the profile feedback data files. See @option{-fprofile-dir}.
11767 To optimize the program based on the collected profile information, use
11768 @option{-fprofile-use}.  @xref{Optimize Options}, for more information.
11770 @item -fprofile-update=@var{method}
11771 @opindex fprofile-update
11773 Alter the update method for an application instrumented for profile
11774 feedback based optimization.  The @var{method} argument should be one of
11775 @samp{single}, @samp{atomic} or @samp{prefer-atomic}.
11776 The first one is useful for single-threaded applications,
11777 while the second one prevents profile corruption by emitting thread-safe code.
11779 @strong{Warning:} When an application does not properly join all threads
11780 (or creates an detached thread), a profile file can be still corrupted.
11782 Using @samp{prefer-atomic} would be transformed either to @samp{atomic},
11783 when supported by a target, or to @samp{single} otherwise.  The GCC driver
11784 automatically selects @samp{prefer-atomic} when @option{-pthread}
11785 is present in the command line.
11787 @item -fsanitize=address
11788 @opindex fsanitize=address
11789 Enable AddressSanitizer, a fast memory error detector.
11790 Memory access instructions are instrumented to detect
11791 out-of-bounds and use-after-free bugs.
11792 The option enables @option{-fsanitize-address-use-after-scope}.
11793 See @uref{https://github.com/google/sanitizers/wiki/AddressSanitizer} for
11794 more details.  The run-time behavior can be influenced using the
11795 @env{ASAN_OPTIONS} environment variable.  When set to @code{help=1},
11796 the available options are shown at startup of the instrumented program.  See
11797 @url{https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags}
11798 for a list of supported options.
11799 The option cannot be combined with @option{-fsanitize=thread}.
11801 @item -fsanitize=kernel-address
11802 @opindex fsanitize=kernel-address
11803 Enable AddressSanitizer for Linux kernel.
11804 See @uref{https://github.com/google/kasan/wiki} for more details.
11806 @item -fsanitize=pointer-compare
11807 @opindex fsanitize=pointer-compare
11808 Instrument comparison operation (<, <=, >, >=) with pointer operands.
11809 The option must be combined with either @option{-fsanitize=kernel-address} or
11810 @option{-fsanitize=address}
11811 The option cannot be combined with @option{-fsanitize=thread}.
11812 Note: By default the check is disabled at run time.  To enable it,
11813 add @code{detect_invalid_pointer_pairs=2} to the environment variable
11814 @env{ASAN_OPTIONS}. Using @code{detect_invalid_pointer_pairs=1} detects
11815 invalid operation only when both pointers are non-null.
11817 @item -fsanitize=pointer-subtract
11818 @opindex fsanitize=pointer-subtract
11819 Instrument subtraction with pointer operands.
11820 The option must be combined with either @option{-fsanitize=kernel-address} or
11821 @option{-fsanitize=address}
11822 The option cannot be combined with @option{-fsanitize=thread}.
11823 Note: By default the check is disabled at run time.  To enable it,
11824 add @code{detect_invalid_pointer_pairs=2} to the environment variable
11825 @env{ASAN_OPTIONS}. Using @code{detect_invalid_pointer_pairs=1} detects
11826 invalid operation only when both pointers are non-null.
11828 @item -fsanitize=thread
11829 @opindex fsanitize=thread
11830 Enable ThreadSanitizer, a fast data race detector.
11831 Memory access instructions are instrumented to detect
11832 data race bugs.  See @uref{https://github.com/google/sanitizers/wiki#threadsanitizer} for more
11833 details. The run-time behavior can be influenced using the @env{TSAN_OPTIONS}
11834 environment variable; see
11835 @url{https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags} for a list of
11836 supported options.
11837 The option cannot be combined with @option{-fsanitize=address},
11838 @option{-fsanitize=leak}.
11840 Note that sanitized atomic builtins cannot throw exceptions when
11841 operating on invalid memory addresses with non-call exceptions
11842 (@option{-fnon-call-exceptions}).
11844 @item -fsanitize=leak
11845 @opindex fsanitize=leak
11846 Enable LeakSanitizer, a memory leak detector.
11847 This option only matters for linking of executables and
11848 the executable is linked against a library that overrides @code{malloc}
11849 and other allocator functions.  See
11850 @uref{https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer} for more
11851 details.  The run-time behavior can be influenced using the
11852 @env{LSAN_OPTIONS} environment variable.
11853 The option cannot be combined with @option{-fsanitize=thread}.
11855 @item -fsanitize=undefined
11856 @opindex fsanitize=undefined
11857 Enable UndefinedBehaviorSanitizer, a fast undefined behavior detector.
11858 Various computations are instrumented to detect undefined behavior
11859 at runtime.  Current suboptions are:
11861 @table @gcctabopt
11863 @item -fsanitize=shift
11864 @opindex fsanitize=shift
11865 This option enables checking that the result of a shift operation is
11866 not undefined.  Note that what exactly is considered undefined differs
11867 slightly between C and C++, as well as between ISO C90 and C99, etc.
11868 This option has two suboptions, @option{-fsanitize=shift-base} and
11869 @option{-fsanitize=shift-exponent}.
11871 @item -fsanitize=shift-exponent
11872 @opindex fsanitize=shift-exponent
11873 This option enables checking that the second argument of a shift operation
11874 is not negative and is smaller than the precision of the promoted first
11875 argument.
11877 @item -fsanitize=shift-base
11878 @opindex fsanitize=shift-base
11879 If the second argument of a shift operation is within range, check that the
11880 result of a shift operation is not undefined.  Note that what exactly is
11881 considered undefined differs slightly between C and C++, as well as between
11882 ISO C90 and C99, etc.
11884 @item -fsanitize=integer-divide-by-zero
11885 @opindex fsanitize=integer-divide-by-zero
11886 Detect integer division by zero as well as @code{INT_MIN / -1} division.
11888 @item -fsanitize=unreachable
11889 @opindex fsanitize=unreachable
11890 With this option, the compiler turns the @code{__builtin_unreachable}
11891 call into a diagnostics message call instead.  When reaching the
11892 @code{__builtin_unreachable} call, the behavior is undefined.
11894 @item -fsanitize=vla-bound
11895 @opindex fsanitize=vla-bound
11896 This option instructs the compiler to check that the size of a variable
11897 length array is positive.
11899 @item -fsanitize=null
11900 @opindex fsanitize=null
11901 This option enables pointer checking.  Particularly, the application
11902 built with this option turned on will issue an error message when it
11903 tries to dereference a NULL pointer, or if a reference (possibly an
11904 rvalue reference) is bound to a NULL pointer, or if a method is invoked
11905 on an object pointed by a NULL pointer.
11907 @item -fsanitize=return
11908 @opindex fsanitize=return
11909 This option enables return statement checking.  Programs
11910 built with this option turned on will issue an error message
11911 when the end of a non-void function is reached without actually
11912 returning a value.  This option works in C++ only.
11914 @item -fsanitize=signed-integer-overflow
11915 @opindex fsanitize=signed-integer-overflow
11916 This option enables signed integer overflow checking.  We check that
11917 the result of @code{+}, @code{*}, and both unary and binary @code{-}
11918 does not overflow in the signed arithmetics.  Note, integer promotion
11919 rules must be taken into account.  That is, the following is not an
11920 overflow:
11921 @smallexample
11922 signed char a = SCHAR_MAX;
11923 a++;
11924 @end smallexample
11926 @item -fsanitize=bounds
11927 @opindex fsanitize=bounds
11928 This option enables instrumentation of array bounds.  Various out of bounds
11929 accesses are detected.  Flexible array members, flexible array member-like
11930 arrays, and initializers of variables with static storage are not instrumented.
11932 @item -fsanitize=bounds-strict
11933 @opindex fsanitize=bounds-strict
11934 This option enables strict instrumentation of array bounds.  Most out of bounds
11935 accesses are detected, including flexible array members and flexible array
11936 member-like arrays.  Initializers of variables with static storage are not
11937 instrumented.
11939 @item -fsanitize=alignment
11940 @opindex fsanitize=alignment
11942 This option enables checking of alignment of pointers when they are
11943 dereferenced, or when a reference is bound to insufficiently aligned target,
11944 or when a method or constructor is invoked on insufficiently aligned object.
11946 @item -fsanitize=object-size
11947 @opindex fsanitize=object-size
11948 This option enables instrumentation of memory references using the
11949 @code{__builtin_object_size} function.  Various out of bounds pointer
11950 accesses are detected.
11952 @item -fsanitize=float-divide-by-zero
11953 @opindex fsanitize=float-divide-by-zero
11954 Detect floating-point division by zero.  Unlike other similar options,
11955 @option{-fsanitize=float-divide-by-zero} is not enabled by
11956 @option{-fsanitize=undefined}, since floating-point division by zero can
11957 be a legitimate way of obtaining infinities and NaNs.
11959 @item -fsanitize=float-cast-overflow
11960 @opindex fsanitize=float-cast-overflow
11961 This option enables floating-point type to integer conversion checking.
11962 We check that the result of the conversion does not overflow.
11963 Unlike other similar options, @option{-fsanitize=float-cast-overflow} is
11964 not enabled by @option{-fsanitize=undefined}.
11965 This option does not work well with @code{FE_INVALID} exceptions enabled.
11967 @item -fsanitize=nonnull-attribute
11968 @opindex fsanitize=nonnull-attribute
11970 This option enables instrumentation of calls, checking whether null values
11971 are not passed to arguments marked as requiring a non-null value by the
11972 @code{nonnull} function attribute.
11974 @item -fsanitize=returns-nonnull-attribute
11975 @opindex fsanitize=returns-nonnull-attribute
11977 This option enables instrumentation of return statements in functions
11978 marked with @code{returns_nonnull} function attribute, to detect returning
11979 of null values from such functions.
11981 @item -fsanitize=bool
11982 @opindex fsanitize=bool
11984 This option enables instrumentation of loads from bool.  If a value other
11985 than 0/1 is loaded, a run-time error is issued.
11987 @item -fsanitize=enum
11988 @opindex fsanitize=enum
11990 This option enables instrumentation of loads from an enum type.  If
11991 a value outside the range of values for the enum type is loaded,
11992 a run-time error is issued.
11994 @item -fsanitize=vptr
11995 @opindex fsanitize=vptr
11997 This option enables instrumentation of C++ member function calls, member
11998 accesses and some conversions between pointers to base and derived classes,
11999 to verify the referenced object has the correct dynamic type.
12001 @item -fsanitize=pointer-overflow
12002 @opindex fsanitize=pointer-overflow
12004 This option enables instrumentation of pointer arithmetics.  If the pointer
12005 arithmetics overflows, a run-time error is issued.
12007 @item -fsanitize=builtin
12008 @opindex fsanitize=builtin
12010 This option enables instrumentation of arguments to selected builtin
12011 functions.  If an invalid value is passed to such arguments, a run-time
12012 error is issued.  E.g.@ passing 0 as the argument to @code{__builtin_ctz}
12013 or @code{__builtin_clz} invokes undefined behavior and is diagnosed
12014 by this option.
12016 @end table
12018 While @option{-ftrapv} causes traps for signed overflows to be emitted,
12019 @option{-fsanitize=undefined} gives a diagnostic message.
12020 This currently works only for the C family of languages.
12022 @item -fno-sanitize=all
12023 @opindex fno-sanitize=all
12025 This option disables all previously enabled sanitizers.
12026 @option{-fsanitize=all} is not allowed, as some sanitizers cannot be used
12027 together.
12029 @item -fasan-shadow-offset=@var{number}
12030 @opindex fasan-shadow-offset
12031 This option forces GCC to use custom shadow offset in AddressSanitizer checks.
12032 It is useful for experimenting with different shadow memory layouts in
12033 Kernel AddressSanitizer.
12035 @item -fsanitize-sections=@var{s1},@var{s2},...
12036 @opindex fsanitize-sections
12037 Sanitize global variables in selected user-defined sections.  @var{si} may
12038 contain wildcards.
12040 @item -fsanitize-recover@r{[}=@var{opts}@r{]}
12041 @opindex fsanitize-recover
12042 @opindex fno-sanitize-recover
12043 @option{-fsanitize-recover=} controls error recovery mode for sanitizers
12044 mentioned in comma-separated list of @var{opts}.  Enabling this option
12045 for a sanitizer component causes it to attempt to continue
12046 running the program as if no error happened.  This means multiple
12047 runtime errors can be reported in a single program run, and the exit
12048 code of the program may indicate success even when errors
12049 have been reported.  The @option{-fno-sanitize-recover=} option
12050 can be used to alter
12051 this behavior: only the first detected error is reported
12052 and program then exits with a non-zero exit code.
12054 Currently this feature only works for @option{-fsanitize=undefined} (and its suboptions
12055 except for @option{-fsanitize=unreachable} and @option{-fsanitize=return}),
12056 @option{-fsanitize=float-cast-overflow}, @option{-fsanitize=float-divide-by-zero},
12057 @option{-fsanitize=bounds-strict},
12058 @option{-fsanitize=kernel-address} and @option{-fsanitize=address}.
12059 For these sanitizers error recovery is turned on by default,
12060 except @option{-fsanitize=address}, for which this feature is experimental.
12061 @option{-fsanitize-recover=all} and @option{-fno-sanitize-recover=all} is also
12062 accepted, the former enables recovery for all sanitizers that support it,
12063 the latter disables recovery for all sanitizers that support it.
12065 Even if a recovery mode is turned on the compiler side, it needs to be also
12066 enabled on the runtime library side, otherwise the failures are still fatal.
12067 The runtime library defaults to @code{halt_on_error=0} for
12068 ThreadSanitizer and UndefinedBehaviorSanitizer, while default value for
12069 AddressSanitizer is @code{halt_on_error=1}. This can be overridden through
12070 setting the @code{halt_on_error} flag in the corresponding environment variable.
12072 Syntax without an explicit @var{opts} parameter is deprecated.  It is
12073 equivalent to specifying an @var{opts} list of:
12075 @smallexample
12076 undefined,float-cast-overflow,float-divide-by-zero,bounds-strict
12077 @end smallexample
12079 @item -fsanitize-address-use-after-scope
12080 @opindex fsanitize-address-use-after-scope
12081 Enable sanitization of local variables to detect use-after-scope bugs.
12082 The option sets @option{-fstack-reuse} to @samp{none}.
12084 @item -fsanitize-undefined-trap-on-error
12085 @opindex fsanitize-undefined-trap-on-error
12086 The @option{-fsanitize-undefined-trap-on-error} option instructs the compiler to
12087 report undefined behavior using @code{__builtin_trap} rather than
12088 a @code{libubsan} library routine.  The advantage of this is that the
12089 @code{libubsan} library is not needed and is not linked in, so this
12090 is usable even in freestanding environments.
12092 @item -fsanitize-coverage=trace-pc
12093 @opindex fsanitize-coverage=trace-pc
12094 Enable coverage-guided fuzzing code instrumentation.
12095 Inserts a call to @code{__sanitizer_cov_trace_pc} into every basic block.
12097 @item -fsanitize-coverage=trace-cmp
12098 @opindex fsanitize-coverage=trace-cmp
12099 Enable dataflow guided fuzzing code instrumentation.
12100 Inserts a call to @code{__sanitizer_cov_trace_cmp1},
12101 @code{__sanitizer_cov_trace_cmp2}, @code{__sanitizer_cov_trace_cmp4} or
12102 @code{__sanitizer_cov_trace_cmp8} for integral comparison with both operands
12103 variable or @code{__sanitizer_cov_trace_const_cmp1},
12104 @code{__sanitizer_cov_trace_const_cmp2},
12105 @code{__sanitizer_cov_trace_const_cmp4} or
12106 @code{__sanitizer_cov_trace_const_cmp8} for integral comparison with one
12107 operand constant, @code{__sanitizer_cov_trace_cmpf} or
12108 @code{__sanitizer_cov_trace_cmpd} for float or double comparisons and
12109 @code{__sanitizer_cov_trace_switch} for switch statements.
12111 @item -fcf-protection=@r{[}full@r{|}branch@r{|}return@r{|}none@r{]}
12112 @opindex fcf-protection
12113 Enable code instrumentation of control-flow transfers to increase
12114 program security by checking that target addresses of control-flow
12115 transfer instructions (such as indirect function call, function return,
12116 indirect jump) are valid.  This prevents diverting the flow of control
12117 to an unexpected target.  This is intended to protect against such
12118 threats as Return-oriented Programming (ROP), and similarly
12119 call/jmp-oriented programming (COP/JOP).
12121 The value @code{branch} tells the compiler to implement checking of
12122 validity of control-flow transfer at the point of indirect branch
12123 instructions, i.e. call/jmp instructions.  The value @code{return}
12124 implements checking of validity at the point of returning from a
12125 function.  The value @code{full} is an alias for specifying both
12126 @code{branch} and @code{return}. The value @code{none} turns off
12127 instrumentation.
12129 The macro @code{__CET__} is defined when @option{-fcf-protection} is
12130 used.  The first bit of @code{__CET__} is set to 1 for the value
12131 @code{branch} and the second bit of @code{__CET__} is set to 1 for
12132 the @code{return}.
12134 You can also use the @code{nocf_check} attribute to identify
12135 which functions and calls should be skipped from instrumentation
12136 (@pxref{Function Attributes}).
12138 Currently the x86 GNU/Linux target provides an implementation based
12139 on Intel Control-flow Enforcement Technology (CET).
12141 @item -fstack-protector
12142 @opindex fstack-protector
12143 Emit extra code to check for buffer overflows, such as stack smashing
12144 attacks.  This is done by adding a guard variable to functions with
12145 vulnerable objects.  This includes functions that call @code{alloca}, and
12146 functions with buffers larger than 8 bytes.  The guards are initialized
12147 when a function is entered and then checked when the function exits.
12148 If a guard check fails, an error message is printed and the program exits.
12150 @item -fstack-protector-all
12151 @opindex fstack-protector-all
12152 Like @option{-fstack-protector} except that all functions are protected.
12154 @item -fstack-protector-strong
12155 @opindex fstack-protector-strong
12156 Like @option{-fstack-protector} but includes additional functions to
12157 be protected --- those that have local array definitions, or have
12158 references to local frame addresses.
12160 @item -fstack-protector-explicit
12161 @opindex fstack-protector-explicit
12162 Like @option{-fstack-protector} but only protects those functions which
12163 have the @code{stack_protect} attribute.
12165 @item -fstack-check
12166 @opindex fstack-check
12167 Generate code to verify that you do not go beyond the boundary of the
12168 stack.  You should specify this flag if you are running in an
12169 environment with multiple threads, but you only rarely need to specify it in
12170 a single-threaded environment since stack overflow is automatically
12171 detected on nearly all systems if there is only one stack.
12173 Note that this switch does not actually cause checking to be done; the
12174 operating system or the language runtime must do that.  The switch causes
12175 generation of code to ensure that they see the stack being extended.
12177 You can additionally specify a string parameter: @samp{no} means no
12178 checking, @samp{generic} means force the use of old-style checking,
12179 @samp{specific} means use the best checking method and is equivalent
12180 to bare @option{-fstack-check}.
12182 Old-style checking is a generic mechanism that requires no specific
12183 target support in the compiler but comes with the following drawbacks:
12185 @enumerate
12186 @item
12187 Modified allocation strategy for large objects: they are always
12188 allocated dynamically if their size exceeds a fixed threshold.  Note this
12189 may change the semantics of some code.
12191 @item
12192 Fixed limit on the size of the static frame of functions: when it is
12193 topped by a particular function, stack checking is not reliable and
12194 a warning is issued by the compiler.
12196 @item
12197 Inefficiency: because of both the modified allocation strategy and the
12198 generic implementation, code performance is hampered.
12199 @end enumerate
12201 Note that old-style stack checking is also the fallback method for
12202 @samp{specific} if no target support has been added in the compiler.
12204 @samp{-fstack-check=} is designed for Ada's needs to detect infinite recursion
12205 and stack overflows.  @samp{specific} is an excellent choice when compiling
12206 Ada code.  It is not generally sufficient to protect against stack-clash
12207 attacks.  To protect against those you want @samp{-fstack-clash-protection}.
12209 @item -fstack-clash-protection
12210 @opindex fstack-clash-protection
12211 Generate code to prevent stack clash style attacks.  When this option is
12212 enabled, the compiler will only allocate one page of stack space at a time
12213 and each page is accessed immediately after allocation.  Thus, it prevents
12214 allocations from jumping over any stack guard page provided by the
12215 operating system.
12217 Most targets do not fully support stack clash protection.  However, on
12218 those targets @option{-fstack-clash-protection} will protect dynamic stack
12219 allocations.  @option{-fstack-clash-protection} may also provide limited
12220 protection for static stack allocations if the target supports
12221 @option{-fstack-check=specific}.
12223 @item -fstack-limit-register=@var{reg}
12224 @itemx -fstack-limit-symbol=@var{sym}
12225 @itemx -fno-stack-limit
12226 @opindex fstack-limit-register
12227 @opindex fstack-limit-symbol
12228 @opindex fno-stack-limit
12229 Generate code to ensure that the stack does not grow beyond a certain value,
12230 either the value of a register or the address of a symbol.  If a larger
12231 stack is required, a signal is raised at run time.  For most targets,
12232 the signal is raised before the stack overruns the boundary, so
12233 it is possible to catch the signal without taking special precautions.
12235 For instance, if the stack starts at absolute address @samp{0x80000000}
12236 and grows downwards, you can use the flags
12237 @option{-fstack-limit-symbol=__stack_limit} and
12238 @option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
12239 of 128KB@.  Note that this may only work with the GNU linker.
12241 You can locally override stack limit checking by using the
12242 @code{no_stack_limit} function attribute (@pxref{Function Attributes}).
12244 @item -fsplit-stack
12245 @opindex fsplit-stack
12246 Generate code to automatically split the stack before it overflows.
12247 The resulting program has a discontiguous stack which can only
12248 overflow if the program is unable to allocate any more memory.  This
12249 is most useful when running threaded programs, as it is no longer
12250 necessary to calculate a good stack size to use for each thread.  This
12251 is currently only implemented for the x86 targets running
12252 GNU/Linux.
12254 When code compiled with @option{-fsplit-stack} calls code compiled
12255 without @option{-fsplit-stack}, there may not be much stack space
12256 available for the latter code to run.  If compiling all code,
12257 including library code, with @option{-fsplit-stack} is not an option,
12258 then the linker can fix up these calls so that the code compiled
12259 without @option{-fsplit-stack} always has a large stack.  Support for
12260 this is implemented in the gold linker in GNU binutils release 2.21
12261 and later.
12263 @item -fvtable-verify=@r{[}std@r{|}preinit@r{|}none@r{]}
12264 @opindex fvtable-verify
12265 This option is only available when compiling C++ code.
12266 It turns on (or off, if using @option{-fvtable-verify=none}) the security
12267 feature that verifies at run time, for every virtual call, that
12268 the vtable pointer through which the call is made is valid for the type of
12269 the object, and has not been corrupted or overwritten.  If an invalid vtable
12270 pointer is detected at run time, an error is reported and execution of the
12271 program is immediately halted.
12273 This option causes run-time data structures to be built at program startup,
12274 which are used for verifying the vtable pointers.  
12275 The options @samp{std} and @samp{preinit}
12276 control the timing of when these data structures are built.  In both cases the
12277 data structures are built before execution reaches @code{main}.  Using
12278 @option{-fvtable-verify=std} causes the data structures to be built after
12279 shared libraries have been loaded and initialized.
12280 @option{-fvtable-verify=preinit} causes them to be built before shared
12281 libraries have been loaded and initialized.
12283 If this option appears multiple times in the command line with different
12284 values specified, @samp{none} takes highest priority over both @samp{std} and
12285 @samp{preinit}; @samp{preinit} takes priority over @samp{std}.
12287 @item -fvtv-debug
12288 @opindex fvtv-debug
12289 When used in conjunction with @option{-fvtable-verify=std} or 
12290 @option{-fvtable-verify=preinit}, causes debug versions of the 
12291 runtime functions for the vtable verification feature to be called.  
12292 This flag also causes the compiler to log information about which 
12293 vtable pointers it finds for each class.
12294 This information is written to a file named @file{vtv_set_ptr_data.log} 
12295 in the directory named by the environment variable @env{VTV_LOGS_DIR} 
12296 if that is defined or the current working directory otherwise.
12298 Note:  This feature @emph{appends} data to the log file. If you want a fresh log
12299 file, be sure to delete any existing one.
12301 @item -fvtv-counts
12302 @opindex fvtv-counts
12303 This is a debugging flag.  When used in conjunction with
12304 @option{-fvtable-verify=std} or @option{-fvtable-verify=preinit}, this
12305 causes the compiler to keep track of the total number of virtual calls
12306 it encounters and the number of verifications it inserts.  It also
12307 counts the number of calls to certain run-time library functions
12308 that it inserts and logs this information for each compilation unit.
12309 The compiler writes this information to a file named
12310 @file{vtv_count_data.log} in the directory named by the environment
12311 variable @env{VTV_LOGS_DIR} if that is defined or the current working
12312 directory otherwise.  It also counts the size of the vtable pointer sets
12313 for each class, and writes this information to @file{vtv_class_set_sizes.log}
12314 in the same directory.
12316 Note:  This feature @emph{appends} data to the log files.  To get fresh log
12317 files, be sure to delete any existing ones.
12319 @item -finstrument-functions
12320 @opindex finstrument-functions
12321 Generate instrumentation calls for entry and exit to functions.  Just
12322 after function entry and just before function exit, the following
12323 profiling functions are called with the address of the current
12324 function and its call site.  (On some platforms,
12325 @code{__builtin_return_address} does not work beyond the current
12326 function, so the call site information may not be available to the
12327 profiling functions otherwise.)
12329 @smallexample
12330 void __cyg_profile_func_enter (void *this_fn,
12331                                void *call_site);
12332 void __cyg_profile_func_exit  (void *this_fn,
12333                                void *call_site);
12334 @end smallexample
12336 The first argument is the address of the start of the current function,
12337 which may be looked up exactly in the symbol table.
12339 This instrumentation is also done for functions expanded inline in other
12340 functions.  The profiling calls indicate where, conceptually, the
12341 inline function is entered and exited.  This means that addressable
12342 versions of such functions must be available.  If all your uses of a
12343 function are expanded inline, this may mean an additional expansion of
12344 code size.  If you use @code{extern inline} in your C code, an
12345 addressable version of such functions must be provided.  (This is
12346 normally the case anyway, but if you get lucky and the optimizer always
12347 expands the functions inline, you might have gotten away without
12348 providing static copies.)
12350 A function may be given the attribute @code{no_instrument_function}, in
12351 which case this instrumentation is not done.  This can be used, for
12352 example, for the profiling functions listed above, high-priority
12353 interrupt routines, and any functions from which the profiling functions
12354 cannot safely be called (perhaps signal handlers, if the profiling
12355 routines generate output or allocate memory).
12357 @item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}
12358 @opindex finstrument-functions-exclude-file-list
12360 Set the list of functions that are excluded from instrumentation (see
12361 the description of @option{-finstrument-functions}).  If the file that
12362 contains a function definition matches with one of @var{file}, then
12363 that function is not instrumented.  The match is done on substrings:
12364 if the @var{file} parameter is a substring of the file name, it is
12365 considered to be a match.
12367 For example:
12369 @smallexample
12370 -finstrument-functions-exclude-file-list=/bits/stl,include/sys
12371 @end smallexample
12373 @noindent
12374 excludes any inline function defined in files whose pathnames
12375 contain @file{/bits/stl} or @file{include/sys}.
12377 If, for some reason, you want to include letter @samp{,} in one of
12378 @var{sym}, write @samp{\,}. For example,
12379 @option{-finstrument-functions-exclude-file-list='\,\,tmp'}
12380 (note the single quote surrounding the option).
12382 @item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{}
12383 @opindex finstrument-functions-exclude-function-list
12385 This is similar to @option{-finstrument-functions-exclude-file-list},
12386 but this option sets the list of function names to be excluded from
12387 instrumentation.  The function name to be matched is its user-visible
12388 name, such as @code{vector<int> blah(const vector<int> &)}, not the
12389 internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}).  The
12390 match is done on substrings: if the @var{sym} parameter is a substring
12391 of the function name, it is considered to be a match.  For C99 and C++
12392 extended identifiers, the function name must be given in UTF-8, not
12393 using universal character names.
12395 @item -fpatchable-function-entry=@var{N}[,@var{M}]
12396 @opindex fpatchable-function-entry
12397 Generate @var{N} NOPs right at the beginning
12398 of each function, with the function entry point before the @var{M}th NOP.
12399 If @var{M} is omitted, it defaults to @code{0} so the
12400 function entry points to the address just at the first NOP.
12401 The NOP instructions reserve extra space which can be used to patch in
12402 any desired instrumentation at run time, provided that the code segment
12403 is writable.  The amount of space is controllable indirectly via
12404 the number of NOPs; the NOP instruction used corresponds to the instruction
12405 emitted by the internal GCC back-end interface @code{gen_nop}.  This behavior
12406 is target-specific and may also depend on the architecture variant and/or
12407 other compilation options.
12409 For run-time identification, the starting addresses of these areas,
12410 which correspond to their respective function entries minus @var{M},
12411 are additionally collected in the @code{__patchable_function_entries}
12412 section of the resulting binary.
12414 Note that the value of @code{__attribute__ ((patchable_function_entry
12415 (N,M)))} takes precedence over command-line option
12416 @option{-fpatchable-function-entry=N,M}.  This can be used to increase
12417 the area size or to remove it completely on a single function.
12418 If @code{N=0}, no pad location is recorded.
12420 The NOP instructions are inserted at---and maybe before, depending on
12421 @var{M}---the function entry address, even before the prologue.
12423 @end table
12426 @node Preprocessor Options
12427 @section Options Controlling the Preprocessor
12428 @cindex preprocessor options
12429 @cindex options, preprocessor
12431 These options control the C preprocessor, which is run on each C source
12432 file before actual compilation.
12434 If you use the @option{-E} option, nothing is done except preprocessing.
12435 Some of these options make sense only together with @option{-E} because
12436 they cause the preprocessor output to be unsuitable for actual
12437 compilation.
12439 In addition to the options listed here, there are a number of options 
12440 to control search paths for include files documented in 
12441 @ref{Directory Options}.  
12442 Options to control preprocessor diagnostics are listed in 
12443 @ref{Warning Options}.
12445 @table @gcctabopt
12446 @include cppopts.texi
12448 @item -Wp,@var{option}
12449 @opindex Wp
12450 You can use @option{-Wp,@var{option}} to bypass the compiler driver
12451 and pass @var{option} directly through to the preprocessor.  If
12452 @var{option} contains commas, it is split into multiple options at the
12453 commas.  However, many options are modified, translated or interpreted
12454 by the compiler driver before being passed to the preprocessor, and
12455 @option{-Wp} forcibly bypasses this phase.  The preprocessor's direct
12456 interface is undocumented and subject to change, so whenever possible
12457 you should avoid using @option{-Wp} and let the driver handle the
12458 options instead.
12460 @item -Xpreprocessor @var{option}
12461 @opindex Xpreprocessor
12462 Pass @var{option} as an option to the preprocessor.  You can use this to
12463 supply system-specific preprocessor options that GCC does not 
12464 recognize.
12466 If you want to pass an option that takes an argument, you must use
12467 @option{-Xpreprocessor} twice, once for the option and once for the argument.
12469 @item -no-integrated-cpp
12470 @opindex no-integrated-cpp
12471 Perform preprocessing as a separate pass before compilation.
12472 By default, GCC performs preprocessing as an integrated part of
12473 input tokenization and parsing.
12474 If this option is provided, the appropriate language front end
12475 (@command{cc1}, @command{cc1plus}, or @command{cc1obj} for C, C++,
12476 and Objective-C, respectively) is instead invoked twice,
12477 once for preprocessing only and once for actual compilation
12478 of the preprocessed input.
12479 This option may be useful in conjunction with the @option{-B} or
12480 @option{-wrapper} options to specify an alternate preprocessor or
12481 perform additional processing of the program source between
12482 normal preprocessing and compilation.
12484 @end table
12486 @node Assembler Options
12487 @section Passing Options to the Assembler
12489 @c prevent bad page break with this line
12490 You can pass options to the assembler.
12492 @table @gcctabopt
12493 @item -Wa,@var{option}
12494 @opindex Wa
12495 Pass @var{option} as an option to the assembler.  If @var{option}
12496 contains commas, it is split into multiple options at the commas.
12498 @item -Xassembler @var{option}
12499 @opindex Xassembler
12500 Pass @var{option} as an option to the assembler.  You can use this to
12501 supply system-specific assembler options that GCC does not
12502 recognize.
12504 If you want to pass an option that takes an argument, you must use
12505 @option{-Xassembler} twice, once for the option and once for the argument.
12507 @end table
12509 @node Link Options
12510 @section Options for Linking
12511 @cindex link options
12512 @cindex options, linking
12514 These options come into play when the compiler links object files into
12515 an executable output file.  They are meaningless if the compiler is
12516 not doing a link step.
12518 @table @gcctabopt
12519 @cindex file names
12520 @item @var{object-file-name}
12521 A file name that does not end in a special recognized suffix is
12522 considered to name an object file or library.  (Object files are
12523 distinguished from libraries by the linker according to the file
12524 contents.)  If linking is done, these object files are used as input
12525 to the linker.
12527 @item -c
12528 @itemx -S
12529 @itemx -E
12530 @opindex c
12531 @opindex S
12532 @opindex E
12533 If any of these options is used, then the linker is not run, and
12534 object file names should not be used as arguments.  @xref{Overall
12535 Options}.
12537 @item -flinker-output=@var{type}
12538 @opindex -flinker-output
12539 This option controls the code generation of the link time optimizer.  By
12540 default the linker output is determined by the linker plugin automatically. For
12541 debugging the compiler and in the case of incremental linking to non-lto object
12542 file is desired, it may be useful to control the type manually.
12544 If @var{type} is @samp{exec} the code generation is configured to produce static
12545 binary. In this case @option{-fpic} and @option{-fpie} are both disabled.
12547 If @var{type} is @samp{dyn} the code generation is configured to produce shared
12548 library. In this case @option{-fpic} or @option{-fPIC} is preserved, but not
12549 enabled automatically.  This makes it possible to build shared libraries without
12550 position independent code on architectures this is possible, i.e. on x86.
12552 If @var{type} is @samp{pie} the code generation is configured to produce
12553 @option{-fpie} executable. This result in similar optimizations as @samp{exec}
12554 except that @option{-fpie} is not disabled if specified at compilation time.
12556 If @var{type} is @samp{rel} the compiler assumes that incremental linking is
12557 done.  The sections containing intermediate code for link-time optimization are
12558 merged, pre-optimized, and output to the resulting object file. In addition, if
12559 @option{-ffat-lto-objects} is specified the binary code is produced for future
12560 non-lto linking. The object file produced by incremental linking will be smaller
12561 than a static library produced from the same object files.  At link-time the
12562 result of incremental linking will also load faster to compiler than a static
12563 library assuming that majority of objects in the library are used.
12565 Finally @samp{nolto-rel} configure compiler to for incremental linking where
12566 code generation is forced, final binary is produced and the intermediate code
12567 for later link-time optimization is stripped. When multiple object files are
12568 linked together the resulting code will be optimized better than with link time
12569 optimizations disabled (for example, the cross-module inlining will happen),
12570 most of benefits of whole program optimizations are however lost. 
12572 During the incremental link (by @option{-r}) the linker plugin will default to
12573 @option{rel}. With current interfaces to GNU Binutils it is however not
12574 possible to link incrementally LTO objects and non-LTO objects into a single
12575 mixed object file.  In the case any of object files in incremental link can not
12576 be used for link-time optimization the linker plugin will output warning and
12577 use @samp{nolto-rel}. To maintain the whole program optimization it is
12578 recommended to link such objects into static library instead. Alternatively it
12579 is possible to use H.J. Lu's binutils with support for mixed objects.
12581 @item -fuse-ld=bfd
12582 @opindex fuse-ld=bfd
12583 Use the @command{bfd} linker instead of the default linker.
12585 @item -fuse-ld=gold
12586 @opindex fuse-ld=gold
12587 Use the @command{gold} linker instead of the default linker.
12589 @cindex Libraries
12590 @item -l@var{library}
12591 @itemx -l @var{library}
12592 @opindex l
12593 Search the library named @var{library} when linking.  (The second
12594 alternative with the library as a separate argument is only for
12595 POSIX compliance and is not recommended.)
12597 It makes a difference where in the command you write this option; the
12598 linker searches and processes libraries and object files in the order they
12599 are specified.  Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
12600 after file @file{foo.o} but before @file{bar.o}.  If @file{bar.o} refers
12601 to functions in @samp{z}, those functions may not be loaded.
12603 The linker searches a standard list of directories for the library,
12604 which is actually a file named @file{lib@var{library}.a}.  The linker
12605 then uses this file as if it had been specified precisely by name.
12607 The directories searched include several standard system directories
12608 plus any that you specify with @option{-L}.
12610 Normally the files found this way are library files---archive files
12611 whose members are object files.  The linker handles an archive file by
12612 scanning through it for members which define symbols that have so far
12613 been referenced but not defined.  But if the file that is found is an
12614 ordinary object file, it is linked in the usual fashion.  The only
12615 difference between using an @option{-l} option and specifying a file name
12616 is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
12617 and searches several directories.
12619 @item -lobjc
12620 @opindex lobjc
12621 You need this special case of the @option{-l} option in order to
12622 link an Objective-C or Objective-C++ program.
12624 @item -nostartfiles
12625 @opindex nostartfiles
12626 Do not use the standard system startup files when linking.
12627 The standard system libraries are used normally, unless @option{-nostdlib},
12628 @option{-nolibc}, or @option{-nodefaultlibs} is used.
12630 @item -nodefaultlibs
12631 @opindex nodefaultlibs
12632 Do not use the standard system libraries when linking.
12633 Only the libraries you specify are passed to the linker, and options
12634 specifying linkage of the system libraries, such as @option{-static-libgcc}
12635 or @option{-shared-libgcc}, are ignored.  
12636 The standard startup files are used normally, unless @option{-nostartfiles}
12637 is used.  
12639 The compiler may generate calls to @code{memcmp},
12640 @code{memset}, @code{memcpy} and @code{memmove}.
12641 These entries are usually resolved by entries in
12642 libc.  These entry points should be supplied through some other
12643 mechanism when this option is specified.
12645 @item -nolibc
12646 @opindex nolibc
12647 Do not use the C library or system libraries tightly coupled with it when
12648 linking.  Still link with the startup files, @file{libgcc} or toolchain
12649 provided language support libraries such as @file{libgnat}, @file{libgfortran}
12650 or @file{libstdc++} unless options preventing their inclusion are used as
12651 well.  This typically removes @option{-lc} from the link command line, as well
12652 as system libraries that normally go with it and become meaningless when
12653 absence of a C library is assumed, for example @option{-lpthread} or
12654 @option{-lm} in some configurations.  This is intended for bare-board
12655 targets when there is indeed no C library available.
12657 @item -nostdlib
12658 @opindex nostdlib
12659 Do not use the standard system startup files or libraries when linking.
12660 No startup files and only the libraries you specify are passed to
12661 the linker, and options specifying linkage of the system libraries, such as
12662 @option{-static-libgcc} or @option{-shared-libgcc}, are ignored.
12664 The compiler may generate calls to @code{memcmp}, @code{memset},
12665 @code{memcpy} and @code{memmove}.
12666 These entries are usually resolved by entries in
12667 libc.  These entry points should be supplied through some other
12668 mechanism when this option is specified.
12670 @cindex @option{-lgcc}, use with @option{-nostdlib}
12671 @cindex @option{-nostdlib} and unresolved references
12672 @cindex unresolved references and @option{-nostdlib}
12673 @cindex @option{-lgcc}, use with @option{-nodefaultlibs}
12674 @cindex @option{-nodefaultlibs} and unresolved references
12675 @cindex unresolved references and @option{-nodefaultlibs}
12676 One of the standard libraries bypassed by @option{-nostdlib} and
12677 @option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
12678 which GCC uses to overcome shortcomings of particular machines, or special
12679 needs for some languages.
12680 (@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
12681 Collection (GCC) Internals},
12682 for more discussion of @file{libgcc.a}.)
12683 In most cases, you need @file{libgcc.a} even when you want to avoid
12684 other standard libraries.  In other words, when you specify @option{-nostdlib}
12685 or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
12686 This ensures that you have no unresolved references to internal GCC
12687 library subroutines.
12688 (An example of such an internal subroutine is @code{__main}, used to ensure C++
12689 constructors are called; @pxref{Collect2,,@code{collect2}, gccint,
12690 GNU Compiler Collection (GCC) Internals}.)
12692 @item -pie
12693 @opindex pie
12694 Produce a dynamically linked position independent executable on targets
12695 that support it.  For predictable results, you must also specify the same
12696 set of options used for compilation (@option{-fpie}, @option{-fPIE},
12697 or model suboptions) when you specify this linker option.
12699 @item -no-pie
12700 @opindex no-pie
12701 Don't produce a dynamically linked position independent executable.
12703 @item -static-pie
12704 @opindex static-pie
12705 Produce a static position independent executable on targets that support
12706 it.  A static position independent executable is similar to a static
12707 executable, but can be loaded at any address without a dynamic linker.
12708 For predictable results, you must also specify the same set of options
12709 used for compilation (@option{-fpie}, @option{-fPIE}, or model
12710 suboptions) when you specify this linker option.
12712 @item -pthread
12713 @opindex pthread
12714 Link with the POSIX threads library.  This option is supported on 
12715 GNU/Linux targets, most other Unix derivatives, and also on 
12716 x86 Cygwin and MinGW targets.  On some targets this option also sets 
12717 flags for the preprocessor, so it should be used consistently for both
12718 compilation and linking.
12720 @item -r
12721 @opindex r
12722 Produce a relocatable object as output.  This is also known as partial
12723 linking.
12725 @item -rdynamic
12726 @opindex rdynamic
12727 Pass the flag @option{-export-dynamic} to the ELF linker, on targets
12728 that support it. This instructs the linker to add all symbols, not
12729 only used ones, to the dynamic symbol table. This option is needed
12730 for some uses of @code{dlopen} or to allow obtaining backtraces
12731 from within a program.
12733 @item -s
12734 @opindex s
12735 Remove all symbol table and relocation information from the executable.
12737 @item -static
12738 @opindex static
12739 On systems that support dynamic linking, this overrides @option{-pie}
12740 and prevents linking with the shared libraries.  On other systems, this
12741 option has no effect.
12743 @item -shared
12744 @opindex shared
12745 Produce a shared object which can then be linked with other objects to
12746 form an executable.  Not all systems support this option.  For predictable
12747 results, you must also specify the same set of options used for compilation
12748 (@option{-fpic}, @option{-fPIC}, or model suboptions) when
12749 you specify this linker option.@footnote{On some systems, @samp{gcc -shared}
12750 needs to build supplementary stub code for constructors to work.  On
12751 multi-libbed systems, @samp{gcc -shared} must select the correct support
12752 libraries to link against.  Failing to supply the correct flags may lead
12753 to subtle defects.  Supplying them in cases where they are not necessary
12754 is innocuous.}
12756 @item -shared-libgcc
12757 @itemx -static-libgcc
12758 @opindex shared-libgcc
12759 @opindex static-libgcc
12760 On systems that provide @file{libgcc} as a shared library, these options
12761 force the use of either the shared or static version, respectively.
12762 If no shared version of @file{libgcc} was built when the compiler was
12763 configured, these options have no effect.
12765 There are several situations in which an application should use the
12766 shared @file{libgcc} instead of the static version.  The most common
12767 of these is when the application wishes to throw and catch exceptions
12768 across different shared libraries.  In that case, each of the libraries
12769 as well as the application itself should use the shared @file{libgcc}.
12771 Therefore, the G++ driver automatically adds @option{-shared-libgcc}
12772 whenever you build a shared library or a main executable, because C++
12773 programs typically use exceptions, so this is the right thing to do.
12775 If, instead, you use the GCC driver to create shared libraries, you may
12776 find that they are not always linked with the shared @file{libgcc}.
12777 If GCC finds, at its configuration time, that you have a non-GNU linker
12778 or a GNU linker that does not support option @option{--eh-frame-hdr},
12779 it links the shared version of @file{libgcc} into shared libraries
12780 by default.  Otherwise, it takes advantage of the linker and optimizes
12781 away the linking with the shared version of @file{libgcc}, linking with
12782 the static version of libgcc by default.  This allows exceptions to
12783 propagate through such shared libraries, without incurring relocation
12784 costs at library load time.
12786 However, if a library or main executable is supposed to throw or catch
12787 exceptions, you must link it using the G++ driver, or using the option
12788 @option{-shared-libgcc}, such that it is linked with the shared
12789 @file{libgcc}.
12791 @item -static-libasan
12792 @opindex static-libasan
12793 When the @option{-fsanitize=address} option is used to link a program,
12794 the GCC driver automatically links against @option{libasan}.  If
12795 @file{libasan} is available as a shared library, and the @option{-static}
12796 option is not used, then this links against the shared version of
12797 @file{libasan}.  The @option{-static-libasan} option directs the GCC
12798 driver to link @file{libasan} statically, without necessarily linking
12799 other libraries statically.
12801 @item -static-libtsan
12802 @opindex static-libtsan
12803 When the @option{-fsanitize=thread} option is used to link a program,
12804 the GCC driver automatically links against @option{libtsan}.  If
12805 @file{libtsan} is available as a shared library, and the @option{-static}
12806 option is not used, then this links against the shared version of
12807 @file{libtsan}.  The @option{-static-libtsan} option directs the GCC
12808 driver to link @file{libtsan} statically, without necessarily linking
12809 other libraries statically.
12811 @item -static-liblsan
12812 @opindex static-liblsan
12813 When the @option{-fsanitize=leak} option is used to link a program,
12814 the GCC driver automatically links against @option{liblsan}.  If
12815 @file{liblsan} is available as a shared library, and the @option{-static}
12816 option is not used, then this links against the shared version of
12817 @file{liblsan}.  The @option{-static-liblsan} option directs the GCC
12818 driver to link @file{liblsan} statically, without necessarily linking
12819 other libraries statically.
12821 @item -static-libubsan
12822 @opindex static-libubsan
12823 When the @option{-fsanitize=undefined} option is used to link a program,
12824 the GCC driver automatically links against @option{libubsan}.  If
12825 @file{libubsan} is available as a shared library, and the @option{-static}
12826 option is not used, then this links against the shared version of
12827 @file{libubsan}.  The @option{-static-libubsan} option directs the GCC
12828 driver to link @file{libubsan} statically, without necessarily linking
12829 other libraries statically.
12831 @item -static-libstdc++
12832 @opindex static-libstdc++
12833 When the @command{g++} program is used to link a C++ program, it
12834 normally automatically links against @option{libstdc++}.  If
12835 @file{libstdc++} is available as a shared library, and the
12836 @option{-static} option is not used, then this links against the
12837 shared version of @file{libstdc++}.  That is normally fine.  However, it
12838 is sometimes useful to freeze the version of @file{libstdc++} used by
12839 the program without going all the way to a fully static link.  The
12840 @option{-static-libstdc++} option directs the @command{g++} driver to
12841 link @file{libstdc++} statically, without necessarily linking other
12842 libraries statically.
12844 @item -symbolic
12845 @opindex symbolic
12846 Bind references to global symbols when building a shared object.  Warn
12847 about any unresolved references (unless overridden by the link editor
12848 option @option{-Xlinker -z -Xlinker defs}).  Only a few systems support
12849 this option.
12851 @item -T @var{script}
12852 @opindex T
12853 @cindex linker script
12854 Use @var{script} as the linker script.  This option is supported by most
12855 systems using the GNU linker.  On some targets, such as bare-board
12856 targets without an operating system, the @option{-T} option may be required
12857 when linking to avoid references to undefined symbols.
12859 @item -Xlinker @var{option}
12860 @opindex Xlinker
12861 Pass @var{option} as an option to the linker.  You can use this to
12862 supply system-specific linker options that GCC does not recognize.
12864 If you want to pass an option that takes a separate argument, you must use
12865 @option{-Xlinker} twice, once for the option and once for the argument.
12866 For example, to pass @option{-assert definitions}, you must write
12867 @option{-Xlinker -assert -Xlinker definitions}.  It does not work to write
12868 @option{-Xlinker "-assert definitions"}, because this passes the entire
12869 string as a single argument, which is not what the linker expects.
12871 When using the GNU linker, it is usually more convenient to pass
12872 arguments to linker options using the @option{@var{option}=@var{value}}
12873 syntax than as separate arguments.  For example, you can specify
12874 @option{-Xlinker -Map=output.map} rather than
12875 @option{-Xlinker -Map -Xlinker output.map}.  Other linkers may not support
12876 this syntax for command-line options.
12878 @item -Wl,@var{option}
12879 @opindex Wl
12880 Pass @var{option} as an option to the linker.  If @var{option} contains
12881 commas, it is split into multiple options at the commas.  You can use this
12882 syntax to pass an argument to the option.
12883 For example, @option{-Wl,-Map,output.map} passes @option{-Map output.map} to the
12884 linker.  When using the GNU linker, you can also get the same effect with
12885 @option{-Wl,-Map=output.map}.
12887 @item -u @var{symbol}
12888 @opindex u
12889 Pretend the symbol @var{symbol} is undefined, to force linking of
12890 library modules to define it.  You can use @option{-u} multiple times with
12891 different symbols to force loading of additional library modules.
12893 @item -z @var{keyword}
12894 @opindex z
12895 @option{-z} is passed directly on to the linker along with the keyword
12896 @var{keyword}. See the section in the documentation of your linker for
12897 permitted values and their meanings.
12898 @end table
12900 @node Directory Options
12901 @section Options for Directory Search
12902 @cindex directory options
12903 @cindex options, directory search
12904 @cindex search path
12906 These options specify directories to search for header files, for
12907 libraries and for parts of the compiler:
12909 @table @gcctabopt
12910 @include cppdiropts.texi
12912 @item -iplugindir=@var{dir}
12913 @opindex iplugindir=
12914 Set the directory to search for plugins that are passed
12915 by @option{-fplugin=@var{name}} instead of
12916 @option{-fplugin=@var{path}/@var{name}.so}.  This option is not meant
12917 to be used by the user, but only passed by the driver.
12919 @item -L@var{dir}
12920 @opindex L
12921 Add directory @var{dir} to the list of directories to be searched
12922 for @option{-l}.
12924 @item -B@var{prefix}
12925 @opindex B
12926 This option specifies where to find the executables, libraries,
12927 include files, and data files of the compiler itself.
12929 The compiler driver program runs one or more of the subprograms
12930 @command{cpp}, @command{cc1}, @command{as} and @command{ld}.  It tries
12931 @var{prefix} as a prefix for each program it tries to run, both with and
12932 without @samp{@var{machine}/@var{version}/} for the corresponding target
12933 machine and compiler version.
12935 For each subprogram to be run, the compiler driver first tries the
12936 @option{-B} prefix, if any.  If that name is not found, or if @option{-B}
12937 is not specified, the driver tries two standard prefixes, 
12938 @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}.  If neither of
12939 those results in a file name that is found, the unmodified program
12940 name is searched for using the directories specified in your
12941 @env{PATH} environment variable.
12943 The compiler checks to see if the path provided by @option{-B}
12944 refers to a directory, and if necessary it adds a directory
12945 separator character at the end of the path.
12947 @option{-B} prefixes that effectively specify directory names also apply
12948 to libraries in the linker, because the compiler translates these
12949 options into @option{-L} options for the linker.  They also apply to
12950 include files in the preprocessor, because the compiler translates these
12951 options into @option{-isystem} options for the preprocessor.  In this case,
12952 the compiler appends @samp{include} to the prefix.
12954 The runtime support file @file{libgcc.a} can also be searched for using
12955 the @option{-B} prefix, if needed.  If it is not found there, the two
12956 standard prefixes above are tried, and that is all.  The file is left
12957 out of the link if it is not found by those means.
12959 Another way to specify a prefix much like the @option{-B} prefix is to use
12960 the environment variable @env{GCC_EXEC_PREFIX}.  @xref{Environment
12961 Variables}.
12963 As a special kludge, if the path provided by @option{-B} is
12964 @file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
12965 9, then it is replaced by @file{[dir/]include}.  This is to help
12966 with boot-strapping the compiler.
12968 @item -no-canonical-prefixes
12969 @opindex no-canonical-prefixes
12970 Do not expand any symbolic links, resolve references to @samp{/../}
12971 or @samp{/./}, or make the path absolute when generating a relative
12972 prefix.
12974 @item --sysroot=@var{dir}
12975 @opindex sysroot
12976 Use @var{dir} as the logical root directory for headers and libraries.
12977 For example, if the compiler normally searches for headers in
12978 @file{/usr/include} and libraries in @file{/usr/lib}, it instead
12979 searches @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
12981 If you use both this option and the @option{-isysroot} option, then
12982 the @option{--sysroot} option applies to libraries, but the
12983 @option{-isysroot} option applies to header files.
12985 The GNU linker (beginning with version 2.16) has the necessary support
12986 for this option.  If your linker does not support this option, the
12987 header file aspect of @option{--sysroot} still works, but the
12988 library aspect does not.
12990 @item --no-sysroot-suffix
12991 @opindex no-sysroot-suffix
12992 For some targets, a suffix is added to the root directory specified
12993 with @option{--sysroot}, depending on the other options used, so that
12994 headers may for example be found in
12995 @file{@var{dir}/@var{suffix}/usr/include} instead of
12996 @file{@var{dir}/usr/include}.  This option disables the addition of
12997 such a suffix.
12999 @end table
13001 @node Code Gen Options
13002 @section Options for Code Generation Conventions
13003 @cindex code generation conventions
13004 @cindex options, code generation
13005 @cindex run-time options
13007 These machine-independent options control the interface conventions
13008 used in code generation.
13010 Most of them have both positive and negative forms; the negative form
13011 of @option{-ffoo} is @option{-fno-foo}.  In the table below, only
13012 one of the forms is listed---the one that is not the default.  You
13013 can figure out the other form by either removing @samp{no-} or adding
13016 @table @gcctabopt
13017 @item -fstack-reuse=@var{reuse-level}
13018 @opindex fstack_reuse
13019 This option controls stack space reuse for user declared local/auto variables
13020 and compiler generated temporaries.  @var{reuse_level} can be @samp{all},
13021 @samp{named_vars}, or @samp{none}. @samp{all} enables stack reuse for all
13022 local variables and temporaries, @samp{named_vars} enables the reuse only for
13023 user defined local variables with names, and @samp{none} disables stack reuse
13024 completely. The default value is @samp{all}. The option is needed when the
13025 program extends the lifetime of a scoped local variable or a compiler generated
13026 temporary beyond the end point defined by the language.  When a lifetime of
13027 a variable ends, and if the variable lives in memory, the optimizing compiler
13028 has the freedom to reuse its stack space with other temporaries or scoped
13029 local variables whose live range does not overlap with it. Legacy code extending
13030 local lifetime is likely to break with the stack reuse optimization.
13032 For example,
13034 @smallexample
13035    int *p;
13036    @{
13037      int local1;
13039      p = &local1;
13040      local1 = 10;
13041      ....
13042    @}
13043    @{
13044       int local2;
13045       local2 = 20;
13046       ...
13047    @}
13049    if (*p == 10)  // out of scope use of local1
13050      @{
13052      @}
13053 @end smallexample
13055 Another example:
13056 @smallexample
13058    struct A
13059    @{
13060        A(int k) : i(k), j(k) @{ @}
13061        int i;
13062        int j;
13063    @};
13065    A *ap;
13067    void foo(const A& ar)
13068    @{
13069       ap = &ar;
13070    @}
13072    void bar()
13073    @{
13074       foo(A(10)); // temp object's lifetime ends when foo returns
13076       @{
13077         A a(20);
13078         ....
13079       @}
13080       ap->i+= 10;  // ap references out of scope temp whose space
13081                    // is reused with a. What is the value of ap->i?
13082    @}
13084 @end smallexample
13086 The lifetime of a compiler generated temporary is well defined by the C++
13087 standard. When a lifetime of a temporary ends, and if the temporary lives
13088 in memory, the optimizing compiler has the freedom to reuse its stack
13089 space with other temporaries or scoped local variables whose live range
13090 does not overlap with it. However some of the legacy code relies on
13091 the behavior of older compilers in which temporaries' stack space is
13092 not reused, the aggressive stack reuse can lead to runtime errors. This
13093 option is used to control the temporary stack reuse optimization.
13095 @item -ftrapv
13096 @opindex ftrapv
13097 This option generates traps for signed overflow on addition, subtraction,
13098 multiplication operations.
13099 The options @option{-ftrapv} and @option{-fwrapv} override each other, so using
13100 @option{-ftrapv} @option{-fwrapv} on the command-line results in
13101 @option{-fwrapv} being effective.  Note that only active options override, so
13102 using @option{-ftrapv} @option{-fwrapv} @option{-fno-wrapv} on the command-line
13103 results in @option{-ftrapv} being effective.
13105 @item -fwrapv
13106 @opindex fwrapv
13107 This option instructs the compiler to assume that signed arithmetic
13108 overflow of addition, subtraction and multiplication wraps around
13109 using twos-complement representation.  This flag enables some optimizations
13110 and disables others.
13111 The options @option{-ftrapv} and @option{-fwrapv} override each other, so using
13112 @option{-ftrapv} @option{-fwrapv} on the command-line results in
13113 @option{-fwrapv} being effective.  Note that only active options override, so
13114 using @option{-ftrapv} @option{-fwrapv} @option{-fno-wrapv} on the command-line
13115 results in @option{-ftrapv} being effective.
13117 @item -fwrapv-pointer
13118 @opindex fwrapv-pointer
13119 This option instructs the compiler to assume that pointer arithmetic
13120 overflow on addition and subtraction wraps around using twos-complement
13121 representation.  This flag disables some optimizations which assume
13122 pointer overflow is invalid.
13124 @item -fstrict-overflow
13125 @opindex fstrict-overflow
13126 This option implies @option{-fno-wrapv} @option{-fno-wrapv-pointer} and when
13127 negated implies @option{-fwrapv} @option{-fwrapv-pointer}.
13129 @item -fexceptions
13130 @opindex fexceptions
13131 Enable exception handling.  Generates extra code needed to propagate
13132 exceptions.  For some targets, this implies GCC generates frame
13133 unwind information for all functions, which can produce significant data
13134 size overhead, although it does not affect execution.  If you do not
13135 specify this option, GCC enables it by default for languages like
13136 C++ that normally require exception handling, and disables it for
13137 languages like C that do not normally require it.  However, you may need
13138 to enable this option when compiling C code that needs to interoperate
13139 properly with exception handlers written in C++.  You may also wish to
13140 disable this option if you are compiling older C++ programs that don't
13141 use exception handling.
13143 @item -fnon-call-exceptions
13144 @opindex fnon-call-exceptions
13145 Generate code that allows trapping instructions to throw exceptions.
13146 Note that this requires platform-specific runtime support that does
13147 not exist everywhere.  Moreover, it only allows @emph{trapping}
13148 instructions to throw exceptions, i.e.@: memory references or floating-point
13149 instructions.  It does not allow exceptions to be thrown from
13150 arbitrary signal handlers such as @code{SIGALRM}.
13152 @item -fdelete-dead-exceptions
13153 @opindex fdelete-dead-exceptions
13154 Consider that instructions that may throw exceptions but don't otherwise
13155 contribute to the execution of the program can be optimized away.
13156 This option is enabled by default for the Ada front end, as permitted by
13157 the Ada language specification.
13158 Optimization passes that cause dead exceptions to be removed are enabled independently at different optimization levels.
13160 @item -funwind-tables
13161 @opindex funwind-tables
13162 Similar to @option{-fexceptions}, except that it just generates any needed
13163 static data, but does not affect the generated code in any other way.
13164 You normally do not need to enable this option; instead, a language processor
13165 that needs this handling enables it on your behalf.
13167 @item -fasynchronous-unwind-tables
13168 @opindex fasynchronous-unwind-tables
13169 Generate unwind table in DWARF format, if supported by target machine.  The
13170 table is exact at each instruction boundary, so it can be used for stack
13171 unwinding from asynchronous events (such as debugger or garbage collector).
13173 @item -fno-gnu-unique
13174 @opindex fno-gnu-unique
13175 On systems with recent GNU assembler and C library, the C++ compiler
13176 uses the @code{STB_GNU_UNIQUE} binding to make sure that definitions
13177 of template static data members and static local variables in inline
13178 functions are unique even in the presence of @code{RTLD_LOCAL}; this
13179 is necessary to avoid problems with a library used by two different
13180 @code{RTLD_LOCAL} plugins depending on a definition in one of them and
13181 therefore disagreeing with the other one about the binding of the
13182 symbol.  But this causes @code{dlclose} to be ignored for affected
13183 DSOs; if your program relies on reinitialization of a DSO via
13184 @code{dlclose} and @code{dlopen}, you can use
13185 @option{-fno-gnu-unique}.
13187 @item -fpcc-struct-return
13188 @opindex fpcc-struct-return
13189 Return ``short'' @code{struct} and @code{union} values in memory like
13190 longer ones, rather than in registers.  This convention is less
13191 efficient, but it has the advantage of allowing intercallability between
13192 GCC-compiled files and files compiled with other compilers, particularly
13193 the Portable C Compiler (pcc).
13195 The precise convention for returning structures in memory depends
13196 on the target configuration macros.
13198 Short structures and unions are those whose size and alignment match
13199 that of some integer type.
13201 @strong{Warning:} code compiled with the @option{-fpcc-struct-return}
13202 switch is not binary compatible with code compiled with the
13203 @option{-freg-struct-return} switch.
13204 Use it to conform to a non-default application binary interface.
13206 @item -freg-struct-return
13207 @opindex freg-struct-return
13208 Return @code{struct} and @code{union} values in registers when possible.
13209 This is more efficient for small structures than
13210 @option{-fpcc-struct-return}.
13212 If you specify neither @option{-fpcc-struct-return} nor
13213 @option{-freg-struct-return}, GCC defaults to whichever convention is
13214 standard for the target.  If there is no standard convention, GCC
13215 defaults to @option{-fpcc-struct-return}, except on targets where GCC is
13216 the principal compiler.  In those cases, we can choose the standard, and
13217 we chose the more efficient register return alternative.
13219 @strong{Warning:} code compiled with the @option{-freg-struct-return}
13220 switch is not binary compatible with code compiled with the
13221 @option{-fpcc-struct-return} switch.
13222 Use it to conform to a non-default application binary interface.
13224 @item -fshort-enums
13225 @opindex fshort-enums
13226 Allocate to an @code{enum} type only as many bytes as it needs for the
13227 declared range of possible values.  Specifically, the @code{enum} type
13228 is equivalent to the smallest integer type that has enough room.
13230 @strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
13231 code that is not binary compatible with code generated without that switch.
13232 Use it to conform to a non-default application binary interface.
13234 @item -fshort-wchar
13235 @opindex fshort-wchar
13236 Override the underlying type for @code{wchar_t} to be @code{short
13237 unsigned int} instead of the default for the target.  This option is
13238 useful for building programs to run under WINE@.
13240 @strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
13241 code that is not binary compatible with code generated without that switch.
13242 Use it to conform to a non-default application binary interface.
13244 @item -fno-common
13245 @opindex fno-common
13246 @cindex tentative definitions
13247 In C code, this option controls the placement of global variables 
13248 defined without an initializer, known as @dfn{tentative definitions} 
13249 in the C standard.  Tentative definitions are distinct from declarations 
13250 of a variable with the @code{extern} keyword, which do not allocate storage.
13252 Unix C compilers have traditionally allocated storage for
13253 uninitialized global variables in a common block.  This allows the
13254 linker to resolve all tentative definitions of the same variable
13255 in different compilation units to the same object, or to a non-tentative
13256 definition.  
13257 This is the behavior specified by @option{-fcommon}, and is the default for 
13258 GCC on most targets.  
13259 On the other hand, this behavior is not required by ISO
13260 C, and on some targets may carry a speed or code size penalty on
13261 variable references.
13263 The @option{-fno-common} option specifies that the compiler should instead
13264 place uninitialized global variables in the data section of the object file.
13265 This inhibits the merging of tentative definitions by the linker so
13266 you get a multiple-definition error if the same 
13267 variable is defined in more than one compilation unit.
13268 Compiling with @option{-fno-common} is useful on targets for which
13269 it provides better performance, or if you wish to verify that the
13270 program will work on other systems that always treat uninitialized
13271 variable definitions this way.
13273 @item -fno-ident
13274 @opindex fno-ident
13275 Ignore the @code{#ident} directive.
13277 @item -finhibit-size-directive
13278 @opindex finhibit-size-directive
13279 Don't output a @code{.size} assembler directive, or anything else that
13280 would cause trouble if the function is split in the middle, and the
13281 two halves are placed at locations far apart in memory.  This option is
13282 used when compiling @file{crtstuff.c}; you should not need to use it
13283 for anything else.
13285 @item -fverbose-asm
13286 @opindex fverbose-asm
13287 Put extra commentary information in the generated assembly code to
13288 make it more readable.  This option is generally only of use to those
13289 who actually need to read the generated assembly code (perhaps while
13290 debugging the compiler itself).
13292 @option{-fno-verbose-asm}, the default, causes the
13293 extra information to be omitted and is useful when comparing two assembler
13294 files.
13296 The added comments include:
13298 @itemize @bullet
13300 @item
13301 information on the compiler version and command-line options,
13303 @item
13304 the source code lines associated with the assembly instructions,
13305 in the form FILENAME:LINENUMBER:CONTENT OF LINE,
13307 @item
13308 hints on which high-level expressions correspond to
13309 the various assembly instruction operands.
13311 @end itemize
13313 For example, given this C source file:
13315 @smallexample
13316 int test (int n)
13318   int i;
13319   int total = 0;
13321   for (i = 0; i < n; i++)
13322     total += i * i;
13324   return total;
13326 @end smallexample
13328 compiling to (x86_64) assembly via @option{-S} and emitting the result
13329 direct to stdout via @option{-o} @option{-}
13331 @smallexample
13332 gcc -S test.c -fverbose-asm -Os -o -
13333 @end smallexample
13335 gives output similar to this:
13337 @smallexample
13338         .file   "test.c"
13339 # GNU C11 (GCC) version 7.0.0 20160809 (experimental) (x86_64-pc-linux-gnu)
13340   [...snip...]
13341 # options passed:
13342   [...snip...]
13344         .text
13345         .globl  test
13346         .type   test, @@function
13347 test:
13348 .LFB0:
13349         .cfi_startproc
13350 # test.c:4:   int total = 0;
13351         xorl    %eax, %eax      # <retval>
13352 # test.c:6:   for (i = 0; i < n; i++)
13353         xorl    %edx, %edx      # i
13354 .L2:
13355 # test.c:6:   for (i = 0; i < n; i++)
13356         cmpl    %edi, %edx      # n, i
13357         jge     .L5     #,
13358 # test.c:7:     total += i * i;
13359         movl    %edx, %ecx      # i, tmp92
13360         imull   %edx, %ecx      # i, tmp92
13361 # test.c:6:   for (i = 0; i < n; i++)
13362         incl    %edx    # i
13363 # test.c:7:     total += i * i;
13364         addl    %ecx, %eax      # tmp92, <retval>
13365         jmp     .L2     #
13366 .L5:
13367 # test.c:10: @}
13368         ret
13369         .cfi_endproc
13370 .LFE0:
13371         .size   test, .-test
13372         .ident  "GCC: (GNU) 7.0.0 20160809 (experimental)"
13373         .section        .note.GNU-stack,"",@@progbits
13374 @end smallexample
13376 The comments are intended for humans rather than machines and hence the
13377 precise format of the comments is subject to change.
13379 @item -frecord-gcc-switches
13380 @opindex frecord-gcc-switches
13381 This switch causes the command line used to invoke the
13382 compiler to be recorded into the object file that is being created.
13383 This switch is only implemented on some targets and the exact format
13384 of the recording is target and binary file format dependent, but it
13385 usually takes the form of a section containing ASCII text.  This
13386 switch is related to the @option{-fverbose-asm} switch, but that
13387 switch only records information in the assembler output file as
13388 comments, so it never reaches the object file.
13389 See also @option{-grecord-gcc-switches} for another
13390 way of storing compiler options into the object file.
13392 @item -fpic
13393 @opindex fpic
13394 @cindex global offset table
13395 @cindex PIC
13396 Generate position-independent code (PIC) suitable for use in a shared
13397 library, if supported for the target machine.  Such code accesses all
13398 constant addresses through a global offset table (GOT)@.  The dynamic
13399 loader resolves the GOT entries when the program starts (the dynamic
13400 loader is not part of GCC; it is part of the operating system).  If
13401 the GOT size for the linked executable exceeds a machine-specific
13402 maximum size, you get an error message from the linker indicating that
13403 @option{-fpic} does not work; in that case, recompile with @option{-fPIC}
13404 instead.  (These maximums are 8k on the SPARC, 28k on AArch64 and 32k
13405 on the m68k and RS/6000.  The x86 has no such limit.)
13407 Position-independent code requires special support, and therefore works
13408 only on certain machines.  For the x86, GCC supports PIC for System V
13409 but not for the Sun 386i.  Code generated for the IBM RS/6000 is always
13410 position-independent.
13412 When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13413 are defined to 1.
13415 @item -fPIC
13416 @opindex fPIC
13417 If supported for the target machine, emit position-independent code,
13418 suitable for dynamic linking and avoiding any limit on the size of the
13419 global offset table.  This option makes a difference on AArch64, m68k,
13420 PowerPC and SPARC@.
13422 Position-independent code requires special support, and therefore works
13423 only on certain machines.
13425 When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13426 are defined to 2.
13428 @item -fpie
13429 @itemx -fPIE
13430 @opindex fpie
13431 @opindex fPIE
13432 These options are similar to @option{-fpic} and @option{-fPIC}, but the
13433 generated position-independent code can be only linked into executables.
13434 Usually these options are used to compile code that will be linked using
13435 the @option{-pie} GCC option.
13437 @option{-fpie} and @option{-fPIE} both define the macros
13438 @code{__pie__} and @code{__PIE__}.  The macros have the value 1
13439 for @option{-fpie} and 2 for @option{-fPIE}.
13441 @item -fno-plt
13442 @opindex fno-plt
13443 Do not use the PLT for external function calls in position-independent code.
13444 Instead, load the callee address at call sites from the GOT and branch to it.
13445 This leads to more efficient code by eliminating PLT stubs and exposing
13446 GOT loads to optimizations.  On architectures such as 32-bit x86 where
13447 PLT stubs expect the GOT pointer in a specific register, this gives more
13448 register allocation freedom to the compiler.
13449 Lazy binding requires use of the PLT; 
13450 with @option{-fno-plt} all external symbols are resolved at load time.
13452 Alternatively, the function attribute @code{noplt} can be used to avoid calls
13453 through the PLT for specific external functions.
13455 In position-dependent code, a few targets also convert calls to
13456 functions that are marked to not use the PLT to use the GOT instead.
13458 @item -fno-jump-tables
13459 @opindex fno-jump-tables
13460 Do not use jump tables for switch statements even where it would be
13461 more efficient than other code generation strategies.  This option is
13462 of use in conjunction with @option{-fpic} or @option{-fPIC} for
13463 building code that forms part of a dynamic linker and cannot
13464 reference the address of a jump table.  On some targets, jump tables
13465 do not require a GOT and this option is not needed.
13467 @item -ffixed-@var{reg}
13468 @opindex ffixed
13469 Treat the register named @var{reg} as a fixed register; generated code
13470 should never refer to it (except perhaps as a stack pointer, frame
13471 pointer or in some other fixed role).
13473 @var{reg} must be the name of a register.  The register names accepted
13474 are machine-specific and are defined in the @code{REGISTER_NAMES}
13475 macro in the machine description macro file.
13477 This flag does not have a negative form, because it specifies a
13478 three-way choice.
13480 @item -fcall-used-@var{reg}
13481 @opindex fcall-used
13482 Treat the register named @var{reg} as an allocable register that is
13483 clobbered by function calls.  It may be allocated for temporaries or
13484 variables that do not live across a call.  Functions compiled this way
13485 do not save and restore the register @var{reg}.
13487 It is an error to use this flag with the frame pointer or stack pointer.
13488 Use of this flag for other registers that have fixed pervasive roles in
13489 the machine's execution model produces disastrous results.
13491 This flag does not have a negative form, because it specifies a
13492 three-way choice.
13494 @item -fcall-saved-@var{reg}
13495 @opindex fcall-saved
13496 Treat the register named @var{reg} as an allocable register saved by
13497 functions.  It may be allocated even for temporaries or variables that
13498 live across a call.  Functions compiled this way save and restore
13499 the register @var{reg} if they use it.
13501 It is an error to use this flag with the frame pointer or stack pointer.
13502 Use of this flag for other registers that have fixed pervasive roles in
13503 the machine's execution model produces disastrous results.
13505 A different sort of disaster results from the use of this flag for
13506 a register in which function values may be returned.
13508 This flag does not have a negative form, because it specifies a
13509 three-way choice.
13511 @item -fpack-struct[=@var{n}]
13512 @opindex fpack-struct
13513 Without a value specified, pack all structure members together without
13514 holes.  When a value is specified (which must be a small power of two), pack
13515 structure members according to this value, representing the maximum
13516 alignment (that is, objects with default alignment requirements larger than
13517 this are output potentially unaligned at the next fitting location.
13519 @strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
13520 code that is not binary compatible with code generated without that switch.
13521 Additionally, it makes the code suboptimal.
13522 Use it to conform to a non-default application binary interface.
13524 @item -fleading-underscore
13525 @opindex fleading-underscore
13526 This option and its counterpart, @option{-fno-leading-underscore}, forcibly
13527 change the way C symbols are represented in the object file.  One use
13528 is to help link with legacy assembly code.
13530 @strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
13531 generate code that is not binary compatible with code generated without that
13532 switch.  Use it to conform to a non-default application binary interface.
13533 Not all targets provide complete support for this switch.
13535 @item -ftls-model=@var{model}
13536 @opindex ftls-model
13537 Alter the thread-local storage model to be used (@pxref{Thread-Local}).
13538 The @var{model} argument should be one of @samp{global-dynamic},
13539 @samp{local-dynamic}, @samp{initial-exec} or @samp{local-exec}.
13540 Note that the choice is subject to optimization: the compiler may use
13541 a more efficient model for symbols not visible outside of the translation
13542 unit, or if @option{-fpic} is not given on the command line.
13544 The default without @option{-fpic} is @samp{initial-exec}; with
13545 @option{-fpic} the default is @samp{global-dynamic}.
13547 @item -ftrampolines
13548 @opindex ftrampolines
13549 For targets that normally need trampolines for nested functions, always
13550 generate them instead of using descriptors.  Otherwise, for targets that
13551 do not need them, like for example HP-PA or IA-64, do nothing.
13553 A trampoline is a small piece of code that is created at run time on the
13554 stack when the address of a nested function is taken, and is used to call
13555 the nested function indirectly.  Therefore, it requires the stack to be
13556 made executable in order for the program to work properly.
13558 @option{-fno-trampolines} is enabled by default on a language by language
13559 basis to let the compiler avoid generating them, if it computes that this
13560 is safe, and replace them with descriptors.  Descriptors are made up of data
13561 only, but the generated code must be prepared to deal with them.  As of this
13562 writing, @option{-fno-trampolines} is enabled by default only for Ada.
13564 Moreover, code compiled with @option{-ftrampolines} and code compiled with
13565 @option{-fno-trampolines} are not binary compatible if nested functions are
13566 present.  This option must therefore be used on a program-wide basis and be
13567 manipulated with extreme care.
13569 @item -fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]}
13570 @opindex fvisibility
13571 Set the default ELF image symbol visibility to the specified option---all
13572 symbols are marked with this unless overridden within the code.
13573 Using this feature can very substantially improve linking and
13574 load times of shared object libraries, produce more optimized
13575 code, provide near-perfect API export and prevent symbol clashes.
13576 It is @strong{strongly} recommended that you use this in any shared objects
13577 you distribute.
13579 Despite the nomenclature, @samp{default} always means public; i.e.,
13580 available to be linked against from outside the shared object.
13581 @samp{protected} and @samp{internal} are pretty useless in real-world
13582 usage so the only other commonly used option is @samp{hidden}.
13583 The default if @option{-fvisibility} isn't specified is
13584 @samp{default}, i.e., make every symbol public.
13586 A good explanation of the benefits offered by ensuring ELF
13587 symbols have the correct visibility is given by ``How To Write
13588 Shared Libraries'' by Ulrich Drepper (which can be found at
13589 @w{@uref{https://www.akkadia.org/drepper/}})---however a superior
13590 solution made possible by this option to marking things hidden when
13591 the default is public is to make the default hidden and mark things
13592 public.  This is the norm with DLLs on Windows and with @option{-fvisibility=hidden}
13593 and @code{__attribute__ ((visibility("default")))} instead of
13594 @code{__declspec(dllexport)} you get almost identical semantics with
13595 identical syntax.  This is a great boon to those working with
13596 cross-platform projects.
13598 For those adding visibility support to existing code, you may find
13599 @code{#pragma GCC visibility} of use.  This works by you enclosing
13600 the declarations you wish to set visibility for with (for example)
13601 @code{#pragma GCC visibility push(hidden)} and
13602 @code{#pragma GCC visibility pop}.
13603 Bear in mind that symbol visibility should be viewed @strong{as
13604 part of the API interface contract} and thus all new code should
13605 always specify visibility when it is not the default; i.e., declarations
13606 only for use within the local DSO should @strong{always} be marked explicitly
13607 as hidden as so to avoid PLT indirection overheads---making this
13608 abundantly clear also aids readability and self-documentation of the code.
13609 Note that due to ISO C++ specification requirements, @code{operator new} and
13610 @code{operator delete} must always be of default visibility.
13612 Be aware that headers from outside your project, in particular system
13613 headers and headers from any other library you use, may not be
13614 expecting to be compiled with visibility other than the default.  You
13615 may need to explicitly say @code{#pragma GCC visibility push(default)}
13616 before including any such headers.
13618 @code{extern} declarations are not affected by @option{-fvisibility}, so
13619 a lot of code can be recompiled with @option{-fvisibility=hidden} with
13620 no modifications.  However, this means that calls to @code{extern}
13621 functions with no explicit visibility use the PLT, so it is more
13622 effective to use @code{__attribute ((visibility))} and/or
13623 @code{#pragma GCC visibility} to tell the compiler which @code{extern}
13624 declarations should be treated as hidden.
13626 Note that @option{-fvisibility} does affect C++ vague linkage
13627 entities. This means that, for instance, an exception class that is
13628 be thrown between DSOs must be explicitly marked with default
13629 visibility so that the @samp{type_info} nodes are unified between
13630 the DSOs.
13632 An overview of these techniques, their benefits and how to use them
13633 is at @uref{http://gcc.gnu.org/@/wiki/@/Visibility}.
13635 @item -fstrict-volatile-bitfields
13636 @opindex fstrict-volatile-bitfields
13637 This option should be used if accesses to volatile bit-fields (or other
13638 structure fields, although the compiler usually honors those types
13639 anyway) should use a single access of the width of the
13640 field's type, aligned to a natural alignment if possible.  For
13641 example, targets with memory-mapped peripheral registers might require
13642 all such accesses to be 16 bits wide; with this flag you can
13643 declare all peripheral bit-fields as @code{unsigned short} (assuming short
13644 is 16 bits on these targets) to force GCC to use 16-bit accesses
13645 instead of, perhaps, a more efficient 32-bit access.
13647 If this option is disabled, the compiler uses the most efficient
13648 instruction.  In the previous example, that might be a 32-bit load
13649 instruction, even though that accesses bytes that do not contain
13650 any portion of the bit-field, or memory-mapped registers unrelated to
13651 the one being updated.
13653 In some cases, such as when the @code{packed} attribute is applied to a 
13654 structure field, it may not be possible to access the field with a single
13655 read or write that is correctly aligned for the target machine.  In this
13656 case GCC falls back to generating multiple accesses rather than code that 
13657 will fault or truncate the result at run time.
13659 Note:  Due to restrictions of the C/C++11 memory model, write accesses are
13660 not allowed to touch non bit-field members.  It is therefore recommended
13661 to define all bits of the field's type as bit-field members.
13663 The default value of this option is determined by the application binary
13664 interface for the target processor.
13666 @item -fsync-libcalls
13667 @opindex fsync-libcalls
13668 This option controls whether any out-of-line instance of the @code{__sync}
13669 family of functions may be used to implement the C++11 @code{__atomic}
13670 family of functions.
13672 The default value of this option is enabled, thus the only useful form
13673 of the option is @option{-fno-sync-libcalls}.  This option is used in
13674 the implementation of the @file{libatomic} runtime library.
13676 @end table
13678 @node Developer Options
13679 @section GCC Developer Options
13680 @cindex developer options
13681 @cindex debugging GCC
13682 @cindex debug dump options
13683 @cindex dump options
13684 @cindex compilation statistics
13686 This section describes command-line options that are primarily of
13687 interest to GCC developers, including options to support compiler
13688 testing and investigation of compiler bugs and compile-time
13689 performance problems.  This includes options that produce debug dumps
13690 at various points in the compilation; that print statistics such as
13691 memory use and execution time; and that print information about GCC's
13692 configuration, such as where it searches for libraries.  You should
13693 rarely need to use any of these options for ordinary compilation and
13694 linking tasks.
13696 Many developer options that cause GCC to dump output to a file take an
13697 optional @samp{=@var{filename}} suffix. You can specify @samp{stdout}
13698 or @samp{-} to dump to standard output, and @samp{stderr} for standard
13699 error.
13701 If @samp{=@var{filename}} is omitted, a default dump file name is
13702 constructed by concatenating the base dump file name, a pass number,
13703 phase letter, and pass name.  The base dump file name is the name of
13704 output file produced by the compiler if explicitly specified and not
13705 an executable; otherwise it is the source file name.
13706 The pass number is determined by the order passes are registered with
13707 the compiler's pass manager. 
13708 This is generally the same as the order of execution, but passes
13709 registered by plugins, target-specific passes, or passes that are
13710 otherwise registered late are numbered higher than the pass named
13711 @samp{final}, even if they are executed earlier.  The phase letter is
13712 one of @samp{i} (inter-procedural analysis), @samp{l}
13713 (language-specific), @samp{r} (RTL), or @samp{t} (tree). 
13714 The files are created in the directory of the output file. 
13716 @table @gcctabopt
13718 @item -d@var{letters}
13719 @itemx -fdump-rtl-@var{pass}
13720 @itemx -fdump-rtl-@var{pass}=@var{filename}
13721 @opindex d
13722 @opindex fdump-rtl-@var{pass}
13723 Says to make debugging dumps during compilation at times specified by
13724 @var{letters}.  This is used for debugging the RTL-based passes of the
13725 compiler.
13727 Some @option{-d@var{letters}} switches have different meaning when
13728 @option{-E} is used for preprocessing.  @xref{Preprocessor Options},
13729 for information about preprocessor-specific dump options.
13731 Debug dumps can be enabled with a @option{-fdump-rtl} switch or some
13732 @option{-d} option @var{letters}.  Here are the possible
13733 letters for use in @var{pass} and @var{letters}, and their meanings:
13735 @table @gcctabopt
13737 @item -fdump-rtl-alignments
13738 @opindex fdump-rtl-alignments
13739 Dump after branch alignments have been computed.
13741 @item -fdump-rtl-asmcons
13742 @opindex fdump-rtl-asmcons
13743 Dump after fixing rtl statements that have unsatisfied in/out constraints.
13745 @item -fdump-rtl-auto_inc_dec
13746 @opindex fdump-rtl-auto_inc_dec
13747 Dump after auto-inc-dec discovery.  This pass is only run on
13748 architectures that have auto inc or auto dec instructions.
13750 @item -fdump-rtl-barriers
13751 @opindex fdump-rtl-barriers
13752 Dump after cleaning up the barrier instructions.
13754 @item -fdump-rtl-bbpart
13755 @opindex fdump-rtl-bbpart
13756 Dump after partitioning hot and cold basic blocks.
13758 @item -fdump-rtl-bbro
13759 @opindex fdump-rtl-bbro
13760 Dump after block reordering.
13762 @item -fdump-rtl-btl1
13763 @itemx -fdump-rtl-btl2
13764 @opindex fdump-rtl-btl2
13765 @opindex fdump-rtl-btl2
13766 @option{-fdump-rtl-btl1} and @option{-fdump-rtl-btl2} enable dumping
13767 after the two branch
13768 target load optimization passes.
13770 @item -fdump-rtl-bypass
13771 @opindex fdump-rtl-bypass
13772 Dump after jump bypassing and control flow optimizations.
13774 @item -fdump-rtl-combine
13775 @opindex fdump-rtl-combine
13776 Dump after the RTL instruction combination pass.
13778 @item -fdump-rtl-compgotos
13779 @opindex fdump-rtl-compgotos
13780 Dump after duplicating the computed gotos.
13782 @item -fdump-rtl-ce1
13783 @itemx -fdump-rtl-ce2
13784 @itemx -fdump-rtl-ce3
13785 @opindex fdump-rtl-ce1
13786 @opindex fdump-rtl-ce2
13787 @opindex fdump-rtl-ce3
13788 @option{-fdump-rtl-ce1}, @option{-fdump-rtl-ce2}, and
13789 @option{-fdump-rtl-ce3} enable dumping after the three
13790 if conversion passes.
13792 @item -fdump-rtl-cprop_hardreg
13793 @opindex fdump-rtl-cprop_hardreg
13794 Dump after hard register copy propagation.
13796 @item -fdump-rtl-csa
13797 @opindex fdump-rtl-csa
13798 Dump after combining stack adjustments.
13800 @item -fdump-rtl-cse1
13801 @itemx -fdump-rtl-cse2
13802 @opindex fdump-rtl-cse1
13803 @opindex fdump-rtl-cse2
13804 @option{-fdump-rtl-cse1} and @option{-fdump-rtl-cse2} enable dumping after
13805 the two common subexpression elimination passes.
13807 @item -fdump-rtl-dce
13808 @opindex fdump-rtl-dce
13809 Dump after the standalone dead code elimination passes.
13811 @item -fdump-rtl-dbr
13812 @opindex fdump-rtl-dbr
13813 Dump after delayed branch scheduling.
13815 @item -fdump-rtl-dce1
13816 @itemx -fdump-rtl-dce2
13817 @opindex fdump-rtl-dce1
13818 @opindex fdump-rtl-dce2
13819 @option{-fdump-rtl-dce1} and @option{-fdump-rtl-dce2} enable dumping after
13820 the two dead store elimination passes.
13822 @item -fdump-rtl-eh
13823 @opindex fdump-rtl-eh
13824 Dump after finalization of EH handling code.
13826 @item -fdump-rtl-eh_ranges
13827 @opindex fdump-rtl-eh_ranges
13828 Dump after conversion of EH handling range regions.
13830 @item -fdump-rtl-expand
13831 @opindex fdump-rtl-expand
13832 Dump after RTL generation.
13834 @item -fdump-rtl-fwprop1
13835 @itemx -fdump-rtl-fwprop2
13836 @opindex fdump-rtl-fwprop1
13837 @opindex fdump-rtl-fwprop2
13838 @option{-fdump-rtl-fwprop1} and @option{-fdump-rtl-fwprop2} enable
13839 dumping after the two forward propagation passes.
13841 @item -fdump-rtl-gcse1
13842 @itemx -fdump-rtl-gcse2
13843 @opindex fdump-rtl-gcse1
13844 @opindex fdump-rtl-gcse2
13845 @option{-fdump-rtl-gcse1} and @option{-fdump-rtl-gcse2} enable dumping
13846 after global common subexpression elimination.
13848 @item -fdump-rtl-init-regs
13849 @opindex fdump-rtl-init-regs
13850 Dump after the initialization of the registers.
13852 @item -fdump-rtl-initvals
13853 @opindex fdump-rtl-initvals
13854 Dump after the computation of the initial value sets.
13856 @item -fdump-rtl-into_cfglayout
13857 @opindex fdump-rtl-into_cfglayout
13858 Dump after converting to cfglayout mode.
13860 @item -fdump-rtl-ira
13861 @opindex fdump-rtl-ira
13862 Dump after iterated register allocation.
13864 @item -fdump-rtl-jump
13865 @opindex fdump-rtl-jump
13866 Dump after the second jump optimization.
13868 @item -fdump-rtl-loop2
13869 @opindex fdump-rtl-loop2
13870 @option{-fdump-rtl-loop2} enables dumping after the rtl
13871 loop optimization passes.
13873 @item -fdump-rtl-mach
13874 @opindex fdump-rtl-mach
13875 Dump after performing the machine dependent reorganization pass, if that
13876 pass exists.
13878 @item -fdump-rtl-mode_sw
13879 @opindex fdump-rtl-mode_sw
13880 Dump after removing redundant mode switches.
13882 @item -fdump-rtl-rnreg
13883 @opindex fdump-rtl-rnreg
13884 Dump after register renumbering.
13886 @item -fdump-rtl-outof_cfglayout
13887 @opindex fdump-rtl-outof_cfglayout
13888 Dump after converting from cfglayout mode.
13890 @item -fdump-rtl-peephole2
13891 @opindex fdump-rtl-peephole2
13892 Dump after the peephole pass.
13894 @item -fdump-rtl-postreload
13895 @opindex fdump-rtl-postreload
13896 Dump after post-reload optimizations.
13898 @item -fdump-rtl-pro_and_epilogue
13899 @opindex fdump-rtl-pro_and_epilogue
13900 Dump after generating the function prologues and epilogues.
13902 @item -fdump-rtl-sched1
13903 @itemx -fdump-rtl-sched2
13904 @opindex fdump-rtl-sched1
13905 @opindex fdump-rtl-sched2
13906 @option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2} enable dumping
13907 after the basic block scheduling passes.
13909 @item -fdump-rtl-ree
13910 @opindex fdump-rtl-ree
13911 Dump after sign/zero extension elimination.
13913 @item -fdump-rtl-seqabstr
13914 @opindex fdump-rtl-seqabstr
13915 Dump after common sequence discovery.
13917 @item -fdump-rtl-shorten
13918 @opindex fdump-rtl-shorten
13919 Dump after shortening branches.
13921 @item -fdump-rtl-sibling
13922 @opindex fdump-rtl-sibling
13923 Dump after sibling call optimizations.
13925 @item -fdump-rtl-split1
13926 @itemx -fdump-rtl-split2
13927 @itemx -fdump-rtl-split3
13928 @itemx -fdump-rtl-split4
13929 @itemx -fdump-rtl-split5
13930 @opindex fdump-rtl-split1
13931 @opindex fdump-rtl-split2
13932 @opindex fdump-rtl-split3
13933 @opindex fdump-rtl-split4
13934 @opindex fdump-rtl-split5
13935 These options enable dumping after five rounds of
13936 instruction splitting.
13938 @item -fdump-rtl-sms
13939 @opindex fdump-rtl-sms
13940 Dump after modulo scheduling.  This pass is only run on some
13941 architectures.
13943 @item -fdump-rtl-stack
13944 @opindex fdump-rtl-stack
13945 Dump after conversion from GCC's ``flat register file'' registers to the
13946 x87's stack-like registers.  This pass is only run on x86 variants.
13948 @item -fdump-rtl-subreg1
13949 @itemx -fdump-rtl-subreg2
13950 @opindex fdump-rtl-subreg1
13951 @opindex fdump-rtl-subreg2
13952 @option{-fdump-rtl-subreg1} and @option{-fdump-rtl-subreg2} enable dumping after
13953 the two subreg expansion passes.
13955 @item -fdump-rtl-unshare
13956 @opindex fdump-rtl-unshare
13957 Dump after all rtl has been unshared.
13959 @item -fdump-rtl-vartrack
13960 @opindex fdump-rtl-vartrack
13961 Dump after variable tracking.
13963 @item -fdump-rtl-vregs
13964 @opindex fdump-rtl-vregs
13965 Dump after converting virtual registers to hard registers.
13967 @item -fdump-rtl-web
13968 @opindex fdump-rtl-web
13969 Dump after live range splitting.
13971 @item -fdump-rtl-regclass
13972 @itemx -fdump-rtl-subregs_of_mode_init
13973 @itemx -fdump-rtl-subregs_of_mode_finish
13974 @itemx -fdump-rtl-dfinit
13975 @itemx -fdump-rtl-dfinish
13976 @opindex fdump-rtl-regclass
13977 @opindex fdump-rtl-subregs_of_mode_init
13978 @opindex fdump-rtl-subregs_of_mode_finish
13979 @opindex fdump-rtl-dfinit
13980 @opindex fdump-rtl-dfinish
13981 These dumps are defined but always produce empty files.
13983 @item -da
13984 @itemx -fdump-rtl-all
13985 @opindex da
13986 @opindex fdump-rtl-all
13987 Produce all the dumps listed above.
13989 @item -dA
13990 @opindex dA
13991 Annotate the assembler output with miscellaneous debugging information.
13993 @item -dD
13994 @opindex dD
13995 Dump all macro definitions, at the end of preprocessing, in addition to
13996 normal output.
13998 @item -dH
13999 @opindex dH
14000 Produce a core dump whenever an error occurs.
14002 @item -dp
14003 @opindex dp
14004 Annotate the assembler output with a comment indicating which
14005 pattern and alternative is used.  The length and cost of each instruction are
14006 also printed.
14008 @item -dP
14009 @opindex dP
14010 Dump the RTL in the assembler output as a comment before each instruction.
14011 Also turns on @option{-dp} annotation.
14013 @item -dx
14014 @opindex dx
14015 Just generate RTL for a function instead of compiling it.  Usually used
14016 with @option{-fdump-rtl-expand}.
14017 @end table
14019 @item -fdump-debug
14020 @opindex fdump-debug
14021 Dump debugging information generated during the debug
14022 generation phase.
14024 @item -fdump-earlydebug
14025 @opindex fdump-earlydebug
14026 Dump debugging information generated during the early debug
14027 generation phase.
14029 @item -fdump-noaddr
14030 @opindex fdump-noaddr
14031 When doing debugging dumps, suppress address output.  This makes it more
14032 feasible to use diff on debugging dumps for compiler invocations with
14033 different compiler binaries and/or different
14034 text / bss / data / heap / stack / dso start locations.
14036 @item -freport-bug
14037 @opindex freport-bug
14038 Collect and dump debug information into a temporary file if an
14039 internal compiler error (ICE) occurs.
14041 @item -fdump-unnumbered
14042 @opindex fdump-unnumbered
14043 When doing debugging dumps, suppress instruction numbers and address output.
14044 This makes it more feasible to use diff on debugging dumps for compiler
14045 invocations with different options, in particular with and without
14046 @option{-g}.
14048 @item -fdump-unnumbered-links
14049 @opindex fdump-unnumbered-links
14050 When doing debugging dumps (see @option{-d} option above), suppress
14051 instruction numbers for the links to the previous and next instructions
14052 in a sequence.
14054 @item -fdump-ipa-@var{switch}
14055 @opindex fdump-ipa
14056 Control the dumping at various stages of inter-procedural analysis
14057 language tree to a file.  The file name is generated by appending a
14058 switch specific suffix to the source file name, and the file is created
14059 in the same directory as the output file.  The following dumps are
14060 possible:
14062 @table @samp
14063 @item all
14064 Enables all inter-procedural analysis dumps.
14066 @item cgraph
14067 Dumps information about call-graph optimization, unused function removal,
14068 and inlining decisions.
14070 @item inline
14071 Dump after function inlining.
14073 @end table
14075 @item -fdump-lang-all
14076 @itemx -fdump-lang-@var{switch}
14077 @itemx -fdump-lang-@var{switch}-@var{options}
14078 @itemx -fdump-lang-@var{switch}-@var{options}=@var{filename}
14079 @opindex fdump-lang-all
14080 @opindex fdump-lang
14081 Control the dumping of language-specific information.  The @var{options}
14082 and @var{filename} portions behave as described in the
14083 @option{-fdump-tree} option.  The following @var{switch} values are
14084 accepted:
14086 @table @samp
14087 @item all
14089 Enable all language-specific dumps.
14091 @item class
14092 Dump class hierarchy information.  Virtual table information is emitted
14093 unless '@option{slim}' is specified.  This option is applicable to C++ only.
14095 @item raw
14096 Dump the raw internal tree data.  This option is applicable to C++ only.
14098 @end table
14100 @item -fdump-passes
14101 @opindex fdump-passes
14102 Print on @file{stderr} the list of optimization passes that are turned
14103 on and off by the current command-line options.
14105 @item -fdump-statistics-@var{option}
14106 @opindex fdump-statistics
14107 Enable and control dumping of pass statistics in a separate file.  The
14108 file name is generated by appending a suffix ending in
14109 @samp{.statistics} to the source file name, and the file is created in
14110 the same directory as the output file.  If the @samp{-@var{option}}
14111 form is used, @samp{-stats} causes counters to be summed over the
14112 whole compilation unit while @samp{-details} dumps every event as
14113 the passes generate them.  The default with no option is to sum
14114 counters for each function compiled.
14116 @item -fdump-tree-all
14117 @itemx -fdump-tree-@var{switch}
14118 @itemx -fdump-tree-@var{switch}-@var{options}
14119 @itemx -fdump-tree-@var{switch}-@var{options}=@var{filename}
14120 @opindex fdump-tree-all
14121 @opindex fdump-tree
14122 Control the dumping at various stages of processing the intermediate
14123 language tree to a file.  If the @samp{-@var{options}}
14124 form is used, @var{options} is a list of @samp{-} separated options
14125 which control the details of the dump.  Not all options are applicable
14126 to all dumps; those that are not meaningful are ignored.  The
14127 following options are available
14129 @table @samp
14130 @item address
14131 Print the address of each node.  Usually this is not meaningful as it
14132 changes according to the environment and source file.  Its primary use
14133 is for tying up a dump file with a debug environment.
14134 @item asmname
14135 If @code{DECL_ASSEMBLER_NAME} has been set for a given decl, use that
14136 in the dump instead of @code{DECL_NAME}.  Its primary use is ease of
14137 use working backward from mangled names in the assembly file.
14138 @item slim
14139 When dumping front-end intermediate representations, inhibit dumping
14140 of members of a scope or body of a function merely because that scope
14141 has been reached.  Only dump such items when they are directly reachable
14142 by some other path.
14144 When dumping pretty-printed trees, this option inhibits dumping the
14145 bodies of control structures.
14147 When dumping RTL, print the RTL in slim (condensed) form instead of
14148 the default LISP-like representation.
14149 @item raw
14150 Print a raw representation of the tree.  By default, trees are
14151 pretty-printed into a C-like representation.
14152 @item details
14153 Enable more detailed dumps (not honored by every dump option). Also
14154 include information from the optimization passes.
14155 @item stats
14156 Enable dumping various statistics about the pass (not honored by every dump
14157 option).
14158 @item blocks
14159 Enable showing basic block boundaries (disabled in raw dumps).
14160 @item graph
14161 For each of the other indicated dump files (@option{-fdump-rtl-@var{pass}}),
14162 dump a representation of the control flow graph suitable for viewing with
14163 GraphViz to @file{@var{file}.@var{passid}.@var{pass}.dot}.  Each function in
14164 the file is pretty-printed as a subgraph, so that GraphViz can render them
14165 all in a single plot.
14167 This option currently only works for RTL dumps, and the RTL is always
14168 dumped in slim form.
14169 @item vops
14170 Enable showing virtual operands for every statement.
14171 @item lineno
14172 Enable showing line numbers for statements.
14173 @item uid
14174 Enable showing the unique ID (@code{DECL_UID}) for each variable.
14175 @item verbose
14176 Enable showing the tree dump for each statement.
14177 @item eh
14178 Enable showing the EH region number holding each statement.
14179 @item scev
14180 Enable showing scalar evolution analysis details.
14181 @item optimized
14182 Enable showing optimization information (only available in certain
14183 passes).
14184 @item missed
14185 Enable showing missed optimization information (only available in certain
14186 passes).
14187 @item note
14188 Enable other detailed optimization information (only available in
14189 certain passes).
14190 @item all
14191 Turn on all options, except @option{raw}, @option{slim}, @option{verbose}
14192 and @option{lineno}.
14193 @item optall
14194 Turn on all optimization options, i.e., @option{optimized},
14195 @option{missed}, and @option{note}.
14196 @end table
14198 To determine what tree dumps are available or find the dump for a pass
14199 of interest follow the steps below.
14201 @enumerate
14202 @item
14203 Invoke GCC with @option{-fdump-passes} and in the @file{stderr} output
14204 look for a code that corresponds to the pass you are interested in.
14205 For example, the codes @code{tree-evrp}, @code{tree-vrp1}, and
14206 @code{tree-vrp2} correspond to the three Value Range Propagation passes.
14207 The number at the end distinguishes distinct invocations of the same pass.
14208 @item
14209 To enable the creation of the dump file, append the pass code to
14210 the @option{-fdump-} option prefix and invoke GCC with it.  For example,
14211 to enable the dump from the Early Value Range Propagation pass, invoke
14212 GCC with the @option{-fdump-tree-evrp} option.  Optionally, you may
14213 specify the name of the dump file.  If you don't specify one, GCC
14214 creates as described below.
14215 @item
14216 Find the pass dump in a file whose name is composed of three components
14217 separated by a period: the name of the source file GCC was invoked to
14218 compile, a numeric suffix indicating the pass number followed by the
14219 letter @samp{t} for tree passes (and the letter @samp{r} for RTL passes),
14220 and finally the pass code.  For example, the Early VRP pass dump might
14221 be in a file named @file{myfile.c.038t.evrp} in the current working
14222 directory.  Note that the numeric codes are not stable and may change
14223 from one version of GCC to another.
14224 @end enumerate
14226 @item -fopt-info
14227 @itemx -fopt-info-@var{options}
14228 @itemx -fopt-info-@var{options}=@var{filename}
14229 @opindex fopt-info
14230 Controls optimization dumps from various optimization passes. If the
14231 @samp{-@var{options}} form is used, @var{options} is a list of
14232 @samp{-} separated option keywords to select the dump details and
14233 optimizations.  
14235 The @var{options} can be divided into three groups:
14236 @enumerate
14237 @item
14238 options describing what kinds of messages should be emitted,
14239 @item
14240 options describing the verbosity of the dump, and
14241 @item
14242 options describing which optimizations should be included.
14243 @end enumerate
14244 The options from each group can be freely mixed as they are
14245 non-overlapping. However, in case of any conflicts,
14246 the later options override the earlier options on the command
14247 line. 
14249 The following options control which kinds of messages should be emitted:
14251 @table @samp
14252 @item optimized
14253 Print information when an optimization is successfully applied. It is
14254 up to a pass to decide which information is relevant. For example, the
14255 vectorizer passes print the source location of loops which are
14256 successfully vectorized.
14257 @item missed
14258 Print information about missed optimizations. Individual passes
14259 control which information to include in the output. 
14260 @item note
14261 Print verbose information about optimizations, such as certain
14262 transformations, more detailed messages about decisions etc.
14263 @item all
14264 Print detailed optimization information. This includes
14265 @samp{optimized}, @samp{missed}, and @samp{note}.
14266 @end table
14268 The following option controls the dump verbosity:
14270 @table @samp
14271 @item internals
14272 By default, only ``high-level'' messages are emitted. This option enables
14273 additional, more detailed, messages, which are likely to only be of interest
14274 to GCC developers.
14275 @end table
14277 One or more of the following option keywords can be used to describe a
14278 group of optimizations:
14280 @table @samp
14281 @item ipa
14282 Enable dumps from all interprocedural optimizations.
14283 @item loop
14284 Enable dumps from all loop optimizations.
14285 @item inline
14286 Enable dumps from all inlining optimizations.
14287 @item omp
14288 Enable dumps from all OMP (Offloading and Multi Processing) optimizations.
14289 @item vec
14290 Enable dumps from all vectorization optimizations.
14291 @item optall
14292 Enable dumps from all optimizations. This is a superset of
14293 the optimization groups listed above.
14294 @end table
14296 If @var{options} is
14297 omitted, it defaults to @samp{optimized-optall}, which means to dump messages
14298 about successful optimizations from all the passes, omitting messages
14299 that are treated as ``internals''.
14301 If the @var{filename} is provided, then the dumps from all the
14302 applicable optimizations are concatenated into the @var{filename}.
14303 Otherwise the dump is output onto @file{stderr}. Though multiple
14304 @option{-fopt-info} options are accepted, only one of them can include
14305 a @var{filename}. If other filenames are provided then all but the
14306 first such option are ignored.
14308 Note that the output @var{filename} is overwritten
14309 in case of multiple translation units. If a combined output from
14310 multiple translation units is desired, @file{stderr} should be used
14311 instead.
14313 In the following example, the optimization info is output to
14314 @file{stderr}:
14316 @smallexample
14317 gcc -O3 -fopt-info
14318 @end smallexample
14320 This example:
14321 @smallexample
14322 gcc -O3 -fopt-info-missed=missed.all
14323 @end smallexample
14325 @noindent
14326 outputs missed optimization report from all the passes into
14327 @file{missed.all}, and this one:
14329 @smallexample
14330 gcc -O2 -ftree-vectorize -fopt-info-vec-missed
14331 @end smallexample
14333 @noindent
14334 prints information about missed optimization opportunities from
14335 vectorization passes on @file{stderr}.  
14336 Note that @option{-fopt-info-vec-missed} is equivalent to 
14337 @option{-fopt-info-missed-vec}.  The order of the optimization group
14338 names and message types listed after @option{-fopt-info} does not matter.
14340 As another example,
14341 @smallexample
14342 gcc -O3 -fopt-info-inline-optimized-missed=inline.txt
14343 @end smallexample
14345 @noindent
14346 outputs information about missed optimizations as well as
14347 optimized locations from all the inlining passes into
14348 @file{inline.txt}.
14350 Finally, consider:
14352 @smallexample
14353 gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt
14354 @end smallexample
14356 @noindent
14357 Here the two output filenames @file{vec.miss} and @file{loop.opt} are
14358 in conflict since only one output file is allowed. In this case, only
14359 the first option takes effect and the subsequent options are
14360 ignored. Thus only @file{vec.miss} is produced which contains
14361 dumps from the vectorizer about missed opportunities.
14363 @item -fsave-optimization-record
14364 @opindex fsave-optimization-record
14365 Write a SRCFILE.opt-record.json file detailing what optimizations
14366 were performed, for those optimizations that support @option{-fopt-info}.
14368 This option is experimental and the format of the data within the JSON
14369 file is subject to change.
14371 It is roughly equivalent to a machine-readable version of
14372 @option{-fopt-info-all}, as a collection of messages with source file,
14373 line number and column number, with the following additional data for
14374 each message:
14376 @itemize @bullet
14378 @item
14379 the execution count of the code being optimized, along with metadata about
14380 whether this was from actual profile data, or just an estimate, allowing
14381 consumers to prioritize messages by code hotness,
14383 @item
14384 the function name of the code being optimized, where applicable,
14386 @item
14387 the ``inlining chain'' for the code being optimized, so that when
14388 a function is inlined into several different places (which might
14389 themselves be inlined), the reader can distinguish between the copies,
14391 @item
14392 objects identifying those parts of the message that refer to expressions,
14393 statements or symbol-table nodes, which of these categories they are, and,
14394 when available, their source code location,
14396 @item
14397 the GCC pass that emitted the message, and
14399 @item
14400 the location in GCC's own code from which the message was emitted
14402 @end itemize
14404 Additionally, some messages are logically nested within other
14405 messages, reflecting implementation details of the optimization
14406 passes.
14408 @item -fsched-verbose=@var{n}
14409 @opindex fsched-verbose
14410 On targets that use instruction scheduling, this option controls the
14411 amount of debugging output the scheduler prints to the dump files.
14413 For @var{n} greater than zero, @option{-fsched-verbose} outputs the
14414 same information as @option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2}.
14415 For @var{n} greater than one, it also output basic block probabilities,
14416 detailed ready list information and unit/insn info.  For @var{n} greater
14417 than two, it includes RTL at abort point, control-flow and regions info.
14418 And for @var{n} over four, @option{-fsched-verbose} also includes
14419 dependence info.
14423 @item -fenable-@var{kind}-@var{pass}
14424 @itemx -fdisable-@var{kind}-@var{pass}=@var{range-list}
14425 @opindex fdisable-
14426 @opindex fenable-
14428 This is a set of options that are used to explicitly disable/enable
14429 optimization passes.  These options are intended for use for debugging GCC.
14430 Compiler users should use regular options for enabling/disabling
14431 passes instead.
14433 @table @gcctabopt
14435 @item -fdisable-ipa-@var{pass}
14436 Disable IPA pass @var{pass}. @var{pass} is the pass name.  If the same pass is
14437 statically invoked in the compiler multiple times, the pass name should be
14438 appended with a sequential number starting from 1.
14440 @item -fdisable-rtl-@var{pass}
14441 @itemx -fdisable-rtl-@var{pass}=@var{range-list}
14442 Disable RTL pass @var{pass}.  @var{pass} is the pass name.  If the same pass is
14443 statically invoked in the compiler multiple times, the pass name should be
14444 appended with a sequential number starting from 1.  @var{range-list} is a 
14445 comma-separated list of function ranges or assembler names.  Each range is a number
14446 pair separated by a colon.  The range is inclusive in both ends.  If the range
14447 is trivial, the number pair can be simplified as a single number.  If the
14448 function's call graph node's @var{uid} falls within one of the specified ranges,
14449 the @var{pass} is disabled for that function.  The @var{uid} is shown in the
14450 function header of a dump file, and the pass names can be dumped by using
14451 option @option{-fdump-passes}.
14453 @item -fdisable-tree-@var{pass}
14454 @itemx -fdisable-tree-@var{pass}=@var{range-list}
14455 Disable tree pass @var{pass}.  See @option{-fdisable-rtl} for the description of
14456 option arguments.
14458 @item -fenable-ipa-@var{pass}
14459 Enable IPA pass @var{pass}.  @var{pass} is the pass name.  If the same pass is
14460 statically invoked in the compiler multiple times, the pass name should be
14461 appended with a sequential number starting from 1.
14463 @item -fenable-rtl-@var{pass}
14464 @itemx -fenable-rtl-@var{pass}=@var{range-list}
14465 Enable RTL pass @var{pass}.  See @option{-fdisable-rtl} for option argument
14466 description and examples.
14468 @item -fenable-tree-@var{pass}
14469 @itemx -fenable-tree-@var{pass}=@var{range-list}
14470 Enable tree pass @var{pass}.  See @option{-fdisable-rtl} for the description
14471 of option arguments.
14473 @end table
14475 Here are some examples showing uses of these options.
14477 @smallexample
14479 # disable ccp1 for all functions
14480    -fdisable-tree-ccp1
14481 # disable complete unroll for function whose cgraph node uid is 1
14482    -fenable-tree-cunroll=1
14483 # disable gcse2 for functions at the following ranges [1,1],
14484 # [300,400], and [400,1000]
14485 # disable gcse2 for functions foo and foo2
14486    -fdisable-rtl-gcse2=foo,foo2
14487 # disable early inlining
14488    -fdisable-tree-einline
14489 # disable ipa inlining
14490    -fdisable-ipa-inline
14491 # enable tree full unroll
14492    -fenable-tree-unroll
14494 @end smallexample
14496 @item -fchecking
14497 @itemx -fchecking=@var{n}
14498 @opindex fchecking
14499 @opindex fno-checking
14500 Enable internal consistency checking.  The default depends on
14501 the compiler configuration.  @option{-fchecking=2} enables further
14502 internal consistency checking that might affect code generation.
14504 @item -frandom-seed=@var{string}
14505 @opindex frandom-seed
14506 This option provides a seed that GCC uses in place of
14507 random numbers in generating certain symbol names
14508 that have to be different in every compiled file.  It is also used to
14509 place unique stamps in coverage data files and the object files that
14510 produce them.  You can use the @option{-frandom-seed} option to produce
14511 reproducibly identical object files.
14513 The @var{string} can either be a number (decimal, octal or hex) or an
14514 arbitrary string (in which case it's converted to a number by
14515 computing CRC32).
14517 The @var{string} should be different for every file you compile.
14519 @item -save-temps
14520 @itemx -save-temps=cwd
14521 @opindex save-temps
14522 Store the usual ``temporary'' intermediate files permanently; place them
14523 in the current directory and name them based on the source file.  Thus,
14524 compiling @file{foo.c} with @option{-c -save-temps} produces files
14525 @file{foo.i} and @file{foo.s}, as well as @file{foo.o}.  This creates a
14526 preprocessed @file{foo.i} output file even though the compiler now
14527 normally uses an integrated preprocessor.
14529 When used in combination with the @option{-x} command-line option,
14530 @option{-save-temps} is sensible enough to avoid over writing an
14531 input source file with the same extension as an intermediate file.
14532 The corresponding intermediate file may be obtained by renaming the
14533 source file before using @option{-save-temps}.
14535 If you invoke GCC in parallel, compiling several different source
14536 files that share a common base name in different subdirectories or the
14537 same source file compiled for multiple output destinations, it is
14538 likely that the different parallel compilers will interfere with each
14539 other, and overwrite the temporary files.  For instance:
14541 @smallexample
14542 gcc -save-temps -o outdir1/foo.o indir1/foo.c&
14543 gcc -save-temps -o outdir2/foo.o indir2/foo.c&
14544 @end smallexample
14546 may result in @file{foo.i} and @file{foo.o} being written to
14547 simultaneously by both compilers.
14549 @item -save-temps=obj
14550 @opindex save-temps=obj
14551 Store the usual ``temporary'' intermediate files permanently.  If the
14552 @option{-o} option is used, the temporary files are based on the
14553 object file.  If the @option{-o} option is not used, the
14554 @option{-save-temps=obj} switch behaves like @option{-save-temps}.
14556 For example:
14558 @smallexample
14559 gcc -save-temps=obj -c foo.c
14560 gcc -save-temps=obj -c bar.c -o dir/xbar.o
14561 gcc -save-temps=obj foobar.c -o dir2/yfoobar
14562 @end smallexample
14564 @noindent
14565 creates @file{foo.i}, @file{foo.s}, @file{dir/xbar.i},
14566 @file{dir/xbar.s}, @file{dir2/yfoobar.i}, @file{dir2/yfoobar.s}, and
14567 @file{dir2/yfoobar.o}.
14569 @item -time@r{[}=@var{file}@r{]}
14570 @opindex time
14571 Report the CPU time taken by each subprocess in the compilation
14572 sequence.  For C source files, this is the compiler proper and assembler
14573 (plus the linker if linking is done).
14575 Without the specification of an output file, the output looks like this:
14577 @smallexample
14578 # cc1 0.12 0.01
14579 # as 0.00 0.01
14580 @end smallexample
14582 The first number on each line is the ``user time'', that is time spent
14583 executing the program itself.  The second number is ``system time'',
14584 time spent executing operating system routines on behalf of the program.
14585 Both numbers are in seconds.
14587 With the specification of an output file, the output is appended to the
14588 named file, and it looks like this:
14590 @smallexample
14591 0.12 0.01 cc1 @var{options}
14592 0.00 0.01 as @var{options}
14593 @end smallexample
14595 The ``user time'' and the ``system time'' are moved before the program
14596 name, and the options passed to the program are displayed, so that one
14597 can later tell what file was being compiled, and with which options.
14599 @item -fdump-final-insns@r{[}=@var{file}@r{]}
14600 @opindex fdump-final-insns
14601 Dump the final internal representation (RTL) to @var{file}.  If the
14602 optional argument is omitted (or if @var{file} is @code{.}), the name
14603 of the dump file is determined by appending @code{.gkd} to the
14604 compilation output file name.
14606 @item -fcompare-debug@r{[}=@var{opts}@r{]}
14607 @opindex fcompare-debug
14608 @opindex fno-compare-debug
14609 If no error occurs during compilation, run the compiler a second time,
14610 adding @var{opts} and @option{-fcompare-debug-second} to the arguments
14611 passed to the second compilation.  Dump the final internal
14612 representation in both compilations, and print an error if they differ.
14614 If the equal sign is omitted, the default @option{-gtoggle} is used.
14616 The environment variable @env{GCC_COMPARE_DEBUG}, if defined, non-empty
14617 and nonzero, implicitly enables @option{-fcompare-debug}.  If
14618 @env{GCC_COMPARE_DEBUG} is defined to a string starting with a dash,
14619 then it is used for @var{opts}, otherwise the default @option{-gtoggle}
14620 is used.
14622 @option{-fcompare-debug=}, with the equal sign but without @var{opts},
14623 is equivalent to @option{-fno-compare-debug}, which disables the dumping
14624 of the final representation and the second compilation, preventing even
14625 @env{GCC_COMPARE_DEBUG} from taking effect.
14627 To verify full coverage during @option{-fcompare-debug} testing, set
14628 @env{GCC_COMPARE_DEBUG} to say @option{-fcompare-debug-not-overridden},
14629 which GCC rejects as an invalid option in any actual compilation
14630 (rather than preprocessing, assembly or linking).  To get just a
14631 warning, setting @env{GCC_COMPARE_DEBUG} to @samp{-w%n-fcompare-debug
14632 not overridden} will do.
14634 @item -fcompare-debug-second
14635 @opindex fcompare-debug-second
14636 This option is implicitly passed to the compiler for the second
14637 compilation requested by @option{-fcompare-debug}, along with options to
14638 silence warnings, and omitting other options that would cause the compiler
14639 to produce output to files or to standard output as a side effect.  Dump
14640 files and preserved temporary files are renamed so as to contain the
14641 @code{.gk} additional extension during the second compilation, to avoid
14642 overwriting those generated by the first.
14644 When this option is passed to the compiler driver, it causes the
14645 @emph{first} compilation to be skipped, which makes it useful for little
14646 other than debugging the compiler proper.
14648 @item -gtoggle
14649 @opindex gtoggle
14650 Turn off generation of debug info, if leaving out this option
14651 generates it, or turn it on at level 2 otherwise.  The position of this
14652 argument in the command line does not matter; it takes effect after all
14653 other options are processed, and it does so only once, no matter how
14654 many times it is given.  This is mainly intended to be used with
14655 @option{-fcompare-debug}.
14657 @item -fvar-tracking-assignments-toggle
14658 @opindex fvar-tracking-assignments-toggle
14659 @opindex fno-var-tracking-assignments-toggle
14660 Toggle @option{-fvar-tracking-assignments}, in the same way that
14661 @option{-gtoggle} toggles @option{-g}.
14663 @item -Q
14664 @opindex Q
14665 Makes the compiler print out each function name as it is compiled, and
14666 print some statistics about each pass when it finishes.
14668 @item -ftime-report
14669 @opindex ftime-report
14670 Makes the compiler print some statistics about the time consumed by each
14671 pass when it finishes.
14673 @item -ftime-report-details
14674 @opindex ftime-report-details
14675 Record the time consumed by infrastructure parts separately for each pass.
14677 @item -fira-verbose=@var{n}
14678 @opindex fira-verbose
14679 Control the verbosity of the dump file for the integrated register allocator.
14680 The default value is 5.  If the value @var{n} is greater or equal to 10,
14681 the dump output is sent to stderr using the same format as @var{n} minus 10.
14683 @item -flto-report
14684 @opindex flto-report
14685 Prints a report with internal details on the workings of the link-time
14686 optimizer.  The contents of this report vary from version to version.
14687 It is meant to be useful to GCC developers when processing object
14688 files in LTO mode (via @option{-flto}).
14690 Disabled by default.
14692 @item -flto-report-wpa
14693 @opindex flto-report-wpa
14694 Like @option{-flto-report}, but only print for the WPA phase of Link
14695 Time Optimization.
14697 @item -fmem-report
14698 @opindex fmem-report
14699 Makes the compiler print some statistics about permanent memory
14700 allocation when it finishes.
14702 @item -fmem-report-wpa
14703 @opindex fmem-report-wpa
14704 Makes the compiler print some statistics about permanent memory
14705 allocation for the WPA phase only.
14707 @item -fpre-ipa-mem-report
14708 @opindex fpre-ipa-mem-report
14709 @item -fpost-ipa-mem-report
14710 @opindex fpost-ipa-mem-report
14711 Makes the compiler print some statistics about permanent memory
14712 allocation before or after interprocedural optimization.
14714 @item -fprofile-report
14715 @opindex fprofile-report
14716 Makes the compiler print some statistics about consistency of the
14717 (estimated) profile and effect of individual passes.
14719 @item -fstack-usage
14720 @opindex fstack-usage
14721 Makes the compiler output stack usage information for the program, on a
14722 per-function basis.  The filename for the dump is made by appending
14723 @file{.su} to the @var{auxname}.  @var{auxname} is generated from the name of
14724 the output file, if explicitly specified and it is not an executable,
14725 otherwise it is the basename of the source file.  An entry is made up
14726 of three fields:
14728 @itemize
14729 @item
14730 The name of the function.
14731 @item
14732 A number of bytes.
14733 @item
14734 One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}.
14735 @end itemize
14737 The qualifier @code{static} means that the function manipulates the stack
14738 statically: a fixed number of bytes are allocated for the frame on function
14739 entry and released on function exit; no stack adjustments are otherwise made
14740 in the function.  The second field is this fixed number of bytes.
14742 The qualifier @code{dynamic} means that the function manipulates the stack
14743 dynamically: in addition to the static allocation described above, stack
14744 adjustments are made in the body of the function, for example to push/pop
14745 arguments around function calls.  If the qualifier @code{bounded} is also
14746 present, the amount of these adjustments is bounded at compile time and
14747 the second field is an upper bound of the total amount of stack used by
14748 the function.  If it is not present, the amount of these adjustments is
14749 not bounded at compile time and the second field only represents the
14750 bounded part.
14752 @item -fstats
14753 @opindex fstats
14754 Emit statistics about front-end processing at the end of the compilation.
14755 This option is supported only by the C++ front end, and
14756 the information is generally only useful to the G++ development team.
14758 @item -fdbg-cnt-list
14759 @opindex fdbg-cnt-list
14760 Print the name and the counter upper bound for all debug counters.
14763 @item -fdbg-cnt=@var{counter-value-list}
14764 @opindex fdbg-cnt
14765 Set the internal debug counter lower and upper bound.  @var{counter-value-list}
14766 is a comma-separated list of @var{name}:@var{lower_bound}:@var{upper_bound}
14767 tuples which sets the lower and the upper bound of each debug
14768 counter @var{name}.  The @var{lower_bound} is optional and is zero
14769 initialized if not set.
14770 All debug counters have the initial upper bound of @code{UINT_MAX};
14771 thus @code{dbg_cnt} returns true always unless the upper bound
14772 is set by this option.
14773 For example, with @option{-fdbg-cnt=dce:2:4,tail_call:10},
14774 @code{dbg_cnt(dce)} returns true only for third and fourth invocation.
14775 For @code{dbg_cnt(tail_call)} true is returned for first 10 invocations.
14777 @item -print-file-name=@var{library}
14778 @opindex print-file-name
14779 Print the full absolute name of the library file @var{library} that
14780 would be used when linking---and don't do anything else.  With this
14781 option, GCC does not compile or link anything; it just prints the
14782 file name.
14784 @item -print-multi-directory
14785 @opindex print-multi-directory
14786 Print the directory name corresponding to the multilib selected by any
14787 other switches present in the command line.  This directory is supposed
14788 to exist in @env{GCC_EXEC_PREFIX}.
14790 @item -print-multi-lib
14791 @opindex print-multi-lib
14792 Print the mapping from multilib directory names to compiler switches
14793 that enable them.  The directory name is separated from the switches by
14794 @samp{;}, and each switch starts with an @samp{@@} instead of the
14795 @samp{-}, without spaces between multiple switches.  This is supposed to
14796 ease shell processing.
14798 @item -print-multi-os-directory
14799 @opindex print-multi-os-directory
14800 Print the path to OS libraries for the selected
14801 multilib, relative to some @file{lib} subdirectory.  If OS libraries are
14802 present in the @file{lib} subdirectory and no multilibs are used, this is
14803 usually just @file{.}, if OS libraries are present in @file{lib@var{suffix}}
14804 sibling directories this prints e.g.@: @file{../lib64}, @file{../lib} or
14805 @file{../lib32}, or if OS libraries are present in @file{lib/@var{subdir}}
14806 subdirectories it prints e.g.@: @file{amd64}, @file{sparcv9} or @file{ev6}.
14808 @item -print-multiarch
14809 @opindex print-multiarch
14810 Print the path to OS libraries for the selected multiarch,
14811 relative to some @file{lib} subdirectory.
14813 @item -print-prog-name=@var{program}
14814 @opindex print-prog-name
14815 Like @option{-print-file-name}, but searches for a program such as @command{cpp}.
14817 @item -print-libgcc-file-name
14818 @opindex print-libgcc-file-name
14819 Same as @option{-print-file-name=libgcc.a}.
14821 This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
14822 but you do want to link with @file{libgcc.a}.  You can do:
14824 @smallexample
14825 gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
14826 @end smallexample
14828 @item -print-search-dirs
14829 @opindex print-search-dirs
14830 Print the name of the configured installation directory and a list of
14831 program and library directories @command{gcc} searches---and don't do anything else.
14833 This is useful when @command{gcc} prints the error message
14834 @samp{installation problem, cannot exec cpp0: No such file or directory}.
14835 To resolve this you either need to put @file{cpp0} and the other compiler
14836 components where @command{gcc} expects to find them, or you can set the environment
14837 variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
14838 Don't forget the trailing @samp{/}.
14839 @xref{Environment Variables}.
14841 @item -print-sysroot
14842 @opindex print-sysroot
14843 Print the target sysroot directory that is used during
14844 compilation.  This is the target sysroot specified either at configure
14845 time or using the @option{--sysroot} option, possibly with an extra
14846 suffix that depends on compilation options.  If no target sysroot is
14847 specified, the option prints nothing.
14849 @item -print-sysroot-headers-suffix
14850 @opindex print-sysroot-headers-suffix
14851 Print the suffix added to the target sysroot when searching for
14852 headers, or give an error if the compiler is not configured with such
14853 a suffix---and don't do anything else.
14855 @item -dumpmachine
14856 @opindex dumpmachine
14857 Print the compiler's target machine (for example,
14858 @samp{i686-pc-linux-gnu})---and don't do anything else.
14860 @item -dumpversion
14861 @opindex dumpversion
14862 Print the compiler version (for example, @code{3.0}, @code{6.3.0} or @code{7})---and don't do
14863 anything else.  This is the compiler version used in filesystem paths and
14864 specs. Depending on how the compiler has been configured it can be just
14865 a single number (major version), two numbers separated by a dot (major and
14866 minor version) or three numbers separated by dots (major, minor and patchlevel
14867 version).
14869 @item -dumpfullversion
14870 @opindex dumpfullversion
14871 Print the full compiler version---and don't do anything else. The output is
14872 always three numbers separated by dots, major, minor and patchlevel version.
14874 @item -dumpspecs
14875 @opindex dumpspecs
14876 Print the compiler's built-in specs---and don't do anything else.  (This
14877 is used when GCC itself is being built.)  @xref{Spec Files}.
14878 @end table
14880 @node Submodel Options
14881 @section Machine-Dependent Options
14882 @cindex submodel options
14883 @cindex specifying hardware config
14884 @cindex hardware models and configurations, specifying
14885 @cindex target-dependent options
14886 @cindex machine-dependent options
14888 Each target machine supported by GCC can have its own options---for
14889 example, to allow you to compile for a particular processor variant or
14890 ABI, or to control optimizations specific to that machine.  By
14891 convention, the names of machine-specific options start with
14892 @samp{-m}.
14894 Some configurations of the compiler also support additional target-specific
14895 options, usually for compatibility with other compilers on the same
14896 platform.
14898 @c This list is ordered alphanumerically by subsection name.
14899 @c It should be the same order and spelling as these options are listed
14900 @c in Machine Dependent Options
14902 @menu
14903 * AArch64 Options::
14904 * Adapteva Epiphany Options::
14905 * ARC Options::
14906 * ARM Options::
14907 * AVR Options::
14908 * Blackfin Options::
14909 * C6X Options::
14910 * CRIS Options::
14911 * CR16 Options::
14912 * C-SKY Options::
14913 * Darwin Options::
14914 * DEC Alpha Options::
14915 * FR30 Options::
14916 * FT32 Options::
14917 * FRV Options::
14918 * GNU/Linux Options::
14919 * H8/300 Options::
14920 * HPPA Options::
14921 * IA-64 Options::
14922 * LM32 Options::
14923 * M32C Options::
14924 * M32R/D Options::
14925 * M680x0 Options::
14926 * MCore Options::
14927 * MeP Options::
14928 * MicroBlaze Options::
14929 * MIPS Options::
14930 * MMIX Options::
14931 * MN10300 Options::
14932 * Moxie Options::
14933 * MSP430 Options::
14934 * NDS32 Options::
14935 * Nios II Options::
14936 * Nvidia PTX Options::
14937 * PDP-11 Options::
14938 * picoChip Options::
14939 * PowerPC Options::
14940 * PowerPC SPE Options::
14941 * RISC-V Options::
14942 * RL78 Options::
14943 * RS/6000 and PowerPC Options::
14944 * RX Options::
14945 * S/390 and zSeries Options::
14946 * Score Options::
14947 * SH Options::
14948 * Solaris 2 Options::
14949 * SPARC Options::
14950 * SPU Options::
14951 * System V Options::
14952 * TILE-Gx Options::
14953 * TILEPro Options::
14954 * V850 Options::
14955 * VAX Options::
14956 * Visium Options::
14957 * VMS Options::
14958 * VxWorks Options::
14959 * x86 Options::
14960 * x86 Windows Options::
14961 * Xstormy16 Options::
14962 * Xtensa Options::
14963 * zSeries Options::
14964 @end menu
14966 @node AArch64 Options
14967 @subsection AArch64 Options
14968 @cindex AArch64 Options
14970 These options are defined for AArch64 implementations:
14972 @table @gcctabopt
14974 @item -mabi=@var{name}
14975 @opindex mabi
14976 Generate code for the specified data model.  Permissible values
14977 are @samp{ilp32} for SysV-like data model where int, long int and pointers
14978 are 32 bits, and @samp{lp64} for SysV-like data model where int is 32 bits,
14979 but long int and pointers are 64 bits.
14981 The default depends on the specific target configuration.  Note that
14982 the LP64 and ILP32 ABIs are not link-compatible; you must compile your
14983 entire program with the same ABI, and link with a compatible set of libraries.
14985 @item -mbig-endian
14986 @opindex mbig-endian
14987 Generate big-endian code.  This is the default when GCC is configured for an
14988 @samp{aarch64_be-*-*} target.
14990 @item -mgeneral-regs-only
14991 @opindex mgeneral-regs-only
14992 Generate code which uses only the general-purpose registers.  This will prevent
14993 the compiler from using floating-point and Advanced SIMD registers but will not
14994 impose any restrictions on the assembler.
14996 @item -mlittle-endian
14997 @opindex mlittle-endian
14998 Generate little-endian code.  This is the default when GCC is configured for an
14999 @samp{aarch64-*-*} but not an @samp{aarch64_be-*-*} target.
15001 @item -mcmodel=tiny
15002 @opindex mcmodel=tiny
15003 Generate code for the tiny code model.  The program and its statically defined
15004 symbols must be within 1MB of each other.  Programs can be statically or
15005 dynamically linked.
15007 @item -mcmodel=small
15008 @opindex mcmodel=small
15009 Generate code for the small code model.  The program and its statically defined
15010 symbols must be within 4GB of each other.  Programs can be statically or
15011 dynamically linked.  This is the default code model.
15013 @item -mcmodel=large
15014 @opindex mcmodel=large
15015 Generate code for the large code model.  This makes no assumptions about
15016 addresses and sizes of sections.  Programs can be statically linked only.
15018 @item -mstrict-align
15019 @itemx -mno-strict-align
15020 @opindex mstrict-align
15021 @opindex mno-strict-align
15022 Avoid or allow generating memory accesses that may not be aligned on a natural
15023 object boundary as described in the architecture specification.
15025 @item -momit-leaf-frame-pointer
15026 @itemx -mno-omit-leaf-frame-pointer
15027 @opindex momit-leaf-frame-pointer
15028 @opindex mno-omit-leaf-frame-pointer
15029 Omit or keep the frame pointer in leaf functions.  The former behavior is the
15030 default.
15032 @item -mtls-dialect=desc
15033 @opindex mtls-dialect=desc
15034 Use TLS descriptors as the thread-local storage mechanism for dynamic accesses
15035 of TLS variables.  This is the default.
15037 @item -mtls-dialect=traditional
15038 @opindex mtls-dialect=traditional
15039 Use traditional TLS as the thread-local storage mechanism for dynamic accesses
15040 of TLS variables.
15042 @item -mtls-size=@var{size}
15043 @opindex mtls-size
15044 Specify bit size of immediate TLS offsets.  Valid values are 12, 24, 32, 48.
15045 This option requires binutils 2.26 or newer.
15047 @item -mfix-cortex-a53-835769
15048 @itemx -mno-fix-cortex-a53-835769
15049 @opindex mfix-cortex-a53-835769
15050 @opindex mno-fix-cortex-a53-835769
15051 Enable or disable the workaround for the ARM Cortex-A53 erratum number 835769.
15052 This involves inserting a NOP instruction between memory instructions and
15053 64-bit integer multiply-accumulate instructions.
15055 @item -mfix-cortex-a53-843419
15056 @itemx -mno-fix-cortex-a53-843419
15057 @opindex mfix-cortex-a53-843419
15058 @opindex mno-fix-cortex-a53-843419
15059 Enable or disable the workaround for the ARM Cortex-A53 erratum number 843419.
15060 This erratum workaround is made at link time and this will only pass the
15061 corresponding flag to the linker.
15063 @item -mlow-precision-recip-sqrt
15064 @itemx -mno-low-precision-recip-sqrt
15065 @opindex mlow-precision-recip-sqrt
15066 @opindex mno-low-precision-recip-sqrt
15067 Enable or disable the reciprocal square root approximation.
15068 This option only has an effect if @option{-ffast-math} or
15069 @option{-funsafe-math-optimizations} is used as well.  Enabling this reduces
15070 precision of reciprocal square root results to about 16 bits for
15071 single precision and to 32 bits for double precision.
15073 @item -mlow-precision-sqrt
15074 @itemx -mno-low-precision-sqrt
15075 @opindex -mlow-precision-sqrt
15076 @opindex -mno-low-precision-sqrt
15077 Enable or disable the square root approximation.
15078 This option only has an effect if @option{-ffast-math} or
15079 @option{-funsafe-math-optimizations} is used as well.  Enabling this reduces
15080 precision of square root results to about 16 bits for
15081 single precision and to 32 bits for double precision.
15082 If enabled, it implies @option{-mlow-precision-recip-sqrt}.
15084 @item -mlow-precision-div
15085 @itemx -mno-low-precision-div
15086 @opindex -mlow-precision-div
15087 @opindex -mno-low-precision-div
15088 Enable or disable the division approximation.
15089 This option only has an effect if @option{-ffast-math} or
15090 @option{-funsafe-math-optimizations} is used as well.  Enabling this reduces
15091 precision of division results to about 16 bits for
15092 single precision and to 32 bits for double precision.
15094 @item -mtrack-speculation
15095 @itemx -mno-track-speculation
15096 Enable or disable generation of additional code to track speculative
15097 execution through conditional branches.  The tracking state can then
15098 be used by the compiler when expanding calls to
15099 @code{__builtin_speculation_safe_copy} to permit a more efficient code
15100 sequence to be generated.
15102 @item -march=@var{name}
15103 @opindex march
15104 Specify the name of the target architecture and, optionally, one or
15105 more feature modifiers.  This option has the form
15106 @option{-march=@var{arch}@r{@{}+@r{[}no@r{]}@var{feature}@r{@}*}}.
15108 The permissible values for @var{arch} are @samp{armv8-a},
15109 @samp{armv8.1-a}, @samp{armv8.2-a}, @samp{armv8.3-a} or @samp{armv8.4-a}
15110 or @var{native}.
15112 The value @samp{armv8.4-a} implies @samp{armv8.3-a} and enables compiler
15113 support for the ARMv8.4-A architecture extensions.
15115 The value @samp{armv8.3-a} implies @samp{armv8.2-a} and enables compiler
15116 support for the ARMv8.3-A architecture extensions.
15118 The value @samp{armv8.2-a} implies @samp{armv8.1-a} and enables compiler
15119 support for the ARMv8.2-A architecture extensions.
15121 The value @samp{armv8.1-a} implies @samp{armv8-a} and enables compiler
15122 support for the ARMv8.1-A architecture extension.  In particular, it
15123 enables the @samp{+crc}, @samp{+lse}, and @samp{+rdma} features.
15125 The value @samp{native} is available on native AArch64 GNU/Linux and
15126 causes the compiler to pick the architecture of the host system.  This
15127 option has no effect if the compiler is unable to recognize the
15128 architecture of the host system,
15130 The permissible values for @var{feature} are listed in the sub-section
15131 on @ref{aarch64-feature-modifiers,,@option{-march} and @option{-mcpu}
15132 Feature Modifiers}.  Where conflicting feature modifiers are
15133 specified, the right-most feature is used.
15135 GCC uses @var{name} to determine what kind of instructions it can emit
15136 when generating assembly code.  If @option{-march} is specified
15137 without either of @option{-mtune} or @option{-mcpu} also being
15138 specified, the code is tuned to perform well across a range of target
15139 processors implementing the target architecture.
15141 @item -mtune=@var{name}
15142 @opindex mtune
15143 Specify the name of the target processor for which GCC should tune the
15144 performance of the code.  Permissible values for this option are:
15145 @samp{generic}, @samp{cortex-a35}, @samp{cortex-a53}, @samp{cortex-a55},
15146 @samp{cortex-a57}, @samp{cortex-a72}, @samp{cortex-a73}, @samp{cortex-a75},
15147 @samp{cortex-a76}, @samp{exynos-m1}, @samp{falkor}, @samp{qdf24xx},
15148 @samp{saphira}, @samp{phecda}, @samp{xgene1}, @samp{vulcan}, @samp{thunderx},
15149 @samp{thunderxt88}, @samp{thunderxt88p1}, @samp{thunderxt81},@samp{tsv110},
15150 @samp{thunderxt83}, @samp{thunderx2t99}, @samp{cortex-a57.cortex-a53},
15151 @samp{cortex-a72.cortex-a53}, @samp{cortex-a73.cortex-a35},
15152 @samp{cortex-a73.cortex-a53}, @samp{cortex-a75.cortex-a55},
15153 @samp{cortex-a76.cortex-a55}
15154 @samp{native}.
15156 The values @samp{cortex-a57.cortex-a53}, @samp{cortex-a72.cortex-a53},
15157 @samp{cortex-a73.cortex-a35}, @samp{cortex-a73.cortex-a53},
15158 @samp{cortex-a75.cortex-a55}, @samp{cortex-a76.cortex-a55} specify that GCC
15159 should tune for a big.LITTLE system.
15161 Additionally on native AArch64 GNU/Linux systems the value
15162 @samp{native} tunes performance to the host system.  This option has no effect
15163 if the compiler is unable to recognize the processor of the host system.
15165 Where none of @option{-mtune=}, @option{-mcpu=} or @option{-march=}
15166 are specified, the code is tuned to perform well across a range
15167 of target processors.
15169 This option cannot be suffixed by feature modifiers.
15171 @item -mcpu=@var{name}
15172 @opindex mcpu
15173 Specify the name of the target processor, optionally suffixed by one
15174 or more feature modifiers.  This option has the form
15175 @option{-mcpu=@var{cpu}@r{@{}+@r{[}no@r{]}@var{feature}@r{@}*}}, where
15176 the permissible values for @var{cpu} are the same as those available
15177 for @option{-mtune}.  The permissible values for @var{feature} are
15178 documented in the sub-section on
15179 @ref{aarch64-feature-modifiers,,@option{-march} and @option{-mcpu}
15180 Feature Modifiers}.  Where conflicting feature modifiers are
15181 specified, the right-most feature is used.
15183 GCC uses @var{name} to determine what kind of instructions it can emit when
15184 generating assembly code (as if by @option{-march}) and to determine
15185 the target processor for which to tune for performance (as if
15186 by @option{-mtune}).  Where this option is used in conjunction
15187 with @option{-march} or @option{-mtune}, those options take precedence
15188 over the appropriate part of this option.
15190 @item -moverride=@var{string}
15191 @opindex moverride
15192 Override tuning decisions made by the back-end in response to a
15193 @option{-mtune=} switch.  The syntax, semantics, and accepted values
15194 for @var{string} in this option are not guaranteed to be consistent
15195 across releases.
15197 This option is only intended to be useful when developing GCC.
15199 @item -mverbose-cost-dump
15200 @opindex mverbose-cost-dump
15201 Enable verbose cost model dumping in the debug dump files.  This option is
15202 provided for use in debugging the compiler.
15204 @item -mpc-relative-literal-loads
15205 @itemx -mno-pc-relative-literal-loads
15206 @opindex mpc-relative-literal-loads
15207 @opindex mno-pc-relative-literal-loads
15208 Enable or disable PC-relative literal loads.  With this option literal pools are
15209 accessed using a single instruction and emitted after each function.  This
15210 limits the maximum size of functions to 1MB.  This is enabled by default for
15211 @option{-mcmodel=tiny}.
15213 @item -msign-return-address=@var{scope}
15214 @opindex msign-return-address
15215 Select the function scope on which return address signing will be applied.
15216 Permissible values are @samp{none}, which disables return address signing,
15217 @samp{non-leaf}, which enables pointer signing for functions which are not leaf
15218 functions, and @samp{all}, which enables pointer signing for all functions.  The
15219 default value is @samp{none}.
15221 @item -msve-vector-bits=@var{bits}
15222 @opindex msve-vector-bits
15223 Specify the number of bits in an SVE vector register.  This option only has
15224 an effect when SVE is enabled.
15226 GCC supports two forms of SVE code generation: ``vector-length
15227 agnostic'' output that works with any size of vector register and
15228 ``vector-length specific'' output that only works when the vector
15229 registers are a particular size.  Replacing @var{bits} with
15230 @samp{scalable} selects vector-length agnostic output while
15231 replacing it with a number selects vector-length specific output.
15232 The possible lengths in the latter case are: 128, 256, 512, 1024
15233 and 2048.  @samp{scalable} is the default.
15235 At present, @samp{-msve-vector-bits=128} produces the same output
15236 as @samp{-msve-vector-bits=scalable}.
15238 @end table
15240 @subsubsection @option{-march} and @option{-mcpu} Feature Modifiers
15241 @anchor{aarch64-feature-modifiers}
15242 @cindex @option{-march} feature modifiers
15243 @cindex @option{-mcpu} feature modifiers
15244 Feature modifiers used with @option{-march} and @option{-mcpu} can be any of
15245 the following and their inverses @option{no@var{feature}}:
15247 @table @samp
15248 @item crc
15249 Enable CRC extension.  This is on by default for
15250 @option{-march=armv8.1-a}.
15251 @item crypto
15252 Enable Crypto extension.  This also enables Advanced SIMD and floating-point
15253 instructions.
15254 @item fp
15255 Enable floating-point instructions.  This is on by default for all possible
15256 values for options @option{-march} and @option{-mcpu}.
15257 @item simd
15258 Enable Advanced SIMD instructions.  This also enables floating-point
15259 instructions.  This is on by default for all possible values for options
15260 @option{-march} and @option{-mcpu}.
15261 @item sve
15262 Enable Scalable Vector Extension instructions.  This also enables Advanced
15263 SIMD and floating-point instructions.
15264 @item lse
15265 Enable Large System Extension instructions.  This is on by default for
15266 @option{-march=armv8.1-a}.
15267 @item rdma
15268 Enable Round Double Multiply Accumulate instructions.  This is on by default
15269 for @option{-march=armv8.1-a}.
15270 @item fp16
15271 Enable FP16 extension.  This also enables floating-point instructions.
15272 @item fp16fml
15273 Enable FP16 fmla extension.  This also enables FP16 extensions and
15274 floating-point instructions. This option is enabled by default for @option{-march=armv8.4-a}. Use of this option with architectures prior to Armv8.2-A is not supported.
15276 @item rcpc
15277 Enable the RcPc extension.  This does not change code generation from GCC,
15278 but is passed on to the assembler, enabling inline asm statements to use
15279 instructions from the RcPc extension.
15280 @item dotprod
15281 Enable the Dot Product extension.  This also enables Advanced SIMD instructions.
15282 @item aes
15283 Enable the Armv8-a aes and pmull crypto extension.  This also enables Advanced
15284 SIMD instructions.
15285 @item sha2
15286 Enable the Armv8-a sha2 crypto extension.  This also enables Advanced SIMD instructions.
15287 @item sha3
15288 Enable the sha512 and sha3 crypto extension.  This also enables Advanced SIMD
15289 instructions. Use of this option with architectures prior to Armv8.2-A is not supported.
15290 @item sm4
15291 Enable the sm3 and sm4 crypto extension.  This also enables Advanced SIMD instructions.
15292 Use of this option with architectures prior to Armv8.2-A is not supported.
15293 @item profile
15294 Enable the Statistical Profiling extension.  This option is only to enable the
15295 extension at the assembler level and does not affect code generation.
15297 @end table
15299 Feature @option{crypto} implies @option{aes}, @option{sha2}, and @option{simd},
15300 which implies @option{fp}.
15301 Conversely, @option{nofp} implies @option{nosimd}, which implies
15302 @option{nocrypto}, @option{noaes} and @option{nosha2}.
15304 @node Adapteva Epiphany Options
15305 @subsection Adapteva Epiphany Options
15307 These @samp{-m} options are defined for Adapteva Epiphany:
15309 @table @gcctabopt
15310 @item -mhalf-reg-file
15311 @opindex mhalf-reg-file
15312 Don't allocate any register in the range @code{r32}@dots{}@code{r63}.
15313 That allows code to run on hardware variants that lack these registers.
15315 @item -mprefer-short-insn-regs
15316 @opindex mprefer-short-insn-regs
15317 Preferentially allocate registers that allow short instruction generation.
15318 This can result in increased instruction count, so this may either reduce or
15319 increase overall code size.
15321 @item -mbranch-cost=@var{num}
15322 @opindex mbranch-cost
15323 Set the cost of branches to roughly @var{num} ``simple'' instructions.
15324 This cost is only a heuristic and is not guaranteed to produce
15325 consistent results across releases.
15327 @item -mcmove
15328 @opindex mcmove
15329 Enable the generation of conditional moves.
15331 @item -mnops=@var{num}
15332 @opindex mnops
15333 Emit @var{num} NOPs before every other generated instruction.
15335 @item -mno-soft-cmpsf
15336 @opindex mno-soft-cmpsf
15337 For single-precision floating-point comparisons, emit an @code{fsub} instruction
15338 and test the flags.  This is faster than a software comparison, but can
15339 get incorrect results in the presence of NaNs, or when two different small
15340 numbers are compared such that their difference is calculated as zero.
15341 The default is @option{-msoft-cmpsf}, which uses slower, but IEEE-compliant,
15342 software comparisons.
15344 @item -mstack-offset=@var{num}
15345 @opindex mstack-offset
15346 Set the offset between the top of the stack and the stack pointer.
15347 E.g., a value of 8 means that the eight bytes in the range @code{sp+0@dots{}sp+7}
15348 can be used by leaf functions without stack allocation.
15349 Values other than @samp{8} or @samp{16} are untested and unlikely to work.
15350 Note also that this option changes the ABI; compiling a program with a
15351 different stack offset than the libraries have been compiled with
15352 generally does not work.
15353 This option can be useful if you want to evaluate if a different stack
15354 offset would give you better code, but to actually use a different stack
15355 offset to build working programs, it is recommended to configure the
15356 toolchain with the appropriate @option{--with-stack-offset=@var{num}} option.
15358 @item -mno-round-nearest
15359 @opindex mno-round-nearest
15360 Make the scheduler assume that the rounding mode has been set to
15361 truncating.  The default is @option{-mround-nearest}.
15363 @item -mlong-calls
15364 @opindex mlong-calls
15365 If not otherwise specified by an attribute, assume all calls might be beyond
15366 the offset range of the @code{b} / @code{bl} instructions, and therefore load the
15367 function address into a register before performing a (otherwise direct) call.
15368 This is the default.
15370 @item -mshort-calls
15371 @opindex short-calls
15372 If not otherwise specified by an attribute, assume all direct calls are
15373 in the range of the @code{b} / @code{bl} instructions, so use these instructions
15374 for direct calls.  The default is @option{-mlong-calls}.
15376 @item -msmall16
15377 @opindex msmall16
15378 Assume addresses can be loaded as 16-bit unsigned values.  This does not
15379 apply to function addresses for which @option{-mlong-calls} semantics
15380 are in effect.
15382 @item -mfp-mode=@var{mode}
15383 @opindex mfp-mode
15384 Set the prevailing mode of the floating-point unit.
15385 This determines the floating-point mode that is provided and expected
15386 at function call and return time.  Making this mode match the mode you
15387 predominantly need at function start can make your programs smaller and
15388 faster by avoiding unnecessary mode switches.
15390 @var{mode} can be set to one the following values:
15392 @table @samp
15393 @item caller
15394 Any mode at function entry is valid, and retained or restored when
15395 the function returns, and when it calls other functions.
15396 This mode is useful for compiling libraries or other compilation units
15397 you might want to incorporate into different programs with different
15398 prevailing FPU modes, and the convenience of being able to use a single
15399 object file outweighs the size and speed overhead for any extra
15400 mode switching that might be needed, compared with what would be needed
15401 with a more specific choice of prevailing FPU mode.
15403 @item truncate
15404 This is the mode used for floating-point calculations with
15405 truncating (i.e.@: round towards zero) rounding mode.  That includes
15406 conversion from floating point to integer.
15408 @item round-nearest
15409 This is the mode used for floating-point calculations with
15410 round-to-nearest-or-even rounding mode.
15412 @item int
15413 This is the mode used to perform integer calculations in the FPU, e.g.@:
15414 integer multiply, or integer multiply-and-accumulate.
15415 @end table
15417 The default is @option{-mfp-mode=caller}
15419 @item -mnosplit-lohi
15420 @itemx -mno-postinc
15421 @itemx -mno-postmodify
15422 @opindex mnosplit-lohi
15423 @opindex mno-postinc
15424 @opindex mno-postmodify
15425 Code generation tweaks that disable, respectively, splitting of 32-bit
15426 loads, generation of post-increment addresses, and generation of
15427 post-modify addresses.  The defaults are @option{msplit-lohi},
15428 @option{-mpost-inc}, and @option{-mpost-modify}.
15430 @item -mnovect-double
15431 @opindex mno-vect-double
15432 Change the preferred SIMD mode to SImode.  The default is
15433 @option{-mvect-double}, which uses DImode as preferred SIMD mode.
15435 @item -max-vect-align=@var{num}
15436 @opindex max-vect-align
15437 The maximum alignment for SIMD vector mode types.
15438 @var{num} may be 4 or 8.  The default is 8.
15439 Note that this is an ABI change, even though many library function
15440 interfaces are unaffected if they don't use SIMD vector modes
15441 in places that affect size and/or alignment of relevant types.
15443 @item -msplit-vecmove-early
15444 @opindex msplit-vecmove-early
15445 Split vector moves into single word moves before reload.  In theory this
15446 can give better register allocation, but so far the reverse seems to be
15447 generally the case.
15449 @item -m1reg-@var{reg}
15450 @opindex m1reg-
15451 Specify a register to hold the constant @minus{}1, which makes loading small negative
15452 constants and certain bitmasks faster.
15453 Allowable values for @var{reg} are @samp{r43} and @samp{r63},
15454 which specify use of that register as a fixed register,
15455 and @samp{none}, which means that no register is used for this
15456 purpose.  The default is @option{-m1reg-none}.
15458 @end table
15460 @node ARC Options
15461 @subsection ARC Options
15462 @cindex ARC options
15464 The following options control the architecture variant for which code
15465 is being compiled:
15467 @c architecture variants
15468 @table @gcctabopt
15470 @item -mbarrel-shifter
15471 @opindex mbarrel-shifter
15472 Generate instructions supported by barrel shifter.  This is the default
15473 unless @option{-mcpu=ARC601} or @samp{-mcpu=ARCEM} is in effect.
15475 @item -mjli-always
15476 @opindex mjli-alawys
15477 Force to call a function using jli_s instruction.  This option is
15478 valid only for ARCv2 architecture.
15480 @item -mcpu=@var{cpu}
15481 @opindex mcpu
15482 Set architecture type, register usage, and instruction scheduling
15483 parameters for @var{cpu}.  There are also shortcut alias options
15484 available for backward compatibility and convenience.  Supported
15485 values for @var{cpu} are
15487 @table @samp
15488 @opindex mA6
15489 @opindex mARC600
15490 @item arc600
15491 Compile for ARC600.  Aliases: @option{-mA6}, @option{-mARC600}.
15493 @item arc601
15494 @opindex mARC601
15495 Compile for ARC601.  Alias: @option{-mARC601}.
15497 @item arc700
15498 @opindex mA7
15499 @opindex mARC700
15500 Compile for ARC700.  Aliases: @option{-mA7}, @option{-mARC700}.
15501 This is the default when configured with @option{--with-cpu=arc700}@.
15503 @item arcem
15504 Compile for ARC EM.
15506 @item archs
15507 Compile for ARC HS.
15509 @item em
15510 Compile for ARC EM CPU with no hardware extensions.
15512 @item em4
15513 Compile for ARC EM4 CPU.
15515 @item em4_dmips
15516 Compile for ARC EM4 DMIPS CPU.
15518 @item em4_fpus
15519 Compile for ARC EM4 DMIPS CPU with the single-precision floating-point
15520 extension.
15522 @item em4_fpuda
15523 Compile for ARC EM4 DMIPS CPU with single-precision floating-point and
15524 double assist instructions.
15526 @item hs
15527 Compile for ARC HS CPU with no hardware extensions except the atomic
15528 instructions.
15530 @item hs34
15531 Compile for ARC HS34 CPU.
15533 @item hs38
15534 Compile for ARC HS38 CPU.
15536 @item hs38_linux
15537 Compile for ARC HS38 CPU with all hardware extensions on.
15539 @item arc600_norm
15540 Compile for ARC 600 CPU with @code{norm} instructions enabled.
15542 @item arc600_mul32x16
15543 Compile for ARC 600 CPU with @code{norm} and 32x16-bit multiply 
15544 instructions enabled.
15546 @item arc600_mul64
15547 Compile for ARC 600 CPU with @code{norm} and @code{mul64}-family 
15548 instructions enabled.
15550 @item arc601_norm
15551 Compile for ARC 601 CPU with @code{norm} instructions enabled.
15553 @item arc601_mul32x16
15554 Compile for ARC 601 CPU with @code{norm} and 32x16-bit multiply
15555 instructions enabled.
15557 @item arc601_mul64
15558 Compile for ARC 601 CPU with @code{norm} and @code{mul64}-family
15559 instructions enabled.
15561 @item nps400
15562 Compile for ARC 700 on NPS400 chip.
15564 @item em_mini
15565 Compile for ARC EM minimalist configuration featuring reduced register
15566 set.
15568 @end table
15570 @item -mdpfp
15571 @opindex mdpfp
15572 @itemx -mdpfp-compact
15573 @opindex mdpfp-compact
15574 Generate double-precision FPX instructions, tuned for the compact
15575 implementation.
15577 @item -mdpfp-fast
15578 @opindex mdpfp-fast
15579 Generate double-precision FPX instructions, tuned for the fast
15580 implementation.
15582 @item -mno-dpfp-lrsr
15583 @opindex mno-dpfp-lrsr
15584 Disable @code{lr} and @code{sr} instructions from using FPX extension
15585 aux registers.
15587 @item -mea
15588 @opindex mea
15589 Generate extended arithmetic instructions.  Currently only
15590 @code{divaw}, @code{adds}, @code{subs}, and @code{sat16} are
15591 supported.  This is always enabled for @option{-mcpu=ARC700}.
15593 @item -mno-mpy
15594 @opindex mno-mpy
15595 Do not generate @code{mpy}-family instructions for ARC700.  This option is
15596 deprecated.
15598 @item -mmul32x16
15599 @opindex mmul32x16
15600 Generate 32x16-bit multiply and multiply-accumulate instructions.
15602 @item -mmul64
15603 @opindex mmul64
15604 Generate @code{mul64} and @code{mulu64} instructions.  
15605 Only valid for @option{-mcpu=ARC600}.
15607 @item -mnorm
15608 @opindex mnorm
15609 Generate @code{norm} instructions.  This is the default if @option{-mcpu=ARC700}
15610 is in effect.
15612 @item -mspfp
15613 @opindex mspfp
15614 @itemx -mspfp-compact
15615 @opindex mspfp-compact
15616 Generate single-precision FPX instructions, tuned for the compact
15617 implementation.
15619 @item -mspfp-fast
15620 @opindex mspfp-fast
15621 Generate single-precision FPX instructions, tuned for the fast
15622 implementation.
15624 @item -msimd
15625 @opindex msimd
15626 Enable generation of ARC SIMD instructions via target-specific
15627 builtins.  Only valid for @option{-mcpu=ARC700}.
15629 @item -msoft-float
15630 @opindex msoft-float
15631 This option ignored; it is provided for compatibility purposes only.
15632 Software floating-point code is emitted by default, and this default
15633 can overridden by FPX options; @option{-mspfp}, @option{-mspfp-compact}, or
15634 @option{-mspfp-fast} for single precision, and @option{-mdpfp},
15635 @option{-mdpfp-compact}, or @option{-mdpfp-fast} for double precision.
15637 @item -mswap
15638 @opindex mswap
15639 Generate @code{swap} instructions.
15641 @item -matomic
15642 @opindex matomic
15643 This enables use of the locked load/store conditional extension to implement
15644 atomic memory built-in functions.  Not available for ARC 6xx or ARC
15645 EM cores.
15647 @item -mdiv-rem
15648 @opindex mdiv-rem
15649 Enable @code{div} and @code{rem} instructions for ARCv2 cores.
15651 @item -mcode-density
15652 @opindex mcode-density
15653 Enable code density instructions for ARC EM.  
15654 This option is on by default for ARC HS.
15656 @item -mll64
15657 @opindex mll64
15658 Enable double load/store operations for ARC HS cores.
15660 @item -mtp-regno=@var{regno}
15661 @opindex mtp-regno
15662 Specify thread pointer register number.
15664 @item -mmpy-option=@var{multo}
15665 @opindex mmpy-option
15666 Compile ARCv2 code with a multiplier design option.  You can specify 
15667 the option using either a string or numeric value for @var{multo}.  
15668 @samp{wlh1} is the default value.  The recognized values are:
15670 @table @samp
15671 @item 0
15672 @itemx none
15673 No multiplier available.
15675 @item 1
15676 @itemx w
15677 16x16 multiplier, fully pipelined.
15678 The following instructions are enabled: @code{mpyw} and @code{mpyuw}.
15680 @item 2
15681 @itemx wlh1
15682 32x32 multiplier, fully
15683 pipelined (1 stage).  The following instructions are additionally
15684 enabled: @code{mpy}, @code{mpyu}, @code{mpym}, @code{mpymu}, and @code{mpy_s}.
15686 @item 3
15687 @itemx wlh2
15688 32x32 multiplier, fully pipelined
15689 (2 stages).  The following instructions are additionally enabled: @code{mpy},
15690 @code{mpyu}, @code{mpym}, @code{mpymu}, and @code{mpy_s}.
15692 @item 4
15693 @itemx wlh3
15694 Two 16x16 multipliers, blocking,
15695 sequential.  The following instructions are additionally enabled: @code{mpy},
15696 @code{mpyu}, @code{mpym}, @code{mpymu}, and @code{mpy_s}.
15698 @item 5
15699 @itemx wlh4
15700 One 16x16 multiplier, blocking,
15701 sequential.  The following instructions are additionally enabled: @code{mpy},
15702 @code{mpyu}, @code{mpym}, @code{mpymu}, and @code{mpy_s}.
15704 @item 6
15705 @itemx wlh5
15706 One 32x4 multiplier, blocking,
15707 sequential.  The following instructions are additionally enabled: @code{mpy},
15708 @code{mpyu}, @code{mpym}, @code{mpymu}, and @code{mpy_s}.
15710 @item 7
15711 @itemx plus_dmpy
15712 ARC HS SIMD support.
15714 @item 8
15715 @itemx plus_macd
15716 ARC HS SIMD support.
15718 @item 9
15719 @itemx plus_qmacw
15720 ARC HS SIMD support.
15722 @end table
15724 This option is only available for ARCv2 cores@.
15726 @item -mfpu=@var{fpu}
15727 @opindex mfpu
15728 Enables support for specific floating-point hardware extensions for ARCv2
15729 cores.  Supported values for @var{fpu} are:
15731 @table @samp
15733 @item fpus
15734 Enables support for single-precision floating-point hardware
15735 extensions@.
15737 @item fpud
15738 Enables support for double-precision floating-point hardware
15739 extensions.  The single-precision floating-point extension is also
15740 enabled.  Not available for ARC EM@.
15742 @item fpuda
15743 Enables support for double-precision floating-point hardware
15744 extensions using double-precision assist instructions.  The single-precision
15745 floating-point extension is also enabled.  This option is
15746 only available for ARC EM@.
15748 @item fpuda_div
15749 Enables support for double-precision floating-point hardware
15750 extensions using double-precision assist instructions.
15751 The single-precision floating-point, square-root, and divide 
15752 extensions are also enabled.  This option is
15753 only available for ARC EM@.
15755 @item fpuda_fma
15756 Enables support for double-precision floating-point hardware
15757 extensions using double-precision assist instructions.
15758 The single-precision floating-point and fused multiply and add 
15759 hardware extensions are also enabled.  This option is
15760 only available for ARC EM@.
15762 @item fpuda_all
15763 Enables support for double-precision floating-point hardware
15764 extensions using double-precision assist instructions.
15765 All single-precision floating-point hardware extensions are also
15766 enabled.  This option is only available for ARC EM@.
15768 @item fpus_div
15769 Enables support for single-precision floating-point, square-root and divide 
15770 hardware extensions@.
15772 @item fpud_div
15773 Enables support for double-precision floating-point, square-root and divide 
15774 hardware extensions.  This option
15775 includes option @samp{fpus_div}. Not available for ARC EM@.
15777 @item fpus_fma
15778 Enables support for single-precision floating-point and 
15779 fused multiply and add hardware extensions@.
15781 @item fpud_fma
15782 Enables support for double-precision floating-point and 
15783 fused multiply and add hardware extensions.  This option
15784 includes option @samp{fpus_fma}.  Not available for ARC EM@.
15786 @item fpus_all
15787 Enables support for all single-precision floating-point hardware
15788 extensions@.
15790 @item fpud_all
15791 Enables support for all single- and double-precision floating-point
15792 hardware extensions.  Not available for ARC EM@.
15794 @end table
15796 @item -mirq-ctrl-saved=@var{register-range}, @var{blink}, @var{lp_count}
15797 @opindex mirq-ctrl-saved
15798 Specifies general-purposes registers that the processor automatically
15799 saves/restores on interrupt entry and exit.  @var{register-range} is
15800 specified as two registers separated by a dash.  The register range
15801 always starts with @code{r0}, the upper limit is @code{fp} register.
15802 @var{blink} and @var{lp_count} are optional.  This option is only
15803 valid for ARC EM and ARC HS cores.
15805 @item -mrgf-banked-regs=@var{number}
15806 @opindex mrgf-banked-regs
15807 Specifies the number of registers replicated in second register bank
15808 on entry to fast interrupt.  Fast interrupts are interrupts with the
15809 highest priority level P0.  These interrupts save only PC and STATUS32
15810 registers to avoid memory transactions during interrupt entry and exit
15811 sequences.  Use this option when you are using fast interrupts in an
15812 ARC V2 family processor.  Permitted values are 4, 8, 16, and 32.
15814 @item -mlpc-width=@var{width}
15815 @opindex mlpc-width
15816 Specify the width of the @code{lp_count} register.  Valid values for
15817 @var{width} are 8, 16, 20, 24, 28 and 32 bits.  The default width is
15818 fixed to 32 bits.  If the width is less than 32, the compiler does not
15819 attempt to transform loops in your program to use the zero-delay loop
15820 mechanism unless it is known that the @code{lp_count} register can
15821 hold the required loop-counter value.  Depending on the width
15822 specified, the compiler and run-time library might continue to use the
15823 loop mechanism for various needs.  This option defines macro
15824 @code{__ARC_LPC_WIDTH__} with the value of @var{width}.
15826 @item -mrf16
15827 @opindex mrf16
15828 This option instructs the compiler to generate code for a 16-entry
15829 register file.  This option defines the @code{__ARC_RF16__}
15830 preprocessor macro.
15832 @end table
15834 The following options are passed through to the assembler, and also
15835 define preprocessor macro symbols.
15837 @c Flags used by the assembler, but for which we define preprocessor
15838 @c macro symbols as well.
15839 @table @gcctabopt
15840 @item -mdsp-packa
15841 @opindex mdsp-packa
15842 Passed down to the assembler to enable the DSP Pack A extensions.
15843 Also sets the preprocessor symbol @code{__Xdsp_packa}.  This option is
15844 deprecated.
15846 @item -mdvbf
15847 @opindex mdvbf
15848 Passed down to the assembler to enable the dual Viterbi butterfly
15849 extension.  Also sets the preprocessor symbol @code{__Xdvbf}.  This
15850 option is deprecated.
15852 @c ARC700 4.10 extension instruction
15853 @item -mlock
15854 @opindex mlock
15855 Passed down to the assembler to enable the locked load/store
15856 conditional extension.  Also sets the preprocessor symbol
15857 @code{__Xlock}.
15859 @item -mmac-d16
15860 @opindex mmac-d16
15861 Passed down to the assembler.  Also sets the preprocessor symbol
15862 @code{__Xxmac_d16}.  This option is deprecated.
15864 @item -mmac-24
15865 @opindex mmac-24
15866 Passed down to the assembler.  Also sets the preprocessor symbol
15867 @code{__Xxmac_24}.  This option is deprecated.
15869 @c ARC700 4.10 extension instruction
15870 @item -mrtsc
15871 @opindex mrtsc
15872 Passed down to the assembler to enable the 64-bit time-stamp counter
15873 extension instruction.  Also sets the preprocessor symbol
15874 @code{__Xrtsc}.  This option is deprecated.
15876 @c ARC700 4.10 extension instruction
15877 @item -mswape
15878 @opindex mswape
15879 Passed down to the assembler to enable the swap byte ordering
15880 extension instruction.  Also sets the preprocessor symbol
15881 @code{__Xswape}.
15883 @item -mtelephony
15884 @opindex mtelephony
15885 Passed down to the assembler to enable dual- and single-operand
15886 instructions for telephony.  Also sets the preprocessor symbol
15887 @code{__Xtelephony}.  This option is deprecated.
15889 @item -mxy
15890 @opindex mxy
15891 Passed down to the assembler to enable the XY memory extension.  Also
15892 sets the preprocessor symbol @code{__Xxy}.
15894 @end table
15896 The following options control how the assembly code is annotated:
15898 @c Assembly annotation options
15899 @table @gcctabopt
15900 @item -misize
15901 @opindex misize
15902 Annotate assembler instructions with estimated addresses.
15904 @item -mannotate-align
15905 @opindex mannotate-align
15906 Explain what alignment considerations lead to the decision to make an
15907 instruction short or long.
15909 @end table
15911 The following options are passed through to the linker:
15913 @c options passed through to the linker
15914 @table @gcctabopt
15915 @item -marclinux
15916 @opindex marclinux
15917 Passed through to the linker, to specify use of the @code{arclinux} emulation.
15918 This option is enabled by default in tool chains built for
15919 @w{@code{arc-linux-uclibc}} and @w{@code{arceb-linux-uclibc}} targets
15920 when profiling is not requested.
15922 @item -marclinux_prof
15923 @opindex marclinux_prof
15924 Passed through to the linker, to specify use of the
15925 @code{arclinux_prof} emulation.  This option is enabled by default in
15926 tool chains built for @w{@code{arc-linux-uclibc}} and
15927 @w{@code{arceb-linux-uclibc}} targets when profiling is requested.
15929 @end table
15931 The following options control the semantics of generated code:
15933 @c semantically relevant code generation options
15934 @table @gcctabopt
15935 @item -mlong-calls
15936 @opindex mlong-calls
15937 Generate calls as register indirect calls, thus providing access
15938 to the full 32-bit address range.
15940 @item -mmedium-calls
15941 @opindex mmedium-calls
15942 Don't use less than 25-bit addressing range for calls, which is the
15943 offset available for an unconditional branch-and-link
15944 instruction.  Conditional execution of function calls is suppressed, to
15945 allow use of the 25-bit range, rather than the 21-bit range with
15946 conditional branch-and-link.  This is the default for tool chains built
15947 for @w{@code{arc-linux-uclibc}} and @w{@code{arceb-linux-uclibc}} targets.
15949 @item -G @var{num}
15950 @opindex G
15951 Put definitions of externally-visible data in a small data section if
15952 that data is no bigger than @var{num} bytes.  The default value of
15953 @var{num} is 4 for any ARC configuration, or 8 when we have double
15954 load/store operations.
15956 @item -mno-sdata
15957 @opindex mno-sdata
15958 Do not generate sdata references.  This is the default for tool chains
15959 built for @w{@code{arc-linux-uclibc}} and @w{@code{arceb-linux-uclibc}}
15960 targets.
15962 @item -mvolatile-cache
15963 @opindex mvolatile-cache
15964 Use ordinarily cached memory accesses for volatile references.  This is the
15965 default.
15967 @item -mno-volatile-cache
15968 @opindex mno-volatile-cache
15969 Enable cache bypass for volatile references.
15971 @end table
15973 The following options fine tune code generation:
15974 @c code generation tuning options
15975 @table @gcctabopt
15976 @item -malign-call
15977 @opindex malign-call
15978 Do alignment optimizations for call instructions.
15980 @item -mauto-modify-reg
15981 @opindex mauto-modify-reg
15982 Enable the use of pre/post modify with register displacement.
15984 @item -mbbit-peephole
15985 @opindex mbbit-peephole
15986 Enable bbit peephole2.
15988 @item -mno-brcc
15989 @opindex mno-brcc
15990 This option disables a target-specific pass in @file{arc_reorg} to
15991 generate compare-and-branch (@code{br@var{cc}}) instructions.  
15992 It has no effect on
15993 generation of these instructions driven by the combiner pass.
15995 @item -mcase-vector-pcrel
15996 @opindex mcase-vector-pcrel
15997 Use PC-relative switch case tables to enable case table shortening.
15998 This is the default for @option{-Os}.
16000 @item -mcompact-casesi
16001 @opindex mcompact-casesi
16002 Enable compact @code{casesi} pattern.  This is the default for @option{-Os},
16003 and only available for ARCv1 cores.
16005 @item -mno-cond-exec
16006 @opindex mno-cond-exec
16007 Disable the ARCompact-specific pass to generate conditional 
16008 execution instructions.
16010 Due to delay slot scheduling and interactions between operand numbers,
16011 literal sizes, instruction lengths, and the support for conditional execution,
16012 the target-independent pass to generate conditional execution is often lacking,
16013 so the ARC port has kept a special pass around that tries to find more
16014 conditional execution generation opportunities after register allocation,
16015 branch shortening, and delay slot scheduling have been done.  This pass
16016 generally, but not always, improves performance and code size, at the cost of
16017 extra compilation time, which is why there is an option to switch it off.
16018 If you have a problem with call instructions exceeding their allowable
16019 offset range because they are conditionalized, you should consider using
16020 @option{-mmedium-calls} instead.
16022 @item -mearly-cbranchsi
16023 @opindex mearly-cbranchsi
16024 Enable pre-reload use of the @code{cbranchsi} pattern.
16026 @item -mexpand-adddi
16027 @opindex mexpand-adddi
16028 Expand @code{adddi3} and @code{subdi3} at RTL generation time into
16029 @code{add.f}, @code{adc} etc.  This option is deprecated.
16031 @item -mindexed-loads
16032 @opindex mindexed-loads
16033 Enable the use of indexed loads.  This can be problematic because some
16034 optimizers then assume that indexed stores exist, which is not
16035 the case.
16037 @item -mlra
16038 @opindex mlra
16039 Enable Local Register Allocation.  This is still experimental for ARC,
16040 so by default the compiler uses standard reload
16041 (i.e. @option{-mno-lra}).
16043 @item -mlra-priority-none
16044 @opindex mlra-priority-none
16045 Don't indicate any priority for target registers.
16047 @item -mlra-priority-compact
16048 @opindex mlra-priority-compact
16049 Indicate target register priority for r0..r3 / r12..r15.
16051 @item -mlra-priority-noncompact
16052 @opindex mlra-priority-noncompact
16053 Reduce target register priority for r0..r3 / r12..r15.
16055 @item -mno-millicode
16056 @opindex mno-millicode
16057 When optimizing for size (using @option{-Os}), prologues and epilogues
16058 that have to save or restore a large number of registers are often
16059 shortened by using call to a special function in libgcc; this is
16060 referred to as a @emph{millicode} call.  As these calls can pose
16061 performance issues, and/or cause linking issues when linking in a
16062 nonstandard way, this option is provided to turn off millicode call
16063 generation.
16065 @item -mmixed-code
16066 @opindex mmixed-code
16067 Tweak register allocation to help 16-bit instruction generation.
16068 This generally has the effect of decreasing the average instruction size
16069 while increasing the instruction count.
16071 @item -mq-class
16072 @opindex mq-class
16073 Enable @samp{q} instruction alternatives.
16074 This is the default for @option{-Os}.
16076 @item -mRcq
16077 @opindex mRcq
16078 Enable @samp{Rcq} constraint handling.  
16079 Most short code generation depends on this.
16080 This is the default.
16082 @item -mRcw
16083 @opindex mRcw
16084 Enable @samp{Rcw} constraint handling.  
16085 Most ccfsm condexec mostly depends on this.
16086 This is the default.
16088 @item -msize-level=@var{level}
16089 @opindex msize-level
16090 Fine-tune size optimization with regards to instruction lengths and alignment.
16091 The recognized values for @var{level} are:
16092 @table @samp
16093 @item 0
16094 No size optimization.  This level is deprecated and treated like @samp{1}.
16096 @item 1
16097 Short instructions are used opportunistically.
16099 @item 2
16100 In addition, alignment of loops and of code after barriers are dropped.
16102 @item 3
16103 In addition, optional data alignment is dropped, and the option @option{Os} is enabled.
16105 @end table
16107 This defaults to @samp{3} when @option{-Os} is in effect.  Otherwise,
16108 the behavior when this is not set is equivalent to level @samp{1}.
16110 @item -mtune=@var{cpu}
16111 @opindex mtune
16112 Set instruction scheduling parameters for @var{cpu}, overriding any implied
16113 by @option{-mcpu=}.
16115 Supported values for @var{cpu} are
16117 @table @samp
16118 @item ARC600
16119 Tune for ARC600 CPU.
16121 @item ARC601
16122 Tune for ARC601 CPU.
16124 @item ARC700
16125 Tune for ARC700 CPU with standard multiplier block.
16127 @item ARC700-xmac
16128 Tune for ARC700 CPU with XMAC block.
16130 @item ARC725D
16131 Tune for ARC725D CPU.
16133 @item ARC750D
16134 Tune for ARC750D CPU.
16136 @end table
16138 @item -mmultcost=@var{num}
16139 @opindex mmultcost
16140 Cost to assume for a multiply instruction, with @samp{4} being equal to a
16141 normal instruction.
16143 @item -munalign-prob-threshold=@var{probability}
16144 @opindex munalign-prob-threshold
16145 Set probability threshold for unaligning branches.
16146 When tuning for @samp{ARC700} and optimizing for speed, branches without
16147 filled delay slot are preferably emitted unaligned and long, unless
16148 profiling indicates that the probability for the branch to be taken
16149 is below @var{probability}.  @xref{Cross-profiling}.
16150 The default is (REG_BR_PROB_BASE/2), i.e.@: 5000.
16152 @end table
16154 The following options are maintained for backward compatibility, but
16155 are now deprecated and will be removed in a future release:
16157 @c Deprecated options
16158 @table @gcctabopt
16160 @item -margonaut
16161 @opindex margonaut
16162 Obsolete FPX.
16164 @item -mbig-endian
16165 @opindex mbig-endian
16166 @itemx -EB
16167 @opindex EB
16168 Compile code for big-endian targets.  Use of these options is now
16169 deprecated.  Big-endian code is supported by configuring GCC to build
16170 @w{@code{arceb-elf32}} and @w{@code{arceb-linux-uclibc}} targets,
16171 for which big endian is the default.
16173 @item -mlittle-endian
16174 @opindex mlittle-endian
16175 @itemx -EL
16176 @opindex EL
16177 Compile code for little-endian targets.  Use of these options is now
16178 deprecated.  Little-endian code is supported by configuring GCC to build 
16179 @w{@code{arc-elf32}} and @w{@code{arc-linux-uclibc}} targets,
16180 for which little endian is the default.
16182 @item -mbarrel_shifter
16183 @opindex mbarrel_shifter
16184 Replaced by @option{-mbarrel-shifter}.
16186 @item -mdpfp_compact
16187 @opindex mdpfp_compact
16188 Replaced by @option{-mdpfp-compact}.
16190 @item -mdpfp_fast
16191 @opindex mdpfp_fast
16192 Replaced by @option{-mdpfp-fast}.
16194 @item -mdsp_packa
16195 @opindex mdsp_packa
16196 Replaced by @option{-mdsp-packa}.
16198 @item -mEA
16199 @opindex mEA
16200 Replaced by @option{-mea}.
16202 @item -mmac_24
16203 @opindex mmac_24
16204 Replaced by @option{-mmac-24}.
16206 @item -mmac_d16
16207 @opindex mmac_d16
16208 Replaced by @option{-mmac-d16}.
16210 @item -mspfp_compact
16211 @opindex mspfp_compact
16212 Replaced by @option{-mspfp-compact}.
16214 @item -mspfp_fast
16215 @opindex mspfp_fast
16216 Replaced by @option{-mspfp-fast}.
16218 @item -mtune=@var{cpu}
16219 @opindex mtune
16220 Values @samp{arc600}, @samp{arc601}, @samp{arc700} and
16221 @samp{arc700-xmac} for @var{cpu} are replaced by @samp{ARC600},
16222 @samp{ARC601}, @samp{ARC700} and @samp{ARC700-xmac} respectively.
16224 @item -multcost=@var{num}
16225 @opindex multcost
16226 Replaced by @option{-mmultcost}.
16228 @end table
16230 @node ARM Options
16231 @subsection ARM Options
16232 @cindex ARM options
16234 These @samp{-m} options are defined for the ARM port:
16236 @table @gcctabopt
16237 @item -mabi=@var{name}
16238 @opindex mabi
16239 Generate code for the specified ABI@.  Permissible values are: @samp{apcs-gnu},
16240 @samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.
16242 @item -mapcs-frame
16243 @opindex mapcs-frame
16244 Generate a stack frame that is compliant with the ARM Procedure Call
16245 Standard for all functions, even if this is not strictly necessary for
16246 correct execution of the code.  Specifying @option{-fomit-frame-pointer}
16247 with this option causes the stack frames not to be generated for
16248 leaf functions.  The default is @option{-mno-apcs-frame}.
16249 This option is deprecated.
16251 @item -mapcs
16252 @opindex mapcs
16253 This is a synonym for @option{-mapcs-frame} and is deprecated.
16255 @ignore
16256 @c not currently implemented
16257 @item -mapcs-stack-check
16258 @opindex mapcs-stack-check
16259 Generate code to check the amount of stack space available upon entry to
16260 every function (that actually uses some stack space).  If there is
16261 insufficient space available then either the function
16262 @code{__rt_stkovf_split_small} or @code{__rt_stkovf_split_big} is
16263 called, depending upon the amount of stack space required.  The runtime
16264 system is required to provide these functions.  The default is
16265 @option{-mno-apcs-stack-check}, since this produces smaller code.
16267 @c not currently implemented
16268 @item -mapcs-reentrant
16269 @opindex mapcs-reentrant
16270 Generate reentrant, position-independent code.  The default is
16271 @option{-mno-apcs-reentrant}.
16272 @end ignore
16274 @item -mthumb-interwork
16275 @opindex mthumb-interwork
16276 Generate code that supports calling between the ARM and Thumb
16277 instruction sets.  Without this option, on pre-v5 architectures, the
16278 two instruction sets cannot be reliably used inside one program.  The
16279 default is @option{-mno-thumb-interwork}, since slightly larger code
16280 is generated when @option{-mthumb-interwork} is specified.  In AAPCS
16281 configurations this option is meaningless.
16283 @item -mno-sched-prolog
16284 @opindex mno-sched-prolog
16285 Prevent the reordering of instructions in the function prologue, or the
16286 merging of those instruction with the instructions in the function's
16287 body.  This means that all functions start with a recognizable set
16288 of instructions (or in fact one of a choice from a small set of
16289 different function prologues), and this information can be used to
16290 locate the start of functions inside an executable piece of code.  The
16291 default is @option{-msched-prolog}.
16293 @item -mfloat-abi=@var{name}
16294 @opindex mfloat-abi
16295 Specifies which floating-point ABI to use.  Permissible values
16296 are: @samp{soft}, @samp{softfp} and @samp{hard}.
16298 Specifying @samp{soft} causes GCC to generate output containing
16299 library calls for floating-point operations.
16300 @samp{softfp} allows the generation of code using hardware floating-point
16301 instructions, but still uses the soft-float calling conventions.
16302 @samp{hard} allows generation of floating-point instructions
16303 and uses FPU-specific calling conventions.
16305 The default depends on the specific target configuration.  Note that
16306 the hard-float and soft-float ABIs are not link-compatible; you must
16307 compile your entire program with the same ABI, and link with a
16308 compatible set of libraries.
16310 @item -mlittle-endian
16311 @opindex mlittle-endian
16312 Generate code for a processor running in little-endian mode.  This is
16313 the default for all standard configurations.
16315 @item -mbig-endian
16316 @opindex mbig-endian
16317 Generate code for a processor running in big-endian mode; the default is
16318 to compile code for a little-endian processor.
16320 @item -mbe8
16321 @itemx -mbe32
16322 @opindex mbe8
16323 When linking a big-endian image select between BE8 and BE32 formats.
16324 The option has no effect for little-endian images and is ignored.  The
16325 default is dependent on the selected target architecture.  For ARMv6
16326 and later architectures the default is BE8, for older architectures
16327 the default is BE32.  BE32 format has been deprecated by ARM.
16329 @item -march=@var{name}@r{[}+extension@dots{}@r{]}
16330 @opindex march
16331 This specifies the name of the target ARM architecture.  GCC uses this
16332 name to determine what kind of instructions it can emit when generating
16333 assembly code.  This option can be used in conjunction with or instead
16334 of the @option{-mcpu=} option.
16336 Permissible names are:
16337 @samp{armv4t},
16338 @samp{armv5t}, @samp{armv5te},
16339 @samp{armv6}, @samp{armv6j}, @samp{armv6k}, @samp{armv6kz}, @samp{armv6t2},
16340 @samp{armv6z}, @samp{armv6zk},
16341 @samp{armv7}, @samp{armv7-a}, @samp{armv7ve}, 
16342 @samp{armv8-a}, @samp{armv8.1-a}, @samp{armv8.2-a}, @samp{armv8.3-a},
16343 @samp{armv8.4-a},
16344 @samp{armv7-r},
16345 @samp{armv8-r},
16346 @samp{armv6-m}, @samp{armv6s-m},
16347 @samp{armv7-m}, @samp{armv7e-m},
16348 @samp{armv8-m.base}, @samp{armv8-m.main},
16349 @samp{iwmmxt} and @samp{iwmmxt2}.
16351 Additionally, the following architectures, which lack support for the
16352 Thumb execution state, are recognized but support is deprecated: @samp{armv4}.
16354 Many of the architectures support extensions.  These can be added by
16355 appending @samp{+@var{extension}} to the architecture name.  Extension
16356 options are processed in order and capabilities accumulate.  An extension
16357 will also enable any necessary base extensions
16358 upon which it depends.  For example, the @samp{+crypto} extension
16359 will always enable the @samp{+simd} extension.  The exception to the
16360 additive construction is for extensions that are prefixed with
16361 @samp{+no@dots{}}: these extensions disable the specified option and
16362 any other extensions that may depend on the presence of that
16363 extension.
16365 For example, @samp{-march=armv7-a+simd+nofp+vfpv4} is equivalent to
16366 writing @samp{-march=armv7-a+vfpv4} since the @samp{+simd} option is
16367 entirely disabled by the @samp{+nofp} option that follows it.
16369 Most extension names are generically named, but have an effect that is
16370 dependent upon the architecture to which it is applied.  For example,
16371 the @samp{+simd} option can be applied to both @samp{armv7-a} and
16372 @samp{armv8-a} architectures, but will enable the original ARMv7-A
16373 Advanced SIMD (Neon) extensions for @samp{armv7-a} and the ARMv8-A
16374 variant for @samp{armv8-a}.
16376 The table below lists the supported extensions for each architecture.
16377 Architectures not mentioned do not support any extensions.
16379 @table @samp
16380 @item armv5te
16381 @itemx armv6
16382 @itemx armv6j
16383 @itemx armv6k
16384 @itemx armv6kz
16385 @itemx armv6t2
16386 @itemx armv6z
16387 @itemx armv6zk
16388 @table @samp
16389 @item +fp
16390 The VFPv2 floating-point instructions.  The extension @samp{+vfpv2} can be
16391 used as an alias for this extension.
16393 @item +nofp
16394 Disable the floating-point instructions.
16395 @end table
16397 @item armv7
16398 The common subset of the ARMv7-A, ARMv7-R and ARMv7-M architectures.
16399 @table @samp
16400 @item +fp
16401 The VFPv3 floating-point instructions, with 16 double-precision
16402 registers.  The extension @samp{+vfpv3-d16} can be used as an alias
16403 for this extension.  Note that floating-point is not supported by the
16404 base ARMv7-M architecture, but is compatible with both the ARMv7-A and
16405 ARMv7-R architectures.
16407 @item +nofp
16408 Disable the floating-point instructions.
16409 @end table
16411 @item armv7-a
16412 @table @samp
16413 @item +fp
16414 The VFPv3 floating-point instructions, with 16 double-precision
16415 registers.  The extension @samp{+vfpv3-d16} can be used as an alias
16416 for this extension.
16418 @item +simd
16419 The Advanced SIMD (Neon) v1 and the VFPv3 floating-point instructions.
16420 The extensions @samp{+neon} and @samp{+neon-vfpv3} can be used as aliases
16421 for this extension.
16423 @item +vfpv3
16424 The VFPv3 floating-point instructions, with 32 double-precision
16425 registers.
16427 @item +vfpv3-d16-fp16
16428 The VFPv3 floating-point instructions, with 16 double-precision
16429 registers and the half-precision floating-point conversion operations.
16431 @item +vfpv3-fp16
16432 The VFPv3 floating-point instructions, with 32 double-precision
16433 registers and the half-precision floating-point conversion operations.
16435 @item +vfpv4-d16
16436 The VFPv4 floating-point instructions, with 16 double-precision
16437 registers.
16439 @item +vfpv4
16440 The VFPv4 floating-point instructions, with 32 double-precision
16441 registers.
16443 @item +neon-fp16
16444 The Advanced SIMD (Neon) v1 and the VFPv3 floating-point instructions, with
16445 the half-precision floating-point conversion operations.
16447 @item +neon-vfpv4
16448 The Advanced SIMD (Neon) v2 and the VFPv4 floating-point instructions.
16450 @item +nosimd
16451 Disable the Advanced SIMD instructions (does not disable floating point).
16453 @item +nofp
16454 Disable the floating-point and Advanced SIMD instructions.
16455 @end table
16457 @item armv7ve
16458 The extended version of the ARMv7-A architecture with support for
16459 virtualization.
16460 @table @samp
16461 @item +fp
16462 The VFPv4 floating-point instructions, with 16 double-precision registers.
16463 The extension @samp{+vfpv4-d16} can be used as an alias for this extension.
16465 @item +simd
16466 The Advanced SIMD (Neon) v2 and the VFPv4 floating-point instructions.  The
16467 extension @samp{+neon-vfpv4} can be used as an alias for this extension.
16469 @item +vfpv3-d16
16470 The VFPv3 floating-point instructions, with 16 double-precision
16471 registers.
16473 @item +vfpv3
16474 The VFPv3 floating-point instructions, with 32 double-precision
16475 registers.
16477 @item +vfpv3-d16-fp16
16478 The VFPv3 floating-point instructions, with 16 double-precision
16479 registers and the half-precision floating-point conversion operations.
16481 @item +vfpv3-fp16
16482 The VFPv3 floating-point instructions, with 32 double-precision
16483 registers and the half-precision floating-point conversion operations.
16485 @item +vfpv4-d16
16486 The VFPv4 floating-point instructions, with 16 double-precision
16487 registers.
16489 @item +vfpv4
16490 The VFPv4 floating-point instructions, with 32 double-precision
16491 registers.
16493 @item +neon
16494 The Advanced SIMD (Neon) v1 and the VFPv3 floating-point instructions.
16495 The extension @samp{+neon-vfpv3} can be used as an alias for this extension.
16497 @item +neon-fp16
16498 The Advanced SIMD (Neon) v1 and the VFPv3 floating-point instructions, with
16499 the half-precision floating-point conversion operations.
16501 @item +nosimd
16502 Disable the Advanced SIMD instructions (does not disable floating point).
16504 @item +nofp
16505 Disable the floating-point and Advanced SIMD instructions.
16506 @end table
16508 @item armv8-a
16509 @table @samp
16510 @item +crc
16511 The Cyclic Redundancy Check (CRC) instructions.
16512 @item +simd
16513 The ARMv8-A Advanced SIMD and floating-point instructions.
16514 @item +crypto
16515 The cryptographic instructions.
16516 @item +nocrypto
16517 Disable the cryptographic instructions.
16518 @item +nofp
16519 Disable the floating-point, Advanced SIMD and cryptographic instructions.
16520 @end table
16522 @item armv8.1-a
16523 @table @samp
16524 @item +simd
16525 The ARMv8.1-A Advanced SIMD and floating-point instructions.
16527 @item +crypto
16528 The cryptographic instructions.  This also enables the Advanced SIMD and
16529 floating-point instructions.
16531 @item +nocrypto
16532 Disable the cryptographic instructions.
16534 @item +nofp
16535 Disable the floating-point, Advanced SIMD and cryptographic instructions.
16536 @end table
16538 @item armv8.2-a
16539 @itemx armv8.3-a
16540 @table @samp
16541 @item +fp16
16542 The half-precision floating-point data processing instructions.
16543 This also enables the Advanced SIMD and floating-point instructions.
16545 @item +fp16fml
16546 The half-precision floating-point fmla extension.  This also enables
16547 the half-precision floating-point extension and Advanced SIMD and
16548 floating-point instructions.
16550 @item +simd
16551 The ARMv8.1-A Advanced SIMD and floating-point instructions.
16553 @item +crypto
16554 The cryptographic instructions.  This also enables the Advanced SIMD and
16555 floating-point instructions.
16557 @item +dotprod
16558 Enable the Dot Product extension.  This also enables Advanced SIMD instructions.
16560 @item +nocrypto
16561 Disable the cryptographic extension.
16563 @item +nofp
16564 Disable the floating-point, Advanced SIMD and cryptographic instructions.
16565 @end table
16567 @item armv8.4-a
16568 @table @samp
16569 @item +fp16
16570 The half-precision floating-point data processing instructions.
16571 This also enables the Advanced SIMD and floating-point instructions as well
16572 as the Dot Product extension and the half-precision floating-point fmla
16573 extension.
16575 @item +simd
16576 The ARMv8.3-A Advanced SIMD and floating-point instructions as well as the
16577 Dot Product extension.
16579 @item +crypto
16580 The cryptographic instructions.  This also enables the Advanced SIMD and
16581 floating-point instructions as well as the Dot Product extension.
16583 @item +nocrypto
16584 Disable the cryptographic extension.
16586 @item +nofp
16587 Disable the floating-point, Advanced SIMD and cryptographic instructions.
16588 @end table
16590 @item armv7-r
16591 @table @samp
16592 @item +fp.sp
16593 The single-precision VFPv3 floating-point instructions.  The extension
16594 @samp{+vfpv3xd} can be used as an alias for this extension.
16596 @item +fp
16597 The VFPv3 floating-point instructions with 16 double-precision registers.
16598 The extension +vfpv3-d16 can be used as an alias for this extension.
16600 @item +nofp
16601 Disable the floating-point extension.
16603 @item +idiv
16604 The ARM-state integer division instructions.
16606 @item +noidiv
16607 Disable the ARM-state integer division extension.
16608 @end table
16610 @item armv7e-m
16611 @table @samp
16612 @item +fp
16613 The single-precision VFPv4 floating-point instructions.
16615 @item +fpv5
16616 The single-precision FPv5 floating-point instructions.
16618 @item +fp.dp
16619 The single- and double-precision FPv5 floating-point instructions.
16621 @item +nofp
16622 Disable the floating-point extensions.
16623 @end table
16625 @item  armv8-m.main
16626 @table @samp
16627 @item +dsp
16628 The DSP instructions.
16630 @item +nodsp
16631 Disable the DSP extension.
16633 @item +fp
16634 The single-precision floating-point instructions.
16636 @item +fp.dp
16637 The single- and double-precision floating-point instructions.
16639 @item +nofp
16640 Disable the floating-point extension.
16641 @end table
16643 @item armv8-r
16644 @table @samp
16645 @item +crc
16646 The Cyclic Redundancy Check (CRC) instructions.
16647 @item +fp.sp
16648 The single-precision FPv5 floating-point instructions.
16649 @item +simd
16650 The ARMv8-A Advanced SIMD and floating-point instructions.
16651 @item +crypto
16652 The cryptographic instructions.
16653 @item +nocrypto
16654 Disable the cryptographic instructions.
16655 @item +nofp
16656 Disable the floating-point, Advanced SIMD and cryptographic instructions.
16657 @end table
16659 @end table
16661 @option{-march=native} causes the compiler to auto-detect the architecture
16662 of the build computer.  At present, this feature is only supported on
16663 GNU/Linux, and not all architectures are recognized.  If the auto-detect
16664 is unsuccessful the option has no effect.
16666 @item -mtune=@var{name}
16667 @opindex mtune
16668 This option specifies the name of the target ARM processor for
16669 which GCC should tune the performance of the code.
16670 For some ARM implementations better performance can be obtained by using
16671 this option.
16672 Permissible names are: @samp{arm2}, @samp{arm250},
16673 @samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
16674 @samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
16675 @samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
16676 @samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
16677 @samp{arm720},
16678 @samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},
16679 @samp{arm710t}, @samp{arm720t}, @samp{arm740t},
16680 @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
16681 @samp{strongarm1110},
16682 @samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
16683 @samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},
16684 @samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},
16685 @samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},
16686 @samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
16687 @samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
16688 @samp{arm1156t2-s}, @samp{arm1156t2f-s}, @samp{arm1176jz-s}, @samp{arm1176jzf-s},
16689 @samp{generic-armv7-a}, @samp{cortex-a5}, @samp{cortex-a7}, @samp{cortex-a8},
16690 @samp{cortex-a9}, @samp{cortex-a12}, @samp{cortex-a15}, @samp{cortex-a17},
16691 @samp{cortex-a32}, @samp{cortex-a35}, @samp{cortex-a53}, @samp{cortex-a55},
16692 @samp{cortex-a57}, @samp{cortex-a72}, @samp{cortex-a73}, @samp{cortex-a75},
16693 @samp{cortex-a76}, @samp{cortex-r4}, @samp{cortex-r4f}, @samp{cortex-r5},
16694 @samp{cortex-r7}, @samp{cortex-r8}, @samp{cortex-r52},
16695 @samp{cortex-m33},
16696 @samp{cortex-m23},
16697 @samp{cortex-m7},
16698 @samp{cortex-m4},
16699 @samp{cortex-m3},
16700 @samp{cortex-m1},
16701 @samp{cortex-m0},
16702 @samp{cortex-m0plus},
16703 @samp{cortex-m1.small-multiply},
16704 @samp{cortex-m0.small-multiply},
16705 @samp{cortex-m0plus.small-multiply},
16706 @samp{exynos-m1},
16707 @samp{marvell-pj4},
16708 @samp{xscale}, @samp{iwmmxt}, @samp{iwmmxt2}, @samp{ep9312},
16709 @samp{fa526}, @samp{fa626},
16710 @samp{fa606te}, @samp{fa626te}, @samp{fmp626}, @samp{fa726te},
16711 @samp{xgene1}.
16713 Additionally, this option can specify that GCC should tune the performance
16714 of the code for a big.LITTLE system.  Permissible names are:
16715 @samp{cortex-a15.cortex-a7}, @samp{cortex-a17.cortex-a7},
16716 @samp{cortex-a57.cortex-a53}, @samp{cortex-a72.cortex-a53},
16717 @samp{cortex-a72.cortex-a35}, @samp{cortex-a73.cortex-a53},
16718 @samp{cortex-a75.cortex-a55}, @samp{cortex-a76.cortex-a55}.
16720 @option{-mtune=generic-@var{arch}} specifies that GCC should tune the
16721 performance for a blend of processors within architecture @var{arch}.
16722 The aim is to generate code that run well on the current most popular
16723 processors, balancing between optimizations that benefit some CPUs in the
16724 range, and avoiding performance pitfalls of other CPUs.  The effects of
16725 this option may change in future GCC versions as CPU models come and go.
16727 @option{-mtune} permits the same extension options as @option{-mcpu}, but
16728 the extension options do not affect the tuning of the generated code.
16730 @option{-mtune=native} causes the compiler to auto-detect the CPU
16731 of the build computer.  At present, this feature is only supported on
16732 GNU/Linux, and not all architectures are recognized.  If the auto-detect is
16733 unsuccessful the option has no effect.
16735 @item -mcpu=@var{name}@r{[}+extension@dots{}@r{]}
16736 @opindex mcpu
16737 This specifies the name of the target ARM processor.  GCC uses this name
16738 to derive the name of the target ARM architecture (as if specified
16739 by @option{-march}) and the ARM processor type for which to tune for
16740 performance (as if specified by @option{-mtune}).  Where this option
16741 is used in conjunction with @option{-march} or @option{-mtune},
16742 those options take precedence over the appropriate part of this option.
16744 Many of the supported CPUs implement optional architectural
16745 extensions.  Where this is so the architectural extensions are
16746 normally enabled by default.  If implementations that lack the
16747 extension exist, then the extension syntax can be used to disable
16748 those extensions that have been omitted.  For floating-point and
16749 Advanced SIMD (Neon) instructions, the settings of the options
16750 @option{-mfloat-abi} and @option{-mfpu} must also be considered:
16751 floating-point and Advanced SIMD instructions will only be used if
16752 @option{-mfloat-abi} is not set to @samp{soft}; and any setting of
16753 @option{-mfpu} other than @samp{auto} will override the available
16754 floating-point and SIMD extension instructions.
16756 For example, @samp{cortex-a9} can be found in three major
16757 configurations: integer only, with just a floating-point unit or with
16758 floating-point and Advanced SIMD.  The default is to enable all the
16759 instructions, but the extensions @samp{+nosimd} and @samp{+nofp} can
16760 be used to disable just the SIMD or both the SIMD and floating-point
16761 instructions respectively.
16763 Permissible names for this option are the same as those for
16764 @option{-mtune}.
16766 The following extension options are common to the listed CPUs:
16768 @table @samp
16769 @item +nodsp
16770 Disable the DSP instructions on @samp{cortex-m33}.
16772 @item  +nofp
16773 Disables the floating-point instructions on @samp{arm9e},
16774 @samp{arm946e-s}, @samp{arm966e-s}, @samp{arm968e-s}, @samp{arm10e},
16775 @samp{arm1020e}, @samp{arm1022e}, @samp{arm926ej-s},
16776 @samp{arm1026ej-s}, @samp{cortex-r5}, @samp{cortex-r7}, @samp{cortex-r8},
16777 @samp{cortex-m4}, @samp{cortex-m7} and @samp{cortex-m33}.
16778 Disables the floating-point and SIMD instructions on
16779 @samp{generic-armv7-a}, @samp{cortex-a5}, @samp{cortex-a7},
16780 @samp{cortex-a8}, @samp{cortex-a9}, @samp{cortex-a12},
16781 @samp{cortex-a15}, @samp{cortex-a17}, @samp{cortex-a15.cortex-a7},
16782 @samp{cortex-a17.cortex-a7}, @samp{cortex-a32}, @samp{cortex-a35},
16783 @samp{cortex-a53} and @samp{cortex-a55}.
16785 @item +nofp.dp
16786 Disables the double-precision component of the floating-point instructions
16787 on @samp{cortex-r5}, @samp{cortex-r52} and @samp{cortex-m7}.
16789 @item +nosimd
16790 Disables the SIMD (but not floating-point) instructions on
16791 @samp{generic-armv7-a}, @samp{cortex-a5}, @samp{cortex-a7}
16792 and @samp{cortex-a9}.
16794 @item +crypto
16795 Enables the cryptographic instructions on @samp{cortex-a32},
16796 @samp{cortex-a35}, @samp{cortex-a53}, @samp{cortex-a55}, @samp{cortex-a57},
16797 @samp{cortex-a72}, @samp{cortex-a73}, @samp{cortex-a75}, @samp{exynos-m1},
16798 @samp{xgene1}, @samp{cortex-a57.cortex-a53}, @samp{cortex-a72.cortex-a53},
16799 @samp{cortex-a73.cortex-a35}, @samp{cortex-a73.cortex-a53} and
16800 @samp{cortex-a75.cortex-a55}.
16801 @end table
16803 Additionally the @samp{generic-armv7-a} pseudo target defaults to
16804 VFPv3 with 16 double-precision registers.  It supports the following
16805 extension options: @samp{vfpv3-d16}, @samp{vfpv3},
16806 @samp{vfpv3-d16-fp16}, @samp{vfpv3-fp16}, @samp{vfpv4-d16},
16807 @samp{vfpv4}, @samp{neon}, @samp{neon-vfpv3}, @samp{neon-fp16},
16808 @samp{neon-vfpv4}.  The meanings are the same as for the extensions to
16809 @option{-march=armv7-a}.
16811 @option{-mcpu=generic-@var{arch}} is also permissible, and is
16812 equivalent to @option{-march=@var{arch} -mtune=generic-@var{arch}}.
16813 See @option{-mtune} for more information.
16815 @option{-mcpu=native} causes the compiler to auto-detect the CPU
16816 of the build computer.  At present, this feature is only supported on
16817 GNU/Linux, and not all architectures are recognized.  If the auto-detect
16818 is unsuccessful the option has no effect.
16820 @item -mfpu=@var{name}
16821 @opindex mfpu
16822 This specifies what floating-point hardware (or hardware emulation) is
16823 available on the target.  Permissible names are: @samp{auto}, @samp{vfpv2},
16824 @samp{vfpv3},
16825 @samp{vfpv3-fp16}, @samp{vfpv3-d16}, @samp{vfpv3-d16-fp16}, @samp{vfpv3xd},
16826 @samp{vfpv3xd-fp16}, @samp{neon-vfpv3}, @samp{neon-fp16}, @samp{vfpv4},
16827 @samp{vfpv4-d16}, @samp{fpv4-sp-d16}, @samp{neon-vfpv4},
16828 @samp{fpv5-d16}, @samp{fpv5-sp-d16},
16829 @samp{fp-armv8}, @samp{neon-fp-armv8} and @samp{crypto-neon-fp-armv8}.
16830 Note that @samp{neon} is an alias for @samp{neon-vfpv3} and @samp{vfp}
16831 is an alias for @samp{vfpv2}.
16833 The setting @samp{auto} is the default and is special.  It causes the
16834 compiler to select the floating-point and Advanced SIMD instructions
16835 based on the settings of @option{-mcpu} and @option{-march}.
16837 If the selected floating-point hardware includes the NEON extension
16838 (e.g. @option{-mfpu=neon}), note that floating-point
16839 operations are not generated by GCC's auto-vectorization pass unless
16840 @option{-funsafe-math-optimizations} is also specified.  This is
16841 because NEON hardware does not fully implement the IEEE 754 standard for
16842 floating-point arithmetic (in particular denormal values are treated as
16843 zero), so the use of NEON instructions may lead to a loss of precision.
16845 You can also set the fpu name at function level by using the @code{target("fpu=")} function attributes (@pxref{ARM Function Attributes}) or pragmas (@pxref{Function Specific Option Pragmas}).
16847 @item -mfp16-format=@var{name}
16848 @opindex mfp16-format
16849 Specify the format of the @code{__fp16} half-precision floating-point type.
16850 Permissible names are @samp{none}, @samp{ieee}, and @samp{alternative};
16851 the default is @samp{none}, in which case the @code{__fp16} type is not
16852 defined.  @xref{Half-Precision}, for more information.
16854 @item -mstructure-size-boundary=@var{n}
16855 @opindex mstructure-size-boundary
16856 The sizes of all structures and unions are rounded up to a multiple
16857 of the number of bits set by this option.  Permissible values are 8, 32
16858 and 64.  The default value varies for different toolchains.  For the COFF
16859 targeted toolchain the default value is 8.  A value of 64 is only allowed
16860 if the underlying ABI supports it.
16862 Specifying a larger number can produce faster, more efficient code, but
16863 can also increase the size of the program.  Different values are potentially
16864 incompatible.  Code compiled with one value cannot necessarily expect to
16865 work with code or libraries compiled with another value, if they exchange
16866 information using structures or unions.
16868 This option is deprecated.
16870 @item -mabort-on-noreturn
16871 @opindex mabort-on-noreturn
16872 Generate a call to the function @code{abort} at the end of a
16873 @code{noreturn} function.  It is executed if the function tries to
16874 return.
16876 @item -mlong-calls
16877 @itemx -mno-long-calls
16878 @opindex mlong-calls
16879 @opindex mno-long-calls
16880 Tells the compiler to perform function calls by first loading the
16881 address of the function into a register and then performing a subroutine
16882 call on this register.  This switch is needed if the target function
16883 lies outside of the 64-megabyte addressing range of the offset-based
16884 version of subroutine call instruction.
16886 Even if this switch is enabled, not all function calls are turned
16887 into long calls.  The heuristic is that static functions, functions
16888 that have the @code{short_call} attribute, functions that are inside
16889 the scope of a @code{#pragma no_long_calls} directive, and functions whose
16890 definitions have already been compiled within the current compilation
16891 unit are not turned into long calls.  The exceptions to this rule are
16892 that weak function definitions, functions with the @code{long_call}
16893 attribute or the @code{section} attribute, and functions that are within
16894 the scope of a @code{#pragma long_calls} directive are always
16895 turned into long calls.
16897 This feature is not enabled by default.  Specifying
16898 @option{-mno-long-calls} restores the default behavior, as does
16899 placing the function calls within the scope of a @code{#pragma
16900 long_calls_off} directive.  Note these switches have no effect on how
16901 the compiler generates code to handle function calls via function
16902 pointers.
16904 @item -msingle-pic-base
16905 @opindex msingle-pic-base
16906 Treat the register used for PIC addressing as read-only, rather than
16907 loading it in the prologue for each function.  The runtime system is
16908 responsible for initializing this register with an appropriate value
16909 before execution begins.
16911 @item -mpic-register=@var{reg}
16912 @opindex mpic-register
16913 Specify the register to be used for PIC addressing.
16914 For standard PIC base case, the default is any suitable register
16915 determined by compiler.  For single PIC base case, the default is
16916 @samp{R9} if target is EABI based or stack-checking is enabled,
16917 otherwise the default is @samp{R10}.
16919 @item -mpic-data-is-text-relative
16920 @opindex mpic-data-is-text-relative
16921 Assume that the displacement between the text and data segments is fixed
16922 at static link time.  This permits using PC-relative addressing
16923 operations to access data known to be in the data segment.  For
16924 non-VxWorks RTP targets, this option is enabled by default.  When
16925 disabled on such targets, it will enable @option{-msingle-pic-base} by
16926 default.
16928 @item -mpoke-function-name
16929 @opindex mpoke-function-name
16930 Write the name of each function into the text section, directly
16931 preceding the function prologue.  The generated code is similar to this:
16933 @smallexample
16934      t0
16935          .ascii "arm_poke_function_name", 0
16936          .align
16937      t1
16938          .word 0xff000000 + (t1 - t0)
16939      arm_poke_function_name
16940          mov     ip, sp
16941          stmfd   sp!, @{fp, ip, lr, pc@}
16942          sub     fp, ip, #4
16943 @end smallexample
16945 When performing a stack backtrace, code can inspect the value of
16946 @code{pc} stored at @code{fp + 0}.  If the trace function then looks at
16947 location @code{pc - 12} and the top 8 bits are set, then we know that
16948 there is a function name embedded immediately preceding this location
16949 and has length @code{((pc[-3]) & 0xff000000)}.
16951 @item -mthumb
16952 @itemx -marm
16953 @opindex marm
16954 @opindex mthumb
16956 Select between generating code that executes in ARM and Thumb
16957 states.  The default for most configurations is to generate code
16958 that executes in ARM state, but the default can be changed by
16959 configuring GCC with the @option{--with-mode=}@var{state}
16960 configure option.
16962 You can also override the ARM and Thumb mode for each function
16963 by using the @code{target("thumb")} and @code{target("arm")} function attributes
16964 (@pxref{ARM Function Attributes}) or pragmas (@pxref{Function Specific Option Pragmas}).
16966 @item -mflip-thumb 
16967 @opindex mflip-thumb
16968 Switch ARM/Thumb modes on alternating functions.
16969 This option is provided for regression testing of mixed Thumb/ARM code
16970 generation, and is not intended for ordinary use in compiling code.
16972 @item -mtpcs-frame
16973 @opindex mtpcs-frame
16974 Generate a stack frame that is compliant with the Thumb Procedure Call
16975 Standard for all non-leaf functions.  (A leaf function is one that does
16976 not call any other functions.)  The default is @option{-mno-tpcs-frame}.
16978 @item -mtpcs-leaf-frame
16979 @opindex mtpcs-leaf-frame
16980 Generate a stack frame that is compliant with the Thumb Procedure Call
16981 Standard for all leaf functions.  (A leaf function is one that does
16982 not call any other functions.)  The default is @option{-mno-apcs-leaf-frame}.
16984 @item -mcallee-super-interworking
16985 @opindex mcallee-super-interworking
16986 Gives all externally visible functions in the file being compiled an ARM
16987 instruction set header which switches to Thumb mode before executing the
16988 rest of the function.  This allows these functions to be called from
16989 non-interworking code.  This option is not valid in AAPCS configurations
16990 because interworking is enabled by default.
16992 @item -mcaller-super-interworking
16993 @opindex mcaller-super-interworking
16994 Allows calls via function pointers (including virtual functions) to
16995 execute correctly regardless of whether the target code has been
16996 compiled for interworking or not.  There is a small overhead in the cost
16997 of executing a function pointer if this option is enabled.  This option
16998 is not valid in AAPCS configurations because interworking is enabled
16999 by default.
17001 @item -mtp=@var{name}
17002 @opindex mtp
17003 Specify the access model for the thread local storage pointer.  The valid
17004 models are @samp{soft}, which generates calls to @code{__aeabi_read_tp},
17005 @samp{cp15}, which fetches the thread pointer from @code{cp15} directly
17006 (supported in the arm6k architecture), and @samp{auto}, which uses the
17007 best available method for the selected processor.  The default setting is
17008 @samp{auto}.
17010 @item -mtls-dialect=@var{dialect}
17011 @opindex mtls-dialect
17012 Specify the dialect to use for accessing thread local storage.  Two
17013 @var{dialect}s are supported---@samp{gnu} and @samp{gnu2}.  The
17014 @samp{gnu} dialect selects the original GNU scheme for supporting
17015 local and global dynamic TLS models.  The @samp{gnu2} dialect
17016 selects the GNU descriptor scheme, which provides better performance
17017 for shared libraries.  The GNU descriptor scheme is compatible with
17018 the original scheme, but does require new assembler, linker and
17019 library support.  Initial and local exec TLS models are unaffected by
17020 this option and always use the original scheme.
17022 @item -mword-relocations
17023 @opindex mword-relocations
17024 Only generate absolute relocations on word-sized values (i.e. R_ARM_ABS32).
17025 This is enabled by default on targets (uClinux, SymbianOS) where the runtime
17026 loader imposes this restriction, and when @option{-fpic} or @option{-fPIC}
17027 is specified.
17029 @item -mfix-cortex-m3-ldrd
17030 @opindex mfix-cortex-m3-ldrd
17031 Some Cortex-M3 cores can cause data corruption when @code{ldrd} instructions
17032 with overlapping destination and base registers are used.  This option avoids
17033 generating these instructions.  This option is enabled by default when
17034 @option{-mcpu=cortex-m3} is specified.
17036 @item -munaligned-access
17037 @itemx -mno-unaligned-access
17038 @opindex munaligned-access
17039 @opindex mno-unaligned-access
17040 Enables (or disables) reading and writing of 16- and 32- bit values
17041 from addresses that are not 16- or 32- bit aligned.  By default
17042 unaligned access is disabled for all pre-ARMv6, all ARMv6-M and for
17043 ARMv8-M Baseline architectures, and enabled for all other
17044 architectures.  If unaligned access is not enabled then words in packed
17045 data structures are accessed a byte at a time.
17047 The ARM attribute @code{Tag_CPU_unaligned_access} is set in the
17048 generated object file to either true or false, depending upon the
17049 setting of this option.  If unaligned access is enabled then the
17050 preprocessor symbol @code{__ARM_FEATURE_UNALIGNED} is also
17051 defined.
17053 @item -mneon-for-64bits
17054 @opindex mneon-for-64bits
17055 Enables using Neon to handle scalar 64-bits operations. This is
17056 disabled by default since the cost of moving data from core registers
17057 to Neon is high.
17059 @item -mslow-flash-data
17060 @opindex mslow-flash-data
17061 Assume loading data from flash is slower than fetching instruction.
17062 Therefore literal load is minimized for better performance.
17063 This option is only supported when compiling for ARMv7 M-profile and
17064 off by default.
17066 @item -masm-syntax-unified
17067 @opindex masm-syntax-unified
17068 Assume inline assembler is using unified asm syntax.  The default is
17069 currently off which implies divided syntax.  This option has no impact
17070 on Thumb2. However, this may change in future releases of GCC.
17071 Divided syntax should be considered deprecated.
17073 @item -mrestrict-it
17074 @opindex mrestrict-it
17075 Restricts generation of IT blocks to conform to the rules of ARMv8-A.
17076 IT blocks can only contain a single 16-bit instruction from a select
17077 set of instructions. This option is on by default for ARMv8-A Thumb mode.
17079 @item -mprint-tune-info
17080 @opindex mprint-tune-info
17081 Print CPU tuning information as comment in assembler file.  This is
17082 an option used only for regression testing of the compiler and not
17083 intended for ordinary use in compiling code.  This option is disabled
17084 by default.
17086 @item -mverbose-cost-dump
17087 @opindex mverbose-cost-dump
17088 Enable verbose cost model dumping in the debug dump files.  This option is
17089 provided for use in debugging the compiler.
17091 @item -mpure-code
17092 @opindex mpure-code
17093 Do not allow constant data to be placed in code sections.
17094 Additionally, when compiling for ELF object format give all text sections the
17095 ELF processor-specific section attribute @code{SHF_ARM_PURECODE}.  This option
17096 is only available when generating non-pic code for M-profile targets with the
17097 MOVT instruction.
17099 @item -mcmse
17100 @opindex mcmse
17101 Generate secure code as per the "ARMv8-M Security Extensions: Requirements on
17102 Development Tools Engineering Specification", which can be found on
17103 @url{http://infocenter.arm.com/help/topic/com.arm.doc.ecm0359818/ECM0359818_armv8m_security_extensions_reqs_on_dev_tools_1_0.pdf}.
17104 @end table
17106 @node AVR Options
17107 @subsection AVR Options
17108 @cindex AVR Options
17110 These options are defined for AVR implementations:
17112 @table @gcctabopt
17113 @item -mmcu=@var{mcu}
17114 @opindex mmcu
17115 Specify Atmel AVR instruction set architectures (ISA) or MCU type.
17117 The default for this option is@tie{}@samp{avr2}.
17119 GCC supports the following AVR devices and ISAs:
17121 @include avr-mmcu.texi
17123 @item -mabsdata
17124 @opindex mabsdata
17126 Assume that all data in static storage can be accessed by LDS / STS
17127 instructions.  This option has only an effect on reduced Tiny devices like
17128 ATtiny40.  See also the @code{absdata}
17129 @ref{AVR Variable Attributes,variable attribute}.
17131 @item -maccumulate-args
17132 @opindex maccumulate-args
17133 Accumulate outgoing function arguments and acquire/release the needed
17134 stack space for outgoing function arguments once in function
17135 prologue/epilogue.  Without this option, outgoing arguments are pushed
17136 before calling a function and popped afterwards.
17138 Popping the arguments after the function call can be expensive on
17139 AVR so that accumulating the stack space might lead to smaller
17140 executables because arguments need not be removed from the
17141 stack after such a function call.
17143 This option can lead to reduced code size for functions that perform
17144 several calls to functions that get their arguments on the stack like
17145 calls to printf-like functions.
17147 @item -mbranch-cost=@var{cost}
17148 @opindex mbranch-cost
17149 Set the branch costs for conditional branch instructions to
17150 @var{cost}.  Reasonable values for @var{cost} are small, non-negative
17151 integers. The default branch cost is 0.
17153 @item -mcall-prologues
17154 @opindex mcall-prologues
17155 Functions prologues/epilogues are expanded as calls to appropriate
17156 subroutines.  Code size is smaller.
17158 @item -mgas-isr-prologues
17159 @opindex mgas-isr-prologues
17160 Interrupt service routines (ISRs) may use the @code{__gcc_isr} pseudo
17161 instruction supported by GNU Binutils.
17162 If this option is on, the feature can still be disabled for individual
17163 ISRs by means of the @ref{AVR Function Attributes,,@code{no_gccisr}}
17164 function attribute.  This feature is activated per default
17165 if optimization is on (but not with @option{-Og}, @pxref{Optimize Options}),
17166 and if GNU Binutils support @w{@uref{https://sourceware.org/PR21683,PR21683}}.
17168 @item -mint8
17169 @opindex mint8
17170 Assume @code{int} to be 8-bit integer.  This affects the sizes of all types: a
17171 @code{char} is 1 byte, an @code{int} is 1 byte, a @code{long} is 2 bytes,
17172 and @code{long long} is 4 bytes.  Please note that this option does not
17173 conform to the C standards, but it results in smaller code
17174 size.
17176 @item -mmain-is-OS_task
17177 @opindex mmain-is-OS_task
17178 Do not save registers in @code{main}.  The effect is the same like
17179 attaching attribute @ref{AVR Function Attributes,,@code{OS_task}}
17180 to @code{main}. It is activated per default if optimization is on.
17182 @item -mn-flash=@var{num}
17183 @opindex mn-flash
17184 Assume that the flash memory has a size of 
17185 @var{num} times 64@tie{}KiB.
17187 @item -mno-interrupts
17188 @opindex mno-interrupts
17189 Generated code is not compatible with hardware interrupts.
17190 Code size is smaller.
17192 @item -mrelax
17193 @opindex mrelax
17194 Try to replace @code{CALL} resp.@: @code{JMP} instruction by the shorter
17195 @code{RCALL} resp.@: @code{RJMP} instruction if applicable.
17196 Setting @option{-mrelax} just adds the @option{--mlink-relax} option to
17197 the assembler's command line and the @option{--relax} option to the
17198 linker's command line.
17200 Jump relaxing is performed by the linker because jump offsets are not
17201 known before code is located. Therefore, the assembler code generated by the
17202 compiler is the same, but the instructions in the executable may
17203 differ from instructions in the assembler code.
17205 Relaxing must be turned on if linker stubs are needed, see the
17206 section on @code{EIND} and linker stubs below.
17208 @item -mrmw
17209 @opindex mrmw
17210 Assume that the device supports the Read-Modify-Write
17211 instructions @code{XCH}, @code{LAC}, @code{LAS} and @code{LAT}.
17213 @item -mshort-calls
17214 @opindex mshort-calls
17216 Assume that @code{RJMP} and @code{RCALL} can target the whole
17217 program memory.
17219 This option is used internally for multilib selection.  It is
17220 not an optimization option, and you don't need to set it by hand.
17222 @item -msp8
17223 @opindex msp8
17224 Treat the stack pointer register as an 8-bit register,
17225 i.e.@: assume the high byte of the stack pointer is zero.
17226 In general, you don't need to set this option by hand.
17228 This option is used internally by the compiler to select and
17229 build multilibs for architectures @code{avr2} and @code{avr25}.
17230 These architectures mix devices with and without @code{SPH}.
17231 For any setting other than @option{-mmcu=avr2} or @option{-mmcu=avr25}
17232 the compiler driver adds or removes this option from the compiler
17233 proper's command line, because the compiler then knows if the device
17234 or architecture has an 8-bit stack pointer and thus no @code{SPH}
17235 register or not.
17237 @item -mstrict-X
17238 @opindex mstrict-X
17239 Use address register @code{X} in a way proposed by the hardware.  This means
17240 that @code{X} is only used in indirect, post-increment or
17241 pre-decrement addressing.
17243 Without this option, the @code{X} register may be used in the same way
17244 as @code{Y} or @code{Z} which then is emulated by additional
17245 instructions.  
17246 For example, loading a value with @code{X+const} addressing with a
17247 small non-negative @code{const < 64} to a register @var{Rn} is
17248 performed as
17250 @example
17251 adiw r26, const   ; X += const
17252 ld   @var{Rn}, X        ; @var{Rn} = *X
17253 sbiw r26, const   ; X -= const
17254 @end example
17256 @item -mtiny-stack
17257 @opindex mtiny-stack
17258 Only change the lower 8@tie{}bits of the stack pointer.
17260 @item -mfract-convert-truncate
17261 @opindex mfract-convert-truncate
17262 Allow to use truncation instead of rounding towards zero for fractional fixed-point types.
17264 @item -nodevicelib
17265 @opindex nodevicelib
17266 Don't link against AVR-LibC's device specific library @code{lib<mcu>.a}.
17268 @item -Waddr-space-convert
17269 @opindex Waddr-space-convert
17270 @opindex Wno-addr-space-convert
17271 Warn about conversions between address spaces in the case where the
17272 resulting address space is not contained in the incoming address space.
17274 @item -Wmisspelled-isr
17275 @opindex Wmisspelled-isr
17276 @opindex Wno-misspelled-isr
17277 Warn if the ISR is misspelled, i.e. without __vector prefix.
17278 Enabled by default.
17279 @end table
17281 @subsubsection @code{EIND} and Devices with More Than 128 Ki Bytes of Flash
17282 @cindex @code{EIND}
17283 Pointers in the implementation are 16@tie{}bits wide.
17284 The address of a function or label is represented as word address so
17285 that indirect jumps and calls can target any code address in the
17286 range of 64@tie{}Ki words.
17288 In order to facilitate indirect jump on devices with more than 128@tie{}Ki
17289 bytes of program memory space, there is a special function register called
17290 @code{EIND} that serves as most significant part of the target address
17291 when @code{EICALL} or @code{EIJMP} instructions are used.
17293 Indirect jumps and calls on these devices are handled as follows by
17294 the compiler and are subject to some limitations:
17296 @itemize @bullet
17298 @item
17299 The compiler never sets @code{EIND}.
17301 @item
17302 The compiler uses @code{EIND} implicitly in @code{EICALL}/@code{EIJMP}
17303 instructions or might read @code{EIND} directly in order to emulate an
17304 indirect call/jump by means of a @code{RET} instruction.
17306 @item
17307 The compiler assumes that @code{EIND} never changes during the startup
17308 code or during the application. In particular, @code{EIND} is not
17309 saved/restored in function or interrupt service routine
17310 prologue/epilogue.
17312 @item
17313 For indirect calls to functions and computed goto, the linker
17314 generates @emph{stubs}. Stubs are jump pads sometimes also called
17315 @emph{trampolines}. Thus, the indirect call/jump jumps to such a stub.
17316 The stub contains a direct jump to the desired address.
17318 @item
17319 Linker relaxation must be turned on so that the linker generates
17320 the stubs correctly in all situations. See the compiler option
17321 @option{-mrelax} and the linker option @option{--relax}.
17322 There are corner cases where the linker is supposed to generate stubs
17323 but aborts without relaxation and without a helpful error message.
17325 @item
17326 The default linker script is arranged for code with @code{EIND = 0}.
17327 If code is supposed to work for a setup with @code{EIND != 0}, a custom
17328 linker script has to be used in order to place the sections whose
17329 name start with @code{.trampolines} into the segment where @code{EIND}
17330 points to.
17332 @item
17333 The startup code from libgcc never sets @code{EIND}.
17334 Notice that startup code is a blend of code from libgcc and AVR-LibC.
17335 For the impact of AVR-LibC on @code{EIND}, see the
17336 @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC user manual}}.
17338 @item
17339 It is legitimate for user-specific startup code to set up @code{EIND}
17340 early, for example by means of initialization code located in
17341 section @code{.init3}. Such code runs prior to general startup code
17342 that initializes RAM and calls constructors, but after the bit
17343 of startup code from AVR-LibC that sets @code{EIND} to the segment
17344 where the vector table is located.
17345 @example
17346 #include <avr/io.h>
17348 static void
17349 __attribute__((section(".init3"),naked,used,no_instrument_function))
17350 init3_set_eind (void)
17352   __asm volatile ("ldi r24,pm_hh8(__trampolines_start)\n\t"
17353                   "out %i0,r24" :: "n" (&EIND) : "r24","memory");
17355 @end example
17357 @noindent
17358 The @code{__trampolines_start} symbol is defined in the linker script.
17360 @item
17361 Stubs are generated automatically by the linker if
17362 the following two conditions are met:
17363 @itemize @minus
17365 @item The address of a label is taken by means of the @code{gs} modifier
17366 (short for @emph{generate stubs}) like so:
17367 @example
17368 LDI r24, lo8(gs(@var{func}))
17369 LDI r25, hi8(gs(@var{func}))
17370 @end example
17371 @item The final location of that label is in a code segment
17372 @emph{outside} the segment where the stubs are located.
17373 @end itemize
17375 @item
17376 The compiler emits such @code{gs} modifiers for code labels in the
17377 following situations:
17378 @itemize @minus
17379 @item Taking address of a function or code label.
17380 @item Computed goto.
17381 @item If prologue-save function is used, see @option{-mcall-prologues}
17382 command-line option.
17383 @item Switch/case dispatch tables. If you do not want such dispatch
17384 tables you can specify the @option{-fno-jump-tables} command-line option.
17385 @item C and C++ constructors/destructors called during startup/shutdown.
17386 @item If the tools hit a @code{gs()} modifier explained above.
17387 @end itemize
17389 @item
17390 Jumping to non-symbolic addresses like so is @emph{not} supported:
17392 @example
17393 int main (void)
17395     /* Call function at word address 0x2 */
17396     return ((int(*)(void)) 0x2)();
17398 @end example
17400 Instead, a stub has to be set up, i.e.@: the function has to be called
17401 through a symbol (@code{func_4} in the example):
17403 @example
17404 int main (void)
17406     extern int func_4 (void);
17408     /* Call function at byte address 0x4 */
17409     return func_4();
17411 @end example
17413 and the application be linked with @option{-Wl,--defsym,func_4=0x4}.
17414 Alternatively, @code{func_4} can be defined in the linker script.
17415 @end itemize
17417 @subsubsection Handling of the @code{RAMPD}, @code{RAMPX}, @code{RAMPY} and @code{RAMPZ} Special Function Registers
17418 @cindex @code{RAMPD}
17419 @cindex @code{RAMPX}
17420 @cindex @code{RAMPY}
17421 @cindex @code{RAMPZ}
17422 Some AVR devices support memories larger than the 64@tie{}KiB range
17423 that can be accessed with 16-bit pointers.  To access memory locations
17424 outside this 64@tie{}KiB range, the content of a @code{RAMP}
17425 register is used as high part of the address:
17426 The @code{X}, @code{Y}, @code{Z} address register is concatenated
17427 with the @code{RAMPX}, @code{RAMPY}, @code{RAMPZ} special function
17428 register, respectively, to get a wide address. Similarly,
17429 @code{RAMPD} is used together with direct addressing.
17431 @itemize
17432 @item
17433 The startup code initializes the @code{RAMP} special function
17434 registers with zero.
17436 @item
17437 If a @ref{AVR Named Address Spaces,named address space} other than
17438 generic or @code{__flash} is used, then @code{RAMPZ} is set
17439 as needed before the operation.
17441 @item
17442 If the device supports RAM larger than 64@tie{}KiB and the compiler
17443 needs to change @code{RAMPZ} to accomplish an operation, @code{RAMPZ}
17444 is reset to zero after the operation.
17446 @item
17447 If the device comes with a specific @code{RAMP} register, the ISR
17448 prologue/epilogue saves/restores that SFR and initializes it with
17449 zero in case the ISR code might (implicitly) use it.
17451 @item
17452 RAM larger than 64@tie{}KiB is not supported by GCC for AVR targets.
17453 If you use inline assembler to read from locations outside the
17454 16-bit address range and change one of the @code{RAMP} registers,
17455 you must reset it to zero after the access.
17457 @end itemize
17459 @subsubsection AVR Built-in Macros
17461 GCC defines several built-in macros so that the user code can test
17462 for the presence or absence of features.  Almost any of the following
17463 built-in macros are deduced from device capabilities and thus
17464 triggered by the @option{-mmcu=} command-line option.
17466 For even more AVR-specific built-in macros see
17467 @ref{AVR Named Address Spaces} and @ref{AVR Built-in Functions}.
17469 @table @code
17471 @item __AVR_ARCH__
17472 Build-in macro that resolves to a decimal number that identifies the
17473 architecture and depends on the @option{-mmcu=@var{mcu}} option.
17474 Possible values are:
17476 @code{2}, @code{25}, @code{3}, @code{31}, @code{35},
17477 @code{4}, @code{5}, @code{51}, @code{6}
17479 for @var{mcu}=@code{avr2}, @code{avr25}, @code{avr3}, @code{avr31},
17480 @code{avr35}, @code{avr4}, @code{avr5}, @code{avr51}, @code{avr6},
17482 respectively and
17484 @code{100},
17485 @code{102}, @code{103}, @code{104},
17486 @code{105}, @code{106}, @code{107}
17488 for @var{mcu}=@code{avrtiny},
17489 @code{avrxmega2}, @code{avrxmega3}, @code{avrxmega4},
17490 @code{avrxmega5}, @code{avrxmega6}, @code{avrxmega7}, respectively.
17491 If @var{mcu} specifies a device, this built-in macro is set
17492 accordingly. For example, with @option{-mmcu=atmega8} the macro is
17493 defined to @code{4}.
17495 @item __AVR_@var{Device}__
17496 Setting @option{-mmcu=@var{device}} defines this built-in macro which reflects
17497 the device's name. For example, @option{-mmcu=atmega8} defines the
17498 built-in macro @code{__AVR_ATmega8__}, @option{-mmcu=attiny261a} defines
17499 @code{__AVR_ATtiny261A__}, etc.
17501 The built-in macros' names follow
17502 the scheme @code{__AVR_@var{Device}__} where @var{Device} is
17503 the device name as from the AVR user manual. The difference between
17504 @var{Device} in the built-in macro and @var{device} in
17505 @option{-mmcu=@var{device}} is that the latter is always lowercase.
17507 If @var{device} is not a device but only a core architecture like
17508 @samp{avr51}, this macro is not defined.
17510 @item __AVR_DEVICE_NAME__
17511 Setting @option{-mmcu=@var{device}} defines this built-in macro to
17512 the device's name. For example, with @option{-mmcu=atmega8} the macro
17513 is defined to @code{atmega8}.
17515 If @var{device} is not a device but only a core architecture like
17516 @samp{avr51}, this macro is not defined.
17518 @item __AVR_XMEGA__
17519 The device / architecture belongs to the XMEGA family of devices.
17521 @item __AVR_HAVE_ELPM__
17522 The device has the @code{ELPM} instruction.
17524 @item __AVR_HAVE_ELPMX__
17525 The device has the @code{ELPM R@var{n},Z} and @code{ELPM
17526 R@var{n},Z+} instructions.
17528 @item __AVR_HAVE_MOVW__
17529 The device has the @code{MOVW} instruction to perform 16-bit
17530 register-register moves.
17532 @item __AVR_HAVE_LPMX__
17533 The device has the @code{LPM R@var{n},Z} and
17534 @code{LPM R@var{n},Z+} instructions.
17536 @item __AVR_HAVE_MUL__
17537 The device has a hardware multiplier. 
17539 @item __AVR_HAVE_JMP_CALL__
17540 The device has the @code{JMP} and @code{CALL} instructions.
17541 This is the case for devices with more than 8@tie{}KiB of program
17542 memory.
17544 @item __AVR_HAVE_EIJMP_EICALL__
17545 @itemx __AVR_3_BYTE_PC__
17546 The device has the @code{EIJMP} and @code{EICALL} instructions.
17547 This is the case for devices with more than 128@tie{}KiB of program memory.
17548 This also means that the program counter
17549 (PC) is 3@tie{}bytes wide.
17551 @item __AVR_2_BYTE_PC__
17552 The program counter (PC) is 2@tie{}bytes wide. This is the case for devices
17553 with up to 128@tie{}KiB of program memory.
17555 @item __AVR_HAVE_8BIT_SP__
17556 @itemx __AVR_HAVE_16BIT_SP__
17557 The stack pointer (SP) register is treated as 8-bit respectively
17558 16-bit register by the compiler.
17559 The definition of these macros is affected by @option{-mtiny-stack}.
17561 @item __AVR_HAVE_SPH__
17562 @itemx __AVR_SP8__
17563 The device has the SPH (high part of stack pointer) special function
17564 register or has an 8-bit stack pointer, respectively.
17565 The definition of these macros is affected by @option{-mmcu=} and
17566 in the cases of @option{-mmcu=avr2} and @option{-mmcu=avr25} also
17567 by @option{-msp8}.
17569 @item __AVR_HAVE_RAMPD__
17570 @itemx __AVR_HAVE_RAMPX__
17571 @itemx __AVR_HAVE_RAMPY__
17572 @itemx __AVR_HAVE_RAMPZ__
17573 The device has the @code{RAMPD}, @code{RAMPX}, @code{RAMPY},
17574 @code{RAMPZ} special function register, respectively.
17576 @item __NO_INTERRUPTS__
17577 This macro reflects the @option{-mno-interrupts} command-line option.
17579 @item __AVR_ERRATA_SKIP__
17580 @itemx __AVR_ERRATA_SKIP_JMP_CALL__
17581 Some AVR devices (AT90S8515, ATmega103) must not skip 32-bit
17582 instructions because of a hardware erratum.  Skip instructions are
17583 @code{SBRS}, @code{SBRC}, @code{SBIS}, @code{SBIC} and @code{CPSE}.
17584 The second macro is only defined if @code{__AVR_HAVE_JMP_CALL__} is also
17585 set.
17587 @item __AVR_ISA_RMW__
17588 The device has Read-Modify-Write instructions (XCH, LAC, LAS and LAT).
17590 @item __AVR_SFR_OFFSET__=@var{offset}
17591 Instructions that can address I/O special function registers directly
17592 like @code{IN}, @code{OUT}, @code{SBI}, etc.@: may use a different
17593 address as if addressed by an instruction to access RAM like @code{LD}
17594 or @code{STS}. This offset depends on the device architecture and has
17595 to be subtracted from the RAM address in order to get the
17596 respective I/O@tie{}address.
17598 @item __AVR_SHORT_CALLS__
17599 The @option{-mshort-calls} command line option is set.
17601 @item __AVR_PM_BASE_ADDRESS__=@var{addr}
17602 Some devices support reading from flash memory by means of @code{LD*}
17603 instructions.  The flash memory is seen in the data address space
17604 at an offset of @code{__AVR_PM_BASE_ADDRESS__}.  If this macro
17605 is not defined, this feature is not available.  If defined,
17606 the address space is linear and there is no need to put
17607 @code{.rodata} into RAM.  This is handled by the default linker
17608 description file, and is currently available for
17609 @code{avrtiny} and @code{avrxmega3}.  Even more convenient,
17610 there is no need to use address spaces like @code{__flash} or
17611 features like attribute @code{progmem} and @code{pgm_read_*}.
17613 @item __WITH_AVRLIBC__
17614 The compiler is configured to be used together with AVR-Libc.
17615 See the @option{--with-avrlibc} configure option.
17617 @end table
17619 @node Blackfin Options
17620 @subsection Blackfin Options
17621 @cindex Blackfin Options
17623 @table @gcctabopt
17624 @item -mcpu=@var{cpu}@r{[}-@var{sirevision}@r{]}
17625 @opindex mcpu=
17626 Specifies the name of the target Blackfin processor.  Currently, @var{cpu}
17627 can be one of @samp{bf512}, @samp{bf514}, @samp{bf516}, @samp{bf518},
17628 @samp{bf522}, @samp{bf523}, @samp{bf524}, @samp{bf525}, @samp{bf526},
17629 @samp{bf527}, @samp{bf531}, @samp{bf532}, @samp{bf533},
17630 @samp{bf534}, @samp{bf536}, @samp{bf537}, @samp{bf538}, @samp{bf539},
17631 @samp{bf542}, @samp{bf544}, @samp{bf547}, @samp{bf548}, @samp{bf549},
17632 @samp{bf542m}, @samp{bf544m}, @samp{bf547m}, @samp{bf548m}, @samp{bf549m},
17633 @samp{bf561}, @samp{bf592}.
17635 The optional @var{sirevision} specifies the silicon revision of the target
17636 Blackfin processor.  Any workarounds available for the targeted silicon revision
17637 are enabled.  If @var{sirevision} is @samp{none}, no workarounds are enabled.
17638 If @var{sirevision} is @samp{any}, all workarounds for the targeted processor
17639 are enabled.  The @code{__SILICON_REVISION__} macro is defined to two
17640 hexadecimal digits representing the major and minor numbers in the silicon
17641 revision.  If @var{sirevision} is @samp{none}, the @code{__SILICON_REVISION__}
17642 is not defined.  If @var{sirevision} is @samp{any}, the
17643 @code{__SILICON_REVISION__} is defined to be @code{0xffff}.
17644 If this optional @var{sirevision} is not used, GCC assumes the latest known
17645 silicon revision of the targeted Blackfin processor.
17647 GCC defines a preprocessor macro for the specified @var{cpu}.
17648 For the @samp{bfin-elf} toolchain, this option causes the hardware BSP
17649 provided by libgloss to be linked in if @option{-msim} is not given.
17651 Without this option, @samp{bf532} is used as the processor by default.
17653 Note that support for @samp{bf561} is incomplete.  For @samp{bf561},
17654 only the preprocessor macro is defined.
17656 @item -msim
17657 @opindex msim
17658 Specifies that the program will be run on the simulator.  This causes
17659 the simulator BSP provided by libgloss to be linked in.  This option
17660 has effect only for @samp{bfin-elf} toolchain.
17661 Certain other options, such as @option{-mid-shared-library} and
17662 @option{-mfdpic}, imply @option{-msim}.
17664 @item -momit-leaf-frame-pointer
17665 @opindex momit-leaf-frame-pointer
17666 Don't keep the frame pointer in a register for leaf functions.  This
17667 avoids the instructions to save, set up and restore frame pointers and
17668 makes an extra register available in leaf functions.
17670 @item -mspecld-anomaly
17671 @opindex mspecld-anomaly
17672 When enabled, the compiler ensures that the generated code does not
17673 contain speculative loads after jump instructions. If this option is used,
17674 @code{__WORKAROUND_SPECULATIVE_LOADS} is defined.
17676 @item -mno-specld-anomaly
17677 @opindex mno-specld-anomaly
17678 Don't generate extra code to prevent speculative loads from occurring.
17680 @item -mcsync-anomaly
17681 @opindex mcsync-anomaly
17682 When enabled, the compiler ensures that the generated code does not
17683 contain CSYNC or SSYNC instructions too soon after conditional branches.
17684 If this option is used, @code{__WORKAROUND_SPECULATIVE_SYNCS} is defined.
17686 @item -mno-csync-anomaly
17687 @opindex mno-csync-anomaly
17688 Don't generate extra code to prevent CSYNC or SSYNC instructions from
17689 occurring too soon after a conditional branch.
17691 @item -mlow-64k
17692 @opindex mlow-64k
17693 When enabled, the compiler is free to take advantage of the knowledge that
17694 the entire program fits into the low 64k of memory.
17696 @item -mno-low-64k
17697 @opindex mno-low-64k
17698 Assume that the program is arbitrarily large.  This is the default.
17700 @item -mstack-check-l1
17701 @opindex mstack-check-l1
17702 Do stack checking using information placed into L1 scratchpad memory by the
17703 uClinux kernel.
17705 @item -mid-shared-library
17706 @opindex mid-shared-library
17707 Generate code that supports shared libraries via the library ID method.
17708 This allows for execute in place and shared libraries in an environment
17709 without virtual memory management.  This option implies @option{-fPIC}.
17710 With a @samp{bfin-elf} target, this option implies @option{-msim}.
17712 @item -mno-id-shared-library
17713 @opindex mno-id-shared-library
17714 Generate code that doesn't assume ID-based shared libraries are being used.
17715 This is the default.
17717 @item -mleaf-id-shared-library
17718 @opindex mleaf-id-shared-library
17719 Generate code that supports shared libraries via the library ID method,
17720 but assumes that this library or executable won't link against any other
17721 ID shared libraries.  That allows the compiler to use faster code for jumps
17722 and calls.
17724 @item -mno-leaf-id-shared-library
17725 @opindex mno-leaf-id-shared-library
17726 Do not assume that the code being compiled won't link against any ID shared
17727 libraries.  Slower code is generated for jump and call insns.
17729 @item -mshared-library-id=n
17730 @opindex mshared-library-id
17731 Specifies the identification number of the ID-based shared library being
17732 compiled.  Specifying a value of 0 generates more compact code; specifying
17733 other values forces the allocation of that number to the current
17734 library but is no more space- or time-efficient than omitting this option.
17736 @item -msep-data
17737 @opindex msep-data
17738 Generate code that allows the data segment to be located in a different
17739 area of memory from the text segment.  This allows for execute in place in
17740 an environment without virtual memory management by eliminating relocations
17741 against the text section.
17743 @item -mno-sep-data
17744 @opindex mno-sep-data
17745 Generate code that assumes that the data segment follows the text segment.
17746 This is the default.
17748 @item -mlong-calls
17749 @itemx -mno-long-calls
17750 @opindex mlong-calls
17751 @opindex mno-long-calls
17752 Tells the compiler to perform function calls by first loading the
17753 address of the function into a register and then performing a subroutine
17754 call on this register.  This switch is needed if the target function
17755 lies outside of the 24-bit addressing range of the offset-based
17756 version of subroutine call instruction.
17758 This feature is not enabled by default.  Specifying
17759 @option{-mno-long-calls} restores the default behavior.  Note these
17760 switches have no effect on how the compiler generates code to handle
17761 function calls via function pointers.
17763 @item -mfast-fp
17764 @opindex mfast-fp
17765 Link with the fast floating-point library. This library relaxes some of
17766 the IEEE floating-point standard's rules for checking inputs against
17767 Not-a-Number (NAN), in the interest of performance.
17769 @item -minline-plt
17770 @opindex minline-plt
17771 Enable inlining of PLT entries in function calls to functions that are
17772 not known to bind locally.  It has no effect without @option{-mfdpic}.
17774 @item -mmulticore
17775 @opindex mmulticore
17776 Build a standalone application for multicore Blackfin processors. 
17777 This option causes proper start files and link scripts supporting 
17778 multicore to be used, and defines the macro @code{__BFIN_MULTICORE}. 
17779 It can only be used with @option{-mcpu=bf561@r{[}-@var{sirevision}@r{]}}. 
17781 This option can be used with @option{-mcorea} or @option{-mcoreb}, which
17782 selects the one-application-per-core programming model.  Without
17783 @option{-mcorea} or @option{-mcoreb}, the single-application/dual-core
17784 programming model is used. In this model, the main function of Core B
17785 should be named as @code{coreb_main}.
17787 If this option is not used, the single-core application programming
17788 model is used.
17790 @item -mcorea
17791 @opindex mcorea
17792 Build a standalone application for Core A of BF561 when using
17793 the one-application-per-core programming model. Proper start files
17794 and link scripts are used to support Core A, and the macro
17795 @code{__BFIN_COREA} is defined.
17796 This option can only be used in conjunction with @option{-mmulticore}.
17798 @item -mcoreb
17799 @opindex mcoreb
17800 Build a standalone application for Core B of BF561 when using
17801 the one-application-per-core programming model. Proper start files
17802 and link scripts are used to support Core B, and the macro
17803 @code{__BFIN_COREB} is defined. When this option is used, @code{coreb_main}
17804 should be used instead of @code{main}. 
17805 This option can only be used in conjunction with @option{-mmulticore}.
17807 @item -msdram
17808 @opindex msdram
17809 Build a standalone application for SDRAM. Proper start files and
17810 link scripts are used to put the application into SDRAM, and the macro
17811 @code{__BFIN_SDRAM} is defined.
17812 The loader should initialize SDRAM before loading the application.
17814 @item -micplb
17815 @opindex micplb
17816 Assume that ICPLBs are enabled at run time.  This has an effect on certain
17817 anomaly workarounds.  For Linux targets, the default is to assume ICPLBs
17818 are enabled; for standalone applications the default is off.
17819 @end table
17821 @node C6X Options
17822 @subsection C6X Options
17823 @cindex C6X Options
17825 @table @gcctabopt
17826 @item -march=@var{name}
17827 @opindex march
17828 This specifies the name of the target architecture.  GCC uses this
17829 name to determine what kind of instructions it can emit when generating
17830 assembly code.  Permissible names are: @samp{c62x},
17831 @samp{c64x}, @samp{c64x+}, @samp{c67x}, @samp{c67x+}, @samp{c674x}.
17833 @item -mbig-endian
17834 @opindex mbig-endian
17835 Generate code for a big-endian target.
17837 @item -mlittle-endian
17838 @opindex mlittle-endian
17839 Generate code for a little-endian target.  This is the default.
17841 @item -msim
17842 @opindex msim
17843 Choose startup files and linker script suitable for the simulator.
17845 @item -msdata=default
17846 @opindex msdata=default
17847 Put small global and static data in the @code{.neardata} section,
17848 which is pointed to by register @code{B14}.  Put small uninitialized
17849 global and static data in the @code{.bss} section, which is adjacent
17850 to the @code{.neardata} section.  Put small read-only data into the
17851 @code{.rodata} section.  The corresponding sections used for large
17852 pieces of data are @code{.fardata}, @code{.far} and @code{.const}.
17854 @item -msdata=all
17855 @opindex msdata=all
17856 Put all data, not just small objects, into the sections reserved for
17857 small data, and use addressing relative to the @code{B14} register to
17858 access them.
17860 @item -msdata=none
17861 @opindex msdata=none
17862 Make no use of the sections reserved for small data, and use absolute
17863 addresses to access all data.  Put all initialized global and static
17864 data in the @code{.fardata} section, and all uninitialized data in the
17865 @code{.far} section.  Put all constant data into the @code{.const}
17866 section.
17867 @end table
17869 @node CRIS Options
17870 @subsection CRIS Options
17871 @cindex CRIS Options
17873 These options are defined specifically for the CRIS ports.
17875 @table @gcctabopt
17876 @item -march=@var{architecture-type}
17877 @itemx -mcpu=@var{architecture-type}
17878 @opindex march
17879 @opindex mcpu
17880 Generate code for the specified architecture.  The choices for
17881 @var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
17882 respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
17883 Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
17884 @samp{v10}.
17886 @item -mtune=@var{architecture-type}
17887 @opindex mtune
17888 Tune to @var{architecture-type} everything applicable about the generated
17889 code, except for the ABI and the set of available instructions.  The
17890 choices for @var{architecture-type} are the same as for
17891 @option{-march=@var{architecture-type}}.
17893 @item -mmax-stack-frame=@var{n}
17894 @opindex mmax-stack-frame
17895 Warn when the stack frame of a function exceeds @var{n} bytes.
17897 @item -metrax4
17898 @itemx -metrax100
17899 @opindex metrax4
17900 @opindex metrax100
17901 The options @option{-metrax4} and @option{-metrax100} are synonyms for
17902 @option{-march=v3} and @option{-march=v8} respectively.
17904 @item -mmul-bug-workaround
17905 @itemx -mno-mul-bug-workaround
17906 @opindex mmul-bug-workaround
17907 @opindex mno-mul-bug-workaround
17908 Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
17909 models where it applies.  This option is active by default.
17911 @item -mpdebug
17912 @opindex mpdebug
17913 Enable CRIS-specific verbose debug-related information in the assembly
17914 code.  This option also has the effect of turning off the @samp{#NO_APP}
17915 formatted-code indicator to the assembler at the beginning of the
17916 assembly file.
17918 @item -mcc-init
17919 @opindex mcc-init
17920 Do not use condition-code results from previous instruction; always emit
17921 compare and test instructions before use of condition codes.
17923 @item -mno-side-effects
17924 @opindex mno-side-effects
17925 Do not emit instructions with side effects in addressing modes other than
17926 post-increment.
17928 @item -mstack-align
17929 @itemx -mno-stack-align
17930 @itemx -mdata-align
17931 @itemx -mno-data-align
17932 @itemx -mconst-align
17933 @itemx -mno-const-align
17934 @opindex mstack-align
17935 @opindex mno-stack-align
17936 @opindex mdata-align
17937 @opindex mno-data-align
17938 @opindex mconst-align
17939 @opindex mno-const-align
17940 These options (@samp{no-} options) arrange (eliminate arrangements) for the
17941 stack frame, individual data and constants to be aligned for the maximum
17942 single data access size for the chosen CPU model.  The default is to
17943 arrange for 32-bit alignment.  ABI details such as structure layout are
17944 not affected by these options.
17946 @item -m32-bit
17947 @itemx -m16-bit
17948 @itemx -m8-bit
17949 @opindex m32-bit
17950 @opindex m16-bit
17951 @opindex m8-bit
17952 Similar to the stack- data- and const-align options above, these options
17953 arrange for stack frame, writable data and constants to all be 32-bit,
17954 16-bit or 8-bit aligned.  The default is 32-bit alignment.
17956 @item -mno-prologue-epilogue
17957 @itemx -mprologue-epilogue
17958 @opindex mno-prologue-epilogue
17959 @opindex mprologue-epilogue
17960 With @option{-mno-prologue-epilogue}, the normal function prologue and
17961 epilogue which set up the stack frame are omitted and no return
17962 instructions or return sequences are generated in the code.  Use this
17963 option only together with visual inspection of the compiled code: no
17964 warnings or errors are generated when call-saved registers must be saved,
17965 or storage for local variables needs to be allocated.
17967 @item -mno-gotplt
17968 @itemx -mgotplt
17969 @opindex mno-gotplt
17970 @opindex mgotplt
17971 With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
17972 instruction sequences that load addresses for functions from the PLT part
17973 of the GOT rather than (traditional on other architectures) calls to the
17974 PLT@.  The default is @option{-mgotplt}.
17976 @item -melf
17977 @opindex melf
17978 Legacy no-op option only recognized with the cris-axis-elf and
17979 cris-axis-linux-gnu targets.
17981 @item -mlinux
17982 @opindex mlinux
17983 Legacy no-op option only recognized with the cris-axis-linux-gnu target.
17985 @item -sim
17986 @opindex sim
17987 This option, recognized for the cris-axis-elf, arranges
17988 to link with input-output functions from a simulator library.  Code,
17989 initialized data and zero-initialized data are allocated consecutively.
17991 @item -sim2
17992 @opindex sim2
17993 Like @option{-sim}, but pass linker options to locate initialized data at
17994 0x40000000 and zero-initialized data at 0x80000000.
17995 @end table
17997 @node CR16 Options
17998 @subsection CR16 Options
17999 @cindex CR16 Options
18001 These options are defined specifically for the CR16 ports.
18003 @table @gcctabopt
18005 @item -mmac
18006 @opindex mmac
18007 Enable the use of multiply-accumulate instructions. Disabled by default.
18009 @item -mcr16cplus
18010 @itemx -mcr16c
18011 @opindex mcr16cplus
18012 @opindex mcr16c
18013 Generate code for CR16C or CR16C+ architecture. CR16C+ architecture 
18014 is default.
18016 @item -msim
18017 @opindex msim
18018 Links the library libsim.a which is in compatible with simulator. Applicable
18019 to ELF compiler only.
18021 @item -mint32
18022 @opindex mint32
18023 Choose integer type as 32-bit wide.
18025 @item -mbit-ops
18026 @opindex mbit-ops
18027 Generates @code{sbit}/@code{cbit} instructions for bit manipulations.
18029 @item -mdata-model=@var{model}
18030 @opindex mdata-model
18031 Choose a data model. The choices for @var{model} are @samp{near},
18032 @samp{far} or @samp{medium}. @samp{medium} is default.
18033 However, @samp{far} is not valid with @option{-mcr16c}, as the
18034 CR16C architecture does not support the far data model.
18035 @end table
18037 @node C-SKY Options
18038 @subsection C-SKY Options
18039 @cindex C-SKY Options
18041 GCC supports these options when compiling for C-SKY V2 processors.
18043 @table @gcctabopt
18045 @item -march=@var{arch}
18046 @opindex march=
18047 Specify the C-SKY target architecture.  Valid values for @var{arch} are:
18048 @samp{ck801}, @samp{ck802}, @samp{ck803}, @samp{ck807}, and @samp{ck810}.
18049 The default is @samp{ck810}.
18051 @item -mcpu=@var{cpu}
18052 @opindex mcpu=
18053 Specify the C-SKY target processor.  Valid values for @var{cpu} are:
18054 @samp{ck801}, @samp{ck801t},
18055 @samp{ck802}, @samp{ck802t}, @samp{ck802j},
18056 @samp{ck803}, @samp{ck803h}, @samp{ck803t}, @samp{ck803ht},
18057 @samp{ck803f}, @samp{ck803fh}, @samp{ck803e}, @samp{ck803eh},
18058 @samp{ck803et}, @samp{ck803eht}, @samp{ck803ef}, @samp{ck803efh},
18059 @samp{ck803ft}, @samp{ck803eft}, @samp{ck803efht}, @samp{ck803r1},
18060 @samp{ck803hr1}, @samp{ck803tr1}, @samp{ck803htr1}, @samp{ck803fr1},
18061 @samp{ck803fhr1}, @samp{ck803er1}, @samp{ck803ehr1}, @samp{ck803etr1},
18062 @samp{ck803ehtr1}, @samp{ck803efr1}, @samp{ck803efhr1}, @samp{ck803ftr1},
18063 @samp{ck803eftr1}, @samp{ck803efhtr1},
18064 @samp{ck803s}, @samp{ck803st}, @samp{ck803se}, @samp{ck803sf},
18065 @samp{ck803sef}, @samp{ck803seft},
18066 @samp{ck807e}, @samp{ck807ef}, @samp{ck807}, @samp{ck807f},
18067 @samp{ck810e}, @samp{ck810et}, @samp{ck810ef}, @samp{ck810eft},
18068 @samp{ck810}, @samp{ck810v}, @samp{ck810f}, @samp{ck810t}, @samp{ck810fv},
18069 @samp{ck810tv}, @samp{ck810ft}, and @samp{ck810ftv}.
18071 @item -mbig-endian
18072 @opindex mbig-endian
18073 @itemx -EB
18074 @opindex -EB
18075 @itemx -mlittle-endian
18076 @opindex mlittle-endian
18077 @itemx -EL
18078 @opindex -EL
18080 Select big- or little-endian code.  The default is little-endian.
18082 @item -mhard-float
18083 @opindex mhard-float
18084 @itemx -msoft-float
18085 @opindex msoft-float
18087 Select hardware or software floating-point implementations.
18088 The default is soft float.
18090 @item -mdouble-float
18091 @itemx -mno-double-float
18092 @opindex mdouble-float
18093 When @option{-mhard-float} is in effect, enable generation of
18094 double-precision float instructions.  This is the default except
18095 when compiling for CK803.
18097 @item -mfdivdu
18098 @itemx -mno-fdivdu
18099 @opindex mfdivdu
18100 When @option{-mhard-float} is in effect, enable generation of
18101 @code{frecipd}, @code{fsqrtd}, and @code{fdivd} instructions.
18102 This is the default except when compiling for CK803.
18104 @item -mfpu=@var{fpu}
18105 @opindex mfpu=
18106 Select the floating-point processor.  This option can only be used with
18107 @option{-mhard-float}.
18108 Values for @var{fpu} are
18109 @samp{fpv2_sf} (equivalent to @samp{-mno-double-float -mno-fdivdu}),
18110 @samp{fpv2} (@samp{-mdouble-float -mno-divdu}), and
18111 @samp{fpv2_divd} (@samp{-mdouble-float -mdivdu}).
18113 @item -melrw
18114 @itemx -mno-elrw
18115 @opindex melrw
18116 Enable the extended @code{lrw} instruction.  This option defaults to on
18117 for CK801 and off otherwise.
18119 @item -mistack
18120 @itemx -mno-istack
18121 @opindex mistack
18122 Enable interrupt stack instructions; the default is off.
18124 The @option{-mistack} option is required to handle the
18125 @code{interrupt} and @code{isr} function attributes
18126 (@pxref{C-SKY Function Attributes}).
18128 @item -mmp
18129 @opindex mmp
18130 Enable multiprocessor instructions; the default is off.
18132 @item -mcp
18133 @opindex mcp
18134 Enable coprocessor instructions; the default is off.
18136 @item -mcache
18137 @opindex mcache
18138 Enable coprocessor instructions; the default is off.
18140 @item -msecurity
18141 @opindex msecurity
18142 Enable C-SKY security instructions; the default is off.
18144 @item -mtrust
18145 @opindex mtrust
18146 Enable C-SKY trust instructions; the default is off.
18148 @item -mdsp
18149 @opindex mdsp
18150 @itemx -medsp
18151 @opindex medsp
18152 @itemx -mvdsp
18153 @opindex mvdsp
18154 Enable C-SKY DSP, Enhanced DSP, or Vector DSP instructions, respectively.
18155 All of these options default to off.
18157 @item -mdiv
18158 @itemx -mno-div
18159 @opindex mdiv
18160 Generate divide instructions.  Default is off.
18162 @item -msmart
18163 @itemx -mno-smart
18164 @opindex msmart
18165 Generate code for Smart Mode, using only registers numbered 0-7 to allow
18166 use of 16-bit instructions.  This option is ignored for CK801 where this
18167 is the required behavior, and it defaults to on for CK802.
18168 For other targets, the default is off.
18170 @item -mhigh-registers
18171 @itemx -mno-high-registers
18172 @opindex mhigh-registers
18173 Generate code using the high registers numbered 16-31.  This option
18174 is not supported on CK801, CK802, or CK803, and is enabled by default
18175 for other processors.
18177 @item -manchor
18178 @itemx -mno-anchor
18179 @opindex manchor
18180 Generate code using global anchor symbol addresses.
18182 @item -mpushpop
18183 @itemx -mno-pushpop
18184 @opindex mpushpop
18185 Generate code using @code{push} and @code{pop} instructions.  This option
18186 defaults to on.
18188 @item -mmultiple-stld
18189 @itemx -mstm
18190 @itemx -mno-multiple-stld
18191 @itemx -mno-stm
18192 @opindex mmultiple-stld
18193 Generate code using @code{stm} and @code{ldm} instructions.  This option
18194 isn't supported on CK801 but is enabled by default on other processors.
18196 @item -mconstpool
18197 @itemx -mno-constpool
18198 @opindex mconstpool
18199 Create constant pools in the compiler instead of deferring it to the
18200 assembler.  This option is the default and required for correct code
18201 generation on CK801 and CK802, and is optional on other processors.
18203 @item -mstack-size
18204 @item -mno-stack-size
18205 @opindex mstack-size
18206 Emit @code{.stack_size} directives for each function in the assembly
18207 output.  This option defaults to off.
18209 @item -mccrt
18210 @itemx -mno-ccrt
18211 @opindex mccrt
18212 Generate code for the C-SKY compiler runtime instead of libgcc.  This
18213 option defaults to off.
18215 @item -mbranch-cost=@var{n}
18216 @opindex mbranch-cost=
18217 Set the branch costs to roughly @code{n} instructions.  The default is 1.
18219 @item -msched-prolog
18220 @itemx -mno-sched-prolog
18221 @opindex msched-prolog
18222 Permit scheduling of function prologue and epilogue sequences.  Using
18223 this option can result in code that is not compliant with the C-SKY V2 ABI
18224 prologue requirements and that cannot be debugged or backtraced.
18225 It is disabled by default.
18227 @end table
18229 @node Darwin Options
18230 @subsection Darwin Options
18231 @cindex Darwin options
18233 These options are defined for all architectures running the Darwin operating
18234 system.
18236 FSF GCC on Darwin does not create ``fat'' object files; it creates
18237 an object file for the single architecture that GCC was built to
18238 target.  Apple's GCC on Darwin does create ``fat'' files if multiple
18239 @option{-arch} options are used; it does so by running the compiler or
18240 linker multiple times and joining the results together with
18241 @file{lipo}.
18243 The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
18244 @samp{i686}) is determined by the flags that specify the ISA
18245 that GCC is targeting, like @option{-mcpu} or @option{-march}.  The
18246 @option{-force_cpusubtype_ALL} option can be used to override this.
18248 The Darwin tools vary in their behavior when presented with an ISA
18249 mismatch.  The assembler, @file{as}, only permits instructions to
18250 be used that are valid for the subtype of the file it is generating,
18251 so you cannot put 64-bit instructions in a @samp{ppc750} object file.
18252 The linker for shared libraries, @file{/usr/bin/libtool}, fails
18253 and prints an error if asked to create a shared library with a less
18254 restrictive subtype than its input files (for instance, trying to put
18255 a @samp{ppc970} object file in a @samp{ppc7400} library).  The linker
18256 for executables, @command{ld}, quietly gives the executable the most
18257 restrictive subtype of any of its input files.
18259 @table @gcctabopt
18260 @item -F@var{dir}
18261 @opindex F
18262 Add the framework directory @var{dir} to the head of the list of
18263 directories to be searched for header files.  These directories are
18264 interleaved with those specified by @option{-I} options and are
18265 scanned in a left-to-right order.
18267 A framework directory is a directory with frameworks in it.  A
18268 framework is a directory with a @file{Headers} and/or
18269 @file{PrivateHeaders} directory contained directly in it that ends
18270 in @file{.framework}.  The name of a framework is the name of this
18271 directory excluding the @file{.framework}.  Headers associated with
18272 the framework are found in one of those two directories, with
18273 @file{Headers} being searched first.  A subframework is a framework
18274 directory that is in a framework's @file{Frameworks} directory.
18275 Includes of subframework headers can only appear in a header of a
18276 framework that contains the subframework, or in a sibling subframework
18277 header.  Two subframeworks are siblings if they occur in the same
18278 framework.  A subframework should not have the same name as a
18279 framework; a warning is issued if this is violated.  Currently a
18280 subframework cannot have subframeworks; in the future, the mechanism
18281 may be extended to support this.  The standard frameworks can be found
18282 in @file{/System/Library/Frameworks} and
18283 @file{/Library/Frameworks}.  An example include looks like
18284 @code{#include <Framework/header.h>}, where @file{Framework} denotes
18285 the name of the framework and @file{header.h} is found in the
18286 @file{PrivateHeaders} or @file{Headers} directory.
18288 @item -iframework@var{dir}
18289 @opindex iframework
18290 Like @option{-F} except the directory is a treated as a system
18291 directory.  The main difference between this @option{-iframework} and
18292 @option{-F} is that with @option{-iframework} the compiler does not
18293 warn about constructs contained within header files found via
18294 @var{dir}.  This option is valid only for the C family of languages.
18296 @item -gused
18297 @opindex gused
18298 Emit debugging information for symbols that are used.  For stabs
18299 debugging format, this enables @option{-feliminate-unused-debug-symbols}.
18300 This is by default ON@.
18302 @item -gfull
18303 @opindex gfull
18304 Emit debugging information for all symbols and types.
18306 @item -mmacosx-version-min=@var{version}
18307 The earliest version of MacOS X that this executable will run on
18308 is @var{version}.  Typical values of @var{version} include @code{10.1},
18309 @code{10.2}, and @code{10.3.9}.
18311 If the compiler was built to use the system's headers by default,
18312 then the default for this option is the system version on which the
18313 compiler is running, otherwise the default is to make choices that
18314 are compatible with as many systems and code bases as possible.
18316 @item -mkernel
18317 @opindex mkernel
18318 Enable kernel development mode.  The @option{-mkernel} option sets
18319 @option{-static}, @option{-fno-common}, @option{-fno-use-cxa-atexit},
18320 @option{-fno-exceptions}, @option{-fno-non-call-exceptions},
18321 @option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where
18322 applicable.  This mode also sets @option{-mno-altivec},
18323 @option{-msoft-float}, @option{-fno-builtin} and
18324 @option{-mlong-branch} for PowerPC targets.
18326 @item -mone-byte-bool
18327 @opindex mone-byte-bool
18328 Override the defaults for @code{bool} so that @code{sizeof(bool)==1}.
18329 By default @code{sizeof(bool)} is @code{4} when compiling for
18330 Darwin/PowerPC and @code{1} when compiling for Darwin/x86, so this
18331 option has no effect on x86.
18333 @strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
18334 to generate code that is not binary compatible with code generated
18335 without that switch.  Using this switch may require recompiling all
18336 other modules in a program, including system libraries.  Use this
18337 switch to conform to a non-default data model.
18339 @item -mfix-and-continue
18340 @itemx -ffix-and-continue
18341 @itemx -findirect-data
18342 @opindex mfix-and-continue
18343 @opindex ffix-and-continue
18344 @opindex findirect-data
18345 Generate code suitable for fast turnaround development, such as to
18346 allow GDB to dynamically load @file{.o} files into already-running
18347 programs.  @option{-findirect-data} and @option{-ffix-and-continue}
18348 are provided for backwards compatibility.
18350 @item -all_load
18351 @opindex all_load
18352 Loads all members of static archive libraries.
18353 See man ld(1) for more information.
18355 @item -arch_errors_fatal
18356 @opindex arch_errors_fatal
18357 Cause the errors having to do with files that have the wrong architecture
18358 to be fatal.
18360 @item -bind_at_load
18361 @opindex bind_at_load
18362 Causes the output file to be marked such that the dynamic linker will
18363 bind all undefined references when the file is loaded or launched.
18365 @item -bundle
18366 @opindex bundle
18367 Produce a Mach-o bundle format file.
18368 See man ld(1) for more information.
18370 @item -bundle_loader @var{executable}
18371 @opindex bundle_loader
18372 This option specifies the @var{executable} that will load the build
18373 output file being linked.  See man ld(1) for more information.
18375 @item -dynamiclib
18376 @opindex dynamiclib
18377 When passed this option, GCC produces a dynamic library instead of
18378 an executable when linking, using the Darwin @file{libtool} command.
18380 @item -force_cpusubtype_ALL
18381 @opindex force_cpusubtype_ALL
18382 This causes GCC's output file to have the @samp{ALL} subtype, instead of
18383 one controlled by the @option{-mcpu} or @option{-march} option.
18385 @item -allowable_client  @var{client_name}
18386 @itemx -client_name
18387 @itemx -compatibility_version
18388 @itemx -current_version
18389 @itemx -dead_strip
18390 @itemx -dependency-file
18391 @itemx -dylib_file
18392 @itemx -dylinker_install_name
18393 @itemx -dynamic
18394 @itemx -exported_symbols_list
18395 @itemx -filelist
18396 @need 800
18397 @itemx -flat_namespace
18398 @itemx -force_flat_namespace
18399 @itemx -headerpad_max_install_names
18400 @itemx -image_base
18401 @itemx -init
18402 @itemx -install_name
18403 @itemx -keep_private_externs
18404 @itemx -multi_module
18405 @itemx -multiply_defined
18406 @itemx -multiply_defined_unused
18407 @need 800
18408 @itemx -noall_load
18409 @itemx -no_dead_strip_inits_and_terms
18410 @itemx -nofixprebinding
18411 @itemx -nomultidefs
18412 @itemx -noprebind
18413 @itemx -noseglinkedit
18414 @itemx -pagezero_size
18415 @itemx -prebind
18416 @itemx -prebind_all_twolevel_modules
18417 @itemx -private_bundle
18418 @need 800
18419 @itemx -read_only_relocs
18420 @itemx -sectalign
18421 @itemx -sectobjectsymbols
18422 @itemx -whyload
18423 @itemx -seg1addr
18424 @itemx -sectcreate
18425 @itemx -sectobjectsymbols
18426 @itemx -sectorder
18427 @itemx -segaddr
18428 @itemx -segs_read_only_addr
18429 @need 800
18430 @itemx -segs_read_write_addr
18431 @itemx -seg_addr_table
18432 @itemx -seg_addr_table_filename
18433 @itemx -seglinkedit
18434 @itemx -segprot
18435 @itemx -segs_read_only_addr
18436 @itemx -segs_read_write_addr
18437 @itemx -single_module
18438 @itemx -static
18439 @itemx -sub_library
18440 @need 800
18441 @itemx -sub_umbrella
18442 @itemx -twolevel_namespace
18443 @itemx -umbrella
18444 @itemx -undefined
18445 @itemx -unexported_symbols_list
18446 @itemx -weak_reference_mismatches
18447 @itemx -whatsloaded
18448 @opindex allowable_client
18449 @opindex client_name
18450 @opindex compatibility_version
18451 @opindex current_version
18452 @opindex dead_strip
18453 @opindex dependency-file
18454 @opindex dylib_file
18455 @opindex dylinker_install_name
18456 @opindex dynamic
18457 @opindex exported_symbols_list
18458 @opindex filelist
18459 @opindex flat_namespace
18460 @opindex force_flat_namespace
18461 @opindex headerpad_max_install_names
18462 @opindex image_base
18463 @opindex init
18464 @opindex install_name
18465 @opindex keep_private_externs
18466 @opindex multi_module
18467 @opindex multiply_defined
18468 @opindex multiply_defined_unused
18469 @opindex noall_load
18470 @opindex no_dead_strip_inits_and_terms
18471 @opindex nofixprebinding
18472 @opindex nomultidefs
18473 @opindex noprebind
18474 @opindex noseglinkedit
18475 @opindex pagezero_size
18476 @opindex prebind
18477 @opindex prebind_all_twolevel_modules
18478 @opindex private_bundle
18479 @opindex read_only_relocs
18480 @opindex sectalign
18481 @opindex sectobjectsymbols
18482 @opindex whyload
18483 @opindex seg1addr
18484 @opindex sectcreate
18485 @opindex sectobjectsymbols
18486 @opindex sectorder
18487 @opindex segaddr
18488 @opindex segs_read_only_addr
18489 @opindex segs_read_write_addr
18490 @opindex seg_addr_table
18491 @opindex seg_addr_table_filename
18492 @opindex seglinkedit
18493 @opindex segprot
18494 @opindex segs_read_only_addr
18495 @opindex segs_read_write_addr
18496 @opindex single_module
18497 @opindex static
18498 @opindex sub_library
18499 @opindex sub_umbrella
18500 @opindex twolevel_namespace
18501 @opindex umbrella
18502 @opindex undefined
18503 @opindex unexported_symbols_list
18504 @opindex weak_reference_mismatches
18505 @opindex whatsloaded
18506 These options are passed to the Darwin linker.  The Darwin linker man page
18507 describes them in detail.
18508 @end table
18510 @node DEC Alpha Options
18511 @subsection DEC Alpha Options
18513 These @samp{-m} options are defined for the DEC Alpha implementations:
18515 @table @gcctabopt
18516 @item -mno-soft-float
18517 @itemx -msoft-float
18518 @opindex mno-soft-float
18519 @opindex msoft-float
18520 Use (do not use) the hardware floating-point instructions for
18521 floating-point operations.  When @option{-msoft-float} is specified,
18522 functions in @file{libgcc.a} are used to perform floating-point
18523 operations.  Unless they are replaced by routines that emulate the
18524 floating-point operations, or compiled in such a way as to call such
18525 emulations routines, these routines issue floating-point
18526 operations.   If you are compiling for an Alpha without floating-point
18527 operations, you must ensure that the library is built so as not to call
18528 them.
18530 Note that Alpha implementations without floating-point operations are
18531 required to have floating-point registers.
18533 @item -mfp-reg
18534 @itemx -mno-fp-regs
18535 @opindex mfp-reg
18536 @opindex mno-fp-regs
18537 Generate code that uses (does not use) the floating-point register set.
18538 @option{-mno-fp-regs} implies @option{-msoft-float}.  If the floating-point
18539 register set is not used, floating-point operands are passed in integer
18540 registers as if they were integers and floating-point results are passed
18541 in @code{$0} instead of @code{$f0}.  This is a non-standard calling sequence,
18542 so any function with a floating-point argument or return value called by code
18543 compiled with @option{-mno-fp-regs} must also be compiled with that
18544 option.
18546 A typical use of this option is building a kernel that does not use,
18547 and hence need not save and restore, any floating-point registers.
18549 @item -mieee
18550 @opindex mieee
18551 The Alpha architecture implements floating-point hardware optimized for
18552 maximum performance.  It is mostly compliant with the IEEE floating-point
18553 standard.  However, for full compliance, software assistance is
18554 required.  This option generates code fully IEEE-compliant code
18555 @emph{except} that the @var{inexact-flag} is not maintained (see below).
18556 If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
18557 defined during compilation.  The resulting code is less efficient but is
18558 able to correctly support denormalized numbers and exceptional IEEE
18559 values such as not-a-number and plus/minus infinity.  Other Alpha
18560 compilers call this option @option{-ieee_with_no_inexact}.
18562 @item -mieee-with-inexact
18563 @opindex mieee-with-inexact
18564 This is like @option{-mieee} except the generated code also maintains
18565 the IEEE @var{inexact-flag}.  Turning on this option causes the
18566 generated code to implement fully-compliant IEEE math.  In addition to
18567 @code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
18568 macro.  On some Alpha implementations the resulting code may execute
18569 significantly slower than the code generated by default.  Since there is
18570 very little code that depends on the @var{inexact-flag}, you should
18571 normally not specify this option.  Other Alpha compilers call this
18572 option @option{-ieee_with_inexact}.
18574 @item -mfp-trap-mode=@var{trap-mode}
18575 @opindex mfp-trap-mode
18576 This option controls what floating-point related traps are enabled.
18577 Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
18578 The trap mode can be set to one of four values:
18580 @table @samp
18581 @item n
18582 This is the default (normal) setting.  The only traps that are enabled
18583 are the ones that cannot be disabled in software (e.g., division by zero
18584 trap).
18586 @item u
18587 In addition to the traps enabled by @samp{n}, underflow traps are enabled
18588 as well.
18590 @item su
18591 Like @samp{u}, but the instructions are marked to be safe for software
18592 completion (see Alpha architecture manual for details).
18594 @item sui
18595 Like @samp{su}, but inexact traps are enabled as well.
18596 @end table
18598 @item -mfp-rounding-mode=@var{rounding-mode}
18599 @opindex mfp-rounding-mode
18600 Selects the IEEE rounding mode.  Other Alpha compilers call this option
18601 @option{-fprm @var{rounding-mode}}.  The @var{rounding-mode} can be one
18604 @table @samp
18605 @item n
18606 Normal IEEE rounding mode.  Floating-point numbers are rounded towards
18607 the nearest machine number or towards the even machine number in case
18608 of a tie.
18610 @item m
18611 Round towards minus infinity.
18613 @item c
18614 Chopped rounding mode.  Floating-point numbers are rounded towards zero.
18616 @item d
18617 Dynamic rounding mode.  A field in the floating-point control register
18618 (@var{fpcr}, see Alpha architecture reference manual) controls the
18619 rounding mode in effect.  The C library initializes this register for
18620 rounding towards plus infinity.  Thus, unless your program modifies the
18621 @var{fpcr}, @samp{d} corresponds to round towards plus infinity.
18622 @end table
18624 @item -mtrap-precision=@var{trap-precision}
18625 @opindex mtrap-precision
18626 In the Alpha architecture, floating-point traps are imprecise.  This
18627 means without software assistance it is impossible to recover from a
18628 floating trap and program execution normally needs to be terminated.
18629 GCC can generate code that can assist operating system trap handlers
18630 in determining the exact location that caused a floating-point trap.
18631 Depending on the requirements of an application, different levels of
18632 precisions can be selected:
18634 @table @samp
18635 @item p
18636 Program precision.  This option is the default and means a trap handler
18637 can only identify which program caused a floating-point exception.
18639 @item f
18640 Function precision.  The trap handler can determine the function that
18641 caused a floating-point exception.
18643 @item i
18644 Instruction precision.  The trap handler can determine the exact
18645 instruction that caused a floating-point exception.
18646 @end table
18648 Other Alpha compilers provide the equivalent options called
18649 @option{-scope_safe} and @option{-resumption_safe}.
18651 @item -mieee-conformant
18652 @opindex mieee-conformant
18653 This option marks the generated code as IEEE conformant.  You must not
18654 use this option unless you also specify @option{-mtrap-precision=i} and either
18655 @option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}.  Its only effect
18656 is to emit the line @samp{.eflag 48} in the function prologue of the
18657 generated assembly file.
18659 @item -mbuild-constants
18660 @opindex mbuild-constants
18661 Normally GCC examines a 32- or 64-bit integer constant to
18662 see if it can construct it from smaller constants in two or three
18663 instructions.  If it cannot, it outputs the constant as a literal and
18664 generates code to load it from the data segment at run time.
18666 Use this option to require GCC to construct @emph{all} integer constants
18667 using code, even if it takes more instructions (the maximum is six).
18669 You typically use this option to build a shared library dynamic
18670 loader.  Itself a shared library, it must relocate itself in memory
18671 before it can find the variables and constants in its own data segment.
18673 @item -mbwx
18674 @itemx -mno-bwx
18675 @itemx -mcix
18676 @itemx -mno-cix
18677 @itemx -mfix
18678 @itemx -mno-fix
18679 @itemx -mmax
18680 @itemx -mno-max
18681 @opindex mbwx
18682 @opindex mno-bwx
18683 @opindex mcix
18684 @opindex mno-cix
18685 @opindex mfix
18686 @opindex mno-fix
18687 @opindex mmax
18688 @opindex mno-max
18689 Indicate whether GCC should generate code to use the optional BWX,
18690 CIX, FIX and MAX instruction sets.  The default is to use the instruction
18691 sets supported by the CPU type specified via @option{-mcpu=} option or that
18692 of the CPU on which GCC was built if none is specified.
18694 @item -mfloat-vax
18695 @itemx -mfloat-ieee
18696 @opindex mfloat-vax
18697 @opindex mfloat-ieee
18698 Generate code that uses (does not use) VAX F and G floating-point
18699 arithmetic instead of IEEE single and double precision.
18701 @item -mexplicit-relocs
18702 @itemx -mno-explicit-relocs
18703 @opindex mexplicit-relocs
18704 @opindex mno-explicit-relocs
18705 Older Alpha assemblers provided no way to generate symbol relocations
18706 except via assembler macros.  Use of these macros does not allow
18707 optimal instruction scheduling.  GNU binutils as of version 2.12
18708 supports a new syntax that allows the compiler to explicitly mark
18709 which relocations should apply to which instructions.  This option
18710 is mostly useful for debugging, as GCC detects the capabilities of
18711 the assembler when it is built and sets the default accordingly.
18713 @item -msmall-data
18714 @itemx -mlarge-data
18715 @opindex msmall-data
18716 @opindex mlarge-data
18717 When @option{-mexplicit-relocs} is in effect, static data is
18718 accessed via @dfn{gp-relative} relocations.  When @option{-msmall-data}
18719 is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
18720 (the @code{.sdata} and @code{.sbss} sections) and are accessed via
18721 16-bit relocations off of the @code{$gp} register.  This limits the
18722 size of the small data area to 64KB, but allows the variables to be
18723 directly accessed via a single instruction.
18725 The default is @option{-mlarge-data}.  With this option the data area
18726 is limited to just below 2GB@.  Programs that require more than 2GB of
18727 data must use @code{malloc} or @code{mmap} to allocate the data in the
18728 heap instead of in the program's data segment.
18730 When generating code for shared libraries, @option{-fpic} implies
18731 @option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
18733 @item -msmall-text
18734 @itemx -mlarge-text
18735 @opindex msmall-text
18736 @opindex mlarge-text
18737 When @option{-msmall-text} is used, the compiler assumes that the
18738 code of the entire program (or shared library) fits in 4MB, and is
18739 thus reachable with a branch instruction.  When @option{-msmall-data}
18740 is used, the compiler can assume that all local symbols share the
18741 same @code{$gp} value, and thus reduce the number of instructions
18742 required for a function call from 4 to 1.
18744 The default is @option{-mlarge-text}.
18746 @item -mcpu=@var{cpu_type}
18747 @opindex mcpu
18748 Set the instruction set and instruction scheduling parameters for
18749 machine type @var{cpu_type}.  You can specify either the @samp{EV}
18750 style name or the corresponding chip number.  GCC supports scheduling
18751 parameters for the EV4, EV5 and EV6 family of processors and
18752 chooses the default values for the instruction set from the processor
18753 you specify.  If you do not specify a processor type, GCC defaults
18754 to the processor on which the compiler was built.
18756 Supported values for @var{cpu_type} are
18758 @table @samp
18759 @item ev4
18760 @itemx ev45
18761 @itemx 21064
18762 Schedules as an EV4 and has no instruction set extensions.
18764 @item ev5
18765 @itemx 21164
18766 Schedules as an EV5 and has no instruction set extensions.
18768 @item ev56
18769 @itemx 21164a
18770 Schedules as an EV5 and supports the BWX extension.
18772 @item pca56
18773 @itemx 21164pc
18774 @itemx 21164PC
18775 Schedules as an EV5 and supports the BWX and MAX extensions.
18777 @item ev6
18778 @itemx 21264
18779 Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
18781 @item ev67
18782 @itemx 21264a
18783 Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
18784 @end table
18786 Native toolchains also support the value @samp{native},
18787 which selects the best architecture option for the host processor.
18788 @option{-mcpu=native} has no effect if GCC does not recognize
18789 the processor.
18791 @item -mtune=@var{cpu_type}
18792 @opindex mtune
18793 Set only the instruction scheduling parameters for machine type
18794 @var{cpu_type}.  The instruction set is not changed.
18796 Native toolchains also support the value @samp{native},
18797 which selects the best architecture option for the host processor.
18798 @option{-mtune=native} has no effect if GCC does not recognize
18799 the processor.
18801 @item -mmemory-latency=@var{time}
18802 @opindex mmemory-latency
18803 Sets the latency the scheduler should assume for typical memory
18804 references as seen by the application.  This number is highly
18805 dependent on the memory access patterns used by the application
18806 and the size of the external cache on the machine.
18808 Valid options for @var{time} are
18810 @table @samp
18811 @item @var{number}
18812 A decimal number representing clock cycles.
18814 @item L1
18815 @itemx L2
18816 @itemx L3
18817 @itemx main
18818 The compiler contains estimates of the number of clock cycles for
18819 ``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
18820 (also called Dcache, Scache, and Bcache), as well as to main memory.
18821 Note that L3 is only valid for EV5.
18823 @end table
18824 @end table
18826 @node FR30 Options
18827 @subsection FR30 Options
18828 @cindex FR30 Options
18830 These options are defined specifically for the FR30 port.
18832 @table @gcctabopt
18834 @item -msmall-model
18835 @opindex msmall-model
18836 Use the small address space model.  This can produce smaller code, but
18837 it does assume that all symbolic values and addresses fit into a
18838 20-bit range.
18840 @item -mno-lsim
18841 @opindex mno-lsim
18842 Assume that runtime support has been provided and so there is no need
18843 to include the simulator library (@file{libsim.a}) on the linker
18844 command line.
18846 @end table
18848 @node FT32 Options
18849 @subsection FT32 Options
18850 @cindex FT32 Options
18852 These options are defined specifically for the FT32 port.
18854 @table @gcctabopt
18856 @item -msim
18857 @opindex msim
18858 Specifies that the program will be run on the simulator.  This causes
18859 an alternate runtime startup and library to be linked.
18860 You must not use this option when generating programs that will run on
18861 real hardware; you must provide your own runtime library for whatever
18862 I/O functions are needed.
18864 @item -mlra
18865 @opindex mlra
18866 Enable Local Register Allocation.  This is still experimental for FT32,
18867 so by default the compiler uses standard reload.
18869 @item -mnodiv
18870 @opindex mnodiv
18871 Do not use div and mod instructions.
18873 @item -mft32b
18874 @opindex mft32b
18875 Enable use of the extended instructions of the FT32B processor.
18877 @item -mcompress
18878 @opindex mcompress
18879 Compress all code using the Ft32B code compression scheme.
18881 @item -mnopm
18882 @opindex  mnopm
18883 Do not generate code that reads program memory.
18885 @end table
18887 @node FRV Options
18888 @subsection FRV Options
18889 @cindex FRV Options
18891 @table @gcctabopt
18892 @item -mgpr-32
18893 @opindex mgpr-32
18895 Only use the first 32 general-purpose registers.
18897 @item -mgpr-64
18898 @opindex mgpr-64
18900 Use all 64 general-purpose registers.
18902 @item -mfpr-32
18903 @opindex mfpr-32
18905 Use only the first 32 floating-point registers.
18907 @item -mfpr-64
18908 @opindex mfpr-64
18910 Use all 64 floating-point registers.
18912 @item -mhard-float
18913 @opindex mhard-float
18915 Use hardware instructions for floating-point operations.
18917 @item -msoft-float
18918 @opindex msoft-float
18920 Use library routines for floating-point operations.
18922 @item -malloc-cc
18923 @opindex malloc-cc
18925 Dynamically allocate condition code registers.
18927 @item -mfixed-cc
18928 @opindex mfixed-cc
18930 Do not try to dynamically allocate condition code registers, only
18931 use @code{icc0} and @code{fcc0}.
18933 @item -mdword
18934 @opindex mdword
18936 Change ABI to use double word insns.
18938 @item -mno-dword
18939 @opindex mno-dword
18941 Do not use double word instructions.
18943 @item -mdouble
18944 @opindex mdouble
18946 Use floating-point double instructions.
18948 @item -mno-double
18949 @opindex mno-double
18951 Do not use floating-point double instructions.
18953 @item -mmedia
18954 @opindex mmedia
18956 Use media instructions.
18958 @item -mno-media
18959 @opindex mno-media
18961 Do not use media instructions.
18963 @item -mmuladd
18964 @opindex mmuladd
18966 Use multiply and add/subtract instructions.
18968 @item -mno-muladd
18969 @opindex mno-muladd
18971 Do not use multiply and add/subtract instructions.
18973 @item -mfdpic
18974 @opindex mfdpic
18976 Select the FDPIC ABI, which uses function descriptors to represent
18977 pointers to functions.  Without any PIC/PIE-related options, it
18978 implies @option{-fPIE}.  With @option{-fpic} or @option{-fpie}, it
18979 assumes GOT entries and small data are within a 12-bit range from the
18980 GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
18981 are computed with 32 bits.
18982 With a @samp{bfin-elf} target, this option implies @option{-msim}.
18984 @item -minline-plt
18985 @opindex minline-plt
18987 Enable inlining of PLT entries in function calls to functions that are
18988 not known to bind locally.  It has no effect without @option{-mfdpic}.
18989 It's enabled by default if optimizing for speed and compiling for
18990 shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
18991 optimization option such as @option{-O3} or above is present in the
18992 command line.
18994 @item -mTLS
18995 @opindex mTLS
18997 Assume a large TLS segment when generating thread-local code.
18999 @item -mtls
19000 @opindex mtls
19002 Do not assume a large TLS segment when generating thread-local code.
19004 @item -mgprel-ro
19005 @opindex mgprel-ro
19007 Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
19008 that is known to be in read-only sections.  It's enabled by default,
19009 except for @option{-fpic} or @option{-fpie}: even though it may help
19010 make the global offset table smaller, it trades 1 instruction for 4.
19011 With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
19012 one of which may be shared by multiple symbols, and it avoids the need
19013 for a GOT entry for the referenced symbol, so it's more likely to be a
19014 win.  If it is not, @option{-mno-gprel-ro} can be used to disable it.
19016 @item -multilib-library-pic
19017 @opindex multilib-library-pic
19019 Link with the (library, not FD) pic libraries.  It's implied by
19020 @option{-mlibrary-pic}, as well as by @option{-fPIC} and
19021 @option{-fpic} without @option{-mfdpic}.  You should never have to use
19022 it explicitly.
19024 @item -mlinked-fp
19025 @opindex mlinked-fp
19027 Follow the EABI requirement of always creating a frame pointer whenever
19028 a stack frame is allocated.  This option is enabled by default and can
19029 be disabled with @option{-mno-linked-fp}.
19031 @item -mlong-calls
19032 @opindex mlong-calls
19034 Use indirect addressing to call functions outside the current
19035 compilation unit.  This allows the functions to be placed anywhere
19036 within the 32-bit address space.
19038 @item -malign-labels
19039 @opindex malign-labels
19041 Try to align labels to an 8-byte boundary by inserting NOPs into the
19042 previous packet.  This option only has an effect when VLIW packing
19043 is enabled.  It doesn't create new packets; it merely adds NOPs to
19044 existing ones.
19046 @item -mlibrary-pic
19047 @opindex mlibrary-pic
19049 Generate position-independent EABI code.
19051 @item -macc-4
19052 @opindex macc-4
19054 Use only the first four media accumulator registers.
19056 @item -macc-8
19057 @opindex macc-8
19059 Use all eight media accumulator registers.
19061 @item -mpack
19062 @opindex mpack
19064 Pack VLIW instructions.
19066 @item -mno-pack
19067 @opindex mno-pack
19069 Do not pack VLIW instructions.
19071 @item -mno-eflags
19072 @opindex mno-eflags
19074 Do not mark ABI switches in e_flags.
19076 @item -mcond-move
19077 @opindex mcond-move
19079 Enable the use of conditional-move instructions (default).
19081 This switch is mainly for debugging the compiler and will likely be removed
19082 in a future version.
19084 @item -mno-cond-move
19085 @opindex mno-cond-move
19087 Disable the use of conditional-move instructions.
19089 This switch is mainly for debugging the compiler and will likely be removed
19090 in a future version.
19092 @item -mscc
19093 @opindex mscc
19095 Enable the use of conditional set instructions (default).
19097 This switch is mainly for debugging the compiler and will likely be removed
19098 in a future version.
19100 @item -mno-scc
19101 @opindex mno-scc
19103 Disable the use of conditional set instructions.
19105 This switch is mainly for debugging the compiler and will likely be removed
19106 in a future version.
19108 @item -mcond-exec
19109 @opindex mcond-exec
19111 Enable the use of conditional execution (default).
19113 This switch is mainly for debugging the compiler and will likely be removed
19114 in a future version.
19116 @item -mno-cond-exec
19117 @opindex mno-cond-exec
19119 Disable the use of conditional execution.
19121 This switch is mainly for debugging the compiler and will likely be removed
19122 in a future version.
19124 @item -mvliw-branch
19125 @opindex mvliw-branch
19127 Run a pass to pack branches into VLIW instructions (default).
19129 This switch is mainly for debugging the compiler and will likely be removed
19130 in a future version.
19132 @item -mno-vliw-branch
19133 @opindex mno-vliw-branch
19135 Do not run a pass to pack branches into VLIW instructions.
19137 This switch is mainly for debugging the compiler and will likely be removed
19138 in a future version.
19140 @item -mmulti-cond-exec
19141 @opindex mmulti-cond-exec
19143 Enable optimization of @code{&&} and @code{||} in conditional execution
19144 (default).
19146 This switch is mainly for debugging the compiler and will likely be removed
19147 in a future version.
19149 @item -mno-multi-cond-exec
19150 @opindex mno-multi-cond-exec
19152 Disable optimization of @code{&&} and @code{||} in conditional execution.
19154 This switch is mainly for debugging the compiler and will likely be removed
19155 in a future version.
19157 @item -mnested-cond-exec
19158 @opindex mnested-cond-exec
19160 Enable nested conditional execution optimizations (default).
19162 This switch is mainly for debugging the compiler and will likely be removed
19163 in a future version.
19165 @item -mno-nested-cond-exec
19166 @opindex mno-nested-cond-exec
19168 Disable nested conditional execution optimizations.
19170 This switch is mainly for debugging the compiler and will likely be removed
19171 in a future version.
19173 @item -moptimize-membar
19174 @opindex moptimize-membar
19176 This switch removes redundant @code{membar} instructions from the
19177 compiler-generated code.  It is enabled by default.
19179 @item -mno-optimize-membar
19180 @opindex mno-optimize-membar
19182 This switch disables the automatic removal of redundant @code{membar}
19183 instructions from the generated code.
19185 @item -mtomcat-stats
19186 @opindex mtomcat-stats
19188 Cause gas to print out tomcat statistics.
19190 @item -mcpu=@var{cpu}
19191 @opindex mcpu
19193 Select the processor type for which to generate code.  Possible values are
19194 @samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
19195 @samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
19197 @end table
19199 @node GNU/Linux Options
19200 @subsection GNU/Linux Options
19202 These @samp{-m} options are defined for GNU/Linux targets:
19204 @table @gcctabopt
19205 @item -mglibc
19206 @opindex mglibc
19207 Use the GNU C library.  This is the default except
19208 on @samp{*-*-linux-*uclibc*}, @samp{*-*-linux-*musl*} and
19209 @samp{*-*-linux-*android*} targets.
19211 @item -muclibc
19212 @opindex muclibc
19213 Use uClibc C library.  This is the default on
19214 @samp{*-*-linux-*uclibc*} targets.
19216 @item -mmusl
19217 @opindex mmusl
19218 Use the musl C library.  This is the default on
19219 @samp{*-*-linux-*musl*} targets.
19221 @item -mbionic
19222 @opindex mbionic
19223 Use Bionic C library.  This is the default on
19224 @samp{*-*-linux-*android*} targets.
19226 @item -mandroid
19227 @opindex mandroid
19228 Compile code compatible with Android platform.  This is the default on
19229 @samp{*-*-linux-*android*} targets.
19231 When compiling, this option enables @option{-mbionic}, @option{-fPIC},
19232 @option{-fno-exceptions} and @option{-fno-rtti} by default.  When linking,
19233 this option makes the GCC driver pass Android-specific options to the linker.
19234 Finally, this option causes the preprocessor macro @code{__ANDROID__}
19235 to be defined.
19237 @item -tno-android-cc
19238 @opindex tno-android-cc
19239 Disable compilation effects of @option{-mandroid}, i.e., do not enable
19240 @option{-mbionic}, @option{-fPIC}, @option{-fno-exceptions} and
19241 @option{-fno-rtti} by default.
19243 @item -tno-android-ld
19244 @opindex tno-android-ld
19245 Disable linking effects of @option{-mandroid}, i.e., pass standard Linux
19246 linking options to the linker.
19248 @end table
19250 @node H8/300 Options
19251 @subsection H8/300 Options
19253 These @samp{-m} options are defined for the H8/300 implementations:
19255 @table @gcctabopt
19256 @item -mrelax
19257 @opindex mrelax
19258 Shorten some address references at link time, when possible; uses the
19259 linker option @option{-relax}.  @xref{H8/300,, @code{ld} and the H8/300,
19260 ld, Using ld}, for a fuller description.
19262 @item -mh
19263 @opindex mh
19264 Generate code for the H8/300H@.
19266 @item -ms
19267 @opindex ms
19268 Generate code for the H8S@.
19270 @item -mn
19271 @opindex mn
19272 Generate code for the H8S and H8/300H in the normal mode.  This switch
19273 must be used either with @option{-mh} or @option{-ms}.
19275 @item -ms2600
19276 @opindex ms2600
19277 Generate code for the H8S/2600.  This switch must be used with @option{-ms}.
19279 @item -mexr
19280 @opindex mexr
19281 Extended registers are stored on stack before execution of function
19282 with monitor attribute. Default option is @option{-mexr}.
19283 This option is valid only for H8S targets.
19285 @item -mno-exr
19286 @opindex mno-exr
19287 Extended registers are not stored on stack before execution of function 
19288 with monitor attribute. Default option is @option{-mno-exr}. 
19289 This option is valid only for H8S targets.
19291 @item -mint32
19292 @opindex mint32
19293 Make @code{int} data 32 bits by default.
19295 @item -malign-300
19296 @opindex malign-300
19297 On the H8/300H and H8S, use the same alignment rules as for the H8/300.
19298 The default for the H8/300H and H8S is to align longs and floats on
19299 4-byte boundaries.
19300 @option{-malign-300} causes them to be aligned on 2-byte boundaries.
19301 This option has no effect on the H8/300.
19302 @end table
19304 @node HPPA Options
19305 @subsection HPPA Options
19306 @cindex HPPA Options
19308 These @samp{-m} options are defined for the HPPA family of computers:
19310 @table @gcctabopt
19311 @item -march=@var{architecture-type}
19312 @opindex march
19313 Generate code for the specified architecture.  The choices for
19314 @var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
19315 1.1, and @samp{2.0} for PA 2.0 processors.  Refer to
19316 @file{/usr/lib/sched.models} on an HP-UX system to determine the proper
19317 architecture option for your machine.  Code compiled for lower numbered
19318 architectures runs on higher numbered architectures, but not the
19319 other way around.
19321 @item -mpa-risc-1-0
19322 @itemx -mpa-risc-1-1
19323 @itemx -mpa-risc-2-0
19324 @opindex mpa-risc-1-0
19325 @opindex mpa-risc-1-1
19326 @opindex mpa-risc-2-0
19327 Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
19329 @item -mcaller-copies
19330 @opindex mcaller-copies
19331 The caller copies function arguments passed by hidden reference.  This
19332 option should be used with care as it is not compatible with the default
19333 32-bit runtime.  However, only aggregates larger than eight bytes are
19334 passed by hidden reference and the option provides better compatibility
19335 with OpenMP.
19337 @item -mjump-in-delay
19338 @opindex mjump-in-delay
19339 This option is ignored and provided for compatibility purposes only.
19341 @item -mdisable-fpregs
19342 @opindex mdisable-fpregs
19343 Prevent floating-point registers from being used in any manner.  This is
19344 necessary for compiling kernels that perform lazy context switching of
19345 floating-point registers.  If you use this option and attempt to perform
19346 floating-point operations, the compiler aborts.
19348 @item -mdisable-indexing
19349 @opindex mdisable-indexing
19350 Prevent the compiler from using indexing address modes.  This avoids some
19351 rather obscure problems when compiling MIG generated code under MACH@.
19353 @item -mno-space-regs
19354 @opindex mno-space-regs
19355 Generate code that assumes the target has no space registers.  This allows
19356 GCC to generate faster indirect calls and use unscaled index address modes.
19358 Such code is suitable for level 0 PA systems and kernels.
19360 @item -mfast-indirect-calls
19361 @opindex mfast-indirect-calls
19362 Generate code that assumes calls never cross space boundaries.  This
19363 allows GCC to emit code that performs faster indirect calls.
19365 This option does not work in the presence of shared libraries or nested
19366 functions.
19368 @item -mfixed-range=@var{register-range}
19369 @opindex mfixed-range
19370 Generate code treating the given register range as fixed registers.
19371 A fixed register is one that the register allocator cannot use.  This is
19372 useful when compiling kernel code.  A register range is specified as
19373 two registers separated by a dash.  Multiple register ranges can be
19374 specified separated by a comma.
19376 @item -mlong-load-store
19377 @opindex mlong-load-store
19378 Generate 3-instruction load and store sequences as sometimes required by
19379 the HP-UX 10 linker.  This is equivalent to the @samp{+k} option to
19380 the HP compilers.
19382 @item -mportable-runtime
19383 @opindex mportable-runtime
19384 Use the portable calling conventions proposed by HP for ELF systems.
19386 @item -mgas
19387 @opindex mgas
19388 Enable the use of assembler directives only GAS understands.
19390 @item -mschedule=@var{cpu-type}
19391 @opindex mschedule
19392 Schedule code according to the constraints for the machine type
19393 @var{cpu-type}.  The choices for @var{cpu-type} are @samp{700}
19394 @samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}.  Refer
19395 to @file{/usr/lib/sched.models} on an HP-UX system to determine the
19396 proper scheduling option for your machine.  The default scheduling is
19397 @samp{8000}.
19399 @item -mlinker-opt
19400 @opindex mlinker-opt
19401 Enable the optimization pass in the HP-UX linker.  Note this makes symbolic
19402 debugging impossible.  It also triggers a bug in the HP-UX 8 and HP-UX 9
19403 linkers in which they give bogus error messages when linking some programs.
19405 @item -msoft-float
19406 @opindex msoft-float
19407 Generate output containing library calls for floating point.
19408 @strong{Warning:} the requisite libraries are not available for all HPPA
19409 targets.  Normally the facilities of the machine's usual C compiler are
19410 used, but this cannot be done directly in cross-compilation.  You must make
19411 your own arrangements to provide suitable library functions for
19412 cross-compilation.
19414 @option{-msoft-float} changes the calling convention in the output file;
19415 therefore, it is only useful if you compile @emph{all} of a program with
19416 this option.  In particular, you need to compile @file{libgcc.a}, the
19417 library that comes with GCC, with @option{-msoft-float} in order for
19418 this to work.
19420 @item -msio
19421 @opindex msio
19422 Generate the predefine, @code{_SIO}, for server IO@.  The default is
19423 @option{-mwsio}.  This generates the predefines, @code{__hp9000s700},
19424 @code{__hp9000s700__} and @code{_WSIO}, for workstation IO@.  These
19425 options are available under HP-UX and HI-UX@.
19427 @item -mgnu-ld
19428 @opindex mgnu-ld
19429 Use options specific to GNU @command{ld}.
19430 This passes @option{-shared} to @command{ld} when
19431 building a shared library.  It is the default when GCC is configured,
19432 explicitly or implicitly, with the GNU linker.  This option does not
19433 affect which @command{ld} is called; it only changes what parameters
19434 are passed to that @command{ld}.
19435 The @command{ld} that is called is determined by the
19436 @option{--with-ld} configure option, GCC's program search path, and
19437 finally by the user's @env{PATH}.  The linker used by GCC can be printed
19438 using @samp{which `gcc -print-prog-name=ld`}.  This option is only available
19439 on the 64-bit HP-UX GCC, i.e.@: configured with @samp{hppa*64*-*-hpux*}.
19441 @item -mhp-ld
19442 @opindex mhp-ld
19443 Use options specific to HP @command{ld}.
19444 This passes @option{-b} to @command{ld} when building
19445 a shared library and passes @option{+Accept TypeMismatch} to @command{ld} on all
19446 links.  It is the default when GCC is configured, explicitly or
19447 implicitly, with the HP linker.  This option does not affect
19448 which @command{ld} is called; it only changes what parameters are passed to that
19449 @command{ld}.
19450 The @command{ld} that is called is determined by the @option{--with-ld}
19451 configure option, GCC's program search path, and finally by the user's
19452 @env{PATH}.  The linker used by GCC can be printed using @samp{which
19453 `gcc -print-prog-name=ld`}.  This option is only available on the 64-bit
19454 HP-UX GCC, i.e.@: configured with @samp{hppa*64*-*-hpux*}.
19456 @item -mlong-calls
19457 @opindex mno-long-calls
19458 Generate code that uses long call sequences.  This ensures that a call
19459 is always able to reach linker generated stubs.  The default is to generate
19460 long calls only when the distance from the call site to the beginning
19461 of the function or translation unit, as the case may be, exceeds a
19462 predefined limit set by the branch type being used.  The limits for
19463 normal calls are 7,600,000 and 240,000 bytes, respectively for the
19464 PA 2.0 and PA 1.X architectures.  Sibcalls are always limited at
19465 240,000 bytes.
19467 Distances are measured from the beginning of functions when using the
19468 @option{-ffunction-sections} option, or when using the @option{-mgas}
19469 and @option{-mno-portable-runtime} options together under HP-UX with
19470 the SOM linker.
19472 It is normally not desirable to use this option as it degrades
19473 performance.  However, it may be useful in large applications,
19474 particularly when partial linking is used to build the application.
19476 The types of long calls used depends on the capabilities of the
19477 assembler and linker, and the type of code being generated.  The
19478 impact on systems that support long absolute calls, and long pic
19479 symbol-difference or pc-relative calls should be relatively small.
19480 However, an indirect call is used on 32-bit ELF systems in pic code
19481 and it is quite long.
19483 @item -munix=@var{unix-std}
19484 @opindex march
19485 Generate compiler predefines and select a startfile for the specified
19486 UNIX standard.  The choices for @var{unix-std} are @samp{93}, @samp{95}
19487 and @samp{98}.  @samp{93} is supported on all HP-UX versions.  @samp{95}
19488 is available on HP-UX 10.10 and later.  @samp{98} is available on HP-UX
19489 11.11 and later.  The default values are @samp{93} for HP-UX 10.00,
19490 @samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
19491 and later.
19493 @option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
19494 @option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
19495 and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
19496 @option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
19497 @code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
19498 @code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
19500 It is @emph{important} to note that this option changes the interfaces
19501 for various library routines.  It also affects the operational behavior
19502 of the C library.  Thus, @emph{extreme} care is needed in using this
19503 option.
19505 Library code that is intended to operate with more than one UNIX
19506 standard must test, set and restore the variable @code{__xpg4_extended_mask}
19507 as appropriate.  Most GNU software doesn't provide this capability.
19509 @item -nolibdld
19510 @opindex nolibdld
19511 Suppress the generation of link options to search libdld.sl when the
19512 @option{-static} option is specified on HP-UX 10 and later.
19514 @item -static
19515 @opindex static
19516 The HP-UX implementation of setlocale in libc has a dependency on
19517 libdld.sl.  There isn't an archive version of libdld.sl.  Thus,
19518 when the @option{-static} option is specified, special link options
19519 are needed to resolve this dependency.
19521 On HP-UX 10 and later, the GCC driver adds the necessary options to
19522 link with libdld.sl when the @option{-static} option is specified.
19523 This causes the resulting binary to be dynamic.  On the 64-bit port,
19524 the linkers generate dynamic binaries by default in any case.  The
19525 @option{-nolibdld} option can be used to prevent the GCC driver from
19526 adding these link options.
19528 @item -threads
19529 @opindex threads
19530 Add support for multithreading with the @dfn{dce thread} library
19531 under HP-UX@.  This option sets flags for both the preprocessor and
19532 linker.
19533 @end table
19535 @node IA-64 Options
19536 @subsection IA-64 Options
19537 @cindex IA-64 Options
19539 These are the @samp{-m} options defined for the Intel IA-64 architecture.
19541 @table @gcctabopt
19542 @item -mbig-endian
19543 @opindex mbig-endian
19544 Generate code for a big-endian target.  This is the default for HP-UX@.
19546 @item -mlittle-endian
19547 @opindex mlittle-endian
19548 Generate code for a little-endian target.  This is the default for AIX5
19549 and GNU/Linux.
19551 @item -mgnu-as
19552 @itemx -mno-gnu-as
19553 @opindex mgnu-as
19554 @opindex mno-gnu-as
19555 Generate (or don't) code for the GNU assembler.  This is the default.
19556 @c Also, this is the default if the configure option @option{--with-gnu-as}
19557 @c is used.
19559 @item -mgnu-ld
19560 @itemx -mno-gnu-ld
19561 @opindex mgnu-ld
19562 @opindex mno-gnu-ld
19563 Generate (or don't) code for the GNU linker.  This is the default.
19564 @c Also, this is the default if the configure option @option{--with-gnu-ld}
19565 @c is used.
19567 @item -mno-pic
19568 @opindex mno-pic
19569 Generate code that does not use a global pointer register.  The result
19570 is not position independent code, and violates the IA-64 ABI@.
19572 @item -mvolatile-asm-stop
19573 @itemx -mno-volatile-asm-stop
19574 @opindex mvolatile-asm-stop
19575 @opindex mno-volatile-asm-stop
19576 Generate (or don't) a stop bit immediately before and after volatile asm
19577 statements.
19579 @item -mregister-names
19580 @itemx -mno-register-names
19581 @opindex mregister-names
19582 @opindex mno-register-names
19583 Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
19584 the stacked registers.  This may make assembler output more readable.
19586 @item -mno-sdata
19587 @itemx -msdata
19588 @opindex mno-sdata
19589 @opindex msdata
19590 Disable (or enable) optimizations that use the small data section.  This may
19591 be useful for working around optimizer bugs.
19593 @item -mconstant-gp
19594 @opindex mconstant-gp
19595 Generate code that uses a single constant global pointer value.  This is
19596 useful when compiling kernel code.
19598 @item -mauto-pic
19599 @opindex mauto-pic
19600 Generate code that is self-relocatable.  This implies @option{-mconstant-gp}.
19601 This is useful when compiling firmware code.
19603 @item -minline-float-divide-min-latency
19604 @opindex minline-float-divide-min-latency
19605 Generate code for inline divides of floating-point values
19606 using the minimum latency algorithm.
19608 @item -minline-float-divide-max-throughput
19609 @opindex minline-float-divide-max-throughput
19610 Generate code for inline divides of floating-point values
19611 using the maximum throughput algorithm.
19613 @item -mno-inline-float-divide
19614 @opindex mno-inline-float-divide
19615 Do not generate inline code for divides of floating-point values.
19617 @item -minline-int-divide-min-latency
19618 @opindex minline-int-divide-min-latency
19619 Generate code for inline divides of integer values
19620 using the minimum latency algorithm.
19622 @item -minline-int-divide-max-throughput
19623 @opindex minline-int-divide-max-throughput
19624 Generate code for inline divides of integer values
19625 using the maximum throughput algorithm.
19627 @item -mno-inline-int-divide
19628 @opindex mno-inline-int-divide
19629 Do not generate inline code for divides of integer values.
19631 @item -minline-sqrt-min-latency
19632 @opindex minline-sqrt-min-latency
19633 Generate code for inline square roots
19634 using the minimum latency algorithm.
19636 @item -minline-sqrt-max-throughput
19637 @opindex minline-sqrt-max-throughput
19638 Generate code for inline square roots
19639 using the maximum throughput algorithm.
19641 @item -mno-inline-sqrt
19642 @opindex mno-inline-sqrt
19643 Do not generate inline code for @code{sqrt}.
19645 @item -mfused-madd
19646 @itemx -mno-fused-madd
19647 @opindex mfused-madd
19648 @opindex mno-fused-madd
19649 Do (don't) generate code that uses the fused multiply/add or multiply/subtract
19650 instructions.  The default is to use these instructions.
19652 @item -mno-dwarf2-asm
19653 @itemx -mdwarf2-asm
19654 @opindex mno-dwarf2-asm
19655 @opindex mdwarf2-asm
19656 Don't (or do) generate assembler code for the DWARF line number debugging
19657 info.  This may be useful when not using the GNU assembler.
19659 @item -mearly-stop-bits
19660 @itemx -mno-early-stop-bits
19661 @opindex mearly-stop-bits
19662 @opindex mno-early-stop-bits
19663 Allow stop bits to be placed earlier than immediately preceding the
19664 instruction that triggered the stop bit.  This can improve instruction
19665 scheduling, but does not always do so.
19667 @item -mfixed-range=@var{register-range}
19668 @opindex mfixed-range
19669 Generate code treating the given register range as fixed registers.
19670 A fixed register is one that the register allocator cannot use.  This is
19671 useful when compiling kernel code.  A register range is specified as
19672 two registers separated by a dash.  Multiple register ranges can be
19673 specified separated by a comma.
19675 @item -mtls-size=@var{tls-size}
19676 @opindex mtls-size
19677 Specify bit size of immediate TLS offsets.  Valid values are 14, 22, and
19680 @item -mtune=@var{cpu-type}
19681 @opindex mtune
19682 Tune the instruction scheduling for a particular CPU, Valid values are
19683 @samp{itanium}, @samp{itanium1}, @samp{merced}, @samp{itanium2},
19684 and @samp{mckinley}.
19686 @item -milp32
19687 @itemx -mlp64
19688 @opindex milp32
19689 @opindex mlp64
19690 Generate code for a 32-bit or 64-bit environment.
19691 The 32-bit environment sets int, long and pointer to 32 bits.
19692 The 64-bit environment sets int to 32 bits and long and pointer
19693 to 64 bits.  These are HP-UX specific flags.
19695 @item -mno-sched-br-data-spec
19696 @itemx -msched-br-data-spec
19697 @opindex mno-sched-br-data-spec
19698 @opindex msched-br-data-spec
19699 (Dis/En)able data speculative scheduling before reload.
19700 This results in generation of @code{ld.a} instructions and
19701 the corresponding check instructions (@code{ld.c} / @code{chk.a}).
19702 The default setting is disabled.
19704 @item -msched-ar-data-spec
19705 @itemx -mno-sched-ar-data-spec
19706 @opindex msched-ar-data-spec
19707 @opindex mno-sched-ar-data-spec
19708 (En/Dis)able data speculative scheduling after reload.
19709 This results in generation of @code{ld.a} instructions and
19710 the corresponding check instructions (@code{ld.c} / @code{chk.a}).
19711 The default setting is enabled.
19713 @item -mno-sched-control-spec
19714 @itemx -msched-control-spec
19715 @opindex mno-sched-control-spec
19716 @opindex msched-control-spec
19717 (Dis/En)able control speculative scheduling.  This feature is
19718 available only during region scheduling (i.e.@: before reload).
19719 This results in generation of the @code{ld.s} instructions and
19720 the corresponding check instructions @code{chk.s}.
19721 The default setting is disabled.
19723 @item -msched-br-in-data-spec
19724 @itemx -mno-sched-br-in-data-spec
19725 @opindex msched-br-in-data-spec
19726 @opindex mno-sched-br-in-data-spec
19727 (En/Dis)able speculative scheduling of the instructions that
19728 are dependent on the data speculative loads before reload.
19729 This is effective only with @option{-msched-br-data-spec} enabled.
19730 The default setting is enabled.
19732 @item -msched-ar-in-data-spec
19733 @itemx -mno-sched-ar-in-data-spec
19734 @opindex msched-ar-in-data-spec
19735 @opindex mno-sched-ar-in-data-spec
19736 (En/Dis)able speculative scheduling of the instructions that
19737 are dependent on the data speculative loads after reload.
19738 This is effective only with @option{-msched-ar-data-spec} enabled.
19739 The default setting is enabled.
19741 @item -msched-in-control-spec
19742 @itemx -mno-sched-in-control-spec
19743 @opindex msched-in-control-spec
19744 @opindex mno-sched-in-control-spec
19745 (En/Dis)able speculative scheduling of the instructions that
19746 are dependent on the control speculative loads.
19747 This is effective only with @option{-msched-control-spec} enabled.
19748 The default setting is enabled.
19750 @item -mno-sched-prefer-non-data-spec-insns
19751 @itemx -msched-prefer-non-data-spec-insns
19752 @opindex mno-sched-prefer-non-data-spec-insns
19753 @opindex msched-prefer-non-data-spec-insns
19754 If enabled, data-speculative instructions are chosen for schedule
19755 only if there are no other choices at the moment.  This makes
19756 the use of the data speculation much more conservative.
19757 The default setting is disabled.
19759 @item -mno-sched-prefer-non-control-spec-insns
19760 @itemx -msched-prefer-non-control-spec-insns
19761 @opindex mno-sched-prefer-non-control-spec-insns
19762 @opindex msched-prefer-non-control-spec-insns
19763 If enabled, control-speculative instructions are chosen for schedule
19764 only if there are no other choices at the moment.  This makes
19765 the use of the control speculation much more conservative.
19766 The default setting is disabled.
19768 @item -mno-sched-count-spec-in-critical-path
19769 @itemx -msched-count-spec-in-critical-path
19770 @opindex mno-sched-count-spec-in-critical-path
19771 @opindex msched-count-spec-in-critical-path
19772 If enabled, speculative dependencies are considered during
19773 computation of the instructions priorities.  This makes the use of the
19774 speculation a bit more conservative.
19775 The default setting is disabled.
19777 @item -msched-spec-ldc
19778 @opindex msched-spec-ldc
19779 Use a simple data speculation check.  This option is on by default.
19781 @item -msched-control-spec-ldc
19782 @opindex msched-spec-ldc
19783 Use a simple check for control speculation.  This option is on by default.
19785 @item -msched-stop-bits-after-every-cycle
19786 @opindex msched-stop-bits-after-every-cycle
19787 Place a stop bit after every cycle when scheduling.  This option is on
19788 by default.
19790 @item -msched-fp-mem-deps-zero-cost
19791 @opindex msched-fp-mem-deps-zero-cost
19792 Assume that floating-point stores and loads are not likely to cause a conflict
19793 when placed into the same instruction group.  This option is disabled by
19794 default.
19796 @item -msel-sched-dont-check-control-spec
19797 @opindex msel-sched-dont-check-control-spec
19798 Generate checks for control speculation in selective scheduling.
19799 This flag is disabled by default.
19801 @item -msched-max-memory-insns=@var{max-insns}
19802 @opindex msched-max-memory-insns
19803 Limit on the number of memory insns per instruction group, giving lower
19804 priority to subsequent memory insns attempting to schedule in the same
19805 instruction group. Frequently useful to prevent cache bank conflicts.
19806 The default value is 1.
19808 @item -msched-max-memory-insns-hard-limit
19809 @opindex msched-max-memory-insns-hard-limit
19810 Makes the limit specified by @option{msched-max-memory-insns} a hard limit,
19811 disallowing more than that number in an instruction group.
19812 Otherwise, the limit is ``soft'', meaning that non-memory operations
19813 are preferred when the limit is reached, but memory operations may still
19814 be scheduled.
19816 @end table
19818 @node LM32 Options
19819 @subsection LM32 Options
19820 @cindex LM32 options
19822 These @option{-m} options are defined for the LatticeMico32 architecture:
19824 @table @gcctabopt
19825 @item -mbarrel-shift-enabled
19826 @opindex mbarrel-shift-enabled
19827 Enable barrel-shift instructions.
19829 @item -mdivide-enabled
19830 @opindex mdivide-enabled
19831 Enable divide and modulus instructions.
19833 @item -mmultiply-enabled
19834 @opindex multiply-enabled
19835 Enable multiply instructions.
19837 @item -msign-extend-enabled
19838 @opindex msign-extend-enabled
19839 Enable sign extend instructions.
19841 @item -muser-enabled
19842 @opindex muser-enabled
19843 Enable user-defined instructions.
19845 @end table
19847 @node M32C Options
19848 @subsection M32C Options
19849 @cindex M32C options
19851 @table @gcctabopt
19852 @item -mcpu=@var{name}
19853 @opindex mcpu=
19854 Select the CPU for which code is generated.  @var{name} may be one of
19855 @samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to
19856 /60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for
19857 the M32C/80 series.
19859 @item -msim
19860 @opindex msim
19861 Specifies that the program will be run on the simulator.  This causes
19862 an alternate runtime library to be linked in which supports, for
19863 example, file I/O@.  You must not use this option when generating
19864 programs that will run on real hardware; you must provide your own
19865 runtime library for whatever I/O functions are needed.
19867 @item -memregs=@var{number}
19868 @opindex memregs=
19869 Specifies the number of memory-based pseudo-registers GCC uses
19870 during code generation.  These pseudo-registers are used like real
19871 registers, so there is a tradeoff between GCC's ability to fit the
19872 code into available registers, and the performance penalty of using
19873 memory instead of registers.  Note that all modules in a program must
19874 be compiled with the same value for this option.  Because of that, you
19875 must not use this option with GCC's default runtime libraries.
19877 @end table
19879 @node M32R/D Options
19880 @subsection M32R/D Options
19881 @cindex M32R/D options
19883 These @option{-m} options are defined for Renesas M32R/D architectures:
19885 @table @gcctabopt
19886 @item -m32r2
19887 @opindex m32r2
19888 Generate code for the M32R/2@.
19890 @item -m32rx
19891 @opindex m32rx
19892 Generate code for the M32R/X@.
19894 @item -m32r
19895 @opindex m32r
19896 Generate code for the M32R@.  This is the default.
19898 @item -mmodel=small
19899 @opindex mmodel=small
19900 Assume all objects live in the lower 16MB of memory (so that their addresses
19901 can be loaded with the @code{ld24} instruction), and assume all subroutines
19902 are reachable with the @code{bl} instruction.
19903 This is the default.
19905 The addressability of a particular object can be set with the
19906 @code{model} attribute.
19908 @item -mmodel=medium
19909 @opindex mmodel=medium
19910 Assume objects may be anywhere in the 32-bit address space (the compiler
19911 generates @code{seth/add3} instructions to load their addresses), and
19912 assume all subroutines are reachable with the @code{bl} instruction.
19914 @item -mmodel=large
19915 @opindex mmodel=large
19916 Assume objects may be anywhere in the 32-bit address space (the compiler
19917 generates @code{seth/add3} instructions to load their addresses), and
19918 assume subroutines may not be reachable with the @code{bl} instruction
19919 (the compiler generates the much slower @code{seth/add3/jl}
19920 instruction sequence).
19922 @item -msdata=none
19923 @opindex msdata=none
19924 Disable use of the small data area.  Variables are put into
19925 one of @code{.data}, @code{.bss}, or @code{.rodata} (unless the
19926 @code{section} attribute has been specified).
19927 This is the default.
19929 The small data area consists of sections @code{.sdata} and @code{.sbss}.
19930 Objects may be explicitly put in the small data area with the
19931 @code{section} attribute using one of these sections.
19933 @item -msdata=sdata
19934 @opindex msdata=sdata
19935 Put small global and static data in the small data area, but do not
19936 generate special code to reference them.
19938 @item -msdata=use
19939 @opindex msdata=use
19940 Put small global and static data in the small data area, and generate
19941 special instructions to reference them.
19943 @item -G @var{num}
19944 @opindex G
19945 @cindex smaller data references
19946 Put global and static objects less than or equal to @var{num} bytes
19947 into the small data or BSS sections instead of the normal data or BSS
19948 sections.  The default value of @var{num} is 8.
19949 The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
19950 for this option to have any effect.
19952 All modules should be compiled with the same @option{-G @var{num}} value.
19953 Compiling with different values of @var{num} may or may not work; if it
19954 doesn't the linker gives an error message---incorrect code is not
19955 generated.
19957 @item -mdebug
19958 @opindex mdebug
19959 Makes the M32R-specific code in the compiler display some statistics
19960 that might help in debugging programs.
19962 @item -malign-loops
19963 @opindex malign-loops
19964 Align all loops to a 32-byte boundary.
19966 @item -mno-align-loops
19967 @opindex mno-align-loops
19968 Do not enforce a 32-byte alignment for loops.  This is the default.
19970 @item -missue-rate=@var{number}
19971 @opindex missue-rate=@var{number}
19972 Issue @var{number} instructions per cycle.  @var{number} can only be 1
19973 or 2.
19975 @item -mbranch-cost=@var{number}
19976 @opindex mbranch-cost=@var{number}
19977 @var{number} can only be 1 or 2.  If it is 1 then branches are
19978 preferred over conditional code, if it is 2, then the opposite applies.
19980 @item -mflush-trap=@var{number}
19981 @opindex mflush-trap=@var{number}
19982 Specifies the trap number to use to flush the cache.  The default is
19983 12.  Valid numbers are between 0 and 15 inclusive.
19985 @item -mno-flush-trap
19986 @opindex mno-flush-trap
19987 Specifies that the cache cannot be flushed by using a trap.
19989 @item -mflush-func=@var{name}
19990 @opindex mflush-func=@var{name}
19991 Specifies the name of the operating system function to call to flush
19992 the cache.  The default is @samp{_flush_cache}, but a function call
19993 is only used if a trap is not available.
19995 @item -mno-flush-func
19996 @opindex mno-flush-func
19997 Indicates that there is no OS function for flushing the cache.
19999 @end table
20001 @node M680x0 Options
20002 @subsection M680x0 Options
20003 @cindex M680x0 options
20005 These are the @samp{-m} options defined for M680x0 and ColdFire processors.
20006 The default settings depend on which architecture was selected when
20007 the compiler was configured; the defaults for the most common choices
20008 are given below.
20010 @table @gcctabopt
20011 @item -march=@var{arch}
20012 @opindex march
20013 Generate code for a specific M680x0 or ColdFire instruction set
20014 architecture.  Permissible values of @var{arch} for M680x0
20015 architectures are: @samp{68000}, @samp{68010}, @samp{68020},
20016 @samp{68030}, @samp{68040}, @samp{68060} and @samp{cpu32}.  ColdFire
20017 architectures are selected according to Freescale's ISA classification
20018 and the permissible values are: @samp{isaa}, @samp{isaaplus},
20019 @samp{isab} and @samp{isac}.
20021 GCC defines a macro @code{__mcf@var{arch}__} whenever it is generating
20022 code for a ColdFire target.  The @var{arch} in this macro is one of the
20023 @option{-march} arguments given above.
20025 When used together, @option{-march} and @option{-mtune} select code
20026 that runs on a family of similar processors but that is optimized
20027 for a particular microarchitecture.
20029 @item -mcpu=@var{cpu}
20030 @opindex mcpu
20031 Generate code for a specific M680x0 or ColdFire processor.
20032 The M680x0 @var{cpu}s are: @samp{68000}, @samp{68010}, @samp{68020},
20033 @samp{68030}, @samp{68040}, @samp{68060}, @samp{68302}, @samp{68332}
20034 and @samp{cpu32}.  The ColdFire @var{cpu}s are given by the table
20035 below, which also classifies the CPUs into families:
20037 @multitable @columnfractions 0.20 0.80
20038 @item @strong{Family} @tab @strong{@samp{-mcpu} arguments}
20039 @item @samp{51} @tab @samp{51} @samp{51ac} @samp{51ag} @samp{51cn} @samp{51em} @samp{51je} @samp{51jf} @samp{51jg} @samp{51jm} @samp{51mm} @samp{51qe} @samp{51qm}
20040 @item @samp{5206} @tab @samp{5202} @samp{5204} @samp{5206}
20041 @item @samp{5206e} @tab @samp{5206e}
20042 @item @samp{5208} @tab @samp{5207} @samp{5208}
20043 @item @samp{5211a} @tab @samp{5210a} @samp{5211a}
20044 @item @samp{5213} @tab @samp{5211} @samp{5212} @samp{5213}
20045 @item @samp{5216} @tab @samp{5214} @samp{5216}
20046 @item @samp{52235} @tab @samp{52230} @samp{52231} @samp{52232} @samp{52233} @samp{52234} @samp{52235}
20047 @item @samp{5225} @tab @samp{5224} @samp{5225}
20048 @item @samp{52259} @tab @samp{52252} @samp{52254} @samp{52255} @samp{52256} @samp{52258} @samp{52259}
20049 @item @samp{5235} @tab @samp{5232} @samp{5233} @samp{5234} @samp{5235} @samp{523x}
20050 @item @samp{5249} @tab @samp{5249}
20051 @item @samp{5250} @tab @samp{5250}
20052 @item @samp{5271} @tab @samp{5270} @samp{5271}
20053 @item @samp{5272} @tab @samp{5272}
20054 @item @samp{5275} @tab @samp{5274} @samp{5275}
20055 @item @samp{5282} @tab @samp{5280} @samp{5281} @samp{5282} @samp{528x}
20056 @item @samp{53017} @tab @samp{53011} @samp{53012} @samp{53013} @samp{53014} @samp{53015} @samp{53016} @samp{53017}
20057 @item @samp{5307} @tab @samp{5307}
20058 @item @samp{5329} @tab @samp{5327} @samp{5328} @samp{5329} @samp{532x}
20059 @item @samp{5373} @tab @samp{5372} @samp{5373} @samp{537x}
20060 @item @samp{5407} @tab @samp{5407}
20061 @item @samp{5475} @tab @samp{5470} @samp{5471} @samp{5472} @samp{5473} @samp{5474} @samp{5475} @samp{547x} @samp{5480} @samp{5481} @samp{5482} @samp{5483} @samp{5484} @samp{5485}
20062 @end multitable
20064 @option{-mcpu=@var{cpu}} overrides @option{-march=@var{arch}} if
20065 @var{arch} is compatible with @var{cpu}.  Other combinations of
20066 @option{-mcpu} and @option{-march} are rejected.
20068 GCC defines the macro @code{__mcf_cpu_@var{cpu}} when ColdFire target
20069 @var{cpu} is selected.  It also defines @code{__mcf_family_@var{family}},
20070 where the value of @var{family} is given by the table above.
20072 @item -mtune=@var{tune}
20073 @opindex mtune
20074 Tune the code for a particular microarchitecture within the
20075 constraints set by @option{-march} and @option{-mcpu}.
20076 The M680x0 microarchitectures are: @samp{68000}, @samp{68010},
20077 @samp{68020}, @samp{68030}, @samp{68040}, @samp{68060}
20078 and @samp{cpu32}.  The ColdFire microarchitectures
20079 are: @samp{cfv1}, @samp{cfv2}, @samp{cfv3}, @samp{cfv4} and @samp{cfv4e}.
20081 You can also use @option{-mtune=68020-40} for code that needs
20082 to run relatively well on 68020, 68030 and 68040 targets.
20083 @option{-mtune=68020-60} is similar but includes 68060 targets
20084 as well.  These two options select the same tuning decisions as
20085 @option{-m68020-40} and @option{-m68020-60} respectively.
20087 GCC defines the macros @code{__mc@var{arch}} and @code{__mc@var{arch}__}
20088 when tuning for 680x0 architecture @var{arch}.  It also defines
20089 @code{mc@var{arch}} unless either @option{-ansi} or a non-GNU @option{-std}
20090 option is used.  If GCC is tuning for a range of architectures,
20091 as selected by @option{-mtune=68020-40} or @option{-mtune=68020-60},
20092 it defines the macros for every architecture in the range.
20094 GCC also defines the macro @code{__m@var{uarch}__} when tuning for
20095 ColdFire microarchitecture @var{uarch}, where @var{uarch} is one
20096 of the arguments given above.
20098 @item -m68000
20099 @itemx -mc68000
20100 @opindex m68000
20101 @opindex mc68000
20102 Generate output for a 68000.  This is the default
20103 when the compiler is configured for 68000-based systems.
20104 It is equivalent to @option{-march=68000}.
20106 Use this option for microcontrollers with a 68000 or EC000 core,
20107 including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
20109 @item -m68010
20110 @opindex m68010
20111 Generate output for a 68010.  This is the default
20112 when the compiler is configured for 68010-based systems.
20113 It is equivalent to @option{-march=68010}.
20115 @item -m68020
20116 @itemx -mc68020
20117 @opindex m68020
20118 @opindex mc68020
20119 Generate output for a 68020.  This is the default
20120 when the compiler is configured for 68020-based systems.
20121 It is equivalent to @option{-march=68020}.
20123 @item -m68030
20124 @opindex m68030
20125 Generate output for a 68030.  This is the default when the compiler is
20126 configured for 68030-based systems.  It is equivalent to
20127 @option{-march=68030}.
20129 @item -m68040
20130 @opindex m68040
20131 Generate output for a 68040.  This is the default when the compiler is
20132 configured for 68040-based systems.  It is equivalent to
20133 @option{-march=68040}.
20135 This option inhibits the use of 68881/68882 instructions that have to be
20136 emulated by software on the 68040.  Use this option if your 68040 does not
20137 have code to emulate those instructions.
20139 @item -m68060
20140 @opindex m68060
20141 Generate output for a 68060.  This is the default when the compiler is
20142 configured for 68060-based systems.  It is equivalent to
20143 @option{-march=68060}.
20145 This option inhibits the use of 68020 and 68881/68882 instructions that
20146 have to be emulated by software on the 68060.  Use this option if your 68060
20147 does not have code to emulate those instructions.
20149 @item -mcpu32
20150 @opindex mcpu32
20151 Generate output for a CPU32.  This is the default
20152 when the compiler is configured for CPU32-based systems.
20153 It is equivalent to @option{-march=cpu32}.
20155 Use this option for microcontrollers with a
20156 CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
20157 68336, 68340, 68341, 68349 and 68360.
20159 @item -m5200
20160 @opindex m5200
20161 Generate output for a 520X ColdFire CPU@.  This is the default
20162 when the compiler is configured for 520X-based systems.
20163 It is equivalent to @option{-mcpu=5206}, and is now deprecated
20164 in favor of that option.
20166 Use this option for microcontroller with a 5200 core, including
20167 the MCF5202, MCF5203, MCF5204 and MCF5206.
20169 @item -m5206e
20170 @opindex m5206e
20171 Generate output for a 5206e ColdFire CPU@.  The option is now
20172 deprecated in favor of the equivalent @option{-mcpu=5206e}.
20174 @item -m528x
20175 @opindex m528x
20176 Generate output for a member of the ColdFire 528X family.
20177 The option is now deprecated in favor of the equivalent
20178 @option{-mcpu=528x}.
20180 @item -m5307
20181 @opindex m5307
20182 Generate output for a ColdFire 5307 CPU@.  The option is now deprecated
20183 in favor of the equivalent @option{-mcpu=5307}.
20185 @item -m5407
20186 @opindex m5407
20187 Generate output for a ColdFire 5407 CPU@.  The option is now deprecated
20188 in favor of the equivalent @option{-mcpu=5407}.
20190 @item -mcfv4e
20191 @opindex mcfv4e
20192 Generate output for a ColdFire V4e family CPU (e.g.@: 547x/548x).
20193 This includes use of hardware floating-point instructions.
20194 The option is equivalent to @option{-mcpu=547x}, and is now
20195 deprecated in favor of that option.
20197 @item -m68020-40
20198 @opindex m68020-40
20199 Generate output for a 68040, without using any of the new instructions.
20200 This results in code that can run relatively efficiently on either a
20201 68020/68881 or a 68030 or a 68040.  The generated code does use the
20202 68881 instructions that are emulated on the 68040.
20204 The option is equivalent to @option{-march=68020} @option{-mtune=68020-40}.
20206 @item -m68020-60
20207 @opindex m68020-60
20208 Generate output for a 68060, without using any of the new instructions.
20209 This results in code that can run relatively efficiently on either a
20210 68020/68881 or a 68030 or a 68040.  The generated code does use the
20211 68881 instructions that are emulated on the 68060.
20213 The option is equivalent to @option{-march=68020} @option{-mtune=68020-60}.
20215 @item -mhard-float
20216 @itemx -m68881
20217 @opindex mhard-float
20218 @opindex m68881
20219 Generate floating-point instructions.  This is the default for 68020
20220 and above, and for ColdFire devices that have an FPU@.  It defines the
20221 macro @code{__HAVE_68881__} on M680x0 targets and @code{__mcffpu__}
20222 on ColdFire targets.
20224 @item -msoft-float
20225 @opindex msoft-float
20226 Do not generate floating-point instructions; use library calls instead.
20227 This is the default for 68000, 68010, and 68832 targets.  It is also
20228 the default for ColdFire devices that have no FPU.
20230 @item -mdiv
20231 @itemx -mno-div
20232 @opindex mdiv
20233 @opindex mno-div
20234 Generate (do not generate) ColdFire hardware divide and remainder
20235 instructions.  If @option{-march} is used without @option{-mcpu},
20236 the default is ``on'' for ColdFire architectures and ``off'' for M680x0
20237 architectures.  Otherwise, the default is taken from the target CPU
20238 (either the default CPU, or the one specified by @option{-mcpu}).  For
20239 example, the default is ``off'' for @option{-mcpu=5206} and ``on'' for
20240 @option{-mcpu=5206e}.
20242 GCC defines the macro @code{__mcfhwdiv__} when this option is enabled.
20244 @item -mshort
20245 @opindex mshort
20246 Consider type @code{int} to be 16 bits wide, like @code{short int}.
20247 Additionally, parameters passed on the stack are also aligned to a
20248 16-bit boundary even on targets whose API mandates promotion to 32-bit.
20250 @item -mno-short
20251 @opindex mno-short
20252 Do not consider type @code{int} to be 16 bits wide.  This is the default.
20254 @item -mnobitfield
20255 @itemx -mno-bitfield
20256 @opindex mnobitfield
20257 @opindex mno-bitfield
20258 Do not use the bit-field instructions.  The @option{-m68000}, @option{-mcpu32}
20259 and @option{-m5200} options imply @w{@option{-mnobitfield}}.
20261 @item -mbitfield
20262 @opindex mbitfield
20263 Do use the bit-field instructions.  The @option{-m68020} option implies
20264 @option{-mbitfield}.  This is the default if you use a configuration
20265 designed for a 68020.
20267 @item -mrtd
20268 @opindex mrtd
20269 Use a different function-calling convention, in which functions
20270 that take a fixed number of arguments return with the @code{rtd}
20271 instruction, which pops their arguments while returning.  This
20272 saves one instruction in the caller since there is no need to pop
20273 the arguments there.
20275 This calling convention is incompatible with the one normally
20276 used on Unix, so you cannot use it if you need to call libraries
20277 compiled with the Unix compiler.
20279 Also, you must provide function prototypes for all functions that
20280 take variable numbers of arguments (including @code{printf});
20281 otherwise incorrect code is generated for calls to those
20282 functions.
20284 In addition, seriously incorrect code results if you call a
20285 function with too many arguments.  (Normally, extra arguments are
20286 harmlessly ignored.)
20288 The @code{rtd} instruction is supported by the 68010, 68020, 68030,
20289 68040, 68060 and CPU32 processors, but not by the 68000 or 5200.
20291 @item -mno-rtd
20292 @opindex mno-rtd
20293 Do not use the calling conventions selected by @option{-mrtd}.
20294 This is the default.
20296 @item -malign-int
20297 @itemx -mno-align-int
20298 @opindex malign-int
20299 @opindex mno-align-int
20300 Control whether GCC aligns @code{int}, @code{long}, @code{long long},
20301 @code{float}, @code{double}, and @code{long double} variables on a 32-bit
20302 boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
20303 Aligning variables on 32-bit boundaries produces code that runs somewhat
20304 faster on processors with 32-bit busses at the expense of more memory.
20306 @strong{Warning:} if you use the @option{-malign-int} switch, GCC
20307 aligns structures containing the above types differently than
20308 most published application binary interface specifications for the m68k.
20310 @item -mpcrel
20311 @opindex mpcrel
20312 Use the pc-relative addressing mode of the 68000 directly, instead of
20313 using a global offset table.  At present, this option implies @option{-fpic},
20314 allowing at most a 16-bit offset for pc-relative addressing.  @option{-fPIC} is
20315 not presently supported with @option{-mpcrel}, though this could be supported for
20316 68020 and higher processors.
20318 @item -mno-strict-align
20319 @itemx -mstrict-align
20320 @opindex mno-strict-align
20321 @opindex mstrict-align
20322 Do not (do) assume that unaligned memory references are handled by
20323 the system.
20325 @item -msep-data
20326 Generate code that allows the data segment to be located in a different
20327 area of memory from the text segment.  This allows for execute-in-place in
20328 an environment without virtual memory management.  This option implies
20329 @option{-fPIC}.
20331 @item -mno-sep-data
20332 Generate code that assumes that the data segment follows the text segment.
20333 This is the default.
20335 @item -mid-shared-library
20336 Generate code that supports shared libraries via the library ID method.
20337 This allows for execute-in-place and shared libraries in an environment
20338 without virtual memory management.  This option implies @option{-fPIC}.
20340 @item -mno-id-shared-library
20341 Generate code that doesn't assume ID-based shared libraries are being used.
20342 This is the default.
20344 @item -mshared-library-id=n
20345 Specifies the identification number of the ID-based shared library being
20346 compiled.  Specifying a value of 0 generates more compact code; specifying
20347 other values forces the allocation of that number to the current
20348 library, but is no more space- or time-efficient than omitting this option.
20350 @item -mxgot
20351 @itemx -mno-xgot
20352 @opindex mxgot
20353 @opindex mno-xgot
20354 When generating position-independent code for ColdFire, generate code
20355 that works if the GOT has more than 8192 entries.  This code is
20356 larger and slower than code generated without this option.  On M680x0
20357 processors, this option is not needed; @option{-fPIC} suffices.
20359 GCC normally uses a single instruction to load values from the GOT@.
20360 While this is relatively efficient, it only works if the GOT
20361 is smaller than about 64k.  Anything larger causes the linker
20362 to report an error such as:
20364 @cindex relocation truncated to fit (ColdFire)
20365 @smallexample
20366 relocation truncated to fit: R_68K_GOT16O foobar
20367 @end smallexample
20369 If this happens, you should recompile your code with @option{-mxgot}.
20370 It should then work with very large GOTs.  However, code generated with
20371 @option{-mxgot} is less efficient, since it takes 4 instructions to fetch
20372 the value of a global symbol.
20374 Note that some linkers, including newer versions of the GNU linker,
20375 can create multiple GOTs and sort GOT entries.  If you have such a linker,
20376 you should only need to use @option{-mxgot} when compiling a single
20377 object file that accesses more than 8192 GOT entries.  Very few do.
20379 These options have no effect unless GCC is generating
20380 position-independent code.
20382 @item -mlong-jump-table-offsets
20383 @opindex mlong-jump-table-offsets
20384 Use 32-bit offsets in @code{switch} tables.  The default is to use
20385 16-bit offsets.
20387 @end table
20389 @node MCore Options
20390 @subsection MCore Options
20391 @cindex MCore options
20393 These are the @samp{-m} options defined for the Motorola M*Core
20394 processors.
20396 @table @gcctabopt
20398 @item -mhardlit
20399 @itemx -mno-hardlit
20400 @opindex mhardlit
20401 @opindex mno-hardlit
20402 Inline constants into the code stream if it can be done in two
20403 instructions or less.
20405 @item -mdiv
20406 @itemx -mno-div
20407 @opindex mdiv
20408 @opindex mno-div
20409 Use the divide instruction.  (Enabled by default).
20411 @item -mrelax-immediate
20412 @itemx -mno-relax-immediate
20413 @opindex mrelax-immediate
20414 @opindex mno-relax-immediate
20415 Allow arbitrary-sized immediates in bit operations.
20417 @item -mwide-bitfields
20418 @itemx -mno-wide-bitfields
20419 @opindex mwide-bitfields
20420 @opindex mno-wide-bitfields
20421 Always treat bit-fields as @code{int}-sized.
20423 @item -m4byte-functions
20424 @itemx -mno-4byte-functions
20425 @opindex m4byte-functions
20426 @opindex mno-4byte-functions
20427 Force all functions to be aligned to a 4-byte boundary.
20429 @item -mcallgraph-data
20430 @itemx -mno-callgraph-data
20431 @opindex mcallgraph-data
20432 @opindex mno-callgraph-data
20433 Emit callgraph information.
20435 @item -mslow-bytes
20436 @itemx -mno-slow-bytes
20437 @opindex mslow-bytes
20438 @opindex mno-slow-bytes
20439 Prefer word access when reading byte quantities.
20441 @item -mlittle-endian
20442 @itemx -mbig-endian
20443 @opindex mlittle-endian
20444 @opindex mbig-endian
20445 Generate code for a little-endian target.
20447 @item -m210
20448 @itemx -m340
20449 @opindex m210
20450 @opindex m340
20451 Generate code for the 210 processor.
20453 @item -mno-lsim
20454 @opindex mno-lsim
20455 Assume that runtime support has been provided and so omit the
20456 simulator library (@file{libsim.a)} from the linker command line.
20458 @item -mstack-increment=@var{size}
20459 @opindex mstack-increment
20460 Set the maximum amount for a single stack increment operation.  Large
20461 values can increase the speed of programs that contain functions
20462 that need a large amount of stack space, but they can also trigger a
20463 segmentation fault if the stack is extended too much.  The default
20464 value is 0x1000.
20466 @end table
20468 @node MeP Options
20469 @subsection MeP Options
20470 @cindex MeP options
20472 @table @gcctabopt
20474 @item -mabsdiff
20475 @opindex mabsdiff
20476 Enables the @code{abs} instruction, which is the absolute difference
20477 between two registers.
20479 @item -mall-opts
20480 @opindex mall-opts
20481 Enables all the optional instructions---average, multiply, divide, bit
20482 operations, leading zero, absolute difference, min/max, clip, and
20483 saturation.
20486 @item -maverage
20487 @opindex maverage
20488 Enables the @code{ave} instruction, which computes the average of two
20489 registers.
20491 @item -mbased=@var{n}
20492 @opindex mbased=
20493 Variables of size @var{n} bytes or smaller are placed in the
20494 @code{.based} section by default.  Based variables use the @code{$tp}
20495 register as a base register, and there is a 128-byte limit to the
20496 @code{.based} section.
20498 @item -mbitops
20499 @opindex mbitops
20500 Enables the bit operation instructions---bit test (@code{btstm}), set
20501 (@code{bsetm}), clear (@code{bclrm}), invert (@code{bnotm}), and
20502 test-and-set (@code{tas}).
20504 @item -mc=@var{name}
20505 @opindex mc=
20506 Selects which section constant data is placed in.  @var{name} may
20507 be @samp{tiny}, @samp{near}, or @samp{far}.
20509 @item -mclip
20510 @opindex mclip
20511 Enables the @code{clip} instruction.  Note that @option{-mclip} is not
20512 useful unless you also provide @option{-mminmax}.
20514 @item -mconfig=@var{name}
20515 @opindex mconfig=
20516 Selects one of the built-in core configurations.  Each MeP chip has
20517 one or more modules in it; each module has a core CPU and a variety of
20518 coprocessors, optional instructions, and peripherals.  The
20519 @code{MeP-Integrator} tool, not part of GCC, provides these
20520 configurations through this option; using this option is the same as
20521 using all the corresponding command-line options.  The default
20522 configuration is @samp{default}.
20524 @item -mcop
20525 @opindex mcop
20526 Enables the coprocessor instructions.  By default, this is a 32-bit
20527 coprocessor.  Note that the coprocessor is normally enabled via the
20528 @option{-mconfig=} option.
20530 @item -mcop32
20531 @opindex mcop32
20532 Enables the 32-bit coprocessor's instructions.
20534 @item -mcop64
20535 @opindex mcop64
20536 Enables the 64-bit coprocessor's instructions.
20538 @item -mivc2
20539 @opindex mivc2
20540 Enables IVC2 scheduling.  IVC2 is a 64-bit VLIW coprocessor.
20542 @item -mdc
20543 @opindex mdc
20544 Causes constant variables to be placed in the @code{.near} section.
20546 @item -mdiv
20547 @opindex mdiv
20548 Enables the @code{div} and @code{divu} instructions.
20550 @item -meb
20551 @opindex meb
20552 Generate big-endian code.
20554 @item -mel
20555 @opindex mel
20556 Generate little-endian code.
20558 @item -mio-volatile
20559 @opindex mio-volatile
20560 Tells the compiler that any variable marked with the @code{io}
20561 attribute is to be considered volatile.
20563 @item -ml
20564 @opindex ml
20565 Causes variables to be assigned to the @code{.far} section by default.
20567 @item -mleadz
20568 @opindex mleadz
20569 Enables the @code{leadz} (leading zero) instruction.
20571 @item -mm
20572 @opindex mm
20573 Causes variables to be assigned to the @code{.near} section by default.
20575 @item -mminmax
20576 @opindex mminmax
20577 Enables the @code{min} and @code{max} instructions.
20579 @item -mmult
20580 @opindex mmult
20581 Enables the multiplication and multiply-accumulate instructions.
20583 @item -mno-opts
20584 @opindex mno-opts
20585 Disables all the optional instructions enabled by @option{-mall-opts}.
20587 @item -mrepeat
20588 @opindex mrepeat
20589 Enables the @code{repeat} and @code{erepeat} instructions, used for
20590 low-overhead looping.
20592 @item -ms
20593 @opindex ms
20594 Causes all variables to default to the @code{.tiny} section.  Note
20595 that there is a 65536-byte limit to this section.  Accesses to these
20596 variables use the @code{%gp} base register.
20598 @item -msatur
20599 @opindex msatur
20600 Enables the saturation instructions.  Note that the compiler does not
20601 currently generate these itself, but this option is included for
20602 compatibility with other tools, like @code{as}.
20604 @item -msdram
20605 @opindex msdram
20606 Link the SDRAM-based runtime instead of the default ROM-based runtime.
20608 @item -msim
20609 @opindex msim
20610 Link the simulator run-time libraries.
20612 @item -msimnovec
20613 @opindex msimnovec
20614 Link the simulator runtime libraries, excluding built-in support
20615 for reset and exception vectors and tables.
20617 @item -mtf
20618 @opindex mtf
20619 Causes all functions to default to the @code{.far} section.  Without
20620 this option, functions default to the @code{.near} section.
20622 @item -mtiny=@var{n}
20623 @opindex mtiny=
20624 Variables that are @var{n} bytes or smaller are allocated to the
20625 @code{.tiny} section.  These variables use the @code{$gp} base
20626 register.  The default for this option is 4, but note that there's a
20627 65536-byte limit to the @code{.tiny} section.
20629 @end table
20631 @node MicroBlaze Options
20632 @subsection MicroBlaze Options
20633 @cindex MicroBlaze Options
20635 @table @gcctabopt
20637 @item -msoft-float
20638 @opindex msoft-float
20639 Use software emulation for floating point (default).
20641 @item -mhard-float
20642 @opindex mhard-float
20643 Use hardware floating-point instructions.
20645 @item -mmemcpy
20646 @opindex mmemcpy
20647 Do not optimize block moves, use @code{memcpy}.
20649 @item -mno-clearbss
20650 @opindex mno-clearbss
20651 This option is deprecated.  Use @option{-fno-zero-initialized-in-bss} instead.
20653 @item -mcpu=@var{cpu-type}
20654 @opindex mcpu=
20655 Use features of, and schedule code for, the given CPU.
20656 Supported values are in the format @samp{v@var{X}.@var{YY}.@var{Z}},
20657 where @var{X} is a major version, @var{YY} is the minor version, and
20658 @var{Z} is compatibility code.  Example values are @samp{v3.00.a},
20659 @samp{v4.00.b}, @samp{v5.00.a}, @samp{v5.00.b}, @samp{v6.00.a}.
20661 @item -mxl-soft-mul
20662 @opindex mxl-soft-mul
20663 Use software multiply emulation (default).
20665 @item -mxl-soft-div
20666 @opindex mxl-soft-div
20667 Use software emulation for divides (default).
20669 @item -mxl-barrel-shift
20670 @opindex mxl-barrel-shift
20671 Use the hardware barrel shifter.
20673 @item -mxl-pattern-compare
20674 @opindex mxl-pattern-compare
20675 Use pattern compare instructions.
20677 @item -msmall-divides
20678 @opindex msmall-divides
20679 Use table lookup optimization for small signed integer divisions.
20681 @item -mxl-stack-check
20682 @opindex mxl-stack-check
20683 This option is deprecated.  Use @option{-fstack-check} instead.
20685 @item -mxl-gp-opt
20686 @opindex mxl-gp-opt
20687 Use GP-relative @code{.sdata}/@code{.sbss} sections.
20689 @item -mxl-multiply-high
20690 @opindex mxl-multiply-high
20691 Use multiply high instructions for high part of 32x32 multiply.
20693 @item -mxl-float-convert
20694 @opindex mxl-float-convert
20695 Use hardware floating-point conversion instructions.
20697 @item -mxl-float-sqrt
20698 @opindex mxl-float-sqrt
20699 Use hardware floating-point square root instruction.
20701 @item -mbig-endian
20702 @opindex mbig-endian
20703 Generate code for a big-endian target.
20705 @item -mlittle-endian
20706 @opindex mlittle-endian
20707 Generate code for a little-endian target.
20709 @item -mxl-reorder
20710 @opindex mxl-reorder
20711 Use reorder instructions (swap and byte reversed load/store).
20713 @item -mxl-mode-@var{app-model}
20714 Select application model @var{app-model}.  Valid models are
20715 @table @samp
20716 @item executable
20717 normal executable (default), uses startup code @file{crt0.o}.
20719 @item -mpic-data-is-text-relative
20720 @opindex mpic-data-is-text-relative
20721 Assume that the displacement between the text and data segments is fixed
20722 at static link time.  This allows data to be referenced by offset from start of
20723 text address instead of GOT since PC-relative addressing is not supported.
20725 @item xmdstub
20726 for use with Xilinx Microprocessor Debugger (XMD) based
20727 software intrusive debug agent called xmdstub. This uses startup file
20728 @file{crt1.o} and sets the start address of the program to 0x800.
20730 @item bootstrap
20731 for applications that are loaded using a bootloader.
20732 This model uses startup file @file{crt2.o} which does not contain a processor
20733 reset vector handler. This is suitable for transferring control on a
20734 processor reset to the bootloader rather than the application.
20736 @item novectors
20737 for applications that do not require any of the
20738 MicroBlaze vectors. This option may be useful for applications running
20739 within a monitoring application. This model uses @file{crt3.o} as a startup file.
20740 @end table
20742 Option @option{-xl-mode-@var{app-model}} is a deprecated alias for
20743 @option{-mxl-mode-@var{app-model}}.
20745 @end table
20747 @node MIPS Options
20748 @subsection MIPS Options
20749 @cindex MIPS options
20751 @table @gcctabopt
20753 @item -EB
20754 @opindex EB
20755 Generate big-endian code.
20757 @item -EL
20758 @opindex EL
20759 Generate little-endian code.  This is the default for @samp{mips*el-*-*}
20760 configurations.
20762 @item -march=@var{arch}
20763 @opindex march
20764 Generate code that runs on @var{arch}, which can be the name of a
20765 generic MIPS ISA, or the name of a particular processor.
20766 The ISA names are:
20767 @samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
20768 @samp{mips32}, @samp{mips32r2}, @samp{mips32r3}, @samp{mips32r5},
20769 @samp{mips32r6}, @samp{mips64}, @samp{mips64r2}, @samp{mips64r3},
20770 @samp{mips64r5} and @samp{mips64r6}.
20771 The processor names are:
20772 @samp{4kc}, @samp{4km}, @samp{4kp}, @samp{4ksc},
20773 @samp{4kec}, @samp{4kem}, @samp{4kep}, @samp{4ksd},
20774 @samp{5kc}, @samp{5kf},
20775 @samp{20kc},
20776 @samp{24kc}, @samp{24kf2_1}, @samp{24kf1_1},
20777 @samp{24kec}, @samp{24kef2_1}, @samp{24kef1_1},
20778 @samp{34kc}, @samp{34kf2_1}, @samp{34kf1_1}, @samp{34kn},
20779 @samp{74kc}, @samp{74kf2_1}, @samp{74kf1_1}, @samp{74kf3_2},
20780 @samp{1004kc}, @samp{1004kf2_1}, @samp{1004kf1_1},
20781 @samp{i6400}, @samp{i6500},
20782 @samp{interaptiv},
20783 @samp{loongson2e}, @samp{loongson2f}, @samp{loongson3a},
20784 @samp{m4k},
20785 @samp{m14k}, @samp{m14kc}, @samp{m14ke}, @samp{m14kec},
20786 @samp{m5100}, @samp{m5101},
20787 @samp{octeon}, @samp{octeon+}, @samp{octeon2}, @samp{octeon3},
20788 @samp{orion},
20789 @samp{p5600}, @samp{p6600},
20790 @samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
20791 @samp{r4600}, @samp{r4650}, @samp{r4700}, @samp{r6000}, @samp{r8000},
20792 @samp{rm7000}, @samp{rm9000},
20793 @samp{r10000}, @samp{r12000}, @samp{r14000}, @samp{r16000},
20794 @samp{sb1},
20795 @samp{sr71000},
20796 @samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
20797 @samp{vr5000}, @samp{vr5400}, @samp{vr5500},
20798 @samp{xlr} and @samp{xlp}.
20799 The special value @samp{from-abi} selects the
20800 most compatible architecture for the selected ABI (that is,
20801 @samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
20803 The native Linux/GNU toolchain also supports the value @samp{native},
20804 which selects the best architecture option for the host processor.
20805 @option{-march=native} has no effect if GCC does not recognize
20806 the processor.
20808 In processor names, a final @samp{000} can be abbreviated as @samp{k}
20809 (for example, @option{-march=r2k}).  Prefixes are optional, and
20810 @samp{vr} may be written @samp{r}.
20812 Names of the form @samp{@var{n}f2_1} refer to processors with
20813 FPUs clocked at half the rate of the core, names of the form
20814 @samp{@var{n}f1_1} refer to processors with FPUs clocked at the same
20815 rate as the core, and names of the form @samp{@var{n}f3_2} refer to
20816 processors with FPUs clocked a ratio of 3:2 with respect to the core.
20817 For compatibility reasons, @samp{@var{n}f} is accepted as a synonym
20818 for @samp{@var{n}f2_1} while @samp{@var{n}x} and @samp{@var{b}fx} are
20819 accepted as synonyms for @samp{@var{n}f1_1}.
20821 GCC defines two macros based on the value of this option.  The first
20822 is @code{_MIPS_ARCH}, which gives the name of target architecture, as
20823 a string.  The second has the form @code{_MIPS_ARCH_@var{foo}},
20824 where @var{foo} is the capitalized value of @code{_MIPS_ARCH}@.
20825 For example, @option{-march=r2000} sets @code{_MIPS_ARCH}
20826 to @code{"r2000"} and defines the macro @code{_MIPS_ARCH_R2000}.
20828 Note that the @code{_MIPS_ARCH} macro uses the processor names given
20829 above.  In other words, it has the full prefix and does not
20830 abbreviate @samp{000} as @samp{k}.  In the case of @samp{from-abi},
20831 the macro names the resolved architecture (either @code{"mips1"} or
20832 @code{"mips3"}).  It names the default architecture when no
20833 @option{-march} option is given.
20835 @item -mtune=@var{arch}
20836 @opindex mtune
20837 Optimize for @var{arch}.  Among other things, this option controls
20838 the way instructions are scheduled, and the perceived cost of arithmetic
20839 operations.  The list of @var{arch} values is the same as for
20840 @option{-march}.
20842 When this option is not used, GCC optimizes for the processor
20843 specified by @option{-march}.  By using @option{-march} and
20844 @option{-mtune} together, it is possible to generate code that
20845 runs on a family of processors, but optimize the code for one
20846 particular member of that family.
20848 @option{-mtune} defines the macros @code{_MIPS_TUNE} and
20849 @code{_MIPS_TUNE_@var{foo}}, which work in the same way as the
20850 @option{-march} ones described above.
20852 @item -mips1
20853 @opindex mips1
20854 Equivalent to @option{-march=mips1}.
20856 @item -mips2
20857 @opindex mips2
20858 Equivalent to @option{-march=mips2}.
20860 @item -mips3
20861 @opindex mips3
20862 Equivalent to @option{-march=mips3}.
20864 @item -mips4
20865 @opindex mips4
20866 Equivalent to @option{-march=mips4}.
20868 @item -mips32
20869 @opindex mips32
20870 Equivalent to @option{-march=mips32}.
20872 @item -mips32r3
20873 @opindex mips32r3
20874 Equivalent to @option{-march=mips32r3}.
20876 @item -mips32r5
20877 @opindex mips32r5
20878 Equivalent to @option{-march=mips32r5}.
20880 @item -mips32r6
20881 @opindex mips32r6
20882 Equivalent to @option{-march=mips32r6}.
20884 @item -mips64
20885 @opindex mips64
20886 Equivalent to @option{-march=mips64}.
20888 @item -mips64r2
20889 @opindex mips64r2
20890 Equivalent to @option{-march=mips64r2}.
20892 @item -mips64r3
20893 @opindex mips64r3
20894 Equivalent to @option{-march=mips64r3}.
20896 @item -mips64r5
20897 @opindex mips64r5
20898 Equivalent to @option{-march=mips64r5}.
20900 @item -mips64r6
20901 @opindex mips64r6
20902 Equivalent to @option{-march=mips64r6}.
20904 @item -mips16
20905 @itemx -mno-mips16
20906 @opindex mips16
20907 @opindex mno-mips16
20908 Generate (do not generate) MIPS16 code.  If GCC is targeting a
20909 MIPS32 or MIPS64 architecture, it makes use of the MIPS16e ASE@.
20911 MIPS16 code generation can also be controlled on a per-function basis
20912 by means of @code{mips16} and @code{nomips16} attributes.
20913 @xref{Function Attributes}, for more information.
20915 @item -mflip-mips16
20916 @opindex mflip-mips16
20917 Generate MIPS16 code on alternating functions.  This option is provided
20918 for regression testing of mixed MIPS16/non-MIPS16 code generation, and is
20919 not intended for ordinary use in compiling user code.
20921 @item -minterlink-compressed
20922 @itemx -mno-interlink-compressed
20923 @opindex minterlink-compressed
20924 @opindex mno-interlink-compressed
20925 Require (do not require) that code using the standard (uncompressed) MIPS ISA
20926 be link-compatible with MIPS16 and microMIPS code, and vice versa.
20928 For example, code using the standard ISA encoding cannot jump directly
20929 to MIPS16 or microMIPS code; it must either use a call or an indirect jump.
20930 @option{-minterlink-compressed} therefore disables direct jumps unless GCC
20931 knows that the target of the jump is not compressed.
20933 @item -minterlink-mips16
20934 @itemx -mno-interlink-mips16
20935 @opindex minterlink-mips16
20936 @opindex mno-interlink-mips16
20937 Aliases of @option{-minterlink-compressed} and
20938 @option{-mno-interlink-compressed}.  These options predate the microMIPS ASE
20939 and are retained for backwards compatibility.
20941 @item -mabi=32
20942 @itemx -mabi=o64
20943 @itemx -mabi=n32
20944 @itemx -mabi=64
20945 @itemx -mabi=eabi
20946 @opindex mabi=32
20947 @opindex mabi=o64
20948 @opindex mabi=n32
20949 @opindex mabi=64
20950 @opindex mabi=eabi
20951 Generate code for the given ABI@.
20953 Note that the EABI has a 32-bit and a 64-bit variant.  GCC normally
20954 generates 64-bit code when you select a 64-bit architecture, but you
20955 can use @option{-mgp32} to get 32-bit code instead.
20957 For information about the O64 ABI, see
20958 @uref{http://gcc.gnu.org/@/projects/@/mipso64-abi.html}.
20960 GCC supports a variant of the o32 ABI in which floating-point registers
20961 are 64 rather than 32 bits wide.  You can select this combination with
20962 @option{-mabi=32} @option{-mfp64}.  This ABI relies on the @code{mthc1}
20963 and @code{mfhc1} instructions and is therefore only supported for
20964 MIPS32R2, MIPS32R3 and MIPS32R5 processors.
20966 The register assignments for arguments and return values remain the
20967 same, but each scalar value is passed in a single 64-bit register
20968 rather than a pair of 32-bit registers.  For example, scalar
20969 floating-point values are returned in @samp{$f0} only, not a
20970 @samp{$f0}/@samp{$f1} pair.  The set of call-saved registers also
20971 remains the same in that the even-numbered double-precision registers
20972 are saved.
20974 Two additional variants of the o32 ABI are supported to enable
20975 a transition from 32-bit to 64-bit registers.  These are FPXX
20976 (@option{-mfpxx}) and FP64A (@option{-mfp64} @option{-mno-odd-spreg}).
20977 The FPXX extension mandates that all code must execute correctly
20978 when run using 32-bit or 64-bit registers.  The code can be interlinked
20979 with either FP32 or FP64, but not both.
20980 The FP64A extension is similar to the FP64 extension but forbids the
20981 use of odd-numbered single-precision registers.  This can be used
20982 in conjunction with the @code{FRE} mode of FPUs in MIPS32R5
20983 processors and allows both FP32 and FP64A code to interlink and
20984 run in the same process without changing FPU modes.
20986 @item -mabicalls
20987 @itemx -mno-abicalls
20988 @opindex mabicalls
20989 @opindex mno-abicalls
20990 Generate (do not generate) code that is suitable for SVR4-style
20991 dynamic objects.  @option{-mabicalls} is the default for SVR4-based
20992 systems.
20994 @item -mshared
20995 @itemx -mno-shared
20996 Generate (do not generate) code that is fully position-independent,
20997 and that can therefore be linked into shared libraries.  This option
20998 only affects @option{-mabicalls}.
21000 All @option{-mabicalls} code has traditionally been position-independent,
21001 regardless of options like @option{-fPIC} and @option{-fpic}.  However,
21002 as an extension, the GNU toolchain allows executables to use absolute
21003 accesses for locally-binding symbols.  It can also use shorter GP
21004 initialization sequences and generate direct calls to locally-defined
21005 functions.  This mode is selected by @option{-mno-shared}.
21007 @option{-mno-shared} depends on binutils 2.16 or higher and generates
21008 objects that can only be linked by the GNU linker.  However, the option
21009 does not affect the ABI of the final executable; it only affects the ABI
21010 of relocatable objects.  Using @option{-mno-shared} generally makes
21011 executables both smaller and quicker.
21013 @option{-mshared} is the default.
21015 @item -mplt
21016 @itemx -mno-plt
21017 @opindex mplt
21018 @opindex mno-plt
21019 Assume (do not assume) that the static and dynamic linkers
21020 support PLTs and copy relocations.  This option only affects
21021 @option{-mno-shared -mabicalls}.  For the n64 ABI, this option
21022 has no effect without @option{-msym32}.
21024 You can make @option{-mplt} the default by configuring
21025 GCC with @option{--with-mips-plt}.  The default is
21026 @option{-mno-plt} otherwise.
21028 @item -mxgot
21029 @itemx -mno-xgot
21030 @opindex mxgot
21031 @opindex mno-xgot
21032 Lift (do not lift) the usual restrictions on the size of the global
21033 offset table.
21035 GCC normally uses a single instruction to load values from the GOT@.
21036 While this is relatively efficient, it only works if the GOT
21037 is smaller than about 64k.  Anything larger causes the linker
21038 to report an error such as:
21040 @cindex relocation truncated to fit (MIPS)
21041 @smallexample
21042 relocation truncated to fit: R_MIPS_GOT16 foobar
21043 @end smallexample
21045 If this happens, you should recompile your code with @option{-mxgot}.
21046 This works with very large GOTs, although the code is also
21047 less efficient, since it takes three instructions to fetch the
21048 value of a global symbol.
21050 Note that some linkers can create multiple GOTs.  If you have such a
21051 linker, you should only need to use @option{-mxgot} when a single object
21052 file accesses more than 64k's worth of GOT entries.  Very few do.
21054 These options have no effect unless GCC is generating position
21055 independent code.
21057 @item -mgp32
21058 @opindex mgp32
21059 Assume that general-purpose registers are 32 bits wide.
21061 @item -mgp64
21062 @opindex mgp64
21063 Assume that general-purpose registers are 64 bits wide.
21065 @item -mfp32
21066 @opindex mfp32
21067 Assume that floating-point registers are 32 bits wide.
21069 @item -mfp64
21070 @opindex mfp64
21071 Assume that floating-point registers are 64 bits wide.
21073 @item -mfpxx
21074 @opindex mfpxx
21075 Do not assume the width of floating-point registers.
21077 @item -mhard-float
21078 @opindex mhard-float
21079 Use floating-point coprocessor instructions.
21081 @item -msoft-float
21082 @opindex msoft-float
21083 Do not use floating-point coprocessor instructions.  Implement
21084 floating-point calculations using library calls instead.
21086 @item -mno-float
21087 @opindex mno-float
21088 Equivalent to @option{-msoft-float}, but additionally asserts that the
21089 program being compiled does not perform any floating-point operations.
21090 This option is presently supported only by some bare-metal MIPS
21091 configurations, where it may select a special set of libraries
21092 that lack all floating-point support (including, for example, the
21093 floating-point @code{printf} formats).  
21094 If code compiled with @option{-mno-float} accidentally contains
21095 floating-point operations, it is likely to suffer a link-time
21096 or run-time failure.
21098 @item -msingle-float
21099 @opindex msingle-float
21100 Assume that the floating-point coprocessor only supports single-precision
21101 operations.
21103 @item -mdouble-float
21104 @opindex mdouble-float
21105 Assume that the floating-point coprocessor supports double-precision
21106 operations.  This is the default.
21108 @item -modd-spreg
21109 @itemx -mno-odd-spreg
21110 @opindex modd-spreg
21111 @opindex mno-odd-spreg
21112 Enable the use of odd-numbered single-precision floating-point registers
21113 for the o32 ABI.  This is the default for processors that are known to
21114 support these registers.  When using the o32 FPXX ABI, @option{-mno-odd-spreg}
21115 is set by default.
21117 @item -mabs=2008
21118 @itemx -mabs=legacy
21119 @opindex mabs=2008
21120 @opindex mabs=legacy
21121 These options control the treatment of the special not-a-number (NaN)
21122 IEEE 754 floating-point data with the @code{abs.@i{fmt}} and
21123 @code{neg.@i{fmt}} machine instructions.
21125 By default or when @option{-mabs=legacy} is used the legacy
21126 treatment is selected.  In this case these instructions are considered
21127 arithmetic and avoided where correct operation is required and the
21128 input operand might be a NaN.  A longer sequence of instructions that
21129 manipulate the sign bit of floating-point datum manually is used
21130 instead unless the @option{-ffinite-math-only} option has also been
21131 specified.
21133 The @option{-mabs=2008} option selects the IEEE 754-2008 treatment.  In
21134 this case these instructions are considered non-arithmetic and therefore
21135 operating correctly in all cases, including in particular where the
21136 input operand is a NaN.  These instructions are therefore always used
21137 for the respective operations.
21139 @item -mnan=2008
21140 @itemx -mnan=legacy
21141 @opindex mnan=2008
21142 @opindex mnan=legacy
21143 These options control the encoding of the special not-a-number (NaN)
21144 IEEE 754 floating-point data.
21146 The @option{-mnan=legacy} option selects the legacy encoding.  In this
21147 case quiet NaNs (qNaNs) are denoted by the first bit of their trailing
21148 significand field being 0, whereas signaling NaNs (sNaNs) are denoted
21149 by the first bit of their trailing significand field being 1.
21151 The @option{-mnan=2008} option selects the IEEE 754-2008 encoding.  In
21152 this case qNaNs are denoted by the first bit of their trailing
21153 significand field being 1, whereas sNaNs are denoted by the first bit of
21154 their trailing significand field being 0.
21156 The default is @option{-mnan=legacy} unless GCC has been configured with
21157 @option{--with-nan=2008}.
21159 @item -mllsc
21160 @itemx -mno-llsc
21161 @opindex mllsc
21162 @opindex mno-llsc
21163 Use (do not use) @samp{ll}, @samp{sc}, and @samp{sync} instructions to
21164 implement atomic memory built-in functions.  When neither option is
21165 specified, GCC uses the instructions if the target architecture
21166 supports them.
21168 @option{-mllsc} is useful if the runtime environment can emulate the
21169 instructions and @option{-mno-llsc} can be useful when compiling for
21170 nonstandard ISAs.  You can make either option the default by
21171 configuring GCC with @option{--with-llsc} and @option{--without-llsc}
21172 respectively.  @option{--with-llsc} is the default for some
21173 configurations; see the installation documentation for details.
21175 @item -mdsp
21176 @itemx -mno-dsp
21177 @opindex mdsp
21178 @opindex mno-dsp
21179 Use (do not use) revision 1 of the MIPS DSP ASE@.
21180 @xref{MIPS DSP Built-in Functions}.  This option defines the
21181 preprocessor macro @code{__mips_dsp}.  It also defines
21182 @code{__mips_dsp_rev} to 1.
21184 @item -mdspr2
21185 @itemx -mno-dspr2
21186 @opindex mdspr2
21187 @opindex mno-dspr2
21188 Use (do not use) revision 2 of the MIPS DSP ASE@.
21189 @xref{MIPS DSP Built-in Functions}.  This option defines the
21190 preprocessor macros @code{__mips_dsp} and @code{__mips_dspr2}.
21191 It also defines @code{__mips_dsp_rev} to 2.
21193 @item -msmartmips
21194 @itemx -mno-smartmips
21195 @opindex msmartmips
21196 @opindex mno-smartmips
21197 Use (do not use) the MIPS SmartMIPS ASE.
21199 @item -mpaired-single
21200 @itemx -mno-paired-single
21201 @opindex mpaired-single
21202 @opindex mno-paired-single
21203 Use (do not use) paired-single floating-point instructions.
21204 @xref{MIPS Paired-Single Support}.  This option requires
21205 hardware floating-point support to be enabled.
21207 @item -mdmx
21208 @itemx -mno-mdmx
21209 @opindex mdmx
21210 @opindex mno-mdmx
21211 Use (do not use) MIPS Digital Media Extension instructions.
21212 This option can only be used when generating 64-bit code and requires
21213 hardware floating-point support to be enabled.
21215 @item -mips3d
21216 @itemx -mno-mips3d
21217 @opindex mips3d
21218 @opindex mno-mips3d
21219 Use (do not use) the MIPS-3D ASE@.  @xref{MIPS-3D Built-in Functions}.
21220 The option @option{-mips3d} implies @option{-mpaired-single}.
21222 @item -mmicromips
21223 @itemx -mno-micromips
21224 @opindex mmicromips
21225 @opindex mno-mmicromips
21226 Generate (do not generate) microMIPS code.
21228 MicroMIPS code generation can also be controlled on a per-function basis
21229 by means of @code{micromips} and @code{nomicromips} attributes.
21230 @xref{Function Attributes}, for more information.
21232 @item -mmt
21233 @itemx -mno-mt
21234 @opindex mmt
21235 @opindex mno-mt
21236 Use (do not use) MT Multithreading instructions.
21238 @item -mmcu
21239 @itemx -mno-mcu
21240 @opindex mmcu
21241 @opindex mno-mcu
21242 Use (do not use) the MIPS MCU ASE instructions.
21244 @item -meva
21245 @itemx -mno-eva
21246 @opindex meva
21247 @opindex mno-eva
21248 Use (do not use) the MIPS Enhanced Virtual Addressing instructions.
21250 @item -mvirt
21251 @itemx -mno-virt
21252 @opindex mvirt
21253 @opindex mno-virt
21254 Use (do not use) the MIPS Virtualization (VZ) instructions.
21256 @item -mxpa
21257 @itemx -mno-xpa
21258 @opindex mxpa
21259 @opindex mno-xpa
21260 Use (do not use) the MIPS eXtended Physical Address (XPA) instructions.
21262 @item -mcrc
21263 @itemx -mno-crc
21264 @opindex mcrc
21265 @opindex mno-crc
21266 Use (do not use) the MIPS Cyclic Redundancy Check (CRC) instructions.
21268 @item -mginv
21269 @itemx -mno-ginv
21270 @opindex mginv
21271 @opindex mno-ginv
21272 Use (do not use) the MIPS Global INValidate (GINV) instructions.
21274 @item -mlong64
21275 @opindex mlong64
21276 Force @code{long} types to be 64 bits wide.  See @option{-mlong32} for
21277 an explanation of the default and the way that the pointer size is
21278 determined.
21280 @item -mlong32
21281 @opindex mlong32
21282 Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
21284 The default size of @code{int}s, @code{long}s and pointers depends on
21285 the ABI@.  All the supported ABIs use 32-bit @code{int}s.  The n64 ABI
21286 uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
21287 32-bit @code{long}s.  Pointers are the same size as @code{long}s,
21288 or the same size as integer registers, whichever is smaller.
21290 @item -msym32
21291 @itemx -mno-sym32
21292 @opindex msym32
21293 @opindex mno-sym32
21294 Assume (do not assume) that all symbols have 32-bit values, regardless
21295 of the selected ABI@.  This option is useful in combination with
21296 @option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
21297 to generate shorter and faster references to symbolic addresses.
21299 @item -G @var{num}
21300 @opindex G
21301 Put definitions of externally-visible data in a small data section
21302 if that data is no bigger than @var{num} bytes.  GCC can then generate
21303 more efficient accesses to the data; see @option{-mgpopt} for details.
21305 The default @option{-G} option depends on the configuration.
21307 @item -mlocal-sdata
21308 @itemx -mno-local-sdata
21309 @opindex mlocal-sdata
21310 @opindex mno-local-sdata
21311 Extend (do not extend) the @option{-G} behavior to local data too,
21312 such as to static variables in C@.  @option{-mlocal-sdata} is the
21313 default for all configurations.
21315 If the linker complains that an application is using too much small data,
21316 you might want to try rebuilding the less performance-critical parts with
21317 @option{-mno-local-sdata}.  You might also want to build large
21318 libraries with @option{-mno-local-sdata}, so that the libraries leave
21319 more room for the main program.
21321 @item -mextern-sdata
21322 @itemx -mno-extern-sdata
21323 @opindex mextern-sdata
21324 @opindex mno-extern-sdata
21325 Assume (do not assume) that externally-defined data is in
21326 a small data section if the size of that data is within the @option{-G} limit.
21327 @option{-mextern-sdata} is the default for all configurations.
21329 If you compile a module @var{Mod} with @option{-mextern-sdata} @option{-G
21330 @var{num}} @option{-mgpopt}, and @var{Mod} references a variable @var{Var}
21331 that is no bigger than @var{num} bytes, you must make sure that @var{Var}
21332 is placed in a small data section.  If @var{Var} is defined by another
21333 module, you must either compile that module with a high-enough
21334 @option{-G} setting or attach a @code{section} attribute to @var{Var}'s
21335 definition.  If @var{Var} is common, you must link the application
21336 with a high-enough @option{-G} setting.
21338 The easiest way of satisfying these restrictions is to compile
21339 and link every module with the same @option{-G} option.  However,
21340 you may wish to build a library that supports several different
21341 small data limits.  You can do this by compiling the library with
21342 the highest supported @option{-G} setting and additionally using
21343 @option{-mno-extern-sdata} to stop the library from making assumptions
21344 about externally-defined data.
21346 @item -mgpopt
21347 @itemx -mno-gpopt
21348 @opindex mgpopt
21349 @opindex mno-gpopt
21350 Use (do not use) GP-relative accesses for symbols that are known to be
21351 in a small data section; see @option{-G}, @option{-mlocal-sdata} and
21352 @option{-mextern-sdata}.  @option{-mgpopt} is the default for all
21353 configurations.
21355 @option{-mno-gpopt} is useful for cases where the @code{$gp} register
21356 might not hold the value of @code{_gp}.  For example, if the code is
21357 part of a library that might be used in a boot monitor, programs that
21358 call boot monitor routines pass an unknown value in @code{$gp}.
21359 (In such situations, the boot monitor itself is usually compiled
21360 with @option{-G0}.)
21362 @option{-mno-gpopt} implies @option{-mno-local-sdata} and
21363 @option{-mno-extern-sdata}.
21365 @item -membedded-data
21366 @itemx -mno-embedded-data
21367 @opindex membedded-data
21368 @opindex mno-embedded-data
21369 Allocate variables to the read-only data section first if possible, then
21370 next in the small data section if possible, otherwise in data.  This gives
21371 slightly slower code than the default, but reduces the amount of RAM required
21372 when executing, and thus may be preferred for some embedded systems.
21374 @item -muninit-const-in-rodata
21375 @itemx -mno-uninit-const-in-rodata
21376 @opindex muninit-const-in-rodata
21377 @opindex mno-uninit-const-in-rodata
21378 Put uninitialized @code{const} variables in the read-only data section.
21379 This option is only meaningful in conjunction with @option{-membedded-data}.
21381 @item -mcode-readable=@var{setting}
21382 @opindex mcode-readable
21383 Specify whether GCC may generate code that reads from executable sections.
21384 There are three possible settings:
21386 @table @gcctabopt
21387 @item -mcode-readable=yes
21388 Instructions may freely access executable sections.  This is the
21389 default setting.
21391 @item -mcode-readable=pcrel
21392 MIPS16 PC-relative load instructions can access executable sections,
21393 but other instructions must not do so.  This option is useful on 4KSc
21394 and 4KSd processors when the code TLBs have the Read Inhibit bit set.
21395 It is also useful on processors that can be configured to have a dual
21396 instruction/data SRAM interface and that, like the M4K, automatically
21397 redirect PC-relative loads to the instruction RAM.
21399 @item -mcode-readable=no
21400 Instructions must not access executable sections.  This option can be
21401 useful on targets that are configured to have a dual instruction/data
21402 SRAM interface but that (unlike the M4K) do not automatically redirect
21403 PC-relative loads to the instruction RAM.
21404 @end table
21406 @item -msplit-addresses
21407 @itemx -mno-split-addresses
21408 @opindex msplit-addresses
21409 @opindex mno-split-addresses
21410 Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
21411 relocation operators.  This option has been superseded by
21412 @option{-mexplicit-relocs} but is retained for backwards compatibility.
21414 @item -mexplicit-relocs
21415 @itemx -mno-explicit-relocs
21416 @opindex mexplicit-relocs
21417 @opindex mno-explicit-relocs
21418 Use (do not use) assembler relocation operators when dealing with symbolic
21419 addresses.  The alternative, selected by @option{-mno-explicit-relocs},
21420 is to use assembler macros instead.
21422 @option{-mexplicit-relocs} is the default if GCC was configured
21423 to use an assembler that supports relocation operators.
21425 @item -mcheck-zero-division
21426 @itemx -mno-check-zero-division
21427 @opindex mcheck-zero-division
21428 @opindex mno-check-zero-division
21429 Trap (do not trap) on integer division by zero.
21431 The default is @option{-mcheck-zero-division}.
21433 @item -mdivide-traps
21434 @itemx -mdivide-breaks
21435 @opindex mdivide-traps
21436 @opindex mdivide-breaks
21437 MIPS systems check for division by zero by generating either a
21438 conditional trap or a break instruction.  Using traps results in
21439 smaller code, but is only supported on MIPS II and later.  Also, some
21440 versions of the Linux kernel have a bug that prevents trap from
21441 generating the proper signal (@code{SIGFPE}).  Use @option{-mdivide-traps} to
21442 allow conditional traps on architectures that support them and
21443 @option{-mdivide-breaks} to force the use of breaks.
21445 The default is usually @option{-mdivide-traps}, but this can be
21446 overridden at configure time using @option{--with-divide=breaks}.
21447 Divide-by-zero checks can be completely disabled using
21448 @option{-mno-check-zero-division}.
21450 @item -mload-store-pairs
21451 @itemx -mno-load-store-pairs
21452 @opindex mload-store-pairs
21453 @opindex mno-load-store-pairs
21454 Enable (disable) an optimization that pairs consecutive load or store
21455 instructions to enable load/store bonding.  This option is enabled by
21456 default but only takes effect when the selected architecture is known
21457 to support bonding.
21459 @item -mmemcpy
21460 @itemx -mno-memcpy
21461 @opindex mmemcpy
21462 @opindex mno-memcpy
21463 Force (do not force) the use of @code{memcpy} for non-trivial block
21464 moves.  The default is @option{-mno-memcpy}, which allows GCC to inline
21465 most constant-sized copies.
21467 @item -mlong-calls
21468 @itemx -mno-long-calls
21469 @opindex mlong-calls
21470 @opindex mno-long-calls
21471 Disable (do not disable) use of the @code{jal} instruction.  Calling
21472 functions using @code{jal} is more efficient but requires the caller
21473 and callee to be in the same 256 megabyte segment.
21475 This option has no effect on abicalls code.  The default is
21476 @option{-mno-long-calls}.
21478 @item -mmad
21479 @itemx -mno-mad
21480 @opindex mmad
21481 @opindex mno-mad
21482 Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
21483 instructions, as provided by the R4650 ISA@.
21485 @item -mimadd
21486 @itemx -mno-imadd
21487 @opindex mimadd
21488 @opindex mno-imadd
21489 Enable (disable) use of the @code{madd} and @code{msub} integer
21490 instructions.  The default is @option{-mimadd} on architectures
21491 that support @code{madd} and @code{msub} except for the 74k 
21492 architecture where it was found to generate slower code.
21494 @item -mfused-madd
21495 @itemx -mno-fused-madd
21496 @opindex mfused-madd
21497 @opindex mno-fused-madd
21498 Enable (disable) use of the floating-point multiply-accumulate
21499 instructions, when they are available.  The default is
21500 @option{-mfused-madd}.
21502 On the R8000 CPU when multiply-accumulate instructions are used,
21503 the intermediate product is calculated to infinite precision
21504 and is not subject to the FCSR Flush to Zero bit.  This may be
21505 undesirable in some circumstances.  On other processors the result
21506 is numerically identical to the equivalent computation using
21507 separate multiply, add, subtract and negate instructions.
21509 @item -nocpp
21510 @opindex nocpp
21511 Tell the MIPS assembler to not run its preprocessor over user
21512 assembler files (with a @samp{.s} suffix) when assembling them.
21514 @item -mfix-24k
21515 @itemx -mno-fix-24k
21516 @opindex mfix-24k
21517 @opindex mno-fix-24k
21518 Work around the 24K E48 (lost data on stores during refill) errata.
21519 The workarounds are implemented by the assembler rather than by GCC@.
21521 @item -mfix-r4000
21522 @itemx -mno-fix-r4000
21523 @opindex mfix-r4000
21524 @opindex mno-fix-r4000
21525 Work around certain R4000 CPU errata:
21526 @itemize @minus
21527 @item
21528 A double-word or a variable shift may give an incorrect result if executed
21529 immediately after starting an integer division.
21530 @item
21531 A double-word or a variable shift may give an incorrect result if executed
21532 while an integer multiplication is in progress.
21533 @item
21534 An integer division may give an incorrect result if started in a delay slot
21535 of a taken branch or a jump.
21536 @end itemize
21538 @item -mfix-r4400
21539 @itemx -mno-fix-r4400
21540 @opindex mfix-r4400
21541 @opindex mno-fix-r4400
21542 Work around certain R4400 CPU errata:
21543 @itemize @minus
21544 @item
21545 A double-word or a variable shift may give an incorrect result if executed
21546 immediately after starting an integer division.
21547 @end itemize
21549 @item -mfix-r10000
21550 @itemx -mno-fix-r10000
21551 @opindex mfix-r10000
21552 @opindex mno-fix-r10000
21553 Work around certain R10000 errata:
21554 @itemize @minus
21555 @item
21556 @code{ll}/@code{sc} sequences may not behave atomically on revisions
21557 prior to 3.0.  They may deadlock on revisions 2.6 and earlier.
21558 @end itemize
21560 This option can only be used if the target architecture supports
21561 branch-likely instructions.  @option{-mfix-r10000} is the default when
21562 @option{-march=r10000} is used; @option{-mno-fix-r10000} is the default
21563 otherwise.
21565 @item -mfix-rm7000
21566 @itemx -mno-fix-rm7000
21567 @opindex mfix-rm7000
21568 Work around the RM7000 @code{dmult}/@code{dmultu} errata.  The
21569 workarounds are implemented by the assembler rather than by GCC@.
21571 @item -mfix-vr4120
21572 @itemx -mno-fix-vr4120
21573 @opindex mfix-vr4120
21574 Work around certain VR4120 errata:
21575 @itemize @minus
21576 @item
21577 @code{dmultu} does not always produce the correct result.
21578 @item
21579 @code{div} and @code{ddiv} do not always produce the correct result if one
21580 of the operands is negative.
21581 @end itemize
21582 The workarounds for the division errata rely on special functions in
21583 @file{libgcc.a}.  At present, these functions are only provided by
21584 the @code{mips64vr*-elf} configurations.
21586 Other VR4120 errata require a NOP to be inserted between certain pairs of
21587 instructions.  These errata are handled by the assembler, not by GCC itself.
21589 @item -mfix-vr4130
21590 @opindex mfix-vr4130
21591 Work around the VR4130 @code{mflo}/@code{mfhi} errata.  The
21592 workarounds are implemented by the assembler rather than by GCC,
21593 although GCC avoids using @code{mflo} and @code{mfhi} if the
21594 VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
21595 instructions are available instead.
21597 @item -mfix-sb1
21598 @itemx -mno-fix-sb1
21599 @opindex mfix-sb1
21600 Work around certain SB-1 CPU core errata.
21601 (This flag currently works around the SB-1 revision 2
21602 ``F1'' and ``F2'' floating-point errata.)
21604 @item -mr10k-cache-barrier=@var{setting}
21605 @opindex mr10k-cache-barrier
21606 Specify whether GCC should insert cache barriers to avoid the
21607 side effects of speculation on R10K processors.
21609 In common with many processors, the R10K tries to predict the outcome
21610 of a conditional branch and speculatively executes instructions from
21611 the ``taken'' branch.  It later aborts these instructions if the
21612 predicted outcome is wrong.  However, on the R10K, even aborted
21613 instructions can have side effects.
21615 This problem only affects kernel stores and, depending on the system,
21616 kernel loads.  As an example, a speculatively-executed store may load
21617 the target memory into cache and mark the cache line as dirty, even if
21618 the store itself is later aborted.  If a DMA operation writes to the
21619 same area of memory before the ``dirty'' line is flushed, the cached
21620 data overwrites the DMA-ed data.  See the R10K processor manual
21621 for a full description, including other potential problems.
21623 One workaround is to insert cache barrier instructions before every memory
21624 access that might be speculatively executed and that might have side
21625 effects even if aborted.  @option{-mr10k-cache-barrier=@var{setting}}
21626 controls GCC's implementation of this workaround.  It assumes that
21627 aborted accesses to any byte in the following regions does not have
21628 side effects:
21630 @enumerate
21631 @item
21632 the memory occupied by the current function's stack frame;
21634 @item
21635 the memory occupied by an incoming stack argument;
21637 @item
21638 the memory occupied by an object with a link-time-constant address.
21639 @end enumerate
21641 It is the kernel's responsibility to ensure that speculative
21642 accesses to these regions are indeed safe.
21644 If the input program contains a function declaration such as:
21646 @smallexample
21647 void foo (void);
21648 @end smallexample
21650 then the implementation of @code{foo} must allow @code{j foo} and
21651 @code{jal foo} to be executed speculatively.  GCC honors this
21652 restriction for functions it compiles itself.  It expects non-GCC
21653 functions (such as hand-written assembly code) to do the same.
21655 The option has three forms:
21657 @table @gcctabopt
21658 @item -mr10k-cache-barrier=load-store
21659 Insert a cache barrier before a load or store that might be
21660 speculatively executed and that might have side effects even
21661 if aborted.
21663 @item -mr10k-cache-barrier=store
21664 Insert a cache barrier before a store that might be speculatively
21665 executed and that might have side effects even if aborted.
21667 @item -mr10k-cache-barrier=none
21668 Disable the insertion of cache barriers.  This is the default setting.
21669 @end table
21671 @item -mflush-func=@var{func}
21672 @itemx -mno-flush-func
21673 @opindex mflush-func
21674 Specifies the function to call to flush the I and D caches, or to not
21675 call any such function.  If called, the function must take the same
21676 arguments as the common @code{_flush_func}, that is, the address of the
21677 memory range for which the cache is being flushed, the size of the
21678 memory range, and the number 3 (to flush both caches).  The default
21679 depends on the target GCC was configured for, but commonly is either
21680 @code{_flush_func} or @code{__cpu_flush}.
21682 @item mbranch-cost=@var{num}
21683 @opindex mbranch-cost
21684 Set the cost of branches to roughly @var{num} ``simple'' instructions.
21685 This cost is only a heuristic and is not guaranteed to produce
21686 consistent results across releases.  A zero cost redundantly selects
21687 the default, which is based on the @option{-mtune} setting.
21689 @item -mbranch-likely
21690 @itemx -mno-branch-likely
21691 @opindex mbranch-likely
21692 @opindex mno-branch-likely
21693 Enable or disable use of Branch Likely instructions, regardless of the
21694 default for the selected architecture.  By default, Branch Likely
21695 instructions may be generated if they are supported by the selected
21696 architecture.  An exception is for the MIPS32 and MIPS64 architectures
21697 and processors that implement those architectures; for those, Branch
21698 Likely instructions are not be generated by default because the MIPS32
21699 and MIPS64 architectures specifically deprecate their use.
21701 @item -mcompact-branches=never
21702 @itemx -mcompact-branches=optimal
21703 @itemx -mcompact-branches=always
21704 @opindex mcompact-branches=never
21705 @opindex mcompact-branches=optimal
21706 @opindex mcompact-branches=always
21707 These options control which form of branches will be generated.  The
21708 default is @option{-mcompact-branches=optimal}.
21710 The @option{-mcompact-branches=never} option ensures that compact branch
21711 instructions will never be generated.
21713 The @option{-mcompact-branches=always} option ensures that a compact
21714 branch instruction will be generated if available.  If a compact branch
21715 instruction is not available, a delay slot form of the branch will be
21716 used instead.
21718 This option is supported from MIPS Release 6 onwards.
21720 The @option{-mcompact-branches=optimal} option will cause a delay slot
21721 branch to be used if one is available in the current ISA and the delay
21722 slot is successfully filled.  If the delay slot is not filled, a compact
21723 branch will be chosen if one is available.
21725 @item -mfp-exceptions
21726 @itemx -mno-fp-exceptions
21727 @opindex mfp-exceptions
21728 Specifies whether FP exceptions are enabled.  This affects how
21729 FP instructions are scheduled for some processors.
21730 The default is that FP exceptions are
21731 enabled.
21733 For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
21734 64-bit code, then we can use both FP pipes.  Otherwise, we can only use one
21735 FP pipe.
21737 @item -mvr4130-align
21738 @itemx -mno-vr4130-align
21739 @opindex mvr4130-align
21740 The VR4130 pipeline is two-way superscalar, but can only issue two
21741 instructions together if the first one is 8-byte aligned.  When this
21742 option is enabled, GCC aligns pairs of instructions that it
21743 thinks should execute in parallel.
21745 This option only has an effect when optimizing for the VR4130.
21746 It normally makes code faster, but at the expense of making it bigger.
21747 It is enabled by default at optimization level @option{-O3}.
21749 @item -msynci
21750 @itemx -mno-synci
21751 @opindex msynci
21752 Enable (disable) generation of @code{synci} instructions on
21753 architectures that support it.  The @code{synci} instructions (if
21754 enabled) are generated when @code{__builtin___clear_cache} is
21755 compiled.
21757 This option defaults to @option{-mno-synci}, but the default can be
21758 overridden by configuring GCC with @option{--with-synci}.
21760 When compiling code for single processor systems, it is generally safe
21761 to use @code{synci}.  However, on many multi-core (SMP) systems, it
21762 does not invalidate the instruction caches on all cores and may lead
21763 to undefined behavior.
21765 @item -mrelax-pic-calls
21766 @itemx -mno-relax-pic-calls
21767 @opindex mrelax-pic-calls
21768 Try to turn PIC calls that are normally dispatched via register
21769 @code{$25} into direct calls.  This is only possible if the linker can
21770 resolve the destination at link time and if the destination is within
21771 range for a direct call.
21773 @option{-mrelax-pic-calls} is the default if GCC was configured to use
21774 an assembler and a linker that support the @code{.reloc} assembly
21775 directive and @option{-mexplicit-relocs} is in effect.  With
21776 @option{-mno-explicit-relocs}, this optimization can be performed by the
21777 assembler and the linker alone without help from the compiler.
21779 @item -mmcount-ra-address
21780 @itemx -mno-mcount-ra-address
21781 @opindex mmcount-ra-address
21782 @opindex mno-mcount-ra-address
21783 Emit (do not emit) code that allows @code{_mcount} to modify the
21784 calling function's return address.  When enabled, this option extends
21785 the usual @code{_mcount} interface with a new @var{ra-address}
21786 parameter, which has type @code{intptr_t *} and is passed in register
21787 @code{$12}.  @code{_mcount} can then modify the return address by
21788 doing both of the following:
21789 @itemize
21790 @item
21791 Returning the new address in register @code{$31}.
21792 @item
21793 Storing the new address in @code{*@var{ra-address}},
21794 if @var{ra-address} is nonnull.
21795 @end itemize
21797 The default is @option{-mno-mcount-ra-address}.
21799 @item -mframe-header-opt
21800 @itemx -mno-frame-header-opt
21801 @opindex mframe-header-opt
21802 Enable (disable) frame header optimization in the o32 ABI.  When using the
21803 o32 ABI, calling functions will allocate 16 bytes on the stack for the called
21804 function to write out register arguments.  When enabled, this optimization
21805 will suppress the allocation of the frame header if it can be determined that
21806 it is unused.
21808 This optimization is off by default at all optimization levels.
21810 @item -mlxc1-sxc1
21811 @itemx -mno-lxc1-sxc1
21812 @opindex mlxc1-sxc1
21813 When applicable, enable (disable) the generation of @code{lwxc1},
21814 @code{swxc1}, @code{ldxc1}, @code{sdxc1} instructions.  Enabled by default.
21816 @item -mmadd4
21817 @itemx -mno-madd4
21818 @opindex mmadd4
21819 When applicable, enable (disable) the generation of 4-operand @code{madd.s},
21820 @code{madd.d} and related instructions.  Enabled by default.
21822 @end table
21824 @node MMIX Options
21825 @subsection MMIX Options
21826 @cindex MMIX Options
21828 These options are defined for the MMIX:
21830 @table @gcctabopt
21831 @item -mlibfuncs
21832 @itemx -mno-libfuncs
21833 @opindex mlibfuncs
21834 @opindex mno-libfuncs
21835 Specify that intrinsic library functions are being compiled, passing all
21836 values in registers, no matter the size.
21838 @item -mepsilon
21839 @itemx -mno-epsilon
21840 @opindex mepsilon
21841 @opindex mno-epsilon
21842 Generate floating-point comparison instructions that compare with respect
21843 to the @code{rE} epsilon register.
21845 @item -mabi=mmixware
21846 @itemx -mabi=gnu
21847 @opindex mabi=mmixware
21848 @opindex mabi=gnu
21849 Generate code that passes function parameters and return values that (in
21850 the called function) are seen as registers @code{$0} and up, as opposed to
21851 the GNU ABI which uses global registers @code{$231} and up.
21853 @item -mzero-extend
21854 @itemx -mno-zero-extend
21855 @opindex mzero-extend
21856 @opindex mno-zero-extend
21857 When reading data from memory in sizes shorter than 64 bits, use (do not
21858 use) zero-extending load instructions by default, rather than
21859 sign-extending ones.
21861 @item -mknuthdiv
21862 @itemx -mno-knuthdiv
21863 @opindex mknuthdiv
21864 @opindex mno-knuthdiv
21865 Make the result of a division yielding a remainder have the same sign as
21866 the divisor.  With the default, @option{-mno-knuthdiv}, the sign of the
21867 remainder follows the sign of the dividend.  Both methods are
21868 arithmetically valid, the latter being almost exclusively used.
21870 @item -mtoplevel-symbols
21871 @itemx -mno-toplevel-symbols
21872 @opindex mtoplevel-symbols
21873 @opindex mno-toplevel-symbols
21874 Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
21875 code can be used with the @code{PREFIX} assembly directive.
21877 @item -melf
21878 @opindex melf
21879 Generate an executable in the ELF format, rather than the default
21880 @samp{mmo} format used by the @command{mmix} simulator.
21882 @item -mbranch-predict
21883 @itemx -mno-branch-predict
21884 @opindex mbranch-predict
21885 @opindex mno-branch-predict
21886 Use (do not use) the probable-branch instructions, when static branch
21887 prediction indicates a probable branch.
21889 @item -mbase-addresses
21890 @itemx -mno-base-addresses
21891 @opindex mbase-addresses
21892 @opindex mno-base-addresses
21893 Generate (do not generate) code that uses @emph{base addresses}.  Using a
21894 base address automatically generates a request (handled by the assembler
21895 and the linker) for a constant to be set up in a global register.  The
21896 register is used for one or more base address requests within the range 0
21897 to 255 from the value held in the register.  The generally leads to short
21898 and fast code, but the number of different data items that can be
21899 addressed is limited.  This means that a program that uses lots of static
21900 data may require @option{-mno-base-addresses}.
21902 @item -msingle-exit
21903 @itemx -mno-single-exit
21904 @opindex msingle-exit
21905 @opindex mno-single-exit
21906 Force (do not force) generated code to have a single exit point in each
21907 function.
21908 @end table
21910 @node MN10300 Options
21911 @subsection MN10300 Options
21912 @cindex MN10300 options
21914 These @option{-m} options are defined for Matsushita MN10300 architectures:
21916 @table @gcctabopt
21917 @item -mmult-bug
21918 @opindex mmult-bug
21919 Generate code to avoid bugs in the multiply instructions for the MN10300
21920 processors.  This is the default.
21922 @item -mno-mult-bug
21923 @opindex mno-mult-bug
21924 Do not generate code to avoid bugs in the multiply instructions for the
21925 MN10300 processors.
21927 @item -mam33
21928 @opindex mam33
21929 Generate code using features specific to the AM33 processor.
21931 @item -mno-am33
21932 @opindex mno-am33
21933 Do not generate code using features specific to the AM33 processor.  This
21934 is the default.
21936 @item -mam33-2
21937 @opindex mam33-2
21938 Generate code using features specific to the AM33/2.0 processor.
21940 @item -mam34
21941 @opindex mam34
21942 Generate code using features specific to the AM34 processor.
21944 @item -mtune=@var{cpu-type}
21945 @opindex mtune
21946 Use the timing characteristics of the indicated CPU type when
21947 scheduling instructions.  This does not change the targeted processor
21948 type.  The CPU type must be one of @samp{mn10300}, @samp{am33},
21949 @samp{am33-2} or @samp{am34}.
21951 @item -mreturn-pointer-on-d0
21952 @opindex mreturn-pointer-on-d0
21953 When generating a function that returns a pointer, return the pointer
21954 in both @code{a0} and @code{d0}.  Otherwise, the pointer is returned
21955 only in @code{a0}, and attempts to call such functions without a prototype
21956 result in errors.  Note that this option is on by default; use
21957 @option{-mno-return-pointer-on-d0} to disable it.
21959 @item -mno-crt0
21960 @opindex mno-crt0
21961 Do not link in the C run-time initialization object file.
21963 @item -mrelax
21964 @opindex mrelax
21965 Indicate to the linker that it should perform a relaxation optimization pass
21966 to shorten branches, calls and absolute memory addresses.  This option only
21967 has an effect when used on the command line for the final link step.
21969 This option makes symbolic debugging impossible.
21971 @item -mliw
21972 @opindex mliw
21973 Allow the compiler to generate @emph{Long Instruction Word}
21974 instructions if the target is the @samp{AM33} or later.  This is the
21975 default.  This option defines the preprocessor macro @code{__LIW__}.
21977 @item -mnoliw
21978 @opindex mnoliw
21979 Do not allow the compiler to generate @emph{Long Instruction Word}
21980 instructions.  This option defines the preprocessor macro
21981 @code{__NO_LIW__}.
21983 @item -msetlb
21984 @opindex msetlb
21985 Allow the compiler to generate the @emph{SETLB} and @emph{Lcc}
21986 instructions if the target is the @samp{AM33} or later.  This is the
21987 default.  This option defines the preprocessor macro @code{__SETLB__}.
21989 @item -mnosetlb
21990 @opindex mnosetlb
21991 Do not allow the compiler to generate @emph{SETLB} or @emph{Lcc}
21992 instructions.  This option defines the preprocessor macro
21993 @code{__NO_SETLB__}.
21995 @end table
21997 @node Moxie Options
21998 @subsection Moxie Options
21999 @cindex Moxie Options
22001 @table @gcctabopt
22003 @item -meb
22004 @opindex meb
22005 Generate big-endian code.  This is the default for @samp{moxie-*-*}
22006 configurations.
22008 @item -mel
22009 @opindex mel
22010 Generate little-endian code.
22012 @item -mmul.x
22013 @opindex mmul.x
22014 Generate mul.x and umul.x instructions.  This is the default for
22015 @samp{moxiebox-*-*} configurations.
22017 @item -mno-crt0
22018 @opindex mno-crt0
22019 Do not link in the C run-time initialization object file.
22021 @end table
22023 @node MSP430 Options
22024 @subsection MSP430 Options
22025 @cindex MSP430 Options
22027 These options are defined for the MSP430:
22029 @table @gcctabopt
22031 @item -masm-hex
22032 @opindex masm-hex
22033 Force assembly output to always use hex constants.  Normally such
22034 constants are signed decimals, but this option is available for
22035 testsuite and/or aesthetic purposes.
22037 @item -mmcu=
22038 @opindex mmcu=
22039 Select the MCU to target.  This is used to create a C preprocessor
22040 symbol based upon the MCU name, converted to upper case and pre- and
22041 post-fixed with @samp{__}.  This in turn is used by the
22042 @file{msp430.h} header file to select an MCU-specific supplementary
22043 header file.
22045 The option also sets the ISA to use.  If the MCU name is one that is
22046 known to only support the 430 ISA then that is selected, otherwise the
22047 430X ISA is selected.  A generic MCU name of @samp{msp430} can also be
22048 used to select the 430 ISA.  Similarly the generic @samp{msp430x} MCU
22049 name selects the 430X ISA.
22051 In addition an MCU-specific linker script is added to the linker
22052 command line.  The script's name is the name of the MCU with
22053 @file{.ld} appended.  Thus specifying @option{-mmcu=xxx} on the @command{gcc}
22054 command line defines the C preprocessor symbol @code{__XXX__} and
22055 cause the linker to search for a script called @file{xxx.ld}.
22057 This option is also passed on to the assembler.
22059 @item -mwarn-mcu
22060 @itemx -mno-warn-mcu
22061 @opindex mwarn-mcu
22062 @opindex mno-warn-mcu
22063 This option enables or disables warnings about conflicts between the
22064 MCU name specified by the @option{-mmcu} option and the ISA set by the
22065 @option{-mcpu} option and/or the hardware multiply support set by the
22066 @option{-mhwmult} option.  It also toggles warnings about unrecognized
22067 MCU names.  This option is on by default.
22069 @item -mcpu=
22070 @opindex mcpu=
22071 Specifies the ISA to use.  Accepted values are @samp{msp430},
22072 @samp{msp430x} and @samp{msp430xv2}.  This option is deprecated.  The
22073 @option{-mmcu=} option should be used to select the ISA.
22075 @item -msim
22076 @opindex msim
22077 Link to the simulator runtime libraries and linker script.  Overrides
22078 any scripts that would be selected by the @option{-mmcu=} option.
22080 @item -mlarge
22081 @opindex mlarge
22082 Use large-model addressing (20-bit pointers, 32-bit @code{size_t}).
22084 @item -msmall
22085 @opindex msmall
22086 Use small-model addressing (16-bit pointers, 16-bit @code{size_t}).
22088 @item -mrelax
22089 @opindex mrelax
22090 This option is passed to the assembler and linker, and allows the
22091 linker to perform certain optimizations that cannot be done until
22092 the final link.
22094 @item mhwmult=
22095 @opindex mhwmult=
22096 Describes the type of hardware multiply supported by the target.
22097 Accepted values are @samp{none} for no hardware multiply, @samp{16bit}
22098 for the original 16-bit-only multiply supported by early MCUs.
22099 @samp{32bit} for the 16/32-bit multiply supported by later MCUs and
22100 @samp{f5series} for the 16/32-bit multiply supported by F5-series MCUs.
22101 A value of @samp{auto} can also be given.  This tells GCC to deduce
22102 the hardware multiply support based upon the MCU name provided by the
22103 @option{-mmcu} option.  If no @option{-mmcu} option is specified or if
22104 the MCU name is not recognized then no hardware multiply support is
22105 assumed.  @code{auto} is the default setting.
22107 Hardware multiplies are normally performed by calling a library
22108 routine.  This saves space in the generated code.  When compiling at
22109 @option{-O3} or higher however the hardware multiplier is invoked
22110 inline.  This makes for bigger, but faster code.
22112 The hardware multiply routines disable interrupts whilst running and
22113 restore the previous interrupt state when they finish.  This makes
22114 them safe to use inside interrupt handlers as well as in normal code.
22116 @item -minrt
22117 @opindex minrt
22118 Enable the use of a minimum runtime environment - no static
22119 initializers or constructors.  This is intended for memory-constrained
22120 devices.  The compiler includes special symbols in some objects
22121 that tell the linker and runtime which code fragments are required.
22123 @item -mcode-region=
22124 @itemx -mdata-region=
22125 @opindex mcode-region
22126 @opindex mdata-region
22127 These options tell the compiler where to place functions and data that
22128 do not have one of the @code{lower}, @code{upper}, @code{either} or
22129 @code{section} attributes.  Possible values are @code{lower},
22130 @code{upper}, @code{either} or @code{any}.  The first three behave
22131 like the corresponding attribute.  The fourth possible value -
22132 @code{any} - is the default.  It leaves placement entirely up to the
22133 linker script and how it assigns the standard sections
22134 (@code{.text}, @code{.data}, etc) to the memory regions.
22136 @item -msilicon-errata=
22137 @opindex msilicon-errata
22138 This option passes on a request to assembler to enable the fixes for
22139 the named silicon errata.
22141 @item -msilicon-errata-warn=
22142 @opindex msilicon-errata-warn
22143 This option passes on a request to the assembler to enable warning
22144 messages when a silicon errata might need to be applied.
22146 @end table
22148 @node NDS32 Options
22149 @subsection NDS32 Options
22150 @cindex NDS32 Options
22152 These options are defined for NDS32 implementations:
22154 @table @gcctabopt
22156 @item -mbig-endian
22157 @opindex mbig-endian
22158 Generate code in big-endian mode.
22160 @item -mlittle-endian
22161 @opindex mlittle-endian
22162 Generate code in little-endian mode.
22164 @item -mreduced-regs
22165 @opindex mreduced-regs
22166 Use reduced-set registers for register allocation.
22168 @item -mfull-regs
22169 @opindex mfull-regs
22170 Use full-set registers for register allocation.
22172 @item -mcmov
22173 @opindex mcmov
22174 Generate conditional move instructions.
22176 @item -mno-cmov
22177 @opindex mno-cmov
22178 Do not generate conditional move instructions.
22180 @item -mext-perf
22181 @opindex mperf-ext
22182 Generate performance extension instructions.
22184 @item -mno-ext-perf
22185 @opindex mno-perf-ext
22186 Do not generate performance extension instructions.
22188 @item -mext-perf2
22189 @opindex mperf-ext
22190 Generate performance extension 2 instructions.
22192 @item -mno-ext-perf2
22193 @opindex mno-perf-ext
22194 Do not generate performance extension 2 instructions.
22196 @item -mext-string
22197 @opindex mperf-ext
22198 Generate string extension instructions.
22200 @item -mno-ext-string
22201 @opindex mno-perf-ext
22202 Do not generate string extension instructions.
22204 @item -mv3push
22205 @opindex mv3push
22206 Generate v3 push25/pop25 instructions.
22208 @item -mno-v3push
22209 @opindex mno-v3push
22210 Do not generate v3 push25/pop25 instructions.
22212 @item -m16-bit
22213 @opindex m16-bit
22214 Generate 16-bit instructions.
22216 @item -mno-16-bit
22217 @opindex mno-16-bit
22218 Do not generate 16-bit instructions.
22220 @item -misr-vector-size=@var{num}
22221 @opindex misr-vector-size
22222 Specify the size of each interrupt vector, which must be 4 or 16.
22224 @item -mcache-block-size=@var{num}
22225 @opindex mcache-block-size
22226 Specify the size of each cache block,
22227 which must be a power of 2 between 4 and 512.
22229 @item -march=@var{arch}
22230 @opindex march
22231 Specify the name of the target architecture.
22233 @item -mcmodel=@var{code-model}
22234 @opindex mcmodel
22235 Set the code model to one of
22236 @table @asis
22237 @item @samp{small}
22238 All the data and read-only data segments must be within 512KB addressing space.
22239 The text segment must be within 16MB addressing space.
22240 @item @samp{medium}
22241 The data segment must be within 512KB while the read-only data segment can be
22242 within 4GB addressing space.  The text segment should be still within 16MB
22243 addressing space.
22244 @item @samp{large}
22245 All the text and data segments can be within 4GB addressing space.
22246 @end table
22248 @item -mctor-dtor
22249 @opindex mctor-dtor
22250 Enable constructor/destructor feature.
22252 @item -mrelax
22253 @opindex mrelax
22254 Guide linker to relax instructions.
22256 @end table
22258 @node Nios II Options
22259 @subsection Nios II Options
22260 @cindex Nios II options
22261 @cindex Altera Nios II options
22263 These are the options defined for the Altera Nios II processor.
22265 @table @gcctabopt
22267 @item -G @var{num}
22268 @opindex G
22269 @cindex smaller data references
22270 Put global and static objects less than or equal to @var{num} bytes
22271 into the small data or BSS sections instead of the normal data or BSS
22272 sections.  The default value of @var{num} is 8.
22274 @item -mgpopt=@var{option}
22275 @itemx -mgpopt
22276 @itemx -mno-gpopt
22277 @opindex mgpopt
22278 @opindex mno-gpopt
22279 Generate (do not generate) GP-relative accesses.  The following 
22280 @var{option} names are recognized:
22282 @table @samp
22284 @item none
22285 Do not generate GP-relative accesses.
22287 @item local
22288 Generate GP-relative accesses for small data objects that are not 
22289 external, weak, or uninitialized common symbols.  
22290 Also use GP-relative addressing for objects that
22291 have been explicitly placed in a small data section via a @code{section}
22292 attribute.
22294 @item global
22295 As for @samp{local}, but also generate GP-relative accesses for
22296 small data objects that are external, weak, or common.  If you use this option,
22297 you must ensure that all parts of your program (including libraries) are
22298 compiled with the same @option{-G} setting.
22300 @item data
22301 Generate GP-relative accesses for all data objects in the program.  If you
22302 use this option, the entire data and BSS segments
22303 of your program must fit in 64K of memory and you must use an appropriate
22304 linker script to allocate them within the addressable range of the
22305 global pointer.
22307 @item all
22308 Generate GP-relative addresses for function pointers as well as data
22309 pointers.  If you use this option, the entire text, data, and BSS segments
22310 of your program must fit in 64K of memory and you must use an appropriate
22311 linker script to allocate them within the addressable range of the
22312 global pointer.
22314 @end table
22316 @option{-mgpopt} is equivalent to @option{-mgpopt=local}, and
22317 @option{-mno-gpopt} is equivalent to @option{-mgpopt=none}.
22319 The default is @option{-mgpopt} except when @option{-fpic} or
22320 @option{-fPIC} is specified to generate position-independent code.
22321 Note that the Nios II ABI does not permit GP-relative accesses from
22322 shared libraries.
22324 You may need to specify @option{-mno-gpopt} explicitly when building
22325 programs that include large amounts of small data, including large
22326 GOT data sections.  In this case, the 16-bit offset for GP-relative
22327 addressing may not be large enough to allow access to the entire 
22328 small data section.
22330 @item -mgprel-sec=@var{regexp}
22331 @opindex mgprel-sec
22332 This option specifies additional section names that can be accessed via
22333 GP-relative addressing.  It is most useful in conjunction with 
22334 @code{section} attributes on variable declarations 
22335 (@pxref{Common Variable Attributes}) and a custom linker script.  
22336 The @var{regexp} is a POSIX Extended Regular Expression.
22338 This option does not affect the behavior of the @option{-G} option, and 
22339 the specified sections are in addition to the standard @code{.sdata}
22340 and @code{.sbss} small-data sections that are recognized by @option{-mgpopt}.
22342 @item -mr0rel-sec=@var{regexp}
22343 @opindex mr0rel-sec
22344 This option specifies names of sections that can be accessed via a 
22345 16-bit offset from @code{r0}; that is, in the low 32K or high 32K 
22346 of the 32-bit address space.  It is most useful in conjunction with 
22347 @code{section} attributes on variable declarations 
22348 (@pxref{Common Variable Attributes}) and a custom linker script.  
22349 The @var{regexp} is a POSIX Extended Regular Expression.
22351 In contrast to the use of GP-relative addressing for small data, 
22352 zero-based addressing is never generated by default and there are no 
22353 conventional section names used in standard linker scripts for sections
22354 in the low or high areas of memory.
22356 @item -mel
22357 @itemx -meb
22358 @opindex mel
22359 @opindex meb
22360 Generate little-endian (default) or big-endian (experimental) code,
22361 respectively.
22363 @item -march=@var{arch}
22364 @opindex march
22365 This specifies the name of the target Nios II architecture.  GCC uses this
22366 name to determine what kind of instructions it can emit when generating
22367 assembly code.  Permissible names are: @samp{r1}, @samp{r2}.
22369 The preprocessor macro @code{__nios2_arch__} is available to programs,
22370 with value 1 or 2, indicating the targeted ISA level.
22372 @item -mbypass-cache
22373 @itemx -mno-bypass-cache
22374 @opindex mno-bypass-cache
22375 @opindex mbypass-cache
22376 Force all load and store instructions to always bypass cache by 
22377 using I/O variants of the instructions. The default is not to
22378 bypass the cache.
22380 @item -mno-cache-volatile 
22381 @itemx -mcache-volatile       
22382 @opindex mcache-volatile 
22383 @opindex mno-cache-volatile
22384 Volatile memory access bypass the cache using the I/O variants of 
22385 the load and store instructions. The default is not to bypass the cache.
22387 @item -mno-fast-sw-div
22388 @itemx -mfast-sw-div
22389 @opindex mno-fast-sw-div
22390 @opindex mfast-sw-div
22391 Do not use table-based fast divide for small numbers. The default 
22392 is to use the fast divide at @option{-O3} and above.
22394 @item -mno-hw-mul
22395 @itemx -mhw-mul
22396 @itemx -mno-hw-mulx
22397 @itemx -mhw-mulx
22398 @itemx -mno-hw-div
22399 @itemx -mhw-div
22400 @opindex mno-hw-mul
22401 @opindex mhw-mul
22402 @opindex mno-hw-mulx
22403 @opindex mhw-mulx
22404 @opindex mno-hw-div
22405 @opindex mhw-div
22406 Enable or disable emitting @code{mul}, @code{mulx} and @code{div} family of 
22407 instructions by the compiler. The default is to emit @code{mul}
22408 and not emit @code{div} and @code{mulx}.
22410 @item -mbmx
22411 @itemx -mno-bmx
22412 @itemx -mcdx
22413 @itemx -mno-cdx
22414 Enable or disable generation of Nios II R2 BMX (bit manipulation) and
22415 CDX (code density) instructions.  Enabling these instructions also
22416 requires @option{-march=r2}.  Since these instructions are optional
22417 extensions to the R2 architecture, the default is not to emit them.
22419 @item -mcustom-@var{insn}=@var{N}
22420 @itemx -mno-custom-@var{insn}
22421 @opindex mcustom-@var{insn}
22422 @opindex mno-custom-@var{insn}
22423 Each @option{-mcustom-@var{insn}=@var{N}} option enables use of a
22424 custom instruction with encoding @var{N} when generating code that uses 
22425 @var{insn}.  For example, @option{-mcustom-fadds=253} generates custom
22426 instruction 253 for single-precision floating-point add operations instead
22427 of the default behavior of using a library call.
22429 The following values of @var{insn} are supported.  Except as otherwise
22430 noted, floating-point operations are expected to be implemented with
22431 normal IEEE 754 semantics and correspond directly to the C operators or the
22432 equivalent GCC built-in functions (@pxref{Other Builtins}).
22434 Single-precision floating point:
22435 @table @asis
22437 @item @samp{fadds}, @samp{fsubs}, @samp{fdivs}, @samp{fmuls}
22438 Binary arithmetic operations.
22440 @item @samp{fnegs}
22441 Unary negation.
22443 @item @samp{fabss}
22444 Unary absolute value.
22446 @item @samp{fcmpeqs}, @samp{fcmpges}, @samp{fcmpgts}, @samp{fcmples}, @samp{fcmplts}, @samp{fcmpnes}
22447 Comparison operations.
22449 @item @samp{fmins}, @samp{fmaxs}
22450 Floating-point minimum and maximum.  These instructions are only
22451 generated if @option{-ffinite-math-only} is specified.
22453 @item @samp{fsqrts}
22454 Unary square root operation.
22456 @item @samp{fcoss}, @samp{fsins}, @samp{ftans}, @samp{fatans}, @samp{fexps}, @samp{flogs}
22457 Floating-point trigonometric and exponential functions.  These instructions
22458 are only generated if @option{-funsafe-math-optimizations} is also specified.
22460 @end table
22462 Double-precision floating point:
22463 @table @asis
22465 @item @samp{faddd}, @samp{fsubd}, @samp{fdivd}, @samp{fmuld}
22466 Binary arithmetic operations.
22468 @item @samp{fnegd}
22469 Unary negation.
22471 @item @samp{fabsd}
22472 Unary absolute value.
22474 @item @samp{fcmpeqd}, @samp{fcmpged}, @samp{fcmpgtd}, @samp{fcmpled}, @samp{fcmpltd}, @samp{fcmpned}
22475 Comparison operations.
22477 @item @samp{fmind}, @samp{fmaxd}
22478 Double-precision minimum and maximum.  These instructions are only
22479 generated if @option{-ffinite-math-only} is specified.
22481 @item @samp{fsqrtd}
22482 Unary square root operation.
22484 @item @samp{fcosd}, @samp{fsind}, @samp{ftand}, @samp{fatand}, @samp{fexpd}, @samp{flogd}
22485 Double-precision trigonometric and exponential functions.  These instructions
22486 are only generated if @option{-funsafe-math-optimizations} is also specified.
22488 @end table
22490 Conversions:
22491 @table @asis
22492 @item @samp{fextsd}
22493 Conversion from single precision to double precision.
22495 @item @samp{ftruncds}
22496 Conversion from double precision to single precision.
22498 @item @samp{fixsi}, @samp{fixsu}, @samp{fixdi}, @samp{fixdu}
22499 Conversion from floating point to signed or unsigned integer types, with
22500 truncation towards zero.
22502 @item @samp{round}
22503 Conversion from single-precision floating point to signed integer,
22504 rounding to the nearest integer and ties away from zero.
22505 This corresponds to the @code{__builtin_lroundf} function when
22506 @option{-fno-math-errno} is used.
22508 @item @samp{floatis}, @samp{floatus}, @samp{floatid}, @samp{floatud}
22509 Conversion from signed or unsigned integer types to floating-point types.
22511 @end table
22513 In addition, all of the following transfer instructions for internal
22514 registers X and Y must be provided to use any of the double-precision
22515 floating-point instructions.  Custom instructions taking two
22516 double-precision source operands expect the first operand in the
22517 64-bit register X.  The other operand (or only operand of a unary
22518 operation) is given to the custom arithmetic instruction with the
22519 least significant half in source register @var{src1} and the most
22520 significant half in @var{src2}.  A custom instruction that returns a
22521 double-precision result returns the most significant 32 bits in the
22522 destination register and the other half in 32-bit register Y.  
22523 GCC automatically generates the necessary code sequences to write
22524 register X and/or read register Y when double-precision floating-point
22525 instructions are used.
22527 @table @asis
22529 @item @samp{fwrx}
22530 Write @var{src1} into the least significant half of X and @var{src2} into
22531 the most significant half of X.
22533 @item @samp{fwry}
22534 Write @var{src1} into Y.
22536 @item @samp{frdxhi}, @samp{frdxlo}
22537 Read the most or least (respectively) significant half of X and store it in
22538 @var{dest}.
22540 @item @samp{frdy}
22541 Read the value of Y and store it into @var{dest}.
22542 @end table
22544 Note that you can gain more local control over generation of Nios II custom
22545 instructions by using the @code{target("custom-@var{insn}=@var{N}")}
22546 and @code{target("no-custom-@var{insn}")} function attributes
22547 (@pxref{Function Attributes})
22548 or pragmas (@pxref{Function Specific Option Pragmas}).
22550 @item -mcustom-fpu-cfg=@var{name}
22551 @opindex mcustom-fpu-cfg
22553 This option enables a predefined, named set of custom instruction encodings
22554 (see @option{-mcustom-@var{insn}} above).  
22555 Currently, the following sets are defined:
22557 @option{-mcustom-fpu-cfg=60-1} is equivalent to:
22558 @gccoptlist{-mcustom-fmuls=252 @gol
22559 -mcustom-fadds=253 @gol
22560 -mcustom-fsubs=254 @gol
22561 -fsingle-precision-constant}
22563 @option{-mcustom-fpu-cfg=60-2} is equivalent to:
22564 @gccoptlist{-mcustom-fmuls=252 @gol
22565 -mcustom-fadds=253 @gol
22566 -mcustom-fsubs=254 @gol
22567 -mcustom-fdivs=255 @gol
22568 -fsingle-precision-constant}
22570 @option{-mcustom-fpu-cfg=72-3} is equivalent to:
22571 @gccoptlist{-mcustom-floatus=243 @gol
22572 -mcustom-fixsi=244 @gol
22573 -mcustom-floatis=245 @gol
22574 -mcustom-fcmpgts=246 @gol
22575 -mcustom-fcmples=249 @gol
22576 -mcustom-fcmpeqs=250 @gol
22577 -mcustom-fcmpnes=251 @gol
22578 -mcustom-fmuls=252 @gol
22579 -mcustom-fadds=253 @gol
22580 -mcustom-fsubs=254 @gol
22581 -mcustom-fdivs=255 @gol
22582 -fsingle-precision-constant}
22584 Custom instruction assignments given by individual
22585 @option{-mcustom-@var{insn}=} options override those given by
22586 @option{-mcustom-fpu-cfg=}, regardless of the
22587 order of the options on the command line.
22589 Note that you can gain more local control over selection of a FPU
22590 configuration by using the @code{target("custom-fpu-cfg=@var{name}")}
22591 function attribute (@pxref{Function Attributes})
22592 or pragma (@pxref{Function Specific Option Pragmas}).
22594 @end table
22596 These additional @samp{-m} options are available for the Altera Nios II
22597 ELF (bare-metal) target:
22599 @table @gcctabopt
22601 @item -mhal
22602 @opindex mhal
22603 Link with HAL BSP.  This suppresses linking with the GCC-provided C runtime
22604 startup and termination code, and is typically used in conjunction with
22605 @option{-msys-crt0=} to specify the location of the alternate startup code
22606 provided by the HAL BSP.
22608 @item -msmallc
22609 @opindex msmallc
22610 Link with a limited version of the C library, @option{-lsmallc}, rather than
22611 Newlib.
22613 @item -msys-crt0=@var{startfile}
22614 @opindex msys-crt0
22615 @var{startfile} is the file name of the startfile (crt0) to use 
22616 when linking.  This option is only useful in conjunction with @option{-mhal}.
22618 @item -msys-lib=@var{systemlib}
22619 @opindex msys-lib
22620 @var{systemlib} is the library name of the library that provides
22621 low-level system calls required by the C library,
22622 e.g. @code{read} and @code{write}.
22623 This option is typically used to link with a library provided by a HAL BSP.
22625 @end table
22627 @node Nvidia PTX Options
22628 @subsection Nvidia PTX Options
22629 @cindex Nvidia PTX options
22630 @cindex nvptx options
22632 These options are defined for Nvidia PTX:
22634 @table @gcctabopt
22636 @item -m32
22637 @itemx -m64
22638 @opindex m32
22639 @opindex m64
22640 Generate code for 32-bit or 64-bit ABI.
22642 @item -misa=@var{ISA-string}
22643 @opindex march
22644 Generate code for given the specified PTX ISA (e.g.@ @samp{sm_35}).  ISA
22645 strings must be lower-case.  Valid ISA strings include @samp{sm_30} and
22646 @samp{sm_35}.  The default ISA is sm_30.
22648 @item -mmainkernel
22649 @opindex mmainkernel
22650 Link in code for a __main kernel.  This is for stand-alone instead of
22651 offloading execution.
22653 @item -moptimize
22654 @opindex moptimize
22655 Apply partitioned execution optimizations.  This is the default when any
22656 level of optimization is selected.
22658 @item -msoft-stack
22659 @opindex msoft-stack
22660 Generate code that does not use @code{.local} memory
22661 directly for stack storage. Instead, a per-warp stack pointer is
22662 maintained explicitly. This enables variable-length stack allocation (with
22663 variable-length arrays or @code{alloca}), and when global memory is used for
22664 underlying storage, makes it possible to access automatic variables from other
22665 threads, or with atomic instructions. This code generation variant is used
22666 for OpenMP offloading, but the option is exposed on its own for the purpose
22667 of testing the compiler; to generate code suitable for linking into programs
22668 using OpenMP offloading, use option @option{-mgomp}.
22670 @item -muniform-simt
22671 @opindex muniform-simt
22672 Switch to code generation variant that allows to execute all threads in each
22673 warp, while maintaining memory state and side effects as if only one thread
22674 in each warp was active outside of OpenMP SIMD regions.  All atomic operations
22675 and calls to runtime (malloc, free, vprintf) are conditionally executed (iff
22676 current lane index equals the master lane index), and the register being
22677 assigned is copied via a shuffle instruction from the master lane.  Outside of
22678 SIMD regions lane 0 is the master; inside, each thread sees itself as the
22679 master.  Shared memory array @code{int __nvptx_uni[]} stores all-zeros or
22680 all-ones bitmasks for each warp, indicating current mode (0 outside of SIMD
22681 regions).  Each thread can bitwise-and the bitmask at position @code{tid.y}
22682 with current lane index to compute the master lane index.
22684 @item -mgomp
22685 @opindex mgomp
22686 Generate code for use in OpenMP offloading: enables @option{-msoft-stack} and
22687 @option{-muniform-simt} options, and selects corresponding multilib variant.
22689 @end table
22691 @node PDP-11 Options
22692 @subsection PDP-11 Options
22693 @cindex PDP-11 Options
22695 These options are defined for the PDP-11:
22697 @table @gcctabopt
22698 @item -mfpu
22699 @opindex mfpu
22700 Use hardware FPP floating point.  This is the default.  (FIS floating
22701 point on the PDP-11/40 is not supported.)  Implies -m45.
22703 @item -msoft-float
22704 @opindex msoft-float
22705 Do not use hardware floating point.
22707 @item -mac0
22708 @opindex mac0
22709 Return floating-point results in ac0 (fr0 in Unix assembler syntax).
22711 @item -mno-ac0
22712 @opindex mno-ac0
22713 Return floating-point results in memory.  This is the default.
22715 @item -m40
22716 @opindex m40
22717 Generate code for a PDP-11/40.  Implies -msoft-float -mno-split.
22719 @item -m45
22720 @opindex m45
22721 Generate code for a PDP-11/45.  This is the default.
22723 @item -m10
22724 @opindex m10
22725 Generate code for a PDP-11/10.  Implies -msoft-float -mno-split.
22727 @item -mint16
22728 @itemx -mno-int32
22729 @opindex mint16
22730 @opindex mno-int32
22731 Use 16-bit @code{int}.  This is the default.
22733 @item -mint32
22734 @itemx -mno-int16
22735 @opindex mint32
22736 @opindex mno-int16
22737 Use 32-bit @code{int}.
22739 @item -msplit
22740 @opindex msplit
22741 Target has split instruction and data space.  Implies -m45.
22743 @item -munix-asm
22744 @opindex munix-asm
22745 Use Unix assembler syntax.
22747 @item -mdec-asm
22748 @opindex mdec-asm
22749 Use DEC assembler syntax.
22751 @item -mgnu-asm
22752 @opindex mgnu-asm
22753 Use GNU assembler syntax.  This is the default.
22755 @item -mlra
22756 @opindex mlra
22757 Use the new LRA register allocator.  By default, the old ``reload''
22758 allocator is used.
22759 @end table
22761 @node picoChip Options
22762 @subsection picoChip Options
22763 @cindex picoChip options
22765 These @samp{-m} options are defined for picoChip implementations:
22767 @table @gcctabopt
22769 @item -mae=@var{ae_type}
22770 @opindex mcpu
22771 Set the instruction set, register set, and instruction scheduling
22772 parameters for array element type @var{ae_type}.  Supported values
22773 for @var{ae_type} are @samp{ANY}, @samp{MUL}, and @samp{MAC}.
22775 @option{-mae=ANY} selects a completely generic AE type.  Code
22776 generated with this option runs on any of the other AE types.  The
22777 code is not as efficient as it would be if compiled for a specific
22778 AE type, and some types of operation (e.g., multiplication) do not
22779 work properly on all types of AE.
22781 @option{-mae=MUL} selects a MUL AE type.  This is the most useful AE type
22782 for compiled code, and is the default.
22784 @option{-mae=MAC} selects a DSP-style MAC AE.  Code compiled with this
22785 option may suffer from poor performance of byte (char) manipulation,
22786 since the DSP AE does not provide hardware support for byte load/stores.
22788 @item -msymbol-as-address
22789 Enable the compiler to directly use a symbol name as an address in a
22790 load/store instruction, without first loading it into a
22791 register.  Typically, the use of this option generates larger
22792 programs, which run faster than when the option isn't used.  However, the
22793 results vary from program to program, so it is left as a user option,
22794 rather than being permanently enabled.
22796 @item -mno-inefficient-warnings
22797 Disables warnings about the generation of inefficient code.  These
22798 warnings can be generated, for example, when compiling code that
22799 performs byte-level memory operations on the MAC AE type.  The MAC AE has
22800 no hardware support for byte-level memory operations, so all byte
22801 load/stores must be synthesized from word load/store operations.  This is
22802 inefficient and a warning is generated to indicate
22803 that you should rewrite the code to avoid byte operations, or to target
22804 an AE type that has the necessary hardware support.  This option disables
22805 these warnings.
22807 @end table
22809 @node PowerPC Options
22810 @subsection PowerPC Options
22811 @cindex PowerPC options
22813 These are listed under @xref{RS/6000 and PowerPC Options}.
22815 @node PowerPC SPE Options
22816 @subsection PowerPC SPE Options
22817 @cindex PowerPC SPE options
22819 These @samp{-m} options are defined for PowerPC SPE:
22820 @table @gcctabopt
22821 @item -mmfcrf
22822 @itemx -mno-mfcrf
22823 @itemx -mpopcntb
22824 @itemx -mno-popcntb
22825 @opindex mmfcrf
22826 @opindex mno-mfcrf
22827 @opindex mpopcntb
22828 @opindex mno-popcntb
22829 You use these options to specify which instructions are available on the
22830 processor you are using.  The default value of these options is
22831 determined when configuring GCC@.  Specifying the
22832 @option{-mcpu=@var{cpu_type}} overrides the specification of these
22833 options.  We recommend you use the @option{-mcpu=@var{cpu_type}} option
22834 rather than the options listed above.
22836 The @option{-mmfcrf} option allows GCC to generate the move from
22837 condition register field instruction implemented on the POWER4
22838 processor and other processors that support the PowerPC V2.01
22839 architecture.
22840 The @option{-mpopcntb} option allows GCC to generate the popcount and
22841 double-precision FP reciprocal estimate instruction implemented on the
22842 POWER5 processor and other processors that support the PowerPC V2.02
22843 architecture.
22845 @item -mcpu=@var{cpu_type}
22846 @opindex mcpu
22847 Set architecture type, register usage, and
22848 instruction scheduling parameters for machine type @var{cpu_type}.
22849 Supported values for @var{cpu_type} are @samp{8540}, @samp{8548},
22850 and @samp{native}.
22852 @option{-mcpu=powerpc} specifies pure 32-bit PowerPC (either
22853 endian), with an appropriate, generic processor model assumed for
22854 scheduling purposes.
22856 Specifying @samp{native} as cpu type detects and selects the
22857 architecture option that corresponds to the host processor of the
22858 system performing the compilation.
22859 @option{-mcpu=native} has no effect if GCC does not recognize the
22860 processor.
22862 The other options specify a specific processor.  Code generated under
22863 those options runs best on that processor, and may not run at all on
22864 others.
22866 The @option{-mcpu} options automatically enable or disable the
22867 following options:
22869 @gccoptlist{-mhard-float  -mmfcrf  -mmultiple @gol
22870 -mpopcntb -mpopcntd @gol
22871 -msingle-float -mdouble-float @gol
22872 -mfloat128}
22874 The particular options set for any particular CPU varies between
22875 compiler versions, depending on what setting seems to produce optimal
22876 code for that CPU; it doesn't necessarily reflect the actual hardware's
22877 capabilities.  If you wish to set an individual option to a particular
22878 value, you may specify it after the @option{-mcpu} option, like
22879 @option{-mcpu=8548}.
22881 @item -mtune=@var{cpu_type}
22882 @opindex mtune
22883 Set the instruction scheduling parameters for machine type
22884 @var{cpu_type}, but do not set the architecture type or register usage,
22885 as @option{-mcpu=@var{cpu_type}} does.  The same
22886 values for @var{cpu_type} are used for @option{-mtune} as for
22887 @option{-mcpu}.  If both are specified, the code generated uses the
22888 architecture and registers set by @option{-mcpu}, but the
22889 scheduling parameters set by @option{-mtune}.
22891 @item -msecure-plt
22892 @opindex msecure-plt
22893 Generate code that allows @command{ld} and @command{ld.so}
22894 to build executables and shared
22895 libraries with non-executable @code{.plt} and @code{.got} sections.
22896 This is a PowerPC
22897 32-bit SYSV ABI option.
22899 @item -mbss-plt
22900 @opindex mbss-plt
22901 Generate code that uses a BSS @code{.plt} section that @command{ld.so}
22902 fills in, and
22903 requires @code{.plt} and @code{.got}
22904 sections that are both writable and executable.
22905 This is a PowerPC 32-bit SYSV ABI option.
22907 @item -misel
22908 @itemx -mno-isel
22909 @opindex misel
22910 @opindex mno-isel
22911 This switch enables or disables the generation of ISEL instructions.
22913 @item -misel=@var{yes/no}
22914 This switch has been deprecated.  Use @option{-misel} and
22915 @option{-mno-isel} instead.
22917 @item -mspe
22918 @itemx -mno-spe
22919 @opindex mspe
22920 @opindex mno-spe
22921 This switch enables or disables the generation of SPE simd
22922 instructions.
22924 @item -mspe=@var{yes/no}
22925 This option has been deprecated.  Use @option{-mspe} and
22926 @option{-mno-spe} instead.
22928 @item -mfloat128
22929 @itemx -mno-float128
22930 @opindex mfloat128
22931 @opindex mno-float128
22932 Enable/disable the @var{__float128} keyword for IEEE 128-bit floating point
22933 and use either software emulation for IEEE 128-bit floating point or
22934 hardware instructions.
22936 @item -mfloat-gprs=@var{yes/single/double/no}
22937 @itemx -mfloat-gprs
22938 @opindex mfloat-gprs
22939 This switch enables or disables the generation of floating-point
22940 operations on the general-purpose registers for architectures that
22941 support it.
22943 The argument @samp{yes} or @samp{single} enables the use of
22944 single-precision floating-point operations.
22946 The argument @samp{double} enables the use of single and
22947 double-precision floating-point operations.
22949 The argument @samp{no} disables floating-point operations on the
22950 general-purpose registers.
22952 This option is currently only available on the MPC854x.
22954 @item -mfull-toc
22955 @itemx -mno-fp-in-toc
22956 @itemx -mno-sum-in-toc
22957 @itemx -mminimal-toc
22958 @opindex mfull-toc
22959 @opindex mno-fp-in-toc
22960 @opindex mno-sum-in-toc
22961 @opindex mminimal-toc
22962 Modify generation of the TOC (Table Of Contents), which is created for
22963 every executable file.  The @option{-mfull-toc} option is selected by
22964 default.  In that case, GCC allocates at least one TOC entry for
22965 each unique non-automatic variable reference in your program.  GCC
22966 also places floating-point constants in the TOC@.  However, only
22967 16,384 entries are available in the TOC@.
22969 If you receive a linker error message that saying you have overflowed
22970 the available TOC space, you can reduce the amount of TOC space used
22971 with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
22972 @option{-mno-fp-in-toc} prevents GCC from putting floating-point
22973 constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
22974 generate code to calculate the sum of an address and a constant at
22975 run time instead of putting that sum into the TOC@.  You may specify one
22976 or both of these options.  Each causes GCC to produce very slightly
22977 slower and larger code at the expense of conserving TOC space.
22979 If you still run out of space in the TOC even when you specify both of
22980 these options, specify @option{-mminimal-toc} instead.  This option causes
22981 GCC to make only one TOC entry for every file.  When you specify this
22982 option, GCC produces code that is slower and larger but which
22983 uses extremely little TOC space.  You may wish to use this option
22984 only on files that contain less frequently-executed code.
22986 @item -maix32
22987 @opindex maix32
22988 Disables the 64-bit ABI.  GCC defaults to @option{-maix32}.
22990 @item -mxl-compat
22991 @itemx -mno-xl-compat
22992 @opindex mxl-compat
22993 @opindex mno-xl-compat
22994 Produce code that conforms more closely to IBM XL compiler semantics
22995 when using AIX-compatible ABI@.  Pass floating-point arguments to
22996 prototyped functions beyond the register save area (RSA) on the stack
22997 in addition to argument FPRs.  Do not assume that most significant
22998 double in 128-bit long double value is properly rounded when comparing
22999 values and converting to double.  Use XL symbol names for long double
23000 support routines.
23002 The AIX calling convention was extended but not initially documented to
23003 handle an obscure K&R C case of calling a function that takes the
23004 address of its arguments with fewer arguments than declared.  IBM XL
23005 compilers access floating-point arguments that do not fit in the
23006 RSA from the stack when a subroutine is compiled without
23007 optimization.  Because always storing floating-point arguments on the
23008 stack is inefficient and rarely needed, this option is not enabled by
23009 default and only is necessary when calling subroutines compiled by IBM
23010 XL compilers without optimization.
23012 @item -malign-natural
23013 @itemx -malign-power
23014 @opindex malign-natural
23015 @opindex malign-power
23016 On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
23017 @option{-malign-natural} overrides the ABI-defined alignment of larger
23018 types, such as floating-point doubles, on their natural size-based boundary.
23019 The option @option{-malign-power} instructs GCC to follow the ABI-specified
23020 alignment rules.  GCC defaults to the standard alignment defined in the ABI@.
23022 On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
23023 is not supported.
23025 @item -msoft-float
23026 @itemx -mhard-float
23027 @opindex msoft-float
23028 @opindex mhard-float
23029 Generate code that does not use (uses) the floating-point register set.
23030 Software floating-point emulation is provided if you use the
23031 @option{-msoft-float} option, and pass the option to GCC when linking.
23033 @item -msingle-float
23034 @itemx -mdouble-float
23035 @opindex msingle-float
23036 @opindex mdouble-float
23037 Generate code for single- or double-precision floating-point operations.
23038 @option{-mdouble-float} implies @option{-msingle-float}.
23040 @item -mmultiple
23041 @itemx -mno-multiple
23042 @opindex mmultiple
23043 @opindex mno-multiple
23044 Generate code that uses (does not use) the load multiple word
23045 instructions and the store multiple word instructions.  These
23046 instructions are generated by default on POWER systems, and not
23047 generated on PowerPC systems.  Do not use @option{-mmultiple} on little-endian
23048 PowerPC systems, since those instructions do not work when the
23049 processor is in little-endian mode.  The exceptions are PPC740 and
23050 PPC750 which permit these instructions in little-endian mode.
23052 @item -mupdate
23053 @itemx -mno-update
23054 @opindex mupdate
23055 @opindex mno-update
23056 Generate code that uses (does not use) the load or store instructions
23057 that update the base register to the address of the calculated memory
23058 location.  These instructions are generated by default.  If you use
23059 @option{-mno-update}, there is a small window between the time that the
23060 stack pointer is updated and the address of the previous frame is
23061 stored, which means code that walks the stack frame across interrupts or
23062 signals may get corrupted data.
23064 @item -mavoid-indexed-addresses
23065 @itemx -mno-avoid-indexed-addresses
23066 @opindex mavoid-indexed-addresses
23067 @opindex mno-avoid-indexed-addresses
23068 Generate code that tries to avoid (not avoid) the use of indexed load
23069 or store instructions. These instructions can incur a performance
23070 penalty on Power6 processors in certain situations, such as when
23071 stepping through large arrays that cross a 16M boundary.  This option
23072 is enabled by default when targeting Power6 and disabled otherwise.
23074 @item -mfused-madd
23075 @itemx -mno-fused-madd
23076 @opindex mfused-madd
23077 @opindex mno-fused-madd
23078 Generate code that uses (does not use) the floating-point multiply and
23079 accumulate instructions.  These instructions are generated by default
23080 if hardware floating point is used.  The machine-dependent
23081 @option{-mfused-madd} option is now mapped to the machine-independent
23082 @option{-ffp-contract=fast} option, and @option{-mno-fused-madd} is
23083 mapped to @option{-ffp-contract=off}.
23085 @item -mno-strict-align
23086 @itemx -mstrict-align
23087 @opindex mno-strict-align
23088 @opindex mstrict-align
23089 On System V.4 and embedded PowerPC systems do not (do) assume that
23090 unaligned memory references are handled by the system.
23092 @item -mrelocatable
23093 @itemx -mno-relocatable
23094 @opindex mrelocatable
23095 @opindex mno-relocatable
23096 Generate code that allows (does not allow) a static executable to be
23097 relocated to a different address at run time.  A simple embedded
23098 PowerPC system loader should relocate the entire contents of
23099 @code{.got2} and 4-byte locations listed in the @code{.fixup} section,
23100 a table of 32-bit addresses generated by this option.  For this to
23101 work, all objects linked together must be compiled with
23102 @option{-mrelocatable} or @option{-mrelocatable-lib}.
23103 @option{-mrelocatable} code aligns the stack to an 8-byte boundary.
23105 @item -mrelocatable-lib
23106 @itemx -mno-relocatable-lib
23107 @opindex mrelocatable-lib
23108 @opindex mno-relocatable-lib
23109 Like @option{-mrelocatable}, @option{-mrelocatable-lib} generates a
23110 @code{.fixup} section to allow static executables to be relocated at
23111 run time, but @option{-mrelocatable-lib} does not use the smaller stack
23112 alignment of @option{-mrelocatable}.  Objects compiled with
23113 @option{-mrelocatable-lib} may be linked with objects compiled with
23114 any combination of the @option{-mrelocatable} options.
23116 @item -mno-toc
23117 @itemx -mtoc
23118 @opindex mno-toc
23119 @opindex mtoc
23120 On System V.4 and embedded PowerPC systems do not (do) assume that
23121 register 2 contains a pointer to a global area pointing to the addresses
23122 used in the program.
23124 @item -mlittle
23125 @itemx -mlittle-endian
23126 @opindex mlittle
23127 @opindex mlittle-endian
23128 On System V.4 and embedded PowerPC systems compile code for the
23129 processor in little-endian mode.  The @option{-mlittle-endian} option is
23130 the same as @option{-mlittle}.
23132 @item -mbig
23133 @itemx -mbig-endian
23134 @opindex mbig
23135 @opindex mbig-endian
23136 On System V.4 and embedded PowerPC systems compile code for the
23137 processor in big-endian mode.  The @option{-mbig-endian} option is
23138 the same as @option{-mbig}.
23140 @item -mdynamic-no-pic
23141 @opindex mdynamic-no-pic
23142 On Darwin and Mac OS X systems, compile code so that it is not
23143 relocatable, but that its external references are relocatable.  The
23144 resulting code is suitable for applications, but not shared
23145 libraries.
23147 @item -msingle-pic-base
23148 @opindex msingle-pic-base
23149 Treat the register used for PIC addressing as read-only, rather than
23150 loading it in the prologue for each function.  The runtime system is
23151 responsible for initializing this register with an appropriate value
23152 before execution begins.
23154 @item -mprioritize-restricted-insns=@var{priority}
23155 @opindex mprioritize-restricted-insns
23156 This option controls the priority that is assigned to
23157 dispatch-slot restricted instructions during the second scheduling
23158 pass.  The argument @var{priority} takes the value @samp{0}, @samp{1},
23159 or @samp{2} to assign no, highest, or second-highest (respectively)
23160 priority to dispatch-slot restricted
23161 instructions.
23163 @item -msched-costly-dep=@var{dependence_type}
23164 @opindex msched-costly-dep
23165 This option controls which dependences are considered costly
23166 by the target during instruction scheduling.  The argument
23167 @var{dependence_type} takes one of the following values:
23169 @table @asis
23170 @item @samp{no}
23171 No dependence is costly.
23173 @item @samp{all}
23174 All dependences are costly.
23176 @item @samp{true_store_to_load}
23177 A true dependence from store to load is costly.
23179 @item @samp{store_to_load}
23180 Any dependence from store to load is costly.
23182 @item @var{number}
23183 Any dependence for which the latency is greater than or equal to
23184 @var{number} is costly.
23185 @end table
23187 @item -minsert-sched-nops=@var{scheme}
23188 @opindex minsert-sched-nops
23189 This option controls which NOP insertion scheme is used during
23190 the second scheduling pass.  The argument @var{scheme} takes one of the
23191 following values:
23193 @table @asis
23194 @item @samp{no}
23195 Don't insert NOPs.
23197 @item @samp{pad}
23198 Pad with NOPs any dispatch group that has vacant issue slots,
23199 according to the scheduler's grouping.
23201 @item @samp{regroup_exact}
23202 Insert NOPs to force costly dependent insns into
23203 separate groups.  Insert exactly as many NOPs as needed to force an insn
23204 to a new group, according to the estimated processor grouping.
23206 @item @var{number}
23207 Insert NOPs to force costly dependent insns into
23208 separate groups.  Insert @var{number} NOPs to force an insn to a new group.
23209 @end table
23211 @item -mcall-sysv
23212 @opindex mcall-sysv
23213 On System V.4 and embedded PowerPC systems compile code using calling
23214 conventions that adhere to the March 1995 draft of the System V
23215 Application Binary Interface, PowerPC processor supplement.  This is the
23216 default unless you configured GCC using @samp{powerpc-*-eabiaix}.
23218 @item -mcall-sysv-eabi
23219 @itemx -mcall-eabi
23220 @opindex mcall-sysv-eabi
23221 @opindex mcall-eabi
23222 Specify both @option{-mcall-sysv} and @option{-meabi} options.
23224 @item -mcall-sysv-noeabi
23225 @opindex mcall-sysv-noeabi
23226 Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
23228 @item -mcall-aixdesc
23229 @opindex m
23230 On System V.4 and embedded PowerPC systems compile code for the AIX
23231 operating system.
23233 @item -mcall-linux
23234 @opindex mcall-linux
23235 On System V.4 and embedded PowerPC systems compile code for the
23236 Linux-based GNU system.
23238 @item -mcall-freebsd
23239 @opindex mcall-freebsd
23240 On System V.4 and embedded PowerPC systems compile code for the
23241 FreeBSD operating system.
23243 @item -mcall-netbsd
23244 @opindex mcall-netbsd
23245 On System V.4 and embedded PowerPC systems compile code for the
23246 NetBSD operating system.
23248 @item -mcall-openbsd
23249 @opindex mcall-netbsd
23250 On System V.4 and embedded PowerPC systems compile code for the
23251 OpenBSD operating system.
23253 @item -maix-struct-return
23254 @opindex maix-struct-return
23255 Return all structures in memory (as specified by the AIX ABI)@.
23257 @item -msvr4-struct-return
23258 @opindex msvr4-struct-return
23259 Return structures smaller than 8 bytes in registers (as specified by the
23260 SVR4 ABI)@.
23262 @item -mabi=@var{abi-type}
23263 @opindex mabi
23264 Extend the current ABI with a particular extension, or remove such extension.
23265 Valid values are @samp{altivec}, @samp{no-altivec}, @samp{spe},
23266 @samp{no-spe}, @samp{ibmlongdouble}, @samp{ieeelongdouble},
23267 @samp{elfv1}, @samp{elfv2}@.
23269 @item -mabi=spe
23270 @opindex mabi=spe
23271 Extend the current ABI with SPE ABI extensions.  This does not change
23272 the default ABI, instead it adds the SPE ABI extensions to the current
23273 ABI@.
23275 @item -mabi=no-spe
23276 @opindex mabi=no-spe
23277 Disable Book-E SPE ABI extensions for the current ABI@.
23279 @item -mabi=ibmlongdouble
23280 @opindex mabi=ibmlongdouble
23281 Change the current ABI to use IBM extended-precision long double.
23282 This is not likely to work if your system defaults to using IEEE
23283 extended-precision long double.  If you change the long double type
23284 from IEEE extended-precision, the compiler will issue a warning unless
23285 you use the @option{-Wno-psabi} option.
23287 @item -mabi=ieeelongdouble
23288 @opindex mabi=ieeelongdouble
23289 Change the current ABI to use IEEE extended-precision long double.
23290 This is not likely to work if your system defaults to using IBM
23291 extended-precision long double.  If you change the long double type
23292 from IBM extended-precision, the compiler will issue a warning unless
23293 you use the @option{-Wno-psabi} option.
23295 @item -mabi=elfv1
23296 @opindex mabi=elfv1
23297 Change the current ABI to use the ELFv1 ABI.
23298 This is the default ABI for big-endian PowerPC 64-bit Linux.
23299 Overriding the default ABI requires special system support and is
23300 likely to fail in spectacular ways.
23302 @item -mabi=elfv2
23303 @opindex mabi=elfv2
23304 Change the current ABI to use the ELFv2 ABI.
23305 This is the default ABI for little-endian PowerPC 64-bit Linux.
23306 Overriding the default ABI requires special system support and is
23307 likely to fail in spectacular ways.
23309 @item -mgnu-attribute
23310 @itemx -mno-gnu-attribute
23311 @opindex mgnu-attribute
23312 @opindex mno-gnu-attribute
23313 Emit .gnu_attribute assembly directives to set tag/value pairs in a
23314 .gnu.attributes section that specify ABI variations in function
23315 parameters or return values.
23317 @item -mprototype
23318 @itemx -mno-prototype
23319 @opindex mprototype
23320 @opindex mno-prototype
23321 On System V.4 and embedded PowerPC systems assume that all calls to
23322 variable argument functions are properly prototyped.  Otherwise, the
23323 compiler must insert an instruction before every non-prototyped call to
23324 set or clear bit 6 of the condition code register (@code{CR}) to
23325 indicate whether floating-point values are passed in the floating-point
23326 registers in case the function takes variable arguments.  With
23327 @option{-mprototype}, only calls to prototyped variable argument functions
23328 set or clear the bit.
23330 @item -msim
23331 @opindex msim
23332 On embedded PowerPC systems, assume that the startup module is called
23333 @file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
23334 @file{libc.a}.  This is the default for @samp{powerpc-*-eabisim}
23335 configurations.
23337 @item -mmvme
23338 @opindex mmvme
23339 On embedded PowerPC systems, assume that the startup module is called
23340 @file{crt0.o} and the standard C libraries are @file{libmvme.a} and
23341 @file{libc.a}.
23343 @item -mads
23344 @opindex mads
23345 On embedded PowerPC systems, assume that the startup module is called
23346 @file{crt0.o} and the standard C libraries are @file{libads.a} and
23347 @file{libc.a}.
23349 @item -myellowknife
23350 @opindex myellowknife
23351 On embedded PowerPC systems, assume that the startup module is called
23352 @file{crt0.o} and the standard C libraries are @file{libyk.a} and
23353 @file{libc.a}.
23355 @item -mvxworks
23356 @opindex mvxworks
23357 On System V.4 and embedded PowerPC systems, specify that you are
23358 compiling for a VxWorks system.
23360 @item -memb
23361 @opindex memb
23362 On embedded PowerPC systems, set the @code{PPC_EMB} bit in the ELF flags
23363 header to indicate that @samp{eabi} extended relocations are used.
23365 @item -meabi
23366 @itemx -mno-eabi
23367 @opindex meabi
23368 @opindex mno-eabi
23369 On System V.4 and embedded PowerPC systems do (do not) adhere to the
23370 Embedded Applications Binary Interface (EABI), which is a set of
23371 modifications to the System V.4 specifications.  Selecting @option{-meabi}
23372 means that the stack is aligned to an 8-byte boundary, a function
23373 @code{__eabi} is called from @code{main} to set up the EABI
23374 environment, and the @option{-msdata} option can use both @code{r2} and
23375 @code{r13} to point to two separate small data areas.  Selecting
23376 @option{-mno-eabi} means that the stack is aligned to a 16-byte boundary,
23377 no EABI initialization function is called from @code{main}, and the
23378 @option{-msdata} option only uses @code{r13} to point to a single
23379 small data area.  The @option{-meabi} option is on by default if you
23380 configured GCC using one of the @samp{powerpc*-*-eabi*} options.
23382 @item -msdata=eabi
23383 @opindex msdata=eabi
23384 On System V.4 and embedded PowerPC systems, put small initialized
23385 @code{const} global and static data in the @code{.sdata2} section, which
23386 is pointed to by register @code{r2}.  Put small initialized
23387 non-@code{const} global and static data in the @code{.sdata} section,
23388 which is pointed to by register @code{r13}.  Put small uninitialized
23389 global and static data in the @code{.sbss} section, which is adjacent to
23390 the @code{.sdata} section.  The @option{-msdata=eabi} option is
23391 incompatible with the @option{-mrelocatable} option.  The
23392 @option{-msdata=eabi} option also sets the @option{-memb} option.
23394 @item -msdata=sysv
23395 @opindex msdata=sysv
23396 On System V.4 and embedded PowerPC systems, put small global and static
23397 data in the @code{.sdata} section, which is pointed to by register
23398 @code{r13}.  Put small uninitialized global and static data in the
23399 @code{.sbss} section, which is adjacent to the @code{.sdata} section.
23400 The @option{-msdata=sysv} option is incompatible with the
23401 @option{-mrelocatable} option.
23403 @item -msdata=default
23404 @itemx -msdata
23405 @opindex msdata=default
23406 @opindex msdata
23407 On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
23408 compile code the same as @option{-msdata=eabi}, otherwise compile code the
23409 same as @option{-msdata=sysv}.
23411 @item -msdata=data
23412 @opindex msdata=data
23413 On System V.4 and embedded PowerPC systems, put small global
23414 data in the @code{.sdata} section.  Put small uninitialized global
23415 data in the @code{.sbss} section.  Do not use register @code{r13}
23416 to address small data however.  This is the default behavior unless
23417 other @option{-msdata} options are used.
23419 @item -msdata=none
23420 @itemx -mno-sdata
23421 @opindex msdata=none
23422 @opindex mno-sdata
23423 On embedded PowerPC systems, put all initialized global and static data
23424 in the @code{.data} section, and all uninitialized data in the
23425 @code{.bss} section.
23427 @item -mblock-move-inline-limit=@var{num}
23428 @opindex mblock-move-inline-limit
23429 Inline all block moves (such as calls to @code{memcpy} or structure
23430 copies) less than or equal to @var{num} bytes.  The minimum value for
23431 @var{num} is 32 bytes on 32-bit targets and 64 bytes on 64-bit
23432 targets.  The default value is target-specific.
23434 @item -G @var{num}
23435 @opindex G
23436 @cindex smaller data references (PowerPC)
23437 @cindex .sdata/.sdata2 references (PowerPC)
23438 On embedded PowerPC systems, put global and static items less than or
23439 equal to @var{num} bytes into the small data or BSS sections instead of
23440 the normal data or BSS section.  By default, @var{num} is 8.  The
23441 @option{-G @var{num}} switch is also passed to the linker.
23442 All modules should be compiled with the same @option{-G @var{num}} value.
23444 @item -mregnames
23445 @itemx -mno-regnames
23446 @opindex mregnames
23447 @opindex mno-regnames
23448 On System V.4 and embedded PowerPC systems do (do not) emit register
23449 names in the assembly language output using symbolic forms.
23451 @item -mlongcall
23452 @itemx -mno-longcall
23453 @opindex mlongcall
23454 @opindex mno-longcall
23455 By default assume that all calls are far away so that a longer and more
23456 expensive calling sequence is required.  This is required for calls
23457 farther than 32 megabytes (33,554,432 bytes) from the current location.
23458 A short call is generated if the compiler knows
23459 the call cannot be that far away.  This setting can be overridden by
23460 the @code{shortcall} function attribute, or by @code{#pragma
23461 longcall(0)}.
23463 Some linkers are capable of detecting out-of-range calls and generating
23464 glue code on the fly.  On these systems, long calls are unnecessary and
23465 generate slower code.  As of this writing, the AIX linker can do this,
23466 as can the GNU linker for PowerPC/64.  It is planned to add this feature
23467 to the GNU linker for 32-bit PowerPC systems as well.
23469 In the future, GCC may ignore all longcall specifications
23470 when the linker is known to generate glue.
23472 @item -mtls-markers
23473 @itemx -mno-tls-markers
23474 @opindex mtls-markers
23475 @opindex mno-tls-markers
23476 Mark (do not mark) calls to @code{__tls_get_addr} with a relocation
23477 specifying the function argument.  The relocation allows the linker to
23478 reliably associate function call with argument setup instructions for
23479 TLS optimization, which in turn allows GCC to better schedule the
23480 sequence.
23482 @item -mrecip
23483 @itemx -mno-recip
23484 @opindex mrecip
23485 This option enables use of the reciprocal estimate and
23486 reciprocal square root estimate instructions with additional
23487 Newton-Raphson steps to increase precision instead of doing a divide or
23488 square root and divide for floating-point arguments.  You should use
23489 the @option{-ffast-math} option when using @option{-mrecip} (or at
23490 least @option{-funsafe-math-optimizations},
23491 @option{-ffinite-math-only}, @option{-freciprocal-math} and
23492 @option{-fno-trapping-math}).  Note that while the throughput of the
23493 sequence is generally higher than the throughput of the non-reciprocal
23494 instruction, the precision of the sequence can be decreased by up to 2
23495 ulp (i.e.@: the inverse of 1.0 equals 0.99999994) for reciprocal square
23496 roots.
23498 @item -mrecip=@var{opt}
23499 @opindex mrecip=opt
23500 This option controls which reciprocal estimate instructions
23501 may be used.  @var{opt} is a comma-separated list of options, which may
23502 be preceded by a @code{!} to invert the option:
23504 @table @samp
23506 @item all
23507 Enable all estimate instructions.
23509 @item default
23510 Enable the default instructions, equivalent to @option{-mrecip}.
23512 @item none
23513 Disable all estimate instructions, equivalent to @option{-mno-recip}.
23515 @item div
23516 Enable the reciprocal approximation instructions for both
23517 single and double precision.
23519 @item divf
23520 Enable the single-precision reciprocal approximation instructions.
23522 @item divd
23523 Enable the double-precision reciprocal approximation instructions.
23525 @item rsqrt
23526 Enable the reciprocal square root approximation instructions for both
23527 single and double precision.
23529 @item rsqrtf
23530 Enable the single-precision reciprocal square root approximation instructions.
23532 @item rsqrtd
23533 Enable the double-precision reciprocal square root approximation instructions.
23535 @end table
23537 So, for example, @option{-mrecip=all,!rsqrtd} enables
23538 all of the reciprocal estimate instructions, except for the
23539 @code{FRSQRTE}, @code{XSRSQRTEDP}, and @code{XVRSQRTEDP} instructions
23540 which handle the double-precision reciprocal square root calculations.
23542 @item -mrecip-precision
23543 @itemx -mno-recip-precision
23544 @opindex mrecip-precision
23545 Assume (do not assume) that the reciprocal estimate instructions
23546 provide higher-precision estimates than is mandated by the PowerPC
23547 ABI.  Selecting @option{-mcpu=power6}, @option{-mcpu=power7} or
23548 @option{-mcpu=power8} automatically selects @option{-mrecip-precision}.
23549 The double-precision square root estimate instructions are not generated by
23550 default on low-precision machines, since they do not provide an
23551 estimate that converges after three steps.
23553 @item -mpointers-to-nested-functions
23554 @itemx -mno-pointers-to-nested-functions
23555 @opindex mpointers-to-nested-functions
23556 Generate (do not generate) code to load up the static chain register
23557 (@code{r11}) when calling through a pointer on AIX and 64-bit Linux
23558 systems where a function pointer points to a 3-word descriptor giving
23559 the function address, TOC value to be loaded in register @code{r2}, and
23560 static chain value to be loaded in register @code{r11}.  The
23561 @option{-mpointers-to-nested-functions} is on by default.  You cannot
23562 call through pointers to nested functions or pointers
23563 to functions compiled in other languages that use the static chain if
23564 you use @option{-mno-pointers-to-nested-functions}.
23566 @item -msave-toc-indirect
23567 @itemx -mno-save-toc-indirect
23568 @opindex msave-toc-indirect
23569 Generate (do not generate) code to save the TOC value in the reserved
23570 stack location in the function prologue if the function calls through
23571 a pointer on AIX and 64-bit Linux systems.  If the TOC value is not
23572 saved in the prologue, it is saved just before the call through the
23573 pointer.  The @option{-mno-save-toc-indirect} option is the default.
23575 @item -mcompat-align-parm
23576 @itemx -mno-compat-align-parm
23577 @opindex mcompat-align-parm
23578 Generate (do not generate) code to pass structure parameters with a
23579 maximum alignment of 64 bits, for compatibility with older versions
23580 of GCC.
23582 Older versions of GCC (prior to 4.9.0) incorrectly did not align a
23583 structure parameter on a 128-bit boundary when that structure contained
23584 a member requiring 128-bit alignment.  This is corrected in more
23585 recent versions of GCC.  This option may be used to generate code
23586 that is compatible with functions compiled with older versions of
23587 GCC.
23589 The @option{-mno-compat-align-parm} option is the default.
23591 @item -mstack-protector-guard=@var{guard}
23592 @itemx -mstack-protector-guard-reg=@var{reg}
23593 @itemx -mstack-protector-guard-offset=@var{offset}
23594 @itemx -mstack-protector-guard-symbol=@var{symbol}
23595 @opindex mstack-protector-guard
23596 @opindex mstack-protector-guard-reg
23597 @opindex mstack-protector-guard-offset
23598 @opindex mstack-protector-guard-symbol
23599 Generate stack protection code using canary at @var{guard}.  Supported
23600 locations are @samp{global} for global canary or @samp{tls} for per-thread
23601 canary in the TLS block (the default with GNU libc version 2.4 or later).
23603 With the latter choice the options
23604 @option{-mstack-protector-guard-reg=@var{reg}} and
23605 @option{-mstack-protector-guard-offset=@var{offset}} furthermore specify
23606 which register to use as base register for reading the canary, and from what
23607 offset from that base register. The default for those is as specified in the
23608 relevant ABI.  @option{-mstack-protector-guard-symbol=@var{symbol}} overrides
23609 the offset with a symbol reference to a canary in the TLS block.
23610 @end table
23613 @node RISC-V Options
23614 @subsection RISC-V Options
23615 @cindex RISC-V Options
23617 These command-line options are defined for RISC-V targets:
23619 @table @gcctabopt
23620 @item -mbranch-cost=@var{n}
23621 @opindex mbranch-cost
23622 Set the cost of branches to roughly @var{n} instructions.
23624 @item -mplt
23625 @itemx -mno-plt
23626 @opindex plt
23627 When generating PIC code, do or don't allow the use of PLTs. Ignored for
23628 non-PIC.  The default is @option{-mplt}.
23630 @item -mabi=@var{ABI-string}
23631 @opindex mabi
23632 Specify integer and floating-point calling convention.  @var{ABI-string}
23633 contains two parts: the size of integer types and the registers used for
23634 floating-point types.  For example @samp{-march=rv64ifd -mabi=lp64d} means that
23635 @samp{long} and pointers are 64-bit (implicitly defining @samp{int} to be
23636 32-bit), and that floating-point values up to 64 bits wide are passed in F
23637 registers.  Contrast this with @samp{-march=rv64ifd -mabi=lp64f}, which still
23638 allows the compiler to generate code that uses the F and D extensions but only
23639 allows floating-point values up to 32 bits long to be passed in registers; or
23640 @samp{-march=rv64ifd -mabi=lp64}, in which no floating-point arguments will be
23641 passed in registers.
23643 The default for this argument is system dependent, users who want a specific
23644 calling convention should specify one explicitly.  The valid calling
23645 conventions are: @samp{ilp32}, @samp{ilp32f}, @samp{ilp32d}, @samp{lp64},
23646 @samp{lp64f}, and @samp{lp64d}.  Some calling conventions are impossible to
23647 implement on some ISAs: for example, @samp{-march=rv32if -mabi=ilp32d} is
23648 invalid because the ABI requires 64-bit values be passed in F registers, but F
23649 registers are only 32 bits wide.  There is also the @samp{ilp32e} ABI that can
23650 only be used with the @samp{rv32e} architecture.  This ABI is not well
23651 specified at present, and is subject to change.
23653 @item -mfdiv
23654 @itemx -mno-fdiv
23655 @opindex mfdiv
23656 Do or don't use hardware floating-point divide and square root instructions.
23657 This requires the F or D extensions for floating-point registers.  The default
23658 is to use them if the specified architecture has these instructions.
23660 @item -mdiv
23661 @itemx -mno-div
23662 @opindex mdiv
23663 Do or don't use hardware instructions for integer division.  This requires the
23664 M extension.  The default is to use them if the specified architecture has
23665 these instructions.
23667 @item -march=@var{ISA-string}
23668 @opindex march
23669 Generate code for given RISC-V ISA (e.g.@ @samp{rv64im}).  ISA strings must be
23670 lower-case.  Examples include @samp{rv64i}, @samp{rv32g}, @samp{rv32e}, and
23671 @samp{rv32imaf}.
23673 @item -mtune=@var{processor-string}
23674 @opindex mtune
23675 Optimize the output for the given processor, specified by microarchitecture
23676 name.
23678 @item -mpreferred-stack-boundary=@var{num}
23679 @opindex mpreferred-stack-boundary
23680 Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
23681 byte boundary.  If @option{-mpreferred-stack-boundary} is not specified,
23682 the default is 4 (16 bytes or 128-bits).
23684 @strong{Warning:} If you use this switch, then you must build all modules with
23685 the same value, including any libraries.  This includes the system libraries
23686 and startup modules.
23688 @item -msmall-data-limit=@var{n}
23689 @opindex msmall-data-limit
23690 Put global and static data smaller than @var{n} bytes into a special section
23691 (on some targets).
23693 @item -msave-restore
23694 @itemx -mno-save-restore
23695 @opindex msave-restore
23696 Do or don't use smaller but slower prologue and epilogue code that uses
23697 library function calls.  The default is to use fast inline prologues and
23698 epilogues.
23700 @item -mstrict-align
23701 @itemx -mno-strict-align
23702 @opindex mstrict-align
23703 Do not or do generate unaligned memory accesses.  The default is set depending
23704 on whether the processor we are optimizing for supports fast unaligned access
23705 or not.
23707 @item -mcmodel=medlow
23708 @opindex mcmodel=medlow
23709 Generate code for the medium-low code model. The program and its statically
23710 defined symbols must lie within a single 2 GiB address range and must lie
23711 between absolute addresses @minus{}2 GiB and +2 GiB. Programs can be
23712 statically or dynamically linked. This is the default code model.
23714 @item -mcmodel=medany
23715 @opindex mcmodel=medany
23716 Generate code for the medium-any code model. The program and its statically
23717 defined symbols must be within any single 2 GiB address range. Programs can be
23718 statically or dynamically linked.
23720 @item -mexplicit-relocs
23721 @itemx -mno-exlicit-relocs
23722 Use or do not use assembler relocation operators when dealing with symbolic
23723 addresses.  The alternative is to use assembler macros instead, which may
23724 limit optimization.
23726 @item -mrelax
23727 @itemx -mno-relax
23728 Take advantage of linker relaxations to reduce the number of instructions
23729 required to materialize symbol addresses. The default is to take advantage of
23730 linker relaxations.
23732 @end table
23734 @node RL78 Options
23735 @subsection RL78 Options
23736 @cindex RL78 Options
23738 @table @gcctabopt
23740 @item -msim
23741 @opindex msim
23742 Links in additional target libraries to support operation within a
23743 simulator.
23745 @item -mmul=none
23746 @itemx -mmul=g10
23747 @itemx -mmul=g13
23748 @itemx -mmul=g14
23749 @itemx -mmul=rl78
23750 @opindex mmul
23751 Specifies the type of hardware multiplication and division support to
23752 be used.  The simplest is @code{none}, which uses software for both
23753 multiplication and division.  This is the default.  The @code{g13}
23754 value is for the hardware multiply/divide peripheral found on the
23755 RL78/G13 (S2 core) targets.  The @code{g14} value selects the use of
23756 the multiplication and division instructions supported by the RL78/G14
23757 (S3 core) parts.  The value @code{rl78} is an alias for @code{g14} and
23758 the value @code{mg10} is an alias for @code{none}.
23760 In addition a C preprocessor macro is defined, based upon the setting
23761 of this option.  Possible values are: @code{__RL78_MUL_NONE__},
23762 @code{__RL78_MUL_G13__} or @code{__RL78_MUL_G14__}.
23764 @item -mcpu=g10
23765 @itemx -mcpu=g13
23766 @itemx -mcpu=g14
23767 @itemx -mcpu=rl78
23768 @opindex mcpu
23769 Specifies the RL78 core to target.  The default is the G14 core, also
23770 known as an S3 core or just RL78.  The G13 or S2 core does not have
23771 multiply or divide instructions, instead it uses a hardware peripheral
23772 for these operations.  The G10 or S1 core does not have register
23773 banks, so it uses a different calling convention.
23775 If this option is set it also selects the type of hardware multiply
23776 support to use, unless this is overridden by an explicit
23777 @option{-mmul=none} option on the command line.  Thus specifying
23778 @option{-mcpu=g13} enables the use of the G13 hardware multiply
23779 peripheral and specifying @option{-mcpu=g10} disables the use of
23780 hardware multiplications altogether.
23782 Note, although the RL78/G14 core is the default target, specifying
23783 @option{-mcpu=g14} or @option{-mcpu=rl78} on the command line does
23784 change the behavior of the toolchain since it also enables G14
23785 hardware multiply support.  If these options are not specified on the
23786 command line then software multiplication routines will be used even
23787 though the code targets the RL78 core.  This is for backwards
23788 compatibility with older toolchains which did not have hardware
23789 multiply and divide support.
23791 In addition a C preprocessor macro is defined, based upon the setting
23792 of this option.  Possible values are: @code{__RL78_G10__},
23793 @code{__RL78_G13__} or @code{__RL78_G14__}.
23795 @item -mg10
23796 @itemx -mg13
23797 @itemx -mg14
23798 @itemx -mrl78
23799 @opindex mg10
23800 @opindex mg13
23801 @opindex mg14
23802 @opindex mrl78
23803 These are aliases for the corresponding @option{-mcpu=} option.  They
23804 are provided for backwards compatibility.
23806 @item -mallregs
23807 @opindex mallregs
23808 Allow the compiler to use all of the available registers.  By default
23809 registers @code{r24..r31} are reserved for use in interrupt handlers.
23810 With this option enabled these registers can be used in ordinary
23811 functions as well.
23813 @item -m64bit-doubles
23814 @itemx -m32bit-doubles
23815 @opindex m64bit-doubles
23816 @opindex m32bit-doubles
23817 Make the @code{double} data type be 64 bits (@option{-m64bit-doubles})
23818 or 32 bits (@option{-m32bit-doubles}) in size.  The default is
23819 @option{-m32bit-doubles}.
23821 @item -msave-mduc-in-interrupts
23822 @itemx -mno-save-mduc-in-interrupts
23823 @opindex msave-mduc-in-interrupts
23824 @opindex mno-save-mduc-in-interrupts
23825 Specifies that interrupt handler functions should preserve the
23826 MDUC registers.  This is only necessary if normal code might use
23827 the MDUC registers, for example because it performs multiplication
23828 and division operations.  The default is to ignore the MDUC registers
23829 as this makes the interrupt handlers faster.  The target option -mg13
23830 needs to be passed for this to work as this feature is only available
23831 on the G13 target (S2 core).  The MDUC registers will only be saved
23832 if the interrupt handler performs a multiplication or division
23833 operation or it calls another function.
23835 @end table
23837 @node RS/6000 and PowerPC Options
23838 @subsection IBM RS/6000 and PowerPC Options
23839 @cindex RS/6000 and PowerPC Options
23840 @cindex IBM RS/6000 and PowerPC Options
23842 These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
23843 @table @gcctabopt
23844 @item -mpowerpc-gpopt
23845 @itemx -mno-powerpc-gpopt
23846 @itemx -mpowerpc-gfxopt
23847 @itemx -mno-powerpc-gfxopt
23848 @need 800
23849 @itemx -mpowerpc64
23850 @itemx -mno-powerpc64
23851 @itemx -mmfcrf
23852 @itemx -mno-mfcrf
23853 @itemx -mpopcntb
23854 @itemx -mno-popcntb
23855 @itemx -mpopcntd
23856 @itemx -mno-popcntd
23857 @itemx -mfprnd
23858 @itemx -mno-fprnd
23859 @need 800
23860 @itemx -mcmpb
23861 @itemx -mno-cmpb
23862 @itemx -mmfpgpr
23863 @itemx -mno-mfpgpr
23864 @itemx -mhard-dfp
23865 @itemx -mno-hard-dfp
23866 @opindex mpowerpc-gpopt
23867 @opindex mno-powerpc-gpopt
23868 @opindex mpowerpc-gfxopt
23869 @opindex mno-powerpc-gfxopt
23870 @opindex mpowerpc64
23871 @opindex mno-powerpc64
23872 @opindex mmfcrf
23873 @opindex mno-mfcrf
23874 @opindex mpopcntb
23875 @opindex mno-popcntb
23876 @opindex mpopcntd
23877 @opindex mno-popcntd
23878 @opindex mfprnd
23879 @opindex mno-fprnd
23880 @opindex mcmpb
23881 @opindex mno-cmpb
23882 @opindex mmfpgpr
23883 @opindex mno-mfpgpr
23884 @opindex mhard-dfp
23885 @opindex mno-hard-dfp
23886 You use these options to specify which instructions are available on the
23887 processor you are using.  The default value of these options is
23888 determined when configuring GCC@.  Specifying the
23889 @option{-mcpu=@var{cpu_type}} overrides the specification of these
23890 options.  We recommend you use the @option{-mcpu=@var{cpu_type}} option
23891 rather than the options listed above.
23893 Specifying @option{-mpowerpc-gpopt} allows
23894 GCC to use the optional PowerPC architecture instructions in the
23895 General Purpose group, including floating-point square root.  Specifying
23896 @option{-mpowerpc-gfxopt} allows GCC to
23897 use the optional PowerPC architecture instructions in the Graphics
23898 group, including floating-point select.
23900 The @option{-mmfcrf} option allows GCC to generate the move from
23901 condition register field instruction implemented on the POWER4
23902 processor and other processors that support the PowerPC V2.01
23903 architecture.
23904 The @option{-mpopcntb} option allows GCC to generate the popcount and
23905 double-precision FP reciprocal estimate instruction implemented on the
23906 POWER5 processor and other processors that support the PowerPC V2.02
23907 architecture.
23908 The @option{-mpopcntd} option allows GCC to generate the popcount
23909 instruction implemented on the POWER7 processor and other processors
23910 that support the PowerPC V2.06 architecture.
23911 The @option{-mfprnd} option allows GCC to generate the FP round to
23912 integer instructions implemented on the POWER5+ processor and other
23913 processors that support the PowerPC V2.03 architecture.
23914 The @option{-mcmpb} option allows GCC to generate the compare bytes
23915 instruction implemented on the POWER6 processor and other processors
23916 that support the PowerPC V2.05 architecture.
23917 The @option{-mmfpgpr} option allows GCC to generate the FP move to/from
23918 general-purpose register instructions implemented on the POWER6X
23919 processor and other processors that support the extended PowerPC V2.05
23920 architecture.
23921 The @option{-mhard-dfp} option allows GCC to generate the decimal
23922 floating-point instructions implemented on some POWER processors.
23924 The @option{-mpowerpc64} option allows GCC to generate the additional
23925 64-bit instructions that are found in the full PowerPC64 architecture
23926 and to treat GPRs as 64-bit, doubleword quantities.  GCC defaults to
23927 @option{-mno-powerpc64}.
23929 @item -mcpu=@var{cpu_type}
23930 @opindex mcpu
23931 Set architecture type, register usage, and
23932 instruction scheduling parameters for machine type @var{cpu_type}.
23933 Supported values for @var{cpu_type} are @samp{401}, @samp{403},
23934 @samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{464}, @samp{464fp},
23935 @samp{476}, @samp{476fp}, @samp{505}, @samp{601}, @samp{602}, @samp{603},
23936 @samp{603e}, @samp{604}, @samp{604e}, @samp{620}, @samp{630}, @samp{740},
23937 @samp{7400}, @samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
23938 @samp{860}, @samp{970}, @samp{8540}, @samp{a2}, @samp{e300c2},
23939 @samp{e300c3}, @samp{e500mc}, @samp{e500mc64}, @samp{e5500},
23940 @samp{e6500}, @samp{ec603e}, @samp{G3}, @samp{G4}, @samp{G5},
23941 @samp{titan}, @samp{power3}, @samp{power4}, @samp{power5}, @samp{power5+},
23942 @samp{power6}, @samp{power6x}, @samp{power7}, @samp{power8},
23943 @samp{power9}, @samp{powerpc}, @samp{powerpc64}, @samp{powerpc64le},
23944 @samp{rs64}, and @samp{native}.
23946 @option{-mcpu=powerpc}, @option{-mcpu=powerpc64}, and
23947 @option{-mcpu=powerpc64le} specify pure 32-bit PowerPC (either
23948 endian), 64-bit big endian PowerPC and 64-bit little endian PowerPC
23949 architecture machine types, with an appropriate, generic processor
23950 model assumed for scheduling purposes.
23952 Specifying @samp{native} as cpu type detects and selects the
23953 architecture option that corresponds to the host processor of the
23954 system performing the compilation.
23955 @option{-mcpu=native} has no effect if GCC does not recognize the
23956 processor.
23958 The other options specify a specific processor.  Code generated under
23959 those options runs best on that processor, and may not run at all on
23960 others.
23962 The @option{-mcpu} options automatically enable or disable the
23963 following options:
23965 @gccoptlist{-maltivec  -mfprnd  -mhard-float  -mmfcrf  -mmultiple @gol
23966 -mpopcntb -mpopcntd  -mpowerpc64 @gol
23967 -mpowerpc-gpopt  -mpowerpc-gfxopt @gol
23968 -mmulhw  -mdlmzb  -mmfpgpr -mvsx @gol
23969 -mcrypto -mhtm -mpower8-fusion -mpower8-vector @gol
23970 -mquad-memory -mquad-memory-atomic -mfloat128 -mfloat128-hardware}
23972 The particular options set for any particular CPU varies between
23973 compiler versions, depending on what setting seems to produce optimal
23974 code for that CPU; it doesn't necessarily reflect the actual hardware's
23975 capabilities.  If you wish to set an individual option to a particular
23976 value, you may specify it after the @option{-mcpu} option, like
23977 @option{-mcpu=970 -mno-altivec}.
23979 On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
23980 not enabled or disabled by the @option{-mcpu} option at present because
23981 AIX does not have full support for these options.  You may still
23982 enable or disable them individually if you're sure it'll work in your
23983 environment.
23985 @item -mtune=@var{cpu_type}
23986 @opindex mtune
23987 Set the instruction scheduling parameters for machine type
23988 @var{cpu_type}, but do not set the architecture type or register usage,
23989 as @option{-mcpu=@var{cpu_type}} does.  The same
23990 values for @var{cpu_type} are used for @option{-mtune} as for
23991 @option{-mcpu}.  If both are specified, the code generated uses the
23992 architecture and registers set by @option{-mcpu}, but the
23993 scheduling parameters set by @option{-mtune}.
23995 @item -mcmodel=small
23996 @opindex mcmodel=small
23997 Generate PowerPC64 code for the small model: The TOC is limited to
23998 64k.
24000 @item -mcmodel=medium
24001 @opindex mcmodel=medium
24002 Generate PowerPC64 code for the medium model: The TOC and other static
24003 data may be up to a total of 4G in size.  This is the default for 64-bit
24004 Linux.
24006 @item -mcmodel=large
24007 @opindex mcmodel=large
24008 Generate PowerPC64 code for the large model: The TOC may be up to 4G
24009 in size.  Other data and code is only limited by the 64-bit address
24010 space.
24012 @item -maltivec
24013 @itemx -mno-altivec
24014 @opindex maltivec
24015 @opindex mno-altivec
24016 Generate code that uses (does not use) AltiVec instructions, and also
24017 enable the use of built-in functions that allow more direct access to
24018 the AltiVec instruction set.  You may also need to set
24019 @option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
24020 enhancements.
24022 When @option{-maltivec} is used, rather than @option{-maltivec=le} or
24023 @option{-maltivec=be}, the element order for AltiVec intrinsics such
24024 as @code{vec_splat}, @code{vec_extract}, and @code{vec_insert} 
24025 match array element order corresponding to the endianness of the
24026 target.  That is, element zero identifies the leftmost element in a
24027 vector register when targeting a big-endian platform, and identifies
24028 the rightmost element in a vector register when targeting a
24029 little-endian platform.
24031 @item -maltivec=be
24032 @opindex maltivec=be
24033 Generate AltiVec instructions using big-endian element order,
24034 regardless of whether the target is big- or little-endian.  This is
24035 the default when targeting a big-endian platform.  Using this option
24036 is currently deprecated.  Support for this feature will be removed in
24037 GCC 9.
24039 The element order is used to interpret element numbers in AltiVec
24040 intrinsics such as @code{vec_splat}, @code{vec_extract}, and
24041 @code{vec_insert}.  By default, these match array element order
24042 corresponding to the endianness for the target.
24044 @item -maltivec=le
24045 @opindex maltivec=le
24046 Generate AltiVec instructions using little-endian element order,
24047 regardless of whether the target is big- or little-endian.  This is
24048 the default when targeting a little-endian platform.  This option is
24049 currently ignored when targeting a big-endian platform.
24051 The element order is used to interpret element numbers in AltiVec
24052 intrinsics such as @code{vec_splat}, @code{vec_extract}, and
24053 @code{vec_insert}.  By default, these match array element order
24054 corresponding to the endianness for the target.
24056 @item -mvrsave
24057 @itemx -mno-vrsave
24058 @opindex mvrsave
24059 @opindex mno-vrsave
24060 Generate VRSAVE instructions when generating AltiVec code.
24062 @item -msecure-plt
24063 @opindex msecure-plt
24064 Generate code that allows @command{ld} and @command{ld.so}
24065 to build executables and shared
24066 libraries with non-executable @code{.plt} and @code{.got} sections.
24067 This is a PowerPC
24068 32-bit SYSV ABI option.
24070 @item -mbss-plt
24071 @opindex mbss-plt
24072 Generate code that uses a BSS @code{.plt} section that @command{ld.so}
24073 fills in, and
24074 requires @code{.plt} and @code{.got}
24075 sections that are both writable and executable.
24076 This is a PowerPC 32-bit SYSV ABI option.
24078 @item -misel
24079 @itemx -mno-isel
24080 @opindex misel
24081 @opindex mno-isel
24082 This switch enables or disables the generation of ISEL instructions.
24084 @item -mvsx
24085 @itemx -mno-vsx
24086 @opindex mvsx
24087 @opindex mno-vsx
24088 Generate code that uses (does not use) vector/scalar (VSX)
24089 instructions, and also enable the use of built-in functions that allow
24090 more direct access to the VSX instruction set.
24092 @item -mcrypto
24093 @itemx -mno-crypto
24094 @opindex mcrypto
24095 @opindex mno-crypto
24096 Enable the use (disable) of the built-in functions that allow direct
24097 access to the cryptographic instructions that were added in version
24098 2.07 of the PowerPC ISA.
24100 @item -mhtm
24101 @itemx -mno-htm
24102 @opindex mhtm
24103 @opindex mno-htm
24104 Enable (disable) the use of the built-in functions that allow direct
24105 access to the Hardware Transactional Memory (HTM) instructions that
24106 were added in version 2.07 of the PowerPC ISA.
24108 @item -mpower8-fusion
24109 @itemx -mno-power8-fusion
24110 @opindex mpower8-fusion
24111 @opindex mno-power8-fusion
24112 Generate code that keeps (does not keeps) some integer operations
24113 adjacent so that the instructions can be fused together on power8 and
24114 later processors.
24116 @item -mpower8-vector
24117 @itemx -mno-power8-vector
24118 @opindex mpower8-vector
24119 @opindex mno-power8-vector
24120 Generate code that uses (does not use) the vector and scalar
24121 instructions that were added in version 2.07 of the PowerPC ISA.  Also
24122 enable the use of built-in functions that allow more direct access to
24123 the vector instructions.
24125 @item -mquad-memory
24126 @itemx -mno-quad-memory
24127 @opindex mquad-memory
24128 @opindex mno-quad-memory
24129 Generate code that uses (does not use) the non-atomic quad word memory
24130 instructions.  The @option{-mquad-memory} option requires use of
24131 64-bit mode.
24133 @item -mquad-memory-atomic
24134 @itemx -mno-quad-memory-atomic
24135 @opindex mquad-memory-atomic
24136 @opindex mno-quad-memory-atomic
24137 Generate code that uses (does not use) the atomic quad word memory
24138 instructions.  The @option{-mquad-memory-atomic} option requires use of
24139 64-bit mode.
24141 @item -mfloat128
24142 @itemx -mno-float128
24143 @opindex mfloat128
24144 @opindex mno-float128
24145 Enable/disable the @var{__float128} keyword for IEEE 128-bit floating point
24146 and use either software emulation for IEEE 128-bit floating point or
24147 hardware instructions.
24149 The VSX instruction set (@option{-mvsx}, @option{-mcpu=power7},
24150 @option{-mcpu=power8}), or @option{-mcpu=power9} must be enabled to
24151 use the IEEE 128-bit floating point support.  The IEEE 128-bit
24152 floating point support only works on PowerPC Linux systems.
24154 The default for @option{-mfloat128} is enabled on PowerPC Linux
24155 systems using the VSX instruction set, and disabled on other systems.
24157 If you use the ISA 3.0 instruction set (@option{-mpower9-vector} or
24158 @option{-mcpu=power9}) on a 64-bit system, the IEEE 128-bit floating
24159 point support will also enable the generation of ISA 3.0 IEEE 128-bit
24160 floating point instructions.  Otherwise, if you do not specify to
24161 generate ISA 3.0 instructions or you are targeting a 32-bit big endian
24162 system, IEEE 128-bit floating point will be done with software
24163 emulation.
24165 @item -mfloat128-hardware
24166 @itemx -mno-float128-hardware
24167 @opindex mfloat128-hardware
24168 @opindex mno-float128-hardware
24169 Enable/disable using ISA 3.0 hardware instructions to support the
24170 @var{__float128} data type.
24172 The default for @option{-mfloat128-hardware} is enabled on PowerPC
24173 Linux systems using the ISA 3.0 instruction set, and disabled on other
24174 systems.
24176 @item -m32
24177 @itemx -m64
24178 @opindex m32
24179 @opindex m64
24180 Generate code for 32-bit or 64-bit environments of Darwin and SVR4
24181 targets (including GNU/Linux).  The 32-bit environment sets int, long
24182 and pointer to 32 bits and generates code that runs on any PowerPC
24183 variant.  The 64-bit environment sets int to 32 bits and long and
24184 pointer to 64 bits, and generates code for PowerPC64, as for
24185 @option{-mpowerpc64}.
24187 @item -mfull-toc
24188 @itemx -mno-fp-in-toc
24189 @itemx -mno-sum-in-toc
24190 @itemx -mminimal-toc
24191 @opindex mfull-toc
24192 @opindex mno-fp-in-toc
24193 @opindex mno-sum-in-toc
24194 @opindex mminimal-toc
24195 Modify generation of the TOC (Table Of Contents), which is created for
24196 every executable file.  The @option{-mfull-toc} option is selected by
24197 default.  In that case, GCC allocates at least one TOC entry for
24198 each unique non-automatic variable reference in your program.  GCC
24199 also places floating-point constants in the TOC@.  However, only
24200 16,384 entries are available in the TOC@.
24202 If you receive a linker error message that saying you have overflowed
24203 the available TOC space, you can reduce the amount of TOC space used
24204 with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
24205 @option{-mno-fp-in-toc} prevents GCC from putting floating-point
24206 constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
24207 generate code to calculate the sum of an address and a constant at
24208 run time instead of putting that sum into the TOC@.  You may specify one
24209 or both of these options.  Each causes GCC to produce very slightly
24210 slower and larger code at the expense of conserving TOC space.
24212 If you still run out of space in the TOC even when you specify both of
24213 these options, specify @option{-mminimal-toc} instead.  This option causes
24214 GCC to make only one TOC entry for every file.  When you specify this
24215 option, GCC produces code that is slower and larger but which
24216 uses extremely little TOC space.  You may wish to use this option
24217 only on files that contain less frequently-executed code.
24219 @item -maix64
24220 @itemx -maix32
24221 @opindex maix64
24222 @opindex maix32
24223 Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
24224 @code{long} type, and the infrastructure needed to support them.
24225 Specifying @option{-maix64} implies @option{-mpowerpc64},
24226 while @option{-maix32} disables the 64-bit ABI and
24227 implies @option{-mno-powerpc64}.  GCC defaults to @option{-maix32}.
24229 @item -mxl-compat
24230 @itemx -mno-xl-compat
24231 @opindex mxl-compat
24232 @opindex mno-xl-compat
24233 Produce code that conforms more closely to IBM XL compiler semantics
24234 when using AIX-compatible ABI@.  Pass floating-point arguments to
24235 prototyped functions beyond the register save area (RSA) on the stack
24236 in addition to argument FPRs.  Do not assume that most significant
24237 double in 128-bit long double value is properly rounded when comparing
24238 values and converting to double.  Use XL symbol names for long double
24239 support routines.
24241 The AIX calling convention was extended but not initially documented to
24242 handle an obscure K&R C case of calling a function that takes the
24243 address of its arguments with fewer arguments than declared.  IBM XL
24244 compilers access floating-point arguments that do not fit in the
24245 RSA from the stack when a subroutine is compiled without
24246 optimization.  Because always storing floating-point arguments on the
24247 stack is inefficient and rarely needed, this option is not enabled by
24248 default and only is necessary when calling subroutines compiled by IBM
24249 XL compilers without optimization.
24251 @item -mpe
24252 @opindex mpe
24253 Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@.  Link an
24254 application written to use message passing with special startup code to
24255 enable the application to run.  The system must have PE installed in the
24256 standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
24257 must be overridden with the @option{-specs=} option to specify the
24258 appropriate directory location.  The Parallel Environment does not
24259 support threads, so the @option{-mpe} option and the @option{-pthread}
24260 option are incompatible.
24262 @item -malign-natural
24263 @itemx -malign-power
24264 @opindex malign-natural
24265 @opindex malign-power
24266 On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
24267 @option{-malign-natural} overrides the ABI-defined alignment of larger
24268 types, such as floating-point doubles, on their natural size-based boundary.
24269 The option @option{-malign-power} instructs GCC to follow the ABI-specified
24270 alignment rules.  GCC defaults to the standard alignment defined in the ABI@.
24272 On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
24273 is not supported.
24275 @item -msoft-float
24276 @itemx -mhard-float
24277 @opindex msoft-float
24278 @opindex mhard-float
24279 Generate code that does not use (uses) the floating-point register set.
24280 Software floating-point emulation is provided if you use the
24281 @option{-msoft-float} option, and pass the option to GCC when linking.
24283 @item -mmultiple
24284 @itemx -mno-multiple
24285 @opindex mmultiple
24286 @opindex mno-multiple
24287 Generate code that uses (does not use) the load multiple word
24288 instructions and the store multiple word instructions.  These
24289 instructions are generated by default on POWER systems, and not
24290 generated on PowerPC systems.  Do not use @option{-mmultiple} on little-endian
24291 PowerPC systems, since those instructions do not work when the
24292 processor is in little-endian mode.  The exceptions are PPC740 and
24293 PPC750 which permit these instructions in little-endian mode.
24295 @item -mupdate
24296 @itemx -mno-update
24297 @opindex mupdate
24298 @opindex mno-update
24299 Generate code that uses (does not use) the load or store instructions
24300 that update the base register to the address of the calculated memory
24301 location.  These instructions are generated by default.  If you use
24302 @option{-mno-update}, there is a small window between the time that the
24303 stack pointer is updated and the address of the previous frame is
24304 stored, which means code that walks the stack frame across interrupts or
24305 signals may get corrupted data.
24307 @item -mavoid-indexed-addresses
24308 @itemx -mno-avoid-indexed-addresses
24309 @opindex mavoid-indexed-addresses
24310 @opindex mno-avoid-indexed-addresses
24311 Generate code that tries to avoid (not avoid) the use of indexed load
24312 or store instructions. These instructions can incur a performance
24313 penalty on Power6 processors in certain situations, such as when
24314 stepping through large arrays that cross a 16M boundary.  This option
24315 is enabled by default when targeting Power6 and disabled otherwise.
24317 @item -mfused-madd
24318 @itemx -mno-fused-madd
24319 @opindex mfused-madd
24320 @opindex mno-fused-madd
24321 Generate code that uses (does not use) the floating-point multiply and
24322 accumulate instructions.  These instructions are generated by default
24323 if hardware floating point is used.  The machine-dependent
24324 @option{-mfused-madd} option is now mapped to the machine-independent
24325 @option{-ffp-contract=fast} option, and @option{-mno-fused-madd} is
24326 mapped to @option{-ffp-contract=off}.
24328 @item -mmulhw
24329 @itemx -mno-mulhw
24330 @opindex mmulhw
24331 @opindex mno-mulhw
24332 Generate code that uses (does not use) the half-word multiply and
24333 multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
24334 These instructions are generated by default when targeting those
24335 processors.
24337 @item -mdlmzb
24338 @itemx -mno-dlmzb
24339 @opindex mdlmzb
24340 @opindex mno-dlmzb
24341 Generate code that uses (does not use) the string-search @samp{dlmzb}
24342 instruction on the IBM 405, 440, 464 and 476 processors.  This instruction is
24343 generated by default when targeting those processors.
24345 @item -mno-bit-align
24346 @itemx -mbit-align
24347 @opindex mno-bit-align
24348 @opindex mbit-align
24349 On System V.4 and embedded PowerPC systems do not (do) force structures
24350 and unions that contain bit-fields to be aligned to the base type of the
24351 bit-field.
24353 For example, by default a structure containing nothing but 8
24354 @code{unsigned} bit-fields of length 1 is aligned to a 4-byte
24355 boundary and has a size of 4 bytes.  By using @option{-mno-bit-align},
24356 the structure is aligned to a 1-byte boundary and is 1 byte in
24357 size.
24359 @item -mno-strict-align
24360 @itemx -mstrict-align
24361 @opindex mno-strict-align
24362 @opindex mstrict-align
24363 On System V.4 and embedded PowerPC systems do not (do) assume that
24364 unaligned memory references are handled by the system.
24366 @item -mrelocatable
24367 @itemx -mno-relocatable
24368 @opindex mrelocatable
24369 @opindex mno-relocatable
24370 Generate code that allows (does not allow) a static executable to be
24371 relocated to a different address at run time.  A simple embedded
24372 PowerPC system loader should relocate the entire contents of
24373 @code{.got2} and 4-byte locations listed in the @code{.fixup} section,
24374 a table of 32-bit addresses generated by this option.  For this to
24375 work, all objects linked together must be compiled with
24376 @option{-mrelocatable} or @option{-mrelocatable-lib}.
24377 @option{-mrelocatable} code aligns the stack to an 8-byte boundary.
24379 @item -mrelocatable-lib
24380 @itemx -mno-relocatable-lib
24381 @opindex mrelocatable-lib
24382 @opindex mno-relocatable-lib
24383 Like @option{-mrelocatable}, @option{-mrelocatable-lib} generates a
24384 @code{.fixup} section to allow static executables to be relocated at
24385 run time, but @option{-mrelocatable-lib} does not use the smaller stack
24386 alignment of @option{-mrelocatable}.  Objects compiled with
24387 @option{-mrelocatable-lib} may be linked with objects compiled with
24388 any combination of the @option{-mrelocatable} options.
24390 @item -mno-toc
24391 @itemx -mtoc
24392 @opindex mno-toc
24393 @opindex mtoc
24394 On System V.4 and embedded PowerPC systems do not (do) assume that
24395 register 2 contains a pointer to a global area pointing to the addresses
24396 used in the program.
24398 @item -mlittle
24399 @itemx -mlittle-endian
24400 @opindex mlittle
24401 @opindex mlittle-endian
24402 On System V.4 and embedded PowerPC systems compile code for the
24403 processor in little-endian mode.  The @option{-mlittle-endian} option is
24404 the same as @option{-mlittle}.
24406 @item -mbig
24407 @itemx -mbig-endian
24408 @opindex mbig
24409 @opindex mbig-endian
24410 On System V.4 and embedded PowerPC systems compile code for the
24411 processor in big-endian mode.  The @option{-mbig-endian} option is
24412 the same as @option{-mbig}.
24414 @item -mdynamic-no-pic
24415 @opindex mdynamic-no-pic
24416 On Darwin and Mac OS X systems, compile code so that it is not
24417 relocatable, but that its external references are relocatable.  The
24418 resulting code is suitable for applications, but not shared
24419 libraries.
24421 @item -msingle-pic-base
24422 @opindex msingle-pic-base
24423 Treat the register used for PIC addressing as read-only, rather than
24424 loading it in the prologue for each function.  The runtime system is
24425 responsible for initializing this register with an appropriate value
24426 before execution begins.
24428 @item -mprioritize-restricted-insns=@var{priority}
24429 @opindex mprioritize-restricted-insns
24430 This option controls the priority that is assigned to
24431 dispatch-slot restricted instructions during the second scheduling
24432 pass.  The argument @var{priority} takes the value @samp{0}, @samp{1},
24433 or @samp{2} to assign no, highest, or second-highest (respectively) 
24434 priority to dispatch-slot restricted
24435 instructions.
24437 @item -msched-costly-dep=@var{dependence_type}
24438 @opindex msched-costly-dep
24439 This option controls which dependences are considered costly
24440 by the target during instruction scheduling.  The argument
24441 @var{dependence_type} takes one of the following values:
24443 @table @asis
24444 @item @samp{no}
24445 No dependence is costly.
24447 @item @samp{all}
24448 All dependences are costly.
24450 @item @samp{true_store_to_load}
24451 A true dependence from store to load is costly.
24453 @item @samp{store_to_load}
24454 Any dependence from store to load is costly.
24456 @item @var{number}
24457 Any dependence for which the latency is greater than or equal to 
24458 @var{number} is costly.
24459 @end table
24461 @item -minsert-sched-nops=@var{scheme}
24462 @opindex minsert-sched-nops
24463 This option controls which NOP insertion scheme is used during
24464 the second scheduling pass.  The argument @var{scheme} takes one of the
24465 following values:
24467 @table @asis
24468 @item @samp{no}
24469 Don't insert NOPs.
24471 @item @samp{pad}
24472 Pad with NOPs any dispatch group that has vacant issue slots,
24473 according to the scheduler's grouping.
24475 @item @samp{regroup_exact}
24476 Insert NOPs to force costly dependent insns into
24477 separate groups.  Insert exactly as many NOPs as needed to force an insn
24478 to a new group, according to the estimated processor grouping.
24480 @item @var{number}
24481 Insert NOPs to force costly dependent insns into
24482 separate groups.  Insert @var{number} NOPs to force an insn to a new group.
24483 @end table
24485 @item -mcall-sysv
24486 @opindex mcall-sysv
24487 On System V.4 and embedded PowerPC systems compile code using calling
24488 conventions that adhere to the March 1995 draft of the System V
24489 Application Binary Interface, PowerPC processor supplement.  This is the
24490 default unless you configured GCC using @samp{powerpc-*-eabiaix}.
24492 @item -mcall-sysv-eabi
24493 @itemx -mcall-eabi
24494 @opindex mcall-sysv-eabi
24495 @opindex mcall-eabi
24496 Specify both @option{-mcall-sysv} and @option{-meabi} options.
24498 @item -mcall-sysv-noeabi
24499 @opindex mcall-sysv-noeabi
24500 Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
24502 @item -mcall-aixdesc
24503 @opindex m
24504 On System V.4 and embedded PowerPC systems compile code for the AIX
24505 operating system.
24507 @item -mcall-linux
24508 @opindex mcall-linux
24509 On System V.4 and embedded PowerPC systems compile code for the
24510 Linux-based GNU system.
24512 @item -mcall-freebsd
24513 @opindex mcall-freebsd
24514 On System V.4 and embedded PowerPC systems compile code for the
24515 FreeBSD operating system.
24517 @item -mcall-netbsd
24518 @opindex mcall-netbsd
24519 On System V.4 and embedded PowerPC systems compile code for the
24520 NetBSD operating system.
24522 @item -mcall-openbsd
24523 @opindex mcall-netbsd
24524 On System V.4 and embedded PowerPC systems compile code for the
24525 OpenBSD operating system.
24527 @item -mtraceback=@var{traceback_type}
24528 @opindex mtraceback
24529 Select the type of traceback table. Valid values for @var{traceback_type}
24530 are @samp{full}, @samp{part}, and @samp{no}.
24532 @item -maix-struct-return
24533 @opindex maix-struct-return
24534 Return all structures in memory (as specified by the AIX ABI)@.
24536 @item -msvr4-struct-return
24537 @opindex msvr4-struct-return
24538 Return structures smaller than 8 bytes in registers (as specified by the
24539 SVR4 ABI)@.
24541 @item -mabi=@var{abi-type}
24542 @opindex mabi
24543 Extend the current ABI with a particular extension, or remove such extension.
24544 Valid values are @samp{altivec}, @samp{no-altivec},
24545 @samp{ibmlongdouble}, @samp{ieeelongdouble},
24546 @samp{elfv1}, @samp{elfv2}@.
24548 @item -mabi=ibmlongdouble
24549 @opindex mabi=ibmlongdouble
24550 Change the current ABI to use IBM extended-precision long double.
24551 This is not likely to work if your system defaults to using IEEE
24552 extended-precision long double.  If you change the long double type
24553 from IEEE extended-precision, the compiler will issue a warning unless
24554 you use the @option{-Wno-psabi} option.
24556 @item -mabi=ieeelongdouble
24557 @opindex mabi=ieeelongdouble
24558 Change the current ABI to use IEEE extended-precision long double.
24559 This is not likely to work if your system defaults to using IBM
24560 extended-precision long double.  If you change the long double type
24561 from IBM extended-precision, the compiler will issue a warning unless
24562 you use the @option{-Wno-psabi} option.
24564 @item -mabi=elfv1
24565 @opindex mabi=elfv1
24566 Change the current ABI to use the ELFv1 ABI.
24567 This is the default ABI for big-endian PowerPC 64-bit Linux.
24568 Overriding the default ABI requires special system support and is
24569 likely to fail in spectacular ways.
24571 @item -mabi=elfv2
24572 @opindex mabi=elfv2
24573 Change the current ABI to use the ELFv2 ABI.
24574 This is the default ABI for little-endian PowerPC 64-bit Linux.
24575 Overriding the default ABI requires special system support and is
24576 likely to fail in spectacular ways.
24578 @item -mgnu-attribute
24579 @itemx -mno-gnu-attribute
24580 @opindex mgnu-attribute
24581 @opindex mno-gnu-attribute
24582 Emit .gnu_attribute assembly directives to set tag/value pairs in a
24583 .gnu.attributes section that specify ABI variations in function
24584 parameters or return values.
24586 @item -mprototype
24587 @itemx -mno-prototype
24588 @opindex mprototype
24589 @opindex mno-prototype
24590 On System V.4 and embedded PowerPC systems assume that all calls to
24591 variable argument functions are properly prototyped.  Otherwise, the
24592 compiler must insert an instruction before every non-prototyped call to
24593 set or clear bit 6 of the condition code register (@code{CR}) to
24594 indicate whether floating-point values are passed in the floating-point
24595 registers in case the function takes variable arguments.  With
24596 @option{-mprototype}, only calls to prototyped variable argument functions
24597 set or clear the bit.
24599 @item -msim
24600 @opindex msim
24601 On embedded PowerPC systems, assume that the startup module is called
24602 @file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
24603 @file{libc.a}.  This is the default for @samp{powerpc-*-eabisim}
24604 configurations.
24606 @item -mmvme
24607 @opindex mmvme
24608 On embedded PowerPC systems, assume that the startup module is called
24609 @file{crt0.o} and the standard C libraries are @file{libmvme.a} and
24610 @file{libc.a}.
24612 @item -mads
24613 @opindex mads
24614 On embedded PowerPC systems, assume that the startup module is called
24615 @file{crt0.o} and the standard C libraries are @file{libads.a} and
24616 @file{libc.a}.
24618 @item -myellowknife
24619 @opindex myellowknife
24620 On embedded PowerPC systems, assume that the startup module is called
24621 @file{crt0.o} and the standard C libraries are @file{libyk.a} and
24622 @file{libc.a}.
24624 @item -mvxworks
24625 @opindex mvxworks
24626 On System V.4 and embedded PowerPC systems, specify that you are
24627 compiling for a VxWorks system.
24629 @item -memb
24630 @opindex memb
24631 On embedded PowerPC systems, set the @code{PPC_EMB} bit in the ELF flags
24632 header to indicate that @samp{eabi} extended relocations are used.
24634 @item -meabi
24635 @itemx -mno-eabi
24636 @opindex meabi
24637 @opindex mno-eabi
24638 On System V.4 and embedded PowerPC systems do (do not) adhere to the
24639 Embedded Applications Binary Interface (EABI), which is a set of
24640 modifications to the System V.4 specifications.  Selecting @option{-meabi}
24641 means that the stack is aligned to an 8-byte boundary, a function
24642 @code{__eabi} is called from @code{main} to set up the EABI
24643 environment, and the @option{-msdata} option can use both @code{r2} and
24644 @code{r13} to point to two separate small data areas.  Selecting
24645 @option{-mno-eabi} means that the stack is aligned to a 16-byte boundary,
24646 no EABI initialization function is called from @code{main}, and the
24647 @option{-msdata} option only uses @code{r13} to point to a single
24648 small data area.  The @option{-meabi} option is on by default if you
24649 configured GCC using one of the @samp{powerpc*-*-eabi*} options.
24651 @item -msdata=eabi
24652 @opindex msdata=eabi
24653 On System V.4 and embedded PowerPC systems, put small initialized
24654 @code{const} global and static data in the @code{.sdata2} section, which
24655 is pointed to by register @code{r2}.  Put small initialized
24656 non-@code{const} global and static data in the @code{.sdata} section,
24657 which is pointed to by register @code{r13}.  Put small uninitialized
24658 global and static data in the @code{.sbss} section, which is adjacent to
24659 the @code{.sdata} section.  The @option{-msdata=eabi} option is
24660 incompatible with the @option{-mrelocatable} option.  The
24661 @option{-msdata=eabi} option also sets the @option{-memb} option.
24663 @item -msdata=sysv
24664 @opindex msdata=sysv
24665 On System V.4 and embedded PowerPC systems, put small global and static
24666 data in the @code{.sdata} section, which is pointed to by register
24667 @code{r13}.  Put small uninitialized global and static data in the
24668 @code{.sbss} section, which is adjacent to the @code{.sdata} section.
24669 The @option{-msdata=sysv} option is incompatible with the
24670 @option{-mrelocatable} option.
24672 @item -msdata=default
24673 @itemx -msdata
24674 @opindex msdata=default
24675 @opindex msdata
24676 On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
24677 compile code the same as @option{-msdata=eabi}, otherwise compile code the
24678 same as @option{-msdata=sysv}.
24680 @item -msdata=data
24681 @opindex msdata=data
24682 On System V.4 and embedded PowerPC systems, put small global
24683 data in the @code{.sdata} section.  Put small uninitialized global
24684 data in the @code{.sbss} section.  Do not use register @code{r13}
24685 to address small data however.  This is the default behavior unless
24686 other @option{-msdata} options are used.
24688 @item -msdata=none
24689 @itemx -mno-sdata
24690 @opindex msdata=none
24691 @opindex mno-sdata
24692 On embedded PowerPC systems, put all initialized global and static data
24693 in the @code{.data} section, and all uninitialized data in the
24694 @code{.bss} section.
24696 @item -mreadonly-in-sdata
24697 @opindex mreadonly-in-sdata
24698 @opindex mno-readonly-in-sdata
24699 Put read-only objects in the @code{.sdata} section as well.  This is the
24700 default.
24702 @item -mblock-move-inline-limit=@var{num}
24703 @opindex mblock-move-inline-limit
24704 Inline all block moves (such as calls to @code{memcpy} or structure
24705 copies) less than or equal to @var{num} bytes.  The minimum value for
24706 @var{num} is 32 bytes on 32-bit targets and 64 bytes on 64-bit
24707 targets.  The default value is target-specific.
24709 @item -mblock-compare-inline-limit=@var{num}
24710 @opindex mblock-compare-inline-limit
24711 Generate non-looping inline code for all block compares (such as calls
24712 to @code{memcmp} or structure compares) less than or equal to @var{num}
24713 bytes. If @var{num} is 0, all inline expansion (non-loop and loop) of
24714 block compare is disabled. The default value is target-specific.
24716 @item -mblock-compare-inline-loop-limit=@var{num}
24717 @opindex mblock-compare-inline-loop-limit
24718 Generate an inline expansion using loop code for all block compares that
24719 are less than or equal to @var{num} bytes, but greater than the limit
24720 for non-loop inline block compare expansion. If the block length is not
24721 constant, at most @var{num} bytes will be compared before @code{memcmp}
24722 is called to compare the remainder of the block. The default value is
24723 target-specific.
24725 @item -mstring-compare-inline-limit=@var{num}
24726 @opindex mstring-compare-inline-limit
24727 Compare at most @var{num} string bytes with inline code.
24728 If the difference or end of string is not found at the
24729 end of the inline compare a call to @code{strcmp} or @code{strncmp} will
24730 take care of the rest of the comparison. The default is 64 bytes.
24732 @item -G @var{num}
24733 @opindex G
24734 @cindex smaller data references (PowerPC)
24735 @cindex .sdata/.sdata2 references (PowerPC)
24736 On embedded PowerPC systems, put global and static items less than or
24737 equal to @var{num} bytes into the small data or BSS sections instead of
24738 the normal data or BSS section.  By default, @var{num} is 8.  The
24739 @option{-G @var{num}} switch is also passed to the linker.
24740 All modules should be compiled with the same @option{-G @var{num}} value.
24742 @item -mregnames
24743 @itemx -mno-regnames
24744 @opindex mregnames
24745 @opindex mno-regnames
24746 On System V.4 and embedded PowerPC systems do (do not) emit register
24747 names in the assembly language output using symbolic forms.
24749 @item -mlongcall
24750 @itemx -mno-longcall
24751 @opindex mlongcall
24752 @opindex mno-longcall
24753 By default assume that all calls are far away so that a longer and more
24754 expensive calling sequence is required.  This is required for calls
24755 farther than 32 megabytes (33,554,432 bytes) from the current location.
24756 A short call is generated if the compiler knows
24757 the call cannot be that far away.  This setting can be overridden by
24758 the @code{shortcall} function attribute, or by @code{#pragma
24759 longcall(0)}.
24761 Some linkers are capable of detecting out-of-range calls and generating
24762 glue code on the fly.  On these systems, long calls are unnecessary and
24763 generate slower code.  As of this writing, the AIX linker can do this,
24764 as can the GNU linker for PowerPC/64.  It is planned to add this feature
24765 to the GNU linker for 32-bit PowerPC systems as well.
24767 On Darwin/PPC systems, @code{#pragma longcall} generates @code{jbsr
24768 callee, L42}, plus a @dfn{branch island} (glue code).  The two target
24769 addresses represent the callee and the branch island.  The
24770 Darwin/PPC linker prefers the first address and generates a @code{bl
24771 callee} if the PPC @code{bl} instruction reaches the callee directly;
24772 otherwise, the linker generates @code{bl L42} to call the branch
24773 island.  The branch island is appended to the body of the
24774 calling function; it computes the full 32-bit address of the callee
24775 and jumps to it.
24777 On Mach-O (Darwin) systems, this option directs the compiler emit to
24778 the glue for every direct call, and the Darwin linker decides whether
24779 to use or discard it.
24781 In the future, GCC may ignore all longcall specifications
24782 when the linker is known to generate glue.
24784 @item -mtls-markers
24785 @itemx -mno-tls-markers
24786 @opindex mtls-markers
24787 @opindex mno-tls-markers
24788 Mark (do not mark) calls to @code{__tls_get_addr} with a relocation
24789 specifying the function argument.  The relocation allows the linker to
24790 reliably associate function call with argument setup instructions for
24791 TLS optimization, which in turn allows GCC to better schedule the
24792 sequence.
24794 @item -mrecip
24795 @itemx -mno-recip
24796 @opindex mrecip
24797 This option enables use of the reciprocal estimate and
24798 reciprocal square root estimate instructions with additional
24799 Newton-Raphson steps to increase precision instead of doing a divide or
24800 square root and divide for floating-point arguments.  You should use
24801 the @option{-ffast-math} option when using @option{-mrecip} (or at
24802 least @option{-funsafe-math-optimizations},
24803 @option{-ffinite-math-only}, @option{-freciprocal-math} and
24804 @option{-fno-trapping-math}).  Note that while the throughput of the
24805 sequence is generally higher than the throughput of the non-reciprocal
24806 instruction, the precision of the sequence can be decreased by up to 2
24807 ulp (i.e.@: the inverse of 1.0 equals 0.99999994) for reciprocal square
24808 roots.
24810 @item -mrecip=@var{opt}
24811 @opindex mrecip=opt
24812 This option controls which reciprocal estimate instructions
24813 may be used.  @var{opt} is a comma-separated list of options, which may
24814 be preceded by a @code{!} to invert the option:
24816 @table @samp
24818 @item all
24819 Enable all estimate instructions.
24821 @item default 
24822 Enable the default instructions, equivalent to @option{-mrecip}.
24824 @item none 
24825 Disable all estimate instructions, equivalent to @option{-mno-recip}.
24827 @item div 
24828 Enable the reciprocal approximation instructions for both 
24829 single and double precision.
24831 @item divf 
24832 Enable the single-precision reciprocal approximation instructions.
24834 @item divd 
24835 Enable the double-precision reciprocal approximation instructions.
24837 @item rsqrt 
24838 Enable the reciprocal square root approximation instructions for both
24839 single and double precision.
24841 @item rsqrtf 
24842 Enable the single-precision reciprocal square root approximation instructions.
24844 @item rsqrtd 
24845 Enable the double-precision reciprocal square root approximation instructions.
24847 @end table
24849 So, for example, @option{-mrecip=all,!rsqrtd} enables
24850 all of the reciprocal estimate instructions, except for the
24851 @code{FRSQRTE}, @code{XSRSQRTEDP}, and @code{XVRSQRTEDP} instructions
24852 which handle the double-precision reciprocal square root calculations.
24854 @item -mrecip-precision
24855 @itemx -mno-recip-precision
24856 @opindex mrecip-precision
24857 Assume (do not assume) that the reciprocal estimate instructions
24858 provide higher-precision estimates than is mandated by the PowerPC
24859 ABI.  Selecting @option{-mcpu=power6}, @option{-mcpu=power7} or
24860 @option{-mcpu=power8} automatically selects @option{-mrecip-precision}.
24861 The double-precision square root estimate instructions are not generated by
24862 default on low-precision machines, since they do not provide an
24863 estimate that converges after three steps.
24865 @item -mveclibabi=@var{type}
24866 @opindex mveclibabi
24867 Specifies the ABI type to use for vectorizing intrinsics using an
24868 external library.  The only type supported at present is @samp{mass},
24869 which specifies to use IBM's Mathematical Acceleration Subsystem
24870 (MASS) libraries for vectorizing intrinsics using external libraries.
24871 GCC currently emits calls to @code{acosd2}, @code{acosf4},
24872 @code{acoshd2}, @code{acoshf4}, @code{asind2}, @code{asinf4},
24873 @code{asinhd2}, @code{asinhf4}, @code{atan2d2}, @code{atan2f4},
24874 @code{atand2}, @code{atanf4}, @code{atanhd2}, @code{atanhf4},
24875 @code{cbrtd2}, @code{cbrtf4}, @code{cosd2}, @code{cosf4},
24876 @code{coshd2}, @code{coshf4}, @code{erfcd2}, @code{erfcf4},
24877 @code{erfd2}, @code{erff4}, @code{exp2d2}, @code{exp2f4},
24878 @code{expd2}, @code{expf4}, @code{expm1d2}, @code{expm1f4},
24879 @code{hypotd2}, @code{hypotf4}, @code{lgammad2}, @code{lgammaf4},
24880 @code{log10d2}, @code{log10f4}, @code{log1pd2}, @code{log1pf4},
24881 @code{log2d2}, @code{log2f4}, @code{logd2}, @code{logf4},
24882 @code{powd2}, @code{powf4}, @code{sind2}, @code{sinf4}, @code{sinhd2},
24883 @code{sinhf4}, @code{sqrtd2}, @code{sqrtf4}, @code{tand2},
24884 @code{tanf4}, @code{tanhd2}, and @code{tanhf4} when generating code
24885 for power7.  Both @option{-ftree-vectorize} and
24886 @option{-funsafe-math-optimizations} must also be enabled.  The MASS
24887 libraries must be specified at link time.
24889 @item -mfriz
24890 @itemx -mno-friz
24891 @opindex mfriz
24892 Generate (do not generate) the @code{friz} instruction when the
24893 @option{-funsafe-math-optimizations} option is used to optimize
24894 rounding of floating-point values to 64-bit integer and back to floating
24895 point.  The @code{friz} instruction does not return the same value if
24896 the floating-point number is too large to fit in an integer.
24898 @item -mpointers-to-nested-functions
24899 @itemx -mno-pointers-to-nested-functions
24900 @opindex mpointers-to-nested-functions
24901 Generate (do not generate) code to load up the static chain register
24902 (@code{r11}) when calling through a pointer on AIX and 64-bit Linux
24903 systems where a function pointer points to a 3-word descriptor giving
24904 the function address, TOC value to be loaded in register @code{r2}, and
24905 static chain value to be loaded in register @code{r11}.  The
24906 @option{-mpointers-to-nested-functions} is on by default.  You cannot
24907 call through pointers to nested functions or pointers
24908 to functions compiled in other languages that use the static chain if
24909 you use @option{-mno-pointers-to-nested-functions}.
24911 @item -msave-toc-indirect
24912 @itemx -mno-save-toc-indirect
24913 @opindex msave-toc-indirect
24914 Generate (do not generate) code to save the TOC value in the reserved
24915 stack location in the function prologue if the function calls through
24916 a pointer on AIX and 64-bit Linux systems.  If the TOC value is not
24917 saved in the prologue, it is saved just before the call through the
24918 pointer.  The @option{-mno-save-toc-indirect} option is the default.
24920 @item -mcompat-align-parm
24921 @itemx -mno-compat-align-parm
24922 @opindex mcompat-align-parm
24923 Generate (do not generate) code to pass structure parameters with a
24924 maximum alignment of 64 bits, for compatibility with older versions
24925 of GCC.
24927 Older versions of GCC (prior to 4.9.0) incorrectly did not align a
24928 structure parameter on a 128-bit boundary when that structure contained
24929 a member requiring 128-bit alignment.  This is corrected in more
24930 recent versions of GCC.  This option may be used to generate code
24931 that is compatible with functions compiled with older versions of
24932 GCC.
24934 The @option{-mno-compat-align-parm} option is the default.
24936 @item -mstack-protector-guard=@var{guard}
24937 @itemx -mstack-protector-guard-reg=@var{reg}
24938 @itemx -mstack-protector-guard-offset=@var{offset}
24939 @itemx -mstack-protector-guard-symbol=@var{symbol}
24940 @opindex mstack-protector-guard
24941 @opindex mstack-protector-guard-reg
24942 @opindex mstack-protector-guard-offset
24943 @opindex mstack-protector-guard-symbol
24944 Generate stack protection code using canary at @var{guard}.  Supported
24945 locations are @samp{global} for global canary or @samp{tls} for per-thread
24946 canary in the TLS block (the default with GNU libc version 2.4 or later).
24948 With the latter choice the options
24949 @option{-mstack-protector-guard-reg=@var{reg}} and
24950 @option{-mstack-protector-guard-offset=@var{offset}} furthermore specify
24951 which register to use as base register for reading the canary, and from what
24952 offset from that base register. The default for those is as specified in the
24953 relevant ABI.  @option{-mstack-protector-guard-symbol=@var{symbol}} overrides
24954 the offset with a symbol reference to a canary in the TLS block.
24955 @end table
24957 @node RX Options
24958 @subsection RX Options
24959 @cindex RX Options
24961 These command-line options are defined for RX targets:
24963 @table @gcctabopt
24964 @item -m64bit-doubles
24965 @itemx -m32bit-doubles
24966 @opindex m64bit-doubles
24967 @opindex m32bit-doubles
24968 Make the @code{double} data type be 64 bits (@option{-m64bit-doubles})
24969 or 32 bits (@option{-m32bit-doubles}) in size.  The default is
24970 @option{-m32bit-doubles}.  @emph{Note} RX floating-point hardware only
24971 works on 32-bit values, which is why the default is
24972 @option{-m32bit-doubles}.
24974 @item -fpu
24975 @itemx -nofpu
24976 @opindex fpu
24977 @opindex nofpu
24978 Enables (@option{-fpu}) or disables (@option{-nofpu}) the use of RX
24979 floating-point hardware.  The default is enabled for the RX600
24980 series and disabled for the RX200 series.
24982 Floating-point instructions are only generated for 32-bit floating-point 
24983 values, however, so the FPU hardware is not used for doubles if the
24984 @option{-m64bit-doubles} option is used.
24986 @emph{Note} If the @option{-fpu} option is enabled then
24987 @option{-funsafe-math-optimizations} is also enabled automatically.
24988 This is because the RX FPU instructions are themselves unsafe.
24990 @item -mcpu=@var{name}
24991 @opindex mcpu
24992 Selects the type of RX CPU to be targeted.  Currently three types are
24993 supported, the generic @samp{RX600} and @samp{RX200} series hardware and
24994 the specific @samp{RX610} CPU.  The default is @samp{RX600}.
24996 The only difference between @samp{RX600} and @samp{RX610} is that the
24997 @samp{RX610} does not support the @code{MVTIPL} instruction.
24999 The @samp{RX200} series does not have a hardware floating-point unit
25000 and so @option{-nofpu} is enabled by default when this type is
25001 selected.
25003 @item -mbig-endian-data
25004 @itemx -mlittle-endian-data
25005 @opindex mbig-endian-data
25006 @opindex mlittle-endian-data
25007 Store data (but not code) in the big-endian format.  The default is
25008 @option{-mlittle-endian-data}, i.e.@: to store data in the little-endian
25009 format.
25011 @item -msmall-data-limit=@var{N}
25012 @opindex msmall-data-limit
25013 Specifies the maximum size in bytes of global and static variables
25014 which can be placed into the small data area.  Using the small data
25015 area can lead to smaller and faster code, but the size of area is
25016 limited and it is up to the programmer to ensure that the area does
25017 not overflow.  Also when the small data area is used one of the RX's
25018 registers (usually @code{r13}) is reserved for use pointing to this
25019 area, so it is no longer available for use by the compiler.  This
25020 could result in slower and/or larger code if variables are pushed onto
25021 the stack instead of being held in this register.
25023 Note, common variables (variables that have not been initialized) and
25024 constants are not placed into the small data area as they are assigned
25025 to other sections in the output executable.
25027 The default value is zero, which disables this feature.  Note, this
25028 feature is not enabled by default with higher optimization levels
25029 (@option{-O2} etc) because of the potentially detrimental effects of
25030 reserving a register.  It is up to the programmer to experiment and
25031 discover whether this feature is of benefit to their program.  See the
25032 description of the @option{-mpid} option for a description of how the
25033 actual register to hold the small data area pointer is chosen.
25035 @item -msim
25036 @itemx -mno-sim
25037 @opindex msim
25038 @opindex mno-sim
25039 Use the simulator runtime.  The default is to use the libgloss
25040 board-specific runtime.
25042 @item -mas100-syntax
25043 @itemx -mno-as100-syntax
25044 @opindex mas100-syntax
25045 @opindex mno-as100-syntax
25046 When generating assembler output use a syntax that is compatible with
25047 Renesas's AS100 assembler.  This syntax can also be handled by the GAS
25048 assembler, but it has some restrictions so it is not generated by default.
25050 @item -mmax-constant-size=@var{N}
25051 @opindex mmax-constant-size
25052 Specifies the maximum size, in bytes, of a constant that can be used as
25053 an operand in a RX instruction.  Although the RX instruction set does
25054 allow constants of up to 4 bytes in length to be used in instructions,
25055 a longer value equates to a longer instruction.  Thus in some
25056 circumstances it can be beneficial to restrict the size of constants
25057 that are used in instructions.  Constants that are too big are instead
25058 placed into a constant pool and referenced via register indirection.
25060 The value @var{N} can be between 0 and 4.  A value of 0 (the default)
25061 or 4 means that constants of any size are allowed.
25063 @item -mrelax
25064 @opindex mrelax
25065 Enable linker relaxation.  Linker relaxation is a process whereby the
25066 linker attempts to reduce the size of a program by finding shorter
25067 versions of various instructions.  Disabled by default.
25069 @item -mint-register=@var{N}
25070 @opindex mint-register
25071 Specify the number of registers to reserve for fast interrupt handler
25072 functions.  The value @var{N} can be between 0 and 4.  A value of 1
25073 means that register @code{r13} is reserved for the exclusive use
25074 of fast interrupt handlers.  A value of 2 reserves @code{r13} and
25075 @code{r12}.  A value of 3 reserves @code{r13}, @code{r12} and
25076 @code{r11}, and a value of 4 reserves @code{r13} through @code{r10}.
25077 A value of 0, the default, does not reserve any registers.
25079 @item -msave-acc-in-interrupts
25080 @opindex msave-acc-in-interrupts
25081 Specifies that interrupt handler functions should preserve the
25082 accumulator register.  This is only necessary if normal code might use
25083 the accumulator register, for example because it performs 64-bit
25084 multiplications.  The default is to ignore the accumulator as this
25085 makes the interrupt handlers faster.
25087 @item -mpid
25088 @itemx -mno-pid
25089 @opindex mpid
25090 @opindex mno-pid
25091 Enables the generation of position independent data.  When enabled any
25092 access to constant data is done via an offset from a base address
25093 held in a register.  This allows the location of constant data to be
25094 determined at run time without requiring the executable to be
25095 relocated, which is a benefit to embedded applications with tight
25096 memory constraints.  Data that can be modified is not affected by this
25097 option.
25099 Note, using this feature reserves a register, usually @code{r13}, for
25100 the constant data base address.  This can result in slower and/or
25101 larger code, especially in complicated functions.
25103 The actual register chosen to hold the constant data base address
25104 depends upon whether the @option{-msmall-data-limit} and/or the
25105 @option{-mint-register} command-line options are enabled.  Starting
25106 with register @code{r13} and proceeding downwards, registers are
25107 allocated first to satisfy the requirements of @option{-mint-register},
25108 then @option{-mpid} and finally @option{-msmall-data-limit}.  Thus it
25109 is possible for the small data area register to be @code{r8} if both
25110 @option{-mint-register=4} and @option{-mpid} are specified on the
25111 command line.
25113 By default this feature is not enabled.  The default can be restored
25114 via the @option{-mno-pid} command-line option.
25116 @item -mno-warn-multiple-fast-interrupts
25117 @itemx -mwarn-multiple-fast-interrupts
25118 @opindex mno-warn-multiple-fast-interrupts
25119 @opindex mwarn-multiple-fast-interrupts
25120 Prevents GCC from issuing a warning message if it finds more than one
25121 fast interrupt handler when it is compiling a file.  The default is to
25122 issue a warning for each extra fast interrupt handler found, as the RX
25123 only supports one such interrupt.
25125 @item -mallow-string-insns
25126 @itemx -mno-allow-string-insns
25127 @opindex mallow-string-insns
25128 @opindex mno-allow-string-insns
25129 Enables or disables the use of the string manipulation instructions
25130 @code{SMOVF}, @code{SCMPU}, @code{SMOVB}, @code{SMOVU}, @code{SUNTIL}
25131 @code{SWHILE} and also the @code{RMPA} instruction.  These
25132 instructions may prefetch data, which is not safe to do if accessing
25133 an I/O register.  (See section 12.2.7 of the RX62N Group User's Manual
25134 for more information).
25136 The default is to allow these instructions, but it is not possible for
25137 GCC to reliably detect all circumstances where a string instruction
25138 might be used to access an I/O register, so their use cannot be
25139 disabled automatically.  Instead it is reliant upon the programmer to
25140 use the @option{-mno-allow-string-insns} option if their program
25141 accesses I/O space.
25143 When the instructions are enabled GCC defines the C preprocessor
25144 symbol @code{__RX_ALLOW_STRING_INSNS__}, otherwise it defines the
25145 symbol @code{__RX_DISALLOW_STRING_INSNS__}.
25147 @item -mjsr
25148 @itemx -mno-jsr
25149 @opindex mjsr
25150 @opindex mno-jsr
25151 Use only (or not only) @code{JSR} instructions to access functions.
25152 This option can be used when code size exceeds the range of @code{BSR}
25153 instructions.  Note that @option{-mno-jsr} does not mean to not use
25154 @code{JSR} but instead means that any type of branch may be used.
25155 @end table
25157 @emph{Note:} The generic GCC command-line option @option{-ffixed-@var{reg}}
25158 has special significance to the RX port when used with the
25159 @code{interrupt} function attribute.  This attribute indicates a
25160 function intended to process fast interrupts.  GCC ensures
25161 that it only uses the registers @code{r10}, @code{r11}, @code{r12}
25162 and/or @code{r13} and only provided that the normal use of the
25163 corresponding registers have been restricted via the
25164 @option{-ffixed-@var{reg}} or @option{-mint-register} command-line
25165 options.
25167 @node S/390 and zSeries Options
25168 @subsection S/390 and zSeries Options
25169 @cindex S/390 and zSeries Options
25171 These are the @samp{-m} options defined for the S/390 and zSeries architecture.
25173 @table @gcctabopt
25174 @item -mhard-float
25175 @itemx -msoft-float
25176 @opindex mhard-float
25177 @opindex msoft-float
25178 Use (do not use) the hardware floating-point instructions and registers
25179 for floating-point operations.  When @option{-msoft-float} is specified,
25180 functions in @file{libgcc.a} are used to perform floating-point
25181 operations.  When @option{-mhard-float} is specified, the compiler
25182 generates IEEE floating-point instructions.  This is the default.
25184 @item -mhard-dfp
25185 @itemx -mno-hard-dfp
25186 @opindex mhard-dfp
25187 @opindex mno-hard-dfp
25188 Use (do not use) the hardware decimal-floating-point instructions for
25189 decimal-floating-point operations.  When @option{-mno-hard-dfp} is
25190 specified, functions in @file{libgcc.a} are used to perform
25191 decimal-floating-point operations.  When @option{-mhard-dfp} is
25192 specified, the compiler generates decimal-floating-point hardware
25193 instructions.  This is the default for @option{-march=z9-ec} or higher.
25195 @item -mlong-double-64
25196 @itemx -mlong-double-128
25197 @opindex mlong-double-64
25198 @opindex mlong-double-128
25199 These switches control the size of @code{long double} type. A size
25200 of 64 bits makes the @code{long double} type equivalent to the @code{double}
25201 type. This is the default.
25203 @item -mbackchain
25204 @itemx -mno-backchain
25205 @opindex mbackchain
25206 @opindex mno-backchain
25207 Store (do not store) the address of the caller's frame as backchain pointer
25208 into the callee's stack frame.
25209 A backchain may be needed to allow debugging using tools that do not understand
25210 DWARF call frame information.
25211 When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
25212 at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
25213 the backchain is placed into the topmost word of the 96/160 byte register
25214 save area.
25216 In general, code compiled with @option{-mbackchain} is call-compatible with
25217 code compiled with @option{-mmo-backchain}; however, use of the backchain
25218 for debugging purposes usually requires that the whole binary is built with
25219 @option{-mbackchain}.  Note that the combination of @option{-mbackchain},
25220 @option{-mpacked-stack} and @option{-mhard-float} is not supported.  In order
25221 to build a linux kernel use @option{-msoft-float}.
25223 The default is to not maintain the backchain.
25225 @item -mpacked-stack
25226 @itemx -mno-packed-stack
25227 @opindex mpacked-stack
25228 @opindex mno-packed-stack
25229 Use (do not use) the packed stack layout.  When @option{-mno-packed-stack} is
25230 specified, the compiler uses the all fields of the 96/160 byte register save
25231 area only for their default purpose; unused fields still take up stack space.
25232 When @option{-mpacked-stack} is specified, register save slots are densely
25233 packed at the top of the register save area; unused space is reused for other
25234 purposes, allowing for more efficient use of the available stack space.
25235 However, when @option{-mbackchain} is also in effect, the topmost word of
25236 the save area is always used to store the backchain, and the return address
25237 register is always saved two words below the backchain.
25239 As long as the stack frame backchain is not used, code generated with
25240 @option{-mpacked-stack} is call-compatible with code generated with
25241 @option{-mno-packed-stack}.  Note that some non-FSF releases of GCC 2.95 for
25242 S/390 or zSeries generated code that uses the stack frame backchain at run
25243 time, not just for debugging purposes.  Such code is not call-compatible
25244 with code compiled with @option{-mpacked-stack}.  Also, note that the
25245 combination of @option{-mbackchain},
25246 @option{-mpacked-stack} and @option{-mhard-float} is not supported.  In order
25247 to build a linux kernel use @option{-msoft-float}.
25249 The default is to not use the packed stack layout.
25251 @item -msmall-exec
25252 @itemx -mno-small-exec
25253 @opindex msmall-exec
25254 @opindex mno-small-exec
25255 Generate (or do not generate) code using the @code{bras} instruction
25256 to do subroutine calls.
25257 This only works reliably if the total executable size does not
25258 exceed 64k.  The default is to use the @code{basr} instruction instead,
25259 which does not have this limitation.
25261 @item -m64
25262 @itemx -m31
25263 @opindex m64
25264 @opindex m31
25265 When @option{-m31} is specified, generate code compliant to the
25266 GNU/Linux for S/390 ABI@.  When @option{-m64} is specified, generate
25267 code compliant to the GNU/Linux for zSeries ABI@.  This allows GCC in
25268 particular to generate 64-bit instructions.  For the @samp{s390}
25269 targets, the default is @option{-m31}, while the @samp{s390x}
25270 targets default to @option{-m64}.
25272 @item -mzarch
25273 @itemx -mesa
25274 @opindex mzarch
25275 @opindex mesa
25276 When @option{-mzarch} is specified, generate code using the
25277 instructions available on z/Architecture.
25278 When @option{-mesa} is specified, generate code using the
25279 instructions available on ESA/390.  Note that @option{-mesa} is
25280 not possible with @option{-m64}.
25281 When generating code compliant to the GNU/Linux for S/390 ABI,
25282 the default is @option{-mesa}.  When generating code compliant
25283 to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
25285 @item -mhtm
25286 @itemx -mno-htm
25287 @opindex mhtm
25288 @opindex mno-htm
25289 The @option{-mhtm} option enables a set of builtins making use of
25290 instructions available with the transactional execution facility
25291 introduced with the IBM zEnterprise EC12 machine generation
25292 @ref{S/390 System z Built-in Functions}.
25293 @option{-mhtm} is enabled by default when using @option{-march=zEC12}.
25295 @item -mvx
25296 @itemx -mno-vx
25297 @opindex mvx
25298 @opindex mno-vx
25299 When @option{-mvx} is specified, generate code using the instructions
25300 available with the vector extension facility introduced with the IBM
25301 z13 machine generation.
25302 This option changes the ABI for some vector type values with regard to
25303 alignment and calling conventions.  In case vector type values are
25304 being used in an ABI-relevant context a GAS @samp{.gnu_attribute}
25305 command will be added to mark the resulting binary with the ABI used.
25306 @option{-mvx} is enabled by default when using @option{-march=z13}.
25308 @item -mzvector
25309 @itemx -mno-zvector
25310 @opindex mzvector
25311 @opindex mno-zvector
25312 The @option{-mzvector} option enables vector language extensions and
25313 builtins using instructions available with the vector extension
25314 facility introduced with the IBM z13 machine generation.
25315 This option adds support for @samp{vector} to be used as a keyword to
25316 define vector type variables and arguments.  @samp{vector} is only
25317 available when GNU extensions are enabled.  It will not be expanded
25318 when requesting strict standard compliance e.g. with @option{-std=c99}.
25319 In addition to the GCC low-level builtins @option{-mzvector} enables
25320 a set of builtins added for compatibility with AltiVec-style
25321 implementations like Power and Cell.  In order to make use of these
25322 builtins the header file @file{vecintrin.h} needs to be included.
25323 @option{-mzvector} is disabled by default.
25325 @item -mmvcle
25326 @itemx -mno-mvcle
25327 @opindex mmvcle
25328 @opindex mno-mvcle
25329 Generate (or do not generate) code using the @code{mvcle} instruction
25330 to perform block moves.  When @option{-mno-mvcle} is specified,
25331 use a @code{mvc} loop instead.  This is the default unless optimizing for
25332 size.
25334 @item -mdebug
25335 @itemx -mno-debug
25336 @opindex mdebug
25337 @opindex mno-debug
25338 Print (or do not print) additional debug information when compiling.
25339 The default is to not print debug information.
25341 @item -march=@var{cpu-type}
25342 @opindex march
25343 Generate code that runs on @var{cpu-type}, which is the name of a
25344 system representing a certain processor type.  Possible values for
25345 @var{cpu-type} are @samp{z900}/@samp{arch5}, @samp{z990}/@samp{arch6},
25346 @samp{z9-109}, @samp{z9-ec}/@samp{arch7}, @samp{z10}/@samp{arch8},
25347 @samp{z196}/@samp{arch9}, @samp{zEC12}, @samp{z13}/@samp{arch11}, and
25348 @samp{native}.
25350 The default is @option{-march=z900}.
25352 Specifying @samp{native} as cpu type can be used to select the best
25353 architecture option for the host processor.
25354 @option{-march=native} has no effect if GCC does not recognize the
25355 processor.
25357 @item -mtune=@var{cpu-type}
25358 @opindex mtune
25359 Tune to @var{cpu-type} everything applicable about the generated code,
25360 except for the ABI and the set of available instructions.
25361 The list of @var{cpu-type} values is the same as for @option{-march}.
25362 The default is the value used for @option{-march}.
25364 @item -mtpf-trace
25365 @itemx -mno-tpf-trace
25366 @opindex mtpf-trace
25367 @opindex mno-tpf-trace
25368 Generate code that adds (does not add) in TPF OS specific branches to trace
25369 routines in the operating system.  This option is off by default, even
25370 when compiling for the TPF OS@.
25372 @item -mfused-madd
25373 @itemx -mno-fused-madd
25374 @opindex mfused-madd
25375 @opindex mno-fused-madd
25376 Generate code that uses (does not use) the floating-point multiply and
25377 accumulate instructions.  These instructions are generated by default if
25378 hardware floating point is used.
25380 @item -mwarn-framesize=@var{framesize}
25381 @opindex mwarn-framesize
25382 Emit a warning if the current function exceeds the given frame size.  Because
25383 this is a compile-time check it doesn't need to be a real problem when the program
25384 runs.  It is intended to identify functions that most probably cause
25385 a stack overflow.  It is useful to be used in an environment with limited stack
25386 size e.g.@: the linux kernel.
25388 @item -mwarn-dynamicstack
25389 @opindex mwarn-dynamicstack
25390 Emit a warning if the function calls @code{alloca} or uses dynamically-sized
25391 arrays.  This is generally a bad idea with a limited stack size.
25393 @item -mstack-guard=@var{stack-guard}
25394 @itemx -mstack-size=@var{stack-size}
25395 @opindex mstack-guard
25396 @opindex mstack-size
25397 If these options are provided the S/390 back end emits additional instructions in
25398 the function prologue that trigger a trap if the stack size is @var{stack-guard}
25399 bytes above the @var{stack-size} (remember that the stack on S/390 grows downward).
25400 If the @var{stack-guard} option is omitted the smallest power of 2 larger than
25401 the frame size of the compiled function is chosen.
25402 These options are intended to be used to help debugging stack overflow problems.
25403 The additionally emitted code causes only little overhead and hence can also be
25404 used in production-like systems without greater performance degradation.  The given
25405 values have to be exact powers of 2 and @var{stack-size} has to be greater than
25406 @var{stack-guard} without exceeding 64k.
25407 In order to be efficient the extra code makes the assumption that the stack starts
25408 at an address aligned to the value given by @var{stack-size}.
25409 The @var{stack-guard} option can only be used in conjunction with @var{stack-size}.
25411 @item -mhotpatch=@var{pre-halfwords},@var{post-halfwords}
25412 @opindex mhotpatch
25413 If the hotpatch option is enabled, a ``hot-patching'' function
25414 prologue is generated for all functions in the compilation unit.
25415 The funtion label is prepended with the given number of two-byte
25416 NOP instructions (@var{pre-halfwords}, maximum 1000000).  After
25417 the label, 2 * @var{post-halfwords} bytes are appended, using the
25418 largest NOP like instructions the architecture allows (maximum
25419 1000000).
25421 If both arguments are zero, hotpatching is disabled.
25423 This option can be overridden for individual functions with the
25424 @code{hotpatch} attribute.
25425 @end table
25427 @node Score Options
25428 @subsection Score Options
25429 @cindex Score Options
25431 These options are defined for Score implementations:
25433 @table @gcctabopt
25434 @item -meb
25435 @opindex meb
25436 Compile code for big-endian mode.  This is the default.
25438 @item -mel
25439 @opindex mel
25440 Compile code for little-endian mode.
25442 @item -mnhwloop
25443 @opindex mnhwloop
25444 Disable generation of @code{bcnz} instructions.
25446 @item -muls
25447 @opindex muls
25448 Enable generation of unaligned load and store instructions.
25450 @item -mmac
25451 @opindex mmac
25452 Enable the use of multiply-accumulate instructions. Disabled by default.
25454 @item -mscore5
25455 @opindex mscore5
25456 Specify the SCORE5 as the target architecture.
25458 @item -mscore5u
25459 @opindex mscore5u
25460 Specify the SCORE5U of the target architecture.
25462 @item -mscore7
25463 @opindex mscore7
25464 Specify the SCORE7 as the target architecture. This is the default.
25466 @item -mscore7d
25467 @opindex mscore7d
25468 Specify the SCORE7D as the target architecture.
25469 @end table
25471 @node SH Options
25472 @subsection SH Options
25474 These @samp{-m} options are defined for the SH implementations:
25476 @table @gcctabopt
25477 @item -m1
25478 @opindex m1
25479 Generate code for the SH1.
25481 @item -m2
25482 @opindex m2
25483 Generate code for the SH2.
25485 @item -m2e
25486 Generate code for the SH2e.
25488 @item -m2a-nofpu
25489 @opindex m2a-nofpu
25490 Generate code for the SH2a without FPU, or for a SH2a-FPU in such a way
25491 that the floating-point unit is not used.
25493 @item -m2a-single-only
25494 @opindex m2a-single-only
25495 Generate code for the SH2a-FPU, in such a way that no double-precision
25496 floating-point operations are used.
25498 @item -m2a-single
25499 @opindex m2a-single
25500 Generate code for the SH2a-FPU assuming the floating-point unit is in
25501 single-precision mode by default.
25503 @item -m2a
25504 @opindex m2a
25505 Generate code for the SH2a-FPU assuming the floating-point unit is in
25506 double-precision mode by default.
25508 @item -m3
25509 @opindex m3
25510 Generate code for the SH3.
25512 @item -m3e
25513 @opindex m3e
25514 Generate code for the SH3e.
25516 @item -m4-nofpu
25517 @opindex m4-nofpu
25518 Generate code for the SH4 without a floating-point unit.
25520 @item -m4-single-only
25521 @opindex m4-single-only
25522 Generate code for the SH4 with a floating-point unit that only
25523 supports single-precision arithmetic.
25525 @item -m4-single
25526 @opindex m4-single
25527 Generate code for the SH4 assuming the floating-point unit is in
25528 single-precision mode by default.
25530 @item -m4
25531 @opindex m4
25532 Generate code for the SH4.
25534 @item -m4-100
25535 @opindex m4-100
25536 Generate code for SH4-100.
25538 @item -m4-100-nofpu
25539 @opindex m4-100-nofpu
25540 Generate code for SH4-100 in such a way that the
25541 floating-point unit is not used.
25543 @item -m4-100-single
25544 @opindex m4-100-single
25545 Generate code for SH4-100 assuming the floating-point unit is in
25546 single-precision mode by default.
25548 @item -m4-100-single-only
25549 @opindex m4-100-single-only
25550 Generate code for SH4-100 in such a way that no double-precision
25551 floating-point operations are used.
25553 @item -m4-200
25554 @opindex m4-200
25555 Generate code for SH4-200.
25557 @item -m4-200-nofpu
25558 @opindex m4-200-nofpu
25559 Generate code for SH4-200 without in such a way that the
25560 floating-point unit is not used.
25562 @item -m4-200-single
25563 @opindex m4-200-single
25564 Generate code for SH4-200 assuming the floating-point unit is in
25565 single-precision mode by default.
25567 @item -m4-200-single-only
25568 @opindex m4-200-single-only
25569 Generate code for SH4-200 in such a way that no double-precision
25570 floating-point operations are used.
25572 @item -m4-300
25573 @opindex m4-300
25574 Generate code for SH4-300.
25576 @item -m4-300-nofpu
25577 @opindex m4-300-nofpu
25578 Generate code for SH4-300 without in such a way that the
25579 floating-point unit is not used.
25581 @item -m4-300-single
25582 @opindex m4-300-single
25583 Generate code for SH4-300 in such a way that no double-precision
25584 floating-point operations are used.
25586 @item -m4-300-single-only
25587 @opindex m4-300-single-only
25588 Generate code for SH4-300 in such a way that no double-precision
25589 floating-point operations are used.
25591 @item -m4-340
25592 @opindex m4-340
25593 Generate code for SH4-340 (no MMU, no FPU).
25595 @item -m4-500
25596 @opindex m4-500
25597 Generate code for SH4-500 (no FPU).  Passes @option{-isa=sh4-nofpu} to the
25598 assembler.
25600 @item -m4a-nofpu
25601 @opindex m4a-nofpu
25602 Generate code for the SH4al-dsp, or for a SH4a in such a way that the
25603 floating-point unit is not used.
25605 @item -m4a-single-only
25606 @opindex m4a-single-only
25607 Generate code for the SH4a, in such a way that no double-precision
25608 floating-point operations are used.
25610 @item -m4a-single
25611 @opindex m4a-single
25612 Generate code for the SH4a assuming the floating-point unit is in
25613 single-precision mode by default.
25615 @item -m4a
25616 @opindex m4a
25617 Generate code for the SH4a.
25619 @item -m4al
25620 @opindex m4al
25621 Same as @option{-m4a-nofpu}, except that it implicitly passes
25622 @option{-dsp} to the assembler.  GCC doesn't generate any DSP
25623 instructions at the moment.
25625 @item -mb
25626 @opindex mb
25627 Compile code for the processor in big-endian mode.
25629 @item -ml
25630 @opindex ml
25631 Compile code for the processor in little-endian mode.
25633 @item -mdalign
25634 @opindex mdalign
25635 Align doubles at 64-bit boundaries.  Note that this changes the calling
25636 conventions, and thus some functions from the standard C library do
25637 not work unless you recompile it first with @option{-mdalign}.
25639 @item -mrelax
25640 @opindex mrelax
25641 Shorten some address references at link time, when possible; uses the
25642 linker option @option{-relax}.
25644 @item -mbigtable
25645 @opindex mbigtable
25646 Use 32-bit offsets in @code{switch} tables.  The default is to use
25647 16-bit offsets.
25649 @item -mbitops
25650 @opindex mbitops
25651 Enable the use of bit manipulation instructions on SH2A.
25653 @item -mfmovd
25654 @opindex mfmovd
25655 Enable the use of the instruction @code{fmovd}.  Check @option{-mdalign} for
25656 alignment constraints.
25658 @item -mrenesas
25659 @opindex mrenesas
25660 Comply with the calling conventions defined by Renesas.
25662 @item -mno-renesas
25663 @opindex mno-renesas
25664 Comply with the calling conventions defined for GCC before the Renesas
25665 conventions were available.  This option is the default for all
25666 targets of the SH toolchain.
25668 @item -mnomacsave
25669 @opindex mnomacsave
25670 Mark the @code{MAC} register as call-clobbered, even if
25671 @option{-mrenesas} is given.
25673 @item -mieee
25674 @itemx -mno-ieee
25675 @opindex mieee
25676 @opindex mno-ieee
25677 Control the IEEE compliance of floating-point comparisons, which affects the
25678 handling of cases where the result of a comparison is unordered.  By default
25679 @option{-mieee} is implicitly enabled.  If @option{-ffinite-math-only} is
25680 enabled @option{-mno-ieee} is implicitly set, which results in faster
25681 floating-point greater-equal and less-equal comparisons.  The implicit settings
25682 can be overridden by specifying either @option{-mieee} or @option{-mno-ieee}.
25684 @item -minline-ic_invalidate
25685 @opindex minline-ic_invalidate
25686 Inline code to invalidate instruction cache entries after setting up
25687 nested function trampolines.
25688 This option has no effect if @option{-musermode} is in effect and the selected
25689 code generation option (e.g. @option{-m4}) does not allow the use of the @code{icbi}
25690 instruction.
25691 If the selected code generation option does not allow the use of the @code{icbi}
25692 instruction, and @option{-musermode} is not in effect, the inlined code
25693 manipulates the instruction cache address array directly with an associative
25694 write.  This not only requires privileged mode at run time, but it also
25695 fails if the cache line had been mapped via the TLB and has become unmapped.
25697 @item -misize
25698 @opindex misize
25699 Dump instruction size and location in the assembly code.
25701 @item -mpadstruct
25702 @opindex mpadstruct
25703 This option is deprecated.  It pads structures to multiple of 4 bytes,
25704 which is incompatible with the SH ABI@.
25706 @item -matomic-model=@var{model}
25707 @opindex matomic-model=@var{model}
25708 Sets the model of atomic operations and additional parameters as a comma
25709 separated list.  For details on the atomic built-in functions see
25710 @ref{__atomic Builtins}.  The following models and parameters are supported:
25712 @table @samp
25714 @item none
25715 Disable compiler generated atomic sequences and emit library calls for atomic
25716 operations.  This is the default if the target is not @code{sh*-*-linux*}.
25718 @item soft-gusa
25719 Generate GNU/Linux compatible gUSA software atomic sequences for the atomic
25720 built-in functions.  The generated atomic sequences require additional support
25721 from the interrupt/exception handling code of the system and are only suitable
25722 for SH3* and SH4* single-core systems.  This option is enabled by default when
25723 the target is @code{sh*-*-linux*} and SH3* or SH4*.  When the target is SH4A,
25724 this option also partially utilizes the hardware atomic instructions
25725 @code{movli.l} and @code{movco.l} to create more efficient code, unless
25726 @samp{strict} is specified.  
25728 @item soft-tcb
25729 Generate software atomic sequences that use a variable in the thread control
25730 block.  This is a variation of the gUSA sequences which can also be used on
25731 SH1* and SH2* targets.  The generated atomic sequences require additional
25732 support from the interrupt/exception handling code of the system and are only
25733 suitable for single-core systems.  When using this model, the @samp{gbr-offset=}
25734 parameter has to be specified as well.
25736 @item soft-imask
25737 Generate software atomic sequences that temporarily disable interrupts by
25738 setting @code{SR.IMASK = 1111}.  This model works only when the program runs
25739 in privileged mode and is only suitable for single-core systems.  Additional
25740 support from the interrupt/exception handling code of the system is not
25741 required.  This model is enabled by default when the target is
25742 @code{sh*-*-linux*} and SH1* or SH2*.
25744 @item hard-llcs
25745 Generate hardware atomic sequences using the @code{movli.l} and @code{movco.l}
25746 instructions only.  This is only available on SH4A and is suitable for
25747 multi-core systems.  Since the hardware instructions support only 32 bit atomic
25748 variables access to 8 or 16 bit variables is emulated with 32 bit accesses.
25749 Code compiled with this option is also compatible with other software
25750 atomic model interrupt/exception handling systems if executed on an SH4A
25751 system.  Additional support from the interrupt/exception handling code of the
25752 system is not required for this model.
25754 @item gbr-offset=
25755 This parameter specifies the offset in bytes of the variable in the thread
25756 control block structure that should be used by the generated atomic sequences
25757 when the @samp{soft-tcb} model has been selected.  For other models this
25758 parameter is ignored.  The specified value must be an integer multiple of four
25759 and in the range 0-1020.
25761 @item strict
25762 This parameter prevents mixed usage of multiple atomic models, even if they
25763 are compatible, and makes the compiler generate atomic sequences of the
25764 specified model only.
25766 @end table
25768 @item -mtas
25769 @opindex mtas
25770 Generate the @code{tas.b} opcode for @code{__atomic_test_and_set}.
25771 Notice that depending on the particular hardware and software configuration
25772 this can degrade overall performance due to the operand cache line flushes
25773 that are implied by the @code{tas.b} instruction.  On multi-core SH4A
25774 processors the @code{tas.b} instruction must be used with caution since it
25775 can result in data corruption for certain cache configurations.
25777 @item -mprefergot
25778 @opindex mprefergot
25779 When generating position-independent code, emit function calls using
25780 the Global Offset Table instead of the Procedure Linkage Table.
25782 @item -musermode
25783 @itemx -mno-usermode
25784 @opindex musermode
25785 @opindex mno-usermode
25786 Don't allow (allow) the compiler generating privileged mode code.  Specifying
25787 @option{-musermode} also implies @option{-mno-inline-ic_invalidate} if the
25788 inlined code would not work in user mode.  @option{-musermode} is the default
25789 when the target is @code{sh*-*-linux*}.  If the target is SH1* or SH2*
25790 @option{-musermode} has no effect, since there is no user mode.
25792 @item -multcost=@var{number}
25793 @opindex multcost=@var{number}
25794 Set the cost to assume for a multiply insn.
25796 @item -mdiv=@var{strategy}
25797 @opindex mdiv=@var{strategy}
25798 Set the division strategy to be used for integer division operations.
25799 @var{strategy} can be one of: 
25801 @table @samp
25803 @item call-div1
25804 Calls a library function that uses the single-step division instruction
25805 @code{div1} to perform the operation.  Division by zero calculates an
25806 unspecified result and does not trap.  This is the default except for SH4,
25807 SH2A and SHcompact.
25809 @item call-fp
25810 Calls a library function that performs the operation in double precision
25811 floating point.  Division by zero causes a floating-point exception.  This is
25812 the default for SHcompact with FPU.  Specifying this for targets that do not
25813 have a double precision FPU defaults to @code{call-div1}.
25815 @item call-table
25816 Calls a library function that uses a lookup table for small divisors and
25817 the @code{div1} instruction with case distinction for larger divisors.  Division
25818 by zero calculates an unspecified result and does not trap.  This is the default
25819 for SH4.  Specifying this for targets that do not have dynamic shift
25820 instructions defaults to @code{call-div1}.
25822 @end table
25824 When a division strategy has not been specified the default strategy is
25825 selected based on the current target.  For SH2A the default strategy is to
25826 use the @code{divs} and @code{divu} instructions instead of library function
25827 calls.
25829 @item -maccumulate-outgoing-args
25830 @opindex maccumulate-outgoing-args
25831 Reserve space once for outgoing arguments in the function prologue rather
25832 than around each call.  Generally beneficial for performance and size.  Also
25833 needed for unwinding to avoid changing the stack frame around conditional code.
25835 @item -mdivsi3_libfunc=@var{name}
25836 @opindex mdivsi3_libfunc=@var{name}
25837 Set the name of the library function used for 32-bit signed division to
25838 @var{name}.
25839 This only affects the name used in the @samp{call} division strategies, and
25840 the compiler still expects the same sets of input/output/clobbered registers as
25841 if this option were not present.
25843 @item -mfixed-range=@var{register-range}
25844 @opindex mfixed-range
25845 Generate code treating the given register range as fixed registers.
25846 A fixed register is one that the register allocator can not use.  This is
25847 useful when compiling kernel code.  A register range is specified as
25848 two registers separated by a dash.  Multiple register ranges can be
25849 specified separated by a comma.
25851 @item -mbranch-cost=@var{num}
25852 @opindex mbranch-cost=@var{num}
25853 Assume @var{num} to be the cost for a branch instruction.  Higher numbers
25854 make the compiler try to generate more branch-free code if possible.  
25855 If not specified the value is selected depending on the processor type that
25856 is being compiled for.
25858 @item -mzdcbranch
25859 @itemx -mno-zdcbranch
25860 @opindex mzdcbranch
25861 @opindex mno-zdcbranch
25862 Assume (do not assume) that zero displacement conditional branch instructions
25863 @code{bt} and @code{bf} are fast.  If @option{-mzdcbranch} is specified, the
25864 compiler prefers zero displacement branch code sequences.  This is
25865 enabled by default when generating code for SH4 and SH4A.  It can be explicitly
25866 disabled by specifying @option{-mno-zdcbranch}.
25868 @item -mcbranch-force-delay-slot
25869 @opindex mcbranch-force-delay-slot
25870 Force the usage of delay slots for conditional branches, which stuffs the delay
25871 slot with a @code{nop} if a suitable instruction cannot be found.  By default
25872 this option is disabled.  It can be enabled to work around hardware bugs as
25873 found in the original SH7055.
25875 @item -mfused-madd
25876 @itemx -mno-fused-madd
25877 @opindex mfused-madd
25878 @opindex mno-fused-madd
25879 Generate code that uses (does not use) the floating-point multiply and
25880 accumulate instructions.  These instructions are generated by default
25881 if hardware floating point is used.  The machine-dependent
25882 @option{-mfused-madd} option is now mapped to the machine-independent
25883 @option{-ffp-contract=fast} option, and @option{-mno-fused-madd} is
25884 mapped to @option{-ffp-contract=off}.
25886 @item -mfsca
25887 @itemx -mno-fsca
25888 @opindex mfsca
25889 @opindex mno-fsca
25890 Allow or disallow the compiler to emit the @code{fsca} instruction for sine
25891 and cosine approximations.  The option @option{-mfsca} must be used in
25892 combination with @option{-funsafe-math-optimizations}.  It is enabled by default
25893 when generating code for SH4A.  Using @option{-mno-fsca} disables sine and cosine
25894 approximations even if @option{-funsafe-math-optimizations} is in effect.
25896 @item -mfsrra
25897 @itemx -mno-fsrra
25898 @opindex mfsrra
25899 @opindex mno-fsrra
25900 Allow or disallow the compiler to emit the @code{fsrra} instruction for
25901 reciprocal square root approximations.  The option @option{-mfsrra} must be used
25902 in combination with @option{-funsafe-math-optimizations} and
25903 @option{-ffinite-math-only}.  It is enabled by default when generating code for
25904 SH4A.  Using @option{-mno-fsrra} disables reciprocal square root approximations
25905 even if @option{-funsafe-math-optimizations} and @option{-ffinite-math-only} are
25906 in effect.
25908 @item -mpretend-cmove
25909 @opindex mpretend-cmove
25910 Prefer zero-displacement conditional branches for conditional move instruction
25911 patterns.  This can result in faster code on the SH4 processor.
25913 @item -mfdpic
25914 @opindex fdpic
25915 Generate code using the FDPIC ABI.
25917 @end table
25919 @node Solaris 2 Options
25920 @subsection Solaris 2 Options
25921 @cindex Solaris 2 options
25923 These @samp{-m} options are supported on Solaris 2:
25925 @table @gcctabopt
25926 @item -mclear-hwcap
25927 @opindex mclear-hwcap
25928 @option{-mclear-hwcap} tells the compiler to remove the hardware
25929 capabilities generated by the Solaris assembler.  This is only necessary
25930 when object files use ISA extensions not supported by the current
25931 machine, but check at runtime whether or not to use them.
25933 @item -mimpure-text
25934 @opindex mimpure-text
25935 @option{-mimpure-text}, used in addition to @option{-shared}, tells
25936 the compiler to not pass @option{-z text} to the linker when linking a
25937 shared object.  Using this option, you can link position-dependent
25938 code into a shared object.
25940 @option{-mimpure-text} suppresses the ``relocations remain against
25941 allocatable but non-writable sections'' linker error message.
25942 However, the necessary relocations trigger copy-on-write, and the
25943 shared object is not actually shared across processes.  Instead of
25944 using @option{-mimpure-text}, you should compile all source code with
25945 @option{-fpic} or @option{-fPIC}.
25947 @end table
25949 These switches are supported in addition to the above on Solaris 2:
25951 @table @gcctabopt
25952 @item -pthreads
25953 @opindex pthreads
25954 This is a synonym for @option{-pthread}.
25955 @end table
25957 @node SPARC Options
25958 @subsection SPARC Options
25959 @cindex SPARC options
25961 These @samp{-m} options are supported on the SPARC:
25963 @table @gcctabopt
25964 @item -mno-app-regs
25965 @itemx -mapp-regs
25966 @opindex mno-app-regs
25967 @opindex mapp-regs
25968 Specify @option{-mapp-regs} to generate output using the global registers
25969 2 through 4, which the SPARC SVR4 ABI reserves for applications.  Like the
25970 global register 1, each global register 2 through 4 is then treated as an
25971 allocable register that is clobbered by function calls.  This is the default.
25973 To be fully SVR4 ABI-compliant at the cost of some performance loss,
25974 specify @option{-mno-app-regs}.  You should compile libraries and system
25975 software with this option.
25977 @item -mflat
25978 @itemx -mno-flat
25979 @opindex mflat
25980 @opindex mno-flat
25981 With @option{-mflat}, the compiler does not generate save/restore instructions
25982 and uses a ``flat'' or single register window model.  This model is compatible
25983 with the regular register window model.  The local registers and the input
25984 registers (0--5) are still treated as ``call-saved'' registers and are
25985 saved on the stack as needed.
25987 With @option{-mno-flat} (the default), the compiler generates save/restore
25988 instructions (except for leaf functions).  This is the normal operating mode.
25990 @item -mfpu
25991 @itemx -mhard-float
25992 @opindex mfpu
25993 @opindex mhard-float
25994 Generate output containing floating-point instructions.  This is the
25995 default.
25997 @item -mno-fpu
25998 @itemx -msoft-float
25999 @opindex mno-fpu
26000 @opindex msoft-float
26001 Generate output containing library calls for floating point.
26002 @strong{Warning:} the requisite libraries are not available for all SPARC
26003 targets.  Normally the facilities of the machine's usual C compiler are
26004 used, but this cannot be done directly in cross-compilation.  You must make
26005 your own arrangements to provide suitable library functions for
26006 cross-compilation.  The embedded targets @samp{sparc-*-aout} and
26007 @samp{sparclite-*-*} do provide software floating-point support.
26009 @option{-msoft-float} changes the calling convention in the output file;
26010 therefore, it is only useful if you compile @emph{all} of a program with
26011 this option.  In particular, you need to compile @file{libgcc.a}, the
26012 library that comes with GCC, with @option{-msoft-float} in order for
26013 this to work.
26015 @item -mhard-quad-float
26016 @opindex mhard-quad-float
26017 Generate output containing quad-word (long double) floating-point
26018 instructions.
26020 @item -msoft-quad-float
26021 @opindex msoft-quad-float
26022 Generate output containing library calls for quad-word (long double)
26023 floating-point instructions.  The functions called are those specified
26024 in the SPARC ABI@.  This is the default.
26026 As of this writing, there are no SPARC implementations that have hardware
26027 support for the quad-word floating-point instructions.  They all invoke
26028 a trap handler for one of these instructions, and then the trap handler
26029 emulates the effect of the instruction.  Because of the trap handler overhead,
26030 this is much slower than calling the ABI library routines.  Thus the
26031 @option{-msoft-quad-float} option is the default.
26033 @item -mno-unaligned-doubles
26034 @itemx -munaligned-doubles
26035 @opindex mno-unaligned-doubles
26036 @opindex munaligned-doubles
26037 Assume that doubles have 8-byte alignment.  This is the default.
26039 With @option{-munaligned-doubles}, GCC assumes that doubles have 8-byte
26040 alignment only if they are contained in another type, or if they have an
26041 absolute address.  Otherwise, it assumes they have 4-byte alignment.
26042 Specifying this option avoids some rare compatibility problems with code
26043 generated by other compilers.  It is not the default because it results
26044 in a performance loss, especially for floating-point code.
26046 @item -muser-mode
26047 @itemx -mno-user-mode
26048 @opindex muser-mode
26049 @opindex mno-user-mode
26050 Do not generate code that can only run in supervisor mode.  This is relevant
26051 only for the @code{casa} instruction emitted for the LEON3 processor.  This
26052 is the default.
26054 @item -mfaster-structs
26055 @itemx -mno-faster-structs
26056 @opindex mfaster-structs
26057 @opindex mno-faster-structs
26058 With @option{-mfaster-structs}, the compiler assumes that structures
26059 should have 8-byte alignment.  This enables the use of pairs of
26060 @code{ldd} and @code{std} instructions for copies in structure
26061 assignment, in place of twice as many @code{ld} and @code{st} pairs.
26062 However, the use of this changed alignment directly violates the SPARC
26063 ABI@.  Thus, it's intended only for use on targets where the developer
26064 acknowledges that their resulting code is not directly in line with
26065 the rules of the ABI@.
26067 @item -mstd-struct-return
26068 @itemx -mno-std-struct-return
26069 @opindex mstd-struct-return
26070 @opindex mno-std-struct-return
26071 With @option{-mstd-struct-return}, the compiler generates checking code
26072 in functions returning structures or unions to detect size mismatches
26073 between the two sides of function calls, as per the 32-bit ABI@.
26075 The default is @option{-mno-std-struct-return}.  This option has no effect
26076 in 64-bit mode.
26078 @item -mlra
26079 @itemx -mno-lra
26080 @opindex mlra
26081 @opindex mno-lra
26082 Enable Local Register Allocation.  This is the default for SPARC since GCC 7
26083 so @option{-mno-lra} needs to be passed to get old Reload.
26085 @item -mcpu=@var{cpu_type}
26086 @opindex mcpu
26087 Set the instruction set, register set, and instruction scheduling parameters
26088 for machine type @var{cpu_type}.  Supported values for @var{cpu_type} are
26089 @samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{hypersparc},
26090 @samp{leon}, @samp{leon3}, @samp{leon3v7}, @samp{sparclite}, @samp{f930},
26091 @samp{f934}, @samp{sparclite86x}, @samp{sparclet}, @samp{tsc701}, @samp{v9},
26092 @samp{ultrasparc}, @samp{ultrasparc3}, @samp{niagara}, @samp{niagara2},
26093 @samp{niagara3}, @samp{niagara4}, @samp{niagara7} and @samp{m8}.
26095 Native Solaris and GNU/Linux toolchains also support the value @samp{native},
26096 which selects the best architecture option for the host processor.
26097 @option{-mcpu=native} has no effect if GCC does not recognize
26098 the processor.
26100 Default instruction scheduling parameters are used for values that select
26101 an architecture and not an implementation.  These are @samp{v7}, @samp{v8},
26102 @samp{sparclite}, @samp{sparclet}, @samp{v9}.
26104 Here is a list of each supported architecture and their supported
26105 implementations.
26107 @table @asis
26108 @item v7
26109 cypress, leon3v7
26111 @item v8
26112 supersparc, hypersparc, leon, leon3
26114 @item sparclite
26115 f930, f934, sparclite86x
26117 @item sparclet
26118 tsc701
26120 @item v9
26121 ultrasparc, ultrasparc3, niagara, niagara2, niagara3, niagara4,
26122 niagara7, m8
26123 @end table
26125 By default (unless configured otherwise), GCC generates code for the V7
26126 variant of the SPARC architecture.  With @option{-mcpu=cypress}, the compiler
26127 additionally optimizes it for the Cypress CY7C602 chip, as used in the
26128 SPARCStation/SPARCServer 3xx series.  This is also appropriate for the older
26129 SPARCStation 1, 2, IPX etc.
26131 With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
26132 architecture.  The only difference from V7 code is that the compiler emits
26133 the integer multiply and integer divide instructions which exist in SPARC-V8
26134 but not in SPARC-V7.  With @option{-mcpu=supersparc}, the compiler additionally
26135 optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
26136 2000 series.
26138 With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
26139 the SPARC architecture.  This adds the integer multiply, integer divide step
26140 and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
26141 With @option{-mcpu=f930}, the compiler additionally optimizes it for the
26142 Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@.  With
26143 @option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
26144 MB86934 chip, which is the more recent SPARClite with FPU@.
26146 With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
26147 the SPARC architecture.  This adds the integer multiply, multiply/accumulate,
26148 integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
26149 but not in SPARC-V7.  With @option{-mcpu=tsc701}, the compiler additionally
26150 optimizes it for the TEMIC SPARClet chip.
26152 With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
26153 architecture.  This adds 64-bit integer and floating-point move instructions,
26154 3 additional floating-point condition code registers and conditional move
26155 instructions.  With @option{-mcpu=ultrasparc}, the compiler additionally
26156 optimizes it for the Sun UltraSPARC I/II/IIi chips.  With
26157 @option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
26158 Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips.  With
26159 @option{-mcpu=niagara}, the compiler additionally optimizes it for
26160 Sun UltraSPARC T1 chips.  With @option{-mcpu=niagara2}, the compiler
26161 additionally optimizes it for Sun UltraSPARC T2 chips. With
26162 @option{-mcpu=niagara3}, the compiler additionally optimizes it for Sun
26163 UltraSPARC T3 chips.  With @option{-mcpu=niagara4}, the compiler
26164 additionally optimizes it for Sun UltraSPARC T4 chips.  With
26165 @option{-mcpu=niagara7}, the compiler additionally optimizes it for
26166 Oracle SPARC M7 chips.  With @option{-mcpu=m8}, the compiler
26167 additionally optimizes it for Oracle M8 chips.
26169 @item -mtune=@var{cpu_type}
26170 @opindex mtune
26171 Set the instruction scheduling parameters for machine type
26172 @var{cpu_type}, but do not set the instruction set or register set that the
26173 option @option{-mcpu=@var{cpu_type}} does.
26175 The same values for @option{-mcpu=@var{cpu_type}} can be used for
26176 @option{-mtune=@var{cpu_type}}, but the only useful values are those
26177 that select a particular CPU implementation.  Those are
26178 @samp{cypress}, @samp{supersparc}, @samp{hypersparc}, @samp{leon},
26179 @samp{leon3}, @samp{leon3v7}, @samp{f930}, @samp{f934},
26180 @samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc},
26181 @samp{ultrasparc3}, @samp{niagara}, @samp{niagara2}, @samp{niagara3},
26182 @samp{niagara4}, @samp{niagara7} and @samp{m8}.  With native Solaris
26183 and GNU/Linux toolchains, @samp{native} can also be used.
26185 @item -mv8plus
26186 @itemx -mno-v8plus
26187 @opindex mv8plus
26188 @opindex mno-v8plus
26189 With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@.  The
26190 difference from the V8 ABI is that the global and out registers are
26191 considered 64 bits wide.  This is enabled by default on Solaris in 32-bit
26192 mode for all SPARC-V9 processors.
26194 @item -mvis
26195 @itemx -mno-vis
26196 @opindex mvis
26197 @opindex mno-vis
26198 With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
26199 Visual Instruction Set extensions.  The default is @option{-mno-vis}.
26201 @item -mvis2
26202 @itemx -mno-vis2
26203 @opindex mvis2
26204 @opindex mno-vis2
26205 With @option{-mvis2}, GCC generates code that takes advantage of
26206 version 2.0 of the UltraSPARC Visual Instruction Set extensions.  The
26207 default is @option{-mvis2} when targeting a cpu that supports such
26208 instructions, such as UltraSPARC-III and later.  Setting @option{-mvis2}
26209 also sets @option{-mvis}.
26211 @item -mvis3
26212 @itemx -mno-vis3
26213 @opindex mvis3
26214 @opindex mno-vis3
26215 With @option{-mvis3}, GCC generates code that takes advantage of
26216 version 3.0 of the UltraSPARC Visual Instruction Set extensions.  The
26217 default is @option{-mvis3} when targeting a cpu that supports such
26218 instructions, such as niagara-3 and later.  Setting @option{-mvis3}
26219 also sets @option{-mvis2} and @option{-mvis}.
26221 @item -mvis4
26222 @itemx -mno-vis4
26223 @opindex mvis4
26224 @opindex mno-vis4
26225 With @option{-mvis4}, GCC generates code that takes advantage of
26226 version 4.0 of the UltraSPARC Visual Instruction Set extensions.  The
26227 default is @option{-mvis4} when targeting a cpu that supports such
26228 instructions, such as niagara-7 and later.  Setting @option{-mvis4}
26229 also sets @option{-mvis3}, @option{-mvis2} and @option{-mvis}.
26231 @item -mvis4b
26232 @itemx -mno-vis4b
26233 @opindex mvis4b
26234 @opindex mno-vis4b
26235 With @option{-mvis4b}, GCC generates code that takes advantage of
26236 version 4.0 of the UltraSPARC Visual Instruction Set extensions, plus
26237 the additional VIS instructions introduced in the Oracle SPARC
26238 Architecture 2017.  The default is @option{-mvis4b} when targeting a
26239 cpu that supports such instructions, such as m8 and later.  Setting
26240 @option{-mvis4b} also sets @option{-mvis4}, @option{-mvis3},
26241 @option{-mvis2} and @option{-mvis}.
26243 @item -mcbcond
26244 @itemx -mno-cbcond
26245 @opindex mcbcond
26246 @opindex mno-cbcond
26247 With @option{-mcbcond}, GCC generates code that takes advantage of the UltraSPARC
26248 Compare-and-Branch-on-Condition instructions.  The default is @option{-mcbcond}
26249 when targeting a CPU that supports such instructions, such as Niagara-4 and
26250 later.
26252 @item -mfmaf
26253 @itemx -mno-fmaf
26254 @opindex mfmaf
26255 @opindex mno-fmaf
26256 With @option{-mfmaf}, GCC generates code that takes advantage of the UltraSPARC
26257 Fused Multiply-Add Floating-point instructions.  The default is @option{-mfmaf}
26258 when targeting a CPU that supports such instructions, such as Niagara-3 and
26259 later.
26261 @item -mfsmuld
26262 @itemx -mno-fsmuld
26263 @opindex mfsmuld
26264 @opindex mno-fsmuld
26265 With @option{-mfsmuld}, GCC generates code that takes advantage of the
26266 Floating-point Multiply Single to Double (FsMULd) instruction.  The default is
26267 @option{-mfsmuld} when targeting a CPU supporting the architecture versions V8
26268 or V9 with FPU except @option{-mcpu=leon}.
26270 @item -mpopc
26271 @itemx -mno-popc
26272 @opindex mpopc
26273 @opindex mno-popc
26274 With @option{-mpopc}, GCC generates code that takes advantage of the UltraSPARC
26275 Population Count instruction.  The default is @option{-mpopc}
26276 when targeting a CPU that supports such an instruction, such as Niagara-2 and
26277 later.
26279 @item -msubxc
26280 @itemx -mno-subxc
26281 @opindex msubxc
26282 @opindex mno-subxc
26283 With @option{-msubxc}, GCC generates code that takes advantage of the UltraSPARC
26284 Subtract-Extended-with-Carry instruction.  The default is @option{-msubxc}
26285 when targeting a CPU that supports such an instruction, such as Niagara-7 and
26286 later.
26288 @item -mfix-at697f
26289 @opindex mfix-at697f
26290 Enable the documented workaround for the single erratum of the Atmel AT697F
26291 processor (which corresponds to erratum #13 of the AT697E processor).
26293 @item -mfix-ut699
26294 @opindex mfix-ut699
26295 Enable the documented workarounds for the floating-point errata and the data
26296 cache nullify errata of the UT699 processor.
26298 @item -mfix-ut700
26299 @opindex mfix-ut700
26300 Enable the documented workaround for the back-to-back store errata of
26301 the UT699E/UT700 processor.
26303 @item -mfix-gr712rc
26304 @opindex mfix-gr712rc
26305 Enable the documented workaround for the back-to-back store errata of
26306 the GR712RC processor.
26307 @end table
26309 These @samp{-m} options are supported in addition to the above
26310 on SPARC-V9 processors in 64-bit environments:
26312 @table @gcctabopt
26313 @item -m32
26314 @itemx -m64
26315 @opindex m32
26316 @opindex m64
26317 Generate code for a 32-bit or 64-bit environment.
26318 The 32-bit environment sets int, long and pointer to 32 bits.
26319 The 64-bit environment sets int to 32 bits and long and pointer
26320 to 64 bits.
26322 @item -mcmodel=@var{which}
26323 @opindex mcmodel
26324 Set the code model to one of
26326 @table @samp
26327 @item medlow
26328 The Medium/Low code model: 64-bit addresses, programs
26329 must be linked in the low 32 bits of memory.  Programs can be statically
26330 or dynamically linked.
26332 @item medmid
26333 The Medium/Middle code model: 64-bit addresses, programs
26334 must be linked in the low 44 bits of memory, the text and data segments must
26335 be less than 2GB in size and the data segment must be located within 2GB of
26336 the text segment.
26338 @item medany
26339 The Medium/Anywhere code model: 64-bit addresses, programs
26340 may be linked anywhere in memory, the text and data segments must be less
26341 than 2GB in size and the data segment must be located within 2GB of the
26342 text segment.
26344 @item embmedany
26345 The Medium/Anywhere code model for embedded systems:
26346 64-bit addresses, the text and data segments must be less than 2GB in
26347 size, both starting anywhere in memory (determined at link time).  The
26348 global register %g4 points to the base of the data segment.  Programs
26349 are statically linked and PIC is not supported.
26350 @end table
26352 @item -mmemory-model=@var{mem-model}
26353 @opindex mmemory-model
26354 Set the memory model in force on the processor to one of
26356 @table @samp
26357 @item default
26358 The default memory model for the processor and operating system.
26360 @item rmo
26361 Relaxed Memory Order
26363 @item pso
26364 Partial Store Order
26366 @item tso
26367 Total Store Order
26369 @item sc
26370 Sequential Consistency
26371 @end table
26373 These memory models are formally defined in Appendix D of the SPARC-V9
26374 architecture manual, as set in the processor's @code{PSTATE.MM} field.
26376 @item -mstack-bias
26377 @itemx -mno-stack-bias
26378 @opindex mstack-bias
26379 @opindex mno-stack-bias
26380 With @option{-mstack-bias}, GCC assumes that the stack pointer, and
26381 frame pointer if present, are offset by @minus{}2047 which must be added back
26382 when making stack frame references.  This is the default in 64-bit mode.
26383 Otherwise, assume no such offset is present.
26384 @end table
26386 @node SPU Options
26387 @subsection SPU Options
26388 @cindex SPU options
26390 These @samp{-m} options are supported on the SPU:
26392 @table @gcctabopt
26393 @item -mwarn-reloc
26394 @itemx -merror-reloc
26395 @opindex mwarn-reloc
26396 @opindex merror-reloc
26398 The loader for SPU does not handle dynamic relocations.  By default, GCC
26399 gives an error when it generates code that requires a dynamic
26400 relocation.  @option{-mno-error-reloc} disables the error,
26401 @option{-mwarn-reloc} generates a warning instead.
26403 @item -msafe-dma
26404 @itemx -munsafe-dma
26405 @opindex msafe-dma
26406 @opindex munsafe-dma
26408 Instructions that initiate or test completion of DMA must not be
26409 reordered with respect to loads and stores of the memory that is being
26410 accessed.
26411 With @option{-munsafe-dma} you must use the @code{volatile} keyword to protect
26412 memory accesses, but that can lead to inefficient code in places where the
26413 memory is known to not change.  Rather than mark the memory as volatile,
26414 you can use @option{-msafe-dma} to tell the compiler to treat
26415 the DMA instructions as potentially affecting all memory.  
26417 @item -mbranch-hints
26418 @opindex mbranch-hints
26420 By default, GCC generates a branch hint instruction to avoid
26421 pipeline stalls for always-taken or probably-taken branches.  A hint
26422 is not generated closer than 8 instructions away from its branch.
26423 There is little reason to disable them, except for debugging purposes,
26424 or to make an object a little bit smaller.
26426 @item -msmall-mem
26427 @itemx -mlarge-mem
26428 @opindex msmall-mem
26429 @opindex mlarge-mem
26431 By default, GCC generates code assuming that addresses are never larger
26432 than 18 bits.  With @option{-mlarge-mem} code is generated that assumes
26433 a full 32-bit address.
26435 @item -mstdmain
26436 @opindex mstdmain
26438 By default, GCC links against startup code that assumes the SPU-style
26439 main function interface (which has an unconventional parameter list).
26440 With @option{-mstdmain}, GCC links your program against startup
26441 code that assumes a C99-style interface to @code{main}, including a
26442 local copy of @code{argv} strings.
26444 @item -mfixed-range=@var{register-range}
26445 @opindex mfixed-range
26446 Generate code treating the given register range as fixed registers.
26447 A fixed register is one that the register allocator cannot use.  This is
26448 useful when compiling kernel code.  A register range is specified as
26449 two registers separated by a dash.  Multiple register ranges can be
26450 specified separated by a comma.
26452 @item -mea32
26453 @itemx -mea64
26454 @opindex mea32
26455 @opindex mea64
26456 Compile code assuming that pointers to the PPU address space accessed
26457 via the @code{__ea} named address space qualifier are either 32 or 64
26458 bits wide.  The default is 32 bits.  As this is an ABI-changing option,
26459 all object code in an executable must be compiled with the same setting.
26461 @item -maddress-space-conversion
26462 @itemx -mno-address-space-conversion
26463 @opindex maddress-space-conversion
26464 @opindex mno-address-space-conversion
26465 Allow/disallow treating the @code{__ea} address space as superset
26466 of the generic address space.  This enables explicit type casts
26467 between @code{__ea} and generic pointer as well as implicit
26468 conversions of generic pointers to @code{__ea} pointers.  The
26469 default is to allow address space pointer conversions.
26471 @item -mcache-size=@var{cache-size}
26472 @opindex mcache-size
26473 This option controls the version of libgcc that the compiler links to an
26474 executable and selects a software-managed cache for accessing variables
26475 in the @code{__ea} address space with a particular cache size.  Possible
26476 options for @var{cache-size} are @samp{8}, @samp{16}, @samp{32}, @samp{64}
26477 and @samp{128}.  The default cache size is 64KB.
26479 @item -matomic-updates
26480 @itemx -mno-atomic-updates
26481 @opindex matomic-updates
26482 @opindex mno-atomic-updates
26483 This option controls the version of libgcc that the compiler links to an
26484 executable and selects whether atomic updates to the software-managed
26485 cache of PPU-side variables are used.  If you use atomic updates, changes
26486 to a PPU variable from SPU code using the @code{__ea} named address space
26487 qualifier do not interfere with changes to other PPU variables residing
26488 in the same cache line from PPU code.  If you do not use atomic updates,
26489 such interference may occur; however, writing back cache lines is
26490 more efficient.  The default behavior is to use atomic updates.
26492 @item -mdual-nops
26493 @itemx -mdual-nops=@var{n}
26494 @opindex mdual-nops
26495 By default, GCC inserts NOPs to increase dual issue when it expects
26496 it to increase performance.  @var{n} can be a value from 0 to 10.  A
26497 smaller @var{n} inserts fewer NOPs.  10 is the default, 0 is the
26498 same as @option{-mno-dual-nops}.  Disabled with @option{-Os}.
26500 @item -mhint-max-nops=@var{n}
26501 @opindex mhint-max-nops
26502 Maximum number of NOPs to insert for a branch hint.  A branch hint must
26503 be at least 8 instructions away from the branch it is affecting.  GCC
26504 inserts up to @var{n} NOPs to enforce this, otherwise it does not
26505 generate the branch hint.
26507 @item -mhint-max-distance=@var{n}
26508 @opindex mhint-max-distance
26509 The encoding of the branch hint instruction limits the hint to be within
26510 256 instructions of the branch it is affecting.  By default, GCC makes
26511 sure it is within 125.
26513 @item -msafe-hints
26514 @opindex msafe-hints
26515 Work around a hardware bug that causes the SPU to stall indefinitely.
26516 By default, GCC inserts the @code{hbrp} instruction to make sure
26517 this stall won't happen.
26519 @end table
26521 @node System V Options
26522 @subsection Options for System V
26524 These additional options are available on System V Release 4 for
26525 compatibility with other compilers on those systems:
26527 @table @gcctabopt
26528 @item -G
26529 @opindex G
26530 Create a shared object.
26531 It is recommended that @option{-symbolic} or @option{-shared} be used instead.
26533 @item -Qy
26534 @opindex Qy
26535 Identify the versions of each tool used by the compiler, in a
26536 @code{.ident} assembler directive in the output.
26538 @item -Qn
26539 @opindex Qn
26540 Refrain from adding @code{.ident} directives to the output file (this is
26541 the default).
26543 @item -YP,@var{dirs}
26544 @opindex YP
26545 Search the directories @var{dirs}, and no others, for libraries
26546 specified with @option{-l}.
26548 @item -Ym,@var{dir}
26549 @opindex Ym
26550 Look in the directory @var{dir} to find the M4 preprocessor.
26551 The assembler uses this option.
26552 @c This is supposed to go with a -Yd for predefined M4 macro files, but
26553 @c the generic assembler that comes with Solaris takes just -Ym.
26554 @end table
26556 @node TILE-Gx Options
26557 @subsection TILE-Gx Options
26558 @cindex TILE-Gx options
26560 These @samp{-m} options are supported on the TILE-Gx:
26562 @table @gcctabopt
26563 @item -mcmodel=small
26564 @opindex mcmodel=small
26565 Generate code for the small model.  The distance for direct calls is
26566 limited to 500M in either direction.  PC-relative addresses are 32
26567 bits.  Absolute addresses support the full address range.
26569 @item -mcmodel=large
26570 @opindex mcmodel=large
26571 Generate code for the large model.  There is no limitation on call
26572 distance, pc-relative addresses, or absolute addresses.
26574 @item -mcpu=@var{name}
26575 @opindex mcpu
26576 Selects the type of CPU to be targeted.  Currently the only supported
26577 type is @samp{tilegx}.
26579 @item -m32
26580 @itemx -m64
26581 @opindex m32
26582 @opindex m64
26583 Generate code for a 32-bit or 64-bit environment.  The 32-bit
26584 environment sets int, long, and pointer to 32 bits.  The 64-bit
26585 environment sets int to 32 bits and long and pointer to 64 bits.
26587 @item -mbig-endian
26588 @itemx -mlittle-endian
26589 @opindex mbig-endian
26590 @opindex mlittle-endian
26591 Generate code in big/little endian mode, respectively.
26592 @end table
26594 @node TILEPro Options
26595 @subsection TILEPro Options
26596 @cindex TILEPro options
26598 These @samp{-m} options are supported on the TILEPro:
26600 @table @gcctabopt
26601 @item -mcpu=@var{name}
26602 @opindex mcpu
26603 Selects the type of CPU to be targeted.  Currently the only supported
26604 type is @samp{tilepro}.
26606 @item -m32
26607 @opindex m32
26608 Generate code for a 32-bit environment, which sets int, long, and
26609 pointer to 32 bits.  This is the only supported behavior so the flag
26610 is essentially ignored.
26611 @end table
26613 @node V850 Options
26614 @subsection V850 Options
26615 @cindex V850 Options
26617 These @samp{-m} options are defined for V850 implementations:
26619 @table @gcctabopt
26620 @item -mlong-calls
26621 @itemx -mno-long-calls
26622 @opindex mlong-calls
26623 @opindex mno-long-calls
26624 Treat all calls as being far away (near).  If calls are assumed to be
26625 far away, the compiler always loads the function's address into a
26626 register, and calls indirect through the pointer.
26628 @item -mno-ep
26629 @itemx -mep
26630 @opindex mno-ep
26631 @opindex mep
26632 Do not optimize (do optimize) basic blocks that use the same index
26633 pointer 4 or more times to copy pointer into the @code{ep} register, and
26634 use the shorter @code{sld} and @code{sst} instructions.  The @option{-mep}
26635 option is on by default if you optimize.
26637 @item -mno-prolog-function
26638 @itemx -mprolog-function
26639 @opindex mno-prolog-function
26640 @opindex mprolog-function
26641 Do not use (do use) external functions to save and restore registers
26642 at the prologue and epilogue of a function.  The external functions
26643 are slower, but use less code space if more than one function saves
26644 the same number of registers.  The @option{-mprolog-function} option
26645 is on by default if you optimize.
26647 @item -mspace
26648 @opindex mspace
26649 Try to make the code as small as possible.  At present, this just turns
26650 on the @option{-mep} and @option{-mprolog-function} options.
26652 @item -mtda=@var{n}
26653 @opindex mtda
26654 Put static or global variables whose size is @var{n} bytes or less into
26655 the tiny data area that register @code{ep} points to.  The tiny data
26656 area can hold up to 256 bytes in total (128 bytes for byte references).
26658 @item -msda=@var{n}
26659 @opindex msda
26660 Put static or global variables whose size is @var{n} bytes or less into
26661 the small data area that register @code{gp} points to.  The small data
26662 area can hold up to 64 kilobytes.
26664 @item -mzda=@var{n}
26665 @opindex mzda
26666 Put static or global variables whose size is @var{n} bytes or less into
26667 the first 32 kilobytes of memory.
26669 @item -mv850
26670 @opindex mv850
26671 Specify that the target processor is the V850.
26673 @item -mv850e3v5
26674 @opindex mv850e3v5
26675 Specify that the target processor is the V850E3V5.  The preprocessor
26676 constant @code{__v850e3v5__} is defined if this option is used.
26678 @item -mv850e2v4
26679 @opindex mv850e2v4
26680 Specify that the target processor is the V850E3V5.  This is an alias for
26681 the @option{-mv850e3v5} option.
26683 @item -mv850e2v3
26684 @opindex mv850e2v3
26685 Specify that the target processor is the V850E2V3.  The preprocessor
26686 constant @code{__v850e2v3__} is defined if this option is used.
26688 @item -mv850e2
26689 @opindex mv850e2
26690 Specify that the target processor is the V850E2.  The preprocessor
26691 constant @code{__v850e2__} is defined if this option is used.
26693 @item -mv850e1
26694 @opindex mv850e1
26695 Specify that the target processor is the V850E1.  The preprocessor
26696 constants @code{__v850e1__} and @code{__v850e__} are defined if
26697 this option is used.
26699 @item -mv850es
26700 @opindex mv850es
26701 Specify that the target processor is the V850ES.  This is an alias for
26702 the @option{-mv850e1} option.
26704 @item -mv850e
26705 @opindex mv850e
26706 Specify that the target processor is the V850E@.  The preprocessor
26707 constant @code{__v850e__} is defined if this option is used.
26709 If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
26710 nor @option{-mv850e2} nor @option{-mv850e2v3} nor @option{-mv850e3v5}
26711 are defined then a default target processor is chosen and the
26712 relevant @samp{__v850*__} preprocessor constant is defined.
26714 The preprocessor constants @code{__v850} and @code{__v851__} are always
26715 defined, regardless of which processor variant is the target.
26717 @item -mdisable-callt
26718 @itemx -mno-disable-callt
26719 @opindex mdisable-callt
26720 @opindex mno-disable-callt
26721 This option suppresses generation of the @code{CALLT} instruction for the
26722 v850e, v850e1, v850e2, v850e2v3 and v850e3v5 flavors of the v850
26723 architecture.
26725 This option is enabled by default when the RH850 ABI is
26726 in use (see @option{-mrh850-abi}), and disabled by default when the
26727 GCC ABI is in use.  If @code{CALLT} instructions are being generated
26728 then the C preprocessor symbol @code{__V850_CALLT__} is defined.
26730 @item -mrelax
26731 @itemx -mno-relax
26732 @opindex mrelax
26733 @opindex mno-relax
26734 Pass on (or do not pass on) the @option{-mrelax} command-line option
26735 to the assembler.
26737 @item -mlong-jumps
26738 @itemx -mno-long-jumps
26739 @opindex mlong-jumps
26740 @opindex mno-long-jumps
26741 Disable (or re-enable) the generation of PC-relative jump instructions.
26743 @item -msoft-float
26744 @itemx -mhard-float
26745 @opindex msoft-float
26746 @opindex mhard-float
26747 Disable (or re-enable) the generation of hardware floating point
26748 instructions.  This option is only significant when the target
26749 architecture is @samp{V850E2V3} or higher.  If hardware floating point
26750 instructions are being generated then the C preprocessor symbol
26751 @code{__FPU_OK__} is defined, otherwise the symbol
26752 @code{__NO_FPU__} is defined.
26754 @item -mloop
26755 @opindex mloop
26756 Enables the use of the e3v5 LOOP instruction.  The use of this
26757 instruction is not enabled by default when the e3v5 architecture is
26758 selected because its use is still experimental.
26760 @item -mrh850-abi
26761 @itemx -mghs
26762 @opindex mrh850-abi
26763 @opindex mghs
26764 Enables support for the RH850 version of the V850 ABI.  This is the
26765 default.  With this version of the ABI the following rules apply:
26767 @itemize
26768 @item
26769 Integer sized structures and unions are returned via a memory pointer
26770 rather than a register.
26772 @item
26773 Large structures and unions (more than 8 bytes in size) are passed by
26774 value.
26776 @item
26777 Functions are aligned to 16-bit boundaries.
26779 @item
26780 The @option{-m8byte-align} command-line option is supported.
26782 @item
26783 The @option{-mdisable-callt} command-line option is enabled by
26784 default.  The @option{-mno-disable-callt} command-line option is not
26785 supported.
26786 @end itemize
26788 When this version of the ABI is enabled the C preprocessor symbol
26789 @code{__V850_RH850_ABI__} is defined.
26791 @item -mgcc-abi
26792 @opindex mgcc-abi
26793 Enables support for the old GCC version of the V850 ABI.  With this
26794 version of the ABI the following rules apply:
26796 @itemize
26797 @item
26798 Integer sized structures and unions are returned in register @code{r10}.
26800 @item
26801 Large structures and unions (more than 8 bytes in size) are passed by
26802 reference.
26804 @item
26805 Functions are aligned to 32-bit boundaries, unless optimizing for
26806 size.
26808 @item
26809 The @option{-m8byte-align} command-line option is not supported.
26811 @item
26812 The @option{-mdisable-callt} command-line option is supported but not
26813 enabled by default.
26814 @end itemize
26816 When this version of the ABI is enabled the C preprocessor symbol
26817 @code{__V850_GCC_ABI__} is defined.
26819 @item -m8byte-align
26820 @itemx -mno-8byte-align
26821 @opindex m8byte-align
26822 @opindex mno-8byte-align
26823 Enables support for @code{double} and @code{long long} types to be
26824 aligned on 8-byte boundaries.  The default is to restrict the
26825 alignment of all objects to at most 4-bytes.  When
26826 @option{-m8byte-align} is in effect the C preprocessor symbol
26827 @code{__V850_8BYTE_ALIGN__} is defined.
26829 @item -mbig-switch
26830 @opindex mbig-switch
26831 Generate code suitable for big switch tables.  Use this option only if
26832 the assembler/linker complain about out of range branches within a switch
26833 table.
26835 @item -mapp-regs
26836 @opindex mapp-regs
26837 This option causes r2 and r5 to be used in the code generated by
26838 the compiler.  This setting is the default.
26840 @item -mno-app-regs
26841 @opindex mno-app-regs
26842 This option causes r2 and r5 to be treated as fixed registers.
26844 @end table
26846 @node VAX Options
26847 @subsection VAX Options
26848 @cindex VAX options
26850 These @samp{-m} options are defined for the VAX:
26852 @table @gcctabopt
26853 @item -munix
26854 @opindex munix
26855 Do not output certain jump instructions (@code{aobleq} and so on)
26856 that the Unix assembler for the VAX cannot handle across long
26857 ranges.
26859 @item -mgnu
26860 @opindex mgnu
26861 Do output those jump instructions, on the assumption that the
26862 GNU assembler is being used.
26864 @item -mg
26865 @opindex mg
26866 Output code for G-format floating-point numbers instead of D-format.
26867 @end table
26869 @node Visium Options
26870 @subsection Visium Options
26871 @cindex Visium options
26873 @table @gcctabopt
26875 @item -mdebug
26876 @opindex mdebug
26877 A program which performs file I/O and is destined to run on an MCM target
26878 should be linked with this option.  It causes the libraries libc.a and
26879 libdebug.a to be linked.  The program should be run on the target under
26880 the control of the GDB remote debugging stub.
26882 @item -msim
26883 @opindex msim
26884 A program which performs file I/O and is destined to run on the simulator
26885 should be linked with option.  This causes libraries libc.a and libsim.a to
26886 be linked.
26888 @item -mfpu
26889 @itemx -mhard-float
26890 @opindex mfpu
26891 @opindex mhard-float
26892 Generate code containing floating-point instructions.  This is the
26893 default.
26895 @item -mno-fpu
26896 @itemx -msoft-float
26897 @opindex mno-fpu
26898 @opindex msoft-float
26899 Generate code containing library calls for floating-point.
26901 @option{-msoft-float} changes the calling convention in the output file;
26902 therefore, it is only useful if you compile @emph{all} of a program with
26903 this option.  In particular, you need to compile @file{libgcc.a}, the
26904 library that comes with GCC, with @option{-msoft-float} in order for
26905 this to work.
26907 @item -mcpu=@var{cpu_type}
26908 @opindex mcpu
26909 Set the instruction set, register set, and instruction scheduling parameters
26910 for machine type @var{cpu_type}.  Supported values for @var{cpu_type} are
26911 @samp{mcm}, @samp{gr5} and @samp{gr6}.
26913 @samp{mcm} is a synonym of @samp{gr5} present for backward compatibility.
26915 By default (unless configured otherwise), GCC generates code for the GR5
26916 variant of the Visium architecture.  
26918 With @option{-mcpu=gr6}, GCC generates code for the GR6 variant of the Visium
26919 architecture.  The only difference from GR5 code is that the compiler will
26920 generate block move instructions.
26922 @item -mtune=@var{cpu_type}
26923 @opindex mtune
26924 Set the instruction scheduling parameters for machine type @var{cpu_type},
26925 but do not set the instruction set or register set that the option
26926 @option{-mcpu=@var{cpu_type}} would.
26928 @item -msv-mode
26929 @opindex msv-mode
26930 Generate code for the supervisor mode, where there are no restrictions on
26931 the access to general registers.  This is the default.
26933 @item -muser-mode
26934 @opindex muser-mode
26935 Generate code for the user mode, where the access to some general registers
26936 is forbidden: on the GR5, registers r24 to r31 cannot be accessed in this
26937 mode; on the GR6, only registers r29 to r31 are affected.
26938 @end table
26940 @node VMS Options
26941 @subsection VMS Options
26943 These @samp{-m} options are defined for the VMS implementations:
26945 @table @gcctabopt
26946 @item -mvms-return-codes
26947 @opindex mvms-return-codes
26948 Return VMS condition codes from @code{main}. The default is to return POSIX-style
26949 condition (e.g.@ error) codes.
26951 @item -mdebug-main=@var{prefix}
26952 @opindex mdebug-main=@var{prefix}
26953 Flag the first routine whose name starts with @var{prefix} as the main
26954 routine for the debugger.
26956 @item -mmalloc64
26957 @opindex mmalloc64
26958 Default to 64-bit memory allocation routines.
26960 @item -mpointer-size=@var{size}
26961 @opindex mpointer-size=@var{size}
26962 Set the default size of pointers. Possible options for @var{size} are
26963 @samp{32} or @samp{short} for 32 bit pointers, @samp{64} or @samp{long}
26964 for 64 bit pointers, and @samp{no} for supporting only 32 bit pointers.
26965 The later option disables @code{pragma pointer_size}.
26966 @end table
26968 @node VxWorks Options
26969 @subsection VxWorks Options
26970 @cindex VxWorks Options
26972 The options in this section are defined for all VxWorks targets.
26973 Options specific to the target hardware are listed with the other
26974 options for that target.
26976 @table @gcctabopt
26977 @item -mrtp
26978 @opindex mrtp
26979 GCC can generate code for both VxWorks kernels and real time processes
26980 (RTPs).  This option switches from the former to the latter.  It also
26981 defines the preprocessor macro @code{__RTP__}.
26983 @item -non-static
26984 @opindex non-static
26985 Link an RTP executable against shared libraries rather than static
26986 libraries.  The options @option{-static} and @option{-shared} can
26987 also be used for RTPs (@pxref{Link Options}); @option{-static}
26988 is the default.
26990 @item -Bstatic
26991 @itemx -Bdynamic
26992 @opindex Bstatic
26993 @opindex Bdynamic
26994 These options are passed down to the linker.  They are defined for
26995 compatibility with Diab.
26997 @item -Xbind-lazy
26998 @opindex Xbind-lazy
26999 Enable lazy binding of function calls.  This option is equivalent to
27000 @option{-Wl,-z,now} and is defined for compatibility with Diab.
27002 @item -Xbind-now
27003 @opindex Xbind-now
27004 Disable lazy binding of function calls.  This option is the default and
27005 is defined for compatibility with Diab.
27006 @end table
27008 @node x86 Options
27009 @subsection x86 Options
27010 @cindex x86 Options
27012 These @samp{-m} options are defined for the x86 family of computers.
27014 @table @gcctabopt
27016 @item -march=@var{cpu-type}
27017 @opindex march
27018 Generate instructions for the machine type @var{cpu-type}.  In contrast to
27019 @option{-mtune=@var{cpu-type}}, which merely tunes the generated code 
27020 for the specified @var{cpu-type}, @option{-march=@var{cpu-type}} allows GCC
27021 to generate code that may not run at all on processors other than the one
27022 indicated.  Specifying @option{-march=@var{cpu-type}} implies 
27023 @option{-mtune=@var{cpu-type}}.
27025 The choices for @var{cpu-type} are:
27027 @table @samp
27028 @item native
27029 This selects the CPU to generate code for at compilation time by determining
27030 the processor type of the compiling machine.  Using @option{-march=native}
27031 enables all instruction subsets supported by the local machine (hence
27032 the result might not run on different machines).  Using @option{-mtune=native}
27033 produces code optimized for the local machine under the constraints
27034 of the selected instruction set.  
27036 @item x86-64
27037 A generic CPU with 64-bit extensions.
27039 @item i386
27040 Original Intel i386 CPU@.
27042 @item i486
27043 Intel i486 CPU@.  (No scheduling is implemented for this chip.)
27045 @item i586
27046 @itemx pentium
27047 Intel Pentium CPU with no MMX support.
27049 @item lakemont
27050 Intel Lakemont MCU, based on Intel Pentium CPU.
27052 @item pentium-mmx
27053 Intel Pentium MMX CPU, based on Pentium core with MMX instruction set support.
27055 @item pentiumpro
27056 Intel Pentium Pro CPU@.
27058 @item i686
27059 When used with @option{-march}, the Pentium Pro
27060 instruction set is used, so the code runs on all i686 family chips.
27061 When used with @option{-mtune}, it has the same meaning as @samp{generic}.
27063 @item pentium2
27064 Intel Pentium II CPU, based on Pentium Pro core with MMX instruction set
27065 support.
27067 @item pentium3
27068 @itemx pentium3m
27069 Intel Pentium III CPU, based on Pentium Pro core with MMX and SSE instruction
27070 set support.
27072 @item pentium-m
27073 Intel Pentium M; low-power version of Intel Pentium III CPU
27074 with MMX, SSE and SSE2 instruction set support.  Used by Centrino notebooks.
27076 @item pentium4
27077 @itemx pentium4m
27078 Intel Pentium 4 CPU with MMX, SSE and SSE2 instruction set support.
27080 @item prescott
27081 Improved version of Intel Pentium 4 CPU with MMX, SSE, SSE2 and SSE3 instruction
27082 set support.
27084 @item nocona
27085 Improved version of Intel Pentium 4 CPU with 64-bit extensions, MMX, SSE,
27086 SSE2 and SSE3 instruction set support.
27088 @item core2
27089 Intel Core 2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3
27090 instruction set support.
27092 @item nehalem
27093 Intel Nehalem CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3,
27094 SSE4.1, SSE4.2 and POPCNT instruction set support.
27096 @item westmere
27097 Intel Westmere CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3,
27098 SSE4.1, SSE4.2, POPCNT, AES and PCLMUL instruction set support.
27100 @item sandybridge
27101 Intel Sandy Bridge CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3,
27102 SSE4.1, SSE4.2, POPCNT, AVX, AES and PCLMUL instruction set support.
27104 @item ivybridge
27105 Intel Ivy Bridge CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3, SSSE3,
27106 SSE4.1, SSE4.2, POPCNT, AVX, AES, PCLMUL, FSGSBASE, RDRND and F16C
27107 instruction set support.
27109 @item haswell
27110 Intel Haswell CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,
27111 SSE4.1, SSE4.2, POPCNT, AVX, AVX2, AES, PCLMUL, FSGSBASE, RDRND, FMA,
27112 BMI, BMI2 and F16C instruction set support.
27114 @item broadwell
27115 Intel Broadwell CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,
27116 SSE4.1, SSE4.2, POPCNT, AVX, AVX2, AES, PCLMUL, FSGSBASE, RDRND, FMA,
27117 BMI, BMI2, F16C, RDSEED, ADCX and PREFETCHW instruction set support.
27119 @item skylake
27120 Intel Skylake CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,
27121 SSE4.1, SSE4.2, POPCNT, AVX, AVX2, AES, PCLMUL, FSGSBASE, RDRND, FMA,
27122 BMI, BMI2, F16C, RDSEED, ADCX, PREFETCHW, CLFLUSHOPT, XSAVEC and
27123 XSAVES instruction set support.
27125 @item bonnell
27126 Intel Bonnell CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3 and SSSE3
27127 instruction set support.
27129 @item silvermont
27130 Intel Silvermont CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,
27131 SSE4.1, SSE4.2, POPCNT, AES, PCLMUL and RDRND instruction set support.
27133 @item goldmont
27134 Intel Goldmont CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,
27135 SSE4.1, SSE4.2, POPCNT, AES, PCLMUL, RDRND, XSAVE, XSAVEOPT and FSGSBASE
27136 instruction set support.
27138 @item goldmont-plus
27139 Intel Goldmont Plus CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3,
27140 SSSE3, SSE4.1, SSE4.2, POPCNT, AES, PCLMUL, RDRND, XSAVE, XSAVEOPT, FSGSBASE,
27141 PTWRITE, RDPID, SGX and UMIP instruction set support.
27143 @item tremont
27144 Intel Tremont CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3, SSSE3,
27145 SSE4.1, SSE4.2, POPCNT, AES, PCLMUL, RDRND, XSAVE, XSAVEOPT, FSGSBASE, PTWRITE,
27146 RDPID, SGX, UMIP, GFNI-SSE, CLWB and ENCLV instruction set support.
27148 @item knl
27149 Intel Knight's Landing CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3,
27150 SSSE3, SSE4.1, SSE4.2, POPCNT, AVX, AVX2, AES, PCLMUL, FSGSBASE, RDRND, FMA,
27151 BMI, BMI2, F16C, RDSEED, ADCX, PREFETCHW, AVX512F, AVX512PF, AVX512ER and
27152 AVX512CD instruction set support.
27154 @item knm
27155 Intel Knights Mill CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3,
27156 SSSE3, SSE4.1, SSE4.2, POPCNT, AVX, AVX2, AES, PCLMUL, FSGSBASE, RDRND, FMA,
27157 BMI, BMI2, F16C, RDSEED, ADCX, PREFETCHW, AVX512F, AVX512PF, AVX512ER, AVX512CD,
27158 AVX5124VNNIW, AVX5124FMAPS and AVX512VPOPCNTDQ instruction set support.
27160 @item skylake-avx512
27161 Intel Skylake Server CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2, SSE3,
27162 SSSE3, SSE4.1, SSE4.2, POPCNT, PKU, AVX, AVX2, AES, PCLMUL, FSGSBASE, RDRND, FMA,
27163 BMI, BMI2, F16C, RDSEED, ADCX, PREFETCHW, CLFLUSHOPT, XSAVEC, XSAVES, AVX512F,
27164 CLWB, AVX512VL, AVX512BW, AVX512DQ and AVX512CD instruction set support.
27166 @item cannonlake
27167 Intel Cannonlake Server CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2,
27168 SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, PKU, AVX, AVX2, AES, PCLMUL, FSGSBASE,
27169 RDRND, FMA, BMI, BMI2, F16C, RDSEED, ADCX, PREFETCHW, CLFLUSHOPT, XSAVEC,
27170 XSAVES, AVX512F, AVX512VL, AVX512BW, AVX512DQ, AVX512CD, AVX512VBMI,
27171 AVX512IFMA, SHA and UMIP instruction set support.
27173 @item icelake-client
27174 Intel Icelake Client CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2,
27175 SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, PKU, AVX, AVX2, AES, PCLMUL, FSGSBASE,
27176 RDRND, FMA, BMI, BMI2, F16C, RDSEED, ADCX, PREFETCHW, CLFLUSHOPT, XSAVEC,
27177 XSAVES, AVX512F, AVX512VL, AVX512BW, AVX512DQ, AVX512CD, AVX512VBMI,
27178 AVX512IFMA, SHA, CLWB, UMIP, RDPID, GFNI, AVX512VBMI2, AVX512VPOPCNTDQ,
27179 AVX512BITALG, AVX512VNNI, VPCLMULQDQ, VAES instruction set support.
27181 @item icelake-server
27182 Intel Icelake Server CPU with 64-bit extensions, MOVBE, MMX, SSE, SSE2,
27183 SSE3, SSSE3, SSE4.1, SSE4.2, POPCNT, PKU, AVX, AVX2, AES, PCLMUL, FSGSBASE,
27184 RDRND, FMA, BMI, BMI2, F16C, RDSEED, ADCX, PREFETCHW, CLFLUSHOPT, XSAVEC,
27185 XSAVES, AVX512F, AVX512VL, AVX512BW, AVX512DQ, AVX512CD, AVX512VBMI,
27186 AVX512IFMA, SHA, CLWB, UMIP, RDPID, GFNI, AVX512VBMI2, AVX512VPOPCNTDQ,
27187 AVX512BITALG, AVX512VNNI, VPCLMULQDQ, VAES, PCONFIG and WBNOINVD instruction
27188 set support.
27190 @item k6
27191 AMD K6 CPU with MMX instruction set support.
27193 @item k6-2
27194 @itemx k6-3
27195 Improved versions of AMD K6 CPU with MMX and 3DNow!@: instruction set support.
27197 @item athlon
27198 @itemx athlon-tbird
27199 AMD Athlon CPU with MMX, 3dNOW!, enhanced 3DNow!@: and SSE prefetch instructions
27200 support.
27202 @item athlon-4
27203 @itemx athlon-xp
27204 @itemx athlon-mp
27205 Improved AMD Athlon CPU with MMX, 3DNow!, enhanced 3DNow!@: and full SSE
27206 instruction set support.
27208 @item k8
27209 @itemx opteron
27210 @itemx athlon64
27211 @itemx athlon-fx
27212 Processors based on the AMD K8 core with x86-64 instruction set support,
27213 including the AMD Opteron, Athlon 64, and Athlon 64 FX processors.
27214 (This supersets MMX, SSE, SSE2, 3DNow!, enhanced 3DNow!@: and 64-bit
27215 instruction set extensions.)
27217 @item k8-sse3
27218 @itemx opteron-sse3
27219 @itemx athlon64-sse3
27220 Improved versions of AMD K8 cores with SSE3 instruction set support.
27222 @item amdfam10
27223 @itemx barcelona
27224 CPUs based on AMD Family 10h cores with x86-64 instruction set support.  (This
27225 supersets MMX, SSE, SSE2, SSE3, SSE4A, 3DNow!, enhanced 3DNow!, ABM and 64-bit
27226 instruction set extensions.)
27228 @item bdver1
27229 CPUs based on AMD Family 15h cores with x86-64 instruction set support.  (This
27230 supersets FMA4, AVX, XOP, LWP, AES, PCL_MUL, CX16, MMX, SSE, SSE2, SSE3, SSE4A,
27231 SSSE3, SSE4.1, SSE4.2, ABM and 64-bit instruction set extensions.)
27232 @item bdver2
27233 AMD Family 15h core based CPUs with x86-64 instruction set support.  (This
27234 supersets BMI, TBM, F16C, FMA, FMA4, AVX, XOP, LWP, AES, PCL_MUL, CX16, MMX,
27235 SSE, SSE2, SSE3, SSE4A, SSSE3, SSE4.1, SSE4.2, ABM and 64-bit instruction set 
27236 extensions.)
27237 @item bdver3
27238 AMD Family 15h core based CPUs with x86-64 instruction set support.  (This
27239 supersets BMI, TBM, F16C, FMA, FMA4, FSGSBASE, AVX, XOP, LWP, AES, 
27240 PCL_MUL, CX16, MMX, SSE, SSE2, SSE3, SSE4A, SSSE3, SSE4.1, SSE4.2, ABM and 
27241 64-bit instruction set extensions.
27242 @item bdver4
27243 AMD Family 15h core based CPUs with x86-64 instruction set support.  (This
27244 supersets BMI, BMI2, TBM, F16C, FMA, FMA4, FSGSBASE, AVX, AVX2, XOP, LWP, 
27245 AES, PCL_MUL, CX16, MOVBE, MMX, SSE, SSE2, SSE3, SSE4A, SSSE3, SSE4.1, 
27246 SSE4.2, ABM and 64-bit instruction set extensions.
27248 @item znver1
27249 AMD Family 17h core based CPUs with x86-64 instruction set support.  (This
27250 supersets BMI, BMI2, F16C, FMA, FSGSBASE, AVX, AVX2, ADCX, RDSEED, MWAITX,
27251 SHA, CLZERO, AES, PCL_MUL, CX16, MOVBE, MMX, SSE, SSE2, SSE3, SSE4A, SSSE3,
27252 SSE4.1, SSE4.2, ABM, XSAVEC, XSAVES, CLFLUSHOPT, POPCNT, and 64-bit
27253 instruction set extensions.
27255 @item btver1
27256 CPUs based on AMD Family 14h cores with x86-64 instruction set support.  (This
27257 supersets MMX, SSE, SSE2, SSE3, SSSE3, SSE4A, CX16, ABM and 64-bit
27258 instruction set extensions.)
27260 @item btver2
27261 CPUs based on AMD Family 16h cores with x86-64 instruction set support. This
27262 includes MOVBE, F16C, BMI, AVX, PCL_MUL, AES, SSE4.2, SSE4.1, CX16, ABM,
27263 SSE4A, SSSE3, SSE3, SSE2, SSE, MMX and 64-bit instruction set extensions.
27265 @item winchip-c6
27266 IDT WinChip C6 CPU, dealt in same way as i486 with additional MMX instruction
27267 set support.
27269 @item winchip2
27270 IDT WinChip 2 CPU, dealt in same way as i486 with additional MMX and 3DNow!@:
27271 instruction set support.
27273 @item c3
27274 VIA C3 CPU with MMX and 3DNow!@: instruction set support.
27275 (No scheduling is implemented for this chip.)
27277 @item c3-2
27278 VIA C3-2 (Nehemiah/C5XL) CPU with MMX and SSE instruction set support.
27279 (No scheduling is implemented for this chip.)
27281 @item c7
27282 VIA C7 (Esther) CPU with MMX, SSE, SSE2 and SSE3 instruction set support.
27283 (No scheduling is implemented for this chip.)
27285 @item samuel-2
27286 VIA Eden Samuel 2 CPU with MMX and 3DNow!@: instruction set support.
27287 (No scheduling is implemented for this chip.)
27289 @item nehemiah
27290 VIA Eden Nehemiah CPU with MMX and SSE instruction set support.
27291 (No scheduling is implemented for this chip.)
27293 @item esther
27294 VIA Eden Esther CPU with MMX, SSE, SSE2 and SSE3 instruction set support.
27295 (No scheduling is implemented for this chip.)
27297 @item eden-x2
27298 VIA Eden X2 CPU with x86-64, MMX, SSE, SSE2 and SSE3 instruction set support.
27299 (No scheduling is implemented for this chip.)
27301 @item eden-x4
27302 VIA Eden X4 CPU with x86-64, MMX, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2,
27303 AVX and AVX2 instruction set support.
27304 (No scheduling is implemented for this chip.)
27306 @item nano
27307 Generic VIA Nano CPU with x86-64, MMX, SSE, SSE2, SSE3 and SSSE3
27308 instruction set support.
27309 (No scheduling is implemented for this chip.)
27311 @item nano-1000
27312 VIA Nano 1xxx CPU with x86-64, MMX, SSE, SSE2, SSE3 and SSSE3
27313 instruction set support.
27314 (No scheduling is implemented for this chip.)
27316 @item nano-2000
27317 VIA Nano 2xxx CPU with x86-64, MMX, SSE, SSE2, SSE3 and SSSE3
27318 instruction set support.
27319 (No scheduling is implemented for this chip.)
27321 @item nano-3000
27322 VIA Nano 3xxx CPU with x86-64, MMX, SSE, SSE2, SSE3, SSSE3 and SSE4.1
27323 instruction set support.
27324 (No scheduling is implemented for this chip.)
27326 @item nano-x2
27327 VIA Nano Dual Core CPU with x86-64, MMX, SSE, SSE2, SSE3, SSSE3 and SSE4.1
27328 instruction set support.
27329 (No scheduling is implemented for this chip.)
27331 @item nano-x4
27332 VIA Nano Quad Core CPU with x86-64, MMX, SSE, SSE2, SSE3, SSSE3 and SSE4.1
27333 instruction set support.
27334 (No scheduling is implemented for this chip.)
27336 @item geode
27337 AMD Geode embedded processor with MMX and 3DNow!@: instruction set support.
27338 @end table
27340 @item -mtune=@var{cpu-type}
27341 @opindex mtune
27342 Tune to @var{cpu-type} everything applicable about the generated code, except
27343 for the ABI and the set of available instructions.  
27344 While picking a specific @var{cpu-type} schedules things appropriately
27345 for that particular chip, the compiler does not generate any code that
27346 cannot run on the default machine type unless you use a
27347 @option{-march=@var{cpu-type}} option.
27348 For example, if GCC is configured for i686-pc-linux-gnu
27349 then @option{-mtune=pentium4} generates code that is tuned for Pentium 4
27350 but still runs on i686 machines.
27352 The choices for @var{cpu-type} are the same as for @option{-march}.
27353 In addition, @option{-mtune} supports 2 extra choices for @var{cpu-type}:
27355 @table @samp
27356 @item generic
27357 Produce code optimized for the most common IA32/@/AMD64/@/EM64T processors.
27358 If you know the CPU on which your code will run, then you should use
27359 the corresponding @option{-mtune} or @option{-march} option instead of
27360 @option{-mtune=generic}.  But, if you do not know exactly what CPU users
27361 of your application will have, then you should use this option.
27363 As new processors are deployed in the marketplace, the behavior of this
27364 option will change.  Therefore, if you upgrade to a newer version of
27365 GCC, code generation controlled by this option will change to reflect
27366 the processors
27367 that are most common at the time that version of GCC is released.
27369 There is no @option{-march=generic} option because @option{-march}
27370 indicates the instruction set the compiler can use, and there is no
27371 generic instruction set applicable to all processors.  In contrast,
27372 @option{-mtune} indicates the processor (or, in this case, collection of
27373 processors) for which the code is optimized.
27375 @item intel
27376 Produce code optimized for the most current Intel processors, which are
27377 Haswell and Silvermont for this version of GCC.  If you know the CPU
27378 on which your code will run, then you should use the corresponding
27379 @option{-mtune} or @option{-march} option instead of @option{-mtune=intel}.
27380 But, if you want your application performs better on both Haswell and
27381 Silvermont, then you should use this option.
27383 As new Intel processors are deployed in the marketplace, the behavior of
27384 this option will change.  Therefore, if you upgrade to a newer version of
27385 GCC, code generation controlled by this option will change to reflect
27386 the most current Intel processors at the time that version of GCC is
27387 released.
27389 There is no @option{-march=intel} option because @option{-march} indicates
27390 the instruction set the compiler can use, and there is no common
27391 instruction set applicable to all processors.  In contrast,
27392 @option{-mtune} indicates the processor (or, in this case, collection of
27393 processors) for which the code is optimized.
27394 @end table
27396 @item -mcpu=@var{cpu-type}
27397 @opindex mcpu
27398 A deprecated synonym for @option{-mtune}.
27400 @item -mfpmath=@var{unit}
27401 @opindex mfpmath
27402 Generate floating-point arithmetic for selected unit @var{unit}.  The choices
27403 for @var{unit} are:
27405 @table @samp
27406 @item 387
27407 Use the standard 387 floating-point coprocessor present on the majority of chips and
27408 emulated otherwise.  Code compiled with this option runs almost everywhere.
27409 The temporary results are computed in 80-bit precision instead of the precision
27410 specified by the type, resulting in slightly different results compared to most
27411 of other chips.  See @option{-ffloat-store} for more detailed description.
27413 This is the default choice for non-Darwin x86-32 targets.
27415 @item sse
27416 Use scalar floating-point instructions present in the SSE instruction set.
27417 This instruction set is supported by Pentium III and newer chips,
27418 and in the AMD line
27419 by Athlon-4, Athlon XP and Athlon MP chips.  The earlier version of the SSE
27420 instruction set supports only single-precision arithmetic, thus the double and
27421 extended-precision arithmetic are still done using 387.  A later version, present
27422 only in Pentium 4 and AMD x86-64 chips, supports double-precision
27423 arithmetic too.
27425 For the x86-32 compiler, you must use @option{-march=@var{cpu-type}}, @option{-msse}
27426 or @option{-msse2} switches to enable SSE extensions and make this option
27427 effective.  For the x86-64 compiler, these extensions are enabled by default.
27429 The resulting code should be considerably faster in the majority of cases and avoid
27430 the numerical instability problems of 387 code, but may break some existing
27431 code that expects temporaries to be 80 bits.
27433 This is the default choice for the x86-64 compiler, Darwin x86-32 targets,
27434 and the default choice for x86-32 targets with the SSE2 instruction set
27435 when @option{-ffast-math} is enabled.
27437 @item sse,387
27438 @itemx sse+387
27439 @itemx both
27440 Attempt to utilize both instruction sets at once.  This effectively doubles the
27441 amount of available registers, and on chips with separate execution units for
27442 387 and SSE the execution resources too.  Use this option with care, as it is
27443 still experimental, because the GCC register allocator does not model separate
27444 functional units well, resulting in unstable performance.
27445 @end table
27447 @item -masm=@var{dialect}
27448 @opindex masm=@var{dialect}
27449 Output assembly instructions using selected @var{dialect}.  Also affects
27450 which dialect is used for basic @code{asm} (@pxref{Basic Asm}) and
27451 extended @code{asm} (@pxref{Extended Asm}). Supported choices (in dialect
27452 order) are @samp{att} or @samp{intel}. The default is @samp{att}. Darwin does
27453 not support @samp{intel}.
27455 @item -mieee-fp
27456 @itemx -mno-ieee-fp
27457 @opindex mieee-fp
27458 @opindex mno-ieee-fp
27459 Control whether or not the compiler uses IEEE floating-point
27460 comparisons.  These correctly handle the case where the result of a
27461 comparison is unordered.
27463 @item -m80387
27464 @itemx -mhard-float
27465 @opindex 80387
27466 @opindex mhard-float
27467 Generate output containing 80387 instructions for floating point.
27469 @item -mno-80387
27470 @itemx -msoft-float
27471 @opindex no-80387
27472 @opindex msoft-float
27473 Generate output containing library calls for floating point.
27475 @strong{Warning:} the requisite libraries are not part of GCC@.
27476 Normally the facilities of the machine's usual C compiler are used, but
27477 this cannot be done directly in cross-compilation.  You must make your
27478 own arrangements to provide suitable library functions for
27479 cross-compilation.
27481 On machines where a function returns floating-point results in the 80387
27482 register stack, some floating-point opcodes may be emitted even if
27483 @option{-msoft-float} is used.
27485 @item -mno-fp-ret-in-387
27486 @opindex mno-fp-ret-in-387
27487 Do not use the FPU registers for return values of functions.
27489 The usual calling convention has functions return values of types
27490 @code{float} and @code{double} in an FPU register, even if there
27491 is no FPU@.  The idea is that the operating system should emulate
27492 an FPU@.
27494 The option @option{-mno-fp-ret-in-387} causes such values to be returned
27495 in ordinary CPU registers instead.
27497 @item -mno-fancy-math-387
27498 @opindex mno-fancy-math-387
27499 Some 387 emulators do not support the @code{sin}, @code{cos} and
27500 @code{sqrt} instructions for the 387.  Specify this option to avoid
27501 generating those instructions.
27502 This option is overridden when @option{-march}
27503 indicates that the target CPU always has an FPU and so the
27504 instruction does not need emulation.  These
27505 instructions are not generated unless you also use the
27506 @option{-funsafe-math-optimizations} switch.
27508 @item -malign-double
27509 @itemx -mno-align-double
27510 @opindex malign-double
27511 @opindex mno-align-double
27512 Control whether GCC aligns @code{double}, @code{long double}, and
27513 @code{long long} variables on a two-word boundary or a one-word
27514 boundary.  Aligning @code{double} variables on a two-word boundary
27515 produces code that runs somewhat faster on a Pentium at the
27516 expense of more memory.
27518 On x86-64, @option{-malign-double} is enabled by default.
27520 @strong{Warning:} if you use the @option{-malign-double} switch,
27521 structures containing the above types are aligned differently than
27522 the published application binary interface specifications for the x86-32
27523 and are not binary compatible with structures in code compiled
27524 without that switch.
27526 @item -m96bit-long-double
27527 @itemx -m128bit-long-double
27528 @opindex m96bit-long-double
27529 @opindex m128bit-long-double
27530 These switches control the size of @code{long double} type.  The x86-32
27531 application binary interface specifies the size to be 96 bits,
27532 so @option{-m96bit-long-double} is the default in 32-bit mode.
27534 Modern architectures (Pentium and newer) prefer @code{long double}
27535 to be aligned to an 8- or 16-byte boundary.  In arrays or structures
27536 conforming to the ABI, this is not possible.  So specifying
27537 @option{-m128bit-long-double} aligns @code{long double}
27538 to a 16-byte boundary by padding the @code{long double} with an additional
27539 32-bit zero.
27541 In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
27542 its ABI specifies that @code{long double} is aligned on 16-byte boundary.
27544 Notice that neither of these options enable any extra precision over the x87
27545 standard of 80 bits for a @code{long double}.
27547 @strong{Warning:} if you override the default value for your target ABI, this
27548 changes the size of 
27549 structures and arrays containing @code{long double} variables,
27550 as well as modifying the function calling convention for functions taking
27551 @code{long double}.  Hence they are not binary-compatible
27552 with code compiled without that switch.
27554 @item -mlong-double-64
27555 @itemx -mlong-double-80
27556 @itemx -mlong-double-128
27557 @opindex mlong-double-64
27558 @opindex mlong-double-80
27559 @opindex mlong-double-128
27560 These switches control the size of @code{long double} type. A size
27561 of 64 bits makes the @code{long double} type equivalent to the @code{double}
27562 type. This is the default for 32-bit Bionic C library.  A size
27563 of 128 bits makes the @code{long double} type equivalent to the
27564 @code{__float128} type. This is the default for 64-bit Bionic C library.
27566 @strong{Warning:} if you override the default value for your target ABI, this
27567 changes the size of
27568 structures and arrays containing @code{long double} variables,
27569 as well as modifying the function calling convention for functions taking
27570 @code{long double}.  Hence they are not binary-compatible
27571 with code compiled without that switch.
27573 @item -malign-data=@var{type}
27574 @opindex malign-data
27575 Control how GCC aligns variables.  Supported values for @var{type} are
27576 @samp{compat} uses increased alignment value compatible uses GCC 4.8
27577 and earlier, @samp{abi} uses alignment value as specified by the
27578 psABI, and @samp{cacheline} uses increased alignment value to match
27579 the cache line size.  @samp{compat} is the default.
27581 @item -mlarge-data-threshold=@var{threshold}
27582 @opindex mlarge-data-threshold
27583 When @option{-mcmodel=medium} is specified, data objects larger than
27584 @var{threshold} are placed in the large data section.  This value must be the
27585 same across all objects linked into the binary, and defaults to 65535.
27587 @item -mrtd
27588 @opindex mrtd
27589 Use a different function-calling convention, in which functions that
27590 take a fixed number of arguments return with the @code{ret @var{num}}
27591 instruction, which pops their arguments while returning.  This saves one
27592 instruction in the caller since there is no need to pop the arguments
27593 there.
27595 You can specify that an individual function is called with this calling
27596 sequence with the function attribute @code{stdcall}.  You can also
27597 override the @option{-mrtd} option by using the function attribute
27598 @code{cdecl}.  @xref{Function Attributes}.
27600 @strong{Warning:} this calling convention is incompatible with the one
27601 normally used on Unix, so you cannot use it if you need to call
27602 libraries compiled with the Unix compiler.
27604 Also, you must provide function prototypes for all functions that
27605 take variable numbers of arguments (including @code{printf});
27606 otherwise incorrect code is generated for calls to those
27607 functions.
27609 In addition, seriously incorrect code results if you call a
27610 function with too many arguments.  (Normally, extra arguments are
27611 harmlessly ignored.)
27613 @item -mregparm=@var{num}
27614 @opindex mregparm
27615 Control how many registers are used to pass integer arguments.  By
27616 default, no registers are used to pass arguments, and at most 3
27617 registers can be used.  You can control this behavior for a specific
27618 function by using the function attribute @code{regparm}.
27619 @xref{Function Attributes}.
27621 @strong{Warning:} if you use this switch, and
27622 @var{num} is nonzero, then you must build all modules with the same
27623 value, including any libraries.  This includes the system libraries and
27624 startup modules.
27626 @item -msseregparm
27627 @opindex msseregparm
27628 Use SSE register passing conventions for float and double arguments
27629 and return values.  You can control this behavior for a specific
27630 function by using the function attribute @code{sseregparm}.
27631 @xref{Function Attributes}.
27633 @strong{Warning:} if you use this switch then you must build all
27634 modules with the same value, including any libraries.  This includes
27635 the system libraries and startup modules.
27637 @item -mvect8-ret-in-mem
27638 @opindex mvect8-ret-in-mem
27639 Return 8-byte vectors in memory instead of MMX registers.  This is the
27640 default on Solaris@tie{}8 and 9 and VxWorks to match the ABI of the Sun
27641 Studio compilers until version 12.  Later compiler versions (starting
27642 with Studio 12 Update@tie{}1) follow the ABI used by other x86 targets, which
27643 is the default on Solaris@tie{}10 and later.  @emph{Only} use this option if
27644 you need to remain compatible with existing code produced by those
27645 previous compiler versions or older versions of GCC@.
27647 @item -mpc32
27648 @itemx -mpc64
27649 @itemx -mpc80
27650 @opindex mpc32
27651 @opindex mpc64
27652 @opindex mpc80
27654 Set 80387 floating-point precision to 32, 64 or 80 bits.  When @option{-mpc32}
27655 is specified, the significands of results of floating-point operations are
27656 rounded to 24 bits (single precision); @option{-mpc64} rounds the
27657 significands of results of floating-point operations to 53 bits (double
27658 precision) and @option{-mpc80} rounds the significands of results of
27659 floating-point operations to 64 bits (extended double precision), which is
27660 the default.  When this option is used, floating-point operations in higher
27661 precisions are not available to the programmer without setting the FPU
27662 control word explicitly.
27664 Setting the rounding of floating-point operations to less than the default
27665 80 bits can speed some programs by 2% or more.  Note that some mathematical
27666 libraries assume that extended-precision (80-bit) floating-point operations
27667 are enabled by default; routines in such libraries could suffer significant
27668 loss of accuracy, typically through so-called ``catastrophic cancellation'',
27669 when this option is used to set the precision to less than extended precision.
27671 @item -mstackrealign
27672 @opindex mstackrealign
27673 Realign the stack at entry.  On the x86, the @option{-mstackrealign}
27674 option generates an alternate prologue and epilogue that realigns the
27675 run-time stack if necessary.  This supports mixing legacy codes that keep
27676 4-byte stack alignment with modern codes that keep 16-byte stack alignment for
27677 SSE compatibility.  See also the attribute @code{force_align_arg_pointer},
27678 applicable to individual functions.
27680 @item -mpreferred-stack-boundary=@var{num}
27681 @opindex mpreferred-stack-boundary
27682 Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
27683 byte boundary.  If @option{-mpreferred-stack-boundary} is not specified,
27684 the default is 4 (16 bytes or 128 bits).
27686 @strong{Warning:} When generating code for the x86-64 architecture with
27687 SSE extensions disabled, @option{-mpreferred-stack-boundary=3} can be
27688 used to keep the stack boundary aligned to 8 byte boundary.  Since
27689 x86-64 ABI require 16 byte stack alignment, this is ABI incompatible and
27690 intended to be used in controlled environment where stack space is
27691 important limitation.  This option leads to wrong code when functions
27692 compiled with 16 byte stack alignment (such as functions from a standard
27693 library) are called with misaligned stack.  In this case, SSE
27694 instructions may lead to misaligned memory access traps.  In addition,
27695 variable arguments are handled incorrectly for 16 byte aligned
27696 objects (including x87 long double and __int128), leading to wrong
27697 results.  You must build all modules with
27698 @option{-mpreferred-stack-boundary=3}, including any libraries.  This
27699 includes the system libraries and startup modules.
27701 @item -mincoming-stack-boundary=@var{num}
27702 @opindex mincoming-stack-boundary
27703 Assume the incoming stack is aligned to a 2 raised to @var{num} byte
27704 boundary.  If @option{-mincoming-stack-boundary} is not specified,
27705 the one specified by @option{-mpreferred-stack-boundary} is used.
27707 On Pentium and Pentium Pro, @code{double} and @code{long double} values
27708 should be aligned to an 8-byte boundary (see @option{-malign-double}) or
27709 suffer significant run time performance penalties.  On Pentium III, the
27710 Streaming SIMD Extension (SSE) data type @code{__m128} may not work
27711 properly if it is not 16-byte aligned.
27713 To ensure proper alignment of this values on the stack, the stack boundary
27714 must be as aligned as that required by any value stored on the stack.
27715 Further, every function must be generated such that it keeps the stack
27716 aligned.  Thus calling a function compiled with a higher preferred
27717 stack boundary from a function compiled with a lower preferred stack
27718 boundary most likely misaligns the stack.  It is recommended that
27719 libraries that use callbacks always use the default setting.
27721 This extra alignment does consume extra stack space, and generally
27722 increases code size.  Code that is sensitive to stack space usage, such
27723 as embedded systems and operating system kernels, may want to reduce the
27724 preferred alignment to @option{-mpreferred-stack-boundary=2}.
27726 @need 200
27727 @item -mmmx
27728 @opindex mmmx
27729 @need 200
27730 @itemx -msse
27731 @opindex msse
27732 @need 200
27733 @itemx -msse2
27734 @opindex msse2
27735 @need 200
27736 @itemx -msse3
27737 @opindex msse3
27738 @need 200
27739 @itemx -mssse3
27740 @opindex mssse3
27741 @need 200
27742 @itemx -msse4
27743 @opindex msse4
27744 @need 200
27745 @itemx -msse4a
27746 @opindex msse4a
27747 @need 200
27748 @itemx -msse4.1
27749 @opindex msse4.1
27750 @need 200
27751 @itemx -msse4.2
27752 @opindex msse4.2
27753 @need 200
27754 @itemx -mavx
27755 @opindex mavx
27756 @need 200
27757 @itemx -mavx2
27758 @opindex mavx2
27759 @need 200
27760 @itemx -mavx512f
27761 @opindex mavx512f
27762 @need 200
27763 @itemx -mavx512pf
27764 @opindex mavx512pf
27765 @need 200
27766 @itemx -mavx512er
27767 @opindex mavx512er
27768 @need 200
27769 @itemx -mavx512cd
27770 @opindex mavx512cd
27771 @need 200
27772 @itemx -mavx512vl
27773 @opindex mavx512vl
27774 @need 200
27775 @itemx -mavx512bw
27776 @opindex mavx512bw
27777 @need 200
27778 @itemx -mavx512dq
27779 @opindex mavx512dq
27780 @need 200
27781 @itemx -mavx512ifma
27782 @opindex mavx512ifma
27783 @need 200
27784 @itemx -mavx512vbmi
27785 @opindex mavx512vbmi
27786 @need 200
27787 @itemx -msha
27788 @opindex msha
27789 @need 200
27790 @itemx -maes
27791 @opindex maes
27792 @need 200
27793 @itemx -mpclmul
27794 @opindex mpclmul
27795 @need 200
27796 @itemx -mclflushopt
27797 @opindex mclflushopt
27798 @need 200
27799 @itemx -mfsgsbase
27800 @opindex mfsgsbase
27801 @need 200
27802 @itemx -mrdrnd
27803 @opindex mrdrnd
27804 @need 200
27805 @itemx -mf16c
27806 @opindex mf16c
27807 @need 200
27808 @itemx -mfma
27809 @opindex mfma
27810 @need 200
27811 @itemx -mpconfig
27812 @opindex mpconfig
27813 @need 200
27814 @itemx -mwbnoinvd
27815 @opindex mwbnoinvd
27816 @need 200
27817 @itemx -mfma4
27818 @opindex mfma4
27819 @need 200
27820 @itemx -mprefetchwt1
27821 @opindex mprefetchwt1
27822 @need 200
27823 @itemx -mxop
27824 @opindex mxop
27825 @need 200
27826 @itemx -mlwp
27827 @opindex mlwp
27828 @need 200
27829 @itemx -m3dnow
27830 @opindex m3dnow
27831 @need 200
27832 @itemx -m3dnowa
27833 @opindex m3dnowa
27834 @need 200
27835 @itemx -mpopcnt
27836 @opindex mpopcnt
27837 @need 200
27838 @itemx -mabm
27839 @opindex mabm
27840 @need 200
27841 @itemx -mbmi
27842 @opindex mbmi
27843 @need 200
27844 @itemx -mbmi2
27845 @need 200
27846 @itemx -mlzcnt
27847 @opindex mlzcnt
27848 @need 200
27849 @itemx -mfxsr
27850 @opindex mfxsr
27851 @need 200
27852 @itemx -mxsave
27853 @opindex mxsave
27854 @need 200
27855 @itemx -mxsaveopt
27856 @opindex mxsaveopt
27857 @need 200
27858 @itemx -mxsavec
27859 @opindex mxsavec
27860 @need 200
27861 @itemx -mxsaves
27862 @opindex mxsaves
27863 @need 200
27864 @itemx -mrtm
27865 @opindex mrtm
27866 @need 200
27867 @itemx -mtbm
27868 @opindex mtbm
27869 @need 200
27870 @itemx -mmwaitx
27871 @opindex mmwaitx
27872 @need 200
27873 @itemx -mclzero
27874 @opindex mclzero
27875 @need 200
27876 @itemx -mpku
27877 @opindex mpku
27878 @need 200
27879 @itemx -mavx512vbmi2
27880 @opindex mavx512vbmi2
27881 @need 200
27882 @itemx -mgfni
27883 @opindex mgfni
27884 @need 200
27885 @itemx -mvaes
27886 @opindex mvaes
27887 @need 200
27888 @itemx -mwaitpkg
27889 @opindex -mwaitpkg
27890 @need 200
27891 @itemx -mvpclmulqdq
27892 @opindex mvpclmulqdq
27893 @need 200
27894 @itemx -mavx512bitalg
27895 @opindex mavx512bitalg
27896 @need 200
27897 @itemx -mmovdiri
27898 @opindex mmovdiri
27899 @need 200
27900 @itemx -mmovdir64b
27901 @opindex mmovdir64b
27902 @need 200
27903 @itemx -mavx512vpopcntdq
27904 @opindex mavx512vpopcntdq
27905 @need 200
27906 @itemx -mcldemote
27907 @opindex mcldemote
27908 These switches enable the use of instructions in the MMX, SSE,
27909 SSE2, SSE3, SSSE3, SSE4.1, AVX, AVX2, AVX512F, AVX512PF, AVX512ER, AVX512CD,
27910 SHA, AES, PCLMUL, FSGSBASE, RDRND, F16C, FMA, SSE4A, FMA4, XOP, LWP, ABM,
27911 AVX512VL, AVX512BW, AVX512DQ, AVX512IFMA, AVX512VBMI, BMI, BMI2, VAES, WAITPKG,
27912 FXSR, XSAVE, XSAVEOPT, LZCNT, RTM, MWAITX, PKU, IBT, SHSTK, AVX512VBMI2,
27913 GFNI, VPCLMULQDQ, AVX512BITALG, MOVDIRI, MOVDIR64B,
27914 AVX512VPOPCNTDQ, CLDEMOTE, 3DNow!@: or enhanced 3DNow!@: extended instruction
27915 sets. Each has a corresponding @option{-mno-} option to disable use of these
27916 instructions.
27918 These extensions are also available as built-in functions: see
27919 @ref{x86 Built-in Functions}, for details of the functions enabled and
27920 disabled by these switches.
27922 To generate SSE/SSE2 instructions automatically from floating-point
27923 code (as opposed to 387 instructions), see @option{-mfpmath=sse}.
27925 GCC depresses SSEx instructions when @option{-mavx} is used. Instead, it
27926 generates new AVX instructions or AVX equivalence for all SSEx instructions
27927 when needed.
27929 These options enable GCC to use these extended instructions in
27930 generated code, even without @option{-mfpmath=sse}.  Applications that
27931 perform run-time CPU detection must compile separate files for each
27932 supported architecture, using the appropriate flags.  In particular,
27933 the file containing the CPU detection code should be compiled without
27934 these options.
27936 @item -mdump-tune-features
27937 @opindex mdump-tune-features
27938 This option instructs GCC to dump the names of the x86 performance 
27939 tuning features and default settings. The names can be used in 
27940 @option{-mtune-ctrl=@var{feature-list}}.
27942 @item -mtune-ctrl=@var{feature-list}
27943 @opindex mtune-ctrl=@var{feature-list}
27944 This option is used to do fine grain control of x86 code generation features.
27945 @var{feature-list} is a comma separated list of @var{feature} names. See also
27946 @option{-mdump-tune-features}. When specified, the @var{feature} is turned
27947 on if it is not preceded with @samp{^}, otherwise, it is turned off. 
27948 @option{-mtune-ctrl=@var{feature-list}} is intended to be used by GCC
27949 developers. Using it may lead to code paths not covered by testing and can
27950 potentially result in compiler ICEs or runtime errors.
27952 @item -mno-default
27953 @opindex mno-default
27954 This option instructs GCC to turn off all tunable features. See also 
27955 @option{-mtune-ctrl=@var{feature-list}} and @option{-mdump-tune-features}.
27957 @item -mcld
27958 @opindex mcld
27959 This option instructs GCC to emit a @code{cld} instruction in the prologue
27960 of functions that use string instructions.  String instructions depend on
27961 the DF flag to select between autoincrement or autodecrement mode.  While the
27962 ABI specifies the DF flag to be cleared on function entry, some operating
27963 systems violate this specification by not clearing the DF flag in their
27964 exception dispatchers.  The exception handler can be invoked with the DF flag
27965 set, which leads to wrong direction mode when string instructions are used.
27966 This option can be enabled by default on 32-bit x86 targets by configuring
27967 GCC with the @option{--enable-cld} configure option.  Generation of @code{cld}
27968 instructions can be suppressed with the @option{-mno-cld} compiler option
27969 in this case.
27971 @item -mvzeroupper
27972 @opindex mvzeroupper
27973 This option instructs GCC to emit a @code{vzeroupper} instruction
27974 before a transfer of control flow out of the function to minimize
27975 the AVX to SSE transition penalty as well as remove unnecessary @code{zeroupper}
27976 intrinsics.
27978 @item -mprefer-avx128
27979 @opindex mprefer-avx128
27980 This option instructs GCC to use 128-bit AVX instructions instead of
27981 256-bit AVX instructions in the auto-vectorizer.
27983 @item -mprefer-vector-width=@var{opt}
27984 @opindex mprefer-vector-width
27985 This option instructs GCC to use @var{opt}-bit vector width in instructions
27986 instead of default on the selected platform.
27988 @table @samp
27989 @item none
27990 No extra limitations applied to GCC other than defined by the selected platform.
27992 @item 128
27993 Prefer 128-bit vector width for instructions.
27995 @item 256
27996 Prefer 256-bit vector width for instructions.
27998 @item 512
27999 Prefer 512-bit vector width for instructions.
28000 @end table
28002 @item -mcx16
28003 @opindex mcx16
28004 This option enables GCC to generate @code{CMPXCHG16B} instructions in 64-bit
28005 code to implement compare-and-exchange operations on 16-byte aligned 128-bit
28006 objects.  This is useful for atomic updates of data structures exceeding one
28007 machine word in size.  The compiler uses this instruction to implement
28008 @ref{__sync Builtins}.  However, for @ref{__atomic Builtins} operating on
28009 128-bit integers, a library call is always used.
28011 @item -msahf
28012 @opindex msahf
28013 This option enables generation of @code{SAHF} instructions in 64-bit code.
28014 Early Intel Pentium 4 CPUs with Intel 64 support,
28015 prior to the introduction of Pentium 4 G1 step in December 2005,
28016 lacked the @code{LAHF} and @code{SAHF} instructions
28017 which are supported by AMD64.
28018 These are load and store instructions, respectively, for certain status flags.
28019 In 64-bit mode, the @code{SAHF} instruction is used to optimize @code{fmod},
28020 @code{drem}, and @code{remainder} built-in functions;
28021 see @ref{Other Builtins} for details.
28023 @item -mmovbe
28024 @opindex mmovbe
28025 This option enables use of the @code{movbe} instruction to implement
28026 @code{__builtin_bswap32} and @code{__builtin_bswap64}.
28028 @item -mshstk
28029 @opindex mshstk
28030 The @option{-mshstk} option enables shadow stack built-in functions
28031 from x86 Control-flow Enforcement Technology (CET).
28033 @item -mcrc32
28034 @opindex mcrc32
28035 This option enables built-in functions @code{__builtin_ia32_crc32qi},
28036 @code{__builtin_ia32_crc32hi}, @code{__builtin_ia32_crc32si} and
28037 @code{__builtin_ia32_crc32di} to generate the @code{crc32} machine instruction.
28039 @item -mrecip
28040 @opindex mrecip
28041 This option enables use of @code{RCPSS} and @code{RSQRTSS} instructions
28042 (and their vectorized variants @code{RCPPS} and @code{RSQRTPS})
28043 with an additional Newton-Raphson step
28044 to increase precision instead of @code{DIVSS} and @code{SQRTSS}
28045 (and their vectorized
28046 variants) for single-precision floating-point arguments.  These instructions
28047 are generated only when @option{-funsafe-math-optimizations} is enabled
28048 together with @option{-ffinite-math-only} and @option{-fno-trapping-math}.
28049 Note that while the throughput of the sequence is higher than the throughput
28050 of the non-reciprocal instruction, the precision of the sequence can be
28051 decreased by up to 2 ulp (i.e. the inverse of 1.0 equals 0.99999994).
28053 Note that GCC implements @code{1.0f/sqrtf(@var{x})} in terms of @code{RSQRTSS}
28054 (or @code{RSQRTPS}) already with @option{-ffast-math} (or the above option
28055 combination), and doesn't need @option{-mrecip}.
28057 Also note that GCC emits the above sequence with additional Newton-Raphson step
28058 for vectorized single-float division and vectorized @code{sqrtf(@var{x})}
28059 already with @option{-ffast-math} (or the above option combination), and
28060 doesn't need @option{-mrecip}.
28062 @item -mrecip=@var{opt}
28063 @opindex mrecip=opt
28064 This option controls which reciprocal estimate instructions
28065 may be used.  @var{opt} is a comma-separated list of options, which may
28066 be preceded by a @samp{!} to invert the option:
28068 @table @samp
28069 @item all
28070 Enable all estimate instructions.
28072 @item default
28073 Enable the default instructions, equivalent to @option{-mrecip}.
28075 @item none
28076 Disable all estimate instructions, equivalent to @option{-mno-recip}.
28078 @item div
28079 Enable the approximation for scalar division.
28081 @item vec-div
28082 Enable the approximation for vectorized division.
28084 @item sqrt
28085 Enable the approximation for scalar square root.
28087 @item vec-sqrt
28088 Enable the approximation for vectorized square root.
28089 @end table
28091 So, for example, @option{-mrecip=all,!sqrt} enables
28092 all of the reciprocal approximations, except for square root.
28094 @item -mveclibabi=@var{type}
28095 @opindex mveclibabi
28096 Specifies the ABI type to use for vectorizing intrinsics using an
28097 external library.  Supported values for @var{type} are @samp{svml} 
28098 for the Intel short
28099 vector math library and @samp{acml} for the AMD math core library.
28100 To use this option, both @option{-ftree-vectorize} and
28101 @option{-funsafe-math-optimizations} have to be enabled, and an SVML or ACML 
28102 ABI-compatible library must be specified at link time.
28104 GCC currently emits calls to @code{vmldExp2},
28105 @code{vmldLn2}, @code{vmldLog102}, @code{vmldPow2},
28106 @code{vmldTanh2}, @code{vmldTan2}, @code{vmldAtan2}, @code{vmldAtanh2},
28107 @code{vmldCbrt2}, @code{vmldSinh2}, @code{vmldSin2}, @code{vmldAsinh2},
28108 @code{vmldAsin2}, @code{vmldCosh2}, @code{vmldCos2}, @code{vmldAcosh2},
28109 @code{vmldAcos2}, @code{vmlsExp4}, @code{vmlsLn4},
28110 @code{vmlsLog104}, @code{vmlsPow4}, @code{vmlsTanh4}, @code{vmlsTan4},
28111 @code{vmlsAtan4}, @code{vmlsAtanh4}, @code{vmlsCbrt4}, @code{vmlsSinh4},
28112 @code{vmlsSin4}, @code{vmlsAsinh4}, @code{vmlsAsin4}, @code{vmlsCosh4},
28113 @code{vmlsCos4}, @code{vmlsAcosh4} and @code{vmlsAcos4} for corresponding
28114 function type when @option{-mveclibabi=svml} is used, and @code{__vrd2_sin},
28115 @code{__vrd2_cos}, @code{__vrd2_exp}, @code{__vrd2_log}, @code{__vrd2_log2},
28116 @code{__vrd2_log10}, @code{__vrs4_sinf}, @code{__vrs4_cosf},
28117 @code{__vrs4_expf}, @code{__vrs4_logf}, @code{__vrs4_log2f},
28118 @code{__vrs4_log10f} and @code{__vrs4_powf} for the corresponding function type
28119 when @option{-mveclibabi=acml} is used.  
28121 @item -mabi=@var{name}
28122 @opindex mabi
28123 Generate code for the specified calling convention.  Permissible values
28124 are @samp{sysv} for the ABI used on GNU/Linux and other systems, and
28125 @samp{ms} for the Microsoft ABI.  The default is to use the Microsoft
28126 ABI when targeting Microsoft Windows and the SysV ABI on all other systems.
28127 You can control this behavior for specific functions by
28128 using the function attributes @code{ms_abi} and @code{sysv_abi}.
28129 @xref{Function Attributes}.
28131 @item -mforce-indirect-call
28132 @opindex mforce-indirect-call
28133 Force all calls to functions to be indirect. This is useful
28134 when using Intel Processor Trace where it generates more precise timing
28135 information for function calls.
28137 @item -mcall-ms2sysv-xlogues
28138 @opindex mcall-ms2sysv-xlogues
28139 @opindex mno-call-ms2sysv-xlogues
28140 Due to differences in 64-bit ABIs, any Microsoft ABI function that calls a
28141 System V ABI function must consider RSI, RDI and XMM6-15 as clobbered.  By
28142 default, the code for saving and restoring these registers is emitted inline,
28143 resulting in fairly lengthy prologues and epilogues.  Using
28144 @option{-mcall-ms2sysv-xlogues} emits prologues and epilogues that
28145 use stubs in the static portion of libgcc to perform these saves and restores,
28146 thus reducing function size at the cost of a few extra instructions.
28148 @item -mtls-dialect=@var{type}
28149 @opindex mtls-dialect
28150 Generate code to access thread-local storage using the @samp{gnu} or
28151 @samp{gnu2} conventions.  @samp{gnu} is the conservative default;
28152 @samp{gnu2} is more efficient, but it may add compile- and run-time
28153 requirements that cannot be satisfied on all systems.
28155 @item -mpush-args
28156 @itemx -mno-push-args
28157 @opindex mpush-args
28158 @opindex mno-push-args
28159 Use PUSH operations to store outgoing parameters.  This method is shorter
28160 and usually equally fast as method using SUB/MOV operations and is enabled
28161 by default.  In some cases disabling it may improve performance because of
28162 improved scheduling and reduced dependencies.
28164 @item -maccumulate-outgoing-args
28165 @opindex maccumulate-outgoing-args
28166 If enabled, the maximum amount of space required for outgoing arguments is
28167 computed in the function prologue.  This is faster on most modern CPUs
28168 because of reduced dependencies, improved scheduling and reduced stack usage
28169 when the preferred stack boundary is not equal to 2.  The drawback is a notable
28170 increase in code size.  This switch implies @option{-mno-push-args}.
28172 @item -mthreads
28173 @opindex mthreads
28174 Support thread-safe exception handling on MinGW.  Programs that rely
28175 on thread-safe exception handling must compile and link all code with the
28176 @option{-mthreads} option.  When compiling, @option{-mthreads} defines
28177 @option{-D_MT}; when linking, it links in a special thread helper library
28178 @option{-lmingwthrd} which cleans up per-thread exception-handling data.
28180 @item -mms-bitfields
28181 @itemx -mno-ms-bitfields
28182 @opindex mms-bitfields
28183 @opindex mno-ms-bitfields
28185 Enable/disable bit-field layout compatible with the native Microsoft
28186 Windows compiler.  
28188 If @code{packed} is used on a structure, or if bit-fields are used,
28189 it may be that the Microsoft ABI lays out the structure differently
28190 than the way GCC normally does.  Particularly when moving packed
28191 data between functions compiled with GCC and the native Microsoft compiler
28192 (either via function call or as data in a file), it may be necessary to access
28193 either format.
28195 This option is enabled by default for Microsoft Windows
28196 targets.  This behavior can also be controlled locally by use of variable
28197 or type attributes.  For more information, see @ref{x86 Variable Attributes}
28198 and @ref{x86 Type Attributes}.
28200 The Microsoft structure layout algorithm is fairly simple with the exception
28201 of the bit-field packing.  
28202 The padding and alignment of members of structures and whether a bit-field 
28203 can straddle a storage-unit boundary are determine by these rules:
28205 @enumerate
28206 @item Structure members are stored sequentially in the order in which they are
28207 declared: the first member has the lowest memory address and the last member
28208 the highest.
28210 @item Every data object has an alignment requirement.  The alignment requirement
28211 for all data except structures, unions, and arrays is either the size of the
28212 object or the current packing size (specified with either the
28213 @code{aligned} attribute or the @code{pack} pragma),
28214 whichever is less.  For structures, unions, and arrays,
28215 the alignment requirement is the largest alignment requirement of its members.
28216 Every object is allocated an offset so that:
28218 @smallexample
28219 offset % alignment_requirement == 0
28220 @end smallexample
28222 @item Adjacent bit-fields are packed into the same 1-, 2-, or 4-byte allocation
28223 unit if the integral types are the same size and if the next bit-field fits
28224 into the current allocation unit without crossing the boundary imposed by the
28225 common alignment requirements of the bit-fields.
28226 @end enumerate
28228 MSVC interprets zero-length bit-fields in the following ways:
28230 @enumerate
28231 @item If a zero-length bit-field is inserted between two bit-fields that
28232 are normally coalesced, the bit-fields are not coalesced.
28234 For example:
28236 @smallexample
28237 struct
28238  @{
28239    unsigned long bf_1 : 12;
28240    unsigned long : 0;
28241    unsigned long bf_2 : 12;
28242  @} t1;
28243 @end smallexample
28245 @noindent
28246 The size of @code{t1} is 8 bytes with the zero-length bit-field.  If the
28247 zero-length bit-field were removed, @code{t1}'s size would be 4 bytes.
28249 @item If a zero-length bit-field is inserted after a bit-field, @code{foo}, and the
28250 alignment of the zero-length bit-field is greater than the member that follows it,
28251 @code{bar}, @code{bar} is aligned as the type of the zero-length bit-field.
28253 For example:
28255 @smallexample
28256 struct
28257  @{
28258    char foo : 4;
28259    short : 0;
28260    char bar;
28261  @} t2;
28263 struct
28264  @{
28265    char foo : 4;
28266    short : 0;
28267    double bar;
28268  @} t3;
28269 @end smallexample
28271 @noindent
28272 For @code{t2}, @code{bar} is placed at offset 2, rather than offset 1.
28273 Accordingly, the size of @code{t2} is 4.  For @code{t3}, the zero-length
28274 bit-field does not affect the alignment of @code{bar} or, as a result, the size
28275 of the structure.
28277 Taking this into account, it is important to note the following:
28279 @enumerate
28280 @item If a zero-length bit-field follows a normal bit-field, the type of the
28281 zero-length bit-field may affect the alignment of the structure as whole. For
28282 example, @code{t2} has a size of 4 bytes, since the zero-length bit-field follows a
28283 normal bit-field, and is of type short.
28285 @item Even if a zero-length bit-field is not followed by a normal bit-field, it may
28286 still affect the alignment of the structure:
28288 @smallexample
28289 struct
28290  @{
28291    char foo : 6;
28292    long : 0;
28293  @} t4;
28294 @end smallexample
28296 @noindent
28297 Here, @code{t4} takes up 4 bytes.
28298 @end enumerate
28300 @item Zero-length bit-fields following non-bit-field members are ignored:
28302 @smallexample
28303 struct
28304  @{
28305    char foo;
28306    long : 0;
28307    char bar;
28308  @} t5;
28309 @end smallexample
28311 @noindent
28312 Here, @code{t5} takes up 2 bytes.
28313 @end enumerate
28316 @item -mno-align-stringops
28317 @opindex mno-align-stringops
28318 Do not align the destination of inlined string operations.  This switch reduces
28319 code size and improves performance in case the destination is already aligned,
28320 but GCC doesn't know about it.
28322 @item -minline-all-stringops
28323 @opindex minline-all-stringops
28324 By default GCC inlines string operations only when the destination is 
28325 known to be aligned to least a 4-byte boundary.  
28326 This enables more inlining and increases code
28327 size, but may improve performance of code that depends on fast
28328 @code{memcpy}, @code{strlen},
28329 and @code{memset} for short lengths.
28331 @item -minline-stringops-dynamically
28332 @opindex minline-stringops-dynamically
28333 For string operations of unknown size, use run-time checks with
28334 inline code for small blocks and a library call for large blocks.
28336 @item -mstringop-strategy=@var{alg}
28337 @opindex mstringop-strategy=@var{alg}
28338 Override the internal decision heuristic for the particular algorithm to use
28339 for inlining string operations.  The allowed values for @var{alg} are:
28341 @table @samp
28342 @item rep_byte
28343 @itemx rep_4byte
28344 @itemx rep_8byte
28345 Expand using i386 @code{rep} prefix of the specified size.
28347 @item byte_loop
28348 @itemx loop
28349 @itemx unrolled_loop
28350 Expand into an inline loop.
28352 @item libcall
28353 Always use a library call.
28354 @end table
28356 @item -mmemcpy-strategy=@var{strategy}
28357 @opindex mmemcpy-strategy=@var{strategy}
28358 Override the internal decision heuristic to decide if @code{__builtin_memcpy}
28359 should be inlined and what inline algorithm to use when the expected size
28360 of the copy operation is known. @var{strategy} 
28361 is a comma-separated list of @var{alg}:@var{max_size}:@var{dest_align} triplets. 
28362 @var{alg} is specified in @option{-mstringop-strategy}, @var{max_size} specifies
28363 the max byte size with which inline algorithm @var{alg} is allowed.  For the last
28364 triplet, the @var{max_size} must be @code{-1}. The @var{max_size} of the triplets
28365 in the list must be specified in increasing order.  The minimal byte size for 
28366 @var{alg} is @code{0} for the first triplet and @code{@var{max_size} + 1} of the 
28367 preceding range.
28369 @item -mmemset-strategy=@var{strategy}
28370 @opindex mmemset-strategy=@var{strategy}
28371 The option is similar to @option{-mmemcpy-strategy=} except that it is to control
28372 @code{__builtin_memset} expansion.
28374 @item -momit-leaf-frame-pointer
28375 @opindex momit-leaf-frame-pointer
28376 Don't keep the frame pointer in a register for leaf functions.  This
28377 avoids the instructions to save, set up, and restore frame pointers and
28378 makes an extra register available in leaf functions.  The option
28379 @option{-fomit-leaf-frame-pointer} removes the frame pointer for leaf functions,
28380 which might make debugging harder.
28382 @item -mtls-direct-seg-refs
28383 @itemx -mno-tls-direct-seg-refs
28384 @opindex mtls-direct-seg-refs
28385 Controls whether TLS variables may be accessed with offsets from the
28386 TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
28387 or whether the thread base pointer must be added.  Whether or not this
28388 is valid depends on the operating system, and whether it maps the
28389 segment to cover the entire TLS area.
28391 For systems that use the GNU C Library, the default is on.
28393 @item -msse2avx
28394 @itemx -mno-sse2avx
28395 @opindex msse2avx
28396 Specify that the assembler should encode SSE instructions with VEX
28397 prefix.  The option @option{-mavx} turns this on by default.
28399 @item -mfentry
28400 @itemx -mno-fentry
28401 @opindex mfentry
28402 If profiling is active (@option{-pg}), put the profiling
28403 counter call before the prologue.
28404 Note: On x86 architectures the attribute @code{ms_hook_prologue}
28405 isn't possible at the moment for @option{-mfentry} and @option{-pg}.
28407 @item -mrecord-mcount
28408 @itemx -mno-record-mcount
28409 @opindex mrecord-mcount
28410 If profiling is active (@option{-pg}), generate a __mcount_loc section
28411 that contains pointers to each profiling call. This is useful for
28412 automatically patching and out calls.
28414 @item -mnop-mcount
28415 @itemx -mno-nop-mcount
28416 @opindex mnop-mcount
28417 If profiling is active (@option{-pg}), generate the calls to
28418 the profiling functions as NOPs. This is useful when they
28419 should be patched in later dynamically. This is likely only
28420 useful together with @option{-mrecord-mcount}.
28422 @item -mskip-rax-setup
28423 @itemx -mno-skip-rax-setup
28424 @opindex mskip-rax-setup
28425 When generating code for the x86-64 architecture with SSE extensions
28426 disabled, @option{-mskip-rax-setup} can be used to skip setting up RAX
28427 register when there are no variable arguments passed in vector registers.
28429 @strong{Warning:} Since RAX register is used to avoid unnecessarily
28430 saving vector registers on stack when passing variable arguments, the
28431 impacts of this option are callees may waste some stack space,
28432 misbehave or jump to a random location.  GCC 4.4 or newer don't have
28433 those issues, regardless the RAX register value.
28435 @item -m8bit-idiv
28436 @itemx -mno-8bit-idiv
28437 @opindex m8bit-idiv
28438 On some processors, like Intel Atom, 8-bit unsigned integer divide is
28439 much faster than 32-bit/64-bit integer divide.  This option generates a
28440 run-time check.  If both dividend and divisor are within range of 0
28441 to 255, 8-bit unsigned integer divide is used instead of
28442 32-bit/64-bit integer divide.
28444 @item -mavx256-split-unaligned-load
28445 @itemx -mavx256-split-unaligned-store
28446 @opindex mavx256-split-unaligned-load
28447 @opindex mavx256-split-unaligned-store
28448 Split 32-byte AVX unaligned load and store.
28450 @item -mstack-protector-guard=@var{guard}
28451 @itemx -mstack-protector-guard-reg=@var{reg}
28452 @itemx -mstack-protector-guard-offset=@var{offset}
28453 @opindex mstack-protector-guard
28454 @opindex mstack-protector-guard-reg
28455 @opindex mstack-protector-guard-offset
28456 Generate stack protection code using canary at @var{guard}.  Supported
28457 locations are @samp{global} for global canary or @samp{tls} for per-thread
28458 canary in the TLS block (the default).  This option has effect only when
28459 @option{-fstack-protector} or @option{-fstack-protector-all} is specified.
28461 With the latter choice the options
28462 @option{-mstack-protector-guard-reg=@var{reg}} and
28463 @option{-mstack-protector-guard-offset=@var{offset}} furthermore specify
28464 which segment register (@code{%fs} or @code{%gs}) to use as base register
28465 for reading the canary, and from what offset from that base register.
28466 The default for those is as specified in the relevant ABI.
28468 @item -mgeneral-regs-only
28469 @opindex mgeneral-regs-only
28470 Generate code that uses only the general-purpose registers.  This
28471 prevents the compiler from using floating-point, vector, mask and bound
28472 registers.
28474 @item -mindirect-branch=@var{choice}
28475 @opindex -mindirect-branch
28476 Convert indirect call and jump with @var{choice}.  The default is
28477 @samp{keep}, which keeps indirect call and jump unmodified.
28478 @samp{thunk} converts indirect call and jump to call and return thunk.
28479 @samp{thunk-inline} converts indirect call and jump to inlined call
28480 and return thunk.  @samp{thunk-extern} converts indirect call and jump
28481 to external call and return thunk provided in a separate object file.
28482 You can control this behavior for a specific function by using the
28483 function attribute @code{indirect_branch}.  @xref{Function Attributes}.
28485 Note that @option{-mcmodel=large} is incompatible with
28486 @option{-mindirect-branch=thunk} and
28487 @option{-mindirect-branch=thunk-extern} since the thunk function may
28488 not be reachable in the large code model.
28490 Note that @option{-mindirect-branch=thunk-extern} is incompatible with
28491 @option{-fcf-protection=branch} since the external thunk can not be modified
28492 to disable control-flow check.
28494 @item -mfunction-return=@var{choice}
28495 @opindex -mfunction-return
28496 Convert function return with @var{choice}.  The default is @samp{keep},
28497 which keeps function return unmodified.  @samp{thunk} converts function
28498 return to call and return thunk.  @samp{thunk-inline} converts function
28499 return to inlined call and return thunk.  @samp{thunk-extern} converts
28500 function return to external call and return thunk provided in a separate
28501 object file.  You can control this behavior for a specific function by
28502 using the function attribute @code{function_return}.
28503 @xref{Function Attributes}.
28505 Note that @option{-mcmodel=large} is incompatible with
28506 @option{-mfunction-return=thunk} and
28507 @option{-mfunction-return=thunk-extern} since the thunk function may
28508 not be reachable in the large code model.
28511 @item -mindirect-branch-register
28512 @opindex -mindirect-branch-register
28513 Force indirect call and jump via register.
28515 @end table
28517 These @samp{-m} switches are supported in addition to the above
28518 on x86-64 processors in 64-bit environments.
28520 @table @gcctabopt
28521 @item -m32
28522 @itemx -m64
28523 @itemx -mx32
28524 @itemx -m16
28525 @itemx -miamcu
28526 @opindex m32
28527 @opindex m64
28528 @opindex mx32
28529 @opindex m16
28530 @opindex miamcu
28531 Generate code for a 16-bit, 32-bit or 64-bit environment.
28532 The @option{-m32} option sets @code{int}, @code{long}, and pointer types
28533 to 32 bits, and
28534 generates code that runs on any i386 system.
28536 The @option{-m64} option sets @code{int} to 32 bits and @code{long} and pointer
28537 types to 64 bits, and generates code for the x86-64 architecture.
28538 For Darwin only the @option{-m64} option also turns off the @option{-fno-pic}
28539 and @option{-mdynamic-no-pic} options.
28541 The @option{-mx32} option sets @code{int}, @code{long}, and pointer types
28542 to 32 bits, and
28543 generates code for the x86-64 architecture.
28545 The @option{-m16} option is the same as @option{-m32}, except for that
28546 it outputs the @code{.code16gcc} assembly directive at the beginning of
28547 the assembly output so that the binary can run in 16-bit mode.
28549 The @option{-miamcu} option generates code which conforms to Intel MCU
28550 psABI.  It requires the @option{-m32} option to be turned on.
28552 @item -mno-red-zone
28553 @opindex mno-red-zone
28554 Do not use a so-called ``red zone'' for x86-64 code.  The red zone is mandated
28555 by the x86-64 ABI; it is a 128-byte area beyond the location of the
28556 stack pointer that is not modified by signal or interrupt handlers
28557 and therefore can be used for temporary data without adjusting the stack
28558 pointer.  The flag @option{-mno-red-zone} disables this red zone.
28560 @item -mcmodel=small
28561 @opindex mcmodel=small
28562 Generate code for the small code model: the program and its symbols must
28563 be linked in the lower 2 GB of the address space.  Pointers are 64 bits.
28564 Programs can be statically or dynamically linked.  This is the default
28565 code model.
28567 @item -mcmodel=kernel
28568 @opindex mcmodel=kernel
28569 Generate code for the kernel code model.  The kernel runs in the
28570 negative 2 GB of the address space.
28571 This model has to be used for Linux kernel code.
28573 @item -mcmodel=medium
28574 @opindex mcmodel=medium
28575 Generate code for the medium model: the program is linked in the lower 2
28576 GB of the address space.  Small symbols are also placed there.  Symbols
28577 with sizes larger than @option{-mlarge-data-threshold} are put into
28578 large data or BSS sections and can be located above 2GB.  Programs can
28579 be statically or dynamically linked.
28581 @item -mcmodel=large
28582 @opindex mcmodel=large
28583 Generate code for the large model.  This model makes no assumptions
28584 about addresses and sizes of sections.
28586 @item -maddress-mode=long
28587 @opindex maddress-mode=long
28588 Generate code for long address mode.  This is only supported for 64-bit
28589 and x32 environments.  It is the default address mode for 64-bit
28590 environments.
28592 @item -maddress-mode=short
28593 @opindex maddress-mode=short
28594 Generate code for short address mode.  This is only supported for 32-bit
28595 and x32 environments.  It is the default address mode for 32-bit and
28596 x32 environments.
28597 @end table
28599 @node x86 Windows Options
28600 @subsection x86 Windows Options
28601 @cindex x86 Windows Options
28602 @cindex Windows Options for x86
28604 These additional options are available for Microsoft Windows targets:
28606 @table @gcctabopt
28607 @item -mconsole
28608 @opindex mconsole
28609 This option
28610 specifies that a console application is to be generated, by
28611 instructing the linker to set the PE header subsystem type
28612 required for console applications.
28613 This option is available for Cygwin and MinGW targets and is
28614 enabled by default on those targets.
28616 @item -mdll
28617 @opindex mdll
28618 This option is available for Cygwin and MinGW targets.  It
28619 specifies that a DLL---a dynamic link library---is to be
28620 generated, enabling the selection of the required runtime
28621 startup object and entry point.
28623 @item -mnop-fun-dllimport
28624 @opindex mnop-fun-dllimport
28625 This option is available for Cygwin and MinGW targets.  It
28626 specifies that the @code{dllimport} attribute should be ignored.
28628 @item -mthread
28629 @opindex mthread
28630 This option is available for MinGW targets. It specifies
28631 that MinGW-specific thread support is to be used.
28633 @item -municode
28634 @opindex municode
28635 This option is available for MinGW-w64 targets.  It causes
28636 the @code{UNICODE} preprocessor macro to be predefined, and
28637 chooses Unicode-capable runtime startup code.
28639 @item -mwin32
28640 @opindex mwin32
28641 This option is available for Cygwin and MinGW targets.  It
28642 specifies that the typical Microsoft Windows predefined macros are to
28643 be set in the pre-processor, but does not influence the choice
28644 of runtime library/startup code.
28646 @item -mwindows
28647 @opindex mwindows
28648 This option is available for Cygwin and MinGW targets.  It
28649 specifies that a GUI application is to be generated by
28650 instructing the linker to set the PE header subsystem type
28651 appropriately.
28653 @item -fno-set-stack-executable
28654 @opindex fno-set-stack-executable
28655 This option is available for MinGW targets. It specifies that
28656 the executable flag for the stack used by nested functions isn't
28657 set. This is necessary for binaries running in kernel mode of
28658 Microsoft Windows, as there the User32 API, which is used to set executable
28659 privileges, isn't available.
28661 @item -fwritable-relocated-rdata
28662 @opindex fno-writable-relocated-rdata
28663 This option is available for MinGW and Cygwin targets.  It specifies
28664 that relocated-data in read-only section is put into the @code{.data}
28665 section.  This is a necessary for older runtimes not supporting
28666 modification of @code{.rdata} sections for pseudo-relocation.
28668 @item -mpe-aligned-commons
28669 @opindex mpe-aligned-commons
28670 This option is available for Cygwin and MinGW targets.  It
28671 specifies that the GNU extension to the PE file format that
28672 permits the correct alignment of COMMON variables should be
28673 used when generating code.  It is enabled by default if
28674 GCC detects that the target assembler found during configuration
28675 supports the feature.
28676 @end table
28678 See also under @ref{x86 Options} for standard options.
28680 @node Xstormy16 Options
28681 @subsection Xstormy16 Options
28682 @cindex Xstormy16 Options
28684 These options are defined for Xstormy16:
28686 @table @gcctabopt
28687 @item -msim
28688 @opindex msim
28689 Choose startup files and linker script suitable for the simulator.
28690 @end table
28692 @node Xtensa Options
28693 @subsection Xtensa Options
28694 @cindex Xtensa Options
28696 These options are supported for Xtensa targets:
28698 @table @gcctabopt
28699 @item -mconst16
28700 @itemx -mno-const16
28701 @opindex mconst16
28702 @opindex mno-const16
28703 Enable or disable use of @code{CONST16} instructions for loading
28704 constant values.  The @code{CONST16} instruction is currently not a
28705 standard option from Tensilica.  When enabled, @code{CONST16}
28706 instructions are always used in place of the standard @code{L32R}
28707 instructions.  The use of @code{CONST16} is enabled by default only if
28708 the @code{L32R} instruction is not available.
28710 @item -mfused-madd
28711 @itemx -mno-fused-madd
28712 @opindex mfused-madd
28713 @opindex mno-fused-madd
28714 Enable or disable use of fused multiply/add and multiply/subtract
28715 instructions in the floating-point option.  This has no effect if the
28716 floating-point option is not also enabled.  Disabling fused multiply/add
28717 and multiply/subtract instructions forces the compiler to use separate
28718 instructions for the multiply and add/subtract operations.  This may be
28719 desirable in some cases where strict IEEE 754-compliant results are
28720 required: the fused multiply add/subtract instructions do not round the
28721 intermediate result, thereby producing results with @emph{more} bits of
28722 precision than specified by the IEEE standard.  Disabling fused multiply
28723 add/subtract instructions also ensures that the program output is not
28724 sensitive to the compiler's ability to combine multiply and add/subtract
28725 operations.
28727 @item -mserialize-volatile
28728 @itemx -mno-serialize-volatile
28729 @opindex mserialize-volatile
28730 @opindex mno-serialize-volatile
28731 When this option is enabled, GCC inserts @code{MEMW} instructions before
28732 @code{volatile} memory references to guarantee sequential consistency.
28733 The default is @option{-mserialize-volatile}.  Use
28734 @option{-mno-serialize-volatile} to omit the @code{MEMW} instructions.
28736 @item -mforce-no-pic
28737 @opindex mforce-no-pic
28738 For targets, like GNU/Linux, where all user-mode Xtensa code must be
28739 position-independent code (PIC), this option disables PIC for compiling
28740 kernel code.
28742 @item -mtext-section-literals
28743 @itemx -mno-text-section-literals
28744 @opindex mtext-section-literals
28745 @opindex mno-text-section-literals
28746 These options control the treatment of literal pools.  The default is
28747 @option{-mno-text-section-literals}, which places literals in a separate
28748 section in the output file.  This allows the literal pool to be placed
28749 in a data RAM/ROM, and it also allows the linker to combine literal
28750 pools from separate object files to remove redundant literals and
28751 improve code size.  With @option{-mtext-section-literals}, the literals
28752 are interspersed in the text section in order to keep them as close as
28753 possible to their references.  This may be necessary for large assembly
28754 files.  Literals for each function are placed right before that function.
28756 @item -mauto-litpools
28757 @itemx -mno-auto-litpools
28758 @opindex mauto-litpools
28759 @opindex mno-auto-litpools
28760 These options control the treatment of literal pools.  The default is
28761 @option{-mno-auto-litpools}, which places literals in a separate
28762 section in the output file unless @option{-mtext-section-literals} is
28763 used.  With @option{-mauto-litpools} the literals are interspersed in
28764 the text section by the assembler.  Compiler does not produce explicit
28765 @code{.literal} directives and loads literals into registers with
28766 @code{MOVI} instructions instead of @code{L32R} to let the assembler
28767 do relaxation and place literals as necessary.  This option allows
28768 assembler to create several literal pools per function and assemble
28769 very big functions, which may not be possible with
28770 @option{-mtext-section-literals}.
28772 @item -mtarget-align
28773 @itemx -mno-target-align
28774 @opindex mtarget-align
28775 @opindex mno-target-align
28776 When this option is enabled, GCC instructs the assembler to
28777 automatically align instructions to reduce branch penalties at the
28778 expense of some code density.  The assembler attempts to widen density
28779 instructions to align branch targets and the instructions following call
28780 instructions.  If there are not enough preceding safe density
28781 instructions to align a target, no widening is performed.  The
28782 default is @option{-mtarget-align}.  These options do not affect the
28783 treatment of auto-aligned instructions like @code{LOOP}, which the
28784 assembler always aligns, either by widening density instructions or
28785 by inserting NOP instructions.
28787 @item -mlongcalls
28788 @itemx -mno-longcalls
28789 @opindex mlongcalls
28790 @opindex mno-longcalls
28791 When this option is enabled, GCC instructs the assembler to translate
28792 direct calls to indirect calls unless it can determine that the target
28793 of a direct call is in the range allowed by the call instruction.  This
28794 translation typically occurs for calls to functions in other source
28795 files.  Specifically, the assembler translates a direct @code{CALL}
28796 instruction into an @code{L32R} followed by a @code{CALLX} instruction.
28797 The default is @option{-mno-longcalls}.  This option should be used in
28798 programs where the call target can potentially be out of range.  This
28799 option is implemented in the assembler, not the compiler, so the
28800 assembly code generated by GCC still shows direct call
28801 instructions---look at the disassembled object code to see the actual
28802 instructions.  Note that the assembler uses an indirect call for
28803 every cross-file call, not just those that really are out of range.
28804 @end table
28806 @node zSeries Options
28807 @subsection zSeries Options
28808 @cindex zSeries options
28810 These are listed under @xref{S/390 and zSeries Options}.
28813 @c man end
28815 @node Spec Files
28816 @section Specifying Subprocesses and the Switches to Pass to Them
28817 @cindex Spec Files
28819 @command{gcc} is a driver program.  It performs its job by invoking a
28820 sequence of other programs to do the work of compiling, assembling and
28821 linking.  GCC interprets its command-line parameters and uses these to
28822 deduce which programs it should invoke, and which command-line options
28823 it ought to place on their command lines.  This behavior is controlled
28824 by @dfn{spec strings}.  In most cases there is one spec string for each
28825 program that GCC can invoke, but a few programs have multiple spec
28826 strings to control their behavior.  The spec strings built into GCC can
28827 be overridden by using the @option{-specs=} command-line switch to specify
28828 a spec file.
28830 @dfn{Spec files} are plain-text files that are used to construct spec
28831 strings.  They consist of a sequence of directives separated by blank
28832 lines.  The type of directive is determined by the first non-whitespace
28833 character on the line, which can be one of the following:
28835 @table @code
28836 @item %@var{command}
28837 Issues a @var{command} to the spec file processor.  The commands that can
28838 appear here are:
28840 @table @code
28841 @item %include <@var{file}>
28842 @cindex @code{%include}
28843 Search for @var{file} and insert its text at the current point in the
28844 specs file.
28846 @item %include_noerr <@var{file}>
28847 @cindex @code{%include_noerr}
28848 Just like @samp{%include}, but do not generate an error message if the include
28849 file cannot be found.
28851 @item %rename @var{old_name} @var{new_name}
28852 @cindex @code{%rename}
28853 Rename the spec string @var{old_name} to @var{new_name}.
28855 @end table
28857 @item *[@var{spec_name}]:
28858 This tells the compiler to create, override or delete the named spec
28859 string.  All lines after this directive up to the next directive or
28860 blank line are considered to be the text for the spec string.  If this
28861 results in an empty string then the spec is deleted.  (Or, if the
28862 spec did not exist, then nothing happens.)  Otherwise, if the spec
28863 does not currently exist a new spec is created.  If the spec does
28864 exist then its contents are overridden by the text of this
28865 directive, unless the first character of that text is the @samp{+}
28866 character, in which case the text is appended to the spec.
28868 @item [@var{suffix}]:
28869 Creates a new @samp{[@var{suffix}] spec} pair.  All lines after this directive
28870 and up to the next directive or blank line are considered to make up the
28871 spec string for the indicated suffix.  When the compiler encounters an
28872 input file with the named suffix, it processes the spec string in
28873 order to work out how to compile that file.  For example:
28875 @smallexample
28876 .ZZ:
28877 z-compile -input %i
28878 @end smallexample
28880 This says that any input file whose name ends in @samp{.ZZ} should be
28881 passed to the program @samp{z-compile}, which should be invoked with the
28882 command-line switch @option{-input} and with the result of performing the
28883 @samp{%i} substitution.  (See below.)
28885 As an alternative to providing a spec string, the text following a
28886 suffix directive can be one of the following:
28888 @table @code
28889 @item @@@var{language}
28890 This says that the suffix is an alias for a known @var{language}.  This is
28891 similar to using the @option{-x} command-line switch to GCC to specify a
28892 language explicitly.  For example:
28894 @smallexample
28895 .ZZ:
28896 @@c++
28897 @end smallexample
28899 Says that .ZZ files are, in fact, C++ source files.
28901 @item #@var{name}
28902 This causes an error messages saying:
28904 @smallexample
28905 @var{name} compiler not installed on this system.
28906 @end smallexample
28907 @end table
28909 GCC already has an extensive list of suffixes built into it.
28910 This directive adds an entry to the end of the list of suffixes, but
28911 since the list is searched from the end backwards, it is effectively
28912 possible to override earlier entries using this technique.
28914 @end table
28916 GCC has the following spec strings built into it.  Spec files can
28917 override these strings or create their own.  Note that individual
28918 targets can also add their own spec strings to this list.
28920 @smallexample
28921 asm          Options to pass to the assembler
28922 asm_final    Options to pass to the assembler post-processor
28923 cpp          Options to pass to the C preprocessor
28924 cc1          Options to pass to the C compiler
28925 cc1plus      Options to pass to the C++ compiler
28926 endfile      Object files to include at the end of the link
28927 link         Options to pass to the linker
28928 lib          Libraries to include on the command line to the linker
28929 libgcc       Decides which GCC support library to pass to the linker
28930 linker       Sets the name of the linker
28931 predefines   Defines to be passed to the C preprocessor
28932 signed_char  Defines to pass to CPP to say whether @code{char} is signed
28933              by default
28934 startfile    Object files to include at the start of the link
28935 @end smallexample
28937 Here is a small example of a spec file:
28939 @smallexample
28940 %rename lib                 old_lib
28942 *lib:
28943 --start-group -lgcc -lc -leval1 --end-group %(old_lib)
28944 @end smallexample
28946 This example renames the spec called @samp{lib} to @samp{old_lib} and
28947 then overrides the previous definition of @samp{lib} with a new one.
28948 The new definition adds in some extra command-line options before
28949 including the text of the old definition.
28951 @dfn{Spec strings} are a list of command-line options to be passed to their
28952 corresponding program.  In addition, the spec strings can contain
28953 @samp{%}-prefixed sequences to substitute variable text or to
28954 conditionally insert text into the command line.  Using these constructs
28955 it is possible to generate quite complex command lines.
28957 Here is a table of all defined @samp{%}-sequences for spec
28958 strings.  Note that spaces are not generated automatically around the
28959 results of expanding these sequences.  Therefore you can concatenate them
28960 together or combine them with constant text in a single argument.
28962 @table @code
28963 @item %%
28964 Substitute one @samp{%} into the program name or argument.
28966 @item %i
28967 Substitute the name of the input file being processed.
28969 @item %b
28970 Substitute the basename of the input file being processed.
28971 This is the substring up to (and not including) the last period
28972 and not including the directory.
28974 @item %B
28975 This is the same as @samp{%b}, but include the file suffix (text after
28976 the last period).
28978 @item %d
28979 Marks the argument containing or following the @samp{%d} as a
28980 temporary file name, so that that file is deleted if GCC exits
28981 successfully.  Unlike @samp{%g}, this contributes no text to the
28982 argument.
28984 @item %g@var{suffix}
28985 Substitute a file name that has suffix @var{suffix} and is chosen
28986 once per compilation, and mark the argument in the same way as
28987 @samp{%d}.  To reduce exposure to denial-of-service attacks, the file
28988 name is now chosen in a way that is hard to predict even when previously
28989 chosen file names are known.  For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
28990 might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}.  @var{suffix} matches
28991 the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
28992 treated exactly as if @samp{%O} had been preprocessed.  Previously, @samp{%g}
28993 was simply substituted with a file name chosen once per compilation,
28994 without regard to any appended suffix (which was therefore treated
28995 just like ordinary text), making such attacks more likely to succeed.
28997 @item %u@var{suffix}
28998 Like @samp{%g}, but generates a new temporary file name
28999 each time it appears instead of once per compilation.
29001 @item %U@var{suffix}
29002 Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
29003 new one if there is no such last file name.  In the absence of any
29004 @samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
29005 the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
29006 involves the generation of two distinct file names, one
29007 for each @samp{%g.s} and another for each @samp{%U.s}.  Previously, @samp{%U} was
29008 simply substituted with a file name chosen for the previous @samp{%u},
29009 without regard to any appended suffix.
29011 @item %j@var{suffix}
29012 Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
29013 writable, and if @option{-save-temps} is not used; 
29014 otherwise, substitute the name
29015 of a temporary file, just like @samp{%u}.  This temporary file is not
29016 meant for communication between processes, but rather as a junk
29017 disposal mechanism.
29019 @item %|@var{suffix}
29020 @itemx %m@var{suffix}
29021 Like @samp{%g}, except if @option{-pipe} is in effect.  In that case
29022 @samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
29023 all.  These are the two most common ways to instruct a program that it
29024 should read from standard input or write to standard output.  If you
29025 need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
29026 construct: see for example @file{f/lang-specs.h}.
29028 @item %.@var{SUFFIX}
29029 Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
29030 when it is subsequently output with @samp{%*}.  @var{SUFFIX} is
29031 terminated by the next space or %.
29033 @item %w
29034 Marks the argument containing or following the @samp{%w} as the
29035 designated output file of this compilation.  This puts the argument
29036 into the sequence of arguments that @samp{%o} substitutes.
29038 @item %o
29039 Substitutes the names of all the output files, with spaces
29040 automatically placed around them.  You should write spaces
29041 around the @samp{%o} as well or the results are undefined.
29042 @samp{%o} is for use in the specs for running the linker.
29043 Input files whose names have no recognized suffix are not compiled
29044 at all, but they are included among the output files, so they are
29045 linked.
29047 @item %O
29048 Substitutes the suffix for object files.  Note that this is
29049 handled specially when it immediately follows @samp{%g, %u, or %U},
29050 because of the need for those to form complete file names.  The
29051 handling is such that @samp{%O} is treated exactly as if it had already
29052 been substituted, except that @samp{%g, %u, and %U} do not currently
29053 support additional @var{suffix} characters following @samp{%O} as they do
29054 following, for example, @samp{.o}.
29056 @item %p
29057 Substitutes the standard macro predefinitions for the
29058 current target machine.  Use this when running @command{cpp}.
29060 @item %P
29061 Like @samp{%p}, but puts @samp{__} before and after the name of each
29062 predefined macro, except for macros that start with @samp{__} or with
29063 @samp{_@var{L}}, where @var{L} is an uppercase letter.  This is for ISO
29066 @item %I
29067 Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
29068 @option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
29069 @option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
29070 and @option{-imultilib} as necessary.
29072 @item %s
29073 Current argument is the name of a library or startup file of some sort.
29074 Search for that file in a standard list of directories and substitute
29075 the full name found.  The current working directory is included in the
29076 list of directories scanned.
29078 @item %T
29079 Current argument is the name of a linker script.  Search for that file
29080 in the current list of directories to scan for libraries. If the file
29081 is located insert a @option{--script} option into the command line
29082 followed by the full path name found.  If the file is not found then
29083 generate an error message.  Note: the current working directory is not
29084 searched.
29086 @item %e@var{str}
29087 Print @var{str} as an error message.  @var{str} is terminated by a newline.
29088 Use this when inconsistent options are detected.
29090 @item %(@var{name})
29091 Substitute the contents of spec string @var{name} at this point.
29093 @item %x@{@var{option}@}
29094 Accumulate an option for @samp{%X}.
29096 @item %X
29097 Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
29098 spec string.
29100 @item %Y
29101 Output the accumulated assembler options specified by @option{-Wa}.
29103 @item %Z
29104 Output the accumulated preprocessor options specified by @option{-Wp}.
29106 @item %a
29107 Process the @code{asm} spec.  This is used to compute the
29108 switches to be passed to the assembler.
29110 @item %A
29111 Process the @code{asm_final} spec.  This is a spec string for
29112 passing switches to an assembler post-processor, if such a program is
29113 needed.
29115 @item %l
29116 Process the @code{link} spec.  This is the spec for computing the
29117 command line passed to the linker.  Typically it makes use of the
29118 @samp{%L %G %S %D and %E} sequences.
29120 @item %D
29121 Dump out a @option{-L} option for each directory that GCC believes might
29122 contain startup files.  If the target supports multilibs then the
29123 current multilib directory is prepended to each of these paths.
29125 @item %L
29126 Process the @code{lib} spec.  This is a spec string for deciding which
29127 libraries are included on the command line to the linker.
29129 @item %G
29130 Process the @code{libgcc} spec.  This is a spec string for deciding
29131 which GCC support library is included on the command line to the linker.
29133 @item %S
29134 Process the @code{startfile} spec.  This is a spec for deciding which
29135 object files are the first ones passed to the linker.  Typically
29136 this might be a file named @file{crt0.o}.
29138 @item %E
29139 Process the @code{endfile} spec.  This is a spec string that specifies
29140 the last object files that are passed to the linker.
29142 @item %C
29143 Process the @code{cpp} spec.  This is used to construct the arguments
29144 to be passed to the C preprocessor.
29146 @item %1
29147 Process the @code{cc1} spec.  This is used to construct the options to be
29148 passed to the actual C compiler (@command{cc1}).
29150 @item %2
29151 Process the @code{cc1plus} spec.  This is used to construct the options to be
29152 passed to the actual C++ compiler (@command{cc1plus}).
29154 @item %*
29155 Substitute the variable part of a matched option.  See below.
29156 Note that each comma in the substituted string is replaced by
29157 a single space.
29159 @item %<S
29160 Remove all occurrences of @code{-S} from the command line.  Note---this
29161 command is position dependent.  @samp{%} commands in the spec string
29162 before this one see @code{-S}, @samp{%} commands in the spec string
29163 after this one do not.
29165 @item %:@var{function}(@var{args})
29166 Call the named function @var{function}, passing it @var{args}.
29167 @var{args} is first processed as a nested spec string, then split
29168 into an argument vector in the usual fashion.  The function returns
29169 a string which is processed as if it had appeared literally as part
29170 of the current spec.
29172 The following built-in spec functions are provided:
29174 @table @code
29175 @item @code{getenv}
29176 The @code{getenv} spec function takes two arguments: an environment
29177 variable name and a string.  If the environment variable is not
29178 defined, a fatal error is issued.  Otherwise, the return value is the
29179 value of the environment variable concatenated with the string.  For
29180 example, if @env{TOPDIR} is defined as @file{/path/to/top}, then:
29182 @smallexample
29183 %:getenv(TOPDIR /include)
29184 @end smallexample
29186 expands to @file{/path/to/top/include}.
29188 @item @code{if-exists}
29189 The @code{if-exists} spec function takes one argument, an absolute
29190 pathname to a file.  If the file exists, @code{if-exists} returns the
29191 pathname.  Here is a small example of its usage:
29193 @smallexample
29194 *startfile:
29195 crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
29196 @end smallexample
29198 @item @code{if-exists-else}
29199 The @code{if-exists-else} spec function is similar to the @code{if-exists}
29200 spec function, except that it takes two arguments.  The first argument is
29201 an absolute pathname to a file.  If the file exists, @code{if-exists-else}
29202 returns the pathname.  If it does not exist, it returns the second argument.
29203 This way, @code{if-exists-else} can be used to select one file or another,
29204 based on the existence of the first.  Here is a small example of its usage:
29206 @smallexample
29207 *startfile:
29208 crt0%O%s %:if-exists(crti%O%s) \
29209 %:if-exists-else(crtbeginT%O%s crtbegin%O%s)
29210 @end smallexample
29212 @item @code{replace-outfile}
29213 The @code{replace-outfile} spec function takes two arguments.  It looks for the
29214 first argument in the outfiles array and replaces it with the second argument.  Here
29215 is a small example of its usage:
29217 @smallexample
29218 %@{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)@}
29219 @end smallexample
29221 @item @code{remove-outfile}
29222 The @code{remove-outfile} spec function takes one argument.  It looks for the
29223 first argument in the outfiles array and removes it.  Here is a small example
29224 its usage:
29226 @smallexample
29227 %:remove-outfile(-lm)
29228 @end smallexample
29230 @item @code{pass-through-libs}
29231 The @code{pass-through-libs} spec function takes any number of arguments.  It
29232 finds any @option{-l} options and any non-options ending in @file{.a} (which it
29233 assumes are the names of linker input library archive files) and returns a
29234 result containing all the found arguments each prepended by
29235 @option{-plugin-opt=-pass-through=} and joined by spaces.  This list is
29236 intended to be passed to the LTO linker plugin.
29238 @smallexample
29239 %:pass-through-libs(%G %L %G)
29240 @end smallexample
29242 @item @code{print-asm-header}
29243 The @code{print-asm-header} function takes no arguments and simply
29244 prints a banner like:
29246 @smallexample
29247 Assembler options
29248 =================
29250 Use "-Wa,OPTION" to pass "OPTION" to the assembler.
29251 @end smallexample
29253 It is used to separate compiler options from assembler options
29254 in the @option{--target-help} output.
29255 @end table
29257 @item %@{S@}
29258 Substitutes the @code{-S} switch, if that switch is given to GCC@.
29259 If that switch is not specified, this substitutes nothing.  Note that
29260 the leading dash is omitted when specifying this option, and it is
29261 automatically inserted if the substitution is performed.  Thus the spec
29262 string @samp{%@{foo@}} matches the command-line option @option{-foo}
29263 and outputs the command-line option @option{-foo}.
29265 @item %W@{S@}
29266 Like %@{@code{S}@} but mark last argument supplied within as a file to be
29267 deleted on failure.
29269 @item %@{S*@}
29270 Substitutes all the switches specified to GCC whose names start
29271 with @code{-S}, but which also take an argument.  This is used for
29272 switches like @option{-o}, @option{-D}, @option{-I}, etc.
29273 GCC considers @option{-o foo} as being
29274 one switch whose name starts with @samp{o}.  %@{o*@} substitutes this
29275 text, including the space.  Thus two arguments are generated.
29277 @item %@{S*&T*@}
29278 Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
29279 (the order of @code{S} and @code{T} in the spec is not significant).
29280 There can be any number of ampersand-separated variables; for each the
29281 wild card is optional.  Useful for CPP as @samp{%@{D*&U*&A*@}}.
29283 @item %@{S:X@}
29284 Substitutes @code{X}, if the @option{-S} switch is given to GCC@.
29286 @item %@{!S:X@}
29287 Substitutes @code{X}, if the @option{-S} switch is @emph{not} given to GCC@.
29289 @item %@{S*:X@}
29290 Substitutes @code{X} if one or more switches whose names start with
29291 @code{-S} are specified to GCC@.  Normally @code{X} is substituted only
29292 once, no matter how many such switches appeared.  However, if @code{%*}
29293 appears somewhere in @code{X}, then @code{X} is substituted once
29294 for each matching switch, with the @code{%*} replaced by the part of
29295 that switch matching the @code{*}.
29297 If @code{%*} appears as the last part of a spec sequence then a space
29298 is added after the end of the last substitution.  If there is more
29299 text in the sequence, however, then a space is not generated.  This
29300 allows the @code{%*} substitution to be used as part of a larger
29301 string.  For example, a spec string like this:
29303 @smallexample
29304 %@{mcu=*:--script=%*/memory.ld@}
29305 @end smallexample
29307 @noindent
29308 when matching an option like @option{-mcu=newchip} produces:
29310 @smallexample
29311 --script=newchip/memory.ld
29312 @end smallexample
29314 @item %@{.S:X@}
29315 Substitutes @code{X}, if processing a file with suffix @code{S}.
29317 @item %@{!.S:X@}
29318 Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
29320 @item %@{,S:X@}
29321 Substitutes @code{X}, if processing a file for language @code{S}.
29323 @item %@{!,S:X@}
29324 Substitutes @code{X}, if not processing a file for language @code{S}.
29326 @item %@{S|P:X@}
29327 Substitutes @code{X} if either @code{-S} or @code{-P} is given to
29328 GCC@.  This may be combined with @samp{!}, @samp{.}, @samp{,}, and
29329 @code{*} sequences as well, although they have a stronger binding than
29330 the @samp{|}.  If @code{%*} appears in @code{X}, all of the
29331 alternatives must be starred, and only the first matching alternative
29332 is substituted.
29334 For example, a spec string like this:
29336 @smallexample
29337 %@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
29338 @end smallexample
29340 @noindent
29341 outputs the following command-line options from the following input
29342 command-line options:
29344 @smallexample
29345 fred.c        -foo -baz
29346 jim.d         -bar -boggle
29347 -d fred.c     -foo -baz -boggle
29348 -d jim.d      -bar -baz -boggle
29349 @end smallexample
29351 @item %@{S:X; T:Y; :D@}
29353 If @code{S} is given to GCC, substitutes @code{X}; else if @code{T} is
29354 given to GCC, substitutes @code{Y}; else substitutes @code{D}.  There can
29355 be as many clauses as you need.  This may be combined with @code{.},
29356 @code{,}, @code{!}, @code{|}, and @code{*} as needed.
29359 @end table
29361 The switch matching text @code{S} in a @samp{%@{S@}}, @samp{%@{S:X@}}
29362 or similar construct can use a backslash to ignore the special meaning
29363 of the character following it, thus allowing literal matching of a
29364 character that is otherwise specially treated.  For example,
29365 @samp{%@{std=iso9899\:1999:X@}} substitutes @code{X} if the
29366 @option{-std=iso9899:1999} option is given.
29368 The conditional text @code{X} in a @samp{%@{S:X@}} or similar
29369 construct may contain other nested @samp{%} constructs or spaces, or
29370 even newlines.  They are processed as usual, as described above.
29371 Trailing white space in @code{X} is ignored.  White space may also
29372 appear anywhere on the left side of the colon in these constructs,
29373 except between @code{.} or @code{*} and the corresponding word.
29375 The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
29376 handled specifically in these constructs.  If another value of
29377 @option{-O} or the negated form of a @option{-f}, @option{-m}, or
29378 @option{-W} switch is found later in the command line, the earlier
29379 switch value is ignored, except with @{@code{S}*@} where @code{S} is
29380 just one letter, which passes all matching options.
29382 The character @samp{|} at the beginning of the predicate text is used to
29383 indicate that a command should be piped to the following command, but
29384 only if @option{-pipe} is specified.
29386 It is built into GCC which switches take arguments and which do not.
29387 (You might think it would be useful to generalize this to allow each
29388 compiler's spec to say which switches take arguments.  But this cannot
29389 be done in a consistent fashion.  GCC cannot even decide which input
29390 files have been specified without knowing which switches take arguments,
29391 and it must know which input files to compile in order to tell which
29392 compilers to run).
29394 GCC also knows implicitly that arguments starting in @option{-l} are to be
29395 treated as compiler output files, and passed to the linker in their
29396 proper position among the other output files.
29398 @node Environment Variables
29399 @section Environment Variables Affecting GCC
29400 @cindex environment variables
29402 @c man begin ENVIRONMENT
29403 This section describes several environment variables that affect how GCC
29404 operates.  Some of them work by specifying directories or prefixes to use
29405 when searching for various kinds of files.  Some are used to specify other
29406 aspects of the compilation environment.
29408 Note that you can also specify places to search using options such as
29409 @option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}).  These
29410 take precedence over places specified using environment variables, which
29411 in turn take precedence over those specified by the configuration of GCC@.
29412 @xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
29413 GNU Compiler Collection (GCC) Internals}.
29415 @table @env
29416 @item LANG
29417 @itemx LC_CTYPE
29418 @c @itemx LC_COLLATE
29419 @itemx LC_MESSAGES
29420 @c @itemx LC_MONETARY
29421 @c @itemx LC_NUMERIC
29422 @c @itemx LC_TIME
29423 @itemx LC_ALL
29424 @findex LANG
29425 @findex LC_CTYPE
29426 @c @findex LC_COLLATE
29427 @findex LC_MESSAGES
29428 @c @findex LC_MONETARY
29429 @c @findex LC_NUMERIC
29430 @c @findex LC_TIME
29431 @findex LC_ALL
29432 @cindex locale
29433 These environment variables control the way that GCC uses
29434 localization information which allows GCC to work with different
29435 national conventions.  GCC inspects the locale categories
29436 @env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
29437 so.  These locale categories can be set to any value supported by your
29438 installation.  A typical value is @samp{en_GB.UTF-8} for English in the United
29439 Kingdom encoded in UTF-8.
29441 The @env{LC_CTYPE} environment variable specifies character
29442 classification.  GCC uses it to determine the character boundaries in
29443 a string; this is needed for some multibyte encodings that contain quote
29444 and escape characters that are otherwise interpreted as a string
29445 end or escape.
29447 The @env{LC_MESSAGES} environment variable specifies the language to
29448 use in diagnostic messages.
29450 If the @env{LC_ALL} environment variable is set, it overrides the value
29451 of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
29452 and @env{LC_MESSAGES} default to the value of the @env{LANG}
29453 environment variable.  If none of these variables are set, GCC
29454 defaults to traditional C English behavior.
29456 @item TMPDIR
29457 @findex TMPDIR
29458 If @env{TMPDIR} is set, it specifies the directory to use for temporary
29459 files.  GCC uses temporary files to hold the output of one stage of
29460 compilation which is to be used as input to the next stage: for example,
29461 the output of the preprocessor, which is the input to the compiler
29462 proper.
29464 @item GCC_COMPARE_DEBUG
29465 @findex GCC_COMPARE_DEBUG
29466 Setting @env{GCC_COMPARE_DEBUG} is nearly equivalent to passing
29467 @option{-fcompare-debug} to the compiler driver.  See the documentation
29468 of this option for more details.
29470 @item GCC_EXEC_PREFIX
29471 @findex GCC_EXEC_PREFIX
29472 If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
29473 names of the subprograms executed by the compiler.  No slash is added
29474 when this prefix is combined with the name of a subprogram, but you can
29475 specify a prefix that ends with a slash if you wish.
29477 If @env{GCC_EXEC_PREFIX} is not set, GCC attempts to figure out
29478 an appropriate prefix to use based on the pathname it is invoked with.
29480 If GCC cannot find the subprogram using the specified prefix, it
29481 tries looking in the usual places for the subprogram.
29483 The default value of @env{GCC_EXEC_PREFIX} is
29484 @file{@var{prefix}/lib/gcc/} where @var{prefix} is the prefix to
29485 the installed compiler. In many cases @var{prefix} is the value
29486 of @code{prefix} when you ran the @file{configure} script.
29488 Other prefixes specified with @option{-B} take precedence over this prefix.
29490 This prefix is also used for finding files such as @file{crt0.o} that are
29491 used for linking.
29493 In addition, the prefix is used in an unusual way in finding the
29494 directories to search for header files.  For each of the standard
29495 directories whose name normally begins with @samp{/usr/local/lib/gcc}
29496 (more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
29497 replacing that beginning with the specified prefix to produce an
29498 alternate directory name.  Thus, with @option{-Bfoo/}, GCC searches
29499 @file{foo/bar} just before it searches the standard directory 
29500 @file{/usr/local/lib/bar}.
29501 If a standard directory begins with the configured
29502 @var{prefix} then the value of @var{prefix} is replaced by
29503 @env{GCC_EXEC_PREFIX} when looking for header files.
29505 @item COMPILER_PATH
29506 @findex COMPILER_PATH
29507 The value of @env{COMPILER_PATH} is a colon-separated list of
29508 directories, much like @env{PATH}.  GCC tries the directories thus
29509 specified when searching for subprograms, if it cannot find the
29510 subprograms using @env{GCC_EXEC_PREFIX}.
29512 @item LIBRARY_PATH
29513 @findex LIBRARY_PATH
29514 The value of @env{LIBRARY_PATH} is a colon-separated list of
29515 directories, much like @env{PATH}.  When configured as a native compiler,
29516 GCC tries the directories thus specified when searching for special
29517 linker files, if it cannot find them using @env{GCC_EXEC_PREFIX}.  Linking
29518 using GCC also uses these directories when searching for ordinary
29519 libraries for the @option{-l} option (but directories specified with
29520 @option{-L} come first).
29522 @item LANG
29523 @findex LANG
29524 @cindex locale definition
29525 This variable is used to pass locale information to the compiler.  One way in
29526 which this information is used is to determine the character set to be used
29527 when character literals, string literals and comments are parsed in C and C++.
29528 When the compiler is configured to allow multibyte characters,
29529 the following values for @env{LANG} are recognized:
29531 @table @samp
29532 @item C-JIS
29533 Recognize JIS characters.
29534 @item C-SJIS
29535 Recognize SJIS characters.
29536 @item C-EUCJP
29537 Recognize EUCJP characters.
29538 @end table
29540 If @env{LANG} is not defined, or if it has some other value, then the
29541 compiler uses @code{mblen} and @code{mbtowc} as defined by the default locale to
29542 recognize and translate multibyte characters.
29543 @end table
29545 @noindent
29546 Some additional environment variables affect the behavior of the
29547 preprocessor.
29549 @include cppenv.texi
29551 @c man end
29553 @node Precompiled Headers
29554 @section Using Precompiled Headers
29555 @cindex precompiled headers
29556 @cindex speed of compilation
29558 Often large projects have many header files that are included in every
29559 source file.  The time the compiler takes to process these header files
29560 over and over again can account for nearly all of the time required to
29561 build the project.  To make builds faster, GCC allows you to
29562 @dfn{precompile} a header file.
29564 To create a precompiled header file, simply compile it as you would any
29565 other file, if necessary using the @option{-x} option to make the driver
29566 treat it as a C or C++ header file.  You may want to use a
29567 tool like @command{make} to keep the precompiled header up-to-date when
29568 the headers it contains change.
29570 A precompiled header file is searched for when @code{#include} is
29571 seen in the compilation.  As it searches for the included file
29572 (@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
29573 compiler looks for a precompiled header in each directory just before it
29574 looks for the include file in that directory.  The name searched for is
29575 the name specified in the @code{#include} with @samp{.gch} appended.  If
29576 the precompiled header file cannot be used, it is ignored.
29578 For instance, if you have @code{#include "all.h"}, and you have
29579 @file{all.h.gch} in the same directory as @file{all.h}, then the
29580 precompiled header file is used if possible, and the original
29581 header is used otherwise.
29583 Alternatively, you might decide to put the precompiled header file in a
29584 directory and use @option{-I} to ensure that directory is searched
29585 before (or instead of) the directory containing the original header.
29586 Then, if you want to check that the precompiled header file is always
29587 used, you can put a file of the same name as the original header in this
29588 directory containing an @code{#error} command.
29590 This also works with @option{-include}.  So yet another way to use
29591 precompiled headers, good for projects not designed with precompiled
29592 header files in mind, is to simply take most of the header files used by
29593 a project, include them from another header file, precompile that header
29594 file, and @option{-include} the precompiled header.  If the header files
29595 have guards against multiple inclusion, they are skipped because
29596 they've already been included (in the precompiled header).
29598 If you need to precompile the same header file for different
29599 languages, targets, or compiler options, you can instead make a
29600 @emph{directory} named like @file{all.h.gch}, and put each precompiled
29601 header in the directory, perhaps using @option{-o}.  It doesn't matter
29602 what you call the files in the directory; every precompiled header in
29603 the directory is considered.  The first precompiled header
29604 encountered in the directory that is valid for this compilation is
29605 used; they're searched in no particular order.
29607 There are many other possibilities, limited only by your imagination,
29608 good sense, and the constraints of your build system.
29610 A precompiled header file can be used only when these conditions apply:
29612 @itemize
29613 @item
29614 Only one precompiled header can be used in a particular compilation.
29616 @item
29617 A precompiled header cannot be used once the first C token is seen.  You
29618 can have preprocessor directives before a precompiled header; you cannot
29619 include a precompiled header from inside another header.
29621 @item
29622 The precompiled header file must be produced for the same language as
29623 the current compilation.  You cannot use a C precompiled header for a C++
29624 compilation.
29626 @item
29627 The precompiled header file must have been produced by the same compiler
29628 binary as the current compilation is using.
29630 @item
29631 Any macros defined before the precompiled header is included must
29632 either be defined in the same way as when the precompiled header was
29633 generated, or must not affect the precompiled header, which usually
29634 means that they don't appear in the precompiled header at all.
29636 The @option{-D} option is one way to define a macro before a
29637 precompiled header is included; using a @code{#define} can also do it.
29638 There are also some options that define macros implicitly, like
29639 @option{-O} and @option{-Wdeprecated}; the same rule applies to macros
29640 defined this way.
29642 @item If debugging information is output when using the precompiled
29643 header, using @option{-g} or similar, the same kind of debugging information
29644 must have been output when building the precompiled header.  However,
29645 a precompiled header built using @option{-g} can be used in a compilation
29646 when no debugging information is being output.
29648 @item The same @option{-m} options must generally be used when building
29649 and using the precompiled header.  @xref{Submodel Options},
29650 for any cases where this rule is relaxed.
29652 @item Each of the following options must be the same when building and using
29653 the precompiled header:
29655 @gccoptlist{-fexceptions}
29657 @item
29658 Some other command-line options starting with @option{-f},
29659 @option{-p}, or @option{-O} must be defined in the same way as when
29660 the precompiled header was generated.  At present, it's not clear
29661 which options are safe to change and which are not; the safest choice
29662 is to use exactly the same options when generating and using the
29663 precompiled header.  The following are known to be safe:
29665 @gccoptlist{-fmessage-length=  -fpreprocessed  -fsched-interblock @gol
29666 -fsched-spec  -fsched-spec-load  -fsched-spec-load-dangerous @gol
29667 -fsched-verbose=@var{number}  -fschedule-insns  -fvisibility= @gol
29668 -pedantic-errors}
29670 @end itemize
29672 For all of these except the last, the compiler automatically
29673 ignores the precompiled header if the conditions aren't met.  If you
29674 find an option combination that doesn't work and doesn't cause the
29675 precompiled header to be ignored, please consider filing a bug report,
29676 see @ref{Bugs}.
29678 If you do use differing options when generating and using the
29679 precompiled header, the actual behavior is a mixture of the
29680 behavior for the options.  For instance, if you use @option{-g} to
29681 generate the precompiled header but not when using it, you may or may
29682 not get debugging information for routines in the precompiled header.