OpenCores
URL https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [gnu-src/] [gcc-4.5.1/] [gcc/] [doc/] [invoke.texi] - Blame information for rev 294

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 284 jeremybenn
@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2
@c 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
3
@c Free Software Foundation, Inc.
4
@c This is part of the GCC manual.
5
@c For copying conditions, see the file gcc.texi.
6
 
7
@ignore
8
@c man begin INCLUDE
9
@include gcc-vers.texi
10
@c man end
11
 
12
@c man begin COPYRIGHT
13
Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
14
1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
15
Free Software Foundation, Inc.
16
 
17
Permission is granted to copy, distribute and/or modify this document
18
under the terms of the GNU Free Documentation License, Version 1.2 or
19
any later version published by the Free Software Foundation; with the
20
Invariant Sections being ``GNU General Public License'' and ``Funding
21
Free Software'', the Front-Cover texts being (a) (see below), and with
22
the Back-Cover Texts being (b) (see below).  A copy of the license is
23
included in the gfdl(7) man page.
24
 
25
(a) The FSF's Front-Cover Text is:
26
 
27
     A GNU Manual
28
 
29
(b) The FSF's Back-Cover Text is:
30
 
31
     You have freedom to copy and modify this GNU Manual, like GNU
32
     software.  Copies published by the Free Software Foundation raise
33
     funds for GNU development.
34
@c man end
35
@c Set file name and title for the man page.
36
@setfilename gcc
37
@settitle GNU project C and C++ compiler
38
@c man begin SYNOPSIS
39
gcc [@option{-c}|@option{-S}|@option{-E}] [@option{-std=}@var{standard}]
40
    [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
41
    [@option{-W}@var{warn}@dots{}] [@option{-pedantic}]
42
    [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
43
    [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
44
    [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
45
    [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}
46
 
47
Only the most useful options are listed here; see below for the
48
remainder.  @samp{g++} accepts mostly the same options as @samp{gcc}.
49
@c man end
50
@c man begin SEEALSO
51
gpl(7), gfdl(7), fsf-funding(7),
52
cpp(1), gcov(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1)
53
and the Info entries for @file{gcc}, @file{cpp}, @file{as},
54
@file{ld}, @file{binutils} and @file{gdb}.
55
@c man end
56
@c man begin BUGS
57
For instructions on reporting bugs, see
58
@w{@value{BUGURL}}.
59
@c man end
60
@c man begin AUTHOR
61
See the Info entry for @command{gcc}, or
62
@w{@uref{http://gcc.gnu.org/onlinedocs/gcc/Contributors.html}},
63
for contributors to GCC@.
64
@c man end
65
@end ignore
66
 
67
@node Invoking GCC
68
@chapter GCC Command Options
69
@cindex GCC command options
70
@cindex command options
71
@cindex options, GCC command
72
 
73
@c man begin DESCRIPTION
74
When you invoke GCC, it normally does preprocessing, compilation,
75
assembly and linking.  The ``overall options'' allow you to stop this
76
process at an intermediate stage.  For example, the @option{-c} option
77
says not to run the linker.  Then the output consists of object files
78
output by the assembler.
79
 
80
Other options are passed on to one stage of processing.  Some options
81
control the preprocessor and others the compiler itself.  Yet other
82
options control the assembler and linker; most of these are not
83
documented here, since you rarely need to use any of them.
84
 
85
@cindex C compilation options
86
Most of the command line options that you can use with GCC are useful
87
for C programs; when an option is only useful with another language
88
(usually C++), the explanation says so explicitly.  If the description
89
for a particular option does not mention a source language, you can use
90
that option with all supported languages.
91
 
92
@cindex C++ compilation options
93
@xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
94
options for compiling C++ programs.
95
 
96
@cindex grouping options
97
@cindex options, grouping
98
The @command{gcc} program accepts options and file names as operands.  Many
99
options have multi-letter names; therefore multiple single-letter options
100
may @emph{not} be grouped: @option{-dv} is very different from @w{@samp{-d
101
-v}}.
102
 
103
@cindex order of options
104
@cindex options, order
105
You can mix options and other arguments.  For the most part, the order
106
you use doesn't matter.  Order does matter when you use several
107
options of the same kind; for example, if you specify @option{-L} more
108
than once, the directories are searched in the order specified.  Also,
109
the placement of the @option{-l} option is significant.
110
 
111
Many options have long names starting with @samp{-f} or with
112
@samp{-W}---for example,
113
@option{-fmove-loop-invariants}, @option{-Wformat} and so on.  Most of
114
these have both positive and negative forms; the negative form of
115
@option{-ffoo} would be @option{-fno-foo}.  This manual documents
116
only one of these two forms, whichever one is not the default.
117
 
118
@c man end
119
 
120
@xref{Option Index}, for an index to GCC's options.
121
 
122
@menu
123
* Option Summary::      Brief list of all options, without explanations.
124
* Overall Options::     Controlling the kind of output:
125
                        an executable, object files, assembler files,
126
                        or preprocessed source.
127
* Invoking G++::        Compiling C++ programs.
128
* C Dialect Options::   Controlling the variant of C language compiled.
129
* C++ Dialect Options:: Variations on C++.
130
* Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
131
                        and Objective-C++.
132
* Language Independent Options:: Controlling how diagnostics should be
133
                        formatted.
134
* Warning Options::     How picky should the compiler be?
135
* Debugging Options::   Symbol tables, measurements, and debugging dumps.
136
* Optimize Options::    How much optimization?
137
* Preprocessor Options:: Controlling header files and macro definitions.
138
                         Also, getting dependency information for Make.
139
* Assembler Options::   Passing options to the assembler.
140
* Link Options::        Specifying libraries and so on.
141
* Directory Options::   Where to find header files and libraries.
142
                        Where to find the compiler executable files.
143
* Spec Files::          How to pass switches to sub-processes.
144
* Target Options::      Running a cross-compiler, or an old version of GCC.
145
* Submodel Options::    Specifying minor hardware or convention variations,
146
                        such as 68010 vs 68020.
147
* Code Gen Options::    Specifying conventions for function calls, data layout
148
                        and register usage.
149
* Environment Variables:: Env vars that affect GCC.
150
* Precompiled Headers:: Compiling a header once, and using it many times.
151
@end menu
152
 
153
@c man begin OPTIONS
154
 
155
@node Option Summary
156
@section Option Summary
157
 
158
Here is a summary of all the options, grouped by type.  Explanations are
159
in the following sections.
160
 
161
@table @emph
162
@item Overall Options
163
@xref{Overall Options,,Options Controlling the Kind of Output}.
164
@gccoptlist{-c  -S  -E  -o @var{file}  -combine  -no-canonical-prefixes  @gol
165
-pipe  -pass-exit-codes  @gol
166
-x @var{language}  -v  -###  --help@r{[}=@var{class}@r{[},@dots{}@r{]]}  --target-help  @gol
167
--version -wrapper@@@var{file} -fplugin=@var{file} -fplugin-arg-@var{name}=@var{arg}}
168
 
169
@item C Language Options
170
@xref{C Dialect Options,,Options Controlling C Dialect}.
171
@gccoptlist{-ansi  -std=@var{standard}  -fgnu89-inline @gol
172
-aux-info @var{filename} @gol
173
-fno-asm  -fno-builtin  -fno-builtin-@var{function} @gol
174
-fhosted  -ffreestanding -fopenmp -fms-extensions @gol
175
-trigraphs  -no-integrated-cpp  -traditional  -traditional-cpp @gol
176
-fallow-single-precision  -fcond-mismatch -flax-vector-conversions @gol
177
-fsigned-bitfields  -fsigned-char @gol
178
-funsigned-bitfields  -funsigned-char}
179
 
180
@item C++ Language Options
181
@xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
182
@gccoptlist{-fabi-version=@var{n}  -fno-access-control  -fcheck-new @gol
183
-fconserve-space  -ffriend-injection @gol
184
-fno-elide-constructors @gol
185
-fno-enforce-eh-specs @gol
186
-ffor-scope  -fno-for-scope  -fno-gnu-keywords @gol
187
-fno-implicit-templates @gol
188
-fno-implicit-inline-templates @gol
189
-fno-implement-inlines  -fms-extensions @gol
190
-fno-nonansi-builtins  -fno-operator-names @gol
191
-fno-optional-diags  -fpermissive @gol
192
-fno-pretty-templates @gol
193
-frepo  -fno-rtti  -fstats  -ftemplate-depth=@var{n} @gol
194
-fno-threadsafe-statics -fuse-cxa-atexit  -fno-weak  -nostdinc++ @gol
195
-fno-default-inline  -fvisibility-inlines-hidden @gol
196
-fvisibility-ms-compat @gol
197
-Wabi  -Wconversion-null  -Wctor-dtor-privacy @gol
198
-Wnon-virtual-dtor  -Wreorder @gol
199
-Weffc++  -Wstrict-null-sentinel @gol
200
-Wno-non-template-friend  -Wold-style-cast @gol
201
-Woverloaded-virtual  -Wno-pmf-conversions @gol
202
-Wsign-promo}
203
 
204
@item Objective-C and Objective-C++ Language Options
205
@xref{Objective-C and Objective-C++ Dialect Options,,Options Controlling
206
Objective-C and Objective-C++ Dialects}.
207
@gccoptlist{-fconstant-string-class=@var{class-name} @gol
208
-fgnu-runtime  -fnext-runtime @gol
209
-fno-nil-receivers @gol
210
-fobjc-call-cxx-cdtors @gol
211
-fobjc-direct-dispatch @gol
212
-fobjc-exceptions @gol
213
-fobjc-gc @gol
214
-freplace-objc-classes @gol
215
-fzero-link @gol
216
-gen-decls @gol
217
-Wassign-intercept @gol
218
-Wno-protocol  -Wselector @gol
219
-Wstrict-selector-match @gol
220
-Wundeclared-selector}
221
 
222
@item Language Independent Options
223
@xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}.
224
@gccoptlist{-fmessage-length=@var{n}  @gol
225
-fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]}  @gol
226
-fdiagnostics-show-option}
227
 
228
@item Warning Options
229
@xref{Warning Options,,Options to Request or Suppress Warnings}.
230
@gccoptlist{-fsyntax-only  -pedantic  -pedantic-errors @gol
231
-w  -Wextra  -Wall  -Waddress  -Waggregate-return  -Warray-bounds @gol
232
-Wno-attributes -Wno-builtin-macro-redefined @gol
233
-Wc++-compat -Wc++0x-compat -Wcast-align  -Wcast-qual  @gol
234
-Wchar-subscripts -Wclobbered  -Wcomment @gol
235
-Wconversion  -Wcoverage-mismatch  -Wno-deprecated  @gol
236
-Wno-deprecated-declarations -Wdisabled-optimization  @gol
237
-Wno-div-by-zero -Wempty-body  -Wenum-compare -Wno-endif-labels @gol
238
-Werror  -Werror=* @gol
239
-Wfatal-errors  -Wfloat-equal  -Wformat  -Wformat=2 @gol
240
-Wno-format-contains-nul -Wno-format-extra-args -Wformat-nonliteral @gol
241
-Wformat-security  -Wformat-y2k @gol
242
-Wframe-larger-than=@var{len} -Wjump-misses-init -Wignored-qualifiers @gol
243
-Wimplicit  -Wimplicit-function-declaration  -Wimplicit-int @gol
244
-Winit-self  -Winline @gol
245
-Wno-int-to-pointer-cast -Wno-invalid-offsetof @gol
246
-Winvalid-pch -Wlarger-than=@var{len}  -Wunsafe-loop-optimizations @gol
247
-Wlogical-op -Wlong-long @gol
248
-Wmain  -Wmissing-braces  -Wmissing-field-initializers @gol
249
-Wmissing-format-attribute  -Wmissing-include-dirs @gol
250
-Wmissing-noreturn  -Wno-mudflap @gol
251
-Wno-multichar  -Wnonnull  -Wno-overflow @gol
252
-Woverlength-strings  -Wpacked  -Wpacked-bitfield-compat  -Wpadded @gol
253
-Wparentheses  -Wpedantic-ms-format -Wno-pedantic-ms-format @gol
254
-Wpointer-arith  -Wno-pointer-to-int-cast @gol
255
-Wredundant-decls @gol
256
-Wreturn-type  -Wsequence-point  -Wshadow @gol
257
-Wsign-compare  -Wsign-conversion  -Wstack-protector @gol
258
-Wstrict-aliasing -Wstrict-aliasing=n @gol
259
-Wstrict-overflow -Wstrict-overflow=@var{n} @gol
260
-Wswitch  -Wswitch-default  -Wswitch-enum -Wsync-nand @gol
261
-Wsystem-headers  -Wtrigraphs  -Wtype-limits  -Wundef  -Wuninitialized @gol
262
-Wunknown-pragmas  -Wno-pragmas @gol
263
-Wunsuffixed-float-constants  -Wunused  -Wunused-function @gol
264
-Wunused-label  -Wunused-parameter -Wno-unused-result -Wunused-value  -Wunused-variable @gol
265
-Wvariadic-macros -Wvla @gol
266
-Wvolatile-register-var  -Wwrite-strings}
267
 
268
@item C and Objective-C-only Warning Options
269
@gccoptlist{-Wbad-function-cast  -Wmissing-declarations @gol
270
-Wmissing-parameter-type  -Wmissing-prototypes  -Wnested-externs @gol
271
-Wold-style-declaration  -Wold-style-definition @gol
272
-Wstrict-prototypes  -Wtraditional  -Wtraditional-conversion @gol
273
-Wdeclaration-after-statement -Wpointer-sign}
274
 
275
@item Debugging Options
276
@xref{Debugging Options,,Options for Debugging Your Program or GCC}.
277
@gccoptlist{-d@var{letters}  -dumpspecs  -dumpmachine  -dumpversion @gol
278
-fdbg-cnt-list -fdbg-cnt=@var{counter-value-list} @gol
279
-fdump-noaddr -fdump-unnumbered -fdump-unnumbered-links @gol
280
-fdump-translation-unit@r{[}-@var{n}@r{]} @gol
281
-fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
282
-fdump-ipa-all -fdump-ipa-cgraph -fdump-ipa-inline @gol
283
-fdump-statistics @gol
284
-fdump-tree-all @gol
285
-fdump-tree-original@r{[}-@var{n}@r{]}  @gol
286
-fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
287
-fdump-tree-cfg -fdump-tree-vcg -fdump-tree-alias @gol
288
-fdump-tree-ch @gol
289
-fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol
290
-fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol
291
-fdump-tree-gimple@r{[}-raw@r{]} -fdump-tree-mudflap@r{[}-@var{n}@r{]} @gol
292
-fdump-tree-dom@r{[}-@var{n}@r{]} @gol
293
-fdump-tree-dse@r{[}-@var{n}@r{]} @gol
294
-fdump-tree-phiprop@r{[}-@var{n}@r{]} @gol
295
-fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol
296
-fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
297
-fdump-tree-copyrename@r{[}-@var{n}@r{]} @gol
298
-fdump-tree-nrv -fdump-tree-vect @gol
299
-fdump-tree-sink @gol
300
-fdump-tree-sra@r{[}-@var{n}@r{]} @gol
301
-fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
302
-fdump-tree-fre@r{[}-@var{n}@r{]} @gol
303
-fdump-tree-vrp@r{[}-@var{n}@r{]} @gol
304
-ftree-vectorizer-verbose=@var{n} @gol
305
-fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol
306
-fdump-final-insns=@var{file} @gol
307
-fcompare-debug@r{[}=@var{opts}@r{]}  -fcompare-debug-second @gol
308
-feliminate-dwarf2-dups -feliminate-unused-debug-types @gol
309
-feliminate-unused-debug-symbols -femit-class-debug-always @gol
310
-fenable-icf-debug @gol
311
-fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report -fprofile-arcs @gol
312
-frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
313
-fsel-sched-verbose -fsel-sched-dump-cfg -fsel-sched-pipelining-verbose @gol
314
-ftest-coverage  -ftime-report -fvar-tracking @gol
315
-fvar-tracking-assignments  -fvar-tracking-assignments-toggle @gol
316
-g  -g@var{level}  -gtoggle  -gcoff  -gdwarf-@var{version} @gol
317
-ggdb  -gstabs  -gstabs+  -gstrict-dwarf  -gno-strict-dwarf @gol
318
-gvms  -gxcoff  -gxcoff+ @gol
319
-fno-merge-debug-strings -fno-dwarf2-cfi-asm @gol
320
-fdebug-prefix-map=@var{old}=@var{new} @gol
321
-femit-struct-debug-baseonly -femit-struct-debug-reduced @gol
322
-femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} @gol
323
-p  -pg  -print-file-name=@var{library}  -print-libgcc-file-name @gol
324
-print-multi-directory  -print-multi-lib  -print-multi-os-directory @gol
325
-print-prog-name=@var{program}  -print-search-dirs  -Q @gol
326
-print-sysroot -print-sysroot-headers-suffix @gol
327
-save-temps -save-temps=cwd -save-temps=obj -time@r{[}=@var{file}@r{]}}
328
 
329
@item Optimization Options
330
@xref{Optimize Options,,Options that Control Optimization}.
331
@gccoptlist{
332
-falign-functions[=@var{n}] -falign-jumps[=@var{n}] @gol
333
-falign-labels[=@var{n}] -falign-loops[=@var{n}] -fassociative-math @gol
334
-fauto-inc-dec -fbranch-probabilities -fbranch-target-load-optimize @gol
335
-fbranch-target-load-optimize2 -fbtr-bb-exclusive -fcaller-saves @gol
336
-fcheck-data-deps -fconserve-stack -fcprop-registers -fcrossjumping @gol
337
-fcse-follow-jumps -fcse-skip-blocks -fcx-fortran-rules -fcx-limited-range @gol
338
-fdata-sections -fdce -fdce @gol
339
-fdelayed-branch -fdelete-null-pointer-checks -fdse -fdse @gol
340
-fearly-inlining -fipa-sra -fexpensive-optimizations -ffast-math @gol
341
-ffinite-math-only -ffloat-store -fexcess-precision=@var{style} @gol
342
-fforward-propagate -ffunction-sections @gol
343
-fgcse -fgcse-after-reload -fgcse-las -fgcse-lm @gol
344
-fgcse-sm -fif-conversion -fif-conversion2 -findirect-inlining @gol
345
-finline-functions -finline-functions-called-once -finline-limit=@var{n} @gol
346
-finline-small-functions -fipa-cp -fipa-cp-clone -fipa-matrix-reorg -fipa-pta @gol
347
-fipa-pure-const -fipa-reference -fipa-struct-reorg @gol
348
-fipa-type-escape -fira-algorithm=@var{algorithm} @gol
349
-fira-region=@var{region} -fira-coalesce @gol
350
-fira-loop-pressure -fno-ira-share-save-slots @gol
351
-fno-ira-share-spill-slots -fira-verbose=@var{n} @gol
352
-fivopts -fkeep-inline-functions -fkeep-static-consts @gol
353
-floop-block -floop-interchange -floop-strip-mine -fgraphite-identity @gol
354
-floop-parallelize-all -flto -flto-compression-level -flto-report -fltrans @gol
355
-fltrans-output-list -fmerge-all-constants -fmerge-constants -fmodulo-sched @gol
356
-fmodulo-sched-allow-regmoves -fmove-loop-invariants -fmudflap @gol
357
-fmudflapir -fmudflapth -fno-branch-count-reg -fno-default-inline @gol
358
-fno-defer-pop -fno-function-cse -fno-guess-branch-probability @gol
359
-fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol
360
-fno-sched-interblock -fno-sched-spec -fno-signed-zeros @gol
361
-fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol
362
-fomit-frame-pointer -foptimize-register-move -foptimize-sibling-calls @gol
363
-fpeel-loops -fpredictive-commoning -fprefetch-loop-arrays @gol
364
-fprofile-correction -fprofile-dir=@var{path} -fprofile-generate @gol
365
-fprofile-generate=@var{path} @gol
366
-fprofile-use -fprofile-use=@var{path} -fprofile-values @gol
367
-freciprocal-math -fregmove -frename-registers -freorder-blocks @gol
368
-freorder-blocks-and-partition -freorder-functions @gol
369
-frerun-cse-after-loop -freschedule-modulo-scheduled-loops @gol
370
-frounding-math -fsched2-use-superblocks -fsched-pressure @gol
371
-fsched-spec-load -fsched-spec-load-dangerous @gol
372
-fsched-stalled-insns-dep[=@var{n}] -fsched-stalled-insns[=@var{n}] @gol
373
-fsched-group-heuristic -fsched-critical-path-heuristic @gol
374
-fsched-spec-insn-heuristic -fsched-rank-heuristic @gol
375
-fsched-last-insn-heuristic -fsched-dep-count-heuristic @gol
376
-fschedule-insns -fschedule-insns2 -fsection-anchors @gol
377
-fselective-scheduling -fselective-scheduling2 @gol
378
-fsel-sched-pipelining -fsel-sched-pipelining-outer-loops @gol
379
-fsignaling-nans -fsingle-precision-constant -fsplit-ivs-in-unroller @gol
380
-fsplit-wide-types -fstack-protector -fstack-protector-all @gol
381
-fstrict-aliasing -fstrict-overflow -fthread-jumps -ftracer @gol
382
-ftree-builtin-call-dce -ftree-ccp -ftree-ch -ftree-copy-prop @gol
383
-ftree-copyrename -ftree-dce @gol
384
-ftree-dominator-opts -ftree-dse -ftree-forwprop -ftree-fre -ftree-loop-im @gol
385
-ftree-phiprop -ftree-loop-distribution @gol
386
-ftree-loop-ivcanon -ftree-loop-linear -ftree-loop-optimize @gol
387
-ftree-parallelize-loops=@var{n} -ftree-pre -ftree-pta -ftree-reassoc @gol
388
-ftree-sink -ftree-sra -ftree-switch-conversion @gol
389
-ftree-ter -ftree-vect-loop-version -ftree-vectorize -ftree-vrp @gol
390
-funit-at-a-time -funroll-all-loops -funroll-loops @gol
391
-funsafe-loop-optimizations -funsafe-math-optimizations -funswitch-loops @gol
392
-fvariable-expansion-in-unroller -fvect-cost-model -fvpt -fweb @gol
393
-fwhole-program -fwhopr -fwpa -fuse-linker-plugin @gol
394
--param @var{name}=@var{value}
395
-O  -O0  -O1  -O2  -O3  -Os}
396
 
397
@item Preprocessor Options
398
@xref{Preprocessor Options,,Options Controlling the Preprocessor}.
399
@gccoptlist{-A@var{question}=@var{answer} @gol
400
-A-@var{question}@r{[}=@var{answer}@r{]} @gol
401
-C  -dD  -dI  -dM  -dN @gol
402
-D@var{macro}@r{[}=@var{defn}@r{]}  -E  -H @gol
403
-idirafter @var{dir} @gol
404
-include @var{file}  -imacros @var{file} @gol
405
-iprefix @var{file}  -iwithprefix @var{dir} @gol
406
-iwithprefixbefore @var{dir}  -isystem @var{dir} @gol
407
-imultilib @var{dir} -isysroot @var{dir} @gol
408
-M  -MM  -MF  -MG  -MP  -MQ  -MT  -nostdinc  @gol
409
-P  -fworking-directory  -remap @gol
410
-trigraphs  -undef  -U@var{macro}  -Wp,@var{option} @gol
411
-Xpreprocessor @var{option}}
412
 
413
@item Assembler Option
414
@xref{Assembler Options,,Passing Options to the Assembler}.
415
@gccoptlist{-Wa,@var{option}  -Xassembler @var{option}}
416
 
417
@item Linker Options
418
@xref{Link Options,,Options for Linking}.
419
@gccoptlist{@var{object-file-name}  -l@var{library} @gol
420
-nostartfiles  -nodefaultlibs  -nostdlib -pie -rdynamic @gol
421
-s  -static  -static-libgcc  -static-libstdc++ -shared  @gol
422
-shared-libgcc  -symbolic @gol
423
-T @var{script}  -Wl,@var{option}  -Xlinker @var{option} @gol
424
-u @var{symbol}}
425
 
426
@item Directory Options
427
@xref{Directory Options,,Options for Directory Search}.
428
@gccoptlist{-B@var{prefix}  -I@var{dir}  -iquote@var{dir}  -L@var{dir}
429
-specs=@var{file}  -I- --sysroot=@var{dir}}
430
 
431
@item Target Options
432
@c I wrote this xref this way to avoid overfull hbox. -- rms
433
@xref{Target Options}.
434
@gccoptlist{-V @var{version}  -b @var{machine}}
435
 
436
@item Machine Dependent Options
437
@xref{Submodel Options,,Hardware Models and Configurations}.
438
@c This list is ordered alphanumerically by subsection name.
439
@c Try and put the significant identifier (CPU or system) first,
440
@c so users have a clue at guessing where the ones they want will be.
441
 
442
@emph{ARC Options}
443
@gccoptlist{-EB  -EL @gol
444
-mmangle-cpu  -mcpu=@var{cpu}  -mtext=@var{text-section} @gol
445
-mdata=@var{data-section}  -mrodata=@var{readonly-data-section}}
446
 
447
@emph{ARM Options}
448
@gccoptlist{-mapcs-frame  -mno-apcs-frame @gol
449
-mabi=@var{name} @gol
450
-mapcs-stack-check  -mno-apcs-stack-check @gol
451
-mapcs-float  -mno-apcs-float @gol
452
-mapcs-reentrant  -mno-apcs-reentrant @gol
453
-msched-prolog  -mno-sched-prolog @gol
454
-mlittle-endian  -mbig-endian  -mwords-little-endian @gol
455
-mfloat-abi=@var{name}  -msoft-float  -mhard-float  -mfpe @gol
456
-mfp16-format=@var{name}
457
-mthumb-interwork  -mno-thumb-interwork @gol
458
-mcpu=@var{name}  -march=@var{name}  -mfpu=@var{name}  @gol
459
-mstructure-size-boundary=@var{n} @gol
460
-mabort-on-noreturn @gol
461
-mlong-calls  -mno-long-calls @gol
462
-msingle-pic-base  -mno-single-pic-base @gol
463
-mpic-register=@var{reg} @gol
464
-mnop-fun-dllimport @gol
465
-mcirrus-fix-invalid-insns -mno-cirrus-fix-invalid-insns @gol
466
-mpoke-function-name @gol
467
-mthumb  -marm @gol
468
-mtpcs-frame  -mtpcs-leaf-frame @gol
469
-mcaller-super-interworking  -mcallee-super-interworking @gol
470
-mtp=@var{name} @gol
471
-mword-relocations @gol
472
-mfix-cortex-m3-ldrd}
473
 
474
@emph{AVR Options}
475
@gccoptlist{-mmcu=@var{mcu}  -mno-interrupts @gol
476
-mcall-prologues  -mtiny-stack  -mint8}
477
 
478
@emph{Blackfin Options}
479
@gccoptlist{-mcpu=@var{cpu}@r{[}-@var{sirevision}@r{]} @gol
480
-msim -momit-leaf-frame-pointer  -mno-omit-leaf-frame-pointer @gol
481
-mspecld-anomaly  -mno-specld-anomaly  -mcsync-anomaly  -mno-csync-anomaly @gol
482
-mlow-64k -mno-low64k  -mstack-check-l1  -mid-shared-library @gol
483
-mno-id-shared-library  -mshared-library-id=@var{n} @gol
484
-mleaf-id-shared-library  -mno-leaf-id-shared-library @gol
485
-msep-data  -mno-sep-data  -mlong-calls  -mno-long-calls @gol
486
-mfast-fp -minline-plt -mmulticore  -mcorea  -mcoreb  -msdram @gol
487
-micplb}
488
 
489
@emph{CRIS Options}
490
@gccoptlist{-mcpu=@var{cpu}  -march=@var{cpu}  -mtune=@var{cpu} @gol
491
-mmax-stack-frame=@var{n}  -melinux-stacksize=@var{n} @gol
492
-metrax4  -metrax100  -mpdebug  -mcc-init  -mno-side-effects @gol
493
-mstack-align  -mdata-align  -mconst-align @gol
494
-m32-bit  -m16-bit  -m8-bit  -mno-prologue-epilogue  -mno-gotplt @gol
495
-melf  -maout  -melinux  -mlinux  -sim  -sim2 @gol
496
-mmul-bug-workaround  -mno-mul-bug-workaround}
497
 
498
@emph{CRX Options}
499
@gccoptlist{-mmac -mpush-args}
500
 
501
@emph{Darwin Options}
502
@gccoptlist{-all_load  -allowable_client  -arch  -arch_errors_fatal @gol
503
-arch_only  -bind_at_load  -bundle  -bundle_loader @gol
504
-client_name  -compatibility_version  -current_version @gol
505
-dead_strip @gol
506
-dependency-file  -dylib_file  -dylinker_install_name @gol
507
-dynamic  -dynamiclib  -exported_symbols_list @gol
508
-filelist  -flat_namespace  -force_cpusubtype_ALL @gol
509
-force_flat_namespace  -headerpad_max_install_names @gol
510
-iframework @gol
511
-image_base  -init  -install_name  -keep_private_externs @gol
512
-multi_module  -multiply_defined  -multiply_defined_unused @gol
513
-noall_load   -no_dead_strip_inits_and_terms @gol
514
-nofixprebinding -nomultidefs  -noprebind  -noseglinkedit @gol
515
-pagezero_size  -prebind  -prebind_all_twolevel_modules @gol
516
-private_bundle  -read_only_relocs  -sectalign @gol
517
-sectobjectsymbols  -whyload  -seg1addr @gol
518
-sectcreate  -sectobjectsymbols  -sectorder @gol
519
-segaddr -segs_read_only_addr -segs_read_write_addr @gol
520
-seg_addr_table  -seg_addr_table_filename  -seglinkedit @gol
521
-segprot  -segs_read_only_addr  -segs_read_write_addr @gol
522
-single_module  -static  -sub_library  -sub_umbrella @gol
523
-twolevel_namespace  -umbrella  -undefined @gol
524
-unexported_symbols_list  -weak_reference_mismatches @gol
525
-whatsloaded -F -gused -gfull -mmacosx-version-min=@var{version} @gol
526
-mkernel -mone-byte-bool}
527
 
528
@emph{DEC Alpha Options}
529
@gccoptlist{-mno-fp-regs  -msoft-float  -malpha-as  -mgas @gol
530
-mieee  -mieee-with-inexact  -mieee-conformant @gol
531
-mfp-trap-mode=@var{mode}  -mfp-rounding-mode=@var{mode} @gol
532
-mtrap-precision=@var{mode}  -mbuild-constants @gol
533
-mcpu=@var{cpu-type}  -mtune=@var{cpu-type} @gol
534
-mbwx  -mmax  -mfix  -mcix @gol
535
-mfloat-vax  -mfloat-ieee @gol
536
-mexplicit-relocs  -msmall-data  -mlarge-data @gol
537
-msmall-text  -mlarge-text @gol
538
-mmemory-latency=@var{time}}
539
 
540
@emph{DEC Alpha/VMS Options}
541
@gccoptlist{-mvms-return-codes -mdebug-main=@var{prefix} -mmalloc64}
542
 
543
@emph{FR30 Options}
544
@gccoptlist{-msmall-model -mno-lsim}
545
 
546
@emph{FRV Options}
547
@gccoptlist{-mgpr-32  -mgpr-64  -mfpr-32  -mfpr-64 @gol
548
-mhard-float  -msoft-float @gol
549
-malloc-cc  -mfixed-cc  -mdword  -mno-dword @gol
550
-mdouble  -mno-double @gol
551
-mmedia  -mno-media  -mmuladd  -mno-muladd @gol
552
-mfdpic  -minline-plt -mgprel-ro  -multilib-library-pic @gol
553
-mlinked-fp  -mlong-calls  -malign-labels @gol
554
-mlibrary-pic  -macc-4  -macc-8 @gol
555
-mpack  -mno-pack  -mno-eflags  -mcond-move  -mno-cond-move @gol
556
-moptimize-membar -mno-optimize-membar @gol
557
-mscc  -mno-scc  -mcond-exec  -mno-cond-exec @gol
558
-mvliw-branch  -mno-vliw-branch @gol
559
-mmulti-cond-exec  -mno-multi-cond-exec  -mnested-cond-exec @gol
560
-mno-nested-cond-exec  -mtomcat-stats @gol
561
-mTLS -mtls @gol
562
-mcpu=@var{cpu}}
563
 
564
@emph{GNU/Linux Options}
565
@gccoptlist{-muclibc}
566
 
567
@emph{H8/300 Options}
568
@gccoptlist{-mrelax  -mh  -ms  -mn  -mint32  -malign-300}
569
 
570
@emph{HPPA Options}
571
@gccoptlist{-march=@var{architecture-type} @gol
572
-mbig-switch  -mdisable-fpregs  -mdisable-indexing @gol
573
-mfast-indirect-calls  -mgas  -mgnu-ld   -mhp-ld @gol
574
-mfixed-range=@var{register-range} @gol
575
-mjump-in-delay -mlinker-opt -mlong-calls @gol
576
-mlong-load-store  -mno-big-switch  -mno-disable-fpregs @gol
577
-mno-disable-indexing  -mno-fast-indirect-calls  -mno-gas @gol
578
-mno-jump-in-delay  -mno-long-load-store @gol
579
-mno-portable-runtime  -mno-soft-float @gol
580
-mno-space-regs  -msoft-float  -mpa-risc-1-0 @gol
581
-mpa-risc-1-1  -mpa-risc-2-0  -mportable-runtime @gol
582
-mschedule=@var{cpu-type}  -mspace-regs  -msio  -mwsio @gol
583
-munix=@var{unix-std}  -nolibdld  -static  -threads}
584
 
585
@emph{i386 and x86-64 Options}
586
@gccoptlist{-mtune=@var{cpu-type}  -march=@var{cpu-type} @gol
587
-mfpmath=@var{unit} @gol
588
-masm=@var{dialect}  -mno-fancy-math-387 @gol
589
-mno-fp-ret-in-387  -msoft-float @gol
590
-mno-wide-multiply  -mrtd  -malign-double @gol
591
-mpreferred-stack-boundary=@var{num}
592
-mincoming-stack-boundary=@var{num}
593
-mcld -mcx16 -msahf -mmovbe -mcrc32 -mrecip @gol
594
-mmmx  -msse  -msse2 -msse3 -mssse3 -msse4.1 -msse4.2 -msse4 -mavx @gol
595
-maes -mpclmul -mfused-madd @gol
596
-msse4a -m3dnow -mpopcnt -mabm -mfma4 -mxop -mlwp @gol
597
-mthreads  -mno-align-stringops  -minline-all-stringops @gol
598
-minline-stringops-dynamically -mstringop-strategy=@var{alg} @gol
599
-mpush-args  -maccumulate-outgoing-args  -m128bit-long-double @gol
600
-m96bit-long-double  -mregparm=@var{num}  -msseregparm @gol
601
-mveclibabi=@var{type} -mpc32 -mpc64 -mpc80 -mstackrealign @gol
602
-momit-leaf-frame-pointer  -mno-red-zone -mno-tls-direct-seg-refs @gol
603
-mcmodel=@var{code-model} -mabi=@var{name} @gol
604
-m32  -m64 -mlarge-data-threshold=@var{num} @gol
605
-msse2avx}
606
 
607
@emph{IA-64 Options}
608
@gccoptlist{-mbig-endian  -mlittle-endian  -mgnu-as  -mgnu-ld  -mno-pic @gol
609
-mvolatile-asm-stop  -mregister-names  -msdata -mno-sdata @gol
610
-mconstant-gp  -mauto-pic  -mfused-madd @gol
611
-minline-float-divide-min-latency @gol
612
-minline-float-divide-max-throughput @gol
613
-mno-inline-float-divide @gol
614
-minline-int-divide-min-latency @gol
615
-minline-int-divide-max-throughput  @gol
616
-mno-inline-int-divide @gol
617
-minline-sqrt-min-latency -minline-sqrt-max-throughput @gol
618
-mno-inline-sqrt @gol
619
-mdwarf2-asm -mearly-stop-bits @gol
620
-mfixed-range=@var{register-range} -mtls-size=@var{tls-size} @gol
621
-mtune=@var{cpu-type} -milp32 -mlp64 @gol
622
-msched-br-data-spec -msched-ar-data-spec -msched-control-spec @gol
623
-msched-br-in-data-spec -msched-ar-in-data-spec -msched-in-control-spec @gol
624
-msched-spec-ldc -msched-spec-control-ldc @gol
625
-msched-prefer-non-data-spec-insns -msched-prefer-non-control-spec-insns @gol
626
-msched-stop-bits-after-every-cycle -msched-count-spec-in-critical-path @gol
627
-msel-sched-dont-check-control-spec -msched-fp-mem-deps-zero-cost @gol
628
-msched-max-memory-insns-hard-limit -msched-max-memory-insns=@var{max-insns}}
629
 
630
@emph{IA-64/VMS Options}
631
@gccoptlist{-mvms-return-codes -mdebug-main=@var{prefix} -mmalloc64}
632
 
633
@emph{LM32 Options}
634
@gccoptlist{-mbarrel-shift-enabled -mdivide-enabled -mmultiply-enabled @gol
635
-msign-extend-enabled -muser-enabled}
636
 
637
@emph{M32R/D Options}
638
@gccoptlist{-m32r2 -m32rx -m32r @gol
639
-mdebug @gol
640
-malign-loops -mno-align-loops @gol
641
-missue-rate=@var{number} @gol
642
-mbranch-cost=@var{number} @gol
643
-mmodel=@var{code-size-model-type} @gol
644
-msdata=@var{sdata-type} @gol
645
-mno-flush-func -mflush-func=@var{name} @gol
646
-mno-flush-trap -mflush-trap=@var{number} @gol
647
-G @var{num}}
648
 
649
@emph{M32C Options}
650
@gccoptlist{-mcpu=@var{cpu} -msim -memregs=@var{number}}
651
 
652
@emph{M680x0 Options}
653
@gccoptlist{-march=@var{arch}  -mcpu=@var{cpu}  -mtune=@var{tune}
654
-m68000  -m68020  -m68020-40  -m68020-60  -m68030  -m68040 @gol
655
-m68060  -mcpu32  -m5200  -m5206e  -m528x  -m5307  -m5407 @gol
656
-mcfv4e  -mbitfield  -mno-bitfield  -mc68000  -mc68020 @gol
657
-mnobitfield  -mrtd  -mno-rtd  -mdiv  -mno-div  -mshort @gol
658
-mno-short  -mhard-float  -m68881  -msoft-float  -mpcrel @gol
659
-malign-int  -mstrict-align  -msep-data  -mno-sep-data @gol
660
-mshared-library-id=n  -mid-shared-library  -mno-id-shared-library @gol
661
-mxgot -mno-xgot}
662
 
663
@emph{M68hc1x Options}
664
@gccoptlist{-m6811  -m6812  -m68hc11  -m68hc12   -m68hcs12 @gol
665
-mauto-incdec  -minmax  -mlong-calls  -mshort @gol
666
-msoft-reg-count=@var{count}}
667
 
668
@emph{MCore Options}
669
@gccoptlist{-mhardlit  -mno-hardlit  -mdiv  -mno-div  -mrelax-immediates @gol
670
-mno-relax-immediates  -mwide-bitfields  -mno-wide-bitfields @gol
671
-m4byte-functions  -mno-4byte-functions  -mcallgraph-data @gol
672
-mno-callgraph-data  -mslow-bytes  -mno-slow-bytes  -mno-lsim @gol
673
-mlittle-endian  -mbig-endian  -m210  -m340  -mstack-increment}
674
 
675
@emph{MeP Options}
676
@gccoptlist{-mabsdiff -mall-opts -maverage -mbased=@var{n} -mbitops @gol
677
-mc=@var{n} -mclip -mconfig=@var{name} -mcop -mcop32 -mcop64 -mivc2 @gol
678
-mdc -mdiv -meb -mel -mio-volatile -ml -mleadz -mm -mminmax @gol
679
-mmult -mno-opts -mrepeat -ms -msatur -msdram -msim -msimnovec -mtf @gol
680
-mtiny=@var{n}}
681
 
682
@emph{MIPS Options}
683
@gccoptlist{-EL  -EB  -march=@var{arch}  -mtune=@var{arch} @gol
684
-mips1  -mips2  -mips3  -mips4  -mips32  -mips32r2 @gol
685
-mips64  -mips64r2 @gol
686
-mips16  -mno-mips16  -mflip-mips16 @gol
687
-minterlink-mips16  -mno-interlink-mips16 @gol
688
-mabi=@var{abi}  -mabicalls  -mno-abicalls @gol
689
-mshared  -mno-shared  -mplt  -mno-plt  -mxgot  -mno-xgot @gol
690
-mgp32  -mgp64  -mfp32  -mfp64  -mhard-float  -msoft-float @gol
691
-msingle-float  -mdouble-float  -mdsp  -mno-dsp  -mdspr2  -mno-dspr2 @gol
692
-mfpu=@var{fpu-type} @gol
693
-msmartmips  -mno-smartmips @gol
694
-mpaired-single  -mno-paired-single  -mdmx  -mno-mdmx @gol
695
-mips3d  -mno-mips3d  -mmt  -mno-mt  -mllsc  -mno-llsc @gol
696
-mlong64  -mlong32  -msym32  -mno-sym32 @gol
697
-G@var{num}  -mlocal-sdata  -mno-local-sdata @gol
698
-mextern-sdata  -mno-extern-sdata  -mgpopt  -mno-gopt @gol
699
-membedded-data  -mno-embedded-data @gol
700
-muninit-const-in-rodata  -mno-uninit-const-in-rodata @gol
701
-mcode-readable=@var{setting} @gol
702
-msplit-addresses  -mno-split-addresses @gol
703
-mexplicit-relocs  -mno-explicit-relocs @gol
704
-mcheck-zero-division  -mno-check-zero-division @gol
705
-mdivide-traps  -mdivide-breaks @gol
706
-mmemcpy  -mno-memcpy  -mlong-calls  -mno-long-calls @gol
707
-mmad  -mno-mad  -mfused-madd  -mno-fused-madd  -nocpp @gol
708
-mfix-r4000  -mno-fix-r4000  -mfix-r4400  -mno-fix-r4400 @gol
709
-mfix-r10000 -mno-fix-r10000  -mfix-vr4120  -mno-fix-vr4120 @gol
710
-mfix-vr4130  -mno-fix-vr4130  -mfix-sb1  -mno-fix-sb1 @gol
711
-mflush-func=@var{func}  -mno-flush-func @gol
712
-mbranch-cost=@var{num}  -mbranch-likely  -mno-branch-likely @gol
713
-mfp-exceptions -mno-fp-exceptions @gol
714
-mvr4130-align -mno-vr4130-align -msynci -mno-synci @gol
715
-mrelax-pic-calls -mno-relax-pic-calls -mmcount-ra-address}
716
 
717
@emph{MMIX Options}
718
@gccoptlist{-mlibfuncs  -mno-libfuncs  -mepsilon  -mno-epsilon  -mabi=gnu @gol
719
-mabi=mmixware  -mzero-extend  -mknuthdiv  -mtoplevel-symbols @gol
720
-melf  -mbranch-predict  -mno-branch-predict  -mbase-addresses @gol
721
-mno-base-addresses  -msingle-exit  -mno-single-exit}
722
 
723
@emph{MN10300 Options}
724
@gccoptlist{-mmult-bug  -mno-mult-bug @gol
725
-mam33  -mno-am33 @gol
726
-mam33-2  -mno-am33-2 @gol
727
-mreturn-pointer-on-d0 @gol
728
-mno-crt0  -mrelax}
729
 
730
@emph{PDP-11 Options}
731
@gccoptlist{-mfpu  -msoft-float  -mac0  -mno-ac0  -m40  -m45  -m10 @gol
732
-mbcopy  -mbcopy-builtin  -mint32  -mno-int16 @gol
733
-mint16  -mno-int32  -mfloat32  -mno-float64 @gol
734
-mfloat64  -mno-float32  -mabshi  -mno-abshi @gol
735
-mbranch-expensive  -mbranch-cheap @gol
736
-msplit  -mno-split  -munix-asm  -mdec-asm}
737
 
738
@emph{picoChip Options}
739
@gccoptlist{-mae=@var{ae_type} -mvliw-lookahead=@var{N}
740
-msymbol-as-address -mno-inefficient-warnings}
741
 
742
@emph{PowerPC Options}
743
See RS/6000 and PowerPC Options.
744
 
745
@emph{RS/6000 and PowerPC Options}
746
@gccoptlist{-mcpu=@var{cpu-type} @gol
747
-mtune=@var{cpu-type} @gol
748
-mpower  -mno-power  -mpower2  -mno-power2 @gol
749
-mpowerpc  -mpowerpc64  -mno-powerpc @gol
750
-maltivec  -mno-altivec @gol
751
-mpowerpc-gpopt  -mno-powerpc-gpopt @gol
752
-mpowerpc-gfxopt  -mno-powerpc-gfxopt @gol
753
-mmfcrf  -mno-mfcrf  -mpopcntb  -mno-popcntb -mpopcntd -mno-popcntd @gol
754
-mfprnd  -mno-fprnd @gol
755
-mcmpb -mno-cmpb -mmfpgpr -mno-mfpgpr -mhard-dfp -mno-hard-dfp @gol
756
-mnew-mnemonics  -mold-mnemonics @gol
757
-mfull-toc   -mminimal-toc  -mno-fp-in-toc  -mno-sum-in-toc @gol
758
-m64  -m32  -mxl-compat  -mno-xl-compat  -mpe @gol
759
-malign-power  -malign-natural @gol
760
-msoft-float  -mhard-float  -mmultiple  -mno-multiple @gol
761
-msingle-float -mdouble-float -msimple-fpu @gol
762
-mstring  -mno-string  -mupdate  -mno-update @gol
763
-mavoid-indexed-addresses  -mno-avoid-indexed-addresses @gol
764
-mfused-madd  -mno-fused-madd  -mbit-align  -mno-bit-align @gol
765
-mstrict-align  -mno-strict-align  -mrelocatable @gol
766
-mno-relocatable  -mrelocatable-lib  -mno-relocatable-lib @gol
767
-mtoc  -mno-toc  -mlittle  -mlittle-endian  -mbig  -mbig-endian @gol
768
-mdynamic-no-pic  -maltivec -mswdiv @gol
769
-mprioritize-restricted-insns=@var{priority} @gol
770
-msched-costly-dep=@var{dependence_type} @gol
771
-minsert-sched-nops=@var{scheme} @gol
772
-mcall-sysv  -mcall-netbsd @gol
773
-maix-struct-return  -msvr4-struct-return @gol
774
-mabi=@var{abi-type} -msecure-plt -mbss-plt @gol
775
-misel -mno-isel @gol
776
-misel=yes  -misel=no @gol
777
-mspe -mno-spe @gol
778
-mspe=yes  -mspe=no @gol
779
-mpaired @gol
780
-mgen-cell-microcode -mwarn-cell-microcode @gol
781
-mvrsave -mno-vrsave @gol
782
-mmulhw -mno-mulhw @gol
783
-mdlmzb -mno-dlmzb @gol
784
-mfloat-gprs=yes  -mfloat-gprs=no -mfloat-gprs=single -mfloat-gprs=double @gol
785
-mprototype  -mno-prototype @gol
786
-msim  -mmvme  -mads  -myellowknife  -memb  -msdata @gol
787
-msdata=@var{opt}  -mvxworks  -G @var{num}  -pthread}
788
 
789
@emph{RX Options}
790
@gccoptlist{-m64bit-doubles  -m32bit-doubles  -fpu  -nofpu@gol
791
-mcpu= -patch=@gol
792
-mbig-endian-data -mlittle-endian-data @gol
793
-msmall-data @gol
794
-msim  -mno-sim@gol
795
-mas100-syntax -mno-as100-syntax@gol
796
-mrelax@gol
797
-mmax-constant-size=@gol
798
-mint-register=@gol
799
-msave-acc-in-interrupts}
800
 
801
@emph{S/390 and zSeries Options}
802
@gccoptlist{-mtune=@var{cpu-type}  -march=@var{cpu-type} @gol
803
-mhard-float  -msoft-float  -mhard-dfp -mno-hard-dfp @gol
804
-mlong-double-64 -mlong-double-128 @gol
805
-mbackchain  -mno-backchain -mpacked-stack  -mno-packed-stack @gol
806
-msmall-exec  -mno-small-exec  -mmvcle -mno-mvcle @gol
807
-m64  -m31  -mdebug  -mno-debug  -mesa  -mzarch @gol
808
-mtpf-trace -mno-tpf-trace  -mfused-madd  -mno-fused-madd @gol
809
-mwarn-framesize  -mwarn-dynamicstack  -mstack-size -mstack-guard}
810
 
811
@emph{Score Options}
812
@gccoptlist{-meb -mel @gol
813
-mnhwloop @gol
814
-muls @gol
815
-mmac @gol
816
-mscore5 -mscore5u -mscore7 -mscore7d}
817
 
818
@emph{SH Options}
819
@gccoptlist{-m1  -m2  -m2e @gol
820
-m2a-nofpu -m2a-single-only -m2a-single -m2a @gol
821
-m3  -m3e @gol
822
-m4-nofpu  -m4-single-only  -m4-single  -m4 @gol
823
-m4a-nofpu -m4a-single-only -m4a-single -m4a -m4al @gol
824
-m5-64media  -m5-64media-nofpu @gol
825
-m5-32media  -m5-32media-nofpu @gol
826
-m5-compact  -m5-compact-nofpu @gol
827
-mb  -ml  -mdalign  -mrelax @gol
828
-mbigtable -mfmovd -mhitachi -mrenesas -mno-renesas -mnomacsave @gol
829
-mieee  -mbitops  -misize  -minline-ic_invalidate -mpadstruct  -mspace @gol
830
-mprefergot  -musermode -multcost=@var{number} -mdiv=@var{strategy} @gol
831
-mdivsi3_libfunc=@var{name} -mfixed-range=@var{register-range} @gol
832
-madjust-unroll -mindexed-addressing -mgettrcost=@var{number} -mpt-fixed @gol
833
-minvalid-symbols}
834
 
835
@emph{SPARC Options}
836
@gccoptlist{-mcpu=@var{cpu-type} @gol
837
-mtune=@var{cpu-type} @gol
838
-mcmodel=@var{code-model} @gol
839
-m32  -m64  -mapp-regs  -mno-app-regs @gol
840
-mfaster-structs  -mno-faster-structs @gol
841
-mfpu  -mno-fpu  -mhard-float  -msoft-float @gol
842
-mhard-quad-float  -msoft-quad-float @gol
843
-mimpure-text  -mno-impure-text  -mlittle-endian @gol
844
-mstack-bias  -mno-stack-bias @gol
845
-munaligned-doubles  -mno-unaligned-doubles @gol
846
-mv8plus  -mno-v8plus  -mvis  -mno-vis
847
-threads -pthreads -pthread}
848
 
849
@emph{SPU Options}
850
@gccoptlist{-mwarn-reloc -merror-reloc @gol
851
-msafe-dma -munsafe-dma @gol
852
-mbranch-hints @gol
853
-msmall-mem -mlarge-mem -mstdmain @gol
854
-mfixed-range=@var{register-range} @gol
855
-mea32 -mea64 @gol
856
-maddress-space-conversion -mno-address-space-conversion @gol
857
-mcache-size=@var{cache-size} @gol
858
-matomic-updates -mno-atomic-updates}
859
 
860
@emph{System V Options}
861
@gccoptlist{-Qy  -Qn  -YP,@var{paths}  -Ym,@var{dir}}
862
 
863
@emph{V850 Options}
864
@gccoptlist{-mlong-calls  -mno-long-calls  -mep  -mno-ep @gol
865
-mprolog-function  -mno-prolog-function  -mspace @gol
866
-mtda=@var{n}  -msda=@var{n}  -mzda=@var{n} @gol
867
-mapp-regs  -mno-app-regs @gol
868
-mdisable-callt  -mno-disable-callt @gol
869
-mv850e1 @gol
870
-mv850e @gol
871
-mv850  -mbig-switch}
872
 
873
@emph{VAX Options}
874
@gccoptlist{-mg  -mgnu  -munix}
875
 
876
@emph{VxWorks Options}
877
@gccoptlist{-mrtp  -non-static  -Bstatic  -Bdynamic @gol
878
-Xbind-lazy  -Xbind-now}
879
 
880
@emph{x86-64 Options}
881
See i386 and x86-64 Options.
882
 
883
@emph{i386 and x86-64 Windows Options}
884
@gccoptlist{-mconsole -mcygwin -mno-cygwin -mdll
885
-mnop-fun-dllimport -mthread -municode -mwin32 -mwindows
886
-fno-set-stack-executable}
887
 
888
@emph{Xstormy16 Options}
889
@gccoptlist{-msim}
890
 
891
@emph{Xtensa Options}
892
@gccoptlist{-mconst16 -mno-const16 @gol
893
-mfused-madd  -mno-fused-madd @gol
894
-mserialize-volatile  -mno-serialize-volatile @gol
895
-mtext-section-literals  -mno-text-section-literals @gol
896
-mtarget-align  -mno-target-align @gol
897
-mlongcalls  -mno-longcalls}
898
 
899
@emph{zSeries Options}
900
See S/390 and zSeries Options.
901
 
902
@item Code Generation Options
903
@xref{Code Gen Options,,Options for Code Generation Conventions}.
904
@gccoptlist{-fcall-saved-@var{reg}  -fcall-used-@var{reg} @gol
905
-ffixed-@var{reg}  -fexceptions @gol
906
-fnon-call-exceptions  -funwind-tables @gol
907
-fasynchronous-unwind-tables @gol
908
-finhibit-size-directive  -finstrument-functions @gol
909
-finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} @gol
910
-finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{} @gol
911
-fno-common  -fno-ident @gol
912
-fpcc-struct-return  -fpic  -fPIC -fpie -fPIE @gol
913
-fno-jump-tables @gol
914
-frecord-gcc-switches @gol
915
-freg-struct-return  -fshort-enums @gol
916
-fshort-double  -fshort-wchar @gol
917
-fverbose-asm  -fpack-struct[=@var{n}]  -fstack-check @gol
918
-fstack-limit-register=@var{reg}  -fstack-limit-symbol=@var{sym} @gol
919
-fno-stack-limit  -fargument-alias  -fargument-noalias @gol
920
-fargument-noalias-global  -fargument-noalias-anything @gol
921
-fleading-underscore  -ftls-model=@var{model} @gol
922
-ftrapv  -fwrapv  -fbounds-check @gol
923
-fvisibility}
924
@end table
925
 
926
@menu
927
* Overall Options::     Controlling the kind of output:
928
                        an executable, object files, assembler files,
929
                        or preprocessed source.
930
* C Dialect Options::   Controlling the variant of C language compiled.
931
* C++ Dialect Options:: Variations on C++.
932
* Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
933
                        and Objective-C++.
934
* Language Independent Options:: Controlling how diagnostics should be
935
                        formatted.
936
* Warning Options::     How picky should the compiler be?
937
* Debugging Options::   Symbol tables, measurements, and debugging dumps.
938
* Optimize Options::    How much optimization?
939
* Preprocessor Options:: Controlling header files and macro definitions.
940
                         Also, getting dependency information for Make.
941
* Assembler Options::   Passing options to the assembler.
942
* Link Options::        Specifying libraries and so on.
943
* Directory Options::   Where to find header files and libraries.
944
                        Where to find the compiler executable files.
945
* Spec Files::          How to pass switches to sub-processes.
946
* Target Options::      Running a cross-compiler, or an old version of GCC.
947
@end menu
948
 
949
@node Overall Options
950
@section Options Controlling the Kind of Output
951
 
952
Compilation can involve up to four stages: preprocessing, compilation
953
proper, assembly and linking, always in that order.  GCC is capable of
954
preprocessing and compiling several files either into several
955
assembler input files, or into one assembler input file; then each
956
assembler input file produces an object file, and linking combines all
957
the object files (those newly compiled, and those specified as input)
958
into an executable file.
959
 
960
@cindex file name suffix
961
For any given input file, the file name suffix determines what kind of
962
compilation is done:
963
 
964
@table @gcctabopt
965
@item @var{file}.c
966
C source code which must be preprocessed.
967
 
968
@item @var{file}.i
969
C source code which should not be preprocessed.
970
 
971
@item @var{file}.ii
972
C++ source code which should not be preprocessed.
973
 
974
@item @var{file}.m
975
Objective-C source code.  Note that you must link with the @file{libobjc}
976
library to make an Objective-C program work.
977
 
978
@item @var{file}.mi
979
Objective-C source code which should not be preprocessed.
980
 
981
@item @var{file}.mm
982
@itemx @var{file}.M
983
Objective-C++ source code.  Note that you must link with the @file{libobjc}
984
library to make an Objective-C++ program work.  Note that @samp{.M} refers
985
to a literal capital M@.
986
 
987
@item @var{file}.mii
988
Objective-C++ source code which should not be preprocessed.
989
 
990
@item @var{file}.h
991
C, C++, Objective-C or Objective-C++ header file to be turned into a
992
precompiled header.
993
 
994
@item @var{file}.cc
995
@itemx @var{file}.cp
996
@itemx @var{file}.cxx
997
@itemx @var{file}.cpp
998
@itemx @var{file}.CPP
999
@itemx @var{file}.c++
1000
@itemx @var{file}.C
1001
C++ source code which must be preprocessed.  Note that in @samp{.cxx},
1002
the last two letters must both be literally @samp{x}.  Likewise,
1003
@samp{.C} refers to a literal capital C@.
1004
 
1005
@item @var{file}.mm
1006
@itemx @var{file}.M
1007
Objective-C++ source code which must be preprocessed.
1008
 
1009
@item @var{file}.mii
1010
Objective-C++ source code which should not be preprocessed.
1011
 
1012
@item @var{file}.hh
1013
@itemx @var{file}.H
1014
@itemx @var{file}.hp
1015
@itemx @var{file}.hxx
1016
@itemx @var{file}.hpp
1017
@itemx @var{file}.HPP
1018
@itemx @var{file}.h++
1019
@itemx @var{file}.tcc
1020
C++ header file to be turned into a precompiled header.
1021
 
1022
@item @var{file}.f
1023
@itemx @var{file}.for
1024
@itemx @var{file}.ftn
1025
Fixed form Fortran source code which should not be preprocessed.
1026
 
1027
@item @var{file}.F
1028
@itemx @var{file}.FOR
1029
@itemx @var{file}.fpp
1030
@itemx @var{file}.FPP
1031
@itemx @var{file}.FTN
1032
Fixed form Fortran source code which must be preprocessed (with the traditional
1033
preprocessor).
1034
 
1035
@item @var{file}.f90
1036
@itemx @var{file}.f95
1037
@itemx @var{file}.f03
1038
@itemx @var{file}.f08
1039
Free form Fortran source code which should not be preprocessed.
1040
 
1041
@item @var{file}.F90
1042
@itemx @var{file}.F95
1043
@itemx @var{file}.F03
1044
@itemx @var{file}.F08
1045
Free form Fortran source code which must be preprocessed (with the
1046
traditional preprocessor).
1047
 
1048
@c FIXME: Descriptions of Java file types.
1049
@c @var{file}.java
1050
@c @var{file}.class
1051
@c @var{file}.zip
1052
@c @var{file}.jar
1053
 
1054
@item @var{file}.ads
1055
Ada source code file which contains a library unit declaration (a
1056
declaration of a package, subprogram, or generic, or a generic
1057
instantiation), or a library unit renaming declaration (a package,
1058
generic, or subprogram renaming declaration).  Such files are also
1059
called @dfn{specs}.
1060
 
1061
@item @var{file}.adb
1062
Ada source code file containing a library unit body (a subprogram or
1063
package body).  Such files are also called @dfn{bodies}.
1064
 
1065
@c GCC also knows about some suffixes for languages not yet included:
1066
@c Pascal:
1067
@c @var{file}.p
1068
@c @var{file}.pas
1069
@c Ratfor:
1070
@c @var{file}.r
1071
 
1072
@item @var{file}.s
1073
Assembler code.
1074
 
1075
@item @var{file}.S
1076
@itemx @var{file}.sx
1077
Assembler code which must be preprocessed.
1078
 
1079
@item @var{other}
1080
An object file to be fed straight into linking.
1081
Any file name with no recognized suffix is treated this way.
1082
@end table
1083
 
1084
@opindex x
1085
You can specify the input language explicitly with the @option{-x} option:
1086
 
1087
@table @gcctabopt
1088
@item -x @var{language}
1089
Specify explicitly the @var{language} for the following input files
1090
(rather than letting the compiler choose a default based on the file
1091
name suffix).  This option applies to all following input files until
1092
the next @option{-x} option.  Possible values for @var{language} are:
1093
@smallexample
1094
c  c-header  c-cpp-output
1095
c++  c++-header  c++-cpp-output
1096
objective-c  objective-c-header  objective-c-cpp-output
1097
objective-c++ objective-c++-header objective-c++-cpp-output
1098
assembler  assembler-with-cpp
1099
ada
1100
f77  f77-cpp-input f95  f95-cpp-input
1101
java
1102
@end smallexample
1103
 
1104
@item -x none
1105
Turn off any specification of a language, so that subsequent files are
1106
handled according to their file name suffixes (as they are if @option{-x}
1107
has not been used at all).
1108
 
1109
@item -pass-exit-codes
1110
@opindex pass-exit-codes
1111
Normally the @command{gcc} program will exit with the code of 1 if any
1112
phase of the compiler returns a non-success return code.  If you specify
1113
@option{-pass-exit-codes}, the @command{gcc} program will instead return with
1114
numerically highest error produced by any phase that returned an error
1115
indication.  The C, C++, and Fortran frontends return 4, if an internal
1116
compiler error is encountered.
1117
@end table
1118
 
1119
If you only want some of the stages of compilation, you can use
1120
@option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
1121
one of the options @option{-c}, @option{-S}, or @option{-E} to say where
1122
@command{gcc} is to stop.  Note that some combinations (for example,
1123
@samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
1124
 
1125
@table @gcctabopt
1126
@item -c
1127
@opindex c
1128
Compile or assemble the source files, but do not link.  The linking
1129
stage simply is not done.  The ultimate output is in the form of an
1130
object file for each source file.
1131
 
1132
By default, the object file name for a source file is made by replacing
1133
the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
1134
 
1135
Unrecognized input files, not requiring compilation or assembly, are
1136
ignored.
1137
 
1138
@item -S
1139
@opindex S
1140
Stop after the stage of compilation proper; do not assemble.  The output
1141
is in the form of an assembler code file for each non-assembler input
1142
file specified.
1143
 
1144
By default, the assembler file name for a source file is made by
1145
replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
1146
 
1147
Input files that don't require compilation are ignored.
1148
 
1149
@item -E
1150
@opindex E
1151
Stop after the preprocessing stage; do not run the compiler proper.  The
1152
output is in the form of preprocessed source code, which is sent to the
1153
standard output.
1154
 
1155
Input files which don't require preprocessing are ignored.
1156
 
1157
@cindex output file option
1158
@item -o @var{file}
1159
@opindex o
1160
Place output in file @var{file}.  This applies regardless to whatever
1161
sort of output is being produced, whether it be an executable file,
1162
an object file, an assembler file or preprocessed C code.
1163
 
1164
If @option{-o} is not specified, the default is to put an executable
1165
file in @file{a.out}, the object file for
1166
@file{@var{source}.@var{suffix}} in @file{@var{source}.o}, its
1167
assembler file in @file{@var{source}.s}, a precompiled header file in
1168
@file{@var{source}.@var{suffix}.gch}, and all preprocessed C source on
1169
standard output.
1170
 
1171
@item -v
1172
@opindex v
1173
Print (on standard error output) the commands executed to run the stages
1174
of compilation.  Also print the version number of the compiler driver
1175
program and of the preprocessor and the compiler proper.
1176
 
1177
@item -###
1178
@opindex ###
1179
Like @option{-v} except the commands are not executed and all command
1180
arguments are quoted.  This is useful for shell scripts to capture the
1181
driver-generated command lines.
1182
 
1183
@item -pipe
1184
@opindex pipe
1185
Use pipes rather than temporary files for communication between the
1186
various stages of compilation.  This fails to work on some systems where
1187
the assembler is unable to read from a pipe; but the GNU assembler has
1188
no trouble.
1189
 
1190
@item -combine
1191
@opindex combine
1192
If you are compiling multiple source files, this option tells the driver
1193
to pass all the source files to the compiler at once (for those
1194
languages for which the compiler can handle this).  This will allow
1195
intermodule analysis (IMA) to be performed by the compiler.  Currently the only
1196
language for which this is supported is C@.  If you pass source files for
1197
multiple languages to the driver, using this option, the driver will invoke
1198
the compiler(s) that support IMA once each, passing each compiler all the
1199
source files appropriate for it.  For those languages that do not support
1200
IMA this option will be ignored, and the compiler will be invoked once for
1201
each source file in that language.  If you use this option in conjunction
1202
with @option{-save-temps}, the compiler will generate multiple
1203
pre-processed files
1204
(one for each source file), but only one (combined) @file{.o} or
1205
@file{.s} file.
1206
 
1207
@item --help
1208
@opindex help
1209
Print (on the standard output) a description of the command line options
1210
understood by @command{gcc}.  If the @option{-v} option is also specified
1211
then @option{--help} will also be passed on to the various processes
1212
invoked by @command{gcc}, so that they can display the command line options
1213
they accept.  If the @option{-Wextra} option has also been specified
1214
(prior to the @option{--help} option), then command line options which
1215
have no documentation associated with them will also be displayed.
1216
 
1217
@item --target-help
1218
@opindex target-help
1219
Print (on the standard output) a description of target-specific command
1220
line options for each tool.  For some targets extra target-specific
1221
information may also be printed.
1222
 
1223
@item --help=@{@var{class}@r{|[}^@r{]}@var{qualifier}@}@r{[},@dots{}@r{]}
1224
Print (on the standard output) a description of the command line
1225
options understood by the compiler that fit into all specified classes
1226
and qualifiers.  These are the supported classes:
1227
 
1228
@table @asis
1229
@item @samp{optimizers}
1230
This will display all of the optimization options supported by the
1231
compiler.
1232
 
1233
@item @samp{warnings}
1234
This will display all of the options controlling warning messages
1235
produced by the compiler.
1236
 
1237
@item @samp{target}
1238
This will display target-specific options.  Unlike the
1239
@option{--target-help} option however, target-specific options of the
1240
linker and assembler will not be displayed.  This is because those
1241
tools do not currently support the extended @option{--help=} syntax.
1242
 
1243
@item @samp{params}
1244
This will display the values recognized by the @option{--param}
1245
option.
1246
 
1247
@item @var{language}
1248
This will display the options supported for @var{language}, where
1249
@var{language} is the name of one of the languages supported in this
1250
version of GCC.
1251
 
1252
@item @samp{common}
1253
This will display the options that are common to all languages.
1254
@end table
1255
 
1256
These are the supported qualifiers:
1257
 
1258
@table @asis
1259
@item @samp{undocumented}
1260
Display only those options which are undocumented.
1261
 
1262
@item @samp{joined}
1263
Display options which take an argument that appears after an equal
1264
sign in the same continuous piece of text, such as:
1265
@samp{--help=target}.
1266
 
1267
@item @samp{separate}
1268
Display options which take an argument that appears as a separate word
1269
following the original option, such as: @samp{-o output-file}.
1270
@end table
1271
 
1272
Thus for example to display all the undocumented target-specific
1273
switches supported by the compiler the following can be used:
1274
 
1275
@smallexample
1276
--help=target,undocumented
1277
@end smallexample
1278
 
1279
The sense of a qualifier can be inverted by prefixing it with the
1280
@samp{^} character, so for example to display all binary warning
1281
options (i.e., ones that are either on or off and that do not take an
1282
argument), which have a description the following can be used:
1283
 
1284
@smallexample
1285
--help=warnings,^joined,^undocumented
1286
@end smallexample
1287
 
1288
The argument to @option{--help=} should not consist solely of inverted
1289
qualifiers.
1290
 
1291
Combining several classes is possible, although this usually
1292
restricts the output by so much that there is nothing to display.  One
1293
case where it does work however is when one of the classes is
1294
@var{target}.  So for example to display all the target-specific
1295
optimization options the following can be used:
1296
 
1297
@smallexample
1298
--help=target,optimizers
1299
@end smallexample
1300
 
1301
The @option{--help=} option can be repeated on the command line.  Each
1302
successive use will display its requested class of options, skipping
1303
those that have already been displayed.
1304
 
1305
If the @option{-Q} option appears on the command line before the
1306
@option{--help=} option, then the descriptive text displayed by
1307
@option{--help=} is changed.  Instead of describing the displayed
1308
options, an indication is given as to whether the option is enabled,
1309
disabled or set to a specific value (assuming that the compiler
1310
knows this at the point where the @option{--help=} option is used).
1311
 
1312
Here is a truncated example from the ARM port of @command{gcc}:
1313
 
1314
@smallexample
1315
  % gcc -Q -mabi=2 --help=target -c
1316
  The following options are target specific:
1317
  -mabi=                                2
1318
  -mabort-on-noreturn                   [disabled]
1319
  -mapcs                                [disabled]
1320
@end smallexample
1321
 
1322
The output is sensitive to the effects of previous command line
1323
options, so for example it is possible to find out which optimizations
1324
are enabled at @option{-O2} by using:
1325
 
1326
@smallexample
1327
-Q -O2 --help=optimizers
1328
@end smallexample
1329
 
1330
Alternatively you can discover which binary optimizations are enabled
1331
by @option{-O3} by using:
1332
 
1333
@smallexample
1334
gcc -c -Q -O3 --help=optimizers > /tmp/O3-opts
1335
gcc -c -Q -O2 --help=optimizers > /tmp/O2-opts
1336
diff /tmp/O2-opts /tmp/O3-opts | grep enabled
1337
@end smallexample
1338
 
1339
@item -no-canonical-prefixes
1340
@opindex no-canonical-prefixes
1341
Do not expand any symbolic links, resolve references to @samp{/../}
1342
or @samp{/./}, or make the path absolute when generating a relative
1343
prefix.
1344
 
1345
@item --version
1346
@opindex version
1347
Display the version number and copyrights of the invoked GCC@.
1348
 
1349
@item -wrapper
1350
@opindex wrapper
1351
Invoke all subcommands under a wrapper program. It takes a single
1352
comma separated list as an argument, which will be used to invoke
1353
the wrapper:
1354
 
1355
@smallexample
1356
gcc -c t.c -wrapper gdb,--args
1357
@end smallexample
1358
 
1359
This will invoke all subprograms of gcc under "gdb --args",
1360
thus cc1 invocation will be "gdb --args cc1 ...".
1361
 
1362
@item -fplugin=@var{name}.so
1363
Load the plugin code in file @var{name}.so, assumed to be a
1364
shared object to be dlopen'd by the compiler.  The base name of
1365
the shared object file is used to identify the plugin for the
1366
purposes of argument parsing (See
1367
@option{-fplugin-arg-@var{name}-@var{key}=@var{value}} below).
1368
Each plugin should define the callback functions specified in the
1369
Plugins API.
1370
 
1371
@item -fplugin-arg-@var{name}-@var{key}=@var{value}
1372
Define an argument called @var{key} with a value of @var{value}
1373
for the plugin called @var{name}.
1374
 
1375
@include @value{srcdir}/../libiberty/at-file.texi
1376
@end table
1377
 
1378
@node Invoking G++
1379
@section Compiling C++ Programs
1380
 
1381
@cindex suffixes for C++ source
1382
@cindex C++ source file suffixes
1383
C++ source files conventionally use one of the suffixes @samp{.C},
1384
@samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or
1385
@samp{.cxx}; C++ header files often use @samp{.hh}, @samp{.hpp},
1386
@samp{.H}, or (for shared template code) @samp{.tcc}; and
1387
preprocessed C++ files use the suffix @samp{.ii}.  GCC recognizes
1388
files with these names and compiles them as C++ programs even if you
1389
call the compiler the same way as for compiling C programs (usually
1390
with the name @command{gcc}).
1391
 
1392
@findex g++
1393
@findex c++
1394
However, the use of @command{gcc} does not add the C++ library.
1395
@command{g++} is a program that calls GCC and treats @samp{.c},
1396
@samp{.h} and @samp{.i} files as C++ source files instead of C source
1397
files unless @option{-x} is used, and automatically specifies linking
1398
against the C++ library.  This program is also useful when
1399
precompiling a C header file with a @samp{.h} extension for use in C++
1400
compilations.  On many systems, @command{g++} is also installed with
1401
the name @command{c++}.
1402
 
1403
@cindex invoking @command{g++}
1404
When you compile C++ programs, you may specify many of the same
1405
command-line options that you use for compiling programs in any
1406
language; or command-line options meaningful for C and related
1407
languages; or options that are meaningful only for C++ programs.
1408
@xref{C Dialect Options,,Options Controlling C Dialect}, for
1409
explanations of options for languages related to C@.
1410
@xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
1411
explanations of options that are meaningful only for C++ programs.
1412
 
1413
@node C Dialect Options
1414
@section Options Controlling C Dialect
1415
@cindex dialect options
1416
@cindex language dialect options
1417
@cindex options, dialect
1418
 
1419
The following options control the dialect of C (or languages derived
1420
from C, such as C++, Objective-C and Objective-C++) that the compiler
1421
accepts:
1422
 
1423
@table @gcctabopt
1424
@cindex ANSI support
1425
@cindex ISO support
1426
@item -ansi
1427
@opindex ansi
1428
In C mode, this is equivalent to @samp{-std=c90}. In C++ mode, it is
1429
equivalent to @samp{-std=c++98}.
1430
 
1431
This turns off certain features of GCC that are incompatible with ISO
1432
C90 (when compiling C code), or of standard C++ (when compiling C++ code),
1433
such as the @code{asm} and @code{typeof} keywords, and
1434
predefined macros such as @code{unix} and @code{vax} that identify the
1435
type of system you are using.  It also enables the undesirable and
1436
rarely used ISO trigraph feature.  For the C compiler,
1437
it disables recognition of C++ style @samp{//} comments as well as
1438
the @code{inline} keyword.
1439
 
1440
The alternate keywords @code{__asm__}, @code{__extension__},
1441
@code{__inline__} and @code{__typeof__} continue to work despite
1442
@option{-ansi}.  You would not want to use them in an ISO C program, of
1443
course, but it is useful to put them in header files that might be included
1444
in compilations done with @option{-ansi}.  Alternate predefined macros
1445
such as @code{__unix__} and @code{__vax__} are also available, with or
1446
without @option{-ansi}.
1447
 
1448
The @option{-ansi} option does not cause non-ISO programs to be
1449
rejected gratuitously.  For that, @option{-pedantic} is required in
1450
addition to @option{-ansi}.  @xref{Warning Options}.
1451
 
1452
The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
1453
option is used.  Some header files may notice this macro and refrain
1454
from declaring certain functions or defining certain macros that the
1455
ISO standard doesn't call for; this is to avoid interfering with any
1456
programs that might use these names for other things.
1457
 
1458
Functions that would normally be built in but do not have semantics
1459
defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
1460
functions when @option{-ansi} is used.  @xref{Other Builtins,,Other
1461
built-in functions provided by GCC}, for details of the functions
1462
affected.
1463
 
1464
@item -std=
1465
@opindex std
1466
Determine the language standard. @xref{Standards,,Language Standards
1467
Supported by GCC}, for details of these standard versions.  This option
1468
is currently only supported when compiling C or C++.
1469
 
1470
The compiler can accept several base standards, such as @samp{c90} or
1471
@samp{c++98}, and GNU dialects of those standards, such as
1472
@samp{gnu90} or @samp{gnu++98}.  By specifying a base standard, the
1473
compiler will accept all programs following that standard and those
1474
using GNU extensions that do not contradict it.  For example,
1475
@samp{-std=c90} turns off certain features of GCC that are
1476
incompatible with ISO C90, such as the @code{asm} and @code{typeof}
1477
keywords, but not other GNU extensions that do not have a meaning in
1478
ISO C90, such as omitting the middle term of a @code{?:}
1479
expression. On the other hand, by specifying a GNU dialect of a
1480
standard, all features the compiler support are enabled, even when
1481
those features change the meaning of the base standard and some
1482
strict-conforming programs may be rejected.  The particular standard
1483
is used by @option{-pedantic} to identify which features are GNU
1484
extensions given that version of the standard. For example
1485
@samp{-std=gnu90 -pedantic} would warn about C++ style @samp{//}
1486
comments, while @samp{-std=gnu99 -pedantic} would not.
1487
 
1488
A value for this option must be provided; possible values are
1489
 
1490
@table @samp
1491
@item c90
1492
@itemx c89
1493
@itemx iso9899:1990
1494
Support all ISO C90 programs (certain GNU extensions that conflict
1495
with ISO C90 are disabled). Same as @option{-ansi} for C code.
1496
 
1497
@item iso9899:199409
1498
ISO C90 as modified in amendment 1.
1499
 
1500
@item c99
1501
@itemx c9x
1502
@itemx iso9899:1999
1503
@itemx iso9899:199x
1504
ISO C99.  Note that this standard is not yet fully supported; see
1505
@w{@uref{http://gcc.gnu.org/gcc-4.5/c99status.html}} for more information.  The
1506
names @samp{c9x} and @samp{iso9899:199x} are deprecated.
1507
 
1508
@item gnu90
1509
@itemx gnu89
1510
GNU dialect of ISO C90 (including some C99 features). This
1511
is the default for C code.
1512
 
1513
@item gnu99
1514
@itemx gnu9x
1515
GNU dialect of ISO C99.  When ISO C99 is fully implemented in GCC,
1516
this will become the default.  The name @samp{gnu9x} is deprecated.
1517
 
1518
@item c++98
1519
The 1998 ISO C++ standard plus amendments. Same as @option{-ansi} for
1520
C++ code.
1521
 
1522
@item gnu++98
1523
GNU dialect of @option{-std=c++98}.  This is the default for
1524
C++ code.
1525
 
1526
@item c++0x
1527
The working draft of the upcoming ISO C++0x standard. This option
1528
enables experimental features that are likely to be included in
1529
C++0x. The working draft is constantly changing, and any feature that is
1530
enabled by this flag may be removed from future versions of GCC if it is
1531
not part of the C++0x standard.
1532
 
1533
@item gnu++0x
1534
GNU dialect of @option{-std=c++0x}. This option enables
1535
experimental features that may be removed in future versions of GCC.
1536
@end table
1537
 
1538
@item -fgnu89-inline
1539
@opindex fgnu89-inline
1540
The option @option{-fgnu89-inline} tells GCC to use the traditional
1541
GNU semantics for @code{inline} functions when in C99 mode.
1542
@xref{Inline,,An Inline Function is As Fast As a Macro}.  This option
1543
is accepted and ignored by GCC versions 4.1.3 up to but not including
1544
4.3.  In GCC versions 4.3 and later it changes the behavior of GCC in
1545
C99 mode.  Using this option is roughly equivalent to adding the
1546
@code{gnu_inline} function attribute to all inline functions
1547
(@pxref{Function Attributes}).
1548
 
1549
The option @option{-fno-gnu89-inline} explicitly tells GCC to use the
1550
C99 semantics for @code{inline} when in C99 or gnu99 mode (i.e., it
1551
specifies the default behavior).  This option was first supported in
1552
GCC 4.3.  This option is not supported in @option{-std=c90} or
1553
@option{-std=gnu90} mode.
1554
 
1555
The preprocessor macros @code{__GNUC_GNU_INLINE__} and
1556
@code{__GNUC_STDC_INLINE__} may be used to check which semantics are
1557
in effect for @code{inline} functions.  @xref{Common Predefined
1558
Macros,,,cpp,The C Preprocessor}.
1559
 
1560
@item -aux-info @var{filename}
1561
@opindex aux-info
1562
Output to the given filename prototyped declarations for all functions
1563
declared and/or defined in a translation unit, including those in header
1564
files.  This option is silently ignored in any language other than C@.
1565
 
1566
Besides declarations, the file indicates, in comments, the origin of
1567
each declaration (source file and line), whether the declaration was
1568
implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
1569
@samp{O} for old, respectively, in the first character after the line
1570
number and the colon), and whether it came from a declaration or a
1571
definition (@samp{C} or @samp{F}, respectively, in the following
1572
character).  In the case of function definitions, a K&R-style list of
1573
arguments followed by their declarations is also provided, inside
1574
comments, after the declaration.
1575
 
1576
@item -fno-asm
1577
@opindex fno-asm
1578
Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1579
keyword, so that code can use these words as identifiers.  You can use
1580
the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
1581
instead.  @option{-ansi} implies @option{-fno-asm}.
1582
 
1583
In C++, this switch only affects the @code{typeof} keyword, since
1584
@code{asm} and @code{inline} are standard keywords.  You may want to
1585
use the @option{-fno-gnu-keywords} flag instead, which has the same
1586
effect.  In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
1587
switch only affects the @code{asm} and @code{typeof} keywords, since
1588
@code{inline} is a standard keyword in ISO C99.
1589
 
1590
@item -fno-builtin
1591
@itemx -fno-builtin-@var{function}
1592
@opindex fno-builtin
1593
@cindex built-in functions
1594
Don't recognize built-in functions that do not begin with
1595
@samp{__builtin_} as prefix.  @xref{Other Builtins,,Other built-in
1596
functions provided by GCC}, for details of the functions affected,
1597
including those which are not built-in functions when @option{-ansi} or
1598
@option{-std} options for strict ISO C conformance are used because they
1599
do not have an ISO standard meaning.
1600
 
1601
GCC normally generates special code to handle certain built-in functions
1602
more efficiently; for instance, calls to @code{alloca} may become single
1603
instructions that adjust the stack directly, and calls to @code{memcpy}
1604
may become inline copy loops.  The resulting code is often both smaller
1605
and faster, but since the function calls no longer appear as such, you
1606
cannot set a breakpoint on those calls, nor can you change the behavior
1607
of the functions by linking with a different library.  In addition,
1608
when a function is recognized as a built-in function, GCC may use
1609
information about that function to warn about problems with calls to
1610
that function, or to generate more efficient code, even if the
1611
resulting code still contains calls to that function.  For example,
1612
warnings are given with @option{-Wformat} for bad calls to
1613
@code{printf}, when @code{printf} is built in, and @code{strlen} is
1614
known not to modify global memory.
1615
 
1616
With the @option{-fno-builtin-@var{function}} option
1617
only the built-in function @var{function} is
1618
disabled.  @var{function} must not begin with @samp{__builtin_}.  If a
1619
function is named that is not built-in in this version of GCC, this
1620
option is ignored.  There is no corresponding
1621
@option{-fbuiltin-@var{function}} option; if you wish to enable
1622
built-in functions selectively when using @option{-fno-builtin} or
1623
@option{-ffreestanding}, you may define macros such as:
1624
 
1625
@smallexample
1626
#define abs(n)          __builtin_abs ((n))
1627
#define strcpy(d, s)    __builtin_strcpy ((d), (s))
1628
@end smallexample
1629
 
1630
@item -fhosted
1631
@opindex fhosted
1632
@cindex hosted environment
1633
 
1634
Assert that compilation takes place in a hosted environment.  This implies
1635
@option{-fbuiltin}.  A hosted environment is one in which the
1636
entire standard library is available, and in which @code{main} has a return
1637
type of @code{int}.  Examples are nearly everything except a kernel.
1638
This is equivalent to @option{-fno-freestanding}.
1639
 
1640
@item -ffreestanding
1641
@opindex ffreestanding
1642
@cindex hosted environment
1643
 
1644
Assert that compilation takes place in a freestanding environment.  This
1645
implies @option{-fno-builtin}.  A freestanding environment
1646
is one in which the standard library may not exist, and program startup may
1647
not necessarily be at @code{main}.  The most obvious example is an OS kernel.
1648
This is equivalent to @option{-fno-hosted}.
1649
 
1650
@xref{Standards,,Language Standards Supported by GCC}, for details of
1651
freestanding and hosted environments.
1652
 
1653
@item -fopenmp
1654
@opindex fopenmp
1655
@cindex openmp parallel
1656
Enable handling of OpenMP directives @code{#pragma omp} in C/C++ and
1657
@code{!$omp} in Fortran.  When @option{-fopenmp} is specified, the
1658
compiler generates parallel code according to the OpenMP Application
1659
Program Interface v3.0 @w{@uref{http://www.openmp.org/}}.  This option
1660
implies @option{-pthread}, and thus is only supported on targets that
1661
have support for @option{-pthread}.
1662
 
1663
@item -fms-extensions
1664
@opindex fms-extensions
1665
Accept some non-standard constructs used in Microsoft header files.
1666
 
1667
Some cases of unnamed fields in structures and unions are only
1668
accepted with this option.  @xref{Unnamed Fields,,Unnamed struct/union
1669
fields within structs/unions}, for details.
1670
 
1671
@item -trigraphs
1672
@opindex trigraphs
1673
Support ISO C trigraphs.  The @option{-ansi} option (and @option{-std}
1674
options for strict ISO C conformance) implies @option{-trigraphs}.
1675
 
1676
@item -no-integrated-cpp
1677
@opindex no-integrated-cpp
1678
Performs a compilation in two passes: preprocessing and compiling.  This
1679
option allows a user supplied "cc1", "cc1plus", or "cc1obj" via the
1680
@option{-B} option.  The user supplied compilation step can then add in
1681
an additional preprocessing step after normal preprocessing but before
1682
compiling.  The default is to use the integrated cpp (internal cpp)
1683
 
1684
The semantics of this option will change if "cc1", "cc1plus", and
1685
"cc1obj" are merged.
1686
 
1687
@cindex traditional C language
1688
@cindex C language, traditional
1689
@item -traditional
1690
@itemx -traditional-cpp
1691
@opindex traditional-cpp
1692
@opindex traditional
1693
Formerly, these options caused GCC to attempt to emulate a pre-standard
1694
C compiler.  They are now only supported with the @option{-E} switch.
1695
The preprocessor continues to support a pre-standard mode.  See the GNU
1696
CPP manual for details.
1697
 
1698
@item -fcond-mismatch
1699
@opindex fcond-mismatch
1700
Allow conditional expressions with mismatched types in the second and
1701
third arguments.  The value of such an expression is void.  This option
1702
is not supported for C++.
1703
 
1704
@item -flax-vector-conversions
1705
@opindex flax-vector-conversions
1706
Allow implicit conversions between vectors with differing numbers of
1707
elements and/or incompatible element types.  This option should not be
1708
used for new code.
1709
 
1710
@item -funsigned-char
1711
@opindex funsigned-char
1712
Let the type @code{char} be unsigned, like @code{unsigned char}.
1713
 
1714
Each kind of machine has a default for what @code{char} should
1715
be.  It is either like @code{unsigned char} by default or like
1716
@code{signed char} by default.
1717
 
1718
Ideally, a portable program should always use @code{signed char} or
1719
@code{unsigned char} when it depends on the signedness of an object.
1720
But many programs have been written to use plain @code{char} and
1721
expect it to be signed, or expect it to be unsigned, depending on the
1722
machines they were written for.  This option, and its inverse, let you
1723
make such a program work with the opposite default.
1724
 
1725
The type @code{char} is always a distinct type from each of
1726
@code{signed char} or @code{unsigned char}, even though its behavior
1727
is always just like one of those two.
1728
 
1729
@item -fsigned-char
1730
@opindex fsigned-char
1731
Let the type @code{char} be signed, like @code{signed char}.
1732
 
1733
Note that this is equivalent to @option{-fno-unsigned-char}, which is
1734
the negative form of @option{-funsigned-char}.  Likewise, the option
1735
@option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
1736
 
1737
@item -fsigned-bitfields
1738
@itemx -funsigned-bitfields
1739
@itemx -fno-signed-bitfields
1740
@itemx -fno-unsigned-bitfields
1741
@opindex fsigned-bitfields
1742
@opindex funsigned-bitfields
1743
@opindex fno-signed-bitfields
1744
@opindex fno-unsigned-bitfields
1745
These options control whether a bit-field is signed or unsigned, when the
1746
declaration does not use either @code{signed} or @code{unsigned}.  By
1747
default, such a bit-field is signed, because this is consistent: the
1748
basic integer types such as @code{int} are signed types.
1749
@end table
1750
 
1751
@node C++ Dialect Options
1752
@section Options Controlling C++ Dialect
1753
 
1754
@cindex compiler options, C++
1755
@cindex C++ options, command line
1756
@cindex options, C++
1757
This section describes the command-line options that are only meaningful
1758
for C++ programs; but you can also use most of the GNU compiler options
1759
regardless of what language your program is in.  For example, you
1760
might compile a file @code{firstClass.C} like this:
1761
 
1762
@smallexample
1763
g++ -g -frepo -O -c firstClass.C
1764
@end smallexample
1765
 
1766
@noindent
1767
In this example, only @option{-frepo} is an option meant
1768
only for C++ programs; you can use the other options with any
1769
language supported by GCC@.
1770
 
1771
Here is a list of options that are @emph{only} for compiling C++ programs:
1772
 
1773
@table @gcctabopt
1774
 
1775
@item -fabi-version=@var{n}
1776
@opindex fabi-version
1777
Use version @var{n} of the C++ ABI@.  Version 2 is the version of the
1778
C++ ABI that first appeared in G++ 3.4.  Version 1 is the version of
1779
the C++ ABI that first appeared in G++ 3.2.  Version 0 will always be
1780
the version that conforms most closely to the C++ ABI specification.
1781
Therefore, the ABI obtained using version 0 will change as ABI bugs
1782
are fixed.
1783
 
1784
The default is version 2.
1785
 
1786
Version 3 corrects an error in mangling a constant address as a
1787
template argument.
1788
 
1789
Version 4 implements a standard mangling for vector types.
1790
 
1791
See also @option{-Wabi}.
1792
 
1793
@item -fno-access-control
1794
@opindex fno-access-control
1795
Turn off all access checking.  This switch is mainly useful for working
1796
around bugs in the access control code.
1797
 
1798
@item -fcheck-new
1799
@opindex fcheck-new
1800
Check that the pointer returned by @code{operator new} is non-null
1801
before attempting to modify the storage allocated.  This check is
1802
normally unnecessary because the C++ standard specifies that
1803
@code{operator new} will only return @code{0} if it is declared
1804
@samp{throw()}, in which case the compiler will always check the
1805
return value even without this option.  In all other cases, when
1806
@code{operator new} has a non-empty exception specification, memory
1807
exhaustion is signalled by throwing @code{std::bad_alloc}.  See also
1808
@samp{new (nothrow)}.
1809
 
1810
@item -fconserve-space
1811
@opindex fconserve-space
1812
Put uninitialized or runtime-initialized global variables into the
1813
common segment, as C does.  This saves space in the executable at the
1814
cost of not diagnosing duplicate definitions.  If you compile with this
1815
flag and your program mysteriously crashes after @code{main()} has
1816
completed, you may have an object that is being destroyed twice because
1817
two definitions were merged.
1818
 
1819
This option is no longer useful on most targets, now that support has
1820
been added for putting variables into BSS without making them common.
1821
 
1822
@item -fno-deduce-init-list
1823
@opindex fno-deduce-init-list
1824
Disable deduction of a template type parameter as
1825
std::initializer_list from a brace-enclosed initializer list, i.e.
1826
 
1827
@smallexample
1828
template <class T> auto forward(T t) -> decltype (realfn (t))
1829
@{
1830
  return realfn (t);
1831
@}
1832
 
1833
void f()
1834
@{
1835
  forward(@{1,2@}); // call forward<std::initializer_list<int>>
1836
@}
1837
@end smallexample
1838
 
1839
This option is present because this deduction is an extension to the
1840
current specification in the C++0x working draft, and there was
1841
some concern about potential overload resolution problems.
1842
 
1843
@item -ffriend-injection
1844
@opindex ffriend-injection
1845
Inject friend functions into the enclosing namespace, so that they are
1846
visible outside the scope of the class in which they are declared.
1847
Friend functions were documented to work this way in the old Annotated
1848
C++ Reference Manual, and versions of G++ before 4.1 always worked
1849
that way.  However, in ISO C++ a friend function which is not declared
1850
in an enclosing scope can only be found using argument dependent
1851
lookup.  This option causes friends to be injected as they were in
1852
earlier releases.
1853
 
1854
This option is for compatibility, and may be removed in a future
1855
release of G++.
1856
 
1857
@item -fno-elide-constructors
1858
@opindex fno-elide-constructors
1859
The C++ standard allows an implementation to omit creating a temporary
1860
which is only used to initialize another object of the same type.
1861
Specifying this option disables that optimization, and forces G++ to
1862
call the copy constructor in all cases.
1863
 
1864
@item -fno-enforce-eh-specs
1865
@opindex fno-enforce-eh-specs
1866
Don't generate code to check for violation of exception specifications
1867
at runtime.  This option violates the C++ standard, but may be useful
1868
for reducing code size in production builds, much like defining
1869
@samp{NDEBUG}.  This does not give user code permission to throw
1870
exceptions in violation of the exception specifications; the compiler
1871
will still optimize based on the specifications, so throwing an
1872
unexpected exception will result in undefined behavior.
1873
 
1874
@item -ffor-scope
1875
@itemx -fno-for-scope
1876
@opindex ffor-scope
1877
@opindex fno-for-scope
1878
If @option{-ffor-scope} is specified, the scope of variables declared in
1879
a @i{for-init-statement} is limited to the @samp{for} loop itself,
1880
as specified by the C++ standard.
1881
If @option{-fno-for-scope} is specified, the scope of variables declared in
1882
a @i{for-init-statement} extends to the end of the enclosing scope,
1883
as was the case in old versions of G++, and other (traditional)
1884
implementations of C++.
1885
 
1886
The default if neither flag is given to follow the standard,
1887
but to allow and give a warning for old-style code that would
1888
otherwise be invalid, or have different behavior.
1889
 
1890
@item -fno-gnu-keywords
1891
@opindex fno-gnu-keywords
1892
Do not recognize @code{typeof} as a keyword, so that code can use this
1893
word as an identifier.  You can use the keyword @code{__typeof__} instead.
1894
@option{-ansi} implies @option{-fno-gnu-keywords}.
1895
 
1896
@item -fno-implicit-templates
1897
@opindex fno-implicit-templates
1898
Never emit code for non-inline templates which are instantiated
1899
implicitly (i.e.@: by use); only emit code for explicit instantiations.
1900
@xref{Template Instantiation}, for more information.
1901
 
1902
@item -fno-implicit-inline-templates
1903
@opindex fno-implicit-inline-templates
1904
Don't emit code for implicit instantiations of inline templates, either.
1905
The default is to handle inlines differently so that compiles with and
1906
without optimization will need the same set of explicit instantiations.
1907
 
1908
@item -fno-implement-inlines
1909
@opindex fno-implement-inlines
1910
To save space, do not emit out-of-line copies of inline functions
1911
controlled by @samp{#pragma implementation}.  This will cause linker
1912
errors if these functions are not inlined everywhere they are called.
1913
 
1914
@item -fms-extensions
1915
@opindex fms-extensions
1916
Disable pedantic warnings about constructs used in MFC, such as implicit
1917
int and getting a pointer to member function via non-standard syntax.
1918
 
1919
@item -fno-nonansi-builtins
1920
@opindex fno-nonansi-builtins
1921
Disable built-in declarations of functions that are not mandated by
1922
ANSI/ISO C@.  These include @code{ffs}, @code{alloca}, @code{_exit},
1923
@code{index}, @code{bzero}, @code{conjf}, and other related functions.
1924
 
1925
@item -fno-operator-names
1926
@opindex fno-operator-names
1927
Do not treat the operator name keywords @code{and}, @code{bitand},
1928
@code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1929
synonyms as keywords.
1930
 
1931
@item -fno-optional-diags
1932
@opindex fno-optional-diags
1933
Disable diagnostics that the standard says a compiler does not need to
1934
issue.  Currently, the only such diagnostic issued by G++ is the one for
1935
a name having multiple meanings within a class.
1936
 
1937
@item -fpermissive
1938
@opindex fpermissive
1939
Downgrade some diagnostics about nonconformant code from errors to
1940
warnings.  Thus, using @option{-fpermissive} will allow some
1941
nonconforming code to compile.
1942
 
1943
@item -fno-pretty-templates
1944
@opindex fno-pretty-templates
1945
When an error message refers to a specialization of a function
1946
template, the compiler will normally print the signature of the
1947
template followed by the template arguments and any typedefs or
1948
typenames in the signature (e.g. @code{void f(T) [with T = int]}
1949
rather than @code{void f(int)}) so that it's clear which template is
1950
involved.  When an error message refers to a specialization of a class
1951
template, the compiler will omit any template arguments which match
1952
the default template arguments for that template.  If either of these
1953
behaviors make it harder to understand the error message rather than
1954
easier, using @option{-fno-pretty-templates} will disable them.
1955
 
1956
@item -frepo
1957
@opindex frepo
1958
Enable automatic template instantiation at link time.  This option also
1959
implies @option{-fno-implicit-templates}.  @xref{Template
1960
Instantiation}, for more information.
1961
 
1962
@item -fno-rtti
1963
@opindex fno-rtti
1964
Disable generation of information about every class with virtual
1965
functions for use by the C++ runtime type identification features
1966
(@samp{dynamic_cast} and @samp{typeid}).  If you don't use those parts
1967
of the language, you can save some space by using this flag.  Note that
1968
exception handling uses the same information, but it will generate it as
1969
needed. The @samp{dynamic_cast} operator can still be used for casts that
1970
do not require runtime type information, i.e.@: casts to @code{void *} or to
1971
unambiguous base classes.
1972
 
1973
@item -fstats
1974
@opindex fstats
1975
Emit statistics about front-end processing at the end of the compilation.
1976
This information is generally only useful to the G++ development team.
1977
 
1978
@item -ftemplate-depth=@var{n}
1979
@opindex ftemplate-depth
1980
Set the maximum instantiation depth for template classes to @var{n}.
1981
A limit on the template instantiation depth is needed to detect
1982
endless recursions during template class instantiation.  ANSI/ISO C++
1983
conforming programs must not rely on a maximum depth greater than 17
1984
(changed to 1024 in C++0x).
1985
 
1986
@item -fno-threadsafe-statics
1987
@opindex fno-threadsafe-statics
1988
Do not emit the extra code to use the routines specified in the C++
1989
ABI for thread-safe initialization of local statics.  You can use this
1990
option to reduce code size slightly in code that doesn't need to be
1991
thread-safe.
1992
 
1993
@item -fuse-cxa-atexit
1994
@opindex fuse-cxa-atexit
1995
Register destructors for objects with static storage duration with the
1996
@code{__cxa_atexit} function rather than the @code{atexit} function.
1997
This option is required for fully standards-compliant handling of static
1998
destructors, but will only work if your C library supports
1999
@code{__cxa_atexit}.
2000
 
2001
@item -fno-use-cxa-get-exception-ptr
2002
@opindex fno-use-cxa-get-exception-ptr
2003
Don't use the @code{__cxa_get_exception_ptr} runtime routine.  This
2004
will cause @code{std::uncaught_exception} to be incorrect, but is necessary
2005
if the runtime routine is not available.
2006
 
2007
@item -fvisibility-inlines-hidden
2008
@opindex fvisibility-inlines-hidden
2009
This switch declares that the user does not attempt to compare
2010
pointers to inline methods where the addresses of the two functions
2011
were taken in different shared objects.
2012
 
2013
The effect of this is that GCC may, effectively, mark inline methods with
2014
@code{__attribute__ ((visibility ("hidden")))} so that they do not
2015
appear in the export table of a DSO and do not require a PLT indirection
2016
when used within the DSO@.  Enabling this option can have a dramatic effect
2017
on load and link times of a DSO as it massively reduces the size of the
2018
dynamic export table when the library makes heavy use of templates.
2019
 
2020
The behavior of this switch is not quite the same as marking the
2021
methods as hidden directly, because it does not affect static variables
2022
local to the function or cause the compiler to deduce that
2023
the function is defined in only one shared object.
2024
 
2025
You may mark a method as having a visibility explicitly to negate the
2026
effect of the switch for that method.  For example, if you do want to
2027
compare pointers to a particular inline method, you might mark it as
2028
having default visibility.  Marking the enclosing class with explicit
2029
visibility will have no effect.
2030
 
2031
Explicitly instantiated inline methods are unaffected by this option
2032
as their linkage might otherwise cross a shared library boundary.
2033
@xref{Template Instantiation}.
2034
 
2035
@item -fvisibility-ms-compat
2036
@opindex fvisibility-ms-compat
2037
This flag attempts to use visibility settings to make GCC's C++
2038
linkage model compatible with that of Microsoft Visual Studio.
2039
 
2040
The flag makes these changes to GCC's linkage model:
2041
 
2042
@enumerate
2043
@item
2044
It sets the default visibility to @code{hidden}, like
2045
@option{-fvisibility=hidden}.
2046
 
2047
@item
2048
Types, but not their members, are not hidden by default.
2049
 
2050
@item
2051
The One Definition Rule is relaxed for types without explicit
2052
visibility specifications which are defined in more than one different
2053
shared object: those declarations are permitted if they would have
2054
been permitted when this option was not used.
2055
@end enumerate
2056
 
2057
In new code it is better to use @option{-fvisibility=hidden} and
2058
export those classes which are intended to be externally visible.
2059
Unfortunately it is possible for code to rely, perhaps accidentally,
2060
on the Visual Studio behavior.
2061
 
2062
Among the consequences of these changes are that static data members
2063
of the same type with the same name but defined in different shared
2064
objects will be different, so changing one will not change the other;
2065
and that pointers to function members defined in different shared
2066
objects may not compare equal.  When this flag is given, it is a
2067
violation of the ODR to define types with the same name differently.
2068
 
2069
@item -fno-weak
2070
@opindex fno-weak
2071
Do not use weak symbol support, even if it is provided by the linker.
2072
By default, G++ will use weak symbols if they are available.  This
2073
option exists only for testing, and should not be used by end-users;
2074
it will result in inferior code and has no benefits.  This option may
2075
be removed in a future release of G++.
2076
 
2077
@item -nostdinc++
2078
@opindex nostdinc++
2079
Do not search for header files in the standard directories specific to
2080
C++, but do still search the other standard directories.  (This option
2081
is used when building the C++ library.)
2082
@end table
2083
 
2084
In addition, these optimization, warning, and code generation options
2085
have meanings only for C++ programs:
2086
 
2087
@table @gcctabopt
2088
@item -fno-default-inline
2089
@opindex fno-default-inline
2090
Do not assume @samp{inline} for functions defined inside a class scope.
2091
@xref{Optimize Options,,Options That Control Optimization}.  Note that these
2092
functions will have linkage like inline functions; they just won't be
2093
inlined by default.
2094
 
2095
@item -Wabi @r{(C, Objective-C, C++ and Objective-C++ only)}
2096
@opindex Wabi
2097
@opindex Wno-abi
2098
Warn when G++ generates code that is probably not compatible with the
2099
vendor-neutral C++ ABI@.  Although an effort has been made to warn about
2100
all such cases, there are probably some cases that are not warned about,
2101
even though G++ is generating incompatible code.  There may also be
2102
cases where warnings are emitted even though the code that is generated
2103
will be compatible.
2104
 
2105
You should rewrite your code to avoid these warnings if you are
2106
concerned about the fact that code generated by G++ may not be binary
2107
compatible with code generated by other compilers.
2108
 
2109
The known incompatibilities in @option{-fabi-version=2} (the default) include:
2110
 
2111
@itemize @bullet
2112
 
2113
@item
2114
A template with a non-type template parameter of reference type is
2115
mangled incorrectly:
2116
@smallexample
2117
extern int N;
2118
template <int &> struct S @{@};
2119
void n (S<N>) @{2@}
2120
@end smallexample
2121
 
2122
This is fixed in @option{-fabi-version=3}.
2123
 
2124
@item
2125
SIMD vector types declared using @code{__attribute ((vector_size))} are
2126
mangled in a non-standard way that does not allow for overloading of
2127
functions taking vectors of different sizes.
2128
 
2129
The mangling is changed in @option{-fabi-version=4}.
2130
@end itemize
2131
 
2132
The known incompatibilities in @option{-fabi-version=1} include:
2133
 
2134
@itemize @bullet
2135
 
2136
@item
2137
Incorrect handling of tail-padding for bit-fields.  G++ may attempt to
2138
pack data into the same byte as a base class.  For example:
2139
 
2140
@smallexample
2141
struct A @{ virtual void f(); int f1 : 1; @};
2142
struct B : public A @{ int f2 : 1; @};
2143
@end smallexample
2144
 
2145
@noindent
2146
In this case, G++ will place @code{B::f2} into the same byte
2147
as@code{A::f1}; other compilers will not.  You can avoid this problem
2148
by explicitly padding @code{A} so that its size is a multiple of the
2149
byte size on your platform; that will cause G++ and other compilers to
2150
layout @code{B} identically.
2151
 
2152
@item
2153
Incorrect handling of tail-padding for virtual bases.  G++ does not use
2154
tail padding when laying out virtual bases.  For example:
2155
 
2156
@smallexample
2157
struct A @{ virtual void f(); char c1; @};
2158
struct B @{ B(); char c2; @};
2159
struct C : public A, public virtual B @{@};
2160
@end smallexample
2161
 
2162
@noindent
2163
In this case, G++ will not place @code{B} into the tail-padding for
2164
@code{A}; other compilers will.  You can avoid this problem by
2165
explicitly padding @code{A} so that its size is a multiple of its
2166
alignment (ignoring virtual base classes); that will cause G++ and other
2167
compilers to layout @code{C} identically.
2168
 
2169
@item
2170
Incorrect handling of bit-fields with declared widths greater than that
2171
of their underlying types, when the bit-fields appear in a union.  For
2172
example:
2173
 
2174
@smallexample
2175
union U @{ int i : 4096; @};
2176
@end smallexample
2177
 
2178
@noindent
2179
Assuming that an @code{int} does not have 4096 bits, G++ will make the
2180
union too small by the number of bits in an @code{int}.
2181
 
2182
@item
2183
Empty classes can be placed at incorrect offsets.  For example:
2184
 
2185
@smallexample
2186
struct A @{@};
2187
 
2188
struct B @{
2189
  A a;
2190
  virtual void f ();
2191
@};
2192
 
2193
struct C : public B, public A @{@};
2194
@end smallexample
2195
 
2196
@noindent
2197
G++ will place the @code{A} base class of @code{C} at a nonzero offset;
2198
it should be placed at offset zero.  G++ mistakenly believes that the
2199
@code{A} data member of @code{B} is already at offset zero.
2200
 
2201
@item
2202
Names of template functions whose types involve @code{typename} or
2203
template template parameters can be mangled incorrectly.
2204
 
2205
@smallexample
2206
template <typename Q>
2207
void f(typename Q::X) @{@}
2208
 
2209
template <template <typename> class Q>
2210
void f(typename Q<int>::X) @{@}
2211
@end smallexample
2212
 
2213
@noindent
2214
Instantiations of these templates may be mangled incorrectly.
2215
 
2216
@end itemize
2217
 
2218
It also warns psABI related changes.  The known psABI changes at this
2219
point include:
2220
 
2221
@itemize @bullet
2222
 
2223
@item
2224
For SYSV/x86-64, when passing union with long double, it is changed to
2225
pass in memory as specified in psABI.  For example:
2226
 
2227
@smallexample
2228
union U @{
2229
  long double ld;
2230
  int i;
2231
@};
2232
@end smallexample
2233
 
2234
@noindent
2235
@code{union U} will always be passed in memory.
2236
 
2237
@end itemize
2238
 
2239
@item -Wctor-dtor-privacy @r{(C++ and Objective-C++ only)}
2240
@opindex Wctor-dtor-privacy
2241
@opindex Wno-ctor-dtor-privacy
2242
Warn when a class seems unusable because all the constructors or
2243
destructors in that class are private, and it has neither friends nor
2244
public static member functions.
2245
 
2246
@item -Wnon-virtual-dtor @r{(C++ and Objective-C++ only)}
2247
@opindex Wnon-virtual-dtor
2248
@opindex Wno-non-virtual-dtor
2249
Warn when a class has virtual functions and accessible non-virtual
2250
destructor, in which case it would be possible but unsafe to delete
2251
an instance of a derived class through a pointer to the base class.
2252
This warning is also enabled if -Weffc++ is specified.
2253
 
2254
@item -Wreorder @r{(C++ and Objective-C++ only)}
2255
@opindex Wreorder
2256
@opindex Wno-reorder
2257
@cindex reordering, warning
2258
@cindex warning for reordering of member initializers
2259
Warn when the order of member initializers given in the code does not
2260
match the order in which they must be executed.  For instance:
2261
 
2262
@smallexample
2263
struct A @{
2264
  int i;
2265
  int j;
2266
  A(): j (0), i (1) @{ @}
2267
@};
2268
@end smallexample
2269
 
2270
The compiler will rearrange the member initializers for @samp{i}
2271
and @samp{j} to match the declaration order of the members, emitting
2272
a warning to that effect.  This warning is enabled by @option{-Wall}.
2273
@end table
2274
 
2275
The following @option{-W@dots{}} options are not affected by @option{-Wall}.
2276
 
2277
@table @gcctabopt
2278
@item -Weffc++ @r{(C++ and Objective-C++ only)}
2279
@opindex Weffc++
2280
@opindex Wno-effc++
2281
Warn about violations of the following style guidelines from Scott Meyers'
2282
@cite{Effective C++} book:
2283
 
2284
@itemize @bullet
2285
@item
2286
Item 11:  Define a copy constructor and an assignment operator for classes
2287
with dynamically allocated memory.
2288
 
2289
@item
2290
Item 12:  Prefer initialization to assignment in constructors.
2291
 
2292
@item
2293
Item 14:  Make destructors virtual in base classes.
2294
 
2295
@item
2296
Item 15:  Have @code{operator=} return a reference to @code{*this}.
2297
 
2298
@item
2299
Item 23:  Don't try to return a reference when you must return an object.
2300
 
2301
@end itemize
2302
 
2303
Also warn about violations of the following style guidelines from
2304
Scott Meyers' @cite{More Effective C++} book:
2305
 
2306
@itemize @bullet
2307
@item
2308
Item 6:  Distinguish between prefix and postfix forms of increment and
2309
decrement operators.
2310
 
2311
@item
2312
Item 7:  Never overload @code{&&}, @code{||}, or @code{,}.
2313
 
2314
@end itemize
2315
 
2316
When selecting this option, be aware that the standard library
2317
headers do not obey all of these guidelines; use @samp{grep -v}
2318
to filter out those warnings.
2319
 
2320
@item -Wstrict-null-sentinel @r{(C++ and Objective-C++ only)}
2321
@opindex Wstrict-null-sentinel
2322
@opindex Wno-strict-null-sentinel
2323
Warn also about the use of an uncasted @code{NULL} as sentinel.  When
2324
compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
2325
to @code{__null}.  Although it is a null pointer constant not a null pointer,
2326
it is guaranteed to be of the same size as a pointer.  But this use is
2327
not portable across different compilers.
2328
 
2329
@item -Wno-non-template-friend @r{(C++ and Objective-C++ only)}
2330
@opindex Wno-non-template-friend
2331
@opindex Wnon-template-friend
2332
Disable warnings when non-templatized friend functions are declared
2333
within a template.  Since the advent of explicit template specification
2334
support in G++, if the name of the friend is an unqualified-id (i.e.,
2335
@samp{friend foo(int)}), the C++ language specification demands that the
2336
friend declare or define an ordinary, nontemplate function.  (Section
2337
14.5.3).  Before G++ implemented explicit specification, unqualified-ids
2338
could be interpreted as a particular specialization of a templatized
2339
function.  Because this non-conforming behavior is no longer the default
2340
behavior for G++, @option{-Wnon-template-friend} allows the compiler to
2341
check existing code for potential trouble spots and is on by default.
2342
This new compiler behavior can be turned off with
2343
@option{-Wno-non-template-friend} which keeps the conformant compiler code
2344
but disables the helpful warning.
2345
 
2346
@item -Wold-style-cast @r{(C++ and Objective-C++ only)}
2347
@opindex Wold-style-cast
2348
@opindex Wno-old-style-cast
2349
Warn if an old-style (C-style) cast to a non-void type is used within
2350
a C++ program.  The new-style casts (@samp{dynamic_cast},
2351
@samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are
2352
less vulnerable to unintended effects and much easier to search for.
2353
 
2354
@item -Woverloaded-virtual @r{(C++ and Objective-C++ only)}
2355
@opindex Woverloaded-virtual
2356
@opindex Wno-overloaded-virtual
2357
@cindex overloaded virtual fn, warning
2358
@cindex warning for overloaded virtual fn
2359
Warn when a function declaration hides virtual functions from a
2360
base class.  For example, in:
2361
 
2362
@smallexample
2363
struct A @{
2364
  virtual void f();
2365
@};
2366
 
2367
struct B: public A @{
2368
  void f(int);
2369
@};
2370
@end smallexample
2371
 
2372
the @code{A} class version of @code{f} is hidden in @code{B}, and code
2373
like:
2374
 
2375
@smallexample
2376
B* b;
2377
b->f();
2378
@end smallexample
2379
 
2380
will fail to compile.
2381
 
2382
@item -Wno-pmf-conversions @r{(C++ and Objective-C++ only)}
2383
@opindex Wno-pmf-conversions
2384
@opindex Wpmf-conversions
2385
Disable the diagnostic for converting a bound pointer to member function
2386
to a plain pointer.
2387
 
2388
@item -Wsign-promo @r{(C++ and Objective-C++ only)}
2389
@opindex Wsign-promo
2390
@opindex Wno-sign-promo
2391
Warn when overload resolution chooses a promotion from unsigned or
2392
enumerated type to a signed type, over a conversion to an unsigned type of
2393
the same size.  Previous versions of G++ would try to preserve
2394
unsignedness, but the standard mandates the current behavior.
2395
 
2396
@smallexample
2397
struct A @{
2398
  operator int ();
2399
  A& operator = (int);
2400
@};
2401
 
2402
main ()
2403
@{
2404
  A a,b;
2405
  a = b;
2406
@}
2407
@end smallexample
2408
 
2409
In this example, G++ will synthesize a default @samp{A& operator =
2410
(const A&);}, while cfront will use the user-defined @samp{operator =}.
2411
@end table
2412
 
2413
@node Objective-C and Objective-C++ Dialect Options
2414
@section Options Controlling Objective-C and Objective-C++ Dialects
2415
 
2416
@cindex compiler options, Objective-C and Objective-C++
2417
@cindex Objective-C and Objective-C++ options, command line
2418
@cindex options, Objective-C and Objective-C++
2419
(NOTE: This manual does not describe the Objective-C and Objective-C++
2420
languages themselves.  See @xref{Standards,,Language Standards
2421
Supported by GCC}, for references.)
2422
 
2423
This section describes the command-line options that are only meaningful
2424
for Objective-C and Objective-C++ programs, but you can also use most of
2425
the language-independent GNU compiler options.
2426
For example, you might compile a file @code{some_class.m} like this:
2427
 
2428
@smallexample
2429
gcc -g -fgnu-runtime -O -c some_class.m
2430
@end smallexample
2431
 
2432
@noindent
2433
In this example, @option{-fgnu-runtime} is an option meant only for
2434
Objective-C and Objective-C++ programs; you can use the other options with
2435
any language supported by GCC@.
2436
 
2437
Note that since Objective-C is an extension of the C language, Objective-C
2438
compilations may also use options specific to the C front-end (e.g.,
2439
@option{-Wtraditional}).  Similarly, Objective-C++ compilations may use
2440
C++-specific options (e.g., @option{-Wabi}).
2441
 
2442
Here is a list of options that are @emph{only} for compiling Objective-C
2443
and Objective-C++ programs:
2444
 
2445
@table @gcctabopt
2446
@item -fconstant-string-class=@var{class-name}
2447
@opindex fconstant-string-class
2448
Use @var{class-name} as the name of the class to instantiate for each
2449
literal string specified with the syntax @code{@@"@dots{}"}.  The default
2450
class name is @code{NXConstantString} if the GNU runtime is being used, and
2451
@code{NSConstantString} if the NeXT runtime is being used (see below).  The
2452
@option{-fconstant-cfstrings} option, if also present, will override the
2453
@option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} literals
2454
to be laid out as constant CoreFoundation strings.
2455
 
2456
@item -fgnu-runtime
2457
@opindex fgnu-runtime
2458
Generate object code compatible with the standard GNU Objective-C
2459
runtime.  This is the default for most types of systems.
2460
 
2461
@item -fnext-runtime
2462
@opindex fnext-runtime
2463
Generate output compatible with the NeXT runtime.  This is the default
2464
for NeXT-based systems, including Darwin and Mac OS X@.  The macro
2465
@code{__NEXT_RUNTIME__} is predefined if (and only if) this option is
2466
used.
2467
 
2468
@item -fno-nil-receivers
2469
@opindex fno-nil-receivers
2470
Assume that all Objective-C message dispatches (e.g.,
2471
@code{[receiver message:arg]}) in this translation unit ensure that the receiver
2472
is not @code{nil}.  This allows for more efficient entry points in the runtime
2473
to be used.  Currently, this option is only available in conjunction with
2474
the NeXT runtime on Mac OS X 10.3 and later.
2475
 
2476
@item -fobjc-call-cxx-cdtors
2477
@opindex fobjc-call-cxx-cdtors
2478
For each Objective-C class, check if any of its instance variables is a
2479
C++ object with a non-trivial default constructor.  If so, synthesize a
2480
special @code{- (id) .cxx_construct} instance method that will run
2481
non-trivial default constructors on any such instance variables, in order,
2482
and then return @code{self}.  Similarly, check if any instance variable
2483
is a C++ object with a non-trivial destructor, and if so, synthesize a
2484
special @code{- (void) .cxx_destruct} method that will run
2485
all such default destructors, in reverse order.
2486
 
2487
The @code{- (id) .cxx_construct} and/or @code{- (void) .cxx_destruct} methods
2488
thusly generated will only operate on instance variables declared in the
2489
current Objective-C class, and not those inherited from superclasses.  It
2490
is the responsibility of the Objective-C runtime to invoke all such methods
2491
in an object's inheritance hierarchy.  The @code{- (id) .cxx_construct} methods
2492
will be invoked by the runtime immediately after a new object
2493
instance is allocated; the @code{- (void) .cxx_destruct} methods will
2494
be invoked immediately before the runtime deallocates an object instance.
2495
 
2496
As of this writing, only the NeXT runtime on Mac OS X 10.4 and later has
2497
support for invoking the @code{- (id) .cxx_construct} and
2498
@code{- (void) .cxx_destruct} methods.
2499
 
2500
@item -fobjc-direct-dispatch
2501
@opindex fobjc-direct-dispatch
2502
Allow fast jumps to the message dispatcher.  On Darwin this is
2503
accomplished via the comm page.
2504
 
2505
@item -fobjc-exceptions
2506
@opindex fobjc-exceptions
2507
Enable syntactic support for structured exception handling in Objective-C,
2508
similar to what is offered by C++ and Java.  This option is
2509
unavailable in conjunction with the NeXT runtime on Mac OS X 10.2 and
2510
earlier.
2511
 
2512
@smallexample
2513
  @@try @{
2514
    @dots{}
2515
       @@throw expr;
2516
    @dots{}
2517
  @}
2518
  @@catch (AnObjCClass *exc) @{
2519
    @dots{}
2520
      @@throw expr;
2521
    @dots{}
2522
      @@throw;
2523
    @dots{}
2524
  @}
2525
  @@catch (AnotherClass *exc) @{
2526
    @dots{}
2527
  @}
2528
  @@catch (id allOthers) @{
2529
    @dots{}
2530
  @}
2531
  @@finally @{
2532
    @dots{}
2533
      @@throw expr;
2534
    @dots{}
2535
  @}
2536
@end smallexample
2537
 
2538
The @code{@@throw} statement may appear anywhere in an Objective-C or
2539
Objective-C++ program; when used inside of a @code{@@catch} block, the
2540
@code{@@throw} may appear without an argument (as shown above), in which case
2541
the object caught by the @code{@@catch} will be rethrown.
2542
 
2543
Note that only (pointers to) Objective-C objects may be thrown and
2544
caught using this scheme.  When an object is thrown, it will be caught
2545
by the nearest @code{@@catch} clause capable of handling objects of that type,
2546
analogously to how @code{catch} blocks work in C++ and Java.  A
2547
@code{@@catch(id @dots{})} clause (as shown above) may also be provided to catch
2548
any and all Objective-C exceptions not caught by previous @code{@@catch}
2549
clauses (if any).
2550
 
2551
The @code{@@finally} clause, if present, will be executed upon exit from the
2552
immediately preceding @code{@@try @dots{} @@catch} section.  This will happen
2553
regardless of whether any exceptions are thrown, caught or rethrown
2554
inside the @code{@@try @dots{} @@catch} section, analogously to the behavior
2555
of the @code{finally} clause in Java.
2556
 
2557
There are several caveats to using the new exception mechanism:
2558
 
2559
@itemize @bullet
2560
@item
2561
Although currently designed to be binary compatible with @code{NS_HANDLER}-style
2562
idioms provided by the @code{NSException} class, the new
2563
exceptions can only be used on Mac OS X 10.3 (Panther) and later
2564
systems, due to additional functionality needed in the (NeXT) Objective-C
2565
runtime.
2566
 
2567
@item
2568
As mentioned above, the new exceptions do not support handling
2569
types other than Objective-C objects.   Furthermore, when used from
2570
Objective-C++, the Objective-C exception model does not interoperate with C++
2571
exceptions at this time.  This means you cannot @code{@@throw} an exception
2572
from Objective-C and @code{catch} it in C++, or vice versa
2573
(i.e., @code{throw @dots{} @@catch}).
2574
@end itemize
2575
 
2576
The @option{-fobjc-exceptions} switch also enables the use of synchronization
2577
blocks for thread-safe execution:
2578
 
2579
@smallexample
2580
  @@synchronized (ObjCClass *guard) @{
2581
    @dots{}
2582
  @}
2583
@end smallexample
2584
 
2585
Upon entering the @code{@@synchronized} block, a thread of execution shall
2586
first check whether a lock has been placed on the corresponding @code{guard}
2587
object by another thread.  If it has, the current thread shall wait until
2588
the other thread relinquishes its lock.  Once @code{guard} becomes available,
2589
the current thread will place its own lock on it, execute the code contained in
2590
the @code{@@synchronized} block, and finally relinquish the lock (thereby
2591
making @code{guard} available to other threads).
2592
 
2593
Unlike Java, Objective-C does not allow for entire methods to be marked
2594
@code{@@synchronized}.  Note that throwing exceptions out of
2595
@code{@@synchronized} blocks is allowed, and will cause the guarding object
2596
to be unlocked properly.
2597
 
2598
@item -fobjc-gc
2599
@opindex fobjc-gc
2600
Enable garbage collection (GC) in Objective-C and Objective-C++ programs.
2601
 
2602
@item -freplace-objc-classes
2603
@opindex freplace-objc-classes
2604
Emit a special marker instructing @command{ld(1)} not to statically link in
2605
the resulting object file, and allow @command{dyld(1)} to load it in at
2606
run time instead.  This is used in conjunction with the Fix-and-Continue
2607
debugging mode, where the object file in question may be recompiled and
2608
dynamically reloaded in the course of program execution, without the need
2609
to restart the program itself.  Currently, Fix-and-Continue functionality
2610
is only available in conjunction with the NeXT runtime on Mac OS X 10.3
2611
and later.
2612
 
2613
@item -fzero-link
2614
@opindex fzero-link
2615
When compiling for the NeXT runtime, the compiler ordinarily replaces calls
2616
to @code{objc_getClass("@dots{}")} (when the name of the class is known at
2617
compile time) with static class references that get initialized at load time,
2618
which improves run-time performance.  Specifying the @option{-fzero-link} flag
2619
suppresses this behavior and causes calls to @code{objc_getClass("@dots{}")}
2620
to be retained.  This is useful in Zero-Link debugging mode, since it allows
2621
for individual class implementations to be modified during program execution.
2622
 
2623
@item -gen-decls
2624
@opindex gen-decls
2625
Dump interface declarations for all classes seen in the source file to a
2626
file named @file{@var{sourcename}.decl}.
2627
 
2628
@item -Wassign-intercept @r{(Objective-C and Objective-C++ only)}
2629
@opindex Wassign-intercept
2630
@opindex Wno-assign-intercept
2631
Warn whenever an Objective-C assignment is being intercepted by the
2632
garbage collector.
2633
 
2634
@item -Wno-protocol @r{(Objective-C and Objective-C++ only)}
2635
@opindex Wno-protocol
2636
@opindex Wprotocol
2637
If a class is declared to implement a protocol, a warning is issued for
2638
every method in the protocol that is not implemented by the class.  The
2639
default behavior is to issue a warning for every method not explicitly
2640
implemented in the class, even if a method implementation is inherited
2641
from the superclass.  If you use the @option{-Wno-protocol} option, then
2642
methods inherited from the superclass are considered to be implemented,
2643
and no warning is issued for them.
2644
 
2645
@item -Wselector @r{(Objective-C and Objective-C++ only)}
2646
@opindex Wselector
2647
@opindex Wno-selector
2648
Warn if multiple methods of different types for the same selector are
2649
found during compilation.  The check is performed on the list of methods
2650
in the final stage of compilation.  Additionally, a check is performed
2651
for each selector appearing in a @code{@@selector(@dots{})}
2652
expression, and a corresponding method for that selector has been found
2653
during compilation.  Because these checks scan the method table only at
2654
the end of compilation, these warnings are not produced if the final
2655
stage of compilation is not reached, for example because an error is
2656
found during compilation, or because the @option{-fsyntax-only} option is
2657
being used.
2658
 
2659
@item -Wstrict-selector-match @r{(Objective-C and Objective-C++ only)}
2660
@opindex Wstrict-selector-match
2661
@opindex Wno-strict-selector-match
2662
Warn if multiple methods with differing argument and/or return types are
2663
found for a given selector when attempting to send a message using this
2664
selector to a receiver of type @code{id} or @code{Class}.  When this flag
2665
is off (which is the default behavior), the compiler will omit such warnings
2666
if any differences found are confined to types which share the same size
2667
and alignment.
2668
 
2669
@item -Wundeclared-selector @r{(Objective-C and Objective-C++ only)}
2670
@opindex Wundeclared-selector
2671
@opindex Wno-undeclared-selector
2672
Warn if a @code{@@selector(@dots{})} expression referring to an
2673
undeclared selector is found.  A selector is considered undeclared if no
2674
method with that name has been declared before the
2675
@code{@@selector(@dots{})} expression, either explicitly in an
2676
@code{@@interface} or @code{@@protocol} declaration, or implicitly in
2677
an @code{@@implementation} section.  This option always performs its
2678
checks as soon as a @code{@@selector(@dots{})} expression is found,
2679
while @option{-Wselector} only performs its checks in the final stage of
2680
compilation.  This also enforces the coding style convention
2681
that methods and selectors must be declared before being used.
2682
 
2683
@item -print-objc-runtime-info
2684
@opindex print-objc-runtime-info
2685
Generate C header describing the largest structure that is passed by
2686
value, if any.
2687
 
2688
@end table
2689
 
2690
@node Language Independent Options
2691
@section Options to Control Diagnostic Messages Formatting
2692
@cindex options to control diagnostics formatting
2693
@cindex diagnostic messages
2694
@cindex message formatting
2695
 
2696
Traditionally, diagnostic messages have been formatted irrespective of
2697
the output device's aspect (e.g.@: its width, @dots{}).  The options described
2698
below can be used to control the diagnostic messages formatting
2699
algorithm, e.g.@: how many characters per line, how often source location
2700
information should be reported.  Right now, only the C++ front end can
2701
honor these options.  However it is expected, in the near future, that
2702
the remaining front ends would be able to digest them correctly.
2703
 
2704
@table @gcctabopt
2705
@item -fmessage-length=@var{n}
2706
@opindex fmessage-length
2707
Try to format error messages so that they fit on lines of about @var{n}
2708
characters.  The default is 72 characters for @command{g++} and 0 for the rest of
2709
the front ends supported by GCC@.  If @var{n} is zero, then no
2710
line-wrapping will be done; each error message will appear on a single
2711
line.
2712
 
2713
@opindex fdiagnostics-show-location
2714
@item -fdiagnostics-show-location=once
2715
Only meaningful in line-wrapping mode.  Instructs the diagnostic messages
2716
reporter to emit @emph{once} source location information; that is, in
2717
case the message is too long to fit on a single physical line and has to
2718
be wrapped, the source location won't be emitted (as prefix) again,
2719
over and over, in subsequent continuation lines.  This is the default
2720
behavior.
2721
 
2722
@item -fdiagnostics-show-location=every-line
2723
Only meaningful in line-wrapping mode.  Instructs the diagnostic
2724
messages reporter to emit the same source location information (as
2725
prefix) for physical lines that result from the process of breaking
2726
a message which is too long to fit on a single line.
2727
 
2728
@item -fdiagnostics-show-option
2729
@opindex fdiagnostics-show-option
2730
This option instructs the diagnostic machinery to add text to each
2731
diagnostic emitted, which indicates which command line option directly
2732
controls that diagnostic, when such an option is known to the
2733
diagnostic machinery.
2734
 
2735
@item -Wcoverage-mismatch
2736
@opindex Wcoverage-mismatch
2737
Warn if feedback profiles do not match when using the
2738
@option{-fprofile-use} option.
2739
If a source file was changed between @option{-fprofile-gen} and
2740
@option{-fprofile-use}, the files with the profile feedback can fail
2741
to match the source file and GCC can not use the profile feedback
2742
information.  By default, GCC emits an error message in this case.
2743
The option @option{-Wcoverage-mismatch} emits a warning instead of an
2744
error.  GCC does not use appropriate feedback profiles, so using this
2745
option can result in poorly optimized code.  This option is useful
2746
only in the case of very minor changes such as bug fixes to an
2747
existing code-base.
2748
 
2749
@end table
2750
 
2751
@node Warning Options
2752
@section Options to Request or Suppress Warnings
2753
@cindex options to control warnings
2754
@cindex warning messages
2755
@cindex messages, warning
2756
@cindex suppressing warnings
2757
 
2758
Warnings are diagnostic messages that report constructions which
2759
are not inherently erroneous but which are risky or suggest there
2760
may have been an error.
2761
 
2762
The following language-independent options do not enable specific
2763
warnings but control the kinds of diagnostics produced by GCC.
2764
 
2765
@table @gcctabopt
2766
@cindex syntax checking
2767
@item -fsyntax-only
2768
@opindex fsyntax-only
2769
Check the code for syntax errors, but don't do anything beyond that.
2770
 
2771
@item -w
2772
@opindex w
2773
Inhibit all warning messages.
2774
 
2775
@item -Werror
2776
@opindex Werror
2777
@opindex Wno-error
2778
Make all warnings into errors.
2779
 
2780
@item -Werror=
2781
@opindex Werror=
2782
@opindex Wno-error=
2783
Make the specified warning into an error.  The specifier for a warning
2784
is appended, for example @option{-Werror=switch} turns the warnings
2785
controlled by @option{-Wswitch} into errors.  This switch takes a
2786
negative form, to be used to negate @option{-Werror} for specific
2787
warnings, for example @option{-Wno-error=switch} makes
2788
@option{-Wswitch} warnings not be errors, even when @option{-Werror}
2789
is in effect.  You can use the @option{-fdiagnostics-show-option}
2790
option to have each controllable warning amended with the option which
2791
controls it, to determine what to use with this option.
2792
 
2793
Note that specifying @option{-Werror=}@var{foo} automatically implies
2794
@option{-W}@var{foo}.  However, @option{-Wno-error=}@var{foo} does not
2795
imply anything.
2796
 
2797
@item -Wfatal-errors
2798
@opindex Wfatal-errors
2799
@opindex Wno-fatal-errors
2800
This option causes the compiler to abort compilation on the first error
2801
occurred rather than trying to keep going and printing further error
2802
messages.
2803
 
2804
@end table
2805
 
2806
You can request many specific warnings with options beginning
2807
@samp{-W}, for example @option{-Wimplicit} to request warnings on
2808
implicit declarations.  Each of these specific warning options also
2809
has a negative form beginning @samp{-Wno-} to turn off warnings; for
2810
example, @option{-Wno-implicit}.  This manual lists only one of the
2811
two forms, whichever is not the default.  For further,
2812
language-specific options also refer to @ref{C++ Dialect Options} and
2813
@ref{Objective-C and Objective-C++ Dialect Options}.
2814
 
2815
@table @gcctabopt
2816
@item -pedantic
2817
@opindex pedantic
2818
Issue all the warnings demanded by strict ISO C and ISO C++;
2819
reject all programs that use forbidden extensions, and some other
2820
programs that do not follow ISO C and ISO C++.  For ISO C, follows the
2821
version of the ISO C standard specified by any @option{-std} option used.
2822
 
2823
Valid ISO C and ISO C++ programs should compile properly with or without
2824
this option (though a rare few will require @option{-ansi} or a
2825
@option{-std} option specifying the required version of ISO C)@.  However,
2826
without this option, certain GNU extensions and traditional C and C++
2827
features are supported as well.  With this option, they are rejected.
2828
 
2829
@option{-pedantic} does not cause warning messages for use of the
2830
alternate keywords whose names begin and end with @samp{__}.  Pedantic
2831
warnings are also disabled in the expression that follows
2832
@code{__extension__}.  However, only system header files should use
2833
these escape routes; application programs should avoid them.
2834
@xref{Alternate Keywords}.
2835
 
2836
Some users try to use @option{-pedantic} to check programs for strict ISO
2837
C conformance.  They soon find that it does not do quite what they want:
2838
it finds some non-ISO practices, but not all---only those for which
2839
ISO C @emph{requires} a diagnostic, and some others for which
2840
diagnostics have been added.
2841
 
2842
A feature to report any failure to conform to ISO C might be useful in
2843
some instances, but would require considerable additional work and would
2844
be quite different from @option{-pedantic}.  We don't have plans to
2845
support such a feature in the near future.
2846
 
2847
Where the standard specified with @option{-std} represents a GNU
2848
extended dialect of C, such as @samp{gnu90} or @samp{gnu99}, there is a
2849
corresponding @dfn{base standard}, the version of ISO C on which the GNU
2850
extended dialect is based.  Warnings from @option{-pedantic} are given
2851
where they are required by the base standard.  (It would not make sense
2852
for such warnings to be given only for features not in the specified GNU
2853
C dialect, since by definition the GNU dialects of C include all
2854
features the compiler supports with the given option, and there would be
2855
nothing to warn about.)
2856
 
2857
@item -pedantic-errors
2858
@opindex pedantic-errors
2859
Like @option{-pedantic}, except that errors are produced rather than
2860
warnings.
2861
 
2862
@item -Wall
2863
@opindex Wall
2864
@opindex Wno-all
2865
This enables all the warnings about constructions that some users
2866
consider questionable, and that are easy to avoid (or modify to
2867
prevent the warning), even in conjunction with macros.  This also
2868
enables some language-specific warnings described in @ref{C++ Dialect
2869
Options} and @ref{Objective-C and Objective-C++ Dialect Options}.
2870
 
2871
@option{-Wall} turns on the following warning flags:
2872
 
2873
@gccoptlist{-Waddress   @gol
2874
-Warray-bounds @r{(only with} @option{-O2}@r{)}  @gol
2875
-Wc++0x-compat  @gol
2876
-Wchar-subscripts  @gol
2877
-Wenum-compare @r{(in C/Objc; this is on by default in C++)} @gol
2878
-Wimplicit-int  @gol
2879
-Wimplicit-function-declaration  @gol
2880
-Wcomment  @gol
2881
-Wformat   @gol
2882
-Wmain @r{(only for C/ObjC and unless} @option{-ffreestanding}@r{)}  @gol
2883
-Wmissing-braces  @gol
2884
-Wnonnull  @gol
2885
-Wparentheses  @gol
2886
-Wpointer-sign  @gol
2887
-Wreorder   @gol
2888
-Wreturn-type  @gol
2889
-Wsequence-point  @gol
2890
-Wsign-compare @r{(only in C++)}  @gol
2891
-Wstrict-aliasing  @gol
2892
-Wstrict-overflow=1  @gol
2893
-Wswitch  @gol
2894
-Wtrigraphs  @gol
2895
-Wuninitialized  @gol
2896
-Wunknown-pragmas  @gol
2897
-Wunused-function  @gol
2898
-Wunused-label     @gol
2899
-Wunused-value     @gol
2900
-Wunused-variable  @gol
2901
-Wvolatile-register-var @gol
2902
}
2903
 
2904
Note that some warning flags are not implied by @option{-Wall}.  Some of
2905
them warn about constructions that users generally do not consider
2906
questionable, but which occasionally you might wish to check for;
2907
others warn about constructions that are necessary or hard to avoid in
2908
some cases, and there is no simple way to modify the code to suppress
2909
the warning. Some of them are enabled by @option{-Wextra} but many of
2910
them must be enabled individually.
2911
 
2912
@item -Wextra
2913
@opindex W
2914
@opindex Wextra
2915
@opindex Wno-extra
2916
This enables some extra warning flags that are not enabled by
2917
@option{-Wall}. (This option used to be called @option{-W}.  The older
2918
name is still supported, but the newer name is more descriptive.)
2919
 
2920
@gccoptlist{-Wclobbered  @gol
2921
-Wempty-body  @gol
2922
-Wignored-qualifiers @gol
2923
-Wmissing-field-initializers  @gol
2924
-Wmissing-parameter-type @r{(C only)}  @gol
2925
-Wold-style-declaration @r{(C only)}  @gol
2926
-Woverride-init  @gol
2927
-Wsign-compare  @gol
2928
-Wtype-limits  @gol
2929
-Wuninitialized  @gol
2930
-Wunused-parameter @r{(only with} @option{-Wunused} @r{or} @option{-Wall}@r{)}  @gol
2931
}
2932
 
2933
The option @option{-Wextra} also prints warning messages for the
2934
following cases:
2935
 
2936
@itemize @bullet
2937
 
2938
@item
2939
A pointer is compared against integer zero with @samp{<}, @samp{<=},
2940
@samp{>}, or @samp{>=}.
2941
 
2942
@item
2943
(C++ only) An enumerator and a non-enumerator both appear in a
2944
conditional expression.
2945
 
2946
@item
2947
(C++ only) Ambiguous virtual bases.
2948
 
2949
@item
2950
(C++ only) Subscripting an array which has been declared @samp{register}.
2951
 
2952
@item
2953
(C++ only) Taking the address of a variable which has been declared
2954
@samp{register}.
2955
 
2956
@item
2957
(C++ only) A base class is not initialized in a derived class' copy
2958
constructor.
2959
 
2960
@end itemize
2961
 
2962
@item -Wchar-subscripts
2963
@opindex Wchar-subscripts
2964
@opindex Wno-char-subscripts
2965
Warn if an array subscript has type @code{char}.  This is a common cause
2966
of error, as programmers often forget that this type is signed on some
2967
machines.
2968
This warning is enabled by @option{-Wall}.
2969
 
2970
@item -Wcomment
2971
@opindex Wcomment
2972
@opindex Wno-comment
2973
Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
2974
comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
2975
This warning is enabled by @option{-Wall}.
2976
 
2977
@item -Wformat
2978
@opindex Wformat
2979
@opindex Wno-format
2980
@opindex ffreestanding
2981
@opindex fno-builtin
2982
Check calls to @code{printf} and @code{scanf}, etc., to make sure that
2983
the arguments supplied have types appropriate to the format string
2984
specified, and that the conversions specified in the format string make
2985
sense.  This includes standard functions, and others specified by format
2986
attributes (@pxref{Function Attributes}), in the @code{printf},
2987
@code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
2988
not in the C standard) families (or other target-specific families).
2989
Which functions are checked without format attributes having been
2990
specified depends on the standard version selected, and such checks of
2991
functions without the attribute specified are disabled by
2992
@option{-ffreestanding} or @option{-fno-builtin}.
2993
 
2994
The formats are checked against the format features supported by GNU
2995
libc version 2.2.  These include all ISO C90 and C99 features, as well
2996
as features from the Single Unix Specification and some BSD and GNU
2997
extensions.  Other library implementations may not support all these
2998
features; GCC does not support warning about features that go beyond a
2999
particular library's limitations.  However, if @option{-pedantic} is used
3000
with @option{-Wformat}, warnings will be given about format features not
3001
in the selected standard version (but not for @code{strfmon} formats,
3002
since those are not in any version of the C standard).  @xref{C Dialect
3003
Options,,Options Controlling C Dialect}.
3004
 
3005
Since @option{-Wformat} also checks for null format arguments for
3006
several functions, @option{-Wformat} also implies @option{-Wnonnull}.
3007
 
3008
@option{-Wformat} is included in @option{-Wall}.  For more control over some
3009
aspects of format checking, the options @option{-Wformat-y2k},
3010
@option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
3011
@option{-Wformat-nonliteral}, @option{-Wformat-security}, and
3012
@option{-Wformat=2} are available, but are not included in @option{-Wall}.
3013
 
3014
@item -Wformat-y2k
3015
@opindex Wformat-y2k
3016
@opindex Wno-format-y2k
3017
If @option{-Wformat} is specified, also warn about @code{strftime}
3018
formats which may yield only a two-digit year.
3019
 
3020
@item -Wno-format-contains-nul
3021
@opindex Wno-format-contains-nul
3022
@opindex Wformat-contains-nul
3023
If @option{-Wformat} is specified, do not warn about format strings that
3024
contain NUL bytes.
3025
 
3026
@item -Wno-format-extra-args
3027
@opindex Wno-format-extra-args
3028
@opindex Wformat-extra-args
3029
If @option{-Wformat} is specified, do not warn about excess arguments to a
3030
@code{printf} or @code{scanf} format function.  The C standard specifies
3031
that such arguments are ignored.
3032
 
3033
Where the unused arguments lie between used arguments that are
3034
specified with @samp{$} operand number specifications, normally
3035
warnings are still given, since the implementation could not know what
3036
type to pass to @code{va_arg} to skip the unused arguments.  However,
3037
in the case of @code{scanf} formats, this option will suppress the
3038
warning if the unused arguments are all pointers, since the Single
3039
Unix Specification says that such unused arguments are allowed.
3040
 
3041
@item -Wno-format-zero-length @r{(C and Objective-C only)}
3042
@opindex Wno-format-zero-length
3043
@opindex Wformat-zero-length
3044
If @option{-Wformat} is specified, do not warn about zero-length formats.
3045
The C standard specifies that zero-length formats are allowed.
3046
 
3047
@item -Wformat-nonliteral
3048
@opindex Wformat-nonliteral
3049
@opindex Wno-format-nonliteral
3050
If @option{-Wformat} is specified, also warn if the format string is not a
3051
string literal and so cannot be checked, unless the format function
3052
takes its format arguments as a @code{va_list}.
3053
 
3054
@item -Wformat-security
3055
@opindex Wformat-security
3056
@opindex Wno-format-security
3057
If @option{-Wformat} is specified, also warn about uses of format
3058
functions that represent possible security problems.  At present, this
3059
warns about calls to @code{printf} and @code{scanf} functions where the
3060
format string is not a string literal and there are no format arguments,
3061
as in @code{printf (foo);}.  This may be a security hole if the format
3062
string came from untrusted input and contains @samp{%n}.  (This is
3063
currently a subset of what @option{-Wformat-nonliteral} warns about, but
3064
in future warnings may be added to @option{-Wformat-security} that are not
3065
included in @option{-Wformat-nonliteral}.)
3066
 
3067
@item -Wformat=2
3068
@opindex Wformat=2
3069
@opindex Wno-format=2
3070
Enable @option{-Wformat} plus format checks not included in
3071
@option{-Wformat}.  Currently equivalent to @samp{-Wformat
3072
-Wformat-nonliteral -Wformat-security -Wformat-y2k}.
3073
 
3074
@item -Wnonnull @r{(C and Objective-C only)}
3075
@opindex Wnonnull
3076
@opindex Wno-nonnull
3077
Warn about passing a null pointer for arguments marked as
3078
requiring a non-null value by the @code{nonnull} function attribute.
3079
 
3080
@option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}.  It
3081
can be disabled with the @option{-Wno-nonnull} option.
3082
 
3083
@item -Winit-self @r{(C, C++, Objective-C and Objective-C++ only)}
3084
@opindex Winit-self
3085
@opindex Wno-init-self
3086
Warn about uninitialized variables which are initialized with themselves.
3087
Note this option can only be used with the @option{-Wuninitialized} option.
3088
 
3089
For example, GCC will warn about @code{i} being uninitialized in the
3090
following snippet only when @option{-Winit-self} has been specified:
3091
@smallexample
3092
@group
3093
int f()
3094
@{
3095
  int i = i;
3096
  return i;
3097
@}
3098
@end group
3099
@end smallexample
3100
 
3101
@item -Wimplicit-int @r{(C and Objective-C only)}
3102
@opindex Wimplicit-int
3103
@opindex Wno-implicit-int
3104
Warn when a declaration does not specify a type.
3105
This warning is enabled by @option{-Wall}.
3106
 
3107
@item -Wimplicit-function-declaration @r{(C and Objective-C only)}
3108
@opindex Wimplicit-function-declaration
3109
@opindex Wno-implicit-function-declaration
3110
Give a warning whenever a function is used before being declared. In
3111
C99 mode (@option{-std=c99} or @option{-std=gnu99}), this warning is
3112
enabled by default and it is made into an error by
3113
@option{-pedantic-errors}. This warning is also enabled by
3114
@option{-Wall}.
3115
 
3116
@item -Wimplicit
3117
@opindex Wimplicit
3118
@opindex Wno-implicit
3119
Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
3120
This warning is enabled by @option{-Wall}.
3121
 
3122
@item -Wignored-qualifiers @r{(C and C++ only)}
3123
@opindex Wignored-qualifiers
3124
@opindex Wno-ignored-qualifiers
3125
Warn if the return type of a function has a type qualifier
3126
such as @code{const}.  For ISO C such a type qualifier has no effect,
3127
since the value returned by a function is not an lvalue.
3128
For C++, the warning is only emitted for scalar types or @code{void}.
3129
ISO C prohibits qualified @code{void} return types on function
3130
definitions, so such return types always receive a warning
3131
even without this option.
3132
 
3133
This warning is also enabled by @option{-Wextra}.
3134
 
3135
@item -Wmain
3136
@opindex Wmain
3137
@opindex Wno-main
3138
Warn if the type of @samp{main} is suspicious.  @samp{main} should be
3139
a function with external linkage, returning int, taking either zero
3140
arguments, two, or three arguments of appropriate types.  This warning
3141
is enabled by default in C++ and is enabled by either @option{-Wall}
3142
or @option{-pedantic}.
3143
 
3144
@item -Wmissing-braces
3145
@opindex Wmissing-braces
3146
@opindex Wno-missing-braces
3147
Warn if an aggregate or union initializer is not fully bracketed.  In
3148
the following example, the initializer for @samp{a} is not fully
3149
bracketed, but that for @samp{b} is fully bracketed.
3150
 
3151
@smallexample
3152
int a[2][2] = @{ 0, 1, 2, 3 @};
3153
int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
3154
@end smallexample
3155
 
3156
This warning is enabled by @option{-Wall}.
3157
 
3158
@item -Wmissing-include-dirs @r{(C, C++, Objective-C and Objective-C++ only)}
3159
@opindex Wmissing-include-dirs
3160
@opindex Wno-missing-include-dirs
3161
Warn if a user-supplied include directory does not exist.
3162
 
3163
@item -Wparentheses
3164
@opindex Wparentheses
3165
@opindex Wno-parentheses
3166
Warn if parentheses are omitted in certain contexts, such
3167
as when there is an assignment in a context where a truth value
3168
is expected, or when operators are nested whose precedence people
3169
often get confused about.
3170
 
3171
Also warn if a comparison like @samp{x<=y<=z} appears; this is
3172
equivalent to @samp{(x<=y ? 1 : 0) <= z}, which is a different
3173
interpretation from that of ordinary mathematical notation.
3174
 
3175
Also warn about constructions where there may be confusion to which
3176
@code{if} statement an @code{else} branch belongs.  Here is an example of
3177
such a case:
3178
 
3179
@smallexample
3180
@group
3181
@{
3182
  if (a)
3183
    if (b)
3184
      foo ();
3185
  else
3186
    bar ();
3187
@}
3188
@end group
3189
@end smallexample
3190
 
3191
In C/C++, every @code{else} branch belongs to the innermost possible
3192
@code{if} statement, which in this example is @code{if (b)}.  This is
3193
often not what the programmer expected, as illustrated in the above
3194
example by indentation the programmer chose.  When there is the
3195
potential for this confusion, GCC will issue a warning when this flag
3196
is specified.  To eliminate the warning, add explicit braces around
3197
the innermost @code{if} statement so there is no way the @code{else}
3198
could belong to the enclosing @code{if}.  The resulting code would
3199
look like this:
3200
 
3201
@smallexample
3202
@group
3203
@{
3204
  if (a)
3205
    @{
3206
      if (b)
3207
        foo ();
3208
      else
3209
        bar ();
3210
    @}
3211
@}
3212
@end group
3213
@end smallexample
3214
 
3215
This warning is enabled by @option{-Wall}.
3216
 
3217
@item -Wsequence-point
3218
@opindex Wsequence-point
3219
@opindex Wno-sequence-point
3220
Warn about code that may have undefined semantics because of violations
3221
of sequence point rules in the C and C++ standards.
3222
 
3223
The C and C++ standards defines the order in which expressions in a C/C++
3224
program are evaluated in terms of @dfn{sequence points}, which represent
3225
a partial ordering between the execution of parts of the program: those
3226
executed before the sequence point, and those executed after it.  These
3227
occur after the evaluation of a full expression (one which is not part
3228
of a larger expression), after the evaluation of the first operand of a
3229
@code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
3230
function is called (but after the evaluation of its arguments and the
3231
expression denoting the called function), and in certain other places.
3232
Other than as expressed by the sequence point rules, the order of
3233
evaluation of subexpressions of an expression is not specified.  All
3234
these rules describe only a partial order rather than a total order,
3235
since, for example, if two functions are called within one expression
3236
with no sequence point between them, the order in which the functions
3237
are called is not specified.  However, the standards committee have
3238
ruled that function calls do not overlap.
3239
 
3240
It is not specified when between sequence points modifications to the
3241
values of objects take effect.  Programs whose behavior depends on this
3242
have undefined behavior; the C and C++ standards specify that ``Between
3243
the previous and next sequence point an object shall have its stored
3244
value modified at most once by the evaluation of an expression.
3245
Furthermore, the prior value shall be read only to determine the value
3246
to be stored.''.  If a program breaks these rules, the results on any
3247
particular implementation are entirely unpredictable.
3248
 
3249
Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
3250
= b[n++]} and @code{a[i++] = i;}.  Some more complicated cases are not
3251
diagnosed by this option, and it may give an occasional false positive
3252
result, but in general it has been found fairly effective at detecting
3253
this sort of problem in programs.
3254
 
3255
The standard is worded confusingly, therefore there is some debate
3256
over the precise meaning of the sequence point rules in subtle cases.
3257
Links to discussions of the problem, including proposed formal
3258
definitions, may be found on the GCC readings page, at
3259
@w{@uref{http://gcc.gnu.org/readings.html}}.
3260
 
3261
This warning is enabled by @option{-Wall} for C and C++.
3262
 
3263
@item -Wreturn-type
3264
@opindex Wreturn-type
3265
@opindex Wno-return-type
3266
Warn whenever a function is defined with a return-type that defaults
3267
to @code{int}.  Also warn about any @code{return} statement with no
3268
return-value in a function whose return-type is not @code{void}
3269
(falling off the end of the function body is considered returning
3270
without a value), and about a @code{return} statement with an
3271
expression in a function whose return-type is @code{void}.
3272
 
3273
For C++, a function without return type always produces a diagnostic
3274
message, even when @option{-Wno-return-type} is specified.  The only
3275
exceptions are @samp{main} and functions defined in system headers.
3276
 
3277
This warning is enabled by @option{-Wall}.
3278
 
3279
@item -Wswitch
3280
@opindex Wswitch
3281
@opindex Wno-switch
3282
Warn whenever a @code{switch} statement has an index of enumerated type
3283
and lacks a @code{case} for one or more of the named codes of that
3284
enumeration.  (The presence of a @code{default} label prevents this
3285
warning.)  @code{case} labels outside the enumeration range also
3286
provoke warnings when this option is used (even if there is a
3287
@code{default} label).
3288
This warning is enabled by @option{-Wall}.
3289
 
3290
@item -Wswitch-default
3291
@opindex Wswitch-default
3292
@opindex Wno-switch-default
3293
Warn whenever a @code{switch} statement does not have a @code{default}
3294
case.
3295
 
3296
@item -Wswitch-enum
3297
@opindex Wswitch-enum
3298
@opindex Wno-switch-enum
3299
Warn whenever a @code{switch} statement has an index of enumerated type
3300
and lacks a @code{case} for one or more of the named codes of that
3301
enumeration.  @code{case} labels outside the enumeration range also
3302
provoke warnings when this option is used.  The only difference
3303
between @option{-Wswitch} and this option is that this option gives a
3304
warning about an omitted enumeration code even if there is a
3305
@code{default} label.
3306
 
3307
@item -Wsync-nand @r{(C and C++ only)}
3308
@opindex Wsync-nand
3309
@opindex Wno-sync-nand
3310
Warn when @code{__sync_fetch_and_nand} and @code{__sync_nand_and_fetch}
3311
built-in functions are used.  These functions changed semantics in GCC 4.4.
3312
 
3313
@item -Wtrigraphs
3314
@opindex Wtrigraphs
3315
@opindex Wno-trigraphs
3316
Warn if any trigraphs are encountered that might change the meaning of
3317
the program (trigraphs within comments are not warned about).
3318
This warning is enabled by @option{-Wall}.
3319
 
3320
@item -Wunused-function
3321
@opindex Wunused-function
3322
@opindex Wno-unused-function
3323
Warn whenever a static function is declared but not defined or a
3324
non-inline static function is unused.
3325
This warning is enabled by @option{-Wall}.
3326
 
3327
@item -Wunused-label
3328
@opindex Wunused-label
3329
@opindex Wno-unused-label
3330
Warn whenever a label is declared but not used.
3331
This warning is enabled by @option{-Wall}.
3332
 
3333
To suppress this warning use the @samp{unused} attribute
3334
(@pxref{Variable Attributes}).
3335
 
3336
@item -Wunused-parameter
3337
@opindex Wunused-parameter
3338
@opindex Wno-unused-parameter
3339
Warn whenever a function parameter is unused aside from its declaration.
3340
 
3341
To suppress this warning use the @samp{unused} attribute
3342
(@pxref{Variable Attributes}).
3343
 
3344
@item -Wno-unused-result
3345
@opindex Wunused-result
3346
@opindex Wno-unused-result
3347
Do not warn if a caller of a function marked with attribute
3348
@code{warn_unused_result} (@pxref{Variable Attributes}) does not use
3349
its return value. The default is @option{-Wunused-result}.
3350
 
3351
@item -Wunused-variable
3352
@opindex Wunused-variable
3353
@opindex Wno-unused-variable
3354
Warn whenever a local variable or non-constant static variable is unused
3355
aside from its declaration.
3356
This warning is enabled by @option{-Wall}.
3357
 
3358
To suppress this warning use the @samp{unused} attribute
3359
(@pxref{Variable Attributes}).
3360
 
3361
@item -Wunused-value
3362
@opindex Wunused-value
3363
@opindex Wno-unused-value
3364
Warn whenever a statement computes a result that is explicitly not
3365
used. To suppress this warning cast the unused expression to
3366
@samp{void}. This includes an expression-statement or the left-hand
3367
side of a comma expression that contains no side effects. For example,
3368
an expression such as @samp{x[i,j]} will cause a warning, while
3369
@samp{x[(void)i,j]} will not.
3370
 
3371
This warning is enabled by @option{-Wall}.
3372
 
3373
@item -Wunused
3374
@opindex Wunused
3375
@opindex Wno-unused
3376
All the above @option{-Wunused} options combined.
3377
 
3378
In order to get a warning about an unused function parameter, you must
3379
either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
3380
@samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
3381
 
3382
@item -Wuninitialized
3383
@opindex Wuninitialized
3384
@opindex Wno-uninitialized
3385
Warn if an automatic variable is used without first being initialized
3386
or if a variable may be clobbered by a @code{setjmp} call. In C++,
3387
warn if a non-static reference or non-static @samp{const} member
3388
appears in a class without constructors.
3389
 
3390
If you want to warn about code which uses the uninitialized value of the
3391
variable in its own initializer, use the @option{-Winit-self} option.
3392
 
3393
These warnings occur for individual uninitialized or clobbered
3394
elements of structure, union or array variables as well as for
3395
variables which are uninitialized or clobbered as a whole.  They do
3396
not occur for variables or elements declared @code{volatile}.  Because
3397
these warnings depend on optimization, the exact variables or elements
3398
for which there are warnings will depend on the precise optimization
3399
options and version of GCC used.
3400
 
3401
Note that there may be no warning about a variable that is used only
3402
to compute a value that itself is never used, because such
3403
computations may be deleted by data flow analysis before the warnings
3404
are printed.
3405
 
3406
These warnings are made optional because GCC is not smart
3407
enough to see all the reasons why the code might be correct
3408
despite appearing to have an error.  Here is one example of how
3409
this can happen:
3410
 
3411
@smallexample
3412
@group
3413
@{
3414
  int x;
3415
  switch (y)
3416
    @{
3417
    case 1: x = 1;
3418
      break;
3419
    case 2: x = 4;
3420
      break;
3421
    case 3: x = 5;
3422
    @}
3423
  foo (x);
3424
@}
3425
@end group
3426
@end smallexample
3427
 
3428
@noindent
3429
If the value of @code{y} is always 1, 2 or 3, then @code{x} is
3430
always initialized, but GCC doesn't know this.  Here is
3431
another common case:
3432
 
3433
@smallexample
3434
@{
3435
  int save_y;
3436
  if (change_y) save_y = y, y = new_y;
3437
  @dots{}
3438
  if (change_y) y = save_y;
3439
@}
3440
@end smallexample
3441
 
3442
@noindent
3443
This has no bug because @code{save_y} is used only if it is set.
3444
 
3445
@cindex @code{longjmp} warnings
3446
This option also warns when a non-volatile automatic variable might be
3447
changed by a call to @code{longjmp}.  These warnings as well are possible
3448
only in optimizing compilation.
3449
 
3450
The compiler sees only the calls to @code{setjmp}.  It cannot know
3451
where @code{longjmp} will be called; in fact, a signal handler could
3452
call it at any point in the code.  As a result, you may get a warning
3453
even when there is in fact no problem because @code{longjmp} cannot
3454
in fact be called at the place which would cause a problem.
3455
 
3456
Some spurious warnings can be avoided if you declare all the functions
3457
you use that never return as @code{noreturn}.  @xref{Function
3458
Attributes}.
3459
 
3460
This warning is enabled by @option{-Wall} or @option{-Wextra}.
3461
 
3462
@item -Wunknown-pragmas
3463
@opindex Wunknown-pragmas
3464
@opindex Wno-unknown-pragmas
3465
@cindex warning for unknown pragmas
3466
@cindex unknown pragmas, warning
3467
@cindex pragmas, warning of unknown
3468
Warn when a #pragma directive is encountered which is not understood by
3469
GCC@.  If this command line option is used, warnings will even be issued
3470
for unknown pragmas in system header files.  This is not the case if
3471
the warnings were only enabled by the @option{-Wall} command line option.
3472
 
3473
@item -Wno-pragmas
3474
@opindex Wno-pragmas
3475
@opindex Wpragmas
3476
Do not warn about misuses of pragmas, such as incorrect parameters,
3477
invalid syntax, or conflicts between pragmas.  See also
3478
@samp{-Wunknown-pragmas}.
3479
 
3480
@item -Wstrict-aliasing
3481
@opindex Wstrict-aliasing
3482
@opindex Wno-strict-aliasing
3483
This option is only active when @option{-fstrict-aliasing} is active.
3484
It warns about code which might break the strict aliasing rules that the
3485
compiler is using for optimization.  The warning does not catch all
3486
cases, but does attempt to catch the more common pitfalls.  It is
3487
included in @option{-Wall}.
3488
It is equivalent to @option{-Wstrict-aliasing=3}
3489
 
3490
@item -Wstrict-aliasing=n
3491
@opindex Wstrict-aliasing=n
3492
@opindex Wno-strict-aliasing=n
3493
This option is only active when @option{-fstrict-aliasing} is active.
3494
It warns about code which might break the strict aliasing rules that the
3495
compiler is using for optimization.
3496
Higher levels correspond to higher accuracy (fewer false positives).
3497
Higher levels also correspond to more effort, similar to the way -O works.
3498
@option{-Wstrict-aliasing} is equivalent to @option{-Wstrict-aliasing=n},
3499
with n=3.
3500
 
3501
Level 1: Most aggressive, quick, least accurate.
3502
Possibly useful when higher levels
3503
do not warn but -fstrict-aliasing still breaks the code, as it has very few
3504
false negatives.  However, it has many false positives.
3505
Warns for all pointer conversions between possibly incompatible types,
3506
even if never dereferenced.  Runs in the frontend only.
3507
 
3508
Level 2: Aggressive, quick, not too precise.
3509
May still have many false positives (not as many as level 1 though),
3510
and few false negatives (but possibly more than level 1).
3511
Unlike level 1, it only warns when an address is taken.  Warns about
3512
incomplete types.  Runs in the frontend only.
3513
 
3514
Level 3 (default for @option{-Wstrict-aliasing}):
3515
Should have very few false positives and few false
3516
negatives.  Slightly slower than levels 1 or 2 when optimization is enabled.
3517
Takes care of the common pun+dereference pattern in the frontend:
3518
@code{*(int*)&some_float}.
3519
If optimization is enabled, it also runs in the backend, where it deals
3520
with multiple statement cases using flow-sensitive points-to information.
3521
Only warns when the converted pointer is dereferenced.
3522
Does not warn about incomplete types.
3523
 
3524
@item -Wstrict-overflow
3525
@itemx -Wstrict-overflow=@var{n}
3526
@opindex Wstrict-overflow
3527
@opindex Wno-strict-overflow
3528
This option is only active when @option{-fstrict-overflow} is active.
3529
It warns about cases where the compiler optimizes based on the
3530
assumption that signed overflow does not occur.  Note that it does not
3531
warn about all cases where the code might overflow: it only warns
3532
about cases where the compiler implements some optimization.  Thus
3533
this warning depends on the optimization level.
3534
 
3535
An optimization which assumes that signed overflow does not occur is
3536
perfectly safe if the values of the variables involved are such that
3537
overflow never does, in fact, occur.  Therefore this warning can
3538
easily give a false positive: a warning about code which is not
3539
actually a problem.  To help focus on important issues, several
3540
warning levels are defined.  No warnings are issued for the use of
3541
undefined signed overflow when estimating how many iterations a loop
3542
will require, in particular when determining whether a loop will be
3543
executed at all.
3544
 
3545
@table @gcctabopt
3546
@item -Wstrict-overflow=1
3547
Warn about cases which are both questionable and easy to avoid.  For
3548
example: @code{x + 1 > x}; with @option{-fstrict-overflow}, the
3549
compiler will simplify this to @code{1}.  This level of
3550
@option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
3551
are not, and must be explicitly requested.
3552
 
3553
@item -Wstrict-overflow=2
3554
Also warn about other cases where a comparison is simplified to a
3555
constant.  For example: @code{abs (x) >= 0}.  This can only be
3556
simplified when @option{-fstrict-overflow} is in effect, because
3557
@code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
3558
zero.  @option{-Wstrict-overflow} (with no level) is the same as
3559
@option{-Wstrict-overflow=2}.
3560
 
3561
@item -Wstrict-overflow=3
3562
Also warn about other cases where a comparison is simplified.  For
3563
example: @code{x + 1 > 1} will be simplified to @code{x > 0}.
3564
 
3565
@item -Wstrict-overflow=4
3566
Also warn about other simplifications not covered by the above cases.
3567
For example: @code{(x * 10) / 5} will be simplified to @code{x * 2}.
3568
 
3569
@item -Wstrict-overflow=5
3570
Also warn about cases where the compiler reduces the magnitude of a
3571
constant involved in a comparison.  For example: @code{x + 2 > y} will
3572
be simplified to @code{x + 1 >= y}.  This is reported only at the
3573
highest warning level because this simplification applies to many
3574
comparisons, so this warning level will give a very large number of
3575
false positives.
3576
@end table
3577
 
3578
@item -Warray-bounds
3579
@opindex Wno-array-bounds
3580
@opindex Warray-bounds
3581
This option is only active when @option{-ftree-vrp} is active
3582
(default for -O2 and above). It warns about subscripts to arrays
3583
that are always out of bounds. This warning is enabled by @option{-Wall}.
3584
 
3585
@item -Wno-div-by-zero
3586
@opindex Wno-div-by-zero
3587
@opindex Wdiv-by-zero
3588
Do not warn about compile-time integer division by zero.  Floating point
3589
division by zero is not warned about, as it can be a legitimate way of
3590
obtaining infinities and NaNs.
3591
 
3592
@item -Wsystem-headers
3593
@opindex Wsystem-headers
3594
@opindex Wno-system-headers
3595
@cindex warnings from system headers
3596
@cindex system headers, warnings from
3597
Print warning messages for constructs found in system header files.
3598
Warnings from system headers are normally suppressed, on the assumption
3599
that they usually do not indicate real problems and would only make the
3600
compiler output harder to read.  Using this command line option tells
3601
GCC to emit warnings from system headers as if they occurred in user
3602
code.  However, note that using @option{-Wall} in conjunction with this
3603
option will @emph{not} warn about unknown pragmas in system
3604
headers---for that, @option{-Wunknown-pragmas} must also be used.
3605
 
3606
@item -Wfloat-equal
3607
@opindex Wfloat-equal
3608
@opindex Wno-float-equal
3609
Warn if floating point values are used in equality comparisons.
3610
 
3611
The idea behind this is that sometimes it is convenient (for the
3612
programmer) to consider floating-point values as approximations to
3613
infinitely precise real numbers.  If you are doing this, then you need
3614
to compute (by analyzing the code, or in some other way) the maximum or
3615
likely maximum error that the computation introduces, and allow for it
3616
when performing comparisons (and when producing output, but that's a
3617
different problem).  In particular, instead of testing for equality, you
3618
would check to see whether the two values have ranges that overlap; and
3619
this is done with the relational operators, so equality comparisons are
3620
probably mistaken.
3621
 
3622
@item -Wtraditional @r{(C and Objective-C only)}
3623
@opindex Wtraditional
3624
@opindex Wno-traditional
3625
Warn about certain constructs that behave differently in traditional and
3626
ISO C@.  Also warn about ISO C constructs that have no traditional C
3627
equivalent, and/or problematic constructs which should be avoided.
3628
 
3629
@itemize @bullet
3630
@item
3631
Macro parameters that appear within string literals in the macro body.
3632
In traditional C macro replacement takes place within string literals,
3633
but does not in ISO C@.
3634
 
3635
@item
3636
In traditional C, some preprocessor directives did not exist.
3637
Traditional preprocessors would only consider a line to be a directive
3638
if the @samp{#} appeared in column 1 on the line.  Therefore
3639
@option{-Wtraditional} warns about directives that traditional C
3640
understands but would ignore because the @samp{#} does not appear as the
3641
first character on the line.  It also suggests you hide directives like
3642
@samp{#pragma} not understood by traditional C by indenting them.  Some
3643
traditional implementations would not recognize @samp{#elif}, so it
3644
suggests avoiding it altogether.
3645
 
3646
@item
3647
A function-like macro that appears without arguments.
3648
 
3649
@item
3650
The unary plus operator.
3651
 
3652
@item
3653
The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
3654
constant suffixes.  (Traditional C does support the @samp{L} suffix on integer
3655
constants.)  Note, these suffixes appear in macros defined in the system
3656
headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
3657
Use of these macros in user code might normally lead to spurious
3658
warnings, however GCC's integrated preprocessor has enough context to
3659
avoid warning in these cases.
3660
 
3661
@item
3662
A function declared external in one block and then used after the end of
3663
the block.
3664
 
3665
@item
3666
A @code{switch} statement has an operand of type @code{long}.
3667
 
3668
@item
3669
A non-@code{static} function declaration follows a @code{static} one.
3670
This construct is not accepted by some traditional C compilers.
3671
 
3672
@item
3673
The ISO type of an integer constant has a different width or
3674
signedness from its traditional type.  This warning is only issued if
3675
the base of the constant is ten.  I.e.@: hexadecimal or octal values, which
3676
typically represent bit patterns, are not warned about.
3677
 
3678
@item
3679
Usage of ISO string concatenation is detected.
3680
 
3681
@item
3682
Initialization of automatic aggregates.
3683
 
3684
@item
3685
Identifier conflicts with labels.  Traditional C lacks a separate
3686
namespace for labels.
3687
 
3688
@item
3689
Initialization of unions.  If the initializer is zero, the warning is
3690
omitted.  This is done under the assumption that the zero initializer in
3691
user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
3692
initializer warnings and relies on default initialization to zero in the
3693
traditional C case.
3694
 
3695
@item
3696
Conversions by prototypes between fixed/floating point values and vice
3697
versa.  The absence of these prototypes when compiling with traditional
3698
C would cause serious problems.  This is a subset of the possible
3699
conversion warnings, for the full set use @option{-Wtraditional-conversion}.
3700
 
3701
@item
3702
Use of ISO C style function definitions.  This warning intentionally is
3703
@emph{not} issued for prototype declarations or variadic functions
3704
because these ISO C features will appear in your code when using
3705
libiberty's traditional C compatibility macros, @code{PARAMS} and
3706
@code{VPARAMS}.  This warning is also bypassed for nested functions
3707
because that feature is already a GCC extension and thus not relevant to
3708
traditional C compatibility.
3709
@end itemize
3710
 
3711
@item -Wtraditional-conversion @r{(C and Objective-C only)}
3712
@opindex Wtraditional-conversion
3713
@opindex Wno-traditional-conversion
3714
Warn if a prototype causes a type conversion that is different from what
3715
would happen to the same argument in the absence of a prototype.  This
3716
includes conversions of fixed point to floating and vice versa, and
3717
conversions changing the width or signedness of a fixed point argument
3718
except when the same as the default promotion.
3719
 
3720
@item -Wdeclaration-after-statement @r{(C and Objective-C only)}
3721
@opindex Wdeclaration-after-statement
3722
@opindex Wno-declaration-after-statement
3723
Warn when a declaration is found after a statement in a block.  This
3724
construct, known from C++, was introduced with ISO C99 and is by default
3725
allowed in GCC@.  It is not supported by ISO C90 and was not supported by
3726
GCC versions before GCC 3.0.  @xref{Mixed Declarations}.
3727
 
3728
@item -Wundef
3729
@opindex Wundef
3730
@opindex Wno-undef
3731
Warn if an undefined identifier is evaluated in an @samp{#if} directive.
3732
 
3733
@item -Wno-endif-labels
3734
@opindex Wno-endif-labels
3735
@opindex Wendif-labels
3736
Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
3737
 
3738
@item -Wshadow
3739
@opindex Wshadow
3740
@opindex Wno-shadow
3741
Warn whenever a local variable shadows another local variable, parameter or
3742
global variable or whenever a built-in function is shadowed.
3743
 
3744
@item -Wlarger-than=@var{len}
3745
@opindex Wlarger-than=@var{len}
3746
@opindex Wlarger-than-@var{len}
3747
Warn whenever an object of larger than @var{len} bytes is defined.
3748
 
3749
@item -Wframe-larger-than=@var{len}
3750
@opindex Wframe-larger-than
3751
Warn if the size of a function frame is larger than @var{len} bytes.
3752
The computation done to determine the stack frame size is approximate
3753
and not conservative.
3754
The actual requirements may be somewhat greater than @var{len}
3755
even if you do not get a warning.  In addition, any space allocated
3756
via @code{alloca}, variable-length arrays, or related constructs
3757
is not included by the compiler when determining
3758
whether or not to issue a warning.
3759
 
3760
@item -Wunsafe-loop-optimizations
3761
@opindex Wunsafe-loop-optimizations
3762
@opindex Wno-unsafe-loop-optimizations
3763
Warn if the loop cannot be optimized because the compiler could not
3764
assume anything on the bounds of the loop indices.  With
3765
@option{-funsafe-loop-optimizations} warn if the compiler made
3766
such assumptions.
3767
 
3768
@item -Wno-pedantic-ms-format @r{(MinGW targets only)}
3769
@opindex Wno-pedantic-ms-format
3770
@opindex Wpedantic-ms-format
3771
Disables the warnings about non-ISO @code{printf} / @code{scanf} format
3772
width specifiers @code{I32}, @code{I64}, and @code{I} used on Windows targets
3773
depending on the MS runtime, when you are using the options @option{-Wformat}
3774
and @option{-pedantic} without gnu-extensions.
3775
 
3776
@item -Wpointer-arith
3777
@opindex Wpointer-arith
3778
@opindex Wno-pointer-arith
3779
Warn about anything that depends on the ``size of'' a function type or
3780
of @code{void}.  GNU C assigns these types a size of 1, for
3781
convenience in calculations with @code{void *} pointers and pointers
3782
to functions.  In C++, warn also when an arithmetic operation involves
3783
@code{NULL}.  This warning is also enabled by @option{-pedantic}.
3784
 
3785
@item -Wtype-limits
3786
@opindex Wtype-limits
3787
@opindex Wno-type-limits
3788
Warn if a comparison is always true or always false due to the limited
3789
range of the data type, but do not warn for constant expressions.  For
3790
example, warn if an unsigned variable is compared against zero with
3791
@samp{<} or @samp{>=}.  This warning is also enabled by
3792
@option{-Wextra}.
3793
 
3794
@item -Wbad-function-cast @r{(C and Objective-C only)}
3795
@opindex Wbad-function-cast
3796
@opindex Wno-bad-function-cast
3797
Warn whenever a function call is cast to a non-matching type.
3798
For example, warn if @code{int malloc()} is cast to @code{anything *}.
3799
 
3800
@item -Wc++-compat @r{(C and Objective-C only)}
3801
Warn about ISO C constructs that are outside of the common subset of
3802
ISO C and ISO C++, e.g.@: request for implicit conversion from
3803
@code{void *} to a pointer to non-@code{void} type.
3804
 
3805
@item -Wc++0x-compat @r{(C++ and Objective-C++ only)}
3806
Warn about C++ constructs whose meaning differs between ISO C++ 1998 and
3807
ISO C++ 200x, e.g., identifiers in ISO C++ 1998 that will become keywords
3808
in ISO C++ 200x.  This warning is enabled by @option{-Wall}.
3809
 
3810
@item -Wcast-qual
3811
@opindex Wcast-qual
3812
@opindex Wno-cast-qual
3813
Warn whenever a pointer is cast so as to remove a type qualifier from
3814
the target type.  For example, warn if a @code{const char *} is cast
3815
to an ordinary @code{char *}.
3816
 
3817
Also warn when making a cast which introduces a type qualifier in an
3818
unsafe way.  For example, casting @code{char **} to @code{const char **}
3819
is unsafe, as in this example:
3820
 
3821
@smallexample
3822
  /* p is char ** value.  */
3823
  const char **q = (const char **) p;
3824
  /* Assignment of readonly string to const char * is OK.  */
3825
  *q = "string";
3826
  /* Now char** pointer points to read-only memory.  */
3827
  **p = 'b';
3828
@end smallexample
3829
 
3830
@item -Wcast-align
3831
@opindex Wcast-align
3832
@opindex Wno-cast-align
3833
Warn whenever a pointer is cast such that the required alignment of the
3834
target is increased.  For example, warn if a @code{char *} is cast to
3835
an @code{int *} on machines where integers can only be accessed at
3836
two- or four-byte boundaries.
3837
 
3838
@item -Wwrite-strings
3839
@opindex Wwrite-strings
3840
@opindex Wno-write-strings
3841
When compiling C, give string constants the type @code{const
3842
char[@var{length}]} so that copying the address of one into a
3843
non-@code{const} @code{char *} pointer will get a warning.  These
3844
warnings will help you find at compile time code that can try to write
3845
into a string constant, but only if you have been very careful about
3846
using @code{const} in declarations and prototypes.  Otherwise, it will
3847
just be a nuisance. This is why we did not make @option{-Wall} request
3848
these warnings.
3849
 
3850
When compiling C++, warn about the deprecated conversion from string
3851
literals to @code{char *}.  This warning is enabled by default for C++
3852
programs.
3853
 
3854
@item -Wclobbered
3855
@opindex Wclobbered
3856
@opindex Wno-clobbered
3857
Warn for variables that might be changed by @samp{longjmp} or
3858
@samp{vfork}.  This warning is also enabled by @option{-Wextra}.
3859
 
3860
@item -Wconversion
3861
@opindex Wconversion
3862
@opindex Wno-conversion
3863
Warn for implicit conversions that may alter a value. This includes
3864
conversions between real and integer, like @code{abs (x)} when
3865
@code{x} is @code{double}; conversions between signed and unsigned,
3866
like @code{unsigned ui = -1}; and conversions to smaller types, like
3867
@code{sqrtf (M_PI)}. Do not warn for explicit casts like @code{abs
3868
((int) x)} and @code{ui = (unsigned) -1}, or if the value is not
3869
changed by the conversion like in @code{abs (2.0)}.  Warnings about
3870
conversions between signed and unsigned integers can be disabled by
3871
using @option{-Wno-sign-conversion}.
3872
 
3873
For C++, also warn for confusing overload resolution for user-defined
3874
conversions; and conversions that will never use a type conversion
3875
operator: conversions to @code{void}, the same type, a base class or a
3876
reference to them. Warnings about conversions between signed and
3877
unsigned integers are disabled by default in C++ unless
3878
@option{-Wsign-conversion} is explicitly enabled.
3879
 
3880
@item -Wno-conversion-null @r{(C++ and Objective-C++ only)}
3881
@opindex Wconversion-null
3882
@opindex Wno-conversion-null
3883
Do not warn for conversions between @code{NULL} and non-pointer
3884
types. @option{-Wconversion-null} is enabled by default.
3885
 
3886
@item -Wempty-body
3887
@opindex Wempty-body
3888
@opindex Wno-empty-body
3889
Warn if an empty body occurs in an @samp{if}, @samp{else} or @samp{do
3890
while} statement.  This warning is also enabled by @option{-Wextra}.
3891
 
3892
@item -Wenum-compare
3893
@opindex Wenum-compare
3894
@opindex Wno-enum-compare
3895
Warn about a comparison between values of different enum types. In C++
3896
this warning is enabled by default.  In C this warning is enabled by
3897
@option{-Wall}.
3898
 
3899
@item -Wjump-misses-init @r{(C, Objective-C only)}
3900
@opindex Wjump-misses-init
3901
@opindex Wno-jump-misses-init
3902
Warn if a @code{goto} statement or a @code{switch} statement jumps
3903
forward across the initialization of a variable, or jumps backward to a
3904
label after the variable has been initialized.  This only warns about
3905
variables which are initialized when they are declared.  This warning is
3906
only supported for C and Objective C; in C++ this sort of branch is an
3907
error in any case.
3908
 
3909
@option{-Wjump-misses-init} is included in @option{-Wc++-compat}.  It
3910
can be disabled with the @option{-Wno-jump-misses-init} option.
3911
 
3912
@item -Wsign-compare
3913
@opindex Wsign-compare
3914
@opindex Wno-sign-compare
3915
@cindex warning for comparison of signed and unsigned values
3916
@cindex comparison of signed and unsigned values, warning
3917
@cindex signed and unsigned values, comparison warning
3918
Warn when a comparison between signed and unsigned values could produce
3919
an incorrect result when the signed value is converted to unsigned.
3920
This warning is also enabled by @option{-Wextra}; to get the other warnings
3921
of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
3922
 
3923
@item -Wsign-conversion
3924
@opindex Wsign-conversion
3925
@opindex Wno-sign-conversion
3926
Warn for implicit conversions that may change the sign of an integer
3927
value, like assigning a signed integer expression to an unsigned
3928
integer variable. An explicit cast silences the warning. In C, this
3929
option is enabled also by @option{-Wconversion}.
3930
 
3931
@item -Waddress
3932
@opindex Waddress
3933
@opindex Wno-address
3934
Warn about suspicious uses of memory addresses. These include using
3935
the address of a function in a conditional expression, such as
3936
@code{void func(void); if (func)}, and comparisons against the memory
3937
address of a string literal, such as @code{if (x == "abc")}.  Such
3938
uses typically indicate a programmer error: the address of a function
3939
always evaluates to true, so their use in a conditional usually
3940
indicate that the programmer forgot the parentheses in a function
3941
call; and comparisons against string literals result in unspecified
3942
behavior and are not portable in C, so they usually indicate that the
3943
programmer intended to use @code{strcmp}.  This warning is enabled by
3944
@option{-Wall}.
3945
 
3946
@item -Wlogical-op
3947
@opindex Wlogical-op
3948
@opindex Wno-logical-op
3949
Warn about suspicious uses of logical operators in expressions.
3950
This includes using logical operators in contexts where a
3951
bit-wise operator is likely to be expected.
3952
 
3953
@item -Waggregate-return
3954
@opindex Waggregate-return
3955
@opindex Wno-aggregate-return
3956
Warn if any functions that return structures or unions are defined or
3957
called.  (In languages where you can return an array, this also elicits
3958
a warning.)
3959
 
3960
@item -Wno-attributes
3961
@opindex Wno-attributes
3962
@opindex Wattributes
3963
Do not warn if an unexpected @code{__attribute__} is used, such as
3964
unrecognized attributes, function attributes applied to variables,
3965
etc.  This will not stop errors for incorrect use of supported
3966
attributes.
3967
 
3968
@item -Wno-builtin-macro-redefined
3969
@opindex Wno-builtin-macro-redefined
3970
@opindex Wbuiltin-macro-redefined
3971
Do not warn if certain built-in macros are redefined.  This suppresses
3972
warnings for redefinition of @code{__TIMESTAMP__}, @code{__TIME__},
3973
@code{__DATE__}, @code{__FILE__}, and @code{__BASE_FILE__}.
3974
 
3975
@item -Wstrict-prototypes @r{(C and Objective-C only)}
3976
@opindex Wstrict-prototypes
3977
@opindex Wno-strict-prototypes
3978
Warn if a function is declared or defined without specifying the
3979
argument types.  (An old-style function definition is permitted without
3980
a warning if preceded by a declaration which specifies the argument
3981
types.)
3982
 
3983
@item -Wold-style-declaration @r{(C and Objective-C only)}
3984
@opindex Wold-style-declaration
3985
@opindex Wno-old-style-declaration
3986
Warn for obsolescent usages, according to the C Standard, in a
3987
declaration. For example, warn if storage-class specifiers like
3988
@code{static} are not the first things in a declaration.  This warning
3989
is also enabled by @option{-Wextra}.
3990
 
3991
@item -Wold-style-definition @r{(C and Objective-C only)}
3992
@opindex Wold-style-definition
3993
@opindex Wno-old-style-definition
3994
Warn if an old-style function definition is used.  A warning is given
3995
even if there is a previous prototype.
3996
 
3997
@item -Wmissing-parameter-type @r{(C and Objective-C only)}
3998
@opindex Wmissing-parameter-type
3999
@opindex Wno-missing-parameter-type
4000
A function parameter is declared without a type specifier in K&R-style
4001
functions:
4002
 
4003
@smallexample
4004
void foo(bar) @{ @}
4005
@end smallexample
4006
 
4007
This warning is also enabled by @option{-Wextra}.
4008
 
4009
@item -Wmissing-prototypes @r{(C and Objective-C only)}
4010
@opindex Wmissing-prototypes
4011
@opindex Wno-missing-prototypes
4012
Warn if a global function is defined without a previous prototype
4013
declaration.  This warning is issued even if the definition itself
4014
provides a prototype.  The aim is to detect global functions that fail
4015
to be declared in header files.
4016
 
4017
@item -Wmissing-declarations
4018
@opindex Wmissing-declarations
4019
@opindex Wno-missing-declarations
4020
Warn if a global function is defined without a previous declaration.
4021
Do so even if the definition itself provides a prototype.
4022
Use this option to detect global functions that are not declared in
4023
header files.  In C++, no warnings are issued for function templates,
4024
or for inline functions, or for functions in anonymous namespaces.
4025
 
4026
@item -Wmissing-field-initializers
4027
@opindex Wmissing-field-initializers
4028
@opindex Wno-missing-field-initializers
4029
@opindex W
4030
@opindex Wextra
4031
@opindex Wno-extra
4032
Warn if a structure's initializer has some fields missing.  For
4033
example, the following code would cause such a warning, because
4034
@code{x.h} is implicitly zero:
4035
 
4036
@smallexample
4037
struct s @{ int f, g, h; @};
4038
struct s x = @{ 3, 4 @};
4039
@end smallexample
4040
 
4041
This option does not warn about designated initializers, so the following
4042
modification would not trigger a warning:
4043
 
4044
@smallexample
4045
struct s @{ int f, g, h; @};
4046
struct s x = @{ .f = 3, .g = 4 @};
4047
@end smallexample
4048
 
4049
This warning is included in @option{-Wextra}.  To get other @option{-Wextra}
4050
warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
4051
 
4052
@item -Wmissing-noreturn
4053
@opindex Wmissing-noreturn
4054
@opindex Wno-missing-noreturn
4055
Warn about functions which might be candidates for attribute @code{noreturn}.
4056
Note these are only possible candidates, not absolute ones.  Care should
4057
be taken to manually verify functions actually do not ever return before
4058
adding the @code{noreturn} attribute, otherwise subtle code generation
4059
bugs could be introduced.  You will not get a warning for @code{main} in
4060
hosted C environments.
4061
 
4062
@item -Wmissing-format-attribute
4063
@opindex Wmissing-format-attribute
4064
@opindex Wno-missing-format-attribute
4065
@opindex Wformat
4066
@opindex Wno-format
4067
Warn about function pointers which might be candidates for @code{format}
4068
attributes.  Note these are only possible candidates, not absolute ones.
4069
GCC will guess that function pointers with @code{format} attributes that
4070
are used in assignment, initialization, parameter passing or return
4071
statements should have a corresponding @code{format} attribute in the
4072
resulting type.  I.e.@: the left-hand side of the assignment or
4073
initialization, the type of the parameter variable, or the return type
4074
of the containing function respectively should also have a @code{format}
4075
attribute to avoid the warning.
4076
 
4077
GCC will also warn about function definitions which might be
4078
candidates for @code{format} attributes.  Again, these are only
4079
possible candidates.  GCC will guess that @code{format} attributes
4080
might be appropriate for any function that calls a function like
4081
@code{vprintf} or @code{vscanf}, but this might not always be the
4082
case, and some functions for which @code{format} attributes are
4083
appropriate may not be detected.
4084
 
4085
@item -Wno-multichar
4086
@opindex Wno-multichar
4087
@opindex Wmultichar
4088
Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
4089
Usually they indicate a typo in the user's code, as they have
4090
implementation-defined values, and should not be used in portable code.
4091
 
4092
@item -Wnormalized=<none|id|nfc|nfkc>
4093
@opindex Wnormalized=
4094
@cindex NFC
4095
@cindex NFKC
4096
@cindex character set, input normalization
4097
In ISO C and ISO C++, two identifiers are different if they are
4098
different sequences of characters.  However, sometimes when characters
4099
outside the basic ASCII character set are used, you can have two
4100
different character sequences that look the same.  To avoid confusion,
4101
the ISO 10646 standard sets out some @dfn{normalization rules} which
4102
when applied ensure that two sequences that look the same are turned into
4103
the same sequence.  GCC can warn you if you are using identifiers which
4104
have not been normalized; this option controls that warning.
4105
 
4106
There are four levels of warning that GCC supports.  The default is
4107
@option{-Wnormalized=nfc}, which warns about any identifier which is
4108
not in the ISO 10646 ``C'' normalized form, @dfn{NFC}.  NFC is the
4109
recommended form for most uses.
4110
 
4111
Unfortunately, there are some characters which ISO C and ISO C++ allow
4112
in identifiers that when turned into NFC aren't allowable as
4113
identifiers.  That is, there's no way to use these symbols in portable
4114
ISO C or C++ and have all your identifiers in NFC@.
4115
@option{-Wnormalized=id} suppresses the warning for these characters.
4116
It is hoped that future versions of the standards involved will correct
4117
this, which is why this option is not the default.
4118
 
4119
You can switch the warning off for all characters by writing
4120
@option{-Wnormalized=none}.  You would only want to do this if you
4121
were using some other normalization scheme (like ``D''), because
4122
otherwise you can easily create bugs that are literally impossible to see.
4123
 
4124
Some characters in ISO 10646 have distinct meanings but look identical
4125
in some fonts or display methodologies, especially once formatting has
4126
been applied.  For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
4127
LETTER N'', will display just like a regular @code{n} which has been
4128
placed in a superscript.  ISO 10646 defines the @dfn{NFKC}
4129
normalization scheme to convert all these into a standard form as
4130
well, and GCC will warn if your code is not in NFKC if you use
4131
@option{-Wnormalized=nfkc}.  This warning is comparable to warning
4132
about every identifier that contains the letter O because it might be
4133
confused with the digit 0, and so is not the default, but may be
4134
useful as a local coding convention if the programming environment is
4135
unable to be fixed to display these characters distinctly.
4136
 
4137
@item -Wno-deprecated
4138
@opindex Wno-deprecated
4139
@opindex Wdeprecated
4140
Do not warn about usage of deprecated features.  @xref{Deprecated Features}.
4141
 
4142
@item -Wno-deprecated-declarations
4143
@opindex Wno-deprecated-declarations
4144
@opindex Wdeprecated-declarations
4145
Do not warn about uses of functions (@pxref{Function Attributes}),
4146
variables (@pxref{Variable Attributes}), and types (@pxref{Type
4147
Attributes}) marked as deprecated by using the @code{deprecated}
4148
attribute.
4149
 
4150
@item -Wno-overflow
4151
@opindex Wno-overflow
4152
@opindex Woverflow
4153
Do not warn about compile-time overflow in constant expressions.
4154
 
4155
@item -Woverride-init @r{(C and Objective-C only)}
4156
@opindex Woverride-init
4157
@opindex Wno-override-init
4158
@opindex W
4159
@opindex Wextra
4160
@opindex Wno-extra
4161
Warn if an initialized field without side effects is overridden when
4162
using designated initializers (@pxref{Designated Inits, , Designated
4163
Initializers}).
4164
 
4165
This warning is included in @option{-Wextra}.  To get other
4166
@option{-Wextra} warnings without this one, use @samp{-Wextra
4167
-Wno-override-init}.
4168
 
4169
@item -Wpacked
4170
@opindex Wpacked
4171
@opindex Wno-packed
4172
Warn if a structure is given the packed attribute, but the packed
4173
attribute has no effect on the layout or size of the structure.
4174
Such structures may be mis-aligned for little benefit.  For
4175
instance, in this code, the variable @code{f.x} in @code{struct bar}
4176
will be misaligned even though @code{struct bar} does not itself
4177
have the packed attribute:
4178
 
4179
@smallexample
4180
@group
4181
struct foo @{
4182
  int x;
4183
  char a, b, c, d;
4184
@} __attribute__((packed));
4185
struct bar @{
4186
  char z;
4187
  struct foo f;
4188
@};
4189
@end group
4190
@end smallexample
4191
 
4192
@item -Wpacked-bitfield-compat
4193
@opindex Wpacked-bitfield-compat
4194
@opindex Wno-packed-bitfield-compat
4195
The 4.1, 4.2 and 4.3 series of GCC ignore the @code{packed} attribute
4196
on bit-fields of type @code{char}.  This has been fixed in GCC 4.4 but
4197
the change can lead to differences in the structure layout.  GCC
4198
informs you when the offset of such a field has changed in GCC 4.4.
4199
For example there is no longer a 4-bit padding between field @code{a}
4200
and @code{b} in this structure:
4201
 
4202
@smallexample
4203
struct foo
4204
@{
4205
  char a:4;
4206
  char b:8;
4207
@} __attribute__ ((packed));
4208
@end smallexample
4209
 
4210
This warning is enabled by default.  Use
4211
@option{-Wno-packed-bitfield-compat} to disable this warning.
4212
 
4213
@item -Wpadded
4214
@opindex Wpadded
4215
@opindex Wno-padded
4216
Warn if padding is included in a structure, either to align an element
4217
of the structure or to align the whole structure.  Sometimes when this
4218
happens it is possible to rearrange the fields of the structure to
4219
reduce the padding and so make the structure smaller.
4220
 
4221
@item -Wredundant-decls
4222
@opindex Wredundant-decls
4223
@opindex Wno-redundant-decls
4224
Warn if anything is declared more than once in the same scope, even in
4225
cases where multiple declaration is valid and changes nothing.
4226
 
4227
@item -Wnested-externs @r{(C and Objective-C only)}
4228
@opindex Wnested-externs
4229
@opindex Wno-nested-externs
4230
Warn if an @code{extern} declaration is encountered within a function.
4231
 
4232
@item -Winline
4233
@opindex Winline
4234
@opindex Wno-inline
4235
Warn if a function can not be inlined and it was declared as inline.
4236
Even with this option, the compiler will not warn about failures to
4237
inline functions declared in system headers.
4238
 
4239
The compiler uses a variety of heuristics to determine whether or not
4240
to inline a function.  For example, the compiler takes into account
4241
the size of the function being inlined and the amount of inlining
4242
that has already been done in the current function.  Therefore,
4243
seemingly insignificant changes in the source program can cause the
4244
warnings produced by @option{-Winline} to appear or disappear.
4245
 
4246
@item -Wno-invalid-offsetof @r{(C++ and Objective-C++ only)}
4247
@opindex Wno-invalid-offsetof
4248
@opindex Winvalid-offsetof
4249
Suppress warnings from applying the @samp{offsetof} macro to a non-POD
4250
type.  According to the 1998 ISO C++ standard, applying @samp{offsetof}
4251
to a non-POD type is undefined.  In existing C++ implementations,
4252
however, @samp{offsetof} typically gives meaningful results even when
4253
applied to certain kinds of non-POD types. (Such as a simple
4254
@samp{struct} that fails to be a POD type only by virtue of having a
4255
constructor.)  This flag is for users who are aware that they are
4256
writing nonportable code and who have deliberately chosen to ignore the
4257
warning about it.
4258
 
4259
The restrictions on @samp{offsetof} may be relaxed in a future version
4260
of the C++ standard.
4261
 
4262
@item -Wno-int-to-pointer-cast @r{(C and Objective-C only)}
4263
@opindex Wno-int-to-pointer-cast
4264
@opindex Wint-to-pointer-cast
4265
Suppress warnings from casts to pointer type of an integer of a
4266
different size.
4267
 
4268
@item -Wno-pointer-to-int-cast @r{(C and Objective-C only)}
4269
@opindex Wno-pointer-to-int-cast
4270
@opindex Wpointer-to-int-cast
4271
Suppress warnings from casts from a pointer to an integer type of a
4272
different size.
4273
 
4274
@item -Winvalid-pch
4275
@opindex Winvalid-pch
4276
@opindex Wno-invalid-pch
4277
Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
4278
the search path but can't be used.
4279
 
4280
@item -Wlong-long
4281
@opindex Wlong-long
4282
@opindex Wno-long-long
4283
Warn if @samp{long long} type is used.  This is enabled by either
4284
@option{-pedantic} or @option{-Wtraditional} in ISO C90 and C++98
4285
modes.  To inhibit the warning messages, use @option{-Wno-long-long}.
4286
 
4287
@item -Wvariadic-macros
4288
@opindex Wvariadic-macros
4289
@opindex Wno-variadic-macros
4290
Warn if variadic macros are used in pedantic ISO C90 mode, or the GNU
4291
alternate syntax when in pedantic ISO C99 mode.  This is default.
4292
To inhibit the warning messages, use @option{-Wno-variadic-macros}.
4293
 
4294
@item -Wvla
4295
@opindex Wvla
4296
@opindex Wno-vla
4297
Warn if variable length array is used in the code.
4298
@option{-Wno-vla} will prevent the @option{-pedantic} warning of
4299
the variable length array.
4300
 
4301
@item -Wvolatile-register-var
4302
@opindex Wvolatile-register-var
4303
@opindex Wno-volatile-register-var
4304
Warn if a register variable is declared volatile.  The volatile
4305
modifier does not inhibit all optimizations that may eliminate reads
4306
and/or writes to register variables.  This warning is enabled by
4307
@option{-Wall}.
4308
 
4309
@item -Wdisabled-optimization
4310
@opindex Wdisabled-optimization
4311
@opindex Wno-disabled-optimization
4312
Warn if a requested optimization pass is disabled.  This warning does
4313
not generally indicate that there is anything wrong with your code; it
4314
merely indicates that GCC's optimizers were unable to handle the code
4315
effectively.  Often, the problem is that your code is too big or too
4316
complex; GCC will refuse to optimize programs when the optimization
4317
itself is likely to take inordinate amounts of time.
4318
 
4319
@item -Wpointer-sign @r{(C and Objective-C only)}
4320
@opindex Wpointer-sign
4321
@opindex Wno-pointer-sign
4322
Warn for pointer argument passing or assignment with different signedness.
4323
This option is only supported for C and Objective-C@.  It is implied by
4324
@option{-Wall} and by @option{-pedantic}, which can be disabled with
4325
@option{-Wno-pointer-sign}.
4326
 
4327
@item -Wstack-protector
4328
@opindex Wstack-protector
4329
@opindex Wno-stack-protector
4330
This option is only active when @option{-fstack-protector} is active.  It
4331
warns about functions that will not be protected against stack smashing.
4332
 
4333
@item -Wno-mudflap
4334
@opindex Wno-mudflap
4335
Suppress warnings about constructs that cannot be instrumented by
4336
@option{-fmudflap}.
4337
 
4338
@item -Woverlength-strings
4339
@opindex Woverlength-strings
4340
@opindex Wno-overlength-strings
4341
Warn about string constants which are longer than the ``minimum
4342
maximum'' length specified in the C standard.  Modern compilers
4343
generally allow string constants which are much longer than the
4344
standard's minimum limit, but very portable programs should avoid
4345
using longer strings.
4346
 
4347
The limit applies @emph{after} string constant concatenation, and does
4348
not count the trailing NUL@.  In C90, the limit was 509 characters; in
4349
C99, it was raised to 4095.  C++98 does not specify a normative
4350
minimum maximum, so we do not diagnose overlength strings in C++@.
4351
 
4352
This option is implied by @option{-pedantic}, and can be disabled with
4353
@option{-Wno-overlength-strings}.
4354
 
4355
@item -Wunsuffixed-float-constants @r{(C and Objective-C only)}
4356
@opindex Wunsuffixed-float-constants
4357
 
4358
GCC will issue a warning for any floating constant that does not have
4359
a suffix.  When used together with @option{-Wsystem-headers} it will
4360
warn about such constants in system header files.  This can be useful
4361
when preparing code to use with the @code{FLOAT_CONST_DECIMAL64} pragma
4362
from the decimal floating-point extension to C99.
4363
@end table
4364
 
4365
@node Debugging Options
4366
@section Options for Debugging Your Program or GCC
4367
@cindex options, debugging
4368
@cindex debugging information options
4369
 
4370
GCC has various special options that are used for debugging
4371
either your program or GCC:
4372
 
4373
@table @gcctabopt
4374
@item -g
4375
@opindex g
4376
Produce debugging information in the operating system's native format
4377
(stabs, COFF, XCOFF, or DWARF 2)@.  GDB can work with this debugging
4378
information.
4379
 
4380
On most systems that use stabs format, @option{-g} enables use of extra
4381
debugging information that only GDB can use; this extra information
4382
makes debugging work better in GDB but will probably make other debuggers
4383
crash or
4384
refuse to read the program.  If you want to control for certain whether
4385
to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
4386
@option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
4387
 
4388
GCC allows you to use @option{-g} with
4389
@option{-O}.  The shortcuts taken by optimized code may occasionally
4390
produce surprising results: some variables you declared may not exist
4391
at all; flow of control may briefly move where you did not expect it;
4392
some statements may not be executed because they compute constant
4393
results or their values were already at hand; some statements may
4394
execute in different places because they were moved out of loops.
4395
 
4396
Nevertheless it proves possible to debug optimized output.  This makes
4397
it reasonable to use the optimizer for programs that might have bugs.
4398
 
4399
The following options are useful when GCC is generated with the
4400
capability for more than one debugging format.
4401
 
4402
@item -ggdb
4403
@opindex ggdb
4404
Produce debugging information for use by GDB@.  This means to use the
4405
most expressive format available (DWARF 2, stabs, or the native format
4406
if neither of those are supported), including GDB extensions if at all
4407
possible.
4408
 
4409
@item -gstabs
4410
@opindex gstabs
4411
Produce debugging information in stabs format (if that is supported),
4412
without GDB extensions.  This is the format used by DBX on most BSD
4413
systems.  On MIPS, Alpha and System V Release 4 systems this option
4414
produces stabs debugging output which is not understood by DBX or SDB@.
4415
On System V Release 4 systems this option requires the GNU assembler.
4416
 
4417
@item -feliminate-unused-debug-symbols
4418
@opindex feliminate-unused-debug-symbols
4419
Produce debugging information in stabs format (if that is supported),
4420
for only symbols that are actually used.
4421
 
4422
@item -femit-class-debug-always
4423
Instead of emitting debugging information for a C++ class in only one
4424
object file, emit it in all object files using the class.  This option
4425
should be used only with debuggers that are unable to handle the way GCC
4426
normally emits debugging information for classes because using this
4427
option will increase the size of debugging information by as much as a
4428
factor of two.
4429
 
4430
@item -gstabs+
4431
@opindex gstabs+
4432
Produce debugging information in stabs format (if that is supported),
4433
using GNU extensions understood only by the GNU debugger (GDB)@.  The
4434
use of these extensions is likely to make other debuggers crash or
4435
refuse to read the program.
4436
 
4437
@item -gcoff
4438
@opindex gcoff
4439
Produce debugging information in COFF format (if that is supported).
4440
This is the format used by SDB on most System V systems prior to
4441
System V Release 4.
4442
 
4443
@item -gxcoff
4444
@opindex gxcoff
4445
Produce debugging information in XCOFF format (if that is supported).
4446
This is the format used by the DBX debugger on IBM RS/6000 systems.
4447
 
4448
@item -gxcoff+
4449
@opindex gxcoff+
4450
Produce debugging information in XCOFF format (if that is supported),
4451
using GNU extensions understood only by the GNU debugger (GDB)@.  The
4452
use of these extensions is likely to make other debuggers crash or
4453
refuse to read the program, and may cause assemblers other than the GNU
4454
assembler (GAS) to fail with an error.
4455
 
4456
@item -gdwarf-@var{version}
4457
@opindex gdwarf-@var{version}
4458
Produce debugging information in DWARF format (if that is
4459
supported).  This is the format used by DBX on IRIX 6.  The value
4460
of @var{version} may be either 2, 3 or 4; the default version is 2.
4461
 
4462
Note that with DWARF version 2 some ports require, and will always
4463
use, some non-conflicting DWARF 3 extensions in the unwind tables.
4464
 
4465
Version 4 may require GDB 7.0 and @option{-fvar-tracking-assignments}
4466
for maximum benefit.
4467
 
4468
@item -gstrict-dwarf
4469
@opindex gstrict-dwarf
4470
Disallow using extensions of later DWARF standard version than selected
4471
with @option{-gdwarf-@var{version}}.  On most targets using non-conflicting
4472
DWARF extensions from later standard versions is allowed.
4473
 
4474
@item -gno-strict-dwarf
4475
@opindex gno-strict-dwarf
4476
Allow using extensions of later DWARF standard version than selected with
4477
@option{-gdwarf-@var{version}}.
4478
 
4479
@item -gvms
4480
@opindex gvms
4481
Produce debugging information in VMS debug format (if that is
4482
supported).  This is the format used by DEBUG on VMS systems.
4483
 
4484
@item -g@var{level}
4485
@itemx -ggdb@var{level}
4486
@itemx -gstabs@var{level}
4487
@itemx -gcoff@var{level}
4488
@itemx -gxcoff@var{level}
4489
@itemx -gvms@var{level}
4490
Request debugging information and also use @var{level} to specify how
4491
much information.  The default level is 2.
4492
 
4493
Level 0 produces no debug information at all.  Thus, @option{-g0} negates
4494
@option{-g}.
4495
 
4496
Level 1 produces minimal information, enough for making backtraces in
4497
parts of the program that you don't plan to debug.  This includes
4498
descriptions of functions and external variables, but no information
4499
about local variables and no line numbers.
4500
 
4501
Level 3 includes extra information, such as all the macro definitions
4502
present in the program.  Some debuggers support macro expansion when
4503
you use @option{-g3}.
4504
 
4505
@option{-gdwarf-2} does not accept a concatenated debug level, because
4506
GCC used to support an option @option{-gdwarf} that meant to generate
4507
debug information in version 1 of the DWARF format (which is very
4508
different from version 2), and it would have been too confusing.  That
4509
debug format is long obsolete, but the option cannot be changed now.
4510
Instead use an additional @option{-g@var{level}} option to change the
4511
debug level for DWARF.
4512
 
4513
@item -gtoggle
4514
@opindex gtoggle
4515
Turn off generation of debug info, if leaving out this option would have
4516
generated it, or turn it on at level 2 otherwise.  The position of this
4517
argument in the command line does not matter, it takes effect after all
4518
other options are processed, and it does so only once, no matter how
4519
many times it is given.  This is mainly intended to be used with
4520
@option{-fcompare-debug}.
4521
 
4522
@item -fdump-final-insns@r{[}=@var{file}@r{]}
4523
@opindex fdump-final-insns
4524
Dump the final internal representation (RTL) to @var{file}.  If the
4525
optional argument is omitted (or if @var{file} is @code{.}), the name
4526
of the dump file will be determined by appending @code{.gkd} to the
4527
compilation output file name.
4528
 
4529
@item -fcompare-debug@r{[}=@var{opts}@r{]}
4530
@opindex fcompare-debug
4531
@opindex fno-compare-debug
4532
If no error occurs during compilation, run the compiler a second time,
4533
adding @var{opts} and @option{-fcompare-debug-second} to the arguments
4534
passed to the second compilation.  Dump the final internal
4535
representation in both compilations, and print an error if they differ.
4536
 
4537
If the equal sign is omitted, the default @option{-gtoggle} is used.
4538
 
4539
The environment variable @env{GCC_COMPARE_DEBUG}, if defined, non-empty
4540
and nonzero, implicitly enables @option{-fcompare-debug}.  If
4541
@env{GCC_COMPARE_DEBUG} is defined to a string starting with a dash,
4542
then it is used for @var{opts}, otherwise the default @option{-gtoggle}
4543
is used.
4544
 
4545
@option{-fcompare-debug=}, with the equal sign but without @var{opts},
4546
is equivalent to @option{-fno-compare-debug}, which disables the dumping
4547
of the final representation and the second compilation, preventing even
4548
@env{GCC_COMPARE_DEBUG} from taking effect.
4549
 
4550
To verify full coverage during @option{-fcompare-debug} testing, set
4551
@env{GCC_COMPARE_DEBUG} to say @samp{-fcompare-debug-not-overridden},
4552
which GCC will reject as an invalid option in any actual compilation
4553
(rather than preprocessing, assembly or linking).  To get just a
4554
warning, setting @env{GCC_COMPARE_DEBUG} to @samp{-w%n-fcompare-debug
4555
not overridden} will do.
4556
 
4557
@item -fcompare-debug-second
4558
@opindex fcompare-debug-second
4559
This option is implicitly passed to the compiler for the second
4560
compilation requested by @option{-fcompare-debug}, along with options to
4561
silence warnings, and omitting other options that would cause
4562
side-effect compiler outputs to files or to the standard output.  Dump
4563
files and preserved temporary files are renamed so as to contain the
4564
@code{.gk} additional extension during the second compilation, to avoid
4565
overwriting those generated by the first.
4566
 
4567
When this option is passed to the compiler driver, it causes the
4568
@emph{first} compilation to be skipped, which makes it useful for little
4569
other than debugging the compiler proper.
4570
 
4571
@item -feliminate-dwarf2-dups
4572
@opindex feliminate-dwarf2-dups
4573
Compress DWARF2 debugging information by eliminating duplicated
4574
information about each symbol.  This option only makes sense when
4575
generating DWARF2 debugging information with @option{-gdwarf-2}.
4576
 
4577
@item -femit-struct-debug-baseonly
4578
Emit debug information for struct-like types
4579
only when the base name of the compilation source file
4580
matches the base name of file in which the struct was defined.
4581
 
4582
This option substantially reduces the size of debugging information,
4583
but at significant potential loss in type information to the debugger.
4584
See @option{-femit-struct-debug-reduced} for a less aggressive option.
4585
See @option{-femit-struct-debug-detailed} for more detailed control.
4586
 
4587
This option works only with DWARF 2.
4588
 
4589
@item -femit-struct-debug-reduced
4590
Emit debug information for struct-like types
4591
only when the base name of the compilation source file
4592
matches the base name of file in which the type was defined,
4593
unless the struct is a template or defined in a system header.
4594
 
4595
This option significantly reduces the size of debugging information,
4596
with some potential loss in type information to the debugger.
4597
See @option{-femit-struct-debug-baseonly} for a more aggressive option.
4598
See @option{-femit-struct-debug-detailed} for more detailed control.
4599
 
4600
This option works only with DWARF 2.
4601
 
4602
@item -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]}
4603
Specify the struct-like types
4604
for which the compiler will generate debug information.
4605
The intent is to reduce duplicate struct debug information
4606
between different object files within the same program.
4607
 
4608
This option is a detailed version of
4609
@option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly},
4610
which will serve for most needs.
4611
 
4612
A specification has the syntax
4613
[@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none})
4614
 
4615
The optional first word limits the specification to
4616
structs that are used directly (@samp{dir:}) or used indirectly (@samp{ind:}).
4617
A struct type is used directly when it is the type of a variable, member.
4618
Indirect uses arise through pointers to structs.
4619
That is, when use of an incomplete struct would be legal, the use is indirect.
4620
An example is
4621
@samp{struct one direct; struct two * indirect;}.
4622
 
4623
The optional second word limits the specification to
4624
ordinary structs (@samp{ord:}) or generic structs (@samp{gen:}).
4625
Generic structs are a bit complicated to explain.
4626
For C++, these are non-explicit specializations of template classes,
4627
or non-template classes within the above.
4628
Other programming languages have generics,
4629
but @samp{-femit-struct-debug-detailed} does not yet implement them.
4630
 
4631
The third word specifies the source files for those
4632
structs for which the compiler will emit debug information.
4633
The values @samp{none} and @samp{any} have the normal meaning.
4634
The value @samp{base} means that
4635
the base of name of the file in which the type declaration appears
4636
must match the base of the name of the main compilation file.
4637
In practice, this means that
4638
types declared in @file{foo.c} and @file{foo.h} will have debug information,
4639
but types declared in other header will not.
4640
The value @samp{sys} means those types satisfying @samp{base}
4641
or declared in system or compiler headers.
4642
 
4643
You may need to experiment to determine the best settings for your application.
4644
 
4645
The default is @samp{-femit-struct-debug-detailed=all}.
4646
 
4647
This option works only with DWARF 2.
4648
 
4649
@item -fenable-icf-debug
4650
@opindex fenable-icf-debug
4651
Generate additional debug information to support identical code folding (ICF).
4652
This option only works with DWARF version 2 or higher.
4653
 
4654
@item -fno-merge-debug-strings
4655
@opindex fmerge-debug-strings
4656
@opindex fno-merge-debug-strings
4657
Direct the linker to not merge together strings in the debugging
4658
information which are identical in different object files.  Merging is
4659
not supported by all assemblers or linkers.  Merging decreases the size
4660
of the debug information in the output file at the cost of increasing
4661
link processing time.  Merging is enabled by default.
4662
 
4663
@item -fdebug-prefix-map=@var{old}=@var{new}
4664
@opindex fdebug-prefix-map
4665
When compiling files in directory @file{@var{old}}, record debugging
4666
information describing them as in @file{@var{new}} instead.
4667
 
4668
@item -fno-dwarf2-cfi-asm
4669
@opindex fdwarf2-cfi-asm
4670
@opindex fno-dwarf2-cfi-asm
4671
Emit DWARF 2 unwind info as compiler generated @code{.eh_frame} section
4672
instead of using GAS @code{.cfi_*} directives.
4673
 
4674
@cindex @command{prof}
4675
@item -p
4676
@opindex p
4677
Generate extra code to write profile information suitable for the
4678
analysis program @command{prof}.  You must use this option when compiling
4679
the source files you want data about, and you must also use it when
4680
linking.
4681
 
4682
@cindex @command{gprof}
4683
@item -pg
4684
@opindex pg
4685
Generate extra code to write profile information suitable for the
4686
analysis program @command{gprof}.  You must use this option when compiling
4687
the source files you want data about, and you must also use it when
4688
linking.
4689
 
4690
@item -Q
4691
@opindex Q
4692
Makes the compiler print out each function name as it is compiled, and
4693
print some statistics about each pass when it finishes.
4694
 
4695
@item -ftime-report
4696
@opindex ftime-report
4697
Makes the compiler print some statistics about the time consumed by each
4698
pass when it finishes.
4699
 
4700
@item -fmem-report
4701
@opindex fmem-report
4702
Makes the compiler print some statistics about permanent memory
4703
allocation when it finishes.
4704
 
4705
@item -fpre-ipa-mem-report
4706
@opindex fpre-ipa-mem-report
4707
@item -fpost-ipa-mem-report
4708
@opindex fpost-ipa-mem-report
4709
Makes the compiler print some statistics about permanent memory
4710
allocation before or after interprocedural optimization.
4711
 
4712
@item -fprofile-arcs
4713
@opindex fprofile-arcs
4714
Add code so that program flow @dfn{arcs} are instrumented.  During
4715
execution the program records how many times each branch and call is
4716
executed and how many times it is taken or returns.  When the compiled
4717
program exits it saves this data to a file called
4718
@file{@var{auxname}.gcda} for each source file.  The data may be used for
4719
profile-directed optimizations (@option{-fbranch-probabilities}), or for
4720
test coverage analysis (@option{-ftest-coverage}).  Each object file's
4721
@var{auxname} is generated from the name of the output file, if
4722
explicitly specified and it is not the final executable, otherwise it is
4723
the basename of the source file.  In both cases any suffix is removed
4724
(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
4725
@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
4726
@xref{Cross-profiling}.
4727
 
4728
@cindex @command{gcov}
4729
@item --coverage
4730
@opindex coverage
4731
 
4732
This option is used to compile and link code instrumented for coverage
4733
analysis.  The option is a synonym for @option{-fprofile-arcs}
4734
@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
4735
linking).  See the documentation for those options for more details.
4736
 
4737
@itemize
4738
 
4739
@item
4740
Compile the source files with @option{-fprofile-arcs} plus optimization
4741
and code generation options.  For test coverage analysis, use the
4742
additional @option{-ftest-coverage} option.  You do not need to profile
4743
every source file in a program.
4744
 
4745
@item
4746
Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
4747
(the latter implies the former).
4748
 
4749
@item
4750
Run the program on a representative workload to generate the arc profile
4751
information.  This may be repeated any number of times.  You can run
4752
concurrent instances of your program, and provided that the file system
4753
supports locking, the data files will be correctly updated.  Also
4754
@code{fork} calls are detected and correctly handled (double counting
4755
will not happen).
4756
 
4757
@item
4758
For profile-directed optimizations, compile the source files again with
4759
the same optimization and code generation options plus
4760
@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
4761
Control Optimization}).
4762
 
4763
@item
4764
For test coverage analysis, use @command{gcov} to produce human readable
4765
information from the @file{.gcno} and @file{.gcda} files.  Refer to the
4766
@command{gcov} documentation for further information.
4767
 
4768
@end itemize
4769
 
4770
With @option{-fprofile-arcs}, for each function of your program GCC
4771
creates a program flow graph, then finds a spanning tree for the graph.
4772
Only arcs that are not on the spanning tree have to be instrumented: the
4773
compiler adds code to count the number of times that these arcs are
4774
executed.  When an arc is the only exit or only entrance to a block, the
4775
instrumentation code can be added to the block; otherwise, a new basic
4776
block must be created to hold the instrumentation code.
4777
 
4778
@need 2000
4779
@item -ftest-coverage
4780
@opindex ftest-coverage
4781
Produce a notes file that the @command{gcov} code-coverage utility
4782
(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
4783
show program coverage.  Each source file's note file is called
4784
@file{@var{auxname}.gcno}.  Refer to the @option{-fprofile-arcs} option
4785
above for a description of @var{auxname} and instructions on how to
4786
generate test coverage data.  Coverage data will match the source files
4787
more closely, if you do not optimize.
4788
 
4789
@item -fdbg-cnt-list
4790
@opindex fdbg-cnt-list
4791
Print the name and the counter upperbound for all debug counters.
4792
 
4793
@item -fdbg-cnt=@var{counter-value-list}
4794
@opindex fdbg-cnt
4795
Set the internal debug counter upperbound. @var{counter-value-list}
4796
is a comma-separated list of @var{name}:@var{value} pairs
4797
which sets the upperbound of each debug counter @var{name} to @var{value}.
4798
All debug counters have the initial upperbound of @var{UINT_MAX},
4799
thus dbg_cnt() returns true always unless the upperbound is set by this option.
4800
e.g. With -fdbg-cnt=dce:10,tail_call:0
4801
dbg_cnt(dce) will return true only for first 10 invocations
4802
and dbg_cnt(tail_call) will return false always.
4803
 
4804
@item -d@var{letters}
4805
@itemx -fdump-rtl-@var{pass}
4806
@opindex d
4807
Says to make debugging dumps during compilation at times specified by
4808
@var{letters}.  This is used for debugging the RTL-based passes of the
4809
compiler.  The file names for most of the dumps are made by appending
4810
a pass number and a word to the @var{dumpname}, and the files are
4811
created in the directory of the output file.  @var{dumpname} is
4812
generated from the name of the output file, if explicitly specified
4813
and it is not an executable, otherwise it is the basename of the
4814
source file. These switches may have different effects when
4815
@option{-E} is used for preprocessing.
4816
 
4817
Debug dumps can be enabled with a @option{-fdump-rtl} switch or some
4818
@option{-d} option @var{letters}.  Here are the possible
4819
letters for use in @var{pass} and @var{letters}, and their meanings:
4820
 
4821
@table @gcctabopt
4822
 
4823
@item -fdump-rtl-alignments
4824
@opindex fdump-rtl-alignments
4825
Dump after branch alignments have been computed.
4826
 
4827
@item -fdump-rtl-asmcons
4828
@opindex fdump-rtl-asmcons
4829
Dump after fixing rtl statements that have unsatisfied in/out constraints.
4830
 
4831
@item -fdump-rtl-auto_inc_dec
4832
@opindex fdump-rtl-auto_inc_dec
4833
Dump after auto-inc-dec discovery.  This pass is only run on
4834
architectures that have auto inc or auto dec instructions.
4835
 
4836
@item -fdump-rtl-barriers
4837
@opindex fdump-rtl-barriers
4838
Dump after cleaning up the barrier instructions.
4839
 
4840
@item -fdump-rtl-bbpart
4841
@opindex fdump-rtl-bbpart
4842
Dump after partitioning hot and cold basic blocks.
4843
 
4844
@item -fdump-rtl-bbro
4845
@opindex fdump-rtl-bbro
4846
Dump after block reordering.
4847
 
4848
@item -fdump-rtl-btl1
4849
@itemx -fdump-rtl-btl2
4850
@opindex fdump-rtl-btl2
4851
@opindex fdump-rtl-btl2
4852
@option{-fdump-rtl-btl1} and @option{-fdump-rtl-btl2} enable dumping
4853
after the two branch
4854
target load optimization passes.
4855
 
4856
@item -fdump-rtl-bypass
4857
@opindex fdump-rtl-bypass
4858
Dump after jump bypassing and control flow optimizations.
4859
 
4860
@item -fdump-rtl-combine
4861
@opindex fdump-rtl-combine
4862
Dump after the RTL instruction combination pass.
4863
 
4864
@item -fdump-rtl-compgotos
4865
@opindex fdump-rtl-compgotos
4866
Dump after duplicating the computed gotos.
4867
 
4868
@item -fdump-rtl-ce1
4869
@itemx -fdump-rtl-ce2
4870
@itemx -fdump-rtl-ce3
4871
@opindex fdump-rtl-ce1
4872
@opindex fdump-rtl-ce2
4873
@opindex fdump-rtl-ce3
4874
@option{-fdump-rtl-ce1}, @option{-fdump-rtl-ce2}, and
4875
@option{-fdump-rtl-ce3} enable dumping after the three
4876
if conversion passes.
4877
 
4878
@itemx -fdump-rtl-cprop_hardreg
4879
@opindex fdump-rtl-cprop_hardreg
4880
Dump after hard register copy propagation.
4881
 
4882
@itemx -fdump-rtl-csa
4883
@opindex fdump-rtl-csa
4884
Dump after combining stack adjustments.
4885
 
4886
@item -fdump-rtl-cse1
4887
@itemx -fdump-rtl-cse2
4888
@opindex fdump-rtl-cse1
4889
@opindex fdump-rtl-cse2
4890
@option{-fdump-rtl-cse1} and @option{-fdump-rtl-cse2} enable dumping after
4891
the two common sub-expression elimination passes.
4892
 
4893
@itemx -fdump-rtl-dce
4894
@opindex fdump-rtl-dce
4895
Dump after the standalone dead code elimination passes.
4896
 
4897
@itemx -fdump-rtl-dbr
4898
@opindex fdump-rtl-dbr
4899
Dump after delayed branch scheduling.
4900
 
4901
@item -fdump-rtl-dce1
4902
@itemx -fdump-rtl-dce2
4903
@opindex fdump-rtl-dce1
4904
@opindex fdump-rtl-dce2
4905
@option{-fdump-rtl-dce1} and @option{-fdump-rtl-dce2} enable dumping after
4906
the two dead store elimination passes.
4907
 
4908
@item -fdump-rtl-eh
4909
@opindex fdump-rtl-eh
4910
Dump after finalization of EH handling code.
4911
 
4912
@item -fdump-rtl-eh_ranges
4913
@opindex fdump-rtl-eh_ranges
4914
Dump after conversion of EH handling range regions.
4915
 
4916
@item -fdump-rtl-expand
4917
@opindex fdump-rtl-expand
4918
Dump after RTL generation.
4919
 
4920
@item -fdump-rtl-fwprop1
4921
@itemx -fdump-rtl-fwprop2
4922
@opindex fdump-rtl-fwprop1
4923
@opindex fdump-rtl-fwprop2
4924
@option{-fdump-rtl-fwprop1} and @option{-fdump-rtl-fwprop2} enable
4925
dumping after the two forward propagation passes.
4926
 
4927
@item -fdump-rtl-gcse1
4928
@itemx -fdump-rtl-gcse2
4929
@opindex fdump-rtl-gcse1
4930
@opindex fdump-rtl-gcse2
4931
@option{-fdump-rtl-gcse1} and @option{-fdump-rtl-gcse2} enable dumping
4932
after global common subexpression elimination.
4933
 
4934
@item -fdump-rtl-init-regs
4935
@opindex fdump-rtl-init-regs
4936
Dump after the initialization of the registers.
4937
 
4938
@item -fdump-rtl-initvals
4939
@opindex fdump-rtl-initvals
4940
Dump after the computation of the initial value sets.
4941
 
4942
@itemx -fdump-rtl-into_cfglayout
4943
@opindex fdump-rtl-into_cfglayout
4944
Dump after converting to cfglayout mode.
4945
 
4946
@item -fdump-rtl-ira
4947
@opindex fdump-rtl-ira
4948
Dump after iterated register allocation.
4949
 
4950
@item -fdump-rtl-jump
4951
@opindex fdump-rtl-jump
4952
Dump after the second jump optimization.
4953
 
4954
@item -fdump-rtl-loop2
4955
@opindex fdump-rtl-loop2
4956
@option{-fdump-rtl-loop2} enables dumping after the rtl
4957
loop optimization passes.
4958
 
4959
@item -fdump-rtl-mach
4960
@opindex fdump-rtl-mach
4961
Dump after performing the machine dependent reorganization pass, if that
4962
pass exists.
4963
 
4964
@item -fdump-rtl-mode_sw
4965
@opindex fdump-rtl-mode_sw
4966
Dump after removing redundant mode switches.
4967
 
4968
@item -fdump-rtl-rnreg
4969
@opindex fdump-rtl-rnreg
4970
Dump after register renumbering.
4971
 
4972
@itemx -fdump-rtl-outof_cfglayout
4973
@opindex fdump-rtl-outof_cfglayout
4974
Dump after converting from cfglayout mode.
4975
 
4976
@item -fdump-rtl-peephole2
4977
@opindex fdump-rtl-peephole2
4978
Dump after the peephole pass.
4979
 
4980
@item -fdump-rtl-postreload
4981
@opindex fdump-rtl-postreload
4982
Dump after post-reload optimizations.
4983
 
4984
@itemx -fdump-rtl-pro_and_epilogue
4985
@opindex fdump-rtl-pro_and_epilogue
4986
Dump after generating the function pro and epilogues.
4987
 
4988
@item -fdump-rtl-regmove
4989
@opindex fdump-rtl-regmove
4990
Dump after the register move pass.
4991
 
4992
@item -fdump-rtl-sched1
4993
@itemx -fdump-rtl-sched2
4994
@opindex fdump-rtl-sched1
4995
@opindex fdump-rtl-sched2
4996
@option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2} enable dumping
4997
after the basic block scheduling passes.
4998
 
4999
@item -fdump-rtl-see
5000
@opindex fdump-rtl-see
5001
Dump after sign extension elimination.
5002
 
5003
@item -fdump-rtl-seqabstr
5004
@opindex fdump-rtl-seqabstr
5005
Dump after common sequence discovery.
5006
 
5007
@item -fdump-rtl-shorten
5008
@opindex fdump-rtl-shorten
5009
Dump after shortening branches.
5010
 
5011
@item -fdump-rtl-sibling
5012
@opindex fdump-rtl-sibling
5013
Dump after sibling call optimizations.
5014
 
5015
@item -fdump-rtl-split1
5016
@itemx -fdump-rtl-split2
5017
@itemx -fdump-rtl-split3
5018
@itemx -fdump-rtl-split4
5019
@itemx -fdump-rtl-split5
5020
@opindex fdump-rtl-split1
5021
@opindex fdump-rtl-split2
5022
@opindex fdump-rtl-split3
5023
@opindex fdump-rtl-split4
5024
@opindex fdump-rtl-split5
5025
@option{-fdump-rtl-split1}, @option{-fdump-rtl-split2},
5026
@option{-fdump-rtl-split3}, @option{-fdump-rtl-split4} and
5027
@option{-fdump-rtl-split5} enable dumping after five rounds of
5028
instruction splitting.
5029
 
5030
@item -fdump-rtl-sms
5031
@opindex fdump-rtl-sms
5032
Dump after modulo scheduling.  This pass is only run on some
5033
architectures.
5034
 
5035
@item -fdump-rtl-stack
5036
@opindex fdump-rtl-stack
5037
Dump after conversion from GCC's "flat register file" registers to the
5038
x87's stack-like registers.  This pass is only run on x86 variants.
5039
 
5040
@item -fdump-rtl-subreg1
5041
@itemx -fdump-rtl-subreg2
5042
@opindex fdump-rtl-subreg1
5043
@opindex fdump-rtl-subreg2
5044
@option{-fdump-rtl-subreg1} and @option{-fdump-rtl-subreg2} enable dumping after
5045
the two subreg expansion passes.
5046
 
5047
@item -fdump-rtl-unshare
5048
@opindex fdump-rtl-unshare
5049
Dump after all rtl has been unshared.
5050
 
5051
@item -fdump-rtl-vartrack
5052
@opindex fdump-rtl-vartrack
5053
Dump after variable tracking.
5054
 
5055
@item -fdump-rtl-vregs
5056
@opindex fdump-rtl-vregs
5057
Dump after converting virtual registers to hard registers.
5058
 
5059
@item -fdump-rtl-web
5060
@opindex fdump-rtl-web
5061
Dump after live range splitting.
5062
 
5063
@item -fdump-rtl-regclass
5064
@itemx -fdump-rtl-subregs_of_mode_init
5065
@itemx -fdump-rtl-subregs_of_mode_finish
5066
@itemx -fdump-rtl-dfinit
5067
@itemx -fdump-rtl-dfinish
5068
@opindex fdump-rtl-regclass
5069
@opindex fdump-rtl-subregs_of_mode_init
5070
@opindex fdump-rtl-subregs_of_mode_finish
5071
@opindex fdump-rtl-dfinit
5072
@opindex fdump-rtl-dfinish
5073
These dumps are defined but always produce empty files.
5074
 
5075
@item -fdump-rtl-all
5076
@opindex fdump-rtl-all
5077
Produce all the dumps listed above.
5078
 
5079
@item -dA
5080
@opindex dA
5081
Annotate the assembler output with miscellaneous debugging information.
5082
 
5083
@item -dD
5084
@opindex dD
5085
Dump all macro definitions, at the end of preprocessing, in addition to
5086
normal output.
5087
 
5088
@item -dH
5089
@opindex dH
5090
Produce a core dump whenever an error occurs.
5091
 
5092
@item -dm
5093
@opindex dm
5094
Print statistics on memory usage, at the end of the run, to
5095
standard error.
5096
 
5097
@item -dp
5098
@opindex dp
5099
Annotate the assembler output with a comment indicating which
5100
pattern and alternative was used.  The length of each instruction is
5101
also printed.
5102
 
5103
@item -dP
5104
@opindex dP
5105
Dump the RTL in the assembler output as a comment before each instruction.
5106
Also turns on @option{-dp} annotation.
5107
 
5108
@item -dv
5109
@opindex dv
5110
For each of the other indicated dump files (@option{-fdump-rtl-@var{pass}}),
5111
dump a representation of the control flow graph suitable for viewing with VCG
5112
to @file{@var{file}.@var{pass}.vcg}.
5113
 
5114
@item -dx
5115
@opindex dx
5116
Just generate RTL for a function instead of compiling it.  Usually used
5117
with @option{-fdump-rtl-expand}.
5118
 
5119
@item -dy
5120
@opindex dy
5121
Dump debugging information during parsing, to standard error.
5122
@end table
5123
 
5124
@item -fdump-noaddr
5125
@opindex fdump-noaddr
5126
When doing debugging dumps, suppress address output.  This makes it more
5127
feasible to use diff on debugging dumps for compiler invocations with
5128
different compiler binaries and/or different
5129
text / bss / data / heap / stack / dso start locations.
5130
 
5131
@item -fdump-unnumbered
5132
@opindex fdump-unnumbered
5133
When doing debugging dumps, suppress instruction numbers and address output.
5134
This makes it more feasible to use diff on debugging dumps for compiler
5135
invocations with different options, in particular with and without
5136
@option{-g}.
5137
 
5138
@item -fdump-unnumbered-links
5139
@opindex fdump-unnumbered-links
5140
When doing debugging dumps (see @option{-d} option above), suppress
5141
instruction numbers for the links to the previous and next instructions
5142
in a sequence.
5143
 
5144
@item -fdump-translation-unit @r{(C++ only)}
5145
@itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
5146
@opindex fdump-translation-unit
5147
Dump a representation of the tree structure for the entire translation
5148
unit to a file.  The file name is made by appending @file{.tu} to the
5149
source file name, and the file is created in the same directory as the
5150
output file.  If the @samp{-@var{options}} form is used, @var{options}
5151
controls the details of the dump as described for the
5152
@option{-fdump-tree} options.
5153
 
5154
@item -fdump-class-hierarchy @r{(C++ only)}
5155
@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
5156
@opindex fdump-class-hierarchy
5157
Dump a representation of each class's hierarchy and virtual function
5158
table layout to a file.  The file name is made by appending
5159
@file{.class} to the source file name, and the file is created in the
5160
same directory as the output file.  If the @samp{-@var{options}} form
5161
is used, @var{options} controls the details of the dump as described
5162
for the @option{-fdump-tree} options.
5163
 
5164
@item -fdump-ipa-@var{switch}
5165
@opindex fdump-ipa
5166
Control the dumping at various stages of inter-procedural analysis
5167
language tree to a file.  The file name is generated by appending a
5168
switch specific suffix to the source file name, and the file is created
5169
in the same directory as the output file.  The following dumps are
5170
possible:
5171
 
5172
@table @samp
5173
@item all
5174
Enables all inter-procedural analysis dumps.
5175
 
5176
@item cgraph
5177
Dumps information about call-graph optimization, unused function removal,
5178
and inlining decisions.
5179
 
5180
@item inline
5181
Dump after function inlining.
5182
 
5183
@end table
5184
 
5185
@item -fdump-statistics-@var{option}
5186
@opindex fdump-statistics
5187
Enable and control dumping of pass statistics in a separate file.  The
5188
file name is generated by appending a suffix ending in
5189
@samp{.statistics} to the source file name, and the file is created in
5190
the same directory as the output file.  If the @samp{-@var{option}}
5191
form is used, @samp{-stats} will cause counters to be summed over the
5192
whole compilation unit while @samp{-details} will dump every event as
5193
the passes generate them.  The default with no option is to sum
5194
counters for each function compiled.
5195
 
5196
@item -fdump-tree-@var{switch}
5197
@itemx -fdump-tree-@var{switch}-@var{options}
5198
@opindex fdump-tree
5199
Control the dumping at various stages of processing the intermediate
5200
language tree to a file.  The file name is generated by appending a
5201
switch specific suffix to the source file name, and the file is
5202
created in the same directory as the output file.  If the
5203
@samp{-@var{options}} form is used, @var{options} is a list of
5204
@samp{-} separated options that control the details of the dump.  Not
5205
all options are applicable to all dumps, those which are not
5206
meaningful will be ignored.  The following options are available
5207
 
5208
@table @samp
5209
@item address
5210
Print the address of each node.  Usually this is not meaningful as it
5211
changes according to the environment and source file.  Its primary use
5212
is for tying up a dump file with a debug environment.
5213
@item asmname
5214
If @code{DECL_ASSEMBLER_NAME} has been set for a given decl, use that
5215
in the dump instead of @code{DECL_NAME}.  Its primary use is ease of
5216
use working backward from mangled names in the assembly file.
5217
@item slim
5218
Inhibit dumping of members of a scope or body of a function merely
5219
because that scope has been reached.  Only dump such items when they
5220
are directly reachable by some other path.  When dumping pretty-printed
5221
trees, this option inhibits dumping the bodies of control structures.
5222
@item raw
5223
Print a raw representation of the tree.  By default, trees are
5224
pretty-printed into a C-like representation.
5225
@item details
5226
Enable more detailed dumps (not honored by every dump option).
5227
@item stats
5228
Enable dumping various statistics about the pass (not honored by every dump
5229
option).
5230
@item blocks
5231
Enable showing basic block boundaries (disabled in raw dumps).
5232
@item vops
5233
Enable showing virtual operands for every statement.
5234
@item lineno
5235
Enable showing line numbers for statements.
5236
@item uid
5237
Enable showing the unique ID (@code{DECL_UID}) for each variable.
5238
@item verbose
5239
Enable showing the tree dump for each statement.
5240
@item eh
5241
Enable showing the EH region number holding each statement.
5242
@item all
5243
Turn on all options, except @option{raw}, @option{slim}, @option{verbose}
5244
and @option{lineno}.
5245
@end table
5246
 
5247
The following tree dumps are possible:
5248
@table @samp
5249
 
5250
@item original
5251
@opindex fdump-tree-original
5252
Dump before any tree based optimization, to @file{@var{file}.original}.
5253
 
5254
@item optimized
5255
@opindex fdump-tree-optimized
5256
Dump after all tree based optimization, to @file{@var{file}.optimized}.
5257
 
5258
@item gimple
5259
@opindex fdump-tree-gimple
5260
Dump each function before and after the gimplification pass to a file.  The
5261
file name is made by appending @file{.gimple} to the source file name.
5262
 
5263
@item cfg
5264
@opindex fdump-tree-cfg
5265
Dump the control flow graph of each function to a file.  The file name is
5266
made by appending @file{.cfg} to the source file name.
5267
 
5268
@item vcg
5269
@opindex fdump-tree-vcg
5270
Dump the control flow graph of each function to a file in VCG format.  The
5271
file name is made by appending @file{.vcg} to the source file name.  Note
5272
that if the file contains more than one function, the generated file cannot
5273
be used directly by VCG@.  You will need to cut and paste each function's
5274
graph into its own separate file first.
5275
 
5276
@item ch
5277
@opindex fdump-tree-ch
5278
Dump each function after copying loop headers.  The file name is made by
5279
appending @file{.ch} to the source file name.
5280
 
5281
@item ssa
5282
@opindex fdump-tree-ssa
5283
Dump SSA related information to a file.  The file name is made by appending
5284
@file{.ssa} to the source file name.
5285
 
5286
@item alias
5287
@opindex fdump-tree-alias
5288
Dump aliasing information for each function.  The file name is made by
5289
appending @file{.alias} to the source file name.
5290
 
5291
@item ccp
5292
@opindex fdump-tree-ccp
5293
Dump each function after CCP@.  The file name is made by appending
5294
@file{.ccp} to the source file name.
5295
 
5296
@item storeccp
5297
@opindex fdump-tree-storeccp
5298
Dump each function after STORE-CCP@.  The file name is made by appending
5299
@file{.storeccp} to the source file name.
5300
 
5301
@item pre
5302
@opindex fdump-tree-pre
5303
Dump trees after partial redundancy elimination.  The file name is made
5304
by appending @file{.pre} to the source file name.
5305
 
5306
@item fre
5307
@opindex fdump-tree-fre
5308
Dump trees after full redundancy elimination.  The file name is made
5309
by appending @file{.fre} to the source file name.
5310
 
5311
@item copyprop
5312
@opindex fdump-tree-copyprop
5313
Dump trees after copy propagation.  The file name is made
5314
by appending @file{.copyprop} to the source file name.
5315
 
5316
@item store_copyprop
5317
@opindex fdump-tree-store_copyprop
5318
Dump trees after store copy-propagation.  The file name is made
5319
by appending @file{.store_copyprop} to the source file name.
5320
 
5321
@item dce
5322
@opindex fdump-tree-dce
5323
Dump each function after dead code elimination.  The file name is made by
5324
appending @file{.dce} to the source file name.
5325
 
5326
@item mudflap
5327
@opindex fdump-tree-mudflap
5328
Dump each function after adding mudflap instrumentation.  The file name is
5329
made by appending @file{.mudflap} to the source file name.
5330
 
5331
@item sra
5332
@opindex fdump-tree-sra
5333
Dump each function after performing scalar replacement of aggregates.  The
5334
file name is made by appending @file{.sra} to the source file name.
5335
 
5336
@item sink
5337
@opindex fdump-tree-sink
5338
Dump each function after performing code sinking.  The file name is made
5339
by appending @file{.sink} to the source file name.
5340
 
5341
@item dom
5342
@opindex fdump-tree-dom
5343
Dump each function after applying dominator tree optimizations.  The file
5344
name is made by appending @file{.dom} to the source file name.
5345
 
5346
@item dse
5347
@opindex fdump-tree-dse
5348
Dump each function after applying dead store elimination.  The file
5349
name is made by appending @file{.dse} to the source file name.
5350
 
5351
@item phiopt
5352
@opindex fdump-tree-phiopt
5353
Dump each function after optimizing PHI nodes into straightline code.  The file
5354
name is made by appending @file{.phiopt} to the source file name.
5355
 
5356
@item forwprop
5357
@opindex fdump-tree-forwprop
5358
Dump each function after forward propagating single use variables.  The file
5359
name is made by appending @file{.forwprop} to the source file name.
5360
 
5361
@item copyrename
5362
@opindex fdump-tree-copyrename
5363
Dump each function after applying the copy rename optimization.  The file
5364
name is made by appending @file{.copyrename} to the source file name.
5365
 
5366
@item nrv
5367
@opindex fdump-tree-nrv
5368
Dump each function after applying the named return value optimization on
5369
generic trees.  The file name is made by appending @file{.nrv} to the source
5370
file name.
5371
 
5372
@item vect
5373
@opindex fdump-tree-vect
5374
Dump each function after applying vectorization of loops.  The file name is
5375
made by appending @file{.vect} to the source file name.
5376
 
5377
@item slp
5378
@opindex fdump-tree-slp
5379
Dump each function after applying vectorization of basic blocks.  The file name
5380
is made by appending @file{.slp} to the source file name.
5381
 
5382
@item vrp
5383
@opindex fdump-tree-vrp
5384
Dump each function after Value Range Propagation (VRP).  The file name
5385
is made by appending @file{.vrp} to the source file name.
5386
 
5387
@item all
5388
@opindex fdump-tree-all
5389
Enable all the available tree dumps with the flags provided in this option.
5390
@end table
5391
 
5392
@item -ftree-vectorizer-verbose=@var{n}
5393
@opindex ftree-vectorizer-verbose
5394
This option controls the amount of debugging output the vectorizer prints.
5395
This information is written to standard error, unless
5396
@option{-fdump-tree-all} or @option{-fdump-tree-vect} is specified,
5397
in which case it is output to the usual dump listing file, @file{.vect}.
5398
For @var{n}=0 no diagnostic information is reported.
5399
If @var{n}=1 the vectorizer reports each loop that got vectorized,
5400
and the total number of loops that got vectorized.
5401
If @var{n}=2 the vectorizer also reports non-vectorized loops that passed
5402
the first analysis phase (vect_analyze_loop_form) - i.e.@: countable,
5403
inner-most, single-bb, single-entry/exit loops.  This is the same verbosity
5404
level that @option{-fdump-tree-vect-stats} uses.
5405
Higher verbosity levels mean either more information dumped for each
5406
reported loop, or same amount of information reported for more loops:
5407
if @var{n}=3, vectorizer cost model information is reported.
5408
If @var{n}=4, alignment related information is added to the reports.
5409
If @var{n}=5, data-references related information (e.g.@: memory dependences,
5410
memory access-patterns) is added to the reports.
5411
If @var{n}=6, the vectorizer reports also non-vectorized inner-most loops
5412
that did not pass the first analysis phase (i.e., may not be countable, or
5413
may have complicated control-flow).
5414
If @var{n}=7, the vectorizer reports also non-vectorized nested loops.
5415
If @var{n}=8, SLP related information is added to the reports.
5416
For @var{n}=9, all the information the vectorizer generates during its
5417
analysis and transformation is reported.  This is the same verbosity level
5418
that @option{-fdump-tree-vect-details} uses.
5419
 
5420
@item -frandom-seed=@var{string}
5421
@opindex frandom-seed
5422
This option provides a seed that GCC uses when it would otherwise use
5423
random numbers.  It is used to generate certain symbol names
5424
that have to be different in every compiled file.  It is also used to
5425
place unique stamps in coverage data files and the object files that
5426
produce them.  You can use the @option{-frandom-seed} option to produce
5427
reproducibly identical object files.
5428
 
5429
The @var{string} should be different for every file you compile.
5430
 
5431
@item -fsched-verbose=@var{n}
5432
@opindex fsched-verbose
5433
On targets that use instruction scheduling, this option controls the
5434
amount of debugging output the scheduler prints.  This information is
5435
written to standard error, unless @option{-fdump-rtl-sched1} or
5436
@option{-fdump-rtl-sched2} is specified, in which case it is output
5437
to the usual dump listing file, @file{.sched1} or @file{.sched2}
5438
respectively.  However for @var{n} greater than nine, the output is
5439
always printed to standard error.
5440
 
5441
For @var{n} greater than zero, @option{-fsched-verbose} outputs the
5442
same information as @option{-fdump-rtl-sched1} and @option{-fdump-rtl-sched2}.
5443
For @var{n} greater than one, it also output basic block probabilities,
5444
detailed ready list information and unit/insn info.  For @var{n} greater
5445
than two, it includes RTL at abort point, control-flow and regions info.
5446
And for @var{n} over four, @option{-fsched-verbose} also includes
5447
dependence info.
5448
 
5449
@item -save-temps
5450
@itemx -save-temps=cwd
5451
@opindex save-temps
5452
Store the usual ``temporary'' intermediate files permanently; place them
5453
in the current directory and name them based on the source file.  Thus,
5454
compiling @file{foo.c} with @samp{-c -save-temps} would produce files
5455
@file{foo.i} and @file{foo.s}, as well as @file{foo.o}.  This creates a
5456
preprocessed @file{foo.i} output file even though the compiler now
5457
normally uses an integrated preprocessor.
5458
 
5459
When used in combination with the @option{-x} command line option,
5460
@option{-save-temps} is sensible enough to avoid over writing an
5461
input source file with the same extension as an intermediate file.
5462
The corresponding intermediate file may be obtained by renaming the
5463
source file before using @option{-save-temps}.
5464
 
5465
If you invoke GCC in parallel, compiling several different source
5466
files that share a common base name in different subdirectories or the
5467
same source file compiled for multiple output destinations, it is
5468
likely that the different parallel compilers will interfere with each
5469
other, and overwrite the temporary files.  For instance:
5470
 
5471
@smallexample
5472
gcc -save-temps -o outdir1/foo.o indir1/foo.c&
5473
gcc -save-temps -o outdir2/foo.o indir2/foo.c&
5474
@end smallexample
5475
 
5476
may result in @file{foo.i} and @file{foo.o} being written to
5477
simultaneously by both compilers.
5478
 
5479
@item -save-temps=obj
5480
@opindex save-temps=obj
5481
Store the usual ``temporary'' intermediate files permanently.  If the
5482
@option{-o} option is used, the temporary files are based on the
5483
object file.  If the @option{-o} option is not used, the
5484
@option{-save-temps=obj} switch behaves like @option{-save-temps}.
5485
 
5486
For example:
5487
 
5488
@smallexample
5489
gcc -save-temps=obj -c foo.c
5490
gcc -save-temps=obj -c bar.c -o dir/xbar.o
5491
gcc -save-temps=obj foobar.c -o dir2/yfoobar
5492
@end smallexample
5493
 
5494
would create @file{foo.i}, @file{foo.s}, @file{dir/xbar.i},
5495
@file{dir/xbar.s}, @file{dir2/yfoobar.i}, @file{dir2/yfoobar.s}, and
5496
@file{dir2/yfoobar.o}.
5497
 
5498
@item -time@r{[}=@var{file}@r{]}
5499
@opindex time
5500
Report the CPU time taken by each subprocess in the compilation
5501
sequence.  For C source files, this is the compiler proper and assembler
5502
(plus the linker if linking is done).
5503
 
5504
Without the specification of an output file, the output looks like this:
5505
 
5506
@smallexample
5507
# cc1 0.12 0.01
5508
# as 0.00 0.01
5509
@end smallexample
5510
 
5511
The first number on each line is the ``user time'', that is time spent
5512
executing the program itself.  The second number is ``system time'',
5513
time spent executing operating system routines on behalf of the program.
5514
Both numbers are in seconds.
5515
 
5516
With the specification of an output file, the output is appended to the
5517
named file, and it looks like this:
5518
 
5519
@smallexample
5520
0.12 0.01 cc1 @var{options}
5521
0.00 0.01 as @var{options}
5522
@end smallexample
5523
 
5524
The ``user time'' and the ``system time'' are moved before the program
5525
name, and the options passed to the program are displayed, so that one
5526
can later tell what file was being compiled, and with which options.
5527
 
5528
@item -fvar-tracking
5529
@opindex fvar-tracking
5530
Run variable tracking pass.  It computes where variables are stored at each
5531
position in code.  Better debugging information is then generated
5532
(if the debugging information format supports this information).
5533
 
5534
It is enabled by default when compiling with optimization (@option{-Os},
5535
@option{-O}, @option{-O2}, @dots{}), debugging information (@option{-g}) and
5536
the debug info format supports it.
5537
 
5538
@item -fvar-tracking-assignments
5539
@opindex fvar-tracking-assignments
5540
@opindex fno-var-tracking-assignments
5541
Annotate assignments to user variables early in the compilation and
5542
attempt to carry the annotations over throughout the compilation all the
5543
way to the end, in an attempt to improve debug information while
5544
optimizing.  Use of @option{-gdwarf-4} is recommended along with it.
5545
 
5546
It can be enabled even if var-tracking is disabled, in which case
5547
annotations will be created and maintained, but discarded at the end.
5548
 
5549
@item -fvar-tracking-assignments-toggle
5550
@opindex fvar-tracking-assignments-toggle
5551
@opindex fno-var-tracking-assignments-toggle
5552
Toggle @option{-fvar-tracking-assignments}, in the same way that
5553
@option{-gtoggle} toggles @option{-g}.
5554
 
5555
@item -print-file-name=@var{library}
5556
@opindex print-file-name
5557
Print the full absolute name of the library file @var{library} that
5558
would be used when linking---and don't do anything else.  With this
5559
option, GCC does not compile or link anything; it just prints the
5560
file name.
5561
 
5562
@item -print-multi-directory
5563
@opindex print-multi-directory
5564
Print the directory name corresponding to the multilib selected by any
5565
other switches present in the command line.  This directory is supposed
5566
to exist in @env{GCC_EXEC_PREFIX}.
5567
 
5568
@item -print-multi-lib
5569
@opindex print-multi-lib
5570
Print the mapping from multilib directory names to compiler switches
5571
that enable them.  The directory name is separated from the switches by
5572
@samp{;}, and each switch starts with an @samp{@@} instead of the
5573
@samp{-}, without spaces between multiple switches.  This is supposed to
5574
ease shell-processing.
5575
 
5576
@item -print-multi-os-directory
5577
@opindex print-multi-os-directory
5578
Print the path to OS libraries for the selected
5579
multilib, relative to some @file{lib} subdirectory.  If OS libraries are
5580
present in the @file{lib} subdirectory and no multilibs are used, this is
5581
usually just @file{.}, if OS libraries are present in @file{lib@var{suffix}}
5582
sibling directories this prints e.g.@: @file{../lib64}, @file{../lib} or
5583
@file{../lib32}, or if OS libraries are present in @file{lib/@var{subdir}}
5584
subdirectories it prints e.g.@: @file{amd64}, @file{sparcv9} or @file{ev6}.
5585
 
5586
@item -print-prog-name=@var{program}
5587
@opindex print-prog-name
5588
Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
5589
 
5590
@item -print-libgcc-file-name
5591
@opindex print-libgcc-file-name
5592
Same as @option{-print-file-name=libgcc.a}.
5593
 
5594
This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
5595
but you do want to link with @file{libgcc.a}.  You can do
5596
 
5597
@smallexample
5598
gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
5599
@end smallexample
5600
 
5601
@item -print-search-dirs
5602
@opindex print-search-dirs
5603
Print the name of the configured installation directory and a list of
5604
program and library directories @command{gcc} will search---and don't do anything else.
5605
 
5606
This is useful when @command{gcc} prints the error message
5607
@samp{installation problem, cannot exec cpp0: No such file or directory}.
5608
To resolve this you either need to put @file{cpp0} and the other compiler
5609
components where @command{gcc} expects to find them, or you can set the environment
5610
variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
5611
Don't forget the trailing @samp{/}.
5612
@xref{Environment Variables}.
5613
 
5614
@item -print-sysroot
5615
@opindex print-sysroot
5616
Print the target sysroot directory that will be used during
5617
compilation.  This is the target sysroot specified either at configure
5618
time or using the @option{--sysroot} option, possibly with an extra
5619
suffix that depends on compilation options.  If no target sysroot is
5620
specified, the option prints nothing.
5621
 
5622
@item -print-sysroot-headers-suffix
5623
@opindex print-sysroot-headers-suffix
5624
Print the suffix added to the target sysroot when searching for
5625
headers, or give an error if the compiler is not configured with such
5626
a suffix---and don't do anything else.
5627
 
5628
@item -dumpmachine
5629
@opindex dumpmachine
5630
Print the compiler's target machine (for example,
5631
@samp{i686-pc-linux-gnu})---and don't do anything else.
5632
 
5633
@item -dumpversion
5634
@opindex dumpversion
5635
Print the compiler version (for example, @samp{3.0})---and don't do
5636
anything else.
5637
 
5638
@item -dumpspecs
5639
@opindex dumpspecs
5640
Print the compiler's built-in specs---and don't do anything else.  (This
5641
is used when GCC itself is being built.)  @xref{Spec Files}.
5642
 
5643
@item -feliminate-unused-debug-types
5644
@opindex feliminate-unused-debug-types
5645
Normally, when producing DWARF2 output, GCC will emit debugging
5646
information for all types declared in a compilation
5647
unit, regardless of whether or not they are actually used
5648
in that compilation unit.  Sometimes this is useful, such as
5649
if, in the debugger, you want to cast a value to a type that is
5650
not actually used in your program (but is declared).  More often,
5651
however, this results in a significant amount of wasted space.
5652
With this option, GCC will avoid producing debug symbol output
5653
for types that are nowhere used in the source file being compiled.
5654
@end table
5655
 
5656
@node Optimize Options
5657
@section Options That Control Optimization
5658
@cindex optimize options
5659
@cindex options, optimization
5660
 
5661
These options control various sorts of optimizations.
5662
 
5663
Without any optimization option, the compiler's goal is to reduce the
5664
cost of compilation and to make debugging produce the expected
5665
results.  Statements are independent: if you stop the program with a
5666
breakpoint between statements, you can then assign a new value to any
5667
variable or change the program counter to any other statement in the
5668
function and get exactly the results you would expect from the source
5669
code.
5670
 
5671
Turning on optimization flags makes the compiler attempt to improve
5672
the performance and/or code size at the expense of compilation time
5673
and possibly the ability to debug the program.
5674
 
5675
The compiler performs optimization based on the knowledge it has of the
5676
program.  Compiling multiple files at once to a single output file mode allows
5677
the compiler to use information gained from all of the files when compiling
5678
each of them.
5679
 
5680
Not all optimizations are controlled directly by a flag.  Only
5681
optimizations that have a flag are listed in this section.
5682
 
5683
Most optimizations are only enabled if an @option{-O} level is set on
5684
the command line.  Otherwise they are disabled, even if individual
5685
optimization flags are specified.
5686
 
5687
Depending on the target and how GCC was configured, a slightly different
5688
set of optimizations may be enabled at each @option{-O} level than
5689
those listed here.  You can invoke GCC with @samp{-Q --help=optimizers}
5690
to find out the exact set of optimizations that are enabled at each level.
5691
@xref{Overall Options}, for examples.
5692
 
5693
@table @gcctabopt
5694
@item -O
5695
@itemx -O1
5696
@opindex O
5697
@opindex O1
5698
Optimize.  Optimizing compilation takes somewhat more time, and a lot
5699
more memory for a large function.
5700
 
5701
With @option{-O}, the compiler tries to reduce code size and execution
5702
time, without performing any optimizations that take a great deal of
5703
compilation time.
5704
 
5705
@option{-O} turns on the following optimization flags:
5706
@gccoptlist{
5707
-fauto-inc-dec @gol
5708
-fcprop-registers @gol
5709
-fdce @gol
5710
-fdefer-pop @gol
5711
-fdelayed-branch @gol
5712
-fdse @gol
5713
-fguess-branch-probability @gol
5714
-fif-conversion2 @gol
5715
-fif-conversion @gol
5716
-fipa-pure-const @gol
5717
-fipa-reference @gol
5718
-fmerge-constants
5719
-fsplit-wide-types @gol
5720
-ftree-builtin-call-dce @gol
5721
-ftree-ccp @gol
5722
-ftree-ch @gol
5723
-ftree-copyrename @gol
5724
-ftree-dce @gol
5725
-ftree-dominator-opts @gol
5726
-ftree-dse @gol
5727
-ftree-forwprop @gol
5728
-ftree-fre @gol
5729
-ftree-phiprop @gol
5730
-ftree-sra @gol
5731
-ftree-pta @gol
5732
-ftree-ter @gol
5733
-funit-at-a-time}
5734
 
5735
@option{-O} also turns on @option{-fomit-frame-pointer} on machines
5736
where doing so does not interfere with debugging.
5737
 
5738
@item -O2
5739
@opindex O2
5740
Optimize even more.  GCC performs nearly all supported optimizations
5741
that do not involve a space-speed tradeoff.
5742
As compared to @option{-O}, this option increases both compilation time
5743
and the performance of the generated code.
5744
 
5745
@option{-O2} turns on all optimization flags specified by @option{-O}.  It
5746
also turns on the following optimization flags:
5747
@gccoptlist{-fthread-jumps @gol
5748
-falign-functions  -falign-jumps @gol
5749
-falign-loops  -falign-labels @gol
5750
-fcaller-saves @gol
5751
-fcrossjumping @gol
5752
-fcse-follow-jumps  -fcse-skip-blocks @gol
5753
-fdelete-null-pointer-checks @gol
5754
-fexpensive-optimizations @gol
5755
-fgcse  -fgcse-lm  @gol
5756
-finline-small-functions @gol
5757
-findirect-inlining @gol
5758
-fipa-sra @gol
5759
-foptimize-sibling-calls @gol
5760
-fpeephole2 @gol
5761
-fregmove @gol
5762
-freorder-blocks  -freorder-functions @gol
5763
-frerun-cse-after-loop  @gol
5764
-fsched-interblock  -fsched-spec @gol
5765
-fschedule-insns  -fschedule-insns2 @gol
5766
-fstrict-aliasing -fstrict-overflow @gol
5767
-ftree-switch-conversion @gol
5768
-ftree-pre @gol
5769
-ftree-vrp}
5770
 
5771
Please note the warning under @option{-fgcse} about
5772
invoking @option{-O2} on programs that use computed gotos.
5773
 
5774
@item -O3
5775
@opindex O3
5776
Optimize yet more.  @option{-O3} turns on all optimizations specified
5777
by @option{-O2} and also turns on the @option{-finline-functions},
5778
@option{-funswitch-loops}, @option{-fpredictive-commoning},
5779
@option{-fgcse-after-reload} and @option{-ftree-vectorize} options.
5780
 
5781
@item -O0
5782
@opindex O0
5783
Reduce compilation time and make debugging produce the expected
5784
results.  This is the default.
5785
 
5786
@item -Os
5787
@opindex Os
5788
Optimize for size.  @option{-Os} enables all @option{-O2} optimizations that
5789
do not typically increase code size.  It also performs further
5790
optimizations designed to reduce code size.
5791
 
5792
@option{-Os} disables the following optimization flags:
5793
@gccoptlist{-falign-functions  -falign-jumps  -falign-loops @gol
5794
-falign-labels  -freorder-blocks  -freorder-blocks-and-partition @gol
5795
-fprefetch-loop-arrays  -ftree-vect-loop-version}
5796
 
5797
If you use multiple @option{-O} options, with or without level numbers,
5798
the last such option is the one that is effective.
5799
@end table
5800
 
5801
Options of the form @option{-f@var{flag}} specify machine-independent
5802
flags.  Most flags have both positive and negative forms; the negative
5803
form of @option{-ffoo} would be @option{-fno-foo}.  In the table
5804
below, only one of the forms is listed---the one you typically will
5805
use.  You can figure out the other form by either removing @samp{no-}
5806
or adding it.
5807
 
5808
The following options control specific optimizations.  They are either
5809
activated by @option{-O} options or are related to ones that are.  You
5810
can use the following flags in the rare cases when ``fine-tuning'' of
5811
optimizations to be performed is desired.
5812
 
5813
@table @gcctabopt
5814
@item -fno-default-inline
5815
@opindex fno-default-inline
5816
Do not make member functions inline by default merely because they are
5817
defined inside the class scope (C++ only).  Otherwise, when you specify
5818
@w{@option{-O}}, member functions defined inside class scope are compiled
5819
inline by default; i.e., you don't need to add @samp{inline} in front of
5820
the member function name.
5821
 
5822
@item -fno-defer-pop
5823
@opindex fno-defer-pop
5824
Always pop the arguments to each function call as soon as that function
5825
returns.  For machines which must pop arguments after a function call,
5826
the compiler normally lets arguments accumulate on the stack for several
5827
function calls and pops them all at once.
5828
 
5829
Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5830
 
5831
@item -fforward-propagate
5832
@opindex fforward-propagate
5833
Perform a forward propagation pass on RTL@.  The pass tries to combine two
5834
instructions and checks if the result can be simplified.  If loop unrolling
5835
is active, two passes are performed and the second is scheduled after
5836
loop unrolling.
5837
 
5838
This option is enabled by default at optimization levels @option{-O},
5839
@option{-O2}, @option{-O3}, @option{-Os}.
5840
 
5841
@item -fomit-frame-pointer
5842
@opindex fomit-frame-pointer
5843
Don't keep the frame pointer in a register for functions that
5844
don't need one.  This avoids the instructions to save, set up and
5845
restore frame pointers; it also makes an extra register available
5846
in many functions.  @strong{It also makes debugging impossible on
5847
some machines.}
5848
 
5849
On some machines, such as the VAX, this flag has no effect, because
5850
the standard calling sequence automatically handles the frame pointer
5851
and nothing is saved by pretending it doesn't exist.  The
5852
machine-description macro @code{FRAME_POINTER_REQUIRED} controls
5853
whether a target machine supports this flag.  @xref{Registers,,Register
5854
Usage, gccint, GNU Compiler Collection (GCC) Internals}.
5855
 
5856
Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5857
 
5858
@item -foptimize-sibling-calls
5859
@opindex foptimize-sibling-calls
5860
Optimize sibling and tail recursive calls.
5861
 
5862
Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5863
 
5864
@item -fno-inline
5865
@opindex fno-inline
5866
Don't pay attention to the @code{inline} keyword.  Normally this option
5867
is used to keep the compiler from expanding any functions inline.
5868
Note that if you are not optimizing, no functions can be expanded inline.
5869
 
5870
@item -finline-small-functions
5871
@opindex finline-small-functions
5872
Integrate functions into their callers when their body is smaller than expected
5873
function call code (so overall size of program gets smaller).  The compiler
5874
heuristically decides which functions are simple enough to be worth integrating
5875
in this way.
5876
 
5877
Enabled at level @option{-O2}.
5878
 
5879
@item -findirect-inlining
5880
@opindex findirect-inlining
5881
Inline also indirect calls that are discovered to be known at compile
5882
time thanks to previous inlining.  This option has any effect only
5883
when inlining itself is turned on by the @option{-finline-functions}
5884
or @option{-finline-small-functions} options.
5885
 
5886
Enabled at level @option{-O2}.
5887
 
5888
@item -finline-functions
5889
@opindex finline-functions
5890
Integrate all simple functions into their callers.  The compiler
5891
heuristically decides which functions are simple enough to be worth
5892
integrating in this way.
5893
 
5894
If all calls to a given function are integrated, and the function is
5895
declared @code{static}, then the function is normally not output as
5896
assembler code in its own right.
5897
 
5898
Enabled at level @option{-O3}.
5899
 
5900
@item -finline-functions-called-once
5901
@opindex finline-functions-called-once
5902
Consider all @code{static} functions called once for inlining into their
5903
caller even if they are not marked @code{inline}.  If a call to a given
5904
function is integrated, then the function is not output as assembler code
5905
in its own right.
5906
 
5907
Enabled at levels @option{-O1}, @option{-O2}, @option{-O3} and @option{-Os}.
5908
 
5909
@item -fearly-inlining
5910
@opindex fearly-inlining
5911
Inline functions marked by @code{always_inline} and functions whose body seems
5912
smaller than the function call overhead early before doing
5913
@option{-fprofile-generate} instrumentation and real inlining pass.  Doing so
5914
makes profiling significantly cheaper and usually inlining faster on programs
5915
having large chains of nested wrapper functions.
5916
 
5917
Enabled by default.
5918
 
5919
@item -fipa-sra
5920
@opindex fipa-sra
5921
Perform interprocedural scalar replacement of aggregates, removal of
5922
unused parameters and replacement of parameters passed by reference
5923
by parameters passed by value.
5924
 
5925
Enabled at levels @option{-O2}, @option{-O3} and @option{-Os}.
5926
 
5927
@item -finline-limit=@var{n}
5928
@opindex finline-limit
5929
By default, GCC limits the size of functions that can be inlined.  This flag
5930
allows coarse control of this limit.  @var{n} is the size of functions that
5931
can be inlined in number of pseudo instructions.
5932
 
5933
Inlining is actually controlled by a number of parameters, which may be
5934
specified individually by using @option{--param @var{name}=@var{value}}.
5935
The @option{-finline-limit=@var{n}} option sets some of these parameters
5936
as follows:
5937
 
5938
@table @gcctabopt
5939
@item max-inline-insns-single
5940
is set to @var{n}/2.
5941
@item max-inline-insns-auto
5942
is set to @var{n}/2.
5943
@end table
5944
 
5945
See below for a documentation of the individual
5946
parameters controlling inlining and for the defaults of these parameters.
5947
 
5948
@emph{Note:} there may be no value to @option{-finline-limit} that results
5949
in default behavior.
5950
 
5951
@emph{Note:} pseudo instruction represents, in this particular context, an
5952
abstract measurement of function's size.  In no way does it represent a count
5953
of assembly instructions and as such its exact meaning might change from one
5954
release to an another.
5955
 
5956
@item -fkeep-inline-functions
5957
@opindex fkeep-inline-functions
5958
In C, emit @code{static} functions that are declared @code{inline}
5959
into the object file, even if the function has been inlined into all
5960
of its callers.  This switch does not affect functions using the
5961
@code{extern inline} extension in GNU C90@.  In C++, emit any and all
5962
inline functions into the object file.
5963
 
5964
@item -fkeep-static-consts
5965
@opindex fkeep-static-consts
5966
Emit variables declared @code{static const} when optimization isn't turned
5967
on, even if the variables aren't referenced.
5968
 
5969
GCC enables this option by default.  If you want to force the compiler to
5970
check if the variable was referenced, regardless of whether or not
5971
optimization is turned on, use the @option{-fno-keep-static-consts} option.
5972
 
5973
@item -fmerge-constants
5974
@opindex fmerge-constants
5975
Attempt to merge identical constants (string constants and floating point
5976
constants) across compilation units.
5977
 
5978
This option is the default for optimized compilation if the assembler and
5979
linker support it.  Use @option{-fno-merge-constants} to inhibit this
5980
behavior.
5981
 
5982
Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5983
 
5984
@item -fmerge-all-constants
5985
@opindex fmerge-all-constants
5986
Attempt to merge identical constants and identical variables.
5987
 
5988
This option implies @option{-fmerge-constants}.  In addition to
5989
@option{-fmerge-constants} this considers e.g.@: even constant initialized
5990
arrays or initialized constant variables with integral or floating point
5991
types.  Languages like C or C++ require each variable, including multiple
5992
instances of the same variable in recursive calls, to have distinct locations,
5993
so using this option will result in non-conforming
5994
behavior.
5995
 
5996
@item -fmodulo-sched
5997
@opindex fmodulo-sched
5998
Perform swing modulo scheduling immediately before the first scheduling
5999
pass.  This pass looks at innermost loops and reorders their
6000
instructions by overlapping different iterations.
6001
 
6002
@item -fmodulo-sched-allow-regmoves
6003
@opindex fmodulo-sched-allow-regmoves
6004
Perform more aggressive SMS based modulo scheduling with register moves
6005
allowed.  By setting this flag certain anti-dependences edges will be
6006
deleted which will trigger the generation of reg-moves based on the
6007
life-range analysis.  This option is effective only with
6008
@option{-fmodulo-sched} enabled.
6009
 
6010
@item -fno-branch-count-reg
6011
@opindex fno-branch-count-reg
6012
Do not use ``decrement and branch'' instructions on a count register,
6013
but instead generate a sequence of instructions that decrement a
6014
register, compare it against zero, then branch based upon the result.
6015
This option is only meaningful on architectures that support such
6016
instructions, which include x86, PowerPC, IA-64 and S/390.
6017
 
6018
The default is @option{-fbranch-count-reg}.
6019
 
6020
@item -fno-function-cse
6021
@opindex fno-function-cse
6022
Do not put function addresses in registers; make each instruction that
6023
calls a constant function contain the function's address explicitly.
6024
 
6025
This option results in less efficient code, but some strange hacks
6026
that alter the assembler output may be confused by the optimizations
6027
performed when this option is not used.
6028
 
6029
The default is @option{-ffunction-cse}
6030
 
6031
@item -fno-zero-initialized-in-bss
6032
@opindex fno-zero-initialized-in-bss
6033
If the target supports a BSS section, GCC by default puts variables that
6034
are initialized to zero into BSS@.  This can save space in the resulting
6035
code.
6036
 
6037
This option turns off this behavior because some programs explicitly
6038
rely on variables going to the data section.  E.g., so that the
6039
resulting executable can find the beginning of that section and/or make
6040
assumptions based on that.
6041
 
6042
The default is @option{-fzero-initialized-in-bss}.
6043
 
6044
@item -fmudflap -fmudflapth -fmudflapir
6045
@opindex fmudflap
6046
@opindex fmudflapth
6047
@opindex fmudflapir
6048
@cindex bounds checking
6049
@cindex mudflap
6050
For front-ends that support it (C and C++), instrument all risky
6051
pointer/array dereferencing operations, some standard library
6052
string/heap functions, and some other associated constructs with
6053
range/validity tests.  Modules so instrumented should be immune to
6054
buffer overflows, invalid heap use, and some other classes of C/C++
6055
programming errors.  The instrumentation relies on a separate runtime
6056
library (@file{libmudflap}), which will be linked into a program if
6057
@option{-fmudflap} is given at link time.  Run-time behavior of the
6058
instrumented program is controlled by the @env{MUDFLAP_OPTIONS}
6059
environment variable.  See @code{env MUDFLAP_OPTIONS=-help a.out}
6060
for its options.
6061
 
6062
Use @option{-fmudflapth} instead of @option{-fmudflap} to compile and to
6063
link if your program is multi-threaded.  Use @option{-fmudflapir}, in
6064
addition to @option{-fmudflap} or @option{-fmudflapth}, if
6065
instrumentation should ignore pointer reads.  This produces less
6066
instrumentation (and therefore faster execution) and still provides
6067
some protection against outright memory corrupting writes, but allows
6068
erroneously read data to propagate within a program.
6069
 
6070
@item -fthread-jumps
6071
@opindex fthread-jumps
6072
Perform optimizations where we check to see if a jump branches to a
6073
location where another comparison subsumed by the first is found.  If
6074
so, the first branch is redirected to either the destination of the
6075
second branch or a point immediately following it, depending on whether
6076
the condition is known to be true or false.
6077
 
6078
Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6079
 
6080
@item -fsplit-wide-types
6081
@opindex fsplit-wide-types
6082
When using a type that occupies multiple registers, such as @code{long
6083
long} on a 32-bit system, split the registers apart and allocate them
6084
independently.  This normally generates better code for those types,
6085
but may make debugging more difficult.
6086
 
6087
Enabled at levels @option{-O}, @option{-O2}, @option{-O3},
6088
@option{-Os}.
6089
 
6090
@item -fcse-follow-jumps
6091
@opindex fcse-follow-jumps
6092
In common subexpression elimination (CSE), scan through jump instructions
6093
when the target of the jump is not reached by any other path.  For
6094
example, when CSE encounters an @code{if} statement with an
6095
@code{else} clause, CSE will follow the jump when the condition
6096
tested is false.
6097
 
6098
Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6099
 
6100
@item -fcse-skip-blocks
6101
@opindex fcse-skip-blocks
6102
This is similar to @option{-fcse-follow-jumps}, but causes CSE to
6103
follow jumps which conditionally skip over blocks.  When CSE
6104
encounters a simple @code{if} statement with no else clause,
6105
@option{-fcse-skip-blocks} causes CSE to follow the jump around the
6106
body of the @code{if}.
6107
 
6108
Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6109
 
6110
@item -frerun-cse-after-loop
6111
@opindex frerun-cse-after-loop
6112
Re-run common subexpression elimination after loop optimizations has been
6113
performed.
6114
 
6115
Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6116
 
6117
@item -fgcse
6118
@opindex fgcse
6119
Perform a global common subexpression elimination pass.
6120
This pass also performs global constant and copy propagation.
6121
 
6122
@emph{Note:} When compiling a program using computed gotos, a GCC
6123
extension, you may get better runtime performance if you disable
6124
the global common subexpression elimination pass by adding
6125
@option{-fno-gcse} to the command line.
6126
 
6127
Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6128
 
6129
@item -fgcse-lm
6130
@opindex fgcse-lm
6131
When @option{-fgcse-lm} is enabled, global common subexpression elimination will
6132
attempt to move loads which are only killed by stores into themselves.  This
6133
allows a loop containing a load/store sequence to be changed to a load outside
6134
the loop, and a copy/store within the loop.
6135
 
6136
Enabled by default when gcse is enabled.
6137
 
6138
@item -fgcse-sm
6139
@opindex fgcse-sm
6140
When @option{-fgcse-sm} is enabled, a store motion pass is run after
6141
global common subexpression elimination.  This pass will attempt to move
6142
stores out of loops.  When used in conjunction with @option{-fgcse-lm},
6143
loops containing a load/store sequence can be changed to a load before
6144
the loop and a store after the loop.
6145
 
6146
Not enabled at any optimization level.
6147
 
6148
@item -fgcse-las
6149
@opindex fgcse-las
6150
When @option{-fgcse-las} is enabled, the global common subexpression
6151
elimination pass eliminates redundant loads that come after stores to the
6152
same memory location (both partial and full redundancies).
6153
 
6154
Not enabled at any optimization level.
6155
 
6156
@item -fgcse-after-reload
6157
@opindex fgcse-after-reload
6158
When @option{-fgcse-after-reload} is enabled, a redundant load elimination
6159
pass is performed after reload.  The purpose of this pass is to cleanup
6160
redundant spilling.
6161
 
6162
@item -funsafe-loop-optimizations
6163
@opindex funsafe-loop-optimizations
6164
If given, the loop optimizer will assume that loop indices do not
6165
overflow, and that the loops with nontrivial exit condition are not
6166
infinite.  This enables a wider range of loop optimizations even if
6167
the loop optimizer itself cannot prove that these assumptions are valid.
6168
Using @option{-Wunsafe-loop-optimizations}, the compiler will warn you
6169
if it finds this kind of loop.
6170
 
6171
@item -fcrossjumping
6172
@opindex fcrossjumping
6173
Perform cross-jumping transformation.  This transformation unifies equivalent code and save code size.  The
6174
resulting code may or may not perform better than without cross-jumping.
6175
 
6176
Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6177
 
6178
@item -fauto-inc-dec
6179
@opindex fauto-inc-dec
6180
Combine increments or decrements of addresses with memory accesses.
6181
This pass is always skipped on architectures that do not have
6182
instructions to support this.  Enabled by default at @option{-O} and
6183
higher on architectures that support this.
6184
 
6185
@item -fdce
6186
@opindex fdce
6187
Perform dead code elimination (DCE) on RTL@.
6188
Enabled by default at @option{-O} and higher.
6189
 
6190
@item -fdse
6191
@opindex fdse
6192
Perform dead store elimination (DSE) on RTL@.
6193
Enabled by default at @option{-O} and higher.
6194
 
6195
@item -fif-conversion
6196
@opindex fif-conversion
6197
Attempt to transform conditional jumps into branch-less equivalents.  This
6198
include use of conditional moves, min, max, set flags and abs instructions, and
6199
some tricks doable by standard arithmetics.  The use of conditional execution
6200
on chips where it is available is controlled by @code{if-conversion2}.
6201
 
6202
Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
6203
 
6204
@item -fif-conversion2
6205
@opindex fif-conversion2
6206
Use conditional execution (where available) to transform conditional jumps into
6207
branch-less equivalents.
6208
 
6209
Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
6210
 
6211
@item -fdelete-null-pointer-checks
6212
@opindex fdelete-null-pointer-checks
6213
Assume that programs cannot safely dereference null pointers, and that
6214
no code or data element resides there.  This enables simple constant
6215
folding optimizations at all optimization levels.  In addition, other
6216
optimization passes in GCC use this flag to control global dataflow
6217
analyses that eliminate useless checks for null pointers; these assume
6218
that if a pointer is checked after it has already been dereferenced,
6219
it cannot be null.
6220
 
6221
Note however that in some environments this assumption is not true.
6222
Use @option{-fno-delete-null-pointer-checks} to disable this optimization
6223
for programs which depend on that behavior.
6224
 
6225
Some targets, especially embedded ones, disable this option at all levels.
6226
Otherwise it is enabled at all levels: @option{-O0}, @option{-O1},
6227
@option{-O2}, @option{-O3}, @option{-Os}.  Passes that use the information
6228
are enabled independently at different optimization levels.
6229
 
6230
@item -fexpensive-optimizations
6231
@opindex fexpensive-optimizations
6232
Perform a number of minor optimizations that are relatively expensive.
6233
 
6234
Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6235
 
6236
@item -foptimize-register-move
6237
@itemx -fregmove
6238
@opindex foptimize-register-move
6239
@opindex fregmove
6240
Attempt to reassign register numbers in move instructions and as
6241
operands of other simple instructions in order to maximize the amount of
6242
register tying.  This is especially helpful on machines with two-operand
6243
instructions.
6244
 
6245
Note @option{-fregmove} and @option{-foptimize-register-move} are the same
6246
optimization.
6247
 
6248
Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6249
 
6250
@item -fira-algorithm=@var{algorithm}
6251
Use specified coloring algorithm for the integrated register
6252
allocator.  The @var{algorithm} argument should be @code{priority} or
6253
@code{CB}.  The first algorithm specifies Chow's priority coloring,
6254
the second one specifies Chaitin-Briggs coloring.  The second
6255
algorithm can be unimplemented for some architectures.  If it is
6256
implemented, it is the default because Chaitin-Briggs coloring as a
6257
rule generates a better code.
6258
 
6259
@item -fira-region=@var{region}
6260
Use specified regions for the integrated register allocator.  The
6261
@var{region} argument should be one of @code{all}, @code{mixed}, or
6262
@code{one}.  The first value means using all loops as register
6263
allocation regions, the second value which is the default means using
6264
all loops except for loops with small register pressure as the
6265
regions, and third one means using all function as a single region.
6266
The first value can give best result for machines with small size and
6267
irregular register set, the third one results in faster and generates
6268
decent code and the smallest size code, and the default value usually
6269
give the best results in most cases and for most architectures.
6270
 
6271
@item -fira-coalesce
6272
@opindex fira-coalesce
6273
Do optimistic register coalescing.  This option might be profitable for
6274
architectures with big regular register files.
6275
 
6276
@item -fira-loop-pressure
6277
@opindex fira-loop-pressure
6278
Use IRA to evaluate register pressure in loops for decision to move
6279
loop invariants.  Usage of this option usually results in generation
6280
of faster and smaller code on machines with big register files (>= 32
6281
registers) but it can slow compiler down.
6282
 
6283
This option is enabled at level @option{-O3} for some targets.
6284
 
6285
@item -fno-ira-share-save-slots
6286
@opindex fno-ira-share-save-slots
6287
Switch off sharing stack slots used for saving call used hard
6288
registers living through a call.  Each hard register will get a
6289
separate stack slot and as a result function stack frame will be
6290
bigger.
6291
 
6292
@item -fno-ira-share-spill-slots
6293
@opindex fno-ira-share-spill-slots
6294
Switch off sharing stack slots allocated for pseudo-registers.  Each
6295
pseudo-register which did not get a hard register will get a separate
6296
stack slot and as a result function stack frame will be bigger.
6297
 
6298
@item -fira-verbose=@var{n}
6299
@opindex fira-verbose
6300
Set up how verbose dump file for the integrated register allocator
6301
will be.  Default value is 5.  If the value is greater or equal to 10,
6302
the dump file will be stderr as if the value were @var{n} minus 10.
6303
 
6304
@item -fdelayed-branch
6305
@opindex fdelayed-branch
6306
If supported for the target machine, attempt to reorder instructions
6307
to exploit instruction slots available after delayed branch
6308
instructions.
6309
 
6310
Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
6311
 
6312
@item -fschedule-insns
6313
@opindex fschedule-insns
6314
If supported for the target machine, attempt to reorder instructions to
6315
eliminate execution stalls due to required data being unavailable.  This
6316
helps machines that have slow floating point or memory load instructions
6317
by allowing other instructions to be issued until the result of the load
6318
or floating point instruction is required.
6319
 
6320
Enabled at levels @option{-O2}, @option{-O3}.
6321
 
6322
@item -fschedule-insns2
6323
@opindex fschedule-insns2
6324
Similar to @option{-fschedule-insns}, but requests an additional pass of
6325
instruction scheduling after register allocation has been done.  This is
6326
especially useful on machines with a relatively small number of
6327
registers and where memory load instructions take more than one cycle.
6328
 
6329
Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6330
 
6331
@item -fno-sched-interblock
6332
@opindex fno-sched-interblock
6333
Don't schedule instructions across basic blocks.  This is normally
6334
enabled by default when scheduling before register allocation, i.e.@:
6335
with @option{-fschedule-insns} or at @option{-O2} or higher.
6336
 
6337
@item -fno-sched-spec
6338
@opindex fno-sched-spec
6339
Don't allow speculative motion of non-load instructions.  This is normally
6340
enabled by default when scheduling before register allocation, i.e.@:
6341
with @option{-fschedule-insns} or at @option{-O2} or higher.
6342
 
6343
@item -fsched-pressure
6344
@opindex fsched-pressure
6345
Enable register pressure sensitive insn scheduling before the register
6346
allocation.  This only makes sense when scheduling before register
6347
allocation is enabled, i.e.@: with @option{-fschedule-insns} or at
6348
@option{-O2} or higher.  Usage of this option can improve the
6349
generated code and decrease its size by preventing register pressure
6350
increase above the number of available hard registers and as a
6351
consequence register spills in the register allocation.
6352
 
6353
@item -fsched-spec-load
6354
@opindex fsched-spec-load
6355
Allow speculative motion of some load instructions.  This only makes
6356
sense when scheduling before register allocation, i.e.@: with
6357
@option{-fschedule-insns} or at @option{-O2} or higher.
6358
 
6359
@item -fsched-spec-load-dangerous
6360
@opindex fsched-spec-load-dangerous
6361
Allow speculative motion of more load instructions.  This only makes
6362
sense when scheduling before register allocation, i.e.@: with
6363
@option{-fschedule-insns} or at @option{-O2} or higher.
6364
 
6365
@item -fsched-stalled-insns
6366
@itemx -fsched-stalled-insns=@var{n}
6367
@opindex fsched-stalled-insns
6368
Define how many insns (if any) can be moved prematurely from the queue
6369
of stalled insns into the ready list, during the second scheduling pass.
6370
@option{-fno-sched-stalled-insns} means that no insns will be moved
6371
prematurely, @option{-fsched-stalled-insns=0} means there is no limit
6372
on how many queued insns can be moved prematurely.
6373
@option{-fsched-stalled-insns} without a value is equivalent to
6374
@option{-fsched-stalled-insns=1}.
6375
 
6376
@item -fsched-stalled-insns-dep
6377
@itemx -fsched-stalled-insns-dep=@var{n}
6378
@opindex fsched-stalled-insns-dep
6379
Define how many insn groups (cycles) will be examined for a dependency
6380
on a stalled insn that is candidate for premature removal from the queue
6381
of stalled insns.  This has an effect only during the second scheduling pass,
6382
and only if @option{-fsched-stalled-insns} is used.
6383
@option{-fno-sched-stalled-insns-dep} is equivalent to
6384
@option{-fsched-stalled-insns-dep=0}.
6385
@option{-fsched-stalled-insns-dep} without a value is equivalent to
6386
@option{-fsched-stalled-insns-dep=1}.
6387
 
6388
@item -fsched2-use-superblocks
6389
@opindex fsched2-use-superblocks
6390
When scheduling after register allocation, do use superblock scheduling
6391
algorithm.  Superblock scheduling allows motion across basic block boundaries
6392
resulting on faster schedules.  This option is experimental, as not all machine
6393
descriptions used by GCC model the CPU closely enough to avoid unreliable
6394
results from the algorithm.
6395
 
6396
This only makes sense when scheduling after register allocation, i.e.@: with
6397
@option{-fschedule-insns2} or at @option{-O2} or higher.
6398
 
6399
@item -fsched-group-heuristic
6400
@opindex fsched-group-heuristic
6401
Enable the group heuristic in the scheduler.  This heuristic favors
6402
the instruction that belongs to a schedule group.  This is enabled
6403
by default when scheduling is enabled, i.e.@: with @option{-fschedule-insns}
6404
or @option{-fschedule-insns2} or at @option{-O2} or higher.
6405
 
6406
@item -fsched-critical-path-heuristic
6407
@opindex fsched-critical-path-heuristic
6408
Enable the critical-path heuristic in the scheduler.  This heuristic favors
6409
instructions on the critical path.  This is enabled by default when
6410
scheduling is enabled, i.e.@: with @option{-fschedule-insns}
6411
or @option{-fschedule-insns2} or at @option{-O2} or higher.
6412
 
6413
@item -fsched-spec-insn-heuristic
6414
@opindex fsched-spec-insn-heuristic
6415
Enable the speculative instruction heuristic in the scheduler.  This
6416
heuristic favors speculative instructions with greater dependency weakness.
6417
This is enabled by default when scheduling is enabled, i.e.@:
6418
with @option{-fschedule-insns} or @option{-fschedule-insns2}
6419
or at @option{-O2} or higher.
6420
 
6421
@item -fsched-rank-heuristic
6422
@opindex fsched-rank-heuristic
6423
Enable the rank heuristic in the scheduler.  This heuristic favors
6424
the instruction belonging to a basic block with greater size or frequency.
6425
This is enabled by default when scheduling is enabled, i.e.@:
6426
with @option{-fschedule-insns} or @option{-fschedule-insns2} or
6427
at @option{-O2} or higher.
6428
 
6429
@item -fsched-last-insn-heuristic
6430
@opindex fsched-last-insn-heuristic
6431
Enable the last-instruction heuristic in the scheduler.  This heuristic
6432
favors the instruction that is less dependent on the last instruction
6433
scheduled.  This is enabled by default when scheduling is enabled,
6434
i.e.@: with @option{-fschedule-insns} or @option{-fschedule-insns2} or
6435
at @option{-O2} or higher.
6436
 
6437
@item -fsched-dep-count-heuristic
6438
@opindex fsched-dep-count-heuristic
6439
Enable the dependent-count heuristic in the scheduler.  This heuristic
6440
favors the instruction that has more instructions depending on it.
6441
This is enabled by default when scheduling is enabled, i.e.@:
6442
with @option{-fschedule-insns} or @option{-fschedule-insns2} or
6443
at @option{-O2} or higher.
6444
 
6445
@item -freschedule-modulo-scheduled-loops
6446
@opindex freschedule-modulo-scheduled-loops
6447
The modulo scheduling comes before the traditional scheduling, if a loop
6448
was modulo scheduled we may want to prevent the later scheduling passes
6449
from changing its schedule, we use this option to control that.
6450
 
6451
@item -fselective-scheduling
6452
@opindex fselective-scheduling
6453
Schedule instructions using selective scheduling algorithm.  Selective
6454
scheduling runs instead of the first scheduler pass.
6455
 
6456
@item -fselective-scheduling2
6457
@opindex fselective-scheduling2
6458
Schedule instructions using selective scheduling algorithm.  Selective
6459
scheduling runs instead of the second scheduler pass.
6460
 
6461
@item -fsel-sched-pipelining
6462
@opindex fsel-sched-pipelining
6463
Enable software pipelining of innermost loops during selective scheduling.
6464
This option has no effect until one of @option{-fselective-scheduling} or
6465
@option{-fselective-scheduling2} is turned on.
6466
 
6467
@item -fsel-sched-pipelining-outer-loops
6468
@opindex fsel-sched-pipelining-outer-loops
6469
When pipelining loops during selective scheduling, also pipeline outer loops.
6470
This option has no effect until @option{-fsel-sched-pipelining} is turned on.
6471
 
6472
@item -fcaller-saves
6473
@opindex fcaller-saves
6474
Enable values to be allocated in registers that will be clobbered by
6475
function calls, by emitting extra instructions to save and restore the
6476
registers around such calls.  Such allocation is done only when it
6477
seems to result in better code than would otherwise be produced.
6478
 
6479
This option is always enabled by default on certain machines, usually
6480
those which have no call-preserved registers to use instead.
6481
 
6482
Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6483
 
6484
@item -fconserve-stack
6485
@opindex fconserve-stack
6486
Attempt to minimize stack usage.  The compiler will attempt to use less
6487
stack space, even if that makes the program slower.  This option
6488
implies setting the @option{large-stack-frame} parameter to 100
6489
and the @option{large-stack-frame-growth} parameter to 400.
6490
 
6491
@item -ftree-reassoc
6492
@opindex ftree-reassoc
6493
Perform reassociation on trees.  This flag is enabled by default
6494
at @option{-O} and higher.
6495
 
6496
@item -ftree-pre
6497
@opindex ftree-pre
6498
Perform partial redundancy elimination (PRE) on trees.  This flag is
6499
enabled by default at @option{-O2} and @option{-O3}.
6500
 
6501
@item -ftree-forwprop
6502
@opindex ftree-forwprop
6503
Perform forward propagation on trees.  This flag is enabled by default
6504
at @option{-O} and higher.
6505
 
6506
@item -ftree-fre
6507
@opindex ftree-fre
6508
Perform full redundancy elimination (FRE) on trees.  The difference
6509
between FRE and PRE is that FRE only considers expressions
6510
that are computed on all paths leading to the redundant computation.
6511
This analysis is faster than PRE, though it exposes fewer redundancies.
6512
This flag is enabled by default at @option{-O} and higher.
6513
 
6514
@item -ftree-phiprop
6515
@opindex ftree-phiprop
6516
Perform hoisting of loads from conditional pointers on trees.  This
6517
pass is enabled by default at @option{-O} and higher.
6518
 
6519
@item -ftree-copy-prop
6520
@opindex ftree-copy-prop
6521
Perform copy propagation on trees.  This pass eliminates unnecessary
6522
copy operations.  This flag is enabled by default at @option{-O} and
6523
higher.
6524
 
6525
@item -fipa-pure-const
6526
@opindex fipa-pure-const
6527
Discover which functions are pure or constant.
6528
Enabled by default at @option{-O} and higher.
6529
 
6530
@item -fipa-reference
6531
@opindex fipa-reference
6532
Discover which static variables do not escape cannot escape the
6533
compilation unit.
6534
Enabled by default at @option{-O} and higher.
6535
 
6536
@item -fipa-struct-reorg
6537
@opindex fipa-struct-reorg
6538
Perform structure reorganization optimization, that change C-like structures
6539
layout in order to better utilize spatial locality.  This transformation is
6540
affective for programs containing arrays of structures.  Available in two
6541
compilation modes: profile-based (enabled with @option{-fprofile-generate})
6542
or static (which uses built-in heuristics).  Require @option{-fipa-type-escape}
6543
to provide the safety of this transformation.  It works only in whole program
6544
mode, so it requires @option{-fwhole-program} and @option{-combine} to be
6545
enabled.  Structures considered @samp{cold} by this transformation are not
6546
affected (see @option{--param struct-reorg-cold-struct-ratio=@var{value}}).
6547
 
6548
With this flag, the program debug info reflects a new structure layout.
6549
 
6550
@item -fipa-pta
6551
@opindex fipa-pta
6552
Perform interprocedural pointer analysis.  This option is experimental
6553
and does not affect generated code.
6554
 
6555
@item -fipa-cp
6556
@opindex fipa-cp
6557
Perform interprocedural constant propagation.
6558
This optimization analyzes the program to determine when values passed
6559
to functions are constants and then optimizes accordingly.
6560
This optimization can substantially increase performance
6561
if the application has constants passed to functions.
6562
This flag is enabled by default at @option{-O2}, @option{-Os} and @option{-O3}.
6563
 
6564
@item -fipa-cp-clone
6565
@opindex fipa-cp-clone
6566
Perform function cloning to make interprocedural constant propagation stronger.
6567
When enabled, interprocedural constant propagation will perform function cloning
6568
when externally visible function can be called with constant arguments.
6569
Because this optimization can create multiple copies of functions,
6570
it may significantly increase code size
6571
(see @option{--param ipcp-unit-growth=@var{value}}).
6572
This flag is enabled by default at @option{-O3}.
6573
 
6574
@item -fipa-matrix-reorg
6575
@opindex fipa-matrix-reorg
6576
Perform matrix flattening and transposing.
6577
Matrix flattening tries to replace an @math{m}-dimensional matrix
6578
with its equivalent @math{n}-dimensional matrix, where @math{n < m}.
6579
This reduces the level of indirection needed for accessing the elements
6580
of the matrix. The second optimization is matrix transposing that
6581
attempts to change the order of the matrix's dimensions in order to
6582
improve cache locality.
6583
Both optimizations need the @option{-fwhole-program} flag.
6584
Transposing is enabled only if profiling information is available.
6585
 
6586
@item -ftree-sink
6587
@opindex ftree-sink
6588
Perform forward store motion  on trees.  This flag is
6589
enabled by default at @option{-O} and higher.
6590
 
6591
@item -ftree-ccp
6592
@opindex ftree-ccp
6593
Perform sparse conditional constant propagation (CCP) on trees.  This
6594
pass only operates on local scalar variables and is enabled by default
6595
at @option{-O} and higher.
6596
 
6597
@item -ftree-switch-conversion
6598
Perform conversion of simple initializations in a switch to
6599
initializations from a scalar array.  This flag is enabled by default
6600
at @option{-O2} and higher.
6601
 
6602
@item -ftree-dce
6603
@opindex ftree-dce
6604
Perform dead code elimination (DCE) on trees.  This flag is enabled by
6605
default at @option{-O} and higher.
6606
 
6607
@item -ftree-builtin-call-dce
6608
@opindex ftree-builtin-call-dce
6609
Perform conditional dead code elimination (DCE) for calls to builtin functions
6610
that may set @code{errno} but are otherwise side-effect free.  This flag is
6611
enabled by default at @option{-O2} and higher if @option{-Os} is not also
6612
specified.
6613
 
6614
@item -ftree-dominator-opts
6615
@opindex ftree-dominator-opts
6616
Perform a variety of simple scalar cleanups (constant/copy
6617
propagation, redundancy elimination, range propagation and expression
6618
simplification) based on a dominator tree traversal.  This also
6619
performs jump threading (to reduce jumps to jumps). This flag is
6620
enabled by default at @option{-O} and higher.
6621
 
6622
@item -ftree-dse
6623
@opindex ftree-dse
6624
Perform dead store elimination (DSE) on trees.  A dead store is a store into
6625
a memory location which will later be overwritten by another store without
6626
any intervening loads.  In this case the earlier store can be deleted.  This
6627
flag is enabled by default at @option{-O} and higher.
6628
 
6629
@item -ftree-ch
6630
@opindex ftree-ch
6631
Perform loop header copying on trees.  This is beneficial since it increases
6632
effectiveness of code motion optimizations.  It also saves one jump.  This flag
6633
is enabled by default at @option{-O} and higher.  It is not enabled
6634
for @option{-Os}, since it usually increases code size.
6635
 
6636
@item -ftree-loop-optimize
6637
@opindex ftree-loop-optimize
6638
Perform loop optimizations on trees.  This flag is enabled by default
6639
at @option{-O} and higher.
6640
 
6641
@item -ftree-loop-linear
6642
@opindex ftree-loop-linear
6643
Perform linear loop transformations on tree.  This flag can improve cache
6644
performance and allow further loop optimizations to take place.
6645
 
6646
@item -floop-interchange
6647
Perform loop interchange transformations on loops.  Interchanging two
6648
nested loops switches the inner and outer loops.  For example, given a
6649
loop like:
6650
@smallexample
6651
DO J = 1, M
6652
  DO I = 1, N
6653
    A(J, I) = A(J, I) * C
6654
  ENDDO
6655
ENDDO
6656
@end smallexample
6657
loop interchange will transform the loop as if the user had written:
6658
@smallexample
6659
DO I = 1, N
6660
  DO J = 1, M
6661
    A(J, I) = A(J, I) * C
6662
  ENDDO
6663
ENDDO
6664
@end smallexample
6665
which can be beneficial when @code{N} is larger than the caches,
6666
because in Fortran, the elements of an array are stored in memory
6667
contiguously by column, and the original loop iterates over rows,
6668
potentially creating at each access a cache miss.  This optimization
6669
applies to all the languages supported by GCC and is not limited to
6670
Fortran.  To use this code transformation, GCC has to be configured
6671
with @option{--with-ppl} and @option{--with-cloog} to enable the
6672
Graphite loop transformation infrastructure.
6673
 
6674
@item -floop-strip-mine
6675
Perform loop strip mining transformations on loops.  Strip mining
6676
splits a loop into two nested loops.  The outer loop has strides
6677
equal to the strip size and the inner loop has strides of the
6678
original loop within a strip.  The strip length can be changed
6679
using the @option{loop-block-tile-size} parameter.  For example,
6680
given a loop like:
6681
@smallexample
6682
DO I = 1, N
6683
  A(I) = A(I) + C
6684
ENDDO
6685
@end smallexample
6686
loop strip mining will transform the loop as if the user had written:
6687
@smallexample
6688
DO II = 1, N, 51
6689
  DO I = II, min (II + 50, N)
6690
    A(I) = A(I) + C
6691
  ENDDO
6692
ENDDO
6693
@end smallexample
6694
This optimization applies to all the languages supported by GCC and is
6695
not limited to Fortran.  To use this code transformation, GCC has to
6696
be configured with @option{--with-ppl} and @option{--with-cloog} to
6697
enable the Graphite loop transformation infrastructure.
6698
 
6699
@item -floop-block
6700
Perform loop blocking transformations on loops.  Blocking strip mines
6701
each loop in the loop nest such that the memory accesses of the
6702
element loops fit inside caches.  The strip length can be changed
6703
using the @option{loop-block-tile-size} parameter.  For example, given
6704
a loop like:
6705
@smallexample
6706
DO I = 1, N
6707
  DO J = 1, M
6708
    A(J, I) = B(I) + C(J)
6709
  ENDDO
6710
ENDDO
6711
@end smallexample
6712
loop blocking will transform the loop as if the user had written:
6713
@smallexample
6714
DO II = 1, N, 51
6715
  DO JJ = 1, M, 51
6716
    DO I = II, min (II + 50, N)
6717
      DO J = JJ, min (JJ + 50, M)
6718
        A(J, I) = B(I) + C(J)
6719
      ENDDO
6720
    ENDDO
6721
  ENDDO
6722
ENDDO
6723
@end smallexample
6724
which can be beneficial when @code{M} is larger than the caches,
6725
because the innermost loop will iterate over a smaller amount of data
6726
that can be kept in the caches.  This optimization applies to all the
6727
languages supported by GCC and is not limited to Fortran.  To use this
6728
code transformation, GCC has to be configured with @option{--with-ppl}
6729
and @option{--with-cloog} to enable the Graphite loop transformation
6730
infrastructure.
6731
 
6732
@item -fgraphite-identity
6733
@opindex fgraphite-identity
6734
Enable the identity transformation for graphite.  For every SCoP we generate
6735
the polyhedral representation and transform it back to gimple.  Using
6736
@option{-fgraphite-identity} we can check the costs or benefits of the
6737
GIMPLE -> GRAPHITE -> GIMPLE transformation.  Some minimal optimizations
6738
are also performed by the code generator CLooG, like index splitting and
6739
dead code elimination in loops.
6740
 
6741
@item -floop-parallelize-all
6742
Use the Graphite data dependence analysis to identify loops that can
6743
be parallelized.  Parallelize all the loops that can be analyzed to
6744
not contain loop carried dependences without checking that it is
6745
profitable to parallelize the loops.
6746
 
6747
@item -fcheck-data-deps
6748
@opindex fcheck-data-deps
6749
Compare the results of several data dependence analyzers.  This option
6750
is used for debugging the data dependence analyzers.
6751
 
6752
@item -ftree-loop-distribution
6753
Perform loop distribution.  This flag can improve cache performance on
6754
big loop bodies and allow further loop optimizations, like
6755
parallelization or vectorization, to take place.  For example, the loop
6756
@smallexample
6757
DO I = 1, N
6758
  A(I) = B(I) + C
6759
  D(I) = E(I) * F
6760
ENDDO
6761
@end smallexample
6762
is transformed to
6763
@smallexample
6764
DO I = 1, N
6765
   A(I) = B(I) + C
6766
ENDDO
6767
DO I = 1, N
6768
   D(I) = E(I) * F
6769
ENDDO
6770
@end smallexample
6771
 
6772
@item -ftree-loop-im
6773
@opindex ftree-loop-im
6774
Perform loop invariant motion on trees.  This pass moves only invariants that
6775
would be hard to handle at RTL level (function calls, operations that expand to
6776
nontrivial sequences of insns).  With @option{-funswitch-loops} it also moves
6777
operands of conditions that are invariant out of the loop, so that we can use
6778
just trivial invariantness analysis in loop unswitching.  The pass also includes
6779
store motion.
6780
 
6781
@item -ftree-loop-ivcanon
6782
@opindex ftree-loop-ivcanon
6783
Create a canonical counter for number of iterations in the loop for that
6784
determining number of iterations requires complicated analysis.  Later
6785
optimizations then may determine the number easily.  Useful especially
6786
in connection with unrolling.
6787
 
6788
@item -fivopts
6789
@opindex fivopts
6790
Perform induction variable optimizations (strength reduction, induction
6791
variable merging and induction variable elimination) on trees.
6792
 
6793
@item -ftree-parallelize-loops=n
6794
@opindex ftree-parallelize-loops
6795
Parallelize loops, i.e., split their iteration space to run in n threads.
6796
This is only possible for loops whose iterations are independent
6797
and can be arbitrarily reordered.  The optimization is only
6798
profitable on multiprocessor machines, for loops that are CPU-intensive,
6799
rather than constrained e.g.@: by memory bandwidth.  This option
6800
implies @option{-pthread}, and thus is only supported on targets
6801
that have support for @option{-pthread}.
6802
 
6803
@item -ftree-pta
6804
@opindex ftree-pta
6805
Perform function-local points-to analysis on trees.  This flag is
6806
enabled by default at @option{-O} and higher.
6807
 
6808
@item -ftree-sra
6809
@opindex ftree-sra
6810
Perform scalar replacement of aggregates.  This pass replaces structure
6811
references with scalars to prevent committing structures to memory too
6812
early.  This flag is enabled by default at @option{-O} and higher.
6813
 
6814
@item -ftree-copyrename
6815
@opindex ftree-copyrename
6816
Perform copy renaming on trees.  This pass attempts to rename compiler
6817
temporaries to other variables at copy locations, usually resulting in
6818
variable names which more closely resemble the original variables.  This flag
6819
is enabled by default at @option{-O} and higher.
6820
 
6821
@item -ftree-ter
6822
@opindex ftree-ter
6823
Perform temporary expression replacement during the SSA->normal phase.  Single
6824
use/single def temporaries are replaced at their use location with their
6825
defining expression.  This results in non-GIMPLE code, but gives the expanders
6826
much more complex trees to work on resulting in better RTL generation.  This is
6827
enabled by default at @option{-O} and higher.
6828
 
6829
@item -ftree-vectorize
6830
@opindex ftree-vectorize
6831
Perform loop vectorization on trees. This flag is enabled by default at
6832
@option{-O3}.
6833
 
6834
@item -ftree-slp-vectorize
6835
@opindex ftree-slp-vectorize
6836
Perform basic block vectorization on trees. This flag is enabled by default at
6837
@option{-O3} and when @option{-ftree-vectorize} is enabled.
6838
 
6839
@item -ftree-vect-loop-version
6840
@opindex ftree-vect-loop-version
6841
Perform loop versioning when doing loop vectorization on trees.  When a loop
6842
appears to be vectorizable except that data alignment or data dependence cannot
6843
be determined at compile time then vectorized and non-vectorized versions of
6844
the loop are generated along with runtime checks for alignment or dependence
6845
to control which version is executed.  This option is enabled by default
6846
except at level @option{-Os} where it is disabled.
6847
 
6848
@item -fvect-cost-model
6849
@opindex fvect-cost-model
6850
Enable cost model for vectorization.
6851
 
6852
@item -ftree-vrp
6853
@opindex ftree-vrp
6854
Perform Value Range Propagation on trees.  This is similar to the
6855
constant propagation pass, but instead of values, ranges of values are
6856
propagated.  This allows the optimizers to remove unnecessary range
6857
checks like array bound checks and null pointer checks.  This is
6858
enabled by default at @option{-O2} and higher.  Null pointer check
6859
elimination is only done if @option{-fdelete-null-pointer-checks} is
6860
enabled.
6861
 
6862
@item -ftracer
6863
@opindex ftracer
6864
Perform tail duplication to enlarge superblock size.  This transformation
6865
simplifies the control flow of the function allowing other optimizations to do
6866
better job.
6867
 
6868
@item -funroll-loops
6869
@opindex funroll-loops
6870
Unroll loops whose number of iterations can be determined at compile
6871
time or upon entry to the loop.  @option{-funroll-loops} implies
6872
@option{-frerun-cse-after-loop}.  This option makes code larger,
6873
and may or may not make it run faster.
6874
 
6875
@item -funroll-all-loops
6876
@opindex funroll-all-loops
6877
Unroll all loops, even if their number of iterations is uncertain when
6878
the loop is entered.  This usually makes programs run more slowly.
6879
@option{-funroll-all-loops} implies the same options as
6880
@option{-funroll-loops},
6881
 
6882
@item -fsplit-ivs-in-unroller
6883
@opindex fsplit-ivs-in-unroller
6884
Enables expressing of values of induction variables in later iterations
6885
of the unrolled loop using the value in the first iteration.  This breaks
6886
long dependency chains, thus improving efficiency of the scheduling passes.
6887
 
6888
Combination of @option{-fweb} and CSE is often sufficient to obtain the
6889
same effect.  However in cases the loop body is more complicated than
6890
a single basic block, this is not reliable.  It also does not work at all
6891
on some of the architectures due to restrictions in the CSE pass.
6892
 
6893
This optimization is enabled by default.
6894
 
6895
@item -fvariable-expansion-in-unroller
6896
@opindex fvariable-expansion-in-unroller
6897
With this option, the compiler will create multiple copies of some
6898
local variables when unrolling a loop which can result in superior code.
6899
 
6900
@item -fpredictive-commoning
6901
@opindex fpredictive-commoning
6902
Perform predictive commoning optimization, i.e., reusing computations
6903
(especially memory loads and stores) performed in previous
6904
iterations of loops.
6905
 
6906
This option is enabled at level @option{-O3}.
6907
 
6908
@item -fprefetch-loop-arrays
6909
@opindex fprefetch-loop-arrays
6910
If supported by the target machine, generate instructions to prefetch
6911
memory to improve the performance of loops that access large arrays.
6912
 
6913
This option may generate better or worse code; results are highly
6914
dependent on the structure of loops within the source code.
6915
 
6916
Disabled at level @option{-Os}.
6917
 
6918
@item -fno-peephole
6919
@itemx -fno-peephole2
6920
@opindex fno-peephole
6921
@opindex fno-peephole2
6922
Disable any machine-specific peephole optimizations.  The difference
6923
between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
6924
are implemented in the compiler; some targets use one, some use the
6925
other, a few use both.
6926
 
6927
@option{-fpeephole} is enabled by default.
6928
@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6929
 
6930
@item -fno-guess-branch-probability
6931
@opindex fno-guess-branch-probability
6932
Do not guess branch probabilities using heuristics.
6933
 
6934
GCC will use heuristics to guess branch probabilities if they are
6935
not provided by profiling feedback (@option{-fprofile-arcs}).  These
6936
heuristics are based on the control flow graph.  If some branch probabilities
6937
are specified by @samp{__builtin_expect}, then the heuristics will be
6938
used to guess branch probabilities for the rest of the control flow graph,
6939
taking the @samp{__builtin_expect} info into account.  The interactions
6940
between the heuristics and @samp{__builtin_expect} can be complex, and in
6941
some cases, it may be useful to disable the heuristics so that the effects
6942
of @samp{__builtin_expect} are easier to understand.
6943
 
6944
The default is @option{-fguess-branch-probability} at levels
6945
@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
6946
 
6947
@item -freorder-blocks
6948
@opindex freorder-blocks
6949
Reorder basic blocks in the compiled function in order to reduce number of
6950
taken branches and improve code locality.
6951
 
6952
Enabled at levels @option{-O2}, @option{-O3}.
6953
 
6954
@item -freorder-blocks-and-partition
6955
@opindex freorder-blocks-and-partition
6956
In addition to reordering basic blocks in the compiled function, in order
6957
to reduce number of taken branches, partitions hot and cold basic blocks
6958
into separate sections of the assembly and .o files, to improve
6959
paging and cache locality performance.
6960
 
6961
This optimization is automatically turned off in the presence of
6962
exception handling, for linkonce sections, for functions with a user-defined
6963
section attribute and on any architecture that does not support named
6964
sections.
6965
 
6966
@item -freorder-functions
6967
@opindex freorder-functions
6968
Reorder functions in the object file in order to
6969
improve code locality.  This is implemented by using special
6970
subsections @code{.text.hot} for most frequently executed functions and
6971
@code{.text.unlikely} for unlikely executed functions.  Reordering is done by
6972
the linker so object file format must support named sections and linker must
6973
place them in a reasonable way.
6974
 
6975
Also profile feedback must be available in to make this option effective.  See
6976
@option{-fprofile-arcs} for details.
6977
 
6978
Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6979
 
6980
@item -fstrict-aliasing
6981
@opindex fstrict-aliasing
6982
Allow the compiler to assume the strictest aliasing rules applicable to
6983
the language being compiled.  For C (and C++), this activates
6984
optimizations based on the type of expressions.  In particular, an
6985
object of one type is assumed never to reside at the same address as an
6986
object of a different type, unless the types are almost the same.  For
6987
example, an @code{unsigned int} can alias an @code{int}, but not a
6988
@code{void*} or a @code{double}.  A character type may alias any other
6989
type.
6990
 
6991
@anchor{Type-punning}Pay special attention to code like this:
6992
@smallexample
6993
union a_union @{
6994
  int i;
6995
  double d;
6996
@};
6997
 
6998
int f() @{
6999
  union a_union t;
7000
  t.d = 3.0;
7001
  return t.i;
7002
@}
7003
@end smallexample
7004
The practice of reading from a different union member than the one most
7005
recently written to (called ``type-punning'') is common.  Even with
7006
@option{-fstrict-aliasing}, type-punning is allowed, provided the memory
7007
is accessed through the union type.  So, the code above will work as
7008
expected.  @xref{Structures unions enumerations and bit-fields
7009
implementation}.  However, this code might not:
7010
@smallexample
7011
int f() @{
7012
  union a_union t;
7013
  int* ip;
7014
  t.d = 3.0;
7015
  ip = &t.i;
7016
  return *ip;
7017
@}
7018
@end smallexample
7019
 
7020
Similarly, access by taking the address, casting the resulting pointer
7021
and dereferencing the result has undefined behavior, even if the cast
7022
uses a union type, e.g.:
7023
@smallexample
7024
int f() @{
7025
  double d = 3.0;
7026
  return ((union a_union *) &d)->i;
7027
@}
7028
@end smallexample
7029
 
7030
The @option{-fstrict-aliasing} option is enabled at levels
7031
@option{-O2}, @option{-O3}, @option{-Os}.
7032
 
7033
@item -fstrict-overflow
7034
@opindex fstrict-overflow
7035
Allow the compiler to assume strict signed overflow rules, depending
7036
on the language being compiled.  For C (and C++) this means that
7037
overflow when doing arithmetic with signed numbers is undefined, which
7038
means that the compiler may assume that it will not happen.  This
7039
permits various optimizations.  For example, the compiler will assume
7040
that an expression like @code{i + 10 > i} will always be true for
7041
signed @code{i}.  This assumption is only valid if signed overflow is
7042
undefined, as the expression is false if @code{i + 10} overflows when
7043
using twos complement arithmetic.  When this option is in effect any
7044
attempt to determine whether an operation on signed numbers will
7045
overflow must be written carefully to not actually involve overflow.
7046
 
7047
This option also allows the compiler to assume strict pointer
7048
semantics: given a pointer to an object, if adding an offset to that
7049
pointer does not produce a pointer to the same object, the addition is
7050
undefined.  This permits the compiler to conclude that @code{p + u >
7051
p} is always true for a pointer @code{p} and unsigned integer
7052
@code{u}.  This assumption is only valid because pointer wraparound is
7053
undefined, as the expression is false if @code{p + u} overflows using
7054
twos complement arithmetic.
7055
 
7056
See also the @option{-fwrapv} option.  Using @option{-fwrapv} means
7057
that integer signed overflow is fully defined: it wraps.  When
7058
@option{-fwrapv} is used, there is no difference between
7059
@option{-fstrict-overflow} and @option{-fno-strict-overflow} for
7060
integers.  With @option{-fwrapv} certain types of overflow are
7061
permitted.  For example, if the compiler gets an overflow when doing
7062
arithmetic on constants, the overflowed value can still be used with
7063
@option{-fwrapv}, but not otherwise.
7064
 
7065
The @option{-fstrict-overflow} option is enabled at levels
7066
@option{-O2}, @option{-O3}, @option{-Os}.
7067
 
7068
@item -falign-functions
7069
@itemx -falign-functions=@var{n}
7070
@opindex falign-functions
7071
Align the start of functions to the next power-of-two greater than
7072
@var{n}, skipping up to @var{n} bytes.  For instance,
7073
@option{-falign-functions=32} aligns functions to the next 32-byte
7074
boundary, but @option{-falign-functions=24} would align to the next
7075
32-byte boundary only if this can be done by skipping 23 bytes or less.
7076
 
7077
@option{-fno-align-functions} and @option{-falign-functions=1} are
7078
equivalent and mean that functions will not be aligned.
7079
 
7080
Some assemblers only support this flag when @var{n} is a power of two;
7081
in that case, it is rounded up.
7082
 
7083
If @var{n} is not specified or is zero, use a machine-dependent default.
7084
 
7085
Enabled at levels @option{-O2}, @option{-O3}.
7086
 
7087
@item -falign-labels
7088
@itemx -falign-labels=@var{n}
7089
@opindex falign-labels
7090
Align all branch targets to a power-of-two boundary, skipping up to
7091
@var{n} bytes like @option{-falign-functions}.  This option can easily
7092
make code slower, because it must insert dummy operations for when the
7093
branch target is reached in the usual flow of the code.
7094
 
7095
@option{-fno-align-labels} and @option{-falign-labels=1} are
7096
equivalent and mean that labels will not be aligned.
7097
 
7098
If @option{-falign-loops} or @option{-falign-jumps} are applicable and
7099
are greater than this value, then their values are used instead.
7100
 
7101
If @var{n} is not specified or is zero, use a machine-dependent default
7102
which is very likely to be @samp{1}, meaning no alignment.
7103
 
7104
Enabled at levels @option{-O2}, @option{-O3}.
7105
 
7106
@item -falign-loops
7107
@itemx -falign-loops=@var{n}
7108
@opindex falign-loops
7109
Align loops to a power-of-two boundary, skipping up to @var{n} bytes
7110
like @option{-falign-functions}.  The hope is that the loop will be
7111
executed many times, which will make up for any execution of the dummy
7112
operations.
7113
 
7114
@option{-fno-align-loops} and @option{-falign-loops=1} are
7115
equivalent and mean that loops will not be aligned.
7116
 
7117
If @var{n} is not specified or is zero, use a machine-dependent default.
7118
 
7119
Enabled at levels @option{-O2}, @option{-O3}.
7120
 
7121
@item -falign-jumps
7122
@itemx -falign-jumps=@var{n}
7123
@opindex falign-jumps
7124
Align branch targets to a power-of-two boundary, for branch targets
7125
where the targets can only be reached by jumping, skipping up to @var{n}
7126
bytes like @option{-falign-functions}.  In this case, no dummy operations
7127
need be executed.
7128
 
7129
@option{-fno-align-jumps} and @option{-falign-jumps=1} are
7130
equivalent and mean that loops will not be aligned.
7131
 
7132
If @var{n} is not specified or is zero, use a machine-dependent default.
7133
 
7134
Enabled at levels @option{-O2}, @option{-O3}.
7135
 
7136
@item -funit-at-a-time
7137
@opindex funit-at-a-time
7138
This option is left for compatibility reasons. @option{-funit-at-a-time}
7139
has no effect, while @option{-fno-unit-at-a-time} implies
7140
@option{-fno-toplevel-reorder} and @option{-fno-section-anchors}.
7141
 
7142
Enabled by default.
7143
 
7144
@item -fno-toplevel-reorder
7145
@opindex fno-toplevel-reorder
7146
Do not reorder top-level functions, variables, and @code{asm}
7147
statements.  Output them in the same order that they appear in the
7148
input file.  When this option is used, unreferenced static variables
7149
will not be removed.  This option is intended to support existing code
7150
which relies on a particular ordering.  For new code, it is better to
7151
use attributes.
7152
 
7153
Enabled at level @option{-O0}.  When disabled explicitly, it also imply
7154
@option{-fno-section-anchors} that is otherwise enabled at @option{-O0} on some
7155
targets.
7156
 
7157
@item -fweb
7158
@opindex fweb
7159
Constructs webs as commonly used for register allocation purposes and assign
7160
each web individual pseudo register.  This allows the register allocation pass
7161
to operate on pseudos directly, but also strengthens several other optimization
7162
passes, such as CSE, loop optimizer and trivial dead code remover.  It can,
7163
however, make debugging impossible, since variables will no longer stay in a
7164
``home register''.
7165
 
7166
Enabled by default with @option{-funroll-loops}.
7167
 
7168
@item -fwhole-program
7169
@opindex fwhole-program
7170
Assume that the current compilation unit represents the whole program being
7171
compiled.  All public functions and variables with the exception of @code{main}
7172
and those merged by attribute @code{externally_visible} become static functions
7173
and in effect are optimized more aggressively by interprocedural optimizers.
7174
While this option is equivalent to proper use of the @code{static} keyword for
7175
programs consisting of a single file, in combination with option
7176
@option{-combine}, @option{-flto} or @option{-fwhopr} this flag can be used to
7177
compile many smaller scale programs since the functions and variables become
7178
local for the whole combined compilation unit, not for the single source file
7179
itself.
7180
 
7181
This option implies @option{-fwhole-file} for Fortran programs.
7182
 
7183
@item -flto
7184
@opindex flto
7185
This option runs the standard link-time optimizer.  When invoked
7186
with source code, it generates GIMPLE (one of GCC's internal
7187
representations) and writes it to special ELF sections in the object
7188
file.  When the object files are linked together, all the function
7189
bodies are read from these ELF sections and instantiated as if they
7190
had been part of the same translation unit.
7191
 
7192
To use the link-timer optimizer, @option{-flto} needs to be specified at
7193
compile time and during the final link.  For example,
7194
 
7195
@smallexample
7196
gcc -c -O2 -flto foo.c
7197
gcc -c -O2 -flto bar.c
7198
gcc -o myprog -flto -O2 foo.o bar.o
7199
@end smallexample
7200
 
7201
The first two invocations to GCC will save a bytecode representation
7202
of GIMPLE into special ELF sections inside @file{foo.o} and
7203
@file{bar.o}.  The final invocation will read the GIMPLE bytecode from
7204
@file{foo.o} and @file{bar.o}, merge the two files into a single
7205
internal image, and compile the result as usual.  Since both
7206
@file{foo.o} and @file{bar.o} are merged into a single image, this
7207
causes all the inter-procedural analyses and optimizations in GCC to
7208
work across the two files as if they were a single one.  This means,
7209
for example, that the inliner will be able to inline functions in
7210
@file{bar.o} into functions in @file{foo.o} and vice-versa.
7211
 
7212
Another (simpler) way to enable link-time optimization is,
7213
 
7214
@smallexample
7215
gcc -o myprog -flto -O2 foo.c bar.c
7216
@end smallexample
7217
 
7218
The above will generate bytecode for @file{foo.c} and @file{bar.c},
7219
merge them together into a single GIMPLE representation and optimize
7220
them as usual to produce @file{myprog}.
7221
 
7222
The only important thing to keep in mind is that to enable link-time
7223
optimizations the @option{-flto} flag needs to be passed to both the
7224
compile and the link commands.
7225
 
7226
Note that when a file is compiled with @option{-flto}, the generated
7227
object file will be larger than a regular object file because it will
7228
contain GIMPLE bytecodes and the usual final code.  This means that
7229
object files with LTO information can be linked as a normal object
7230
file.  So, in the previous example, if the final link is done with
7231
 
7232
@smallexample
7233
gcc -o myprog foo.o bar.o
7234
@end smallexample
7235
 
7236
The only difference will be that no inter-procedural optimizations
7237
will be applied to produce @file{myprog}.  The two object files
7238
@file{foo.o} and @file{bar.o} will be simply sent to the regular
7239
linker.
7240
 
7241
Additionally, the optimization flags used to compile individual files
7242
are not necessarily related to those used at link-time.  For instance,
7243
 
7244
@smallexample
7245
gcc -c -O0 -flto foo.c
7246
gcc -c -O0 -flto bar.c
7247
gcc -o myprog -flto -O3 foo.o bar.o
7248
@end smallexample
7249
 
7250
This will produce individual object files with unoptimized assembler
7251
code, but the resulting binary @file{myprog} will be optimized at
7252
@option{-O3}.  Now, if the final binary is generated without
7253
@option{-flto}, then @file{myprog} will not be optimized.
7254
 
7255
When producing the final binary with @option{-flto}, GCC will only
7256
apply link-time optimizations to those files that contain bytecode.
7257
Therefore, you can mix and match object files and libraries with
7258
GIMPLE bytecodes and final object code.  GCC will automatically select
7259
which files to optimize in LTO mode and which files to link without
7260
further processing.
7261
 
7262
There are some code generation flags that GCC will preserve when
7263
generating bytecodes, as they need to be used during the final link
7264
stage.  Currently, the following options are saved into the GIMPLE
7265
bytecode files: @option{-fPIC}, @option{-fcommon} and all the
7266
@option{-m} target flags.
7267
 
7268
At link time, these options are read-in and reapplied.  Note that the
7269
current implementation makes no attempt at recognizing conflicting
7270
values for these options.  If two or more files have a conflicting
7271
value (e.g., one file is compiled with @option{-fPIC} and another
7272
isn't), the compiler will simply use the last value read from the
7273
bytecode files.  It is recommended, then, that all the files
7274
participating in the same link be compiled with the same options.
7275
 
7276
Another feature of LTO is that it is possible to apply interprocedural
7277
optimizations on files written in different languages.  This requires
7278
some support in the language front end.  Currently, the C, C++ and
7279
Fortran front ends are capable of emitting GIMPLE bytecodes, so
7280
something like this should work
7281
 
7282
@smallexample
7283
gcc -c -flto foo.c
7284
g++ -c -flto bar.cc
7285
gfortran -c -flto baz.f90
7286
g++ -o myprog -flto -O3 foo.o bar.o baz.o -lgfortran
7287
@end smallexample
7288
 
7289
Notice that the final link is done with @command{g++} to get the C++
7290
runtime libraries and @option{-lgfortran} is added to get the Fortran
7291
runtime libraries.  In general, when mixing languages in LTO mode, you
7292
should use the same link command used when mixing languages in a
7293
regular (non-LTO) compilation.  This means that if your build process
7294
was mixing languages before, all you need to add is @option{-flto} to
7295
all the compile and link commands.
7296
 
7297
If LTO encounters objects with C linkage declared with incompatible
7298
types in separate translation units to be linked together (undefined
7299
behavior according to ISO C99 6.2.7), a non-fatal diagnostic may be
7300
issued.  The behavior is still undefined at runtime.
7301
 
7302
If object files containing GIMPLE bytecode are stored in a library
7303
archive, say @file{libfoo.a}, it is possible to extract and use them
7304
in an LTO link if you are using @command{gold} as the linker (which,
7305
in turn requires GCC to be configured with @option{--enable-gold}).
7306
To enable this feature, use the flag @option{-fuse-linker-plugin} at
7307
link-time:
7308
 
7309
@smallexample
7310
gcc -o myprog -O2 -flto -fuse-linker-plugin a.o b.o -lfoo
7311
@end smallexample
7312
 
7313
With the linker plugin enabled, @command{gold} will extract the needed
7314
GIMPLE files from @file{libfoo.a} and pass them on to the running GCC
7315
to make them part of the aggregated GIMPLE image to be optimized.
7316
 
7317
If you are not using @command{gold} and/or do not specify
7318
@option{-fuse-linker-plugin} then the objects inside @file{libfoo.a}
7319
will be extracted and linked as usual, but they will not participate
7320
in the LTO optimization process.
7321
 
7322
Link time optimizations do not require the presence of the whole
7323
program to operate.  If the program does not require any symbols to
7324
be exported, it is possible to combine @option{-flto} and
7325
@option{-fwhopr} with @option{-fwhole-program} to allow the
7326
interprocedural optimizers to use more aggressive assumptions which
7327
may lead to improved optimization opportunities.
7328
 
7329
Regarding portability: the current implementation of LTO makes no
7330
attempt at generating bytecode that can be ported between different
7331
types of hosts.  The bytecode files are versioned and there is a
7332
strict version check, so bytecode files generated in one version of
7333
GCC will not work with an older/newer version of GCC.
7334
 
7335
Link time optimization does not play well with generating debugging
7336
information.  Combining @option{-flto} or @option{-fwhopr} with
7337
@option{-g} is experimental.
7338
 
7339
This option is disabled by default.
7340
 
7341
@item -fwhopr
7342
@opindex fwhopr
7343
This option is identical in functionality to @option{-flto} but it
7344
differs in how the final link stage is executed.  Instead of loading
7345
all the function bodies in memory, the callgraph is analyzed and
7346
optimization decisions are made (whole program analysis or WPA). Once
7347
optimization decisions are made, the callgraph is partitioned and the
7348
different sections are compiled separately (local transformations or
7349
LTRANS)@.  This process allows optimizations on very large programs
7350
that otherwise would not fit in memory.  This option enables
7351
@option{-fwpa} and @option{-fltrans} automatically.
7352
 
7353
Disabled by default.
7354
 
7355
This option is experimental.
7356
 
7357
@item -fwpa
7358
@opindex fwpa
7359
This is an internal option used by GCC when compiling with
7360
@option{-fwhopr}.  You should never need to use it.
7361
 
7362
This option runs the link-time optimizer in the whole-program-analysis
7363
(WPA) mode, which reads in summary information from all inputs and
7364
performs a whole-program analysis based on summary information only.
7365
It generates object files for subsequent runs of the link-time
7366
optimizer where individual object files are optimized using both
7367
summary information from the WPA mode and the actual function bodies.
7368
It then drives the LTRANS phase.
7369
 
7370
Disabled by default.
7371
 
7372
@item -fltrans
7373
@opindex fltrans
7374
This is an internal option used by GCC when compiling with
7375
@option{-fwhopr}.  You should never need to use it.
7376
 
7377
This option runs the link-time optimizer in the local-transformation (LTRANS)
7378
mode, which reads in output from a previous run of the LTO in WPA mode.
7379
In the LTRANS mode, LTO optimizes an object and produces the final assembly.
7380
 
7381
Disabled by default.
7382
 
7383
@item -fltrans-output-list=@var{file}
7384
@opindex fltrans-output-list
7385
This is an internal option used by GCC when compiling with
7386
@option{-fwhopr}.  You should never need to use it.
7387
 
7388
This option specifies a file to which the names of LTRANS output files are
7389
written.  This option is only meaningful in conjunction with @option{-fwpa}.
7390
 
7391
Disabled by default.
7392
 
7393
@item -flto-compression-level=@var{n}
7394
This option specifies the level of compression used for intermediate
7395
language written to LTO object files, and is only meaningful in
7396
conjunction with LTO mode (@option{-fwhopr}, @option{-flto}).  Valid
7397
values are 0 (no compression) to 9 (maximum compression).  Values
7398
outside this range are clamped to either 0 or 9.  If the option is not
7399
given, a default balanced compression setting is used.
7400
 
7401
@item -flto-report
7402
Prints a report with internal details on the workings of the link-time
7403
optimizer.  The contents of this report vary from version to version,
7404
it is meant to be useful to GCC developers when processing object
7405
files in LTO mode (via @option{-fwhopr} or @option{-flto}).
7406
 
7407
Disabled by default.
7408
 
7409
@item -fuse-linker-plugin
7410
Enables the extraction of objects with GIMPLE bytecode information
7411
from library archives.  This option relies on features available only
7412
in @command{gold}, so to use this you must configure GCC with
7413
@option{--enable-gold}.  See @option{-flto} for a description on the
7414
effect of this flag and how to use it.
7415
 
7416
Disabled by default.
7417
 
7418
@item -fcprop-registers
7419
@opindex fcprop-registers
7420
After register allocation and post-register allocation instruction splitting,
7421
we perform a copy-propagation pass to try to reduce scheduling dependencies
7422
and occasionally eliminate the copy.
7423
 
7424
Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
7425
 
7426
@item -fprofile-correction
7427
@opindex fprofile-correction
7428
Profiles collected using an instrumented binary for multi-threaded programs may
7429
be inconsistent due to missed counter updates. When this option is specified,
7430
GCC will use heuristics to correct or smooth out such inconsistencies. By
7431
default, GCC will emit an error message when an inconsistent profile is detected.
7432
 
7433
@item -fprofile-dir=@var{path}
7434
@opindex fprofile-dir
7435
 
7436
Set the directory to search the profile data files in to @var{path}.
7437
This option affects only the profile data generated by
7438
@option{-fprofile-generate}, @option{-ftest-coverage}, @option{-fprofile-arcs}
7439
and used by @option{-fprofile-use} and @option{-fbranch-probabilities}
7440
and its related options.
7441
By default, GCC will use the current directory as @var{path}
7442
thus the profile data file will appear in the same directory as the object file.
7443
 
7444
@item -fprofile-generate
7445
@itemx -fprofile-generate=@var{path}
7446
@opindex fprofile-generate
7447
 
7448
Enable options usually used for instrumenting application to produce
7449
profile useful for later recompilation with profile feedback based
7450
optimization.  You must use @option{-fprofile-generate} both when
7451
compiling and when linking your program.
7452
 
7453
The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
7454
 
7455
If @var{path} is specified, GCC will look at the @var{path} to find
7456
the profile feedback data files. See @option{-fprofile-dir}.
7457
 
7458
@item -fprofile-use
7459
@itemx -fprofile-use=@var{path}
7460
@opindex fprofile-use
7461
Enable profile feedback directed optimizations, and optimizations
7462
generally profitable only with profile feedback available.
7463
 
7464
The following options are enabled: @code{-fbranch-probabilities}, @code{-fvpt},
7465
@code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}
7466
 
7467
By default, GCC emits an error message if the feedback profiles do not
7468
match the source code.  This error can be turned into a warning by using
7469
@option{-Wcoverage-mismatch}.  Note this may result in poorly optimized
7470
code.
7471
 
7472
If @var{path} is specified, GCC will look at the @var{path} to find
7473
the profile feedback data files. See @option{-fprofile-dir}.
7474
@end table
7475
 
7476
The following options control compiler behavior regarding floating
7477
point arithmetic.  These options trade off between speed and
7478
correctness.  All must be specifically enabled.
7479
 
7480
@table @gcctabopt
7481
@item -ffloat-store
7482
@opindex ffloat-store
7483
Do not store floating point variables in registers, and inhibit other
7484
options that might change whether a floating point value is taken from a
7485
register or memory.
7486
 
7487
@cindex floating point precision
7488
This option prevents undesirable excess precision on machines such as
7489
the 68000 where the floating registers (of the 68881) keep more
7490
precision than a @code{double} is supposed to have.  Similarly for the
7491
x86 architecture.  For most programs, the excess precision does only
7492
good, but a few programs rely on the precise definition of IEEE floating
7493
point.  Use @option{-ffloat-store} for such programs, after modifying
7494
them to store all pertinent intermediate computations into variables.
7495
 
7496
@item -fexcess-precision=@var{style}
7497
@opindex fexcess-precision
7498
This option allows further control over excess precision on machines
7499
where floating-point registers have more precision than the IEEE
7500
@code{float} and @code{double} types and the processor does not
7501
support operations rounding to those types.  By default,
7502
@option{-fexcess-precision=fast} is in effect; this means that
7503
operations are carried out in the precision of the registers and that
7504
it is unpredictable when rounding to the types specified in the source
7505
code takes place.  When compiling C, if
7506
@option{-fexcess-precision=standard} is specified then excess
7507
precision will follow the rules specified in ISO C99; in particular,
7508
both casts and assignments cause values to be rounded to their
7509
semantic types (whereas @option{-ffloat-store} only affects
7510
assignments).  This option is enabled by default for C if a strict
7511
conformance option such as @option{-std=c99} is used.
7512
 
7513
@opindex mfpmath
7514
@option{-fexcess-precision=standard} is not implemented for languages
7515
other than C, and has no effect if
7516
@option{-funsafe-math-optimizations} or @option{-ffast-math} is
7517
specified.  On the x86, it also has no effect if @option{-mfpmath=sse}
7518
or @option{-mfpmath=sse+387} is specified; in the former case, IEEE
7519
semantics apply without excess precision, and in the latter, rounding
7520
is unpredictable.
7521
 
7522
@item -ffast-math
7523
@opindex ffast-math
7524
Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations},
7525
@option{-ffinite-math-only}, @option{-fno-rounding-math},
7526
@option{-fno-signaling-nans} and @option{-fcx-limited-range}.
7527
 
7528
This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
7529
 
7530
This option is not turned on by any @option{-O} option since
7531
it can result in incorrect output for programs which depend on
7532
an exact implementation of IEEE or ISO rules/specifications for
7533
math functions. It may, however, yield faster code for programs
7534
that do not require the guarantees of these specifications.
7535
 
7536
@item -fno-math-errno
7537
@opindex fno-math-errno
7538
Do not set ERRNO after calling math functions that are executed
7539
with a single instruction, e.g., sqrt.  A program that relies on
7540
IEEE exceptions for math error handling may want to use this flag
7541
for speed while maintaining IEEE arithmetic compatibility.
7542
 
7543
This option is not turned on by any @option{-O} option since
7544
it can result in incorrect output for programs which depend on
7545
an exact implementation of IEEE or ISO rules/specifications for
7546
math functions. It may, however, yield faster code for programs
7547
that do not require the guarantees of these specifications.
7548
 
7549
The default is @option{-fmath-errno}.
7550
 
7551
On Darwin systems, the math library never sets @code{errno}.  There is
7552
therefore no reason for the compiler to consider the possibility that
7553
it might, and @option{-fno-math-errno} is the default.
7554
 
7555
@item -funsafe-math-optimizations
7556
@opindex funsafe-math-optimizations
7557
 
7558
Allow optimizations for floating-point arithmetic that (a) assume
7559
that arguments and results are valid and (b) may violate IEEE or
7560
ANSI standards.  When used at link-time, it may include libraries
7561
or startup files that change the default FPU control word or other
7562
similar optimizations.
7563
 
7564
This option is not turned on by any @option{-O} option since
7565
it can result in incorrect output for programs which depend on
7566
an exact implementation of IEEE or ISO rules/specifications for
7567
math functions. It may, however, yield faster code for programs
7568
that do not require the guarantees of these specifications.
7569
Enables @option{-fno-signed-zeros}, @option{-fno-trapping-math},
7570
@option{-fassociative-math} and @option{-freciprocal-math}.
7571
 
7572
The default is @option{-fno-unsafe-math-optimizations}.
7573
 
7574
@item -fassociative-math
7575
@opindex fassociative-math
7576
 
7577
Allow re-association of operands in series of floating-point operations.
7578
This violates the ISO C and C++ language standard by possibly changing
7579
computation result.  NOTE: re-ordering may change the sign of zero as
7580
well as ignore NaNs and inhibit or create underflow or overflow (and
7581
thus cannot be used on a code which relies on rounding behavior like
7582
@code{(x + 2**52) - 2**52)}.  May also reorder floating-point comparisons
7583
and thus may not be used when ordered comparisons are required.
7584
This option requires that both @option{-fno-signed-zeros} and
7585
@option{-fno-trapping-math} be in effect.  Moreover, it doesn't make
7586
much sense with @option{-frounding-math}. For Fortran the option
7587
is automatically enabled when both @option{-fno-signed-zeros} and
7588
@option{-fno-trapping-math} are in effect.
7589
 
7590
The default is @option{-fno-associative-math}.
7591
 
7592
@item -freciprocal-math
7593
@opindex freciprocal-math
7594
 
7595
Allow the reciprocal of a value to be used instead of dividing by
7596
the value if this enables optimizations.  For example @code{x / y}
7597
can be replaced with @code{x * (1/y)} which is useful if @code{(1/y)}
7598
is subject to common subexpression elimination.  Note that this loses
7599
precision and increases the number of flops operating on the value.
7600
 
7601
The default is @option{-fno-reciprocal-math}.
7602
 
7603
@item -ffinite-math-only
7604
@opindex ffinite-math-only
7605
Allow optimizations for floating-point arithmetic that assume
7606
that arguments and results are not NaNs or +-Infs.
7607
 
7608
This option is not turned on by any @option{-O} option since
7609
it can result in incorrect output for programs which depend on
7610
an exact implementation of IEEE or ISO rules/specifications for
7611
math functions. It may, however, yield faster code for programs
7612
that do not require the guarantees of these specifications.
7613
 
7614
The default is @option{-fno-finite-math-only}.
7615
 
7616
@item -fno-signed-zeros
7617
@opindex fno-signed-zeros
7618
Allow optimizations for floating point arithmetic that ignore the
7619
signedness of zero.  IEEE arithmetic specifies the behavior of
7620
distinct +0.0 and @minus{}0.0 values, which then prohibits simplification
7621
of expressions such as x+0.0 or 0.0*x (even with @option{-ffinite-math-only}).
7622
This option implies that the sign of a zero result isn't significant.
7623
 
7624
The default is @option{-fsigned-zeros}.
7625
 
7626
@item -fno-trapping-math
7627
@opindex fno-trapping-math
7628
Compile code assuming that floating-point operations cannot generate
7629
user-visible traps.  These traps include division by zero, overflow,
7630
underflow, inexact result and invalid operation.  This option requires
7631
that @option{-fno-signaling-nans} be in effect.  Setting this option may
7632
allow faster code if one relies on ``non-stop'' IEEE arithmetic, for example.
7633
 
7634
This option should never be turned on by any @option{-O} option since
7635
it can result in incorrect output for programs which depend on
7636
an exact implementation of IEEE or ISO rules/specifications for
7637
math functions.
7638
 
7639
The default is @option{-ftrapping-math}.
7640
 
7641
@item -frounding-math
7642
@opindex frounding-math
7643
Disable transformations and optimizations that assume default floating
7644
point rounding behavior.  This is round-to-zero for all floating point
7645
to integer conversions, and round-to-nearest for all other arithmetic
7646
truncations.  This option should be specified for programs that change
7647
the FP rounding mode dynamically, or that may be executed with a
7648
non-default rounding mode.  This option disables constant folding of
7649
floating point expressions at compile-time (which may be affected by
7650
rounding mode) and arithmetic transformations that are unsafe in the
7651
presence of sign-dependent rounding modes.
7652
 
7653
The default is @option{-fno-rounding-math}.
7654
 
7655
This option is experimental and does not currently guarantee to
7656
disable all GCC optimizations that are affected by rounding mode.
7657
Future versions of GCC may provide finer control of this setting
7658
using C99's @code{FENV_ACCESS} pragma.  This command line option
7659
will be used to specify the default state for @code{FENV_ACCESS}.
7660
 
7661
@item -fsignaling-nans
7662
@opindex fsignaling-nans
7663
Compile code assuming that IEEE signaling NaNs may generate user-visible
7664
traps during floating-point operations.  Setting this option disables
7665
optimizations that may change the number of exceptions visible with
7666
signaling NaNs.  This option implies @option{-ftrapping-math}.
7667
 
7668
This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
7669
be defined.
7670
 
7671
The default is @option{-fno-signaling-nans}.
7672
 
7673
This option is experimental and does not currently guarantee to
7674
disable all GCC optimizations that affect signaling NaN behavior.
7675
 
7676
@item -fsingle-precision-constant
7677
@opindex fsingle-precision-constant
7678
Treat floating point constant as single precision constant instead of
7679
implicitly converting it to double precision constant.
7680
 
7681
@item -fcx-limited-range
7682
@opindex fcx-limited-range
7683
When enabled, this option states that a range reduction step is not
7684
needed when performing complex division.  Also, there is no checking
7685
whether the result of a complex multiplication or division is @code{NaN
7686
+ I*NaN}, with an attempt to rescue the situation in that case.  The
7687
default is @option{-fno-cx-limited-range}, but is enabled by
7688
@option{-ffast-math}.
7689
 
7690
This option controls the default setting of the ISO C99
7691
@code{CX_LIMITED_RANGE} pragma.  Nevertheless, the option applies to
7692
all languages.
7693
 
7694
@item -fcx-fortran-rules
7695
@opindex fcx-fortran-rules
7696
Complex multiplication and division follow Fortran rules.  Range
7697
reduction is done as part of complex division, but there is no checking
7698
whether the result of a complex multiplication or division is @code{NaN
7699
+ I*NaN}, with an attempt to rescue the situation in that case.
7700
 
7701
The default is @option{-fno-cx-fortran-rules}.
7702
 
7703
@end table
7704
 
7705
The following options control optimizations that may improve
7706
performance, but are not enabled by any @option{-O} options.  This
7707
section includes experimental options that may produce broken code.
7708
 
7709
@table @gcctabopt
7710
@item -fbranch-probabilities
7711
@opindex fbranch-probabilities
7712
After running a program compiled with @option{-fprofile-arcs}
7713
(@pxref{Debugging Options,, Options for Debugging Your Program or
7714
@command{gcc}}), you can compile it a second time using
7715
@option{-fbranch-probabilities}, to improve optimizations based on
7716
the number of times each branch was taken.  When the program
7717
compiled with @option{-fprofile-arcs} exits it saves arc execution
7718
counts to a file called @file{@var{sourcename}.gcda} for each source
7719
file.  The information in this data file is very dependent on the
7720
structure of the generated code, so you must use the same source code
7721
and the same optimization options for both compilations.
7722
 
7723
With @option{-fbranch-probabilities}, GCC puts a
7724
@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
7725
These can be used to improve optimization.  Currently, they are only
7726
used in one place: in @file{reorg.c}, instead of guessing which path a
7727
branch is mostly to take, the @samp{REG_BR_PROB} values are used to
7728
exactly determine which path is taken more often.
7729
 
7730
@item -fprofile-values
7731
@opindex fprofile-values
7732
If combined with @option{-fprofile-arcs}, it adds code so that some
7733
data about values of expressions in the program is gathered.
7734
 
7735
With @option{-fbranch-probabilities}, it reads back the data gathered
7736
from profiling values of expressions and adds @samp{REG_VALUE_PROFILE}
7737
notes to instructions for their later usage in optimizations.
7738
 
7739
Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
7740
 
7741
@item -fvpt
7742
@opindex fvpt
7743
If combined with @option{-fprofile-arcs}, it instructs the compiler to add
7744
a code to gather information about values of expressions.
7745
 
7746
With @option{-fbranch-probabilities}, it reads back the data gathered
7747
and actually performs the optimizations based on them.
7748
Currently the optimizations include specialization of division operation
7749
using the knowledge about the value of the denominator.
7750
 
7751
@item -frename-registers
7752
@opindex frename-registers
7753
Attempt to avoid false dependencies in scheduled code by making use
7754
of registers left over after register allocation.  This optimization
7755
will most benefit processors with lots of registers.  Depending on the
7756
debug information format adopted by the target, however, it can
7757
make debugging impossible, since variables will no longer stay in
7758
a ``home register''.
7759
 
7760
Enabled by default with @option{-funroll-loops} and @option{-fpeel-loops}.
7761
 
7762
@item -ftracer
7763
@opindex ftracer
7764
Perform tail duplication to enlarge superblock size.  This transformation
7765
simplifies the control flow of the function allowing other optimizations to do
7766
better job.
7767
 
7768
Enabled with @option{-fprofile-use}.
7769
 
7770
@item -funroll-loops
7771
@opindex funroll-loops
7772
Unroll loops whose number of iterations can be determined at compile time or
7773
upon entry to the loop.  @option{-funroll-loops} implies
7774
@option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.
7775
It also turns on complete loop peeling (i.e.@: complete removal of loops with
7776
small constant number of iterations).  This option makes code larger, and may
7777
or may not make it run faster.
7778
 
7779
Enabled with @option{-fprofile-use}.
7780
 
7781
@item -funroll-all-loops
7782
@opindex funroll-all-loops
7783
Unroll all loops, even if their number of iterations is uncertain when
7784
the loop is entered.  This usually makes programs run more slowly.
7785
@option{-funroll-all-loops} implies the same options as
7786
@option{-funroll-loops}.
7787
 
7788
@item -fpeel-loops
7789
@opindex fpeel-loops
7790
Peels the loops for that there is enough information that they do not
7791
roll much (from profile feedback).  It also turns on complete loop peeling
7792
(i.e.@: complete removal of loops with small constant number of iterations).
7793
 
7794
Enabled with @option{-fprofile-use}.
7795
 
7796
@item -fmove-loop-invariants
7797
@opindex fmove-loop-invariants
7798
Enables the loop invariant motion pass in the RTL loop optimizer.  Enabled
7799
at level @option{-O1}
7800
 
7801
@item -funswitch-loops
7802
@opindex funswitch-loops
7803
Move branches with loop invariant conditions out of the loop, with duplicates
7804
of the loop on both branches (modified according to result of the condition).
7805
 
7806
@item -ffunction-sections
7807
@itemx -fdata-sections
7808
@opindex ffunction-sections
7809
@opindex fdata-sections
7810
Place each function or data item into its own section in the output
7811
file if the target supports arbitrary sections.  The name of the
7812
function or the name of the data item determines the section's name
7813
in the output file.
7814
 
7815
Use these options on systems where the linker can perform optimizations
7816
to improve locality of reference in the instruction space.  Most systems
7817
using the ELF object format and SPARC processors running Solaris 2 have
7818
linkers with such optimizations.  AIX may have these optimizations in
7819
the future.
7820
 
7821
Only use these options when there are significant benefits from doing
7822
so.  When you specify these options, the assembler and linker will
7823
create larger object and executable files and will also be slower.
7824
You will not be able to use @code{gprof} on all systems if you
7825
specify this option and you may have problems with debugging if
7826
you specify both this option and @option{-g}.
7827
 
7828
@item -fbranch-target-load-optimize
7829
@opindex fbranch-target-load-optimize
7830
Perform branch target register load optimization before prologue / epilogue
7831
threading.
7832
The use of target registers can typically be exposed only during reload,
7833
thus hoisting loads out of loops and doing inter-block scheduling needs
7834
a separate optimization pass.
7835
 
7836
@item -fbranch-target-load-optimize2
7837
@opindex fbranch-target-load-optimize2
7838
Perform branch target register load optimization after prologue / epilogue
7839
threading.
7840
 
7841
@item -fbtr-bb-exclusive
7842
@opindex fbtr-bb-exclusive
7843
When performing branch target register load optimization, don't reuse
7844
branch target registers in within any basic block.
7845
 
7846
@item -fstack-protector
7847
@opindex fstack-protector
7848
Emit extra code to check for buffer overflows, such as stack smashing
7849
attacks.  This is done by adding a guard variable to functions with
7850
vulnerable objects.  This includes functions that call alloca, and
7851
functions with buffers larger than 8 bytes.  The guards are initialized
7852
when a function is entered and then checked when the function exits.
7853
If a guard check fails, an error message is printed and the program exits.
7854
 
7855
@item -fstack-protector-all
7856
@opindex fstack-protector-all
7857
Like @option{-fstack-protector} except that all functions are protected.
7858
 
7859
@item -fsection-anchors
7860
@opindex fsection-anchors
7861
Try to reduce the number of symbolic address calculations by using
7862
shared ``anchor'' symbols to address nearby objects.  This transformation
7863
can help to reduce the number of GOT entries and GOT accesses on some
7864
targets.
7865
 
7866
For example, the implementation of the following function @code{foo}:
7867
 
7868
@smallexample
7869
static int a, b, c;
7870
int foo (void) @{ return a + b + c; @}
7871
@end smallexample
7872
 
7873
would usually calculate the addresses of all three variables, but if you
7874
compile it with @option{-fsection-anchors}, it will access the variables
7875
from a common anchor point instead.  The effect is similar to the
7876
following pseudocode (which isn't valid C):
7877
 
7878
@smallexample
7879
int foo (void)
7880
@{
7881
  register int *xr = &x;
7882
  return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
7883
@}
7884
@end smallexample
7885
 
7886
Not all targets support this option.
7887
 
7888
@item --param @var{name}=@var{value}
7889
@opindex param
7890
In some places, GCC uses various constants to control the amount of
7891
optimization that is done.  For example, GCC will not inline functions
7892
that contain more that a certain number of instructions.  You can
7893
control some of these constants on the command-line using the
7894
@option{--param} option.
7895
 
7896
The names of specific parameters, and the meaning of the values, are
7897
tied to the internals of the compiler, and are subject to change
7898
without notice in future releases.
7899
 
7900
In each case, the @var{value} is an integer.  The allowable choices for
7901
@var{name} are given in the following table:
7902
 
7903
@table @gcctabopt
7904
@item struct-reorg-cold-struct-ratio
7905
The threshold ratio (as a percentage) between a structure frequency
7906
and the frequency of the hottest structure in the program.  This parameter
7907
is used by struct-reorg optimization enabled by @option{-fipa-struct-reorg}.
7908
We say that if the ratio of a structure frequency, calculated by profiling,
7909
to the hottest structure frequency in the program is less than this
7910
parameter, then structure reorganization is not applied to this structure.
7911
The default is 10.
7912
 
7913
@item predictable-branch-outcome
7914
When branch is predicted to be taken with probability lower than this threshold
7915
(in percent), then it is considered well predictable. The default is 10.
7916
 
7917
@item max-crossjump-edges
7918
The maximum number of incoming edges to consider for crossjumping.
7919
The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
7920
the number of edges incoming to each block.  Increasing values mean
7921
more aggressive optimization, making the compile time increase with
7922
probably small improvement in executable size.
7923
 
7924
@item min-crossjump-insns
7925
The minimum number of instructions which must be matched at the end
7926
of two blocks before crossjumping will be performed on them.  This
7927
value is ignored in the case where all instructions in the block being
7928
crossjumped from are matched.  The default value is 5.
7929
 
7930
@item max-grow-copy-bb-insns
7931
The maximum code size expansion factor when copying basic blocks
7932
instead of jumping.  The expansion is relative to a jump instruction.
7933
The default value is 8.
7934
 
7935
@item max-goto-duplication-insns
7936
The maximum number of instructions to duplicate to a block that jumps
7937
to a computed goto.  To avoid @math{O(N^2)} behavior in a number of
7938
passes, GCC factors computed gotos early in the compilation process,
7939
and unfactors them as late as possible.  Only computed jumps at the
7940
end of a basic blocks with no more than max-goto-duplication-insns are
7941
unfactored.  The default value is 8.
7942
 
7943
@item max-delay-slot-insn-search
7944
The maximum number of instructions to consider when looking for an
7945
instruction to fill a delay slot.  If more than this arbitrary number of
7946
instructions is searched, the time savings from filling the delay slot
7947
will be minimal so stop searching.  Increasing values mean more
7948
aggressive optimization, making the compile time increase with probably
7949
small improvement in executable run time.
7950
 
7951
@item max-delay-slot-live-search
7952
When trying to fill delay slots, the maximum number of instructions to
7953
consider when searching for a block with valid live register
7954
information.  Increasing this arbitrarily chosen value means more
7955
aggressive optimization, increasing the compile time.  This parameter
7956
should be removed when the delay slot code is rewritten to maintain the
7957
control-flow graph.
7958
 
7959
@item max-gcse-memory
7960
The approximate maximum amount of memory that will be allocated in
7961
order to perform the global common subexpression elimination
7962
optimization.  If more memory than specified is required, the
7963
optimization will not be done.
7964
 
7965
@item max-pending-list-length
7966
The maximum number of pending dependencies scheduling will allow
7967
before flushing the current state and starting over.  Large functions
7968
with few branches or calls can create excessively large lists which
7969
needlessly consume memory and resources.
7970
 
7971
@item max-inline-insns-single
7972
Several parameters control the tree inliner used in gcc.
7973
This number sets the maximum number of instructions (counted in GCC's
7974
internal representation) in a single function that the tree inliner
7975
will consider for inlining.  This only affects functions declared
7976
inline and methods implemented in a class declaration (C++).
7977
The default value is 300.
7978
 
7979
@item max-inline-insns-auto
7980
When you use @option{-finline-functions} (included in @option{-O3}),
7981
a lot of functions that would otherwise not be considered for inlining
7982
by the compiler will be investigated.  To those functions, a different
7983
(more restrictive) limit compared to functions declared inline can
7984
be applied.
7985
The default value is 50.
7986
 
7987
@item large-function-insns
7988
The limit specifying really large functions.  For functions larger than this
7989
limit after inlining, inlining is constrained by
7990
@option{--param large-function-growth}.  This parameter is useful primarily
7991
to avoid extreme compilation time caused by non-linear algorithms used by the
7992
backend.
7993
The default value is 2700.
7994
 
7995
@item large-function-growth
7996
Specifies maximal growth of large function caused by inlining in percents.
7997
The default value is 100 which limits large function growth to 2.0 times
7998
the original size.
7999
 
8000
@item large-unit-insns
8001
The limit specifying large translation unit.  Growth caused by inlining of
8002
units larger than this limit is limited by @option{--param inline-unit-growth}.
8003
For small units this might be too tight (consider unit consisting of function A
8004
that is inline and B that just calls A three time.  If B is small relative to
8005
A, the growth of unit is 300\% and yet such inlining is very sane.  For very
8006
large units consisting of small inlineable functions however the overall unit
8007
growth limit is needed to avoid exponential explosion of code size.  Thus for
8008
smaller units, the size is increased to @option{--param large-unit-insns}
8009
before applying @option{--param inline-unit-growth}.  The default is 10000
8010
 
8011
@item inline-unit-growth
8012
Specifies maximal overall growth of the compilation unit caused by inlining.
8013
The default value is 30 which limits unit growth to 1.3 times the original
8014
size.
8015
 
8016
@item ipcp-unit-growth
8017
Specifies maximal overall growth of the compilation unit caused by
8018
interprocedural constant propagation.  The default value is 10 which limits
8019
unit growth to 1.1 times the original size.
8020
 
8021
@item large-stack-frame
8022
The limit specifying large stack frames.  While inlining the algorithm is trying
8023
to not grow past this limit too much.  Default value is 256 bytes.
8024
 
8025
@item large-stack-frame-growth
8026
Specifies maximal growth of large stack frames caused by inlining in percents.
8027
The default value is 1000 which limits large stack frame growth to 11 times
8028
the original size.
8029
 
8030
@item max-inline-insns-recursive
8031
@itemx max-inline-insns-recursive-auto
8032
Specifies maximum number of instructions out-of-line copy of self recursive inline
8033
function can grow into by performing recursive inlining.
8034
 
8035
For functions declared inline @option{--param max-inline-insns-recursive} is
8036
taken into account.  For function not declared inline, recursive inlining
8037
happens only when @option{-finline-functions} (included in @option{-O3}) is
8038
enabled and @option{--param max-inline-insns-recursive-auto} is used.  The
8039
default value is 450.
8040
 
8041
@item max-inline-recursive-depth
8042
@itemx max-inline-recursive-depth-auto
8043
Specifies maximum recursion depth used by the recursive inlining.
8044
 
8045
For functions declared inline @option{--param max-inline-recursive-depth} is
8046
taken into account.  For function not declared inline, recursive inlining
8047
happens only when @option{-finline-functions} (included in @option{-O3}) is
8048
enabled and @option{--param max-inline-recursive-depth-auto} is used.  The
8049
default value is 8.
8050
 
8051
@item min-inline-recursive-probability
8052
Recursive inlining is profitable only for function having deep recursion
8053
in average and can hurt for function having little recursion depth by
8054
increasing the prologue size or complexity of function body to other
8055
optimizers.
8056
 
8057
When profile feedback is available (see @option{-fprofile-generate}) the actual
8058
recursion depth can be guessed from probability that function will recurse via
8059
given call expression.  This parameter limits inlining only to call expression
8060
whose probability exceeds given threshold (in percents).  The default value is
8061
10.
8062
 
8063
@item early-inlining-insns
8064
Specify growth that early inliner can make.  In effect it increases amount of
8065
inlining for code having large abstraction penalty.  The default value is 8.
8066
 
8067
@item max-early-inliner-iterations
8068
@itemx max-early-inliner-iterations
8069
Limit of iterations of early inliner.  This basically bounds number of nested
8070
indirect calls early inliner can resolve.  Deeper chains are still handled by
8071
late inlining.
8072
 
8073
@item min-vect-loop-bound
8074
The minimum number of iterations under which a loop will not get vectorized
8075
when @option{-ftree-vectorize} is used.  The number of iterations after
8076
vectorization needs to be greater than the value specified by this option
8077
to allow vectorization.  The default value is 0.
8078
 
8079
@item max-unrolled-insns
8080
The maximum number of instructions that a loop should have if that loop
8081
is unrolled, and if the loop is unrolled, it determines how many times
8082
the loop code is unrolled.
8083
 
8084
@item max-average-unrolled-insns
8085
The maximum number of instructions biased by probabilities of their execution
8086
that a loop should have if that loop is unrolled, and if the loop is unrolled,
8087
it determines how many times the loop code is unrolled.
8088
 
8089
@item max-unroll-times
8090
The maximum number of unrollings of a single loop.
8091
 
8092
@item max-peeled-insns
8093
The maximum number of instructions that a loop should have if that loop
8094
is peeled, and if the loop is peeled, it determines how many times
8095
the loop code is peeled.
8096
 
8097
@item max-peel-times
8098
The maximum number of peelings of a single loop.
8099
 
8100
@item max-completely-peeled-insns
8101
The maximum number of insns of a completely peeled loop.
8102
 
8103
@item max-completely-peel-times
8104
The maximum number of iterations of a loop to be suitable for complete peeling.
8105
 
8106
@item max-completely-peel-loop-nest-depth
8107
The maximum depth of a loop nest suitable for complete peeling.
8108
 
8109
@item max-unswitch-insns
8110
The maximum number of insns of an unswitched loop.
8111
 
8112
@item max-unswitch-level
8113
The maximum number of branches unswitched in a single loop.
8114
 
8115
@item lim-expensive
8116
The minimum cost of an expensive expression in the loop invariant motion.
8117
 
8118
@item iv-consider-all-candidates-bound
8119
Bound on number of candidates for induction variables below that
8120
all candidates are considered for each use in induction variable
8121
optimizations.  Only the most relevant candidates are considered
8122
if there are more candidates, to avoid quadratic time complexity.
8123
 
8124
@item iv-max-considered-uses
8125
The induction variable optimizations give up on loops that contain more
8126
induction variable uses.
8127
 
8128
@item iv-always-prune-cand-set-bound
8129
If number of candidates in the set is smaller than this value,
8130
we always try to remove unnecessary ivs from the set during its
8131
optimization when a new iv is added to the set.
8132
 
8133
@item scev-max-expr-size
8134
Bound on size of expressions used in the scalar evolutions analyzer.
8135
Large expressions slow the analyzer.
8136
 
8137
@item omega-max-vars
8138
The maximum number of variables in an Omega constraint system.
8139
The default value is 128.
8140
 
8141
@item omega-max-geqs
8142
The maximum number of inequalities in an Omega constraint system.
8143
The default value is 256.
8144
 
8145
@item omega-max-eqs
8146
The maximum number of equalities in an Omega constraint system.
8147
The default value is 128.
8148
 
8149
@item omega-max-wild-cards
8150
The maximum number of wildcard variables that the Omega solver will
8151
be able to insert.  The default value is 18.
8152
 
8153
@item omega-hash-table-size
8154
The size of the hash table in the Omega solver.  The default value is
8155
550.
8156
 
8157
@item omega-max-keys
8158
The maximal number of keys used by the Omega solver.  The default
8159
value is 500.
8160
 
8161
@item omega-eliminate-redundant-constraints
8162
When set to 1, use expensive methods to eliminate all redundant
8163
constraints.  The default value is 0.
8164
 
8165
@item vect-max-version-for-alignment-checks
8166
The maximum number of runtime checks that can be performed when
8167
doing loop versioning for alignment in the vectorizer.  See option
8168
ftree-vect-loop-version for more information.
8169
 
8170
@item vect-max-version-for-alias-checks
8171
The maximum number of runtime checks that can be performed when
8172
doing loop versioning for alias in the vectorizer.  See option
8173
ftree-vect-loop-version for more information.
8174
 
8175
@item max-iterations-to-track
8176
 
8177
The maximum number of iterations of a loop the brute force algorithm
8178
for analysis of # of iterations of the loop tries to evaluate.
8179
 
8180
@item hot-bb-count-fraction
8181
Select fraction of the maximal count of repetitions of basic block in program
8182
given basic block needs to have to be considered hot.
8183
 
8184
@item hot-bb-frequency-fraction
8185
Select fraction of the maximal frequency of executions of basic block in
8186
function given basic block needs to have to be considered hot
8187
 
8188
@item max-predicted-iterations
8189
The maximum number of loop iterations we predict statically.  This is useful
8190
in cases where function contain single loop with known bound and other loop
8191
with unknown.  We predict the known number of iterations correctly, while
8192
the unknown number of iterations average to roughly 10.  This means that the
8193
loop without bounds would appear artificially cold relative to the other one.
8194
 
8195
@item align-threshold
8196
 
8197
Select fraction of the maximal frequency of executions of basic block in
8198
function given basic block will get aligned.
8199
 
8200
@item align-loop-iterations
8201
 
8202
A loop expected to iterate at lest the selected number of iterations will get
8203
aligned.
8204
 
8205
@item tracer-dynamic-coverage
8206
@itemx tracer-dynamic-coverage-feedback
8207
 
8208
This value is used to limit superblock formation once the given percentage of
8209
executed instructions is covered.  This limits unnecessary code size
8210
expansion.
8211
 
8212
The @option{tracer-dynamic-coverage-feedback} is used only when profile
8213
feedback is available.  The real profiles (as opposed to statically estimated
8214
ones) are much less balanced allowing the threshold to be larger value.
8215
 
8216
@item tracer-max-code-growth
8217
Stop tail duplication once code growth has reached given percentage.  This is
8218
rather hokey argument, as most of the duplicates will be eliminated later in
8219
cross jumping, so it may be set to much higher values than is the desired code
8220
growth.
8221
 
8222
@item tracer-min-branch-ratio
8223
 
8224
Stop reverse growth when the reverse probability of best edge is less than this
8225
threshold (in percent).
8226
 
8227
@item tracer-min-branch-ratio
8228
@itemx tracer-min-branch-ratio-feedback
8229
 
8230
Stop forward growth if the best edge do have probability lower than this
8231
threshold.
8232
 
8233
Similarly to @option{tracer-dynamic-coverage} two values are present, one for
8234
compilation for profile feedback and one for compilation without.  The value
8235
for compilation with profile feedback needs to be more conservative (higher) in
8236
order to make tracer effective.
8237
 
8238
@item max-cse-path-length
8239
 
8240
Maximum number of basic blocks on path that cse considers.  The default is 10.
8241
 
8242
@item max-cse-insns
8243
The maximum instructions CSE process before flushing. The default is 1000.
8244
 
8245
@item ggc-min-expand
8246
 
8247
GCC uses a garbage collector to manage its own memory allocation.  This
8248
parameter specifies the minimum percentage by which the garbage
8249
collector's heap should be allowed to expand between collections.
8250
Tuning this may improve compilation speed; it has no effect on code
8251
generation.
8252
 
8253
The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
8254
RAM >= 1GB@.  If @code{getrlimit} is available, the notion of "RAM" is
8255
the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}.  If
8256
GCC is not able to calculate RAM on a particular platform, the lower
8257
bound of 30% is used.  Setting this parameter and
8258
@option{ggc-min-heapsize} to zero causes a full collection to occur at
8259
every opportunity.  This is extremely slow, but can be useful for
8260
debugging.
8261
 
8262
@item ggc-min-heapsize
8263
 
8264
Minimum size of the garbage collector's heap before it begins bothering
8265
to collect garbage.  The first collection occurs after the heap expands
8266
by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}.  Again,
8267
tuning this may improve compilation speed, and has no effect on code
8268
generation.
8269
 
8270
The default is the smaller of RAM/8, RLIMIT_RSS, or a limit which
8271
tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
8272
with a lower bound of 4096 (four megabytes) and an upper bound of
8273
131072 (128 megabytes).  If GCC is not able to calculate RAM on a
8274
particular platform, the lower bound is used.  Setting this parameter
8275
very large effectively disables garbage collection.  Setting this
8276
parameter and @option{ggc-min-expand} to zero causes a full collection
8277
to occur at every opportunity.
8278
 
8279
@item max-reload-search-insns
8280
The maximum number of instruction reload should look backward for equivalent
8281
register.  Increasing values mean more aggressive optimization, making the
8282
compile time increase with probably slightly better performance.  The default
8283
value is 100.
8284
 
8285
@item max-cselib-memory-locations
8286
The maximum number of memory locations cselib should take into account.
8287
Increasing values mean more aggressive optimization, making the compile time
8288
increase with probably slightly better performance.  The default value is 500.
8289
 
8290
@item reorder-blocks-duplicate
8291
@itemx reorder-blocks-duplicate-feedback
8292
 
8293
Used by basic block reordering pass to decide whether to use unconditional
8294
branch or duplicate the code on its destination.  Code is duplicated when its
8295
estimated size is smaller than this value multiplied by the estimated size of
8296
unconditional jump in the hot spots of the program.
8297
 
8298
The @option{reorder-block-duplicate-feedback} is used only when profile
8299
feedback is available and may be set to higher values than
8300
@option{reorder-block-duplicate} since information about the hot spots is more
8301
accurate.
8302
 
8303
@item max-sched-ready-insns
8304
The maximum number of instructions ready to be issued the scheduler should
8305
consider at any given time during the first scheduling pass.  Increasing
8306
values mean more thorough searches, making the compilation time increase
8307
with probably little benefit.  The default value is 100.
8308
 
8309
@item max-sched-region-blocks
8310
The maximum number of blocks in a region to be considered for
8311
interblock scheduling.  The default value is 10.
8312
 
8313
@item max-pipeline-region-blocks
8314
The maximum number of blocks in a region to be considered for
8315
pipelining in the selective scheduler.  The default value is 15.
8316
 
8317
@item max-sched-region-insns
8318
The maximum number of insns in a region to be considered for
8319
interblock scheduling.  The default value is 100.
8320
 
8321
@item max-pipeline-region-insns
8322
The maximum number of insns in a region to be considered for
8323
pipelining in the selective scheduler.  The default value is 200.
8324
 
8325
@item min-spec-prob
8326
The minimum probability (in percents) of reaching a source block
8327
for interblock speculative scheduling.  The default value is 40.
8328
 
8329
@item max-sched-extend-regions-iters
8330
The maximum number of iterations through CFG to extend regions.
8331
 
8332
N - do at most N iterations.
8333
The default value is 0.
8334
 
8335
@item max-sched-insn-conflict-delay
8336
The maximum conflict delay for an insn to be considered for speculative motion.
8337
The default value is 3.
8338
 
8339
@item sched-spec-prob-cutoff
8340
The minimal probability of speculation success (in percents), so that
8341
speculative insn will be scheduled.
8342
The default value is 40.
8343
 
8344
@item sched-mem-true-dep-cost
8345
Minimal distance (in CPU cycles) between store and load targeting same
8346
memory locations.  The default value is 1.
8347
 
8348
@item selsched-max-lookahead
8349
The maximum size of the lookahead window of selective scheduling.  It is a
8350
depth of search for available instructions.
8351
The default value is 50.
8352
 
8353
@item selsched-max-sched-times
8354
The maximum number of times that an instruction will be scheduled during
8355
selective scheduling.  This is the limit on the number of iterations
8356
through which the instruction may be pipelined.  The default value is 2.
8357
 
8358
@item selsched-max-insns-to-rename
8359
The maximum number of best instructions in the ready list that are considered
8360
for renaming in the selective scheduler.  The default value is 2.
8361
 
8362
@item max-last-value-rtl
8363
The maximum size measured as number of RTLs that can be recorded in an expression
8364
in combiner for a pseudo register as last known value of that register.  The default
8365
is 10000.
8366
 
8367
@item integer-share-limit
8368
Small integer constants can use a shared data structure, reducing the
8369
compiler's memory usage and increasing its speed.  This sets the maximum
8370
value of a shared integer constant.  The default value is 256.
8371
 
8372
@item min-virtual-mappings
8373
Specifies the minimum number of virtual mappings in the incremental
8374
SSA updater that should be registered to trigger the virtual mappings
8375
heuristic defined by virtual-mappings-ratio.  The default value is
8376
100.
8377
 
8378
@item virtual-mappings-ratio
8379
If the number of virtual mappings is virtual-mappings-ratio bigger
8380
than the number of virtual symbols to be updated, then the incremental
8381
SSA updater switches to a full update for those symbols.  The default
8382
ratio is 3.
8383
 
8384
@item ssp-buffer-size
8385
The minimum size of buffers (i.e.@: arrays) that will receive stack smashing
8386
protection when @option{-fstack-protection} is used.
8387
 
8388
@item max-jump-thread-duplication-stmts
8389
Maximum number of statements allowed in a block that needs to be
8390
duplicated when threading jumps.
8391
 
8392
@item max-fields-for-field-sensitive
8393
Maximum number of fields in a structure we will treat in
8394
a field sensitive manner during pointer analysis.  The default is zero
8395
for -O0, and -O1 and 100 for -Os, -O2, and -O3.
8396
 
8397
@item prefetch-latency
8398
Estimate on average number of instructions that are executed before
8399
prefetch finishes.  The distance we prefetch ahead is proportional
8400
to this constant.  Increasing this number may also lead to less
8401
streams being prefetched (see @option{simultaneous-prefetches}).
8402
 
8403
@item simultaneous-prefetches
8404
Maximum number of prefetches that can run at the same time.
8405
 
8406
@item l1-cache-line-size
8407
The size of cache line in L1 cache, in bytes.
8408
 
8409
@item l1-cache-size
8410
The size of L1 cache, in kilobytes.
8411
 
8412
@item l2-cache-size
8413
The size of L2 cache, in kilobytes.
8414
 
8415
@item min-insn-to-prefetch-ratio
8416
The minimum ratio between the number of instructions and the
8417
number of prefetches to enable prefetching in a loop with an
8418
unknown trip count.
8419
 
8420
@item prefetch-min-insn-to-mem-ratio
8421
The minimum ratio between the number of instructions and the
8422
number of memory references to enable prefetching in a loop.
8423
 
8424
@item use-canonical-types
8425
Whether the compiler should use the ``canonical'' type system.  By
8426
default, this should always be 1, which uses a more efficient internal
8427
mechanism for comparing types in C++ and Objective-C++.  However, if
8428
bugs in the canonical type system are causing compilation failures,
8429
set this value to 0 to disable canonical types.
8430
 
8431
@item switch-conversion-max-branch-ratio
8432
Switch initialization conversion will refuse to create arrays that are
8433
bigger than @option{switch-conversion-max-branch-ratio} times the number of
8434
branches in the switch.
8435
 
8436
@item max-partial-antic-length
8437
Maximum length of the partial antic set computed during the tree
8438
partial redundancy elimination optimization (@option{-ftree-pre}) when
8439
optimizing at @option{-O3} and above.  For some sorts of source code
8440
the enhanced partial redundancy elimination optimization can run away,
8441
consuming all of the memory available on the host machine.  This
8442
parameter sets a limit on the length of the sets that are computed,
8443
which prevents the runaway behavior.  Setting a value of 0 for
8444
this parameter will allow an unlimited set length.
8445
 
8446
@item sccvn-max-scc-size
8447
Maximum size of a strongly connected component (SCC) during SCCVN
8448
processing.  If this limit is hit, SCCVN processing for the whole
8449
function will not be done and optimizations depending on it will
8450
be disabled.  The default maximum SCC size is 10000.
8451
 
8452
@item ira-max-loops-num
8453
IRA uses a regional register allocation by default.  If a function
8454
contains loops more than number given by the parameter, only at most
8455
given number of the most frequently executed loops will form regions
8456
for the regional register allocation.  The default value of the
8457
parameter is 100.
8458
 
8459
@item ira-max-conflict-table-size
8460
Although IRA uses a sophisticated algorithm of compression conflict
8461
table, the table can be still big for huge functions.  If the conflict
8462
table for a function could be more than size in MB given by the
8463
parameter, the conflict table is not built and faster, simpler, and
8464
lower quality register allocation algorithm will be used.  The
8465
algorithm do not use pseudo-register conflicts.  The default value of
8466
the parameter is 2000.
8467
 
8468
@item ira-loop-reserved-regs
8469
IRA can be used to evaluate more accurate register pressure in loops
8470
for decision to move loop invariants (see @option{-O3}).  The number
8471
of available registers reserved for some other purposes is described
8472
by this parameter.  The default value of the parameter is 2 which is
8473
minimal number of registers needed for execution of typical
8474
instruction.  This value is the best found from numerous experiments.
8475
 
8476
@item loop-invariant-max-bbs-in-loop
8477
Loop invariant motion can be very expensive, both in compile time and
8478
in amount of needed compile time memory, with very large loops.  Loops
8479
with more basic blocks than this parameter won't have loop invariant
8480
motion optimization performed on them.  The default value of the
8481
parameter is 1000 for -O1 and 10000 for -O2 and above.
8482
 
8483
@item max-vartrack-size
8484
Sets a maximum number of hash table slots to use during variable
8485
tracking dataflow analysis of any function.  If this limit is exceeded
8486
with variable tracking at assignments enabled, analysis for that
8487
function is retried without it, after removing all debug insns from
8488
the function.  If the limit is exceeded even without debug insns, var
8489
tracking analysis is completely disabled for the function.  Setting
8490
the parameter to zero makes it unlimited.
8491
 
8492
@item min-nondebug-insn-uid
8493
Use uids starting at this parameter for nondebug insns.  The range below
8494
the parameter is reserved exclusively for debug insns created by
8495
@option{-fvar-tracking-assignments}, but debug insns may get
8496
(non-overlapping) uids above it if the reserved range is exhausted.
8497
 
8498
@item ipa-sra-ptr-growth-factor
8499
IPA-SRA will replace a pointer to an aggregate with one or more new
8500
parameters only when their cumulative size is less or equal to
8501
@option{ipa-sra-ptr-growth-factor} times the size of the original
8502
pointer parameter.
8503
 
8504
@item graphite-max-nb-scop-params
8505
To avoid exponential effects in the Graphite loop transforms, the
8506
number of parameters in a Static Control Part (SCoP) is bounded.  The
8507
default value is 10 parameters.  A variable whose value is unknown at
8508
compile time and defined outside a SCoP is a parameter of the SCoP.
8509
 
8510
@item graphite-max-bbs-per-function
8511
To avoid exponential effects in the detection of SCoPs, the size of
8512
the functions analyzed by Graphite is bounded.  The default value is
8513
100 basic blocks.
8514
 
8515
@item loop-block-tile-size
8516
Loop blocking or strip mining transforms, enabled with
8517
@option{-floop-block} or @option{-floop-strip-mine}, strip mine each
8518
loop in the loop nest by a given number of iterations.  The strip
8519
length can be changed using the @option{loop-block-tile-size}
8520
parameter.  The default value is 51 iterations.
8521
 
8522
@end table
8523
@end table
8524
 
8525
@node Preprocessor Options
8526
@section Options Controlling the Preprocessor
8527
@cindex preprocessor options
8528
@cindex options, preprocessor
8529
 
8530
These options control the C preprocessor, which is run on each C source
8531
file before actual compilation.
8532
 
8533
If you use the @option{-E} option, nothing is done except preprocessing.
8534
Some of these options make sense only together with @option{-E} because
8535
they cause the preprocessor output to be unsuitable for actual
8536
compilation.
8537
 
8538
@table @gcctabopt
8539
@item -Wp,@var{option}
8540
@opindex Wp
8541
You can use @option{-Wp,@var{option}} to bypass the compiler driver
8542
and pass @var{option} directly through to the preprocessor.  If
8543
@var{option} contains commas, it is split into multiple options at the
8544
commas.  However, many options are modified, translated or interpreted
8545
by the compiler driver before being passed to the preprocessor, and
8546
@option{-Wp} forcibly bypasses this phase.  The preprocessor's direct
8547
interface is undocumented and subject to change, so whenever possible
8548
you should avoid using @option{-Wp} and let the driver handle the
8549
options instead.
8550
 
8551
@item -Xpreprocessor @var{option}
8552
@opindex Xpreprocessor
8553
Pass @var{option} as an option to the preprocessor.  You can use this to
8554
supply system-specific preprocessor options which GCC does not know how to
8555
recognize.
8556
 
8557
If you want to pass an option that takes an argument, you must use
8558
@option{-Xpreprocessor} twice, once for the option and once for the argument.
8559
@end table
8560
 
8561
@include cppopts.texi
8562
 
8563
@node Assembler Options
8564
@section Passing Options to the Assembler
8565
 
8566
@c prevent bad page break with this line
8567
You can pass options to the assembler.
8568
 
8569
@table @gcctabopt
8570
@item -Wa,@var{option}
8571
@opindex Wa
8572
Pass @var{option} as an option to the assembler.  If @var{option}
8573
contains commas, it is split into multiple options at the commas.
8574
 
8575
@item -Xassembler @var{option}
8576
@opindex Xassembler
8577
Pass @var{option} as an option to the assembler.  You can use this to
8578
supply system-specific assembler options which GCC does not know how to
8579
recognize.
8580
 
8581
If you want to pass an option that takes an argument, you must use
8582
@option{-Xassembler} twice, once for the option and once for the argument.
8583
 
8584
@end table
8585
 
8586
@node Link Options
8587
@section Options for Linking
8588
@cindex link options
8589
@cindex options, linking
8590
 
8591
These options come into play when the compiler links object files into
8592
an executable output file.  They are meaningless if the compiler is
8593
not doing a link step.
8594
 
8595
@table @gcctabopt
8596
@cindex file names
8597
@item @var{object-file-name}
8598
A file name that does not end in a special recognized suffix is
8599
considered to name an object file or library.  (Object files are
8600
distinguished from libraries by the linker according to the file
8601
contents.)  If linking is done, these object files are used as input
8602
to the linker.
8603
 
8604
@item -c
8605
@itemx -S
8606
@itemx -E
8607
@opindex c
8608
@opindex S
8609
@opindex E
8610
If any of these options is used, then the linker is not run, and
8611
object file names should not be used as arguments.  @xref{Overall
8612
Options}.
8613
 
8614
@cindex Libraries
8615
@item -l@var{library}
8616
@itemx -l @var{library}
8617
@opindex l
8618
Search the library named @var{library} when linking.  (The second
8619
alternative with the library as a separate argument is only for
8620
POSIX compliance and is not recommended.)
8621
 
8622
It makes a difference where in the command you write this option; the
8623
linker searches and processes libraries and object files in the order they
8624
are specified.  Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
8625
after file @file{foo.o} but before @file{bar.o}.  If @file{bar.o} refers
8626
to functions in @samp{z}, those functions may not be loaded.
8627
 
8628
The linker searches a standard list of directories for the library,
8629
which is actually a file named @file{lib@var{library}.a}.  The linker
8630
then uses this file as if it had been specified precisely by name.
8631
 
8632
The directories searched include several standard system directories
8633
plus any that you specify with @option{-L}.
8634
 
8635
Normally the files found this way are library files---archive files
8636
whose members are object files.  The linker handles an archive file by
8637
scanning through it for members which define symbols that have so far
8638
been referenced but not defined.  But if the file that is found is an
8639
ordinary object file, it is linked in the usual fashion.  The only
8640
difference between using an @option{-l} option and specifying a file name
8641
is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
8642
and searches several directories.
8643
 
8644
@item -lobjc
8645
@opindex lobjc
8646
You need this special case of the @option{-l} option in order to
8647
link an Objective-C or Objective-C++ program.
8648
 
8649
@item -nostartfiles
8650
@opindex nostartfiles
8651
Do not use the standard system startup files when linking.
8652
The standard system libraries are used normally, unless @option{-nostdlib}
8653
or @option{-nodefaultlibs} is used.
8654
 
8655
@item -nodefaultlibs
8656
@opindex nodefaultlibs
8657
Do not use the standard system libraries when linking.
8658
Only the libraries you specify will be passed to the linker, options
8659
specifying linkage of the system libraries, such as @code{-static-libgcc}
8660
or @code{-shared-libgcc}, will be ignored.
8661
The standard startup files are used normally, unless @option{-nostartfiles}
8662
is used.  The compiler may generate calls to @code{memcmp},
8663
@code{memset}, @code{memcpy} and @code{memmove}.
8664
These entries are usually resolved by entries in
8665
libc.  These entry points should be supplied through some other
8666
mechanism when this option is specified.
8667
 
8668
@item -nostdlib
8669
@opindex nostdlib
8670
Do not use the standard system startup files or libraries when linking.
8671
No startup files and only the libraries you specify will be passed to
8672
the linker, options specifying linkage of the system libraries, such as
8673
@code{-static-libgcc} or @code{-shared-libgcc}, will be ignored.
8674
The compiler may generate calls to @code{memcmp}, @code{memset},
8675
@code{memcpy} and @code{memmove}.
8676
These entries are usually resolved by entries in
8677
libc.  These entry points should be supplied through some other
8678
mechanism when this option is specified.
8679
 
8680
@cindex @option{-lgcc}, use with @option{-nostdlib}
8681
@cindex @option{-nostdlib} and unresolved references
8682
@cindex unresolved references and @option{-nostdlib}
8683
@cindex @option{-lgcc}, use with @option{-nodefaultlibs}
8684
@cindex @option{-nodefaultlibs} and unresolved references
8685
@cindex unresolved references and @option{-nodefaultlibs}
8686
One of the standard libraries bypassed by @option{-nostdlib} and
8687
@option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
8688
that GCC uses to overcome shortcomings of particular machines, or special
8689
needs for some languages.
8690
(@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
8691
Collection (GCC) Internals},
8692
for more discussion of @file{libgcc.a}.)
8693
In most cases, you need @file{libgcc.a} even when you want to avoid
8694
other standard libraries.  In other words, when you specify @option{-nostdlib}
8695
or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
8696
This ensures that you have no unresolved references to internal GCC
8697
library subroutines.  (For example, @samp{__main}, used to ensure C++
8698
constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
8699
GNU Compiler Collection (GCC) Internals}.)
8700
 
8701
@item -pie
8702
@opindex pie
8703
Produce a position independent executable on targets which support it.
8704
For predictable results, you must also specify the same set of options
8705
that were used to generate code (@option{-fpie}, @option{-fPIE},
8706
or model suboptions) when you specify this option.
8707
 
8708
@item -rdynamic
8709
@opindex rdynamic
8710
Pass the flag @option{-export-dynamic} to the ELF linker, on targets
8711
that support it. This instructs the linker to add all symbols, not
8712
only used ones, to the dynamic symbol table. This option is needed
8713
for some uses of @code{dlopen} or to allow obtaining backtraces
8714
from within a program.
8715
 
8716
@item -s
8717
@opindex s
8718
Remove all symbol table and relocation information from the executable.
8719
 
8720
@item -static
8721
@opindex static
8722
On systems that support dynamic linking, this prevents linking with the shared
8723
libraries.  On other systems, this option has no effect.
8724
 
8725
@item -shared
8726
@opindex shared
8727
Produce a shared object which can then be linked with other objects to
8728
form an executable.  Not all systems support this option.  For predictable
8729
results, you must also specify the same set of options that were used to
8730
generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
8731
when you specify this option.@footnote{On some systems, @samp{gcc -shared}
8732
needs to build supplementary stub code for constructors to work.  On
8733
multi-libbed systems, @samp{gcc -shared} must select the correct support
8734
libraries to link against.  Failing to supply the correct flags may lead
8735
to subtle defects.  Supplying them in cases where they are not necessary
8736
is innocuous.}
8737
 
8738
@item -shared-libgcc
8739
@itemx -static-libgcc
8740
@opindex shared-libgcc
8741
@opindex static-libgcc
8742
On systems that provide @file{libgcc} as a shared library, these options
8743
force the use of either the shared or static version respectively.
8744
If no shared version of @file{libgcc} was built when the compiler was
8745
configured, these options have no effect.
8746
 
8747
There are several situations in which an application should use the
8748
shared @file{libgcc} instead of the static version.  The most common
8749
of these is when the application wishes to throw and catch exceptions
8750
across different shared libraries.  In that case, each of the libraries
8751
as well as the application itself should use the shared @file{libgcc}.
8752
 
8753
Therefore, the G++ and GCJ drivers automatically add
8754
@option{-shared-libgcc} whenever you build a shared library or a main
8755
executable, because C++ and Java programs typically use exceptions, so
8756
this is the right thing to do.
8757
 
8758
If, instead, you use the GCC driver to create shared libraries, you may
8759
find that they will not always be linked with the shared @file{libgcc}.
8760
If GCC finds, at its configuration time, that you have a non-GNU linker
8761
or a GNU linker that does not support option @option{--eh-frame-hdr},
8762
it will link the shared version of @file{libgcc} into shared libraries
8763
by default.  Otherwise, it will take advantage of the linker and optimize
8764
away the linking with the shared version of @file{libgcc}, linking with
8765
the static version of libgcc by default.  This allows exceptions to
8766
propagate through such shared libraries, without incurring relocation
8767
costs at library load time.
8768
 
8769
However, if a library or main executable is supposed to throw or catch
8770
exceptions, you must link it using the G++ or GCJ driver, as appropriate
8771
for the languages used in the program, or using the option
8772
@option{-shared-libgcc}, such that it is linked with the shared
8773
@file{libgcc}.
8774
 
8775
@item -static-libstdc++
8776
When the @command{g++} program is used to link a C++ program, it will
8777
normally automatically link against @option{libstdc++}.  If
8778
@file{libstdc++} is available as a shared library, and the
8779
@option{-static} option is not used, then this will link against the
8780
shared version of @file{libstdc++}.  That is normally fine.  However, it
8781
is sometimes useful to freeze the version of @file{libstdc++} used by
8782
the program without going all the way to a fully static link.  The
8783
@option{-static-libstdc++} option directs the @command{g++} driver to
8784
link @file{libstdc++} statically, without necessarily linking other
8785
libraries statically.
8786
 
8787
@item -symbolic
8788
@opindex symbolic
8789
Bind references to global symbols when building a shared object.  Warn
8790
about any unresolved references (unless overridden by the link editor
8791
option @samp{-Xlinker -z -Xlinker defs}).  Only a few systems support
8792
this option.
8793
 
8794
@item -T @var{script}
8795
@opindex T
8796
@cindex linker script
8797
Use @var{script} as the linker script.  This option is supported by most
8798
systems using the GNU linker.  On some targets, such as bare-board
8799
targets without an operating system, the @option{-T} option may be required
8800
when linking to avoid references to undefined symbols.
8801
 
8802
@item -Xlinker @var{option}
8803
@opindex Xlinker
8804
Pass @var{option} as an option to the linker.  You can use this to
8805
supply system-specific linker options which GCC does not know how to
8806
recognize.
8807
 
8808
If you want to pass an option that takes a separate argument, you must use
8809
@option{-Xlinker} twice, once for the option and once for the argument.
8810
For example, to pass @option{-assert definitions}, you must write
8811
@samp{-Xlinker -assert -Xlinker definitions}.  It does not work to write
8812
@option{-Xlinker "-assert definitions"}, because this passes the entire
8813
string as a single argument, which is not what the linker expects.
8814
 
8815
When using the GNU linker, it is usually more convenient to pass
8816
arguments to linker options using the @option{@var{option}=@var{value}}
8817
syntax than as separate arguments.  For example, you can specify
8818
@samp{-Xlinker -Map=output.map} rather than
8819
@samp{-Xlinker -Map -Xlinker output.map}.  Other linkers may not support
8820
this syntax for command-line options.
8821
 
8822
@item -Wl,@var{option}
8823
@opindex Wl
8824
Pass @var{option} as an option to the linker.  If @var{option} contains
8825
commas, it is split into multiple options at the commas.  You can use this
8826
syntax to pass an argument to the option.
8827
For example, @samp{-Wl,-Map,output.map} passes @samp{-Map output.map} to the
8828
linker.  When using the GNU linker, you can also get the same effect with
8829
@samp{-Wl,-Map=output.map}.
8830
 
8831
@item -u @var{symbol}
8832
@opindex u
8833
Pretend the symbol @var{symbol} is undefined, to force linking of
8834
library modules to define it.  You can use @option{-u} multiple times with
8835
different symbols to force loading of additional library modules.
8836
@end table
8837
 
8838
@node Directory Options
8839
@section Options for Directory Search
8840
@cindex directory options
8841
@cindex options, directory search
8842
@cindex search path
8843
 
8844
These options specify directories to search for header files, for
8845
libraries and for parts of the compiler:
8846
 
8847
@table @gcctabopt
8848
@item -I@var{dir}
8849
@opindex I
8850
Add the directory @var{dir} to the head of the list of directories to be
8851
searched for header files.  This can be used to override a system header
8852
file, substituting your own version, since these directories are
8853
searched before the system header file directories.  However, you should
8854
not use this option to add directories that contain vendor-supplied
8855
system header files (use @option{-isystem} for that).  If you use more than
8856
one @option{-I} option, the directories are scanned in left-to-right
8857
order; the standard system directories come after.
8858
 
8859
If a standard system include directory, or a directory specified with
8860
@option{-isystem}, is also specified with @option{-I}, the @option{-I}
8861
option will be ignored.  The directory will still be searched but as a
8862
system directory at its normal position in the system include chain.
8863
This is to ensure that GCC's procedure to fix buggy system headers and
8864
the ordering for the include_next directive are not inadvertently changed.
8865
If you really need to change the search order for system directories,
8866
use the @option{-nostdinc} and/or @option{-isystem} options.
8867
 
8868
@item -iquote@var{dir}
8869
@opindex iquote
8870
Add the directory @var{dir} to the head of the list of directories to
8871
be searched for header files only for the case of @samp{#include
8872
"@var{file}"}; they are not searched for @samp{#include <@var{file}>},
8873
otherwise just like @option{-I}.
8874
 
8875
@item -L@var{dir}
8876
@opindex L
8877
Add directory @var{dir} to the list of directories to be searched
8878
for @option{-l}.
8879
 
8880
@item -B@var{prefix}
8881
@opindex B
8882
This option specifies where to find the executables, libraries,
8883
include files, and data files of the compiler itself.
8884
 
8885
The compiler driver program runs one or more of the subprograms
8886
@file{cpp}, @file{cc1}, @file{as} and @file{ld}.  It tries
8887
@var{prefix} as a prefix for each program it tries to run, both with and
8888
without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
8889
 
8890
For each subprogram to be run, the compiler driver first tries the
8891
@option{-B} prefix, if any.  If that name is not found, or if @option{-B}
8892
was not specified, the driver tries two standard prefixes, which are
8893
@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}.  If neither of
8894
those results in a file name that is found, the unmodified program
8895
name is searched for using the directories specified in your
8896
@env{PATH} environment variable.
8897
 
8898
The compiler will check to see if the path provided by the @option{-B}
8899
refers to a directory, and if necessary it will add a directory
8900
separator character at the end of the path.
8901
 
8902
@option{-B} prefixes that effectively specify directory names also apply
8903
to libraries in the linker, because the compiler translates these
8904
options into @option{-L} options for the linker.  They also apply to
8905
includes files in the preprocessor, because the compiler translates these
8906
options into @option{-isystem} options for the preprocessor.  In this case,
8907
the compiler appends @samp{include} to the prefix.
8908
 
8909
The run-time support file @file{libgcc.a} can also be searched for using
8910
the @option{-B} prefix, if needed.  If it is not found there, the two
8911
standard prefixes above are tried, and that is all.  The file is left
8912
out of the link if it is not found by those means.
8913
 
8914
Another way to specify a prefix much like the @option{-B} prefix is to use
8915
the environment variable @env{GCC_EXEC_PREFIX}.  @xref{Environment
8916
Variables}.
8917
 
8918
As a special kludge, if the path provided by @option{-B} is
8919
@file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
8920
9, then it will be replaced by @file{[dir/]include}.  This is to help
8921
with boot-strapping the compiler.
8922
 
8923
@item -specs=@var{file}
8924
@opindex specs
8925
Process @var{file} after the compiler reads in the standard @file{specs}
8926
file, in order to override the defaults that the @file{gcc} driver
8927
program uses when determining what switches to pass to @file{cc1},
8928
@file{cc1plus}, @file{as}, @file{ld}, etc.  More than one
8929
@option{-specs=@var{file}} can be specified on the command line, and they
8930
are processed in order, from left to right.
8931
 
8932
@item --sysroot=@var{dir}
8933
@opindex sysroot
8934
Use @var{dir} as the logical root directory for headers and libraries.
8935
For example, if the compiler would normally search for headers in
8936
@file{/usr/include} and libraries in @file{/usr/lib}, it will instead
8937
search @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
8938
 
8939
If you use both this option and the @option{-isysroot} option, then
8940
the @option{--sysroot} option will apply to libraries, but the
8941
@option{-isysroot} option will apply to header files.
8942
 
8943
The GNU linker (beginning with version 2.16) has the necessary support
8944
for this option.  If your linker does not support this option, the
8945
header file aspect of @option{--sysroot} will still work, but the
8946
library aspect will not.
8947
 
8948
@item -I-
8949
@opindex I-
8950
This option has been deprecated.  Please use @option{-iquote} instead for
8951
@option{-I} directories before the @option{-I-} and remove the @option{-I-}.
8952
Any directories you specify with @option{-I} options before the @option{-I-}
8953
option are searched only for the case of @samp{#include "@var{file}"};
8954
they are not searched for @samp{#include <@var{file}>}.
8955
 
8956
If additional directories are specified with @option{-I} options after
8957
the @option{-I-}, these directories are searched for all @samp{#include}
8958
directives.  (Ordinarily @emph{all} @option{-I} directories are used
8959
this way.)
8960
 
8961
In addition, the @option{-I-} option inhibits the use of the current
8962
directory (where the current input file came from) as the first search
8963
directory for @samp{#include "@var{file}"}.  There is no way to
8964
override this effect of @option{-I-}.  With @option{-I.} you can specify
8965
searching the directory which was current when the compiler was
8966
invoked.  That is not exactly the same as what the preprocessor does
8967
by default, but it is often satisfactory.
8968
 
8969
@option{-I-} does not inhibit the use of the standard system directories
8970
for header files.  Thus, @option{-I-} and @option{-nostdinc} are
8971
independent.
8972
@end table
8973
 
8974
@c man end
8975
 
8976
@node Spec Files
8977
@section Specifying subprocesses and the switches to pass to them
8978
@cindex Spec Files
8979
 
8980
@command{gcc} is a driver program.  It performs its job by invoking a
8981
sequence of other programs to do the work of compiling, assembling and
8982
linking.  GCC interprets its command-line parameters and uses these to
8983
deduce which programs it should invoke, and which command-line options
8984
it ought to place on their command lines.  This behavior is controlled
8985
by @dfn{spec strings}.  In most cases there is one spec string for each
8986
program that GCC can invoke, but a few programs have multiple spec
8987
strings to control their behavior.  The spec strings built into GCC can
8988
be overridden by using the @option{-specs=} command-line switch to specify
8989
a spec file.
8990
 
8991
@dfn{Spec files} are plaintext files that are used to construct spec
8992
strings.  They consist of a sequence of directives separated by blank
8993
lines.  The type of directive is determined by the first non-whitespace
8994
character on the line and it can be one of the following:
8995
 
8996
@table @code
8997
@item %@var{command}
8998
Issues a @var{command} to the spec file processor.  The commands that can
8999
appear here are:
9000
 
9001
@table @code
9002
@item %include <@var{file}>
9003
@cindex %include
9004
Search for @var{file} and insert its text at the current point in the
9005
specs file.
9006
 
9007
@item %include_noerr <@var{file}>
9008
@cindex %include_noerr
9009
Just like @samp{%include}, but do not generate an error message if the include
9010
file cannot be found.
9011
 
9012
@item %rename @var{old_name} @var{new_name}
9013
@cindex %rename
9014
Rename the spec string @var{old_name} to @var{new_name}.
9015
 
9016
@end table
9017
 
9018
@item *[@var{spec_name}]:
9019
This tells the compiler to create, override or delete the named spec
9020
string.  All lines after this directive up to the next directive or
9021
blank line are considered to be the text for the spec string.  If this
9022
results in an empty string then the spec will be deleted.  (Or, if the
9023
spec did not exist, then nothing will happened.)  Otherwise, if the spec
9024
does not currently exist a new spec will be created.  If the spec does
9025
exist then its contents will be overridden by the text of this
9026
directive, unless the first character of that text is the @samp{+}
9027
character, in which case the text will be appended to the spec.
9028
 
9029
@item [@var{suffix}]:
9030
Creates a new @samp{[@var{suffix}] spec} pair.  All lines after this directive
9031
and up to the next directive or blank line are considered to make up the
9032
spec string for the indicated suffix.  When the compiler encounters an
9033
input file with the named suffix, it will processes the spec string in
9034
order to work out how to compile that file.  For example:
9035
 
9036
@smallexample
9037
.ZZ:
9038
z-compile -input %i
9039
@end smallexample
9040
 
9041
This says that any input file whose name ends in @samp{.ZZ} should be
9042
passed to the program @samp{z-compile}, which should be invoked with the
9043
command-line switch @option{-input} and with the result of performing the
9044
@samp{%i} substitution.  (See below.)
9045
 
9046
As an alternative to providing a spec string, the text that follows a
9047
suffix directive can be one of the following:
9048
 
9049
@table @code
9050
@item @@@var{language}
9051
This says that the suffix is an alias for a known @var{language}.  This is
9052
similar to using the @option{-x} command-line switch to GCC to specify a
9053
language explicitly.  For example:
9054
 
9055
@smallexample
9056
.ZZ:
9057
@@c++
9058
@end smallexample
9059
 
9060
Says that .ZZ files are, in fact, C++ source files.
9061
 
9062
@item #@var{name}
9063
This causes an error messages saying:
9064
 
9065
@smallexample
9066
@var{name} compiler not installed on this system.
9067
@end smallexample
9068
@end table
9069
 
9070
GCC already has an extensive list of suffixes built into it.
9071
This directive will add an entry to the end of the list of suffixes, but
9072
since the list is searched from the end backwards, it is effectively
9073
possible to override earlier entries using this technique.
9074
 
9075
@end table
9076
 
9077
GCC has the following spec strings built into it.  Spec files can
9078
override these strings or create their own.  Note that individual
9079
targets can also add their own spec strings to this list.
9080
 
9081
@smallexample
9082
asm          Options to pass to the assembler
9083
asm_final    Options to pass to the assembler post-processor
9084
cpp          Options to pass to the C preprocessor
9085
cc1          Options to pass to the C compiler
9086
cc1plus      Options to pass to the C++ compiler
9087
endfile      Object files to include at the end of the link
9088
link         Options to pass to the linker
9089
lib          Libraries to include on the command line to the linker
9090
libgcc       Decides which GCC support library to pass to the linker
9091
linker       Sets the name of the linker
9092
predefines   Defines to be passed to the C preprocessor
9093
signed_char  Defines to pass to CPP to say whether @code{char} is signed
9094
             by default
9095
startfile    Object files to include at the start of the link
9096
@end smallexample
9097
 
9098
Here is a small example of a spec file:
9099
 
9100
@smallexample
9101
%rename lib                 old_lib
9102
 
9103
*lib:
9104
--start-group -lgcc -lc -leval1 --end-group %(old_lib)
9105
@end smallexample
9106
 
9107
This example renames the spec called @samp{lib} to @samp{old_lib} and
9108
then overrides the previous definition of @samp{lib} with a new one.
9109
The new definition adds in some extra command-line options before
9110
including the text of the old definition.
9111
 
9112
@dfn{Spec strings} are a list of command-line options to be passed to their
9113
corresponding program.  In addition, the spec strings can contain
9114
@samp{%}-prefixed sequences to substitute variable text or to
9115
conditionally insert text into the command line.  Using these constructs
9116
it is possible to generate quite complex command lines.
9117
 
9118
Here is a table of all defined @samp{%}-sequences for spec
9119
strings.  Note that spaces are not generated automatically around the
9120
results of expanding these sequences.  Therefore you can concatenate them
9121
together or combine them with constant text in a single argument.
9122
 
9123
@table @code
9124
@item %%
9125
Substitute one @samp{%} into the program name or argument.
9126
 
9127
@item %i
9128
Substitute the name of the input file being processed.
9129
 
9130
@item %b
9131
Substitute the basename of the input file being processed.
9132
This is the substring up to (and not including) the last period
9133
and not including the directory.
9134
 
9135
@item %B
9136
This is the same as @samp{%b}, but include the file suffix (text after
9137
the last period).
9138
 
9139
@item %d
9140
Marks the argument containing or following the @samp{%d} as a
9141
temporary file name, so that that file will be deleted if GCC exits
9142
successfully.  Unlike @samp{%g}, this contributes no text to the
9143
argument.
9144
 
9145
@item %g@var{suffix}
9146
Substitute a file name that has suffix @var{suffix} and is chosen
9147
once per compilation, and mark the argument in the same way as
9148
@samp{%d}.  To reduce exposure to denial-of-service attacks, the file
9149
name is now chosen in a way that is hard to predict even when previously
9150
chosen file names are known.  For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
9151
might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}.  @var{suffix} matches
9152
the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
9153
treated exactly as if @samp{%O} had been preprocessed.  Previously, @samp{%g}
9154
was simply substituted with a file name chosen once per compilation,
9155
without regard to any appended suffix (which was therefore treated
9156
just like ordinary text), making such attacks more likely to succeed.
9157
 
9158
@item %u@var{suffix}
9159
Like @samp{%g}, but generates a new temporary file name even if
9160
@samp{%u@var{suffix}} was already seen.
9161
 
9162
@item %U@var{suffix}
9163
Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
9164
new one if there is no such last file name.  In the absence of any
9165
@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
9166
the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
9167
would involve the generation of two distinct file names, one
9168
for each @samp{%g.s} and another for each @samp{%U.s}.  Previously, @samp{%U} was
9169
simply substituted with a file name chosen for the previous @samp{%u},
9170
without regard to any appended suffix.
9171
 
9172
@item %j@var{suffix}
9173
Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
9174
writable, and if save-temps is off; otherwise, substitute the name
9175
of a temporary file, just like @samp{%u}.  This temporary file is not
9176
meant for communication between processes, but rather as a junk
9177
disposal mechanism.
9178
 
9179
@item %|@var{suffix}
9180
@itemx %m@var{suffix}
9181
Like @samp{%g}, except if @option{-pipe} is in effect.  In that case
9182
@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
9183
all.  These are the two most common ways to instruct a program that it
9184
should read from standard input or write to standard output.  If you
9185
need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
9186
construct: see for example @file{f/lang-specs.h}.
9187
 
9188
@item %.@var{SUFFIX}
9189
Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
9190
when it is subsequently output with @samp{%*}.  @var{SUFFIX} is
9191
terminated by the next space or %.
9192
 
9193
@item %w
9194
Marks the argument containing or following the @samp{%w} as the
9195
designated output file of this compilation.  This puts the argument
9196
into the sequence of arguments that @samp{%o} will substitute later.
9197
 
9198
@item %o
9199
Substitutes the names of all the output files, with spaces
9200
automatically placed around them.  You should write spaces
9201
around the @samp{%o} as well or the results are undefined.
9202
@samp{%o} is for use in the specs for running the linker.
9203
Input files whose names have no recognized suffix are not compiled
9204
at all, but they are included among the output files, so they will
9205
be linked.
9206
 
9207
@item %O
9208
Substitutes the suffix for object files.  Note that this is
9209
handled specially when it immediately follows @samp{%g, %u, or %U},
9210
because of the need for those to form complete file names.  The
9211
handling is such that @samp{%O} is treated exactly as if it had already
9212
been substituted, except that @samp{%g, %u, and %U} do not currently
9213
support additional @var{suffix} characters following @samp{%O} as they would
9214
following, for example, @samp{.o}.
9215
 
9216
@item %p
9217
Substitutes the standard macro predefinitions for the
9218
current target machine.  Use this when running @code{cpp}.
9219
 
9220
@item %P
9221
Like @samp{%p}, but puts @samp{__} before and after the name of each
9222
predefined macro, except for macros that start with @samp{__} or with
9223
@samp{_@var{L}}, where @var{L} is an uppercase letter.  This is for ISO
9224
C@.
9225
 
9226
@item %I
9227
Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
9228
@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
9229
@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
9230
and @option{-imultilib} as necessary.
9231
 
9232
@item %s
9233
Current argument is the name of a library or startup file of some sort.
9234
Search for that file in a standard list of directories and substitute
9235
the full name found.  The current working directory is included in the
9236
list of directories scanned.
9237
 
9238
@item %T
9239
Current argument is the name of a linker script.  Search for that file
9240
in the current list of directories to scan for libraries. If the file
9241
is located insert a @option{--script} option into the command line
9242
followed by the full path name found.  If the file is not found then
9243
generate an error message.  Note: the current working directory is not
9244
searched.
9245
 
9246
@item %e@var{str}
9247
Print @var{str} as an error message.  @var{str} is terminated by a newline.
9248
Use this when inconsistent options are detected.
9249
 
9250
@item %(@var{name})
9251
Substitute the contents of spec string @var{name} at this point.
9252
 
9253
@item %[@var{name}]
9254
Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
9255
 
9256
@item %x@{@var{option}@}
9257
Accumulate an option for @samp{%X}.
9258
 
9259
@item %X
9260
Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
9261
spec string.
9262
 
9263
@item %Y
9264
Output the accumulated assembler options specified by @option{-Wa}.
9265
 
9266
@item %Z
9267
Output the accumulated preprocessor options specified by @option{-Wp}.
9268
 
9269
@item %a
9270
Process the @code{asm} spec.  This is used to compute the
9271
switches to be passed to the assembler.
9272
 
9273
@item %A
9274
Process the @code{asm_final} spec.  This is a spec string for
9275
passing switches to an assembler post-processor, if such a program is
9276
needed.
9277
 
9278
@item %l
9279
Process the @code{link} spec.  This is the spec for computing the
9280
command line passed to the linker.  Typically it will make use of the
9281
@samp{%L %G %S %D and %E} sequences.
9282
 
9283
@item %D
9284
Dump out a @option{-L} option for each directory that GCC believes might
9285
contain startup files.  If the target supports multilibs then the
9286
current multilib directory will be prepended to each of these paths.
9287
 
9288
@item %L
9289
Process the @code{lib} spec.  This is a spec string for deciding which
9290
libraries should be included on the command line to the linker.
9291
 
9292
@item %G
9293
Process the @code{libgcc} spec.  This is a spec string for deciding
9294
which GCC support library should be included on the command line to the linker.
9295
 
9296
@item %S
9297
Process the @code{startfile} spec.  This is a spec for deciding which
9298
object files should be the first ones passed to the linker.  Typically
9299
this might be a file named @file{crt0.o}.
9300
 
9301
@item %E
9302
Process the @code{endfile} spec.  This is a spec string that specifies
9303
the last object files that will be passed to the linker.
9304
 
9305
@item %C
9306
Process the @code{cpp} spec.  This is used to construct the arguments
9307
to be passed to the C preprocessor.
9308
 
9309
@item %1
9310
Process the @code{cc1} spec.  This is used to construct the options to be
9311
passed to the actual C compiler (@samp{cc1}).
9312
 
9313
@item %2
9314
Process the @code{cc1plus} spec.  This is used to construct the options to be
9315
passed to the actual C++ compiler (@samp{cc1plus}).
9316
 
9317
@item %*
9318
Substitute the variable part of a matched option.  See below.
9319
Note that each comma in the substituted string is replaced by
9320
a single space.
9321
 
9322
@item %<@code{S}
9323
Remove all occurrences of @code{-S} from the command line.  Note---this
9324
command is position dependent.  @samp{%} commands in the spec string
9325
before this one will see @code{-S}, @samp{%} commands in the spec string
9326
after this one will not.
9327
 
9328
@item %:@var{function}(@var{args})
9329
Call the named function @var{function}, passing it @var{args}.
9330
@var{args} is first processed as a nested spec string, then split
9331
into an argument vector in the usual fashion.  The function returns
9332
a string which is processed as if it had appeared literally as part
9333
of the current spec.
9334
 
9335
The following built-in spec functions are provided:
9336
 
9337
@table @code
9338
@item @code{getenv}
9339
The @code{getenv} spec function takes two arguments: an environment
9340
variable name and a string.  If the environment variable is not
9341
defined, a fatal error is issued.  Otherwise, the return value is the
9342
value of the environment variable concatenated with the string.  For
9343
example, if @env{TOPDIR} is defined as @file{/path/to/top}, then:
9344
 
9345
@smallexample
9346
%:getenv(TOPDIR /include)
9347
@end smallexample
9348
 
9349
expands to @file{/path/to/top/include}.
9350
 
9351
@item @code{if-exists}
9352
The @code{if-exists} spec function takes one argument, an absolute
9353
pathname to a file.  If the file exists, @code{if-exists} returns the
9354
pathname.  Here is a small example of its usage:
9355
 
9356
@smallexample
9357
*startfile:
9358
crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
9359
@end smallexample
9360
 
9361
@item @code{if-exists-else}
9362
The @code{if-exists-else} spec function is similar to the @code{if-exists}
9363
spec function, except that it takes two arguments.  The first argument is
9364
an absolute pathname to a file.  If the file exists, @code{if-exists-else}
9365
returns the pathname.  If it does not exist, it returns the second argument.
9366
This way, @code{if-exists-else} can be used to select one file or another,
9367
based on the existence of the first.  Here is a small example of its usage:
9368
 
9369
@smallexample
9370
*startfile:
9371
crt0%O%s %:if-exists(crti%O%s) \
9372
%:if-exists-else(crtbeginT%O%s crtbegin%O%s)
9373
@end smallexample
9374
 
9375
@item @code{replace-outfile}
9376
The @code{replace-outfile} spec function takes two arguments.  It looks for the
9377
first argument in the outfiles array and replaces it with the second argument.  Here
9378
is a small example of its usage:
9379
 
9380
@smallexample
9381
%@{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)@}
9382
@end smallexample
9383
 
9384
@item @code{print-asm-header}
9385
The @code{print-asm-header} function takes no arguments and simply
9386
prints a banner like:
9387
 
9388
@smallexample
9389
Assembler options
9390
=================
9391
 
9392
Use "-Wa,OPTION" to pass "OPTION" to the assembler.
9393
@end smallexample
9394
 
9395
It is used to separate compiler options from assembler options
9396
in the @option{--target-help} output.
9397
@end table
9398
 
9399
@item %@{@code{S}@}
9400
Substitutes the @code{-S} switch, if that switch was given to GCC@.
9401
If that switch was not specified, this substitutes nothing.  Note that
9402
the leading dash is omitted when specifying this option, and it is
9403
automatically inserted if the substitution is performed.  Thus the spec
9404
string @samp{%@{foo@}} would match the command-line option @option{-foo}
9405
and would output the command line option @option{-foo}.
9406
 
9407
@item %W@{@code{S}@}
9408
Like %@{@code{S}@} but mark last argument supplied within as a file to be
9409
deleted on failure.
9410
 
9411
@item %@{@code{S}*@}
9412
Substitutes all the switches specified to GCC whose names start
9413
with @code{-S}, but which also take an argument.  This is used for
9414
switches like @option{-o}, @option{-D}, @option{-I}, etc.
9415
GCC considers @option{-o foo} as being
9416
one switch whose names starts with @samp{o}.  %@{o*@} would substitute this
9417
text, including the space.  Thus two arguments would be generated.
9418
 
9419
@item %@{@code{S}*&@code{T}*@}
9420
Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
9421
(the order of @code{S} and @code{T} in the spec is not significant).
9422
There can be any number of ampersand-separated variables; for each the
9423
wild card is optional.  Useful for CPP as @samp{%@{D*&U*&A*@}}.
9424
 
9425
@item %@{@code{S}:@code{X}@}
9426
Substitutes @code{X}, if the @samp{-S} switch was given to GCC@.
9427
 
9428
@item %@{!@code{S}:@code{X}@}
9429
Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@.
9430
 
9431
@item %@{@code{S}*:@code{X}@}
9432
Substitutes @code{X} if one or more switches whose names start with
9433
@code{-S} are specified to GCC@.  Normally @code{X} is substituted only
9434
once, no matter how many such switches appeared.  However, if @code{%*}
9435
appears somewhere in @code{X}, then @code{X} will be substituted once
9436
for each matching switch, with the @code{%*} replaced by the part of
9437
that switch that matched the @code{*}.
9438
 
9439
@item %@{.@code{S}:@code{X}@}
9440
Substitutes @code{X}, if processing a file with suffix @code{S}.
9441
 
9442
@item %@{!.@code{S}:@code{X}@}
9443
Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
9444
 
9445
@item %@{,@code{S}:@code{X}@}
9446
Substitutes @code{X}, if processing a file for language @code{S}.
9447
 
9448
@item %@{!,@code{S}:@code{X}@}
9449
Substitutes @code{X}, if not processing a file for language @code{S}.
9450
 
9451
@item %@{@code{S}|@code{P}:@code{X}@}
9452
Substitutes @code{X} if either @code{-S} or @code{-P} was given to
9453
GCC@.  This may be combined with @samp{!}, @samp{.}, @samp{,}, and
9454
@code{*} sequences as well, although they have a stronger binding than
9455
the @samp{|}.  If @code{%*} appears in @code{X}, all of the
9456
alternatives must be starred, and only the first matching alternative
9457
is substituted.
9458
 
9459
For example, a spec string like this:
9460
 
9461
@smallexample
9462
%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
9463
@end smallexample
9464
 
9465
will output the following command-line options from the following input
9466
command-line options:
9467
 
9468
@smallexample
9469
fred.c        -foo -baz
9470
jim.d         -bar -boggle
9471
-d fred.c     -foo -baz -boggle
9472
-d jim.d      -bar -baz -boggle
9473
@end smallexample
9474
 
9475
@item %@{S:X; T:Y; :D@}
9476
 
9477
If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was
9478
given to GCC, substitutes @code{Y}; else substitutes @code{D}.  There can
9479
be as many clauses as you need.  This may be combined with @code{.},
9480
@code{,}, @code{!}, @code{|}, and @code{*} as needed.
9481
 
9482
 
9483
@end table
9484
 
9485
The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
9486
construct may contain other nested @samp{%} constructs or spaces, or
9487
even newlines.  They are processed as usual, as described above.
9488
Trailing white space in @code{X} is ignored.  White space may also
9489
appear anywhere on the left side of the colon in these constructs,
9490
except between @code{.} or @code{*} and the corresponding word.
9491
 
9492
The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
9493
handled specifically in these constructs.  If another value of
9494
@option{-O} or the negated form of a @option{-f}, @option{-m}, or
9495
@option{-W} switch is found later in the command line, the earlier
9496
switch value is ignored, except with @{@code{S}*@} where @code{S} is
9497
just one letter, which passes all matching options.
9498
 
9499
The character @samp{|} at the beginning of the predicate text is used to
9500
indicate that a command should be piped to the following command, but
9501
only if @option{-pipe} is specified.
9502
 
9503
It is built into GCC which switches take arguments and which do not.
9504
(You might think it would be useful to generalize this to allow each
9505
compiler's spec to say which switches take arguments.  But this cannot
9506
be done in a consistent fashion.  GCC cannot even decide which input
9507
files have been specified without knowing which switches take arguments,
9508
and it must know which input files to compile in order to tell which
9509
compilers to run).
9510
 
9511
GCC also knows implicitly that arguments starting in @option{-l} are to be
9512
treated as compiler output files, and passed to the linker in their
9513
proper position among the other output files.
9514
 
9515
@c man begin OPTIONS
9516
 
9517
@node Target Options
9518
@section Specifying Target Machine and Compiler Version
9519
@cindex target options
9520
@cindex cross compiling
9521
@cindex specifying machine version
9522
@cindex specifying compiler version and target machine
9523
@cindex compiler version, specifying
9524
@cindex target machine, specifying
9525
 
9526
The usual way to run GCC is to run the executable called @file{gcc}, or
9527
@file{<machine>-gcc} when cross-compiling, or
9528
@file{<machine>-gcc-<version>} to run a version other than the one that
9529
was installed last.  Sometimes this is inconvenient, so GCC provides
9530
options that will switch to another cross-compiler or version.
9531
 
9532
@table @gcctabopt
9533
@item -b @var{machine}
9534
@opindex b
9535
The argument @var{machine} specifies the target machine for compilation.
9536
 
9537
The value to use for @var{machine} is the same as was specified as the
9538
machine type when configuring GCC as a cross-compiler.  For
9539
example, if a cross-compiler was configured with @samp{configure
9540
arm-elf}, meaning to compile for an arm processor with elf binaries,
9541
then you would specify @option{-b arm-elf} to run that cross compiler.
9542
Because there are other options beginning with @option{-b}, the
9543
configuration must contain a hyphen, or @option{-b} alone should be one
9544
argument followed by the configuration in the next argument.
9545
 
9546
@item -V @var{version}
9547
@opindex V
9548
The argument @var{version} specifies which version of GCC to run.
9549
This is useful when multiple versions are installed.  For example,
9550
@var{version} might be @samp{4.0}, meaning to run GCC version 4.0.
9551
@end table
9552
 
9553
The @option{-V} and @option{-b} options work by running the
9554
@file{<machine>-gcc-<version>} executable, so there's no real reason to
9555
use them if you can just run that directly.
9556
 
9557
@node Submodel Options
9558
@section Hardware Models and Configurations
9559
@cindex submodel options
9560
@cindex specifying hardware config
9561
@cindex hardware models and configurations, specifying
9562
@cindex machine dependent options
9563
 
9564
Earlier we discussed the standard option @option{-b} which chooses among
9565
different installed compilers for completely different target
9566
machines, such as VAX vs.@: 68000 vs.@: 80386.
9567
 
9568
In addition, each of these target machine types can have its own
9569
special options, starting with @samp{-m}, to choose among various
9570
hardware models or configurations---for example, 68010 vs 68020,
9571
floating coprocessor or none.  A single installed version of the
9572
compiler can compile for any model or configuration, according to the
9573
options specified.
9574
 
9575
Some configurations of the compiler also support additional special
9576
options, usually for compatibility with other compilers on the same
9577
platform.
9578
 
9579
@c This list is ordered alphanumerically by subsection name.
9580
@c It should be the same order and spelling as these options are listed
9581
@c in Machine Dependent Options
9582
 
9583
@menu
9584
* ARC Options::
9585
* ARM Options::
9586
* AVR Options::
9587
* Blackfin Options::
9588
* CRIS Options::
9589
* CRX Options::
9590
* Darwin Options::
9591
* DEC Alpha Options::
9592
* DEC Alpha/VMS Options::
9593
* FR30 Options::
9594
* FRV Options::
9595
* GNU/Linux Options::
9596
* H8/300 Options::
9597
* HPPA Options::
9598
* i386 and x86-64 Options::
9599
* i386 and x86-64 Windows Options::
9600
* IA-64 Options::
9601
* IA-64/VMS Options::
9602
* LM32 Options::
9603
* M32C Options::
9604
* M32R/D Options::
9605
* M680x0 Options::
9606
* M68hc1x Options::
9607
* MCore Options::
9608
* MeP Options::
9609
* MIPS Options::
9610
* MMIX Options::
9611
* MN10300 Options::
9612
* PDP-11 Options::
9613
* picoChip Options::
9614
* PowerPC Options::
9615
* RS/6000 and PowerPC Options::
9616
* RX Options::
9617
* S/390 and zSeries Options::
9618
* Score Options::
9619
* SH Options::
9620
* SPARC Options::
9621
* SPU Options::
9622
* System V Options::
9623
* V850 Options::
9624
* VAX Options::
9625
* VxWorks Options::
9626
* x86-64 Options::
9627
* Xstormy16 Options::
9628
* Xtensa Options::
9629
* zSeries Options::
9630
@end menu
9631
 
9632
@node ARC Options
9633
@subsection ARC Options
9634
@cindex ARC Options
9635
 
9636
These options are defined for ARC implementations:
9637
 
9638
@table @gcctabopt
9639
@item -EL
9640
@opindex EL
9641
Compile code for little endian mode.  This is the default.
9642
 
9643
@item -EB
9644
@opindex EB
9645
Compile code for big endian mode.
9646
 
9647
@item -mmangle-cpu
9648
@opindex mmangle-cpu
9649
Prepend the name of the cpu to all public symbol names.
9650
In multiple-processor systems, there are many ARC variants with different
9651
instruction and register set characteristics.  This flag prevents code
9652
compiled for one cpu to be linked with code compiled for another.
9653
No facility exists for handling variants that are ``almost identical''.
9654
This is an all or nothing option.
9655
 
9656
@item -mcpu=@var{cpu}
9657
@opindex mcpu
9658
Compile code for ARC variant @var{cpu}.
9659
Which variants are supported depend on the configuration.
9660
All variants support @option{-mcpu=base}, this is the default.
9661
 
9662
@item -mtext=@var{text-section}
9663
@itemx -mdata=@var{data-section}
9664
@itemx -mrodata=@var{readonly-data-section}
9665
@opindex mtext
9666
@opindex mdata
9667
@opindex mrodata
9668
Put functions, data, and readonly data in @var{text-section},
9669
@var{data-section}, and @var{readonly-data-section} respectively
9670
by default.  This can be overridden with the @code{section} attribute.
9671
@xref{Variable Attributes}.
9672
 
9673
@item -mfix-cortex-m3-ldrd
9674
@opindex mfix-cortex-m3-ldrd
9675
Some Cortex-M3 cores can cause data corruption when @code{ldrd} instructions
9676
with overlapping destination and base registers are used.  This option avoids
9677
generating these instructions.  This option is enabled by default when
9678
@option{-mcpu=cortex-m3} is specified.
9679
 
9680
@end table
9681
 
9682
@node ARM Options
9683
@subsection ARM Options
9684
@cindex ARM options
9685
 
9686
These @samp{-m} options are defined for Advanced RISC Machines (ARM)
9687
architectures:
9688
 
9689
@table @gcctabopt
9690
@item -mabi=@var{name}
9691
@opindex mabi
9692
Generate code for the specified ABI@.  Permissible values are: @samp{apcs-gnu},
9693
@samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.
9694
 
9695
@item -mapcs-frame
9696
@opindex mapcs-frame
9697
Generate a stack frame that is compliant with the ARM Procedure Call
9698
Standard for all functions, even if this is not strictly necessary for
9699
correct execution of the code.  Specifying @option{-fomit-frame-pointer}
9700
with this option will cause the stack frames not to be generated for
9701
leaf functions.  The default is @option{-mno-apcs-frame}.
9702
 
9703
@item -mapcs
9704
@opindex mapcs
9705
This is a synonym for @option{-mapcs-frame}.
9706
 
9707
@ignore
9708
@c not currently implemented
9709
@item -mapcs-stack-check
9710
@opindex mapcs-stack-check
9711
Generate code to check the amount of stack space available upon entry to
9712
every function (that actually uses some stack space).  If there is
9713
insufficient space available then either the function
9714
@samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
9715
called, depending upon the amount of stack space required.  The run time
9716
system is required to provide these functions.  The default is
9717
@option{-mno-apcs-stack-check}, since this produces smaller code.
9718
 
9719
@c not currently implemented
9720
@item -mapcs-float
9721
@opindex mapcs-float
9722
Pass floating point arguments using the float point registers.  This is
9723
one of the variants of the APCS@.  This option is recommended if the
9724
target hardware has a floating point unit or if a lot of floating point
9725
arithmetic is going to be performed by the code.  The default is
9726
@option{-mno-apcs-float}, since integer only code is slightly increased in
9727
size if @option{-mapcs-float} is used.
9728
 
9729
@c not currently implemented
9730
@item -mapcs-reentrant
9731
@opindex mapcs-reentrant
9732
Generate reentrant, position independent code.  The default is
9733
@option{-mno-apcs-reentrant}.
9734
@end ignore
9735
 
9736
@item -mthumb-interwork
9737
@opindex mthumb-interwork
9738
Generate code which supports calling between the ARM and Thumb
9739
instruction sets.  Without this option the two instruction sets cannot
9740
be reliably used inside one program.  The default is
9741
@option{-mno-thumb-interwork}, since slightly larger code is generated
9742
when @option{-mthumb-interwork} is specified.
9743
 
9744
@item -mno-sched-prolog
9745
@opindex mno-sched-prolog
9746
Prevent the reordering of instructions in the function prolog, or the
9747
merging of those instruction with the instructions in the function's
9748
body.  This means that all functions will start with a recognizable set
9749
of instructions (or in fact one of a choice from a small set of
9750
different function prologues), and this information can be used to
9751
locate the start if functions inside an executable piece of code.  The
9752
default is @option{-msched-prolog}.
9753
 
9754
@item -mfloat-abi=@var{name}
9755
@opindex mfloat-abi
9756
Specifies which floating-point ABI to use.  Permissible values
9757
are: @samp{soft}, @samp{softfp} and @samp{hard}.
9758
 
9759
Specifying @samp{soft} causes GCC to generate output containing
9760
library calls for floating-point operations.
9761
@samp{softfp} allows the generation of code using hardware floating-point
9762
instructions, but still uses the soft-float calling conventions.
9763
@samp{hard} allows generation of floating-point instructions
9764
and uses FPU-specific calling conventions.
9765
 
9766
The default depends on the specific target configuration.  Note that
9767
the hard-float and soft-float ABIs are not link-compatible; you must
9768
compile your entire program with the same ABI, and link with a
9769
compatible set of libraries.
9770
 
9771
@item -mhard-float
9772
@opindex mhard-float
9773
Equivalent to @option{-mfloat-abi=hard}.
9774
 
9775
@item -msoft-float
9776
@opindex msoft-float
9777
Equivalent to @option{-mfloat-abi=soft}.
9778
 
9779
@item -mlittle-endian
9780
@opindex mlittle-endian
9781
Generate code for a processor running in little-endian mode.  This is
9782
the default for all standard configurations.
9783
 
9784
@item -mbig-endian
9785
@opindex mbig-endian
9786
Generate code for a processor running in big-endian mode; the default is
9787
to compile code for a little-endian processor.
9788
 
9789
@item -mwords-little-endian
9790
@opindex mwords-little-endian
9791
This option only applies when generating code for big-endian processors.
9792
Generate code for a little-endian word order but a big-endian byte
9793
order.  That is, a byte order of the form @samp{32107654}.  Note: this
9794
option should only be used if you require compatibility with code for
9795
big-endian ARM processors generated by versions of the compiler prior to
9796
2.8.
9797
 
9798
@item -mcpu=@var{name}
9799
@opindex mcpu
9800
This specifies the name of the target ARM processor.  GCC uses this name
9801
to determine what kind of instructions it can emit when generating
9802
assembly code.  Permissible names are: @samp{arm2}, @samp{arm250},
9803
@samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
9804
@samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
9805
@samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
9806
@samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
9807
@samp{arm720},
9808
@samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},
9809
@samp{arm710t}, @samp{arm720t}, @samp{arm740t},
9810
@samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
9811
@samp{strongarm1110},
9812
@samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
9813
@samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},
9814
@samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},
9815
@samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},
9816
@samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
9817
@samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
9818
@samp{arm1156t2-s}, @samp{arm1156t2f-s}, @samp{arm1176jz-s}, @samp{arm1176jzf-s},
9819
@samp{cortex-a5}, @samp{cortex-a8}, @samp{cortex-a9},
9820
@samp{cortex-r4}, @samp{cortex-r4f}, @samp{cortex-m3},
9821
@samp{cortex-m1},
9822
@samp{cortex-m0},
9823
@samp{xscale}, @samp{iwmmxt}, @samp{iwmmxt2}, @samp{ep9312}.
9824
 
9825
@item -mtune=@var{name}
9826
@opindex mtune
9827
This option is very similar to the @option{-mcpu=} option, except that
9828
instead of specifying the actual target processor type, and hence
9829
restricting which instructions can be used, it specifies that GCC should
9830
tune the performance of the code as if the target were of the type
9831
specified in this option, but still choosing the instructions that it
9832
will generate based on the cpu specified by a @option{-mcpu=} option.
9833
For some ARM implementations better performance can be obtained by using
9834
this option.
9835
 
9836
@item -march=@var{name}
9837
@opindex march
9838
This specifies the name of the target ARM architecture.  GCC uses this
9839
name to determine what kind of instructions it can emit when generating
9840
assembly code.  This option can be used in conjunction with or instead
9841
of the @option{-mcpu=} option.  Permissible names are: @samp{armv2},
9842
@samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
9843
@samp{armv5}, @samp{armv5t}, @samp{armv5e}, @samp{armv5te},
9844
@samp{armv6}, @samp{armv6j},
9845
@samp{armv6t2}, @samp{armv6z}, @samp{armv6zk}, @samp{armv6-m},
9846
@samp{armv7}, @samp{armv7-a}, @samp{armv7-r}, @samp{armv7-m},
9847
@samp{iwmmxt}, @samp{iwmmxt2}, @samp{ep9312}.
9848
 
9849
@item -mfpu=@var{name}
9850
@itemx -mfpe=@var{number}
9851
@itemx -mfp=@var{number}
9852
@opindex mfpu
9853
@opindex mfpe
9854
@opindex mfp
9855
This specifies what floating point hardware (or hardware emulation) is
9856
available on the target.  Permissible names are: @samp{fpa}, @samp{fpe2},
9857
@samp{fpe3}, @samp{maverick}, @samp{vfp}, @samp{vfpv3}, @samp{vfpv3-fp16},
9858
@samp{vfpv3-d16}, @samp{vfpv3-d16-fp16}, @samp{vfpv3xd}, @samp{vfpv3xd-fp16},
9859
@samp{neon}, @samp{neon-fp16}, @samp{vfpv4}, @samp{vfpv4-d16},
9860
@samp{fpv4-sp-d16} and @samp{neon-vfpv4}.
9861
@option{-mfp} and @option{-mfpe} are synonyms for
9862
@option{-mfpu}=@samp{fpe}@var{number}, for compatibility with older versions
9863
of GCC@.
9864
 
9865
If @option{-msoft-float} is specified this specifies the format of
9866
floating point values.
9867
 
9868
@item -mfp16-format=@var{name}
9869
@opindex mfp16-format
9870
Specify the format of the @code{__fp16} half-precision floating-point type.
9871
Permissible names are @samp{none}, @samp{ieee}, and @samp{alternative};
9872
the default is @samp{none}, in which case the @code{__fp16} type is not
9873
defined.  @xref{Half-Precision}, for more information.
9874
 
9875
@item -mstructure-size-boundary=@var{n}
9876
@opindex mstructure-size-boundary
9877
The size of all structures and unions will be rounded up to a multiple
9878
of the number of bits set by this option.  Permissible values are 8, 32
9879
and 64.  The default value varies for different toolchains.  For the COFF
9880
targeted toolchain the default value is 8.  A value of 64 is only allowed
9881
if the underlying ABI supports it.
9882
 
9883
Specifying the larger number can produce faster, more efficient code, but
9884
can also increase the size of the program.  Different values are potentially
9885
incompatible.  Code compiled with one value cannot necessarily expect to
9886
work with code or libraries compiled with another value, if they exchange
9887
information using structures or unions.
9888
 
9889
@item -mabort-on-noreturn
9890
@opindex mabort-on-noreturn
9891
Generate a call to the function @code{abort} at the end of a
9892
@code{noreturn} function.  It will be executed if the function tries to
9893
return.
9894
 
9895
@item -mlong-calls
9896
@itemx -mno-long-calls
9897
@opindex mlong-calls
9898
@opindex mno-long-calls
9899
Tells the compiler to perform function calls by first loading the
9900
address of the function into a register and then performing a subroutine
9901
call on this register.  This switch is needed if the target function
9902
will lie outside of the 64 megabyte addressing range of the offset based
9903
version of subroutine call instruction.
9904
 
9905
Even if this switch is enabled, not all function calls will be turned
9906
into long calls.  The heuristic is that static functions, functions
9907
which have the @samp{short-call} attribute, functions that are inside
9908
the scope of a @samp{#pragma no_long_calls} directive and functions whose
9909
definitions have already been compiled within the current compilation
9910
unit, will not be turned into long calls.  The exception to this rule is
9911
that weak function definitions, functions with the @samp{long-call}
9912
attribute or the @samp{section} attribute, and functions that are within
9913
the scope of a @samp{#pragma long_calls} directive, will always be
9914
turned into long calls.
9915
 
9916
This feature is not enabled by default.  Specifying
9917
@option{-mno-long-calls} will restore the default behavior, as will
9918
placing the function calls within the scope of a @samp{#pragma
9919
long_calls_off} directive.  Note these switches have no effect on how
9920
the compiler generates code to handle function calls via function
9921
pointers.
9922
 
9923
@item -msingle-pic-base
9924
@opindex msingle-pic-base
9925
Treat the register used for PIC addressing as read-only, rather than
9926
loading it in the prologue for each function.  The run-time system is
9927
responsible for initializing this register with an appropriate value
9928
before execution begins.
9929
 
9930
@item -mpic-register=@var{reg}
9931
@opindex mpic-register
9932
Specify the register to be used for PIC addressing.  The default is R10
9933
unless stack-checking is enabled, when R9 is used.
9934
 
9935
@item -mcirrus-fix-invalid-insns
9936
@opindex mcirrus-fix-invalid-insns
9937
@opindex mno-cirrus-fix-invalid-insns
9938
Insert NOPs into the instruction stream to in order to work around
9939
problems with invalid Maverick instruction combinations.  This option
9940
is only valid if the @option{-mcpu=ep9312} option has been used to
9941
enable generation of instructions for the Cirrus Maverick floating
9942
point co-processor.  This option is not enabled by default, since the
9943
problem is only present in older Maverick implementations.  The default
9944
can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns}
9945
switch.
9946
 
9947
@item -mpoke-function-name
9948
@opindex mpoke-function-name
9949
Write the name of each function into the text section, directly
9950
preceding the function prologue.  The generated code is similar to this:
9951
 
9952
@smallexample
9953
     t0
9954
         .ascii "arm_poke_function_name", 0
9955
         .align
9956
     t1
9957
         .word 0xff000000 + (t1 - t0)
9958
     arm_poke_function_name
9959
         mov     ip, sp
9960
         stmfd   sp!, @{fp, ip, lr, pc@}
9961
         sub     fp, ip, #4
9962
@end smallexample
9963
 
9964
When performing a stack backtrace, code can inspect the value of
9965
@code{pc} stored at @code{fp + 0}.  If the trace function then looks at
9966
location @code{pc - 12} and the top 8 bits are set, then we know that
9967
there is a function name embedded immediately preceding this location
9968
and has length @code{((pc[-3]) & 0xff000000)}.
9969
 
9970
@item -mthumb
9971
@opindex mthumb
9972
Generate code for the Thumb instruction set.  The default is to
9973
use the 32-bit ARM instruction set.
9974
This option automatically enables either 16-bit Thumb-1 or
9975
mixed 16/32-bit Thumb-2 instructions based on the @option{-mcpu=@var{name}}
9976
and @option{-march=@var{name}} options.  This option is not passed to the
9977
assembler. If you want to force assembler files to be interpreted as Thumb code,
9978
either add a @samp{.thumb} directive to the source or pass the @option{-mthumb}
9979
option directly to the assembler by prefixing it with @option{-Wa}.
9980
 
9981
@item -mtpcs-frame
9982
@opindex mtpcs-frame
9983
Generate a stack frame that is compliant with the Thumb Procedure Call
9984
Standard for all non-leaf functions.  (A leaf function is one that does
9985
not call any other functions.)  The default is @option{-mno-tpcs-frame}.
9986
 
9987
@item -mtpcs-leaf-frame
9988
@opindex mtpcs-leaf-frame
9989
Generate a stack frame that is compliant with the Thumb Procedure Call
9990
Standard for all leaf functions.  (A leaf function is one that does
9991
not call any other functions.)  The default is @option{-mno-apcs-leaf-frame}.
9992
 
9993
@item -mcallee-super-interworking
9994
@opindex mcallee-super-interworking
9995
Gives all externally visible functions in the file being compiled an ARM
9996
instruction set header which switches to Thumb mode before executing the
9997
rest of the function.  This allows these functions to be called from
9998
non-interworking code.  This option is not valid in AAPCS configurations
9999
because interworking is enabled by default.
10000
 
10001
@item -mcaller-super-interworking
10002
@opindex mcaller-super-interworking
10003
Allows calls via function pointers (including virtual functions) to
10004
execute correctly regardless of whether the target code has been
10005
compiled for interworking or not.  There is a small overhead in the cost
10006
of executing a function pointer if this option is enabled.  This option
10007
is not valid in AAPCS configurations because interworking is enabled
10008
by default.
10009
 
10010
@item -mtp=@var{name}
10011
@opindex mtp
10012
Specify the access model for the thread local storage pointer.  The valid
10013
models are @option{soft}, which generates calls to @code{__aeabi_read_tp},
10014
@option{cp15}, which fetches the thread pointer from @code{cp15} directly
10015
(supported in the arm6k architecture), and @option{auto}, which uses the
10016
best available method for the selected processor.  The default setting is
10017
@option{auto}.
10018
 
10019
@item -mword-relocations
10020
@opindex mword-relocations
10021
Only generate absolute relocations on word sized values (i.e. R_ARM_ABS32).
10022
This is enabled by default on targets (uClinux, SymbianOS) where the runtime
10023
loader imposes this restriction, and when @option{-fpic} or @option{-fPIC}
10024
is specified.
10025
 
10026
@end table
10027
 
10028
@node AVR Options
10029
@subsection AVR Options
10030
@cindex AVR Options
10031
 
10032
These options are defined for AVR implementations:
10033
 
10034
@table @gcctabopt
10035
@item -mmcu=@var{mcu}
10036
@opindex mmcu
10037
Specify ATMEL AVR instruction set or MCU type.
10038
 
10039
Instruction set avr1 is for the minimal AVR core, not supported by the C
10040
compiler, only for assembler programs (MCU types: at90s1200, attiny10,
10041
attiny11, attiny12, attiny15, attiny28).
10042
 
10043
Instruction set avr2 (default) is for the classic AVR core with up to
10044
8K program memory space (MCU types: at90s2313, at90s2323, attiny22,
10045
at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
10046
at90c8534, at90s8535).
10047
 
10048
Instruction set avr3 is for the classic AVR core with up to 128K program
10049
memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
10050
 
10051
Instruction set avr4 is for the enhanced AVR core with up to 8K program
10052
memory space (MCU types: atmega8, atmega83, atmega85).
10053
 
10054
Instruction set avr5 is for the enhanced AVR core with up to 128K program
10055
memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
10056
atmega64, atmega128, at43usb355, at94k).
10057
 
10058
@item -mno-interrupts
10059
@opindex mno-interrupts
10060
Generated code is not compatible with hardware interrupts.
10061
Code size will be smaller.
10062
 
10063
@item -mcall-prologues
10064
@opindex mcall-prologues
10065
Functions prologues/epilogues expanded as call to appropriate
10066
subroutines.  Code size will be smaller.
10067
 
10068
@item -mtiny-stack
10069
@opindex mtiny-stack
10070
Change only the low 8 bits of the stack pointer.
10071
 
10072
@item -mint8
10073
@opindex mint8
10074
Assume int to be 8 bit integer.  This affects the sizes of all types: A
10075
char will be 1 byte, an int will be 1 byte, a long will be 2 bytes
10076
and long long will be 4 bytes.  Please note that this option does not
10077
comply to the C standards, but it will provide you with smaller code
10078
size.
10079
@end table
10080
 
10081
@node Blackfin Options
10082
@subsection Blackfin Options
10083
@cindex Blackfin Options
10084
 
10085
@table @gcctabopt
10086
@item -mcpu=@var{cpu}@r{[}-@var{sirevision}@r{]}
10087
@opindex mcpu=
10088
Specifies the name of the target Blackfin processor.  Currently, @var{cpu}
10089
can be one of @samp{bf512}, @samp{bf514}, @samp{bf516}, @samp{bf518},
10090
@samp{bf522}, @samp{bf523}, @samp{bf524}, @samp{bf525}, @samp{bf526},
10091
@samp{bf527}, @samp{bf531}, @samp{bf532}, @samp{bf533},
10092
@samp{bf534}, @samp{bf536}, @samp{bf537}, @samp{bf538}, @samp{bf539},
10093
@samp{bf542}, @samp{bf544}, @samp{bf547}, @samp{bf548}, @samp{bf549},
10094
@samp{bf542m}, @samp{bf544m}, @samp{bf547m}, @samp{bf548m}, @samp{bf549m},
10095
@samp{bf561}.
10096
The optional @var{sirevision} specifies the silicon revision of the target
10097
Blackfin processor.  Any workarounds available for the targeted silicon revision
10098
will be enabled.  If @var{sirevision} is @samp{none}, no workarounds are enabled.
10099
If @var{sirevision} is @samp{any}, all workarounds for the targeted processor
10100
will be enabled.  The @code{__SILICON_REVISION__} macro is defined to two
10101
hexadecimal digits representing the major and minor numbers in the silicon
10102
revision.  If @var{sirevision} is @samp{none}, the @code{__SILICON_REVISION__}
10103
is not defined.  If @var{sirevision} is @samp{any}, the
10104
@code{__SILICON_REVISION__} is defined to be @code{0xffff}.
10105
If this optional @var{sirevision} is not used, GCC assumes the latest known
10106
silicon revision of the targeted Blackfin processor.
10107
 
10108
Support for @samp{bf561} is incomplete.  For @samp{bf561},
10109
Only the processor macro is defined.
10110
Without this option, @samp{bf532} is used as the processor by default.
10111
The corresponding predefined processor macros for @var{cpu} is to
10112
be defined.  And for @samp{bfin-elf} toolchain, this causes the hardware BSP
10113
provided by libgloss to be linked in if @option{-msim} is not given.
10114
 
10115
@item -msim
10116
@opindex msim
10117
Specifies that the program will be run on the simulator.  This causes
10118
the simulator BSP provided by libgloss to be linked in.  This option
10119
has effect only for @samp{bfin-elf} toolchain.
10120
Certain other options, such as @option{-mid-shared-library} and
10121
@option{-mfdpic}, imply @option{-msim}.
10122
 
10123
@item -momit-leaf-frame-pointer
10124
@opindex momit-leaf-frame-pointer
10125
Don't keep the frame pointer in a register for leaf functions.  This
10126
avoids the instructions to save, set up and restore frame pointers and
10127
makes an extra register available in leaf functions.  The option
10128
@option{-fomit-frame-pointer} removes the frame pointer for all functions
10129
which might make debugging harder.
10130
 
10131
@item -mspecld-anomaly
10132
@opindex mspecld-anomaly
10133
When enabled, the compiler will ensure that the generated code does not
10134
contain speculative loads after jump instructions. If this option is used,
10135
@code{__WORKAROUND_SPECULATIVE_LOADS} is defined.
10136
 
10137
@item -mno-specld-anomaly
10138
@opindex mno-specld-anomaly
10139
Don't generate extra code to prevent speculative loads from occurring.
10140
 
10141
@item -mcsync-anomaly
10142
@opindex mcsync-anomaly
10143
When enabled, the compiler will ensure that the generated code does not
10144
contain CSYNC or SSYNC instructions too soon after conditional branches.
10145
If this option is used, @code{__WORKAROUND_SPECULATIVE_SYNCS} is defined.
10146
 
10147
@item -mno-csync-anomaly
10148
@opindex mno-csync-anomaly
10149
Don't generate extra code to prevent CSYNC or SSYNC instructions from
10150
occurring too soon after a conditional branch.
10151
 
10152
@item -mlow-64k
10153
@opindex mlow-64k
10154
When enabled, the compiler is free to take advantage of the knowledge that
10155
the entire program fits into the low 64k of memory.
10156
 
10157
@item -mno-low-64k
10158
@opindex mno-low-64k
10159
Assume that the program is arbitrarily large.  This is the default.
10160
 
10161
@item -mstack-check-l1
10162
@opindex mstack-check-l1
10163
Do stack checking using information placed into L1 scratchpad memory by the
10164
uClinux kernel.
10165
 
10166
@item -mid-shared-library
10167
@opindex mid-shared-library
10168
Generate code that supports shared libraries via the library ID method.
10169
This allows for execute in place and shared libraries in an environment
10170
without virtual memory management.  This option implies @option{-fPIC}.
10171
With a @samp{bfin-elf} target, this option implies @option{-msim}.
10172
 
10173
@item -mno-id-shared-library
10174
@opindex mno-id-shared-library
10175
Generate code that doesn't assume ID based shared libraries are being used.
10176
This is the default.
10177
 
10178
@item -mleaf-id-shared-library
10179
@opindex mleaf-id-shared-library
10180
Generate code that supports shared libraries via the library ID method,
10181
but assumes that this library or executable won't link against any other
10182
ID shared libraries.  That allows the compiler to use faster code for jumps
10183
and calls.
10184
 
10185
@item -mno-leaf-id-shared-library
10186
@opindex mno-leaf-id-shared-library
10187
Do not assume that the code being compiled won't link against any ID shared
10188
libraries.  Slower code will be generated for jump and call insns.
10189
 
10190
@item -mshared-library-id=n
10191
@opindex mshared-library-id
10192
Specified the identification number of the ID based shared library being
10193
compiled.  Specifying a value of 0 will generate more compact code, specifying
10194
other values will force the allocation of that number to the current
10195
library but is no more space or time efficient than omitting this option.
10196
 
10197
@item -msep-data
10198
@opindex msep-data
10199
Generate code that allows the data segment to be located in a different
10200
area of memory from the text segment.  This allows for execute in place in
10201
an environment without virtual memory management by eliminating relocations
10202
against the text section.
10203
 
10204
@item -mno-sep-data
10205
@opindex mno-sep-data
10206
Generate code that assumes that the data segment follows the text segment.
10207
This is the default.
10208
 
10209
@item -mlong-calls
10210
@itemx -mno-long-calls
10211
@opindex mlong-calls
10212
@opindex mno-long-calls
10213
Tells the compiler to perform function calls by first loading the
10214
address of the function into a register and then performing a subroutine
10215
call on this register.  This switch is needed if the target function
10216
will lie outside of the 24 bit addressing range of the offset based
10217
version of subroutine call instruction.
10218
 
10219
This feature is not enabled by default.  Specifying
10220
@option{-mno-long-calls} will restore the default behavior.  Note these
10221
switches have no effect on how the compiler generates code to handle
10222
function calls via function pointers.
10223
 
10224
@item -mfast-fp
10225
@opindex mfast-fp
10226
Link with the fast floating-point library. This library relaxes some of
10227
the IEEE floating-point standard's rules for checking inputs against
10228
Not-a-Number (NAN), in the interest of performance.
10229
 
10230
@item -minline-plt
10231
@opindex minline-plt
10232
Enable inlining of PLT entries in function calls to functions that are
10233
not known to bind locally.  It has no effect without @option{-mfdpic}.
10234
 
10235
@item -mmulticore
10236
@opindex mmulticore
10237
Build standalone application for multicore Blackfin processor. Proper
10238
start files and link scripts will be used to support multicore.
10239
This option defines @code{__BFIN_MULTICORE}. It can only be used with
10240
@option{-mcpu=bf561@r{[}-@var{sirevision}@r{]}}. It can be used with
10241
@option{-mcorea} or @option{-mcoreb}. If it's used without
10242
@option{-mcorea} or @option{-mcoreb}, single application/dual core
10243
programming model is used. In this model, the main function of Core B
10244
should be named as coreb_main. If it's used with @option{-mcorea} or
10245
@option{-mcoreb}, one application per core programming model is used.
10246
If this option is not used, single core application programming
10247
model is used.
10248
 
10249
@item -mcorea
10250
@opindex mcorea
10251
Build standalone application for Core A of BF561 when using
10252
one application per core programming model. Proper start files
10253
and link scripts will be used to support Core A. This option
10254
defines @code{__BFIN_COREA}. It must be used with @option{-mmulticore}.
10255
 
10256
@item -mcoreb
10257
@opindex mcoreb
10258
Build standalone application for Core B of BF561 when using
10259
one application per core programming model. Proper start files
10260
and link scripts will be used to support Core B. This option
10261
defines @code{__BFIN_COREB}. When this option is used, coreb_main
10262
should be used instead of main. It must be used with
10263
@option{-mmulticore}.
10264
 
10265
@item -msdram
10266
@opindex msdram
10267
Build standalone application for SDRAM. Proper start files and
10268
link scripts will be used to put the application into SDRAM.
10269
Loader should initialize SDRAM before loading the application
10270
into SDRAM. This option defines @code{__BFIN_SDRAM}.
10271
 
10272
@item -micplb
10273
@opindex micplb
10274
Assume that ICPLBs are enabled at runtime.  This has an effect on certain
10275
anomaly workarounds.  For Linux targets, the default is to assume ICPLBs
10276
are enabled; for standalone applications the default is off.
10277
@end table
10278
 
10279
@node CRIS Options
10280
@subsection CRIS Options
10281
@cindex CRIS Options
10282
 
10283
These options are defined specifically for the CRIS ports.
10284
 
10285
@table @gcctabopt
10286
@item -march=@var{architecture-type}
10287
@itemx -mcpu=@var{architecture-type}
10288
@opindex march
10289
@opindex mcpu
10290
Generate code for the specified architecture.  The choices for
10291
@var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
10292
respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
10293
Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
10294
@samp{v10}.
10295
 
10296
@item -mtune=@var{architecture-type}
10297
@opindex mtune
10298
Tune to @var{architecture-type} everything applicable about the generated
10299
code, except for the ABI and the set of available instructions.  The
10300
choices for @var{architecture-type} are the same as for
10301
@option{-march=@var{architecture-type}}.
10302
 
10303
@item -mmax-stack-frame=@var{n}
10304
@opindex mmax-stack-frame
10305
Warn when the stack frame of a function exceeds @var{n} bytes.
10306
 
10307
@item -metrax4
10308
@itemx -metrax100
10309
@opindex metrax4
10310
@opindex metrax100
10311
The options @option{-metrax4} and @option{-metrax100} are synonyms for
10312
@option{-march=v3} and @option{-march=v8} respectively.
10313
 
10314
@item -mmul-bug-workaround
10315
@itemx -mno-mul-bug-workaround
10316
@opindex mmul-bug-workaround
10317
@opindex mno-mul-bug-workaround
10318
Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
10319
models where it applies.  This option is active by default.
10320
 
10321
@item -mpdebug
10322
@opindex mpdebug
10323
Enable CRIS-specific verbose debug-related information in the assembly
10324
code.  This option also has the effect to turn off the @samp{#NO_APP}
10325
formatted-code indicator to the assembler at the beginning of the
10326
assembly file.
10327
 
10328
@item -mcc-init
10329
@opindex mcc-init
10330
Do not use condition-code results from previous instruction; always emit
10331
compare and test instructions before use of condition codes.
10332
 
10333
@item -mno-side-effects
10334
@opindex mno-side-effects
10335
Do not emit instructions with side-effects in addressing modes other than
10336
post-increment.
10337
 
10338
@item -mstack-align
10339
@itemx -mno-stack-align
10340
@itemx -mdata-align
10341
@itemx -mno-data-align
10342
@itemx -mconst-align
10343
@itemx -mno-const-align
10344
@opindex mstack-align
10345
@opindex mno-stack-align
10346
@opindex mdata-align
10347
@opindex mno-data-align
10348
@opindex mconst-align
10349
@opindex mno-const-align
10350
These options (no-options) arranges (eliminate arrangements) for the
10351
stack-frame, individual data and constants to be aligned for the maximum
10352
single data access size for the chosen CPU model.  The default is to
10353
arrange for 32-bit alignment.  ABI details such as structure layout are
10354
not affected by these options.
10355
 
10356
@item -m32-bit
10357
@itemx -m16-bit
10358
@itemx -m8-bit
10359
@opindex m32-bit
10360
@opindex m16-bit
10361
@opindex m8-bit
10362
Similar to the stack- data- and const-align options above, these options
10363
arrange for stack-frame, writable data and constants to all be 32-bit,
10364
16-bit or 8-bit aligned.  The default is 32-bit alignment.
10365
 
10366
@item -mno-prologue-epilogue
10367
@itemx -mprologue-epilogue
10368
@opindex mno-prologue-epilogue
10369
@opindex mprologue-epilogue
10370
With @option{-mno-prologue-epilogue}, the normal function prologue and
10371
epilogue that sets up the stack-frame are omitted and no return
10372
instructions or return sequences are generated in the code.  Use this
10373
option only together with visual inspection of the compiled code: no
10374
warnings or errors are generated when call-saved registers must be saved,
10375
or storage for local variable needs to be allocated.
10376
 
10377
@item -mno-gotplt
10378
@itemx -mgotplt
10379
@opindex mno-gotplt
10380
@opindex mgotplt
10381
With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
10382
instruction sequences that load addresses for functions from the PLT part
10383
of the GOT rather than (traditional on other architectures) calls to the
10384
PLT@.  The default is @option{-mgotplt}.
10385
 
10386
@item -melf
10387
@opindex melf
10388
Legacy no-op option only recognized with the cris-axis-elf and
10389
cris-axis-linux-gnu targets.
10390
 
10391
@item -mlinux
10392
@opindex mlinux
10393
Legacy no-op option only recognized with the cris-axis-linux-gnu target.
10394
 
10395
@item -sim
10396
@opindex sim
10397
This option, recognized for the cris-axis-elf arranges
10398
to link with input-output functions from a simulator library.  Code,
10399
initialized data and zero-initialized data are allocated consecutively.
10400
 
10401
@item -sim2
10402
@opindex sim2
10403
Like @option{-sim}, but pass linker options to locate initialized data at
10404
0x40000000 and zero-initialized data at 0x80000000.
10405
@end table
10406
 
10407
@node CRX Options
10408
@subsection CRX Options
10409
@cindex CRX Options
10410
 
10411
These options are defined specifically for the CRX ports.
10412
 
10413
@table @gcctabopt
10414
 
10415
@item -mmac
10416
@opindex mmac
10417
Enable the use of multiply-accumulate instructions. Disabled by default.
10418
 
10419
@item -mpush-args
10420
@opindex mpush-args
10421
Push instructions will be used to pass outgoing arguments when functions
10422
are called. Enabled by default.
10423
@end table
10424
 
10425
@node Darwin Options
10426
@subsection Darwin Options
10427
@cindex Darwin options
10428
 
10429
These options are defined for all architectures running the Darwin operating
10430
system.
10431
 
10432
FSF GCC on Darwin does not create ``fat'' object files; it will create
10433
an object file for the single architecture that it was built to
10434
target.  Apple's GCC on Darwin does create ``fat'' files if multiple
10435
@option{-arch} options are used; it does so by running the compiler or
10436
linker multiple times and joining the results together with
10437
@file{lipo}.
10438
 
10439
The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
10440
@samp{i686}) is determined by the flags that specify the ISA
10441
that GCC is targetting, like @option{-mcpu} or @option{-march}.  The
10442
@option{-force_cpusubtype_ALL} option can be used to override this.
10443
 
10444
The Darwin tools vary in their behavior when presented with an ISA
10445
mismatch.  The assembler, @file{as}, will only permit instructions to
10446
be used that are valid for the subtype of the file it is generating,
10447
so you cannot put 64-bit instructions in a @samp{ppc750} object file.
10448
The linker for shared libraries, @file{/usr/bin/libtool}, will fail
10449
and print an error if asked to create a shared library with a less
10450
restrictive subtype than its input files (for instance, trying to put
10451
a @samp{ppc970} object file in a @samp{ppc7400} library).  The linker
10452
for executables, @file{ld}, will quietly give the executable the most
10453
restrictive subtype of any of its input files.
10454
 
10455
@table @gcctabopt
10456
@item -F@var{dir}
10457
@opindex F
10458
Add the framework directory @var{dir} to the head of the list of
10459
directories to be searched for header files.  These directories are
10460
interleaved with those specified by @option{-I} options and are
10461
scanned in a left-to-right order.
10462
 
10463
A framework directory is a directory with frameworks in it.  A
10464
framework is a directory with a @samp{"Headers"} and/or
10465
@samp{"PrivateHeaders"} directory contained directly in it that ends
10466
in @samp{".framework"}.  The name of a framework is the name of this
10467
directory excluding the @samp{".framework"}.  Headers associated with
10468
the framework are found in one of those two directories, with
10469
@samp{"Headers"} being searched first.  A subframework is a framework
10470
directory that is in a framework's @samp{"Frameworks"} directory.
10471
Includes of subframework headers can only appear in a header of a
10472
framework that contains the subframework, or in a sibling subframework
10473
header.  Two subframeworks are siblings if they occur in the same
10474
framework.  A subframework should not have the same name as a
10475
framework, a warning will be issued if this is violated.  Currently a
10476
subframework cannot have subframeworks, in the future, the mechanism
10477
may be extended to support this.  The standard frameworks can be found
10478
in @samp{"/System/Library/Frameworks"} and
10479
@samp{"/Library/Frameworks"}.  An example include looks like
10480
@code{#include <Framework/header.h>}, where @samp{Framework} denotes
10481
the name of the framework and header.h is found in the
10482
@samp{"PrivateHeaders"} or @samp{"Headers"} directory.
10483
 
10484
@item -iframework@var{dir}
10485
@opindex iframework
10486
Like @option{-F} except the directory is a treated as a system
10487
directory.  The main difference between this @option{-iframework} and
10488
@option{-F} is that with @option{-iframework} the compiler does not
10489
warn about constructs contained within header files found via
10490
@var{dir}.  This option is valid only for the C family of languages.
10491
 
10492
@item -gused
10493
@opindex gused
10494
Emit debugging information for symbols that are used.  For STABS
10495
debugging format, this enables @option{-feliminate-unused-debug-symbols}.
10496
This is by default ON@.
10497
 
10498
@item -gfull
10499
@opindex gfull
10500
Emit debugging information for all symbols and types.
10501
 
10502
@item -mmacosx-version-min=@var{version}
10503
The earliest version of MacOS X that this executable will run on
10504
is @var{version}.  Typical values of @var{version} include @code{10.1},
10505
@code{10.2}, and @code{10.3.9}.
10506
 
10507
If the compiler was built to use the system's headers by default,
10508
then the default for this option is the system version on which the
10509
compiler is running, otherwise the default is to make choices which
10510
are compatible with as many systems and code bases as possible.
10511
 
10512
@item -mkernel
10513
@opindex mkernel
10514
Enable kernel development mode.  The @option{-mkernel} option sets
10515
@option{-static}, @option{-fno-common}, @option{-fno-cxa-atexit},
10516
@option{-fno-exceptions}, @option{-fno-non-call-exceptions},
10517
@option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where
10518
applicable.  This mode also sets @option{-mno-altivec},
10519
@option{-msoft-float}, @option{-fno-builtin} and
10520
@option{-mlong-branch} for PowerPC targets.
10521
 
10522
@item -mone-byte-bool
10523
@opindex mone-byte-bool
10524
Override the defaults for @samp{bool} so that @samp{sizeof(bool)==1}.
10525
By default @samp{sizeof(bool)} is @samp{4} when compiling for
10526
Darwin/PowerPC and @samp{1} when compiling for Darwin/x86, so this
10527
option has no effect on x86.
10528
 
10529
@strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
10530
to generate code that is not binary compatible with code generated
10531
without that switch.  Using this switch may require recompiling all
10532
other modules in a program, including system libraries.  Use this
10533
switch to conform to a non-default data model.
10534
 
10535
@item -mfix-and-continue
10536
@itemx -ffix-and-continue
10537
@itemx -findirect-data
10538
@opindex mfix-and-continue
10539
@opindex ffix-and-continue
10540
@opindex findirect-data
10541
Generate code suitable for fast turn around development.  Needed to
10542
enable gdb to dynamically load @code{.o} files into already running
10543
programs.  @option{-findirect-data} and @option{-ffix-and-continue}
10544
are provided for backwards compatibility.
10545
 
10546
@item -all_load
10547
@opindex all_load
10548
Loads all members of static archive libraries.
10549
See man ld(1) for more information.
10550
 
10551
@item -arch_errors_fatal
10552
@opindex arch_errors_fatal
10553
Cause the errors having to do with files that have the wrong architecture
10554
to be fatal.
10555
 
10556
@item -bind_at_load
10557
@opindex bind_at_load
10558
Causes the output file to be marked such that the dynamic linker will
10559
bind all undefined references when the file is loaded or launched.
10560
 
10561
@item -bundle
10562
@opindex bundle
10563
Produce a Mach-o bundle format file.
10564
See man ld(1) for more information.
10565
 
10566
@item -bundle_loader @var{executable}
10567
@opindex bundle_loader
10568
This option specifies the @var{executable} that will be loading the build
10569
output file being linked.  See man ld(1) for more information.
10570
 
10571
@item -dynamiclib
10572
@opindex dynamiclib
10573
When passed this option, GCC will produce a dynamic library instead of
10574
an executable when linking, using the Darwin @file{libtool} command.
10575
 
10576
@item -force_cpusubtype_ALL
10577
@opindex force_cpusubtype_ALL
10578
This causes GCC's output file to have the @var{ALL} subtype, instead of
10579
one controlled by the @option{-mcpu} or @option{-march} option.
10580
 
10581
@item -allowable_client  @var{client_name}
10582
@itemx -client_name
10583
@itemx -compatibility_version
10584
@itemx -current_version
10585
@itemx -dead_strip
10586
@itemx -dependency-file
10587
@itemx -dylib_file
10588
@itemx -dylinker_install_name
10589
@itemx -dynamic
10590
@itemx -exported_symbols_list
10591
@itemx -filelist
10592
@itemx -flat_namespace
10593
@itemx -force_flat_namespace
10594
@itemx -headerpad_max_install_names
10595
@itemx -image_base
10596
@itemx -init
10597
@itemx -install_name
10598
@itemx -keep_private_externs
10599
@itemx -multi_module
10600
@itemx -multiply_defined
10601
@itemx -multiply_defined_unused
10602
@itemx -noall_load
10603
@itemx -no_dead_strip_inits_and_terms
10604
@itemx -nofixprebinding
10605
@itemx -nomultidefs
10606
@itemx -noprebind
10607
@itemx -noseglinkedit
10608
@itemx -pagezero_size
10609
@itemx -prebind
10610
@itemx -prebind_all_twolevel_modules
10611
@itemx -private_bundle
10612
@itemx -read_only_relocs
10613
@itemx -sectalign
10614
@itemx -sectobjectsymbols
10615
@itemx -whyload
10616
@itemx -seg1addr
10617
@itemx -sectcreate
10618
@itemx -sectobjectsymbols
10619
@itemx -sectorder
10620
@itemx -segaddr
10621
@itemx -segs_read_only_addr
10622
@itemx -segs_read_write_addr
10623
@itemx -seg_addr_table
10624
@itemx -seg_addr_table_filename
10625
@itemx -seglinkedit
10626
@itemx -segprot
10627
@itemx -segs_read_only_addr
10628
@itemx -segs_read_write_addr
10629
@itemx -single_module
10630
@itemx -static
10631
@itemx -sub_library
10632
@itemx -sub_umbrella
10633
@itemx -twolevel_namespace
10634
@itemx -umbrella
10635
@itemx -undefined
10636
@itemx -unexported_symbols_list
10637
@itemx -weak_reference_mismatches
10638
@itemx -whatsloaded
10639
@opindex allowable_client
10640
@opindex client_name
10641
@opindex compatibility_version
10642
@opindex current_version
10643
@opindex dead_strip
10644
@opindex dependency-file
10645
@opindex dylib_file
10646
@opindex dylinker_install_name
10647
@opindex dynamic
10648
@opindex exported_symbols_list
10649
@opindex filelist
10650
@opindex flat_namespace
10651
@opindex force_flat_namespace
10652
@opindex headerpad_max_install_names
10653
@opindex image_base
10654
@opindex init
10655
@opindex install_name
10656
@opindex keep_private_externs
10657
@opindex multi_module
10658
@opindex multiply_defined
10659
@opindex multiply_defined_unused
10660
@opindex noall_load
10661
@opindex no_dead_strip_inits_and_terms
10662
@opindex nofixprebinding
10663
@opindex nomultidefs
10664
@opindex noprebind
10665
@opindex noseglinkedit
10666
@opindex pagezero_size
10667
@opindex prebind
10668
@opindex prebind_all_twolevel_modules
10669
@opindex private_bundle
10670
@opindex read_only_relocs
10671
@opindex sectalign
10672
@opindex sectobjectsymbols
10673
@opindex whyload
10674
@opindex seg1addr
10675
@opindex sectcreate
10676
@opindex sectobjectsymbols
10677
@opindex sectorder
10678
@opindex segaddr
10679
@opindex segs_read_only_addr
10680
@opindex segs_read_write_addr
10681
@opindex seg_addr_table
10682
@opindex seg_addr_table_filename
10683
@opindex seglinkedit
10684
@opindex segprot
10685
@opindex segs_read_only_addr
10686
@opindex segs_read_write_addr
10687
@opindex single_module
10688
@opindex static
10689
@opindex sub_library
10690
@opindex sub_umbrella
10691
@opindex twolevel_namespace
10692
@opindex umbrella
10693
@opindex undefined
10694
@opindex unexported_symbols_list
10695
@opindex weak_reference_mismatches
10696
@opindex whatsloaded
10697
These options are passed to the Darwin linker.  The Darwin linker man page
10698
describes them in detail.
10699
@end table
10700
 
10701
@node DEC Alpha Options
10702
@subsection DEC Alpha Options
10703
 
10704
These @samp{-m} options are defined for the DEC Alpha implementations:
10705
 
10706
@table @gcctabopt
10707
@item -mno-soft-float
10708
@itemx -msoft-float
10709
@opindex mno-soft-float
10710
@opindex msoft-float
10711
Use (do not use) the hardware floating-point instructions for
10712
floating-point operations.  When @option{-msoft-float} is specified,
10713
functions in @file{libgcc.a} will be used to perform floating-point
10714
operations.  Unless they are replaced by routines that emulate the
10715
floating-point operations, or compiled in such a way as to call such
10716
emulations routines, these routines will issue floating-point
10717
operations.   If you are compiling for an Alpha without floating-point
10718
operations, you must ensure that the library is built so as not to call
10719
them.
10720
 
10721
Note that Alpha implementations without floating-point operations are
10722
required to have floating-point registers.
10723
 
10724
@item -mfp-reg
10725
@itemx -mno-fp-regs
10726
@opindex mfp-reg
10727
@opindex mno-fp-regs
10728
Generate code that uses (does not use) the floating-point register set.
10729
@option{-mno-fp-regs} implies @option{-msoft-float}.  If the floating-point
10730
register set is not used, floating point operands are passed in integer
10731
registers as if they were integers and floating-point results are passed
10732
in @code{$0} instead of @code{$f0}.  This is a non-standard calling sequence,
10733
so any function with a floating-point argument or return value called by code
10734
compiled with @option{-mno-fp-regs} must also be compiled with that
10735
option.
10736
 
10737
A typical use of this option is building a kernel that does not use,
10738
and hence need not save and restore, any floating-point registers.
10739
 
10740
@item -mieee
10741
@opindex mieee
10742
The Alpha architecture implements floating-point hardware optimized for
10743
maximum performance.  It is mostly compliant with the IEEE floating
10744
point standard.  However, for full compliance, software assistance is
10745
required.  This option generates code fully IEEE compliant code
10746
@emph{except} that the @var{inexact-flag} is not maintained (see below).
10747
If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
10748
defined during compilation.  The resulting code is less efficient but is
10749
able to correctly support denormalized numbers and exceptional IEEE
10750
values such as not-a-number and plus/minus infinity.  Other Alpha
10751
compilers call this option @option{-ieee_with_no_inexact}.
10752
 
10753
@item -mieee-with-inexact
10754
@opindex mieee-with-inexact
10755
This is like @option{-mieee} except the generated code also maintains
10756
the IEEE @var{inexact-flag}.  Turning on this option causes the
10757
generated code to implement fully-compliant IEEE math.  In addition to
10758
@code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
10759
macro.  On some Alpha implementations the resulting code may execute
10760
significantly slower than the code generated by default.  Since there is
10761
very little code that depends on the @var{inexact-flag}, you should
10762
normally not specify this option.  Other Alpha compilers call this
10763
option @option{-ieee_with_inexact}.
10764
 
10765
@item -mfp-trap-mode=@var{trap-mode}
10766
@opindex mfp-trap-mode
10767
This option controls what floating-point related traps are enabled.
10768
Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
10769
The trap mode can be set to one of four values:
10770
 
10771
@table @samp
10772
@item n
10773
This is the default (normal) setting.  The only traps that are enabled
10774
are the ones that cannot be disabled in software (e.g., division by zero
10775
trap).
10776
 
10777
@item u
10778
In addition to the traps enabled by @samp{n}, underflow traps are enabled
10779
as well.
10780
 
10781
@item su
10782
Like @samp{u}, but the instructions are marked to be safe for software
10783
completion (see Alpha architecture manual for details).
10784
 
10785
@item sui
10786
Like @samp{su}, but inexact traps are enabled as well.
10787
@end table
10788
 
10789
@item -mfp-rounding-mode=@var{rounding-mode}
10790
@opindex mfp-rounding-mode
10791
Selects the IEEE rounding mode.  Other Alpha compilers call this option
10792
@option{-fprm @var{rounding-mode}}.  The @var{rounding-mode} can be one
10793
of:
10794
 
10795
@table @samp
10796
@item n
10797
Normal IEEE rounding mode.  Floating point numbers are rounded towards
10798
the nearest machine number or towards the even machine number in case
10799
of a tie.
10800
 
10801
@item m
10802
Round towards minus infinity.
10803
 
10804
@item c
10805
Chopped rounding mode.  Floating point numbers are rounded towards zero.
10806
 
10807
@item d
10808
Dynamic rounding mode.  A field in the floating point control register
10809
(@var{fpcr}, see Alpha architecture reference manual) controls the
10810
rounding mode in effect.  The C library initializes this register for
10811
rounding towards plus infinity.  Thus, unless your program modifies the
10812
@var{fpcr}, @samp{d} corresponds to round towards plus infinity.
10813
@end table
10814
 
10815
@item -mtrap-precision=@var{trap-precision}
10816
@opindex mtrap-precision
10817
In the Alpha architecture, floating point traps are imprecise.  This
10818
means without software assistance it is impossible to recover from a
10819
floating trap and program execution normally needs to be terminated.
10820
GCC can generate code that can assist operating system trap handlers
10821
in determining the exact location that caused a floating point trap.
10822
Depending on the requirements of an application, different levels of
10823
precisions can be selected:
10824
 
10825
@table @samp
10826
@item p
10827
Program precision.  This option is the default and means a trap handler
10828
can only identify which program caused a floating point exception.
10829
 
10830
@item f
10831
Function precision.  The trap handler can determine the function that
10832
caused a floating point exception.
10833
 
10834
@item i
10835
Instruction precision.  The trap handler can determine the exact
10836
instruction that caused a floating point exception.
10837
@end table
10838
 
10839
Other Alpha compilers provide the equivalent options called
10840
@option{-scope_safe} and @option{-resumption_safe}.
10841
 
10842
@item -mieee-conformant
10843
@opindex mieee-conformant
10844
This option marks the generated code as IEEE conformant.  You must not
10845
use this option unless you also specify @option{-mtrap-precision=i} and either
10846
@option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}.  Its only effect
10847
is to emit the line @samp{.eflag 48} in the function prologue of the
10848
generated assembly file.  Under DEC Unix, this has the effect that
10849
IEEE-conformant math library routines will be linked in.
10850
 
10851
@item -mbuild-constants
10852
@opindex mbuild-constants
10853
Normally GCC examines a 32- or 64-bit integer constant to
10854
see if it can construct it from smaller constants in two or three
10855
instructions.  If it cannot, it will output the constant as a literal and
10856
generate code to load it from the data segment at runtime.
10857
 
10858
Use this option to require GCC to construct @emph{all} integer constants
10859
using code, even if it takes more instructions (the maximum is six).
10860
 
10861
You would typically use this option to build a shared library dynamic
10862
loader.  Itself a shared library, it must relocate itself in memory
10863
before it can find the variables and constants in its own data segment.
10864
 
10865
@item -malpha-as
10866
@itemx -mgas
10867
@opindex malpha-as
10868
@opindex mgas
10869
Select whether to generate code to be assembled by the vendor-supplied
10870
assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
10871
 
10872
@item -mbwx
10873
@itemx -mno-bwx
10874
@itemx -mcix
10875
@itemx -mno-cix
10876
@itemx -mfix
10877
@itemx -mno-fix
10878
@itemx -mmax
10879
@itemx -mno-max
10880
@opindex mbwx
10881
@opindex mno-bwx
10882
@opindex mcix
10883
@opindex mno-cix
10884
@opindex mfix
10885
@opindex mno-fix
10886
@opindex mmax
10887
@opindex mno-max
10888
Indicate whether GCC should generate code to use the optional BWX,
10889
CIX, FIX and MAX instruction sets.  The default is to use the instruction
10890
sets supported by the CPU type specified via @option{-mcpu=} option or that
10891
of the CPU on which GCC was built if none was specified.
10892
 
10893
@item -mfloat-vax
10894
@itemx -mfloat-ieee
10895
@opindex mfloat-vax
10896
@opindex mfloat-ieee
10897
Generate code that uses (does not use) VAX F and G floating point
10898
arithmetic instead of IEEE single and double precision.
10899
 
10900
@item -mexplicit-relocs
10901
@itemx -mno-explicit-relocs
10902
@opindex mexplicit-relocs
10903
@opindex mno-explicit-relocs
10904
Older Alpha assemblers provided no way to generate symbol relocations
10905
except via assembler macros.  Use of these macros does not allow
10906
optimal instruction scheduling.  GNU binutils as of version 2.12
10907
supports a new syntax that allows the compiler to explicitly mark
10908
which relocations should apply to which instructions.  This option
10909
is mostly useful for debugging, as GCC detects the capabilities of
10910
the assembler when it is built and sets the default accordingly.
10911
 
10912
@item -msmall-data
10913
@itemx -mlarge-data
10914
@opindex msmall-data
10915
@opindex mlarge-data
10916
When @option{-mexplicit-relocs} is in effect, static data is
10917
accessed via @dfn{gp-relative} relocations.  When @option{-msmall-data}
10918
is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
10919
(the @code{.sdata} and @code{.sbss} sections) and are accessed via
10920
16-bit relocations off of the @code{$gp} register.  This limits the
10921
size of the small data area to 64KB, but allows the variables to be
10922
directly accessed via a single instruction.
10923
 
10924
The default is @option{-mlarge-data}.  With this option the data area
10925
is limited to just below 2GB@.  Programs that require more than 2GB of
10926
data must use @code{malloc} or @code{mmap} to allocate the data in the
10927
heap instead of in the program's data segment.
10928
 
10929
When generating code for shared libraries, @option{-fpic} implies
10930
@option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
10931
 
10932
@item -msmall-text
10933
@itemx -mlarge-text
10934
@opindex msmall-text
10935
@opindex mlarge-text
10936
When @option{-msmall-text} is used, the compiler assumes that the
10937
code of the entire program (or shared library) fits in 4MB, and is
10938
thus reachable with a branch instruction.  When @option{-msmall-data}
10939
is used, the compiler can assume that all local symbols share the
10940
same @code{$gp} value, and thus reduce the number of instructions
10941
required for a function call from 4 to 1.
10942
 
10943
The default is @option{-mlarge-text}.
10944
 
10945
@item -mcpu=@var{cpu_type}
10946
@opindex mcpu
10947
Set the instruction set and instruction scheduling parameters for
10948
machine type @var{cpu_type}.  You can specify either the @samp{EV}
10949
style name or the corresponding chip number.  GCC supports scheduling
10950
parameters for the EV4, EV5 and EV6 family of processors and will
10951
choose the default values for the instruction set from the processor
10952
you specify.  If you do not specify a processor type, GCC will default
10953
to the processor on which the compiler was built.
10954
 
10955
Supported values for @var{cpu_type} are
10956
 
10957
@table @samp
10958
@item ev4
10959
@itemx ev45
10960
@itemx 21064
10961
Schedules as an EV4 and has no instruction set extensions.
10962
 
10963
@item ev5
10964
@itemx 21164
10965
Schedules as an EV5 and has no instruction set extensions.
10966
 
10967
@item ev56
10968
@itemx 21164a
10969
Schedules as an EV5 and supports the BWX extension.
10970
 
10971
@item pca56
10972
@itemx 21164pc
10973
@itemx 21164PC
10974
Schedules as an EV5 and supports the BWX and MAX extensions.
10975
 
10976
@item ev6
10977
@itemx 21264
10978
Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
10979
 
10980
@item ev67
10981
@itemx 21264a
10982
Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
10983
@end table
10984
 
10985
Native Linux/GNU toolchains also support the value @samp{native},
10986
which selects the best architecture option for the host processor.
10987
@option{-mcpu=native} has no effect if GCC does not recognize
10988
the processor.
10989
 
10990
@item -mtune=@var{cpu_type}
10991
@opindex mtune
10992
Set only the instruction scheduling parameters for machine type
10993
@var{cpu_type}.  The instruction set is not changed.
10994
 
10995
Native Linux/GNU toolchains also support the value @samp{native},
10996
which selects the best architecture option for the host processor.
10997
@option{-mtune=native} has no effect if GCC does not recognize
10998
the processor.
10999
 
11000
@item -mmemory-latency=@var{time}
11001
@opindex mmemory-latency
11002
Sets the latency the scheduler should assume for typical memory
11003
references as seen by the application.  This number is highly
11004
dependent on the memory access patterns used by the application
11005
and the size of the external cache on the machine.
11006
 
11007
Valid options for @var{time} are
11008
 
11009
@table @samp
11010
@item @var{number}
11011
A decimal number representing clock cycles.
11012
 
11013
@item L1
11014
@itemx L2
11015
@itemx L3
11016
@itemx main
11017
The compiler contains estimates of the number of clock cycles for
11018
``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
11019
(also called Dcache, Scache, and Bcache), as well as to main memory.
11020
Note that L3 is only valid for EV5.
11021
 
11022
@end table
11023
@end table
11024
 
11025
@node DEC Alpha/VMS Options
11026
@subsection DEC Alpha/VMS Options
11027
 
11028
These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
11029
 
11030
@table @gcctabopt
11031
@item -mvms-return-codes
11032
@opindex mvms-return-codes
11033
Return VMS condition codes from main.  The default is to return POSIX
11034
style condition (e.g.@: error) codes.
11035
 
11036
@item -mdebug-main=@var{prefix}
11037
@opindex mdebug-main=@var{prefix}
11038
Flag the first routine whose name starts with @var{prefix} as the main
11039
routine for the debugger.
11040
 
11041
@item -mmalloc64
11042
@opindex mmalloc64
11043
Default to 64bit memory allocation routines.
11044
@end table
11045
 
11046
@node FR30 Options
11047
@subsection FR30 Options
11048
@cindex FR30 Options
11049
 
11050
These options are defined specifically for the FR30 port.
11051
 
11052
@table @gcctabopt
11053
 
11054
@item -msmall-model
11055
@opindex msmall-model
11056
Use the small address space model.  This can produce smaller code, but
11057
it does assume that all symbolic values and addresses will fit into a
11058
20-bit range.
11059
 
11060
@item -mno-lsim
11061
@opindex mno-lsim
11062
Assume that run-time support has been provided and so there is no need
11063
to include the simulator library (@file{libsim.a}) on the linker
11064
command line.
11065
 
11066
@end table
11067
 
11068
@node FRV Options
11069
@subsection FRV Options
11070
@cindex FRV Options
11071
 
11072
@table @gcctabopt
11073
@item -mgpr-32
11074
@opindex mgpr-32
11075
 
11076
Only use the first 32 general purpose registers.
11077
 
11078
@item -mgpr-64
11079
@opindex mgpr-64
11080
 
11081
Use all 64 general purpose registers.
11082
 
11083
@item -mfpr-32
11084
@opindex mfpr-32
11085
 
11086
Use only the first 32 floating point registers.
11087
 
11088
@item -mfpr-64
11089
@opindex mfpr-64
11090
 
11091
Use all 64 floating point registers
11092
 
11093
@item -mhard-float
11094
@opindex mhard-float
11095
 
11096
Use hardware instructions for floating point operations.
11097
 
11098
@item -msoft-float
11099
@opindex msoft-float
11100
 
11101
Use library routines for floating point operations.
11102
 
11103
@item -malloc-cc
11104
@opindex malloc-cc
11105
 
11106
Dynamically allocate condition code registers.
11107
 
11108
@item -mfixed-cc
11109
@opindex mfixed-cc
11110
 
11111
Do not try to dynamically allocate condition code registers, only
11112
use @code{icc0} and @code{fcc0}.
11113
 
11114
@item -mdword
11115
@opindex mdword
11116
 
11117
Change ABI to use double word insns.
11118
 
11119
@item -mno-dword
11120
@opindex mno-dword
11121
 
11122
Do not use double word instructions.
11123
 
11124
@item -mdouble
11125
@opindex mdouble
11126
 
11127
Use floating point double instructions.
11128
 
11129
@item -mno-double
11130
@opindex mno-double
11131
 
11132
Do not use floating point double instructions.
11133
 
11134
@item -mmedia
11135
@opindex mmedia
11136
 
11137
Use media instructions.
11138
 
11139
@item -mno-media
11140
@opindex mno-media
11141
 
11142
Do not use media instructions.
11143
 
11144
@item -mmuladd
11145
@opindex mmuladd
11146
 
11147
Use multiply and add/subtract instructions.
11148
 
11149
@item -mno-muladd
11150
@opindex mno-muladd
11151
 
11152
Do not use multiply and add/subtract instructions.
11153
 
11154
@item -mfdpic
11155
@opindex mfdpic
11156
 
11157
Select the FDPIC ABI, that uses function descriptors to represent
11158
pointers to functions.  Without any PIC/PIE-related options, it
11159
implies @option{-fPIE}.  With @option{-fpic} or @option{-fpie}, it
11160
assumes GOT entries and small data are within a 12-bit range from the
11161
GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
11162
are computed with 32 bits.
11163
With a @samp{bfin-elf} target, this option implies @option{-msim}.
11164
 
11165
@item -minline-plt
11166
@opindex minline-plt
11167
 
11168
Enable inlining of PLT entries in function calls to functions that are
11169
not known to bind locally.  It has no effect without @option{-mfdpic}.
11170
It's enabled by default if optimizing for speed and compiling for
11171
shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
11172
optimization option such as @option{-O3} or above is present in the
11173
command line.
11174
 
11175
@item -mTLS
11176
@opindex mTLS
11177
 
11178
Assume a large TLS segment when generating thread-local code.
11179
 
11180
@item -mtls
11181
@opindex mtls
11182
 
11183
Do not assume a large TLS segment when generating thread-local code.
11184
 
11185
@item -mgprel-ro
11186
@opindex mgprel-ro
11187
 
11188
Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
11189
that is known to be in read-only sections.  It's enabled by default,
11190
except for @option{-fpic} or @option{-fpie}: even though it may help
11191
make the global offset table smaller, it trades 1 instruction for 4.
11192
With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
11193
one of which may be shared by multiple symbols, and it avoids the need
11194
for a GOT entry for the referenced symbol, so it's more likely to be a
11195
win.  If it is not, @option{-mno-gprel-ro} can be used to disable it.
11196
 
11197
@item -multilib-library-pic
11198
@opindex multilib-library-pic
11199
 
11200
Link with the (library, not FD) pic libraries.  It's implied by
11201
@option{-mlibrary-pic}, as well as by @option{-fPIC} and
11202
@option{-fpic} without @option{-mfdpic}.  You should never have to use
11203
it explicitly.
11204
 
11205
@item -mlinked-fp
11206
@opindex mlinked-fp
11207
 
11208
Follow the EABI requirement of always creating a frame pointer whenever
11209
a stack frame is allocated.  This option is enabled by default and can
11210
be disabled with @option{-mno-linked-fp}.
11211
 
11212
@item -mlong-calls
11213
@opindex mlong-calls
11214
 
11215
Use indirect addressing to call functions outside the current
11216
compilation unit.  This allows the functions to be placed anywhere
11217
within the 32-bit address space.
11218
 
11219
@item -malign-labels
11220
@opindex malign-labels
11221
 
11222
Try to align labels to an 8-byte boundary by inserting nops into the
11223
previous packet.  This option only has an effect when VLIW packing
11224
is enabled.  It doesn't create new packets; it merely adds nops to
11225
existing ones.
11226
 
11227
@item -mlibrary-pic
11228
@opindex mlibrary-pic
11229
 
11230
Generate position-independent EABI code.
11231
 
11232
@item -macc-4
11233
@opindex macc-4
11234
 
11235
Use only the first four media accumulator registers.
11236
 
11237
@item -macc-8
11238
@opindex macc-8
11239
 
11240
Use all eight media accumulator registers.
11241
 
11242
@item -mpack
11243
@opindex mpack
11244
 
11245
Pack VLIW instructions.
11246
 
11247
@item -mno-pack
11248
@opindex mno-pack
11249
 
11250
Do not pack VLIW instructions.
11251
 
11252
@item -mno-eflags
11253
@opindex mno-eflags
11254
 
11255
Do not mark ABI switches in e_flags.
11256
 
11257
@item -mcond-move
11258
@opindex mcond-move
11259
 
11260
Enable the use of conditional-move instructions (default).
11261
 
11262
This switch is mainly for debugging the compiler and will likely be removed
11263
in a future version.
11264
 
11265
@item -mno-cond-move
11266
@opindex mno-cond-move
11267
 
11268
Disable the use of conditional-move instructions.
11269
 
11270
This switch is mainly for debugging the compiler and will likely be removed
11271
in a future version.
11272
 
11273
@item -mscc
11274
@opindex mscc
11275
 
11276
Enable the use of conditional set instructions (default).
11277
 
11278
This switch is mainly for debugging the compiler and will likely be removed
11279
in a future version.
11280
 
11281
@item -mno-scc
11282
@opindex mno-scc
11283
 
11284
Disable the use of conditional set instructions.
11285
 
11286
This switch is mainly for debugging the compiler and will likely be removed
11287
in a future version.
11288
 
11289
@item -mcond-exec
11290
@opindex mcond-exec
11291
 
11292
Enable the use of conditional execution (default).
11293
 
11294
This switch is mainly for debugging the compiler and will likely be removed
11295
in a future version.
11296
 
11297
@item -mno-cond-exec
11298
@opindex mno-cond-exec
11299
 
11300
Disable the use of conditional execution.
11301
 
11302
This switch is mainly for debugging the compiler and will likely be removed
11303
in a future version.
11304
 
11305
@item -mvliw-branch
11306
@opindex mvliw-branch
11307
 
11308
Run a pass to pack branches into VLIW instructions (default).
11309
 
11310
This switch is mainly for debugging the compiler and will likely be removed
11311
in a future version.
11312
 
11313
@item -mno-vliw-branch
11314
@opindex mno-vliw-branch
11315
 
11316
Do not run a pass to pack branches into VLIW instructions.
11317
 
11318
This switch is mainly for debugging the compiler and will likely be removed
11319
in a future version.
11320
 
11321
@item -mmulti-cond-exec
11322
@opindex mmulti-cond-exec
11323
 
11324
Enable optimization of @code{&&} and @code{||} in conditional execution
11325
(default).
11326
 
11327
This switch is mainly for debugging the compiler and will likely be removed
11328
in a future version.
11329
 
11330
@item -mno-multi-cond-exec
11331
@opindex mno-multi-cond-exec
11332
 
11333
Disable optimization of @code{&&} and @code{||} in conditional execution.
11334
 
11335
This switch is mainly for debugging the compiler and will likely be removed
11336
in a future version.
11337
 
11338
@item -mnested-cond-exec
11339
@opindex mnested-cond-exec
11340
 
11341
Enable nested conditional execution optimizations (default).
11342
 
11343
This switch is mainly for debugging the compiler and will likely be removed
11344
in a future version.
11345
 
11346
@item -mno-nested-cond-exec
11347
@opindex mno-nested-cond-exec
11348
 
11349
Disable nested conditional execution optimizations.
11350
 
11351
This switch is mainly for debugging the compiler and will likely be removed
11352
in a future version.
11353
 
11354
@item -moptimize-membar
11355
@opindex moptimize-membar
11356
 
11357
This switch removes redundant @code{membar} instructions from the
11358
compiler generated code.  It is enabled by default.
11359
 
11360
@item -mno-optimize-membar
11361
@opindex mno-optimize-membar
11362
 
11363
This switch disables the automatic removal of redundant @code{membar}
11364
instructions from the generated code.
11365
 
11366
@item -mtomcat-stats
11367
@opindex mtomcat-stats
11368
 
11369
Cause gas to print out tomcat statistics.
11370
 
11371
@item -mcpu=@var{cpu}
11372
@opindex mcpu
11373
 
11374
Select the processor type for which to generate code.  Possible values are
11375
@samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
11376
@samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
11377
 
11378
@end table
11379
 
11380
@node GNU/Linux Options
11381
@subsection GNU/Linux Options
11382
 
11383
These @samp{-m} options are defined for GNU/Linux targets:
11384
 
11385
@table @gcctabopt
11386
@item -mglibc
11387
@opindex mglibc
11388
Use the GNU C library instead of uClibc.  This is the default except
11389
on @samp{*-*-linux-*uclibc*} targets.
11390
 
11391
@item -muclibc
11392
@opindex muclibc
11393
Use uClibc instead of the GNU C library.  This is the default on
11394
@samp{*-*-linux-*uclibc*} targets.
11395
@end table
11396
 
11397
@node H8/300 Options
11398
@subsection H8/300 Options
11399
 
11400
These @samp{-m} options are defined for the H8/300 implementations:
11401
 
11402
@table @gcctabopt
11403
@item -mrelax
11404
@opindex mrelax
11405
Shorten some address references at link time, when possible; uses the
11406
linker option @option{-relax}.  @xref{H8/300,, @code{ld} and the H8/300,
11407
ld, Using ld}, for a fuller description.
11408
 
11409
@item -mh
11410
@opindex mh
11411
Generate code for the H8/300H@.
11412
 
11413
@item -ms
11414
@opindex ms
11415
Generate code for the H8S@.
11416
 
11417
@item -mn
11418
@opindex mn
11419
Generate code for the H8S and H8/300H in the normal mode.  This switch
11420
must be used either with @option{-mh} or @option{-ms}.
11421
 
11422
@item -ms2600
11423
@opindex ms2600
11424
Generate code for the H8S/2600.  This switch must be used with @option{-ms}.
11425
 
11426
@item -mint32
11427
@opindex mint32
11428
Make @code{int} data 32 bits by default.
11429
 
11430
@item -malign-300
11431
@opindex malign-300
11432
On the H8/300H and H8S, use the same alignment rules as for the H8/300.
11433
The default for the H8/300H and H8S is to align longs and floats on 4
11434
byte boundaries.
11435
@option{-malign-300} causes them to be aligned on 2 byte boundaries.
11436
This option has no effect on the H8/300.
11437
@end table
11438
 
11439
@node HPPA Options
11440
@subsection HPPA Options
11441
@cindex HPPA Options
11442
 
11443
These @samp{-m} options are defined for the HPPA family of computers:
11444
 
11445
@table @gcctabopt
11446
@item -march=@var{architecture-type}
11447
@opindex march
11448
Generate code for the specified architecture.  The choices for
11449
@var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
11450
1.1, and @samp{2.0} for PA 2.0 processors.  Refer to
11451
@file{/usr/lib/sched.models} on an HP-UX system to determine the proper
11452
architecture option for your machine.  Code compiled for lower numbered
11453
architectures will run on higher numbered architectures, but not the
11454
other way around.
11455
 
11456
@item -mpa-risc-1-0
11457
@itemx -mpa-risc-1-1
11458
@itemx -mpa-risc-2-0
11459
@opindex mpa-risc-1-0
11460
@opindex mpa-risc-1-1
11461
@opindex mpa-risc-2-0
11462
Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
11463
 
11464
@item -mbig-switch
11465
@opindex mbig-switch
11466
Generate code suitable for big switch tables.  Use this option only if
11467
the assembler/linker complain about out of range branches within a switch
11468
table.
11469
 
11470
@item -mjump-in-delay
11471
@opindex mjump-in-delay
11472
Fill delay slots of function calls with unconditional jump instructions
11473
by modifying the return pointer for the function call to be the target
11474
of the conditional jump.
11475
 
11476
@item -mdisable-fpregs
11477
@opindex mdisable-fpregs
11478
Prevent floating point registers from being used in any manner.  This is
11479
necessary for compiling kernels which perform lazy context switching of
11480
floating point registers.  If you use this option and attempt to perform
11481
floating point operations, the compiler will abort.
11482
 
11483
@item -mdisable-indexing
11484
@opindex mdisable-indexing
11485
Prevent the compiler from using indexing address modes.  This avoids some
11486
rather obscure problems when compiling MIG generated code under MACH@.
11487
 
11488
@item -mno-space-regs
11489
@opindex mno-space-regs
11490
Generate code that assumes the target has no space registers.  This allows
11491
GCC to generate faster indirect calls and use unscaled index address modes.
11492
 
11493
Such code is suitable for level 0 PA systems and kernels.
11494
 
11495
@item -mfast-indirect-calls
11496
@opindex mfast-indirect-calls
11497
Generate code that assumes calls never cross space boundaries.  This
11498
allows GCC to emit code which performs faster indirect calls.
11499
 
11500
This option will not work in the presence of shared libraries or nested
11501
functions.
11502
 
11503
@item -mfixed-range=@var{register-range}
11504
@opindex mfixed-range
11505
Generate code treating the given register range as fixed registers.
11506
A fixed register is one that the register allocator can not use.  This is
11507
useful when compiling kernel code.  A register range is specified as
11508
two registers separated by a dash.  Multiple register ranges can be
11509
specified separated by a comma.
11510
 
11511
@item -mlong-load-store
11512
@opindex mlong-load-store
11513
Generate 3-instruction load and store sequences as sometimes required by
11514
the HP-UX 10 linker.  This is equivalent to the @samp{+k} option to
11515
the HP compilers.
11516
 
11517
@item -mportable-runtime
11518
@opindex mportable-runtime
11519
Use the portable calling conventions proposed by HP for ELF systems.
11520
 
11521
@item -mgas
11522
@opindex mgas
11523
Enable the use of assembler directives only GAS understands.
11524
 
11525
@item -mschedule=@var{cpu-type}
11526
@opindex mschedule
11527
Schedule code according to the constraints for the machine type
11528
@var{cpu-type}.  The choices for @var{cpu-type} are @samp{700}
11529
@samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}.  Refer
11530
to @file{/usr/lib/sched.models} on an HP-UX system to determine the
11531
proper scheduling option for your machine.  The default scheduling is
11532
@samp{8000}.
11533
 
11534
@item -mlinker-opt
11535
@opindex mlinker-opt
11536
Enable the optimization pass in the HP-UX linker.  Note this makes symbolic
11537
debugging impossible.  It also triggers a bug in the HP-UX 8 and HP-UX 9
11538
linkers in which they give bogus error messages when linking some programs.
11539
 
11540
@item -msoft-float
11541
@opindex msoft-float
11542
Generate output containing library calls for floating point.
11543
@strong{Warning:} the requisite libraries are not available for all HPPA
11544
targets.  Normally the facilities of the machine's usual C compiler are
11545
used, but this cannot be done directly in cross-compilation.  You must make
11546
your own arrangements to provide suitable library functions for
11547
cross-compilation.
11548
 
11549
@option{-msoft-float} changes the calling convention in the output file;
11550
therefore, it is only useful if you compile @emph{all} of a program with
11551
this option.  In particular, you need to compile @file{libgcc.a}, the
11552
library that comes with GCC, with @option{-msoft-float} in order for
11553
this to work.
11554
 
11555
@item -msio
11556
@opindex msio
11557
Generate the predefine, @code{_SIO}, for server IO@.  The default is
11558
@option{-mwsio}.  This generates the predefines, @code{__hp9000s700},
11559
@code{__hp9000s700__} and @code{_WSIO}, for workstation IO@.  These
11560
options are available under HP-UX and HI-UX@.
11561
 
11562
@item -mgnu-ld
11563
@opindex mgnu-ld
11564
Use GNU ld specific options.  This passes @option{-shared} to ld when
11565
building a shared library.  It is the default when GCC is configured,
11566
explicitly or implicitly, with the GNU linker.  This option does not
11567
have any affect on which ld is called, it only changes what parameters
11568
are passed to that ld.  The ld that is called is determined by the
11569
@option{--with-ld} configure option, GCC's program search path, and
11570
finally by the user's @env{PATH}.  The linker used by GCC can be printed
11571
using @samp{which `gcc -print-prog-name=ld`}.  This option is only available
11572
on the 64 bit HP-UX GCC, i.e.@: configured with @samp{hppa*64*-*-hpux*}.
11573
 
11574
@item -mhp-ld
11575
@opindex mhp-ld
11576
Use HP ld specific options.  This passes @option{-b} to ld when building
11577
a shared library and passes @option{+Accept TypeMismatch} to ld on all
11578
links.  It is the default when GCC is configured, explicitly or
11579
implicitly, with the HP linker.  This option does not have any affect on
11580
which ld is called, it only changes what parameters are passed to that
11581
ld.  The ld that is called is determined by the @option{--with-ld}
11582
configure option, GCC's program search path, and finally by the user's
11583
@env{PATH}.  The linker used by GCC can be printed using @samp{which
11584
`gcc -print-prog-name=ld`}.  This option is only available on the 64 bit
11585
HP-UX GCC, i.e.@: configured with @samp{hppa*64*-*-hpux*}.
11586
 
11587
@item -mlong-calls
11588
@opindex mno-long-calls
11589
Generate code that uses long call sequences.  This ensures that a call
11590
is always able to reach linker generated stubs.  The default is to generate
11591
long calls only when the distance from the call site to the beginning
11592
of the function or translation unit, as the case may be, exceeds a
11593
predefined limit set by the branch type being used.  The limits for
11594
normal calls are 7,600,000 and 240,000 bytes, respectively for the
11595
PA 2.0 and PA 1.X architectures.  Sibcalls are always limited at
11596
240,000 bytes.
11597
 
11598
Distances are measured from the beginning of functions when using the
11599
@option{-ffunction-sections} option, or when using the @option{-mgas}
11600
and @option{-mno-portable-runtime} options together under HP-UX with
11601
the SOM linker.
11602
 
11603
It is normally not desirable to use this option as it will degrade
11604
performance.  However, it may be useful in large applications,
11605
particularly when partial linking is used to build the application.
11606
 
11607
The types of long calls used depends on the capabilities of the
11608
assembler and linker, and the type of code being generated.  The
11609
impact on systems that support long absolute calls, and long pic
11610
symbol-difference or pc-relative calls should be relatively small.
11611
However, an indirect call is used on 32-bit ELF systems in pic code
11612
and it is quite long.
11613
 
11614
@item -munix=@var{unix-std}
11615
@opindex march
11616
Generate compiler predefines and select a startfile for the specified
11617
UNIX standard.  The choices for @var{unix-std} are @samp{93}, @samp{95}
11618
and @samp{98}.  @samp{93} is supported on all HP-UX versions.  @samp{95}
11619
is available on HP-UX 10.10 and later.  @samp{98} is available on HP-UX
11620
11.11 and later.  The default values are @samp{93} for HP-UX 10.00,
11621
@samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
11622
and later.
11623
 
11624
@option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
11625
@option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
11626
and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
11627
@option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
11628
@code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
11629
@code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
11630
 
11631
It is @emph{important} to note that this option changes the interfaces
11632
for various library routines.  It also affects the operational behavior
11633
of the C library.  Thus, @emph{extreme} care is needed in using this
11634
option.
11635
 
11636
Library code that is intended to operate with more than one UNIX
11637
standard must test, set and restore the variable @var{__xpg4_extended_mask}
11638
as appropriate.  Most GNU software doesn't provide this capability.
11639
 
11640
@item -nolibdld
11641
@opindex nolibdld
11642
Suppress the generation of link options to search libdld.sl when the
11643
@option{-static} option is specified on HP-UX 10 and later.
11644
 
11645
@item -static
11646
@opindex static
11647
The HP-UX implementation of setlocale in libc has a dependency on
11648
libdld.sl.  There isn't an archive version of libdld.sl.  Thus,
11649
when the @option{-static} option is specified, special link options
11650
are needed to resolve this dependency.
11651
 
11652
On HP-UX 10 and later, the GCC driver adds the necessary options to
11653
link with libdld.sl when the @option{-static} option is specified.
11654
This causes the resulting binary to be dynamic.  On the 64-bit port,
11655
the linkers generate dynamic binaries by default in any case.  The
11656
@option{-nolibdld} option can be used to prevent the GCC driver from
11657
adding these link options.
11658
 
11659
@item -threads
11660
@opindex threads
11661
Add support for multithreading with the @dfn{dce thread} library
11662
under HP-UX@.  This option sets flags for both the preprocessor and
11663
linker.
11664
@end table
11665
 
11666
@node i386 and x86-64 Options
11667
@subsection Intel 386 and AMD x86-64 Options
11668
@cindex i386 Options
11669
@cindex x86-64 Options
11670
@cindex Intel 386 Options
11671
@cindex AMD x86-64 Options
11672
 
11673
These @samp{-m} options are defined for the i386 and x86-64 family of
11674
computers:
11675
 
11676
@table @gcctabopt
11677
@item -mtune=@var{cpu-type}
11678
@opindex mtune
11679
Tune to @var{cpu-type} everything applicable about the generated code, except
11680
for the ABI and the set of available instructions.  The choices for
11681
@var{cpu-type} are:
11682
@table @emph
11683
@item generic
11684
Produce code optimized for the most common IA32/AMD64/EM64T processors.
11685
If you know the CPU on which your code will run, then you should use
11686
the corresponding @option{-mtune} option instead of
11687
@option{-mtune=generic}.  But, if you do not know exactly what CPU users
11688
of your application will have, then you should use this option.
11689
 
11690
As new processors are deployed in the marketplace, the behavior of this
11691
option will change.  Therefore, if you upgrade to a newer version of
11692
GCC, the code generated option will change to reflect the processors
11693
that were most common when that version of GCC was released.
11694
 
11695
There is no @option{-march=generic} option because @option{-march}
11696
indicates the instruction set the compiler can use, and there is no
11697
generic instruction set applicable to all processors.  In contrast,
11698
@option{-mtune} indicates the processor (or, in this case, collection of
11699
processors) for which the code is optimized.
11700
@item native
11701
This selects the CPU to tune for at compilation time by determining
11702
the processor type of the compiling machine.  Using @option{-mtune=native}
11703
will produce code optimized for the local machine under the constraints
11704
of the selected instruction set.  Using @option{-march=native} will
11705
enable all instruction subsets supported by the local machine (hence
11706
the result might not run on different machines).
11707
@item i386
11708
Original Intel's i386 CPU@.
11709
@item i486
11710
Intel's i486 CPU@.  (No scheduling is implemented for this chip.)
11711
@item i586, pentium
11712
Intel Pentium CPU with no MMX support.
11713
@item pentium-mmx
11714
Intel PentiumMMX CPU based on Pentium core with MMX instruction set support.
11715
@item pentiumpro
11716
Intel PentiumPro CPU@.
11717
@item i686
11718
Same as @code{generic}, but when used as @code{march} option, PentiumPro
11719
instruction set will be used, so the code will run on all i686 family chips.
11720
@item pentium2
11721
Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support.
11722
@item pentium3, pentium3m
11723
Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set
11724
support.
11725
@item pentium-m
11726
Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set
11727
support.  Used by Centrino notebooks.
11728
@item pentium4, pentium4m
11729
Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support.
11730
@item prescott
11731
Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction
11732
set support.
11733
@item nocona
11734
Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE,
11735
SSE2 and SSE3 instruction set support.
11736
@item core2
11737
Intel Core2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3
11738
instruction set support.
11739
@item atom
11740
Intel Atom CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3
11741
instruction set support.
11742
@item k6
11743
AMD K6 CPU with MMX instruction set support.
11744
@item k6-2, k6-3
11745
Improved versions of AMD K6 CPU with MMX and 3DNow!@: instruction set support.
11746
@item athlon, athlon-tbird
11747
AMD Athlon CPU with MMX, 3dNOW!, enhanced 3DNow!@: and SSE prefetch instructions
11748
support.
11749
@item athlon-4, athlon-xp, athlon-mp
11750
Improved AMD Athlon CPU with MMX, 3DNow!, enhanced 3DNow!@: and full SSE
11751
instruction set support.
11752
@item k8, opteron, athlon64, athlon-fx
11753
AMD K8 core based CPUs with x86-64 instruction set support.  (This supersets
11754
MMX, SSE, SSE2, 3DNow!, enhanced 3DNow!@: and 64-bit instruction set extensions.)
11755
@item k8-sse3, opteron-sse3, athlon64-sse3
11756
Improved versions of k8, opteron and athlon64 with SSE3 instruction set support.
11757
@item amdfam10, barcelona
11758
AMD Family 10h core based CPUs with x86-64 instruction set support.  (This
11759
supersets MMX, SSE, SSE2, SSE3, SSE4A, 3DNow!, enhanced 3DNow!, ABM and 64-bit
11760
instruction set extensions.)
11761
@item winchip-c6
11762
IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction
11763
set support.
11764
@item winchip2
11765
IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3DNow!@:
11766
instruction set support.
11767
@item c3
11768
Via C3 CPU with MMX and 3DNow!@: instruction set support.  (No scheduling is
11769
implemented for this chip.)
11770
@item c3-2
11771
Via C3-2 CPU with MMX and SSE instruction set support.  (No scheduling is
11772
implemented for this chip.)
11773
@item geode
11774
Embedded AMD CPU with MMX and 3DNow!@: instruction set support.
11775
@end table
11776
 
11777
While picking a specific @var{cpu-type} will schedule things appropriately
11778
for that particular chip, the compiler will not generate any code that
11779
does not run on the i386 without the @option{-march=@var{cpu-type}} option
11780
being used.
11781
 
11782
@item -march=@var{cpu-type}
11783
@opindex march
11784
Generate instructions for the machine type @var{cpu-type}.  The choices
11785
for @var{cpu-type} are the same as for @option{-mtune}.  Moreover,
11786
specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}.
11787
 
11788
@item -mcpu=@var{cpu-type}
11789
@opindex mcpu
11790
A deprecated synonym for @option{-mtune}.
11791
 
11792
@item -mfpmath=@var{unit}
11793
@opindex mfpmath
11794
Generate floating point arithmetics for selected unit @var{unit}.  The choices
11795
for @var{unit} are:
11796
 
11797
@table @samp
11798
@item 387
11799
Use the standard 387 floating point coprocessor present majority of chips and
11800
emulated otherwise.  Code compiled with this option will run almost everywhere.
11801
The temporary results are computed in 80bit precision instead of precision
11802
specified by the type resulting in slightly different results compared to most
11803
of other chips.  See @option{-ffloat-store} for more detailed description.
11804
 
11805
This is the default choice for i386 compiler.
11806
 
11807
@item sse
11808
Use scalar floating point instructions present in the SSE instruction set.
11809
This instruction set is supported by Pentium3 and newer chips, in the AMD line
11810
by Athlon-4, Athlon-xp and Athlon-mp chips.  The earlier version of SSE
11811
instruction set supports only single precision arithmetics, thus the double and
11812
extended precision arithmetics is still done using 387.  Later version, present
11813
only in Pentium4 and the future AMD x86-64 chips supports double precision
11814
arithmetics too.
11815
 
11816
For the i386 compiler, you need to use @option{-march=@var{cpu-type}}, @option{-msse}
11817
or @option{-msse2} switches to enable SSE extensions and make this option
11818
effective.  For the x86-64 compiler, these extensions are enabled by default.
11819
 
11820
The resulting code should be considerably faster in the majority of cases and avoid
11821
the numerical instability problems of 387 code, but may break some existing
11822
code that expects temporaries to be 80bit.
11823
 
11824
This is the default choice for the x86-64 compiler.
11825
 
11826
@item sse,387
11827
@itemx sse+387
11828
@itemx both
11829
Attempt to utilize both instruction sets at once.  This effectively double the
11830
amount of available registers and on chips with separate execution units for
11831
387 and SSE the execution resources too.  Use this option with care, as it is
11832
still experimental, because the GCC register allocator does not model separate
11833
functional units well resulting in instable performance.
11834
@end table
11835
 
11836
@item -masm=@var{dialect}
11837
@opindex masm=@var{dialect}
11838
Output asm instructions using selected @var{dialect}.  Supported
11839
choices are @samp{intel} or @samp{att} (the default one).  Darwin does
11840
not support @samp{intel}.
11841
 
11842
@item -mieee-fp
11843
@itemx -mno-ieee-fp
11844
@opindex mieee-fp
11845
@opindex mno-ieee-fp
11846
Control whether or not the compiler uses IEEE floating point
11847
comparisons.  These handle correctly the case where the result of a
11848
comparison is unordered.
11849
 
11850
@item -msoft-float
11851
@opindex msoft-float
11852
Generate output containing library calls for floating point.
11853
@strong{Warning:} the requisite libraries are not part of GCC@.
11854
Normally the facilities of the machine's usual C compiler are used, but
11855
this can't be done directly in cross-compilation.  You must make your
11856
own arrangements to provide suitable library functions for
11857
cross-compilation.
11858
 
11859
On machines where a function returns floating point results in the 80387
11860
register stack, some floating point opcodes may be emitted even if
11861
@option{-msoft-float} is used.
11862
 
11863
@item -mno-fp-ret-in-387
11864
@opindex mno-fp-ret-in-387
11865
Do not use the FPU registers for return values of functions.
11866
 
11867
The usual calling convention has functions return values of types
11868
@code{float} and @code{double} in an FPU register, even if there
11869
is no FPU@.  The idea is that the operating system should emulate
11870
an FPU@.
11871
 
11872
The option @option{-mno-fp-ret-in-387} causes such values to be returned
11873
in ordinary CPU registers instead.
11874
 
11875
@item -mno-fancy-math-387
11876
@opindex mno-fancy-math-387
11877
Some 387 emulators do not support the @code{sin}, @code{cos} and
11878
@code{sqrt} instructions for the 387.  Specify this option to avoid
11879
generating those instructions.  This option is the default on FreeBSD,
11880
OpenBSD and NetBSD@.  This option is overridden when @option{-march}
11881
indicates that the target cpu will always have an FPU and so the
11882
instruction will not need emulation.  As of revision 2.6.1, these
11883
instructions are not generated unless you also use the
11884
@option{-funsafe-math-optimizations} switch.
11885
 
11886
@item -malign-double
11887
@itemx -mno-align-double
11888
@opindex malign-double
11889
@opindex mno-align-double
11890
Control whether GCC aligns @code{double}, @code{long double}, and
11891
@code{long long} variables on a two word boundary or a one word
11892
boundary.  Aligning @code{double} variables on a two word boundary will
11893
produce code that runs somewhat faster on a @samp{Pentium} at the
11894
expense of more memory.
11895
 
11896
On x86-64, @option{-malign-double} is enabled by default.
11897
 
11898
@strong{Warning:} if you use the @option{-malign-double} switch,
11899
structures containing the above types will be aligned differently than
11900
the published application binary interface specifications for the 386
11901
and will not be binary compatible with structures in code compiled
11902
without that switch.
11903
 
11904
@item -m96bit-long-double
11905
@itemx -m128bit-long-double
11906
@opindex m96bit-long-double
11907
@opindex m128bit-long-double
11908
These switches control the size of @code{long double} type.  The i386
11909
application binary interface specifies the size to be 96 bits,
11910
so @option{-m96bit-long-double} is the default in 32 bit mode.
11911
 
11912
Modern architectures (Pentium and newer) would prefer @code{long double}
11913
to be aligned to an 8 or 16 byte boundary.  In arrays or structures
11914
conforming to the ABI, this would not be possible.  So specifying a
11915
@option{-m128bit-long-double} will align @code{long double}
11916
to a 16 byte boundary by padding the @code{long double} with an additional
11917
32 bit zero.
11918
 
11919
In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
11920
its ABI specifies that @code{long double} is to be aligned on 16 byte boundary.
11921
 
11922
Notice that neither of these options enable any extra precision over the x87
11923
standard of 80 bits for a @code{long double}.
11924
 
11925
@strong{Warning:} if you override the default value for your target ABI, the
11926
structures and arrays containing @code{long double} variables will change
11927
their size as well as function calling convention for function taking
11928
@code{long double} will be modified.  Hence they will not be binary
11929
compatible with arrays or structures in code compiled without that switch.
11930
 
11931
@item -mlarge-data-threshold=@var{number}
11932
@opindex mlarge-data-threshold=@var{number}
11933
When @option{-mcmodel=medium} is specified, the data greater than
11934
@var{threshold} are placed in large data section.  This value must be the
11935
same across all object linked into the binary and defaults to 65535.
11936
 
11937
@item -mrtd
11938
@opindex mrtd
11939
Use a different function-calling convention, in which functions that
11940
take a fixed number of arguments return with the @code{ret} @var{num}
11941
instruction, which pops their arguments while returning.  This saves one
11942
instruction in the caller since there is no need to pop the arguments
11943
there.
11944
 
11945
You can specify that an individual function is called with this calling
11946
sequence with the function attribute @samp{stdcall}.  You can also
11947
override the @option{-mrtd} option by using the function attribute
11948
@samp{cdecl}.  @xref{Function Attributes}.
11949
 
11950
@strong{Warning:} this calling convention is incompatible with the one
11951
normally used on Unix, so you cannot use it if you need to call
11952
libraries compiled with the Unix compiler.
11953
 
11954
Also, you must provide function prototypes for all functions that
11955
take variable numbers of arguments (including @code{printf});
11956
otherwise incorrect code will be generated for calls to those
11957
functions.
11958
 
11959
In addition, seriously incorrect code will result if you call a
11960
function with too many arguments.  (Normally, extra arguments are
11961
harmlessly ignored.)
11962
 
11963
@item -mregparm=@var{num}
11964
@opindex mregparm
11965
Control how many registers are used to pass integer arguments.  By
11966
default, no registers are used to pass arguments, and at most 3
11967
registers can be used.  You can control this behavior for a specific
11968
function by using the function attribute @samp{regparm}.
11969
@xref{Function Attributes}.
11970
 
11971
@strong{Warning:} if you use this switch, and
11972
@var{num} is nonzero, then you must build all modules with the same
11973
value, including any libraries.  This includes the system libraries and
11974
startup modules.
11975
 
11976
@item -msseregparm
11977
@opindex msseregparm
11978
Use SSE register passing conventions for float and double arguments
11979
and return values.  You can control this behavior for a specific
11980
function by using the function attribute @samp{sseregparm}.
11981
@xref{Function Attributes}.
11982
 
11983
@strong{Warning:} if you use this switch then you must build all
11984
modules with the same value, including any libraries.  This includes
11985
the system libraries and startup modules.
11986
 
11987
@item -mpc32
11988
@itemx -mpc64
11989
@itemx -mpc80
11990
@opindex mpc32
11991
@opindex mpc64
11992
@opindex mpc80
11993
 
11994
Set 80387 floating-point precision to 32, 64 or 80 bits.  When @option{-mpc32}
11995
is specified, the significands of results of floating-point operations are
11996
rounded to 24 bits (single precision); @option{-mpc64} rounds the
11997
significands of results of floating-point operations to 53 bits (double
11998
precision) and @option{-mpc80} rounds the significands of results of
11999
floating-point operations to 64 bits (extended double precision), which is
12000
the default.  When this option is used, floating-point operations in higher
12001
precisions are not available to the programmer without setting the FPU
12002
control word explicitly.
12003
 
12004
Setting the rounding of floating-point operations to less than the default
12005
80 bits can speed some programs by 2% or more.  Note that some mathematical
12006
libraries assume that extended precision (80 bit) floating-point operations
12007
are enabled by default; routines in such libraries could suffer significant
12008
loss of accuracy, typically through so-called "catastrophic cancellation",
12009
when this option is used to set the precision to less than extended precision.
12010
 
12011
@item -mstackrealign
12012
@opindex mstackrealign
12013
Realign the stack at entry.  On the Intel x86, the @option{-mstackrealign}
12014
option will generate an alternate prologue and epilogue that realigns the
12015
runtime stack if necessary.  This supports mixing legacy codes that keep
12016
a 4-byte aligned stack with modern codes that keep a 16-byte stack for
12017
SSE compatibility.  See also the attribute @code{force_align_arg_pointer},
12018
applicable to individual functions.
12019
 
12020
@item -mpreferred-stack-boundary=@var{num}
12021
@opindex mpreferred-stack-boundary
12022
Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
12023
byte boundary.  If @option{-mpreferred-stack-boundary} is not specified,
12024
the default is 4 (16 bytes or 128 bits).
12025
 
12026
@item -mincoming-stack-boundary=@var{num}
12027
@opindex mincoming-stack-boundary
12028
Assume the incoming stack is aligned to a 2 raised to @var{num} byte
12029
boundary.  If @option{-mincoming-stack-boundary} is not specified,
12030
the one specified by @option{-mpreferred-stack-boundary} will be used.
12031
 
12032
On Pentium and PentiumPro, @code{double} and @code{long double} values
12033
should be aligned to an 8 byte boundary (see @option{-malign-double}) or
12034
suffer significant run time performance penalties.  On Pentium III, the
12035
Streaming SIMD Extension (SSE) data type @code{__m128} may not work
12036
properly if it is not 16 byte aligned.
12037
 
12038
To ensure proper alignment of this values on the stack, the stack boundary
12039
must be as aligned as that required by any value stored on the stack.
12040
Further, every function must be generated such that it keeps the stack
12041
aligned.  Thus calling a function compiled with a higher preferred
12042
stack boundary from a function compiled with a lower preferred stack
12043
boundary will most likely misalign the stack.  It is recommended that
12044
libraries that use callbacks always use the default setting.
12045
 
12046
This extra alignment does consume extra stack space, and generally
12047
increases code size.  Code that is sensitive to stack space usage, such
12048
as embedded systems and operating system kernels, may want to reduce the
12049
preferred alignment to @option{-mpreferred-stack-boundary=2}.
12050
 
12051
@item -mmmx
12052
@itemx -mno-mmx
12053
@itemx -msse
12054
@itemx -mno-sse
12055
@itemx -msse2
12056
@itemx -mno-sse2
12057
@itemx -msse3
12058
@itemx -mno-sse3
12059
@itemx -mssse3
12060
@itemx -mno-ssse3
12061
@itemx -msse4.1
12062
@itemx -mno-sse4.1
12063
@itemx -msse4.2
12064
@itemx -mno-sse4.2
12065
@itemx -msse4
12066
@itemx -mno-sse4
12067
@itemx -mavx
12068
@itemx -mno-avx
12069
@itemx -maes
12070
@itemx -mno-aes
12071
@itemx -mpclmul
12072
@itemx -mno-pclmul
12073
@itemx -msse4a
12074
@itemx -mno-sse4a
12075
@itemx -mfma4
12076
@itemx -mno-fma4
12077
@itemx -mxop
12078
@itemx -mno-xop
12079
@itemx -mlwp
12080
@itemx -mno-lwp
12081
@itemx -m3dnow
12082
@itemx -mno-3dnow
12083
@itemx -mpopcnt
12084
@itemx -mno-popcnt
12085
@itemx -mabm
12086
@itemx -mno-abm
12087
@opindex mmmx
12088
@opindex mno-mmx
12089
@opindex msse
12090
@opindex mno-sse
12091
@opindex m3dnow
12092
@opindex mno-3dnow
12093
These switches enable or disable the use of instructions in the MMX,
12094
SSE, SSE2, SSE3, SSSE3, SSE4.1, AVX, AES, PCLMUL, SSE4A, FMA4, XOP,
12095
LWP, ABM or 3DNow!@: extended instruction sets.
12096
These extensions are also available as built-in functions: see
12097
@ref{X86 Built-in Functions}, for details of the functions enabled and
12098
disabled by these switches.
12099
 
12100
To have SSE/SSE2 instructions generated automatically from floating-point
12101
code (as opposed to 387 instructions), see @option{-mfpmath=sse}.
12102
 
12103
GCC depresses SSEx instructions when @option{-mavx} is used. Instead, it
12104
generates new AVX instructions or AVX equivalence for all SSEx instructions
12105
when needed.
12106
 
12107
These options will enable GCC to use these extended instructions in
12108
generated code, even without @option{-mfpmath=sse}.  Applications which
12109
perform runtime CPU detection must compile separate files for each
12110
supported architecture, using the appropriate flags.  In particular,
12111
the file containing the CPU detection code should be compiled without
12112
these options.
12113
 
12114
@item -mfused-madd
12115
@itemx -mno-fused-madd
12116
@opindex mfused-madd
12117
@opindex mno-fused-madd
12118
Do (don't) generate code that uses the fused multiply/add or multiply/subtract
12119
instructions.  The default is to use these instructions.
12120
 
12121
@item -mcld
12122
@opindex mcld
12123
This option instructs GCC to emit a @code{cld} instruction in the prologue
12124
of functions that use string instructions.  String instructions depend on
12125
the DF flag to select between autoincrement or autodecrement mode.  While the
12126
ABI specifies the DF flag to be cleared on function entry, some operating
12127
systems violate this specification by not clearing the DF flag in their
12128
exception dispatchers.  The exception handler can be invoked with the DF flag
12129
set which leads to wrong direction mode, when string instructions are used.
12130
This option can be enabled by default on 32-bit x86 targets by configuring
12131
GCC with the @option{--enable-cld} configure option.  Generation of @code{cld}
12132
instructions can be suppressed with the @option{-mno-cld} compiler option
12133
in this case.
12134
 
12135
@item -mcx16
12136
@opindex mcx16
12137
This option will enable GCC to use CMPXCHG16B instruction in generated code.
12138
CMPXCHG16B allows for atomic operations on 128-bit double quadword (or oword)
12139
data types.  This is useful for high resolution counters that could be updated
12140
by multiple processors (or cores).  This instruction is generated as part of
12141
atomic built-in functions: see @ref{Atomic Builtins} for details.
12142
 
12143
@item -msahf
12144
@opindex msahf
12145
This option will enable GCC to use SAHF instruction in generated 64-bit code.
12146
Early Intel CPUs with Intel 64 lacked LAHF and SAHF instructions supported
12147
by AMD64 until introduction of Pentium 4 G1 step in December 2005.  LAHF and
12148
SAHF are load and store instructions, respectively, for certain status flags.
12149
In 64-bit mode, SAHF instruction is used to optimize @code{fmod}, @code{drem}
12150
or @code{remainder} built-in functions: see @ref{Other Builtins} for details.
12151
 
12152
@item -mmovbe
12153
@opindex mmovbe
12154
This option will enable GCC to use movbe instruction to implement
12155
@code{__builtin_bswap32} and @code{__builtin_bswap64}.
12156
 
12157
@item -mcrc32
12158
@opindex mcrc32
12159
This option will enable built-in functions, @code{__builtin_ia32_crc32qi},
12160
@code{__builtin_ia32_crc32hi}. @code{__builtin_ia32_crc32si} and
12161
@code{__builtin_ia32_crc32di} to generate the crc32 machine instruction.
12162
 
12163
@item -mrecip
12164
@opindex mrecip
12165
This option will enable GCC to use RCPSS and RSQRTSS instructions (and their
12166
vectorized variants RCPPS and RSQRTPS) with an additional Newton-Raphson step
12167
to increase precision instead of DIVSS and SQRTSS (and their vectorized
12168
variants) for single precision floating point arguments.  These instructions
12169
are generated only when @option{-funsafe-math-optimizations} is enabled
12170
together with @option{-finite-math-only} and @option{-fno-trapping-math}.
12171
Note that while the throughput of the sequence is higher than the throughput
12172
of the non-reciprocal instruction, the precision of the sequence can be
12173
decreased by up to 2 ulp (i.e. the inverse of 1.0 equals 0.99999994).
12174
 
12175
Note that GCC implements 1.0f/sqrtf(x) in terms of RSQRTSS (or RSQRTPS)
12176
already with @option{-ffast-math} (or the above option combination), and
12177
doesn't need @option{-mrecip}.
12178
 
12179
@item -mveclibabi=@var{type}
12180
@opindex mveclibabi
12181
Specifies the ABI type to use for vectorizing intrinsics using an
12182
external library.  Supported types are @code{svml} for the Intel short
12183
vector math library and @code{acml} for the AMD math core library style
12184
of interfacing.  GCC will currently emit calls to @code{vmldExp2},
12185
@code{vmldLn2}, @code{vmldLog102}, @code{vmldLog102}, @code{vmldPow2},
12186
@code{vmldTanh2}, @code{vmldTan2}, @code{vmldAtan2}, @code{vmldAtanh2},
12187
@code{vmldCbrt2}, @code{vmldSinh2}, @code{vmldSin2}, @code{vmldAsinh2},
12188
@code{vmldAsin2}, @code{vmldCosh2}, @code{vmldCos2}, @code{vmldAcosh2},
12189
@code{vmldAcos2}, @code{vmlsExp4}, @code{vmlsLn4}, @code{vmlsLog104},
12190
@code{vmlsLog104}, @code{vmlsPow4}, @code{vmlsTanh4}, @code{vmlsTan4},
12191
@code{vmlsAtan4}, @code{vmlsAtanh4}, @code{vmlsCbrt4}, @code{vmlsSinh4},
12192
@code{vmlsSin4}, @code{vmlsAsinh4}, @code{vmlsAsin4}, @code{vmlsCosh4},
12193
@code{vmlsCos4}, @code{vmlsAcosh4} and @code{vmlsAcos4} for corresponding
12194
function type when @option{-mveclibabi=svml} is used and @code{__vrd2_sin},
12195
@code{__vrd2_cos}, @code{__vrd2_exp}, @code{__vrd2_log}, @code{__vrd2_log2},
12196
@code{__vrd2_log10}, @code{__vrs4_sinf}, @code{__vrs4_cosf},
12197
@code{__vrs4_expf}, @code{__vrs4_logf}, @code{__vrs4_log2f},
12198
@code{__vrs4_log10f} and @code{__vrs4_powf} for corresponding function type
12199
when @option{-mveclibabi=acml} is used. Both @option{-ftree-vectorize} and
12200
@option{-funsafe-math-optimizations} have to be enabled. A SVML or ACML ABI
12201
compatible library will have to be specified at link time.
12202
 
12203
@item -mabi=@var{name}
12204
@opindex mabi
12205
Generate code for the specified calling convention.  Permissible values
12206
are: @samp{sysv} for the ABI used on GNU/Linux and other systems and
12207
@samp{ms} for the Microsoft ABI.  The default is to use the Microsoft
12208
ABI when targeting Windows.  On all other systems, the default is the
12209
SYSV ABI.  You can control this behavior for a specific function by
12210
using the function attribute @samp{ms_abi}/@samp{sysv_abi}.
12211
@xref{Function Attributes}.
12212
 
12213
@item -mpush-args
12214
@itemx -mno-push-args
12215
@opindex mpush-args
12216
@opindex mno-push-args
12217
Use PUSH operations to store outgoing parameters.  This method is shorter
12218
and usually equally fast as method using SUB/MOV operations and is enabled
12219
by default.  In some cases disabling it may improve performance because of
12220
improved scheduling and reduced dependencies.
12221
 
12222
@item -maccumulate-outgoing-args
12223
@opindex maccumulate-outgoing-args
12224
If enabled, the maximum amount of space required for outgoing arguments will be
12225
computed in the function prologue.  This is faster on most modern CPUs
12226
because of reduced dependencies, improved scheduling and reduced stack usage
12227
when preferred stack boundary is not equal to 2.  The drawback is a notable
12228
increase in code size.  This switch implies @option{-mno-push-args}.
12229
 
12230
@item -mthreads
12231
@opindex mthreads
12232
Support thread-safe exception handling on @samp{Mingw32}.  Code that relies
12233
on thread-safe exception handling must compile and link all code with the
12234
@option{-mthreads} option.  When compiling, @option{-mthreads} defines
12235
@option{-D_MT}; when linking, it links in a special thread helper library
12236
@option{-lmingwthrd} which cleans up per thread exception handling data.
12237
 
12238
@item -mno-align-stringops
12239
@opindex mno-align-stringops
12240
Do not align destination of inlined string operations.  This switch reduces
12241
code size and improves performance in case the destination is already aligned,
12242
but GCC doesn't know about it.
12243
 
12244
@item -minline-all-stringops
12245
@opindex minline-all-stringops
12246
By default GCC inlines string operations only when destination is known to be
12247
aligned at least to 4 byte boundary.  This enables more inlining, increase code
12248
size, but may improve performance of code that depends on fast memcpy, strlen
12249
and memset for short lengths.
12250
 
12251
@item -minline-stringops-dynamically
12252
@opindex minline-stringops-dynamically
12253
For string operation of unknown size, inline runtime checks so for small
12254
blocks inline code is used, while for large blocks library call is used.
12255
 
12256
@item -mstringop-strategy=@var{alg}
12257
@opindex mstringop-strategy=@var{alg}
12258
Overwrite internal decision heuristic about particular algorithm to inline
12259
string operation with.  The allowed values are @code{rep_byte},
12260
@code{rep_4byte}, @code{rep_8byte} for expanding using i386 @code{rep} prefix
12261
of specified size, @code{byte_loop}, @code{loop}, @code{unrolled_loop} for
12262
expanding inline loop, @code{libcall} for always expanding library call.
12263
 
12264
@item -momit-leaf-frame-pointer
12265
@opindex momit-leaf-frame-pointer
12266
Don't keep the frame pointer in a register for leaf functions.  This
12267
avoids the instructions to save, set up and restore frame pointers and
12268
makes an extra register available in leaf functions.  The option
12269
@option{-fomit-frame-pointer} removes the frame pointer for all functions
12270
which might make debugging harder.
12271
 
12272
@item -mtls-direct-seg-refs
12273
@itemx -mno-tls-direct-seg-refs
12274
@opindex mtls-direct-seg-refs
12275
Controls whether TLS variables may be accessed with offsets from the
12276
TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
12277
or whether the thread base pointer must be added.  Whether or not this
12278
is legal depends on the operating system, and whether it maps the
12279
segment to cover the entire TLS area.
12280
 
12281
For systems that use GNU libc, the default is on.
12282
 
12283
@item -msse2avx
12284
@itemx -mno-sse2avx
12285
@opindex msse2avx
12286
Specify that the assembler should encode SSE instructions with VEX
12287
prefix.  The option @option{-mavx} turns this on by default.
12288
@end table
12289
 
12290
These @samp{-m} switches are supported in addition to the above
12291
on AMD x86-64 processors in 64-bit environments.
12292
 
12293
@table @gcctabopt
12294
@item -m32
12295
@itemx -m64
12296
@opindex m32
12297
@opindex m64
12298
Generate code for a 32-bit or 64-bit environment.
12299
The 32-bit environment sets int, long and pointer to 32 bits and
12300
generates code that runs on any i386 system.
12301
The 64-bit environment sets int to 32 bits and long and pointer
12302
to 64 bits and generates code for AMD's x86-64 architecture. For
12303
darwin only the -m64 option turns off the @option{-fno-pic} and
12304
@option{-mdynamic-no-pic} options.
12305
 
12306
@item -mno-red-zone
12307
@opindex mno-red-zone
12308
Do not use a so called red zone for x86-64 code.  The red zone is mandated
12309
by the x86-64 ABI, it is a 128-byte area beyond the location of the
12310
stack pointer that will not be modified by signal or interrupt handlers
12311
and therefore can be used for temporary data without adjusting the stack
12312
pointer.  The flag @option{-mno-red-zone} disables this red zone.
12313
 
12314
@item -mcmodel=small
12315
@opindex mcmodel=small
12316
Generate code for the small code model: the program and its symbols must
12317
be linked in the lower 2 GB of the address space.  Pointers are 64 bits.
12318
Programs can be statically or dynamically linked.  This is the default
12319
code model.
12320
 
12321
@item -mcmodel=kernel
12322
@opindex mcmodel=kernel
12323
Generate code for the kernel code model.  The kernel runs in the
12324
negative 2 GB of the address space.
12325
This model has to be used for Linux kernel code.
12326
 
12327
@item -mcmodel=medium
12328
@opindex mcmodel=medium
12329
Generate code for the medium model: The program is linked in the lower 2
12330
GB of the address space.  Small symbols are also placed there.  Symbols
12331
with sizes larger than @option{-mlarge-data-threshold} are put into
12332
large data or bss sections and can be located above 2GB.  Programs can
12333
be statically or dynamically linked.
12334
 
12335
@item -mcmodel=large
12336
@opindex mcmodel=large
12337
Generate code for the large model: This model makes no assumptions
12338
about addresses and sizes of sections.
12339
@end table
12340
 
12341
@node IA-64 Options
12342
@subsection IA-64 Options
12343
@cindex IA-64 Options
12344
 
12345
These are the @samp{-m} options defined for the Intel IA-64 architecture.
12346
 
12347
@table @gcctabopt
12348
@item -mbig-endian
12349
@opindex mbig-endian
12350
Generate code for a big endian target.  This is the default for HP-UX@.
12351
 
12352
@item -mlittle-endian
12353
@opindex mlittle-endian
12354
Generate code for a little endian target.  This is the default for AIX5
12355
and GNU/Linux.
12356
 
12357
@item -mgnu-as
12358
@itemx -mno-gnu-as
12359
@opindex mgnu-as
12360
@opindex mno-gnu-as
12361
Generate (or don't) code for the GNU assembler.  This is the default.
12362
@c Also, this is the default if the configure option @option{--with-gnu-as}
12363
@c is used.
12364
 
12365
@item -mgnu-ld
12366
@itemx -mno-gnu-ld
12367
@opindex mgnu-ld
12368
@opindex mno-gnu-ld
12369
Generate (or don't) code for the GNU linker.  This is the default.
12370
@c Also, this is the default if the configure option @option{--with-gnu-ld}
12371
@c is used.
12372
 
12373
@item -mno-pic
12374
@opindex mno-pic
12375
Generate code that does not use a global pointer register.  The result
12376
is not position independent code, and violates the IA-64 ABI@.
12377
 
12378
@item -mvolatile-asm-stop
12379
@itemx -mno-volatile-asm-stop
12380
@opindex mvolatile-asm-stop
12381
@opindex mno-volatile-asm-stop
12382
Generate (or don't) a stop bit immediately before and after volatile asm
12383
statements.
12384
 
12385
@item -mregister-names
12386
@itemx -mno-register-names
12387
@opindex mregister-names
12388
@opindex mno-register-names
12389
Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
12390
the stacked registers.  This may make assembler output more readable.
12391
 
12392
@item -mno-sdata
12393
@itemx -msdata
12394
@opindex mno-sdata
12395
@opindex msdata
12396
Disable (or enable) optimizations that use the small data section.  This may
12397
be useful for working around optimizer bugs.
12398
 
12399
@item -mconstant-gp
12400
@opindex mconstant-gp
12401
Generate code that uses a single constant global pointer value.  This is
12402
useful when compiling kernel code.
12403
 
12404
@item -mauto-pic
12405
@opindex mauto-pic
12406
Generate code that is self-relocatable.  This implies @option{-mconstant-gp}.
12407
This is useful when compiling firmware code.
12408
 
12409
@item -minline-float-divide-min-latency
12410
@opindex minline-float-divide-min-latency
12411
Generate code for inline divides of floating point values
12412
using the minimum latency algorithm.
12413
 
12414
@item -minline-float-divide-max-throughput
12415
@opindex minline-float-divide-max-throughput
12416
Generate code for inline divides of floating point values
12417
using the maximum throughput algorithm.
12418
 
12419
@item -mno-inline-float-divide
12420
@opindex mno-inline-float-divide
12421
Do not generate inline code for divides of floating point values.
12422
 
12423
@item -minline-int-divide-min-latency
12424
@opindex minline-int-divide-min-latency
12425
Generate code for inline divides of integer values
12426
using the minimum latency algorithm.
12427
 
12428
@item -minline-int-divide-max-throughput
12429
@opindex minline-int-divide-max-throughput
12430
Generate code for inline divides of integer values
12431
using the maximum throughput algorithm.
12432
 
12433
@item -mno-inline-int-divide
12434
@opindex mno-inline-int-divide
12435
Do not generate inline code for divides of integer values.
12436
 
12437
@item -minline-sqrt-min-latency
12438
@opindex minline-sqrt-min-latency
12439
Generate code for inline square roots
12440
using the minimum latency algorithm.
12441
 
12442
@item -minline-sqrt-max-throughput
12443
@opindex minline-sqrt-max-throughput
12444
Generate code for inline square roots
12445
using the maximum throughput algorithm.
12446
 
12447
@item -mno-inline-sqrt
12448
@opindex mno-inline-sqrt
12449
Do not generate inline code for sqrt.
12450
 
12451
@item -mfused-madd
12452
@itemx -mno-fused-madd
12453
@opindex mfused-madd
12454
@opindex mno-fused-madd
12455
Do (don't) generate code that uses the fused multiply/add or multiply/subtract
12456
instructions.  The default is to use these instructions.
12457
 
12458
@item -mno-dwarf2-asm
12459
@itemx -mdwarf2-asm
12460
@opindex mno-dwarf2-asm
12461
@opindex mdwarf2-asm
12462
Don't (or do) generate assembler code for the DWARF2 line number debugging
12463
info.  This may be useful when not using the GNU assembler.
12464
 
12465
@item -mearly-stop-bits
12466
@itemx -mno-early-stop-bits
12467
@opindex mearly-stop-bits
12468
@opindex mno-early-stop-bits
12469
Allow stop bits to be placed earlier than immediately preceding the
12470
instruction that triggered the stop bit.  This can improve instruction
12471
scheduling, but does not always do so.
12472
 
12473
@item -mfixed-range=@var{register-range}
12474
@opindex mfixed-range
12475
Generate code treating the given register range as fixed registers.
12476
A fixed register is one that the register allocator can not use.  This is
12477
useful when compiling kernel code.  A register range is specified as
12478
two registers separated by a dash.  Multiple register ranges can be
12479
specified separated by a comma.
12480
 
12481
@item -mtls-size=@var{tls-size}
12482
@opindex mtls-size
12483
Specify bit size of immediate TLS offsets.  Valid values are 14, 22, and
12484
64.
12485
 
12486
@item -mtune=@var{cpu-type}
12487
@opindex mtune
12488
Tune the instruction scheduling for a particular CPU, Valid values are
12489
itanium, itanium1, merced, itanium2, and mckinley.
12490
 
12491
@item -milp32
12492
@itemx -mlp64
12493
@opindex milp32
12494
@opindex mlp64
12495
Generate code for a 32-bit or 64-bit environment.
12496
The 32-bit environment sets int, long and pointer to 32 bits.
12497
The 64-bit environment sets int to 32 bits and long and pointer
12498
to 64 bits.  These are HP-UX specific flags.
12499
 
12500
@item -mno-sched-br-data-spec
12501
@itemx -msched-br-data-spec
12502
@opindex mno-sched-br-data-spec
12503
@opindex msched-br-data-spec
12504
(Dis/En)able data speculative scheduling before reload.
12505
This will result in generation of the ld.a instructions and
12506
the corresponding check instructions (ld.c / chk.a).
12507
The default is 'disable'.
12508
 
12509
@item -msched-ar-data-spec
12510
@itemx -mno-sched-ar-data-spec
12511
@opindex msched-ar-data-spec
12512
@opindex mno-sched-ar-data-spec
12513
(En/Dis)able data speculative scheduling after reload.
12514
This will result in generation of the ld.a instructions and
12515
the corresponding check instructions (ld.c / chk.a).
12516
The default is 'enable'.
12517
 
12518
@item -mno-sched-control-spec
12519
@itemx -msched-control-spec
12520
@opindex mno-sched-control-spec
12521
@opindex msched-control-spec
12522
(Dis/En)able control speculative scheduling.  This feature is
12523
available only during region scheduling (i.e.@: before reload).
12524
This will result in generation of the ld.s instructions and
12525
the corresponding check instructions chk.s .
12526
The default is 'disable'.
12527
 
12528
@item -msched-br-in-data-spec
12529
@itemx -mno-sched-br-in-data-spec
12530
@opindex msched-br-in-data-spec
12531
@opindex mno-sched-br-in-data-spec
12532
(En/Dis)able speculative scheduling of the instructions that
12533
are dependent on the data speculative loads before reload.
12534
This is effective only with @option{-msched-br-data-spec} enabled.
12535
The default is 'enable'.
12536
 
12537
@item -msched-ar-in-data-spec
12538
@itemx -mno-sched-ar-in-data-spec
12539
@opindex msched-ar-in-data-spec
12540
@opindex mno-sched-ar-in-data-spec
12541
(En/Dis)able speculative scheduling of the instructions that
12542
are dependent on the data speculative loads after reload.
12543
This is effective only with @option{-msched-ar-data-spec} enabled.
12544
The default is 'enable'.
12545
 
12546
@item -msched-in-control-spec
12547
@itemx -mno-sched-in-control-spec
12548
@opindex msched-in-control-spec
12549
@opindex mno-sched-in-control-spec
12550
(En/Dis)able speculative scheduling of the instructions that
12551
are dependent on the control speculative loads.
12552
This is effective only with @option{-msched-control-spec} enabled.
12553
The default is 'enable'.
12554
 
12555
@item -mno-sched-prefer-non-data-spec-insns
12556
@itemx -msched-prefer-non-data-spec-insns
12557
@opindex mno-sched-prefer-non-data-spec-insns
12558
@opindex msched-prefer-non-data-spec-insns
12559
If enabled, data speculative instructions will be chosen for schedule
12560
only if there are no other choices at the moment.  This will make
12561
the use of the data speculation much more conservative.
12562
The default is 'disable'.
12563
 
12564
@item -mno-sched-prefer-non-control-spec-insns
12565
@itemx -msched-prefer-non-control-spec-insns
12566
@opindex mno-sched-prefer-non-control-spec-insns
12567
@opindex msched-prefer-non-control-spec-insns
12568
If enabled, control speculative instructions will be chosen for schedule
12569
only if there are no other choices at the moment.  This will make
12570
the use of the control speculation much more conservative.
12571
The default is 'disable'.
12572
 
12573
@item -mno-sched-count-spec-in-critical-path
12574
@itemx -msched-count-spec-in-critical-path
12575
@opindex mno-sched-count-spec-in-critical-path
12576
@opindex msched-count-spec-in-critical-path
12577
If enabled, speculative dependencies will be considered during
12578
computation of the instructions priorities.  This will make the use of the
12579
speculation a bit more conservative.
12580
The default is 'disable'.
12581
 
12582
@item -msched-spec-ldc
12583
@opindex msched-spec-ldc
12584
Use a simple data speculation check.  This option is on by default.
12585
 
12586
@item -msched-control-spec-ldc
12587
@opindex msched-spec-ldc
12588
Use a simple check for control speculation.  This option is on by default.
12589
 
12590
@item -msched-stop-bits-after-every-cycle
12591
@opindex msched-stop-bits-after-every-cycle
12592
Place a stop bit after every cycle when scheduling.  This option is on
12593
by default.
12594
 
12595
@item -msched-fp-mem-deps-zero-cost
12596
@opindex msched-fp-mem-deps-zero-cost
12597
Assume that floating-point stores and loads are not likely to cause a conflict
12598
when placed into the same instruction group.  This option is disabled by
12599
default.
12600
 
12601
@item -msel-sched-dont-check-control-spec
12602
@opindex msel-sched-dont-check-control-spec
12603
Generate checks for control speculation in selective scheduling.
12604
This flag is disabled by default.
12605
 
12606
@item -msched-max-memory-insns=@var{max-insns}
12607
@opindex msched-max-memory-insns
12608
Limit on the number of memory insns per instruction group, giving lower
12609
priority to subsequent memory insns attempting to schedule in the same
12610
instruction group. Frequently useful to prevent cache bank conflicts.
12611
The default value is 1.
12612
 
12613
@item -msched-max-memory-insns-hard-limit
12614
@opindex msched-max-memory-insns-hard-limit
12615
Disallow more than `msched-max-memory-insns' in instruction group.
12616
Otherwise, limit is `soft' meaning that we would prefer non-memory operations
12617
when limit is reached but may still schedule memory operations.
12618
 
12619
@end table
12620
 
12621
@node IA-64/VMS Options
12622
@subsection IA-64/VMS Options
12623
 
12624
These @samp{-m} options are defined for the IA-64/VMS implementations:
12625
 
12626
@table @gcctabopt
12627
@item -mvms-return-codes
12628
@opindex mvms-return-codes
12629
Return VMS condition codes from main. The default is to return POSIX
12630
style condition (e.g.@ error) codes.
12631
 
12632
@item -mdebug-main=@var{prefix}
12633
@opindex mdebug-main=@var{prefix}
12634
Flag the first routine whose name starts with @var{prefix} as the main
12635
routine for the debugger.
12636
 
12637
@item -mmalloc64
12638
@opindex mmalloc64
12639
Default to 64bit memory allocation routines.
12640
@end table
12641
 
12642
@node LM32 Options
12643
@subsection LM32 Options
12644
@cindex LM32 options
12645
 
12646
These @option{-m} options are defined for the Lattice Mico32 architecture:
12647
 
12648
@table @gcctabopt
12649
@item -mbarrel-shift-enabled
12650
@opindex mbarrel-shift-enabled
12651
Enable barrel-shift instructions.
12652
 
12653
@item -mdivide-enabled
12654
@opindex mdivide-enabled
12655
Enable divide and modulus instructions.
12656
 
12657
@item -mmultiply-enabled
12658
@opindex multiply-enabled
12659
Enable multiply instructions.
12660
 
12661
@item -msign-extend-enabled
12662
@opindex msign-extend-enabled
12663
Enable sign extend instructions.
12664
 
12665
@item -muser-enabled
12666
@opindex muser-enabled
12667
Enable user-defined instructions.
12668
 
12669
@end table
12670
 
12671
@node M32C Options
12672
@subsection M32C Options
12673
@cindex M32C options
12674
 
12675
@table @gcctabopt
12676
@item -mcpu=@var{name}
12677
@opindex mcpu=
12678
Select the CPU for which code is generated.  @var{name} may be one of
12679
@samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to
12680
/60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for
12681
the M32C/80 series.
12682
 
12683
@item -msim
12684
@opindex msim
12685
Specifies that the program will be run on the simulator.  This causes
12686
an alternate runtime library to be linked in which supports, for
12687
example, file I/O@.  You must not use this option when generating
12688
programs that will run on real hardware; you must provide your own
12689
runtime library for whatever I/O functions are needed.
12690
 
12691
@item -memregs=@var{number}
12692
@opindex memregs=
12693
Specifies the number of memory-based pseudo-registers GCC will use
12694
during code generation.  These pseudo-registers will be used like real
12695
registers, so there is a tradeoff between GCC's ability to fit the
12696
code into available registers, and the performance penalty of using
12697
memory instead of registers.  Note that all modules in a program must
12698
be compiled with the same value for this option.  Because of that, you
12699
must not use this option with the default runtime libraries gcc
12700
builds.
12701
 
12702
@end table
12703
 
12704
@node M32R/D Options
12705
@subsection M32R/D Options
12706
@cindex M32R/D options
12707
 
12708
These @option{-m} options are defined for Renesas M32R/D architectures:
12709
 
12710
@table @gcctabopt
12711
@item -m32r2
12712
@opindex m32r2
12713
Generate code for the M32R/2@.
12714
 
12715
@item -m32rx
12716
@opindex m32rx
12717
Generate code for the M32R/X@.
12718
 
12719
@item -m32r
12720
@opindex m32r
12721
Generate code for the M32R@.  This is the default.
12722
 
12723
@item -mmodel=small
12724
@opindex mmodel=small
12725
Assume all objects live in the lower 16MB of memory (so that their addresses
12726
can be loaded with the @code{ld24} instruction), and assume all subroutines
12727
are reachable with the @code{bl} instruction.
12728
This is the default.
12729
 
12730
The addressability of a particular object can be set with the
12731
@code{model} attribute.
12732
 
12733
@item -mmodel=medium
12734
@opindex mmodel=medium
12735
Assume objects may be anywhere in the 32-bit address space (the compiler
12736
will generate @code{seth/add3} instructions to load their addresses), and
12737
assume all subroutines are reachable with the @code{bl} instruction.
12738
 
12739
@item -mmodel=large
12740
@opindex mmodel=large
12741
Assume objects may be anywhere in the 32-bit address space (the compiler
12742
will generate @code{seth/add3} instructions to load their addresses), and
12743
assume subroutines may not be reachable with the @code{bl} instruction
12744
(the compiler will generate the much slower @code{seth/add3/jl}
12745
instruction sequence).
12746
 
12747
@item -msdata=none
12748
@opindex msdata=none
12749
Disable use of the small data area.  Variables will be put into
12750
one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
12751
@code{section} attribute has been specified).
12752
This is the default.
12753
 
12754
The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
12755
Objects may be explicitly put in the small data area with the
12756
@code{section} attribute using one of these sections.
12757
 
12758
@item -msdata=sdata
12759
@opindex msdata=sdata
12760
Put small global and static data in the small data area, but do not
12761
generate special code to reference them.
12762
 
12763
@item -msdata=use
12764
@opindex msdata=use
12765
Put small global and static data in the small data area, and generate
12766
special instructions to reference them.
12767
 
12768
@item -G @var{num}
12769
@opindex G
12770
@cindex smaller data references
12771
Put global and static objects less than or equal to @var{num} bytes
12772
into the small data or bss sections instead of the normal data or bss
12773
sections.  The default value of @var{num} is 8.
12774
The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
12775
for this option to have any effect.
12776
 
12777
All modules should be compiled with the same @option{-G @var{num}} value.
12778
Compiling with different values of @var{num} may or may not work; if it
12779
doesn't the linker will give an error message---incorrect code will not be
12780
generated.
12781
 
12782
@item -mdebug
12783
@opindex mdebug
12784
Makes the M32R specific code in the compiler display some statistics
12785
that might help in debugging programs.
12786
 
12787
@item -malign-loops
12788
@opindex malign-loops
12789
Align all loops to a 32-byte boundary.
12790
 
12791
@item -mno-align-loops
12792
@opindex mno-align-loops
12793
Do not enforce a 32-byte alignment for loops.  This is the default.
12794
 
12795
@item -missue-rate=@var{number}
12796
@opindex missue-rate=@var{number}
12797
Issue @var{number} instructions per cycle.  @var{number} can only be 1
12798
or 2.
12799
 
12800
@item -mbranch-cost=@var{number}
12801
@opindex mbranch-cost=@var{number}
12802
@var{number} can only be 1 or 2.  If it is 1 then branches will be
12803
preferred over conditional code, if it is 2, then the opposite will
12804
apply.
12805
 
12806
@item -mflush-trap=@var{number}
12807
@opindex mflush-trap=@var{number}
12808
Specifies the trap number to use to flush the cache.  The default is
12809
12.  Valid numbers are between 0 and 15 inclusive.
12810
 
12811
@item -mno-flush-trap
12812
@opindex mno-flush-trap
12813
Specifies that the cache cannot be flushed by using a trap.
12814
 
12815
@item -mflush-func=@var{name}
12816
@opindex mflush-func=@var{name}
12817
Specifies the name of the operating system function to call to flush
12818
the cache.  The default is @emph{_flush_cache}, but a function call
12819
will only be used if a trap is not available.
12820
 
12821
@item -mno-flush-func
12822
@opindex mno-flush-func
12823
Indicates that there is no OS function for flushing the cache.
12824
 
12825
@end table
12826
 
12827
@node M680x0 Options
12828
@subsection M680x0 Options
12829
@cindex M680x0 options
12830
 
12831
These are the @samp{-m} options defined for M680x0 and ColdFire processors.
12832
The default settings depend on which architecture was selected when
12833
the compiler was configured; the defaults for the most common choices
12834
are given below.
12835
 
12836
@table @gcctabopt
12837
@item -march=@var{arch}
12838
@opindex march
12839
Generate code for a specific M680x0 or ColdFire instruction set
12840
architecture.  Permissible values of @var{arch} for M680x0
12841
architectures are: @samp{68000}, @samp{68010}, @samp{68020},
12842
@samp{68030}, @samp{68040}, @samp{68060} and @samp{cpu32}.  ColdFire
12843
architectures are selected according to Freescale's ISA classification
12844
and the permissible values are: @samp{isaa}, @samp{isaaplus},
12845
@samp{isab} and @samp{isac}.
12846
 
12847
gcc defines a macro @samp{__mcf@var{arch}__} whenever it is generating
12848
code for a ColdFire target.  The @var{arch} in this macro is one of the
12849
@option{-march} arguments given above.
12850
 
12851
When used together, @option{-march} and @option{-mtune} select code
12852
that runs on a family of similar processors but that is optimized
12853
for a particular microarchitecture.
12854
 
12855
@item -mcpu=@var{cpu}
12856
@opindex mcpu
12857
Generate code for a specific M680x0 or ColdFire processor.
12858
The M680x0 @var{cpu}s are: @samp{68000}, @samp{68010}, @samp{68020},
12859
@samp{68030}, @samp{68040}, @samp{68060}, @samp{68302}, @samp{68332}
12860
and @samp{cpu32}.  The ColdFire @var{cpu}s are given by the table
12861
below, which also classifies the CPUs into families:
12862
 
12863
@multitable @columnfractions 0.20 0.80
12864
@item @strong{Family} @tab @strong{@samp{-mcpu} arguments}
12865
@item @samp{51} @tab @samp{51} @samp{51ac} @samp{51cn} @samp{51em} @samp{51qe}
12866
@item @samp{5206} @tab @samp{5202} @samp{5204} @samp{5206}
12867
@item @samp{5206e} @tab @samp{5206e}
12868
@item @samp{5208} @tab @samp{5207} @samp{5208}
12869
@item @samp{5211a} @tab @samp{5210a} @samp{5211a}
12870
@item @samp{5213} @tab @samp{5211} @samp{5212} @samp{5213}
12871
@item @samp{5216} @tab @samp{5214} @samp{5216}
12872
@item @samp{52235} @tab @samp{52230} @samp{52231} @samp{52232} @samp{52233} @samp{52234} @samp{52235}
12873
@item @samp{5225} @tab @samp{5224} @samp{5225}
12874
@item @samp{52259} @tab @samp{52252} @samp{52254} @samp{52255} @samp{52256} @samp{52258} @samp{52259}
12875
@item @samp{5235} @tab @samp{5232} @samp{5233} @samp{5234} @samp{5235} @samp{523x}
12876
@item @samp{5249} @tab @samp{5249}
12877
@item @samp{5250} @tab @samp{5250}
12878
@item @samp{5271} @tab @samp{5270} @samp{5271}
12879
@item @samp{5272} @tab @samp{5272}
12880
@item @samp{5275} @tab @samp{5274} @samp{5275}
12881
@item @samp{5282} @tab @samp{5280} @samp{5281} @samp{5282} @samp{528x}
12882
@item @samp{53017} @tab @samp{53011} @samp{53012} @samp{53013} @samp{53014} @samp{53015} @samp{53016} @samp{53017}
12883
@item @samp{5307} @tab @samp{5307}
12884
@item @samp{5329} @tab @samp{5327} @samp{5328} @samp{5329} @samp{532x}
12885
@item @samp{5373} @tab @samp{5372} @samp{5373} @samp{537x}
12886
@item @samp{5407} @tab @samp{5407}
12887
@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}
12888
@end multitable
12889
 
12890
@option{-mcpu=@var{cpu}} overrides @option{-march=@var{arch}} if
12891
@var{arch} is compatible with @var{cpu}.  Other combinations of
12892
@option{-mcpu} and @option{-march} are rejected.
12893
 
12894
gcc defines the macro @samp{__mcf_cpu_@var{cpu}} when ColdFire target
12895
@var{cpu} is selected.  It also defines @samp{__mcf_family_@var{family}},
12896
where the value of @var{family} is given by the table above.
12897
 
12898
@item -mtune=@var{tune}
12899
@opindex mtune
12900
Tune the code for a particular microarchitecture, within the
12901
constraints set by @option{-march} and @option{-mcpu}.
12902
The M680x0 microarchitectures are: @samp{68000}, @samp{68010},
12903
@samp{68020}, @samp{68030}, @samp{68040}, @samp{68060}
12904
and @samp{cpu32}.  The ColdFire microarchitectures
12905
are: @samp{cfv1}, @samp{cfv2}, @samp{cfv3}, @samp{cfv4} and @samp{cfv4e}.
12906
 
12907
You can also use @option{-mtune=68020-40} for code that needs
12908
to run relatively well on 68020, 68030 and 68040 targets.
12909
@option{-mtune=68020-60} is similar but includes 68060 targets
12910
as well.  These two options select the same tuning decisions as
12911
@option{-m68020-40} and @option{-m68020-60} respectively.
12912
 
12913
gcc defines the macros @samp{__mc@var{arch}} and @samp{__mc@var{arch}__}
12914
when tuning for 680x0 architecture @var{arch}.  It also defines
12915
@samp{mc@var{arch}} unless either @option{-ansi} or a non-GNU @option{-std}
12916
option is used.  If gcc is tuning for a range of architectures,
12917
as selected by @option{-mtune=68020-40} or @option{-mtune=68020-60},
12918
it defines the macros for every architecture in the range.
12919
 
12920
gcc also defines the macro @samp{__m@var{uarch}__} when tuning for
12921
ColdFire microarchitecture @var{uarch}, where @var{uarch} is one
12922
of the arguments given above.
12923
 
12924
@item -m68000
12925
@itemx -mc68000
12926
@opindex m68000
12927
@opindex mc68000
12928
Generate output for a 68000.  This is the default
12929
when the compiler is configured for 68000-based systems.
12930
It is equivalent to @option{-march=68000}.
12931
 
12932
Use this option for microcontrollers with a 68000 or EC000 core,
12933
including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
12934
 
12935
@item -m68010
12936
@opindex m68010
12937
Generate output for a 68010.  This is the default
12938
when the compiler is configured for 68010-based systems.
12939
It is equivalent to @option{-march=68010}.
12940
 
12941
@item -m68020
12942
@itemx -mc68020
12943
@opindex m68020
12944
@opindex mc68020
12945
Generate output for a 68020.  This is the default
12946
when the compiler is configured for 68020-based systems.
12947
It is equivalent to @option{-march=68020}.
12948
 
12949
@item -m68030
12950
@opindex m68030
12951
Generate output for a 68030.  This is the default when the compiler is
12952
configured for 68030-based systems.  It is equivalent to
12953
@option{-march=68030}.
12954
 
12955
@item -m68040
12956
@opindex m68040
12957
Generate output for a 68040.  This is the default when the compiler is
12958
configured for 68040-based systems.  It is equivalent to
12959
@option{-march=68040}.
12960
 
12961
This option inhibits the use of 68881/68882 instructions that have to be
12962
emulated by software on the 68040.  Use this option if your 68040 does not
12963
have code to emulate those instructions.
12964
 
12965
@item -m68060
12966
@opindex m68060
12967
Generate output for a 68060.  This is the default when the compiler is
12968
configured for 68060-based systems.  It is equivalent to
12969
@option{-march=68060}.
12970
 
12971
This option inhibits the use of 68020 and 68881/68882 instructions that
12972
have to be emulated by software on the 68060.  Use this option if your 68060
12973
does not have code to emulate those instructions.
12974
 
12975
@item -mcpu32
12976
@opindex mcpu32
12977
Generate output for a CPU32.  This is the default
12978
when the compiler is configured for CPU32-based systems.
12979
It is equivalent to @option{-march=cpu32}.
12980
 
12981
Use this option for microcontrollers with a
12982
CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
12983
68336, 68340, 68341, 68349 and 68360.
12984
 
12985
@item -m5200
12986
@opindex m5200
12987
Generate output for a 520X ColdFire CPU@.  This is the default
12988
when the compiler is configured for 520X-based systems.
12989
It is equivalent to @option{-mcpu=5206}, and is now deprecated
12990
in favor of that option.
12991
 
12992
Use this option for microcontroller with a 5200 core, including
12993
the MCF5202, MCF5203, MCF5204 and MCF5206.
12994
 
12995
@item -m5206e
12996
@opindex m5206e
12997
Generate output for a 5206e ColdFire CPU@.  The option is now
12998
deprecated in favor of the equivalent @option{-mcpu=5206e}.
12999
 
13000
@item -m528x
13001
@opindex m528x
13002
Generate output for a member of the ColdFire 528X family.
13003
The option is now deprecated in favor of the equivalent
13004
@option{-mcpu=528x}.
13005
 
13006
@item -m5307
13007
@opindex m5307
13008
Generate output for a ColdFire 5307 CPU@.  The option is now deprecated
13009
in favor of the equivalent @option{-mcpu=5307}.
13010
 
13011
@item -m5407
13012
@opindex m5407
13013
Generate output for a ColdFire 5407 CPU@.  The option is now deprecated
13014
in favor of the equivalent @option{-mcpu=5407}.
13015
 
13016
@item -mcfv4e
13017
@opindex mcfv4e
13018
Generate output for a ColdFire V4e family CPU (e.g.@: 547x/548x).
13019
This includes use of hardware floating point instructions.
13020
The option is equivalent to @option{-mcpu=547x}, and is now
13021
deprecated in favor of that option.
13022
 
13023
@item -m68020-40
13024
@opindex m68020-40
13025
Generate output for a 68040, without using any of the new instructions.
13026
This results in code which can run relatively efficiently on either a
13027
68020/68881 or a 68030 or a 68040.  The generated code does use the
13028
68881 instructions that are emulated on the 68040.
13029
 
13030
The option is equivalent to @option{-march=68020} @option{-mtune=68020-40}.
13031
 
13032
@item -m68020-60
13033
@opindex m68020-60
13034
Generate output for a 68060, without using any of the new instructions.
13035
This results in code which can run relatively efficiently on either a
13036
68020/68881 or a 68030 or a 68040.  The generated code does use the
13037
68881 instructions that are emulated on the 68060.
13038
 
13039
The option is equivalent to @option{-march=68020} @option{-mtune=68020-60}.
13040
 
13041
@item -mhard-float
13042
@itemx -m68881
13043
@opindex mhard-float
13044
@opindex m68881
13045
Generate floating-point instructions.  This is the default for 68020
13046
and above, and for ColdFire devices that have an FPU@.  It defines the
13047
macro @samp{__HAVE_68881__} on M680x0 targets and @samp{__mcffpu__}
13048
on ColdFire targets.
13049
 
13050
@item -msoft-float
13051
@opindex msoft-float
13052
Do not generate floating-point instructions; use library calls instead.
13053
This is the default for 68000, 68010, and 68832 targets.  It is also
13054
the default for ColdFire devices that have no FPU.
13055
 
13056
@item -mdiv
13057
@itemx -mno-div
13058
@opindex mdiv
13059
@opindex mno-div
13060
Generate (do not generate) ColdFire hardware divide and remainder
13061
instructions.  If @option{-march} is used without @option{-mcpu},
13062
the default is ``on'' for ColdFire architectures and ``off'' for M680x0
13063
architectures.  Otherwise, the default is taken from the target CPU
13064
(either the default CPU, or the one specified by @option{-mcpu}).  For
13065
example, the default is ``off'' for @option{-mcpu=5206} and ``on'' for
13066
@option{-mcpu=5206e}.
13067
 
13068
gcc defines the macro @samp{__mcfhwdiv__} when this option is enabled.
13069
 
13070
@item -mshort
13071
@opindex mshort
13072
Consider type @code{int} to be 16 bits wide, like @code{short int}.
13073
Additionally, parameters passed on the stack are also aligned to a
13074
16-bit boundary even on targets whose API mandates promotion to 32-bit.
13075
 
13076
@item -mno-short
13077
@opindex mno-short
13078
Do not consider type @code{int} to be 16 bits wide.  This is the default.
13079
 
13080
@item -mnobitfield
13081
@itemx -mno-bitfield
13082
@opindex mnobitfield
13083
@opindex mno-bitfield
13084
Do not use the bit-field instructions.  The @option{-m68000}, @option{-mcpu32}
13085
and @option{-m5200} options imply @w{@option{-mnobitfield}}.
13086
 
13087
@item -mbitfield
13088
@opindex mbitfield
13089
Do use the bit-field instructions.  The @option{-m68020} option implies
13090
@option{-mbitfield}.  This is the default if you use a configuration
13091
designed for a 68020.
13092
 
13093
@item -mrtd
13094
@opindex mrtd
13095
Use a different function-calling convention, in which functions
13096
that take a fixed number of arguments return with the @code{rtd}
13097
instruction, which pops their arguments while returning.  This
13098
saves one instruction in the caller since there is no need to pop
13099
the arguments there.
13100
 
13101
This calling convention is incompatible with the one normally
13102
used on Unix, so you cannot use it if you need to call libraries
13103
compiled with the Unix compiler.
13104
 
13105
Also, you must provide function prototypes for all functions that
13106
take variable numbers of arguments (including @code{printf});
13107
otherwise incorrect code will be generated for calls to those
13108
functions.
13109
 
13110
In addition, seriously incorrect code will result if you call a
13111
function with too many arguments.  (Normally, extra arguments are
13112
harmlessly ignored.)
13113
 
13114
The @code{rtd} instruction is supported by the 68010, 68020, 68030,
13115
68040, 68060 and CPU32 processors, but not by the 68000 or 5200.
13116
 
13117
@item -mno-rtd
13118
@opindex mno-rtd
13119
Do not use the calling conventions selected by @option{-mrtd}.
13120
This is the default.
13121
 
13122
@item -malign-int
13123
@itemx -mno-align-int
13124
@opindex malign-int
13125
@opindex mno-align-int
13126
Control whether GCC aligns @code{int}, @code{long}, @code{long long},
13127
@code{float}, @code{double}, and @code{long double} variables on a 32-bit
13128
boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
13129
Aligning variables on 32-bit boundaries produces code that runs somewhat
13130
faster on processors with 32-bit busses at the expense of more memory.
13131
 
13132
@strong{Warning:} if you use the @option{-malign-int} switch, GCC will
13133
align structures containing the above types  differently than
13134
most published application binary interface specifications for the m68k.
13135
 
13136
@item -mpcrel
13137
@opindex mpcrel
13138
Use the pc-relative addressing mode of the 68000 directly, instead of
13139
using a global offset table.  At present, this option implies @option{-fpic},
13140
allowing at most a 16-bit offset for pc-relative addressing.  @option{-fPIC} is
13141
not presently supported with @option{-mpcrel}, though this could be supported for
13142
68020 and higher processors.
13143
 
13144
@item -mno-strict-align
13145
@itemx -mstrict-align
13146
@opindex mno-strict-align
13147
@opindex mstrict-align
13148
Do not (do) assume that unaligned memory references will be handled by
13149
the system.
13150
 
13151
@item -msep-data
13152
Generate code that allows the data segment to be located in a different
13153
area of memory from the text segment.  This allows for execute in place in
13154
an environment without virtual memory management.  This option implies
13155
@option{-fPIC}.
13156
 
13157
@item -mno-sep-data
13158
Generate code that assumes that the data segment follows the text segment.
13159
This is the default.
13160
 
13161
@item -mid-shared-library
13162
Generate code that supports shared libraries via the library ID method.
13163
This allows for execute in place and shared libraries in an environment
13164
without virtual memory management.  This option implies @option{-fPIC}.
13165
 
13166
@item -mno-id-shared-library
13167
Generate code that doesn't assume ID based shared libraries are being used.
13168
This is the default.
13169
 
13170
@item -mshared-library-id=n
13171
Specified the identification number of the ID based shared library being
13172
compiled.  Specifying a value of 0 will generate more compact code, specifying
13173
other values will force the allocation of that number to the current
13174
library but is no more space or time efficient than omitting this option.
13175
 
13176
@item -mxgot
13177
@itemx -mno-xgot
13178
@opindex mxgot
13179
@opindex mno-xgot
13180
When generating position-independent code for ColdFire, generate code
13181
that works if the GOT has more than 8192 entries.  This code is
13182
larger and slower than code generated without this option.  On M680x0
13183
processors, this option is not needed; @option{-fPIC} suffices.
13184
 
13185
GCC normally uses a single instruction to load values from the GOT@.
13186
While this is relatively efficient, it only works if the GOT
13187
is smaller than about 64k.  Anything larger causes the linker
13188
to report an error such as:
13189
 
13190
@cindex relocation truncated to fit (ColdFire)
13191
@smallexample
13192
relocation truncated to fit: R_68K_GOT16O foobar
13193
@end smallexample
13194
 
13195
If this happens, you should recompile your code with @option{-mxgot}.
13196
It should then work with very large GOTs.  However, code generated with
13197
@option{-mxgot} is less efficient, since it takes 4 instructions to fetch
13198
the value of a global symbol.
13199
 
13200
Note that some linkers, including newer versions of the GNU linker,
13201
can create multiple GOTs and sort GOT entries.  If you have such a linker,
13202
you should only need to use @option{-mxgot} when compiling a single
13203
object file that accesses more than 8192 GOT entries.  Very few do.
13204
 
13205
These options have no effect unless GCC is generating
13206
position-independent code.
13207
 
13208
@end table
13209
 
13210
@node M68hc1x Options
13211
@subsection M68hc1x Options
13212
@cindex M68hc1x options
13213
 
13214
These are the @samp{-m} options defined for the 68hc11 and 68hc12
13215
microcontrollers.  The default values for these options depends on
13216
which style of microcontroller was selected when the compiler was configured;
13217
the defaults for the most common choices are given below.
13218
 
13219
@table @gcctabopt
13220
@item -m6811
13221
@itemx -m68hc11
13222
@opindex m6811
13223
@opindex m68hc11
13224
Generate output for a 68HC11.  This is the default
13225
when the compiler is configured for 68HC11-based systems.
13226
 
13227
@item -m6812
13228
@itemx -m68hc12
13229
@opindex m6812
13230
@opindex m68hc12
13231
Generate output for a 68HC12.  This is the default
13232
when the compiler is configured for 68HC12-based systems.
13233
 
13234
@item -m68S12
13235
@itemx -m68hcs12
13236
@opindex m68S12
13237
@opindex m68hcs12
13238
Generate output for a 68HCS12.
13239
 
13240
@item -mauto-incdec
13241
@opindex mauto-incdec
13242
Enable the use of 68HC12 pre and post auto-increment and auto-decrement
13243
addressing modes.
13244
 
13245
@item -minmax
13246
@itemx -mnominmax
13247
@opindex minmax
13248
@opindex mnominmax
13249
Enable the use of 68HC12 min and max instructions.
13250
 
13251
@item -mlong-calls
13252
@itemx -mno-long-calls
13253
@opindex mlong-calls
13254
@opindex mno-long-calls
13255
Treat all calls as being far away (near).  If calls are assumed to be
13256
far away, the compiler will use the @code{call} instruction to
13257
call a function and the @code{rtc} instruction for returning.
13258
 
13259
@item -mshort
13260
@opindex mshort
13261
Consider type @code{int} to be 16 bits wide, like @code{short int}.
13262
 
13263
@item -msoft-reg-count=@var{count}
13264
@opindex msoft-reg-count
13265
Specify the number of pseudo-soft registers which are used for the
13266
code generation.  The maximum number is 32.  Using more pseudo-soft
13267
register may or may not result in better code depending on the program.
13268
The default is 4 for 68HC11 and 2 for 68HC12.
13269
 
13270
@end table
13271
 
13272
@node MCore Options
13273
@subsection MCore Options
13274
@cindex MCore options
13275
 
13276
These are the @samp{-m} options defined for the Motorola M*Core
13277
processors.
13278
 
13279
@table @gcctabopt
13280
 
13281
@item -mhardlit
13282
@itemx -mno-hardlit
13283
@opindex mhardlit
13284
@opindex mno-hardlit
13285
Inline constants into the code stream if it can be done in two
13286
instructions or less.
13287
 
13288
@item -mdiv
13289
@itemx -mno-div
13290
@opindex mdiv
13291
@opindex mno-div
13292
Use the divide instruction.  (Enabled by default).
13293
 
13294
@item -mrelax-immediate
13295
@itemx -mno-relax-immediate
13296
@opindex mrelax-immediate
13297
@opindex mno-relax-immediate
13298
Allow arbitrary sized immediates in bit operations.
13299
 
13300
@item -mwide-bitfields
13301
@itemx -mno-wide-bitfields
13302
@opindex mwide-bitfields
13303
@opindex mno-wide-bitfields
13304
Always treat bit-fields as int-sized.
13305
 
13306
@item -m4byte-functions
13307
@itemx -mno-4byte-functions
13308
@opindex m4byte-functions
13309
@opindex mno-4byte-functions
13310
Force all functions to be aligned to a four byte boundary.
13311
 
13312
@item -mcallgraph-data
13313
@itemx -mno-callgraph-data
13314
@opindex mcallgraph-data
13315
@opindex mno-callgraph-data
13316
Emit callgraph information.
13317
 
13318
@item -mslow-bytes
13319
@itemx -mno-slow-bytes
13320
@opindex mslow-bytes
13321
@opindex mno-slow-bytes
13322
Prefer word access when reading byte quantities.
13323
 
13324
@item -mlittle-endian
13325
@itemx -mbig-endian
13326
@opindex mlittle-endian
13327
@opindex mbig-endian
13328
Generate code for a little endian target.
13329
 
13330
@item -m210
13331
@itemx -m340
13332
@opindex m210
13333
@opindex m340
13334
Generate code for the 210 processor.
13335
 
13336
@item -mno-lsim
13337
@opindex mno-lsim
13338
Assume that run-time support has been provided and so omit the
13339
simulator library (@file{libsim.a)} from the linker command line.
13340
 
13341
@item -mstack-increment=@var{size}
13342
@opindex mstack-increment
13343
Set the maximum amount for a single stack increment operation.  Large
13344
values can increase the speed of programs which contain functions
13345
that need a large amount of stack space, but they can also trigger a
13346
segmentation fault if the stack is extended too much.  The default
13347
value is 0x1000.
13348
 
13349
@end table
13350
 
13351
@node MeP Options
13352
@subsection MeP Options
13353
@cindex MeP options
13354
 
13355
@table @gcctabopt
13356
 
13357
@item -mabsdiff
13358
@opindex mabsdiff
13359
Enables the @code{abs} instruction, which is the absolute difference
13360
between two registers.
13361
 
13362
@item -mall-opts
13363
@opindex mall-opts
13364
Enables all the optional instructions - average, multiply, divide, bit
13365
operations, leading zero, absolute difference, min/max, clip, and
13366
saturation.
13367
 
13368
 
13369
@item -maverage
13370
@opindex maverage
13371
Enables the @code{ave} instruction, which computes the average of two
13372
registers.
13373
 
13374
@item -mbased=@var{n}
13375
@opindex mbased=
13376
Variables of size @var{n} bytes or smaller will be placed in the
13377
@code{.based} section by default.  Based variables use the @code{$tp}
13378
register as a base register, and there is a 128 byte limit to the
13379
@code{.based} section.
13380
 
13381
@item -mbitops
13382
@opindex mbitops
13383
Enables the bit operation instructions - bit test (@code{btstm}), set
13384
(@code{bsetm}), clear (@code{bclrm}), invert (@code{bnotm}), and
13385
test-and-set (@code{tas}).
13386
 
13387
@item -mc=@var{name}
13388
@opindex mc=
13389
Selects which section constant data will be placed in.  @var{name} may
13390
be @code{tiny}, @code{near}, or @code{far}.
13391
 
13392
@item -mclip
13393
@opindex mclip
13394
Enables the @code{clip} instruction.  Note that @code{-mclip} is not
13395
useful unless you also provide @code{-mminmax}.
13396
 
13397
@item -mconfig=@var{name}
13398
@opindex mconfig=
13399
Selects one of the build-in core configurations.  Each MeP chip has
13400
one or more modules in it; each module has a core CPU and a variety of
13401
coprocessors, optional instructions, and peripherals.  The
13402
@code{MeP-Integrator} tool, not part of GCC, provides these
13403
configurations through this option; using this option is the same as
13404
using all the corresponding command line options.  The default
13405
configuration is @code{default}.
13406
 
13407
@item -mcop
13408
@opindex mcop
13409
Enables the coprocessor instructions.  By default, this is a 32-bit
13410
coprocessor.  Note that the coprocessor is normally enabled via the
13411
@code{-mconfig=} option.
13412
 
13413
@item -mcop32
13414
@opindex mcop32
13415
Enables the 32-bit coprocessor's instructions.
13416
 
13417
@item -mcop64
13418
@opindex mcop64
13419
Enables the 64-bit coprocessor's instructions.
13420
 
13421
@item -mivc2
13422
@opindex mivc2
13423
Enables IVC2 scheduling.  IVC2 is a 64-bit VLIW coprocessor.
13424
 
13425
@item -mdc
13426
@opindex mdc
13427
Causes constant variables to be placed in the @code{.near} section.
13428
 
13429
@item -mdiv
13430
@opindex mdiv
13431
Enables the @code{div} and @code{divu} instructions.
13432
 
13433
@item -meb
13434
@opindex meb
13435
Generate big-endian code.
13436
 
13437
@item -mel
13438
@opindex mel
13439
Generate little-endian code.
13440
 
13441
@item -mio-volatile
13442
@opindex mio-volatile
13443
Tells the compiler that any variable marked with the @code{io}
13444
attribute is to be considered volatile.
13445
 
13446
@item -ml
13447
@opindex ml
13448
Causes variables to be assigned to the @code{.far} section by default.
13449
 
13450
@item -mleadz
13451
@opindex mleadz
13452
Enables the @code{leadz} (leading zero) instruction.
13453
 
13454
@item -mm
13455
@opindex mm
13456
Causes variables to be assigned to the @code{.near} section by default.
13457
 
13458
@item -mminmax
13459
@opindex mminmax
13460
Enables the @code{min} and @code{max} instructions.
13461
 
13462
@item -mmult
13463
@opindex mmult
13464
Enables the multiplication and multiply-accumulate instructions.
13465
 
13466
@item -mno-opts
13467
@opindex mno-opts
13468
Disables all the optional instructions enabled by @code{-mall-opts}.
13469
 
13470
@item -mrepeat
13471
@opindex mrepeat
13472
Enables the @code{repeat} and @code{erepeat} instructions, used for
13473
low-overhead looping.
13474
 
13475
@item -ms
13476
@opindex ms
13477
Causes all variables to default to the @code{.tiny} section.  Note
13478
that there is a 65536 byte limit to this section.  Accesses to these
13479
variables use the @code{%gp} base register.
13480
 
13481
@item -msatur
13482
@opindex msatur
13483
Enables the saturation instructions.  Note that the compiler does not
13484
currently generate these itself, but this option is included for
13485
compatibility with other tools, like @code{as}.
13486
 
13487
@item -msdram
13488
@opindex msdram
13489
Link the SDRAM-based runtime instead of the default ROM-based runtime.
13490
 
13491
@item -msim
13492
@opindex msim
13493
Link the simulator runtime libraries.
13494
 
13495
@item -msimnovec
13496
@opindex msimnovec
13497
Link the simulator runtime libraries, excluding built-in support
13498
for reset and exception vectors and tables.
13499
 
13500
@item -mtf
13501
@opindex mtf
13502
Causes all functions to default to the @code{.far} section.  Without
13503
this option, functions default to the @code{.near} section.
13504
 
13505
@item -mtiny=@var{n}
13506
@opindex mtiny=
13507
Variables that are @var{n} bytes or smaller will be allocated to the
13508
@code{.tiny} section.  These variables use the @code{$gp} base
13509
register.  The default for this option is 4, but note that there's a
13510
65536 byte limit to the @code{.tiny} section.
13511
 
13512
@end table
13513
 
13514
@node MIPS Options
13515
@subsection MIPS Options
13516
@cindex MIPS options
13517
 
13518
@table @gcctabopt
13519
 
13520
@item -EB
13521
@opindex EB
13522
Generate big-endian code.
13523
 
13524
@item -EL
13525
@opindex EL
13526
Generate little-endian code.  This is the default for @samp{mips*el-*-*}
13527
configurations.
13528
 
13529
@item -march=@var{arch}
13530
@opindex march
13531
Generate code that will run on @var{arch}, which can be the name of a
13532
generic MIPS ISA, or the name of a particular processor.
13533
The ISA names are:
13534
@samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
13535
@samp{mips32}, @samp{mips32r2}, @samp{mips64} and @samp{mips64r2}.
13536
The processor names are:
13537
@samp{4kc}, @samp{4km}, @samp{4kp}, @samp{4ksc},
13538
@samp{4kec}, @samp{4kem}, @samp{4kep}, @samp{4ksd},
13539
@samp{5kc}, @samp{5kf},
13540
@samp{20kc},
13541
@samp{24kc}, @samp{24kf2_1}, @samp{24kf1_1},
13542
@samp{24kec}, @samp{24kef2_1}, @samp{24kef1_1},
13543
@samp{34kc}, @samp{34kf2_1}, @samp{34kf1_1},
13544
@samp{74kc}, @samp{74kf2_1}, @samp{74kf1_1}, @samp{74kf3_2},
13545
@samp{1004kc}, @samp{1004kf2_1}, @samp{1004kf1_1},
13546
@samp{loongson2e}, @samp{loongson2f},
13547
@samp{m4k},
13548
@samp{octeon},
13549
@samp{orion},
13550
@samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
13551
@samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000},
13552
@samp{rm7000}, @samp{rm9000},
13553
@samp{r10000}, @samp{r12000}, @samp{r14000}, @samp{r16000},
13554
@samp{sb1},
13555
@samp{sr71000},
13556
@samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
13557
@samp{vr5000}, @samp{vr5400}, @samp{vr5500}
13558
and @samp{xlr}.
13559
The special value @samp{from-abi} selects the
13560
most compatible architecture for the selected ABI (that is,
13561
@samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
13562
 
13563
Native Linux/GNU toolchains also support the value @samp{native},
13564
which selects the best architecture option for the host processor.
13565
@option{-march=native} has no effect if GCC does not recognize
13566
the processor.
13567
 
13568
In processor names, a final @samp{000} can be abbreviated as @samp{k}
13569
(for example, @samp{-march=r2k}).  Prefixes are optional, and
13570
@samp{vr} may be written @samp{r}.
13571
 
13572
Names of the form @samp{@var{n}f2_1} refer to processors with
13573
FPUs clocked at half the rate of the core, names of the form
13574
@samp{@var{n}f1_1} refer to processors with FPUs clocked at the same
13575
rate as the core, and names of the form @samp{@var{n}f3_2} refer to
13576
processors with FPUs clocked a ratio of 3:2 with respect to the core.
13577
For compatibility reasons, @samp{@var{n}f} is accepted as a synonym
13578
for @samp{@var{n}f2_1} while @samp{@var{n}x} and @samp{@var{b}fx} are
13579
accepted as synonyms for @samp{@var{n}f1_1}.
13580
 
13581
GCC defines two macros based on the value of this option.  The first
13582
is @samp{_MIPS_ARCH}, which gives the name of target architecture, as
13583
a string.  The second has the form @samp{_MIPS_ARCH_@var{foo}},
13584
where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@.
13585
For example, @samp{-march=r2000} will set @samp{_MIPS_ARCH}
13586
to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}.
13587
 
13588
Note that the @samp{_MIPS_ARCH} macro uses the processor names given
13589
above.  In other words, it will have the full prefix and will not
13590
abbreviate @samp{000} as @samp{k}.  In the case of @samp{from-abi},
13591
the macro names the resolved architecture (either @samp{"mips1"} or
13592
@samp{"mips3"}).  It names the default architecture when no
13593
@option{-march} option is given.
13594
 
13595
@item -mtune=@var{arch}
13596
@opindex mtune
13597
Optimize for @var{arch}.  Among other things, this option controls
13598
the way instructions are scheduled, and the perceived cost of arithmetic
13599
operations.  The list of @var{arch} values is the same as for
13600
@option{-march}.
13601
 
13602
When this option is not used, GCC will optimize for the processor
13603
specified by @option{-march}.  By using @option{-march} and
13604
@option{-mtune} together, it is possible to generate code that will
13605
run on a family of processors, but optimize the code for one
13606
particular member of that family.
13607
 
13608
@samp{-mtune} defines the macros @samp{_MIPS_TUNE} and
13609
@samp{_MIPS_TUNE_@var{foo}}, which work in the same way as the
13610
@samp{-march} ones described above.
13611
 
13612
@item -mips1
13613
@opindex mips1
13614
Equivalent to @samp{-march=mips1}.
13615
 
13616
@item -mips2
13617
@opindex mips2
13618
Equivalent to @samp{-march=mips2}.
13619
 
13620
@item -mips3
13621
@opindex mips3
13622
Equivalent to @samp{-march=mips3}.
13623
 
13624
@item -mips4
13625
@opindex mips4
13626
Equivalent to @samp{-march=mips4}.
13627
 
13628
@item -mips32
13629
@opindex mips32
13630
Equivalent to @samp{-march=mips32}.
13631
 
13632
@item -mips32r2
13633
@opindex mips32r2
13634
Equivalent to @samp{-march=mips32r2}.
13635
 
13636
@item -mips64
13637
@opindex mips64
13638
Equivalent to @samp{-march=mips64}.
13639
 
13640
@item -mips64r2
13641
@opindex mips64r2
13642
Equivalent to @samp{-march=mips64r2}.
13643
 
13644
@item -mips16
13645
@itemx -mno-mips16
13646
@opindex mips16
13647
@opindex mno-mips16
13648
Generate (do not generate) MIPS16 code.  If GCC is targetting a
13649
MIPS32 or MIPS64 architecture, it will make use of the MIPS16e ASE@.
13650
 
13651
MIPS16 code generation can also be controlled on a per-function basis
13652
by means of @code{mips16} and @code{nomips16} attributes.
13653
@xref{Function Attributes}, for more information.
13654
 
13655
@item -mflip-mips16
13656
@opindex mflip-mips16
13657
Generate MIPS16 code on alternating functions.  This option is provided
13658
for regression testing of mixed MIPS16/non-MIPS16 code generation, and is
13659
not intended for ordinary use in compiling user code.
13660
 
13661
@item -minterlink-mips16
13662
@itemx -mno-interlink-mips16
13663
@opindex minterlink-mips16
13664
@opindex mno-interlink-mips16
13665
Require (do not require) that non-MIPS16 code be link-compatible with
13666
MIPS16 code.
13667
 
13668
For example, non-MIPS16 code cannot jump directly to MIPS16 code;
13669
it must either use a call or an indirect jump.  @option{-minterlink-mips16}
13670
therefore disables direct jumps unless GCC knows that the target of the
13671
jump is not MIPS16.
13672
 
13673
@item -mabi=32
13674
@itemx -mabi=o64
13675
@itemx -mabi=n32
13676
@itemx -mabi=64
13677
@itemx -mabi=eabi
13678
@opindex mabi=32
13679
@opindex mabi=o64
13680
@opindex mabi=n32
13681
@opindex mabi=64
13682
@opindex mabi=eabi
13683
Generate code for the given ABI@.
13684
 
13685
Note that the EABI has a 32-bit and a 64-bit variant.  GCC normally
13686
generates 64-bit code when you select a 64-bit architecture, but you
13687
can use @option{-mgp32} to get 32-bit code instead.
13688
 
13689
For information about the O64 ABI, see
13690
@w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
13691
 
13692
GCC supports a variant of the o32 ABI in which floating-point registers
13693
are 64 rather than 32 bits wide.  You can select this combination with
13694
@option{-mabi=32} @option{-mfp64}.  This ABI relies on the @samp{mthc1}
13695
and @samp{mfhc1} instructions and is therefore only supported for
13696
MIPS32R2 processors.
13697
 
13698
The register assignments for arguments and return values remain the
13699
same, but each scalar value is passed in a single 64-bit register
13700
rather than a pair of 32-bit registers.  For example, scalar
13701
floating-point values are returned in @samp{$f0} only, not a
13702
@samp{$f0}/@samp{$f1} pair.  The set of call-saved registers also
13703
remains the same, but all 64 bits are saved.
13704
 
13705
@item -mabicalls
13706
@itemx -mno-abicalls
13707
@opindex mabicalls
13708
@opindex mno-abicalls
13709
Generate (do not generate) code that is suitable for SVR4-style
13710
dynamic objects.  @option{-mabicalls} is the default for SVR4-based
13711
systems.
13712
 
13713
@item -mshared
13714
@itemx -mno-shared
13715
Generate (do not generate) code that is fully position-independent,
13716
and that can therefore be linked into shared libraries.  This option
13717
only affects @option{-mabicalls}.
13718
 
13719
All @option{-mabicalls} code has traditionally been position-independent,
13720
regardless of options like @option{-fPIC} and @option{-fpic}.  However,
13721
as an extension, the GNU toolchain allows executables to use absolute
13722
accesses for locally-binding symbols.  It can also use shorter GP
13723
initialization sequences and generate direct calls to locally-defined
13724
functions.  This mode is selected by @option{-mno-shared}.
13725
 
13726
@option{-mno-shared} depends on binutils 2.16 or higher and generates
13727
objects that can only be linked by the GNU linker.  However, the option
13728
does not affect the ABI of the final executable; it only affects the ABI
13729
of relocatable objects.  Using @option{-mno-shared} will generally make
13730
executables both smaller and quicker.
13731
 
13732
@option{-mshared} is the default.
13733
 
13734
@item -mplt
13735
@itemx -mno-plt
13736
@opindex mplt
13737
@opindex mno-plt
13738
Assume (do not assume) that the static and dynamic linkers
13739
support PLTs and copy relocations.  This option only affects
13740
@samp{-mno-shared -mabicalls}.  For the n64 ABI, this option
13741
has no effect without @samp{-msym32}.
13742
 
13743
You can make @option{-mplt} the default by configuring
13744
GCC with @option{--with-mips-plt}.  The default is
13745
@option{-mno-plt} otherwise.
13746
 
13747
@item -mxgot
13748
@itemx -mno-xgot
13749
@opindex mxgot
13750
@opindex mno-xgot
13751
Lift (do not lift) the usual restrictions on the size of the global
13752
offset table.
13753
 
13754
GCC normally uses a single instruction to load values from the GOT@.
13755
While this is relatively efficient, it will only work if the GOT
13756
is smaller than about 64k.  Anything larger will cause the linker
13757
to report an error such as:
13758
 
13759
@cindex relocation truncated to fit (MIPS)
13760
@smallexample
13761
relocation truncated to fit: R_MIPS_GOT16 foobar
13762
@end smallexample
13763
 
13764
If this happens, you should recompile your code with @option{-mxgot}.
13765
It should then work with very large GOTs, although it will also be
13766
less efficient, since it will take three instructions to fetch the
13767
value of a global symbol.
13768
 
13769
Note that some linkers can create multiple GOTs.  If you have such a
13770
linker, you should only need to use @option{-mxgot} when a single object
13771
file accesses more than 64k's worth of GOT entries.  Very few do.
13772
 
13773
These options have no effect unless GCC is generating position
13774
independent code.
13775
 
13776
@item -mgp32
13777
@opindex mgp32
13778
Assume that general-purpose registers are 32 bits wide.
13779
 
13780
@item -mgp64
13781
@opindex mgp64
13782
Assume that general-purpose registers are 64 bits wide.
13783
 
13784
@item -mfp32
13785
@opindex mfp32
13786
Assume that floating-point registers are 32 bits wide.
13787
 
13788
@item -mfp64
13789
@opindex mfp64
13790
Assume that floating-point registers are 64 bits wide.
13791
 
13792
@item -mhard-float
13793
@opindex mhard-float
13794
Use floating-point coprocessor instructions.
13795
 
13796
@item -msoft-float
13797
@opindex msoft-float
13798
Do not use floating-point coprocessor instructions.  Implement
13799
floating-point calculations using library calls instead.
13800
 
13801
@item -msingle-float
13802
@opindex msingle-float
13803
Assume that the floating-point coprocessor only supports single-precision
13804
operations.
13805
 
13806
@item -mdouble-float
13807
@opindex mdouble-float
13808
Assume that the floating-point coprocessor supports double-precision
13809
operations.  This is the default.
13810
 
13811
@item -mllsc
13812
@itemx -mno-llsc
13813
@opindex mllsc
13814
@opindex mno-llsc
13815
Use (do not use) @samp{ll}, @samp{sc}, and @samp{sync} instructions to
13816
implement atomic memory built-in functions.  When neither option is
13817
specified, GCC will use the instructions if the target architecture
13818
supports them.
13819
 
13820
@option{-mllsc} is useful if the runtime environment can emulate the
13821
instructions and @option{-mno-llsc} can be useful when compiling for
13822
nonstandard ISAs.  You can make either option the default by
13823
configuring GCC with @option{--with-llsc} and @option{--without-llsc}
13824
respectively.  @option{--with-llsc} is the default for some
13825
configurations; see the installation documentation for details.
13826
 
13827
@item -mdsp
13828
@itemx -mno-dsp
13829
@opindex mdsp
13830
@opindex mno-dsp
13831
Use (do not use) revision 1 of the MIPS DSP ASE@.
13832
@xref{MIPS DSP Built-in Functions}.  This option defines the
13833
preprocessor macro @samp{__mips_dsp}.  It also defines
13834
@samp{__mips_dsp_rev} to 1.
13835
 
13836
@item -mdspr2
13837
@itemx -mno-dspr2
13838
@opindex mdspr2
13839
@opindex mno-dspr2
13840
Use (do not use) revision 2 of the MIPS DSP ASE@.
13841
@xref{MIPS DSP Built-in Functions}.  This option defines the
13842
preprocessor macros @samp{__mips_dsp} and @samp{__mips_dspr2}.
13843
It also defines @samp{__mips_dsp_rev} to 2.
13844
 
13845
@item -msmartmips
13846
@itemx -mno-smartmips
13847
@opindex msmartmips
13848
@opindex mno-smartmips
13849
Use (do not use) the MIPS SmartMIPS ASE.
13850
 
13851
@item -mpaired-single
13852
@itemx -mno-paired-single
13853
@opindex mpaired-single
13854
@opindex mno-paired-single
13855
Use (do not use) paired-single floating-point instructions.
13856
@xref{MIPS Paired-Single Support}.  This option requires
13857
hardware floating-point support to be enabled.
13858
 
13859
@item -mdmx
13860
@itemx -mno-mdmx
13861
@opindex mdmx
13862
@opindex mno-mdmx
13863
Use (do not use) MIPS Digital Media Extension instructions.
13864
This option can only be used when generating 64-bit code and requires
13865
hardware floating-point support to be enabled.
13866
 
13867
@item -mips3d
13868
@itemx -mno-mips3d
13869
@opindex mips3d
13870
@opindex mno-mips3d
13871
Use (do not use) the MIPS-3D ASE@.  @xref{MIPS-3D Built-in Functions}.
13872
The option @option{-mips3d} implies @option{-mpaired-single}.
13873
 
13874
@item -mmt
13875
@itemx -mno-mt
13876
@opindex mmt
13877
@opindex mno-mt
13878
Use (do not use) MT Multithreading instructions.
13879
 
13880
@item -mlong64
13881
@opindex mlong64
13882
Force @code{long} types to be 64 bits wide.  See @option{-mlong32} for
13883
an explanation of the default and the way that the pointer size is
13884
determined.
13885
 
13886
@item -mlong32
13887
@opindex mlong32
13888
Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
13889
 
13890
The default size of @code{int}s, @code{long}s and pointers depends on
13891
the ABI@.  All the supported ABIs use 32-bit @code{int}s.  The n64 ABI
13892
uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
13893
32-bit @code{long}s.  Pointers are the same size as @code{long}s,
13894
or the same size as integer registers, whichever is smaller.
13895
 
13896
@item -msym32
13897
@itemx -mno-sym32
13898
@opindex msym32
13899
@opindex mno-sym32
13900
Assume (do not assume) that all symbols have 32-bit values, regardless
13901
of the selected ABI@.  This option is useful in combination with
13902
@option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
13903
to generate shorter and faster references to symbolic addresses.
13904
 
13905
@item -G @var{num}
13906
@opindex G
13907
Put definitions of externally-visible data in a small data section
13908
if that data is no bigger than @var{num} bytes.  GCC can then access
13909
the data more efficiently; see @option{-mgpopt} for details.
13910
 
13911
The default @option{-G} option depends on the configuration.
13912
 
13913
@item -mlocal-sdata
13914
@itemx -mno-local-sdata
13915
@opindex mlocal-sdata
13916
@opindex mno-local-sdata
13917
Extend (do not extend) the @option{-G} behavior to local data too,
13918
such as to static variables in C@.  @option{-mlocal-sdata} is the
13919
default for all configurations.
13920
 
13921
If the linker complains that an application is using too much small data,
13922
you might want to try rebuilding the less performance-critical parts with
13923
@option{-mno-local-sdata}.  You might also want to build large
13924
libraries with @option{-mno-local-sdata}, so that the libraries leave
13925
more room for the main program.
13926
 
13927
@item -mextern-sdata
13928
@itemx -mno-extern-sdata
13929
@opindex mextern-sdata
13930
@opindex mno-extern-sdata
13931
Assume (do not assume) that externally-defined data will be in
13932
a small data section if that data is within the @option{-G} limit.
13933
@option{-mextern-sdata} is the default for all configurations.
13934
 
13935
If you compile a module @var{Mod} with @option{-mextern-sdata} @option{-G
13936
@var{num}} @option{-mgpopt}, and @var{Mod} references a variable @var{Var}
13937
that is no bigger than @var{num} bytes, you must make sure that @var{Var}
13938
is placed in a small data section.  If @var{Var} is defined by another
13939
module, you must either compile that module with a high-enough
13940
@option{-G} setting or attach a @code{section} attribute to @var{Var}'s
13941
definition.  If @var{Var} is common, you must link the application
13942
with a high-enough @option{-G} setting.
13943
 
13944
The easiest way of satisfying these restrictions is to compile
13945
and link every module with the same @option{-G} option.  However,
13946
you may wish to build a library that supports several different
13947
small data limits.  You can do this by compiling the library with
13948
the highest supported @option{-G} setting and additionally using
13949
@option{-mno-extern-sdata} to stop the library from making assumptions
13950
about externally-defined data.
13951
 
13952
@item -mgpopt
13953
@itemx -mno-gpopt
13954
@opindex mgpopt
13955
@opindex mno-gpopt
13956
Use (do not use) GP-relative accesses for symbols that are known to be
13957
in a small data section; see @option{-G}, @option{-mlocal-sdata} and
13958
@option{-mextern-sdata}.  @option{-mgpopt} is the default for all
13959
configurations.
13960
 
13961
@option{-mno-gpopt} is useful for cases where the @code{$gp} register
13962
might not hold the value of @code{_gp}.  For example, if the code is
13963
part of a library that might be used in a boot monitor, programs that
13964
call boot monitor routines will pass an unknown value in @code{$gp}.
13965
(In such situations, the boot monitor itself would usually be compiled
13966
with @option{-G0}.)
13967
 
13968
@option{-mno-gpopt} implies @option{-mno-local-sdata} and
13969
@option{-mno-extern-sdata}.
13970
 
13971
@item -membedded-data
13972
@itemx -mno-embedded-data
13973
@opindex membedded-data
13974
@opindex mno-embedded-data
13975
Allocate variables to the read-only data section first if possible, then
13976
next in the small data section if possible, otherwise in data.  This gives
13977
slightly slower code than the default, but reduces the amount of RAM required
13978
when executing, and thus may be preferred for some embedded systems.
13979
 
13980
@item -muninit-const-in-rodata
13981
@itemx -mno-uninit-const-in-rodata
13982
@opindex muninit-const-in-rodata
13983
@opindex mno-uninit-const-in-rodata
13984
Put uninitialized @code{const} variables in the read-only data section.
13985
This option is only meaningful in conjunction with @option{-membedded-data}.
13986
 
13987
@item -mcode-readable=@var{setting}
13988
@opindex mcode-readable
13989
Specify whether GCC may generate code that reads from executable sections.
13990
There are three possible settings:
13991
 
13992
@table @gcctabopt
13993
@item -mcode-readable=yes
13994
Instructions may freely access executable sections.  This is the
13995
default setting.
13996
 
13997
@item -mcode-readable=pcrel
13998
MIPS16 PC-relative load instructions can access executable sections,
13999
but other instructions must not do so.  This option is useful on 4KSc
14000
and 4KSd processors when the code TLBs have the Read Inhibit bit set.
14001
It is also useful on processors that can be configured to have a dual
14002
instruction/data SRAM interface and that, like the M4K, automatically
14003
redirect PC-relative loads to the instruction RAM.
14004
 
14005
@item -mcode-readable=no
14006
Instructions must not access executable sections.  This option can be
14007
useful on targets that are configured to have a dual instruction/data
14008
SRAM interface but that (unlike the M4K) do not automatically redirect
14009
PC-relative loads to the instruction RAM.
14010
@end table
14011
 
14012
@item -msplit-addresses
14013
@itemx -mno-split-addresses
14014
@opindex msplit-addresses
14015
@opindex mno-split-addresses
14016
Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
14017
relocation operators.  This option has been superseded by
14018
@option{-mexplicit-relocs} but is retained for backwards compatibility.
14019
 
14020
@item -mexplicit-relocs
14021
@itemx -mno-explicit-relocs
14022
@opindex mexplicit-relocs
14023
@opindex mno-explicit-relocs
14024
Use (do not use) assembler relocation operators when dealing with symbolic
14025
addresses.  The alternative, selected by @option{-mno-explicit-relocs},
14026
is to use assembler macros instead.
14027
 
14028
@option{-mexplicit-relocs} is the default if GCC was configured
14029
to use an assembler that supports relocation operators.
14030
 
14031
@item -mcheck-zero-division
14032
@itemx -mno-check-zero-division
14033
@opindex mcheck-zero-division
14034
@opindex mno-check-zero-division
14035
Trap (do not trap) on integer division by zero.
14036
 
14037
The default is @option{-mcheck-zero-division}.
14038
 
14039
@item -mdivide-traps
14040
@itemx -mdivide-breaks
14041
@opindex mdivide-traps
14042
@opindex mdivide-breaks
14043
MIPS systems check for division by zero by generating either a
14044
conditional trap or a break instruction.  Using traps results in
14045
smaller code, but is only supported on MIPS II and later.  Also, some
14046
versions of the Linux kernel have a bug that prevents trap from
14047
generating the proper signal (@code{SIGFPE}).  Use @option{-mdivide-traps} to
14048
allow conditional traps on architectures that support them and
14049
@option{-mdivide-breaks} to force the use of breaks.
14050
 
14051
The default is usually @option{-mdivide-traps}, but this can be
14052
overridden at configure time using @option{--with-divide=breaks}.
14053
Divide-by-zero checks can be completely disabled using
14054
@option{-mno-check-zero-division}.
14055
 
14056
@item -mmemcpy
14057
@itemx -mno-memcpy
14058
@opindex mmemcpy
14059
@opindex mno-memcpy
14060
Force (do not force) the use of @code{memcpy()} for non-trivial block
14061
moves.  The default is @option{-mno-memcpy}, which allows GCC to inline
14062
most constant-sized copies.
14063
 
14064
@item -mlong-calls
14065
@itemx -mno-long-calls
14066
@opindex mlong-calls
14067
@opindex mno-long-calls
14068
Disable (do not disable) use of the @code{jal} instruction.  Calling
14069
functions using @code{jal} is more efficient but requires the caller
14070
and callee to be in the same 256 megabyte segment.
14071
 
14072
This option has no effect on abicalls code.  The default is
14073
@option{-mno-long-calls}.
14074
 
14075
@item -mmad
14076
@itemx -mno-mad
14077
@opindex mmad
14078
@opindex mno-mad
14079
Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
14080
instructions, as provided by the R4650 ISA@.
14081
 
14082
@item -mfused-madd
14083
@itemx -mno-fused-madd
14084
@opindex mfused-madd
14085
@opindex mno-fused-madd
14086
Enable (disable) use of the floating point multiply-accumulate
14087
instructions, when they are available.  The default is
14088
@option{-mfused-madd}.
14089
 
14090
When multiply-accumulate instructions are used, the intermediate
14091
product is calculated to infinite precision and is not subject to
14092
the FCSR Flush to Zero bit.  This may be undesirable in some
14093
circumstances.
14094
 
14095
@item -nocpp
14096
@opindex nocpp
14097
Tell the MIPS assembler to not run its preprocessor over user
14098
assembler files (with a @samp{.s} suffix) when assembling them.
14099
 
14100
@item -mfix-r4000
14101
@itemx -mno-fix-r4000
14102
@opindex mfix-r4000
14103
@opindex mno-fix-r4000
14104
Work around certain R4000 CPU errata:
14105
@itemize @minus
14106
@item
14107
A double-word or a variable shift may give an incorrect result if executed
14108
immediately after starting an integer division.
14109
@item
14110
A double-word or a variable shift may give an incorrect result if executed
14111
while an integer multiplication is in progress.
14112
@item
14113
An integer division may give an incorrect result if started in a delay slot
14114
of a taken branch or a jump.
14115
@end itemize
14116
 
14117
@item -mfix-r4400
14118
@itemx -mno-fix-r4400
14119
@opindex mfix-r4400
14120
@opindex mno-fix-r4400
14121
Work around certain R4400 CPU errata:
14122
@itemize @minus
14123
@item
14124
A double-word or a variable shift may give an incorrect result if executed
14125
immediately after starting an integer division.
14126
@end itemize
14127
 
14128
@item -mfix-r10000
14129
@itemx -mno-fix-r10000
14130
@opindex mfix-r10000
14131
@opindex mno-fix-r10000
14132
Work around certain R10000 errata:
14133
@itemize @minus
14134
@item
14135
@code{ll}/@code{sc} sequences may not behave atomically on revisions
14136
prior to 3.0.  They may deadlock on revisions 2.6 and earlier.
14137
@end itemize
14138
 
14139
This option can only be used if the target architecture supports
14140
branch-likely instructions.  @option{-mfix-r10000} is the default when
14141
@option{-march=r10000} is used; @option{-mno-fix-r10000} is the default
14142
otherwise.
14143
 
14144
@item -mfix-vr4120
14145
@itemx -mno-fix-vr4120
14146
@opindex mfix-vr4120
14147
Work around certain VR4120 errata:
14148
@itemize @minus
14149
@item
14150
@code{dmultu} does not always produce the correct result.
14151
@item
14152
@code{div} and @code{ddiv} do not always produce the correct result if one
14153
of the operands is negative.
14154
@end itemize
14155
The workarounds for the division errata rely on special functions in
14156
@file{libgcc.a}.  At present, these functions are only provided by
14157
the @code{mips64vr*-elf} configurations.
14158
 
14159
Other VR4120 errata require a nop to be inserted between certain pairs of
14160
instructions.  These errata are handled by the assembler, not by GCC itself.
14161
 
14162
@item -mfix-vr4130
14163
@opindex mfix-vr4130
14164
Work around the VR4130 @code{mflo}/@code{mfhi} errata.  The
14165
workarounds are implemented by the assembler rather than by GCC,
14166
although GCC will avoid using @code{mflo} and @code{mfhi} if the
14167
VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
14168
instructions are available instead.
14169
 
14170
@item -mfix-sb1
14171
@itemx -mno-fix-sb1
14172
@opindex mfix-sb1
14173
Work around certain SB-1 CPU core errata.
14174
(This flag currently works around the SB-1 revision 2
14175
``F1'' and ``F2'' floating point errata.)
14176
 
14177
@item -mr10k-cache-barrier=@var{setting}
14178
@opindex mr10k-cache-barrier
14179
Specify whether GCC should insert cache barriers to avoid the
14180
side-effects of speculation on R10K processors.
14181
 
14182
In common with many processors, the R10K tries to predict the outcome
14183
of a conditional branch and speculatively executes instructions from
14184
the ``taken'' branch.  It later aborts these instructions if the
14185
predicted outcome was wrong.  However, on the R10K, even aborted
14186
instructions can have side effects.
14187
 
14188
This problem only affects kernel stores and, depending on the system,
14189
kernel loads.  As an example, a speculatively-executed store may load
14190
the target memory into cache and mark the cache line as dirty, even if
14191
the store itself is later aborted.  If a DMA operation writes to the
14192
same area of memory before the ``dirty'' line is flushed, the cached
14193
data will overwrite the DMA-ed data.  See the R10K processor manual
14194
for a full description, including other potential problems.
14195
 
14196
One workaround is to insert cache barrier instructions before every memory
14197
access that might be speculatively executed and that might have side
14198
effects even if aborted.  @option{-mr10k-cache-barrier=@var{setting}}
14199
controls GCC's implementation of this workaround.  It assumes that
14200
aborted accesses to any byte in the following regions will not have
14201
side effects:
14202
 
14203
@enumerate
14204
@item
14205
the memory occupied by the current function's stack frame;
14206
 
14207
@item
14208
the memory occupied by an incoming stack argument;
14209
 
14210
@item
14211
the memory occupied by an object with a link-time-constant address.
14212
@end enumerate
14213
 
14214
It is the kernel's responsibility to ensure that speculative
14215
accesses to these regions are indeed safe.
14216
 
14217
If the input program contains a function declaration such as:
14218
 
14219
@smallexample
14220
void foo (void);
14221
@end smallexample
14222
 
14223
then the implementation of @code{foo} must allow @code{j foo} and
14224
@code{jal foo} to be executed speculatively.  GCC honors this
14225
restriction for functions it compiles itself.  It expects non-GCC
14226
functions (such as hand-written assembly code) to do the same.
14227
 
14228
The option has three forms:
14229
 
14230
@table @gcctabopt
14231
@item -mr10k-cache-barrier=load-store
14232
Insert a cache barrier before a load or store that might be
14233
speculatively executed and that might have side effects even
14234
if aborted.
14235
 
14236
@item -mr10k-cache-barrier=store
14237
Insert a cache barrier before a store that might be speculatively
14238
executed and that might have side effects even if aborted.
14239
 
14240
@item -mr10k-cache-barrier=none
14241
Disable the insertion of cache barriers.  This is the default setting.
14242
@end table
14243
 
14244
@item -mflush-func=@var{func}
14245
@itemx -mno-flush-func
14246
@opindex mflush-func
14247
Specifies the function to call to flush the I and D caches, or to not
14248
call any such function.  If called, the function must take the same
14249
arguments as the common @code{_flush_func()}, that is, the address of the
14250
memory range for which the cache is being flushed, the size of the
14251
memory range, and the number 3 (to flush both caches).  The default
14252
depends on the target GCC was configured for, but commonly is either
14253
@samp{_flush_func} or @samp{__cpu_flush}.
14254
 
14255
@item mbranch-cost=@var{num}
14256
@opindex mbranch-cost
14257
Set the cost of branches to roughly @var{num} ``simple'' instructions.
14258
This cost is only a heuristic and is not guaranteed to produce
14259
consistent results across releases.  A zero cost redundantly selects
14260
the default, which is based on the @option{-mtune} setting.
14261
 
14262
@item -mbranch-likely
14263
@itemx -mno-branch-likely
14264
@opindex mbranch-likely
14265
@opindex mno-branch-likely
14266
Enable or disable use of Branch Likely instructions, regardless of the
14267
default for the selected architecture.  By default, Branch Likely
14268
instructions may be generated if they are supported by the selected
14269
architecture.  An exception is for the MIPS32 and MIPS64 architectures
14270
and processors which implement those architectures; for those, Branch
14271
Likely instructions will not be generated by default because the MIPS32
14272
and MIPS64 architectures specifically deprecate their use.
14273
 
14274
@item -mfp-exceptions
14275
@itemx -mno-fp-exceptions
14276
@opindex mfp-exceptions
14277
Specifies whether FP exceptions are enabled.  This affects how we schedule
14278
FP instructions for some processors.  The default is that FP exceptions are
14279
enabled.
14280
 
14281
For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
14282
64-bit code, then we can use both FP pipes.  Otherwise, we can only use one
14283
FP pipe.
14284
 
14285
@item -mvr4130-align
14286
@itemx -mno-vr4130-align
14287
@opindex mvr4130-align
14288
The VR4130 pipeline is two-way superscalar, but can only issue two
14289
instructions together if the first one is 8-byte aligned.  When this
14290
option is enabled, GCC will align pairs of instructions that it
14291
thinks should execute in parallel.
14292
 
14293
This option only has an effect when optimizing for the VR4130.
14294
It normally makes code faster, but at the expense of making it bigger.
14295
It is enabled by default at optimization level @option{-O3}.
14296
 
14297
@item -msynci
14298
@itemx -mno-synci
14299
@opindex msynci
14300
Enable (disable) generation of @code{synci} instructions on
14301
architectures that support it.  The @code{synci} instructions (if
14302
enabled) will be generated when @code{__builtin___clear_cache()} is
14303
compiled.
14304
 
14305
This option defaults to @code{-mno-synci}, but the default can be
14306
overridden by configuring with @code{--with-synci}.
14307
 
14308
When compiling code for single processor systems, it is generally safe
14309
to use @code{synci}.  However, on many multi-core (SMP) systems, it
14310
will not invalidate the instruction caches on all cores and may lead
14311
to undefined behavior.
14312
 
14313
@item -mrelax-pic-calls
14314
@itemx -mno-relax-pic-calls
14315
@opindex mrelax-pic-calls
14316
Try to turn PIC calls that are normally dispatched via register
14317
@code{$25} into direct calls.  This is only possible if the linker can
14318
resolve the destination at link-time and if the destination is within
14319
range for a direct call.
14320
 
14321
@option{-mrelax-pic-calls} is the default if GCC was configured to use
14322
an assembler and a linker that supports the @code{.reloc} assembly
14323
directive and @code{-mexplicit-relocs} is in effect.  With
14324
@code{-mno-explicit-relocs}, this optimization can be performed by the
14325
assembler and the linker alone without help from the compiler.
14326
 
14327
@item -mmcount-ra-address
14328
@itemx -mno-mcount-ra-address
14329
@opindex mmcount-ra-address
14330
@opindex mno-mcount-ra-address
14331
Emit (do not emit) code that allows @code{_mcount} to modify the
14332
calling function's return address.  When enabled, this option extends
14333
the usual @code{_mcount} interface with a new @var{ra-address}
14334
parameter, which has type @code{intptr_t *} and is passed in register
14335
@code{$12}.  @code{_mcount} can then modify the return address by
14336
doing both of the following:
14337
@itemize
14338
@item
14339
Returning the new address in register @code{$31}.
14340
@item
14341
Storing the new address in @code{*@var{ra-address}},
14342
if @var{ra-address} is nonnull.
14343
@end itemize
14344
 
14345
The default is @option{-mno-mcount-ra-address}.
14346
 
14347
@end table
14348
 
14349
@node MMIX Options
14350
@subsection MMIX Options
14351
@cindex MMIX Options
14352
 
14353
These options are defined for the MMIX:
14354
 
14355
@table @gcctabopt
14356
@item -mlibfuncs
14357
@itemx -mno-libfuncs
14358
@opindex mlibfuncs
14359
@opindex mno-libfuncs
14360
Specify that intrinsic library functions are being compiled, passing all
14361
values in registers, no matter the size.
14362
 
14363
@item -mepsilon
14364
@itemx -mno-epsilon
14365
@opindex mepsilon
14366
@opindex mno-epsilon
14367
Generate floating-point comparison instructions that compare with respect
14368
to the @code{rE} epsilon register.
14369
 
14370
@item -mabi=mmixware
14371
@itemx -mabi=gnu
14372
@opindex mabi=mmixware
14373
@opindex mabi=gnu
14374
Generate code that passes function parameters and return values that (in
14375
the called function) are seen as registers @code{$0} and up, as opposed to
14376
the GNU ABI which uses global registers @code{$231} and up.
14377
 
14378
@item -mzero-extend
14379
@itemx -mno-zero-extend
14380
@opindex mzero-extend
14381
@opindex mno-zero-extend
14382
When reading data from memory in sizes shorter than 64 bits, use (do not
14383
use) zero-extending load instructions by default, rather than
14384
sign-extending ones.
14385
 
14386
@item -mknuthdiv
14387
@itemx -mno-knuthdiv
14388
@opindex mknuthdiv
14389
@opindex mno-knuthdiv
14390
Make the result of a division yielding a remainder have the same sign as
14391
the divisor.  With the default, @option{-mno-knuthdiv}, the sign of the
14392
remainder follows the sign of the dividend.  Both methods are
14393
arithmetically valid, the latter being almost exclusively used.
14394
 
14395
@item -mtoplevel-symbols
14396
@itemx -mno-toplevel-symbols
14397
@opindex mtoplevel-symbols
14398
@opindex mno-toplevel-symbols
14399
Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
14400
code can be used with the @code{PREFIX} assembly directive.
14401
 
14402
@item -melf
14403
@opindex melf
14404
Generate an executable in the ELF format, rather than the default
14405
@samp{mmo} format used by the @command{mmix} simulator.
14406
 
14407
@item -mbranch-predict
14408
@itemx -mno-branch-predict
14409
@opindex mbranch-predict
14410
@opindex mno-branch-predict
14411
Use (do not use) the probable-branch instructions, when static branch
14412
prediction indicates a probable branch.
14413
 
14414
@item -mbase-addresses
14415
@itemx -mno-base-addresses
14416
@opindex mbase-addresses
14417
@opindex mno-base-addresses
14418
Generate (do not generate) code that uses @emph{base addresses}.  Using a
14419
base address automatically generates a request (handled by the assembler
14420
and the linker) for a constant to be set up in a global register.  The
14421
register is used for one or more base address requests within the range 0
14422
to 255 from the value held in the register.  The generally leads to short
14423
and fast code, but the number of different data items that can be
14424
addressed is limited.  This means that a program that uses lots of static
14425
data may require @option{-mno-base-addresses}.
14426
 
14427
@item -msingle-exit
14428
@itemx -mno-single-exit
14429
@opindex msingle-exit
14430
@opindex mno-single-exit
14431
Force (do not force) generated code to have a single exit point in each
14432
function.
14433
@end table
14434
 
14435
@node MN10300 Options
14436
@subsection MN10300 Options
14437
@cindex MN10300 options
14438
 
14439
These @option{-m} options are defined for Matsushita MN10300 architectures:
14440
 
14441
@table @gcctabopt
14442
@item -mmult-bug
14443
@opindex mmult-bug
14444
Generate code to avoid bugs in the multiply instructions for the MN10300
14445
processors.  This is the default.
14446
 
14447
@item -mno-mult-bug
14448
@opindex mno-mult-bug
14449
Do not generate code to avoid bugs in the multiply instructions for the
14450
MN10300 processors.
14451
 
14452
@item -mam33
14453
@opindex mam33
14454
Generate code which uses features specific to the AM33 processor.
14455
 
14456
@item -mno-am33
14457
@opindex mno-am33
14458
Do not generate code which uses features specific to the AM33 processor.  This
14459
is the default.
14460
 
14461
@item -mreturn-pointer-on-d0
14462
@opindex mreturn-pointer-on-d0
14463
When generating a function which returns a pointer, return the pointer
14464
in both @code{a0} and @code{d0}.  Otherwise, the pointer is returned
14465
only in a0, and attempts to call such functions without a prototype
14466
would result in errors.  Note that this option is on by default; use
14467
@option{-mno-return-pointer-on-d0} to disable it.
14468
 
14469
@item -mno-crt0
14470
@opindex mno-crt0
14471
Do not link in the C run-time initialization object file.
14472
 
14473
@item -mrelax
14474
@opindex mrelax
14475
Indicate to the linker that it should perform a relaxation optimization pass
14476
to shorten branches, calls and absolute memory addresses.  This option only
14477
has an effect when used on the command line for the final link step.
14478
 
14479
This option makes symbolic debugging impossible.
14480
@end table
14481
 
14482
@node PDP-11 Options
14483
@subsection PDP-11 Options
14484
@cindex PDP-11 Options
14485
 
14486
These options are defined for the PDP-11:
14487
 
14488
@table @gcctabopt
14489
@item -mfpu
14490
@opindex mfpu
14491
Use hardware FPP floating point.  This is the default.  (FIS floating
14492
point on the PDP-11/40 is not supported.)
14493
 
14494
@item -msoft-float
14495
@opindex msoft-float
14496
Do not use hardware floating point.
14497
 
14498
@item -mac0
14499
@opindex mac0
14500
Return floating-point results in ac0 (fr0 in Unix assembler syntax).
14501
 
14502
@item -mno-ac0
14503
@opindex mno-ac0
14504
Return floating-point results in memory.  This is the default.
14505
 
14506
@item -m40
14507
@opindex m40
14508
Generate code for a PDP-11/40.
14509
 
14510
@item -m45
14511
@opindex m45
14512
Generate code for a PDP-11/45.  This is the default.
14513
 
14514
@item -m10
14515
@opindex m10
14516
Generate code for a PDP-11/10.
14517
 
14518
@item -mbcopy-builtin
14519
@opindex mbcopy-builtin
14520
Use inline @code{movmemhi} patterns for copying memory.  This is the
14521
default.
14522
 
14523
@item -mbcopy
14524
@opindex mbcopy
14525
Do not use inline @code{movmemhi} patterns for copying memory.
14526
 
14527
@item -mint16
14528
@itemx -mno-int32
14529
@opindex mint16
14530
@opindex mno-int32
14531
Use 16-bit @code{int}.  This is the default.
14532
 
14533
@item -mint32
14534
@itemx -mno-int16
14535
@opindex mint32
14536
@opindex mno-int16
14537
Use 32-bit @code{int}.
14538
 
14539
@item -mfloat64
14540
@itemx -mno-float32
14541
@opindex mfloat64
14542
@opindex mno-float32
14543
Use 64-bit @code{float}.  This is the default.
14544
 
14545
@item -mfloat32
14546
@itemx -mno-float64
14547
@opindex mfloat32
14548
@opindex mno-float64
14549
Use 32-bit @code{float}.
14550
 
14551
@item -mabshi
14552
@opindex mabshi
14553
Use @code{abshi2} pattern.  This is the default.
14554
 
14555
@item -mno-abshi
14556
@opindex mno-abshi
14557
Do not use @code{abshi2} pattern.
14558
 
14559
@item -mbranch-expensive
14560
@opindex mbranch-expensive
14561
Pretend that branches are expensive.  This is for experimenting with
14562
code generation only.
14563
 
14564
@item -mbranch-cheap
14565
@opindex mbranch-cheap
14566
Do not pretend that branches are expensive.  This is the default.
14567
 
14568
@item -msplit
14569
@opindex msplit
14570
Generate code for a system with split I&D@.
14571
 
14572
@item -mno-split
14573
@opindex mno-split
14574
Generate code for a system without split I&D@.  This is the default.
14575
 
14576
@item -munix-asm
14577
@opindex munix-asm
14578
Use Unix assembler syntax.  This is the default when configured for
14579
@samp{pdp11-*-bsd}.
14580
 
14581
@item -mdec-asm
14582
@opindex mdec-asm
14583
Use DEC assembler syntax.  This is the default when configured for any
14584
PDP-11 target other than @samp{pdp11-*-bsd}.
14585
@end table
14586
 
14587
@node picoChip Options
14588
@subsection picoChip Options
14589
@cindex picoChip options
14590
 
14591
These @samp{-m} options are defined for picoChip implementations:
14592
 
14593
@table @gcctabopt
14594
 
14595
@item -mae=@var{ae_type}
14596
@opindex mcpu
14597
Set the instruction set, register set, and instruction scheduling
14598
parameters for array element type @var{ae_type}.  Supported values
14599
for @var{ae_type} are @samp{ANY}, @samp{MUL}, and @samp{MAC}.
14600
 
14601
@option{-mae=ANY} selects a completely generic AE type.  Code
14602
generated with this option will run on any of the other AE types.  The
14603
code will not be as efficient as it would be if compiled for a specific
14604
AE type, and some types of operation (e.g., multiplication) will not
14605
work properly on all types of AE.
14606
 
14607
@option{-mae=MUL} selects a MUL AE type.  This is the most useful AE type
14608
for compiled code, and is the default.
14609
 
14610
@option{-mae=MAC} selects a DSP-style MAC AE.  Code compiled with this
14611
option may suffer from poor performance of byte (char) manipulation,
14612
since the DSP AE does not provide hardware support for byte load/stores.
14613
 
14614
@item -msymbol-as-address
14615
Enable the compiler to directly use a symbol name as an address in a
14616
load/store instruction, without first loading it into a
14617
register.  Typically, the use of this option will generate larger
14618
programs, which run faster than when the option isn't used.  However, the
14619
results vary from program to program, so it is left as a user option,
14620
rather than being permanently enabled.
14621
 
14622
@item -mno-inefficient-warnings
14623
Disables warnings about the generation of inefficient code.  These
14624
warnings can be generated, for example, when compiling code which
14625
performs byte-level memory operations on the MAC AE type.  The MAC AE has
14626
no hardware support for byte-level memory operations, so all byte
14627
load/stores must be synthesized from word load/store operations.  This is
14628
inefficient and a warning will be generated indicating to the programmer
14629
that they should rewrite the code to avoid byte operations, or to target
14630
an AE type which has the necessary hardware support.  This option enables
14631
the warning to be turned off.
14632
 
14633
@end table
14634
 
14635
@node PowerPC Options
14636
@subsection PowerPC Options
14637
@cindex PowerPC options
14638
 
14639
These are listed under @xref{RS/6000 and PowerPC Options}.
14640
 
14641
@node RS/6000 and PowerPC Options
14642
@subsection IBM RS/6000 and PowerPC Options
14643
@cindex RS/6000 and PowerPC Options
14644
@cindex IBM RS/6000 and PowerPC Options
14645
 
14646
These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
14647
@table @gcctabopt
14648
@item -mpower
14649
@itemx -mno-power
14650
@itemx -mpower2
14651
@itemx -mno-power2
14652
@itemx -mpowerpc
14653
@itemx -mno-powerpc
14654
@itemx -mpowerpc-gpopt
14655
@itemx -mno-powerpc-gpopt
14656
@itemx -mpowerpc-gfxopt
14657
@itemx -mno-powerpc-gfxopt
14658
@itemx -mpowerpc64
14659
@itemx -mno-powerpc64
14660
@itemx -mmfcrf
14661
@itemx -mno-mfcrf
14662
@itemx -mpopcntb
14663
@itemx -mno-popcntb
14664
@itemx -mpopcntd
14665
@itemx -mno-popcntd
14666
@itemx -mfprnd
14667
@itemx -mno-fprnd
14668
@itemx -mcmpb
14669
@itemx -mno-cmpb
14670
@itemx -mmfpgpr
14671
@itemx -mno-mfpgpr
14672
@itemx -mhard-dfp
14673
@itemx -mno-hard-dfp
14674
@opindex mpower
14675
@opindex mno-power
14676
@opindex mpower2
14677
@opindex mno-power2
14678
@opindex mpowerpc
14679
@opindex mno-powerpc
14680
@opindex mpowerpc-gpopt
14681
@opindex mno-powerpc-gpopt
14682
@opindex mpowerpc-gfxopt
14683
@opindex mno-powerpc-gfxopt
14684
@opindex mpowerpc64
14685
@opindex mno-powerpc64
14686
@opindex mmfcrf
14687
@opindex mno-mfcrf
14688
@opindex mpopcntb
14689
@opindex mno-popcntb
14690
@opindex mpopcntd
14691
@opindex mno-popcntd
14692
@opindex mfprnd
14693
@opindex mno-fprnd
14694
@opindex mcmpb
14695
@opindex mno-cmpb
14696
@opindex mmfpgpr
14697
@opindex mno-mfpgpr
14698
@opindex mhard-dfp
14699
@opindex mno-hard-dfp
14700
GCC supports two related instruction set architectures for the
14701
RS/6000 and PowerPC@.  The @dfn{POWER} instruction set are those
14702
instructions supported by the @samp{rios} chip set used in the original
14703
RS/6000 systems and the @dfn{PowerPC} instruction set is the
14704
architecture of the Freescale MPC5xx, MPC6xx, MPC8xx microprocessors, and
14705
the IBM 4xx, 6xx, and follow-on microprocessors.
14706
 
14707
Neither architecture is a subset of the other.  However there is a
14708
large common subset of instructions supported by both.  An MQ
14709
register is included in processors supporting the POWER architecture.
14710
 
14711
You use these options to specify which instructions are available on the
14712
processor you are using.  The default value of these options is
14713
determined when configuring GCC@.  Specifying the
14714
@option{-mcpu=@var{cpu_type}} overrides the specification of these
14715
options.  We recommend you use the @option{-mcpu=@var{cpu_type}} option
14716
rather than the options listed above.
14717
 
14718
The @option{-mpower} option allows GCC to generate instructions that
14719
are found only in the POWER architecture and to use the MQ register.
14720
Specifying @option{-mpower2} implies @option{-power} and also allows GCC
14721
to generate instructions that are present in the POWER2 architecture but
14722
not the original POWER architecture.
14723
 
14724
The @option{-mpowerpc} option allows GCC to generate instructions that
14725
are found only in the 32-bit subset of the PowerPC architecture.
14726
Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
14727
GCC to use the optional PowerPC architecture instructions in the
14728
General Purpose group, including floating-point square root.  Specifying
14729
@option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
14730
use the optional PowerPC architecture instructions in the Graphics
14731
group, including floating-point select.
14732
 
14733
The @option{-mmfcrf} option allows GCC to generate the move from
14734
condition register field instruction implemented on the POWER4
14735
processor and other processors that support the PowerPC V2.01
14736
architecture.
14737
The @option{-mpopcntb} option allows GCC to generate the popcount and
14738
double precision FP reciprocal estimate instruction implemented on the
14739
POWER5 processor and other processors that support the PowerPC V2.02
14740
architecture.
14741
The @option{-mpopcntd} option allows GCC to generate the popcount
14742
instruction implemented on the POWER7 processor and other processors
14743
that support the PowerPC V2.06 architecture.
14744
The @option{-mfprnd} option allows GCC to generate the FP round to
14745
integer instructions implemented on the POWER5+ processor and other
14746
processors that support the PowerPC V2.03 architecture.
14747
The @option{-mcmpb} option allows GCC to generate the compare bytes
14748
instruction implemented on the POWER6 processor and other processors
14749
that support the PowerPC V2.05 architecture.
14750
The @option{-mmfpgpr} option allows GCC to generate the FP move to/from
14751
general purpose register instructions implemented on the POWER6X
14752
processor and other processors that support the extended PowerPC V2.05
14753
architecture.
14754
The @option{-mhard-dfp} option allows GCC to generate the decimal floating
14755
point instructions implemented on some POWER processors.
14756
 
14757
The @option{-mpowerpc64} option allows GCC to generate the additional
14758
64-bit instructions that are found in the full PowerPC64 architecture
14759
and to treat GPRs as 64-bit, doubleword quantities.  GCC defaults to
14760
@option{-mno-powerpc64}.
14761
 
14762
If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
14763
will use only the instructions in the common subset of both
14764
architectures plus some special AIX common-mode calls, and will not use
14765
the MQ register.  Specifying both @option{-mpower} and @option{-mpowerpc}
14766
permits GCC to use any instruction from either architecture and to
14767
allow use of the MQ register; specify this for the Motorola MPC601.
14768
 
14769
@item -mnew-mnemonics
14770
@itemx -mold-mnemonics
14771
@opindex mnew-mnemonics
14772
@opindex mold-mnemonics
14773
Select which mnemonics to use in the generated assembler code.  With
14774
@option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
14775
the PowerPC architecture.  With @option{-mold-mnemonics} it uses the
14776
assembler mnemonics defined for the POWER architecture.  Instructions
14777
defined in only one architecture have only one mnemonic; GCC uses that
14778
mnemonic irrespective of which of these options is specified.
14779
 
14780
GCC defaults to the mnemonics appropriate for the architecture in
14781
use.  Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
14782
value of these option.  Unless you are building a cross-compiler, you
14783
should normally not specify either @option{-mnew-mnemonics} or
14784
@option{-mold-mnemonics}, but should instead accept the default.
14785
 
14786
@item -mcpu=@var{cpu_type}
14787
@opindex mcpu
14788
Set architecture type, register usage, choice of mnemonics, and
14789
instruction scheduling parameters for machine type @var{cpu_type}.
14790
Supported values for @var{cpu_type} are @samp{401}, @samp{403},
14791
@samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{464}, @samp{464fp},
14792
@samp{476}, @samp{476fp}, @samp{505}, @samp{601}, @samp{602}, @samp{603},
14793
@samp{603e}, @samp{604}, @samp{604e}, @samp{620}, @samp{630}, @samp{740},
14794
@samp{7400}, @samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
14795
@samp{860}, @samp{970}, @samp{8540}, @samp{a2}, @samp{e300c2},
14796
@samp{e300c3}, @samp{e500mc}, @samp{e500mc64}, @samp{ec603e}, @samp{G3},
14797
@samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3},
14798
@samp{power4}, @samp{power5}, @samp{power5+}, @samp{power6}, @samp{power6x},
14799
@samp{power7}, @samp{common}, @samp{powerpc}, @samp{powerpc64}, @samp{rios},
14800
@samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64}.
14801
 
14802
@option{-mcpu=common} selects a completely generic processor.  Code
14803
generated under this option will run on any POWER or PowerPC processor.
14804
GCC will use only the instructions in the common subset of both
14805
architectures, and will not use the MQ register.  GCC assumes a generic
14806
processor model for scheduling purposes.
14807
 
14808
@option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
14809
@option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
14810
PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
14811
types, with an appropriate, generic processor model assumed for
14812
scheduling purposes.
14813
 
14814
The other options specify a specific processor.  Code generated under
14815
those options will run best on that processor, and may not run at all on
14816
others.
14817
 
14818
The @option{-mcpu} options automatically enable or disable the
14819
following options:
14820
 
14821
@gccoptlist{-maltivec  -mfprnd  -mhard-float  -mmfcrf  -mmultiple @gol
14822
-mnew-mnemonics  -mpopcntb -mpopcntd  -mpower  -mpower2  -mpowerpc64 @gol
14823
-mpowerpc-gpopt  -mpowerpc-gfxopt  -msingle-float -mdouble-float @gol
14824
-msimple-fpu -mstring  -mmulhw  -mdlmzb  -mmfpgpr -mvsx}
14825
 
14826
The particular options set for any particular CPU will vary between
14827
compiler versions, depending on what setting seems to produce optimal
14828
code for that CPU; it doesn't necessarily reflect the actual hardware's
14829
capabilities.  If you wish to set an individual option to a particular
14830
value, you may specify it after the @option{-mcpu} option, like
14831
@samp{-mcpu=970 -mno-altivec}.
14832
 
14833
On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
14834
not enabled or disabled by the @option{-mcpu} option at present because
14835
AIX does not have full support for these options.  You may still
14836
enable or disable them individually if you're sure it'll work in your
14837
environment.
14838
 
14839
@item -mtune=@var{cpu_type}
14840
@opindex mtune
14841
Set the instruction scheduling parameters for machine type
14842
@var{cpu_type}, but do not set the architecture type, register usage, or
14843
choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would.  The same
14844
values for @var{cpu_type} are used for @option{-mtune} as for
14845
@option{-mcpu}.  If both are specified, the code generated will use the
14846
architecture, registers, and mnemonics set by @option{-mcpu}, but the
14847
scheduling parameters set by @option{-mtune}.
14848
 
14849
@item -mswdiv
14850
@itemx -mno-swdiv
14851
@opindex mswdiv
14852
@opindex mno-swdiv
14853
Generate code to compute division as reciprocal estimate and iterative
14854
refinement, creating opportunities for increased throughput.  This
14855
feature requires: optional PowerPC Graphics instruction set for single
14856
precision and FRE instruction for double precision, assuming divides
14857
cannot generate user-visible traps, and the domain values not include
14858
Infinities, denormals or zero denominator.
14859
 
14860
@item -maltivec
14861
@itemx -mno-altivec
14862
@opindex maltivec
14863
@opindex mno-altivec
14864
Generate code that uses (does not use) AltiVec instructions, and also
14865
enable the use of built-in functions that allow more direct access to
14866
the AltiVec instruction set.  You may also need to set
14867
@option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
14868
enhancements.
14869
 
14870
@item -mvrsave
14871
@itemx -mno-vrsave
14872
@opindex mvrsave
14873
@opindex mno-vrsave
14874
Generate VRSAVE instructions when generating AltiVec code.
14875
 
14876
@item -mgen-cell-microcode
14877
@opindex mgen-cell-microcode
14878
Generate Cell microcode instructions
14879
 
14880
@item -mwarn-cell-microcode
14881
@opindex mwarn-cell-microcode
14882
Warning when a Cell microcode instruction is going to emitted.  An example
14883
of a Cell microcode instruction is a variable shift.
14884
 
14885
@item -msecure-plt
14886
@opindex msecure-plt
14887
Generate code that allows ld and ld.so to build executables and shared
14888
libraries with non-exec .plt and .got sections.  This is a PowerPC
14889
32-bit SYSV ABI option.
14890
 
14891
@item -mbss-plt
14892
@opindex mbss-plt
14893
Generate code that uses a BSS .plt section that ld.so fills in, and
14894
requires .plt and .got sections that are both writable and executable.
14895
This is a PowerPC 32-bit SYSV ABI option.
14896
 
14897
@item -misel
14898
@itemx -mno-isel
14899
@opindex misel
14900
@opindex mno-isel
14901
This switch enables or disables the generation of ISEL instructions.
14902
 
14903
@item -misel=@var{yes/no}
14904
This switch has been deprecated.  Use @option{-misel} and
14905
@option{-mno-isel} instead.
14906
 
14907
@item -mspe
14908
@itemx -mno-spe
14909
@opindex mspe
14910
@opindex mno-spe
14911
This switch enables or disables the generation of SPE simd
14912
instructions.
14913
 
14914
@item -mpaired
14915
@itemx -mno-paired
14916
@opindex mpaired
14917
@opindex mno-paired
14918
This switch enables or disables the generation of PAIRED simd
14919
instructions.
14920
 
14921
@item -mspe=@var{yes/no}
14922
This option has been deprecated.  Use @option{-mspe} and
14923
@option{-mno-spe} instead.
14924
 
14925
@item -mvsx
14926
@itemx -mno-vsx
14927
@opindex mvsx
14928
@opindex mno-vsx
14929
Generate code that uses (does not use) vector/scalar (VSX)
14930
instructions, and also enable the use of built-in functions that allow
14931
more direct access to the VSX instruction set.
14932
 
14933
@item -mfloat-gprs=@var{yes/single/double/no}
14934
@itemx -mfloat-gprs
14935
@opindex mfloat-gprs
14936
This switch enables or disables the generation of floating point
14937
operations on the general purpose registers for architectures that
14938
support it.
14939
 
14940
The argument @var{yes} or @var{single} enables the use of
14941
single-precision floating point operations.
14942
 
14943
The argument @var{double} enables the use of single and
14944
double-precision floating point operations.
14945
 
14946
The argument @var{no} disables floating point operations on the
14947
general purpose registers.
14948
 
14949
This option is currently only available on the MPC854x.
14950
 
14951
@item -m32
14952
@itemx -m64
14953
@opindex m32
14954
@opindex m64
14955
Generate code for 32-bit or 64-bit environments of Darwin and SVR4
14956
targets (including GNU/Linux).  The 32-bit environment sets int, long
14957
and pointer to 32 bits and generates code that runs on any PowerPC
14958
variant.  The 64-bit environment sets int to 32 bits and long and
14959
pointer to 64 bits, and generates code for PowerPC64, as for
14960
@option{-mpowerpc64}.
14961
 
14962
@item -mfull-toc
14963
@itemx -mno-fp-in-toc
14964
@itemx -mno-sum-in-toc
14965
@itemx -mminimal-toc
14966
@opindex mfull-toc
14967
@opindex mno-fp-in-toc
14968
@opindex mno-sum-in-toc
14969
@opindex mminimal-toc
14970
Modify generation of the TOC (Table Of Contents), which is created for
14971
every executable file.  The @option{-mfull-toc} option is selected by
14972
default.  In that case, GCC will allocate at least one TOC entry for
14973
each unique non-automatic variable reference in your program.  GCC
14974
will also place floating-point constants in the TOC@.  However, only
14975
16,384 entries are available in the TOC@.
14976
 
14977
If you receive a linker error message that saying you have overflowed
14978
the available TOC space, you can reduce the amount of TOC space used
14979
with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
14980
@option{-mno-fp-in-toc} prevents GCC from putting floating-point
14981
constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
14982
generate code to calculate the sum of an address and a constant at
14983
run-time instead of putting that sum into the TOC@.  You may specify one
14984
or both of these options.  Each causes GCC to produce very slightly
14985
slower and larger code at the expense of conserving TOC space.
14986
 
14987
If you still run out of space in the TOC even when you specify both of
14988
these options, specify @option{-mminimal-toc} instead.  This option causes
14989
GCC to make only one TOC entry for every file.  When you specify this
14990
option, GCC will produce code that is slower and larger but which
14991
uses extremely little TOC space.  You may wish to use this option
14992
only on files that contain less frequently executed code.
14993
 
14994
@item -maix64
14995
@itemx -maix32
14996
@opindex maix64
14997
@opindex maix32
14998
Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
14999
@code{long} type, and the infrastructure needed to support them.
15000
Specifying @option{-maix64} implies @option{-mpowerpc64} and
15001
@option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
15002
implies @option{-mno-powerpc64}.  GCC defaults to @option{-maix32}.
15003
 
15004
@item -mxl-compat
15005
@itemx -mno-xl-compat
15006
@opindex mxl-compat
15007
@opindex mno-xl-compat
15008
Produce code that conforms more closely to IBM XL compiler semantics
15009
when using AIX-compatible ABI@.  Pass floating-point arguments to
15010
prototyped functions beyond the register save area (RSA) on the stack
15011
in addition to argument FPRs.  Do not assume that most significant
15012
double in 128-bit long double value is properly rounded when comparing
15013
values and converting to double.  Use XL symbol names for long double
15014
support routines.
15015
 
15016
The AIX calling convention was extended but not initially documented to
15017
handle an obscure K&R C case of calling a function that takes the
15018
address of its arguments with fewer arguments than declared.  IBM XL
15019
compilers access floating point arguments which do not fit in the
15020
RSA from the stack when a subroutine is compiled without
15021
optimization.  Because always storing floating-point arguments on the
15022
stack is inefficient and rarely needed, this option is not enabled by
15023
default and only is necessary when calling subroutines compiled by IBM
15024
XL compilers without optimization.
15025
 
15026
@item -mpe
15027
@opindex mpe
15028
Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@.  Link an
15029
application written to use message passing with special startup code to
15030
enable the application to run.  The system must have PE installed in the
15031
standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
15032
must be overridden with the @option{-specs=} option to specify the
15033
appropriate directory location.  The Parallel Environment does not
15034
support threads, so the @option{-mpe} option and the @option{-pthread}
15035
option are incompatible.
15036
 
15037
@item -malign-natural
15038
@itemx -malign-power
15039
@opindex malign-natural
15040
@opindex malign-power
15041
On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
15042
@option{-malign-natural} overrides the ABI-defined alignment of larger
15043
types, such as floating-point doubles, on their natural size-based boundary.
15044
The option @option{-malign-power} instructs GCC to follow the ABI-specified
15045
alignment rules.  GCC defaults to the standard alignment defined in the ABI@.
15046
 
15047
On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
15048
is not supported.
15049
 
15050
@item -msoft-float
15051
@itemx -mhard-float
15052
@opindex msoft-float
15053
@opindex mhard-float
15054
Generate code that does not use (uses) the floating-point register set.
15055
Software floating point emulation is provided if you use the
15056
@option{-msoft-float} option, and pass the option to GCC when linking.
15057
 
15058
@item -msingle-float
15059
@itemx -mdouble-float
15060
@opindex msingle-float
15061
@opindex mdouble-float
15062
Generate code for single or double-precision floating point operations.
15063
@option{-mdouble-float} implies @option{-msingle-float}.
15064
 
15065
@item -msimple-fpu
15066
@opindex msimple-fpu
15067
Do not generate sqrt and div instructions for hardware floating point unit.
15068
 
15069
@item -mfpu
15070
@opindex mfpu
15071
Specify type of floating point unit.  Valid values are @var{sp_lite}
15072
(equivalent to -msingle-float -msimple-fpu), @var{dp_lite} (equivalent
15073
to -mdouble-float -msimple-fpu), @var{sp_full} (equivalent to -msingle-float),
15074
and @var{dp_full} (equivalent to -mdouble-float).
15075
 
15076
@item -mxilinx-fpu
15077
@opindex mxilinx-fpu
15078
Perform optimizations for floating point unit on Xilinx PPC 405/440.
15079
 
15080
@item -mmultiple
15081
@itemx -mno-multiple
15082
@opindex mmultiple
15083
@opindex mno-multiple
15084
Generate code that uses (does not use) the load multiple word
15085
instructions and the store multiple word instructions.  These
15086
instructions are generated by default on POWER systems, and not
15087
generated on PowerPC systems.  Do not use @option{-mmultiple} on little
15088
endian PowerPC systems, since those instructions do not work when the
15089
processor is in little endian mode.  The exceptions are PPC740 and
15090
PPC750 which permit the instructions usage in little endian mode.
15091
 
15092
@item -mstring
15093
@itemx -mno-string
15094
@opindex mstring
15095
@opindex mno-string
15096
Generate code that uses (does not use) the load string instructions
15097
and the store string word instructions to save multiple registers and
15098
do small block moves.  These instructions are generated by default on
15099
POWER systems, and not generated on PowerPC systems.  Do not use
15100
@option{-mstring} on little endian PowerPC systems, since those
15101
instructions do not work when the processor is in little endian mode.
15102
The exceptions are PPC740 and PPC750 which permit the instructions
15103
usage in little endian mode.
15104
 
15105
@item -mupdate
15106
@itemx -mno-update
15107
@opindex mupdate
15108
@opindex mno-update
15109
Generate code that uses (does not use) the load or store instructions
15110
that update the base register to the address of the calculated memory
15111
location.  These instructions are generated by default.  If you use
15112
@option{-mno-update}, there is a small window between the time that the
15113
stack pointer is updated and the address of the previous frame is
15114
stored, which means code that walks the stack frame across interrupts or
15115
signals may get corrupted data.
15116
 
15117
@item -mavoid-indexed-addresses
15118
@itemx -mno-avoid-indexed-addresses
15119
@opindex mavoid-indexed-addresses
15120
@opindex mno-avoid-indexed-addresses
15121
Generate code that tries to avoid (not avoid) the use of indexed load
15122
or store instructions. These instructions can incur a performance
15123
penalty on Power6 processors in certain situations, such as when
15124
stepping through large arrays that cross a 16M boundary.  This option
15125
is enabled by default when targetting Power6 and disabled otherwise.
15126
 
15127
@item -mfused-madd
15128
@itemx -mno-fused-madd
15129
@opindex mfused-madd
15130
@opindex mno-fused-madd
15131
Generate code that uses (does not use) the floating point multiply and
15132
accumulate instructions.  These instructions are generated by default if
15133
hardware floating is used.
15134
 
15135
@item -mmulhw
15136
@itemx -mno-mulhw
15137
@opindex mmulhw
15138
@opindex mno-mulhw
15139
Generate code that uses (does not use) the half-word multiply and
15140
multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
15141
These instructions are generated by default when targetting those
15142
processors.
15143
 
15144
@item -mdlmzb
15145
@itemx -mno-dlmzb
15146
@opindex mdlmzb
15147
@opindex mno-dlmzb
15148
Generate code that uses (does not use) the string-search @samp{dlmzb}
15149
instruction on the IBM 405, 440, 464 and 476 processors.  This instruction is
15150
generated by default when targetting those processors.
15151
 
15152
@item -mno-bit-align
15153
@itemx -mbit-align
15154
@opindex mno-bit-align
15155
@opindex mbit-align
15156
On System V.4 and embedded PowerPC systems do not (do) force structures
15157
and unions that contain bit-fields to be aligned to the base type of the
15158
bit-field.
15159
 
15160
For example, by default a structure containing nothing but 8
15161
@code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
15162
boundary and have a size of 4 bytes.  By using @option{-mno-bit-align},
15163
the structure would be aligned to a 1 byte boundary and be one byte in
15164
size.
15165
 
15166
@item -mno-strict-align
15167
@itemx -mstrict-align
15168
@opindex mno-strict-align
15169
@opindex mstrict-align
15170
On System V.4 and embedded PowerPC systems do not (do) assume that
15171
unaligned memory references will be handled by the system.
15172
 
15173
@item -mrelocatable
15174
@itemx -mno-relocatable
15175
@opindex mrelocatable
15176
@opindex mno-relocatable
15177
On embedded PowerPC systems generate code that allows (does not allow)
15178
the program to be relocated to a different address at runtime.  If you
15179
use @option{-mrelocatable} on any module, all objects linked together must
15180
be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
15181
 
15182
@item -mrelocatable-lib
15183
@itemx -mno-relocatable-lib
15184
@opindex mrelocatable-lib
15185
@opindex mno-relocatable-lib
15186
On embedded PowerPC systems generate code that allows (does not allow)
15187
the program to be relocated to a different address at runtime.  Modules
15188
compiled with @option{-mrelocatable-lib} can be linked with either modules
15189
compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
15190
with modules compiled with the @option{-mrelocatable} options.
15191
 
15192
@item -mno-toc
15193
@itemx -mtoc
15194
@opindex mno-toc
15195
@opindex mtoc
15196
On System V.4 and embedded PowerPC systems do not (do) assume that
15197
register 2 contains a pointer to a global area pointing to the addresses
15198
used in the program.
15199
 
15200
@item -mlittle
15201
@itemx -mlittle-endian
15202
@opindex mlittle
15203
@opindex mlittle-endian
15204
On System V.4 and embedded PowerPC systems compile code for the
15205
processor in little endian mode.  The @option{-mlittle-endian} option is
15206
the same as @option{-mlittle}.
15207
 
15208
@item -mbig
15209
@itemx -mbig-endian
15210
@opindex mbig
15211
@opindex mbig-endian
15212
On System V.4 and embedded PowerPC systems compile code for the
15213
processor in big endian mode.  The @option{-mbig-endian} option is
15214
the same as @option{-mbig}.
15215
 
15216
@item -mdynamic-no-pic
15217
@opindex mdynamic-no-pic
15218
On Darwin and Mac OS X systems, compile code so that it is not
15219
relocatable, but that its external references are relocatable.  The
15220
resulting code is suitable for applications, but not shared
15221
libraries.
15222
 
15223
@item -mprioritize-restricted-insns=@var{priority}
15224
@opindex mprioritize-restricted-insns
15225
This option controls the priority that is assigned to
15226
dispatch-slot restricted instructions during the second scheduling
15227
pass.  The argument @var{priority} takes the value @var{0/1/2} to assign
15228
@var{no/highest/second-highest} priority to dispatch slot restricted
15229
instructions.
15230
 
15231
@item -msched-costly-dep=@var{dependence_type}
15232
@opindex msched-costly-dep
15233
This option controls which dependences are considered costly
15234
by the target during instruction scheduling.  The argument
15235
@var{dependence_type} takes one of the following values:
15236
@var{no}: no dependence is costly,
15237
@var{all}: all dependences are costly,
15238
@var{true_store_to_load}: a true dependence from store to load is costly,
15239
@var{store_to_load}: any dependence from store to load is costly,
15240
@var{number}: any dependence which latency >= @var{number} is costly.
15241
 
15242
@item -minsert-sched-nops=@var{scheme}
15243
@opindex minsert-sched-nops
15244
This option controls which nop insertion scheme will be used during
15245
the second scheduling pass.  The argument @var{scheme} takes one of the
15246
following values:
15247
@var{no}: Don't insert nops.
15248
@var{pad}: Pad with nops any dispatch group which has vacant issue slots,
15249
according to the scheduler's grouping.
15250
@var{regroup_exact}: Insert nops to force costly dependent insns into
15251
separate groups.  Insert exactly as many nops as needed to force an insn
15252
to a new group, according to the estimated processor grouping.
15253
@var{number}: Insert nops to force costly dependent insns into
15254
separate groups.  Insert @var{number} nops to force an insn to a new group.
15255
 
15256
@item -mcall-sysv
15257
@opindex mcall-sysv
15258
On System V.4 and embedded PowerPC systems compile code using calling
15259
conventions that adheres to the March 1995 draft of the System V
15260
Application Binary Interface, PowerPC processor supplement.  This is the
15261
default unless you configured GCC using @samp{powerpc-*-eabiaix}.
15262
 
15263
@item -mcall-sysv-eabi
15264
@itemx -mcall-eabi
15265
@opindex mcall-sysv-eabi
15266
@opindex mcall-eabi
15267
Specify both @option{-mcall-sysv} and @option{-meabi} options.
15268
 
15269
@item -mcall-sysv-noeabi
15270
@opindex mcall-sysv-noeabi
15271
Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
15272
 
15273
@item -mcall-aixdesc
15274
@opindex m
15275
On System V.4 and embedded PowerPC systems compile code for the AIX
15276
operating system.
15277
 
15278
@item -mcall-linux
15279
@opindex mcall-linux
15280
On System V.4 and embedded PowerPC systems compile code for the
15281
Linux-based GNU system.
15282
 
15283
@item -mcall-gnu
15284
@opindex mcall-gnu
15285
On System V.4 and embedded PowerPC systems compile code for the
15286
Hurd-based GNU system.
15287
 
15288
@item -mcall-freebsd
15289
@opindex mcall-freebsd
15290
On System V.4 and embedded PowerPC systems compile code for the
15291
FreeBSD operating system.
15292
 
15293
@item -mcall-netbsd
15294
@opindex mcall-netbsd
15295
On System V.4 and embedded PowerPC systems compile code for the
15296
NetBSD operating system.
15297
 
15298
@item -mcall-openbsd
15299
@opindex mcall-netbsd
15300
On System V.4 and embedded PowerPC systems compile code for the
15301
OpenBSD operating system.
15302
 
15303
@item -maix-struct-return
15304
@opindex maix-struct-return
15305
Return all structures in memory (as specified by the AIX ABI)@.
15306
 
15307
@item -msvr4-struct-return
15308
@opindex msvr4-struct-return
15309
Return structures smaller than 8 bytes in registers (as specified by the
15310
SVR4 ABI)@.
15311
 
15312
@item -mabi=@var{abi-type}
15313
@opindex mabi
15314
Extend the current ABI with a particular extension, or remove such extension.
15315
Valid values are @var{altivec}, @var{no-altivec}, @var{spe},
15316
@var{no-spe}, @var{ibmlongdouble}, @var{ieeelongdouble}@.
15317
 
15318
@item -mabi=spe
15319
@opindex mabi=spe
15320
Extend the current ABI with SPE ABI extensions.  This does not change
15321
the default ABI, instead it adds the SPE ABI extensions to the current
15322
ABI@.
15323
 
15324
@item -mabi=no-spe
15325
@opindex mabi=no-spe
15326
Disable Booke SPE ABI extensions for the current ABI@.
15327
 
15328
@item -mabi=ibmlongdouble
15329
@opindex mabi=ibmlongdouble
15330
Change the current ABI to use IBM extended precision long double.
15331
This is a PowerPC 32-bit SYSV ABI option.
15332
 
15333
@item -mabi=ieeelongdouble
15334
@opindex mabi=ieeelongdouble
15335
Change the current ABI to use IEEE extended precision long double.
15336
This is a PowerPC 32-bit Linux ABI option.
15337
 
15338
@item -mprototype
15339
@itemx -mno-prototype
15340
@opindex mprototype
15341
@opindex mno-prototype
15342
On System V.4 and embedded PowerPC systems assume that all calls to
15343
variable argument functions are properly prototyped.  Otherwise, the
15344
compiler must insert an instruction before every non prototyped call to
15345
set or clear bit 6 of the condition code register (@var{CR}) to
15346
indicate whether floating point values were passed in the floating point
15347
registers in case the function takes a variable arguments.  With
15348
@option{-mprototype}, only calls to prototyped variable argument functions
15349
will set or clear the bit.
15350
 
15351
@item -msim
15352
@opindex msim
15353
On embedded PowerPC systems, assume that the startup module is called
15354
@file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
15355
@file{libc.a}.  This is the default for @samp{powerpc-*-eabisim}
15356
configurations.
15357
 
15358
@item -mmvme
15359
@opindex mmvme
15360
On embedded PowerPC systems, assume that the startup module is called
15361
@file{crt0.o} and the standard C libraries are @file{libmvme.a} and
15362
@file{libc.a}.
15363
 
15364
@item -mads
15365
@opindex mads
15366
On embedded PowerPC systems, assume that the startup module is called
15367
@file{crt0.o} and the standard C libraries are @file{libads.a} and
15368
@file{libc.a}.
15369
 
15370
@item -myellowknife
15371
@opindex myellowknife
15372
On embedded PowerPC systems, assume that the startup module is called
15373
@file{crt0.o} and the standard C libraries are @file{libyk.a} and
15374
@file{libc.a}.
15375
 
15376
@item -mvxworks
15377
@opindex mvxworks
15378
On System V.4 and embedded PowerPC systems, specify that you are
15379
compiling for a VxWorks system.
15380
 
15381
@item -memb
15382
@opindex memb
15383
On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
15384
header to indicate that @samp{eabi} extended relocations are used.
15385
 
15386
@item -meabi
15387
@itemx -mno-eabi
15388
@opindex meabi
15389
@opindex mno-eabi
15390
On System V.4 and embedded PowerPC systems do (do not) adhere to the
15391
Embedded Applications Binary Interface (eabi) which is a set of
15392
modifications to the System V.4 specifications.  Selecting @option{-meabi}
15393
means that the stack is aligned to an 8 byte boundary, a function
15394
@code{__eabi} is called to from @code{main} to set up the eabi
15395
environment, and the @option{-msdata} option can use both @code{r2} and
15396
@code{r13} to point to two separate small data areas.  Selecting
15397
@option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
15398
do not call an initialization function from @code{main}, and the
15399
@option{-msdata} option will only use @code{r13} to point to a single
15400
small data area.  The @option{-meabi} option is on by default if you
15401
configured GCC using one of the @samp{powerpc*-*-eabi*} options.
15402
 
15403
@item -msdata=eabi
15404
@opindex msdata=eabi
15405
On System V.4 and embedded PowerPC systems, put small initialized
15406
@code{const} global and static data in the @samp{.sdata2} section, which
15407
is pointed to by register @code{r2}.  Put small initialized
15408
non-@code{const} global and static data in the @samp{.sdata} section,
15409
which is pointed to by register @code{r13}.  Put small uninitialized
15410
global and static data in the @samp{.sbss} section, which is adjacent to
15411
the @samp{.sdata} section.  The @option{-msdata=eabi} option is
15412
incompatible with the @option{-mrelocatable} option.  The
15413
@option{-msdata=eabi} option also sets the @option{-memb} option.
15414
 
15415
@item -msdata=sysv
15416
@opindex msdata=sysv
15417
On System V.4 and embedded PowerPC systems, put small global and static
15418
data in the @samp{.sdata} section, which is pointed to by register
15419
@code{r13}.  Put small uninitialized global and static data in the
15420
@samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
15421
The @option{-msdata=sysv} option is incompatible with the
15422
@option{-mrelocatable} option.
15423
 
15424
@item -msdata=default
15425
@itemx -msdata
15426
@opindex msdata=default
15427
@opindex msdata
15428
On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
15429
compile code the same as @option{-msdata=eabi}, otherwise compile code the
15430
same as @option{-msdata=sysv}.
15431
 
15432
@item -msdata=data
15433
@opindex msdata=data
15434
On System V.4 and embedded PowerPC systems, put small global
15435
data in the @samp{.sdata} section.  Put small uninitialized global
15436
data in the @samp{.sbss} section.  Do not use register @code{r13}
15437
to address small data however.  This is the default behavior unless
15438
other @option{-msdata} options are used.
15439
 
15440
@item -msdata=none
15441
@itemx -mno-sdata
15442
@opindex msdata=none
15443
@opindex mno-sdata
15444
On embedded PowerPC systems, put all initialized global and static data
15445
in the @samp{.data} section, and all uninitialized data in the
15446
@samp{.bss} section.
15447
 
15448
@item -G @var{num}
15449
@opindex G
15450
@cindex smaller data references (PowerPC)
15451
@cindex .sdata/.sdata2 references (PowerPC)
15452
On embedded PowerPC systems, put global and static items less than or
15453
equal to @var{num} bytes into the small data or bss sections instead of
15454
the normal data or bss section.  By default, @var{num} is 8.  The
15455
@option{-G @var{num}} switch is also passed to the linker.
15456
All modules should be compiled with the same @option{-G @var{num}} value.
15457
 
15458
@item -mregnames
15459
@itemx -mno-regnames
15460
@opindex mregnames
15461
@opindex mno-regnames
15462
On System V.4 and embedded PowerPC systems do (do not) emit register
15463
names in the assembly language output using symbolic forms.
15464
 
15465
@item -mlongcall
15466
@itemx -mno-longcall
15467
@opindex mlongcall
15468
@opindex mno-longcall
15469
By default assume that all calls are far away so that a longer more
15470
expensive calling sequence is required.  This is required for calls
15471
further than 32 megabytes (33,554,432 bytes) from the current location.
15472
A short call will be generated if the compiler knows
15473
the call cannot be that far away.  This setting can be overridden by
15474
the @code{shortcall} function attribute, or by @code{#pragma
15475
longcall(0)}.
15476
 
15477
Some linkers are capable of detecting out-of-range calls and generating
15478
glue code on the fly.  On these systems, long calls are unnecessary and
15479
generate slower code.  As of this writing, the AIX linker can do this,
15480
as can the GNU linker for PowerPC/64.  It is planned to add this feature
15481
to the GNU linker for 32-bit PowerPC systems as well.
15482
 
15483
On Darwin/PPC systems, @code{#pragma longcall} will generate ``jbsr
15484
callee, L42'', plus a ``branch island'' (glue code).  The two target
15485
addresses represent the callee and the ``branch island''.  The
15486
Darwin/PPC linker will prefer the first address and generate a ``bl
15487
callee'' if the PPC ``bl'' instruction will reach the callee directly;
15488
otherwise, the linker will generate ``bl L42'' to call the ``branch
15489
island''.  The ``branch island'' is appended to the body of the
15490
calling function; it computes the full 32-bit address of the callee
15491
and jumps to it.
15492
 
15493
On Mach-O (Darwin) systems, this option directs the compiler emit to
15494
the glue for every direct call, and the Darwin linker decides whether
15495
to use or discard it.
15496
 
15497
In the future, we may cause GCC to ignore all longcall specifications
15498
when the linker is known to generate glue.
15499
 
15500
@item -mtls-markers
15501
@itemx -mno-tls-markers
15502
@opindex mtls-markers
15503
@opindex mno-tls-markers
15504
Mark (do not mark) calls to @code{__tls_get_addr} with a relocation
15505
specifying the function argument.  The relocation allows ld to
15506
reliably associate function call with argument setup instructions for
15507
TLS optimization, which in turn allows gcc to better schedule the
15508
sequence.
15509
 
15510
@item -pthread
15511
@opindex pthread
15512
Adds support for multithreading with the @dfn{pthreads} library.
15513
This option sets flags for both the preprocessor and linker.
15514
 
15515
@end table
15516
 
15517
@node RX Options
15518
@subsection RX Options
15519
@cindex RX Options
15520
 
15521
These command line options are defined for RX targets:
15522
 
15523
@table @gcctabopt
15524
@item -m64bit-doubles
15525
@itemx -m32bit-doubles
15526
@opindex m64bit-doubles
15527
@opindex m32bit-doubles
15528
Make the @code{double} data type be 64-bits (@option{-m64bit-doubles})
15529
or 32-bits (@option{-m32bit-doubles}) in size.  The default is
15530
@option{-m32bit-doubles}.  @emph{Note} RX floating point hardware only
15531
works on 32-bit values, which is why the default is
15532
@option{-m32bit-doubles}.
15533
 
15534
@item -fpu
15535
@itemx -nofpu
15536
@opindex fpu
15537
@opindex nofpu
15538
Enables (@option{-fpu}) or disables (@option{-nofpu}) the use of RX
15539
floating point hardware.  The default is enabled for the @var{RX600}
15540
series and disabled for the @var{RX200} series.
15541
 
15542
Floating point instructions will only be generated for 32-bit floating
15543
point values however, so if the @option{-m64bit-doubles} option is in
15544
use then the FPU hardware will not be used for doubles.
15545
 
15546
@emph{Note} If the @option{-fpu} option is enabled then
15547
@option{-funsafe-math-optimizations} is also enabled automatically.
15548
This is because the RX FPU instructions are themselves unsafe.
15549
 
15550
@item -mcpu=@var{name}
15551
@itemx -patch=@var{name}
15552
@opindex -mcpu
15553
@opindex -patch
15554
Selects the type of RX CPU to be targeted.  Currently three types are
15555
supported, the generic @var{RX600} and @var{RX200} series hardware and
15556
the specific @var{RX610} cpu.  The default is @var{RX600}.
15557
 
15558
The only difference between @var{RX600} and @var{RX610} is that the
15559
@var{RX610} does not support the @code{MVTIPL} instruction.
15560
 
15561
The @var{RX200} series does not have a hardware floating point unit
15562
and so @option{-nofpu} is enabled by default when this type is
15563
selected.
15564
 
15565
@item -mbig-endian-data
15566
@itemx -mlittle-endian-data
15567
@opindex mbig-endian-data
15568
@opindex mlittle-endian-data
15569
Store data (but not code) in the big-endian format.  The default is
15570
@option{-mlittle-endian-data}, ie to store data in the little endian
15571
format.
15572
 
15573
@item -msmall-data-limit=@var{N}
15574
@opindex msmall-data-limit
15575
Specifies the maximum size in bytes of global and static variables
15576
which can be placed into the small data area.  Using the small data
15577
area can lead to smaller and faster code, but the size of area is
15578
limited and it is up to the programmer to ensure that the area does
15579
not overflow.  Also when the small data area is used one of the RX's
15580
registers (@code{r13}) is reserved for use pointing to this area, so
15581
it is no longer available for use by the compiler.  This could result
15582
in slower and/or larger code if variables which once could have been
15583
held in @code{r13} are now pushed onto the stack.
15584
 
15585
Note, common variables (variables which have not been initialised) and
15586
constants are not placed into the small data area as they are assigned
15587
to other sections in the output executable.
15588
 
15589
The default value is zero, which disables this feature.  Note, this
15590
feature is not enabled by default with higher optimization levels
15591
(@option{-O2} etc) because of the potentially detrimental effects of
15592
reserving register @code{r13}.  It is up to the programmer to
15593
experiment and discover whether this feature is of benefit to their
15594
program.
15595
 
15596
@item -msim
15597
@itemx -mno-sim
15598
@opindex msim
15599
@opindex mno-sim
15600
Use the simulator runtime.  The default is to use the libgloss board
15601
specific runtime.
15602
 
15603
@item -mas100-syntax
15604
@itemx -mno-as100-syntax
15605
@opindex mas100-syntax
15606
@opindex mno-as100-syntax
15607
When generating assembler output use a syntax that is compatible with
15608
Renesas's AS100 assembler.  This syntax can also be handled by the GAS
15609
assembler but it has some restrictions so generating it is not the
15610
default option.
15611
 
15612
@item -mmax-constant-size=@var{N}
15613
@opindex mmax-constant-size
15614
Specifies the maximum size, in bytes, of a constant that can be used as
15615
an operand in a RX instruction.  Although the RX instruction set does
15616
allow constants of up to 4 bytes in length to be used in instructions,
15617
a longer value equates to a longer instruction.  Thus in some
15618
circumstances it can be beneficial to restrict the size of constants
15619
that are used in instructions.  Constants that are too big are instead
15620
placed into a constant pool and referenced via register indirection.
15621
 
15622
The value @var{N} can be between 0 and 4.  A value of 0 (the default)
15623
or 4 means that constants of any size are allowed.
15624
 
15625
@item -mrelax
15626
@opindex mrelax
15627
Enable linker relaxation.  Linker relaxation is a process whereby the
15628
linker will attempt to reduce the size of a program by finding shorter
15629
versions of various instructions.  Disabled by default.
15630
 
15631
@item -mint-register=@var{N}
15632
@opindex mint-register
15633
Specify the number of registers to reserve for fast interrupt handler
15634
functions.  The value @var{N} can be between 0 and 4.  A value of 1
15635
means that register @code{r13} will be reserved for the exclusive use
15636
of fast interrupt handlers.  A value of 2 reserves @code{r13} and
15637
@code{r12}.  A value of 3 reserves @code{r13}, @code{r12} and
15638
@code{r11}, and a value of 4 reserves @code{r13} through @code{r10}.
15639
A value of 0, the default, does not reserve any registers.
15640
 
15641
@item -msave-acc-in-interrupts
15642
@opindex msave-acc-in-interrupts
15643
Specifies that interrupt handler functions should preserve the
15644
accumulator register.  This is only necessary if normal code might use
15645
the accumulator register, for example because it performs 64-bit
15646
multiplications.  The default is to ignore the accumulator as this
15647
makes the interrupt handlers faster.
15648
 
15649
@end table
15650
 
15651
@emph{Note:} The generic GCC command line @option{-ffixed-@var{reg}}
15652
has special significance to the RX port when used with the
15653
@code{interrupt} function attribute.  This attribute indicates a
15654
function intended to process fast interrupts.  GCC will will ensure
15655
that it only uses the registers @code{r10}, @code{r11}, @code{r12}
15656
and/or @code{r13} and only provided that the normal use of the
15657
corresponding registers have been restricted via the
15658
@option{-ffixed-@var{reg}} or @option{-mint-register} command line
15659
options.
15660
 
15661
@node S/390 and zSeries Options
15662
@subsection S/390 and zSeries Options
15663
@cindex S/390 and zSeries Options
15664
 
15665
These are the @samp{-m} options defined for the S/390 and zSeries architecture.
15666
 
15667
@table @gcctabopt
15668
@item -mhard-float
15669
@itemx -msoft-float
15670
@opindex mhard-float
15671
@opindex msoft-float
15672
Use (do not use) the hardware floating-point instructions and registers
15673
for floating-point operations.  When @option{-msoft-float} is specified,
15674
functions in @file{libgcc.a} will be used to perform floating-point
15675
operations.  When @option{-mhard-float} is specified, the compiler
15676
generates IEEE floating-point instructions.  This is the default.
15677
 
15678
@item -mhard-dfp
15679
@itemx -mno-hard-dfp
15680
@opindex mhard-dfp
15681
@opindex mno-hard-dfp
15682
Use (do not use) the hardware decimal-floating-point instructions for
15683
decimal-floating-point operations.  When @option{-mno-hard-dfp} is
15684
specified, functions in @file{libgcc.a} will be used to perform
15685
decimal-floating-point operations.  When @option{-mhard-dfp} is
15686
specified, the compiler generates decimal-floating-point hardware
15687
instructions.  This is the default for @option{-march=z9-ec} or higher.
15688
 
15689
@item -mlong-double-64
15690
@itemx -mlong-double-128
15691
@opindex mlong-double-64
15692
@opindex mlong-double-128
15693
These switches control the size of @code{long double} type. A size
15694
of 64bit makes the @code{long double} type equivalent to the @code{double}
15695
type. This is the default.
15696
 
15697
@item -mbackchain
15698
@itemx -mno-backchain
15699
@opindex mbackchain
15700
@opindex mno-backchain
15701
Store (do not store) the address of the caller's frame as backchain pointer
15702
into the callee's stack frame.
15703
A backchain may be needed to allow debugging using tools that do not understand
15704
DWARF-2 call frame information.
15705
When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
15706
at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
15707
the backchain is placed into the topmost word of the 96/160 byte register
15708
save area.
15709
 
15710
In general, code compiled with @option{-mbackchain} is call-compatible with
15711
code compiled with @option{-mmo-backchain}; however, use of the backchain
15712
for debugging purposes usually requires that the whole binary is built with
15713
@option{-mbackchain}.  Note that the combination of @option{-mbackchain},
15714
@option{-mpacked-stack} and @option{-mhard-float} is not supported.  In order
15715
to build a linux kernel use @option{-msoft-float}.
15716
 
15717
The default is to not maintain the backchain.
15718
 
15719
@item -mpacked-stack
15720
@itemx -mno-packed-stack
15721
@opindex mpacked-stack
15722
@opindex mno-packed-stack
15723
Use (do not use) the packed stack layout.  When @option{-mno-packed-stack} is
15724
specified, the compiler uses the all fields of the 96/160 byte register save
15725
area only for their default purpose; unused fields still take up stack space.
15726
When @option{-mpacked-stack} is specified, register save slots are densely
15727
packed at the top of the register save area; unused space is reused for other
15728
purposes, allowing for more efficient use of the available stack space.
15729
However, when @option{-mbackchain} is also in effect, the topmost word of
15730
the save area is always used to store the backchain, and the return address
15731
register is always saved two words below the backchain.
15732
 
15733
As long as the stack frame backchain is not used, code generated with
15734
@option{-mpacked-stack} is call-compatible with code generated with
15735
@option{-mno-packed-stack}.  Note that some non-FSF releases of GCC 2.95 for
15736
S/390 or zSeries generated code that uses the stack frame backchain at run
15737
time, not just for debugging purposes.  Such code is not call-compatible
15738
with code compiled with @option{-mpacked-stack}.  Also, note that the
15739
combination of @option{-mbackchain},
15740
@option{-mpacked-stack} and @option{-mhard-float} is not supported.  In order
15741
to build a linux kernel use @option{-msoft-float}.
15742
 
15743
The default is to not use the packed stack layout.
15744
 
15745
@item -msmall-exec
15746
@itemx -mno-small-exec
15747
@opindex msmall-exec
15748
@opindex mno-small-exec
15749
Generate (or do not generate) code using the @code{bras} instruction
15750
to do subroutine calls.
15751
This only works reliably if the total executable size does not
15752
exceed 64k.  The default is to use the @code{basr} instruction instead,
15753
which does not have this limitation.
15754
 
15755
@item -m64
15756
@itemx -m31
15757
@opindex m64
15758
@opindex m31
15759
When @option{-m31} is specified, generate code compliant to the
15760
GNU/Linux for S/390 ABI@.  When @option{-m64} is specified, generate
15761
code compliant to the GNU/Linux for zSeries ABI@.  This allows GCC in
15762
particular to generate 64-bit instructions.  For the @samp{s390}
15763
targets, the default is @option{-m31}, while the @samp{s390x}
15764
targets default to @option{-m64}.
15765
 
15766
@item -mzarch
15767
@itemx -mesa
15768
@opindex mzarch
15769
@opindex mesa
15770
When @option{-mzarch} is specified, generate code using the
15771
instructions available on z/Architecture.
15772
When @option{-mesa} is specified, generate code using the
15773
instructions available on ESA/390.  Note that @option{-mesa} is
15774
not possible with @option{-m64}.
15775
When generating code compliant to the GNU/Linux for S/390 ABI,
15776
the default is @option{-mesa}.  When generating code compliant
15777
to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
15778
 
15779
@item -mmvcle
15780
@itemx -mno-mvcle
15781
@opindex mmvcle
15782
@opindex mno-mvcle
15783
Generate (or do not generate) code using the @code{mvcle} instruction
15784
to perform block moves.  When @option{-mno-mvcle} is specified,
15785
use a @code{mvc} loop instead.  This is the default unless optimizing for
15786
size.
15787
 
15788
@item -mdebug
15789
@itemx -mno-debug
15790
@opindex mdebug
15791
@opindex mno-debug
15792
Print (or do not print) additional debug information when compiling.
15793
The default is to not print debug information.
15794
 
15795
@item -march=@var{cpu-type}
15796
@opindex march
15797
Generate code that will run on @var{cpu-type}, which is the name of a system
15798
representing a certain processor type.  Possible values for
15799
@var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, @samp{z990},
15800
@samp{z9-109}, @samp{z9-ec} and @samp{z10}.
15801
When generating code using the instructions available on z/Architecture,
15802
the default is @option{-march=z900}.  Otherwise, the default is
15803
@option{-march=g5}.
15804
 
15805
@item -mtune=@var{cpu-type}
15806
@opindex mtune
15807
Tune to @var{cpu-type} everything applicable about the generated code,
15808
except for the ABI and the set of available instructions.
15809
The list of @var{cpu-type} values is the same as for @option{-march}.
15810
The default is the value used for @option{-march}.
15811
 
15812
@item -mtpf-trace
15813
@itemx -mno-tpf-trace
15814
@opindex mtpf-trace
15815
@opindex mno-tpf-trace
15816
Generate code that adds (does not add) in TPF OS specific branches to trace
15817
routines in the operating system.  This option is off by default, even
15818
when compiling for the TPF OS@.
15819
 
15820
@item -mfused-madd
15821
@itemx -mno-fused-madd
15822
@opindex mfused-madd
15823
@opindex mno-fused-madd
15824
Generate code that uses (does not use) the floating point multiply and
15825
accumulate instructions.  These instructions are generated by default if
15826
hardware floating point is used.
15827
 
15828
@item -mwarn-framesize=@var{framesize}
15829
@opindex mwarn-framesize
15830
Emit a warning if the current function exceeds the given frame size.  Because
15831
this is a compile time check it doesn't need to be a real problem when the program
15832
runs.  It is intended to identify functions which most probably cause
15833
a stack overflow.  It is useful to be used in an environment with limited stack
15834
size e.g.@: the linux kernel.
15835
 
15836
@item -mwarn-dynamicstack
15837
@opindex mwarn-dynamicstack
15838
Emit a warning if the function calls alloca or uses dynamically
15839
sized arrays.  This is generally a bad idea with a limited stack size.
15840
 
15841
@item -mstack-guard=@var{stack-guard}
15842
@itemx -mstack-size=@var{stack-size}
15843
@opindex mstack-guard
15844
@opindex mstack-size
15845
If these options are provided the s390 back end emits additional instructions in
15846
the function prologue which trigger a trap if the stack size is @var{stack-guard}
15847
bytes above the @var{stack-size} (remember that the stack on s390 grows downward).
15848
If the @var{stack-guard} option is omitted the smallest power of 2 larger than
15849
the frame size of the compiled function is chosen.
15850
These options are intended to be used to help debugging stack overflow problems.
15851
The additionally emitted code causes only little overhead and hence can also be
15852
used in production like systems without greater performance degradation.  The given
15853
values have to be exact powers of 2 and @var{stack-size} has to be greater than
15854
@var{stack-guard} without exceeding 64k.
15855
In order to be efficient the extra code makes the assumption that the stack starts
15856
at an address aligned to the value given by @var{stack-size}.
15857
The @var{stack-guard} option can only be used in conjunction with @var{stack-size}.
15858
@end table
15859
 
15860
@node Score Options
15861
@subsection Score Options
15862
@cindex Score Options
15863
 
15864
These options are defined for Score implementations:
15865
 
15866
@table @gcctabopt
15867
@item -meb
15868
@opindex meb
15869
Compile code for big endian mode.  This is the default.
15870
 
15871
@item -mel
15872
@opindex mel
15873
Compile code for little endian mode.
15874
 
15875
@item -mnhwloop
15876
@opindex mnhwloop
15877
Disable generate bcnz instruction.
15878
 
15879
@item -muls
15880
@opindex muls
15881
Enable generate unaligned load and store instruction.
15882
 
15883
@item -mmac
15884
@opindex mmac
15885
Enable the use of multiply-accumulate instructions. Disabled by default.
15886
 
15887
@item -mscore5
15888
@opindex mscore5
15889
Specify the SCORE5 as the target architecture.
15890
 
15891
@item -mscore5u
15892
@opindex mscore5u
15893
Specify the SCORE5U of the target architecture.
15894
 
15895
@item -mscore7
15896
@opindex mscore7
15897
Specify the SCORE7 as the target architecture. This is the default.
15898
 
15899
@item -mscore7d
15900
@opindex mscore7d
15901
Specify the SCORE7D as the target architecture.
15902
@end table
15903
 
15904
@node SH Options
15905
@subsection SH Options
15906
 
15907
These @samp{-m} options are defined for the SH implementations:
15908
 
15909
@table @gcctabopt
15910
@item -m1
15911
@opindex m1
15912
Generate code for the SH1.
15913
 
15914
@item -m2
15915
@opindex m2
15916
Generate code for the SH2.
15917
 
15918
@item -m2e
15919
Generate code for the SH2e.
15920
 
15921
@item -m2a-nofpu
15922
@opindex m2a-nofpu
15923
Generate code for the SH2a without FPU, or for a SH2a-FPU in such a way
15924
that the floating-point unit is not used.
15925
 
15926
@item -m2a-single-only
15927
@opindex m2a-single-only
15928
Generate code for the SH2a-FPU, in such a way that no double-precision
15929
floating point operations are used.
15930
 
15931
@item -m2a-single
15932
@opindex m2a-single
15933
Generate code for the SH2a-FPU assuming the floating-point unit is in
15934
single-precision mode by default.
15935
 
15936
@item -m2a
15937
@opindex m2a
15938
Generate code for the SH2a-FPU assuming the floating-point unit is in
15939
double-precision mode by default.
15940
 
15941
@item -m3
15942
@opindex m3
15943
Generate code for the SH3.
15944
 
15945
@item -m3e
15946
@opindex m3e
15947
Generate code for the SH3e.
15948
 
15949
@item -m4-nofpu
15950
@opindex m4-nofpu
15951
Generate code for the SH4 without a floating-point unit.
15952
 
15953
@item -m4-single-only
15954
@opindex m4-single-only
15955
Generate code for the SH4 with a floating-point unit that only
15956
supports single-precision arithmetic.
15957
 
15958
@item -m4-single
15959
@opindex m4-single
15960
Generate code for the SH4 assuming the floating-point unit is in
15961
single-precision mode by default.
15962
 
15963
@item -m4
15964
@opindex m4
15965
Generate code for the SH4.
15966
 
15967
@item -m4a-nofpu
15968
@opindex m4a-nofpu
15969
Generate code for the SH4al-dsp, or for a SH4a in such a way that the
15970
floating-point unit is not used.
15971
 
15972
@item -m4a-single-only
15973
@opindex m4a-single-only
15974
Generate code for the SH4a, in such a way that no double-precision
15975
floating point operations are used.
15976
 
15977
@item -m4a-single
15978
@opindex m4a-single
15979
Generate code for the SH4a assuming the floating-point unit is in
15980
single-precision mode by default.
15981
 
15982
@item -m4a
15983
@opindex m4a
15984
Generate code for the SH4a.
15985
 
15986
@item -m4al
15987
@opindex m4al
15988
Same as @option{-m4a-nofpu}, except that it implicitly passes
15989
@option{-dsp} to the assembler.  GCC doesn't generate any DSP
15990
instructions at the moment.
15991
 
15992
@item -mb
15993
@opindex mb
15994
Compile code for the processor in big endian mode.
15995
 
15996
@item -ml
15997
@opindex ml
15998
Compile code for the processor in little endian mode.
15999
 
16000
@item -mdalign
16001
@opindex mdalign
16002
Align doubles at 64-bit boundaries.  Note that this changes the calling
16003
conventions, and thus some functions from the standard C library will
16004
not work unless you recompile it first with @option{-mdalign}.
16005
 
16006
@item -mrelax
16007
@opindex mrelax
16008
Shorten some address references at link time, when possible; uses the
16009
linker option @option{-relax}.
16010
 
16011
@item -mbigtable
16012
@opindex mbigtable
16013
Use 32-bit offsets in @code{switch} tables.  The default is to use
16014
16-bit offsets.
16015
 
16016
@item -mbitops
16017
@opindex mbitops
16018
Enable the use of bit manipulation instructions on SH2A.
16019
 
16020
@item -mfmovd
16021
@opindex mfmovd
16022
Enable the use of the instruction @code{fmovd}.  Check @option{-mdalign} for
16023
alignment constraints.
16024
 
16025
@item -mhitachi
16026
@opindex mhitachi
16027
Comply with the calling conventions defined by Renesas.
16028
 
16029
@item -mrenesas
16030
@opindex mhitachi
16031
Comply with the calling conventions defined by Renesas.
16032
 
16033
@item -mno-renesas
16034
@opindex mhitachi
16035
Comply with the calling conventions defined for GCC before the Renesas
16036
conventions were available.  This option is the default for all
16037
targets of the SH toolchain except for @samp{sh-symbianelf}.
16038
 
16039
@item -mnomacsave
16040
@opindex mnomacsave
16041
Mark the @code{MAC} register as call-clobbered, even if
16042
@option{-mhitachi} is given.
16043
 
16044
@item -mieee
16045
@opindex mieee
16046
Increase IEEE-compliance of floating-point code.
16047
At the moment, this is equivalent to @option{-fno-finite-math-only}.
16048
When generating 16 bit SH opcodes, getting IEEE-conforming results for
16049
comparisons of NANs / infinities incurs extra overhead in every
16050
floating point comparison, therefore the default is set to
16051
@option{-ffinite-math-only}.
16052
 
16053
@item -minline-ic_invalidate
16054
@opindex minline-ic_invalidate
16055
Inline code to invalidate instruction cache entries after setting up
16056
nested function trampolines.
16057
This option has no effect if -musermode is in effect and the selected
16058
code generation option (e.g. -m4) does not allow the use of the icbi
16059
instruction.
16060
If the selected code generation option does not allow the use of the icbi
16061
instruction, and -musermode is not in effect, the inlined code will
16062
manipulate the instruction cache address array directly with an associative
16063
write.  This not only requires privileged mode, but it will also
16064
fail if the cache line had been mapped via the TLB and has become unmapped.
16065
 
16066
@item -misize
16067
@opindex misize
16068
Dump instruction size and location in the assembly code.
16069
 
16070
@item -mpadstruct
16071
@opindex mpadstruct
16072
This option is deprecated.  It pads structures to multiple of 4 bytes,
16073
which is incompatible with the SH ABI@.
16074
 
16075
@item -mspace
16076
@opindex mspace
16077
Optimize for space instead of speed.  Implied by @option{-Os}.
16078
 
16079
@item -mprefergot
16080
@opindex mprefergot
16081
When generating position-independent code, emit function calls using
16082
the Global Offset Table instead of the Procedure Linkage Table.
16083
 
16084
@item -musermode
16085
@opindex musermode
16086
Don't generate privileged mode only code; implies -mno-inline-ic_invalidate
16087
if the inlined code would not work in user mode.
16088
This is the default when the target is @code{sh-*-linux*}.
16089
 
16090
@item -multcost=@var{number}
16091
@opindex multcost=@var{number}
16092
Set the cost to assume for a multiply insn.
16093
 
16094
@item -mdiv=@var{strategy}
16095
@opindex mdiv=@var{strategy}
16096
Set the division strategy to use for SHmedia code.  @var{strategy} must be
16097
one of: call, call2, fp, inv, inv:minlat, inv20u, inv20l, inv:call,
16098
inv:call2, inv:fp .
16099
"fp" performs the operation in floating point.  This has a very high latency,
16100
but needs only a few instructions, so it might be a good choice if
16101
your code has enough easily exploitable ILP to allow the compiler to
16102
schedule the floating point instructions together with other instructions.
16103
Division by zero causes a floating point exception.
16104
"inv" uses integer operations to calculate the inverse of the divisor,
16105
and then multiplies the dividend with the inverse.  This strategy allows
16106
cse and hoisting of the inverse calculation.  Division by zero calculates
16107
an unspecified result, but does not trap.
16108
"inv:minlat" is a variant of "inv" where if no cse / hoisting opportunities
16109
have been found, or if the entire operation has been hoisted to the same
16110
place, the last stages of the inverse calculation are intertwined with the
16111
final multiply to reduce the overall latency, at the expense of using a few
16112
more instructions, and thus offering fewer scheduling opportunities with
16113
other code.
16114
"call" calls a library function that usually implements the inv:minlat
16115
strategy.
16116
This gives high code density for m5-*media-nofpu compilations.
16117
"call2" uses a different entry point of the same library function, where it
16118
assumes that a pointer to a lookup table has already been set up, which
16119
exposes the pointer load to cse / code hoisting optimizations.
16120
"inv:call", "inv:call2" and "inv:fp" all use the "inv" algorithm for initial
16121
code generation, but if the code stays unoptimized, revert to the "call",
16122
"call2", or "fp" strategies, respectively.  Note that the
16123
potentially-trapping side effect of division by zero is carried by a
16124
separate instruction, so it is possible that all the integer instructions
16125
are hoisted out, but the marker for the side effect stays where it is.
16126
A recombination to fp operations or a call is not possible in that case.
16127
"inv20u" and "inv20l" are variants of the "inv:minlat" strategy.  In the case
16128
that the inverse calculation was nor separated from the multiply, they speed
16129
up division where the dividend fits into 20 bits (plus sign where applicable),
16130
by inserting a test to skip a number of operations in this case; this test
16131
slows down the case of larger dividends.  inv20u assumes the case of a such
16132
a small dividend to be unlikely, and inv20l assumes it to be likely.
16133
 
16134
@item -mdivsi3_libfunc=@var{name}
16135
@opindex mdivsi3_libfunc=@var{name}
16136
Set the name of the library function used for 32 bit signed division to
16137
@var{name}.  This only affect the name used in the call and inv:call
16138
division strategies, and the compiler will still expect the same
16139
sets of input/output/clobbered registers as if this option was not present.
16140
 
16141
@item -mfixed-range=@var{register-range}
16142
@opindex mfixed-range
16143
Generate code treating the given register range as fixed registers.
16144
A fixed register is one that the register allocator can not use.  This is
16145
useful when compiling kernel code.  A register range is specified as
16146
two registers separated by a dash.  Multiple register ranges can be
16147
specified separated by a comma.
16148
 
16149
@item -madjust-unroll
16150
@opindex madjust-unroll
16151
Throttle unrolling to avoid thrashing target registers.
16152
This option only has an effect if the gcc code base supports the
16153
TARGET_ADJUST_UNROLL_MAX target hook.
16154
 
16155
@item -mindexed-addressing
16156
@opindex mindexed-addressing
16157
Enable the use of the indexed addressing mode for SHmedia32/SHcompact.
16158
This is only safe if the hardware and/or OS implement 32 bit wrap-around
16159
semantics for the indexed addressing mode.  The architecture allows the
16160
implementation of processors with 64 bit MMU, which the OS could use to
16161
get 32 bit addressing, but since no current hardware implementation supports
16162
this or any other way to make the indexed addressing mode safe to use in
16163
the 32 bit ABI, the default is -mno-indexed-addressing.
16164
 
16165
@item -mgettrcost=@var{number}
16166
@opindex mgettrcost=@var{number}
16167
Set the cost assumed for the gettr instruction to @var{number}.
16168
The default is 2 if @option{-mpt-fixed} is in effect, 100 otherwise.
16169
 
16170
@item -mpt-fixed
16171
@opindex mpt-fixed
16172
Assume pt* instructions won't trap.  This will generally generate better
16173
scheduled code, but is unsafe on current hardware.  The current architecture
16174
definition says that ptabs and ptrel trap when the target anded with 3 is 3.
16175
This has the unintentional effect of making it unsafe to schedule ptabs /
16176
ptrel before a branch, or hoist it out of a loop.  For example,
16177
__do_global_ctors, a part of libgcc that runs constructors at program
16178
startup, calls functions in a list which is delimited by @minus{}1.  With the
16179
-mpt-fixed option, the ptabs will be done before testing against @minus{}1.
16180
That means that all the constructors will be run a bit quicker, but when
16181
the loop comes to the end of the list, the program crashes because ptabs
16182
loads @minus{}1 into a target register.  Since this option is unsafe for any
16183
hardware implementing the current architecture specification, the default
16184
is -mno-pt-fixed.  Unless the user specifies a specific cost with
16185
@option{-mgettrcost}, -mno-pt-fixed also implies @option{-mgettrcost=100};
16186
this deters register allocation using target registers for storing
16187
ordinary integers.
16188
 
16189
@item -minvalid-symbols
16190
@opindex minvalid-symbols
16191
Assume symbols might be invalid.  Ordinary function symbols generated by
16192
the compiler will always be valid to load with movi/shori/ptabs or
16193
movi/shori/ptrel, but with assembler and/or linker tricks it is possible
16194
to generate symbols that will cause ptabs / ptrel to trap.
16195
This option is only meaningful when @option{-mno-pt-fixed} is in effect.
16196
It will then prevent cross-basic-block cse, hoisting and most scheduling
16197
of symbol loads.  The default is @option{-mno-invalid-symbols}.
16198
@end table
16199
 
16200
@node SPARC Options
16201
@subsection SPARC Options
16202
@cindex SPARC options
16203
 
16204
These @samp{-m} options are supported on the SPARC:
16205
 
16206
@table @gcctabopt
16207
@item -mno-app-regs
16208
@itemx -mapp-regs
16209
@opindex mno-app-regs
16210
@opindex mapp-regs
16211
Specify @option{-mapp-regs} to generate output using the global registers
16212
2 through 4, which the SPARC SVR4 ABI reserves for applications.  This
16213
is the default.
16214
 
16215
To be fully SVR4 ABI compliant at the cost of some performance loss,
16216
specify @option{-mno-app-regs}.  You should compile libraries and system
16217
software with this option.
16218
 
16219
@item -mfpu
16220
@itemx -mhard-float
16221
@opindex mfpu
16222
@opindex mhard-float
16223
Generate output containing floating point instructions.  This is the
16224
default.
16225
 
16226
@item -mno-fpu
16227
@itemx -msoft-float
16228
@opindex mno-fpu
16229
@opindex msoft-float
16230
Generate output containing library calls for floating point.
16231
@strong{Warning:} the requisite libraries are not available for all SPARC
16232
targets.  Normally the facilities of the machine's usual C compiler are
16233
used, but this cannot be done directly in cross-compilation.  You must make
16234
your own arrangements to provide suitable library functions for
16235
cross-compilation.  The embedded targets @samp{sparc-*-aout} and
16236
@samp{sparclite-*-*} do provide software floating point support.
16237
 
16238
@option{-msoft-float} changes the calling convention in the output file;
16239
therefore, it is only useful if you compile @emph{all} of a program with
16240
this option.  In particular, you need to compile @file{libgcc.a}, the
16241
library that comes with GCC, with @option{-msoft-float} in order for
16242
this to work.
16243
 
16244
@item -mhard-quad-float
16245
@opindex mhard-quad-float
16246
Generate output containing quad-word (long double) floating point
16247
instructions.
16248
 
16249
@item -msoft-quad-float
16250
@opindex msoft-quad-float
16251
Generate output containing library calls for quad-word (long double)
16252
floating point instructions.  The functions called are those specified
16253
in the SPARC ABI@.  This is the default.
16254
 
16255
As of this writing, there are no SPARC implementations that have hardware
16256
support for the quad-word floating point instructions.  They all invoke
16257
a trap handler for one of these instructions, and then the trap handler
16258
emulates the effect of the instruction.  Because of the trap handler overhead,
16259
this is much slower than calling the ABI library routines.  Thus the
16260
@option{-msoft-quad-float} option is the default.
16261
 
16262
@item -mno-unaligned-doubles
16263
@itemx -munaligned-doubles
16264
@opindex mno-unaligned-doubles
16265
@opindex munaligned-doubles
16266
Assume that doubles have 8 byte alignment.  This is the default.
16267
 
16268
With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
16269
alignment only if they are contained in another type, or if they have an
16270
absolute address.  Otherwise, it assumes they have 4 byte alignment.
16271
Specifying this option avoids some rare compatibility problems with code
16272
generated by other compilers.  It is not the default because it results
16273
in a performance loss, especially for floating point code.
16274
 
16275
@item -mno-faster-structs
16276
@itemx -mfaster-structs
16277
@opindex mno-faster-structs
16278
@opindex mfaster-structs
16279
With @option{-mfaster-structs}, the compiler assumes that structures
16280
should have 8 byte alignment.  This enables the use of pairs of
16281
@code{ldd} and @code{std} instructions for copies in structure
16282
assignment, in place of twice as many @code{ld} and @code{st} pairs.
16283
However, the use of this changed alignment directly violates the SPARC
16284
ABI@.  Thus, it's intended only for use on targets where the developer
16285
acknowledges that their resulting code will not be directly in line with
16286
the rules of the ABI@.
16287
 
16288
@item -mimpure-text
16289
@opindex mimpure-text
16290
@option{-mimpure-text}, used in addition to @option{-shared}, tells
16291
the compiler to not pass @option{-z text} to the linker when linking a
16292
shared object.  Using this option, you can link position-dependent
16293
code into a shared object.
16294
 
16295
@option{-mimpure-text} suppresses the ``relocations remain against
16296
allocatable but non-writable sections'' linker error message.
16297
However, the necessary relocations will trigger copy-on-write, and the
16298
shared object is not actually shared across processes.  Instead of
16299
using @option{-mimpure-text}, you should compile all source code with
16300
@option{-fpic} or @option{-fPIC}.
16301
 
16302
This option is only available on SunOS and Solaris.
16303
 
16304
@item -mcpu=@var{cpu_type}
16305
@opindex mcpu
16306
Set the instruction set, register set, and instruction scheduling parameters
16307
for machine type @var{cpu_type}.  Supported values for @var{cpu_type} are
16308
@samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
16309
@samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x},
16310
@samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc},
16311
@samp{ultrasparc3}, @samp{niagara} and @samp{niagara2}.
16312
 
16313
Default instruction scheduling parameters are used for values that select
16314
an architecture and not an implementation.  These are @samp{v7}, @samp{v8},
16315
@samp{sparclite}, @samp{sparclet}, @samp{v9}.
16316
 
16317
Here is a list of each supported architecture and their supported
16318
implementations.
16319
 
16320
@smallexample
16321
    v7:             cypress
16322
    v8:             supersparc, hypersparc
16323
    sparclite:      f930, f934, sparclite86x
16324
    sparclet:       tsc701
16325
    v9:             ultrasparc, ultrasparc3, niagara, niagara2
16326
@end smallexample
16327
 
16328
By default (unless configured otherwise), GCC generates code for the V7
16329
variant of the SPARC architecture.  With @option{-mcpu=cypress}, the compiler
16330
additionally optimizes it for the Cypress CY7C602 chip, as used in the
16331
SPARCStation/SPARCServer 3xx series.  This is also appropriate for the older
16332
SPARCStation 1, 2, IPX etc.
16333
 
16334
With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
16335
architecture.  The only difference from V7 code is that the compiler emits
16336
the integer multiply and integer divide instructions which exist in SPARC-V8
16337
but not in SPARC-V7.  With @option{-mcpu=supersparc}, the compiler additionally
16338
optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
16339
2000 series.
16340
 
16341
With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
16342
the SPARC architecture.  This adds the integer multiply, integer divide step
16343
and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
16344
With @option{-mcpu=f930}, the compiler additionally optimizes it for the
16345
Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@.  With
16346
@option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
16347
MB86934 chip, which is the more recent SPARClite with FPU@.
16348
 
16349
With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
16350
the SPARC architecture.  This adds the integer multiply, multiply/accumulate,
16351
integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
16352
but not in SPARC-V7.  With @option{-mcpu=tsc701}, the compiler additionally
16353
optimizes it for the TEMIC SPARClet chip.
16354
 
16355
With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
16356
architecture.  This adds 64-bit integer and floating-point move instructions,
16357
3 additional floating-point condition code registers and conditional move
16358
instructions.  With @option{-mcpu=ultrasparc}, the compiler additionally
16359
optimizes it for the Sun UltraSPARC I/II/IIi chips.  With
16360
@option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
16361
Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips.  With
16362
@option{-mcpu=niagara}, the compiler additionally optimizes it for
16363
Sun UltraSPARC T1 chips.  With @option{-mcpu=niagara2}, the compiler
16364
additionally optimizes it for Sun UltraSPARC T2 chips.
16365
 
16366
@item -mtune=@var{cpu_type}
16367
@opindex mtune
16368
Set the instruction scheduling parameters for machine type
16369
@var{cpu_type}, but do not set the instruction set or register set that the
16370
option @option{-mcpu=@var{cpu_type}} would.
16371
 
16372
The same values for @option{-mcpu=@var{cpu_type}} can be used for
16373
@option{-mtune=@var{cpu_type}}, but the only useful values are those
16374
that select a particular cpu implementation.  Those are @samp{cypress},
16375
@samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
16376
@samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc},
16377
@samp{ultrasparc3}, @samp{niagara}, and @samp{niagara2}.
16378
 
16379
@item -mv8plus
16380
@itemx -mno-v8plus
16381
@opindex mv8plus
16382
@opindex mno-v8plus
16383
With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@.  The
16384
difference from the V8 ABI is that the global and out registers are
16385
considered 64-bit wide.  This is enabled by default on Solaris in 32-bit
16386
mode for all SPARC-V9 processors.
16387
 
16388
@item -mvis
16389
@itemx -mno-vis
16390
@opindex mvis
16391
@opindex mno-vis
16392
With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
16393
Visual Instruction Set extensions.  The default is @option{-mno-vis}.
16394
@end table
16395
 
16396
These @samp{-m} options are supported in addition to the above
16397
on SPARC-V9 processors in 64-bit environments:
16398
 
16399
@table @gcctabopt
16400
@item -mlittle-endian
16401
@opindex mlittle-endian
16402
Generate code for a processor running in little-endian mode.  It is only
16403
available for a few configurations and most notably not on Solaris and Linux.
16404
 
16405
@item -m32
16406
@itemx -m64
16407
@opindex m32
16408
@opindex m64
16409
Generate code for a 32-bit or 64-bit environment.
16410
The 32-bit environment sets int, long and pointer to 32 bits.
16411
The 64-bit environment sets int to 32 bits and long and pointer
16412
to 64 bits.
16413
 
16414
@item -mcmodel=medlow
16415
@opindex mcmodel=medlow
16416
Generate code for the Medium/Low code model: 64-bit addresses, programs
16417
must be linked in the low 32 bits of memory.  Programs can be statically
16418
or dynamically linked.
16419
 
16420
@item -mcmodel=medmid
16421
@opindex mcmodel=medmid
16422
Generate code for the Medium/Middle code model: 64-bit addresses, programs
16423
must be linked in the low 44 bits of memory, the text and data segments must
16424
be less than 2GB in size and the data segment must be located within 2GB of
16425
the text segment.
16426
 
16427
@item -mcmodel=medany
16428
@opindex mcmodel=medany
16429
Generate code for the Medium/Anywhere code model: 64-bit addresses, programs
16430
may be linked anywhere in memory, the text and data segments must be less
16431
than 2GB in size and the data segment must be located within 2GB of the
16432
text segment.
16433
 
16434
@item -mcmodel=embmedany
16435
@opindex mcmodel=embmedany
16436
Generate code for the Medium/Anywhere code model for embedded systems:
16437
64-bit addresses, the text and data segments must be less than 2GB in
16438
size, both starting anywhere in memory (determined at link time).  The
16439
global register %g4 points to the base of the data segment.  Programs
16440
are statically linked and PIC is not supported.
16441
 
16442
@item -mstack-bias
16443
@itemx -mno-stack-bias
16444
@opindex mstack-bias
16445
@opindex mno-stack-bias
16446
With @option{-mstack-bias}, GCC assumes that the stack pointer, and
16447
frame pointer if present, are offset by @minus{}2047 which must be added back
16448
when making stack frame references.  This is the default in 64-bit mode.
16449
Otherwise, assume no such offset is present.
16450
@end table
16451
 
16452
These switches are supported in addition to the above on Solaris:
16453
 
16454
@table @gcctabopt
16455
@item -threads
16456
@opindex threads
16457
Add support for multithreading using the Solaris threads library.  This
16458
option sets flags for both the preprocessor and linker.  This option does
16459
not affect the thread safety of object code produced by the compiler or
16460
that of libraries supplied with it.
16461
 
16462
@item -pthreads
16463
@opindex pthreads
16464
Add support for multithreading using the POSIX threads library.  This
16465
option sets flags for both the preprocessor and linker.  This option does
16466
not affect the thread safety of object code produced  by the compiler or
16467
that of libraries supplied with it.
16468
 
16469
@item -pthread
16470
@opindex pthread
16471
This is a synonym for @option{-pthreads}.
16472
@end table
16473
 
16474
@node SPU Options
16475
@subsection SPU Options
16476
@cindex SPU options
16477
 
16478
These @samp{-m} options are supported on the SPU:
16479
 
16480
@table @gcctabopt
16481
@item -mwarn-reloc
16482
@itemx -merror-reloc
16483
@opindex mwarn-reloc
16484
@opindex merror-reloc
16485
 
16486
The loader for SPU does not handle dynamic relocations.  By default, GCC
16487
will give an error when it generates code that requires a dynamic
16488
relocation.  @option{-mno-error-reloc} disables the error,
16489
@option{-mwarn-reloc} will generate a warning instead.
16490
 
16491
@item -msafe-dma
16492
@itemx -munsafe-dma
16493
@opindex msafe-dma
16494
@opindex munsafe-dma
16495
 
16496
Instructions which initiate or test completion of DMA must not be
16497
reordered with respect to loads and stores of the memory which is being
16498
accessed.  Users typically address this problem using the volatile
16499
keyword, but that can lead to inefficient code in places where the
16500
memory is known to not change.  Rather than mark the memory as volatile
16501
we treat the DMA instructions as potentially effecting all memory.  With
16502
@option{-munsafe-dma} users must use the volatile keyword to protect
16503
memory accesses.
16504
 
16505
@item -mbranch-hints
16506
@opindex mbranch-hints
16507
 
16508
By default, GCC will generate a branch hint instruction to avoid
16509
pipeline stalls for always taken or probably taken branches.  A hint
16510
will not be generated closer than 8 instructions away from its branch.
16511
There is little reason to disable them, except for debugging purposes,
16512
or to make an object a little bit smaller.
16513
 
16514
@item -msmall-mem
16515
@itemx -mlarge-mem
16516
@opindex msmall-mem
16517
@opindex mlarge-mem
16518
 
16519
By default, GCC generates code assuming that addresses are never larger
16520
than 18 bits.  With @option{-mlarge-mem} code is generated that assumes
16521
a full 32 bit address.
16522
 
16523
@item -mstdmain
16524
@opindex mstdmain
16525
 
16526
By default, GCC links against startup code that assumes the SPU-style
16527
main function interface (which has an unconventional parameter list).
16528
With @option{-mstdmain}, GCC will link your program against startup
16529
code that assumes a C99-style interface to @code{main}, including a
16530
local copy of @code{argv} strings.
16531
 
16532
@item -mfixed-range=@var{register-range}
16533
@opindex mfixed-range
16534
Generate code treating the given register range as fixed registers.
16535
A fixed register is one that the register allocator can not use.  This is
16536
useful when compiling kernel code.  A register range is specified as
16537
two registers separated by a dash.  Multiple register ranges can be
16538
specified separated by a comma.
16539
 
16540
@item -mea32
16541
@itemx -mea64
16542
@opindex mea32
16543
@opindex mea64
16544
Compile code assuming that pointers to the PPU address space accessed
16545
via the @code{__ea} named address space qualifier are either 32 or 64
16546
bits wide.  The default is 32 bits.  As this is an ABI changing option,
16547
all object code in an executable must be compiled with the same setting.
16548
 
16549
@item -maddress-space-conversion
16550
@itemx -mno-address-space-conversion
16551
@opindex maddress-space-conversion
16552
@opindex mno-address-space-conversion
16553
Allow/disallow treating the @code{__ea} address space as superset
16554
of the generic address space.  This enables explicit type casts
16555
between @code{__ea} and generic pointer as well as implicit
16556
conversions of generic pointers to @code{__ea} pointers.  The
16557
default is to allow address space pointer conversions.
16558
 
16559
@item -mcache-size=@var{cache-size}
16560
@opindex mcache-size
16561
This option controls the version of libgcc that the compiler links to an
16562
executable and selects a software-managed cache for accessing variables
16563
in the @code{__ea} address space with a particular cache size.  Possible
16564
options for @var{cache-size} are @samp{8}, @samp{16}, @samp{32}, @samp{64}
16565
and @samp{128}.  The default cache size is 64KB.
16566
 
16567
@item -matomic-updates
16568
@itemx -mno-atomic-updates
16569
@opindex matomic-updates
16570
@opindex mno-atomic-updates
16571
This option controls the version of libgcc that the compiler links to an
16572
executable and selects whether atomic updates to the software-managed
16573
cache of PPU-side variables are used.  If you use atomic updates, changes
16574
to a PPU variable from SPU code using the @code{__ea} named address space
16575
qualifier will not interfere with changes to other PPU variables residing
16576
in the same cache line from PPU code.  If you do not use atomic updates,
16577
such interference may occur; however, writing back cache lines will be
16578
more efficient.  The default behavior is to use atomic updates.
16579
 
16580
@item -mdual-nops
16581
@itemx -mdual-nops=@var{n}
16582
@opindex mdual-nops
16583
By default, GCC will insert nops to increase dual issue when it expects
16584
it to increase performance.  @var{n} can be a value from 0 to 10.  A
16585
smaller @var{n} will insert fewer nops.  10 is the default, 0 is the
16586
same as @option{-mno-dual-nops}.  Disabled with @option{-Os}.
16587
 
16588
@item -mhint-max-nops=@var{n}
16589
@opindex mhint-max-nops
16590
Maximum number of nops to insert for a branch hint.  A branch hint must
16591
be at least 8 instructions away from the branch it is effecting.  GCC
16592
will insert up to @var{n} nops to enforce this, otherwise it will not
16593
generate the branch hint.
16594
 
16595
@item -mhint-max-distance=@var{n}
16596
@opindex mhint-max-distance
16597
The encoding of the branch hint instruction limits the hint to be within
16598
256 instructions of the branch it is effecting.  By default, GCC makes
16599
sure it is within 125.
16600
 
16601
@item -msafe-hints
16602
@opindex msafe-hints
16603
Work around a hardware bug which causes the SPU to stall indefinitely.
16604
By default, GCC will insert the @code{hbrp} instruction to make sure
16605
this stall won't happen.
16606
 
16607
@end table
16608
 
16609
@node System V Options
16610
@subsection Options for System V
16611
 
16612
These additional options are available on System V Release 4 for
16613
compatibility with other compilers on those systems:
16614
 
16615
@table @gcctabopt
16616
@item -G
16617
@opindex G
16618
Create a shared object.
16619
It is recommended that @option{-symbolic} or @option{-shared} be used instead.
16620
 
16621
@item -Qy
16622
@opindex Qy
16623
Identify the versions of each tool used by the compiler, in a
16624
@code{.ident} assembler directive in the output.
16625
 
16626
@item -Qn
16627
@opindex Qn
16628
Refrain from adding @code{.ident} directives to the output file (this is
16629
the default).
16630
 
16631
@item -YP,@var{dirs}
16632
@opindex YP
16633
Search the directories @var{dirs}, and no others, for libraries
16634
specified with @option{-l}.
16635
 
16636
@item -Ym,@var{dir}
16637
@opindex Ym
16638
Look in the directory @var{dir} to find the M4 preprocessor.
16639
The assembler uses this option.
16640
@c This is supposed to go with a -Yd for predefined M4 macro files, but
16641
@c the generic assembler that comes with Solaris takes just -Ym.
16642
@end table
16643
 
16644
@node V850 Options
16645
@subsection V850 Options
16646
@cindex V850 Options
16647
 
16648
These @samp{-m} options are defined for V850 implementations:
16649
 
16650
@table @gcctabopt
16651
@item -mlong-calls
16652
@itemx -mno-long-calls
16653
@opindex mlong-calls
16654
@opindex mno-long-calls
16655
Treat all calls as being far away (near).  If calls are assumed to be
16656
far away, the compiler will always load the functions address up into a
16657
register, and call indirect through the pointer.
16658
 
16659
@item -mno-ep
16660
@itemx -mep
16661
@opindex mno-ep
16662
@opindex mep
16663
Do not optimize (do optimize) basic blocks that use the same index
16664
pointer 4 or more times to copy pointer into the @code{ep} register, and
16665
use the shorter @code{sld} and @code{sst} instructions.  The @option{-mep}
16666
option is on by default if you optimize.
16667
 
16668
@item -mno-prolog-function
16669
@itemx -mprolog-function
16670
@opindex mno-prolog-function
16671
@opindex mprolog-function
16672
Do not use (do use) external functions to save and restore registers
16673
at the prologue and epilogue of a function.  The external functions
16674
are slower, but use less code space if more than one function saves
16675
the same number of registers.  The @option{-mprolog-function} option
16676
is on by default if you optimize.
16677
 
16678
@item -mspace
16679
@opindex mspace
16680
Try to make the code as small as possible.  At present, this just turns
16681
on the @option{-mep} and @option{-mprolog-function} options.
16682
 
16683
@item -mtda=@var{n}
16684
@opindex mtda
16685
Put static or global variables whose size is @var{n} bytes or less into
16686
the tiny data area that register @code{ep} points to.  The tiny data
16687
area can hold up to 256 bytes in total (128 bytes for byte references).
16688
 
16689
@item -msda=@var{n}
16690
@opindex msda
16691
Put static or global variables whose size is @var{n} bytes or less into
16692
the small data area that register @code{gp} points to.  The small data
16693
area can hold up to 64 kilobytes.
16694
 
16695
@item -mzda=@var{n}
16696
@opindex mzda
16697
Put static or global variables whose size is @var{n} bytes or less into
16698
the first 32 kilobytes of memory.
16699
 
16700
@item -mv850
16701
@opindex mv850
16702
Specify that the target processor is the V850.
16703
 
16704
@item -mbig-switch
16705
@opindex mbig-switch
16706
Generate code suitable for big switch tables.  Use this option only if
16707
the assembler/linker complain about out of range branches within a switch
16708
table.
16709
 
16710
@item -mapp-regs
16711
@opindex mapp-regs
16712
This option will cause r2 and r5 to be used in the code generated by
16713
the compiler.  This setting is the default.
16714
 
16715
@item -mno-app-regs
16716
@opindex mno-app-regs
16717
This option will cause r2 and r5 to be treated as fixed registers.
16718
 
16719
@item -mv850e1
16720
@opindex mv850e1
16721
Specify that the target processor is the V850E1.  The preprocessor
16722
constants @samp{__v850e1__} and @samp{__v850e__} will be defined if
16723
this option is used.
16724
 
16725
@item -mv850e
16726
@opindex mv850e
16727
Specify that the target processor is the V850E@.  The preprocessor
16728
constant @samp{__v850e__} will be defined if this option is used.
16729
 
16730
If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
16731
are defined then a default target processor will be chosen and the
16732
relevant @samp{__v850*__} preprocessor constant will be defined.
16733
 
16734
The preprocessor constants @samp{__v850} and @samp{__v851__} are always
16735
defined, regardless of which processor variant is the target.
16736
 
16737
@item -mdisable-callt
16738
@opindex mdisable-callt
16739
This option will suppress generation of the CALLT instruction for the
16740
v850e and v850e1 flavors of the v850 architecture.  The default is
16741
@option{-mno-disable-callt} which allows the CALLT instruction to be used.
16742
 
16743
@end table
16744
 
16745
@node VAX Options
16746
@subsection VAX Options
16747
@cindex VAX options
16748
 
16749
These @samp{-m} options are defined for the VAX:
16750
 
16751
@table @gcctabopt
16752
@item -munix
16753
@opindex munix
16754
Do not output certain jump instructions (@code{aobleq} and so on)
16755
that the Unix assembler for the VAX cannot handle across long
16756
ranges.
16757
 
16758
@item -mgnu
16759
@opindex mgnu
16760
Do output those jump instructions, on the assumption that you
16761
will assemble with the GNU assembler.
16762
 
16763
@item -mg
16764
@opindex mg
16765
Output code for g-format floating point numbers instead of d-format.
16766
@end table
16767
 
16768
@node VxWorks Options
16769
@subsection VxWorks Options
16770
@cindex VxWorks Options
16771
 
16772
The options in this section are defined for all VxWorks targets.
16773
Options specific to the target hardware are listed with the other
16774
options for that target.
16775
 
16776
@table @gcctabopt
16777
@item -mrtp
16778
@opindex mrtp
16779
GCC can generate code for both VxWorks kernels and real time processes
16780
(RTPs).  This option switches from the former to the latter.  It also
16781
defines the preprocessor macro @code{__RTP__}.
16782
 
16783
@item -non-static
16784
@opindex non-static
16785
Link an RTP executable against shared libraries rather than static
16786
libraries.  The options @option{-static} and @option{-shared} can
16787
also be used for RTPs (@pxref{Link Options}); @option{-static}
16788
is the default.
16789
 
16790
@item -Bstatic
16791
@itemx -Bdynamic
16792
@opindex Bstatic
16793
@opindex Bdynamic
16794
These options are passed down to the linker.  They are defined for
16795
compatibility with Diab.
16796
 
16797
@item -Xbind-lazy
16798
@opindex Xbind-lazy
16799
Enable lazy binding of function calls.  This option is equivalent to
16800
@option{-Wl,-z,now} and is defined for compatibility with Diab.
16801
 
16802
@item -Xbind-now
16803
@opindex Xbind-now
16804
Disable lazy binding of function calls.  This option is the default and
16805
is defined for compatibility with Diab.
16806
@end table
16807
 
16808
@node x86-64 Options
16809
@subsection x86-64 Options
16810
@cindex x86-64 options
16811
 
16812
These are listed under @xref{i386 and x86-64 Options}.
16813
 
16814
@node i386 and x86-64 Windows Options
16815
@subsection i386 and x86-64 Windows Options
16816
@cindex i386 and x86-64 Windows Options
16817
 
16818
These additional options are available for Windows targets:
16819
 
16820
@table @gcctabopt
16821
@item -mconsole
16822
@opindex mconsole
16823
This option is available for Cygwin and MinGW targets.  It
16824
specifies that a console application is to be generated, by
16825
instructing the linker to set the PE header subsystem type
16826
required for console applications.
16827
This is the default behavior for Cygwin and MinGW targets.
16828
 
16829
@item -mcygwin
16830
@opindex mcygwin
16831
This option is available for Cygwin targets.  It specifies that
16832
the Cygwin internal interface is to be used for predefined
16833
preprocessor macros, C runtime libraries and related linker
16834
paths and options.  For Cygwin targets this is the default behavior.
16835
This option is deprecated and will be removed in a future release.
16836
 
16837
@item -mno-cygwin
16838
@opindex mno-cygwin
16839
This option is available for Cygwin targets.  It specifies that
16840
the MinGW internal interface is to be used instead of Cygwin's, by
16841
setting MinGW-related predefined macros and linker paths and default
16842
library options.
16843
This option is deprecated and will be removed in a future release.
16844
 
16845
@item -mdll
16846
@opindex mdll
16847
This option is available for Cygwin and MinGW targets.  It
16848
specifies that a DLL - a dynamic link library - is to be
16849
generated, enabling the selection of the required runtime
16850
startup object and entry point.
16851
 
16852
@item -mnop-fun-dllimport
16853
@opindex mnop-fun-dllimport
16854
This option is available for Cygwin and MinGW targets.  It
16855
specifies that the dllimport attribute should be ignored.
16856
 
16857
@item -mthread
16858
@opindex mthread
16859
This option is available for MinGW targets. It specifies
16860
that MinGW-specific thread support is to be used.
16861
 
16862
@item -municode
16863
@opindex municode
16864
This option is available for mingw-w64 targets.  It specifies
16865
that the UNICODE macro is getting pre-defined and that the
16866
unicode capable runtime startup code is chosen.
16867
 
16868
@item -mwin32
16869
@opindex mwin32
16870
This option is available for Cygwin and MinGW targets.  It
16871
specifies that the typical Windows pre-defined macros are to
16872
be set in the pre-processor, but does not influence the choice
16873
of runtime library/startup code.
16874
 
16875
@item -mwindows
16876
@opindex mwindows
16877
This option is available for Cygwin and MinGW targets.  It
16878
specifies that a GUI application is to be generated by
16879
instructing the linker to set the PE header subsystem type
16880
appropriately.
16881
 
16882
@item -fno-set-stack-executable
16883
@opindex fno-set-stack-executable
16884
This option is available for MinGW targets. It specifies that
16885
the executable flag for stack used by nested functions isn't
16886
set. This is necessary for binaries running in kernel mode of
16887
Windows, as there the user32 API, which is used to set executable
16888
privileges, isn't available.
16889
 
16890
@item -mpe-aligned-commons
16891
@opindex mpe-aligned-commons
16892
This option is available for Cygwin and MinGW targets.  It
16893
specifies that the GNU extension to the PE file format that
16894
permits the correct alignment of COMMON variables should be
16895
used when generating code.  It will be enabled by default if
16896
GCC detects that the target assembler found during configuration
16897
supports the feature.
16898
@end table
16899
 
16900
See also under @ref{i386 and x86-64 Options} for standard options.
16901
 
16902
@node Xstormy16 Options
16903
@subsection Xstormy16 Options
16904
@cindex Xstormy16 Options
16905
 
16906
These options are defined for Xstormy16:
16907
 
16908
@table @gcctabopt
16909
@item -msim
16910
@opindex msim
16911
Choose startup files and linker script suitable for the simulator.
16912
@end table
16913
 
16914
@node Xtensa Options
16915
@subsection Xtensa Options
16916
@cindex Xtensa Options
16917
 
16918
These options are supported for Xtensa targets:
16919
 
16920
@table @gcctabopt
16921
@item -mconst16
16922
@itemx -mno-const16
16923
@opindex mconst16
16924
@opindex mno-const16
16925
Enable or disable use of @code{CONST16} instructions for loading
16926
constant values.  The @code{CONST16} instruction is currently not a
16927
standard option from Tensilica.  When enabled, @code{CONST16}
16928
instructions are always used in place of the standard @code{L32R}
16929
instructions.  The use of @code{CONST16} is enabled by default only if
16930
the @code{L32R} instruction is not available.
16931
 
16932
@item -mfused-madd
16933
@itemx -mno-fused-madd
16934
@opindex mfused-madd
16935
@opindex mno-fused-madd
16936
Enable or disable use of fused multiply/add and multiply/subtract
16937
instructions in the floating-point option.  This has no effect if the
16938
floating-point option is not also enabled.  Disabling fused multiply/add
16939
and multiply/subtract instructions forces the compiler to use separate
16940
instructions for the multiply and add/subtract operations.  This may be
16941
desirable in some cases where strict IEEE 754-compliant results are
16942
required: the fused multiply add/subtract instructions do not round the
16943
intermediate result, thereby producing results with @emph{more} bits of
16944
precision than specified by the IEEE standard.  Disabling fused multiply
16945
add/subtract instructions also ensures that the program output is not
16946
sensitive to the compiler's ability to combine multiply and add/subtract
16947
operations.
16948
 
16949
@item -mserialize-volatile
16950
@itemx -mno-serialize-volatile
16951
@opindex mserialize-volatile
16952
@opindex mno-serialize-volatile
16953
When this option is enabled, GCC inserts @code{MEMW} instructions before
16954
@code{volatile} memory references to guarantee sequential consistency.
16955
The default is @option{-mserialize-volatile}.  Use
16956
@option{-mno-serialize-volatile} to omit the @code{MEMW} instructions.
16957
 
16958
@item -mtext-section-literals
16959
@itemx -mno-text-section-literals
16960
@opindex mtext-section-literals
16961
@opindex mno-text-section-literals
16962
Control the treatment of literal pools.  The default is
16963
@option{-mno-text-section-literals}, which places literals in a separate
16964
section in the output file.  This allows the literal pool to be placed
16965
in a data RAM/ROM, and it also allows the linker to combine literal
16966
pools from separate object files to remove redundant literals and
16967
improve code size.  With @option{-mtext-section-literals}, the literals
16968
are interspersed in the text section in order to keep them as close as
16969
possible to their references.  This may be necessary for large assembly
16970
files.
16971
 
16972
@item -mtarget-align
16973
@itemx -mno-target-align
16974
@opindex mtarget-align
16975
@opindex mno-target-align
16976
When this option is enabled, GCC instructs the assembler to
16977
automatically align instructions to reduce branch penalties at the
16978
expense of some code density.  The assembler attempts to widen density
16979
instructions to align branch targets and the instructions following call
16980
instructions.  If there are not enough preceding safe density
16981
instructions to align a target, no widening will be performed.  The
16982
default is @option{-mtarget-align}.  These options do not affect the
16983
treatment of auto-aligned instructions like @code{LOOP}, which the
16984
assembler will always align, either by widening density instructions or
16985
by inserting no-op instructions.
16986
 
16987
@item -mlongcalls
16988
@itemx -mno-longcalls
16989
@opindex mlongcalls
16990
@opindex mno-longcalls
16991
When this option is enabled, GCC instructs the assembler to translate
16992
direct calls to indirect calls unless it can determine that the target
16993
of a direct call is in the range allowed by the call instruction.  This
16994
translation typically occurs for calls to functions in other source
16995
files.  Specifically, the assembler translates a direct @code{CALL}
16996
instruction into an @code{L32R} followed by a @code{CALLX} instruction.
16997
The default is @option{-mno-longcalls}.  This option should be used in
16998
programs where the call target can potentially be out of range.  This
16999
option is implemented in the assembler, not the compiler, so the
17000
assembly code generated by GCC will still show direct call
17001
instructions---look at the disassembled object code to see the actual
17002
instructions.  Note that the assembler will use an indirect call for
17003
every cross-file call, not just those that really will be out of range.
17004
@end table
17005
 
17006
@node zSeries Options
17007
@subsection zSeries Options
17008
@cindex zSeries options
17009
 
17010
These are listed under @xref{S/390 and zSeries Options}.
17011
 
17012
@node Code Gen Options
17013
@section Options for Code Generation Conventions
17014
@cindex code generation conventions
17015
@cindex options, code generation
17016
@cindex run-time options
17017
 
17018
These machine-independent options control the interface conventions
17019
used in code generation.
17020
 
17021
Most of them have both positive and negative forms; the negative form
17022
of @option{-ffoo} would be @option{-fno-foo}.  In the table below, only
17023
one of the forms is listed---the one which is not the default.  You
17024
can figure out the other form by either removing @samp{no-} or adding
17025
it.
17026
 
17027
@table @gcctabopt
17028
@item -fbounds-check
17029
@opindex fbounds-check
17030
For front-ends that support it, generate additional code to check that
17031
indices used to access arrays are within the declared range.  This is
17032
currently only supported by the Java and Fortran front-ends, where
17033
this option defaults to true and false respectively.
17034
 
17035
@item -ftrapv
17036
@opindex ftrapv
17037
This option generates traps for signed overflow on addition, subtraction,
17038
multiplication operations.
17039
 
17040
@item -fwrapv
17041
@opindex fwrapv
17042
This option instructs the compiler to assume that signed arithmetic
17043
overflow of addition, subtraction and multiplication wraps around
17044
using twos-complement representation.  This flag enables some optimizations
17045
and disables others.  This option is enabled by default for the Java
17046
front-end, as required by the Java language specification.
17047
 
17048
@item -fexceptions
17049
@opindex fexceptions
17050
Enable exception handling.  Generates extra code needed to propagate
17051
exceptions.  For some targets, this implies GCC will generate frame
17052
unwind information for all functions, which can produce significant data
17053
size overhead, although it does not affect execution.  If you do not
17054
specify this option, GCC will enable it by default for languages like
17055
C++ which normally require exception handling, and disable it for
17056
languages like C that do not normally require it.  However, you may need
17057
to enable this option when compiling C code that needs to interoperate
17058
properly with exception handlers written in C++.  You may also wish to
17059
disable this option if you are compiling older C++ programs that don't
17060
use exception handling.
17061
 
17062
@item -fnon-call-exceptions
17063
@opindex fnon-call-exceptions
17064
Generate code that allows trapping instructions to throw exceptions.
17065
Note that this requires platform-specific runtime support that does
17066
not exist everywhere.  Moreover, it only allows @emph{trapping}
17067
instructions to throw exceptions, i.e.@: memory references or floating
17068
point instructions.  It does not allow exceptions to be thrown from
17069
arbitrary signal handlers such as @code{SIGALRM}.
17070
 
17071
@item -funwind-tables
17072
@opindex funwind-tables
17073
Similar to @option{-fexceptions}, except that it will just generate any needed
17074
static data, but will not affect the generated code in any other way.
17075
You will normally not enable this option; instead, a language processor
17076
that needs this handling would enable it on your behalf.
17077
 
17078
@item -fasynchronous-unwind-tables
17079
@opindex fasynchronous-unwind-tables
17080
Generate unwind table in dwarf2 format, if supported by target machine.  The
17081
table is exact at each instruction boundary, so it can be used for stack
17082
unwinding from asynchronous events (such as debugger or garbage collector).
17083
 
17084
@item -fpcc-struct-return
17085
@opindex fpcc-struct-return
17086
Return ``short'' @code{struct} and @code{union} values in memory like
17087
longer ones, rather than in registers.  This convention is less
17088
efficient, but it has the advantage of allowing intercallability between
17089
GCC-compiled files and files compiled with other compilers, particularly
17090
the Portable C Compiler (pcc).
17091
 
17092
The precise convention for returning structures in memory depends
17093
on the target configuration macros.
17094
 
17095
Short structures and unions are those whose size and alignment match
17096
that of some integer type.
17097
 
17098
@strong{Warning:} code compiled with the @option{-fpcc-struct-return}
17099
switch is not binary compatible with code compiled with the
17100
@option{-freg-struct-return} switch.
17101
Use it to conform to a non-default application binary interface.
17102
 
17103
@item -freg-struct-return
17104
@opindex freg-struct-return
17105
Return @code{struct} and @code{union} values in registers when possible.
17106
This is more efficient for small structures than
17107
@option{-fpcc-struct-return}.
17108
 
17109
If you specify neither @option{-fpcc-struct-return} nor
17110
@option{-freg-struct-return}, GCC defaults to whichever convention is
17111
standard for the target.  If there is no standard convention, GCC
17112
defaults to @option{-fpcc-struct-return}, except on targets where GCC is
17113
the principal compiler.  In those cases, we can choose the standard, and
17114
we chose the more efficient register return alternative.
17115
 
17116
@strong{Warning:} code compiled with the @option{-freg-struct-return}
17117
switch is not binary compatible with code compiled with the
17118
@option{-fpcc-struct-return} switch.
17119
Use it to conform to a non-default application binary interface.
17120
 
17121
@item -fshort-enums
17122
@opindex fshort-enums
17123
Allocate to an @code{enum} type only as many bytes as it needs for the
17124
declared range of possible values.  Specifically, the @code{enum} type
17125
will be equivalent to the smallest integer type which has enough room.
17126
 
17127
@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
17128
code that is not binary compatible with code generated without that switch.
17129
Use it to conform to a non-default application binary interface.
17130
 
17131
@item -fshort-double
17132
@opindex fshort-double
17133
Use the same size for @code{double} as for @code{float}.
17134
 
17135
@strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
17136
code that is not binary compatible with code generated without that switch.
17137
Use it to conform to a non-default application binary interface.
17138
 
17139
@item -fshort-wchar
17140
@opindex fshort-wchar
17141
Override the underlying type for @samp{wchar_t} to be @samp{short
17142
unsigned int} instead of the default for the target.  This option is
17143
useful for building programs to run under WINE@.
17144
 
17145
@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
17146
code that is not binary compatible with code generated without that switch.
17147
Use it to conform to a non-default application binary interface.
17148
 
17149
@item -fno-common
17150
@opindex fno-common
17151
In C code, controls the placement of uninitialized global variables.
17152
Unix C compilers have traditionally permitted multiple definitions of
17153
such variables in different compilation units by placing the variables
17154
in a common block.
17155
This is the behavior specified by @option{-fcommon}, and is the default
17156
for GCC on most targets.
17157
On the other hand, this behavior is not required by ISO C, and on some
17158
targets may carry a speed or code size penalty on variable references.
17159
The @option{-fno-common} option specifies that the compiler should place
17160
uninitialized global variables in the data section of the object file,
17161
rather than generating them as common blocks.
17162
This has the effect that if the same variable is declared
17163
(without @code{extern}) in two different compilations,
17164
you will get a multiple-definition error when you link them.
17165
In this case, you must compile with @option{-fcommon} instead.
17166
Compiling with @option{-fno-common} is useful on targets for which
17167
it provides better performance, or if you wish to verify that the
17168
program will work on other systems which always treat uninitialized
17169
variable declarations this way.
17170
 
17171
@item -fno-ident
17172
@opindex fno-ident
17173
Ignore the @samp{#ident} directive.
17174
 
17175
@item -finhibit-size-directive
17176
@opindex finhibit-size-directive
17177
Don't output a @code{.size} assembler directive, or anything else that
17178
would cause trouble if the function is split in the middle, and the
17179
two halves are placed at locations far apart in memory.  This option is
17180
used when compiling @file{crtstuff.c}; you should not need to use it
17181
for anything else.
17182
 
17183
@item -fverbose-asm
17184
@opindex fverbose-asm
17185
Put extra commentary information in the generated assembly code to
17186
make it more readable.  This option is generally only of use to those
17187
who actually need to read the generated assembly code (perhaps while
17188
debugging the compiler itself).
17189
 
17190
@option{-fno-verbose-asm}, the default, causes the
17191
extra information to be omitted and is useful when comparing two assembler
17192
files.
17193
 
17194
@item -frecord-gcc-switches
17195
@opindex frecord-gcc-switches
17196
This switch causes the command line that was used to invoke the
17197
compiler to be recorded into the object file that is being created.
17198
This switch is only implemented on some targets and the exact format
17199
of the recording is target and binary file format dependent, but it
17200
usually takes the form of a section containing ASCII text.  This
17201
switch is related to the @option{-fverbose-asm} switch, but that
17202
switch only records information in the assembler output file as
17203
comments, so it never reaches the object file.
17204
 
17205
@item -fpic
17206
@opindex fpic
17207
@cindex global offset table
17208
@cindex PIC
17209
Generate position-independent code (PIC) suitable for use in a shared
17210
library, if supported for the target machine.  Such code accesses all
17211
constant addresses through a global offset table (GOT)@.  The dynamic
17212
loader resolves the GOT entries when the program starts (the dynamic
17213
loader is not part of GCC; it is part of the operating system).  If
17214
the GOT size for the linked executable exceeds a machine-specific
17215
maximum size, you get an error message from the linker indicating that
17216
@option{-fpic} does not work; in that case, recompile with @option{-fPIC}
17217
instead.  (These maximums are 8k on the SPARC and 32k
17218
on the m68k and RS/6000.  The 386 has no such limit.)
17219
 
17220
Position-independent code requires special support, and therefore works
17221
only on certain machines.  For the 386, GCC supports PIC for System V
17222
but not for the Sun 386i.  Code generated for the IBM RS/6000 is always
17223
position-independent.
17224
 
17225
When this flag is set, the macros @code{__pic__} and @code{__PIC__}
17226
are defined to 1.
17227
 
17228
@item -fPIC
17229
@opindex fPIC
17230
If supported for the target machine, emit position-independent code,
17231
suitable for dynamic linking and avoiding any limit on the size of the
17232
global offset table.  This option makes a difference on the m68k,
17233
PowerPC and SPARC@.
17234
 
17235
Position-independent code requires special support, and therefore works
17236
only on certain machines.
17237
 
17238
When this flag is set, the macros @code{__pic__} and @code{__PIC__}
17239
are defined to 2.
17240
 
17241
@item -fpie
17242
@itemx -fPIE
17243
@opindex fpie
17244
@opindex fPIE
17245
These options are similar to @option{-fpic} and @option{-fPIC}, but
17246
generated position independent code can be only linked into executables.
17247
Usually these options are used when @option{-pie} GCC option will be
17248
used during linking.
17249
 
17250
@option{-fpie} and @option{-fPIE} both define the macros
17251
@code{__pie__} and @code{__PIE__}.  The macros have the value 1
17252
for @option{-fpie} and 2 for @option{-fPIE}.
17253
 
17254
@item -fno-jump-tables
17255
@opindex fno-jump-tables
17256
Do not use jump tables for switch statements even where it would be
17257
more efficient than other code generation strategies.  This option is
17258
of use in conjunction with @option{-fpic} or @option{-fPIC} for
17259
building code which forms part of a dynamic linker and cannot
17260
reference the address of a jump table.  On some targets, jump tables
17261
do not require a GOT and this option is not needed.
17262
 
17263
@item -ffixed-@var{reg}
17264
@opindex ffixed
17265
Treat the register named @var{reg} as a fixed register; generated code
17266
should never refer to it (except perhaps as a stack pointer, frame
17267
pointer or in some other fixed role).
17268
 
17269
@var{reg} must be the name of a register.  The register names accepted
17270
are machine-specific and are defined in the @code{REGISTER_NAMES}
17271
macro in the machine description macro file.
17272
 
17273
This flag does not have a negative form, because it specifies a
17274
three-way choice.
17275
 
17276
@item -fcall-used-@var{reg}
17277
@opindex fcall-used
17278
Treat the register named @var{reg} as an allocable register that is
17279
clobbered by function calls.  It may be allocated for temporaries or
17280
variables that do not live across a call.  Functions compiled this way
17281
will not save and restore the register @var{reg}.
17282
 
17283
It is an error to used this flag with the frame pointer or stack pointer.
17284
Use of this flag for other registers that have fixed pervasive roles in
17285
the machine's execution model will produce disastrous results.
17286
 
17287
This flag does not have a negative form, because it specifies a
17288
three-way choice.
17289
 
17290
@item -fcall-saved-@var{reg}
17291
@opindex fcall-saved
17292
Treat the register named @var{reg} as an allocable register saved by
17293
functions.  It may be allocated even for temporaries or variables that
17294
live across a call.  Functions compiled this way will save and restore
17295
the register @var{reg} if they use it.
17296
 
17297
It is an error to used this flag with the frame pointer or stack pointer.
17298
Use of this flag for other registers that have fixed pervasive roles in
17299
the machine's execution model will produce disastrous results.
17300
 
17301
A different sort of disaster will result from the use of this flag for
17302
a register in which function values may be returned.
17303
 
17304
This flag does not have a negative form, because it specifies a
17305
three-way choice.
17306
 
17307
@item -fpack-struct[=@var{n}]
17308
@opindex fpack-struct
17309
Without a value specified, pack all structure members together without
17310
holes.  When a value is specified (which must be a small power of two), pack
17311
structure members according to this value, representing the maximum
17312
alignment (that is, objects with default alignment requirements larger than
17313
this will be output potentially unaligned at the next fitting location.
17314
 
17315
@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
17316
code that is not binary compatible with code generated without that switch.
17317
Additionally, it makes the code suboptimal.
17318
Use it to conform to a non-default application binary interface.
17319
 
17320
@item -finstrument-functions
17321
@opindex finstrument-functions
17322
Generate instrumentation calls for entry and exit to functions.  Just
17323
after function entry and just before function exit, the following
17324
profiling functions will be called with the address of the current
17325
function and its call site.  (On some platforms,
17326
@code{__builtin_return_address} does not work beyond the current
17327
function, so the call site information may not be available to the
17328
profiling functions otherwise.)
17329
 
17330
@smallexample
17331
void __cyg_profile_func_enter (void *this_fn,
17332
                               void *call_site);
17333
void __cyg_profile_func_exit  (void *this_fn,
17334
                               void *call_site);
17335
@end smallexample
17336
 
17337
The first argument is the address of the start of the current function,
17338
which may be looked up exactly in the symbol table.
17339
 
17340
This instrumentation is also done for functions expanded inline in other
17341
functions.  The profiling calls will indicate where, conceptually, the
17342
inline function is entered and exited.  This means that addressable
17343
versions of such functions must be available.  If all your uses of a
17344
function are expanded inline, this may mean an additional expansion of
17345
code size.  If you use @samp{extern inline} in your C code, an
17346
addressable version of such functions must be provided.  (This is
17347
normally the case anyways, but if you get lucky and the optimizer always
17348
expands the functions inline, you might have gotten away without
17349
providing static copies.)
17350
 
17351
A function may be given the attribute @code{no_instrument_function}, in
17352
which case this instrumentation will not be done.  This can be used, for
17353
example, for the profiling functions listed above, high-priority
17354
interrupt routines, and any functions from which the profiling functions
17355
cannot safely be called (perhaps signal handlers, if the profiling
17356
routines generate output or allocate memory).
17357
 
17358
@item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}
17359
@opindex finstrument-functions-exclude-file-list
17360
 
17361
Set the list of functions that are excluded from instrumentation (see
17362
the description of @code{-finstrument-functions}).  If the file that
17363
contains a function definition matches with one of @var{file}, then
17364
that function is not instrumented.  The match is done on substrings:
17365
if the @var{file} parameter is a substring of the file name, it is
17366
considered to be a match.
17367
 
17368
For example,
17369
@code{-finstrument-functions-exclude-file-list=/bits/stl,include/sys}
17370
will exclude any inline function defined in files whose pathnames
17371
contain @code{/bits/stl} or @code{include/sys}.
17372
 
17373
If, for some reason, you want to include letter @code{','} in one of
17374
@var{sym}, write @code{'\,'}. For example,
17375
@code{-finstrument-functions-exclude-file-list='\,\,tmp'}
17376
(note the single quote surrounding the option).
17377
 
17378
@item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{}
17379
@opindex finstrument-functions-exclude-function-list
17380
 
17381
This is similar to @code{-finstrument-functions-exclude-file-list},
17382
but this option sets the list of function names to be excluded from
17383
instrumentation.  The function name to be matched is its user-visible
17384
name, such as @code{vector<int> blah(const vector<int> &)}, not the
17385
internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}).  The
17386
match is done on substrings: if the @var{sym} parameter is a substring
17387
of the function name, it is considered to be a match.  For C99 and C++
17388
extended identifiers, the function name must be given in UTF-8, not
17389
using universal character names.
17390
 
17391
@item -fstack-check
17392
@opindex fstack-check
17393
Generate code to verify that you do not go beyond the boundary of the
17394
stack.  You should specify this flag if you are running in an
17395
environment with multiple threads, but only rarely need to specify it in
17396
a single-threaded environment since stack overflow is automatically
17397
detected on nearly all systems if there is only one stack.
17398
 
17399
Note that this switch does not actually cause checking to be done; the
17400
operating system or the language runtime must do that.  The switch causes
17401
generation of code to ensure that they see the stack being extended.
17402
 
17403
You can additionally specify a string parameter: @code{no} means no
17404
checking, @code{generic} means force the use of old-style checking,
17405
@code{specific} means use the best checking method and is equivalent
17406
to bare @option{-fstack-check}.
17407
 
17408
Old-style checking is a generic mechanism that requires no specific
17409
target support in the compiler but comes with the following drawbacks:
17410
 
17411
@enumerate
17412
@item
17413
Modified allocation strategy for large objects: they will always be
17414
allocated dynamically if their size exceeds a fixed threshold.
17415
 
17416
@item
17417
Fixed limit on the size of the static frame of functions: when it is
17418
topped by a particular function, stack checking is not reliable and
17419
a warning is issued by the compiler.
17420
 
17421
@item
17422
Inefficiency: because of both the modified allocation strategy and the
17423
generic implementation, the performances of the code are hampered.
17424
@end enumerate
17425
 
17426
Note that old-style stack checking is also the fallback method for
17427
@code{specific} if no target support has been added in the compiler.
17428
 
17429
@item -fstack-limit-register=@var{reg}
17430
@itemx -fstack-limit-symbol=@var{sym}
17431
@itemx -fno-stack-limit
17432
@opindex fstack-limit-register
17433
@opindex fstack-limit-symbol
17434
@opindex fno-stack-limit
17435
Generate code to ensure that the stack does not grow beyond a certain value,
17436
either the value of a register or the address of a symbol.  If the stack
17437
would grow beyond the value, a signal is raised.  For most targets,
17438
the signal is raised before the stack overruns the boundary, so
17439
it is possible to catch the signal without taking special precautions.
17440
 
17441
For instance, if the stack starts at absolute address @samp{0x80000000}
17442
and grows downwards, you can use the flags
17443
@option{-fstack-limit-symbol=__stack_limit} and
17444
@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
17445
of 128KB@.  Note that this may only work with the GNU linker.
17446
 
17447
@cindex aliasing of parameters
17448
@cindex parameters, aliased
17449
@item -fargument-alias
17450
@itemx -fargument-noalias
17451
@itemx -fargument-noalias-global
17452
@itemx -fargument-noalias-anything
17453
@opindex fargument-alias
17454
@opindex fargument-noalias
17455
@opindex fargument-noalias-global
17456
@opindex fargument-noalias-anything
17457
Specify the possible relationships among parameters and between
17458
parameters and global data.
17459
 
17460
@option{-fargument-alias} specifies that arguments (parameters) may
17461
alias each other and may alias global storage.@*
17462
@option{-fargument-noalias} specifies that arguments do not alias
17463
each other, but may alias global storage.@*
17464
@option{-fargument-noalias-global} specifies that arguments do not
17465
alias each other and do not alias global storage.
17466
@option{-fargument-noalias-anything} specifies that arguments do not
17467
alias any other storage.
17468
 
17469
Each language will automatically use whatever option is required by
17470
the language standard.  You should not need to use these options yourself.
17471
 
17472
@item -fleading-underscore
17473
@opindex fleading-underscore
17474
This option and its counterpart, @option{-fno-leading-underscore}, forcibly
17475
change the way C symbols are represented in the object file.  One use
17476
is to help link with legacy assembly code.
17477
 
17478
@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
17479
generate code that is not binary compatible with code generated without that
17480
switch.  Use it to conform to a non-default application binary interface.
17481
Not all targets provide complete support for this switch.
17482
 
17483
@item -ftls-model=@var{model}
17484
@opindex ftls-model
17485
Alter the thread-local storage model to be used (@pxref{Thread-Local}).
17486
The @var{model} argument should be one of @code{global-dynamic},
17487
@code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
17488
 
17489
The default without @option{-fpic} is @code{initial-exec}; with
17490
@option{-fpic} the default is @code{global-dynamic}.
17491
 
17492
@item -fvisibility=@var{default|internal|hidden|protected}
17493
@opindex fvisibility
17494
Set the default ELF image symbol visibility to the specified option---all
17495
symbols will be marked with this unless overridden within the code.
17496
Using this feature can very substantially improve linking and
17497
load times of shared object libraries, produce more optimized
17498
code, provide near-perfect API export and prevent symbol clashes.
17499
It is @strong{strongly} recommended that you use this in any shared objects
17500
you distribute.
17501
 
17502
Despite the nomenclature, @code{default} always means public ie;
17503
available to be linked against from outside the shared object.
17504
@code{protected} and @code{internal} are pretty useless in real-world
17505
usage so the only other commonly used option will be @code{hidden}.
17506
The default if @option{-fvisibility} isn't specified is
17507
@code{default}, i.e., make every
17508
symbol public---this causes the same behavior as previous versions of
17509
GCC@.
17510
 
17511
A good explanation of the benefits offered by ensuring ELF
17512
symbols have the correct visibility is given by ``How To Write
17513
Shared Libraries'' by Ulrich Drepper (which can be found at
17514
@w{@uref{http://people.redhat.com/~drepper/}})---however a superior
17515
solution made possible by this option to marking things hidden when
17516
the default is public is to make the default hidden and mark things
17517
public.  This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
17518
and @code{__attribute__ ((visibility("default")))} instead of
17519
@code{__declspec(dllexport)} you get almost identical semantics with
17520
identical syntax.  This is a great boon to those working with
17521
cross-platform projects.
17522
 
17523
For those adding visibility support to existing code, you may find
17524
@samp{#pragma GCC visibility} of use.  This works by you enclosing
17525
the declarations you wish to set visibility for with (for example)
17526
@samp{#pragma GCC visibility push(hidden)} and
17527
@samp{#pragma GCC visibility pop}.
17528
Bear in mind that symbol visibility should be viewed @strong{as
17529
part of the API interface contract} and thus all new code should
17530
always specify visibility when it is not the default ie; declarations
17531
only for use within the local DSO should @strong{always} be marked explicitly
17532
as hidden as so to avoid PLT indirection overheads---making this
17533
abundantly clear also aids readability and self-documentation of the code.
17534
Note that due to ISO C++ specification requirements, operator new and
17535
operator delete must always be of default visibility.
17536
 
17537
Be aware that headers from outside your project, in particular system
17538
headers and headers from any other library you use, may not be
17539
expecting to be compiled with visibility other than the default.  You
17540
may need to explicitly say @samp{#pragma GCC visibility push(default)}
17541
before including any such headers.
17542
 
17543
@samp{extern} declarations are not affected by @samp{-fvisibility}, so
17544
a lot of code can be recompiled with @samp{-fvisibility=hidden} with
17545
no modifications.  However, this means that calls to @samp{extern}
17546
functions with no explicit visibility will use the PLT, so it is more
17547
effective to use @samp{__attribute ((visibility))} and/or
17548
@samp{#pragma GCC visibility} to tell the compiler which @samp{extern}
17549
declarations should be treated as hidden.
17550
 
17551
Note that @samp{-fvisibility} does affect C++ vague linkage
17552
entities. This means that, for instance, an exception class that will
17553
be thrown between DSOs must be explicitly marked with default
17554
visibility so that the @samp{type_info} nodes will be unified between
17555
the DSOs.
17556
 
17557
An overview of these techniques, their benefits and how to use them
17558
is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
17559
 
17560
@end table
17561
 
17562
@c man end
17563
 
17564
@node Environment Variables
17565
@section Environment Variables Affecting GCC
17566
@cindex environment variables
17567
 
17568
@c man begin ENVIRONMENT
17569
This section describes several environment variables that affect how GCC
17570
operates.  Some of them work by specifying directories or prefixes to use
17571
when searching for various kinds of files.  Some are used to specify other
17572
aspects of the compilation environment.
17573
 
17574
Note that you can also specify places to search using options such as
17575
@option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}).  These
17576
take precedence over places specified using environment variables, which
17577
in turn take precedence over those specified by the configuration of GCC@.
17578
@xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
17579
GNU Compiler Collection (GCC) Internals}.
17580
 
17581
@table @env
17582
@item LANG
17583
@itemx LC_CTYPE
17584
@c @itemx LC_COLLATE
17585
@itemx LC_MESSAGES
17586
@c @itemx LC_MONETARY
17587
@c @itemx LC_NUMERIC
17588
@c @itemx LC_TIME
17589
@itemx LC_ALL
17590
@findex LANG
17591
@findex LC_CTYPE
17592
@c @findex LC_COLLATE
17593
@findex LC_MESSAGES
17594
@c @findex LC_MONETARY
17595
@c @findex LC_NUMERIC
17596
@c @findex LC_TIME
17597
@findex LC_ALL
17598
@cindex locale
17599
These environment variables control the way that GCC uses
17600
localization information that allow GCC to work with different
17601
national conventions.  GCC inspects the locale categories
17602
@env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
17603
so.  These locale categories can be set to any value supported by your
17604
installation.  A typical value is @samp{en_GB.UTF-8} for English in the United
17605
Kingdom encoded in UTF-8.
17606
 
17607
The @env{LC_CTYPE} environment variable specifies character
17608
classification.  GCC uses it to determine the character boundaries in
17609
a string; this is needed for some multibyte encodings that contain quote
17610
and escape characters that would otherwise be interpreted as a string
17611
end or escape.
17612
 
17613
The @env{LC_MESSAGES} environment variable specifies the language to
17614
use in diagnostic messages.
17615
 
17616
If the @env{LC_ALL} environment variable is set, it overrides the value
17617
of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
17618
and @env{LC_MESSAGES} default to the value of the @env{LANG}
17619
environment variable.  If none of these variables are set, GCC
17620
defaults to traditional C English behavior.
17621
 
17622
@item TMPDIR
17623
@findex TMPDIR
17624
If @env{TMPDIR} is set, it specifies the directory to use for temporary
17625
files.  GCC uses temporary files to hold the output of one stage of
17626
compilation which is to be used as input to the next stage: for example,
17627
the output of the preprocessor, which is the input to the compiler
17628
proper.
17629
 
17630
@item GCC_EXEC_PREFIX
17631
@findex GCC_EXEC_PREFIX
17632
If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
17633
names of the subprograms executed by the compiler.  No slash is added
17634
when this prefix is combined with the name of a subprogram, but you can
17635
specify a prefix that ends with a slash if you wish.
17636
 
17637
If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
17638
an appropriate prefix to use based on the pathname it was invoked with.
17639
 
17640
If GCC cannot find the subprogram using the specified prefix, it
17641
tries looking in the usual places for the subprogram.
17642
 
17643
The default value of @env{GCC_EXEC_PREFIX} is
17644
@file{@var{prefix}/lib/gcc/} where @var{prefix} is the prefix to
17645
the installed compiler. In many cases @var{prefix} is the value
17646
of @code{prefix} when you ran the @file{configure} script.
17647
 
17648
Other prefixes specified with @option{-B} take precedence over this prefix.
17649
 
17650
This prefix is also used for finding files such as @file{crt0.o} that are
17651
used for linking.
17652
 
17653
In addition, the prefix is used in an unusual way in finding the
17654
directories to search for header files.  For each of the standard
17655
directories whose name normally begins with @samp{/usr/local/lib/gcc}
17656
(more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
17657
replacing that beginning with the specified prefix to produce an
17658
alternate directory name.  Thus, with @option{-Bfoo/}, GCC will search
17659
@file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
17660
These alternate directories are searched first; the standard directories
17661
come next. If a standard directory begins with the configured
17662
@var{prefix} then the value of @var{prefix} is replaced by
17663
@env{GCC_EXEC_PREFIX} when looking for header files.
17664
 
17665
@item COMPILER_PATH
17666
@findex COMPILER_PATH
17667
The value of @env{COMPILER_PATH} is a colon-separated list of
17668
directories, much like @env{PATH}.  GCC tries the directories thus
17669
specified when searching for subprograms, if it can't find the
17670
subprograms using @env{GCC_EXEC_PREFIX}.
17671
 
17672
@item LIBRARY_PATH
17673
@findex LIBRARY_PATH
17674
The value of @env{LIBRARY_PATH} is a colon-separated list of
17675
directories, much like @env{PATH}.  When configured as a native compiler,
17676
GCC tries the directories thus specified when searching for special
17677
linker files, if it can't find them using @env{GCC_EXEC_PREFIX}.  Linking
17678
using GCC also uses these directories when searching for ordinary
17679
libraries for the @option{-l} option (but directories specified with
17680
@option{-L} come first).
17681
 
17682
@item LANG
17683
@findex LANG
17684
@cindex locale definition
17685
This variable is used to pass locale information to the compiler.  One way in
17686
which this information is used is to determine the character set to be used
17687
when character literals, string literals and comments are parsed in C and C++.
17688
When the compiler is configured to allow multibyte characters,
17689
the following values for @env{LANG} are recognized:
17690
 
17691
@table @samp
17692
@item C-JIS
17693
Recognize JIS characters.
17694
@item C-SJIS
17695
Recognize SJIS characters.
17696
@item C-EUCJP
17697
Recognize EUCJP characters.
17698
@end table
17699
 
17700
If @env{LANG} is not defined, or if it has some other value, then the
17701
compiler will use mblen and mbtowc as defined by the default locale to
17702
recognize and translate multibyte characters.
17703
@end table
17704
 
17705
@noindent
17706
Some additional environments variables affect the behavior of the
17707
preprocessor.
17708
 
17709
@include cppenv.texi
17710
 
17711
@c man end
17712
 
17713
@node Precompiled Headers
17714
@section Using Precompiled Headers
17715
@cindex precompiled headers
17716
@cindex speed of compilation
17717
 
17718
Often large projects have many header files that are included in every
17719
source file.  The time the compiler takes to process these header files
17720
over and over again can account for nearly all of the time required to
17721
build the project.  To make builds faster, GCC allows users to
17722
`precompile' a header file; then, if builds can use the precompiled
17723
header file they will be much faster.
17724
 
17725
To create a precompiled header file, simply compile it as you would any
17726
other file, if necessary using the @option{-x} option to make the driver
17727
treat it as a C or C++ header file.  You will probably want to use a
17728
tool like @command{make} to keep the precompiled header up-to-date when
17729
the headers it contains change.
17730
 
17731
A precompiled header file will be searched for when @code{#include} is
17732
seen in the compilation.  As it searches for the included file
17733
(@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
17734
compiler looks for a precompiled header in each directory just before it
17735
looks for the include file in that directory.  The name searched for is
17736
the name specified in the @code{#include} with @samp{.gch} appended.  If
17737
the precompiled header file can't be used, it is ignored.
17738
 
17739
For instance, if you have @code{#include "all.h"}, and you have
17740
@file{all.h.gch} in the same directory as @file{all.h}, then the
17741
precompiled header file will be used if possible, and the original
17742
header will be used otherwise.
17743
 
17744
Alternatively, you might decide to put the precompiled header file in a
17745
directory and use @option{-I} to ensure that directory is searched
17746
before (or instead of) the directory containing the original header.
17747
Then, if you want to check that the precompiled header file is always
17748
used, you can put a file of the same name as the original header in this
17749
directory containing an @code{#error} command.
17750
 
17751
This also works with @option{-include}.  So yet another way to use
17752
precompiled headers, good for projects not designed with precompiled
17753
header files in mind, is to simply take most of the header files used by
17754
a project, include them from another header file, precompile that header
17755
file, and @option{-include} the precompiled header.  If the header files
17756
have guards against multiple inclusion, they will be skipped because
17757
they've already been included (in the precompiled header).
17758
 
17759
If you need to precompile the same header file for different
17760
languages, targets, or compiler options, you can instead make a
17761
@emph{directory} named like @file{all.h.gch}, and put each precompiled
17762
header in the directory, perhaps using @option{-o}.  It doesn't matter
17763
what you call the files in the directory, every precompiled header in
17764
the directory will be considered.  The first precompiled header
17765
encountered in the directory that is valid for this compilation will
17766
be used; they're searched in no particular order.
17767
 
17768
There are many other possibilities, limited only by your imagination,
17769
good sense, and the constraints of your build system.
17770
 
17771
A precompiled header file can be used only when these conditions apply:
17772
 
17773
@itemize
17774
@item
17775
Only one precompiled header can be used in a particular compilation.
17776
 
17777
@item
17778
A precompiled header can't be used once the first C token is seen.  You
17779
can have preprocessor directives before a precompiled header; you can
17780
even include a precompiled header from inside another header, so long as
17781
there are no C tokens before the @code{#include}.
17782
 
17783
@item
17784
The precompiled header file must be produced for the same language as
17785
the current compilation.  You can't use a C precompiled header for a C++
17786
compilation.
17787
 
17788
@item
17789
The precompiled header file must have been produced by the same compiler
17790
binary as the current compilation is using.
17791
 
17792
@item
17793
Any macros defined before the precompiled header is included must
17794
either be defined in the same way as when the precompiled header was
17795
generated, or must not affect the precompiled header, which usually
17796
means that they don't appear in the precompiled header at all.
17797
 
17798
The @option{-D} option is one way to define a macro before a
17799
precompiled header is included; using a @code{#define} can also do it.
17800
There are also some options that define macros implicitly, like
17801
@option{-O} and @option{-Wdeprecated}; the same rule applies to macros
17802
defined this way.
17803
 
17804
@item If debugging information is output when using the precompiled
17805
header, using @option{-g} or similar, the same kind of debugging information
17806
must have been output when building the precompiled header.  However,
17807
a precompiled header built using @option{-g} can be used in a compilation
17808
when no debugging information is being output.
17809
 
17810
@item The same @option{-m} options must generally be used when building
17811
and using the precompiled header.  @xref{Submodel Options},
17812
for any cases where this rule is relaxed.
17813
 
17814
@item Each of the following options must be the same when building and using
17815
the precompiled header:
17816
 
17817
@gccoptlist{-fexceptions}
17818
 
17819
@item
17820
Some other command-line options starting with @option{-f},
17821
@option{-p}, or @option{-O} must be defined in the same way as when
17822
the precompiled header was generated.  At present, it's not clear
17823
which options are safe to change and which are not; the safest choice
17824
is to use exactly the same options when generating and using the
17825
precompiled header.  The following are known to be safe:
17826
 
17827
@gccoptlist{-fmessage-length=  -fpreprocessed  -fsched-interblock @gol
17828
-fsched-spec  -fsched-spec-load  -fsched-spec-load-dangerous @gol
17829
-fsched-verbose=<number>  -fschedule-insns  -fvisibility= @gol
17830
-pedantic-errors}
17831
 
17832
@end itemize
17833
 
17834
For all of these except the last, the compiler will automatically
17835
ignore the precompiled header if the conditions aren't met.  If you
17836
find an option combination that doesn't work and doesn't cause the
17837
precompiled header to be ignored, please consider filing a bug report,
17838
see @ref{Bugs}.
17839
 
17840
If you do use differing options when generating and using the
17841
precompiled header, the actual behavior will be a mixture of the
17842
behavior for the options.  For instance, if you use @option{-g} to
17843
generate the precompiled header but not when using it, you may or may
17844
not get debugging information for routines in the precompiled header.

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.