Deleted Added
sdiff udiff text old ( 258081 ) new ( 258204 )
full compact
invoke.texi (258081) invoke.texi (258204)
1@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2@c 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
3@c This is part of the GCC manual.
4@c For copying conditions, see the file gcc.texi.
5
6@ignore
7@c man begin INCLUDE
8@include gcc-vers.texi
9@c man end
10
11@c man begin COPYRIGHT
12Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
131999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
14
15Permission is granted to copy, distribute and/or modify this document
16under the terms of the GNU Free Documentation License, Version 1.2 or
17any later version published by the Free Software Foundation; with the
18Invariant Sections being ``GNU General Public License'' and ``Funding
19Free Software'', the Front-Cover texts being (a) (see below), and with
20the Back-Cover Texts being (b) (see below). A copy of the license is
21included in the gfdl(7) man page.
22
23(a) The FSF's Front-Cover Text is:
24
25 A GNU Manual
26
27(b) The FSF's Back-Cover Text is:
28
29 You have freedom to copy and modify this GNU Manual, like GNU
30 software. Copies published by the Free Software Foundation raise
31 funds for GNU development.
32@c man end
33@c Set file name and title for the man page.
34@setfilename gcc
35@settitle GNU project C and C++ compiler
36@c man begin SYNOPSIS
37gcc [@option{-c}|@option{-S}|@option{-E}] [@option{-std=}@var{standard}]
38 [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
39 [@option{-W}@var{warn}@dots{}] [@option{-pedantic}]
40 [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
41 [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
42 [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
43 [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}
44
45Only the most useful options are listed here; see below for the
46remainder. @samp{g++} accepts mostly the same options as @samp{gcc}.
47@c man end
48@c man begin SEEALSO
49gpl(7), gfdl(7), fsf-funding(7),
50cpp(1), gcov(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1)
51and the Info entries for @file{gcc}, @file{cpp}, @file{as},
52@file{ld}, @file{binutils} and @file{gdb}.
53@c man end
54@c man begin BUGS
55For instructions on reporting bugs, see
56@w{@uref{http://gcc.gnu.org/bugs.html}}.
57@c man end
58@c man begin AUTHOR
59See the Info entry for @command{gcc}, or
60@w{@uref{http://gcc.gnu.org/onlinedocs/gcc/Contributors.html}},
61for contributors to GCC@.
62@c man end
63@end ignore
64
65@node Invoking GCC
66@chapter GCC Command Options
67@cindex GCC command options
68@cindex command options
69@cindex options, GCC command
70
71@c man begin DESCRIPTION
72When you invoke GCC, it normally does preprocessing, compilation,
73assembly and linking. The ``overall options'' allow you to stop this
74process at an intermediate stage. For example, the @option{-c} option
75says not to run the linker. Then the output consists of object files
76output by the assembler.
77
78Other options are passed on to one stage of processing. Some options
79control the preprocessor and others the compiler itself. Yet other
80options control the assembler and linker; most of these are not
81documented here, since you rarely need to use any of them.
82
83@cindex C compilation options
84Most of the command line options that you can use with GCC are useful
85for C programs; when an option is only useful with another language
86(usually C++), the explanation says so explicitly. If the description
87for a particular option does not mention a source language, you can use
88that option with all supported languages.
89
90@cindex C++ compilation options
91@xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
92options for compiling C++ programs.
93
94@cindex grouping options
95@cindex options, grouping
96The @command{gcc} program accepts options and file names as operands. Many
97options have multi-letter names; therefore multiple single-letter options
98may @emph{not} be grouped: @option{-dr} is very different from @w{@samp{-d
99-r}}.
100
101@cindex order of options
102@cindex options, order
103You can mix options and other arguments. For the most part, the order
104you use doesn't matter. Order does matter when you use several options
105of the same kind; for example, if you specify @option{-L} more than once,
106the directories are searched in the order specified.
107
108Many options have long names starting with @samp{-f} or with
109@samp{-W}---for example,
110@option{-fmove-loop-invariants}, @option{-Wformat} and so on. Most of
111these have both positive and negative forms; the negative form of
112@option{-ffoo} would be @option{-fno-foo}. This manual documents
113only one of these two forms, whichever one is not the default.
114
115@c man end
116
117@xref{Option Index}, for an index to GCC's options.
118
119@menu
120* Option Summary:: Brief list of all options, without explanations.
121* Overall Options:: Controlling the kind of output:
122 an executable, object files, assembler files,
123 or preprocessed source.
124* Invoking G++:: Compiling C++ programs.
125* C Dialect Options:: Controlling the variant of C language compiled.
126* C++ Dialect Options:: Variations on C++.
127* Language Independent Options:: Controlling how diagnostics should be
128 formatted.
129* Warning Options:: How picky should the compiler be?
130* Debugging Options:: Symbol tables, measurements, and debugging dumps.
131* Optimize Options:: How much optimization?
132* Preprocessor Options:: Controlling header files and macro definitions.
133 Also, getting dependency information for Make.
134* Assembler Options:: Passing options to the assembler.
135* Link Options:: Specifying libraries and so on.
136* Directory Options:: Where to find header files and libraries.
137 Where to find the compiler executable files.
138* Spec Files:: How to pass switches to sub-processes.
139* Target Options:: Running a cross-compiler, or an old version of GCC.
140* Submodel Options:: Specifying minor hardware or convention variations,
141 such as 68010 vs 68020.
142* Code Gen Options:: Specifying conventions for function calls, data layout
143 and register usage.
144* Environment Variables:: Env vars that affect GCC.
145* Precompiled Headers:: Compiling a header once, and using it many times.
146* Running Protoize:: Automatically adding or removing function prototypes.
147@end menu
148
149@c man begin OPTIONS
150
151@node Option Summary
152@section Option Summary
153
154Here is a summary of all the options, grouped by type. Explanations are
155in the following sections.
156
157@table @emph
158@item Overall Options
159@xref{Overall Options,,Options Controlling the Kind of Output}.
160@gccoptlist{-c -S -E -o @var{file} -combine -pipe -pass-exit-codes @gol
161-x @var{language} -v -### --help --target-help --version @@@var{file}}
162
163@item C Language Options
164@xref{C Dialect Options,,Options Controlling C Dialect}.
165@gccoptlist{-ansi -std=@var{standard} -fgnu89-inline @gol
166-aux-info @var{filename} @gol
167-fno-asm -fno-builtin -fno-builtin-@var{function} @gol
168-fhosted -ffreestanding -fopenmp -fms-extensions @gol
169-trigraphs -no-integrated-cpp -traditional -traditional-cpp @gol
170-fallow-single-precision -fcond-mismatch @gol
171-fsigned-bitfields -fsigned-char @gol
172-funsigned-bitfields -funsigned-char}
173
174@item C++ Language Options
175@xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
176@gccoptlist{-fabi-version=@var{n} -fno-access-control -fcheck-new @gol
177-fconserve-space -ffriend-injection @gol
178-fno-elide-constructors @gol
179-fno-enforce-eh-specs @gol
180-ffor-scope -fno-for-scope -fno-gnu-keywords @gol
181-fno-implicit-templates @gol
182-fno-implicit-inline-templates @gol
183-fno-implement-inlines -fms-extensions @gol
184-fno-nonansi-builtins -fno-operator-names @gol
185-fno-optional-diags -fpermissive @gol
186-frepo -fno-rtti -fstats -ftemplate-depth-@var{n} @gol
187-fno-threadsafe-statics -fuse-cxa-atexit -fno-weak -nostdinc++ @gol
188-fno-default-inline -fvisibility-inlines-hidden @gol
189-Wabi -Wctor-dtor-privacy @gol
190-Wnon-virtual-dtor -Wreorder @gol
191-Weffc++ -Wno-deprecated -Wstrict-null-sentinel @gol
192-Wno-non-template-friend -Wold-style-cast @gol
193-Woverloaded-virtual -Wno-pmf-conversions @gol
194-Wsign-promo}
195
196@item Language Independent Options
197@xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}.
198@gccoptlist{-fmessage-length=@var{n} @gol
199-fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]} @gol
200-fdiagnostics-show-option}
201
202@item Warning Options
203@xref{Warning Options,,Options to Request or Suppress Warnings}.
204@gccoptlist{-fsyntax-only -pedantic -pedantic-errors @gol
205-w -Wextra -Wall -Waddress -Waggregate-return -Wno-attributes @gol
206-Wc++-compat -Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment @gol
207-Wconversion -Wno-deprecated-declarations @gol
208-Wdisabled-optimization -Wno-div-by-zero -Wno-endif-labels @gol
209-Werror -Werror=* -Werror-implicit-function-declaration @gol
210-Wfatal-errors -Wfloat-equal -Wformat -Wformat=2 @gol
211-Wno-format-extra-args -Wformat-nonliteral @gol
212-Wformat-security -Wformat-y2k @gol
213-Wimplicit -Wimplicit-function-declaration -Wimplicit-int @gol
214-Wimport -Wno-import -Winit-self -Winline @gol
215-Wno-int-to-pointer-cast @gol
216-Wno-invalid-offsetof -Winvalid-pch @gol
217-Wlarger-than-@var{len} -Wunsafe-loop-optimizations -Wlong-long @gol
218-Wmain -Wmissing-braces -Wmissing-field-initializers @gol
219-Wmissing-format-attribute -Wmissing-include-dirs @gol
220-Wmissing-noreturn @gol
221-Wno-multichar -Wnonnull -Wno-overflow @gol
222-Woverlength-strings -Wpacked -Wpadded @gol
223-Wparentheses -Wpointer-arith -Wno-pointer-to-int-cast @gol
224-Wredundant-decls @gol
225-Wreturn-type -Wsequence-point -Wshadow @gol
226-Wsign-compare -Wstack-protector @gol
227-Wstrict-aliasing -Wstrict-aliasing=2 @gol
228-Wstrict-overflow -Wstrict-overflow=@var{n} @gol
229-Wswitch -Wswitch-default -Wswitch-enum @gol
230-Wsystem-headers -Wtrigraphs -Wundef -Wuninitialized @gol
231-Wunknown-pragmas -Wno-pragmas -Wunreachable-code @gol
232-Wunused -Wunused-function -Wunused-label -Wunused-parameter @gol
1@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2@c 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
3@c This is part of the GCC manual.
4@c For copying conditions, see the file gcc.texi.
5
6@ignore
7@c man begin INCLUDE
8@include gcc-vers.texi
9@c man end
10
11@c man begin COPYRIGHT
12Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
131999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
14
15Permission is granted to copy, distribute and/or modify this document
16under the terms of the GNU Free Documentation License, Version 1.2 or
17any later version published by the Free Software Foundation; with the
18Invariant Sections being ``GNU General Public License'' and ``Funding
19Free Software'', the Front-Cover texts being (a) (see below), and with
20the Back-Cover Texts being (b) (see below). A copy of the license is
21included in the gfdl(7) man page.
22
23(a) The FSF's Front-Cover Text is:
24
25 A GNU Manual
26
27(b) The FSF's Back-Cover Text is:
28
29 You have freedom to copy and modify this GNU Manual, like GNU
30 software. Copies published by the Free Software Foundation raise
31 funds for GNU development.
32@c man end
33@c Set file name and title for the man page.
34@setfilename gcc
35@settitle GNU project C and C++ compiler
36@c man begin SYNOPSIS
37gcc [@option{-c}|@option{-S}|@option{-E}] [@option{-std=}@var{standard}]
38 [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
39 [@option{-W}@var{warn}@dots{}] [@option{-pedantic}]
40 [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
41 [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
42 [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
43 [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}
44
45Only the most useful options are listed here; see below for the
46remainder. @samp{g++} accepts mostly the same options as @samp{gcc}.
47@c man end
48@c man begin SEEALSO
49gpl(7), gfdl(7), fsf-funding(7),
50cpp(1), gcov(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1)
51and the Info entries for @file{gcc}, @file{cpp}, @file{as},
52@file{ld}, @file{binutils} and @file{gdb}.
53@c man end
54@c man begin BUGS
55For instructions on reporting bugs, see
56@w{@uref{http://gcc.gnu.org/bugs.html}}.
57@c man end
58@c man begin AUTHOR
59See the Info entry for @command{gcc}, or
60@w{@uref{http://gcc.gnu.org/onlinedocs/gcc/Contributors.html}},
61for contributors to GCC@.
62@c man end
63@end ignore
64
65@node Invoking GCC
66@chapter GCC Command Options
67@cindex GCC command options
68@cindex command options
69@cindex options, GCC command
70
71@c man begin DESCRIPTION
72When you invoke GCC, it normally does preprocessing, compilation,
73assembly and linking. The ``overall options'' allow you to stop this
74process at an intermediate stage. For example, the @option{-c} option
75says not to run the linker. Then the output consists of object files
76output by the assembler.
77
78Other options are passed on to one stage of processing. Some options
79control the preprocessor and others the compiler itself. Yet other
80options control the assembler and linker; most of these are not
81documented here, since you rarely need to use any of them.
82
83@cindex C compilation options
84Most of the command line options that you can use with GCC are useful
85for C programs; when an option is only useful with another language
86(usually C++), the explanation says so explicitly. If the description
87for a particular option does not mention a source language, you can use
88that option with all supported languages.
89
90@cindex C++ compilation options
91@xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
92options for compiling C++ programs.
93
94@cindex grouping options
95@cindex options, grouping
96The @command{gcc} program accepts options and file names as operands. Many
97options have multi-letter names; therefore multiple single-letter options
98may @emph{not} be grouped: @option{-dr} is very different from @w{@samp{-d
99-r}}.
100
101@cindex order of options
102@cindex options, order
103You can mix options and other arguments. For the most part, the order
104you use doesn't matter. Order does matter when you use several options
105of the same kind; for example, if you specify @option{-L} more than once,
106the directories are searched in the order specified.
107
108Many options have long names starting with @samp{-f} or with
109@samp{-W}---for example,
110@option{-fmove-loop-invariants}, @option{-Wformat} and so on. Most of
111these have both positive and negative forms; the negative form of
112@option{-ffoo} would be @option{-fno-foo}. This manual documents
113only one of these two forms, whichever one is not the default.
114
115@c man end
116
117@xref{Option Index}, for an index to GCC's options.
118
119@menu
120* Option Summary:: Brief list of all options, without explanations.
121* Overall Options:: Controlling the kind of output:
122 an executable, object files, assembler files,
123 or preprocessed source.
124* Invoking G++:: Compiling C++ programs.
125* C Dialect Options:: Controlling the variant of C language compiled.
126* C++ Dialect Options:: Variations on C++.
127* Language Independent Options:: Controlling how diagnostics should be
128 formatted.
129* Warning Options:: How picky should the compiler be?
130* Debugging Options:: Symbol tables, measurements, and debugging dumps.
131* Optimize Options:: How much optimization?
132* Preprocessor Options:: Controlling header files and macro definitions.
133 Also, getting dependency information for Make.
134* Assembler Options:: Passing options to the assembler.
135* Link Options:: Specifying libraries and so on.
136* Directory Options:: Where to find header files and libraries.
137 Where to find the compiler executable files.
138* Spec Files:: How to pass switches to sub-processes.
139* Target Options:: Running a cross-compiler, or an old version of GCC.
140* Submodel Options:: Specifying minor hardware or convention variations,
141 such as 68010 vs 68020.
142* Code Gen Options:: Specifying conventions for function calls, data layout
143 and register usage.
144* Environment Variables:: Env vars that affect GCC.
145* Precompiled Headers:: Compiling a header once, and using it many times.
146* Running Protoize:: Automatically adding or removing function prototypes.
147@end menu
148
149@c man begin OPTIONS
150
151@node Option Summary
152@section Option Summary
153
154Here is a summary of all the options, grouped by type. Explanations are
155in the following sections.
156
157@table @emph
158@item Overall Options
159@xref{Overall Options,,Options Controlling the Kind of Output}.
160@gccoptlist{-c -S -E -o @var{file} -combine -pipe -pass-exit-codes @gol
161-x @var{language} -v -### --help --target-help --version @@@var{file}}
162
163@item C Language Options
164@xref{C Dialect Options,,Options Controlling C Dialect}.
165@gccoptlist{-ansi -std=@var{standard} -fgnu89-inline @gol
166-aux-info @var{filename} @gol
167-fno-asm -fno-builtin -fno-builtin-@var{function} @gol
168-fhosted -ffreestanding -fopenmp -fms-extensions @gol
169-trigraphs -no-integrated-cpp -traditional -traditional-cpp @gol
170-fallow-single-precision -fcond-mismatch @gol
171-fsigned-bitfields -fsigned-char @gol
172-funsigned-bitfields -funsigned-char}
173
174@item C++ Language Options
175@xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
176@gccoptlist{-fabi-version=@var{n} -fno-access-control -fcheck-new @gol
177-fconserve-space -ffriend-injection @gol
178-fno-elide-constructors @gol
179-fno-enforce-eh-specs @gol
180-ffor-scope -fno-for-scope -fno-gnu-keywords @gol
181-fno-implicit-templates @gol
182-fno-implicit-inline-templates @gol
183-fno-implement-inlines -fms-extensions @gol
184-fno-nonansi-builtins -fno-operator-names @gol
185-fno-optional-diags -fpermissive @gol
186-frepo -fno-rtti -fstats -ftemplate-depth-@var{n} @gol
187-fno-threadsafe-statics -fuse-cxa-atexit -fno-weak -nostdinc++ @gol
188-fno-default-inline -fvisibility-inlines-hidden @gol
189-Wabi -Wctor-dtor-privacy @gol
190-Wnon-virtual-dtor -Wreorder @gol
191-Weffc++ -Wno-deprecated -Wstrict-null-sentinel @gol
192-Wno-non-template-friend -Wold-style-cast @gol
193-Woverloaded-virtual -Wno-pmf-conversions @gol
194-Wsign-promo}
195
196@item Language Independent Options
197@xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}.
198@gccoptlist{-fmessage-length=@var{n} @gol
199-fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]} @gol
200-fdiagnostics-show-option}
201
202@item Warning Options
203@xref{Warning Options,,Options to Request or Suppress Warnings}.
204@gccoptlist{-fsyntax-only -pedantic -pedantic-errors @gol
205-w -Wextra -Wall -Waddress -Waggregate-return -Wno-attributes @gol
206-Wc++-compat -Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment @gol
207-Wconversion -Wno-deprecated-declarations @gol
208-Wdisabled-optimization -Wno-div-by-zero -Wno-endif-labels @gol
209-Werror -Werror=* -Werror-implicit-function-declaration @gol
210-Wfatal-errors -Wfloat-equal -Wformat -Wformat=2 @gol
211-Wno-format-extra-args -Wformat-nonliteral @gol
212-Wformat-security -Wformat-y2k @gol
213-Wimplicit -Wimplicit-function-declaration -Wimplicit-int @gol
214-Wimport -Wno-import -Winit-self -Winline @gol
215-Wno-int-to-pointer-cast @gol
216-Wno-invalid-offsetof -Winvalid-pch @gol
217-Wlarger-than-@var{len} -Wunsafe-loop-optimizations -Wlong-long @gol
218-Wmain -Wmissing-braces -Wmissing-field-initializers @gol
219-Wmissing-format-attribute -Wmissing-include-dirs @gol
220-Wmissing-noreturn @gol
221-Wno-multichar -Wnonnull -Wno-overflow @gol
222-Woverlength-strings -Wpacked -Wpadded @gol
223-Wparentheses -Wpointer-arith -Wno-pointer-to-int-cast @gol
224-Wredundant-decls @gol
225-Wreturn-type -Wsequence-point -Wshadow @gol
226-Wsign-compare -Wstack-protector @gol
227-Wstrict-aliasing -Wstrict-aliasing=2 @gol
228-Wstrict-overflow -Wstrict-overflow=@var{n} @gol
229-Wswitch -Wswitch-default -Wswitch-enum @gol
230-Wsystem-headers -Wtrigraphs -Wundef -Wuninitialized @gol
231-Wunknown-pragmas -Wno-pragmas -Wunreachable-code @gol
232-Wunused -Wunused-function -Wunused-label -Wunused-parameter @gol
233-Wunused-value -Wunused-variable -Wvariadic-macros @gol
233-Wunused-value -Wunused-variable @gol
234-Wvariadic-macros -Wvla @gol
234-Wvolatile-register-var -Wwrite-strings}
235
236@item C-only Warning Options
237@gccoptlist{-Wbad-function-cast -Wmissing-declarations @gol
238-Wmissing-prototypes -Wnested-externs -Wold-style-definition @gol
239-Wstrict-prototypes -Wtraditional @gol
240-Wdeclaration-after-statement -Wpointer-sign}
241
242@item Debugging Options
243@xref{Debugging Options,,Options for Debugging Your Program or GCC}.
244@gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
245-fdump-noaddr -fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} @gol
246-fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
247-fdump-ipa-all -fdump-ipa-cgraph @gol
248-fdump-tree-all @gol
249-fdump-tree-original@r{[}-@var{n}@r{]} @gol
250-fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
251-fdump-tree-inlined@r{[}-@var{n}@r{]} @gol
252-fdump-tree-cfg -fdump-tree-vcg -fdump-tree-alias @gol
253-fdump-tree-ch @gol
254-fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol
255-fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol
256-fdump-tree-gimple@r{[}-raw@r{]} -fdump-tree-mudflap@r{[}-@var{n}@r{]} @gol
257-fdump-tree-dom@r{[}-@var{n}@r{]} @gol
258-fdump-tree-dse@r{[}-@var{n}@r{]} @gol
259-fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol
260-fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
261-fdump-tree-copyrename@r{[}-@var{n}@r{]} @gol
262-fdump-tree-nrv -fdump-tree-vect @gol
263-fdump-tree-sink @gol
264-fdump-tree-sra@r{[}-@var{n}@r{]} @gol
265-fdump-tree-salias @gol
266-fdump-tree-fre@r{[}-@var{n}@r{]} @gol
267-fdump-tree-vrp@r{[}-@var{n}@r{]} @gol
268-ftree-vectorizer-verbose=@var{n} @gol
269-fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol
270-feliminate-dwarf2-dups -feliminate-unused-debug-types @gol
271-feliminate-unused-debug-symbols -femit-class-debug-always @gol
272-fmem-report -fprofile-arcs @gol
273-frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
274-ftest-coverage -ftime-report -fvar-tracking @gol
275-g -g@var{level} -gcoff -gdwarf-2 @gol
276-ggdb -gstabs -gstabs+ -gvms -gxcoff -gxcoff+ @gol
277-p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol
278-print-multi-directory -print-multi-lib @gol
279-print-prog-name=@var{program} -print-search-dirs -Q @gol
280-save-temps -time}
281
282@item Optimization Options
283@xref{Optimize Options,,Options that Control Optimization}.
284@gccoptlist{-falign-functions=@var{n} -falign-jumps=@var{n} @gol
285-falign-labels=@var{n} -falign-loops=@var{n} @gol
286-fbounds-check -fmudflap -fmudflapth -fmudflapir @gol
287-fbranch-probabilities -fprofile-values -fvpt -fbranch-target-load-optimize @gol
288-fbranch-target-load-optimize2 -fbtr-bb-exclusive @gol
289-fcaller-saves -fcprop-registers -fcse-follow-jumps @gol
290-fcse-skip-blocks -fcx-limited-range -fdata-sections @gol
291-fdelayed-branch -fdelete-null-pointer-checks -fearly-inlining @gol
292-fexpensive-optimizations -ffast-math -ffloat-store @gol
293-fforce-addr -ffunction-sections @gol
294-fgcse -fgcse-lm -fgcse-sm -fgcse-las -fgcse-after-reload @gol
295-fcrossjumping -fif-conversion -fif-conversion2 @gol
296-finline-functions -finline-functions-called-once @gol
297-finline-limit=@var{n} -fkeep-inline-functions @gol
298-fkeep-static-consts -fmerge-constants -fmerge-all-constants @gol
299-fmodulo-sched -fno-branch-count-reg @gol
300-fno-default-inline -fno-defer-pop -fmove-loop-invariants @gol
301-fno-function-cse -fno-guess-branch-probability @gol
302-fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol
303-funsafe-math-optimizations -funsafe-loop-optimizations -ffinite-math-only @gol
304-fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol
305-fomit-frame-pointer -foptimize-register-move @gol
306-foptimize-sibling-calls -fprefetch-loop-arrays @gol
307-fprofile-generate -fprofile-use @gol
308-fregmove -frename-registers @gol
309-freorder-blocks -freorder-blocks-and-partition -freorder-functions @gol
310-frerun-cse-after-loop @gol
311-frounding-math -frtl-abstract-sequences @gol
312-fschedule-insns -fschedule-insns2 @gol
313-fno-sched-interblock -fno-sched-spec -fsched-spec-load @gol
314-fsched-spec-load-dangerous @gol
315-fsched-stalled-insns=@var{n} -fsched-stalled-insns-dep=@var{n} @gol
316-fsched2-use-superblocks @gol
317-fsched2-use-traces -fsee -freschedule-modulo-scheduled-loops @gol
318-fsection-anchors -fsignaling-nans -fsingle-precision-constant @gol
319-fstack-protector -fstack-protector-all @gol
320-fstrict-aliasing -fstrict-overflow -ftracer -fthread-jumps @gol
321-funroll-all-loops -funroll-loops -fpeel-loops @gol
322-fsplit-ivs-in-unroller -funswitch-loops @gol
323-fvariable-expansion-in-unroller @gol
324-ftree-pre -ftree-ccp -ftree-dce -ftree-loop-optimize @gol
325-ftree-loop-linear -ftree-loop-im -ftree-loop-ivcanon -fivopts @gol
326-ftree-dominator-opts -ftree-dse -ftree-copyrename -ftree-sink @gol
327-ftree-ch -ftree-sra -ftree-ter -ftree-lrs -ftree-fre -ftree-vectorize @gol
328-ftree-vect-loop-version -ftree-salias -fipa-pta -fweb @gol
329-ftree-copy-prop -ftree-store-ccp -ftree-store-copy-prop -fwhole-program @gol
330--param @var{name}=@var{value}
331-O -O0 -O1 -O2 -O3 -Os}
332
333@item Preprocessor Options
334@xref{Preprocessor Options,,Options Controlling the Preprocessor}.
335@gccoptlist{-A@var{question}=@var{answer} @gol
336-A-@var{question}@r{[}=@var{answer}@r{]} @gol
337-C -dD -dI -dM -dN @gol
338-D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol
339-idirafter @var{dir} @gol
340-include @var{file} -imacros @var{file} @gol
341-iprefix @var{file} -iwithprefix @var{dir} @gol
342-iwithprefixbefore @var{dir} -isystem @var{dir} @gol
343-imultilib @var{dir} -isysroot @var{dir} @gol
344-M -MM -MF -MG -MP -MQ -MT -nostdinc @gol
345-P -fworking-directory -remap @gol
346-trigraphs -undef -U@var{macro} -Wp,@var{option} @gol
347-Xpreprocessor @var{option}}
348
349@item Assembler Option
350@xref{Assembler Options,,Passing Options to the Assembler}.
351@gccoptlist{-Wa,@var{option} -Xassembler @var{option}}
352
353@item Linker Options
354@xref{Link Options,,Options for Linking}.
355@gccoptlist{@var{object-file-name} -l@var{library} @gol
356-nostartfiles -nodefaultlibs -nostdlib -pie -rdynamic @gol
357-s -static -static-libgcc -shared -shared-libgcc -symbolic @gol
358-Wl,@var{option} -Xlinker @var{option} @gol
359-u @var{symbol}}
360
361@item Directory Options
362@xref{Directory Options,,Options for Directory Search}.
363@gccoptlist{-B@var{prefix} -I@var{dir} -iquote@var{dir} -L@var{dir}
364-specs=@var{file} -I- --sysroot=@var{dir}}
365
366@item Target Options
367@c I wrote this xref this way to avoid overfull hbox. -- rms
368@xref{Target Options}.
369@gccoptlist{-V @var{version} -b @var{machine}}
370
371@item Machine Dependent Options
372@xref{Submodel Options,,Hardware Models and Configurations}.
373@c This list is ordered alphanumerically by subsection name.
374@c Try and put the significant identifier (CPU or system) first,
375@c so users have a clue at guessing where the ones they want will be.
376
377@emph{ARC Options}
378@gccoptlist{-EB -EL @gol
379-mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text-section} @gol
380-mdata=@var{data-section} -mrodata=@var{readonly-data-section}}
381
382@emph{ARM Options}
383@gccoptlist{-mapcs-frame -mno-apcs-frame @gol
384-mabi=@var{name} @gol
385-mapcs-stack-check -mno-apcs-stack-check @gol
386-mapcs-float -mno-apcs-float @gol
387-mapcs-reentrant -mno-apcs-reentrant @gol
388-msched-prolog -mno-sched-prolog @gol
389-mlittle-endian -mbig-endian -mwords-little-endian @gol
390-mfloat-abi=@var{name} -msoft-float -mhard-float -mfpe @gol
391-mthumb-interwork -mno-thumb-interwork @gol
392-mcpu=@var{name} -march=@var{name} -mfpu=@var{name} @gol
393-mstructure-size-boundary=@var{n} @gol
394-mabort-on-noreturn @gol
395-mlong-calls -mno-long-calls @gol
396-msingle-pic-base -mno-single-pic-base @gol
397-mpic-register=@var{reg} @gol
398-mnop-fun-dllimport @gol
399-mcirrus-fix-invalid-insns -mno-cirrus-fix-invalid-insns @gol
400-mpoke-function-name @gol
401-mthumb -marm @gol
402-mtpcs-frame -mtpcs-leaf-frame @gol
403-mcaller-super-interworking -mcallee-super-interworking @gol
404-mtp=@var{name}}
405
406@emph{AVR Options}
407@gccoptlist{-mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts @gol
408-mcall-prologues -mno-tablejump -mtiny-stack -mint8}
409
410@emph{Blackfin Options}
411@gccoptlist{-momit-leaf-frame-pointer -mno-omit-leaf-frame-pointer @gol
412-mspecld-anomaly -mno-specld-anomaly -mcsync-anomaly -mno-csync-anomaly @gol
413-mlow-64k -mno-low64k -mid-shared-library @gol
414-mno-id-shared-library -mshared-library-id=@var{n} @gol
415-mlong-calls -mno-long-calls}
416
417@emph{CRIS Options}
418@gccoptlist{-mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol
419-mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol
420-metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol
421-mstack-align -mdata-align -mconst-align @gol
422-m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol
423-melf -maout -melinux -mlinux -sim -sim2 @gol
424-mmul-bug-workaround -mno-mul-bug-workaround}
425
426@emph{CRX Options}
427@gccoptlist{-mmac -mpush-args}
428
429@emph{Darwin Options}
430@gccoptlist{-all_load -allowable_client -arch -arch_errors_fatal @gol
431-arch_only -bind_at_load -bundle -bundle_loader @gol
432-client_name -compatibility_version -current_version @gol
433-dead_strip @gol
434-dependency-file -dylib_file -dylinker_install_name @gol
435-dynamic -dynamiclib -exported_symbols_list @gol
436-filelist -flat_namespace -force_cpusubtype_ALL @gol
437-force_flat_namespace -headerpad_max_install_names @gol
438-image_base -init -install_name -keep_private_externs @gol
439-multi_module -multiply_defined -multiply_defined_unused @gol
440-noall_load -no_dead_strip_inits_and_terms @gol
441-nofixprebinding -nomultidefs -noprebind -noseglinkedit @gol
442-pagezero_size -prebind -prebind_all_twolevel_modules @gol
443-private_bundle -read_only_relocs -sectalign @gol
444-sectobjectsymbols -whyload -seg1addr @gol
445-sectcreate -sectobjectsymbols -sectorder @gol
446-segaddr -segs_read_only_addr -segs_read_write_addr @gol
447-seg_addr_table -seg_addr_table_filename -seglinkedit @gol
448-segprot -segs_read_only_addr -segs_read_write_addr @gol
449-single_module -static -sub_library -sub_umbrella @gol
450-twolevel_namespace -umbrella -undefined @gol
451-unexported_symbols_list -weak_reference_mismatches @gol
452-whatsloaded -F -gused -gfull -mmacosx-version-min=@var{version} @gol
453-mkernel -mone-byte-bool}
454
455@emph{DEC Alpha Options}
456@gccoptlist{-mno-fp-regs -msoft-float -malpha-as -mgas @gol
457-mieee -mieee-with-inexact -mieee-conformant @gol
458-mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} @gol
459-mtrap-precision=@var{mode} -mbuild-constants @gol
460-mcpu=@var{cpu-type} -mtune=@var{cpu-type} @gol
461-mbwx -mmax -mfix -mcix @gol
462-mfloat-vax -mfloat-ieee @gol
463-mexplicit-relocs -msmall-data -mlarge-data @gol
464-msmall-text -mlarge-text @gol
465-mmemory-latency=@var{time}}
466
467@emph{DEC Alpha/VMS Options}
468@gccoptlist{-mvms-return-codes}
469
470@emph{FRV Options}
471@gccoptlist{-mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 @gol
472-mhard-float -msoft-float @gol
473-malloc-cc -mfixed-cc -mdword -mno-dword @gol
474-mdouble -mno-double @gol
475-mmedia -mno-media -mmuladd -mno-muladd @gol
476-mfdpic -minline-plt -mgprel-ro -multilib-library-pic @gol
477-mlinked-fp -mlong-calls -malign-labels @gol
478-mlibrary-pic -macc-4 -macc-8 @gol
479-mpack -mno-pack -mno-eflags -mcond-move -mno-cond-move @gol
480-moptimize-membar -mno-optimize-membar @gol
481-mscc -mno-scc -mcond-exec -mno-cond-exec @gol
482-mvliw-branch -mno-vliw-branch @gol
483-mmulti-cond-exec -mno-multi-cond-exec -mnested-cond-exec @gol
484-mno-nested-cond-exec -mtomcat-stats @gol
485-mTLS -mtls @gol
486-mcpu=@var{cpu}}
487
488@emph{GNU/Linux Options}
489@gccoptlist{-muclibc}
490
491@emph{H8/300 Options}
492@gccoptlist{-mrelax -mh -ms -mn -mint32 -malign-300}
493
494@emph{HPPA Options}
495@gccoptlist{-march=@var{architecture-type} @gol
496-mbig-switch -mdisable-fpregs -mdisable-indexing @gol
497-mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol
498-mfixed-range=@var{register-range} @gol
499-mjump-in-delay -mlinker-opt -mlong-calls @gol
500-mlong-load-store -mno-big-switch -mno-disable-fpregs @gol
501-mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol
502-mno-jump-in-delay -mno-long-load-store @gol
503-mno-portable-runtime -mno-soft-float @gol
504-mno-space-regs -msoft-float -mpa-risc-1-0 @gol
505-mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime @gol
506-mschedule=@var{cpu-type} -mspace-regs -msio -mwsio @gol
507-munix=@var{unix-std} -nolibdld -static -threads}
508
509@emph{i386 and x86-64 Options}
510@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
511-mfpmath=@var{unit} @gol
512-masm=@var{dialect} -mno-fancy-math-387 @gol
513-mno-fp-ret-in-387 -msoft-float -msvr3-shlib @gol
514-mno-wide-multiply -mrtd -malign-double @gol
515-mpreferred-stack-boundary=@var{num} @gol
516-mmmx -msse -msse2 -msse3 -mssse3 -msse4a -m3dnow -mpopcnt -mabm -maes @gol
517-mthreads -mno-align-stringops -minline-all-stringops @gol
518-mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol
519-m96bit-long-double -mregparm=@var{num} -msseregparm @gol
520-mstackrealign @gol
521-momit-leaf-frame-pointer -mno-red-zone -mno-tls-direct-seg-refs @gol
522-mcmodel=@var{code-model} @gol
523-m32 -m64 -mlarge-data-threshold=@var{num}}
524
525@emph{IA-64 Options}
526@gccoptlist{-mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol
527-mvolatile-asm-stop -mregister-names -mno-sdata @gol
528-mconstant-gp -mauto-pic -minline-float-divide-min-latency @gol
529-minline-float-divide-max-throughput @gol
530-minline-int-divide-min-latency @gol
531-minline-int-divide-max-throughput @gol
532-minline-sqrt-min-latency -minline-sqrt-max-throughput @gol
533-mno-dwarf2-asm -mearly-stop-bits @gol
534-mfixed-range=@var{register-range} -mtls-size=@var{tls-size} @gol
535-mtune=@var{cpu-type} -mt -pthread -milp32 -mlp64 @gol
536-mno-sched-br-data-spec -msched-ar-data-spec -mno-sched-control-spec @gol
537-msched-br-in-data-spec -msched-ar-in-data-spec -msched-in-control-spec @gol
538-msched-ldc -mno-sched-control-ldc -mno-sched-spec-verbose @gol
539-mno-sched-prefer-non-data-spec-insns @gol
540-mno-sched-prefer-non-control-spec-insns @gol
541-mno-sched-count-spec-in-critical-path}
542
543@emph{M32R/D Options}
544@gccoptlist{-m32r2 -m32rx -m32r @gol
545-mdebug @gol
546-malign-loops -mno-align-loops @gol
547-missue-rate=@var{number} @gol
548-mbranch-cost=@var{number} @gol
549-mmodel=@var{code-size-model-type} @gol
550-msdata=@var{sdata-type} @gol
551-mno-flush-func -mflush-func=@var{name} @gol
552-mno-flush-trap -mflush-trap=@var{number} @gol
553-G @var{num}}
554
555@emph{M32C Options}
556@gccoptlist{-mcpu=@var{cpu} -msim -memregs=@var{number}}
557
558@emph{M680x0 Options}
559@gccoptlist{-m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol
560-m68060 -mcpu32 -m5200 -mcfv4e -m68881 -mbitfield @gol
561-mc68000 -mc68020 @gol
562-mnobitfield -mrtd -mshort -msoft-float -mpcrel @gol
563-malign-int -mstrict-align -msep-data -mno-sep-data @gol
564-mshared-library-id=n -mid-shared-library -mno-id-shared-library}
565
566@emph{M68hc1x Options}
567@gccoptlist{-m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 @gol
568-mauto-incdec -minmax -mlong-calls -mshort @gol
569-msoft-reg-count=@var{count}}
570
571@emph{MCore Options}
572@gccoptlist{-mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol
573-mno-relax-immediates -mwide-bitfields -mno-wide-bitfields @gol
574-m4byte-functions -mno-4byte-functions -mcallgraph-data @gol
575-mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim @gol
576-mlittle-endian -mbig-endian -m210 -m340 -mstack-increment}
577
578@emph{MIPS Options}
579@gccoptlist{-EL -EB -march=@var{arch} -mtune=@var{arch} @gol
580-mips1 -mips2 -mips3 -mips4 -mips32 -mips32r2 -mips64 @gol
581-mips16 -mno-mips16 -mabi=@var{abi} -mabicalls -mno-abicalls @gol
582-mshared -mno-shared -mxgot -mno-xgot -mgp32 -mgp64 @gol
583-mfp32 -mfp64 -mhard-float -msoft-float @gol
584-msingle-float -mdouble-float -mdsp -mpaired-single -mips3d @gol
585-mlong64 -mlong32 -msym32 -mno-sym32 @gol
586-G@var{num} -membedded-data -mno-embedded-data @gol
587-muninit-const-in-rodata -mno-uninit-const-in-rodata @gol
588-msplit-addresses -mno-split-addresses @gol
589-mexplicit-relocs -mno-explicit-relocs @gol
590-mcheck-zero-division -mno-check-zero-division @gol
591-mdivide-traps -mdivide-breaks @gol
592-mmemcpy -mno-memcpy -mlong-calls -mno-long-calls @gol
593-mmad -mno-mad -mfused-madd -mno-fused-madd -nocpp @gol
594-mfix-r4000 -mno-fix-r4000 -mfix-r4400 -mno-fix-r4400 @gol
595-mfix-vr4120 -mno-fix-vr4120 -mfix-vr4130 @gol
596-mfix-sb1 -mno-fix-sb1 @gol
597-mflush-func=@var{func} -mno-flush-func @gol
598-mbranch-likely -mno-branch-likely @gol
599-mfp-exceptions -mno-fp-exceptions @gol
600-mvr4130-align -mno-vr4130-align}
601
602@emph{MMIX Options}
603@gccoptlist{-mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol
604-mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol
605-melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol
606-mno-base-addresses -msingle-exit -mno-single-exit}
607
608@emph{MN10300 Options}
609@gccoptlist{-mmult-bug -mno-mult-bug @gol
610-mam33 -mno-am33 @gol
611-mam33-2 -mno-am33-2 @gol
612-mreturn-pointer-on-d0 @gol
613-mno-crt0 -mrelax}
614
615@emph{MT Options}
616@gccoptlist{-mno-crt0 -mbacc -msim @gol
617-march=@var{cpu-type} }
618
619@emph{PDP-11 Options}
620@gccoptlist{-mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol
621-mbcopy -mbcopy-builtin -mint32 -mno-int16 @gol
622-mint16 -mno-int32 -mfloat32 -mno-float64 @gol
623-mfloat64 -mno-float32 -mabshi -mno-abshi @gol
624-mbranch-expensive -mbranch-cheap @gol
625-msplit -mno-split -munix-asm -mdec-asm}
626
627@emph{PowerPC Options}
628See RS/6000 and PowerPC Options.
629
630@emph{RS/6000 and PowerPC Options}
631@gccoptlist{-mcpu=@var{cpu-type} @gol
632-mtune=@var{cpu-type} @gol
633-mpower -mno-power -mpower2 -mno-power2 @gol
634-mpowerpc -mpowerpc64 -mno-powerpc @gol
635-maltivec -mno-altivec @gol
636-mpowerpc-gpopt -mno-powerpc-gpopt @gol
637-mpowerpc-gfxopt -mno-powerpc-gfxopt @gol
638-mmfcrf -mno-mfcrf -mpopcntb -mno-popcntb -mfprnd -mno-fprnd @gol
639-mnew-mnemonics -mold-mnemonics @gol
640-mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc @gol
641-m64 -m32 -mxl-compat -mno-xl-compat -mpe @gol
642-malign-power -malign-natural @gol
643-msoft-float -mhard-float -mmultiple -mno-multiple @gol
644-mstring -mno-string -mupdate -mno-update @gol
645-mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol
646-mstrict-align -mno-strict-align -mrelocatable @gol
647-mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol
648-mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol
649-mdynamic-no-pic -maltivec -mswdiv @gol
650-mprioritize-restricted-insns=@var{priority} @gol
651-msched-costly-dep=@var{dependence_type} @gol
652-minsert-sched-nops=@var{scheme} @gol
653-mcall-sysv -mcall-netbsd @gol
654-maix-struct-return -msvr4-struct-return @gol
655-mabi=@var{abi-type} -msecure-plt -mbss-plt @gol
656-misel -mno-isel @gol
657-misel=yes -misel=no @gol
658-mspe -mno-spe @gol
659-mspe=yes -mspe=no @gol
660-mvrsave -mno-vrsave @gol
661-mmulhw -mno-mulhw @gol
662-mdlmzb -mno-dlmzb @gol
663-mfloat-gprs=yes -mfloat-gprs=no -mfloat-gprs=single -mfloat-gprs=double @gol
664-mprototype -mno-prototype @gol
665-msim -mmvme -mads -myellowknife -memb -msdata @gol
666-msdata=@var{opt} -mvxworks -mwindiss -G @var{num} -pthread}
667
668@emph{S/390 and zSeries Options}
669@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
670-mhard-float -msoft-float -mlong-double-64 -mlong-double-128 @gol
671-mbackchain -mno-backchain -mpacked-stack -mno-packed-stack @gol
672-msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol
673-m64 -m31 -mdebug -mno-debug -mesa -mzarch @gol
674-mtpf-trace -mno-tpf-trace -mfused-madd -mno-fused-madd @gol
675-mwarn-framesize -mwarn-dynamicstack -mstack-size -mstack-guard}
676
677@emph{Score Options}
678@gccoptlist{-meb -mel @gol
679-mnhwloop @gol
680-muls @gol
681-mmac @gol
682-mscore5 -mscore5u -mscore7 -mscore7d}
683
684@emph{SH Options}
685@gccoptlist{-m1 -m2 -m2e -m3 -m3e @gol
686-m4-nofpu -m4-single-only -m4-single -m4 @gol
687-m4a-nofpu -m4a-single-only -m4a-single -m4a -m4al @gol
688-m5-64media -m5-64media-nofpu @gol
689-m5-32media -m5-32media-nofpu @gol
690-m5-compact -m5-compact-nofpu @gol
691-mb -ml -mdalign -mrelax @gol
692-mbigtable -mfmovd -mhitachi -mrenesas -mno-renesas -mnomacsave @gol
693-mieee -misize -mpadstruct -mspace @gol
694-mprefergot -musermode -multcost=@var{number} -mdiv=@var{strategy} @gol
695-mdivsi3_libfunc=@var{name} @gol
696-madjust-unroll -mindexed-addressing -mgettrcost=@var{number} -mpt-fixed @gol
697 -minvalid-symbols}
698
699@emph{SPARC Options}
700@gccoptlist{-mcpu=@var{cpu-type} @gol
701-mtune=@var{cpu-type} @gol
702-mcmodel=@var{code-model} @gol
703-m32 -m64 -mapp-regs -mno-app-regs @gol
704-mfaster-structs -mno-faster-structs @gol
705-mfpu -mno-fpu -mhard-float -msoft-float @gol
706-mhard-quad-float -msoft-quad-float @gol
707-mimpure-text -mno-impure-text -mlittle-endian @gol
708-mstack-bias -mno-stack-bias @gol
709-munaligned-doubles -mno-unaligned-doubles @gol
710-mv8plus -mno-v8plus -mvis -mno-vis
711-threads -pthreads -pthread}
712
713@emph{System V Options}
714@gccoptlist{-Qy -Qn -YP,@var{paths} -Ym,@var{dir}}
715
716@emph{TMS320C3x/C4x Options}
717@gccoptlist{-mcpu=@var{cpu} -mbig -msmall -mregparm -mmemparm @gol
718-mfast-fix -mmpyi -mbk -mti -mdp-isr-reload @gol
719-mrpts=@var{count} -mrptb -mdb -mloop-unsigned @gol
720-mparallel-insns -mparallel-mpy -mpreserve-float}
721
722@emph{V850 Options}
723@gccoptlist{-mlong-calls -mno-long-calls -mep -mno-ep @gol
724-mprolog-function -mno-prolog-function -mspace @gol
725-mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol
726-mapp-regs -mno-app-regs @gol
727-mdisable-callt -mno-disable-callt @gol
728-mv850e1 @gol
729-mv850e @gol
730-mv850 -mbig-switch}
731
732@emph{VAX Options}
733@gccoptlist{-mg -mgnu -munix}
734
735@emph{x86-64 Options}
736See i386 and x86-64 Options.
737
738@emph{Xstormy16 Options}
739@gccoptlist{-msim}
740
741@emph{Xtensa Options}
742@gccoptlist{-mconst16 -mno-const16 @gol
743-mfused-madd -mno-fused-madd @gol
744-mtext-section-literals -mno-text-section-literals @gol
745-mtarget-align -mno-target-align @gol
746-mlongcalls -mno-longcalls}
747
748@emph{zSeries Options}
749See S/390 and zSeries Options.
750
751@item Code Generation Options
752@xref{Code Gen Options,,Options for Code Generation Conventions}.
753@gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol
754-ffixed-@var{reg} -fexceptions @gol
755-fnon-call-exceptions -funwind-tables @gol
756-fasynchronous-unwind-tables @gol
757-finhibit-size-directive -finstrument-functions @gol
758-fno-common -fno-ident @gol
759-fpcc-struct-return -fpic -fPIC -fpie -fPIE @gol
760-fno-jump-tables @gol
761-freg-struct-return -fshort-enums @gol
762-fshort-double -fshort-wchar @gol
763-fverbose-asm -fpack-struct[=@var{n}] -fstack-check @gol
764-fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
765-fargument-alias -fargument-noalias @gol
766-fargument-noalias-global -fargument-noalias-anything
767-fleading-underscore -ftls-model=@var{model} @gol
768-ftrapv -fwrapv -fbounds-check @gol
769-fvisibility}
770@end table
771
772@menu
773* Overall Options:: Controlling the kind of output:
774 an executable, object files, assembler files,
775 or preprocessed source.
776* C Dialect Options:: Controlling the variant of C language compiled.
777* C++ Dialect Options:: Variations on C++.
778* Language Independent Options:: Controlling how diagnostics should be
779 formatted.
780* Warning Options:: How picky should the compiler be?
781* Debugging Options:: Symbol tables, measurements, and debugging dumps.
782* Optimize Options:: How much optimization?
783* Preprocessor Options:: Controlling header files and macro definitions.
784 Also, getting dependency information for Make.
785* Assembler Options:: Passing options to the assembler.
786* Link Options:: Specifying libraries and so on.
787* Directory Options:: Where to find header files and libraries.
788 Where to find the compiler executable files.
789* Spec Files:: How to pass switches to sub-processes.
790* Target Options:: Running a cross-compiler, or an old version of GCC.
791@end menu
792
793@node Overall Options
794@section Options Controlling the Kind of Output
795
796Compilation can involve up to four stages: preprocessing, compilation
797proper, assembly and linking, always in that order. GCC is capable of
798preprocessing and compiling several files either into several
799assembler input files, or into one assembler input file; then each
800assembler input file produces an object file, and linking combines all
801the object files (those newly compiled, and those specified as input)
802into an executable file.
803
804@cindex file name suffix
805For any given input file, the file name suffix determines what kind of
806compilation is done:
807
808@table @gcctabopt
809@item @var{file}.c
810C source code which must be preprocessed.
811
812@item @var{file}.i
813C source code which should not be preprocessed.
814
815@item @var{file}.ii
816C++ source code which should not be preprocessed.
817
818@item @var{file}.h
819C, or C++ header file to be turned into a precompiled header.
820
821@item @var{file}.cc
822@itemx @var{file}.cp
823@itemx @var{file}.cxx
824@itemx @var{file}.cpp
825@itemx @var{file}.CPP
826@itemx @var{file}.c++
827@itemx @var{file}.C
828C++ source code which must be preprocessed. Note that in @samp{.cxx},
829the last two letters must both be literally @samp{x}. Likewise,
830@samp{.C} refers to a literal capital C@.
831
832@item @var{file}.hh
833@itemx @var{file}.H
834C++ header file to be turned into a precompiled header.
835
836@item @var{file}.f
837@itemx @var{file}.for
838@itemx @var{file}.FOR
839Fixed form Fortran source code which should not be preprocessed.
840
841@item @var{file}.F
842@itemx @var{file}.fpp
843@itemx @var{file}.FPP
844Fixed form Fortran source code which must be preprocessed (with the traditional
845preprocessor).
846
847@item @var{file}.f90
848@itemx @var{file}.f95
849Free form Fortran source code which should not be preprocessed.
850
851@item @var{file}.F90
852@itemx @var{file}.F95
853Free form Fortran source code which must be preprocessed (with the
854traditional preprocessor).
855
856@c FIXME: Descriptions of Java file types.
857@c @var{file}.java
858@c @var{file}.class
859@c @var{file}.zip
860@c @var{file}.jar
861
862@item @var{file}.ads
863Ada source code file which contains a library unit declaration (a
864declaration of a package, subprogram, or generic, or a generic
865instantiation), or a library unit renaming declaration (a package,
866generic, or subprogram renaming declaration). Such files are also
867called @dfn{specs}.
868
869@itemx @var{file}.adb
870Ada source code file containing a library unit body (a subprogram or
871package body). Such files are also called @dfn{bodies}.
872
873@c GCC also knows about some suffixes for languages not yet included:
874@c Pascal:
875@c @var{file}.p
876@c @var{file}.pas
877@c Ratfor:
878@c @var{file}.r
879
880@item @var{file}.s
881Assembler code.
882
883@item @var{file}.S
884Assembler code which must be preprocessed.
885
886@item @var{other}
887An object file to be fed straight into linking.
888Any file name with no recognized suffix is treated this way.
889@end table
890
891@opindex x
892You can specify the input language explicitly with the @option{-x} option:
893
894@table @gcctabopt
895@item -x @var{language}
896Specify explicitly the @var{language} for the following input files
897(rather than letting the compiler choose a default based on the file
898name suffix). This option applies to all following input files until
899the next @option{-x} option. Possible values for @var{language} are:
900@smallexample
901c c-header c-cpp-output
902c++ c++-header c++-cpp-output
903assembler assembler-with-cpp
904ada
905f95 f95-cpp-input
906java
907treelang
908@end smallexample
909
910@item -x none
911Turn off any specification of a language, so that subsequent files are
912handled according to their file name suffixes (as they are if @option{-x}
913has not been used at all).
914
915@item -pass-exit-codes
916@opindex pass-exit-codes
917Normally the @command{gcc} program will exit with the code of 1 if any
918phase of the compiler returns a non-success return code. If you specify
919@option{-pass-exit-codes}, the @command{gcc} program will instead return with
920numerically highest error produced by any phase that returned an error
921indication. The C, C++, and Fortran frontends return 4, if an internal
922compiler error is encountered.
923@end table
924
925If you only want some of the stages of compilation, you can use
926@option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
927one of the options @option{-c}, @option{-S}, or @option{-E} to say where
928@command{gcc} is to stop. Note that some combinations (for example,
929@samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
930
931@table @gcctabopt
932@item -c
933@opindex c
934Compile or assemble the source files, but do not link. The linking
935stage simply is not done. The ultimate output is in the form of an
936object file for each source file.
937
938By default, the object file name for a source file is made by replacing
939the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
940
941Unrecognized input files, not requiring compilation or assembly, are
942ignored.
943
944@item -S
945@opindex S
946Stop after the stage of compilation proper; do not assemble. The output
947is in the form of an assembler code file for each non-assembler input
948file specified.
949
950By default, the assembler file name for a source file is made by
951replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
952
953Input files that don't require compilation are ignored.
954
955@item -E
956@opindex E
957Stop after the preprocessing stage; do not run the compiler proper. The
958output is in the form of preprocessed source code, which is sent to the
959standard output.
960
961Input files which don't require preprocessing are ignored.
962
963@cindex output file option
964@item -o @var{file}
965@opindex o
966Place output in file @var{file}. This applies regardless to whatever
967sort of output is being produced, whether it be an executable file,
968an object file, an assembler file or preprocessed C code.
969
970If @option{-o} is not specified, the default is to put an executable
971file in @file{a.out}, the object file for
972@file{@var{source}.@var{suffix}} in @file{@var{source}.o}, its
973assembler file in @file{@var{source}.s}, a precompiled header file in
974@file{@var{source}.@var{suffix}.gch}, and all preprocessed C source on
975standard output.
976
977@item -v
978@opindex v
979Print (on standard error output) the commands executed to run the stages
980of compilation. Also print the version number of the compiler driver
981program and of the preprocessor and the compiler proper.
982
983@item -###
984@opindex ###
985Like @option{-v} except the commands are not executed and all command
986arguments are quoted. This is useful for shell scripts to capture the
987driver-generated command lines.
988
989@item -pipe
990@opindex pipe
991Use pipes rather than temporary files for communication between the
992various stages of compilation. This fails to work on some systems where
993the assembler is unable to read from a pipe; but the GNU assembler has
994no trouble.
995
996@item -combine
997@opindex combine
998If you are compiling multiple source files, this option tells the driver
999to pass all the source files to the compiler at once (for those
1000languages for which the compiler can handle this). This will allow
1001intermodule analysis (IMA) to be performed by the compiler. Currently the only
1002language for which this is supported is C@. If you pass source files for
1003multiple languages to the driver, using this option, the driver will invoke
1004the compiler(s) that support IMA once each, passing each compiler all the
1005source files appropriate for it. For those languages that do not support
1006IMA this option will be ignored, and the compiler will be invoked once for
1007each source file in that language. If you use this option in conjunction
1008with @option{-save-temps}, the compiler will generate multiple
1009pre-processed files
1010(one for each source file), but only one (combined) @file{.o} or
1011@file{.s} file.
1012
1013@item --help
1014@opindex help
1015Print (on the standard output) a description of the command line options
1016understood by @command{gcc}. If the @option{-v} option is also specified
1017then @option{--help} will also be passed on to the various processes
1018invoked by @command{gcc}, so that they can display the command line options
1019they accept. If the @option{-Wextra} option is also specified then command
1020line options which have no documentation associated with them will also
1021be displayed.
1022
1023@item --target-help
1024@opindex target-help
1025Print (on the standard output) a description of target specific command
1026line options for each tool.
1027
1028@item --version
1029@opindex version
1030Display the version number and copyrights of the invoked GCC@.
1031
1032@include @value{srcdir}/../libiberty/at-file.texi
1033@end table
1034
1035@node Invoking G++
1036@section Compiling C++ Programs
1037
1038@cindex suffixes for C++ source
1039@cindex C++ source file suffixes
1040C++ source files conventionally use one of the suffixes @samp{.C},
1041@samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or
1042@samp{.cxx}; C++ header files often use @samp{.hh} or @samp{.H}; and
1043preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes
1044files with these names and compiles them as C++ programs even if you
1045call the compiler the same way as for compiling C programs (usually
1046with the name @command{gcc}).
1047
1048@findex g++
1049@findex c++
1050However, the use of @command{gcc} does not add the C++ library.
1051@command{g++} is a program that calls GCC and treats @samp{.c},
1052@samp{.h} and @samp{.i} files as C++ source files instead of C source
1053files unless @option{-x} is used, and automatically specifies linking
1054against the C++ library. This program is also useful when
1055precompiling a C header file with a @samp{.h} extension for use in C++
1056compilations. On many systems, @command{g++} is also installed with
1057the name @command{c++}.
1058
1059@cindex invoking @command{g++}
1060When you compile C++ programs, you may specify many of the same
1061command-line options that you use for compiling programs in any
1062language; or command-line options meaningful for C and related
1063languages; or options that are meaningful only for C++ programs.
1064@xref{C Dialect Options,,Options Controlling C Dialect}, for
1065explanations of options for languages related to C@.
1066@xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
1067explanations of options that are meaningful only for C++ programs.
1068
1069@node C Dialect Options
1070@section Options Controlling C Dialect
1071@cindex dialect options
1072@cindex language dialect options
1073@cindex options, dialect
1074
1075The following options control the dialect of C (or languages derived
1076from C, such as C++) that the compiler accepts:
1077
1078@table @gcctabopt
1079@cindex ANSI support
1080@cindex ISO support
1081@item -ansi
1082@opindex ansi
1083In C mode, support all ISO C90 programs. In C++ mode,
1084remove GNU extensions that conflict with ISO C++.
1085
1086This turns off certain features of GCC that are incompatible with ISO
1087C90 (when compiling C code), or of standard C++ (when compiling C++ code),
1088such as the @code{asm} and @code{typeof} keywords, and
1089predefined macros such as @code{unix} and @code{vax} that identify the
1090type of system you are using. It also enables the undesirable and
1091rarely used ISO trigraph feature. For the C compiler,
1092it disables recognition of C++ style @samp{//} comments as well as
1093the @code{inline} keyword.
1094
1095The alternate keywords @code{__asm__}, @code{__extension__},
1096@code{__inline__} and @code{__typeof__} continue to work despite
1097@option{-ansi}. You would not want to use them in an ISO C program, of
1098course, but it is useful to put them in header files that might be included
1099in compilations done with @option{-ansi}. Alternate predefined macros
1100such as @code{__unix__} and @code{__vax__} are also available, with or
1101without @option{-ansi}.
1102
1103The @option{-ansi} option does not cause non-ISO programs to be
1104rejected gratuitously. For that, @option{-pedantic} is required in
1105addition to @option{-ansi}. @xref{Warning Options}.
1106
1107The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
1108option is used. Some header files may notice this macro and refrain
1109from declaring certain functions or defining certain macros that the
1110ISO standard doesn't call for; this is to avoid interfering with any
1111programs that might use these names for other things.
1112
1113Functions which would normally be built in but do not have semantics
1114defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
1115functions with @option{-ansi} is used. @xref{Other Builtins,,Other
1116built-in functions provided by GCC}, for details of the functions
1117affected.
1118
1119@item -std=
1120@opindex std
1121Determine the language standard. This option is currently only
1122supported when compiling C or C++. A value for this option must be
1123provided; possible values are
1124
1125@table @samp
1126@item c89
1127@itemx iso9899:1990
1128ISO C90 (same as @option{-ansi}).
1129
1130@item iso9899:199409
1131ISO C90 as modified in amendment 1.
1132
1133@item c99
1134@itemx c9x
1135@itemx iso9899:1999
1136@itemx iso9899:199x
1137ISO C99. Note that this standard is not yet fully supported; see
1138@w{@uref{http://gcc.gnu.org/gcc-4.2/c99status.html}} for more information. The
1139names @samp{c9x} and @samp{iso9899:199x} are deprecated.
1140
1141@item gnu89
1142Default, ISO C90 plus GNU extensions (including some C99 features).
1143
1144@item gnu99
1145@itemx gnu9x
1146ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC,
1147this will become the default. The name @samp{gnu9x} is deprecated.
1148
1149@item c++98
1150The 1998 ISO C++ standard plus amendments.
1151
1152@item gnu++98
1153The same as @option{-std=c++98} plus GNU extensions. This is the
1154default for C++ code.
1155@end table
1156
1157Even when this option is not specified, you can still use some of the
1158features of newer standards in so far as they do not conflict with
1159previous C standards. For example, you may use @code{__restrict__} even
1160when @option{-std=c99} is not specified.
1161
1162The @option{-std} options specifying some version of ISO C have the same
1163effects as @option{-ansi}, except that features that were not in ISO C90
1164but are in the specified version (for example, @samp{//} comments and
1165the @code{inline} keyword in ISO C99) are not disabled.
1166
1167@xref{Standards,,Language Standards Supported by GCC}, for details of
1168these standard versions.
1169
1170@item -fgnu89-inline
1171@opindex fgnu89-inline
1172The option @option{-fgnu89-inline} tells GCC to use the traditional
1173GNU semantics for @code{inline} functions when in C99 mode.
1174@xref{Inline,,An Inline Function is As Fast As a Macro}. Using this
1175option is roughly equivalent to adding the @code{gnu_inline} function
1176attribute to all inline functions (@pxref{Function Attributes}).
1177
1178This option is accepted by GCC versions 4.1.3 and up. In GCC versions
1179prior to 4.3, C99 inline semantics are not supported, and thus this
1180option is effectively assumed to be present regardless of whether or not
1181it is specified; the only effect of specifying it explicitly is to
1182disable warnings about using inline functions in C99 mode. Likewise,
1183the option @option{-fno-gnu89-inline} is not supported in versions of
1184GCC before 4.3. It will be supported only in C99 or gnu99 mode, not in
1185C89 or gnu89 mode.
1186
1187The preprocesor macros @code{__GNUC_GNU_INLINE__} and
1188@code{__GNUC_STDC_INLINE__} may be used to check which semantics are
1189in effect for @code{inline} functions. @xref{Common Predefined
1190Macros,,,cpp,The C Preprocessor}.
1191
1192@item -aux-info @var{filename}
1193@opindex aux-info
1194Output to the given filename prototyped declarations for all functions
1195declared and/or defined in a translation unit, including those in header
1196files. This option is silently ignored in any language other than C@.
1197
1198Besides declarations, the file indicates, in comments, the origin of
1199each declaration (source file and line), whether the declaration was
1200implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
1201@samp{O} for old, respectively, in the first character after the line
1202number and the colon), and whether it came from a declaration or a
1203definition (@samp{C} or @samp{F}, respectively, in the following
1204character). In the case of function definitions, a K&R-style list of
1205arguments followed by their declarations is also provided, inside
1206comments, after the declaration.
1207
1208@item -fno-asm
1209@opindex fno-asm
1210Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1211keyword, so that code can use these words as identifiers. You can use
1212the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
1213instead. @option{-ansi} implies @option{-fno-asm}.
1214
1215In C++, this switch only affects the @code{typeof} keyword, since
1216@code{asm} and @code{inline} are standard keywords. You may want to
1217use the @option{-fno-gnu-keywords} flag instead, which has the same
1218effect. In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
1219switch only affects the @code{asm} and @code{typeof} keywords, since
1220@code{inline} is a standard keyword in ISO C99.
1221
1222@item -fno-builtin
1223@itemx -fno-builtin-@var{function}
1224@opindex fno-builtin
1225@cindex built-in functions
1226Don't recognize built-in functions that do not begin with
1227@samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in
1228functions provided by GCC}, for details of the functions affected,
1229including those which are not built-in functions when @option{-ansi} or
1230@option{-std} options for strict ISO C conformance are used because they
1231do not have an ISO standard meaning.
1232
1233GCC normally generates special code to handle certain built-in functions
1234more efficiently; for instance, calls to @code{alloca} may become single
1235instructions that adjust the stack directly, and calls to @code{memcpy}
1236may become inline copy loops. The resulting code is often both smaller
1237and faster, but since the function calls no longer appear as such, you
1238cannot set a breakpoint on those calls, nor can you change the behavior
1239of the functions by linking with a different library. In addition,
1240when a function is recognized as a built-in function, GCC may use
1241information about that function to warn about problems with calls to
1242that function, or to generate more efficient code, even if the
1243resulting code still contains calls to that function. For example,
1244warnings are given with @option{-Wformat} for bad calls to
1245@code{printf}, when @code{printf} is built in, and @code{strlen} is
1246known not to modify global memory.
1247
1248With the @option{-fno-builtin-@var{function}} option
1249only the built-in function @var{function} is
1250disabled. @var{function} must not begin with @samp{__builtin_}. If a
1251function is named this is not built-in in this version of GCC, this
1252option is ignored. There is no corresponding
1253@option{-fbuiltin-@var{function}} option; if you wish to enable
1254built-in functions selectively when using @option{-fno-builtin} or
1255@option{-ffreestanding}, you may define macros such as:
1256
1257@smallexample
1258#define abs(n) __builtin_abs ((n))
1259#define strcpy(d, s) __builtin_strcpy ((d), (s))
1260@end smallexample
1261
1262@item -fhosted
1263@opindex fhosted
1264@cindex hosted environment
1265
1266Assert that compilation takes place in a hosted environment. This implies
1267@option{-fbuiltin}. A hosted environment is one in which the
1268entire standard library is available, and in which @code{main} has a return
1269type of @code{int}. Examples are nearly everything except a kernel.
1270This is equivalent to @option{-fno-freestanding}.
1271
1272@item -ffreestanding
1273@opindex ffreestanding
1274@cindex hosted environment
1275
1276Assert that compilation takes place in a freestanding environment. This
1277implies @option{-fno-builtin}. A freestanding environment
1278is one in which the standard library may not exist, and program startup may
1279not necessarily be at @code{main}. The most obvious example is an OS kernel.
1280This is equivalent to @option{-fno-hosted}.
1281
1282@xref{Standards,,Language Standards Supported by GCC}, for details of
1283freestanding and hosted environments.
1284
1285@item -fopenmp
1286@opindex fopenmp
1287@cindex openmp parallel
1288Enable handling of OpenMP directives @code{#pragma omp} in C/C++ and
1289@code{!$omp} in Fortran. When @option{-fopenmp} is specified, the
1290compiler generates parallel code according to the OpenMP Application
1291Program Interface v2.5 @w{@uref{http://www.openmp.org/}}.
1292
1293@item -fms-extensions
1294@opindex fms-extensions
1295Accept some non-standard constructs used in Microsoft header files.
1296
1297Some cases of unnamed fields in structures and unions are only
1298accepted with this option. @xref{Unnamed Fields,,Unnamed struct/union
1299fields within structs/unions}, for details.
1300
1301@item -trigraphs
1302@opindex trigraphs
1303Support ISO C trigraphs. The @option{-ansi} option (and @option{-std}
1304options for strict ISO C conformance) implies @option{-trigraphs}.
1305
1306@item -no-integrated-cpp
1307@opindex no-integrated-cpp
1308Performs a compilation in two passes: preprocessing and compiling. This
1309option allows a user supplied "cc1", "cc1plus", or "cc1obj" via the
1310@option{-B} option. The user supplied compilation step can then add in
1311an additional preprocessing step after normal preprocessing but before
1312compiling. The default is to use the integrated cpp (internal cpp)
1313
1314The semantics of this option will change if "cc1", "cc1plus", and
1315"cc1obj" are merged.
1316
1317@cindex traditional C language
1318@cindex C language, traditional
1319@item -traditional
1320@itemx -traditional-cpp
1321@opindex traditional-cpp
1322@opindex traditional
1323Formerly, these options caused GCC to attempt to emulate a pre-standard
1324C compiler. They are now only supported with the @option{-E} switch.
1325The preprocessor continues to support a pre-standard mode. See the GNU
1326CPP manual for details.
1327
1328@item -fcond-mismatch
1329@opindex fcond-mismatch
1330Allow conditional expressions with mismatched types in the second and
1331third arguments. The value of such an expression is void. This option
1332is not supported for C++.
1333
1334@item -funsigned-char
1335@opindex funsigned-char
1336Let the type @code{char} be unsigned, like @code{unsigned char}.
1337
1338Each kind of machine has a default for what @code{char} should
1339be. It is either like @code{unsigned char} by default or like
1340@code{signed char} by default.
1341
1342Ideally, a portable program should always use @code{signed char} or
1343@code{unsigned char} when it depends on the signedness of an object.
1344But many programs have been written to use plain @code{char} and
1345expect it to be signed, or expect it to be unsigned, depending on the
1346machines they were written for. This option, and its inverse, let you
1347make such a program work with the opposite default.
1348
1349The type @code{char} is always a distinct type from each of
1350@code{signed char} or @code{unsigned char}, even though its behavior
1351is always just like one of those two.
1352
1353@item -fsigned-char
1354@opindex fsigned-char
1355Let the type @code{char} be signed, like @code{signed char}.
1356
1357Note that this is equivalent to @option{-fno-unsigned-char}, which is
1358the negative form of @option{-funsigned-char}. Likewise, the option
1359@option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
1360
1361@item -fsigned-bitfields
1362@itemx -funsigned-bitfields
1363@itemx -fno-signed-bitfields
1364@itemx -fno-unsigned-bitfields
1365@opindex fsigned-bitfields
1366@opindex funsigned-bitfields
1367@opindex fno-signed-bitfields
1368@opindex fno-unsigned-bitfields
1369These options control whether a bit-field is signed or unsigned, when the
1370declaration does not use either @code{signed} or @code{unsigned}. By
1371default, such a bit-field is signed, because this is consistent: the
1372basic integer types such as @code{int} are signed types.
1373@end table
1374
1375@node C++ Dialect Options
1376@section Options Controlling C++ Dialect
1377
1378@cindex compiler options, C++
1379@cindex C++ options, command line
1380@cindex options, C++
1381This section describes the command-line options that are only meaningful
1382for C++ programs; but you can also use most of the GNU compiler options
1383regardless of what language your program is in. For example, you
1384might compile a file @code{firstClass.C} like this:
1385
1386@smallexample
1387g++ -g -frepo -O -c firstClass.C
1388@end smallexample
1389
1390@noindent
1391In this example, only @option{-frepo} is an option meant
1392only for C++ programs; you can use the other options with any
1393language supported by GCC@.
1394
1395Here is a list of options that are @emph{only} for compiling C++ programs:
1396
1397@table @gcctabopt
1398
1399@item -fabi-version=@var{n}
1400@opindex fabi-version
1401Use version @var{n} of the C++ ABI@. Version 2 is the version of the
1402C++ ABI that first appeared in G++ 3.4. Version 1 is the version of
1403the C++ ABI that first appeared in G++ 3.2. Version 0 will always be
1404the version that conforms most closely to the C++ ABI specification.
1405Therefore, the ABI obtained using version 0 will change as ABI bugs
1406are fixed.
1407
1408The default is version 2.
1409
1410@item -fno-access-control
1411@opindex fno-access-control
1412Turn off all access checking. This switch is mainly useful for working
1413around bugs in the access control code.
1414
1415@item -fcheck-new
1416@opindex fcheck-new
1417Check that the pointer returned by @code{operator new} is non-null
1418before attempting to modify the storage allocated. This check is
1419normally unnecessary because the C++ standard specifies that
1420@code{operator new} will only return @code{0} if it is declared
1421@samp{throw()}, in which case the compiler will always check the
1422return value even without this option. In all other cases, when
1423@code{operator new} has a non-empty exception specification, memory
1424exhaustion is signalled by throwing @code{std::bad_alloc}. See also
1425@samp{new (nothrow)}.
1426
1427@item -fconserve-space
1428@opindex fconserve-space
1429Put uninitialized or runtime-initialized global variables into the
1430common segment, as C does. This saves space in the executable at the
1431cost of not diagnosing duplicate definitions. If you compile with this
1432flag and your program mysteriously crashes after @code{main()} has
1433completed, you may have an object that is being destroyed twice because
1434two definitions were merged.
1435
1436This option is no longer useful on most targets, now that support has
1437been added for putting variables into BSS without making them common.
1438
1439@item -ffriend-injection
1440@opindex ffriend-injection
1441Inject friend functions into the enclosing namespace, so that they are
1442visible outside the scope of the class in which they are declared.
1443Friend functions were documented to work this way in the old Annotated
1444C++ Reference Manual, and versions of G++ before 4.1 always worked
1445that way. However, in ISO C++ a friend function which is not declared
1446in an enclosing scope can only be found using argument dependent
1447lookup. This option causes friends to be injected as they were in
1448earlier releases.
1449
1450This option is for compatibility, and may be removed in a future
1451release of G++.
1452
1453@item -fno-elide-constructors
1454@opindex fno-elide-constructors
1455The C++ standard allows an implementation to omit creating a temporary
1456which is only used to initialize another object of the same type.
1457Specifying this option disables that optimization, and forces G++ to
1458call the copy constructor in all cases.
1459
1460@item -fno-enforce-eh-specs
1461@opindex fno-enforce-eh-specs
1462Don't generate code to check for violation of exception specifications
1463at runtime. This option violates the C++ standard, but may be useful
1464for reducing code size in production builds, much like defining
1465@samp{NDEBUG}. This does not give user code permission to throw
1466exceptions in violation of the exception specifications; the compiler
1467will still optimize based on the specifications, so throwing an
1468unexpected exception will result in undefined behavior.
1469
1470@item -ffor-scope
1471@itemx -fno-for-scope
1472@opindex ffor-scope
1473@opindex fno-for-scope
1474If @option{-ffor-scope} is specified, the scope of variables declared in
1475a @i{for-init-statement} is limited to the @samp{for} loop itself,
1476as specified by the C++ standard.
1477If @option{-fno-for-scope} is specified, the scope of variables declared in
1478a @i{for-init-statement} extends to the end of the enclosing scope,
1479as was the case in old versions of G++, and other (traditional)
1480implementations of C++.
1481
1482The default if neither flag is given to follow the standard,
1483but to allow and give a warning for old-style code that would
1484otherwise be invalid, or have different behavior.
1485
1486@item -fno-gnu-keywords
1487@opindex fno-gnu-keywords
1488Do not recognize @code{typeof} as a keyword, so that code can use this
1489word as an identifier. You can use the keyword @code{__typeof__} instead.
1490@option{-ansi} implies @option{-fno-gnu-keywords}.
1491
1492@item -fno-implicit-templates
1493@opindex fno-implicit-templates
1494Never emit code for non-inline templates which are instantiated
1495implicitly (i.e.@: by use); only emit code for explicit instantiations.
1496@xref{Template Instantiation}, for more information.
1497
1498@item -fno-implicit-inline-templates
1499@opindex fno-implicit-inline-templates
1500Don't emit code for implicit instantiations of inline templates, either.
1501The default is to handle inlines differently so that compiles with and
1502without optimization will need the same set of explicit instantiations.
1503
1504@item -fno-implement-inlines
1505@opindex fno-implement-inlines
1506To save space, do not emit out-of-line copies of inline functions
1507controlled by @samp{#pragma implementation}. This will cause linker
1508errors if these functions are not inlined everywhere they are called.
1509
1510@item -fms-extensions
1511@opindex fms-extensions
1512Disable pedantic warnings about constructs used in MFC, such as implicit
1513int and getting a pointer to member function via non-standard syntax.
1514
1515@item -fno-nonansi-builtins
1516@opindex fno-nonansi-builtins
1517Disable built-in declarations of functions that are not mandated by
1518ANSI/ISO C@. These include @code{ffs}, @code{alloca}, @code{_exit},
1519@code{index}, @code{bzero}, @code{conjf}, and other related functions.
1520
1521@item -fno-operator-names
1522@opindex fno-operator-names
1523Do not treat the operator name keywords @code{and}, @code{bitand},
1524@code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1525synonyms as keywords.
1526
1527@item -fno-optional-diags
1528@opindex fno-optional-diags
1529Disable diagnostics that the standard says a compiler does not need to
1530issue. Currently, the only such diagnostic issued by G++ is the one for
1531a name having multiple meanings within a class.
1532
1533@item -fpermissive
1534@opindex fpermissive
1535Downgrade some diagnostics about nonconformant code from errors to
1536warnings. Thus, using @option{-fpermissive} will allow some
1537nonconforming code to compile.
1538
1539@item -frepo
1540@opindex frepo
1541Enable automatic template instantiation at link time. This option also
1542implies @option{-fno-implicit-templates}. @xref{Template
1543Instantiation}, for more information.
1544
1545@item -fno-rtti
1546@opindex fno-rtti
1547Disable generation of information about every class with virtual
1548functions for use by the C++ runtime type identification features
1549(@samp{dynamic_cast} and @samp{typeid}). If you don't use those parts
1550of the language, you can save some space by using this flag. Note that
1551exception handling uses the same information, but it will generate it as
1552needed. The @samp{dynamic_cast} operator can still be used for casts that
1553do not require runtime type information, i.e. casts to @code{void *} or to
1554unambiguous base classes.
1555
1556@item -fstats
1557@opindex fstats
1558Emit statistics about front-end processing at the end of the compilation.
1559This information is generally only useful to the G++ development team.
1560
1561@item -ftemplate-depth-@var{n}
1562@opindex ftemplate-depth
1563Set the maximum instantiation depth for template classes to @var{n}.
1564A limit on the template instantiation depth is needed to detect
1565endless recursions during template class instantiation. ANSI/ISO C++
1566conforming programs must not rely on a maximum depth greater than 17.
1567
1568@item -fno-threadsafe-statics
1569@opindex fno-threadsafe-statics
1570Do not emit the extra code to use the routines specified in the C++
1571ABI for thread-safe initialization of local statics. You can use this
1572option to reduce code size slightly in code that doesn't need to be
1573thread-safe.
1574
1575@item -fuse-cxa-atexit
1576@opindex fuse-cxa-atexit
1577Register destructors for objects with static storage duration with the
1578@code{__cxa_atexit} function rather than the @code{atexit} function.
1579This option is required for fully standards-compliant handling of static
1580destructors, but will only work if your C library supports
1581@code{__cxa_atexit}.
1582
1583@item -fno-use-cxa-get-exception-ptr
1584@opindex fno-use-cxa-get-exception-ptr
1585Don't use the @code{__cxa_get_exception_ptr} runtime routine. This
1586will cause @code{std::uncaught_exception} to be incorrect, but is necessary
1587if the runtime routine is not available.
1588
1589@item -fvisibility-inlines-hidden
1590@opindex fvisibility-inlines-hidden
1591This switch declares that the user does not attempt to compare
1592pointers to inline methods where the addresses of the two functions
1593were taken in different shared objects.
1594
1595The effect of this is that GCC may, effectively, mark inline methods with
1596@code{__attribute__ ((visibility ("hidden")))} so that they do not
1597appear in the export table of a DSO and do not require a PLT indirection
1598when used within the DSO@. Enabling this option can have a dramatic effect
1599on load and link times of a DSO as it massively reduces the size of the
1600dynamic export table when the library makes heavy use of templates.
1601
1602The behaviour of this switch is not quite the same as marking the
1603methods as hidden directly, because it does not affect static variables
1604local to the function or cause the compiler to deduce that
1605the function is defined in only one shared object.
1606
1607You may mark a method as having a visibility explicitly to negate the
1608effect of the switch for that method. For example, if you do want to
1609compare pointers to a particular inline method, you might mark it as
1610having default visibility. Marking the enclosing class with explicit
1611visibility will have no effect.
1612
1613Explicitly instantiated inline methods are unaffected by this option
1614as their linkage might otherwise cross a shared library boundary.
1615@xref{Template Instantiation}.
1616
1617@item -fno-weak
1618@opindex fno-weak
1619Do not use weak symbol support, even if it is provided by the linker.
1620By default, G++ will use weak symbols if they are available. This
1621option exists only for testing, and should not be used by end-users;
1622it will result in inferior code and has no benefits. This option may
1623be removed in a future release of G++.
1624
1625@item -nostdinc++
1626@opindex nostdinc++
1627Do not search for header files in the standard directories specific to
1628C++, but do still search the other standard directories. (This option
1629is used when building the C++ library.)
1630@end table
1631
1632In addition, these optimization, warning, and code generation options
1633have meanings only for C++ programs:
1634
1635@table @gcctabopt
1636@item -fno-default-inline
1637@opindex fno-default-inline
1638Do not assume @samp{inline} for functions defined inside a class scope.
1639@xref{Optimize Options,,Options That Control Optimization}. Note that these
1640functions will have linkage like inline functions; they just won't be
1641inlined by default.
1642
1643@item -Wabi @r{(C++ only)}
1644@opindex Wabi
1645Warn when G++ generates code that is probably not compatible with the
1646vendor-neutral C++ ABI@. Although an effort has been made to warn about
1647all such cases, there are probably some cases that are not warned about,
1648even though G++ is generating incompatible code. There may also be
1649cases where warnings are emitted even though the code that is generated
1650will be compatible.
1651
1652You should rewrite your code to avoid these warnings if you are
1653concerned about the fact that code generated by G++ may not be binary
1654compatible with code generated by other compilers.
1655
1656The known incompatibilities at this point include:
1657
1658@itemize @bullet
1659
1660@item
1661Incorrect handling of tail-padding for bit-fields. G++ may attempt to
1662pack data into the same byte as a base class. For example:
1663
1664@smallexample
1665struct A @{ virtual void f(); int f1 : 1; @};
1666struct B : public A @{ int f2 : 1; @};
1667@end smallexample
1668
1669@noindent
1670In this case, G++ will place @code{B::f2} into the same byte
1671as@code{A::f1}; other compilers will not. You can avoid this problem
1672by explicitly padding @code{A} so that its size is a multiple of the
1673byte size on your platform; that will cause G++ and other compilers to
1674layout @code{B} identically.
1675
1676@item
1677Incorrect handling of tail-padding for virtual bases. G++ does not use
1678tail padding when laying out virtual bases. For example:
1679
1680@smallexample
1681struct A @{ virtual void f(); char c1; @};
1682struct B @{ B(); char c2; @};
1683struct C : public A, public virtual B @{@};
1684@end smallexample
1685
1686@noindent
1687In this case, G++ will not place @code{B} into the tail-padding for
1688@code{A}; other compilers will. You can avoid this problem by
1689explicitly padding @code{A} so that its size is a multiple of its
1690alignment (ignoring virtual base classes); that will cause G++ and other
1691compilers to layout @code{C} identically.
1692
1693@item
1694Incorrect handling of bit-fields with declared widths greater than that
1695of their underlying types, when the bit-fields appear in a union. For
1696example:
1697
1698@smallexample
1699union U @{ int i : 4096; @};
1700@end smallexample
1701
1702@noindent
1703Assuming that an @code{int} does not have 4096 bits, G++ will make the
1704union too small by the number of bits in an @code{int}.
1705
1706@item
1707Empty classes can be placed at incorrect offsets. For example:
1708
1709@smallexample
1710struct A @{@};
1711
1712struct B @{
1713 A a;
1714 virtual void f ();
1715@};
1716
1717struct C : public B, public A @{@};
1718@end smallexample
1719
1720@noindent
1721G++ will place the @code{A} base class of @code{C} at a nonzero offset;
1722it should be placed at offset zero. G++ mistakenly believes that the
1723@code{A} data member of @code{B} is already at offset zero.
1724
1725@item
1726Names of template functions whose types involve @code{typename} or
1727template template parameters can be mangled incorrectly.
1728
1729@smallexample
1730template <typename Q>
1731void f(typename Q::X) @{@}
1732
1733template <template <typename> class Q>
1734void f(typename Q<int>::X) @{@}
1735@end smallexample
1736
1737@noindent
1738Instantiations of these templates may be mangled incorrectly.
1739
1740@end itemize
1741
1742@item -Wctor-dtor-privacy @r{(C++ only)}
1743@opindex Wctor-dtor-privacy
1744Warn when a class seems unusable because all the constructors or
1745destructors in that class are private, and it has neither friends nor
1746public static member functions.
1747
1748@item -Wnon-virtual-dtor @r{(C++ only)}
1749@opindex Wnon-virtual-dtor
1750Warn when a class appears to be polymorphic, thereby requiring a virtual
1751destructor, yet it declares a non-virtual one. This warning is also
1752enabled if -Weffc++ is specified.
1753
1754@item -Wreorder @r{(C++ only)}
1755@opindex Wreorder
1756@cindex reordering, warning
1757@cindex warning for reordering of member initializers
1758Warn when the order of member initializers given in the code does not
1759match the order in which they must be executed. For instance:
1760
1761@smallexample
1762struct A @{
1763 int i;
1764 int j;
1765 A(): j (0), i (1) @{ @}
1766@};
1767@end smallexample
1768
1769The compiler will rearrange the member initializers for @samp{i}
1770and @samp{j} to match the declaration order of the members, emitting
1771a warning to that effect. This warning is enabled by @option{-Wall}.
1772@end table
1773
1774The following @option{-W@dots{}} options are not affected by @option{-Wall}.
1775
1776@table @gcctabopt
1777@item -Weffc++ @r{(C++ only)}
1778@opindex Weffc++
1779Warn about violations of the following style guidelines from Scott Meyers'
1780@cite{Effective C++} book:
1781
1782@itemize @bullet
1783@item
1784Item 11: Define a copy constructor and an assignment operator for classes
1785with dynamically allocated memory.
1786
1787@item
1788Item 12: Prefer initialization to assignment in constructors.
1789
1790@item
1791Item 14: Make destructors virtual in base classes.
1792
1793@item
1794Item 15: Have @code{operator=} return a reference to @code{*this}.
1795
1796@item
1797Item 23: Don't try to return a reference when you must return an object.
1798
1799@end itemize
1800
1801Also warn about violations of the following style guidelines from
1802Scott Meyers' @cite{More Effective C++} book:
1803
1804@itemize @bullet
1805@item
1806Item 6: Distinguish between prefix and postfix forms of increment and
1807decrement operators.
1808
1809@item
1810Item 7: Never overload @code{&&}, @code{||}, or @code{,}.
1811
1812@end itemize
1813
1814When selecting this option, be aware that the standard library
1815headers do not obey all of these guidelines; use @samp{grep -v}
1816to filter out those warnings.
1817
1818@item -Wno-deprecated @r{(C++ only)}
1819@opindex Wno-deprecated
1820Do not warn about usage of deprecated features. @xref{Deprecated Features}.
1821
1822@item -Wstrict-null-sentinel @r{(C++ only)}
1823@opindex Wstrict-null-sentinel
1824Warn also about the use of an uncasted @code{NULL} as sentinel. When
1825compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
1826to @code{__null}. Although it is a null pointer constant not a null pointer,
1827it is guaranteed to of the same size as a pointer. But this use is
1828not portable across different compilers.
1829
1830@item -Wno-non-template-friend @r{(C++ only)}
1831@opindex Wno-non-template-friend
1832Disable warnings when non-templatized friend functions are declared
1833within a template. Since the advent of explicit template specification
1834support in G++, if the name of the friend is an unqualified-id (i.e.,
1835@samp{friend foo(int)}), the C++ language specification demands that the
1836friend declare or define an ordinary, nontemplate function. (Section
183714.5.3). Before G++ implemented explicit specification, unqualified-ids
1838could be interpreted as a particular specialization of a templatized
1839function. Because this non-conforming behavior is no longer the default
1840behavior for G++, @option{-Wnon-template-friend} allows the compiler to
1841check existing code for potential trouble spots and is on by default.
1842This new compiler behavior can be turned off with
1843@option{-Wno-non-template-friend} which keeps the conformant compiler code
1844but disables the helpful warning.
1845
1846@item -Wold-style-cast @r{(C++ only)}
1847@opindex Wold-style-cast
1848Warn if an old-style (C-style) cast to a non-void type is used within
1849a C++ program. The new-style casts (@samp{dynamic_cast},
1850@samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are
1851less vulnerable to unintended effects and much easier to search for.
1852
1853@item -Woverloaded-virtual @r{(C++ only)}
1854@opindex Woverloaded-virtual
1855@cindex overloaded virtual fn, warning
1856@cindex warning for overloaded virtual fn
1857Warn when a function declaration hides virtual functions from a
1858base class. For example, in:
1859
1860@smallexample
1861struct A @{
1862 virtual void f();
1863@};
1864
1865struct B: public A @{
1866 void f(int);
1867@};
1868@end smallexample
1869
1870the @code{A} class version of @code{f} is hidden in @code{B}, and code
1871like:
1872
1873@smallexample
1874B* b;
1875b->f();
1876@end smallexample
1877
1878will fail to compile.
1879
1880@item -Wno-pmf-conversions @r{(C++ only)}
1881@opindex Wno-pmf-conversions
1882Disable the diagnostic for converting a bound pointer to member function
1883to a plain pointer.
1884
1885@item -Wsign-promo @r{(C++ only)}
1886@opindex Wsign-promo
1887Warn when overload resolution chooses a promotion from unsigned or
1888enumerated type to a signed type, over a conversion to an unsigned type of
1889the same size. Previous versions of G++ would try to preserve
1890unsignedness, but the standard mandates the current behavior.
1891
1892@smallexample
1893struct A @{
1894 operator int ();
1895 A& operator = (int);
1896@};
1897
1898main ()
1899@{
1900 A a,b;
1901 a = b;
1902@}
1903@end smallexample
1904
1905In this example, G++ will synthesize a default @samp{A& operator =
1906(const A&);}, while cfront will use the user-defined @samp{operator =}.
1907@end table
1908
1909@node Language Independent Options
1910@section Options to Control Diagnostic Messages Formatting
1911@cindex options to control diagnostics formatting
1912@cindex diagnostic messages
1913@cindex message formatting
1914
1915Traditionally, diagnostic messages have been formatted irrespective of
1916the output device's aspect (e.g.@: its width, @dots{}). The options described
1917below can be used to control the diagnostic messages formatting
1918algorithm, e.g.@: how many characters per line, how often source location
1919information should be reported. Right now, only the C++ front end can
1920honor these options. However it is expected, in the near future, that
1921the remaining front ends would be able to digest them correctly.
1922
1923@table @gcctabopt
1924@item -fmessage-length=@var{n}
1925@opindex fmessage-length
1926Try to format error messages so that they fit on lines of about @var{n}
1927characters. The default is 72 characters for @command{g++} and 0 for the rest of
1928the front ends supported by GCC@. If @var{n} is zero, then no
1929line-wrapping will be done; each error message will appear on a single
1930line.
1931
1932@opindex fdiagnostics-show-location
1933@item -fdiagnostics-show-location=once
1934Only meaningful in line-wrapping mode. Instructs the diagnostic messages
1935reporter to emit @emph{once} source location information; that is, in
1936case the message is too long to fit on a single physical line and has to
1937be wrapped, the source location won't be emitted (as prefix) again,
1938over and over, in subsequent continuation lines. This is the default
1939behavior.
1940
1941@item -fdiagnostics-show-location=every-line
1942Only meaningful in line-wrapping mode. Instructs the diagnostic
1943messages reporter to emit the same source location information (as
1944prefix) for physical lines that result from the process of breaking
1945a message which is too long to fit on a single line.
1946
1947@item -fdiagnostics-show-option
1948@opindex fdiagnostics-show-option
1949This option instructs the diagnostic machinery to add text to each
1950diagnostic emitted, which indicates which command line option directly
1951controls that diagnostic, when such an option is known to the
1952diagnostic machinery.
1953
1954@end table
1955
1956@node Warning Options
1957@section Options to Request or Suppress Warnings
1958@cindex options to control warnings
1959@cindex warning messages
1960@cindex messages, warning
1961@cindex suppressing warnings
1962
1963Warnings are diagnostic messages that report constructions which
1964are not inherently erroneous but which are risky or suggest there
1965may have been an error.
1966
1967You can request many specific warnings with options beginning @samp{-W},
1968for example @option{-Wimplicit} to request warnings on implicit
1969declarations. Each of these specific warning options also has a
1970negative form beginning @samp{-Wno-} to turn off warnings;
1971for example, @option{-Wno-implicit}. This manual lists only one of the
1972two forms, whichever is not the default.
1973
1974The following options control the amount and kinds of warnings produced
1975by GCC; for further, language-specific options also refer to
1976@ref{C++ Dialect Options}.
1977
1978@table @gcctabopt
1979@cindex syntax checking
1980@item -fsyntax-only
1981@opindex fsyntax-only
1982Check the code for syntax errors, but don't do anything beyond that.
1983
1984@item -pedantic
1985@opindex pedantic
1986Issue all the warnings demanded by strict ISO C and ISO C++;
1987reject all programs that use forbidden extensions, and some other
1988programs that do not follow ISO C and ISO C++. For ISO C, follows the
1989version of the ISO C standard specified by any @option{-std} option used.
1990
1991Valid ISO C and ISO C++ programs should compile properly with or without
1992this option (though a rare few will require @option{-ansi} or a
1993@option{-std} option specifying the required version of ISO C)@. However,
1994without this option, certain GNU extensions and traditional C and C++
1995features are supported as well. With this option, they are rejected.
1996
1997@option{-pedantic} does not cause warning messages for use of the
1998alternate keywords whose names begin and end with @samp{__}. Pedantic
1999warnings are also disabled in the expression that follows
2000@code{__extension__}. However, only system header files should use
2001these escape routes; application programs should avoid them.
2002@xref{Alternate Keywords}.
2003
2004Some users try to use @option{-pedantic} to check programs for strict ISO
2005C conformance. They soon find that it does not do quite what they want:
2006it finds some non-ISO practices, but not all---only those for which
2007ISO C @emph{requires} a diagnostic, and some others for which
2008diagnostics have been added.
2009
2010A feature to report any failure to conform to ISO C might be useful in
2011some instances, but would require considerable additional work and would
2012be quite different from @option{-pedantic}. We don't have plans to
2013support such a feature in the near future.
2014
2015Where the standard specified with @option{-std} represents a GNU
2016extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
2017corresponding @dfn{base standard}, the version of ISO C on which the GNU
2018extended dialect is based. Warnings from @option{-pedantic} are given
2019where they are required by the base standard. (It would not make sense
2020for such warnings to be given only for features not in the specified GNU
2021C dialect, since by definition the GNU dialects of C include all
2022features the compiler supports with the given option, and there would be
2023nothing to warn about.)
2024
2025@item -pedantic-errors
2026@opindex pedantic-errors
2027Like @option{-pedantic}, except that errors are produced rather than
2028warnings.
2029
2030@item -w
2031@opindex w
2032Inhibit all warning messages.
2033
2034@item -Wno-import
2035@opindex Wno-import
2036Inhibit warning messages about the use of @samp{#import}.
2037
2038@item -Wchar-subscripts
2039@opindex Wchar-subscripts
2040Warn if an array subscript has type @code{char}. This is a common cause
2041of error, as programmers often forget that this type is signed on some
2042machines.
2043This warning is enabled by @option{-Wall}.
2044
2045@item -Wcomment
2046@opindex Wcomment
2047Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
2048comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
2049This warning is enabled by @option{-Wall}.
2050
2051@item -Wfatal-errors
2052@opindex Wfatal-errors
2053This option causes the compiler to abort compilation on the first error
2054occurred rather than trying to keep going and printing further error
2055messages.
2056
2057@item -Wformat
2058@opindex Wformat
2059@opindex ffreestanding
2060@opindex fno-builtin
2061Check calls to @code{printf} and @code{scanf}, etc., to make sure that
2062the arguments supplied have types appropriate to the format string
2063specified, and that the conversions specified in the format string make
2064sense. This includes standard functions, and others specified by format
2065attributes (@pxref{Function Attributes}), in the @code{printf},
2066@code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
2067not in the C standard) families (or other target-specific families).
2068Which functions are checked without format attributes having been
2069specified depends on the standard version selected, and such checks of
2070functions without the attribute specified are disabled by
2071@option{-ffreestanding} or @option{-fno-builtin}.
2072
2073The formats are checked against the format features supported by GNU
2074libc version 2.2. These include all ISO C90 and C99 features, as well
2075as features from the Single Unix Specification and some BSD and GNU
2076extensions. Other library implementations may not support all these
2077features; GCC does not support warning about features that go beyond a
2078particular library's limitations. However, if @option{-pedantic} is used
2079with @option{-Wformat}, warnings will be given about format features not
2080in the selected standard version (but not for @code{strfmon} formats,
2081since those are not in any version of the C standard). @xref{C Dialect
2082Options,,Options Controlling C Dialect}.
2083
2084Since @option{-Wformat} also checks for null format arguments for
2085several functions, @option{-Wformat} also implies @option{-Wnonnull}.
2086
2087@option{-Wformat} is included in @option{-Wall}. For more control over some
2088aspects of format checking, the options @option{-Wformat-y2k},
2089@option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
2090@option{-Wformat-nonliteral}, @option{-Wformat-security}, and
2091@option{-Wformat=2} are available, but are not included in @option{-Wall}.
2092
2093@item -Wformat-y2k
2094@opindex Wformat-y2k
2095If @option{-Wformat} is specified, also warn about @code{strftime}
2096formats which may yield only a two-digit year.
2097
2098@item -Wno-format-extra-args
2099@opindex Wno-format-extra-args
2100If @option{-Wformat} is specified, do not warn about excess arguments to a
2101@code{printf} or @code{scanf} format function. The C standard specifies
2102that such arguments are ignored.
2103
2104Where the unused arguments lie between used arguments that are
2105specified with @samp{$} operand number specifications, normally
2106warnings are still given, since the implementation could not know what
2107type to pass to @code{va_arg} to skip the unused arguments. However,
2108in the case of @code{scanf} formats, this option will suppress the
2109warning if the unused arguments are all pointers, since the Single
2110Unix Specification says that such unused arguments are allowed.
2111
2112@item -Wno-format-zero-length
2113@opindex Wno-format-zero-length
2114If @option{-Wformat} is specified, do not warn about zero-length formats.
2115The C standard specifies that zero-length formats are allowed.
2116
2117@item -Wformat-nonliteral
2118@opindex Wformat-nonliteral
2119If @option{-Wformat} is specified, also warn if the format string is not a
2120string literal and so cannot be checked, unless the format function
2121takes its format arguments as a @code{va_list}.
2122
2123@item -Wformat-security
2124@opindex Wformat-security
2125If @option{-Wformat} is specified, also warn about uses of format
2126functions that represent possible security problems. At present, this
2127warns about calls to @code{printf} and @code{scanf} functions where the
2128format string is not a string literal and there are no format arguments,
2129as in @code{printf (foo);}. This may be a security hole if the format
2130string came from untrusted input and contains @samp{%n}. (This is
2131currently a subset of what @option{-Wformat-nonliteral} warns about, but
2132in future warnings may be added to @option{-Wformat-security} that are not
2133included in @option{-Wformat-nonliteral}.)
2134
2135@item -Wformat=2
2136@opindex Wformat=2
2137Enable @option{-Wformat} plus format checks not included in
2138@option{-Wformat}. Currently equivalent to @samp{-Wformat
2139-Wformat-nonliteral -Wformat-security -Wformat-y2k}.
2140
2141@item -Wnonnull
2142@opindex Wnonnull
2143Warn about passing a null pointer for arguments marked as
2144requiring a non-null value by the @code{nonnull} function attribute.
2145
2146@option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It
2147can be disabled with the @option{-Wno-nonnull} option.
2148
2149@item -Winit-self @r{(C and C++ only)}
2150@opindex Winit-self
2151Warn about uninitialized variables which are initialized with themselves.
2152Note this option can only be used with the @option{-Wuninitialized} option,
2153which in turn only works with @option{-O1} and above.
2154
2155For example, GCC will warn about @code{i} being uninitialized in the
2156following snippet only when @option{-Winit-self} has been specified:
2157@smallexample
2158@group
2159int f()
2160@{
2161 int i = i;
2162 return i;
2163@}
2164@end group
2165@end smallexample
2166
2167@item -Wimplicit-int
2168@opindex Wimplicit-int
2169Warn when a declaration does not specify a type.
2170This warning is enabled by @option{-Wall}.
2171
2172@item -Wimplicit-function-declaration
2173@itemx -Werror-implicit-function-declaration
2174@opindex Wimplicit-function-declaration
2175@opindex Werror-implicit-function-declaration
2176Give a warning (or error) whenever a function is used before being
2177declared. The form @option{-Wno-error-implicit-function-declaration}
2178is not supported.
2179This warning is enabled by @option{-Wall} (as a warning, not an error).
2180
2181@item -Wimplicit
2182@opindex Wimplicit
2183Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
2184This warning is enabled by @option{-Wall}.
2185
2186@item -Wmain
2187@opindex Wmain
2188Warn if the type of @samp{main} is suspicious. @samp{main} should be a
2189function with external linkage, returning int, taking either zero
2190arguments, two, or three arguments of appropriate types.
2191This warning is enabled by @option{-Wall}.
2192
2193@item -Wmissing-braces
2194@opindex Wmissing-braces
2195Warn if an aggregate or union initializer is not fully bracketed. In
2196the following example, the initializer for @samp{a} is not fully
2197bracketed, but that for @samp{b} is fully bracketed.
2198
2199@smallexample
2200int a[2][2] = @{ 0, 1, 2, 3 @};
2201int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
2202@end smallexample
2203
2204This warning is enabled by @option{-Wall}.
2205
2206@item -Wmissing-include-dirs @r{(C and C++ only)}
2207@opindex Wmissing-include-dirs
2208Warn if a user-supplied include directory does not exist.
2209
2210@item -Wparentheses
2211@opindex Wparentheses
2212Warn if parentheses are omitted in certain contexts, such
2213as when there is an assignment in a context where a truth value
2214is expected, or when operators are nested whose precedence people
2215often get confused about.
2216
2217Also warn if a comparison like @samp{x<=y<=z} appears; this is
2218equivalent to @samp{(x<=y ? 1 : 0) <= z}, which is a different
2219interpretation from that of ordinary mathematical notation.
2220
2221Also warn about constructions where there may be confusion to which
2222@code{if} statement an @code{else} branch belongs. Here is an example of
2223such a case:
2224
2225@smallexample
2226@group
2227@{
2228 if (a)
2229 if (b)
2230 foo ();
2231 else
2232 bar ();
2233@}
2234@end group
2235@end smallexample
2236
2237In C/C++, every @code{else} branch belongs to the innermost possible
2238@code{if} statement, which in this example is @code{if (b)}. This is
2239often not what the programmer expected, as illustrated in the above
2240example by indentation the programmer chose. When there is the
2241potential for this confusion, GCC will issue a warning when this flag
2242is specified. To eliminate the warning, add explicit braces around
2243the innermost @code{if} statement so there is no way the @code{else}
2244could belong to the enclosing @code{if}. The resulting code would
2245look like this:
2246
2247@smallexample
2248@group
2249@{
2250 if (a)
2251 @{
2252 if (b)
2253 foo ();
2254 else
2255 bar ();
2256 @}
2257@}
2258@end group
2259@end smallexample
2260
2261This warning is enabled by @option{-Wall}.
2262
2263@item -Wsequence-point
2264@opindex Wsequence-point
2265Warn about code that may have undefined semantics because of violations
2266of sequence point rules in the C and C++ standards.
2267
2268The C and C++ standards defines the order in which expressions in a C/C++
2269program are evaluated in terms of @dfn{sequence points}, which represent
2270a partial ordering between the execution of parts of the program: those
2271executed before the sequence point, and those executed after it. These
2272occur after the evaluation of a full expression (one which is not part
2273of a larger expression), after the evaluation of the first operand of a
2274@code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
2275function is called (but after the evaluation of its arguments and the
2276expression denoting the called function), and in certain other places.
2277Other than as expressed by the sequence point rules, the order of
2278evaluation of subexpressions of an expression is not specified. All
2279these rules describe only a partial order rather than a total order,
2280since, for example, if two functions are called within one expression
2281with no sequence point between them, the order in which the functions
2282are called is not specified. However, the standards committee have
2283ruled that function calls do not overlap.
2284
2285It is not specified when between sequence points modifications to the
2286values of objects take effect. Programs whose behavior depends on this
2287have undefined behavior; the C and C++ standards specify that ``Between
2288the previous and next sequence point an object shall have its stored
2289value modified at most once by the evaluation of an expression.
2290Furthermore, the prior value shall be read only to determine the value
2291to be stored.''. If a program breaks these rules, the results on any
2292particular implementation are entirely unpredictable.
2293
2294Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
2295= b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
2296diagnosed by this option, and it may give an occasional false positive
2297result, but in general it has been found fairly effective at detecting
2298this sort of problem in programs.
2299
2300The standard is worded confusingly, therefore there is some debate
2301over the precise meaning of the sequence point rules in subtle cases.
2302Links to discussions of the problem, including proposed formal
2303definitions, may be found on the GCC readings page, at
2304@w{@uref{http://gcc.gnu.org/readings.html}}.
2305
2306This warning is enabled by @option{-Wall} for C and C++.
2307
2308@item -Wreturn-type
2309@opindex Wreturn-type
2310Warn whenever a function is defined with a return-type that defaults to
2311@code{int}. Also warn about any @code{return} statement with no
2312return-value in a function whose return-type is not @code{void}.
2313
2314For C, also warn if the return type of a function has a type qualifier
2315such as @code{const}. Such a type qualifier has no effect, since the
2316value returned by a function is not an lvalue. ISO C prohibits
2317qualified @code{void} return types on function definitions, so such
2318return types always receive a warning even without this option.
2319
2320For C++, a function without return type always produces a diagnostic
2321message, even when @option{-Wno-return-type} is specified. The only
2322exceptions are @samp{main} and functions defined in system headers.
2323
2324This warning is enabled by @option{-Wall}.
2325
2326@item -Wswitch
2327@opindex Wswitch
2328Warn whenever a @code{switch} statement has an index of enumerated type
2329and lacks a @code{case} for one or more of the named codes of that
2330enumeration. (The presence of a @code{default} label prevents this
2331warning.) @code{case} labels outside the enumeration range also
2332provoke warnings when this option is used.
2333This warning is enabled by @option{-Wall}.
2334
2335@item -Wswitch-default
2336@opindex Wswitch-switch
2337Warn whenever a @code{switch} statement does not have a @code{default}
2338case.
2339
2340@item -Wswitch-enum
2341@opindex Wswitch-enum
2342Warn whenever a @code{switch} statement has an index of enumerated type
2343and lacks a @code{case} for one or more of the named codes of that
2344enumeration. @code{case} labels outside the enumeration range also
2345provoke warnings when this option is used.
2346
2347@item -Wtrigraphs
2348@opindex Wtrigraphs
2349Warn if any trigraphs are encountered that might change the meaning of
2350the program (trigraphs within comments are not warned about).
2351This warning is enabled by @option{-Wall}.
2352
2353@item -Wunused-function
2354@opindex Wunused-function
2355Warn whenever a static function is declared but not defined or a
2356non-inline static function is unused.
2357This warning is enabled by @option{-Wall}.
2358
2359@item -Wunused-label
2360@opindex Wunused-label
2361Warn whenever a label is declared but not used.
2362This warning is enabled by @option{-Wall}.
2363
2364To suppress this warning use the @samp{unused} attribute
2365(@pxref{Variable Attributes}).
2366
2367@item -Wunused-parameter
2368@opindex Wunused-parameter
2369Warn whenever a function parameter is unused aside from its declaration.
2370
2371To suppress this warning use the @samp{unused} attribute
2372(@pxref{Variable Attributes}).
2373
2374@item -Wunused-variable
2375@opindex Wunused-variable
2376Warn whenever a local variable or non-constant static variable is unused
2377aside from its declaration.
2378This warning is enabled by @option{-Wall}.
2379
2380To suppress this warning use the @samp{unused} attribute
2381(@pxref{Variable Attributes}).
2382
2383@item -Wunused-value
2384@opindex Wunused-value
2385Warn whenever a statement computes a result that is explicitly not used.
2386This warning is enabled by @option{-Wall}.
2387
2388To suppress this warning cast the expression to @samp{void}.
2389
2390@item -Wunused
2391@opindex Wunused
2392All the above @option{-Wunused} options combined.
2393
2394In order to get a warning about an unused function parameter, you must
2395either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
2396@samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
2397
2398@item -Wuninitialized
2399@opindex Wuninitialized
2400Warn if an automatic variable is used without first being initialized or
2401if a variable may be clobbered by a @code{setjmp} call.
2402
2403These warnings are possible only in optimizing compilation,
2404because they require data flow information that is computed only
2405when optimizing. If you do not specify @option{-O}, you will not get
2406these warnings. Instead, GCC will issue a warning about @option{-Wuninitialized}
2407requiring @option{-O}.
2408
2409If you want to warn about code which uses the uninitialized value of the
2410variable in its own initializer, use the @option{-Winit-self} option.
2411
2412These warnings occur for individual uninitialized or clobbered
2413elements of structure, union or array variables as well as for
2414variables which are uninitialized or clobbered as a whole. They do
2415not occur for variables or elements declared @code{volatile}. Because
2416these warnings depend on optimization, the exact variables or elements
2417for which there are warnings will depend on the precise optimization
2418options and version of GCC used.
2419
2420Note that there may be no warning about a variable that is used only
2421to compute a value that itself is never used, because such
2422computations may be deleted by data flow analysis before the warnings
2423are printed.
2424
2425These warnings are made optional because GCC is not smart
2426enough to see all the reasons why the code might be correct
2427despite appearing to have an error. Here is one example of how
2428this can happen:
2429
2430@smallexample
2431@group
2432@{
2433 int x;
2434 switch (y)
2435 @{
2436 case 1: x = 1;
2437 break;
2438 case 2: x = 4;
2439 break;
2440 case 3: x = 5;
2441 @}
2442 foo (x);
2443@}
2444@end group
2445@end smallexample
2446
2447@noindent
2448If the value of @code{y} is always 1, 2 or 3, then @code{x} is
2449always initialized, but GCC doesn't know this. Here is
2450another common case:
2451
2452@smallexample
2453@{
2454 int save_y;
2455 if (change_y) save_y = y, y = new_y;
2456 @dots{}
2457 if (change_y) y = save_y;
2458@}
2459@end smallexample
2460
2461@noindent
2462This has no bug because @code{save_y} is used only if it is set.
2463
2464@cindex @code{longjmp} warnings
2465This option also warns when a non-volatile automatic variable might be
2466changed by a call to @code{longjmp}. These warnings as well are possible
2467only in optimizing compilation.
2468
2469The compiler sees only the calls to @code{setjmp}. It cannot know
2470where @code{longjmp} will be called; in fact, a signal handler could
2471call it at any point in the code. As a result, you may get a warning
2472even when there is in fact no problem because @code{longjmp} cannot
2473in fact be called at the place which would cause a problem.
2474
2475Some spurious warnings can be avoided if you declare all the functions
2476you use that never return as @code{noreturn}. @xref{Function
2477Attributes}.
2478
2479This warning is enabled by @option{-Wall}.
2480
2481@item -Wunknown-pragmas
2482@opindex Wunknown-pragmas
2483@cindex warning for unknown pragmas
2484@cindex unknown pragmas, warning
2485@cindex pragmas, warning of unknown
2486Warn when a #pragma directive is encountered which is not understood by
2487GCC@. If this command line option is used, warnings will even be issued
2488for unknown pragmas in system header files. This is not the case if
2489the warnings were only enabled by the @option{-Wall} command line option.
2490
2491@item -Wno-pragmas
2492@opindex Wno-pragmas
2493@opindex Wpragmas
2494Do not warn about misuses of pragmas, such as incorrect parameters,
2495invalid syntax, or conflicts between pragmas. See also
2496@samp{-Wunknown-pragmas}.
2497
2498@item -Wstrict-aliasing
2499@opindex Wstrict-aliasing
2500This option is only active when @option{-fstrict-aliasing} is active.
2501It warns about code which might break the strict aliasing rules that the
2502compiler is using for optimization. The warning does not catch all
2503cases, but does attempt to catch the more common pitfalls. It is
2504included in @option{-Wall}.
2505
2506@item -Wstrict-aliasing=2
2507@opindex Wstrict-aliasing=2
2508This option is only active when @option{-fstrict-aliasing} is active.
2509It warns about code which might break the strict aliasing rules that the
2510compiler is using for optimization. This warning catches more cases than
2511@option{-Wstrict-aliasing}, but it will also give a warning for some ambiguous
2512cases that are safe.
2513
2514@item -Wstrict-overflow
2515@item -Wstrict-overflow=@var{n}
2516@opindex Wstrict-overflow
2517This option is only active when @option{-fstrict-overflow} is active.
2518It warns about cases where the compiler optimizes based on the
2519assumption that signed overflow does not occur. Note that it does not
2520warn about all cases where the code might overflow: it only warns
2521about cases where the compiler implements some optimization. Thus
2522this warning depends on the optimization level.
2523
2524An optimization which assumes that signed overflow does not occur is
2525perfectly safe if the values of the variables involved are such that
2526overflow never does, in fact, occur. Therefore this warning can
2527easily give a false positive: a warning about code which is not
2528actually a problem. To help focus on important issues, several
2529warning levels are defined. No warnings are issued for the use of
2530undefined signed overflow when estimating how many iterations a loop
2531will require, in particular when determining whether a loop will be
2532executed at all.
2533
2534@table @option
2535@item -Wstrict-overflow=1
2536Warn about cases which are both questionable and easy to avoid. For
2537example: @code{x + 1 > x}; with @option{-fstrict-overflow}, the
2538compiler will simplify this to @code{1}. This level of
2539@option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
2540are not, and must be explicitly requested.
2541
2542@item -Wstrict-overflow=2
2543Also warn about other cases where a comparison is simplified to a
2544constant. For example: @code{abs (x) >= 0}. This can only be
2545simplified when @option{-fstrict-overflow} is in effect, because
2546@code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
2547zero. @option{-Wstrict-overflow} (with no level) is the same as
2548@option{-Wstrict-overflow=2}.
2549
2550@item -Wstrict-overflow=3
2551Also warn about other cases where a comparison is simplified. For
2552example: @code{x + 1 > 1} will be simplified to @code{x > 0}.
2553
2554@item -Wstrict-overflow=4
2555Also warn about other simplifications not covered by the above cases.
2556For example: @code{(x * 10) / 5} will be simplified to @code{x * 2}.
2557
2558@item -Wstrict-overflow=5
2559Also warn about cases where the compiler reduces the magnitude of a
2560constant involved in a comparison. For example: @code{x + 2 > y} will
2561be simplified to @code{x + 1 >= y}. This is reported only at the
2562highest warning level because this simplification applies to many
2563comparisons, so this warning level will give a very large number of
2564false positives.
2565@end table
2566
2567@item -Wall
2568@opindex Wall
2569All of the above @samp{-W} options combined. This enables all the
2570warnings about constructions that some users consider questionable, and
2571that are easy to avoid (or modify to prevent the warning), even in
2572conjunction with macros. This also enables some language-specific
2573warnings described in @ref{C++ Dialect Options}.
2574@end table
2575
2576The following @option{-W@dots{}} options are not implied by @option{-Wall}.
2577Some of them warn about constructions that users generally do not
2578consider questionable, but which occasionally you might wish to check
2579for; others warn about constructions that are necessary or hard to avoid
2580in some cases, and there is no simple way to modify the code to suppress
2581the warning.
2582
2583@table @gcctabopt
2584@item -Wextra
2585@opindex W
2586@opindex Wextra
2587(This option used to be called @option{-W}. The older name is still
2588supported, but the newer name is more descriptive.) Print extra warning
2589messages for these events:
2590
2591@itemize @bullet
2592@item
2593A function can return either with or without a value. (Falling
2594off the end of the function body is considered returning without
2595a value.) For example, this function would evoke such a
2596warning:
2597
2598@smallexample
2599@group
2600foo (a)
2601@{
2602 if (a > 0)
2603 return a;
2604@}
2605@end group
2606@end smallexample
2607
2608@item
2609An expression-statement or the left-hand side of a comma expression
2610contains no side effects.
2611To suppress the warning, cast the unused expression to void.
2612For example, an expression such as @samp{x[i,j]} will cause a warning,
2613but @samp{x[(void)i,j]} will not.
2614
2615@item
2616An unsigned value is compared against zero with @samp{<} or @samp{>=}.
2617
2618@item
2619Storage-class specifiers like @code{static} are not the first things in
2620a declaration. According to the C Standard, this usage is obsolescent.
2621
2622@item
2623If @option{-Wall} or @option{-Wunused} is also specified, warn about unused
2624arguments.
2625
2626@item
2627A comparison between signed and unsigned values could produce an
2628incorrect result when the signed value is converted to unsigned.
2629(But don't warn if @option{-Wno-sign-compare} is also specified.)
2630
2631@item
2632An aggregate has an initializer which does not initialize all members.
2633This warning can be independently controlled by
2634@option{-Wmissing-field-initializers}.
2635
2636@item
2637An initialized field without side effects is overridden when using
2638designated initializers (@pxref{Designated Inits, , Designated
2639Initializers}). This warning can be independently controlled by
2640@option{-Woverride-init}.
2641
2642@item
2643A function parameter is declared without a type specifier in K&R-style
2644functions:
2645
2646@smallexample
2647void foo(bar) @{ @}
2648@end smallexample
2649
2650@item
2651An empty body occurs in an @samp{if} or @samp{else} statement.
2652
2653@item
2654A pointer is compared against integer zero with @samp{<}, @samp{<=},
2655@samp{>}, or @samp{>=}.
2656
2657@item
2658A variable might be changed by @samp{longjmp} or @samp{vfork}.
2659
2660@item @r{(C++ only)}
2661An enumerator and a non-enumerator both appear in a conditional expression.
2662
2663@item @r{(C++ only)}
2664A non-static reference or non-static @samp{const} member appears in a
2665class without constructors.
2666
2667@item @r{(C++ only)}
2668Ambiguous virtual bases.
2669
2670@item @r{(C++ only)}
2671Subscripting an array which has been declared @samp{register}.
2672
2673@item @r{(C++ only)}
2674Taking the address of a variable which has been declared @samp{register}.
2675
2676@item @r{(C++ only)}
2677A base class is not initialized in a derived class' copy constructor.
2678@end itemize
2679
2680@item -Wno-div-by-zero
2681@opindex Wno-div-by-zero
2682@opindex Wdiv-by-zero
2683Do not warn about compile-time integer division by zero. Floating point
2684division by zero is not warned about, as it can be a legitimate way of
2685obtaining infinities and NaNs.
2686
2687@item -Wsystem-headers
2688@opindex Wsystem-headers
2689@cindex warnings from system headers
2690@cindex system headers, warnings from
2691Print warning messages for constructs found in system header files.
2692Warnings from system headers are normally suppressed, on the assumption
2693that they usually do not indicate real problems and would only make the
2694compiler output harder to read. Using this command line option tells
2695GCC to emit warnings from system headers as if they occurred in user
2696code. However, note that using @option{-Wall} in conjunction with this
2697option will @emph{not} warn about unknown pragmas in system
2698headers---for that, @option{-Wunknown-pragmas} must also be used.
2699
2700@item -Wfloat-equal
2701@opindex Wfloat-equal
2702Warn if floating point values are used in equality comparisons.
2703
2704The idea behind this is that sometimes it is convenient (for the
2705programmer) to consider floating-point values as approximations to
2706infinitely precise real numbers. If you are doing this, then you need
2707to compute (by analyzing the code, or in some other way) the maximum or
2708likely maximum error that the computation introduces, and allow for it
2709when performing comparisons (and when producing output, but that's a
2710different problem). In particular, instead of testing for equality, you
2711would check to see whether the two values have ranges that overlap; and
2712this is done with the relational operators, so equality comparisons are
2713probably mistaken.
2714
2715@item -Wtraditional @r{(C only)}
2716@opindex Wtraditional
2717Warn about certain constructs that behave differently in traditional and
2718ISO C@. Also warn about ISO C constructs that have no traditional C
2719equivalent, and/or problematic constructs which should be avoided.
2720
2721@itemize @bullet
2722@item
2723Macro parameters that appear within string literals in the macro body.
2724In traditional C macro replacement takes place within string literals,
2725but does not in ISO C@.
2726
2727@item
2728In traditional C, some preprocessor directives did not exist.
2729Traditional preprocessors would only consider a line to be a directive
2730if the @samp{#} appeared in column 1 on the line. Therefore
2731@option{-Wtraditional} warns about directives that traditional C
2732understands but would ignore because the @samp{#} does not appear as the
2733first character on the line. It also suggests you hide directives like
2734@samp{#pragma} not understood by traditional C by indenting them. Some
2735traditional implementations would not recognize @samp{#elif}, so it
2736suggests avoiding it altogether.
2737
2738@item
2739A function-like macro that appears without arguments.
2740
2741@item
2742The unary plus operator.
2743
2744@item
2745The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
2746constant suffixes. (Traditional C does support the @samp{L} suffix on integer
2747constants.) Note, these suffixes appear in macros defined in the system
2748headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
2749Use of these macros in user code might normally lead to spurious
2750warnings, however GCC's integrated preprocessor has enough context to
2751avoid warning in these cases.
2752
2753@item
2754A function declared external in one block and then used after the end of
2755the block.
2756
2757@item
2758A @code{switch} statement has an operand of type @code{long}.
2759
2760@item
2761A non-@code{static} function declaration follows a @code{static} one.
2762This construct is not accepted by some traditional C compilers.
2763
2764@item
2765The ISO type of an integer constant has a different width or
2766signedness from its traditional type. This warning is only issued if
2767the base of the constant is ten. I.e.@: hexadecimal or octal values, which
2768typically represent bit patterns, are not warned about.
2769
2770@item
2771Usage of ISO string concatenation is detected.
2772
2773@item
2774Initialization of automatic aggregates.
2775
2776@item
2777Identifier conflicts with labels. Traditional C lacks a separate
2778namespace for labels.
2779
2780@item
2781Initialization of unions. If the initializer is zero, the warning is
2782omitted. This is done under the assumption that the zero initializer in
2783user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
2784initializer warnings and relies on default initialization to zero in the
2785traditional C case.
2786
2787@item
2788Conversions by prototypes between fixed/floating point values and vice
2789versa. The absence of these prototypes when compiling with traditional
2790C would cause serious problems. This is a subset of the possible
2791conversion warnings, for the full set use @option{-Wconversion}.
2792
2793@item
2794Use of ISO C style function definitions. This warning intentionally is
2795@emph{not} issued for prototype declarations or variadic functions
2796because these ISO C features will appear in your code when using
2797libiberty's traditional C compatibility macros, @code{PARAMS} and
2798@code{VPARAMS}. This warning is also bypassed for nested functions
2799because that feature is already a GCC extension and thus not relevant to
2800traditional C compatibility.
2801@end itemize
2802
2803@item -Wdeclaration-after-statement @r{(C only)}
2804@opindex Wdeclaration-after-statement
2805Warn when a declaration is found after a statement in a block. This
2806construct, known from C++, was introduced with ISO C99 and is by default
2807allowed in GCC@. It is not supported by ISO C90 and was not supported by
2808GCC versions before GCC 3.0. @xref{Mixed Declarations}.
2809
2810@item -Wundef
2811@opindex Wundef
2812Warn if an undefined identifier is evaluated in an @samp{#if} directive.
2813
2814@item -Wno-endif-labels
2815@opindex Wno-endif-labels
2816@opindex Wendif-labels
2817Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
2818
2819@item -Wshadow
2820@opindex Wshadow
2821Warn whenever a local variable shadows another local variable, parameter or
2822global variable or whenever a built-in function is shadowed.
2823
2824@item -Wlarger-than-@var{len}
2825@opindex Wlarger-than
2826Warn whenever an object of larger than @var{len} bytes is defined.
2827
2828@item -Wunsafe-loop-optimizations
2829@opindex Wunsafe-loop-optimizations
2830Warn if the loop cannot be optimized because the compiler could not
2831assume anything on the bounds of the loop indices. With
2832@option{-funsafe-loop-optimizations} warn if the compiler made
2833such assumptions.
2834
2835@item -Wpointer-arith
2836@opindex Wpointer-arith
2837Warn about anything that depends on the ``size of'' a function type or
2838of @code{void}. GNU C assigns these types a size of 1, for
2839convenience in calculations with @code{void *} pointers and pointers
2840to functions.
2841
2842@item -Wbad-function-cast @r{(C only)}
2843@opindex Wbad-function-cast
2844Warn whenever a function call is cast to a non-matching type.
2845For example, warn if @code{int malloc()} is cast to @code{anything *}.
2846
2847@item -Wc++-compat
2848Warn about ISO C constructs that are outside of the common subset of
2849ISO C and ISO C++, e.g.@: request for implicit conversion from
2850@code{void *} to a pointer to non-@code{void} type.
2851
2852@item -Wcast-qual
2853@opindex Wcast-qual
2854Warn whenever a pointer is cast so as to remove a type qualifier from
2855the target type. For example, warn if a @code{const char *} is cast
2856to an ordinary @code{char *}.
2857
2858@item -Wcast-align
2859@opindex Wcast-align
2860Warn whenever a pointer is cast such that the required alignment of the
2861target is increased. For example, warn if a @code{char *} is cast to
2862an @code{int *} on machines where integers can only be accessed at
2863two- or four-byte boundaries.
2864
2865@item -Wwrite-strings
2866@opindex Wwrite-strings
2867When compiling C, give string constants the type @code{const
2868char[@var{length}]} so that
2869copying the address of one into a non-@code{const} @code{char *}
2870pointer will get a warning; when compiling C++, warn about the
2871deprecated conversion from string literals to @code{char *}. This
2872warning, by default, is enabled for C++ programs.
2873These warnings will help you find at
2874compile time code that can try to write into a string constant, but
2875only if you have been very careful about using @code{const} in
2876declarations and prototypes. Otherwise, it will just be a nuisance;
2877this is why we did not make @option{-Wall} request these warnings.
2878
2879@item -Wconversion
2880@opindex Wconversion
2881Warn if a prototype causes a type conversion that is different from what
2882would happen to the same argument in the absence of a prototype. This
2883includes conversions of fixed point to floating and vice versa, and
2884conversions changing the width or signedness of a fixed point argument
2885except when the same as the default promotion.
2886
2887Also, warn if a negative integer constant expression is implicitly
2888converted to an unsigned type. For example, warn about the assignment
2889@code{x = -1} if @code{x} is unsigned. But do not warn about explicit
2890casts like @code{(unsigned) -1}.
2891
2892@item -Wsign-compare
2893@opindex Wsign-compare
2894@cindex warning for comparison of signed and unsigned values
2895@cindex comparison of signed and unsigned values, warning
2896@cindex signed and unsigned values, comparison warning
2897Warn when a comparison between signed and unsigned values could produce
2898an incorrect result when the signed value is converted to unsigned.
2899This warning is also enabled by @option{-Wextra}; to get the other warnings
2900of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
2901
2902@item -Waddress
2903@opindex Waddress
2904@opindex Wno-address
2905Warn about suspicious uses of memory addresses. These include using
2906the address of a function in a conditional expression, such as
2907@code{void func(void); if (func)}, and comparisons against the memory
2908address of a string literal, such as @code{if (x == "abc")}. Such
2909uses typically indicate a programmer error: the address of a function
2910always evaluates to true, so their use in a conditional usually
2911indicate that the programmer forgot the parentheses in a function
2912call; and comparisons against string literals result in unspecified
2913behavior and are not portable in C, so they usually indicate that the
2914programmer intended to use @code{strcmp}. This warning is enabled by
2915@option{-Wall}.
2916
2917@item -Waggregate-return
2918@opindex Waggregate-return
2919Warn if any functions that return structures or unions are defined or
2920called. (In languages where you can return an array, this also elicits
2921a warning.)
2922
2923@item -Wno-attributes
2924@opindex Wno-attributes
2925@opindex Wattributes
2926Do not warn if an unexpected @code{__attribute__} is used, such as
2927unrecognized attributes, function attributes applied to variables,
2928etc. This will not stop errors for incorrect use of supported
2929attributes.
2930
2931@item -Wstrict-prototypes @r{(C only)}
2932@opindex Wstrict-prototypes
2933Warn if a function is declared or defined without specifying the
2934argument types. (An old-style function definition is permitted without
2935a warning if preceded by a declaration which specifies the argument
2936types.)
2937
2938@item -Wold-style-definition @r{(C only)}
2939@opindex Wold-style-definition
2940Warn if an old-style function definition is used. A warning is given
2941even if there is a previous prototype.
2942
2943@item -Wmissing-prototypes @r{(C only)}
2944@opindex Wmissing-prototypes
2945Warn if a global function is defined without a previous prototype
2946declaration. This warning is issued even if the definition itself
2947provides a prototype. The aim is to detect global functions that fail
2948to be declared in header files.
2949
2950@item -Wmissing-declarations @r{(C only)}
2951@opindex Wmissing-declarations
2952Warn if a global function is defined without a previous declaration.
2953Do so even if the definition itself provides a prototype.
2954Use this option to detect global functions that are not declared in
2955header files.
2956
2957@item -Wmissing-field-initializers
2958@opindex Wmissing-field-initializers
2959@opindex W
2960@opindex Wextra
2961Warn if a structure's initializer has some fields missing. For
2962example, the following code would cause such a warning, because
2963@code{x.h} is implicitly zero:
2964
2965@smallexample
2966struct s @{ int f, g, h; @};
2967struct s x = @{ 3, 4 @};
2968@end smallexample
2969
2970This option does not warn about designated initializers, so the following
2971modification would not trigger a warning:
2972
2973@smallexample
2974struct s @{ int f, g, h; @};
2975struct s x = @{ .f = 3, .g = 4 @};
2976@end smallexample
2977
2978This warning is included in @option{-Wextra}. To get other @option{-Wextra}
2979warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
2980
2981@item -Wmissing-noreturn
2982@opindex Wmissing-noreturn
2983Warn about functions which might be candidates for attribute @code{noreturn}.
2984Note these are only possible candidates, not absolute ones. Care should
2985be taken to manually verify functions actually do not ever return before
2986adding the @code{noreturn} attribute, otherwise subtle code generation
2987bugs could be introduced. You will not get a warning for @code{main} in
2988hosted C environments.
2989
2990@item -Wmissing-format-attribute
2991@opindex Wmissing-format-attribute
2992@opindex Wformat
2993Warn about function pointers which might be candidates for @code{format}
2994attributes. Note these are only possible candidates, not absolute ones.
2995GCC will guess that function pointers with @code{format} attributes that
2996are used in assignment, initialization, parameter passing or return
2997statements should have a corresponding @code{format} attribute in the
2998resulting type. I.e.@: the left-hand side of the assignment or
2999initialization, the type of the parameter variable, or the return type
3000of the containing function respectively should also have a @code{format}
3001attribute to avoid the warning.
3002
3003GCC will also warn about function definitions which might be
3004candidates for @code{format} attributes. Again, these are only
3005possible candidates. GCC will guess that @code{format} attributes
3006might be appropriate for any function that calls a function like
3007@code{vprintf} or @code{vscanf}, but this might not always be the
3008case, and some functions for which @code{format} attributes are
3009appropriate may not be detected.
3010
3011@item -Wno-multichar
3012@opindex Wno-multichar
3013@opindex Wmultichar
3014Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
3015Usually they indicate a typo in the user's code, as they have
3016implementation-defined values, and should not be used in portable code.
3017
3018@item -Wnormalized=<none|id|nfc|nfkc>
3019@opindex Wnormalized
3020@cindex NFC
3021@cindex NFKC
3022@cindex character set, input normalization
3023In ISO C and ISO C++, two identifiers are different if they are
3024different sequences of characters. However, sometimes when characters
3025outside the basic ASCII character set are used, you can have two
3026different character sequences that look the same. To avoid confusion,
3027the ISO 10646 standard sets out some @dfn{normalization rules} which
3028when applied ensure that two sequences that look the same are turned into
3029the same sequence. GCC can warn you if you are using identifiers which
3030have not been normalized; this option controls that warning.
3031
3032There are four levels of warning that GCC supports. The default is
3033@option{-Wnormalized=nfc}, which warns about any identifier which is
3034not in the ISO 10646 ``C'' normalized form, @dfn{NFC}. NFC is the
3035recommended form for most uses.
3036
3037Unfortunately, there are some characters which ISO C and ISO C++ allow
3038in identifiers that when turned into NFC aren't allowable as
3039identifiers. That is, there's no way to use these symbols in portable
3040ISO C or C++ and have all your identifiers in NFC.
3041@option{-Wnormalized=id} suppresses the warning for these characters.
3042It is hoped that future versions of the standards involved will correct
3043this, which is why this option is not the default.
3044
3045You can switch the warning off for all characters by writing
3046@option{-Wnormalized=none}. You would only want to do this if you
3047were using some other normalization scheme (like ``D''), because
3048otherwise you can easily create bugs that are literally impossible to see.
3049
3050Some characters in ISO 10646 have distinct meanings but look identical
3051in some fonts or display methodologies, especially once formatting has
3052been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
3053LETTER N'', will display just like a regular @code{n} which has been
3054placed in a superscript. ISO 10646 defines the @dfn{NFKC}
3055normalization scheme to convert all these into a standard form as
3056well, and GCC will warn if your code is not in NFKC if you use
3057@option{-Wnormalized=nfkc}. This warning is comparable to warning
3058about every identifier that contains the letter O because it might be
3059confused with the digit 0, and so is not the default, but may be
3060useful as a local coding convention if the programming environment is
3061unable to be fixed to display these characters distinctly.
3062
3063@item -Wno-deprecated-declarations
3064@opindex Wno-deprecated-declarations
3065Do not warn about uses of functions (@pxref{Function Attributes}),
3066variables (@pxref{Variable Attributes}), and types (@pxref{Type
3067Attributes}) marked as deprecated by using the @code{deprecated}
3068attribute.
3069
3070@item -Wno-overflow
3071@opindex Wno-overflow
3072Do not warn about compile-time overflow in constant expressions.
3073
3074@item -Woverride-init
3075@opindex Woverride-init
3076@opindex W
3077@opindex Wextra
3078Warn if an initialized field without side effects is overridden when
3079using designated initializers (@pxref{Designated Inits, , Designated
3080Initializers}).
3081
3082This warning is included in @option{-Wextra}. To get other
3083@option{-Wextra} warnings without this one, use @samp{-Wextra
3084-Wno-override-init}.
3085
3086@item -Wpacked
3087@opindex Wpacked
3088Warn if a structure is given the packed attribute, but the packed
3089attribute has no effect on the layout or size of the structure.
3090Such structures may be mis-aligned for little benefit. For
3091instance, in this code, the variable @code{f.x} in @code{struct bar}
3092will be misaligned even though @code{struct bar} does not itself
3093have the packed attribute:
3094
3095@smallexample
3096@group
3097struct foo @{
3098 int x;
3099 char a, b, c, d;
3100@} __attribute__((packed));
3101struct bar @{
3102 char z;
3103 struct foo f;
3104@};
3105@end group
3106@end smallexample
3107
3108@item -Wpadded
3109@opindex Wpadded
3110Warn if padding is included in a structure, either to align an element
3111of the structure or to align the whole structure. Sometimes when this
3112happens it is possible to rearrange the fields of the structure to
3113reduce the padding and so make the structure smaller.
3114
3115@item -Wredundant-decls
3116@opindex Wredundant-decls
3117Warn if anything is declared more than once in the same scope, even in
3118cases where multiple declaration is valid and changes nothing.
3119
3120@item -Wnested-externs @r{(C only)}
3121@opindex Wnested-externs
3122Warn if an @code{extern} declaration is encountered within a function.
3123
3124@item -Wunreachable-code
3125@opindex Wunreachable-code
3126Warn if the compiler detects that code will never be executed.
3127
3128This option is intended to warn when the compiler detects that at
3129least a whole line of source code will never be executed, because
3130some condition is never satisfied or because it is after a
3131procedure that never returns.
3132
3133It is possible for this option to produce a warning even though there
3134are circumstances under which part of the affected line can be executed,
3135so care should be taken when removing apparently-unreachable code.
3136
3137For instance, when a function is inlined, a warning may mean that the
3138line is unreachable in only one inlined copy of the function.
3139
3140This option is not made part of @option{-Wall} because in a debugging
3141version of a program there is often substantial code which checks
3142correct functioning of the program and is, hopefully, unreachable
3143because the program does work. Another common use of unreachable
3144code is to provide behavior which is selectable at compile-time.
3145
3146@item -Winline
3147@opindex Winline
3148Warn if a function can not be inlined and it was declared as inline.
3149Even with this option, the compiler will not warn about failures to
3150inline functions declared in system headers.
3151
3152The compiler uses a variety of heuristics to determine whether or not
3153to inline a function. For example, the compiler takes into account
3154the size of the function being inlined and the amount of inlining
3155that has already been done in the current function. Therefore,
3156seemingly insignificant changes in the source program can cause the
3157warnings produced by @option{-Winline} to appear or disappear.
3158
3159@item -Wno-invalid-offsetof @r{(C++ only)}
3160@opindex Wno-invalid-offsetof
3161Suppress warnings from applying the @samp{offsetof} macro to a non-POD
3162type. According to the 1998 ISO C++ standard, applying @samp{offsetof}
3163to a non-POD type is undefined. In existing C++ implementations,
3164however, @samp{offsetof} typically gives meaningful results even when
3165applied to certain kinds of non-POD types. (Such as a simple
3166@samp{struct} that fails to be a POD type only by virtue of having a
3167constructor.) This flag is for users who are aware that they are
3168writing nonportable code and who have deliberately chosen to ignore the
3169warning about it.
3170
3171The restrictions on @samp{offsetof} may be relaxed in a future version
3172of the C++ standard.
3173
3174@item -Wno-int-to-pointer-cast @r{(C only)}
3175@opindex Wno-int-to-pointer-cast
3176Suppress warnings from casts to pointer type of an integer of a
3177different size.
3178
3179@item -Wno-pointer-to-int-cast @r{(C only)}
3180@opindex Wno-pointer-to-int-cast
3181Suppress warnings from casts from a pointer to an integer type of a
3182different size.
3183
3184@item -Winvalid-pch
3185@opindex Winvalid-pch
3186Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
3187the search path but can't be used.
3188
3189@item -Wlong-long
3190@opindex Wlong-long
3191@opindex Wno-long-long
3192Warn if @samp{long long} type is used. This is default. To inhibit
3193the warning messages, use @option{-Wno-long-long}. Flags
3194@option{-Wlong-long} and @option{-Wno-long-long} are taken into account
3195only when @option{-pedantic} flag is used.
3196
3197@item -Wvariadic-macros
3198@opindex Wvariadic-macros
3199@opindex Wno-variadic-macros
3200Warn if variadic macros are used in pedantic ISO C90 mode, or the GNU
3201alternate syntax when in pedantic ISO C99 mode. This is default.
3202To inhibit the warning messages, use @option{-Wno-variadic-macros}.
3203
235-Wvolatile-register-var -Wwrite-strings}
236
237@item C-only Warning Options
238@gccoptlist{-Wbad-function-cast -Wmissing-declarations @gol
239-Wmissing-prototypes -Wnested-externs -Wold-style-definition @gol
240-Wstrict-prototypes -Wtraditional @gol
241-Wdeclaration-after-statement -Wpointer-sign}
242
243@item Debugging Options
244@xref{Debugging Options,,Options for Debugging Your Program or GCC}.
245@gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
246-fdump-noaddr -fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} @gol
247-fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
248-fdump-ipa-all -fdump-ipa-cgraph @gol
249-fdump-tree-all @gol
250-fdump-tree-original@r{[}-@var{n}@r{]} @gol
251-fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
252-fdump-tree-inlined@r{[}-@var{n}@r{]} @gol
253-fdump-tree-cfg -fdump-tree-vcg -fdump-tree-alias @gol
254-fdump-tree-ch @gol
255-fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol
256-fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol
257-fdump-tree-gimple@r{[}-raw@r{]} -fdump-tree-mudflap@r{[}-@var{n}@r{]} @gol
258-fdump-tree-dom@r{[}-@var{n}@r{]} @gol
259-fdump-tree-dse@r{[}-@var{n}@r{]} @gol
260-fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol
261-fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
262-fdump-tree-copyrename@r{[}-@var{n}@r{]} @gol
263-fdump-tree-nrv -fdump-tree-vect @gol
264-fdump-tree-sink @gol
265-fdump-tree-sra@r{[}-@var{n}@r{]} @gol
266-fdump-tree-salias @gol
267-fdump-tree-fre@r{[}-@var{n}@r{]} @gol
268-fdump-tree-vrp@r{[}-@var{n}@r{]} @gol
269-ftree-vectorizer-verbose=@var{n} @gol
270-fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol
271-feliminate-dwarf2-dups -feliminate-unused-debug-types @gol
272-feliminate-unused-debug-symbols -femit-class-debug-always @gol
273-fmem-report -fprofile-arcs @gol
274-frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
275-ftest-coverage -ftime-report -fvar-tracking @gol
276-g -g@var{level} -gcoff -gdwarf-2 @gol
277-ggdb -gstabs -gstabs+ -gvms -gxcoff -gxcoff+ @gol
278-p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol
279-print-multi-directory -print-multi-lib @gol
280-print-prog-name=@var{program} -print-search-dirs -Q @gol
281-save-temps -time}
282
283@item Optimization Options
284@xref{Optimize Options,,Options that Control Optimization}.
285@gccoptlist{-falign-functions=@var{n} -falign-jumps=@var{n} @gol
286-falign-labels=@var{n} -falign-loops=@var{n} @gol
287-fbounds-check -fmudflap -fmudflapth -fmudflapir @gol
288-fbranch-probabilities -fprofile-values -fvpt -fbranch-target-load-optimize @gol
289-fbranch-target-load-optimize2 -fbtr-bb-exclusive @gol
290-fcaller-saves -fcprop-registers -fcse-follow-jumps @gol
291-fcse-skip-blocks -fcx-limited-range -fdata-sections @gol
292-fdelayed-branch -fdelete-null-pointer-checks -fearly-inlining @gol
293-fexpensive-optimizations -ffast-math -ffloat-store @gol
294-fforce-addr -ffunction-sections @gol
295-fgcse -fgcse-lm -fgcse-sm -fgcse-las -fgcse-after-reload @gol
296-fcrossjumping -fif-conversion -fif-conversion2 @gol
297-finline-functions -finline-functions-called-once @gol
298-finline-limit=@var{n} -fkeep-inline-functions @gol
299-fkeep-static-consts -fmerge-constants -fmerge-all-constants @gol
300-fmodulo-sched -fno-branch-count-reg @gol
301-fno-default-inline -fno-defer-pop -fmove-loop-invariants @gol
302-fno-function-cse -fno-guess-branch-probability @gol
303-fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol
304-funsafe-math-optimizations -funsafe-loop-optimizations -ffinite-math-only @gol
305-fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol
306-fomit-frame-pointer -foptimize-register-move @gol
307-foptimize-sibling-calls -fprefetch-loop-arrays @gol
308-fprofile-generate -fprofile-use @gol
309-fregmove -frename-registers @gol
310-freorder-blocks -freorder-blocks-and-partition -freorder-functions @gol
311-frerun-cse-after-loop @gol
312-frounding-math -frtl-abstract-sequences @gol
313-fschedule-insns -fschedule-insns2 @gol
314-fno-sched-interblock -fno-sched-spec -fsched-spec-load @gol
315-fsched-spec-load-dangerous @gol
316-fsched-stalled-insns=@var{n} -fsched-stalled-insns-dep=@var{n} @gol
317-fsched2-use-superblocks @gol
318-fsched2-use-traces -fsee -freschedule-modulo-scheduled-loops @gol
319-fsection-anchors -fsignaling-nans -fsingle-precision-constant @gol
320-fstack-protector -fstack-protector-all @gol
321-fstrict-aliasing -fstrict-overflow -ftracer -fthread-jumps @gol
322-funroll-all-loops -funroll-loops -fpeel-loops @gol
323-fsplit-ivs-in-unroller -funswitch-loops @gol
324-fvariable-expansion-in-unroller @gol
325-ftree-pre -ftree-ccp -ftree-dce -ftree-loop-optimize @gol
326-ftree-loop-linear -ftree-loop-im -ftree-loop-ivcanon -fivopts @gol
327-ftree-dominator-opts -ftree-dse -ftree-copyrename -ftree-sink @gol
328-ftree-ch -ftree-sra -ftree-ter -ftree-lrs -ftree-fre -ftree-vectorize @gol
329-ftree-vect-loop-version -ftree-salias -fipa-pta -fweb @gol
330-ftree-copy-prop -ftree-store-ccp -ftree-store-copy-prop -fwhole-program @gol
331--param @var{name}=@var{value}
332-O -O0 -O1 -O2 -O3 -Os}
333
334@item Preprocessor Options
335@xref{Preprocessor Options,,Options Controlling the Preprocessor}.
336@gccoptlist{-A@var{question}=@var{answer} @gol
337-A-@var{question}@r{[}=@var{answer}@r{]} @gol
338-C -dD -dI -dM -dN @gol
339-D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol
340-idirafter @var{dir} @gol
341-include @var{file} -imacros @var{file} @gol
342-iprefix @var{file} -iwithprefix @var{dir} @gol
343-iwithprefixbefore @var{dir} -isystem @var{dir} @gol
344-imultilib @var{dir} -isysroot @var{dir} @gol
345-M -MM -MF -MG -MP -MQ -MT -nostdinc @gol
346-P -fworking-directory -remap @gol
347-trigraphs -undef -U@var{macro} -Wp,@var{option} @gol
348-Xpreprocessor @var{option}}
349
350@item Assembler Option
351@xref{Assembler Options,,Passing Options to the Assembler}.
352@gccoptlist{-Wa,@var{option} -Xassembler @var{option}}
353
354@item Linker Options
355@xref{Link Options,,Options for Linking}.
356@gccoptlist{@var{object-file-name} -l@var{library} @gol
357-nostartfiles -nodefaultlibs -nostdlib -pie -rdynamic @gol
358-s -static -static-libgcc -shared -shared-libgcc -symbolic @gol
359-Wl,@var{option} -Xlinker @var{option} @gol
360-u @var{symbol}}
361
362@item Directory Options
363@xref{Directory Options,,Options for Directory Search}.
364@gccoptlist{-B@var{prefix} -I@var{dir} -iquote@var{dir} -L@var{dir}
365-specs=@var{file} -I- --sysroot=@var{dir}}
366
367@item Target Options
368@c I wrote this xref this way to avoid overfull hbox. -- rms
369@xref{Target Options}.
370@gccoptlist{-V @var{version} -b @var{machine}}
371
372@item Machine Dependent Options
373@xref{Submodel Options,,Hardware Models and Configurations}.
374@c This list is ordered alphanumerically by subsection name.
375@c Try and put the significant identifier (CPU or system) first,
376@c so users have a clue at guessing where the ones they want will be.
377
378@emph{ARC Options}
379@gccoptlist{-EB -EL @gol
380-mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text-section} @gol
381-mdata=@var{data-section} -mrodata=@var{readonly-data-section}}
382
383@emph{ARM Options}
384@gccoptlist{-mapcs-frame -mno-apcs-frame @gol
385-mabi=@var{name} @gol
386-mapcs-stack-check -mno-apcs-stack-check @gol
387-mapcs-float -mno-apcs-float @gol
388-mapcs-reentrant -mno-apcs-reentrant @gol
389-msched-prolog -mno-sched-prolog @gol
390-mlittle-endian -mbig-endian -mwords-little-endian @gol
391-mfloat-abi=@var{name} -msoft-float -mhard-float -mfpe @gol
392-mthumb-interwork -mno-thumb-interwork @gol
393-mcpu=@var{name} -march=@var{name} -mfpu=@var{name} @gol
394-mstructure-size-boundary=@var{n} @gol
395-mabort-on-noreturn @gol
396-mlong-calls -mno-long-calls @gol
397-msingle-pic-base -mno-single-pic-base @gol
398-mpic-register=@var{reg} @gol
399-mnop-fun-dllimport @gol
400-mcirrus-fix-invalid-insns -mno-cirrus-fix-invalid-insns @gol
401-mpoke-function-name @gol
402-mthumb -marm @gol
403-mtpcs-frame -mtpcs-leaf-frame @gol
404-mcaller-super-interworking -mcallee-super-interworking @gol
405-mtp=@var{name}}
406
407@emph{AVR Options}
408@gccoptlist{-mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts @gol
409-mcall-prologues -mno-tablejump -mtiny-stack -mint8}
410
411@emph{Blackfin Options}
412@gccoptlist{-momit-leaf-frame-pointer -mno-omit-leaf-frame-pointer @gol
413-mspecld-anomaly -mno-specld-anomaly -mcsync-anomaly -mno-csync-anomaly @gol
414-mlow-64k -mno-low64k -mid-shared-library @gol
415-mno-id-shared-library -mshared-library-id=@var{n} @gol
416-mlong-calls -mno-long-calls}
417
418@emph{CRIS Options}
419@gccoptlist{-mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol
420-mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol
421-metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol
422-mstack-align -mdata-align -mconst-align @gol
423-m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol
424-melf -maout -melinux -mlinux -sim -sim2 @gol
425-mmul-bug-workaround -mno-mul-bug-workaround}
426
427@emph{CRX Options}
428@gccoptlist{-mmac -mpush-args}
429
430@emph{Darwin Options}
431@gccoptlist{-all_load -allowable_client -arch -arch_errors_fatal @gol
432-arch_only -bind_at_load -bundle -bundle_loader @gol
433-client_name -compatibility_version -current_version @gol
434-dead_strip @gol
435-dependency-file -dylib_file -dylinker_install_name @gol
436-dynamic -dynamiclib -exported_symbols_list @gol
437-filelist -flat_namespace -force_cpusubtype_ALL @gol
438-force_flat_namespace -headerpad_max_install_names @gol
439-image_base -init -install_name -keep_private_externs @gol
440-multi_module -multiply_defined -multiply_defined_unused @gol
441-noall_load -no_dead_strip_inits_and_terms @gol
442-nofixprebinding -nomultidefs -noprebind -noseglinkedit @gol
443-pagezero_size -prebind -prebind_all_twolevel_modules @gol
444-private_bundle -read_only_relocs -sectalign @gol
445-sectobjectsymbols -whyload -seg1addr @gol
446-sectcreate -sectobjectsymbols -sectorder @gol
447-segaddr -segs_read_only_addr -segs_read_write_addr @gol
448-seg_addr_table -seg_addr_table_filename -seglinkedit @gol
449-segprot -segs_read_only_addr -segs_read_write_addr @gol
450-single_module -static -sub_library -sub_umbrella @gol
451-twolevel_namespace -umbrella -undefined @gol
452-unexported_symbols_list -weak_reference_mismatches @gol
453-whatsloaded -F -gused -gfull -mmacosx-version-min=@var{version} @gol
454-mkernel -mone-byte-bool}
455
456@emph{DEC Alpha Options}
457@gccoptlist{-mno-fp-regs -msoft-float -malpha-as -mgas @gol
458-mieee -mieee-with-inexact -mieee-conformant @gol
459-mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} @gol
460-mtrap-precision=@var{mode} -mbuild-constants @gol
461-mcpu=@var{cpu-type} -mtune=@var{cpu-type} @gol
462-mbwx -mmax -mfix -mcix @gol
463-mfloat-vax -mfloat-ieee @gol
464-mexplicit-relocs -msmall-data -mlarge-data @gol
465-msmall-text -mlarge-text @gol
466-mmemory-latency=@var{time}}
467
468@emph{DEC Alpha/VMS Options}
469@gccoptlist{-mvms-return-codes}
470
471@emph{FRV Options}
472@gccoptlist{-mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 @gol
473-mhard-float -msoft-float @gol
474-malloc-cc -mfixed-cc -mdword -mno-dword @gol
475-mdouble -mno-double @gol
476-mmedia -mno-media -mmuladd -mno-muladd @gol
477-mfdpic -minline-plt -mgprel-ro -multilib-library-pic @gol
478-mlinked-fp -mlong-calls -malign-labels @gol
479-mlibrary-pic -macc-4 -macc-8 @gol
480-mpack -mno-pack -mno-eflags -mcond-move -mno-cond-move @gol
481-moptimize-membar -mno-optimize-membar @gol
482-mscc -mno-scc -mcond-exec -mno-cond-exec @gol
483-mvliw-branch -mno-vliw-branch @gol
484-mmulti-cond-exec -mno-multi-cond-exec -mnested-cond-exec @gol
485-mno-nested-cond-exec -mtomcat-stats @gol
486-mTLS -mtls @gol
487-mcpu=@var{cpu}}
488
489@emph{GNU/Linux Options}
490@gccoptlist{-muclibc}
491
492@emph{H8/300 Options}
493@gccoptlist{-mrelax -mh -ms -mn -mint32 -malign-300}
494
495@emph{HPPA Options}
496@gccoptlist{-march=@var{architecture-type} @gol
497-mbig-switch -mdisable-fpregs -mdisable-indexing @gol
498-mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol
499-mfixed-range=@var{register-range} @gol
500-mjump-in-delay -mlinker-opt -mlong-calls @gol
501-mlong-load-store -mno-big-switch -mno-disable-fpregs @gol
502-mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol
503-mno-jump-in-delay -mno-long-load-store @gol
504-mno-portable-runtime -mno-soft-float @gol
505-mno-space-regs -msoft-float -mpa-risc-1-0 @gol
506-mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime @gol
507-mschedule=@var{cpu-type} -mspace-regs -msio -mwsio @gol
508-munix=@var{unix-std} -nolibdld -static -threads}
509
510@emph{i386 and x86-64 Options}
511@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
512-mfpmath=@var{unit} @gol
513-masm=@var{dialect} -mno-fancy-math-387 @gol
514-mno-fp-ret-in-387 -msoft-float -msvr3-shlib @gol
515-mno-wide-multiply -mrtd -malign-double @gol
516-mpreferred-stack-boundary=@var{num} @gol
517-mmmx -msse -msse2 -msse3 -mssse3 -msse4a -m3dnow -mpopcnt -mabm -maes @gol
518-mthreads -mno-align-stringops -minline-all-stringops @gol
519-mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol
520-m96bit-long-double -mregparm=@var{num} -msseregparm @gol
521-mstackrealign @gol
522-momit-leaf-frame-pointer -mno-red-zone -mno-tls-direct-seg-refs @gol
523-mcmodel=@var{code-model} @gol
524-m32 -m64 -mlarge-data-threshold=@var{num}}
525
526@emph{IA-64 Options}
527@gccoptlist{-mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol
528-mvolatile-asm-stop -mregister-names -mno-sdata @gol
529-mconstant-gp -mauto-pic -minline-float-divide-min-latency @gol
530-minline-float-divide-max-throughput @gol
531-minline-int-divide-min-latency @gol
532-minline-int-divide-max-throughput @gol
533-minline-sqrt-min-latency -minline-sqrt-max-throughput @gol
534-mno-dwarf2-asm -mearly-stop-bits @gol
535-mfixed-range=@var{register-range} -mtls-size=@var{tls-size} @gol
536-mtune=@var{cpu-type} -mt -pthread -milp32 -mlp64 @gol
537-mno-sched-br-data-spec -msched-ar-data-spec -mno-sched-control-spec @gol
538-msched-br-in-data-spec -msched-ar-in-data-spec -msched-in-control-spec @gol
539-msched-ldc -mno-sched-control-ldc -mno-sched-spec-verbose @gol
540-mno-sched-prefer-non-data-spec-insns @gol
541-mno-sched-prefer-non-control-spec-insns @gol
542-mno-sched-count-spec-in-critical-path}
543
544@emph{M32R/D Options}
545@gccoptlist{-m32r2 -m32rx -m32r @gol
546-mdebug @gol
547-malign-loops -mno-align-loops @gol
548-missue-rate=@var{number} @gol
549-mbranch-cost=@var{number} @gol
550-mmodel=@var{code-size-model-type} @gol
551-msdata=@var{sdata-type} @gol
552-mno-flush-func -mflush-func=@var{name} @gol
553-mno-flush-trap -mflush-trap=@var{number} @gol
554-G @var{num}}
555
556@emph{M32C Options}
557@gccoptlist{-mcpu=@var{cpu} -msim -memregs=@var{number}}
558
559@emph{M680x0 Options}
560@gccoptlist{-m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol
561-m68060 -mcpu32 -m5200 -mcfv4e -m68881 -mbitfield @gol
562-mc68000 -mc68020 @gol
563-mnobitfield -mrtd -mshort -msoft-float -mpcrel @gol
564-malign-int -mstrict-align -msep-data -mno-sep-data @gol
565-mshared-library-id=n -mid-shared-library -mno-id-shared-library}
566
567@emph{M68hc1x Options}
568@gccoptlist{-m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 @gol
569-mauto-incdec -minmax -mlong-calls -mshort @gol
570-msoft-reg-count=@var{count}}
571
572@emph{MCore Options}
573@gccoptlist{-mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol
574-mno-relax-immediates -mwide-bitfields -mno-wide-bitfields @gol
575-m4byte-functions -mno-4byte-functions -mcallgraph-data @gol
576-mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim @gol
577-mlittle-endian -mbig-endian -m210 -m340 -mstack-increment}
578
579@emph{MIPS Options}
580@gccoptlist{-EL -EB -march=@var{arch} -mtune=@var{arch} @gol
581-mips1 -mips2 -mips3 -mips4 -mips32 -mips32r2 -mips64 @gol
582-mips16 -mno-mips16 -mabi=@var{abi} -mabicalls -mno-abicalls @gol
583-mshared -mno-shared -mxgot -mno-xgot -mgp32 -mgp64 @gol
584-mfp32 -mfp64 -mhard-float -msoft-float @gol
585-msingle-float -mdouble-float -mdsp -mpaired-single -mips3d @gol
586-mlong64 -mlong32 -msym32 -mno-sym32 @gol
587-G@var{num} -membedded-data -mno-embedded-data @gol
588-muninit-const-in-rodata -mno-uninit-const-in-rodata @gol
589-msplit-addresses -mno-split-addresses @gol
590-mexplicit-relocs -mno-explicit-relocs @gol
591-mcheck-zero-division -mno-check-zero-division @gol
592-mdivide-traps -mdivide-breaks @gol
593-mmemcpy -mno-memcpy -mlong-calls -mno-long-calls @gol
594-mmad -mno-mad -mfused-madd -mno-fused-madd -nocpp @gol
595-mfix-r4000 -mno-fix-r4000 -mfix-r4400 -mno-fix-r4400 @gol
596-mfix-vr4120 -mno-fix-vr4120 -mfix-vr4130 @gol
597-mfix-sb1 -mno-fix-sb1 @gol
598-mflush-func=@var{func} -mno-flush-func @gol
599-mbranch-likely -mno-branch-likely @gol
600-mfp-exceptions -mno-fp-exceptions @gol
601-mvr4130-align -mno-vr4130-align}
602
603@emph{MMIX Options}
604@gccoptlist{-mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol
605-mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol
606-melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol
607-mno-base-addresses -msingle-exit -mno-single-exit}
608
609@emph{MN10300 Options}
610@gccoptlist{-mmult-bug -mno-mult-bug @gol
611-mam33 -mno-am33 @gol
612-mam33-2 -mno-am33-2 @gol
613-mreturn-pointer-on-d0 @gol
614-mno-crt0 -mrelax}
615
616@emph{MT Options}
617@gccoptlist{-mno-crt0 -mbacc -msim @gol
618-march=@var{cpu-type} }
619
620@emph{PDP-11 Options}
621@gccoptlist{-mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol
622-mbcopy -mbcopy-builtin -mint32 -mno-int16 @gol
623-mint16 -mno-int32 -mfloat32 -mno-float64 @gol
624-mfloat64 -mno-float32 -mabshi -mno-abshi @gol
625-mbranch-expensive -mbranch-cheap @gol
626-msplit -mno-split -munix-asm -mdec-asm}
627
628@emph{PowerPC Options}
629See RS/6000 and PowerPC Options.
630
631@emph{RS/6000 and PowerPC Options}
632@gccoptlist{-mcpu=@var{cpu-type} @gol
633-mtune=@var{cpu-type} @gol
634-mpower -mno-power -mpower2 -mno-power2 @gol
635-mpowerpc -mpowerpc64 -mno-powerpc @gol
636-maltivec -mno-altivec @gol
637-mpowerpc-gpopt -mno-powerpc-gpopt @gol
638-mpowerpc-gfxopt -mno-powerpc-gfxopt @gol
639-mmfcrf -mno-mfcrf -mpopcntb -mno-popcntb -mfprnd -mno-fprnd @gol
640-mnew-mnemonics -mold-mnemonics @gol
641-mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc @gol
642-m64 -m32 -mxl-compat -mno-xl-compat -mpe @gol
643-malign-power -malign-natural @gol
644-msoft-float -mhard-float -mmultiple -mno-multiple @gol
645-mstring -mno-string -mupdate -mno-update @gol
646-mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol
647-mstrict-align -mno-strict-align -mrelocatable @gol
648-mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol
649-mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol
650-mdynamic-no-pic -maltivec -mswdiv @gol
651-mprioritize-restricted-insns=@var{priority} @gol
652-msched-costly-dep=@var{dependence_type} @gol
653-minsert-sched-nops=@var{scheme} @gol
654-mcall-sysv -mcall-netbsd @gol
655-maix-struct-return -msvr4-struct-return @gol
656-mabi=@var{abi-type} -msecure-plt -mbss-plt @gol
657-misel -mno-isel @gol
658-misel=yes -misel=no @gol
659-mspe -mno-spe @gol
660-mspe=yes -mspe=no @gol
661-mvrsave -mno-vrsave @gol
662-mmulhw -mno-mulhw @gol
663-mdlmzb -mno-dlmzb @gol
664-mfloat-gprs=yes -mfloat-gprs=no -mfloat-gprs=single -mfloat-gprs=double @gol
665-mprototype -mno-prototype @gol
666-msim -mmvme -mads -myellowknife -memb -msdata @gol
667-msdata=@var{opt} -mvxworks -mwindiss -G @var{num} -pthread}
668
669@emph{S/390 and zSeries Options}
670@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
671-mhard-float -msoft-float -mlong-double-64 -mlong-double-128 @gol
672-mbackchain -mno-backchain -mpacked-stack -mno-packed-stack @gol
673-msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol
674-m64 -m31 -mdebug -mno-debug -mesa -mzarch @gol
675-mtpf-trace -mno-tpf-trace -mfused-madd -mno-fused-madd @gol
676-mwarn-framesize -mwarn-dynamicstack -mstack-size -mstack-guard}
677
678@emph{Score Options}
679@gccoptlist{-meb -mel @gol
680-mnhwloop @gol
681-muls @gol
682-mmac @gol
683-mscore5 -mscore5u -mscore7 -mscore7d}
684
685@emph{SH Options}
686@gccoptlist{-m1 -m2 -m2e -m3 -m3e @gol
687-m4-nofpu -m4-single-only -m4-single -m4 @gol
688-m4a-nofpu -m4a-single-only -m4a-single -m4a -m4al @gol
689-m5-64media -m5-64media-nofpu @gol
690-m5-32media -m5-32media-nofpu @gol
691-m5-compact -m5-compact-nofpu @gol
692-mb -ml -mdalign -mrelax @gol
693-mbigtable -mfmovd -mhitachi -mrenesas -mno-renesas -mnomacsave @gol
694-mieee -misize -mpadstruct -mspace @gol
695-mprefergot -musermode -multcost=@var{number} -mdiv=@var{strategy} @gol
696-mdivsi3_libfunc=@var{name} @gol
697-madjust-unroll -mindexed-addressing -mgettrcost=@var{number} -mpt-fixed @gol
698 -minvalid-symbols}
699
700@emph{SPARC Options}
701@gccoptlist{-mcpu=@var{cpu-type} @gol
702-mtune=@var{cpu-type} @gol
703-mcmodel=@var{code-model} @gol
704-m32 -m64 -mapp-regs -mno-app-regs @gol
705-mfaster-structs -mno-faster-structs @gol
706-mfpu -mno-fpu -mhard-float -msoft-float @gol
707-mhard-quad-float -msoft-quad-float @gol
708-mimpure-text -mno-impure-text -mlittle-endian @gol
709-mstack-bias -mno-stack-bias @gol
710-munaligned-doubles -mno-unaligned-doubles @gol
711-mv8plus -mno-v8plus -mvis -mno-vis
712-threads -pthreads -pthread}
713
714@emph{System V Options}
715@gccoptlist{-Qy -Qn -YP,@var{paths} -Ym,@var{dir}}
716
717@emph{TMS320C3x/C4x Options}
718@gccoptlist{-mcpu=@var{cpu} -mbig -msmall -mregparm -mmemparm @gol
719-mfast-fix -mmpyi -mbk -mti -mdp-isr-reload @gol
720-mrpts=@var{count} -mrptb -mdb -mloop-unsigned @gol
721-mparallel-insns -mparallel-mpy -mpreserve-float}
722
723@emph{V850 Options}
724@gccoptlist{-mlong-calls -mno-long-calls -mep -mno-ep @gol
725-mprolog-function -mno-prolog-function -mspace @gol
726-mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol
727-mapp-regs -mno-app-regs @gol
728-mdisable-callt -mno-disable-callt @gol
729-mv850e1 @gol
730-mv850e @gol
731-mv850 -mbig-switch}
732
733@emph{VAX Options}
734@gccoptlist{-mg -mgnu -munix}
735
736@emph{x86-64 Options}
737See i386 and x86-64 Options.
738
739@emph{Xstormy16 Options}
740@gccoptlist{-msim}
741
742@emph{Xtensa Options}
743@gccoptlist{-mconst16 -mno-const16 @gol
744-mfused-madd -mno-fused-madd @gol
745-mtext-section-literals -mno-text-section-literals @gol
746-mtarget-align -mno-target-align @gol
747-mlongcalls -mno-longcalls}
748
749@emph{zSeries Options}
750See S/390 and zSeries Options.
751
752@item Code Generation Options
753@xref{Code Gen Options,,Options for Code Generation Conventions}.
754@gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol
755-ffixed-@var{reg} -fexceptions @gol
756-fnon-call-exceptions -funwind-tables @gol
757-fasynchronous-unwind-tables @gol
758-finhibit-size-directive -finstrument-functions @gol
759-fno-common -fno-ident @gol
760-fpcc-struct-return -fpic -fPIC -fpie -fPIE @gol
761-fno-jump-tables @gol
762-freg-struct-return -fshort-enums @gol
763-fshort-double -fshort-wchar @gol
764-fverbose-asm -fpack-struct[=@var{n}] -fstack-check @gol
765-fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
766-fargument-alias -fargument-noalias @gol
767-fargument-noalias-global -fargument-noalias-anything
768-fleading-underscore -ftls-model=@var{model} @gol
769-ftrapv -fwrapv -fbounds-check @gol
770-fvisibility}
771@end table
772
773@menu
774* Overall Options:: Controlling the kind of output:
775 an executable, object files, assembler files,
776 or preprocessed source.
777* C Dialect Options:: Controlling the variant of C language compiled.
778* C++ Dialect Options:: Variations on C++.
779* Language Independent Options:: Controlling how diagnostics should be
780 formatted.
781* Warning Options:: How picky should the compiler be?
782* Debugging Options:: Symbol tables, measurements, and debugging dumps.
783* Optimize Options:: How much optimization?
784* Preprocessor Options:: Controlling header files and macro definitions.
785 Also, getting dependency information for Make.
786* Assembler Options:: Passing options to the assembler.
787* Link Options:: Specifying libraries and so on.
788* Directory Options:: Where to find header files and libraries.
789 Where to find the compiler executable files.
790* Spec Files:: How to pass switches to sub-processes.
791* Target Options:: Running a cross-compiler, or an old version of GCC.
792@end menu
793
794@node Overall Options
795@section Options Controlling the Kind of Output
796
797Compilation can involve up to four stages: preprocessing, compilation
798proper, assembly and linking, always in that order. GCC is capable of
799preprocessing and compiling several files either into several
800assembler input files, or into one assembler input file; then each
801assembler input file produces an object file, and linking combines all
802the object files (those newly compiled, and those specified as input)
803into an executable file.
804
805@cindex file name suffix
806For any given input file, the file name suffix determines what kind of
807compilation is done:
808
809@table @gcctabopt
810@item @var{file}.c
811C source code which must be preprocessed.
812
813@item @var{file}.i
814C source code which should not be preprocessed.
815
816@item @var{file}.ii
817C++ source code which should not be preprocessed.
818
819@item @var{file}.h
820C, or C++ header file to be turned into a precompiled header.
821
822@item @var{file}.cc
823@itemx @var{file}.cp
824@itemx @var{file}.cxx
825@itemx @var{file}.cpp
826@itemx @var{file}.CPP
827@itemx @var{file}.c++
828@itemx @var{file}.C
829C++ source code which must be preprocessed. Note that in @samp{.cxx},
830the last two letters must both be literally @samp{x}. Likewise,
831@samp{.C} refers to a literal capital C@.
832
833@item @var{file}.hh
834@itemx @var{file}.H
835C++ header file to be turned into a precompiled header.
836
837@item @var{file}.f
838@itemx @var{file}.for
839@itemx @var{file}.FOR
840Fixed form Fortran source code which should not be preprocessed.
841
842@item @var{file}.F
843@itemx @var{file}.fpp
844@itemx @var{file}.FPP
845Fixed form Fortran source code which must be preprocessed (with the traditional
846preprocessor).
847
848@item @var{file}.f90
849@itemx @var{file}.f95
850Free form Fortran source code which should not be preprocessed.
851
852@item @var{file}.F90
853@itemx @var{file}.F95
854Free form Fortran source code which must be preprocessed (with the
855traditional preprocessor).
856
857@c FIXME: Descriptions of Java file types.
858@c @var{file}.java
859@c @var{file}.class
860@c @var{file}.zip
861@c @var{file}.jar
862
863@item @var{file}.ads
864Ada source code file which contains a library unit declaration (a
865declaration of a package, subprogram, or generic, or a generic
866instantiation), or a library unit renaming declaration (a package,
867generic, or subprogram renaming declaration). Such files are also
868called @dfn{specs}.
869
870@itemx @var{file}.adb
871Ada source code file containing a library unit body (a subprogram or
872package body). Such files are also called @dfn{bodies}.
873
874@c GCC also knows about some suffixes for languages not yet included:
875@c Pascal:
876@c @var{file}.p
877@c @var{file}.pas
878@c Ratfor:
879@c @var{file}.r
880
881@item @var{file}.s
882Assembler code.
883
884@item @var{file}.S
885Assembler code which must be preprocessed.
886
887@item @var{other}
888An object file to be fed straight into linking.
889Any file name with no recognized suffix is treated this way.
890@end table
891
892@opindex x
893You can specify the input language explicitly with the @option{-x} option:
894
895@table @gcctabopt
896@item -x @var{language}
897Specify explicitly the @var{language} for the following input files
898(rather than letting the compiler choose a default based on the file
899name suffix). This option applies to all following input files until
900the next @option{-x} option. Possible values for @var{language} are:
901@smallexample
902c c-header c-cpp-output
903c++ c++-header c++-cpp-output
904assembler assembler-with-cpp
905ada
906f95 f95-cpp-input
907java
908treelang
909@end smallexample
910
911@item -x none
912Turn off any specification of a language, so that subsequent files are
913handled according to their file name suffixes (as they are if @option{-x}
914has not been used at all).
915
916@item -pass-exit-codes
917@opindex pass-exit-codes
918Normally the @command{gcc} program will exit with the code of 1 if any
919phase of the compiler returns a non-success return code. If you specify
920@option{-pass-exit-codes}, the @command{gcc} program will instead return with
921numerically highest error produced by any phase that returned an error
922indication. The C, C++, and Fortran frontends return 4, if an internal
923compiler error is encountered.
924@end table
925
926If you only want some of the stages of compilation, you can use
927@option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
928one of the options @option{-c}, @option{-S}, or @option{-E} to say where
929@command{gcc} is to stop. Note that some combinations (for example,
930@samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
931
932@table @gcctabopt
933@item -c
934@opindex c
935Compile or assemble the source files, but do not link. The linking
936stage simply is not done. The ultimate output is in the form of an
937object file for each source file.
938
939By default, the object file name for a source file is made by replacing
940the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
941
942Unrecognized input files, not requiring compilation or assembly, are
943ignored.
944
945@item -S
946@opindex S
947Stop after the stage of compilation proper; do not assemble. The output
948is in the form of an assembler code file for each non-assembler input
949file specified.
950
951By default, the assembler file name for a source file is made by
952replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
953
954Input files that don't require compilation are ignored.
955
956@item -E
957@opindex E
958Stop after the preprocessing stage; do not run the compiler proper. The
959output is in the form of preprocessed source code, which is sent to the
960standard output.
961
962Input files which don't require preprocessing are ignored.
963
964@cindex output file option
965@item -o @var{file}
966@opindex o
967Place output in file @var{file}. This applies regardless to whatever
968sort of output is being produced, whether it be an executable file,
969an object file, an assembler file or preprocessed C code.
970
971If @option{-o} is not specified, the default is to put an executable
972file in @file{a.out}, the object file for
973@file{@var{source}.@var{suffix}} in @file{@var{source}.o}, its
974assembler file in @file{@var{source}.s}, a precompiled header file in
975@file{@var{source}.@var{suffix}.gch}, and all preprocessed C source on
976standard output.
977
978@item -v
979@opindex v
980Print (on standard error output) the commands executed to run the stages
981of compilation. Also print the version number of the compiler driver
982program and of the preprocessor and the compiler proper.
983
984@item -###
985@opindex ###
986Like @option{-v} except the commands are not executed and all command
987arguments are quoted. This is useful for shell scripts to capture the
988driver-generated command lines.
989
990@item -pipe
991@opindex pipe
992Use pipes rather than temporary files for communication between the
993various stages of compilation. This fails to work on some systems where
994the assembler is unable to read from a pipe; but the GNU assembler has
995no trouble.
996
997@item -combine
998@opindex combine
999If you are compiling multiple source files, this option tells the driver
1000to pass all the source files to the compiler at once (for those
1001languages for which the compiler can handle this). This will allow
1002intermodule analysis (IMA) to be performed by the compiler. Currently the only
1003language for which this is supported is C@. If you pass source files for
1004multiple languages to the driver, using this option, the driver will invoke
1005the compiler(s) that support IMA once each, passing each compiler all the
1006source files appropriate for it. For those languages that do not support
1007IMA this option will be ignored, and the compiler will be invoked once for
1008each source file in that language. If you use this option in conjunction
1009with @option{-save-temps}, the compiler will generate multiple
1010pre-processed files
1011(one for each source file), but only one (combined) @file{.o} or
1012@file{.s} file.
1013
1014@item --help
1015@opindex help
1016Print (on the standard output) a description of the command line options
1017understood by @command{gcc}. If the @option{-v} option is also specified
1018then @option{--help} will also be passed on to the various processes
1019invoked by @command{gcc}, so that they can display the command line options
1020they accept. If the @option{-Wextra} option is also specified then command
1021line options which have no documentation associated with them will also
1022be displayed.
1023
1024@item --target-help
1025@opindex target-help
1026Print (on the standard output) a description of target specific command
1027line options for each tool.
1028
1029@item --version
1030@opindex version
1031Display the version number and copyrights of the invoked GCC@.
1032
1033@include @value{srcdir}/../libiberty/at-file.texi
1034@end table
1035
1036@node Invoking G++
1037@section Compiling C++ Programs
1038
1039@cindex suffixes for C++ source
1040@cindex C++ source file suffixes
1041C++ source files conventionally use one of the suffixes @samp{.C},
1042@samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or
1043@samp{.cxx}; C++ header files often use @samp{.hh} or @samp{.H}; and
1044preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes
1045files with these names and compiles them as C++ programs even if you
1046call the compiler the same way as for compiling C programs (usually
1047with the name @command{gcc}).
1048
1049@findex g++
1050@findex c++
1051However, the use of @command{gcc} does not add the C++ library.
1052@command{g++} is a program that calls GCC and treats @samp{.c},
1053@samp{.h} and @samp{.i} files as C++ source files instead of C source
1054files unless @option{-x} is used, and automatically specifies linking
1055against the C++ library. This program is also useful when
1056precompiling a C header file with a @samp{.h} extension for use in C++
1057compilations. On many systems, @command{g++} is also installed with
1058the name @command{c++}.
1059
1060@cindex invoking @command{g++}
1061When you compile C++ programs, you may specify many of the same
1062command-line options that you use for compiling programs in any
1063language; or command-line options meaningful for C and related
1064languages; or options that are meaningful only for C++ programs.
1065@xref{C Dialect Options,,Options Controlling C Dialect}, for
1066explanations of options for languages related to C@.
1067@xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
1068explanations of options that are meaningful only for C++ programs.
1069
1070@node C Dialect Options
1071@section Options Controlling C Dialect
1072@cindex dialect options
1073@cindex language dialect options
1074@cindex options, dialect
1075
1076The following options control the dialect of C (or languages derived
1077from C, such as C++) that the compiler accepts:
1078
1079@table @gcctabopt
1080@cindex ANSI support
1081@cindex ISO support
1082@item -ansi
1083@opindex ansi
1084In C mode, support all ISO C90 programs. In C++ mode,
1085remove GNU extensions that conflict with ISO C++.
1086
1087This turns off certain features of GCC that are incompatible with ISO
1088C90 (when compiling C code), or of standard C++ (when compiling C++ code),
1089such as the @code{asm} and @code{typeof} keywords, and
1090predefined macros such as @code{unix} and @code{vax} that identify the
1091type of system you are using. It also enables the undesirable and
1092rarely used ISO trigraph feature. For the C compiler,
1093it disables recognition of C++ style @samp{//} comments as well as
1094the @code{inline} keyword.
1095
1096The alternate keywords @code{__asm__}, @code{__extension__},
1097@code{__inline__} and @code{__typeof__} continue to work despite
1098@option{-ansi}. You would not want to use them in an ISO C program, of
1099course, but it is useful to put them in header files that might be included
1100in compilations done with @option{-ansi}. Alternate predefined macros
1101such as @code{__unix__} and @code{__vax__} are also available, with or
1102without @option{-ansi}.
1103
1104The @option{-ansi} option does not cause non-ISO programs to be
1105rejected gratuitously. For that, @option{-pedantic} is required in
1106addition to @option{-ansi}. @xref{Warning Options}.
1107
1108The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
1109option is used. Some header files may notice this macro and refrain
1110from declaring certain functions or defining certain macros that the
1111ISO standard doesn't call for; this is to avoid interfering with any
1112programs that might use these names for other things.
1113
1114Functions which would normally be built in but do not have semantics
1115defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
1116functions with @option{-ansi} is used. @xref{Other Builtins,,Other
1117built-in functions provided by GCC}, for details of the functions
1118affected.
1119
1120@item -std=
1121@opindex std
1122Determine the language standard. This option is currently only
1123supported when compiling C or C++. A value for this option must be
1124provided; possible values are
1125
1126@table @samp
1127@item c89
1128@itemx iso9899:1990
1129ISO C90 (same as @option{-ansi}).
1130
1131@item iso9899:199409
1132ISO C90 as modified in amendment 1.
1133
1134@item c99
1135@itemx c9x
1136@itemx iso9899:1999
1137@itemx iso9899:199x
1138ISO C99. Note that this standard is not yet fully supported; see
1139@w{@uref{http://gcc.gnu.org/gcc-4.2/c99status.html}} for more information. The
1140names @samp{c9x} and @samp{iso9899:199x} are deprecated.
1141
1142@item gnu89
1143Default, ISO C90 plus GNU extensions (including some C99 features).
1144
1145@item gnu99
1146@itemx gnu9x
1147ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC,
1148this will become the default. The name @samp{gnu9x} is deprecated.
1149
1150@item c++98
1151The 1998 ISO C++ standard plus amendments.
1152
1153@item gnu++98
1154The same as @option{-std=c++98} plus GNU extensions. This is the
1155default for C++ code.
1156@end table
1157
1158Even when this option is not specified, you can still use some of the
1159features of newer standards in so far as they do not conflict with
1160previous C standards. For example, you may use @code{__restrict__} even
1161when @option{-std=c99} is not specified.
1162
1163The @option{-std} options specifying some version of ISO C have the same
1164effects as @option{-ansi}, except that features that were not in ISO C90
1165but are in the specified version (for example, @samp{//} comments and
1166the @code{inline} keyword in ISO C99) are not disabled.
1167
1168@xref{Standards,,Language Standards Supported by GCC}, for details of
1169these standard versions.
1170
1171@item -fgnu89-inline
1172@opindex fgnu89-inline
1173The option @option{-fgnu89-inline} tells GCC to use the traditional
1174GNU semantics for @code{inline} functions when in C99 mode.
1175@xref{Inline,,An Inline Function is As Fast As a Macro}. Using this
1176option is roughly equivalent to adding the @code{gnu_inline} function
1177attribute to all inline functions (@pxref{Function Attributes}).
1178
1179This option is accepted by GCC versions 4.1.3 and up. In GCC versions
1180prior to 4.3, C99 inline semantics are not supported, and thus this
1181option is effectively assumed to be present regardless of whether or not
1182it is specified; the only effect of specifying it explicitly is to
1183disable warnings about using inline functions in C99 mode. Likewise,
1184the option @option{-fno-gnu89-inline} is not supported in versions of
1185GCC before 4.3. It will be supported only in C99 or gnu99 mode, not in
1186C89 or gnu89 mode.
1187
1188The preprocesor macros @code{__GNUC_GNU_INLINE__} and
1189@code{__GNUC_STDC_INLINE__} may be used to check which semantics are
1190in effect for @code{inline} functions. @xref{Common Predefined
1191Macros,,,cpp,The C Preprocessor}.
1192
1193@item -aux-info @var{filename}
1194@opindex aux-info
1195Output to the given filename prototyped declarations for all functions
1196declared and/or defined in a translation unit, including those in header
1197files. This option is silently ignored in any language other than C@.
1198
1199Besides declarations, the file indicates, in comments, the origin of
1200each declaration (source file and line), whether the declaration was
1201implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
1202@samp{O} for old, respectively, in the first character after the line
1203number and the colon), and whether it came from a declaration or a
1204definition (@samp{C} or @samp{F}, respectively, in the following
1205character). In the case of function definitions, a K&R-style list of
1206arguments followed by their declarations is also provided, inside
1207comments, after the declaration.
1208
1209@item -fno-asm
1210@opindex fno-asm
1211Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1212keyword, so that code can use these words as identifiers. You can use
1213the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
1214instead. @option{-ansi} implies @option{-fno-asm}.
1215
1216In C++, this switch only affects the @code{typeof} keyword, since
1217@code{asm} and @code{inline} are standard keywords. You may want to
1218use the @option{-fno-gnu-keywords} flag instead, which has the same
1219effect. In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
1220switch only affects the @code{asm} and @code{typeof} keywords, since
1221@code{inline} is a standard keyword in ISO C99.
1222
1223@item -fno-builtin
1224@itemx -fno-builtin-@var{function}
1225@opindex fno-builtin
1226@cindex built-in functions
1227Don't recognize built-in functions that do not begin with
1228@samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in
1229functions provided by GCC}, for details of the functions affected,
1230including those which are not built-in functions when @option{-ansi} or
1231@option{-std} options for strict ISO C conformance are used because they
1232do not have an ISO standard meaning.
1233
1234GCC normally generates special code to handle certain built-in functions
1235more efficiently; for instance, calls to @code{alloca} may become single
1236instructions that adjust the stack directly, and calls to @code{memcpy}
1237may become inline copy loops. The resulting code is often both smaller
1238and faster, but since the function calls no longer appear as such, you
1239cannot set a breakpoint on those calls, nor can you change the behavior
1240of the functions by linking with a different library. In addition,
1241when a function is recognized as a built-in function, GCC may use
1242information about that function to warn about problems with calls to
1243that function, or to generate more efficient code, even if the
1244resulting code still contains calls to that function. For example,
1245warnings are given with @option{-Wformat} for bad calls to
1246@code{printf}, when @code{printf} is built in, and @code{strlen} is
1247known not to modify global memory.
1248
1249With the @option{-fno-builtin-@var{function}} option
1250only the built-in function @var{function} is
1251disabled. @var{function} must not begin with @samp{__builtin_}. If a
1252function is named this is not built-in in this version of GCC, this
1253option is ignored. There is no corresponding
1254@option{-fbuiltin-@var{function}} option; if you wish to enable
1255built-in functions selectively when using @option{-fno-builtin} or
1256@option{-ffreestanding}, you may define macros such as:
1257
1258@smallexample
1259#define abs(n) __builtin_abs ((n))
1260#define strcpy(d, s) __builtin_strcpy ((d), (s))
1261@end smallexample
1262
1263@item -fhosted
1264@opindex fhosted
1265@cindex hosted environment
1266
1267Assert that compilation takes place in a hosted environment. This implies
1268@option{-fbuiltin}. A hosted environment is one in which the
1269entire standard library is available, and in which @code{main} has a return
1270type of @code{int}. Examples are nearly everything except a kernel.
1271This is equivalent to @option{-fno-freestanding}.
1272
1273@item -ffreestanding
1274@opindex ffreestanding
1275@cindex hosted environment
1276
1277Assert that compilation takes place in a freestanding environment. This
1278implies @option{-fno-builtin}. A freestanding environment
1279is one in which the standard library may not exist, and program startup may
1280not necessarily be at @code{main}. The most obvious example is an OS kernel.
1281This is equivalent to @option{-fno-hosted}.
1282
1283@xref{Standards,,Language Standards Supported by GCC}, for details of
1284freestanding and hosted environments.
1285
1286@item -fopenmp
1287@opindex fopenmp
1288@cindex openmp parallel
1289Enable handling of OpenMP directives @code{#pragma omp} in C/C++ and
1290@code{!$omp} in Fortran. When @option{-fopenmp} is specified, the
1291compiler generates parallel code according to the OpenMP Application
1292Program Interface v2.5 @w{@uref{http://www.openmp.org/}}.
1293
1294@item -fms-extensions
1295@opindex fms-extensions
1296Accept some non-standard constructs used in Microsoft header files.
1297
1298Some cases of unnamed fields in structures and unions are only
1299accepted with this option. @xref{Unnamed Fields,,Unnamed struct/union
1300fields within structs/unions}, for details.
1301
1302@item -trigraphs
1303@opindex trigraphs
1304Support ISO C trigraphs. The @option{-ansi} option (and @option{-std}
1305options for strict ISO C conformance) implies @option{-trigraphs}.
1306
1307@item -no-integrated-cpp
1308@opindex no-integrated-cpp
1309Performs a compilation in two passes: preprocessing and compiling. This
1310option allows a user supplied "cc1", "cc1plus", or "cc1obj" via the
1311@option{-B} option. The user supplied compilation step can then add in
1312an additional preprocessing step after normal preprocessing but before
1313compiling. The default is to use the integrated cpp (internal cpp)
1314
1315The semantics of this option will change if "cc1", "cc1plus", and
1316"cc1obj" are merged.
1317
1318@cindex traditional C language
1319@cindex C language, traditional
1320@item -traditional
1321@itemx -traditional-cpp
1322@opindex traditional-cpp
1323@opindex traditional
1324Formerly, these options caused GCC to attempt to emulate a pre-standard
1325C compiler. They are now only supported with the @option{-E} switch.
1326The preprocessor continues to support a pre-standard mode. See the GNU
1327CPP manual for details.
1328
1329@item -fcond-mismatch
1330@opindex fcond-mismatch
1331Allow conditional expressions with mismatched types in the second and
1332third arguments. The value of such an expression is void. This option
1333is not supported for C++.
1334
1335@item -funsigned-char
1336@opindex funsigned-char
1337Let the type @code{char} be unsigned, like @code{unsigned char}.
1338
1339Each kind of machine has a default for what @code{char} should
1340be. It is either like @code{unsigned char} by default or like
1341@code{signed char} by default.
1342
1343Ideally, a portable program should always use @code{signed char} or
1344@code{unsigned char} when it depends on the signedness of an object.
1345But many programs have been written to use plain @code{char} and
1346expect it to be signed, or expect it to be unsigned, depending on the
1347machines they were written for. This option, and its inverse, let you
1348make such a program work with the opposite default.
1349
1350The type @code{char} is always a distinct type from each of
1351@code{signed char} or @code{unsigned char}, even though its behavior
1352is always just like one of those two.
1353
1354@item -fsigned-char
1355@opindex fsigned-char
1356Let the type @code{char} be signed, like @code{signed char}.
1357
1358Note that this is equivalent to @option{-fno-unsigned-char}, which is
1359the negative form of @option{-funsigned-char}. Likewise, the option
1360@option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
1361
1362@item -fsigned-bitfields
1363@itemx -funsigned-bitfields
1364@itemx -fno-signed-bitfields
1365@itemx -fno-unsigned-bitfields
1366@opindex fsigned-bitfields
1367@opindex funsigned-bitfields
1368@opindex fno-signed-bitfields
1369@opindex fno-unsigned-bitfields
1370These options control whether a bit-field is signed or unsigned, when the
1371declaration does not use either @code{signed} or @code{unsigned}. By
1372default, such a bit-field is signed, because this is consistent: the
1373basic integer types such as @code{int} are signed types.
1374@end table
1375
1376@node C++ Dialect Options
1377@section Options Controlling C++ Dialect
1378
1379@cindex compiler options, C++
1380@cindex C++ options, command line
1381@cindex options, C++
1382This section describes the command-line options that are only meaningful
1383for C++ programs; but you can also use most of the GNU compiler options
1384regardless of what language your program is in. For example, you
1385might compile a file @code{firstClass.C} like this:
1386
1387@smallexample
1388g++ -g -frepo -O -c firstClass.C
1389@end smallexample
1390
1391@noindent
1392In this example, only @option{-frepo} is an option meant
1393only for C++ programs; you can use the other options with any
1394language supported by GCC@.
1395
1396Here is a list of options that are @emph{only} for compiling C++ programs:
1397
1398@table @gcctabopt
1399
1400@item -fabi-version=@var{n}
1401@opindex fabi-version
1402Use version @var{n} of the C++ ABI@. Version 2 is the version of the
1403C++ ABI that first appeared in G++ 3.4. Version 1 is the version of
1404the C++ ABI that first appeared in G++ 3.2. Version 0 will always be
1405the version that conforms most closely to the C++ ABI specification.
1406Therefore, the ABI obtained using version 0 will change as ABI bugs
1407are fixed.
1408
1409The default is version 2.
1410
1411@item -fno-access-control
1412@opindex fno-access-control
1413Turn off all access checking. This switch is mainly useful for working
1414around bugs in the access control code.
1415
1416@item -fcheck-new
1417@opindex fcheck-new
1418Check that the pointer returned by @code{operator new} is non-null
1419before attempting to modify the storage allocated. This check is
1420normally unnecessary because the C++ standard specifies that
1421@code{operator new} will only return @code{0} if it is declared
1422@samp{throw()}, in which case the compiler will always check the
1423return value even without this option. In all other cases, when
1424@code{operator new} has a non-empty exception specification, memory
1425exhaustion is signalled by throwing @code{std::bad_alloc}. See also
1426@samp{new (nothrow)}.
1427
1428@item -fconserve-space
1429@opindex fconserve-space
1430Put uninitialized or runtime-initialized global variables into the
1431common segment, as C does. This saves space in the executable at the
1432cost of not diagnosing duplicate definitions. If you compile with this
1433flag and your program mysteriously crashes after @code{main()} has
1434completed, you may have an object that is being destroyed twice because
1435two definitions were merged.
1436
1437This option is no longer useful on most targets, now that support has
1438been added for putting variables into BSS without making them common.
1439
1440@item -ffriend-injection
1441@opindex ffriend-injection
1442Inject friend functions into the enclosing namespace, so that they are
1443visible outside the scope of the class in which they are declared.
1444Friend functions were documented to work this way in the old Annotated
1445C++ Reference Manual, and versions of G++ before 4.1 always worked
1446that way. However, in ISO C++ a friend function which is not declared
1447in an enclosing scope can only be found using argument dependent
1448lookup. This option causes friends to be injected as they were in
1449earlier releases.
1450
1451This option is for compatibility, and may be removed in a future
1452release of G++.
1453
1454@item -fno-elide-constructors
1455@opindex fno-elide-constructors
1456The C++ standard allows an implementation to omit creating a temporary
1457which is only used to initialize another object of the same type.
1458Specifying this option disables that optimization, and forces G++ to
1459call the copy constructor in all cases.
1460
1461@item -fno-enforce-eh-specs
1462@opindex fno-enforce-eh-specs
1463Don't generate code to check for violation of exception specifications
1464at runtime. This option violates the C++ standard, but may be useful
1465for reducing code size in production builds, much like defining
1466@samp{NDEBUG}. This does not give user code permission to throw
1467exceptions in violation of the exception specifications; the compiler
1468will still optimize based on the specifications, so throwing an
1469unexpected exception will result in undefined behavior.
1470
1471@item -ffor-scope
1472@itemx -fno-for-scope
1473@opindex ffor-scope
1474@opindex fno-for-scope
1475If @option{-ffor-scope} is specified, the scope of variables declared in
1476a @i{for-init-statement} is limited to the @samp{for} loop itself,
1477as specified by the C++ standard.
1478If @option{-fno-for-scope} is specified, the scope of variables declared in
1479a @i{for-init-statement} extends to the end of the enclosing scope,
1480as was the case in old versions of G++, and other (traditional)
1481implementations of C++.
1482
1483The default if neither flag is given to follow the standard,
1484but to allow and give a warning for old-style code that would
1485otherwise be invalid, or have different behavior.
1486
1487@item -fno-gnu-keywords
1488@opindex fno-gnu-keywords
1489Do not recognize @code{typeof} as a keyword, so that code can use this
1490word as an identifier. You can use the keyword @code{__typeof__} instead.
1491@option{-ansi} implies @option{-fno-gnu-keywords}.
1492
1493@item -fno-implicit-templates
1494@opindex fno-implicit-templates
1495Never emit code for non-inline templates which are instantiated
1496implicitly (i.e.@: by use); only emit code for explicit instantiations.
1497@xref{Template Instantiation}, for more information.
1498
1499@item -fno-implicit-inline-templates
1500@opindex fno-implicit-inline-templates
1501Don't emit code for implicit instantiations of inline templates, either.
1502The default is to handle inlines differently so that compiles with and
1503without optimization will need the same set of explicit instantiations.
1504
1505@item -fno-implement-inlines
1506@opindex fno-implement-inlines
1507To save space, do not emit out-of-line copies of inline functions
1508controlled by @samp{#pragma implementation}. This will cause linker
1509errors if these functions are not inlined everywhere they are called.
1510
1511@item -fms-extensions
1512@opindex fms-extensions
1513Disable pedantic warnings about constructs used in MFC, such as implicit
1514int and getting a pointer to member function via non-standard syntax.
1515
1516@item -fno-nonansi-builtins
1517@opindex fno-nonansi-builtins
1518Disable built-in declarations of functions that are not mandated by
1519ANSI/ISO C@. These include @code{ffs}, @code{alloca}, @code{_exit},
1520@code{index}, @code{bzero}, @code{conjf}, and other related functions.
1521
1522@item -fno-operator-names
1523@opindex fno-operator-names
1524Do not treat the operator name keywords @code{and}, @code{bitand},
1525@code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1526synonyms as keywords.
1527
1528@item -fno-optional-diags
1529@opindex fno-optional-diags
1530Disable diagnostics that the standard says a compiler does not need to
1531issue. Currently, the only such diagnostic issued by G++ is the one for
1532a name having multiple meanings within a class.
1533
1534@item -fpermissive
1535@opindex fpermissive
1536Downgrade some diagnostics about nonconformant code from errors to
1537warnings. Thus, using @option{-fpermissive} will allow some
1538nonconforming code to compile.
1539
1540@item -frepo
1541@opindex frepo
1542Enable automatic template instantiation at link time. This option also
1543implies @option{-fno-implicit-templates}. @xref{Template
1544Instantiation}, for more information.
1545
1546@item -fno-rtti
1547@opindex fno-rtti
1548Disable generation of information about every class with virtual
1549functions for use by the C++ runtime type identification features
1550(@samp{dynamic_cast} and @samp{typeid}). If you don't use those parts
1551of the language, you can save some space by using this flag. Note that
1552exception handling uses the same information, but it will generate it as
1553needed. The @samp{dynamic_cast} operator can still be used for casts that
1554do not require runtime type information, i.e. casts to @code{void *} or to
1555unambiguous base classes.
1556
1557@item -fstats
1558@opindex fstats
1559Emit statistics about front-end processing at the end of the compilation.
1560This information is generally only useful to the G++ development team.
1561
1562@item -ftemplate-depth-@var{n}
1563@opindex ftemplate-depth
1564Set the maximum instantiation depth for template classes to @var{n}.
1565A limit on the template instantiation depth is needed to detect
1566endless recursions during template class instantiation. ANSI/ISO C++
1567conforming programs must not rely on a maximum depth greater than 17.
1568
1569@item -fno-threadsafe-statics
1570@opindex fno-threadsafe-statics
1571Do not emit the extra code to use the routines specified in the C++
1572ABI for thread-safe initialization of local statics. You can use this
1573option to reduce code size slightly in code that doesn't need to be
1574thread-safe.
1575
1576@item -fuse-cxa-atexit
1577@opindex fuse-cxa-atexit
1578Register destructors for objects with static storage duration with the
1579@code{__cxa_atexit} function rather than the @code{atexit} function.
1580This option is required for fully standards-compliant handling of static
1581destructors, but will only work if your C library supports
1582@code{__cxa_atexit}.
1583
1584@item -fno-use-cxa-get-exception-ptr
1585@opindex fno-use-cxa-get-exception-ptr
1586Don't use the @code{__cxa_get_exception_ptr} runtime routine. This
1587will cause @code{std::uncaught_exception} to be incorrect, but is necessary
1588if the runtime routine is not available.
1589
1590@item -fvisibility-inlines-hidden
1591@opindex fvisibility-inlines-hidden
1592This switch declares that the user does not attempt to compare
1593pointers to inline methods where the addresses of the two functions
1594were taken in different shared objects.
1595
1596The effect of this is that GCC may, effectively, mark inline methods with
1597@code{__attribute__ ((visibility ("hidden")))} so that they do not
1598appear in the export table of a DSO and do not require a PLT indirection
1599when used within the DSO@. Enabling this option can have a dramatic effect
1600on load and link times of a DSO as it massively reduces the size of the
1601dynamic export table when the library makes heavy use of templates.
1602
1603The behaviour of this switch is not quite the same as marking the
1604methods as hidden directly, because it does not affect static variables
1605local to the function or cause the compiler to deduce that
1606the function is defined in only one shared object.
1607
1608You may mark a method as having a visibility explicitly to negate the
1609effect of the switch for that method. For example, if you do want to
1610compare pointers to a particular inline method, you might mark it as
1611having default visibility. Marking the enclosing class with explicit
1612visibility will have no effect.
1613
1614Explicitly instantiated inline methods are unaffected by this option
1615as their linkage might otherwise cross a shared library boundary.
1616@xref{Template Instantiation}.
1617
1618@item -fno-weak
1619@opindex fno-weak
1620Do not use weak symbol support, even if it is provided by the linker.
1621By default, G++ will use weak symbols if they are available. This
1622option exists only for testing, and should not be used by end-users;
1623it will result in inferior code and has no benefits. This option may
1624be removed in a future release of G++.
1625
1626@item -nostdinc++
1627@opindex nostdinc++
1628Do not search for header files in the standard directories specific to
1629C++, but do still search the other standard directories. (This option
1630is used when building the C++ library.)
1631@end table
1632
1633In addition, these optimization, warning, and code generation options
1634have meanings only for C++ programs:
1635
1636@table @gcctabopt
1637@item -fno-default-inline
1638@opindex fno-default-inline
1639Do not assume @samp{inline} for functions defined inside a class scope.
1640@xref{Optimize Options,,Options That Control Optimization}. Note that these
1641functions will have linkage like inline functions; they just won't be
1642inlined by default.
1643
1644@item -Wabi @r{(C++ only)}
1645@opindex Wabi
1646Warn when G++ generates code that is probably not compatible with the
1647vendor-neutral C++ ABI@. Although an effort has been made to warn about
1648all such cases, there are probably some cases that are not warned about,
1649even though G++ is generating incompatible code. There may also be
1650cases where warnings are emitted even though the code that is generated
1651will be compatible.
1652
1653You should rewrite your code to avoid these warnings if you are
1654concerned about the fact that code generated by G++ may not be binary
1655compatible with code generated by other compilers.
1656
1657The known incompatibilities at this point include:
1658
1659@itemize @bullet
1660
1661@item
1662Incorrect handling of tail-padding for bit-fields. G++ may attempt to
1663pack data into the same byte as a base class. For example:
1664
1665@smallexample
1666struct A @{ virtual void f(); int f1 : 1; @};
1667struct B : public A @{ int f2 : 1; @};
1668@end smallexample
1669
1670@noindent
1671In this case, G++ will place @code{B::f2} into the same byte
1672as@code{A::f1}; other compilers will not. You can avoid this problem
1673by explicitly padding @code{A} so that its size is a multiple of the
1674byte size on your platform; that will cause G++ and other compilers to
1675layout @code{B} identically.
1676
1677@item
1678Incorrect handling of tail-padding for virtual bases. G++ does not use
1679tail padding when laying out virtual bases. For example:
1680
1681@smallexample
1682struct A @{ virtual void f(); char c1; @};
1683struct B @{ B(); char c2; @};
1684struct C : public A, public virtual B @{@};
1685@end smallexample
1686
1687@noindent
1688In this case, G++ will not place @code{B} into the tail-padding for
1689@code{A}; other compilers will. You can avoid this problem by
1690explicitly padding @code{A} so that its size is a multiple of its
1691alignment (ignoring virtual base classes); that will cause G++ and other
1692compilers to layout @code{C} identically.
1693
1694@item
1695Incorrect handling of bit-fields with declared widths greater than that
1696of their underlying types, when the bit-fields appear in a union. For
1697example:
1698
1699@smallexample
1700union U @{ int i : 4096; @};
1701@end smallexample
1702
1703@noindent
1704Assuming that an @code{int} does not have 4096 bits, G++ will make the
1705union too small by the number of bits in an @code{int}.
1706
1707@item
1708Empty classes can be placed at incorrect offsets. For example:
1709
1710@smallexample
1711struct A @{@};
1712
1713struct B @{
1714 A a;
1715 virtual void f ();
1716@};
1717
1718struct C : public B, public A @{@};
1719@end smallexample
1720
1721@noindent
1722G++ will place the @code{A} base class of @code{C} at a nonzero offset;
1723it should be placed at offset zero. G++ mistakenly believes that the
1724@code{A} data member of @code{B} is already at offset zero.
1725
1726@item
1727Names of template functions whose types involve @code{typename} or
1728template template parameters can be mangled incorrectly.
1729
1730@smallexample
1731template <typename Q>
1732void f(typename Q::X) @{@}
1733
1734template <template <typename> class Q>
1735void f(typename Q<int>::X) @{@}
1736@end smallexample
1737
1738@noindent
1739Instantiations of these templates may be mangled incorrectly.
1740
1741@end itemize
1742
1743@item -Wctor-dtor-privacy @r{(C++ only)}
1744@opindex Wctor-dtor-privacy
1745Warn when a class seems unusable because all the constructors or
1746destructors in that class are private, and it has neither friends nor
1747public static member functions.
1748
1749@item -Wnon-virtual-dtor @r{(C++ only)}
1750@opindex Wnon-virtual-dtor
1751Warn when a class appears to be polymorphic, thereby requiring a virtual
1752destructor, yet it declares a non-virtual one. This warning is also
1753enabled if -Weffc++ is specified.
1754
1755@item -Wreorder @r{(C++ only)}
1756@opindex Wreorder
1757@cindex reordering, warning
1758@cindex warning for reordering of member initializers
1759Warn when the order of member initializers given in the code does not
1760match the order in which they must be executed. For instance:
1761
1762@smallexample
1763struct A @{
1764 int i;
1765 int j;
1766 A(): j (0), i (1) @{ @}
1767@};
1768@end smallexample
1769
1770The compiler will rearrange the member initializers for @samp{i}
1771and @samp{j} to match the declaration order of the members, emitting
1772a warning to that effect. This warning is enabled by @option{-Wall}.
1773@end table
1774
1775The following @option{-W@dots{}} options are not affected by @option{-Wall}.
1776
1777@table @gcctabopt
1778@item -Weffc++ @r{(C++ only)}
1779@opindex Weffc++
1780Warn about violations of the following style guidelines from Scott Meyers'
1781@cite{Effective C++} book:
1782
1783@itemize @bullet
1784@item
1785Item 11: Define a copy constructor and an assignment operator for classes
1786with dynamically allocated memory.
1787
1788@item
1789Item 12: Prefer initialization to assignment in constructors.
1790
1791@item
1792Item 14: Make destructors virtual in base classes.
1793
1794@item
1795Item 15: Have @code{operator=} return a reference to @code{*this}.
1796
1797@item
1798Item 23: Don't try to return a reference when you must return an object.
1799
1800@end itemize
1801
1802Also warn about violations of the following style guidelines from
1803Scott Meyers' @cite{More Effective C++} book:
1804
1805@itemize @bullet
1806@item
1807Item 6: Distinguish between prefix and postfix forms of increment and
1808decrement operators.
1809
1810@item
1811Item 7: Never overload @code{&&}, @code{||}, or @code{,}.
1812
1813@end itemize
1814
1815When selecting this option, be aware that the standard library
1816headers do not obey all of these guidelines; use @samp{grep -v}
1817to filter out those warnings.
1818
1819@item -Wno-deprecated @r{(C++ only)}
1820@opindex Wno-deprecated
1821Do not warn about usage of deprecated features. @xref{Deprecated Features}.
1822
1823@item -Wstrict-null-sentinel @r{(C++ only)}
1824@opindex Wstrict-null-sentinel
1825Warn also about the use of an uncasted @code{NULL} as sentinel. When
1826compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
1827to @code{__null}. Although it is a null pointer constant not a null pointer,
1828it is guaranteed to of the same size as a pointer. But this use is
1829not portable across different compilers.
1830
1831@item -Wno-non-template-friend @r{(C++ only)}
1832@opindex Wno-non-template-friend
1833Disable warnings when non-templatized friend functions are declared
1834within a template. Since the advent of explicit template specification
1835support in G++, if the name of the friend is an unqualified-id (i.e.,
1836@samp{friend foo(int)}), the C++ language specification demands that the
1837friend declare or define an ordinary, nontemplate function. (Section
183814.5.3). Before G++ implemented explicit specification, unqualified-ids
1839could be interpreted as a particular specialization of a templatized
1840function. Because this non-conforming behavior is no longer the default
1841behavior for G++, @option{-Wnon-template-friend} allows the compiler to
1842check existing code for potential trouble spots and is on by default.
1843This new compiler behavior can be turned off with
1844@option{-Wno-non-template-friend} which keeps the conformant compiler code
1845but disables the helpful warning.
1846
1847@item -Wold-style-cast @r{(C++ only)}
1848@opindex Wold-style-cast
1849Warn if an old-style (C-style) cast to a non-void type is used within
1850a C++ program. The new-style casts (@samp{dynamic_cast},
1851@samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are
1852less vulnerable to unintended effects and much easier to search for.
1853
1854@item -Woverloaded-virtual @r{(C++ only)}
1855@opindex Woverloaded-virtual
1856@cindex overloaded virtual fn, warning
1857@cindex warning for overloaded virtual fn
1858Warn when a function declaration hides virtual functions from a
1859base class. For example, in:
1860
1861@smallexample
1862struct A @{
1863 virtual void f();
1864@};
1865
1866struct B: public A @{
1867 void f(int);
1868@};
1869@end smallexample
1870
1871the @code{A} class version of @code{f} is hidden in @code{B}, and code
1872like:
1873
1874@smallexample
1875B* b;
1876b->f();
1877@end smallexample
1878
1879will fail to compile.
1880
1881@item -Wno-pmf-conversions @r{(C++ only)}
1882@opindex Wno-pmf-conversions
1883Disable the diagnostic for converting a bound pointer to member function
1884to a plain pointer.
1885
1886@item -Wsign-promo @r{(C++ only)}
1887@opindex Wsign-promo
1888Warn when overload resolution chooses a promotion from unsigned or
1889enumerated type to a signed type, over a conversion to an unsigned type of
1890the same size. Previous versions of G++ would try to preserve
1891unsignedness, but the standard mandates the current behavior.
1892
1893@smallexample
1894struct A @{
1895 operator int ();
1896 A& operator = (int);
1897@};
1898
1899main ()
1900@{
1901 A a,b;
1902 a = b;
1903@}
1904@end smallexample
1905
1906In this example, G++ will synthesize a default @samp{A& operator =
1907(const A&);}, while cfront will use the user-defined @samp{operator =}.
1908@end table
1909
1910@node Language Independent Options
1911@section Options to Control Diagnostic Messages Formatting
1912@cindex options to control diagnostics formatting
1913@cindex diagnostic messages
1914@cindex message formatting
1915
1916Traditionally, diagnostic messages have been formatted irrespective of
1917the output device's aspect (e.g.@: its width, @dots{}). The options described
1918below can be used to control the diagnostic messages formatting
1919algorithm, e.g.@: how many characters per line, how often source location
1920information should be reported. Right now, only the C++ front end can
1921honor these options. However it is expected, in the near future, that
1922the remaining front ends would be able to digest them correctly.
1923
1924@table @gcctabopt
1925@item -fmessage-length=@var{n}
1926@opindex fmessage-length
1927Try to format error messages so that they fit on lines of about @var{n}
1928characters. The default is 72 characters for @command{g++} and 0 for the rest of
1929the front ends supported by GCC@. If @var{n} is zero, then no
1930line-wrapping will be done; each error message will appear on a single
1931line.
1932
1933@opindex fdiagnostics-show-location
1934@item -fdiagnostics-show-location=once
1935Only meaningful in line-wrapping mode. Instructs the diagnostic messages
1936reporter to emit @emph{once} source location information; that is, in
1937case the message is too long to fit on a single physical line and has to
1938be wrapped, the source location won't be emitted (as prefix) again,
1939over and over, in subsequent continuation lines. This is the default
1940behavior.
1941
1942@item -fdiagnostics-show-location=every-line
1943Only meaningful in line-wrapping mode. Instructs the diagnostic
1944messages reporter to emit the same source location information (as
1945prefix) for physical lines that result from the process of breaking
1946a message which is too long to fit on a single line.
1947
1948@item -fdiagnostics-show-option
1949@opindex fdiagnostics-show-option
1950This option instructs the diagnostic machinery to add text to each
1951diagnostic emitted, which indicates which command line option directly
1952controls that diagnostic, when such an option is known to the
1953diagnostic machinery.
1954
1955@end table
1956
1957@node Warning Options
1958@section Options to Request or Suppress Warnings
1959@cindex options to control warnings
1960@cindex warning messages
1961@cindex messages, warning
1962@cindex suppressing warnings
1963
1964Warnings are diagnostic messages that report constructions which
1965are not inherently erroneous but which are risky or suggest there
1966may have been an error.
1967
1968You can request many specific warnings with options beginning @samp{-W},
1969for example @option{-Wimplicit} to request warnings on implicit
1970declarations. Each of these specific warning options also has a
1971negative form beginning @samp{-Wno-} to turn off warnings;
1972for example, @option{-Wno-implicit}. This manual lists only one of the
1973two forms, whichever is not the default.
1974
1975The following options control the amount and kinds of warnings produced
1976by GCC; for further, language-specific options also refer to
1977@ref{C++ Dialect Options}.
1978
1979@table @gcctabopt
1980@cindex syntax checking
1981@item -fsyntax-only
1982@opindex fsyntax-only
1983Check the code for syntax errors, but don't do anything beyond that.
1984
1985@item -pedantic
1986@opindex pedantic
1987Issue all the warnings demanded by strict ISO C and ISO C++;
1988reject all programs that use forbidden extensions, and some other
1989programs that do not follow ISO C and ISO C++. For ISO C, follows the
1990version of the ISO C standard specified by any @option{-std} option used.
1991
1992Valid ISO C and ISO C++ programs should compile properly with or without
1993this option (though a rare few will require @option{-ansi} or a
1994@option{-std} option specifying the required version of ISO C)@. However,
1995without this option, certain GNU extensions and traditional C and C++
1996features are supported as well. With this option, they are rejected.
1997
1998@option{-pedantic} does not cause warning messages for use of the
1999alternate keywords whose names begin and end with @samp{__}. Pedantic
2000warnings are also disabled in the expression that follows
2001@code{__extension__}. However, only system header files should use
2002these escape routes; application programs should avoid them.
2003@xref{Alternate Keywords}.
2004
2005Some users try to use @option{-pedantic} to check programs for strict ISO
2006C conformance. They soon find that it does not do quite what they want:
2007it finds some non-ISO practices, but not all---only those for which
2008ISO C @emph{requires} a diagnostic, and some others for which
2009diagnostics have been added.
2010
2011A feature to report any failure to conform to ISO C might be useful in
2012some instances, but would require considerable additional work and would
2013be quite different from @option{-pedantic}. We don't have plans to
2014support such a feature in the near future.
2015
2016Where the standard specified with @option{-std} represents a GNU
2017extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
2018corresponding @dfn{base standard}, the version of ISO C on which the GNU
2019extended dialect is based. Warnings from @option{-pedantic} are given
2020where they are required by the base standard. (It would not make sense
2021for such warnings to be given only for features not in the specified GNU
2022C dialect, since by definition the GNU dialects of C include all
2023features the compiler supports with the given option, and there would be
2024nothing to warn about.)
2025
2026@item -pedantic-errors
2027@opindex pedantic-errors
2028Like @option{-pedantic}, except that errors are produced rather than
2029warnings.
2030
2031@item -w
2032@opindex w
2033Inhibit all warning messages.
2034
2035@item -Wno-import
2036@opindex Wno-import
2037Inhibit warning messages about the use of @samp{#import}.
2038
2039@item -Wchar-subscripts
2040@opindex Wchar-subscripts
2041Warn if an array subscript has type @code{char}. This is a common cause
2042of error, as programmers often forget that this type is signed on some
2043machines.
2044This warning is enabled by @option{-Wall}.
2045
2046@item -Wcomment
2047@opindex Wcomment
2048Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
2049comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
2050This warning is enabled by @option{-Wall}.
2051
2052@item -Wfatal-errors
2053@opindex Wfatal-errors
2054This option causes the compiler to abort compilation on the first error
2055occurred rather than trying to keep going and printing further error
2056messages.
2057
2058@item -Wformat
2059@opindex Wformat
2060@opindex ffreestanding
2061@opindex fno-builtin
2062Check calls to @code{printf} and @code{scanf}, etc., to make sure that
2063the arguments supplied have types appropriate to the format string
2064specified, and that the conversions specified in the format string make
2065sense. This includes standard functions, and others specified by format
2066attributes (@pxref{Function Attributes}), in the @code{printf},
2067@code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
2068not in the C standard) families (or other target-specific families).
2069Which functions are checked without format attributes having been
2070specified depends on the standard version selected, and such checks of
2071functions without the attribute specified are disabled by
2072@option{-ffreestanding} or @option{-fno-builtin}.
2073
2074The formats are checked against the format features supported by GNU
2075libc version 2.2. These include all ISO C90 and C99 features, as well
2076as features from the Single Unix Specification and some BSD and GNU
2077extensions. Other library implementations may not support all these
2078features; GCC does not support warning about features that go beyond a
2079particular library's limitations. However, if @option{-pedantic} is used
2080with @option{-Wformat}, warnings will be given about format features not
2081in the selected standard version (but not for @code{strfmon} formats,
2082since those are not in any version of the C standard). @xref{C Dialect
2083Options,,Options Controlling C Dialect}.
2084
2085Since @option{-Wformat} also checks for null format arguments for
2086several functions, @option{-Wformat} also implies @option{-Wnonnull}.
2087
2088@option{-Wformat} is included in @option{-Wall}. For more control over some
2089aspects of format checking, the options @option{-Wformat-y2k},
2090@option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
2091@option{-Wformat-nonliteral}, @option{-Wformat-security}, and
2092@option{-Wformat=2} are available, but are not included in @option{-Wall}.
2093
2094@item -Wformat-y2k
2095@opindex Wformat-y2k
2096If @option{-Wformat} is specified, also warn about @code{strftime}
2097formats which may yield only a two-digit year.
2098
2099@item -Wno-format-extra-args
2100@opindex Wno-format-extra-args
2101If @option{-Wformat} is specified, do not warn about excess arguments to a
2102@code{printf} or @code{scanf} format function. The C standard specifies
2103that such arguments are ignored.
2104
2105Where the unused arguments lie between used arguments that are
2106specified with @samp{$} operand number specifications, normally
2107warnings are still given, since the implementation could not know what
2108type to pass to @code{va_arg} to skip the unused arguments. However,
2109in the case of @code{scanf} formats, this option will suppress the
2110warning if the unused arguments are all pointers, since the Single
2111Unix Specification says that such unused arguments are allowed.
2112
2113@item -Wno-format-zero-length
2114@opindex Wno-format-zero-length
2115If @option{-Wformat} is specified, do not warn about zero-length formats.
2116The C standard specifies that zero-length formats are allowed.
2117
2118@item -Wformat-nonliteral
2119@opindex Wformat-nonliteral
2120If @option{-Wformat} is specified, also warn if the format string is not a
2121string literal and so cannot be checked, unless the format function
2122takes its format arguments as a @code{va_list}.
2123
2124@item -Wformat-security
2125@opindex Wformat-security
2126If @option{-Wformat} is specified, also warn about uses of format
2127functions that represent possible security problems. At present, this
2128warns about calls to @code{printf} and @code{scanf} functions where the
2129format string is not a string literal and there are no format arguments,
2130as in @code{printf (foo);}. This may be a security hole if the format
2131string came from untrusted input and contains @samp{%n}. (This is
2132currently a subset of what @option{-Wformat-nonliteral} warns about, but
2133in future warnings may be added to @option{-Wformat-security} that are not
2134included in @option{-Wformat-nonliteral}.)
2135
2136@item -Wformat=2
2137@opindex Wformat=2
2138Enable @option{-Wformat} plus format checks not included in
2139@option{-Wformat}. Currently equivalent to @samp{-Wformat
2140-Wformat-nonliteral -Wformat-security -Wformat-y2k}.
2141
2142@item -Wnonnull
2143@opindex Wnonnull
2144Warn about passing a null pointer for arguments marked as
2145requiring a non-null value by the @code{nonnull} function attribute.
2146
2147@option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It
2148can be disabled with the @option{-Wno-nonnull} option.
2149
2150@item -Winit-self @r{(C and C++ only)}
2151@opindex Winit-self
2152Warn about uninitialized variables which are initialized with themselves.
2153Note this option can only be used with the @option{-Wuninitialized} option,
2154which in turn only works with @option{-O1} and above.
2155
2156For example, GCC will warn about @code{i} being uninitialized in the
2157following snippet only when @option{-Winit-self} has been specified:
2158@smallexample
2159@group
2160int f()
2161@{
2162 int i = i;
2163 return i;
2164@}
2165@end group
2166@end smallexample
2167
2168@item -Wimplicit-int
2169@opindex Wimplicit-int
2170Warn when a declaration does not specify a type.
2171This warning is enabled by @option{-Wall}.
2172
2173@item -Wimplicit-function-declaration
2174@itemx -Werror-implicit-function-declaration
2175@opindex Wimplicit-function-declaration
2176@opindex Werror-implicit-function-declaration
2177Give a warning (or error) whenever a function is used before being
2178declared. The form @option{-Wno-error-implicit-function-declaration}
2179is not supported.
2180This warning is enabled by @option{-Wall} (as a warning, not an error).
2181
2182@item -Wimplicit
2183@opindex Wimplicit
2184Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
2185This warning is enabled by @option{-Wall}.
2186
2187@item -Wmain
2188@opindex Wmain
2189Warn if the type of @samp{main} is suspicious. @samp{main} should be a
2190function with external linkage, returning int, taking either zero
2191arguments, two, or three arguments of appropriate types.
2192This warning is enabled by @option{-Wall}.
2193
2194@item -Wmissing-braces
2195@opindex Wmissing-braces
2196Warn if an aggregate or union initializer is not fully bracketed. In
2197the following example, the initializer for @samp{a} is not fully
2198bracketed, but that for @samp{b} is fully bracketed.
2199
2200@smallexample
2201int a[2][2] = @{ 0, 1, 2, 3 @};
2202int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
2203@end smallexample
2204
2205This warning is enabled by @option{-Wall}.
2206
2207@item -Wmissing-include-dirs @r{(C and C++ only)}
2208@opindex Wmissing-include-dirs
2209Warn if a user-supplied include directory does not exist.
2210
2211@item -Wparentheses
2212@opindex Wparentheses
2213Warn if parentheses are omitted in certain contexts, such
2214as when there is an assignment in a context where a truth value
2215is expected, or when operators are nested whose precedence people
2216often get confused about.
2217
2218Also warn if a comparison like @samp{x<=y<=z} appears; this is
2219equivalent to @samp{(x<=y ? 1 : 0) <= z}, which is a different
2220interpretation from that of ordinary mathematical notation.
2221
2222Also warn about constructions where there may be confusion to which
2223@code{if} statement an @code{else} branch belongs. Here is an example of
2224such a case:
2225
2226@smallexample
2227@group
2228@{
2229 if (a)
2230 if (b)
2231 foo ();
2232 else
2233 bar ();
2234@}
2235@end group
2236@end smallexample
2237
2238In C/C++, every @code{else} branch belongs to the innermost possible
2239@code{if} statement, which in this example is @code{if (b)}. This is
2240often not what the programmer expected, as illustrated in the above
2241example by indentation the programmer chose. When there is the
2242potential for this confusion, GCC will issue a warning when this flag
2243is specified. To eliminate the warning, add explicit braces around
2244the innermost @code{if} statement so there is no way the @code{else}
2245could belong to the enclosing @code{if}. The resulting code would
2246look like this:
2247
2248@smallexample
2249@group
2250@{
2251 if (a)
2252 @{
2253 if (b)
2254 foo ();
2255 else
2256 bar ();
2257 @}
2258@}
2259@end group
2260@end smallexample
2261
2262This warning is enabled by @option{-Wall}.
2263
2264@item -Wsequence-point
2265@opindex Wsequence-point
2266Warn about code that may have undefined semantics because of violations
2267of sequence point rules in the C and C++ standards.
2268
2269The C and C++ standards defines the order in which expressions in a C/C++
2270program are evaluated in terms of @dfn{sequence points}, which represent
2271a partial ordering between the execution of parts of the program: those
2272executed before the sequence point, and those executed after it. These
2273occur after the evaluation of a full expression (one which is not part
2274of a larger expression), after the evaluation of the first operand of a
2275@code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
2276function is called (but after the evaluation of its arguments and the
2277expression denoting the called function), and in certain other places.
2278Other than as expressed by the sequence point rules, the order of
2279evaluation of subexpressions of an expression is not specified. All
2280these rules describe only a partial order rather than a total order,
2281since, for example, if two functions are called within one expression
2282with no sequence point between them, the order in which the functions
2283are called is not specified. However, the standards committee have
2284ruled that function calls do not overlap.
2285
2286It is not specified when between sequence points modifications to the
2287values of objects take effect. Programs whose behavior depends on this
2288have undefined behavior; the C and C++ standards specify that ``Between
2289the previous and next sequence point an object shall have its stored
2290value modified at most once by the evaluation of an expression.
2291Furthermore, the prior value shall be read only to determine the value
2292to be stored.''. If a program breaks these rules, the results on any
2293particular implementation are entirely unpredictable.
2294
2295Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
2296= b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
2297diagnosed by this option, and it may give an occasional false positive
2298result, but in general it has been found fairly effective at detecting
2299this sort of problem in programs.
2300
2301The standard is worded confusingly, therefore there is some debate
2302over the precise meaning of the sequence point rules in subtle cases.
2303Links to discussions of the problem, including proposed formal
2304definitions, may be found on the GCC readings page, at
2305@w{@uref{http://gcc.gnu.org/readings.html}}.
2306
2307This warning is enabled by @option{-Wall} for C and C++.
2308
2309@item -Wreturn-type
2310@opindex Wreturn-type
2311Warn whenever a function is defined with a return-type that defaults to
2312@code{int}. Also warn about any @code{return} statement with no
2313return-value in a function whose return-type is not @code{void}.
2314
2315For C, also warn if the return type of a function has a type qualifier
2316such as @code{const}. Such a type qualifier has no effect, since the
2317value returned by a function is not an lvalue. ISO C prohibits
2318qualified @code{void} return types on function definitions, so such
2319return types always receive a warning even without this option.
2320
2321For C++, a function without return type always produces a diagnostic
2322message, even when @option{-Wno-return-type} is specified. The only
2323exceptions are @samp{main} and functions defined in system headers.
2324
2325This warning is enabled by @option{-Wall}.
2326
2327@item -Wswitch
2328@opindex Wswitch
2329Warn whenever a @code{switch} statement has an index of enumerated type
2330and lacks a @code{case} for one or more of the named codes of that
2331enumeration. (The presence of a @code{default} label prevents this
2332warning.) @code{case} labels outside the enumeration range also
2333provoke warnings when this option is used.
2334This warning is enabled by @option{-Wall}.
2335
2336@item -Wswitch-default
2337@opindex Wswitch-switch
2338Warn whenever a @code{switch} statement does not have a @code{default}
2339case.
2340
2341@item -Wswitch-enum
2342@opindex Wswitch-enum
2343Warn whenever a @code{switch} statement has an index of enumerated type
2344and lacks a @code{case} for one or more of the named codes of that
2345enumeration. @code{case} labels outside the enumeration range also
2346provoke warnings when this option is used.
2347
2348@item -Wtrigraphs
2349@opindex Wtrigraphs
2350Warn if any trigraphs are encountered that might change the meaning of
2351the program (trigraphs within comments are not warned about).
2352This warning is enabled by @option{-Wall}.
2353
2354@item -Wunused-function
2355@opindex Wunused-function
2356Warn whenever a static function is declared but not defined or a
2357non-inline static function is unused.
2358This warning is enabled by @option{-Wall}.
2359
2360@item -Wunused-label
2361@opindex Wunused-label
2362Warn whenever a label is declared but not used.
2363This warning is enabled by @option{-Wall}.
2364
2365To suppress this warning use the @samp{unused} attribute
2366(@pxref{Variable Attributes}).
2367
2368@item -Wunused-parameter
2369@opindex Wunused-parameter
2370Warn whenever a function parameter is unused aside from its declaration.
2371
2372To suppress this warning use the @samp{unused} attribute
2373(@pxref{Variable Attributes}).
2374
2375@item -Wunused-variable
2376@opindex Wunused-variable
2377Warn whenever a local variable or non-constant static variable is unused
2378aside from its declaration.
2379This warning is enabled by @option{-Wall}.
2380
2381To suppress this warning use the @samp{unused} attribute
2382(@pxref{Variable Attributes}).
2383
2384@item -Wunused-value
2385@opindex Wunused-value
2386Warn whenever a statement computes a result that is explicitly not used.
2387This warning is enabled by @option{-Wall}.
2388
2389To suppress this warning cast the expression to @samp{void}.
2390
2391@item -Wunused
2392@opindex Wunused
2393All the above @option{-Wunused} options combined.
2394
2395In order to get a warning about an unused function parameter, you must
2396either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
2397@samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
2398
2399@item -Wuninitialized
2400@opindex Wuninitialized
2401Warn if an automatic variable is used without first being initialized or
2402if a variable may be clobbered by a @code{setjmp} call.
2403
2404These warnings are possible only in optimizing compilation,
2405because they require data flow information that is computed only
2406when optimizing. If you do not specify @option{-O}, you will not get
2407these warnings. Instead, GCC will issue a warning about @option{-Wuninitialized}
2408requiring @option{-O}.
2409
2410If you want to warn about code which uses the uninitialized value of the
2411variable in its own initializer, use the @option{-Winit-self} option.
2412
2413These warnings occur for individual uninitialized or clobbered
2414elements of structure, union or array variables as well as for
2415variables which are uninitialized or clobbered as a whole. They do
2416not occur for variables or elements declared @code{volatile}. Because
2417these warnings depend on optimization, the exact variables or elements
2418for which there are warnings will depend on the precise optimization
2419options and version of GCC used.
2420
2421Note that there may be no warning about a variable that is used only
2422to compute a value that itself is never used, because such
2423computations may be deleted by data flow analysis before the warnings
2424are printed.
2425
2426These warnings are made optional because GCC is not smart
2427enough to see all the reasons why the code might be correct
2428despite appearing to have an error. Here is one example of how
2429this can happen:
2430
2431@smallexample
2432@group
2433@{
2434 int x;
2435 switch (y)
2436 @{
2437 case 1: x = 1;
2438 break;
2439 case 2: x = 4;
2440 break;
2441 case 3: x = 5;
2442 @}
2443 foo (x);
2444@}
2445@end group
2446@end smallexample
2447
2448@noindent
2449If the value of @code{y} is always 1, 2 or 3, then @code{x} is
2450always initialized, but GCC doesn't know this. Here is
2451another common case:
2452
2453@smallexample
2454@{
2455 int save_y;
2456 if (change_y) save_y = y, y = new_y;
2457 @dots{}
2458 if (change_y) y = save_y;
2459@}
2460@end smallexample
2461
2462@noindent
2463This has no bug because @code{save_y} is used only if it is set.
2464
2465@cindex @code{longjmp} warnings
2466This option also warns when a non-volatile automatic variable might be
2467changed by a call to @code{longjmp}. These warnings as well are possible
2468only in optimizing compilation.
2469
2470The compiler sees only the calls to @code{setjmp}. It cannot know
2471where @code{longjmp} will be called; in fact, a signal handler could
2472call it at any point in the code. As a result, you may get a warning
2473even when there is in fact no problem because @code{longjmp} cannot
2474in fact be called at the place which would cause a problem.
2475
2476Some spurious warnings can be avoided if you declare all the functions
2477you use that never return as @code{noreturn}. @xref{Function
2478Attributes}.
2479
2480This warning is enabled by @option{-Wall}.
2481
2482@item -Wunknown-pragmas
2483@opindex Wunknown-pragmas
2484@cindex warning for unknown pragmas
2485@cindex unknown pragmas, warning
2486@cindex pragmas, warning of unknown
2487Warn when a #pragma directive is encountered which is not understood by
2488GCC@. If this command line option is used, warnings will even be issued
2489for unknown pragmas in system header files. This is not the case if
2490the warnings were only enabled by the @option{-Wall} command line option.
2491
2492@item -Wno-pragmas
2493@opindex Wno-pragmas
2494@opindex Wpragmas
2495Do not warn about misuses of pragmas, such as incorrect parameters,
2496invalid syntax, or conflicts between pragmas. See also
2497@samp{-Wunknown-pragmas}.
2498
2499@item -Wstrict-aliasing
2500@opindex Wstrict-aliasing
2501This option is only active when @option{-fstrict-aliasing} is active.
2502It warns about code which might break the strict aliasing rules that the
2503compiler is using for optimization. The warning does not catch all
2504cases, but does attempt to catch the more common pitfalls. It is
2505included in @option{-Wall}.
2506
2507@item -Wstrict-aliasing=2
2508@opindex Wstrict-aliasing=2
2509This option is only active when @option{-fstrict-aliasing} is active.
2510It warns about code which might break the strict aliasing rules that the
2511compiler is using for optimization. This warning catches more cases than
2512@option{-Wstrict-aliasing}, but it will also give a warning for some ambiguous
2513cases that are safe.
2514
2515@item -Wstrict-overflow
2516@item -Wstrict-overflow=@var{n}
2517@opindex Wstrict-overflow
2518This option is only active when @option{-fstrict-overflow} is active.
2519It warns about cases where the compiler optimizes based on the
2520assumption that signed overflow does not occur. Note that it does not
2521warn about all cases where the code might overflow: it only warns
2522about cases where the compiler implements some optimization. Thus
2523this warning depends on the optimization level.
2524
2525An optimization which assumes that signed overflow does not occur is
2526perfectly safe if the values of the variables involved are such that
2527overflow never does, in fact, occur. Therefore this warning can
2528easily give a false positive: a warning about code which is not
2529actually a problem. To help focus on important issues, several
2530warning levels are defined. No warnings are issued for the use of
2531undefined signed overflow when estimating how many iterations a loop
2532will require, in particular when determining whether a loop will be
2533executed at all.
2534
2535@table @option
2536@item -Wstrict-overflow=1
2537Warn about cases which are both questionable and easy to avoid. For
2538example: @code{x + 1 > x}; with @option{-fstrict-overflow}, the
2539compiler will simplify this to @code{1}. This level of
2540@option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
2541are not, and must be explicitly requested.
2542
2543@item -Wstrict-overflow=2
2544Also warn about other cases where a comparison is simplified to a
2545constant. For example: @code{abs (x) >= 0}. This can only be
2546simplified when @option{-fstrict-overflow} is in effect, because
2547@code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
2548zero. @option{-Wstrict-overflow} (with no level) is the same as
2549@option{-Wstrict-overflow=2}.
2550
2551@item -Wstrict-overflow=3
2552Also warn about other cases where a comparison is simplified. For
2553example: @code{x + 1 > 1} will be simplified to @code{x > 0}.
2554
2555@item -Wstrict-overflow=4
2556Also warn about other simplifications not covered by the above cases.
2557For example: @code{(x * 10) / 5} will be simplified to @code{x * 2}.
2558
2559@item -Wstrict-overflow=5
2560Also warn about cases where the compiler reduces the magnitude of a
2561constant involved in a comparison. For example: @code{x + 2 > y} will
2562be simplified to @code{x + 1 >= y}. This is reported only at the
2563highest warning level because this simplification applies to many
2564comparisons, so this warning level will give a very large number of
2565false positives.
2566@end table
2567
2568@item -Wall
2569@opindex Wall
2570All of the above @samp{-W} options combined. This enables all the
2571warnings about constructions that some users consider questionable, and
2572that are easy to avoid (or modify to prevent the warning), even in
2573conjunction with macros. This also enables some language-specific
2574warnings described in @ref{C++ Dialect Options}.
2575@end table
2576
2577The following @option{-W@dots{}} options are not implied by @option{-Wall}.
2578Some of them warn about constructions that users generally do not
2579consider questionable, but which occasionally you might wish to check
2580for; others warn about constructions that are necessary or hard to avoid
2581in some cases, and there is no simple way to modify the code to suppress
2582the warning.
2583
2584@table @gcctabopt
2585@item -Wextra
2586@opindex W
2587@opindex Wextra
2588(This option used to be called @option{-W}. The older name is still
2589supported, but the newer name is more descriptive.) Print extra warning
2590messages for these events:
2591
2592@itemize @bullet
2593@item
2594A function can return either with or without a value. (Falling
2595off the end of the function body is considered returning without
2596a value.) For example, this function would evoke such a
2597warning:
2598
2599@smallexample
2600@group
2601foo (a)
2602@{
2603 if (a > 0)
2604 return a;
2605@}
2606@end group
2607@end smallexample
2608
2609@item
2610An expression-statement or the left-hand side of a comma expression
2611contains no side effects.
2612To suppress the warning, cast the unused expression to void.
2613For example, an expression such as @samp{x[i,j]} will cause a warning,
2614but @samp{x[(void)i,j]} will not.
2615
2616@item
2617An unsigned value is compared against zero with @samp{<} or @samp{>=}.
2618
2619@item
2620Storage-class specifiers like @code{static} are not the first things in
2621a declaration. According to the C Standard, this usage is obsolescent.
2622
2623@item
2624If @option{-Wall} or @option{-Wunused} is also specified, warn about unused
2625arguments.
2626
2627@item
2628A comparison between signed and unsigned values could produce an
2629incorrect result when the signed value is converted to unsigned.
2630(But don't warn if @option{-Wno-sign-compare} is also specified.)
2631
2632@item
2633An aggregate has an initializer which does not initialize all members.
2634This warning can be independently controlled by
2635@option{-Wmissing-field-initializers}.
2636
2637@item
2638An initialized field without side effects is overridden when using
2639designated initializers (@pxref{Designated Inits, , Designated
2640Initializers}). This warning can be independently controlled by
2641@option{-Woverride-init}.
2642
2643@item
2644A function parameter is declared without a type specifier in K&R-style
2645functions:
2646
2647@smallexample
2648void foo(bar) @{ @}
2649@end smallexample
2650
2651@item
2652An empty body occurs in an @samp{if} or @samp{else} statement.
2653
2654@item
2655A pointer is compared against integer zero with @samp{<}, @samp{<=},
2656@samp{>}, or @samp{>=}.
2657
2658@item
2659A variable might be changed by @samp{longjmp} or @samp{vfork}.
2660
2661@item @r{(C++ only)}
2662An enumerator and a non-enumerator both appear in a conditional expression.
2663
2664@item @r{(C++ only)}
2665A non-static reference or non-static @samp{const} member appears in a
2666class without constructors.
2667
2668@item @r{(C++ only)}
2669Ambiguous virtual bases.
2670
2671@item @r{(C++ only)}
2672Subscripting an array which has been declared @samp{register}.
2673
2674@item @r{(C++ only)}
2675Taking the address of a variable which has been declared @samp{register}.
2676
2677@item @r{(C++ only)}
2678A base class is not initialized in a derived class' copy constructor.
2679@end itemize
2680
2681@item -Wno-div-by-zero
2682@opindex Wno-div-by-zero
2683@opindex Wdiv-by-zero
2684Do not warn about compile-time integer division by zero. Floating point
2685division by zero is not warned about, as it can be a legitimate way of
2686obtaining infinities and NaNs.
2687
2688@item -Wsystem-headers
2689@opindex Wsystem-headers
2690@cindex warnings from system headers
2691@cindex system headers, warnings from
2692Print warning messages for constructs found in system header files.
2693Warnings from system headers are normally suppressed, on the assumption
2694that they usually do not indicate real problems and would only make the
2695compiler output harder to read. Using this command line option tells
2696GCC to emit warnings from system headers as if they occurred in user
2697code. However, note that using @option{-Wall} in conjunction with this
2698option will @emph{not} warn about unknown pragmas in system
2699headers---for that, @option{-Wunknown-pragmas} must also be used.
2700
2701@item -Wfloat-equal
2702@opindex Wfloat-equal
2703Warn if floating point values are used in equality comparisons.
2704
2705The idea behind this is that sometimes it is convenient (for the
2706programmer) to consider floating-point values as approximations to
2707infinitely precise real numbers. If you are doing this, then you need
2708to compute (by analyzing the code, or in some other way) the maximum or
2709likely maximum error that the computation introduces, and allow for it
2710when performing comparisons (and when producing output, but that's a
2711different problem). In particular, instead of testing for equality, you
2712would check to see whether the two values have ranges that overlap; and
2713this is done with the relational operators, so equality comparisons are
2714probably mistaken.
2715
2716@item -Wtraditional @r{(C only)}
2717@opindex Wtraditional
2718Warn about certain constructs that behave differently in traditional and
2719ISO C@. Also warn about ISO C constructs that have no traditional C
2720equivalent, and/or problematic constructs which should be avoided.
2721
2722@itemize @bullet
2723@item
2724Macro parameters that appear within string literals in the macro body.
2725In traditional C macro replacement takes place within string literals,
2726but does not in ISO C@.
2727
2728@item
2729In traditional C, some preprocessor directives did not exist.
2730Traditional preprocessors would only consider a line to be a directive
2731if the @samp{#} appeared in column 1 on the line. Therefore
2732@option{-Wtraditional} warns about directives that traditional C
2733understands but would ignore because the @samp{#} does not appear as the
2734first character on the line. It also suggests you hide directives like
2735@samp{#pragma} not understood by traditional C by indenting them. Some
2736traditional implementations would not recognize @samp{#elif}, so it
2737suggests avoiding it altogether.
2738
2739@item
2740A function-like macro that appears without arguments.
2741
2742@item
2743The unary plus operator.
2744
2745@item
2746The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
2747constant suffixes. (Traditional C does support the @samp{L} suffix on integer
2748constants.) Note, these suffixes appear in macros defined in the system
2749headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
2750Use of these macros in user code might normally lead to spurious
2751warnings, however GCC's integrated preprocessor has enough context to
2752avoid warning in these cases.
2753
2754@item
2755A function declared external in one block and then used after the end of
2756the block.
2757
2758@item
2759A @code{switch} statement has an operand of type @code{long}.
2760
2761@item
2762A non-@code{static} function declaration follows a @code{static} one.
2763This construct is not accepted by some traditional C compilers.
2764
2765@item
2766The ISO type of an integer constant has a different width or
2767signedness from its traditional type. This warning is only issued if
2768the base of the constant is ten. I.e.@: hexadecimal or octal values, which
2769typically represent bit patterns, are not warned about.
2770
2771@item
2772Usage of ISO string concatenation is detected.
2773
2774@item
2775Initialization of automatic aggregates.
2776
2777@item
2778Identifier conflicts with labels. Traditional C lacks a separate
2779namespace for labels.
2780
2781@item
2782Initialization of unions. If the initializer is zero, the warning is
2783omitted. This is done under the assumption that the zero initializer in
2784user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
2785initializer warnings and relies on default initialization to zero in the
2786traditional C case.
2787
2788@item
2789Conversions by prototypes between fixed/floating point values and vice
2790versa. The absence of these prototypes when compiling with traditional
2791C would cause serious problems. This is a subset of the possible
2792conversion warnings, for the full set use @option{-Wconversion}.
2793
2794@item
2795Use of ISO C style function definitions. This warning intentionally is
2796@emph{not} issued for prototype declarations or variadic functions
2797because these ISO C features will appear in your code when using
2798libiberty's traditional C compatibility macros, @code{PARAMS} and
2799@code{VPARAMS}. This warning is also bypassed for nested functions
2800because that feature is already a GCC extension and thus not relevant to
2801traditional C compatibility.
2802@end itemize
2803
2804@item -Wdeclaration-after-statement @r{(C only)}
2805@opindex Wdeclaration-after-statement
2806Warn when a declaration is found after a statement in a block. This
2807construct, known from C++, was introduced with ISO C99 and is by default
2808allowed in GCC@. It is not supported by ISO C90 and was not supported by
2809GCC versions before GCC 3.0. @xref{Mixed Declarations}.
2810
2811@item -Wundef
2812@opindex Wundef
2813Warn if an undefined identifier is evaluated in an @samp{#if} directive.
2814
2815@item -Wno-endif-labels
2816@opindex Wno-endif-labels
2817@opindex Wendif-labels
2818Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
2819
2820@item -Wshadow
2821@opindex Wshadow
2822Warn whenever a local variable shadows another local variable, parameter or
2823global variable or whenever a built-in function is shadowed.
2824
2825@item -Wlarger-than-@var{len}
2826@opindex Wlarger-than
2827Warn whenever an object of larger than @var{len} bytes is defined.
2828
2829@item -Wunsafe-loop-optimizations
2830@opindex Wunsafe-loop-optimizations
2831Warn if the loop cannot be optimized because the compiler could not
2832assume anything on the bounds of the loop indices. With
2833@option{-funsafe-loop-optimizations} warn if the compiler made
2834such assumptions.
2835
2836@item -Wpointer-arith
2837@opindex Wpointer-arith
2838Warn about anything that depends on the ``size of'' a function type or
2839of @code{void}. GNU C assigns these types a size of 1, for
2840convenience in calculations with @code{void *} pointers and pointers
2841to functions.
2842
2843@item -Wbad-function-cast @r{(C only)}
2844@opindex Wbad-function-cast
2845Warn whenever a function call is cast to a non-matching type.
2846For example, warn if @code{int malloc()} is cast to @code{anything *}.
2847
2848@item -Wc++-compat
2849Warn about ISO C constructs that are outside of the common subset of
2850ISO C and ISO C++, e.g.@: request for implicit conversion from
2851@code{void *} to a pointer to non-@code{void} type.
2852
2853@item -Wcast-qual
2854@opindex Wcast-qual
2855Warn whenever a pointer is cast so as to remove a type qualifier from
2856the target type. For example, warn if a @code{const char *} is cast
2857to an ordinary @code{char *}.
2858
2859@item -Wcast-align
2860@opindex Wcast-align
2861Warn whenever a pointer is cast such that the required alignment of the
2862target is increased. For example, warn if a @code{char *} is cast to
2863an @code{int *} on machines where integers can only be accessed at
2864two- or four-byte boundaries.
2865
2866@item -Wwrite-strings
2867@opindex Wwrite-strings
2868When compiling C, give string constants the type @code{const
2869char[@var{length}]} so that
2870copying the address of one into a non-@code{const} @code{char *}
2871pointer will get a warning; when compiling C++, warn about the
2872deprecated conversion from string literals to @code{char *}. This
2873warning, by default, is enabled for C++ programs.
2874These warnings will help you find at
2875compile time code that can try to write into a string constant, but
2876only if you have been very careful about using @code{const} in
2877declarations and prototypes. Otherwise, it will just be a nuisance;
2878this is why we did not make @option{-Wall} request these warnings.
2879
2880@item -Wconversion
2881@opindex Wconversion
2882Warn if a prototype causes a type conversion that is different from what
2883would happen to the same argument in the absence of a prototype. This
2884includes conversions of fixed point to floating and vice versa, and
2885conversions changing the width or signedness of a fixed point argument
2886except when the same as the default promotion.
2887
2888Also, warn if a negative integer constant expression is implicitly
2889converted to an unsigned type. For example, warn about the assignment
2890@code{x = -1} if @code{x} is unsigned. But do not warn about explicit
2891casts like @code{(unsigned) -1}.
2892
2893@item -Wsign-compare
2894@opindex Wsign-compare
2895@cindex warning for comparison of signed and unsigned values
2896@cindex comparison of signed and unsigned values, warning
2897@cindex signed and unsigned values, comparison warning
2898Warn when a comparison between signed and unsigned values could produce
2899an incorrect result when the signed value is converted to unsigned.
2900This warning is also enabled by @option{-Wextra}; to get the other warnings
2901of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
2902
2903@item -Waddress
2904@opindex Waddress
2905@opindex Wno-address
2906Warn about suspicious uses of memory addresses. These include using
2907the address of a function in a conditional expression, such as
2908@code{void func(void); if (func)}, and comparisons against the memory
2909address of a string literal, such as @code{if (x == "abc")}. Such
2910uses typically indicate a programmer error: the address of a function
2911always evaluates to true, so their use in a conditional usually
2912indicate that the programmer forgot the parentheses in a function
2913call; and comparisons against string literals result in unspecified
2914behavior and are not portable in C, so they usually indicate that the
2915programmer intended to use @code{strcmp}. This warning is enabled by
2916@option{-Wall}.
2917
2918@item -Waggregate-return
2919@opindex Waggregate-return
2920Warn if any functions that return structures or unions are defined or
2921called. (In languages where you can return an array, this also elicits
2922a warning.)
2923
2924@item -Wno-attributes
2925@opindex Wno-attributes
2926@opindex Wattributes
2927Do not warn if an unexpected @code{__attribute__} is used, such as
2928unrecognized attributes, function attributes applied to variables,
2929etc. This will not stop errors for incorrect use of supported
2930attributes.
2931
2932@item -Wstrict-prototypes @r{(C only)}
2933@opindex Wstrict-prototypes
2934Warn if a function is declared or defined without specifying the
2935argument types. (An old-style function definition is permitted without
2936a warning if preceded by a declaration which specifies the argument
2937types.)
2938
2939@item -Wold-style-definition @r{(C only)}
2940@opindex Wold-style-definition
2941Warn if an old-style function definition is used. A warning is given
2942even if there is a previous prototype.
2943
2944@item -Wmissing-prototypes @r{(C only)}
2945@opindex Wmissing-prototypes
2946Warn if a global function is defined without a previous prototype
2947declaration. This warning is issued even if the definition itself
2948provides a prototype. The aim is to detect global functions that fail
2949to be declared in header files.
2950
2951@item -Wmissing-declarations @r{(C only)}
2952@opindex Wmissing-declarations
2953Warn if a global function is defined without a previous declaration.
2954Do so even if the definition itself provides a prototype.
2955Use this option to detect global functions that are not declared in
2956header files.
2957
2958@item -Wmissing-field-initializers
2959@opindex Wmissing-field-initializers
2960@opindex W
2961@opindex Wextra
2962Warn if a structure's initializer has some fields missing. For
2963example, the following code would cause such a warning, because
2964@code{x.h} is implicitly zero:
2965
2966@smallexample
2967struct s @{ int f, g, h; @};
2968struct s x = @{ 3, 4 @};
2969@end smallexample
2970
2971This option does not warn about designated initializers, so the following
2972modification would not trigger a warning:
2973
2974@smallexample
2975struct s @{ int f, g, h; @};
2976struct s x = @{ .f = 3, .g = 4 @};
2977@end smallexample
2978
2979This warning is included in @option{-Wextra}. To get other @option{-Wextra}
2980warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
2981
2982@item -Wmissing-noreturn
2983@opindex Wmissing-noreturn
2984Warn about functions which might be candidates for attribute @code{noreturn}.
2985Note these are only possible candidates, not absolute ones. Care should
2986be taken to manually verify functions actually do not ever return before
2987adding the @code{noreturn} attribute, otherwise subtle code generation
2988bugs could be introduced. You will not get a warning for @code{main} in
2989hosted C environments.
2990
2991@item -Wmissing-format-attribute
2992@opindex Wmissing-format-attribute
2993@opindex Wformat
2994Warn about function pointers which might be candidates for @code{format}
2995attributes. Note these are only possible candidates, not absolute ones.
2996GCC will guess that function pointers with @code{format} attributes that
2997are used in assignment, initialization, parameter passing or return
2998statements should have a corresponding @code{format} attribute in the
2999resulting type. I.e.@: the left-hand side of the assignment or
3000initialization, the type of the parameter variable, or the return type
3001of the containing function respectively should also have a @code{format}
3002attribute to avoid the warning.
3003
3004GCC will also warn about function definitions which might be
3005candidates for @code{format} attributes. Again, these are only
3006possible candidates. GCC will guess that @code{format} attributes
3007might be appropriate for any function that calls a function like
3008@code{vprintf} or @code{vscanf}, but this might not always be the
3009case, and some functions for which @code{format} attributes are
3010appropriate may not be detected.
3011
3012@item -Wno-multichar
3013@opindex Wno-multichar
3014@opindex Wmultichar
3015Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
3016Usually they indicate a typo in the user's code, as they have
3017implementation-defined values, and should not be used in portable code.
3018
3019@item -Wnormalized=<none|id|nfc|nfkc>
3020@opindex Wnormalized
3021@cindex NFC
3022@cindex NFKC
3023@cindex character set, input normalization
3024In ISO C and ISO C++, two identifiers are different if they are
3025different sequences of characters. However, sometimes when characters
3026outside the basic ASCII character set are used, you can have two
3027different character sequences that look the same. To avoid confusion,
3028the ISO 10646 standard sets out some @dfn{normalization rules} which
3029when applied ensure that two sequences that look the same are turned into
3030the same sequence. GCC can warn you if you are using identifiers which
3031have not been normalized; this option controls that warning.
3032
3033There are four levels of warning that GCC supports. The default is
3034@option{-Wnormalized=nfc}, which warns about any identifier which is
3035not in the ISO 10646 ``C'' normalized form, @dfn{NFC}. NFC is the
3036recommended form for most uses.
3037
3038Unfortunately, there are some characters which ISO C and ISO C++ allow
3039in identifiers that when turned into NFC aren't allowable as
3040identifiers. That is, there's no way to use these symbols in portable
3041ISO C or C++ and have all your identifiers in NFC.
3042@option{-Wnormalized=id} suppresses the warning for these characters.
3043It is hoped that future versions of the standards involved will correct
3044this, which is why this option is not the default.
3045
3046You can switch the warning off for all characters by writing
3047@option{-Wnormalized=none}. You would only want to do this if you
3048were using some other normalization scheme (like ``D''), because
3049otherwise you can easily create bugs that are literally impossible to see.
3050
3051Some characters in ISO 10646 have distinct meanings but look identical
3052in some fonts or display methodologies, especially once formatting has
3053been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
3054LETTER N'', will display just like a regular @code{n} which has been
3055placed in a superscript. ISO 10646 defines the @dfn{NFKC}
3056normalization scheme to convert all these into a standard form as
3057well, and GCC will warn if your code is not in NFKC if you use
3058@option{-Wnormalized=nfkc}. This warning is comparable to warning
3059about every identifier that contains the letter O because it might be
3060confused with the digit 0, and so is not the default, but may be
3061useful as a local coding convention if the programming environment is
3062unable to be fixed to display these characters distinctly.
3063
3064@item -Wno-deprecated-declarations
3065@opindex Wno-deprecated-declarations
3066Do not warn about uses of functions (@pxref{Function Attributes}),
3067variables (@pxref{Variable Attributes}), and types (@pxref{Type
3068Attributes}) marked as deprecated by using the @code{deprecated}
3069attribute.
3070
3071@item -Wno-overflow
3072@opindex Wno-overflow
3073Do not warn about compile-time overflow in constant expressions.
3074
3075@item -Woverride-init
3076@opindex Woverride-init
3077@opindex W
3078@opindex Wextra
3079Warn if an initialized field without side effects is overridden when
3080using designated initializers (@pxref{Designated Inits, , Designated
3081Initializers}).
3082
3083This warning is included in @option{-Wextra}. To get other
3084@option{-Wextra} warnings without this one, use @samp{-Wextra
3085-Wno-override-init}.
3086
3087@item -Wpacked
3088@opindex Wpacked
3089Warn if a structure is given the packed attribute, but the packed
3090attribute has no effect on the layout or size of the structure.
3091Such structures may be mis-aligned for little benefit. For
3092instance, in this code, the variable @code{f.x} in @code{struct bar}
3093will be misaligned even though @code{struct bar} does not itself
3094have the packed attribute:
3095
3096@smallexample
3097@group
3098struct foo @{
3099 int x;
3100 char a, b, c, d;
3101@} __attribute__((packed));
3102struct bar @{
3103 char z;
3104 struct foo f;
3105@};
3106@end group
3107@end smallexample
3108
3109@item -Wpadded
3110@opindex Wpadded
3111Warn if padding is included in a structure, either to align an element
3112of the structure or to align the whole structure. Sometimes when this
3113happens it is possible to rearrange the fields of the structure to
3114reduce the padding and so make the structure smaller.
3115
3116@item -Wredundant-decls
3117@opindex Wredundant-decls
3118Warn if anything is declared more than once in the same scope, even in
3119cases where multiple declaration is valid and changes nothing.
3120
3121@item -Wnested-externs @r{(C only)}
3122@opindex Wnested-externs
3123Warn if an @code{extern} declaration is encountered within a function.
3124
3125@item -Wunreachable-code
3126@opindex Wunreachable-code
3127Warn if the compiler detects that code will never be executed.
3128
3129This option is intended to warn when the compiler detects that at
3130least a whole line of source code will never be executed, because
3131some condition is never satisfied or because it is after a
3132procedure that never returns.
3133
3134It is possible for this option to produce a warning even though there
3135are circumstances under which part of the affected line can be executed,
3136so care should be taken when removing apparently-unreachable code.
3137
3138For instance, when a function is inlined, a warning may mean that the
3139line is unreachable in only one inlined copy of the function.
3140
3141This option is not made part of @option{-Wall} because in a debugging
3142version of a program there is often substantial code which checks
3143correct functioning of the program and is, hopefully, unreachable
3144because the program does work. Another common use of unreachable
3145code is to provide behavior which is selectable at compile-time.
3146
3147@item -Winline
3148@opindex Winline
3149Warn if a function can not be inlined and it was declared as inline.
3150Even with this option, the compiler will not warn about failures to
3151inline functions declared in system headers.
3152
3153The compiler uses a variety of heuristics to determine whether or not
3154to inline a function. For example, the compiler takes into account
3155the size of the function being inlined and the amount of inlining
3156that has already been done in the current function. Therefore,
3157seemingly insignificant changes in the source program can cause the
3158warnings produced by @option{-Winline} to appear or disappear.
3159
3160@item -Wno-invalid-offsetof @r{(C++ only)}
3161@opindex Wno-invalid-offsetof
3162Suppress warnings from applying the @samp{offsetof} macro to a non-POD
3163type. According to the 1998 ISO C++ standard, applying @samp{offsetof}
3164to a non-POD type is undefined. In existing C++ implementations,
3165however, @samp{offsetof} typically gives meaningful results even when
3166applied to certain kinds of non-POD types. (Such as a simple
3167@samp{struct} that fails to be a POD type only by virtue of having a
3168constructor.) This flag is for users who are aware that they are
3169writing nonportable code and who have deliberately chosen to ignore the
3170warning about it.
3171
3172The restrictions on @samp{offsetof} may be relaxed in a future version
3173of the C++ standard.
3174
3175@item -Wno-int-to-pointer-cast @r{(C only)}
3176@opindex Wno-int-to-pointer-cast
3177Suppress warnings from casts to pointer type of an integer of a
3178different size.
3179
3180@item -Wno-pointer-to-int-cast @r{(C only)}
3181@opindex Wno-pointer-to-int-cast
3182Suppress warnings from casts from a pointer to an integer type of a
3183different size.
3184
3185@item -Winvalid-pch
3186@opindex Winvalid-pch
3187Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
3188the search path but can't be used.
3189
3190@item -Wlong-long
3191@opindex Wlong-long
3192@opindex Wno-long-long
3193Warn if @samp{long long} type is used. This is default. To inhibit
3194the warning messages, use @option{-Wno-long-long}. Flags
3195@option{-Wlong-long} and @option{-Wno-long-long} are taken into account
3196only when @option{-pedantic} flag is used.
3197
3198@item -Wvariadic-macros
3199@opindex Wvariadic-macros
3200@opindex Wno-variadic-macros
3201Warn if variadic macros are used in pedantic ISO C90 mode, or the GNU
3202alternate syntax when in pedantic ISO C99 mode. This is default.
3203To inhibit the warning messages, use @option{-Wno-variadic-macros}.
3204
3205@item -Wvla
3206@opindex Wvla
3207@opindex Wno-vla
3208Warn if variable length array is used in the code.
3209@option{-Wno-vla} will prevent the @option{-pedantic} warning of
3210the variable length array.
3211
3204@item -Wvolatile-register-var
3205@opindex Wvolatile-register-var
3206@opindex Wno-volatile-register-var
3207Warn if a register variable is declared volatile. The volatile
3208modifier does not inhibit all optimizations that may eliminate reads
3209and/or writes to register variables.
3210
3211@item -Wdisabled-optimization
3212@opindex Wdisabled-optimization
3213Warn if a requested optimization pass is disabled. This warning does
3214not generally indicate that there is anything wrong with your code; it
3215merely indicates that GCC's optimizers were unable to handle the code
3216effectively. Often, the problem is that your code is too big or too
3217complex; GCC will refuse to optimize programs when the optimization
3218itself is likely to take inordinate amounts of time.
3219
3220@item -Wpointer-sign
3221@opindex Wpointer-sign
3222@opindex Wno-pointer-sign
3223Warn for pointer argument passing or assignment with different signedness.
3224This option is only supported for C. It is implied by @option{-Wall}
3225and by @option{-pedantic}, which can be disabled with
3226@option{-Wno-pointer-sign}.
3227
3228@item -Werror
3229@opindex Werror
3230Make all warnings into errors.
3231
3232@item -Werror=
3233@opindex Werror=
3234Make the specified warning into an errors. The specifier for a
3235warning is appended, for example @option{-Werror=switch} turns the
3236warnings controlled by @option{-Wswitch} into errors. This switch
3237takes a negative form, to be used to negate @option{-Werror} for
3238specific warnings, for example @option{-Wno-error=switch} makes
3239@option{-Wswitch} warnings not be errors, even when @option{-Werror}
3240is in effect. You can use the @option{-fdiagnostics-show-option}
3241option to have each controllable warning amended with the option which
3242controls it, to determine what to use with this option.
3243
3244Note that specifying @option{-Werror=}@var{foo} automatically implies
3245@option{-W}@var{foo}. However, @option{-Wno-error=}@var{foo} does not
3246imply anything.
3247
3248@item -Wstack-protector
3249@opindex Wstack-protector
3250This option is only active when @option{-fstack-protector} is active. It
3251warns about functions that will not be protected against stack smashing.
3252
3253@item -Woverlength-strings
3254@opindex Woverlength-strings
3255Warn about string constants which are longer than the ``minimum
3256maximum'' length specified in the C standard. Modern compilers
3257generally allow string constants which are much longer than the
3258standard's minimum limit, but very portable programs should avoid
3259using longer strings.
3260
3261The limit applies @emph{after} string constant concatenation, and does
3262not count the trailing NUL@. In C89, the limit was 509 characters; in
3263C99, it was raised to 4095. C++98 does not specify a normative
3264minimum maximum, so we do not diagnose overlength strings in C++@.
3265
3266This option is implied by @option{-pedantic}, and can be disabled with
3267@option{-Wno-overlength-strings}.
3268@end table
3269
3270@node Debugging Options
3271@section Options for Debugging Your Program or GCC
3272@cindex options, debugging
3273@cindex debugging information options
3274
3275GCC has various special options that are used for debugging
3276either your program or GCC:
3277
3278@table @gcctabopt
3279@item -g
3280@opindex g
3281Produce debugging information in the operating system's native format
3282(stabs, COFF, XCOFF, or DWARF 2)@. GDB can work with this debugging
3283information.
3284
3285On most systems that use stabs format, @option{-g} enables use of extra
3286debugging information that only GDB can use; this extra information
3287makes debugging work better in GDB but will probably make other debuggers
3288crash or
3289refuse to read the program. If you want to control for certain whether
3290to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
3291@option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
3292
3293GCC allows you to use @option{-g} with
3294@option{-O}. The shortcuts taken by optimized code may occasionally
3295produce surprising results: some variables you declared may not exist
3296at all; flow of control may briefly move where you did not expect it;
3297some statements may not be executed because they compute constant
3298results or their values were already at hand; some statements may
3299execute in different places because they were moved out of loops.
3300
3301Nevertheless it proves possible to debug optimized output. This makes
3302it reasonable to use the optimizer for programs that might have bugs.
3303
3304The following options are useful when GCC is generated with the
3305capability for more than one debugging format.
3306
3307@item -ggdb
3308@opindex ggdb
3309Produce debugging information for use by GDB@. This means to use the
3310most expressive format available (DWARF 2, stabs, or the native format
3311if neither of those are supported), including GDB extensions if at all
3312possible.
3313
3314@item -gstabs
3315@opindex gstabs
3316Produce debugging information in stabs format (if that is supported),
3317without GDB extensions. This is the format used by DBX on most BSD
3318systems. On MIPS, Alpha and System V Release 4 systems this option
3319produces stabs debugging output which is not understood by DBX or SDB@.
3320On System V Release 4 systems this option requires the GNU assembler.
3321
3322@item -feliminate-unused-debug-symbols
3323@opindex feliminate-unused-debug-symbols
3324Produce debugging information in stabs format (if that is supported),
3325for only symbols that are actually used.
3326
3327@item -femit-class-debug-always
3328Instead of emitting debugging information for a C++ class in only one
3329object file, emit it in all object files using the class. This option
3330should be used only with debuggers that are unable to handle the way GCC
3331normally emits debugging information for classes because using this
3332option will increase the size of debugging information by as much as a
3333factor of two.
3334
3335@item -gstabs+
3336@opindex gstabs+
3337Produce debugging information in stabs format (if that is supported),
3338using GNU extensions understood only by the GNU debugger (GDB)@. The
3339use of these extensions is likely to make other debuggers crash or
3340refuse to read the program.
3341
3342@item -gcoff
3343@opindex gcoff
3344Produce debugging information in COFF format (if that is supported).
3345This is the format used by SDB on most System V systems prior to
3346System V Release 4.
3347
3348@item -gxcoff
3349@opindex gxcoff
3350Produce debugging information in XCOFF format (if that is supported).
3351This is the format used by the DBX debugger on IBM RS/6000 systems.
3352
3353@item -gxcoff+
3354@opindex gxcoff+
3355Produce debugging information in XCOFF format (if that is supported),
3356using GNU extensions understood only by the GNU debugger (GDB)@. The
3357use of these extensions is likely to make other debuggers crash or
3358refuse to read the program, and may cause assemblers other than the GNU
3359assembler (GAS) to fail with an error.
3360
3361@item -gdwarf-2
3362@opindex gdwarf-2
3363Produce debugging information in DWARF version 2 format (if that is
3364supported). This is the format used by DBX on IRIX 6. With this
3365option, GCC uses features of DWARF version 3 when they are useful;
3366version 3 is upward compatible with version 2, but may still cause
3367problems for older debuggers.
3368
3369@item -gvms
3370@opindex gvms
3371Produce debugging information in VMS debug format (if that is
3372supported). This is the format used by DEBUG on VMS systems.
3373
3374@item -g@var{level}
3375@itemx -ggdb@var{level}
3376@itemx -gstabs@var{level}
3377@itemx -gcoff@var{level}
3378@itemx -gxcoff@var{level}
3379@itemx -gvms@var{level}
3380Request debugging information and also use @var{level} to specify how
3381much information. The default level is 2.
3382
3383Level 1 produces minimal information, enough for making backtraces in
3384parts of the program that you don't plan to debug. This includes
3385descriptions of functions and external variables, but no information
3386about local variables and no line numbers.
3387
3388Level 3 includes extra information, such as all the macro definitions
3389present in the program. Some debuggers support macro expansion when
3390you use @option{-g3}.
3391
3392@option{-gdwarf-2} does not accept a concatenated debug level, because
3393GCC used to support an option @option{-gdwarf} that meant to generate
3394debug information in version 1 of the DWARF format (which is very
3395different from version 2), and it would have been too confusing. That
3396debug format is long obsolete, but the option cannot be changed now.
3397Instead use an additional @option{-g@var{level}} option to change the
3398debug level for DWARF2.
3399
3400@item -feliminate-dwarf2-dups
3401@opindex feliminate-dwarf2-dups
3402Compress DWARF2 debugging information by eliminating duplicated
3403information about each symbol. This option only makes sense when
3404generating DWARF2 debugging information with @option{-gdwarf-2}.
3405
3406@cindex @command{prof}
3407@item -p
3408@opindex p
3409Generate extra code to write profile information suitable for the
3410analysis program @command{prof}. You must use this option when compiling
3411the source files you want data about, and you must also use it when
3412linking.
3413
3414@cindex @command{gprof}
3415@item -pg
3416@opindex pg
3417Generate extra code to write profile information suitable for the
3418analysis program @command{gprof}. You must use this option when compiling
3419the source files you want data about, and you must also use it when
3420linking.
3421
3422@item -Q
3423@opindex Q
3424Makes the compiler print out each function name as it is compiled, and
3425print some statistics about each pass when it finishes.
3426
3427@item -ftime-report
3428@opindex ftime-report
3429Makes the compiler print some statistics about the time consumed by each
3430pass when it finishes.
3431
3432@item -fmem-report
3433@opindex fmem-report
3434Makes the compiler print some statistics about permanent memory
3435allocation when it finishes.
3436
3437@item -fprofile-arcs
3438@opindex fprofile-arcs
3439Add code so that program flow @dfn{arcs} are instrumented. During
3440execution the program records how many times each branch and call is
3441executed and how many times it is taken or returns. When the compiled
3442program exits it saves this data to a file called
3443@file{@var{auxname}.gcda} for each source file. The data may be used for
3444profile-directed optimizations (@option{-fbranch-probabilities}), or for
3445test coverage analysis (@option{-ftest-coverage}). Each object file's
3446@var{auxname} is generated from the name of the output file, if
3447explicitly specified and it is not the final executable, otherwise it is
3448the basename of the source file. In both cases any suffix is removed
3449(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
3450@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
3451@xref{Cross-profiling}.
3452
3453@cindex @command{gcov}
3454@item --coverage
3455@opindex coverage
3456
3457This option is used to compile and link code instrumented for coverage
3458analysis. The option is a synonym for @option{-fprofile-arcs}
3459@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
3460linking). See the documentation for those options for more details.
3461
3462@itemize
3463
3464@item
3465Compile the source files with @option{-fprofile-arcs} plus optimization
3466and code generation options. For test coverage analysis, use the
3467additional @option{-ftest-coverage} option. You do not need to profile
3468every source file in a program.
3469
3470@item
3471Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
3472(the latter implies the former).
3473
3474@item
3475Run the program on a representative workload to generate the arc profile
3476information. This may be repeated any number of times. You can run
3477concurrent instances of your program, and provided that the file system
3478supports locking, the data files will be correctly updated. Also
3479@code{fork} calls are detected and correctly handled (double counting
3480will not happen).
3481
3482@item
3483For profile-directed optimizations, compile the source files again with
3484the same optimization and code generation options plus
3485@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
3486Control Optimization}).
3487
3488@item
3489For test coverage analysis, use @command{gcov} to produce human readable
3490information from the @file{.gcno} and @file{.gcda} files. Refer to the
3491@command{gcov} documentation for further information.
3492
3493@end itemize
3494
3495With @option{-fprofile-arcs}, for each function of your program GCC
3496creates a program flow graph, then finds a spanning tree for the graph.
3497Only arcs that are not on the spanning tree have to be instrumented: the
3498compiler adds code to count the number of times that these arcs are
3499executed. When an arc is the only exit or only entrance to a block, the
3500instrumentation code can be added to the block; otherwise, a new basic
3501block must be created to hold the instrumentation code.
3502
3503@need 2000
3504@item -ftest-coverage
3505@opindex ftest-coverage
3506Produce a notes file that the @command{gcov} code-coverage utility
3507(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
3508show program coverage. Each source file's note file is called
3509@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
3510above for a description of @var{auxname} and instructions on how to
3511generate test coverage data. Coverage data will match the source files
3512more closely, if you do not optimize.
3513
3514@item -d@var{letters}
3515@item -fdump-rtl-@var{pass}
3516@opindex d
3517Says to make debugging dumps during compilation at times specified by
3518@var{letters}. This is used for debugging the RTL-based passes of the
3519compiler. The file names for most of the dumps are made by appending a
3520pass number and a word to the @var{dumpname}. @var{dumpname} is generated
3521from the name of the output file, if explicitly specified and it is not
3522an executable, otherwise it is the basename of the source file.
3523
3524Most debug dumps can be enabled either passing a letter to the @option{-d}
3525option, or with a long @option{-fdump-rtl} switch; here are the possible
3526letters for use in @var{letters} and @var{pass}, and their meanings:
3527
3528@table @gcctabopt
3529@item -dA
3530@opindex dA
3531Annotate the assembler output with miscellaneous debugging information.
3532
3533@item -dB
3534@itemx -fdump-rtl-bbro
3535@opindex dB
3536@opindex fdump-rtl-bbro
3537Dump after block reordering, to @file{@var{file}.148r.bbro}.
3538
3539@item -dc
3540@itemx -fdump-rtl-combine
3541@opindex dc
3542@opindex fdump-rtl-combine
3543Dump after instruction combination, to the file @file{@var{file}.129r.combine}.
3544
3545@item -dC
3546@itemx -fdump-rtl-ce1
3547@itemx -fdump-rtl-ce2
3548@opindex dC
3549@opindex fdump-rtl-ce1
3550@opindex fdump-rtl-ce2
3551@option{-dC} and @option{-fdump-rtl-ce1} enable dumping after the
3552first if conversion, to the file @file{@var{file}.117r.ce1}. @option{-dC}
3553and @option{-fdump-rtl-ce2} enable dumping after the second if
3554conversion, to the file @file{@var{file}.130r.ce2}.
3555
3556@item -dd
3557@itemx -fdump-rtl-btl
3558@itemx -fdump-rtl-dbr
3559@opindex dd
3560@opindex fdump-rtl-btl
3561@opindex fdump-rtl-dbr
3562@option{-dd} and @option{-fdump-rtl-btl} enable dumping after branch
3563target load optimization, to @file{@var{file}.31.btl}. @option{-dd}
3564and @option{-fdump-rtl-dbr} enable dumping after delayed branch
3565scheduling, to @file{@var{file}.36.dbr}.
3566
3567@item -dD
3568@opindex dD
3569Dump all macro definitions, at the end of preprocessing, in addition to
3570normal output.
3571
3572@item -dE
3573@itemx -fdump-rtl-ce3
3574@opindex dE
3575@opindex fdump-rtl-ce3
3576Dump after the third if conversion, to @file{@var{file}.146r.ce3}.
3577
3578@item -df
3579@itemx -fdump-rtl-cfg
3580@itemx -fdump-rtl-life
3581@opindex df
3582@opindex fdump-rtl-cfg
3583@opindex fdump-rtl-life
3584@option{-df} and @option{-fdump-rtl-cfg} enable dumping after control
3585and data flow analysis, to @file{@var{file}.116r.cfg}. @option{-df}
3586and @option{-fdump-rtl-cfg} enable dumping dump after life analysis,
3587to @file{@var{file}.128r.life1} and @file{@var{file}.135r.life2}.
3588
3589@item -dg
3590@itemx -fdump-rtl-greg
3591@opindex dg
3592@opindex fdump-rtl-greg
3593Dump after global register allocation, to @file{@var{file}.139r.greg}.
3594
3595@item -dG
3596@itemx -fdump-rtl-gcse
3597@itemx -fdump-rtl-bypass
3598@opindex dG
3599@opindex fdump-rtl-gcse
3600@opindex fdump-rtl-bypass
3601@option{-dG} and @option{-fdump-rtl-gcse} enable dumping after GCSE, to
3602@file{@var{file}.114r.gcse}. @option{-dG} and @option{-fdump-rtl-bypass}
3603enable dumping after jump bypassing and control flow optimizations, to
3604@file{@var{file}.115r.bypass}.
3605
3606@item -dh
3607@itemx -fdump-rtl-eh
3608@opindex dh
3609@opindex fdump-rtl-eh
3610Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
3611
3612@item -di
3613@itemx -fdump-rtl-sibling
3614@opindex di
3615@opindex fdump-rtl-sibling
3616Dump after sibling call optimizations, to @file{@var{file}.106r.sibling}.
3617
3618@item -dj
3619@itemx -fdump-rtl-jump
3620@opindex dj
3621@opindex fdump-rtl-jump
3622Dump after the first jump optimization, to @file{@var{file}.112r.jump}.
3623
3624@item -dk
3625@itemx -fdump-rtl-stack
3626@opindex dk
3627@opindex fdump-rtl-stack
3628Dump after conversion from registers to stack, to @file{@var{file}.152r.stack}.
3629
3630@item -dl
3631@itemx -fdump-rtl-lreg
3632@opindex dl
3633@opindex fdump-rtl-lreg
3634Dump after local register allocation, to @file{@var{file}.138r.lreg}.
3635
3636@item -dL
3637@itemx -fdump-rtl-loop2
3638@opindex dL
3639@opindex fdump-rtl-loop2
3640@option{-dL} and @option{-fdump-rtl-loop2} enable dumping after the
3641loop optimization pass, to @file{@var{file}.119r.loop2},
3642@file{@var{file}.120r.loop2_init},
3643@file{@var{file}.121r.loop2_invariant}, and
3644@file{@var{file}.125r.loop2_done}.
3645
3646@item -dm
3647@itemx -fdump-rtl-sms
3648@opindex dm
3649@opindex fdump-rtl-sms
3650Dump after modulo scheduling, to @file{@var{file}.136r.sms}.
3651
3652@item -dM
3653@itemx -fdump-rtl-mach
3654@opindex dM
3655@opindex fdump-rtl-mach
3656Dump after performing the machine dependent reorganization pass, to
3657@file{@var{file}.155r.mach}.
3658
3659@item -dn
3660@itemx -fdump-rtl-rnreg
3661@opindex dn
3662@opindex fdump-rtl-rnreg
3663Dump after register renumbering, to @file{@var{file}.147r.rnreg}.
3664
3665@item -dN
3666@itemx -fdump-rtl-regmove
3667@opindex dN
3668@opindex fdump-rtl-regmove
3669Dump after the register move pass, to @file{@var{file}.132r.regmove}.
3670
3671@item -do
3672@itemx -fdump-rtl-postreload
3673@opindex do
3674@opindex fdump-rtl-postreload
3675Dump after post-reload optimizations, to @file{@var{file}.24.postreload}.
3676
3677@item -dr
3678@itemx -fdump-rtl-expand
3679@opindex dr
3680@opindex fdump-rtl-expand
3681Dump after RTL generation, to @file{@var{file}.104r.expand}.
3682
3683@item -dR
3684@itemx -fdump-rtl-sched2
3685@opindex dR
3686@opindex fdump-rtl-sched2
3687Dump after the second scheduling pass, to @file{@var{file}.150r.sched2}.
3688
3689@item -ds
3690@itemx -fdump-rtl-cse
3691@opindex ds
3692@opindex fdump-rtl-cse
3693Dump after CSE (including the jump optimization that sometimes follows
3694CSE), to @file{@var{file}.113r.cse}.
3695
3696@item -dS
3697@itemx -fdump-rtl-sched
3698@opindex dS
3699@opindex fdump-rtl-sched
3700Dump after the first scheduling pass, to @file{@var{file}.21.sched}.
3701
3702@item -dt
3703@itemx -fdump-rtl-cse2
3704@opindex dt
3705@opindex fdump-rtl-cse2
3706Dump after the second CSE pass (including the jump optimization that
3707sometimes follows CSE), to @file{@var{file}.127r.cse2}.
3708
3709@item -dT
3710@itemx -fdump-rtl-tracer
3711@opindex dT
3712@opindex fdump-rtl-tracer
3713Dump after running tracer, to @file{@var{file}.118r.tracer}.
3714
3715@item -dV
3716@itemx -fdump-rtl-vpt
3717@itemx -fdump-rtl-vartrack
3718@opindex dV
3719@opindex fdump-rtl-vpt
3720@opindex fdump-rtl-vartrack
3721@option{-dV} and @option{-fdump-rtl-vpt} enable dumping after the value
3722profile transformations, to @file{@var{file}.10.vpt}. @option{-dV}
3723and @option{-fdump-rtl-vartrack} enable dumping after variable tracking,
3724to @file{@var{file}.154r.vartrack}.
3725
3726@item -dw
3727@itemx -fdump-rtl-flow2
3728@opindex dw
3729@opindex fdump-rtl-flow2
3730Dump after the second flow pass, to @file{@var{file}.142r.flow2}.
3731
3732@item -dz
3733@itemx -fdump-rtl-peephole2
3734@opindex dz
3735@opindex fdump-rtl-peephole2
3736Dump after the peephole pass, to @file{@var{file}.145r.peephole2}.
3737
3738@item -dZ
3739@itemx -fdump-rtl-web
3740@opindex dZ
3741@opindex fdump-rtl-web
3742Dump after live range splitting, to @file{@var{file}.126r.web}.
3743
3744@item -da
3745@itemx -fdump-rtl-all
3746@opindex da
3747@opindex fdump-rtl-all
3748Produce all the dumps listed above.
3749
3750@item -dH
3751@opindex dH
3752Produce a core dump whenever an error occurs.
3753
3754@item -dm
3755@opindex dm
3756Print statistics on memory usage, at the end of the run, to
3757standard error.
3758
3759@item -dp
3760@opindex dp
3761Annotate the assembler output with a comment indicating which
3762pattern and alternative was used. The length of each instruction is
3763also printed.
3764
3765@item -dP
3766@opindex dP
3767Dump the RTL in the assembler output as a comment before each instruction.
3768Also turns on @option{-dp} annotation.
3769
3770@item -dv
3771@opindex dv
3772For each of the other indicated dump files (either with @option{-d} or
3773@option{-fdump-rtl-@var{pass}}), dump a representation of the control flow
3774graph suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
3775
3776@item -dx
3777@opindex dx
3778Just generate RTL for a function instead of compiling it. Usually used
3779with @samp{r} (@option{-fdump-rtl-expand}).
3780
3781@item -dy
3782@opindex dy
3783Dump debugging information during parsing, to standard error.
3784@end table
3785
3786@item -fdump-noaddr
3787@opindex fdump-noaddr
3788When doing debugging dumps (see @option{-d} option above), suppress
3789address output. This makes it more feasible to use diff on debugging
3790dumps for compiler invocations with different compiler binaries and/or
3791different text / bss / data / heap / stack / dso start locations.
3792
3793@item -fdump-unnumbered
3794@opindex fdump-unnumbered
3795When doing debugging dumps (see @option{-d} option above), suppress instruction
3796numbers, line number note and address output. This makes it more feasible to
3797use diff on debugging dumps for compiler invocations with different
3798options, in particular with and without @option{-g}.
3799
3800@item -fdump-translation-unit @r{(C++ only)}
3801@itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
3802@opindex fdump-translation-unit
3803Dump a representation of the tree structure for the entire translation
3804unit to a file. The file name is made by appending @file{.tu} to the
3805source file name. If the @samp{-@var{options}} form is used, @var{options}
3806controls the details of the dump as described for the
3807@option{-fdump-tree} options.
3808
3809@item -fdump-class-hierarchy @r{(C++ only)}
3810@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
3811@opindex fdump-class-hierarchy
3812Dump a representation of each class's hierarchy and virtual function
3813table layout to a file. The file name is made by appending @file{.class}
3814to the source file name. If the @samp{-@var{options}} form is used,
3815@var{options} controls the details of the dump as described for the
3816@option{-fdump-tree} options.
3817
3818@item -fdump-ipa-@var{switch}
3819@opindex fdump-ipa
3820Control the dumping at various stages of inter-procedural analysis
3821language tree to a file. The file name is generated by appending a switch
3822specific suffix to the source file name. The following dumps are possible:
3823
3824@table @samp
3825@item all
3826Enables all inter-procedural analysis dumps; currently the only produced
3827dump is the @samp{cgraph} dump.
3828
3829@item cgraph
3830Dumps information about call-graph optimization, unused function removal,
3831and inlining decisions.
3832@end table
3833
3834@item -fdump-tree-@var{switch}
3835@itemx -fdump-tree-@var{switch}-@var{options}
3836@opindex fdump-tree
3837Control the dumping at various stages of processing the intermediate
3838language tree to a file. The file name is generated by appending a switch
3839specific suffix to the source file name. If the @samp{-@var{options}}
3840form is used, @var{options} is a list of @samp{-} separated options that
3841control the details of the dump. Not all options are applicable to all
3842dumps, those which are not meaningful will be ignored. The following
3843options are available
3844
3845@table @samp
3846@item address
3847Print the address of each node. Usually this is not meaningful as it
3848changes according to the environment and source file. Its primary use
3849is for tying up a dump file with a debug environment.
3850@item slim
3851Inhibit dumping of members of a scope or body of a function merely
3852because that scope has been reached. Only dump such items when they
3853are directly reachable by some other path. When dumping pretty-printed
3854trees, this option inhibits dumping the bodies of control structures.
3855@item raw
3856Print a raw representation of the tree. By default, trees are
3857pretty-printed into a C-like representation.
3858@item details
3859Enable more detailed dumps (not honored by every dump option).
3860@item stats
3861Enable dumping various statistics about the pass (not honored by every dump
3862option).
3863@item blocks
3864Enable showing basic block boundaries (disabled in raw dumps).
3865@item vops
3866Enable showing virtual operands for every statement.
3867@item lineno
3868Enable showing line numbers for statements.
3869@item uid
3870Enable showing the unique ID (@code{DECL_UID}) for each variable.
3871@item all
3872Turn on all options, except @option{raw}, @option{slim} and @option{lineno}.
3873@end table
3874
3875The following tree dumps are possible:
3876@table @samp
3877
3878@item original
3879Dump before any tree based optimization, to @file{@var{file}.original}.
3880
3881@item optimized
3882Dump after all tree based optimization, to @file{@var{file}.optimized}.
3883
3884@item inlined
3885Dump after function inlining, to @file{@var{file}.inlined}.
3886
3887@item gimple
3888@opindex fdump-tree-gimple
3889Dump each function before and after the gimplification pass to a file. The
3890file name is made by appending @file{.gimple} to the source file name.
3891
3892@item cfg
3893@opindex fdump-tree-cfg
3894Dump the control flow graph of each function to a file. The file name is
3895made by appending @file{.cfg} to the source file name.
3896
3897@item vcg
3898@opindex fdump-tree-vcg
3899Dump the control flow graph of each function to a file in VCG format. The
3900file name is made by appending @file{.vcg} to the source file name. Note
3901that if the file contains more than one function, the generated file cannot
3902be used directly by VCG@. You will need to cut and paste each function's
3903graph into its own separate file first.
3904
3905@item ch
3906@opindex fdump-tree-ch
3907Dump each function after copying loop headers. The file name is made by
3908appending @file{.ch} to the source file name.
3909
3910@item ssa
3911@opindex fdump-tree-ssa
3912Dump SSA related information to a file. The file name is made by appending
3913@file{.ssa} to the source file name.
3914
3915@item salias
3916@opindex fdump-tree-salias
3917Dump structure aliasing variable information to a file. This file name
3918is made by appending @file{.salias} to the source file name.
3919
3920@item alias
3921@opindex fdump-tree-alias
3922Dump aliasing information for each function. The file name is made by
3923appending @file{.alias} to the source file name.
3924
3925@item ccp
3926@opindex fdump-tree-ccp
3927Dump each function after CCP@. The file name is made by appending
3928@file{.ccp} to the source file name.
3929
3930@item storeccp
3931@opindex fdump-tree-storeccp
3932Dump each function after STORE-CCP. The file name is made by appending
3933@file{.storeccp} to the source file name.
3934
3935@item pre
3936@opindex fdump-tree-pre
3937Dump trees after partial redundancy elimination. The file name is made
3938by appending @file{.pre} to the source file name.
3939
3940@item fre
3941@opindex fdump-tree-fre
3942Dump trees after full redundancy elimination. The file name is made
3943by appending @file{.fre} to the source file name.
3944
3945@item copyprop
3946@opindex fdump-tree-copyprop
3947Dump trees after copy propagation. The file name is made
3948by appending @file{.copyprop} to the source file name.
3949
3950@item store_copyprop
3951@opindex fdump-tree-store_copyprop
3952Dump trees after store copy-propagation. The file name is made
3953by appending @file{.store_copyprop} to the source file name.
3954
3955@item dce
3956@opindex fdump-tree-dce
3957Dump each function after dead code elimination. The file name is made by
3958appending @file{.dce} to the source file name.
3959
3960@item mudflap
3961@opindex fdump-tree-mudflap
3962Dump each function after adding mudflap instrumentation. The file name is
3963made by appending @file{.mudflap} to the source file name.
3964
3965@item sra
3966@opindex fdump-tree-sra
3967Dump each function after performing scalar replacement of aggregates. The
3968file name is made by appending @file{.sra} to the source file name.
3969
3970@item sink
3971@opindex fdump-tree-sink
3972Dump each function after performing code sinking. The file name is made
3973by appending @file{.sink} to the source file name.
3974
3975@item dom
3976@opindex fdump-tree-dom
3977Dump each function after applying dominator tree optimizations. The file
3978name is made by appending @file{.dom} to the source file name.
3979
3980@item dse
3981@opindex fdump-tree-dse
3982Dump each function after applying dead store elimination. The file
3983name is made by appending @file{.dse} to the source file name.
3984
3985@item phiopt
3986@opindex fdump-tree-phiopt
3987Dump each function after optimizing PHI nodes into straightline code. The file
3988name is made by appending @file{.phiopt} to the source file name.
3989
3990@item forwprop
3991@opindex fdump-tree-forwprop
3992Dump each function after forward propagating single use variables. The file
3993name is made by appending @file{.forwprop} to the source file name.
3994
3995@item copyrename
3996@opindex fdump-tree-copyrename
3997Dump each function after applying the copy rename optimization. The file
3998name is made by appending @file{.copyrename} to the source file name.
3999
4000@item nrv
4001@opindex fdump-tree-nrv
4002Dump each function after applying the named return value optimization on
4003generic trees. The file name is made by appending @file{.nrv} to the source
4004file name.
4005
4006@item vect
4007@opindex fdump-tree-vect
4008Dump each function after applying vectorization of loops. The file name is
4009made by appending @file{.vect} to the source file name.
4010
4011@item vrp
4012@opindex fdump-tree-vrp
4013Dump each function after Value Range Propagation (VRP). The file name
4014is made by appending @file{.vrp} to the source file name.
4015
4016@item all
4017@opindex fdump-tree-all
4018Enable all the available tree dumps with the flags provided in this option.
4019@end table
4020
4021@item -ftree-vectorizer-verbose=@var{n}
4022@opindex ftree-vectorizer-verbose
4023This option controls the amount of debugging output the vectorizer prints.
4024This information is written to standard error, unless
4025@option{-fdump-tree-all} or @option{-fdump-tree-vect} is specified,
4026in which case it is output to the usual dump listing file, @file{.vect}.
4027For @var{n}=0 no diagnostic information is reported.
4028If @var{n}=1 the vectorizer reports each loop that got vectorized,
4029and the total number of loops that got vectorized.
4030If @var{n}=2 the vectorizer also reports non-vectorized loops that passed
4031the first analysis phase (vect_analyze_loop_form) - i.e. countable,
4032inner-most, single-bb, single-entry/exit loops. This is the same verbosity
4033level that @option{-fdump-tree-vect-stats} uses.
4034Higher verbosity levels mean either more information dumped for each
4035reported loop, or same amount of information reported for more loops:
4036If @var{n}=3, alignment related information is added to the reports.
4037If @var{n}=4, data-references related information (e.g. memory dependences,
4038memory access-patterns) is added to the reports.
4039If @var{n}=5, the vectorizer reports also non-vectorized inner-most loops
4040that did not pass the first analysis phase (i.e. may not be countable, or
4041may have complicated control-flow).
4042If @var{n}=6, the vectorizer reports also non-vectorized nested loops.
4043For @var{n}=7, all the information the vectorizer generates during its
4044analysis and transformation is reported. This is the same verbosity level
4045that @option{-fdump-tree-vect-details} uses.
4046
4047@item -frandom-seed=@var{string}
4048@opindex frandom-string
4049This option provides a seed that GCC uses when it would otherwise use
4050random numbers. It is used to generate certain symbol names
4051that have to be different in every compiled file. It is also used to
4052place unique stamps in coverage data files and the object files that
4053produce them. You can use the @option{-frandom-seed} option to produce
4054reproducibly identical object files.
4055
4056The @var{string} should be different for every file you compile.
4057
4058@item -fsched-verbose=@var{n}
4059@opindex fsched-verbose
4060On targets that use instruction scheduling, this option controls the
4061amount of debugging output the scheduler prints. This information is
4062written to standard error, unless @option{-dS} or @option{-dR} is
4063specified, in which case it is output to the usual dump
4064listing file, @file{.sched} or @file{.sched2} respectively. However
4065for @var{n} greater than nine, the output is always printed to standard
4066error.
4067
4068For @var{n} greater than zero, @option{-fsched-verbose} outputs the
4069same information as @option{-dRS}. For @var{n} greater than one, it
4070also output basic block probabilities, detailed ready list information
4071and unit/insn info. For @var{n} greater than two, it includes RTL
4072at abort point, control-flow and regions info. And for @var{n} over
4073four, @option{-fsched-verbose} also includes dependence info.
4074
4075@item -save-temps
4076@opindex save-temps
4077Store the usual ``temporary'' intermediate files permanently; place them
4078in the current directory and name them based on the source file. Thus,
4079compiling @file{foo.c} with @samp{-c -save-temps} would produce files
4080@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
4081preprocessed @file{foo.i} output file even though the compiler now
4082normally uses an integrated preprocessor.
4083
4084When used in combination with the @option{-x} command line option,
4085@option{-save-temps} is sensible enough to avoid over writing an
4086input source file with the same extension as an intermediate file.
4087The corresponding intermediate file may be obtained by renaming the
4088source file before using @option{-save-temps}.
4089
4090@item -time
4091@opindex time
4092Report the CPU time taken by each subprocess in the compilation
4093sequence. For C source files, this is the compiler proper and assembler
4094(plus the linker if linking is done). The output looks like this:
4095
4096@smallexample
4097# cc1 0.12 0.01
4098# as 0.00 0.01
4099@end smallexample
4100
4101The first number on each line is the ``user time'', that is time spent
4102executing the program itself. The second number is ``system time'',
4103time spent executing operating system routines on behalf of the program.
4104Both numbers are in seconds.
4105
4106@item -fvar-tracking
4107@opindex fvar-tracking
4108Run variable tracking pass. It computes where variables are stored at each
4109position in code. Better debugging information is then generated
4110(if the debugging information format supports this information).
4111
4112It is enabled by default when compiling with optimization (@option{-Os},
4113@option{-O}, @option{-O2}, ...), debugging information (@option{-g}) and
4114the debug info format supports it.
4115
4116@item -print-file-name=@var{library}
4117@opindex print-file-name
4118Print the full absolute name of the library file @var{library} that
4119would be used when linking---and don't do anything else. With this
4120option, GCC does not compile or link anything; it just prints the
4121file name.
4122
4123@item -print-multi-directory
4124@opindex print-multi-directory
4125Print the directory name corresponding to the multilib selected by any
4126other switches present in the command line. This directory is supposed
4127to exist in @env{GCC_EXEC_PREFIX}.
4128
4129@item -print-multi-lib
4130@opindex print-multi-lib
4131Print the mapping from multilib directory names to compiler switches
4132that enable them. The directory name is separated from the switches by
4133@samp{;}, and each switch starts with an @samp{@@} instead of the
4134@samp{-}, without spaces between multiple switches. This is supposed to
4135ease shell-processing.
4136
4137@item -print-prog-name=@var{program}
4138@opindex print-prog-name
4139Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
4140
4141@item -print-libgcc-file-name
4142@opindex print-libgcc-file-name
4143Same as @option{-print-file-name=libgcc.a}.
4144
4145This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
4146but you do want to link with @file{libgcc.a}. You can do
4147
4148@smallexample
4149gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
4150@end smallexample
4151
4152@item -print-search-dirs
4153@opindex print-search-dirs
4154Print the name of the configured installation directory and a list of
4155program and library directories @command{gcc} will search---and don't do anything else.
4156
4157This is useful when @command{gcc} prints the error message
4158@samp{installation problem, cannot exec cpp0: No such file or directory}.
4159To resolve this you either need to put @file{cpp0} and the other compiler
4160components where @command{gcc} expects to find them, or you can set the environment
4161variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
4162Don't forget the trailing @samp{/}.
4163@xref{Environment Variables}.
4164
4165@item -dumpmachine
4166@opindex dumpmachine
4167Print the compiler's target machine (for example,
4168@samp{i686-pc-linux-gnu})---and don't do anything else.
4169
4170@item -dumpversion
4171@opindex dumpversion
4172Print the compiler version (for example, @samp{3.0})---and don't do
4173anything else.
4174
4175@item -dumpspecs
4176@opindex dumpspecs
4177Print the compiler's built-in specs---and don't do anything else. (This
4178is used when GCC itself is being built.) @xref{Spec Files}.
4179
4180@item -feliminate-unused-debug-types
4181@opindex feliminate-unused-debug-types
4182Normally, when producing DWARF2 output, GCC will emit debugging
4183information for all types declared in a compilation
4184unit, regardless of whether or not they are actually used
4185in that compilation unit. Sometimes this is useful, such as
4186if, in the debugger, you want to cast a value to a type that is
4187not actually used in your program (but is declared). More often,
4188however, this results in a significant amount of wasted space.
4189With this option, GCC will avoid producing debug symbol output
4190for types that are nowhere used in the source file being compiled.
4191@end table
4192
4193@node Optimize Options
4194@section Options That Control Optimization
4195@cindex optimize options
4196@cindex options, optimization
4197
4198These options control various sorts of optimizations.
4199
4200Without any optimization option, the compiler's goal is to reduce the
4201cost of compilation and to make debugging produce the expected
4202results. Statements are independent: if you stop the program with a
4203breakpoint between statements, you can then assign a new value to any
4204variable or change the program counter to any other statement in the
4205function and get exactly the results you would expect from the source
4206code.
4207
4208Turning on optimization flags makes the compiler attempt to improve
4209the performance and/or code size at the expense of compilation time
4210and possibly the ability to debug the program.
4211
4212The compiler performs optimization based on the knowledge it has of
4213the program. Optimization levels @option{-O} and above, in
4214particular, enable @emph{unit-at-a-time} mode, which allows the
4215compiler to consider information gained from later functions in
4216the file when compiling a function. Compiling multiple files at
4217once to a single output file in @emph{unit-at-a-time} mode allows
4218the compiler to use information gained from all of the files when
4219compiling each of them.
4220
4221Not all optimizations are controlled directly by a flag. Only
4222optimizations that have a flag are listed.
4223
4224@table @gcctabopt
4225@item -O
4226@itemx -O1
4227@opindex O
4228@opindex O1
4229Optimize. Optimizing compilation takes somewhat more time, and a lot
4230more memory for a large function.
4231
4232With @option{-O}, the compiler tries to reduce code size and execution
4233time, without performing any optimizations that take a great deal of
4234compilation time.
4235
4236@option{-O} turns on the following optimization flags:
4237@gccoptlist{-fdefer-pop @gol
4238-fdelayed-branch @gol
4239-fguess-branch-probability @gol
4240-fcprop-registers @gol
4241-fif-conversion @gol
4242-fif-conversion2 @gol
4243-ftree-ccp @gol
4244-ftree-dce @gol
4245-ftree-dominator-opts @gol
4246-ftree-dse @gol
4247-ftree-ter @gol
4248-ftree-lrs @gol
4249-ftree-sra @gol
4250-ftree-copyrename @gol
4251-ftree-fre @gol
4252-ftree-ch @gol
4253-funit-at-a-time @gol
4254-fmerge-constants}
4255
4256@option{-O} also turns on @option{-fomit-frame-pointer} on machines
4257where doing so does not interfere with debugging.
4258
4259@item -O2
4260@opindex O2
4261Optimize even more. GCC performs nearly all supported optimizations
4262that do not involve a space-speed tradeoff. The compiler does not
4263perform loop unrolling or function inlining when you specify @option{-O2}.
4264As compared to @option{-O}, this option increases both compilation time
4265and the performance of the generated code.
4266
4267@option{-O2} turns on all optimization flags specified by @option{-O}. It
4268also turns on the following optimization flags:
4269@gccoptlist{-fthread-jumps @gol
4270-fcrossjumping @gol
4271-foptimize-sibling-calls @gol
4272-fcse-follow-jumps -fcse-skip-blocks @gol
4273-fgcse -fgcse-lm @gol
4274-fexpensive-optimizations @gol
4275-frerun-cse-after-loop @gol
4276-fcaller-saves @gol
4277-fpeephole2 @gol
4278-fschedule-insns -fschedule-insns2 @gol
4279-fsched-interblock -fsched-spec @gol
4280-fregmove @gol
4281-fstrict-aliasing -fstrict-overflow @gol
4282-fdelete-null-pointer-checks @gol
4283-freorder-blocks -freorder-functions @gol
4284-falign-functions -falign-jumps @gol
4285-falign-loops -falign-labels @gol
4286-ftree-vrp @gol
4287-ftree-pre}
4288
4289Please note the warning under @option{-fgcse} about
4290invoking @option{-O2} on programs that use computed gotos.
4291
4292@option{-O2} doesn't turn on @option{-ftree-vrp} for the Ada compiler.
4293This option must be explicitly specified on the command line to be
4294enabled for the Ada compiler.
4295
4296@item -O3
4297@opindex O3
4298Optimize yet more. @option{-O3} turns on all optimizations specified by
4299@option{-O2} and also turns on the @option{-finline-functions},
4300@option{-funswitch-loops} and @option{-fgcse-after-reload} options.
4301
4302@item -O0
4303@opindex O0
4304Do not optimize. This is the default.
4305
4306@item -Os
4307@opindex Os
4308Optimize for size. @option{-Os} enables all @option{-O2} optimizations that
4309do not typically increase code size. It also performs further
4310optimizations designed to reduce code size.
4311
4312@option{-Os} disables the following optimization flags:
4313@gccoptlist{-falign-functions -falign-jumps -falign-loops @gol
4314-falign-labels -freorder-blocks -freorder-blocks-and-partition @gol
4315-fprefetch-loop-arrays -ftree-vect-loop-version}
4316
4317If you use multiple @option{-O} options, with or without level numbers,
4318the last such option is the one that is effective.
4319@end table
4320
4321Options of the form @option{-f@var{flag}} specify machine-independent
4322flags. Most flags have both positive and negative forms; the negative
4323form of @option{-ffoo} would be @option{-fno-foo}. In the table
4324below, only one of the forms is listed---the one you typically will
4325use. You can figure out the other form by either removing @samp{no-}
4326or adding it.
4327
4328The following options control specific optimizations. They are either
4329activated by @option{-O} options or are related to ones that are. You
4330can use the following flags in the rare cases when ``fine-tuning'' of
4331optimizations to be performed is desired.
4332
4333@table @gcctabopt
4334@item -fno-default-inline
4335@opindex fno-default-inline
4336Do not make member functions inline by default merely because they are
4337defined inside the class scope (C++ only). Otherwise, when you specify
4338@w{@option{-O}}, member functions defined inside class scope are compiled
4339inline by default; i.e., you don't need to add @samp{inline} in front of
4340the member function name.
4341
4342@item -fno-defer-pop
4343@opindex fno-defer-pop
4344Always pop the arguments to each function call as soon as that function
4345returns. For machines which must pop arguments after a function call,
4346the compiler normally lets arguments accumulate on the stack for several
4347function calls and pops them all at once.
4348
4349Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4350
4351@item -fforce-mem
4352@opindex fforce-mem
4353Force memory operands to be copied into registers before doing
4354arithmetic on them. This produces better code by making all memory
4355references potential common subexpressions. When they are not common
4356subexpressions, instruction combination should eliminate the separate
4357register-load. This option is now a nop and will be removed in 4.3.
4358
4359@item -fforce-addr
4360@opindex fforce-addr
4361Force memory address constants to be copied into registers before
4362doing arithmetic on them.
4363
4364@item -fomit-frame-pointer
4365@opindex fomit-frame-pointer
4366Don't keep the frame pointer in a register for functions that
4367don't need one. This avoids the instructions to save, set up and
4368restore frame pointers; it also makes an extra register available
4369in many functions. @strong{It also makes debugging impossible on
4370some machines.}
4371
4372On some machines, such as the VAX, this flag has no effect, because
4373the standard calling sequence automatically handles the frame pointer
4374and nothing is saved by pretending it doesn't exist. The
4375machine-description macro @code{FRAME_POINTER_REQUIRED} controls
4376whether a target machine supports this flag. @xref{Registers,,Register
4377Usage, gccint, GNU Compiler Collection (GCC) Internals}.
4378
4379Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4380
4381@item -foptimize-sibling-calls
4382@opindex foptimize-sibling-calls
4383Optimize sibling and tail recursive calls.
4384
4385Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4386
4387@item -fno-inline
4388@opindex fno-inline
4389Don't pay attention to the @code{inline} keyword. Normally this option
4390is used to keep the compiler from expanding any functions inline.
4391Note that if you are not optimizing, no functions can be expanded inline.
4392
4393@item -finline-functions
4394@opindex finline-functions
4395Integrate all simple functions into their callers. The compiler
4396heuristically decides which functions are simple enough to be worth
4397integrating in this way.
4398
4399If all calls to a given function are integrated, and the function is
4400declared @code{static}, then the function is normally not output as
4401assembler code in its own right.
4402
4403Enabled at level @option{-O3}.
4404
4405@item -finline-functions-called-once
4406@opindex finline-functions-called-once
4407Consider all @code{static} functions called once for inlining into their
4408caller even if they are not marked @code{inline}. If a call to a given
4409function is integrated, then the function is not output as assembler code
4410in its own right.
4411
4412Enabled if @option{-funit-at-a-time} is enabled.
4413
4414@item -fearly-inlining
4415@opindex fearly-inlining
4416Inline functions marked by @code{always_inline} and functions whose body seems
4417smaller than the function call overhead early before doing
4418@option{-fprofile-generate} instrumentation and real inlining pass. Doing so
4419makes profiling significantly cheaper and usually inlining faster on programs
4420having large chains of nested wrapper functions.
4421
4422Enabled by default.
4423
4424@item -finline-limit=@var{n}
4425@opindex finline-limit
4426By default, GCC limits the size of functions that can be inlined. This flag
4427allows the control of this limit for functions that are explicitly marked as
4428inline (i.e., marked with the inline keyword or defined within the class
4429definition in c++). @var{n} is the size of functions that can be inlined in
4430number of pseudo instructions (not counting parameter handling). The default
4431value of @var{n} is 600.
4432Increasing this value can result in more inlined code at
4433the cost of compilation time and memory consumption. Decreasing usually makes
4434the compilation faster and less code will be inlined (which presumably
4435means slower programs). This option is particularly useful for programs that
4436use inlining heavily such as those based on recursive templates with C++.
4437
4438Inlining is actually controlled by a number of parameters, which may be
4439specified individually by using @option{--param @var{name}=@var{value}}.
4440The @option{-finline-limit=@var{n}} option sets some of these parameters
4441as follows:
4442
4443@table @gcctabopt
4444@item max-inline-insns-single
4445 is set to @var{n}/2.
4446@item max-inline-insns-auto
4447 is set to @var{n}/2.
4448@item min-inline-insns
4449 is set to 130 or @var{n}/4, whichever is smaller.
4450@item max-inline-insns-rtl
4451 is set to @var{n}.
4452@end table
4453
4454See below for a documentation of the individual
4455parameters controlling inlining.
4456
4457@emph{Note:} pseudo instruction represents, in this particular context, an
4458abstract measurement of function's size. In no way does it represent a count
4459of assembly instructions and as such its exact meaning might change from one
4460release to an another.
4461
4462@item -fkeep-inline-functions
4463@opindex fkeep-inline-functions
4464In C, emit @code{static} functions that are declared @code{inline}
4465into the object file, even if the function has been inlined into all
4466of its callers. This switch does not affect functions using the
4467@code{extern inline} extension in GNU C@. In C++, emit any and all
4468inline functions into the object file.
4469
4470@item -fkeep-static-consts
4471@opindex fkeep-static-consts
4472Emit variables declared @code{static const} when optimization isn't turned
4473on, even if the variables aren't referenced.
4474
4475GCC enables this option by default. If you want to force the compiler to
4476check if the variable was referenced, regardless of whether or not
4477optimization is turned on, use the @option{-fno-keep-static-consts} option.
4478
4479@item -fmerge-constants
4480Attempt to merge identical constants (string constants and floating point
4481constants) across compilation units.
4482
4483This option is the default for optimized compilation if the assembler and
4484linker support it. Use @option{-fno-merge-constants} to inhibit this
4485behavior.
4486
4487Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4488
4489@item -fmerge-all-constants
4490Attempt to merge identical constants and identical variables.
4491
4492This option implies @option{-fmerge-constants}. In addition to
4493@option{-fmerge-constants} this considers e.g.@: even constant initialized
4494arrays or initialized constant variables with integral or floating point
4495types. Languages like C or C++ require each non-automatic variable to
4496have distinct location, so using this option will result in non-conforming
4497behavior.
4498
4499@item -fmodulo-sched
4500@opindex fmodulo-sched
4501Perform swing modulo scheduling immediately before the first scheduling
4502pass. This pass looks at innermost loops and reorders their
4503instructions by overlapping different iterations.
4504
4505@item -fno-branch-count-reg
4506@opindex fno-branch-count-reg
4507Do not use ``decrement and branch'' instructions on a count register,
4508but instead generate a sequence of instructions that decrement a
4509register, compare it against zero, then branch based upon the result.
4510This option is only meaningful on architectures that support such
4511instructions, which include x86, PowerPC, IA-64 and S/390.
4512
4513The default is @option{-fbranch-count-reg}.
4514
4515@item -fno-function-cse
4516@opindex fno-function-cse
4517Do not put function addresses in registers; make each instruction that
4518calls a constant function contain the function's address explicitly.
4519
4520This option results in less efficient code, but some strange hacks
4521that alter the assembler output may be confused by the optimizations
4522performed when this option is not used.
4523
4524The default is @option{-ffunction-cse}
4525
4526@item -fno-zero-initialized-in-bss
4527@opindex fno-zero-initialized-in-bss
4528If the target supports a BSS section, GCC by default puts variables that
4529are initialized to zero into BSS@. This can save space in the resulting
4530code.
4531
4532This option turns off this behavior because some programs explicitly
4533rely on variables going to the data section. E.g., so that the
4534resulting executable can find the beginning of that section and/or make
4535assumptions based on that.
4536
4537The default is @option{-fzero-initialized-in-bss}.
4538
4539@item -fbounds-check
4540@opindex fbounds-check
4541For front-ends that support it, generate additional code to check that
4542indices used to access arrays are within the declared range. This is
4543currently only supported by the Java and Fortran front-ends, where
4544this option defaults to true and false respectively.
4545
4546@item -fmudflap -fmudflapth -fmudflapir
4547@opindex fmudflap
4548@opindex fmudflapth
4549@opindex fmudflapir
4550@cindex bounds checking
4551@cindex mudflap
4552For front-ends that support it (C and C++), instrument all risky
4553pointer/array dereferencing operations, some standard library
4554string/heap functions, and some other associated constructs with
4555range/validity tests. Modules so instrumented should be immune to
4556buffer overflows, invalid heap use, and some other classes of C/C++
4557programming errors. The instrumentation relies on a separate runtime
4558library (@file{libmudflap}), which will be linked into a program if
4559@option{-fmudflap} is given at link time. Run-time behavior of the
4560instrumented program is controlled by the @env{MUDFLAP_OPTIONS}
4561environment variable. See @code{env MUDFLAP_OPTIONS=-help a.out}
4562for its options.
4563
4564Use @option{-fmudflapth} instead of @option{-fmudflap} to compile and to
4565link if your program is multi-threaded. Use @option{-fmudflapir}, in
4566addition to @option{-fmudflap} or @option{-fmudflapth}, if
4567instrumentation should ignore pointer reads. This produces less
4568instrumentation (and therefore faster execution) and still provides
4569some protection against outright memory corrupting writes, but allows
4570erroneously read data to propagate within a program.
4571
4572@item -fthread-jumps
4573@opindex fthread-jumps
4574Perform optimizations where we check to see if a jump branches to a
4575location where another comparison subsumed by the first is found. If
4576so, the first branch is redirected to either the destination of the
4577second branch or a point immediately following it, depending on whether
4578the condition is known to be true or false.
4579
4580Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4581
4582@item -fcse-follow-jumps
4583@opindex fcse-follow-jumps
4584In common subexpression elimination, scan through jump instructions
4585when the target of the jump is not reached by any other path. For
4586example, when CSE encounters an @code{if} statement with an
4587@code{else} clause, CSE will follow the jump when the condition
4588tested is false.
4589
4590Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4591
4592@item -fcse-skip-blocks
4593@opindex fcse-skip-blocks
4594This is similar to @option{-fcse-follow-jumps}, but causes CSE to
4595follow jumps which conditionally skip over blocks. When CSE
4596encounters a simple @code{if} statement with no else clause,
4597@option{-fcse-skip-blocks} causes CSE to follow the jump around the
4598body of the @code{if}.
4599
4600Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4601
4602@item -frerun-cse-after-loop
4603@opindex frerun-cse-after-loop
4604Re-run common subexpression elimination after loop optimizations has been
4605performed.
4606
4607Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4608
4609@item -fgcse
4610@opindex fgcse
4611Perform a global common subexpression elimination pass.
4612This pass also performs global constant and copy propagation.
4613
4614@emph{Note:} When compiling a program using computed gotos, a GCC
4615extension, you may get better runtime performance if you disable
4616the global common subexpression elimination pass by adding
4617@option{-fno-gcse} to the command line.
4618
4619Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4620
4621@item -fgcse-lm
4622@opindex fgcse-lm
4623When @option{-fgcse-lm} is enabled, global common subexpression elimination will
4624attempt to move loads which are only killed by stores into themselves. This
4625allows a loop containing a load/store sequence to be changed to a load outside
4626the loop, and a copy/store within the loop.
4627
4628Enabled by default when gcse is enabled.
4629
4630@item -fgcse-sm
4631@opindex fgcse-sm
4632When @option{-fgcse-sm} is enabled, a store motion pass is run after
4633global common subexpression elimination. This pass will attempt to move
4634stores out of loops. When used in conjunction with @option{-fgcse-lm},
4635loops containing a load/store sequence can be changed to a load before
4636the loop and a store after the loop.
4637
4638Not enabled at any optimization level.
4639
4640@item -fgcse-las
4641@opindex fgcse-las
4642When @option{-fgcse-las} is enabled, the global common subexpression
4643elimination pass eliminates redundant loads that come after stores to the
4644same memory location (both partial and full redundancies).
4645
4646Not enabled at any optimization level.
4647
4648@item -fgcse-after-reload
4649@opindex fgcse-after-reload
4650When @option{-fgcse-after-reload} is enabled, a redundant load elimination
4651pass is performed after reload. The purpose of this pass is to cleanup
4652redundant spilling.
4653
4654@item -funsafe-loop-optimizations
4655@opindex funsafe-loop-optimizations
4656If given, the loop optimizer will assume that loop indices do not
4657overflow, and that the loops with nontrivial exit condition are not
4658infinite. This enables a wider range of loop optimizations even if
4659the loop optimizer itself cannot prove that these assumptions are valid.
4660Using @option{-Wunsafe-loop-optimizations}, the compiler will warn you
4661if it finds this kind of loop.
4662
4663@item -fcrossjumping
4664@opindex crossjumping
4665Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
4666resulting code may or may not perform better than without cross-jumping.
4667
4668Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4669
4670@item -fif-conversion
4671@opindex if-conversion
4672Attempt to transform conditional jumps into branch-less equivalents. This
4673include use of conditional moves, min, max, set flags and abs instructions, and
4674some tricks doable by standard arithmetics. The use of conditional execution
4675on chips where it is available is controlled by @code{if-conversion2}.
4676
4677Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4678
4679@item -fif-conversion2
4680@opindex if-conversion2
4681Use conditional execution (where available) to transform conditional jumps into
4682branch-less equivalents.
4683
4684Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4685
4686@item -fdelete-null-pointer-checks
4687@opindex fdelete-null-pointer-checks
4688Use global dataflow analysis to identify and eliminate useless checks
4689for null pointers. The compiler assumes that dereferencing a null
4690pointer would have halted the program. If a pointer is checked after
4691it has already been dereferenced, it cannot be null.
4692
4693In some environments, this assumption is not true, and programs can
4694safely dereference null pointers. Use
4695@option{-fno-delete-null-pointer-checks} to disable this optimization
4696for programs which depend on that behavior.
4697
4698Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4699
4700@item -fexpensive-optimizations
4701@opindex fexpensive-optimizations
4702Perform a number of minor optimizations that are relatively expensive.
4703
4704Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4705
4706@item -foptimize-register-move
4707@itemx -fregmove
4708@opindex foptimize-register-move
4709@opindex fregmove
4710Attempt to reassign register numbers in move instructions and as
4711operands of other simple instructions in order to maximize the amount of
4712register tying. This is especially helpful on machines with two-operand
4713instructions.
4714
4715Note @option{-fregmove} and @option{-foptimize-register-move} are the same
4716optimization.
4717
4718Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4719
4720@item -fdelayed-branch
4721@opindex fdelayed-branch
4722If supported for the target machine, attempt to reorder instructions
4723to exploit instruction slots available after delayed branch
4724instructions.
4725
4726Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4727
4728@item -fschedule-insns
4729@opindex fschedule-insns
4730If supported for the target machine, attempt to reorder instructions to
4731eliminate execution stalls due to required data being unavailable. This
4732helps machines that have slow floating point or memory load instructions
4733by allowing other instructions to be issued until the result of the load
4734or floating point instruction is required.
4735
4736Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4737
4738@item -fschedule-insns2
4739@opindex fschedule-insns2
4740Similar to @option{-fschedule-insns}, but requests an additional pass of
4741instruction scheduling after register allocation has been done. This is
4742especially useful on machines with a relatively small number of
4743registers and where memory load instructions take more than one cycle.
4744
4745Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4746
4747@item -fno-sched-interblock
4748@opindex fno-sched-interblock
4749Don't schedule instructions across basic blocks. This is normally
4750enabled by default when scheduling before register allocation, i.e.@:
4751with @option{-fschedule-insns} or at @option{-O2} or higher.
4752
4753@item -fno-sched-spec
4754@opindex fno-sched-spec
4755Don't allow speculative motion of non-load instructions. This is normally
4756enabled by default when scheduling before register allocation, i.e.@:
4757with @option{-fschedule-insns} or at @option{-O2} or higher.
4758
4759@item -fsched-spec-load
4760@opindex fsched-spec-load
4761Allow speculative motion of some load instructions. This only makes
4762sense when scheduling before register allocation, i.e.@: with
4763@option{-fschedule-insns} or at @option{-O2} or higher.
4764
4765@item -fsched-spec-load-dangerous
4766@opindex fsched-spec-load-dangerous
4767Allow speculative motion of more load instructions. This only makes
4768sense when scheduling before register allocation, i.e.@: with
4769@option{-fschedule-insns} or at @option{-O2} or higher.
4770
4771@item -fsched-stalled-insns=@var{n}
4772@opindex fsched-stalled-insns
4773Define how many insns (if any) can be moved prematurely from the queue
4774of stalled insns into the ready list, during the second scheduling pass.
4775
4776@item -fsched-stalled-insns-dep=@var{n}
4777@opindex fsched-stalled-insns-dep
4778Define how many insn groups (cycles) will be examined for a dependency
4779on a stalled insn that is candidate for premature removal from the queue
4780of stalled insns. Has an effect only during the second scheduling pass,
4781and only if @option{-fsched-stalled-insns} is used and its value is not zero.
4782
4783@item -fsched2-use-superblocks
4784@opindex fsched2-use-superblocks
4785When scheduling after register allocation, do use superblock scheduling
4786algorithm. Superblock scheduling allows motion across basic block boundaries
4787resulting on faster schedules. This option is experimental, as not all machine
4788descriptions used by GCC model the CPU closely enough to avoid unreliable
4789results from the algorithm.
4790
4791This only makes sense when scheduling after register allocation, i.e.@: with
4792@option{-fschedule-insns2} or at @option{-O2} or higher.
4793
4794@item -fsched2-use-traces
4795@opindex fsched2-use-traces
4796Use @option{-fsched2-use-superblocks} algorithm when scheduling after register
4797allocation and additionally perform code duplication in order to increase the
4798size of superblocks using tracer pass. See @option{-ftracer} for details on
4799trace formation.
4800
4801This mode should produce faster but significantly longer programs. Also
4802without @option{-fbranch-probabilities} the traces constructed may not
4803match the reality and hurt the performance. This only makes
4804sense when scheduling after register allocation, i.e.@: with
4805@option{-fschedule-insns2} or at @option{-O2} or higher.
4806
4807@item -fsee
4808@opindex fsee
4809Eliminates redundant extension instructions and move the non redundant
4810ones to optimal placement using LCM.
4811
4812@item -freschedule-modulo-scheduled-loops
4813@opindex fscheduling-in-modulo-scheduled-loops
4814The modulo scheduling comes before the traditional scheduling, if a loop was modulo scheduled
4815we may want to prevent the later scheduling passes from changing its schedule, we use this
4816option to control that.
4817
4818@item -fcaller-saves
4819@opindex fcaller-saves
4820Enable values to be allocated in registers that will be clobbered by
4821function calls, by emitting extra instructions to save and restore the
4822registers around such calls. Such allocation is done only when it
4823seems to result in better code than would otherwise be produced.
4824
4825This option is always enabled by default on certain machines, usually
4826those which have no call-preserved registers to use instead.
4827
4828Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4829
4830@item -ftree-pre
4831Perform Partial Redundancy Elimination (PRE) on trees. This flag is
4832enabled by default at @option{-O2} and @option{-O3}.
4833
4834@item -ftree-fre
4835Perform Full Redundancy Elimination (FRE) on trees. The difference
4836between FRE and PRE is that FRE only considers expressions
4837that are computed on all paths leading to the redundant computation.
4838This analysis faster than PRE, though it exposes fewer redundancies.
4839This flag is enabled by default at @option{-O} and higher.
4840
4841@item -ftree-copy-prop
4842Perform copy propagation on trees. This pass eliminates unnecessary
4843copy operations. This flag is enabled by default at @option{-O} and
4844higher.
4845
4846@item -ftree-store-copy-prop
4847Perform copy propagation of memory loads and stores. This pass
4848eliminates unnecessary copy operations in memory references
4849(structures, global variables, arrays, etc). This flag is enabled by
4850default at @option{-O2} and higher.
4851
4852@item -ftree-salias
4853Perform structural alias analysis on trees. This flag
4854is enabled by default at @option{-O} and higher.
4855
4856@item -fipa-pta
4857Perform interprocedural pointer analysis.
4858
4859@item -ftree-sink
4860Perform forward store motion on trees. This flag is
4861enabled by default at @option{-O} and higher.
4862
4863@item -ftree-ccp
4864Perform sparse conditional constant propagation (CCP) on trees. This
4865pass only operates on local scalar variables and is enabled by default
4866at @option{-O} and higher.
4867
4868@item -ftree-store-ccp
4869Perform sparse conditional constant propagation (CCP) on trees. This
4870pass operates on both local scalar variables and memory stores and
4871loads (global variables, structures, arrays, etc). This flag is
4872enabled by default at @option{-O2} and higher.
4873
4874@item -ftree-dce
4875Perform dead code elimination (DCE) on trees. This flag is enabled by
4876default at @option{-O} and higher.
4877
4878@item -ftree-dominator-opts
4879Perform a variety of simple scalar cleanups (constant/copy
4880propagation, redundancy elimination, range propagation and expression
4881simplification) based on a dominator tree traversal. This also
4882performs jump threading (to reduce jumps to jumps). This flag is
4883enabled by default at @option{-O} and higher.
4884
4885@item -ftree-ch
4886Perform loop header copying on trees. This is beneficial since it increases
4887effectiveness of code motion optimizations. It also saves one jump. This flag
4888is enabled by default at @option{-O} and higher. It is not enabled
4889for @option{-Os}, since it usually increases code size.
4890
4891@item -ftree-loop-optimize
4892Perform loop optimizations on trees. This flag is enabled by default
4893at @option{-O} and higher.
4894
4895@item -ftree-loop-linear
4896Perform linear loop transformations on tree. This flag can improve cache
4897performance and allow further loop optimizations to take place.
4898
4899@item -ftree-loop-im
4900Perform loop invariant motion on trees. This pass moves only invariants that
4901would be hard to handle at RTL level (function calls, operations that expand to
4902nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
4903operands of conditions that are invariant out of the loop, so that we can use
4904just trivial invariantness analysis in loop unswitching. The pass also includes
4905store motion.
4906
4907@item -ftree-loop-ivcanon
4908Create a canonical counter for number of iterations in the loop for that
4909determining number of iterations requires complicated analysis. Later
4910optimizations then may determine the number easily. Useful especially
4911in connection with unrolling.
4912
4913@item -fivopts
4914Perform induction variable optimizations (strength reduction, induction
4915variable merging and induction variable elimination) on trees.
4916
4917@item -ftree-sra
4918Perform scalar replacement of aggregates. This pass replaces structure
4919references with scalars to prevent committing structures to memory too
4920early. This flag is enabled by default at @option{-O} and higher.
4921
4922@item -ftree-copyrename
4923Perform copy renaming on trees. This pass attempts to rename compiler
4924temporaries to other variables at copy locations, usually resulting in
4925variable names which more closely resemble the original variables. This flag
4926is enabled by default at @option{-O} and higher.
4927
4928@item -ftree-ter
4929Perform temporary expression replacement during the SSA->normal phase. Single
4930use/single def temporaries are replaced at their use location with their
4931defining expression. This results in non-GIMPLE code, but gives the expanders
4932much more complex trees to work on resulting in better RTL generation. This is
4933enabled by default at @option{-O} and higher.
4934
4935@item -ftree-lrs
4936Perform live range splitting during the SSA->normal phase. Distinct live
4937ranges of a variable are split into unique variables, allowing for better
4938optimization later. This is enabled by default at @option{-O} and higher.
4939
4940@item -ftree-vectorize
4941Perform loop vectorization on trees.
4942
4943@item -ftree-vect-loop-version
4944@opindex ftree-vect-loop-version
4945Perform loop versioning when doing loop vectorization on trees. When a loop
4946appears to be vectorizable except that data alignment or data dependence cannot
4947be determined at compile time then vectorized and non-vectorized versions of
4948the loop are generated along with runtime checks for alignment or dependence
4949to control which version is executed. This option is enabled by default
4950except at level @option{-Os} where it is disabled.
4951
4952@item -ftree-vrp
4953Perform Value Range Propagation on trees. This is similar to the
4954constant propagation pass, but instead of values, ranges of values are
4955propagated. This allows the optimizers to remove unnecessary range
4956checks like array bound checks and null pointer checks. This is
4957enabled by default at @option{-O2} and higher. Null pointer check
4958elimination is only done if @option{-fdelete-null-pointer-checks} is
4959enabled.
4960
4961@item -ftracer
4962@opindex ftracer
4963Perform tail duplication to enlarge superblock size. This transformation
4964simplifies the control flow of the function allowing other optimizations to do
4965better job.
4966
4967@item -funroll-loops
4968@opindex funroll-loops
4969Unroll loops whose number of iterations can be determined at compile
4970time or upon entry to the loop. @option{-funroll-loops} implies
4971@option{-frerun-cse-after-loop}. This option makes code larger,
4972and may or may not make it run faster.
4973
4974@item -funroll-all-loops
4975@opindex funroll-all-loops
4976Unroll all loops, even if their number of iterations is uncertain when
4977the loop is entered. This usually makes programs run more slowly.
4978@option{-funroll-all-loops} implies the same options as
4979@option{-funroll-loops},
4980
4981@item -fsplit-ivs-in-unroller
4982@opindex fsplit-ivs-in-unroller
4983Enables expressing of values of induction variables in later iterations
4984of the unrolled loop using the value in the first iteration. This breaks
4985long dependency chains, thus improving efficiency of the scheduling passes.
4986
4987Combination of @option{-fweb} and CSE is often sufficient to obtain the
4988same effect. However in cases the loop body is more complicated than
4989a single basic block, this is not reliable. It also does not work at all
4990on some of the architectures due to restrictions in the CSE pass.
4991
4992This optimization is enabled by default.
4993
4994@item -fvariable-expansion-in-unroller
4995@opindex fvariable-expansion-in-unroller
4996With this option, the compiler will create multiple copies of some
4997local variables when unrolling a loop which can result in superior code.
4998
4999@item -fprefetch-loop-arrays
5000@opindex fprefetch-loop-arrays
5001If supported by the target machine, generate instructions to prefetch
5002memory to improve the performance of loops that access large arrays.
5003
5004This option may generate better or worse code; results are highly
5005dependent on the structure of loops within the source code.
5006
5007Disabled at level @option{-Os}.
5008
5009@item -fno-peephole
5010@itemx -fno-peephole2
5011@opindex fno-peephole
5012@opindex fno-peephole2
5013Disable any machine-specific peephole optimizations. The difference
5014between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
5015are implemented in the compiler; some targets use one, some use the
5016other, a few use both.
5017
5018@option{-fpeephole} is enabled by default.
5019@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5020
5021@item -fno-guess-branch-probability
5022@opindex fno-guess-branch-probability
5023Do not guess branch probabilities using heuristics.
5024
5025GCC will use heuristics to guess branch probabilities if they are
5026not provided by profiling feedback (@option{-fprofile-arcs}). These
5027heuristics are based on the control flow graph. If some branch probabilities
5028are specified by @samp{__builtin_expect}, then the heuristics will be
5029used to guess branch probabilities for the rest of the control flow graph,
5030taking the @samp{__builtin_expect} info into account. The interactions
5031between the heuristics and @samp{__builtin_expect} can be complex, and in
5032some cases, it may be useful to disable the heuristics so that the effects
5033of @samp{__builtin_expect} are easier to understand.
5034
5035The default is @option{-fguess-branch-probability} at levels
5036@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5037
5038@item -freorder-blocks
5039@opindex freorder-blocks
5040Reorder basic blocks in the compiled function in order to reduce number of
5041taken branches and improve code locality.
5042
5043Enabled at levels @option{-O2}, @option{-O3}.
5044
5045@item -freorder-blocks-and-partition
5046@opindex freorder-blocks-and-partition
5047In addition to reordering basic blocks in the compiled function, in order
5048to reduce number of taken branches, partitions hot and cold basic blocks
5049into separate sections of the assembly and .o files, to improve
5050paging and cache locality performance.
5051
5052This optimization is automatically turned off in the presence of
5053exception handling, for linkonce sections, for functions with a user-defined
5054section attribute and on any architecture that does not support named
5055sections.
5056
5057@item -freorder-functions
5058@opindex freorder-functions
5059Reorder functions in the object file in order to
5060improve code locality. This is implemented by using special
5061subsections @code{.text.hot} for most frequently executed functions and
5062@code{.text.unlikely} for unlikely executed functions. Reordering is done by
5063the linker so object file format must support named sections and linker must
5064place them in a reasonable way.
5065
5066Also profile feedback must be available in to make this option effective. See
5067@option{-fprofile-arcs} for details.
5068
5069Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5070
5071@item -fstrict-aliasing
5072@opindex fstrict-aliasing
5073Allows the compiler to assume the strictest aliasing rules applicable to
5074the language being compiled. For C (and C++), this activates
5075optimizations based on the type of expressions. In particular, an
5076object of one type is assumed never to reside at the same address as an
5077object of a different type, unless the types are almost the same. For
5078example, an @code{unsigned int} can alias an @code{int}, but not a
5079@code{void*} or a @code{double}. A character type may alias any other
5080type.
5081
5082Pay special attention to code like this:
5083@smallexample
5084union a_union @{
5085 int i;
5086 double d;
5087@};
5088
5089int f() @{
5090 a_union t;
5091 t.d = 3.0;
5092 return t.i;
5093@}
5094@end smallexample
5095The practice of reading from a different union member than the one most
5096recently written to (called ``type-punning'') is common. Even with
5097@option{-fstrict-aliasing}, type-punning is allowed, provided the memory
5098is accessed through the union type. So, the code above will work as
5099expected. However, this code might not:
5100@smallexample
5101int f() @{
5102 a_union t;
5103 int* ip;
5104 t.d = 3.0;
5105 ip = &t.i;
5106 return *ip;
5107@}
5108@end smallexample
5109
5110Every language that wishes to perform language-specific alias analysis
5111should define a function that computes, given an @code{tree}
5112node, an alias set for the node. Nodes in different alias sets are not
5113allowed to alias. For an example, see the C front-end function
5114@code{c_get_alias_set}.
5115
5116Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5117
5118@item -fstrict-overflow
5119@opindex fstrict-overflow
5120Allow the compiler to assume strict signed overflow rules, depending
5121on the language being compiled. For C (and C++) this means that
5122overflow when doing arithmetic with signed numbers is undefined, which
5123means that the compiler may assume that it will not happen. This
5124permits various optimizations. For example, the compiler will assume
5125that an expression like @code{i + 10 > i} will always be true for
5126signed @code{i}. This assumption is only valid if signed overflow is
5127undefined, as the expression is false if @code{i + 10} overflows when
5128using twos complement arithmetic. When this option is in effect any
5129attempt to determine whether an operation on signed numbers will
5130overflow must be written carefully to not actually involve overflow.
5131
5132See also the @option{-fwrapv} option. Using @option{-fwrapv} means
5133that signed overflow is fully defined: it wraps. When
5134@option{-fwrapv} is used, there is no difference between
5135@option{-fstrict-overflow} and @option{-fno-strict-overflow}. With
5136@option{-fwrapv} certain types of overflow are permitted. For
5137example, if the compiler gets an overflow when doing arithmetic on
5138constants, the overflowed value can still be used with
5139@option{-fwrapv}, but not otherwise.
5140
5141The @option{-fstrict-overflow} option is enabled at levels
5142@option{-O2}, @option{-O3}, @option{-Os}.
5143
5144@item -falign-functions
5145@itemx -falign-functions=@var{n}
5146@opindex falign-functions
5147Align the start of functions to the next power-of-two greater than
5148@var{n}, skipping up to @var{n} bytes. For instance,
5149@option{-falign-functions=32} aligns functions to the next 32-byte
5150boundary, but @option{-falign-functions=24} would align to the next
515132-byte boundary only if this can be done by skipping 23 bytes or less.
5152
5153@option{-fno-align-functions} and @option{-falign-functions=1} are
5154equivalent and mean that functions will not be aligned.
5155
5156Some assemblers only support this flag when @var{n} is a power of two;
5157in that case, it is rounded up.
5158
5159If @var{n} is not specified or is zero, use a machine-dependent default.
5160
5161Enabled at levels @option{-O2}, @option{-O3}.
5162
5163@item -falign-labels
5164@itemx -falign-labels=@var{n}
5165@opindex falign-labels
5166Align all branch targets to a power-of-two boundary, skipping up to
5167@var{n} bytes like @option{-falign-functions}. This option can easily
5168make code slower, because it must insert dummy operations for when the
5169branch target is reached in the usual flow of the code.
5170
5171@option{-fno-align-labels} and @option{-falign-labels=1} are
5172equivalent and mean that labels will not be aligned.
5173
5174If @option{-falign-loops} or @option{-falign-jumps} are applicable and
5175are greater than this value, then their values are used instead.
5176
5177If @var{n} is not specified or is zero, use a machine-dependent default
5178which is very likely to be @samp{1}, meaning no alignment.
5179
5180Enabled at levels @option{-O2}, @option{-O3}.
5181
5182@item -falign-loops
5183@itemx -falign-loops=@var{n}
5184@opindex falign-loops
5185Align loops to a power-of-two boundary, skipping up to @var{n} bytes
5186like @option{-falign-functions}. The hope is that the loop will be
5187executed many times, which will make up for any execution of the dummy
5188operations.
5189
5190@option{-fno-align-loops} and @option{-falign-loops=1} are
5191equivalent and mean that loops will not be aligned.
5192
5193If @var{n} is not specified or is zero, use a machine-dependent default.
5194
5195Enabled at levels @option{-O2}, @option{-O3}.
5196
5197@item -falign-jumps
5198@itemx -falign-jumps=@var{n}
5199@opindex falign-jumps
5200Align branch targets to a power-of-two boundary, for branch targets
5201where the targets can only be reached by jumping, skipping up to @var{n}
5202bytes like @option{-falign-functions}. In this case, no dummy operations
5203need be executed.
5204
5205@option{-fno-align-jumps} and @option{-falign-jumps=1} are
5206equivalent and mean that loops will not be aligned.
5207
5208If @var{n} is not specified or is zero, use a machine-dependent default.
5209
5210Enabled at levels @option{-O2}, @option{-O3}.
5211
5212@item -funit-at-a-time
5213@opindex funit-at-a-time
5214Parse the whole compilation unit before starting to produce code.
5215This allows some extra optimizations to take place but consumes
5216more memory (in general). There are some compatibility issues
5217with @emph{unit-at-a-time} mode:
5218@itemize @bullet
5219@item
5220enabling @emph{unit-at-a-time} mode may change the order
5221in which functions, variables, and top-level @code{asm} statements
5222are emitted, and will likely break code relying on some particular
5223ordering. The majority of such top-level @code{asm} statements,
5224though, can be replaced by @code{section} attributes. The
5225@option{fno-toplevel-reorder} option may be used to keep the ordering
5226used in the input file, at the cost of some optimizations.
5227
5228@item
5229@emph{unit-at-a-time} mode removes unreferenced static variables
5230and functions. This may result in undefined references
5231when an @code{asm} statement refers directly to variables or functions
5232that are otherwise unused. In that case either the variable/function
5233shall be listed as an operand of the @code{asm} statement operand or,
5234in the case of top-level @code{asm} statements the attribute @code{used}
5235shall be used on the declaration.
5236
5237@item
5238Static functions now can use non-standard passing conventions that
5239may break @code{asm} statements calling functions directly. Again,
5240attribute @code{used} will prevent this behavior.
5241@end itemize
5242
5243As a temporary workaround, @option{-fno-unit-at-a-time} can be used,
5244but this scheme may not be supported by future releases of GCC@.
5245
5246Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5247
5248@item -fno-toplevel-reorder
5249Do not reorder top-level functions, variables, and @code{asm}
5250statements. Output them in the same order that they appear in the
5251input file. When this option is used, unreferenced static variables
5252will not be removed. This option is intended to support existing code
5253which relies on a particular ordering. For new code, it is better to
5254use attributes.
5255
5256@item -fweb
5257@opindex fweb
5258Constructs webs as commonly used for register allocation purposes and assign
5259each web individual pseudo register. This allows the register allocation pass
5260to operate on pseudos directly, but also strengthens several other optimization
5261passes, such as CSE, loop optimizer and trivial dead code remover. It can,
5262however, make debugging impossible, since variables will no longer stay in a
5263``home register''.
5264
5265Enabled by default with @option{-funroll-loops}.
5266
5267@item -fwhole-program
5268@opindex fwhole-program
5269Assume that the current compilation unit represents whole program being
5270compiled. All public functions and variables with the exception of @code{main}
5271and those merged by attribute @code{externally_visible} become static functions
5272and in a affect gets more aggressively optimized by interprocedural optimizers.
5273While this option is equivalent to proper use of @code{static} keyword for
5274programs consisting of single file, in combination with option
5275@option{--combine} this flag can be used to compile most of smaller scale C
5276programs since the functions and variables become local for the whole combined
5277compilation unit, not for the single source file itself.
5278
5279
5280@item -fno-cprop-registers
5281@opindex fno-cprop-registers
5282After register allocation and post-register allocation instruction splitting,
5283we perform a copy-propagation pass to try to reduce scheduling dependencies
5284and occasionally eliminate the copy.
5285
5286Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5287
5288@item -fprofile-generate
5289@opindex fprofile-generate
5290
5291Enable options usually used for instrumenting application to produce
5292profile useful for later recompilation with profile feedback based
5293optimization. You must use @option{-fprofile-generate} both when
5294compiling and when linking your program.
5295
5296The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
5297
5298@item -fprofile-use
5299@opindex fprofile-use
5300Enable profile feedback directed optimizations, and optimizations
5301generally profitable only with profile feedback available.
5302
5303The following options are enabled: @code{-fbranch-probabilities}, @code{-fvpt},
5304@code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}
5305
5306@end table
5307
5308The following options control compiler behavior regarding floating
5309point arithmetic. These options trade off between speed and
5310correctness. All must be specifically enabled.
5311
5312@table @gcctabopt
5313@item -ffloat-store
5314@opindex ffloat-store
5315Do not store floating point variables in registers, and inhibit other
5316options that might change whether a floating point value is taken from a
5317register or memory.
5318
5319@cindex floating point precision
5320This option prevents undesirable excess precision on machines such as
5321the 68000 where the floating registers (of the 68881) keep more
5322precision than a @code{double} is supposed to have. Similarly for the
5323x86 architecture. For most programs, the excess precision does only
5324good, but a few programs rely on the precise definition of IEEE floating
5325point. Use @option{-ffloat-store} for such programs, after modifying
5326them to store all pertinent intermediate computations into variables.
5327
5328@item -ffast-math
5329@opindex ffast-math
5330Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
5331@option{-fno-trapping-math}, @option{-ffinite-math-only},
5332@option{-fno-rounding-math}, @option{-fno-signaling-nans}
5333and @option{fcx-limited-range}.
5334
5335This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
5336
5337This option should never be turned on by any @option{-O} option since
5338it can result in incorrect output for programs which depend on
5339an exact implementation of IEEE or ISO rules/specifications for
5340math functions.
5341
5342@item -fno-math-errno
5343@opindex fno-math-errno
5344Do not set ERRNO after calling math functions that are executed
5345with a single instruction, e.g., sqrt. A program that relies on
5346IEEE exceptions for math error handling may want to use this flag
5347for speed while maintaining IEEE arithmetic compatibility.
5348
5349This option should never be turned on by any @option{-O} option since
5350it can result in incorrect output for programs which depend on
5351an exact implementation of IEEE or ISO rules/specifications for
5352math functions.
5353
5354The default is @option{-fmath-errno}.
5355
5356On Darwin and FreeBSD systems, the math library never sets @code{errno}.
5357There is therefore
5358no reason for the compiler to consider the possibility that it might,
5359and @option{-fno-math-errno} is the default.
5360
5361@item -funsafe-math-optimizations
5362@opindex funsafe-math-optimizations
5363Allow optimizations for floating-point arithmetic that (a) assume
5364that arguments and results are valid and (b) may violate IEEE or
5365ANSI standards. When used at link-time, it may include libraries
5366or startup files that change the default FPU control word or other
5367similar optimizations.
5368
5369This option should never be turned on by any @option{-O} option since
5370it can result in incorrect output for programs which depend on
5371an exact implementation of IEEE or ISO rules/specifications for
5372math functions.
5373
5374The default is @option{-fno-unsafe-math-optimizations}.
5375
5376@item -ffinite-math-only
5377@opindex ffinite-math-only
5378Allow optimizations for floating-point arithmetic that assume
5379that arguments and results are not NaNs or +-Infs.
5380
5381This option should never be turned on by any @option{-O} option since
5382it can result in incorrect output for programs which depend on
5383an exact implementation of IEEE or ISO rules/specifications.
5384
5385The default is @option{-fno-finite-math-only}.
5386
5387@item -fno-trapping-math
5388@opindex fno-trapping-math
5389Compile code assuming that floating-point operations cannot generate
5390user-visible traps. These traps include division by zero, overflow,
5391underflow, inexact result and invalid operation. This option implies
5392@option{-fno-signaling-nans}. Setting this option may allow faster
5393code if one relies on ``non-stop'' IEEE arithmetic, for example.
5394
5395This option should never be turned on by any @option{-O} option since
5396it can result in incorrect output for programs which depend on
5397an exact implementation of IEEE or ISO rules/specifications for
5398math functions.
5399
5400The default is @option{-ftrapping-math}.
5401
5402@item -frounding-math
5403@opindex frounding-math
5404Disable transformations and optimizations that assume default floating
5405point rounding behavior. This is round-to-zero for all floating point
5406to integer conversions, and round-to-nearest for all other arithmetic
5407truncations. This option should be specified for programs that change
5408the FP rounding mode dynamically, or that may be executed with a
5409non-default rounding mode. This option disables constant folding of
5410floating point expressions at compile-time (which may be affected by
5411rounding mode) and arithmetic transformations that are unsafe in the
5412presence of sign-dependent rounding modes.
5413
5414The default is @option{-fno-rounding-math}.
5415
5416This option is experimental and does not currently guarantee to
5417disable all GCC optimizations that are affected by rounding mode.
5418Future versions of GCC may provide finer control of this setting
5419using C99's @code{FENV_ACCESS} pragma. This command line option
5420will be used to specify the default state for @code{FENV_ACCESS}.
5421
5422@item -frtl-abstract-sequences
5423@opindex frtl-abstract-sequences
5424It is a size optimization method. This option is to find identical
5425sequences of code, which can be turned into pseudo-procedures and
5426then replace all occurrences with calls to the newly created
5427subroutine. It is kind of an opposite of @option{-finline-functions}.
5428This optimization runs at RTL level.
5429
5430@item -fsignaling-nans
5431@opindex fsignaling-nans
5432Compile code assuming that IEEE signaling NaNs may generate user-visible
5433traps during floating-point operations. Setting this option disables
5434optimizations that may change the number of exceptions visible with
5435signaling NaNs. This option implies @option{-ftrapping-math}.
5436
5437This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
5438be defined.
5439
5440The default is @option{-fno-signaling-nans}.
5441
5442This option is experimental and does not currently guarantee to
5443disable all GCC optimizations that affect signaling NaN behavior.
5444
5445@item -fsingle-precision-constant
5446@opindex fsingle-precision-constant
5447Treat floating point constant as single precision constant instead of
5448implicitly converting it to double precision constant.
5449
5450@item -fcx-limited-range
5451@itemx -fno-cx-limited-range
5452@opindex fcx-limited-range
5453@opindex fno-cx-limited-range
5454When enabled, this option states that a range reduction step is not
5455needed when performing complex division. The default is
5456@option{-fno-cx-limited-range}, but is enabled by @option{-ffast-math}.
5457
5458This option controls the default setting of the ISO C99
5459@code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to
5460all languages.
5461
5462@end table
5463
5464The following options control optimizations that may improve
5465performance, but are not enabled by any @option{-O} options. This
5466section includes experimental options that may produce broken code.
5467
5468@table @gcctabopt
5469@item -fbranch-probabilities
5470@opindex fbranch-probabilities
5471After running a program compiled with @option{-fprofile-arcs}
5472(@pxref{Debugging Options,, Options for Debugging Your Program or
5473@command{gcc}}), you can compile it a second time using
5474@option{-fbranch-probabilities}, to improve optimizations based on
5475the number of times each branch was taken. When the program
5476compiled with @option{-fprofile-arcs} exits it saves arc execution
5477counts to a file called @file{@var{sourcename}.gcda} for each source
5478file The information in this data file is very dependent on the
5479structure of the generated code, so you must use the same source code
5480and the same optimization options for both compilations.
5481
5482With @option{-fbranch-probabilities}, GCC puts a
5483@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
5484These can be used to improve optimization. Currently, they are only
5485used in one place: in @file{reorg.c}, instead of guessing which path a
5486branch is mostly to take, the @samp{REG_BR_PROB} values are used to
5487exactly determine which path is taken more often.
5488
5489@item -fprofile-values
5490@opindex fprofile-values
5491If combined with @option{-fprofile-arcs}, it adds code so that some
5492data about values of expressions in the program is gathered.
5493
5494With @option{-fbranch-probabilities}, it reads back the data gathered
5495from profiling values of expressions and adds @samp{REG_VALUE_PROFILE}
5496notes to instructions for their later usage in optimizations.
5497
5498Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
5499
5500@item -fvpt
5501@opindex fvpt
5502If combined with @option{-fprofile-arcs}, it instructs the compiler to add
5503a code to gather information about values of expressions.
5504
5505With @option{-fbranch-probabilities}, it reads back the data gathered
5506and actually performs the optimizations based on them.
5507Currently the optimizations include specialization of division operation
5508using the knowledge about the value of the denominator.
5509
5510@item -frename-registers
5511@opindex frename-registers
5512Attempt to avoid false dependencies in scheduled code by making use
5513of registers left over after register allocation. This optimization
5514will most benefit processors with lots of registers. Depending on the
5515debug information format adopted by the target, however, it can
5516make debugging impossible, since variables will no longer stay in
5517a ``home register''.
5518
5519Enabled by default with @option{-funroll-loops}.
5520
5521@item -ftracer
5522@opindex ftracer
5523Perform tail duplication to enlarge superblock size. This transformation
5524simplifies the control flow of the function allowing other optimizations to do
5525better job.
5526
5527Enabled with @option{-fprofile-use}.
5528
5529@item -funroll-loops
5530@opindex funroll-loops
5531Unroll loops whose number of iterations can be determined at compile time or
5532upon entry to the loop. @option{-funroll-loops} implies
5533@option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.
5534It also turns on complete loop peeling (i.e.@: complete removal of loops with
5535small constant number of iterations). This option makes code larger, and may
5536or may not make it run faster.
5537
5538Enabled with @option{-fprofile-use}.
5539
5540@item -funroll-all-loops
5541@opindex funroll-all-loops
5542Unroll all loops, even if their number of iterations is uncertain when
5543the loop is entered. This usually makes programs run more slowly.
5544@option{-funroll-all-loops} implies the same options as
5545@option{-funroll-loops}.
5546
5547@item -fpeel-loops
5548@opindex fpeel-loops
5549Peels the loops for that there is enough information that they do not
5550roll much (from profile feedback). It also turns on complete loop peeling
5551(i.e.@: complete removal of loops with small constant number of iterations).
5552
5553Enabled with @option{-fprofile-use}.
5554
5555@item -fmove-loop-invariants
5556@opindex fmove-loop-invariants
5557Enables the loop invariant motion pass in the RTL loop optimizer. Enabled
5558at level @option{-O1}
5559
5560@item -funswitch-loops
5561@opindex funswitch-loops
5562Move branches with loop invariant conditions out of the loop, with duplicates
5563of the loop on both branches (modified according to result of the condition).
5564
5565@item -ffunction-sections
5566@itemx -fdata-sections
5567@opindex ffunction-sections
5568@opindex fdata-sections
5569Place each function or data item into its own section in the output
5570file if the target supports arbitrary sections. The name of the
5571function or the name of the data item determines the section's name
5572in the output file.
5573
5574Use these options on systems where the linker can perform optimizations
5575to improve locality of reference in the instruction space. Most systems
5576using the ELF object format and SPARC processors running Solaris 2 have
5577linkers with such optimizations. AIX may have these optimizations in
5578the future.
5579
5580Only use these options when there are significant benefits from doing
5581so. When you specify these options, the assembler and linker will
5582create larger object and executable files and will also be slower.
5583You will not be able to use @code{gprof} on all systems if you
5584specify this option and you may have problems with debugging if
5585you specify both this option and @option{-g}.
5586
5587@item -fbranch-target-load-optimize
5588@opindex fbranch-target-load-optimize
5589Perform branch target register load optimization before prologue / epilogue
5590threading.
5591The use of target registers can typically be exposed only during reload,
5592thus hoisting loads out of loops and doing inter-block scheduling needs
5593a separate optimization pass.
5594
5595@item -fbranch-target-load-optimize2
5596@opindex fbranch-target-load-optimize2
5597Perform branch target register load optimization after prologue / epilogue
5598threading.
5599
5600@item -fbtr-bb-exclusive
5601@opindex fbtr-bb-exclusive
5602When performing branch target register load optimization, don't reuse
5603branch target registers in within any basic block.
5604
5605@item -fstack-protector
5606Emit extra code to check for buffer overflows, such as stack smashing
5607attacks. This is done by adding a guard variable to functions with
5608vulnerable objects. This includes functions that call alloca, and
5609functions with buffers larger than 8 bytes. The guards are initialized
5610when a function is entered and then checked when the function exits.
5611If a guard check fails, an error message is printed and the program exits.
5612
5613@item -fstack-protector-all
5614Like @option{-fstack-protector} except that all functions are protected.
5615
5616@item -fsection-anchors
5617@opindex fsection-anchors
5618Try to reduce the number of symbolic address calculations by using
5619shared ``anchor'' symbols to address nearby objects. This transformation
5620can help to reduce the number of GOT entries and GOT accesses on some
5621targets.
5622
5623For example, the implementation of the following function @code{foo}:
5624
5625@smallexample
5626static int a, b, c;
5627int foo (void) @{ return a + b + c; @}
5628@end smallexample
5629
5630would usually calculate the addresses of all three variables, but if you
5631compile it with @option{-fsection-anchors}, it will access the variables
5632from a common anchor point instead. The effect is similar to the
5633following pseudocode (which isn't valid C):
5634
5635@smallexample
5636int foo (void)
5637@{
5638 register int *xr = &x;
5639 return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
5640@}
5641@end smallexample
5642
5643Not all targets support this option.
5644
5645@item --param @var{name}=@var{value}
5646@opindex param
5647In some places, GCC uses various constants to control the amount of
5648optimization that is done. For example, GCC will not inline functions
5649that contain more that a certain number of instructions. You can
5650control some of these constants on the command-line using the
5651@option{--param} option.
5652
5653The names of specific parameters, and the meaning of the values, are
5654tied to the internals of the compiler, and are subject to change
5655without notice in future releases.
5656
5657In each case, the @var{value} is an integer. The allowable choices for
5658@var{name} are given in the following table:
5659
5660@table @gcctabopt
5661@item salias-max-implicit-fields
5662The maximum number of fields in a variable without direct
5663structure accesses for which structure aliasing will consider trying
5664to track each field. The default is 5
5665
5666@item salias-max-array-elements
5667The maximum number of elements an array can have and its elements
5668still be tracked individually by structure aliasing. The default is 4
5669
5670@item sra-max-structure-size
5671The maximum structure size, in bytes, at which the scalar replacement
5672of aggregates (SRA) optimization will perform block copies. The
5673default value, 0, implies that GCC will select the most appropriate
5674size itself.
5675
5676@item sra-field-structure-ratio
5677The threshold ratio (as a percentage) between instantiated fields and
5678the complete structure size. We say that if the ratio of the number
5679of bytes in instantiated fields to the number of bytes in the complete
5680structure exceeds this parameter, then block copies are not used. The
5681default is 75.
5682
5683@item max-crossjump-edges
5684The maximum number of incoming edges to consider for crossjumping.
5685The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
5686the number of edges incoming to each block. Increasing values mean
5687more aggressive optimization, making the compile time increase with
5688probably small improvement in executable size.
5689
5690@item min-crossjump-insns
5691The minimum number of instructions which must be matched at the end
5692of two blocks before crossjumping will be performed on them. This
5693value is ignored in the case where all instructions in the block being
5694crossjumped from are matched. The default value is 5.
5695
5696@item max-grow-copy-bb-insns
5697The maximum code size expansion factor when copying basic blocks
5698instead of jumping. The expansion is relative to a jump instruction.
5699The default value is 8.
5700
5701@item max-goto-duplication-insns
5702The maximum number of instructions to duplicate to a block that jumps
5703to a computed goto. To avoid @math{O(N^2)} behavior in a number of
5704passes, GCC factors computed gotos early in the compilation process,
5705and unfactors them as late as possible. Only computed jumps at the
5706end of a basic blocks with no more than max-goto-duplication-insns are
5707unfactored. The default value is 8.
5708
5709@item max-delay-slot-insn-search
5710The maximum number of instructions to consider when looking for an
5711instruction to fill a delay slot. If more than this arbitrary number of
5712instructions is searched, the time savings from filling the delay slot
5713will be minimal so stop searching. Increasing values mean more
5714aggressive optimization, making the compile time increase with probably
5715small improvement in executable run time.
5716
5717@item max-delay-slot-live-search
5718When trying to fill delay slots, the maximum number of instructions to
5719consider when searching for a block with valid live register
5720information. Increasing this arbitrarily chosen value means more
5721aggressive optimization, increasing the compile time. This parameter
5722should be removed when the delay slot code is rewritten to maintain the
5723control-flow graph.
5724
5725@item max-gcse-memory
5726The approximate maximum amount of memory that will be allocated in
5727order to perform the global common subexpression elimination
5728optimization. If more memory than specified is required, the
5729optimization will not be done.
5730
5731@item max-gcse-passes
5732The maximum number of passes of GCSE to run. The default is 1.
5733
5734@item max-pending-list-length
5735The maximum number of pending dependencies scheduling will allow
5736before flushing the current state and starting over. Large functions
5737with few branches or calls can create excessively large lists which
5738needlessly consume memory and resources.
5739
5740@item max-inline-insns-single
5741Several parameters control the tree inliner used in gcc.
5742This number sets the maximum number of instructions (counted in GCC's
5743internal representation) in a single function that the tree inliner
5744will consider for inlining. This only affects functions declared
5745inline and methods implemented in a class declaration (C++).
5746The default value is 450.
5747
5748@item max-inline-insns-auto
5749When you use @option{-finline-functions} (included in @option{-O3}),
5750a lot of functions that would otherwise not be considered for inlining
5751by the compiler will be investigated. To those functions, a different
5752(more restrictive) limit compared to functions declared inline can
5753be applied.
5754The default value is 90.
5755
5756@item large-function-insns
5757The limit specifying really large functions. For functions larger than this
5758limit after inlining inlining is constrained by
5759@option{--param large-function-growth}. This parameter is useful primarily
5760to avoid extreme compilation time caused by non-linear algorithms used by the
5761backend.
5762This parameter is ignored when @option{-funit-at-a-time} is not used.
5763The default value is 2700.
5764
5765@item large-function-growth
5766Specifies maximal growth of large function caused by inlining in percents.
5767This parameter is ignored when @option{-funit-at-a-time} is not used.
5768The default value is 100 which limits large function growth to 2.0 times
5769the original size.
5770
5771@item large-unit-insns
5772The limit specifying large translation unit. Growth caused by inlining of
5773units larger than this limit is limited by @option{--param inline-unit-growth}.
5774For small units this might be too tight (consider unit consisting of function A
5775that is inline and B that just calls A three time. If B is small relative to
5776A, the growth of unit is 300\% and yet such inlining is very sane. For very
5777large units consisting of small inlininable functions however the overall unit
5778growth limit is needed to avoid exponential explosion of code size. Thus for
5779smaller units, the size is increased to @option{--param large-unit-insns}
5780before applying @option{--param inline-unit-growth}. The default is 10000
5781
5782@item inline-unit-growth
5783Specifies maximal overall growth of the compilation unit caused by inlining.
5784This parameter is ignored when @option{-funit-at-a-time} is not used.
5785The default value is 50 which limits unit growth to 1.5 times the original
5786size.
5787
5788@item max-inline-insns-recursive
5789@itemx max-inline-insns-recursive-auto
5790Specifies maximum number of instructions out-of-line copy of self recursive inline
5791function can grow into by performing recursive inlining.
5792
5793For functions declared inline @option{--param max-inline-insns-recursive} is
5794taken into account. For function not declared inline, recursive inlining
5795happens only when @option{-finline-functions} (included in @option{-O3}) is
5796enabled and @option{--param max-inline-insns-recursive-auto} is used. The
5797default value is 450.
5798
5799@item max-inline-recursive-depth
5800@itemx max-inline-recursive-depth-auto
5801Specifies maximum recursion depth used by the recursive inlining.
5802
5803For functions declared inline @option{--param max-inline-recursive-depth} is
5804taken into account. For function not declared inline, recursive inlining
5805happens only when @option{-finline-functions} (included in @option{-O3}) is
5806enabled and @option{--param max-inline-recursive-depth-auto} is used. The
5807default value is 450.
5808
5809@item min-inline-recursive-probability
5810Recursive inlining is profitable only for function having deep recursion
5811in average and can hurt for function having little recursion depth by
5812increasing the prologue size or complexity of function body to other
5813optimizers.
5814
5815When profile feedback is available (see @option{-fprofile-generate}) the actual
5816recursion depth can be guessed from probability that function will recurse via
5817given call expression. This parameter limits inlining only to call expression
5818whose probability exceeds given threshold (in percents). The default value is
581910.
5820
5821@item inline-call-cost
5822Specify cost of call instruction relative to simple arithmetics operations
5823(having cost of 1). Increasing this cost disqualifies inlining of non-leaf
5824functions and at the same time increases size of leaf function that is believed to
5825reduce function size by being inlined. In effect it increases amount of
5826inlining for code having large abstraction penalty (many functions that just
5827pass the arguments to other functions) and decrease inlining for code with low
5828abstraction penalty. The default value is 16.
5829
5830@item max-unrolled-insns
5831The maximum number of instructions that a loop should have if that loop
5832is unrolled, and if the loop is unrolled, it determines how many times
5833the loop code is unrolled.
5834
5835@item max-average-unrolled-insns
5836The maximum number of instructions biased by probabilities of their execution
5837that a loop should have if that loop is unrolled, and if the loop is unrolled,
5838it determines how many times the loop code is unrolled.
5839
5840@item max-unroll-times
5841The maximum number of unrollings of a single loop.
5842
5843@item max-peeled-insns
5844The maximum number of instructions that a loop should have if that loop
5845is peeled, and if the loop is peeled, it determines how many times
5846the loop code is peeled.
5847
5848@item max-peel-times
5849The maximum number of peelings of a single loop.
5850
5851@item max-completely-peeled-insns
5852The maximum number of insns of a completely peeled loop.
5853
5854@item max-completely-peel-times
5855The maximum number of iterations of a loop to be suitable for complete peeling.
5856
5857@item max-unswitch-insns
5858The maximum number of insns of an unswitched loop.
5859
5860@item max-unswitch-level
5861The maximum number of branches unswitched in a single loop.
5862
5863@item lim-expensive
5864The minimum cost of an expensive expression in the loop invariant motion.
5865
5866@item iv-consider-all-candidates-bound
5867Bound on number of candidates for induction variables below that
5868all candidates are considered for each use in induction variable
5869optimizations. Only the most relevant candidates are considered
5870if there are more candidates, to avoid quadratic time complexity.
5871
5872@item iv-max-considered-uses
5873The induction variable optimizations give up on loops that contain more
5874induction variable uses.
5875
5876@item iv-always-prune-cand-set-bound
5877If number of candidates in the set is smaller than this value,
5878we always try to remove unnecessary ivs from the set during its
5879optimization when a new iv is added to the set.
5880
5881@item scev-max-expr-size
5882Bound on size of expressions used in the scalar evolutions analyzer.
5883Large expressions slow the analyzer.
5884
5885@item vect-max-version-checks
5886The maximum number of runtime checks that can be performed when doing
5887loop versioning in the vectorizer. See option ftree-vect-loop-version
5888for more information.
5889
5890@item max-iterations-to-track
5891
5892The maximum number of iterations of a loop the brute force algorithm
5893for analysis of # of iterations of the loop tries to evaluate.
5894
5895@item hot-bb-count-fraction
5896Select fraction of the maximal count of repetitions of basic block in program
5897given basic block needs to have to be considered hot.
5898
5899@item hot-bb-frequency-fraction
5900Select fraction of the maximal frequency of executions of basic block in
5901function given basic block needs to have to be considered hot
5902
5903@item max-predicted-iterations
5904The maximum number of loop iterations we predict statically. This is useful
5905in cases where function contain single loop with known bound and other loop
5906with unknown. We predict the known number of iterations correctly, while
5907the unknown number of iterations average to roughly 10. This means that the
5908loop without bounds would appear artificially cold relative to the other one.
5909
5910@item tracer-dynamic-coverage
5911@itemx tracer-dynamic-coverage-feedback
5912
5913This value is used to limit superblock formation once the given percentage of
5914executed instructions is covered. This limits unnecessary code size
5915expansion.
5916
5917The @option{tracer-dynamic-coverage-feedback} is used only when profile
5918feedback is available. The real profiles (as opposed to statically estimated
5919ones) are much less balanced allowing the threshold to be larger value.
5920
5921@item tracer-max-code-growth
5922Stop tail duplication once code growth has reached given percentage. This is
5923rather hokey argument, as most of the duplicates will be eliminated later in
5924cross jumping, so it may be set to much higher values than is the desired code
5925growth.
5926
5927@item tracer-min-branch-ratio
5928
5929Stop reverse growth when the reverse probability of best edge is less than this
5930threshold (in percent).
5931
5932@item tracer-min-branch-ratio
5933@itemx tracer-min-branch-ratio-feedback
5934
5935Stop forward growth if the best edge do have probability lower than this
5936threshold.
5937
5938Similarly to @option{tracer-dynamic-coverage} two values are present, one for
5939compilation for profile feedback and one for compilation without. The value
5940for compilation with profile feedback needs to be more conservative (higher) in
5941order to make tracer effective.
5942
5943@item max-cse-path-length
5944
5945Maximum number of basic blocks on path that cse considers. The default is 10.
5946
5947@item max-cse-insns
5948The maximum instructions CSE process before flushing. The default is 1000.
5949
5950@item global-var-threshold
5951
5952Counts the number of function calls (@var{n}) and the number of
5953call-clobbered variables (@var{v}). If @var{n}x@var{v} is larger than this limit, a
5954single artificial variable will be created to represent all the
5955call-clobbered variables at function call sites. This artificial
5956variable will then be made to alias every call-clobbered variable.
5957(done as @code{int * size_t} on the host machine; beware overflow).
5958
5959@item max-aliased-vops
5960
5961Maximum number of virtual operands allowed to represent aliases
5962before triggering the alias grouping heuristic. Alias grouping
5963reduces compile times and memory consumption needed for aliasing at
5964the expense of precision loss in alias information.
5965
5966@item ggc-min-expand
5967
5968GCC uses a garbage collector to manage its own memory allocation. This
5969parameter specifies the minimum percentage by which the garbage
5970collector's heap should be allowed to expand between collections.
5971Tuning this may improve compilation speed; it has no effect on code
5972generation.
5973
5974The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
5975RAM >= 1GB@. If @code{getrlimit} is available, the notion of "RAM" is
5976the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If
5977GCC is not able to calculate RAM on a particular platform, the lower
5978bound of 30% is used. Setting this parameter and
5979@option{ggc-min-heapsize} to zero causes a full collection to occur at
5980every opportunity. This is extremely slow, but can be useful for
5981debugging.
5982
5983@item ggc-min-heapsize
5984
5985Minimum size of the garbage collector's heap before it begins bothering
5986to collect garbage. The first collection occurs after the heap expands
5987by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again,
5988tuning this may improve compilation speed, and has no effect on code
5989generation.
5990
5991The default is the smaller of RAM/8, RLIMIT_RSS, or a limit which
5992tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
5993with a lower bound of 4096 (four megabytes) and an upper bound of
5994131072 (128 megabytes). If GCC is not able to calculate RAM on a
5995particular platform, the lower bound is used. Setting this parameter
5996very large effectively disables garbage collection. Setting this
5997parameter and @option{ggc-min-expand} to zero causes a full collection
5998to occur at every opportunity.
5999
6000@item max-reload-search-insns
6001The maximum number of instruction reload should look backward for equivalent
6002register. Increasing values mean more aggressive optimization, making the
6003compile time increase with probably slightly better performance. The default
6004value is 100.
6005
6006@item max-cselib-memory-locations
6007The maximum number of memory locations cselib should take into account.
6008Increasing values mean more aggressive optimization, making the compile time
6009increase with probably slightly better performance. The default value is 500.
6010
6011@item max-flow-memory-locations
6012Similar as @option{max-cselib-memory-locations} but for dataflow liveness.
6013The default value is 100.
6014
6015@item reorder-blocks-duplicate
6016@itemx reorder-blocks-duplicate-feedback
6017
6018Used by basic block reordering pass to decide whether to use unconditional
6019branch or duplicate the code on its destination. Code is duplicated when its
6020estimated size is smaller than this value multiplied by the estimated size of
6021unconditional jump in the hot spots of the program.
6022
6023The @option{reorder-block-duplicate-feedback} is used only when profile
6024feedback is available and may be set to higher values than
6025@option{reorder-block-duplicate} since information about the hot spots is more
6026accurate.
6027
6028@item max-sched-ready-insns
6029The maximum number of instructions ready to be issued the scheduler should
6030consider at any given time during the first scheduling pass. Increasing
6031values mean more thorough searches, making the compilation time increase
6032with probably little benefit. The default value is 100.
6033
6034@item max-sched-region-blocks
6035The maximum number of blocks in a region to be considered for
6036interblock scheduling. The default value is 10.
6037
6038@item max-sched-region-insns
6039The maximum number of insns in a region to be considered for
6040interblock scheduling. The default value is 100.
6041
6042@item min-spec-prob
6043The minimum probability (in percents) of reaching a source block
6044for interblock speculative scheduling. The default value is 40.
6045
6046@item max-sched-extend-regions-iters
6047The maximum number of iterations through CFG to extend regions.
60480 - disable region extension,
6049N - do at most N iterations.
6050The default value is 0.
6051
6052@item max-sched-insn-conflict-delay
6053The maximum conflict delay for an insn to be considered for speculative motion.
6054The default value is 3.
6055
6056@item sched-spec-prob-cutoff
6057The minimal probability of speculation success (in percents), so that
6058speculative insn will be scheduled.
6059The default value is 40.
6060
6061@item max-last-value-rtl
6062
6063The maximum size measured as number of RTLs that can be recorded in an expression
6064in combiner for a pseudo register as last known value of that register. The default
6065is 10000.
6066
6067@item integer-share-limit
6068Small integer constants can use a shared data structure, reducing the
6069compiler's memory usage and increasing its speed. This sets the maximum
6070value of a shared integer constant's. The default value is 256.
6071
6072@item min-virtual-mappings
6073Specifies the minimum number of virtual mappings in the incremental
6074SSA updater that should be registered to trigger the virtual mappings
6075heuristic defined by virtual-mappings-ratio. The default value is
6076100.
6077
6078@item virtual-mappings-ratio
6079If the number of virtual mappings is virtual-mappings-ratio bigger
6080than the number of virtual symbols to be updated, then the incremental
6081SSA updater switches to a full update for those symbols. The default
6082ratio is 3.
6083
6084@item ssp-buffer-size
6085The minimum size of buffers (i.e. arrays) that will receive stack smashing
6086protection when @option{-fstack-protection} is used.
6087
6088@item max-jump-thread-duplication-stmts
6089Maximum number of statements allowed in a block that needs to be
6090duplicated when threading jumps.
6091
6092@item max-fields-for-field-sensitive
6093Maximum number of fields in a structure we will treat in
6094a field sensitive manner during pointer analysis.
6095
6096@end table
6097@end table
6098
6099@node Preprocessor Options
6100@section Options Controlling the Preprocessor
6101@cindex preprocessor options
6102@cindex options, preprocessor
6103
6104These options control the C preprocessor, which is run on each C source
6105file before actual compilation.
6106
6107If you use the @option{-E} option, nothing is done except preprocessing.
6108Some of these options make sense only together with @option{-E} because
6109they cause the preprocessor output to be unsuitable for actual
6110compilation.
6111
6112@table @gcctabopt
6113@opindex Wp
6114You can use @option{-Wp,@var{option}} to bypass the compiler driver
6115and pass @var{option} directly through to the preprocessor. If
6116@var{option} contains commas, it is split into multiple options at the
6117commas. However, many options are modified, translated or interpreted
6118by the compiler driver before being passed to the preprocessor, and
6119@option{-Wp} forcibly bypasses this phase. The preprocessor's direct
6120interface is undocumented and subject to change, so whenever possible
6121you should avoid using @option{-Wp} and let the driver handle the
6122options instead.
6123
6124@item -Xpreprocessor @var{option}
6125@opindex preprocessor
6126Pass @var{option} as an option to the preprocessor. You can use this to
6127supply system-specific preprocessor options which GCC does not know how to
6128recognize.
6129
6130If you want to pass an option that takes an argument, you must use
6131@option{-Xpreprocessor} twice, once for the option and once for the argument.
6132@end table
6133
6134@include cppopts.texi
6135
6136@node Assembler Options
6137@section Passing Options to the Assembler
6138
6139@c prevent bad page break with this line
6140You can pass options to the assembler.
6141
6142@table @gcctabopt
6143@item -Wa,@var{option}
6144@opindex Wa
6145Pass @var{option} as an option to the assembler. If @var{option}
6146contains commas, it is split into multiple options at the commas.
6147
6148@item -Xassembler @var{option}
6149@opindex Xassembler
6150Pass @var{option} as an option to the assembler. You can use this to
6151supply system-specific assembler options which GCC does not know how to
6152recognize.
6153
6154If you want to pass an option that takes an argument, you must use
6155@option{-Xassembler} twice, once for the option and once for the argument.
6156
6157@end table
6158
6159@node Link Options
6160@section Options for Linking
6161@cindex link options
6162@cindex options, linking
6163
6164These options come into play when the compiler links object files into
6165an executable output file. They are meaningless if the compiler is
6166not doing a link step.
6167
6168@table @gcctabopt
6169@cindex file names
6170@item @var{object-file-name}
6171A file name that does not end in a special recognized suffix is
6172considered to name an object file or library. (Object files are
6173distinguished from libraries by the linker according to the file
6174contents.) If linking is done, these object files are used as input
6175to the linker.
6176
6177@item -c
6178@itemx -S
6179@itemx -E
6180@opindex c
6181@opindex S
6182@opindex E
6183If any of these options is used, then the linker is not run, and
6184object file names should not be used as arguments. @xref{Overall
6185Options}.
6186
6187@cindex Libraries
6188@item -l@var{library}
6189@itemx -l @var{library}
6190@opindex l
6191Search the library named @var{library} when linking. (The second
6192alternative with the library as a separate argument is only for
6193POSIX compliance and is not recommended.)
6194
6195It makes a difference where in the command you write this option; the
6196linker searches and processes libraries and object files in the order they
6197are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
6198after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
6199to functions in @samp{z}, those functions may not be loaded.
6200
6201The linker searches a standard list of directories for the library,
6202which is actually a file named @file{lib@var{library}.a}. The linker
6203then uses this file as if it had been specified precisely by name.
6204
6205The directories searched include several standard system directories
6206plus any that you specify with @option{-L}.
6207
6208Normally the files found this way are library files---archive files
6209whose members are object files. The linker handles an archive file by
6210scanning through it for members which define symbols that have so far
6211been referenced but not defined. But if the file that is found is an
6212ordinary object file, it is linked in the usual fashion. The only
6213difference between using an @option{-l} option and specifying a file name
6214is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
6215and searches several directories.
6216
6217@item -nostartfiles
6218@opindex nostartfiles
6219Do not use the standard system startup files when linking.
6220The standard system libraries are used normally, unless @option{-nostdlib}
6221or @option{-nodefaultlibs} is used.
6222
6223@item -nodefaultlibs
6224@opindex nodefaultlibs
6225Do not use the standard system libraries when linking.
6226Only the libraries you specify will be passed to the linker.
6227The standard startup files are used normally, unless @option{-nostartfiles}
6228is used. The compiler may generate calls to @code{memcmp},
6229@code{memset}, @code{memcpy} and @code{memmove}.
6230These entries are usually resolved by entries in
6231libc. These entry points should be supplied through some other
6232mechanism when this option is specified.
6233
6234@item -nostdlib
6235@opindex nostdlib
6236Do not use the standard system startup files or libraries when linking.
6237No startup files and only the libraries you specify will be passed to
6238the linker. The compiler may generate calls to @code{memcmp}, @code{memset},
6239@code{memcpy} and @code{memmove}.
6240These entries are usually resolved by entries in
6241libc. These entry points should be supplied through some other
6242mechanism when this option is specified.
6243
6244@cindex @option{-lgcc}, use with @option{-nostdlib}
6245@cindex @option{-nostdlib} and unresolved references
6246@cindex unresolved references and @option{-nostdlib}
6247@cindex @option{-lgcc}, use with @option{-nodefaultlibs}
6248@cindex @option{-nodefaultlibs} and unresolved references
6249@cindex unresolved references and @option{-nodefaultlibs}
6250One of the standard libraries bypassed by @option{-nostdlib} and
6251@option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
6252that GCC uses to overcome shortcomings of particular machines, or special
6253needs for some languages.
6254(@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
6255Collection (GCC) Internals},
6256for more discussion of @file{libgcc.a}.)
6257In most cases, you need @file{libgcc.a} even when you want to avoid
6258other standard libraries. In other words, when you specify @option{-nostdlib}
6259or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
6260This ensures that you have no unresolved references to internal GCC
6261library subroutines. (For example, @samp{__main}, used to ensure C++
6262constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
6263GNU Compiler Collection (GCC) Internals}.)
6264
6265@item -pie
6266@opindex pie
6267Produce a position independent executable on targets which support it.
6268For predictable results, you must also specify the same set of options
6269that were used to generate code (@option{-fpie}, @option{-fPIE},
6270or model suboptions) when you specify this option.
6271
6272@item -rdynamic
6273@opindex rdynamic
6274Pass the flag @option{-export-dynamic} to the ELF linker, on targets
6275that support it. This instructs the linker to add all symbols, not
6276only used ones, to the dynamic symbol table. This option is needed
6277for some uses of @code{dlopen} or to allow obtaining backtraces
6278from within a program.
6279
6280@item -s
6281@opindex s
6282Remove all symbol table and relocation information from the executable.
6283
6284@item -static
6285@opindex static
6286On systems that support dynamic linking, this prevents linking with the shared
6287libraries. On other systems, this option has no effect.
6288
6289@item -shared
6290@opindex shared
6291Produce a shared object which can then be linked with other objects to
6292form an executable. Not all systems support this option. For predictable
6293results, you must also specify the same set of options that were used to
6294generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
6295when you specify this option.@footnote{On some systems, @samp{gcc -shared}
6296needs to build supplementary stub code for constructors to work. On
6297multi-libbed systems, @samp{gcc -shared} must select the correct support
6298libraries to link against. Failing to supply the correct flags may lead
6299to subtle defects. Supplying them in cases where they are not necessary
6300is innocuous.}
6301
6302@item -shared-libgcc
6303@itemx -static-libgcc
6304@opindex shared-libgcc
6305@opindex static-libgcc
6306On systems that provide @file{libgcc} as a shared library, these options
6307force the use of either the shared or static version respectively.
6308If no shared version of @file{libgcc} was built when the compiler was
6309configured, these options have no effect.
6310
6311There are several situations in which an application should use the
6312shared @file{libgcc} instead of the static version. The most common
6313of these is when the application wishes to throw and catch exceptions
6314across different shared libraries. In that case, each of the libraries
6315as well as the application itself should use the shared @file{libgcc}.
6316
6317Therefore, the G++ and GCJ drivers automatically add
6318@option{-shared-libgcc} whenever you build a shared library or a main
6319executable, because C++ and Java programs typically use exceptions, so
6320this is the right thing to do.
6321
6322If, instead, you use the GCC driver to create shared libraries, you may
6323find that they will not always be linked with the shared @file{libgcc}.
6324If GCC finds, at its configuration time, that you have a non-GNU linker
6325or a GNU linker that does not support option @option{--eh-frame-hdr},
6326it will link the shared version of @file{libgcc} into shared libraries
6327by default. Otherwise, it will take advantage of the linker and optimize
6328away the linking with the shared version of @file{libgcc}, linking with
6329the static version of libgcc by default. This allows exceptions to
6330propagate through such shared libraries, without incurring relocation
6331costs at library load time.
6332
6333However, if a library or main executable is supposed to throw or catch
6334exceptions, you must link it using the G++ or GCJ driver, as appropriate
6335for the languages used in the program, or using the option
6336@option{-shared-libgcc}, such that it is linked with the shared
6337@file{libgcc}.
6338
6339@item -symbolic
6340@opindex symbolic
6341Bind references to global symbols when building a shared object. Warn
6342about any unresolved references (unless overridden by the link editor
6343option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
6344this option.
6345
6346@item -Xlinker @var{option}
6347@opindex Xlinker
6348Pass @var{option} as an option to the linker. You can use this to
6349supply system-specific linker options which GCC does not know how to
6350recognize.
6351
6352If you want to pass an option that takes an argument, you must use
6353@option{-Xlinker} twice, once for the option and once for the argument.
6354For example, to pass @option{-assert definitions}, you must write
6355@samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
6356@option{-Xlinker "-assert definitions"}, because this passes the entire
6357string as a single argument, which is not what the linker expects.
6358
6359@item -Wl,@var{option}
6360@opindex Wl
6361Pass @var{option} as an option to the linker. If @var{option} contains
6362commas, it is split into multiple options at the commas.
6363
6364@item -u @var{symbol}
6365@opindex u
6366Pretend the symbol @var{symbol} is undefined, to force linking of
6367library modules to define it. You can use @option{-u} multiple times with
6368different symbols to force loading of additional library modules.
6369@end table
6370
6371@node Directory Options
6372@section Options for Directory Search
6373@cindex directory options
6374@cindex options, directory search
6375@cindex search path
6376
6377These options specify directories to search for header files, for
6378libraries and for parts of the compiler:
6379
6380@table @gcctabopt
6381@item -I@var{dir}
6382@opindex I
6383Add the directory @var{dir} to the head of the list of directories to be
6384searched for header files. This can be used to override a system header
6385file, substituting your own version, since these directories are
6386searched before the system header file directories. However, you should
6387not use this option to add directories that contain vendor-supplied
6388system header files (use @option{-isystem} for that). If you use more than
6389one @option{-I} option, the directories are scanned in left-to-right
6390order; the standard system directories come after.
6391
6392If a standard system include directory, or a directory specified with
6393@option{-isystem}, is also specified with @option{-I}, the @option{-I}
6394option will be ignored. The directory will still be searched but as a
6395system directory at its normal position in the system include chain.
6396This is to ensure that GCC's procedure to fix buggy system headers and
6397the ordering for the include_next directive are not inadvertently changed.
6398If you really need to change the search order for system directories,
6399use the @option{-nostdinc} and/or @option{-isystem} options.
6400
6401@item -iquote@var{dir}
6402@opindex iquote
6403Add the directory @var{dir} to the head of the list of directories to
6404be searched for header files only for the case of @samp{#include
6405"@var{file}"}; they are not searched for @samp{#include <@var{file}>},
6406otherwise just like @option{-I}.
6407
6408@item -L@var{dir}
6409@opindex L
6410Add directory @var{dir} to the list of directories to be searched
6411for @option{-l}.
6412
6413@item -B@var{prefix}
6414@opindex B
6415This option specifies where to find the executables, libraries,
6416include files, and data files of the compiler itself.
6417
6418The compiler driver program runs one or more of the subprograms
6419@file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
6420@var{prefix} as a prefix for each program it tries to run, both with and
6421without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
6422
6423For each subprogram to be run, the compiler driver first tries the
6424@option{-B} prefix, if any. If that name is not found, or if @option{-B}
6425was not specified, the driver tries two standard prefixes, which are
6426@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of
6427those results in a file name that is found, the unmodified program
6428name is searched for using the directories specified in your
6429@env{PATH} environment variable.
6430
6431The compiler will check to see if the path provided by the @option{-B}
6432refers to a directory, and if necessary it will add a directory
6433separator character at the end of the path.
6434
6435@option{-B} prefixes that effectively specify directory names also apply
6436to libraries in the linker, because the compiler translates these
6437options into @option{-L} options for the linker. They also apply to
6438includes files in the preprocessor, because the compiler translates these
6439options into @option{-isystem} options for the preprocessor. In this case,
6440the compiler appends @samp{include} to the prefix.
6441
6442The run-time support file @file{libgcc.a} can also be searched for using
6443the @option{-B} prefix, if needed. If it is not found there, the two
6444standard prefixes above are tried, and that is all. The file is left
6445out of the link if it is not found by those means.
6446
6447Another way to specify a prefix much like the @option{-B} prefix is to use
6448the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
6449Variables}.
6450
6451As a special kludge, if the path provided by @option{-B} is
6452@file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
64539, then it will be replaced by @file{[dir/]include}. This is to help
6454with boot-strapping the compiler.
6455
6456@item -specs=@var{file}
6457@opindex specs
6458Process @var{file} after the compiler reads in the standard @file{specs}
6459file, in order to override the defaults that the @file{gcc} driver
6460program uses when determining what switches to pass to @file{cc1},
6461@file{cc1plus}, @file{as}, @file{ld}, etc. More than one
6462@option{-specs=@var{file}} can be specified on the command line, and they
6463are processed in order, from left to right.
6464
6465@item --sysroot=@var{dir}
6466@opindex sysroot
6467Use @var{dir} as the logical root directory for headers and libraries.
6468For example, if the compiler would normally search for headers in
6469@file{/usr/include} and libraries in @file{/usr/lib}, it will instead
6470search @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
6471
6472If you use both this option and the @option{-isysroot} option, then
6473the @option{--sysroot} option will apply to libraries, but the
6474@option{-isysroot} option will apply to header files.
6475
6476The GNU linker (beginning with version 2.16) has the necessary support
6477for this option. If your linker does not support this option, the
6478header file aspect of @option{--sysroot} will still work, but the
6479library aspect will not.
6480
6481@item -I-
6482@opindex I-
6483This option has been deprecated. Please use @option{-iquote} instead for
6484@option{-I} directories before the @option{-I-} and remove the @option{-I-}.
6485Any directories you specify with @option{-I} options before the @option{-I-}
6486option are searched only for the case of @samp{#include "@var{file}"};
6487they are not searched for @samp{#include <@var{file}>}.
6488
6489If additional directories are specified with @option{-I} options after
6490the @option{-I-}, these directories are searched for all @samp{#include}
6491directives. (Ordinarily @emph{all} @option{-I} directories are used
6492this way.)
6493
6494In addition, the @option{-I-} option inhibits the use of the current
6495directory (where the current input file came from) as the first search
6496directory for @samp{#include "@var{file}"}. There is no way to
6497override this effect of @option{-I-}. With @option{-I.} you can specify
6498searching the directory which was current when the compiler was
6499invoked. That is not exactly the same as what the preprocessor does
6500by default, but it is often satisfactory.
6501
6502@option{-I-} does not inhibit the use of the standard system directories
6503for header files. Thus, @option{-I-} and @option{-nostdinc} are
6504independent.
6505@end table
6506
6507@c man end
6508
6509@node Spec Files
6510@section Specifying subprocesses and the switches to pass to them
6511@cindex Spec Files
6512
6513@command{gcc} is a driver program. It performs its job by invoking a
6514sequence of other programs to do the work of compiling, assembling and
6515linking. GCC interprets its command-line parameters and uses these to
6516deduce which programs it should invoke, and which command-line options
6517it ought to place on their command lines. This behavior is controlled
6518by @dfn{spec strings}. In most cases there is one spec string for each
6519program that GCC can invoke, but a few programs have multiple spec
6520strings to control their behavior. The spec strings built into GCC can
6521be overridden by using the @option{-specs=} command-line switch to specify
6522a spec file.
6523
6524@dfn{Spec files} are plaintext files that are used to construct spec
6525strings. They consist of a sequence of directives separated by blank
6526lines. The type of directive is determined by the first non-whitespace
6527character on the line and it can be one of the following:
6528
6529@table @code
6530@item %@var{command}
6531Issues a @var{command} to the spec file processor. The commands that can
6532appear here are:
6533
6534@table @code
6535@item %include <@var{file}>
6536@cindex %include
6537Search for @var{file} and insert its text at the current point in the
6538specs file.
6539
6540@item %include_noerr <@var{file}>
6541@cindex %include_noerr
6542Just like @samp{%include}, but do not generate an error message if the include
6543file cannot be found.
6544
6545@item %rename @var{old_name} @var{new_name}
6546@cindex %rename
6547Rename the spec string @var{old_name} to @var{new_name}.
6548
6549@end table
6550
6551@item *[@var{spec_name}]:
6552This tells the compiler to create, override or delete the named spec
6553string. All lines after this directive up to the next directive or
6554blank line are considered to be the text for the spec string. If this
6555results in an empty string then the spec will be deleted. (Or, if the
6556spec did not exist, then nothing will happened.) Otherwise, if the spec
6557does not currently exist a new spec will be created. If the spec does
6558exist then its contents will be overridden by the text of this
6559directive, unless the first character of that text is the @samp{+}
6560character, in which case the text will be appended to the spec.
6561
6562@item [@var{suffix}]:
6563Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
6564and up to the next directive or blank line are considered to make up the
6565spec string for the indicated suffix. When the compiler encounters an
6566input file with the named suffix, it will processes the spec string in
6567order to work out how to compile that file. For example:
6568
6569@smallexample
6570.ZZ:
6571z-compile -input %i
6572@end smallexample
6573
6574This says that any input file whose name ends in @samp{.ZZ} should be
6575passed to the program @samp{z-compile}, which should be invoked with the
6576command-line switch @option{-input} and with the result of performing the
6577@samp{%i} substitution. (See below.)
6578
6579As an alternative to providing a spec string, the text that follows a
6580suffix directive can be one of the following:
6581
6582@table @code
6583@item @@@var{language}
6584This says that the suffix is an alias for a known @var{language}. This is
6585similar to using the @option{-x} command-line switch to GCC to specify a
6586language explicitly. For example:
6587
6588@smallexample
6589.ZZ:
6590@@c++
6591@end smallexample
6592
6593Says that .ZZ files are, in fact, C++ source files.
6594
6595@item #@var{name}
6596This causes an error messages saying:
6597
6598@smallexample
6599@var{name} compiler not installed on this system.
6600@end smallexample
6601@end table
6602
6603GCC already has an extensive list of suffixes built into it.
6604This directive will add an entry to the end of the list of suffixes, but
6605since the list is searched from the end backwards, it is effectively
6606possible to override earlier entries using this technique.
6607
6608@end table
6609
6610GCC has the following spec strings built into it. Spec files can
6611override these strings or create their own. Note that individual
6612targets can also add their own spec strings to this list.
6613
6614@smallexample
6615asm Options to pass to the assembler
6616asm_final Options to pass to the assembler post-processor
6617cpp Options to pass to the C preprocessor
6618cc1 Options to pass to the C compiler
6619cc1plus Options to pass to the C++ compiler
6620endfile Object files to include at the end of the link
6621link Options to pass to the linker
6622lib Libraries to include on the command line to the linker
6623libgcc Decides which GCC support library to pass to the linker
6624linker Sets the name of the linker
6625predefines Defines to be passed to the C preprocessor
6626signed_char Defines to pass to CPP to say whether @code{char} is signed
6627 by default
6628startfile Object files to include at the start of the link
6629@end smallexample
6630
6631Here is a small example of a spec file:
6632
6633@smallexample
6634%rename lib old_lib
6635
6636*lib:
6637--start-group -lgcc -lc -leval1 --end-group %(old_lib)
6638@end smallexample
6639
6640This example renames the spec called @samp{lib} to @samp{old_lib} and
6641then overrides the previous definition of @samp{lib} with a new one.
6642The new definition adds in some extra command-line options before
6643including the text of the old definition.
6644
6645@dfn{Spec strings} are a list of command-line options to be passed to their
6646corresponding program. In addition, the spec strings can contain
6647@samp{%}-prefixed sequences to substitute variable text or to
6648conditionally insert text into the command line. Using these constructs
6649it is possible to generate quite complex command lines.
6650
6651Here is a table of all defined @samp{%}-sequences for spec
6652strings. Note that spaces are not generated automatically around the
6653results of expanding these sequences. Therefore you can concatenate them
6654together or combine them with constant text in a single argument.
6655
6656@table @code
6657@item %%
6658Substitute one @samp{%} into the program name or argument.
6659
6660@item %i
6661Substitute the name of the input file being processed.
6662
6663@item %b
6664Substitute the basename of the input file being processed.
6665This is the substring up to (and not including) the last period
6666and not including the directory.
6667
6668@item %B
6669This is the same as @samp{%b}, but include the file suffix (text after
6670the last period).
6671
6672@item %d
6673Marks the argument containing or following the @samp{%d} as a
6674temporary file name, so that that file will be deleted if GCC exits
6675successfully. Unlike @samp{%g}, this contributes no text to the
6676argument.
6677
6678@item %g@var{suffix}
6679Substitute a file name that has suffix @var{suffix} and is chosen
6680once per compilation, and mark the argument in the same way as
6681@samp{%d}. To reduce exposure to denial-of-service attacks, the file
6682name is now chosen in a way that is hard to predict even when previously
6683chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
6684might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
6685the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
6686treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
6687was simply substituted with a file name chosen once per compilation,
6688without regard to any appended suffix (which was therefore treated
6689just like ordinary text), making such attacks more likely to succeed.
6690
6691@item %u@var{suffix}
6692Like @samp{%g}, but generates a new temporary file name even if
6693@samp{%u@var{suffix}} was already seen.
6694
6695@item %U@var{suffix}
6696Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
6697new one if there is no such last file name. In the absence of any
6698@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
6699the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
6700would involve the generation of two distinct file names, one
6701for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
6702simply substituted with a file name chosen for the previous @samp{%u},
6703without regard to any appended suffix.
6704
6705@item %j@var{suffix}
6706Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
6707writable, and if save-temps is off; otherwise, substitute the name
6708of a temporary file, just like @samp{%u}. This temporary file is not
6709meant for communication between processes, but rather as a junk
6710disposal mechanism.
6711
6712@item %|@var{suffix}
6713@itemx %m@var{suffix}
6714Like @samp{%g}, except if @option{-pipe} is in effect. In that case
6715@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
6716all. These are the two most common ways to instruct a program that it
6717should read from standard input or write to standard output. If you
6718need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
6719construct: see for example @file{f/lang-specs.h}.
6720
6721@item %.@var{SUFFIX}
6722Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
6723when it is subsequently output with @samp{%*}. @var{SUFFIX} is
6724terminated by the next space or %.
6725
6726@item %w
6727Marks the argument containing or following the @samp{%w} as the
6728designated output file of this compilation. This puts the argument
6729into the sequence of arguments that @samp{%o} will substitute later.
6730
6731@item %o
6732Substitutes the names of all the output files, with spaces
6733automatically placed around them. You should write spaces
6734around the @samp{%o} as well or the results are undefined.
6735@samp{%o} is for use in the specs for running the linker.
6736Input files whose names have no recognized suffix are not compiled
6737at all, but they are included among the output files, so they will
6738be linked.
6739
6740@item %O
6741Substitutes the suffix for object files. Note that this is
6742handled specially when it immediately follows @samp{%g, %u, or %U},
6743because of the need for those to form complete file names. The
6744handling is such that @samp{%O} is treated exactly as if it had already
6745been substituted, except that @samp{%g, %u, and %U} do not currently
6746support additional @var{suffix} characters following @samp{%O} as they would
6747following, for example, @samp{.o}.
6748
6749@item %p
6750Substitutes the standard macro predefinitions for the
6751current target machine. Use this when running @code{cpp}.
6752
6753@item %P
6754Like @samp{%p}, but puts @samp{__} before and after the name of each
6755predefined macro, except for macros that start with @samp{__} or with
6756@samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
6757C@.
6758
6759@item %I
6760Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
6761@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
6762@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
6763and @option{-imultilib} as necessary.
6764
6765@item %s
6766Current argument is the name of a library or startup file of some sort.
6767Search for that file in a standard list of directories and substitute
6768the full name found.
6769
6770@item %e@var{str}
6771Print @var{str} as an error message. @var{str} is terminated by a newline.
6772Use this when inconsistent options are detected.
6773
6774@item %(@var{name})
6775Substitute the contents of spec string @var{name} at this point.
6776
6777@item %[@var{name}]
6778Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
6779
6780@item %x@{@var{option}@}
6781Accumulate an option for @samp{%X}.
6782
6783@item %X
6784Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
6785spec string.
6786
6787@item %Y
6788Output the accumulated assembler options specified by @option{-Wa}.
6789
6790@item %Z
6791Output the accumulated preprocessor options specified by @option{-Wp}.
6792
6793@item %a
6794Process the @code{asm} spec. This is used to compute the
6795switches to be passed to the assembler.
6796
6797@item %A
6798Process the @code{asm_final} spec. This is a spec string for
6799passing switches to an assembler post-processor, if such a program is
6800needed.
6801
6802@item %l
6803Process the @code{link} spec. This is the spec for computing the
6804command line passed to the linker. Typically it will make use of the
6805@samp{%L %G %S %D and %E} sequences.
6806
6807@item %D
6808Dump out a @option{-L} option for each directory that GCC believes might
6809contain startup files. If the target supports multilibs then the
6810current multilib directory will be prepended to each of these paths.
6811
6812@item %L
6813Process the @code{lib} spec. This is a spec string for deciding which
6814libraries should be included on the command line to the linker.
6815
6816@item %G
6817Process the @code{libgcc} spec. This is a spec string for deciding
6818which GCC support library should be included on the command line to the linker.
6819
6820@item %S
6821Process the @code{startfile} spec. This is a spec for deciding which
6822object files should be the first ones passed to the linker. Typically
6823this might be a file named @file{crt0.o}.
6824
6825@item %E
6826Process the @code{endfile} spec. This is a spec string that specifies
6827the last object files that will be passed to the linker.
6828
6829@item %C
6830Process the @code{cpp} spec. This is used to construct the arguments
6831to be passed to the C preprocessor.
6832
6833@item %1
6834Process the @code{cc1} spec. This is used to construct the options to be
6835passed to the actual C compiler (@samp{cc1}).
6836
6837@item %2
6838Process the @code{cc1plus} spec. This is used to construct the options to be
6839passed to the actual C++ compiler (@samp{cc1plus}).
6840
6841@item %*
6842Substitute the variable part of a matched option. See below.
6843Note that each comma in the substituted string is replaced by
6844a single space.
6845
6846@item %<@code{S}
6847Remove all occurrences of @code{-S} from the command line. Note---this
6848command is position dependent. @samp{%} commands in the spec string
6849before this one will see @code{-S}, @samp{%} commands in the spec string
6850after this one will not.
6851
6852@item %:@var{function}(@var{args})
6853Call the named function @var{function}, passing it @var{args}.
6854@var{args} is first processed as a nested spec string, then split
6855into an argument vector in the usual fashion. The function returns
6856a string which is processed as if it had appeared literally as part
6857of the current spec.
6858
6859The following built-in spec functions are provided:
6860
6861@table @code
6862@item @code{if-exists}
6863The @code{if-exists} spec function takes one argument, an absolute
6864pathname to a file. If the file exists, @code{if-exists} returns the
6865pathname. Here is a small example of its usage:
6866
6867@smallexample
6868*startfile:
6869crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
6870@end smallexample
6871
6872@item @code{if-exists-else}
6873The @code{if-exists-else} spec function is similar to the @code{if-exists}
6874spec function, except that it takes two arguments. The first argument is
6875an absolute pathname to a file. If the file exists, @code{if-exists-else}
6876returns the pathname. If it does not exist, it returns the second argument.
6877This way, @code{if-exists-else} can be used to select one file or another,
6878based on the existence of the first. Here is a small example of its usage:
6879
6880@smallexample
6881*startfile:
6882crt0%O%s %:if-exists(crti%O%s) \
6883%:if-exists-else(crtbeginT%O%s crtbegin%O%s)
6884@end smallexample
6885
6886@item @code{replace-outfile}
6887The @code{replace-outfile} spec function takes two arguments. It looks for the
6888first argument in the outfiles array and replaces it with the second argument. Here
6889is a small example of its usage:
6890
6891@smallexample
6892%@{static|static-libgcc|static-libstdc++:%:replace-outfile(-lstdc++ \
6893libstdc++.a%s)@}
6894
6895@end smallexample
6896
6897@end table
6898
6899@item %@{@code{S}@}
6900Substitutes the @code{-S} switch, if that switch was given to GCC@.
6901If that switch was not specified, this substitutes nothing. Note that
6902the leading dash is omitted when specifying this option, and it is
6903automatically inserted if the substitution is performed. Thus the spec
6904string @samp{%@{foo@}} would match the command-line option @option{-foo}
6905and would output the command line option @option{-foo}.
6906
6907@item %W@{@code{S}@}
6908Like %@{@code{S}@} but mark last argument supplied within as a file to be
6909deleted on failure.
6910
6911@item %@{@code{S}*@}
6912Substitutes all the switches specified to GCC whose names start
6913with @code{-S}, but which also take an argument. This is used for
6914switches like @option{-o}, @option{-D}, @option{-I}, etc.
6915GCC considers @option{-o foo} as being
6916one switch whose names starts with @samp{o}. %@{o*@} would substitute this
6917text, including the space. Thus two arguments would be generated.
6918
6919@item %@{@code{S}*&@code{T}*@}
6920Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
6921(the order of @code{S} and @code{T} in the spec is not significant).
6922There can be any number of ampersand-separated variables; for each the
6923wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
6924
6925@item %@{@code{S}:@code{X}@}
6926Substitutes @code{X}, if the @samp{-S} switch was given to GCC@.
6927
6928@item %@{!@code{S}:@code{X}@}
6929Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@.
6930
6931@item %@{@code{S}*:@code{X}@}
6932Substitutes @code{X} if one or more switches whose names start with
6933@code{-S} are specified to GCC@. Normally @code{X} is substituted only
6934once, no matter how many such switches appeared. However, if @code{%*}
6935appears somewhere in @code{X}, then @code{X} will be substituted once
6936for each matching switch, with the @code{%*} replaced by the part of
6937that switch that matched the @code{*}.
6938
6939@item %@{.@code{S}:@code{X}@}
6940Substitutes @code{X}, if processing a file with suffix @code{S}.
6941
6942@item %@{!.@code{S}:@code{X}@}
6943Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
6944
6945@item %@{@code{S}|@code{P}:@code{X}@}
6946Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@.
6947This may be combined with @samp{!}, @samp{.}, and @code{*} sequences as well,
6948although they have a stronger binding than the @samp{|}. If @code{%*}
6949appears in @code{X}, all of the alternatives must be starred, and only
6950the first matching alternative is substituted.
6951
6952For example, a spec string like this:
6953
6954@smallexample
6955%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
6956@end smallexample
6957
6958will output the following command-line options from the following input
6959command-line options:
6960
6961@smallexample
6962fred.c -foo -baz
6963jim.d -bar -boggle
6964-d fred.c -foo -baz -boggle
6965-d jim.d -bar -baz -boggle
6966@end smallexample
6967
6968@item %@{S:X; T:Y; :D@}
6969
6970If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was
6971given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
6972be as many clauses as you need. This may be combined with @code{.},
6973@code{!}, @code{|}, and @code{*} as needed.
6974
6975
6976@end table
6977
6978The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
6979construct may contain other nested @samp{%} constructs or spaces, or
6980even newlines. They are processed as usual, as described above.
6981Trailing white space in @code{X} is ignored. White space may also
6982appear anywhere on the left side of the colon in these constructs,
6983except between @code{.} or @code{*} and the corresponding word.
6984
6985The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
6986handled specifically in these constructs. If another value of
6987@option{-O} or the negated form of a @option{-f}, @option{-m}, or
6988@option{-W} switch is found later in the command line, the earlier
6989switch value is ignored, except with @{@code{S}*@} where @code{S} is
6990just one letter, which passes all matching options.
6991
6992The character @samp{|} at the beginning of the predicate text is used to
6993indicate that a command should be piped to the following command, but
6994only if @option{-pipe} is specified.
6995
6996It is built into GCC which switches take arguments and which do not.
6997(You might think it would be useful to generalize this to allow each
6998compiler's spec to say which switches take arguments. But this cannot
6999be done in a consistent fashion. GCC cannot even decide which input
7000files have been specified without knowing which switches take arguments,
7001and it must know which input files to compile in order to tell which
7002compilers to run).
7003
7004GCC also knows implicitly that arguments starting in @option{-l} are to be
7005treated as compiler output files, and passed to the linker in their
7006proper position among the other output files.
7007
7008@c man begin OPTIONS
7009
7010@node Target Options
7011@section Specifying Target Machine and Compiler Version
7012@cindex target options
7013@cindex cross compiling
7014@cindex specifying machine version
7015@cindex specifying compiler version and target machine
7016@cindex compiler version, specifying
7017@cindex target machine, specifying
7018
7019The usual way to run GCC is to run the executable called @file{gcc}, or
7020@file{<machine>-gcc} when cross-compiling, or
7021@file{<machine>-gcc-<version>} to run a version other than the one that
7022was installed last. Sometimes this is inconvenient, so GCC provides
7023options that will switch to another cross-compiler or version.
7024
7025@table @gcctabopt
7026@item -b @var{machine}
7027@opindex b
7028The argument @var{machine} specifies the target machine for compilation.
7029
7030The value to use for @var{machine} is the same as was specified as the
7031machine type when configuring GCC as a cross-compiler. For
7032example, if a cross-compiler was configured with @samp{configure
7033arm-elf}, meaning to compile for an arm processor with elf binaries,
7034then you would specify @option{-b arm-elf} to run that cross compiler.
7035Because there are other options beginning with @option{-b}, the
7036configuration must contain a hyphen.
7037
7038@item -V @var{version}
7039@opindex V
7040The argument @var{version} specifies which version of GCC to run.
7041This is useful when multiple versions are installed. For example,
7042@var{version} might be @samp{4.0}, meaning to run GCC version 4.0.
7043@end table
7044
7045The @option{-V} and @option{-b} options work by running the
7046@file{<machine>-gcc-<version>} executable, so there's no real reason to
7047use them if you can just run that directly.
7048
7049@node Submodel Options
7050@section Hardware Models and Configurations
7051@cindex submodel options
7052@cindex specifying hardware config
7053@cindex hardware models and configurations, specifying
7054@cindex machine dependent options
7055
7056Earlier we discussed the standard option @option{-b} which chooses among
7057different installed compilers for completely different target
7058machines, such as VAX vs.@: 68000 vs.@: 80386.
7059
7060In addition, each of these target machine types can have its own
7061special options, starting with @samp{-m}, to choose among various
7062hardware models or configurations---for example, 68010 vs 68020,
7063floating coprocessor or none. A single installed version of the
7064compiler can compile for any model or configuration, according to the
7065options specified.
7066
7067Some configurations of the compiler also support additional special
7068options, usually for compatibility with other compilers on the same
7069platform.
7070
7071@c This list is ordered alphanumerically by subsection name.
7072@c It should be the same order and spelling as these options are listed
7073@c in Machine Dependent Options
7074
7075@menu
7076* ARC Options::
7077* ARM Options::
7078* AVR Options::
7079* Blackfin Options::
7080* CRIS Options::
7081* CRX Options::
7082* Darwin Options::
7083* DEC Alpha Options::
7084* DEC Alpha/VMS Options::
7085* FRV Options::
7086* GNU/Linux Options::
7087* H8/300 Options::
7088* HPPA Options::
7089* i386 and x86-64 Options::
7090* IA-64 Options::
7091* M32C Options::
7092* M32R/D Options::
7093* M680x0 Options::
7094* M68hc1x Options::
7095* MCore Options::
7096* MIPS Options::
7097* MMIX Options::
7098* MN10300 Options::
7099* MT Options::
7100* PDP-11 Options::
7101* PowerPC Options::
7102* RS/6000 and PowerPC Options::
7103* S/390 and zSeries Options::
7104* Score Options::
7105* SH Options::
7106* SPARC Options::
7107* System V Options::
7108* TMS320C3x/C4x Options::
7109* V850 Options::
7110* VAX Options::
7111* x86-64 Options::
7112* Xstormy16 Options::
7113* Xtensa Options::
7114* zSeries Options::
7115@end menu
7116
7117@node ARC Options
7118@subsection ARC Options
7119@cindex ARC Options
7120
7121These options are defined for ARC implementations:
7122
7123@table @gcctabopt
7124@item -EL
7125@opindex EL
7126Compile code for little endian mode. This is the default.
7127
7128@item -EB
7129@opindex EB
7130Compile code for big endian mode.
7131
7132@item -mmangle-cpu
7133@opindex mmangle-cpu
7134Prepend the name of the cpu to all public symbol names.
7135In multiple-processor systems, there are many ARC variants with different
7136instruction and register set characteristics. This flag prevents code
7137compiled for one cpu to be linked with code compiled for another.
7138No facility exists for handling variants that are ``almost identical''.
7139This is an all or nothing option.
7140
7141@item -mcpu=@var{cpu}
7142@opindex mcpu
7143Compile code for ARC variant @var{cpu}.
7144Which variants are supported depend on the configuration.
7145All variants support @option{-mcpu=base}, this is the default.
7146
7147@item -mtext=@var{text-section}
7148@itemx -mdata=@var{data-section}
7149@itemx -mrodata=@var{readonly-data-section}
7150@opindex mtext
7151@opindex mdata
7152@opindex mrodata
7153Put functions, data, and readonly data in @var{text-section},
7154@var{data-section}, and @var{readonly-data-section} respectively
7155by default. This can be overridden with the @code{section} attribute.
7156@xref{Variable Attributes}.
7157
7158@end table
7159
7160@node ARM Options
7161@subsection ARM Options
7162@cindex ARM options
7163
7164These @samp{-m} options are defined for Advanced RISC Machines (ARM)
7165architectures:
7166
7167@table @gcctabopt
7168@item -mabi=@var{name}
7169@opindex mabi
7170Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu},
7171@samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.
7172
7173@item -mapcs-frame
7174@opindex mapcs-frame
7175Generate a stack frame that is compliant with the ARM Procedure Call
7176Standard for all functions, even if this is not strictly necessary for
7177correct execution of the code. Specifying @option{-fomit-frame-pointer}
7178with this option will cause the stack frames not to be generated for
7179leaf functions. The default is @option{-mno-apcs-frame}.
7180
7181@item -mapcs
7182@opindex mapcs
7183This is a synonym for @option{-mapcs-frame}.
7184
7185@ignore
7186@c not currently implemented
7187@item -mapcs-stack-check
7188@opindex mapcs-stack-check
7189Generate code to check the amount of stack space available upon entry to
7190every function (that actually uses some stack space). If there is
7191insufficient space available then either the function
7192@samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
7193called, depending upon the amount of stack space required. The run time
7194system is required to provide these functions. The default is
7195@option{-mno-apcs-stack-check}, since this produces smaller code.
7196
7197@c not currently implemented
7198@item -mapcs-float
7199@opindex mapcs-float
7200Pass floating point arguments using the float point registers. This is
7201one of the variants of the APCS@. This option is recommended if the
7202target hardware has a floating point unit or if a lot of floating point
7203arithmetic is going to be performed by the code. The default is
7204@option{-mno-apcs-float}, since integer only code is slightly increased in
7205size if @option{-mapcs-float} is used.
7206
7207@c not currently implemented
7208@item -mapcs-reentrant
7209@opindex mapcs-reentrant
7210Generate reentrant, position independent code. The default is
7211@option{-mno-apcs-reentrant}.
7212@end ignore
7213
7214@item -mthumb-interwork
7215@opindex mthumb-interwork
7216Generate code which supports calling between the ARM and Thumb
7217instruction sets. Without this option the two instruction sets cannot
7218be reliably used inside one program. The default is
7219@option{-mno-thumb-interwork}, since slightly larger code is generated
7220when @option{-mthumb-interwork} is specified.
7221
7222@item -mno-sched-prolog
7223@opindex mno-sched-prolog
7224Prevent the reordering of instructions in the function prolog, or the
7225merging of those instruction with the instructions in the function's
7226body. This means that all functions will start with a recognizable set
7227of instructions (or in fact one of a choice from a small set of
7228different function prologues), and this information can be used to
7229locate the start if functions inside an executable piece of code. The
7230default is @option{-msched-prolog}.
7231
7232@item -mhard-float
7233@opindex mhard-float
7234Generate output containing floating point instructions. This is the
7235default.
7236
7237@item -msoft-float
7238@opindex msoft-float
7239Generate output containing library calls for floating point.
7240@strong{Warning:} the requisite libraries are not available for all ARM
7241targets. Normally the facilities of the machine's usual C compiler are
7242used, but this cannot be done directly in cross-compilation. You must make
7243your own arrangements to provide suitable library functions for
7244cross-compilation.
7245
7246@option{-msoft-float} changes the calling convention in the output file;
7247therefore, it is only useful if you compile @emph{all} of a program with
7248this option. In particular, you need to compile @file{libgcc.a}, the
7249library that comes with GCC, with @option{-msoft-float} in order for
7250this to work.
7251
7252@item -mfloat-abi=@var{name}
7253@opindex mfloat-abi
7254Specifies which ABI to use for floating point values. Permissible values
7255are: @samp{soft}, @samp{softfp} and @samp{hard}.
7256
7257@samp{soft} and @samp{hard} are equivalent to @option{-msoft-float}
7258and @option{-mhard-float} respectively. @samp{softfp} allows the generation
7259of floating point instructions, but still uses the soft-float calling
7260conventions.
7261
7262@item -mlittle-endian
7263@opindex mlittle-endian
7264Generate code for a processor running in little-endian mode. This is
7265the default for all standard configurations.
7266
7267@item -mbig-endian
7268@opindex mbig-endian
7269Generate code for a processor running in big-endian mode; the default is
7270to compile code for a little-endian processor.
7271
7272@item -mwords-little-endian
7273@opindex mwords-little-endian
7274This option only applies when generating code for big-endian processors.
7275Generate code for a little-endian word order but a big-endian byte
7276order. That is, a byte order of the form @samp{32107654}. Note: this
7277option should only be used if you require compatibility with code for
7278big-endian ARM processors generated by versions of the compiler prior to
72792.8.
7280
7281@item -mcpu=@var{name}
7282@opindex mcpu
7283This specifies the name of the target ARM processor. GCC uses this name
7284to determine what kind of instructions it can emit when generating
7285assembly code. Permissible names are: @samp{arm2}, @samp{arm250},
7286@samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
7287@samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
7288@samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
7289@samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
7290@samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},
7291@samp{arm8}, @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
7292@samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
7293@samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},
7294@samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},
7295@samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},
7296@samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
7297@samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
7298@samp{arm1176jz-s}, @samp{arm1176jzf-s}, @samp{xscale}, @samp{iwmmxt},
7299@samp{ep9312}.
7300
7301@itemx -mtune=@var{name}
7302@opindex mtune
7303This option is very similar to the @option{-mcpu=} option, except that
7304instead of specifying the actual target processor type, and hence
7305restricting which instructions can be used, it specifies that GCC should
7306tune the performance of the code as if the target were of the type
7307specified in this option, but still choosing the instructions that it
7308will generate based on the cpu specified by a @option{-mcpu=} option.
7309For some ARM implementations better performance can be obtained by using
7310this option.
7311
7312@item -march=@var{name}
7313@opindex march
7314This specifies the name of the target ARM architecture. GCC uses this
7315name to determine what kind of instructions it can emit when generating
7316assembly code. This option can be used in conjunction with or instead
7317of the @option{-mcpu=} option. Permissible names are: @samp{armv2},
7318@samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
7319@samp{armv5}, @samp{armv5t}, @samp{armv5te}, @samp{armv6}, @samp{armv6j},
7320@samp{iwmmxt}, @samp{ep9312}.
7321
7322@item -mfpu=@var{name}
7323@itemx -mfpe=@var{number}
7324@itemx -mfp=@var{number}
7325@opindex mfpu
7326@opindex mfpe
7327@opindex mfp
7328This specifies what floating point hardware (or hardware emulation) is
7329available on the target. Permissible names are: @samp{fpa}, @samp{fpe2},
7330@samp{fpe3}, @samp{maverick}, @samp{vfp}. @option{-mfp} and @option{-mfpe}
7331are synonyms for @option{-mfpu}=@samp{fpe}@var{number}, for compatibility
7332with older versions of GCC@.
7333
7334If @option{-msoft-float} is specified this specifies the format of
7335floating point values.
7336
7337@item -mstructure-size-boundary=@var{n}
7338@opindex mstructure-size-boundary
7339The size of all structures and unions will be rounded up to a multiple
7340of the number of bits set by this option. Permissible values are 8, 32
7341and 64. The default value varies for different toolchains. For the COFF
7342targeted toolchain the default value is 8. A value of 64 is only allowed
7343if the underlying ABI supports it.
7344
7345Specifying the larger number can produce faster, more efficient code, but
7346can also increase the size of the program. Different values are potentially
7347incompatible. Code compiled with one value cannot necessarily expect to
7348work with code or libraries compiled with another value, if they exchange
7349information using structures or unions.
7350
7351@item -mabort-on-noreturn
7352@opindex mabort-on-noreturn
7353Generate a call to the function @code{abort} at the end of a
7354@code{noreturn} function. It will be executed if the function tries to
7355return.
7356
7357@item -mlong-calls
7358@itemx -mno-long-calls
7359@opindex mlong-calls
7360@opindex mno-long-calls
7361Tells the compiler to perform function calls by first loading the
7362address of the function into a register and then performing a subroutine
7363call on this register. This switch is needed if the target function
7364will lie outside of the 64 megabyte addressing range of the offset based
7365version of subroutine call instruction.
7366
7367Even if this switch is enabled, not all function calls will be turned
7368into long calls. The heuristic is that static functions, functions
7369which have the @samp{short-call} attribute, functions that are inside
7370the scope of a @samp{#pragma no_long_calls} directive and functions whose
7371definitions have already been compiled within the current compilation
7372unit, will not be turned into long calls. The exception to this rule is
7373that weak function definitions, functions with the @samp{long-call}
7374attribute or the @samp{section} attribute, and functions that are within
7375the scope of a @samp{#pragma long_calls} directive, will always be
7376turned into long calls.
7377
7378This feature is not enabled by default. Specifying
7379@option{-mno-long-calls} will restore the default behavior, as will
7380placing the function calls within the scope of a @samp{#pragma
7381long_calls_off} directive. Note these switches have no effect on how
7382the compiler generates code to handle function calls via function
7383pointers.
7384
7385@item -mnop-fun-dllimport
7386@opindex mnop-fun-dllimport
7387Disable support for the @code{dllimport} attribute.
7388
7389@item -msingle-pic-base
7390@opindex msingle-pic-base
7391Treat the register used for PIC addressing as read-only, rather than
7392loading it in the prologue for each function. The run-time system is
7393responsible for initializing this register with an appropriate value
7394before execution begins.
7395
7396@item -mpic-register=@var{reg}
7397@opindex mpic-register
7398Specify the register to be used for PIC addressing. The default is R10
7399unless stack-checking is enabled, when R9 is used.
7400
7401@item -mcirrus-fix-invalid-insns
7402@opindex mcirrus-fix-invalid-insns
7403@opindex mno-cirrus-fix-invalid-insns
7404Insert NOPs into the instruction stream to in order to work around
7405problems with invalid Maverick instruction combinations. This option
7406is only valid if the @option{-mcpu=ep9312} option has been used to
7407enable generation of instructions for the Cirrus Maverick floating
7408point co-processor. This option is not enabled by default, since the
7409problem is only present in older Maverick implementations. The default
7410can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns}
7411switch.
7412
7413@item -mpoke-function-name
7414@opindex mpoke-function-name
7415Write the name of each function into the text section, directly
7416preceding the function prologue. The generated code is similar to this:
7417
7418@smallexample
7419 t0
7420 .ascii "arm_poke_function_name", 0
7421 .align
7422 t1
7423 .word 0xff000000 + (t1 - t0)
7424 arm_poke_function_name
7425 mov ip, sp
7426 stmfd sp!, @{fp, ip, lr, pc@}
7427 sub fp, ip, #4
7428@end smallexample
7429
7430When performing a stack backtrace, code can inspect the value of
7431@code{pc} stored at @code{fp + 0}. If the trace function then looks at
7432location @code{pc - 12} and the top 8 bits are set, then we know that
7433there is a function name embedded immediately preceding this location
7434and has length @code{((pc[-3]) & 0xff000000)}.
7435
7436@item -mthumb
7437@opindex mthumb
7438Generate code for the 16-bit Thumb instruction set. The default is to
7439use the 32-bit ARM instruction set.
7440
7441@item -mtpcs-frame
7442@opindex mtpcs-frame
7443Generate a stack frame that is compliant with the Thumb Procedure Call
7444Standard for all non-leaf functions. (A leaf function is one that does
7445not call any other functions.) The default is @option{-mno-tpcs-frame}.
7446
7447@item -mtpcs-leaf-frame
7448@opindex mtpcs-leaf-frame
7449Generate a stack frame that is compliant with the Thumb Procedure Call
7450Standard for all leaf functions. (A leaf function is one that does
7451not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
7452
7453@item -mcallee-super-interworking
7454@opindex mcallee-super-interworking
7455Gives all externally visible functions in the file being compiled an ARM
7456instruction set header which switches to Thumb mode before executing the
7457rest of the function. This allows these functions to be called from
7458non-interworking code.
7459
7460@item -mcaller-super-interworking
7461@opindex mcaller-super-interworking
7462Allows calls via function pointers (including virtual functions) to
7463execute correctly regardless of whether the target code has been
7464compiled for interworking or not. There is a small overhead in the cost
7465of executing a function pointer if this option is enabled.
7466
7467@item -mtp=@var{name}
7468@opindex mtp
7469Specify the access model for the thread local storage pointer. The valid
7470models are @option{soft}, which generates calls to @code{__aeabi_read_tp},
7471@option{cp15}, which fetches the thread pointer from @code{cp15} directly
7472(supported in the arm6k architecture), and @option{auto}, which uses the
7473best available method for the selected processor. The default setting is
7474@option{auto}.
7475
7476@end table
7477
7478@node AVR Options
7479@subsection AVR Options
7480@cindex AVR Options
7481
7482These options are defined for AVR implementations:
7483
7484@table @gcctabopt
7485@item -mmcu=@var{mcu}
7486@opindex mmcu
7487Specify ATMEL AVR instruction set or MCU type.
7488
7489Instruction set avr1 is for the minimal AVR core, not supported by the C
7490compiler, only for assembler programs (MCU types: at90s1200, attiny10,
7491attiny11, attiny12, attiny15, attiny28).
7492
7493Instruction set avr2 (default) is for the classic AVR core with up to
74948K program memory space (MCU types: at90s2313, at90s2323, attiny22,
7495at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
7496at90c8534, at90s8535).
7497
7498Instruction set avr3 is for the classic AVR core with up to 128K program
7499memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
7500
7501Instruction set avr4 is for the enhanced AVR core with up to 8K program
7502memory space (MCU types: atmega8, atmega83, atmega85).
7503
7504Instruction set avr5 is for the enhanced AVR core with up to 128K program
7505memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
7506atmega64, atmega128, at43usb355, at94k).
7507
7508@item -msize
7509@opindex msize
7510Output instruction sizes to the asm file.
7511
7512@item -minit-stack=@var{N}
7513@opindex minit-stack
7514Specify the initial stack address, which may be a symbol or numeric value,
7515@samp{__stack} is the default.
7516
7517@item -mno-interrupts
7518@opindex mno-interrupts
7519Generated code is not compatible with hardware interrupts.
7520Code size will be smaller.
7521
7522@item -mcall-prologues
7523@opindex mcall-prologues
7524Functions prologues/epilogues expanded as call to appropriate
7525subroutines. Code size will be smaller.
7526
7527@item -mno-tablejump
7528@opindex mno-tablejump
7529Do not generate tablejump insns which sometimes increase code size.
7530
7531@item -mtiny-stack
7532@opindex mtiny-stack
7533Change only the low 8 bits of the stack pointer.
7534
7535@item -mint8
7536@opindex mint8
7537Assume int to be 8 bit integer. This affects the sizes of all types: A
7538char will be 1 byte, an int will be 1 byte, an long will be 2 bytes
7539and long long will be 4 bytes. Please note that this option does not
7540comply to the C standards, but it will provide you with smaller code
7541size.
7542@end table
7543
7544@node Blackfin Options
7545@subsection Blackfin Options
7546@cindex Blackfin Options
7547
7548@table @gcctabopt
7549@item -momit-leaf-frame-pointer
7550@opindex momit-leaf-frame-pointer
7551Don't keep the frame pointer in a register for leaf functions. This
7552avoids the instructions to save, set up and restore frame pointers and
7553makes an extra register available in leaf functions. The option
7554@option{-fomit-frame-pointer} removes the frame pointer for all functions
7555which might make debugging harder.
7556
7557@item -mspecld-anomaly
7558@opindex mspecld-anomaly
7559When enabled, the compiler will ensure that the generated code does not
7560contain speculative loads after jump instructions. This option is enabled
7561by default.
7562
7563@item -mno-specld-anomaly
7564@opindex mno-specld-anomaly
7565Don't generate extra code to prevent speculative loads from occurring.
7566
7567@item -mcsync-anomaly
7568@opindex mcsync-anomaly
7569When enabled, the compiler will ensure that the generated code does not
7570contain CSYNC or SSYNC instructions too soon after conditional branches.
7571This option is enabled by default.
7572
7573@item -mno-csync-anomaly
7574@opindex mno-csync-anomaly
7575Don't generate extra code to prevent CSYNC or SSYNC instructions from
7576occurring too soon after a conditional branch.
7577
7578@item -mlow-64k
7579@opindex mlow-64k
7580When enabled, the compiler is free to take advantage of the knowledge that
7581the entire program fits into the low 64k of memory.
7582
7583@item -mno-low-64k
7584@opindex mno-low-64k
7585Assume that the program is arbitrarily large. This is the default.
7586
7587@item -mid-shared-library
7588@opindex mid-shared-library
7589Generate code that supports shared libraries via the library ID method.
7590This allows for execute in place and shared libraries in an environment
7591without virtual memory management. This option implies @option{-fPIC}.
7592
7593@item -mno-id-shared-library
7594@opindex mno-id-shared-library
7595Generate code that doesn't assume ID based shared libraries are being used.
7596This is the default.
7597
7598@item -mshared-library-id=n
7599@opindex mshared-library-id
7600Specified the identification number of the ID based shared library being
7601compiled. Specifying a value of 0 will generate more compact code, specifying
7602other values will force the allocation of that number to the current
7603library but is no more space or time efficient than omitting this option.
7604
7605@item -mlong-calls
7606@itemx -mno-long-calls
7607@opindex mlong-calls
7608@opindex mno-long-calls
7609Tells the compiler to perform function calls by first loading the
7610address of the function into a register and then performing a subroutine
7611call on this register. This switch is needed if the target function
7612will lie outside of the 24 bit addressing range of the offset based
7613version of subroutine call instruction.
7614
7615This feature is not enabled by default. Specifying
7616@option{-mno-long-calls} will restore the default behavior. Note these
7617switches have no effect on how the compiler generates code to handle
7618function calls via function pointers.
7619@end table
7620
7621@node CRIS Options
7622@subsection CRIS Options
7623@cindex CRIS Options
7624
7625These options are defined specifically for the CRIS ports.
7626
7627@table @gcctabopt
7628@item -march=@var{architecture-type}
7629@itemx -mcpu=@var{architecture-type}
7630@opindex march
7631@opindex mcpu
7632Generate code for the specified architecture. The choices for
7633@var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
7634respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
7635Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
7636@samp{v10}.
7637
7638@item -mtune=@var{architecture-type}
7639@opindex mtune
7640Tune to @var{architecture-type} everything applicable about the generated
7641code, except for the ABI and the set of available instructions. The
7642choices for @var{architecture-type} are the same as for
7643@option{-march=@var{architecture-type}}.
7644
7645@item -mmax-stack-frame=@var{n}
7646@opindex mmax-stack-frame
7647Warn when the stack frame of a function exceeds @var{n} bytes.
7648
7649@item -melinux-stacksize=@var{n}
7650@opindex melinux-stacksize
7651Only available with the @samp{cris-axis-aout} target. Arranges for
7652indications in the program to the kernel loader that the stack of the
7653program should be set to @var{n} bytes.
7654
7655@item -metrax4
7656@itemx -metrax100
7657@opindex metrax4
7658@opindex metrax100
7659The options @option{-metrax4} and @option{-metrax100} are synonyms for
7660@option{-march=v3} and @option{-march=v8} respectively.
7661
7662@item -mmul-bug-workaround
7663@itemx -mno-mul-bug-workaround
7664@opindex mmul-bug-workaround
7665@opindex mno-mul-bug-workaround
7666Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
7667models where it applies. This option is active by default.
7668
7669@item -mpdebug
7670@opindex mpdebug
7671Enable CRIS-specific verbose debug-related information in the assembly
7672code. This option also has the effect to turn off the @samp{#NO_APP}
7673formatted-code indicator to the assembler at the beginning of the
7674assembly file.
7675
7676@item -mcc-init
7677@opindex mcc-init
7678Do not use condition-code results from previous instruction; always emit
7679compare and test instructions before use of condition codes.
7680
7681@item -mno-side-effects
7682@opindex mno-side-effects
7683Do not emit instructions with side-effects in addressing modes other than
7684post-increment.
7685
7686@item -mstack-align
7687@itemx -mno-stack-align
7688@itemx -mdata-align
7689@itemx -mno-data-align
7690@itemx -mconst-align
7691@itemx -mno-const-align
7692@opindex mstack-align
7693@opindex mno-stack-align
7694@opindex mdata-align
7695@opindex mno-data-align
7696@opindex mconst-align
7697@opindex mno-const-align
7698These options (no-options) arranges (eliminate arrangements) for the
7699stack-frame, individual data and constants to be aligned for the maximum
7700single data access size for the chosen CPU model. The default is to
7701arrange for 32-bit alignment. ABI details such as structure layout are
7702not affected by these options.
7703
7704@item -m32-bit
7705@itemx -m16-bit
7706@itemx -m8-bit
7707@opindex m32-bit
7708@opindex m16-bit
7709@opindex m8-bit
7710Similar to the stack- data- and const-align options above, these options
7711arrange for stack-frame, writable data and constants to all be 32-bit,
771216-bit or 8-bit aligned. The default is 32-bit alignment.
7713
7714@item -mno-prologue-epilogue
7715@itemx -mprologue-epilogue
7716@opindex mno-prologue-epilogue
7717@opindex mprologue-epilogue
7718With @option{-mno-prologue-epilogue}, the normal function prologue and
7719epilogue that sets up the stack-frame are omitted and no return
7720instructions or return sequences are generated in the code. Use this
7721option only together with visual inspection of the compiled code: no
7722warnings or errors are generated when call-saved registers must be saved,
7723or storage for local variable needs to be allocated.
7724
7725@item -mno-gotplt
7726@itemx -mgotplt
7727@opindex mno-gotplt
7728@opindex mgotplt
7729With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
7730instruction sequences that load addresses for functions from the PLT part
7731of the GOT rather than (traditional on other architectures) calls to the
7732PLT@. The default is @option{-mgotplt}.
7733
7734@item -maout
7735@opindex maout
7736Legacy no-op option only recognized with the cris-axis-aout target.
7737
7738@item -melf
7739@opindex melf
7740Legacy no-op option only recognized with the cris-axis-elf and
7741cris-axis-linux-gnu targets.
7742
7743@item -melinux
7744@opindex melinux
7745Only recognized with the cris-axis-aout target, where it selects a
7746GNU/linux-like multilib, include files and instruction set for
7747@option{-march=v8}.
7748
7749@item -mlinux
7750@opindex mlinux
7751Legacy no-op option only recognized with the cris-axis-linux-gnu target.
7752
7753@item -sim
7754@opindex sim
7755This option, recognized for the cris-axis-aout and cris-axis-elf arranges
7756to link with input-output functions from a simulator library. Code,
7757initialized data and zero-initialized data are allocated consecutively.
7758
7759@item -sim2
7760@opindex sim2
7761Like @option{-sim}, but pass linker options to locate initialized data at
77620x40000000 and zero-initialized data at 0x80000000.
7763@end table
7764
7765@node CRX Options
7766@subsection CRX Options
7767@cindex CRX Options
7768
7769These options are defined specifically for the CRX ports.
7770
7771@table @gcctabopt
7772
7773@item -mmac
7774@opindex mmac
7775Enable the use of multiply-accumulate instructions. Disabled by default.
7776
7777@item -mpush-args
7778@opindex mpush-args
7779Push instructions will be used to pass outgoing arguments when functions
7780are called. Enabled by default.
7781@end table
7782
7783@node Darwin Options
7784@subsection Darwin Options
7785@cindex Darwin options
7786
7787These options are defined for all architectures running the Darwin operating
7788system.
7789
7790FSF GCC on Darwin does not create ``fat'' object files; it will create
7791an object file for the single architecture that it was built to
7792target. Apple's GCC on Darwin does create ``fat'' files if multiple
7793@option{-arch} options are used; it does so by running the compiler or
7794linker multiple times and joining the results together with
7795@file{lipo}.
7796
7797The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
7798@samp{i686}) is determined by the flags that specify the ISA
7799that GCC is targetting, like @option{-mcpu} or @option{-march}. The
7800@option{-force_cpusubtype_ALL} option can be used to override this.
7801
7802The Darwin tools vary in their behavior when presented with an ISA
7803mismatch. The assembler, @file{as}, will only permit instructions to
7804be used that are valid for the subtype of the file it is generating,
7805so you cannot put 64-bit instructions in an @samp{ppc750} object file.
7806The linker for shared libraries, @file{/usr/bin/libtool}, will fail
7807and print an error if asked to create a shared library with a less
7808restrictive subtype than its input files (for instance, trying to put
7809a @samp{ppc970} object file in a @samp{ppc7400} library). The linker
7810for executables, @file{ld}, will quietly give the executable the most
7811restrictive subtype of any of its input files.
7812
7813@table @gcctabopt
7814@item -F@var{dir}
7815@opindex F
7816Add the framework directory @var{dir} to the head of the list of
7817directories to be searched for header files. These directories are
7818interleaved with those specified by @option{-I} options and are
7819scanned in a left-to-right order.
7820
7821A framework directory is a directory with frameworks in it. A
7822framework is a directory with a @samp{"Headers"} and/or
7823@samp{"PrivateHeaders"} directory contained directly in it that ends
7824in @samp{".framework"}. The name of a framework is the name of this
7825directory excluding the @samp{".framework"}. Headers associated with
7826the framework are found in one of those two directories, with
7827@samp{"Headers"} being searched first. A subframework is a framework
7828directory that is in a framework's @samp{"Frameworks"} directory.
7829Includes of subframework headers can only appear in a header of a
7830framework that contains the subframework, or in a sibling subframework
7831header. Two subframeworks are siblings if they occur in the same
7832framework. A subframework should not have the same name as a
7833framework, a warning will be issued if this is violated. Currently a
7834subframework cannot have subframeworks, in the future, the mechanism
7835may be extended to support this. The standard frameworks can be found
7836in @samp{"/System/Library/Frameworks"} and
7837@samp{"/Library/Frameworks"}. An example include looks like
7838@code{#include <Framework/header.h>}, where @samp{Framework} denotes
7839the name of the framework and header.h is found in the
7840@samp{"PrivateHeaders"} or @samp{"Headers"} directory.
7841
7842@item -gused
7843@opindex gused
7844Emit debugging information for symbols that are used. For STABS
7845debugging format, this enables @option{-feliminate-unused-debug-symbols}.
7846This is by default ON@.
7847
7848@item -gfull
7849@opindex gfull
7850Emit debugging information for all symbols and types.
7851
7852@item -mmacosx-version-min=@var{version}
7853The earliest version of MacOS X that this executable will run on
7854is @var{version}. Typical values of @var{version} include @code{10.1},
7855@code{10.2}, and @code{10.3.9}.
7856
7857The default for this option is to make choices that seem to be most
7858useful.
7859
7860@item -mkernel
7861@opindex mkernel
7862Enable kernel development mode. The @option{-mkernel} option sets
7863@option{-static}, @option{-fno-common}, @option{-fno-cxa-atexit},
7864@option{-fno-exceptions}, @option{-fno-non-call-exceptions},
7865@option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where
7866applicable. This mode also sets @option{-mno-altivec},
7867@option{-msoft-float}, @option{-fno-builtin} and
7868@option{-mlong-branch} for PowerPC targets.
7869
7870@item -mone-byte-bool
7871@opindex mone-byte-bool
7872Override the defaults for @samp{bool} so that @samp{sizeof(bool)==1}.
7873By default @samp{sizeof(bool)} is @samp{4} when compiling for
7874Darwin/PowerPC and @samp{1} when compiling for Darwin/x86, so this
7875option has no effect on x86.
7876
7877@strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
7878to generate code that is not binary compatible with code generated
7879without that switch. Using this switch may require recompiling all
7880other modules in a program, including system libraries. Use this
7881switch to conform to a non-default data model.
7882
7883@item -mfix-and-continue
7884@itemx -ffix-and-continue
7885@itemx -findirect-data
7886@opindex mfix-and-continue
7887@opindex ffix-and-continue
7888@opindex findirect-data
7889Generate code suitable for fast turn around development. Needed to
7890enable gdb to dynamically load @code{.o} files into already running
7891programs. @option{-findirect-data} and @option{-ffix-and-continue}
7892are provided for backwards compatibility.
7893
7894@item -all_load
7895@opindex all_load
7896Loads all members of static archive libraries.
7897See man ld(1) for more information.
7898
7899@item -arch_errors_fatal
7900@opindex arch_errors_fatal
7901Cause the errors having to do with files that have the wrong architecture
7902to be fatal.
7903
7904@item -bind_at_load
7905@opindex bind_at_load
7906Causes the output file to be marked such that the dynamic linker will
7907bind all undefined references when the file is loaded or launched.
7908
7909@item -bundle
7910@opindex bundle
7911Produce a Mach-o bundle format file.
7912See man ld(1) for more information.
7913
7914@item -bundle_loader @var{executable}
7915@opindex bundle_loader
7916This option specifies the @var{executable} that will be loading the build
7917output file being linked. See man ld(1) for more information.
7918
7919@item -dynamiclib
7920@opindex dynamiclib
7921When passed this option, GCC will produce a dynamic library instead of
7922an executable when linking, using the Darwin @file{libtool} command.
7923
7924@item -force_cpusubtype_ALL
7925@opindex force_cpusubtype_ALL
7926This causes GCC's output file to have the @var{ALL} subtype, instead of
7927one controlled by the @option{-mcpu} or @option{-march} option.
7928
7929@item -allowable_client @var{client_name}
7930@itemx -client_name
7931@itemx -compatibility_version
7932@itemx -current_version
7933@itemx -dead_strip
7934@itemx -dependency-file
7935@itemx -dylib_file
7936@itemx -dylinker_install_name
7937@itemx -dynamic
7938@itemx -exported_symbols_list
7939@itemx -filelist
7940@itemx -flat_namespace
7941@itemx -force_flat_namespace
7942@itemx -headerpad_max_install_names
7943@itemx -image_base
7944@itemx -init
7945@itemx -install_name
7946@itemx -keep_private_externs
7947@itemx -multi_module
7948@itemx -multiply_defined
7949@itemx -multiply_defined_unused
7950@itemx -noall_load
7951@itemx -no_dead_strip_inits_and_terms
7952@itemx -nofixprebinding
7953@itemx -nomultidefs
7954@itemx -noprebind
7955@itemx -noseglinkedit
7956@itemx -pagezero_size
7957@itemx -prebind
7958@itemx -prebind_all_twolevel_modules
7959@itemx -private_bundle
7960@itemx -read_only_relocs
7961@itemx -sectalign
7962@itemx -sectobjectsymbols
7963@itemx -whyload
7964@itemx -seg1addr
7965@itemx -sectcreate
7966@itemx -sectobjectsymbols
7967@itemx -sectorder
7968@itemx -segaddr
7969@itemx -segs_read_only_addr
7970@itemx -segs_read_write_addr
7971@itemx -seg_addr_table
7972@itemx -seg_addr_table_filename
7973@itemx -seglinkedit
7974@itemx -segprot
7975@itemx -segs_read_only_addr
7976@itemx -segs_read_write_addr
7977@itemx -single_module
7978@itemx -static
7979@itemx -sub_library
7980@itemx -sub_umbrella
7981@itemx -twolevel_namespace
7982@itemx -umbrella
7983@itemx -undefined
7984@itemx -unexported_symbols_list
7985@itemx -weak_reference_mismatches
7986@itemx -whatsloaded
7987
7988@opindex allowable_client
7989@opindex client_name
7990@opindex compatibility_version
7991@opindex current_version
7992@opindex dead_strip
7993@opindex dependency-file
7994@opindex dylib_file
7995@opindex dylinker_install_name
7996@opindex dynamic
7997@opindex exported_symbols_list
7998@opindex filelist
7999@opindex flat_namespace
8000@opindex force_flat_namespace
8001@opindex headerpad_max_install_names
8002@opindex image_base
8003@opindex init
8004@opindex install_name
8005@opindex keep_private_externs
8006@opindex multi_module
8007@opindex multiply_defined
8008@opindex multiply_defined_unused
8009@opindex noall_load
8010@opindex no_dead_strip_inits_and_terms
8011@opindex nofixprebinding
8012@opindex nomultidefs
8013@opindex noprebind
8014@opindex noseglinkedit
8015@opindex pagezero_size
8016@opindex prebind
8017@opindex prebind_all_twolevel_modules
8018@opindex private_bundle
8019@opindex read_only_relocs
8020@opindex sectalign
8021@opindex sectobjectsymbols
8022@opindex whyload
8023@opindex seg1addr
8024@opindex sectcreate
8025@opindex sectobjectsymbols
8026@opindex sectorder
8027@opindex segaddr
8028@opindex segs_read_only_addr
8029@opindex segs_read_write_addr
8030@opindex seg_addr_table
8031@opindex seg_addr_table_filename
8032@opindex seglinkedit
8033@opindex segprot
8034@opindex segs_read_only_addr
8035@opindex segs_read_write_addr
8036@opindex single_module
8037@opindex static
8038@opindex sub_library
8039@opindex sub_umbrella
8040@opindex twolevel_namespace
8041@opindex umbrella
8042@opindex undefined
8043@opindex unexported_symbols_list
8044@opindex weak_reference_mismatches
8045@opindex whatsloaded
8046
8047These options are passed to the Darwin linker. The Darwin linker man page
8048describes them in detail.
8049@end table
8050
8051@node DEC Alpha Options
8052@subsection DEC Alpha Options
8053
8054These @samp{-m} options are defined for the DEC Alpha implementations:
8055
8056@table @gcctabopt
8057@item -mno-soft-float
8058@itemx -msoft-float
8059@opindex mno-soft-float
8060@opindex msoft-float
8061Use (do not use) the hardware floating-point instructions for
8062floating-point operations. When @option{-msoft-float} is specified,
8063functions in @file{libgcc.a} will be used to perform floating-point
8064operations. Unless they are replaced by routines that emulate the
8065floating-point operations, or compiled in such a way as to call such
8066emulations routines, these routines will issue floating-point
8067operations. If you are compiling for an Alpha without floating-point
8068operations, you must ensure that the library is built so as not to call
8069them.
8070
8071Note that Alpha implementations without floating-point operations are
8072required to have floating-point registers.
8073
8074@item -mfp-reg
8075@itemx -mno-fp-regs
8076@opindex mfp-reg
8077@opindex mno-fp-regs
8078Generate code that uses (does not use) the floating-point register set.
8079@option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
8080register set is not used, floating point operands are passed in integer
8081registers as if they were integers and floating-point results are passed
8082in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
8083so any function with a floating-point argument or return value called by code
8084compiled with @option{-mno-fp-regs} must also be compiled with that
8085option.
8086
8087A typical use of this option is building a kernel that does not use,
8088and hence need not save and restore, any floating-point registers.
8089
8090@item -mieee
8091@opindex mieee
8092The Alpha architecture implements floating-point hardware optimized for
8093maximum performance. It is mostly compliant with the IEEE floating
8094point standard. However, for full compliance, software assistance is
8095required. This option generates code fully IEEE compliant code
8096@emph{except} that the @var{inexact-flag} is not maintained (see below).
8097If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
8098defined during compilation. The resulting code is less efficient but is
8099able to correctly support denormalized numbers and exceptional IEEE
8100values such as not-a-number and plus/minus infinity. Other Alpha
8101compilers call this option @option{-ieee_with_no_inexact}.
8102
8103@item -mieee-with-inexact
8104@opindex mieee-with-inexact
8105This is like @option{-mieee} except the generated code also maintains
8106the IEEE @var{inexact-flag}. Turning on this option causes the
8107generated code to implement fully-compliant IEEE math. In addition to
8108@code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
8109macro. On some Alpha implementations the resulting code may execute
8110significantly slower than the code generated by default. Since there is
8111very little code that depends on the @var{inexact-flag}, you should
8112normally not specify this option. Other Alpha compilers call this
8113option @option{-ieee_with_inexact}.
8114
8115@item -mfp-trap-mode=@var{trap-mode}
8116@opindex mfp-trap-mode
8117This option controls what floating-point related traps are enabled.
8118Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
8119The trap mode can be set to one of four values:
8120
8121@table @samp
8122@item n
8123This is the default (normal) setting. The only traps that are enabled
8124are the ones that cannot be disabled in software (e.g., division by zero
8125trap).
8126
8127@item u
8128In addition to the traps enabled by @samp{n}, underflow traps are enabled
8129as well.
8130
8131@item su
8132Like @samp{u}, but the instructions are marked to be safe for software
8133completion (see Alpha architecture manual for details).
8134
8135@item sui
8136Like @samp{su}, but inexact traps are enabled as well.
8137@end table
8138
8139@item -mfp-rounding-mode=@var{rounding-mode}
8140@opindex mfp-rounding-mode
8141Selects the IEEE rounding mode. Other Alpha compilers call this option
8142@option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
8143of:
8144
8145@table @samp
8146@item n
8147Normal IEEE rounding mode. Floating point numbers are rounded towards
8148the nearest machine number or towards the even machine number in case
8149of a tie.
8150
8151@item m
8152Round towards minus infinity.
8153
8154@item c
8155Chopped rounding mode. Floating point numbers are rounded towards zero.
8156
8157@item d
8158Dynamic rounding mode. A field in the floating point control register
8159(@var{fpcr}, see Alpha architecture reference manual) controls the
8160rounding mode in effect. The C library initializes this register for
8161rounding towards plus infinity. Thus, unless your program modifies the
8162@var{fpcr}, @samp{d} corresponds to round towards plus infinity.
8163@end table
8164
8165@item -mtrap-precision=@var{trap-precision}
8166@opindex mtrap-precision
8167In the Alpha architecture, floating point traps are imprecise. This
8168means without software assistance it is impossible to recover from a
8169floating trap and program execution normally needs to be terminated.
8170GCC can generate code that can assist operating system trap handlers
8171in determining the exact location that caused a floating point trap.
8172Depending on the requirements of an application, different levels of
8173precisions can be selected:
8174
8175@table @samp
8176@item p
8177Program precision. This option is the default and means a trap handler
8178can only identify which program caused a floating point exception.
8179
8180@item f
8181Function precision. The trap handler can determine the function that
8182caused a floating point exception.
8183
8184@item i
8185Instruction precision. The trap handler can determine the exact
8186instruction that caused a floating point exception.
8187@end table
8188
8189Other Alpha compilers provide the equivalent options called
8190@option{-scope_safe} and @option{-resumption_safe}.
8191
8192@item -mieee-conformant
8193@opindex mieee-conformant
8194This option marks the generated code as IEEE conformant. You must not
8195use this option unless you also specify @option{-mtrap-precision=i} and either
8196@option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
8197is to emit the line @samp{.eflag 48} in the function prologue of the
8198generated assembly file. Under DEC Unix, this has the effect that
8199IEEE-conformant math library routines will be linked in.
8200
8201@item -mbuild-constants
8202@opindex mbuild-constants
8203Normally GCC examines a 32- or 64-bit integer constant to
8204see if it can construct it from smaller constants in two or three
8205instructions. If it cannot, it will output the constant as a literal and
8206generate code to load it from the data segment at runtime.
8207
8208Use this option to require GCC to construct @emph{all} integer constants
8209using code, even if it takes more instructions (the maximum is six).
8210
8211You would typically use this option to build a shared library dynamic
8212loader. Itself a shared library, it must relocate itself in memory
8213before it can find the variables and constants in its own data segment.
8214
8215@item -malpha-as
8216@itemx -mgas
8217@opindex malpha-as
8218@opindex mgas
8219Select whether to generate code to be assembled by the vendor-supplied
8220assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
8221
8222@item -mbwx
8223@itemx -mno-bwx
8224@itemx -mcix
8225@itemx -mno-cix
8226@itemx -mfix
8227@itemx -mno-fix
8228@itemx -mmax
8229@itemx -mno-max
8230@opindex mbwx
8231@opindex mno-bwx
8232@opindex mcix
8233@opindex mno-cix
8234@opindex mfix
8235@opindex mno-fix
8236@opindex mmax
8237@opindex mno-max
8238Indicate whether GCC should generate code to use the optional BWX,
8239CIX, FIX and MAX instruction sets. The default is to use the instruction
8240sets supported by the CPU type specified via @option{-mcpu=} option or that
8241of the CPU on which GCC was built if none was specified.
8242
8243@item -mfloat-vax
8244@itemx -mfloat-ieee
8245@opindex mfloat-vax
8246@opindex mfloat-ieee
8247Generate code that uses (does not use) VAX F and G floating point
8248arithmetic instead of IEEE single and double precision.
8249
8250@item -mexplicit-relocs
8251@itemx -mno-explicit-relocs
8252@opindex mexplicit-relocs
8253@opindex mno-explicit-relocs
8254Older Alpha assemblers provided no way to generate symbol relocations
8255except via assembler macros. Use of these macros does not allow
8256optimal instruction scheduling. GNU binutils as of version 2.12
8257supports a new syntax that allows the compiler to explicitly mark
8258which relocations should apply to which instructions. This option
8259is mostly useful for debugging, as GCC detects the capabilities of
8260the assembler when it is built and sets the default accordingly.
8261
8262@item -msmall-data
8263@itemx -mlarge-data
8264@opindex msmall-data
8265@opindex mlarge-data
8266When @option{-mexplicit-relocs} is in effect, static data is
8267accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
8268is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
8269(the @code{.sdata} and @code{.sbss} sections) and are accessed via
827016-bit relocations off of the @code{$gp} register. This limits the
8271size of the small data area to 64KB, but allows the variables to be
8272directly accessed via a single instruction.
8273
8274The default is @option{-mlarge-data}. With this option the data area
8275is limited to just below 2GB@. Programs that require more than 2GB of
8276data must use @code{malloc} or @code{mmap} to allocate the data in the
8277heap instead of in the program's data segment.
8278
8279When generating code for shared libraries, @option{-fpic} implies
8280@option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
8281
8282@item -msmall-text
8283@itemx -mlarge-text
8284@opindex msmall-text
8285@opindex mlarge-text
8286When @option{-msmall-text} is used, the compiler assumes that the
8287code of the entire program (or shared library) fits in 4MB, and is
8288thus reachable with a branch instruction. When @option{-msmall-data}
8289is used, the compiler can assume that all local symbols share the
8290same @code{$gp} value, and thus reduce the number of instructions
8291required for a function call from 4 to 1.
8292
8293The default is @option{-mlarge-text}.
8294
8295@item -mcpu=@var{cpu_type}
8296@opindex mcpu
8297Set the instruction set and instruction scheduling parameters for
8298machine type @var{cpu_type}. You can specify either the @samp{EV}
8299style name or the corresponding chip number. GCC supports scheduling
8300parameters for the EV4, EV5 and EV6 family of processors and will
8301choose the default values for the instruction set from the processor
8302you specify. If you do not specify a processor type, GCC will default
8303to the processor on which the compiler was built.
8304
8305Supported values for @var{cpu_type} are
8306
8307@table @samp
8308@item ev4
8309@itemx ev45
8310@itemx 21064
8311Schedules as an EV4 and has no instruction set extensions.
8312
8313@item ev5
8314@itemx 21164
8315Schedules as an EV5 and has no instruction set extensions.
8316
8317@item ev56
8318@itemx 21164a
8319Schedules as an EV5 and supports the BWX extension.
8320
8321@item pca56
8322@itemx 21164pc
8323@itemx 21164PC
8324Schedules as an EV5 and supports the BWX and MAX extensions.
8325
8326@item ev6
8327@itemx 21264
8328Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
8329
8330@item ev67
8331@itemx 21264a
8332Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
8333@end table
8334
8335@item -mtune=@var{cpu_type}
8336@opindex mtune
8337Set only the instruction scheduling parameters for machine type
8338@var{cpu_type}. The instruction set is not changed.
8339
8340@item -mmemory-latency=@var{time}
8341@opindex mmemory-latency
8342Sets the latency the scheduler should assume for typical memory
8343references as seen by the application. This number is highly
8344dependent on the memory access patterns used by the application
8345and the size of the external cache on the machine.
8346
8347Valid options for @var{time} are
8348
8349@table @samp
8350@item @var{number}
8351A decimal number representing clock cycles.
8352
8353@item L1
8354@itemx L2
8355@itemx L3
8356@itemx main
8357The compiler contains estimates of the number of clock cycles for
8358``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
8359(also called Dcache, Scache, and Bcache), as well as to main memory.
8360Note that L3 is only valid for EV5.
8361
8362@end table
8363@end table
8364
8365@node DEC Alpha/VMS Options
8366@subsection DEC Alpha/VMS Options
8367
8368These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
8369
8370@table @gcctabopt
8371@item -mvms-return-codes
8372@opindex mvms-return-codes
8373Return VMS condition codes from main. The default is to return POSIX
8374style condition (e.g.@ error) codes.
8375@end table
8376
8377@node FRV Options
8378@subsection FRV Options
8379@cindex FRV Options
8380
8381@table @gcctabopt
8382@item -mgpr-32
8383@opindex mgpr-32
8384
8385Only use the first 32 general purpose registers.
8386
8387@item -mgpr-64
8388@opindex mgpr-64
8389
8390Use all 64 general purpose registers.
8391
8392@item -mfpr-32
8393@opindex mfpr-32
8394
8395Use only the first 32 floating point registers.
8396
8397@item -mfpr-64
8398@opindex mfpr-64
8399
8400Use all 64 floating point registers
8401
8402@item -mhard-float
8403@opindex mhard-float
8404
8405Use hardware instructions for floating point operations.
8406
8407@item -msoft-float
8408@opindex msoft-float
8409
8410Use library routines for floating point operations.
8411
8412@item -malloc-cc
8413@opindex malloc-cc
8414
8415Dynamically allocate condition code registers.
8416
8417@item -mfixed-cc
8418@opindex mfixed-cc
8419
8420Do not try to dynamically allocate condition code registers, only
8421use @code{icc0} and @code{fcc0}.
8422
8423@item -mdword
8424@opindex mdword
8425
8426Change ABI to use double word insns.
8427
8428@item -mno-dword
8429@opindex mno-dword
8430
8431Do not use double word instructions.
8432
8433@item -mdouble
8434@opindex mdouble
8435
8436Use floating point double instructions.
8437
8438@item -mno-double
8439@opindex mno-double
8440
8441Do not use floating point double instructions.
8442
8443@item -mmedia
8444@opindex mmedia
8445
8446Use media instructions.
8447
8448@item -mno-media
8449@opindex mno-media
8450
8451Do not use media instructions.
8452
8453@item -mmuladd
8454@opindex mmuladd
8455
8456Use multiply and add/subtract instructions.
8457
8458@item -mno-muladd
8459@opindex mno-muladd
8460
8461Do not use multiply and add/subtract instructions.
8462
8463@item -mfdpic
8464@opindex mfdpic
8465
8466Select the FDPIC ABI, that uses function descriptors to represent
8467pointers to functions. Without any PIC/PIE-related options, it
8468implies @option{-fPIE}. With @option{-fpic} or @option{-fpie}, it
8469assumes GOT entries and small data are within a 12-bit range from the
8470GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
8471are computed with 32 bits.
8472
8473@item -minline-plt
8474@opindex minline-plt
8475
8476Enable inlining of PLT entries in function calls to functions that are
8477not known to bind locally. It has no effect without @option{-mfdpic}.
8478It's enabled by default if optimizing for speed and compiling for
8479shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
8480optimization option such as @option{-O3} or above is present in the
8481command line.
8482
8483@item -mTLS
8484@opindex TLS
8485
8486Assume a large TLS segment when generating thread-local code.
8487
8488@item -mtls
8489@opindex tls
8490
8491Do not assume a large TLS segment when generating thread-local code.
8492
8493@item -mgprel-ro
8494@opindex mgprel-ro
8495
8496Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
8497that is known to be in read-only sections. It's enabled by default,
8498except for @option{-fpic} or @option{-fpie}: even though it may help
8499make the global offset table smaller, it trades 1 instruction for 4.
8500With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
8501one of which may be shared by multiple symbols, and it avoids the need
8502for a GOT entry for the referenced symbol, so it's more likely to be a
8503win. If it is not, @option{-mno-gprel-ro} can be used to disable it.
8504
8505@item -multilib-library-pic
8506@opindex multilib-library-pic
8507
8508Link with the (library, not FD) pic libraries. It's implied by
8509@option{-mlibrary-pic}, as well as by @option{-fPIC} and
8510@option{-fpic} without @option{-mfdpic}. You should never have to use
8511it explicitly.
8512
8513@item -mlinked-fp
8514@opindex mlinked-fp
8515
8516Follow the EABI requirement of always creating a frame pointer whenever
8517a stack frame is allocated. This option is enabled by default and can
8518be disabled with @option{-mno-linked-fp}.
8519
8520@item -mlong-calls
8521@opindex mlong-calls
8522
8523Use indirect addressing to call functions outside the current
8524compilation unit. This allows the functions to be placed anywhere
8525within the 32-bit address space.
8526
8527@item -malign-labels
8528@opindex malign-labels
8529
8530Try to align labels to an 8-byte boundary by inserting nops into the
8531previous packet. This option only has an effect when VLIW packing
8532is enabled. It doesn't create new packets; it merely adds nops to
8533existing ones.
8534
8535@item -mlibrary-pic
8536@opindex mlibrary-pic
8537
8538Generate position-independent EABI code.
8539
8540@item -macc-4
8541@opindex macc-4
8542
8543Use only the first four media accumulator registers.
8544
8545@item -macc-8
8546@opindex macc-8
8547
8548Use all eight media accumulator registers.
8549
8550@item -mpack
8551@opindex mpack
8552
8553Pack VLIW instructions.
8554
8555@item -mno-pack
8556@opindex mno-pack
8557
8558Do not pack VLIW instructions.
8559
8560@item -mno-eflags
8561@opindex mno-eflags
8562
8563Do not mark ABI switches in e_flags.
8564
8565@item -mcond-move
8566@opindex mcond-move
8567
8568Enable the use of conditional-move instructions (default).
8569
8570This switch is mainly for debugging the compiler and will likely be removed
8571in a future version.
8572
8573@item -mno-cond-move
8574@opindex mno-cond-move
8575
8576Disable the use of conditional-move instructions.
8577
8578This switch is mainly for debugging the compiler and will likely be removed
8579in a future version.
8580
8581@item -mscc
8582@opindex mscc
8583
8584Enable the use of conditional set instructions (default).
8585
8586This switch is mainly for debugging the compiler and will likely be removed
8587in a future version.
8588
8589@item -mno-scc
8590@opindex mno-scc
8591
8592Disable the use of conditional set instructions.
8593
8594This switch is mainly for debugging the compiler and will likely be removed
8595in a future version.
8596
8597@item -mcond-exec
8598@opindex mcond-exec
8599
8600Enable the use of conditional execution (default).
8601
8602This switch is mainly for debugging the compiler and will likely be removed
8603in a future version.
8604
8605@item -mno-cond-exec
8606@opindex mno-cond-exec
8607
8608Disable the use of conditional execution.
8609
8610This switch is mainly for debugging the compiler and will likely be removed
8611in a future version.
8612
8613@item -mvliw-branch
8614@opindex mvliw-branch
8615
8616Run a pass to pack branches into VLIW instructions (default).
8617
8618This switch is mainly for debugging the compiler and will likely be removed
8619in a future version.
8620
8621@item -mno-vliw-branch
8622@opindex mno-vliw-branch
8623
8624Do not run a pass to pack branches into VLIW instructions.
8625
8626This switch is mainly for debugging the compiler and will likely be removed
8627in a future version.
8628
8629@item -mmulti-cond-exec
8630@opindex mmulti-cond-exec
8631
8632Enable optimization of @code{&&} and @code{||} in conditional execution
8633(default).
8634
8635This switch is mainly for debugging the compiler and will likely be removed
8636in a future version.
8637
8638@item -mno-multi-cond-exec
8639@opindex mno-multi-cond-exec
8640
8641Disable optimization of @code{&&} and @code{||} in conditional execution.
8642
8643This switch is mainly for debugging the compiler and will likely be removed
8644in a future version.
8645
8646@item -mnested-cond-exec
8647@opindex mnested-cond-exec
8648
8649Enable nested conditional execution optimizations (default).
8650
8651This switch is mainly for debugging the compiler and will likely be removed
8652in a future version.
8653
8654@item -mno-nested-cond-exec
8655@opindex mno-nested-cond-exec
8656
8657Disable nested conditional execution optimizations.
8658
8659This switch is mainly for debugging the compiler and will likely be removed
8660in a future version.
8661
8662@item -moptimize-membar
8663@opindex moptimize-membar
8664
8665This switch removes redundant @code{membar} instructions from the
8666compiler generated code. It is enabled by default.
8667
8668@item -mno-optimize-membar
8669@opindex mno-optimize-membar
8670
8671This switch disables the automatic removal of redundant @code{membar}
8672instructions from the generated code.
8673
8674@item -mtomcat-stats
8675@opindex mtomcat-stats
8676
8677Cause gas to print out tomcat statistics.
8678
8679@item -mcpu=@var{cpu}
8680@opindex mcpu
8681
8682Select the processor type for which to generate code. Possible values are
8683@samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
8684@samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
8685
8686@end table
8687
8688@node GNU/Linux Options
8689@subsection GNU/Linux Options
8690
8691These @samp{-m} options are defined for GNU/Linux targets:
8692
8693@table @gcctabopt
8694@item -mglibc
8695@opindex mglibc
8696Use the GNU C library instead of uClibc. This is the default except
8697on @samp{*-*-linux-*uclibc*} targets.
8698
8699@item -muclibc
8700@opindex muclibc
8701Use uClibc instead of the GNU C library. This is the default on
8702@samp{*-*-linux-*uclibc*} targets.
8703@end table
8704
8705@node H8/300 Options
8706@subsection H8/300 Options
8707
8708These @samp{-m} options are defined for the H8/300 implementations:
8709
8710@table @gcctabopt
8711@item -mrelax
8712@opindex mrelax
8713Shorten some address references at link time, when possible; uses the
8714linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
8715ld, Using ld}, for a fuller description.
8716
8717@item -mh
8718@opindex mh
8719Generate code for the H8/300H@.
8720
8721@item -ms
8722@opindex ms
8723Generate code for the H8S@.
8724
8725@item -mn
8726@opindex mn
8727Generate code for the H8S and H8/300H in the normal mode. This switch
8728must be used either with @option{-mh} or @option{-ms}.
8729
8730@item -ms2600
8731@opindex ms2600
8732Generate code for the H8S/2600. This switch must be used with @option{-ms}.
8733
8734@item -mint32
8735@opindex mint32
8736Make @code{int} data 32 bits by default.
8737
8738@item -malign-300
8739@opindex malign-300
8740On the H8/300H and H8S, use the same alignment rules as for the H8/300.
8741The default for the H8/300H and H8S is to align longs and floats on 4
8742byte boundaries.
8743@option{-malign-300} causes them to be aligned on 2 byte boundaries.
8744This option has no effect on the H8/300.
8745@end table
8746
8747@node HPPA Options
8748@subsection HPPA Options
8749@cindex HPPA Options
8750
8751These @samp{-m} options are defined for the HPPA family of computers:
8752
8753@table @gcctabopt
8754@item -march=@var{architecture-type}
8755@opindex march
8756Generate code for the specified architecture. The choices for
8757@var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
87581.1, and @samp{2.0} for PA 2.0 processors. Refer to
8759@file{/usr/lib/sched.models} on an HP-UX system to determine the proper
8760architecture option for your machine. Code compiled for lower numbered
8761architectures will run on higher numbered architectures, but not the
8762other way around.
8763
8764@item -mpa-risc-1-0
8765@itemx -mpa-risc-1-1
8766@itemx -mpa-risc-2-0
8767@opindex mpa-risc-1-0
8768@opindex mpa-risc-1-1
8769@opindex mpa-risc-2-0
8770Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
8771
8772@item -mbig-switch
8773@opindex mbig-switch
8774Generate code suitable for big switch tables. Use this option only if
8775the assembler/linker complain about out of range branches within a switch
8776table.
8777
8778@item -mjump-in-delay
8779@opindex mjump-in-delay
8780Fill delay slots of function calls with unconditional jump instructions
8781by modifying the return pointer for the function call to be the target
8782of the conditional jump.
8783
8784@item -mdisable-fpregs
8785@opindex mdisable-fpregs
8786Prevent floating point registers from being used in any manner. This is
8787necessary for compiling kernels which perform lazy context switching of
8788floating point registers. If you use this option and attempt to perform
8789floating point operations, the compiler will abort.
8790
8791@item -mdisable-indexing
8792@opindex mdisable-indexing
8793Prevent the compiler from using indexing address modes. This avoids some
8794rather obscure problems when compiling MIG generated code under MACH@.
8795
8796@item -mno-space-regs
8797@opindex mno-space-regs
8798Generate code that assumes the target has no space registers. This allows
8799GCC to generate faster indirect calls and use unscaled index address modes.
8800
8801Such code is suitable for level 0 PA systems and kernels.
8802
8803@item -mfast-indirect-calls
8804@opindex mfast-indirect-calls
8805Generate code that assumes calls never cross space boundaries. This
8806allows GCC to emit code which performs faster indirect calls.
8807
8808This option will not work in the presence of shared libraries or nested
8809functions.
8810
8811@item -mfixed-range=@var{register-range}
8812@opindex mfixed-range
8813Generate code treating the given register range as fixed registers.
8814A fixed register is one that the register allocator can not use. This is
8815useful when compiling kernel code. A register range is specified as
8816two registers separated by a dash. Multiple register ranges can be
8817specified separated by a comma.
8818
8819@item -mlong-load-store
8820@opindex mlong-load-store
8821Generate 3-instruction load and store sequences as sometimes required by
8822the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
8823the HP compilers.
8824
8825@item -mportable-runtime
8826@opindex mportable-runtime
8827Use the portable calling conventions proposed by HP for ELF systems.
8828
8829@item -mgas
8830@opindex mgas
8831Enable the use of assembler directives only GAS understands.
8832
8833@item -mschedule=@var{cpu-type}
8834@opindex mschedule
8835Schedule code according to the constraints for the machine type
8836@var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
8837@samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer
8838to @file{/usr/lib/sched.models} on an HP-UX system to determine the
8839proper scheduling option for your machine. The default scheduling is
8840@samp{8000}.
8841
8842@item -mlinker-opt
8843@opindex mlinker-opt
8844Enable the optimization pass in the HP-UX linker. Note this makes symbolic
8845debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9
8846linkers in which they give bogus error messages when linking some programs.
8847
8848@item -msoft-float
8849@opindex msoft-float
8850Generate output containing library calls for floating point.
8851@strong{Warning:} the requisite libraries are not available for all HPPA
8852targets. Normally the facilities of the machine's usual C compiler are
8853used, but this cannot be done directly in cross-compilation. You must make
8854your own arrangements to provide suitable library functions for
8855cross-compilation. The embedded target @samp{hppa1.1-*-pro}
8856does provide software floating point support.
8857
8858@option{-msoft-float} changes the calling convention in the output file;
8859therefore, it is only useful if you compile @emph{all} of a program with
8860this option. In particular, you need to compile @file{libgcc.a}, the
8861library that comes with GCC, with @option{-msoft-float} in order for
8862this to work.
8863
8864@item -msio
8865@opindex msio
8866Generate the predefine, @code{_SIO}, for server IO@. The default is
8867@option{-mwsio}. This generates the predefines, @code{__hp9000s700},
8868@code{__hp9000s700__} and @code{_WSIO}, for workstation IO@. These
8869options are available under HP-UX and HI-UX@.
8870
8871@item -mgnu-ld
8872@opindex gnu-ld
8873Use GNU ld specific options. This passes @option{-shared} to ld when
8874building a shared library. It is the default when GCC is configured,
8875explicitly or implicitly, with the GNU linker. This option does not
8876have any affect on which ld is called, it only changes what parameters
8877are passed to that ld. The ld that is called is determined by the
8878@option{--with-ld} configure option, GCC's program search path, and
8879finally by the user's @env{PATH}. The linker used by GCC can be printed
8880using @samp{which `gcc -print-prog-name=ld`}. This option is only available
8881on the 64 bit HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
8882
8883@item -mhp-ld
8884@opindex hp-ld
8885Use HP ld specific options. This passes @option{-b} to ld when building
8886a shared library and passes @option{+Accept TypeMismatch} to ld on all
8887links. It is the default when GCC is configured, explicitly or
8888implicitly, with the HP linker. This option does not have any affect on
8889which ld is called, it only changes what parameters are passed to that
8890ld. The ld that is called is determined by the @option{--with-ld}
8891configure option, GCC's program search path, and finally by the user's
8892@env{PATH}. The linker used by GCC can be printed using @samp{which
8893`gcc -print-prog-name=ld`}. This option is only available on the 64 bit
8894HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
8895
8896@item -mlong-calls
8897@opindex mno-long-calls
8898Generate code that uses long call sequences. This ensures that a call
8899is always able to reach linker generated stubs. The default is to generate
8900long calls only when the distance from the call site to the beginning
8901of the function or translation unit, as the case may be, exceeds a
8902predefined limit set by the branch type being used. The limits for
8903normal calls are 7,600,000 and 240,000 bytes, respectively for the
8904PA 2.0 and PA 1.X architectures. Sibcalls are always limited at
8905240,000 bytes.
8906
8907Distances are measured from the beginning of functions when using the
8908@option{-ffunction-sections} option, or when using the @option{-mgas}
8909and @option{-mno-portable-runtime} options together under HP-UX with
8910the SOM linker.
8911
8912It is normally not desirable to use this option as it will degrade
8913performance. However, it may be useful in large applications,
8914particularly when partial linking is used to build the application.
8915
8916The types of long calls used depends on the capabilities of the
8917assembler and linker, and the type of code being generated. The
8918impact on systems that support long absolute calls, and long pic
8919symbol-difference or pc-relative calls should be relatively small.
8920However, an indirect call is used on 32-bit ELF systems in pic code
8921and it is quite long.
8922
8923@item -munix=@var{unix-std}
8924@opindex march
8925Generate compiler predefines and select a startfile for the specified
8926UNIX standard. The choices for @var{unix-std} are @samp{93}, @samp{95}
8927and @samp{98}. @samp{93} is supported on all HP-UX versions. @samp{95}
8928is available on HP-UX 10.10 and later. @samp{98} is available on HP-UX
892911.11 and later. The default values are @samp{93} for HP-UX 10.00,
8930@samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
8931and later.
8932
8933@option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
8934@option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
8935and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
8936@option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
8937@code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
8938@code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
8939
8940It is @emph{important} to note that this option changes the interfaces
8941for various library routines. It also affects the operational behavior
8942of the C library. Thus, @emph{extreme} care is needed in using this
8943option.
8944
8945Library code that is intended to operate with more than one UNIX
8946standard must test, set and restore the variable @var{__xpg4_extended_mask}
8947as appropriate. Most GNU software doesn't provide this capability.
8948
8949@item -nolibdld
8950@opindex nolibdld
8951Suppress the generation of link options to search libdld.sl when the
8952@option{-static} option is specified on HP-UX 10 and later.
8953
8954@item -static
8955@opindex static
8956The HP-UX implementation of setlocale in libc has a dependency on
8957libdld.sl. There isn't an archive version of libdld.sl. Thus,
8958when the @option{-static} option is specified, special link options
8959are needed to resolve this dependency.
8960
8961On HP-UX 10 and later, the GCC driver adds the necessary options to
8962link with libdld.sl when the @option{-static} option is specified.
8963This causes the resulting binary to be dynamic. On the 64-bit port,
8964the linkers generate dynamic binaries by default in any case. The
8965@option{-nolibdld} option can be used to prevent the GCC driver from
8966adding these link options.
8967
8968@item -threads
8969@opindex threads
8970Add support for multithreading with the @dfn{dce thread} library
8971under HP-UX@. This option sets flags for both the preprocessor and
8972linker.
8973@end table
8974
8975@node i386 and x86-64 Options
8976@subsection Intel 386 and AMD x86-64 Options
8977@cindex i386 Options
8978@cindex x86-64 Options
8979@cindex Intel 386 Options
8980@cindex AMD x86-64 Options
8981
8982These @samp{-m} options are defined for the i386 and x86-64 family of
8983computers:
8984
8985@table @gcctabopt
8986@item -mtune=@var{cpu-type}
8987@opindex mtune
8988Tune to @var{cpu-type} everything applicable about the generated code, except
8989for the ABI and the set of available instructions. The choices for
8990@var{cpu-type} are:
8991@table @emph
8992@item generic
8993Produce code optimized for the most common IA32/AMD64/EM64T processors.
8994If you know the CPU on which your code will run, then you should use
8995the corresponding @option{-mtune} option instead of
8996@option{-mtune=generic}. But, if you do not know exactly what CPU users
8997of your application will have, then you should use this option.
8998
8999As new processors are deployed in the marketplace, the behavior of this
9000option will change. Therefore, if you upgrade to a newer version of
9001GCC, the code generated option will change to reflect the processors
9002that were most common when that version of GCC was released.
9003
9004There is no @option{-march=generic} option because @option{-march}
9005indicates the instruction set the compiler can use, and there is no
9006generic instruction set applicable to all processors. In contrast,
9007@option{-mtune} indicates the processor (or, in this case, collection of
9008processors) for which the code is optimized.
9009@item native
9010This selects the CPU to tune for at compilation time by determining
9011the processor type of the compiling machine. Using @option{-mtune=native}
9012will produce code optimized for the local machine under the constraints
9013of the selected instruction set. Using @option{-march=native} will
9014enable all instruction subsets supported by the local machine (hence
9015the result might not run on different machines).
9016@item i386
9017Original Intel's i386 CPU@.
9018@item i486
9019Intel's i486 CPU@. (No scheduling is implemented for this chip.)
9020@item i586, pentium
9021Intel Pentium CPU with no MMX support.
9022@item pentium-mmx
9023Intel PentiumMMX CPU based on Pentium core with MMX instruction set support.
9024@item pentiumpro
9025Intel PentiumPro CPU@.
9026@item i686
9027Same as @code{generic}, but when used as @code{march} option, PentiumPro
9028instruction set will be used, so the code will run on all i686 family chips.
9029@item pentium2
9030Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support.
9031@item pentium3, pentium3m
9032Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set
9033support.
9034@item pentium-m
9035Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set
9036support. Used by Centrino notebooks.
9037@item pentium4, pentium4m
9038Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support.
9039@item prescott
9040Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction
9041set support.
9042@item nocona
9043Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE,
9044SSE2 and SSE3 instruction set support.
9045@item core2
9046Intel Core2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3
9047instruction set support.
9048@item k6
9049AMD K6 CPU with MMX instruction set support.
9050@item k6-2, k6-3
9051Improved versions of AMD K6 CPU with MMX and 3dNOW! instruction set support.
9052@item athlon, athlon-tbird
9053AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and SSE prefetch instructions
9054support.
9055@item athlon-4, athlon-xp, athlon-mp
9056Improved AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and full SSE
9057instruction set support.
9058@item k8, opteron, athlon64, athlon-fx
9059AMD K8 core based CPUs with x86-64 instruction set support. (This supersets
9060MMX, SSE, SSE2, 3dNOW!, enhanced 3dNOW! and 64-bit instruction set extensions.)
9061@item k8-sse3, opteron-sse3, athlon64-sse3
9062Improved versions of k8, opteron and athlon64 with SSE3 instruction set support.
9063@item amdfam10, barcelona
9064AMD Family 10h core based CPUs with x86-64 instruction set support. (This
9065supersets MMX, SSE, SSE2, SSE3, SSE4A, 3dNOW!, enhanced 3dNOW!, ABM and 64-bit
9066instruction set extensions.)
9067@item winchip-c6
9068IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction
9069set support.
9070@item winchip2
9071IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3dNOW!
9072instruction set support.
9073@item c3
9074Via C3 CPU with MMX and 3dNOW! instruction set support. (No scheduling is
9075implemented for this chip.)
9076@item c3-2
9077Via C3-2 CPU with MMX and SSE instruction set support. (No scheduling is
9078implemented for this chip.)
9079@item geode
9080Embedded AMD CPU with MMX and 3dNOW! instruction set support.
9081@end table
9082
9083While picking a specific @var{cpu-type} will schedule things appropriately
9084for that particular chip, the compiler will not generate any code that
9085does not run on the i386 without the @option{-march=@var{cpu-type}} option
9086being used.
9087
9088@item -march=@var{cpu-type}
9089@opindex march
9090Generate instructions for the machine type @var{cpu-type}. The choices
9091for @var{cpu-type} are the same as for @option{-mtune}. Moreover,
9092specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}.
9093
9094@item -mcpu=@var{cpu-type}
9095@opindex mcpu
9096A deprecated synonym for @option{-mtune}.
9097
9098@item -m386
9099@itemx -m486
9100@itemx -mpentium
9101@itemx -mpentiumpro
9102@opindex m386
9103@opindex m486
9104@opindex mpentium
9105@opindex mpentiumpro
9106These options are synonyms for @option{-mtune=i386}, @option{-mtune=i486},
9107@option{-mtune=pentium}, and @option{-mtune=pentiumpro} respectively.
9108These synonyms are deprecated.
9109
9110@item -mfpmath=@var{unit}
9111@opindex march
9112Generate floating point arithmetics for selected unit @var{unit}. The choices
9113for @var{unit} are:
9114
9115@table @samp
9116@item 387
9117Use the standard 387 floating point coprocessor present majority of chips and
9118emulated otherwise. Code compiled with this option will run almost everywhere.
9119The temporary results are computed in 80bit precision instead of precision
9120specified by the type resulting in slightly different results compared to most
9121of other chips. See @option{-ffloat-store} for more detailed description.
9122
9123This is the default choice for i386 compiler.
9124
9125@item sse
9126Use scalar floating point instructions present in the SSE instruction set.
9127This instruction set is supported by Pentium3 and newer chips, in the AMD line
9128by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE
9129instruction set supports only single precision arithmetics, thus the double and
9130extended precision arithmetics is still done using 387. Later version, present
9131only in Pentium4 and the future AMD x86-64 chips supports double precision
9132arithmetics too.
9133
9134For the i386 compiler, you need to use @option{-march=@var{cpu-type}}, @option{-msse}
9135or @option{-msse2} switches to enable SSE extensions and make this option
9136effective. For the x86-64 compiler, these extensions are enabled by default.
9137
9138The resulting code should be considerably faster in the majority of cases and avoid
9139the numerical instability problems of 387 code, but may break some existing
9140code that expects temporaries to be 80bit.
9141
9142This is the default choice for the x86-64 compiler.
9143
9144@item sse,387
9145Attempt to utilize both instruction sets at once. This effectively double the
9146amount of available registers and on chips with separate execution units for
9147387 and SSE the execution resources too. Use this option with care, as it is
9148still experimental, because the GCC register allocator does not model separate
9149functional units well resulting in instable performance.
9150@end table
9151
9152@item -masm=@var{dialect}
9153@opindex masm=@var{dialect}
9154Output asm instructions using selected @var{dialect}. Supported
9155choices are @samp{intel} or @samp{att} (the default one). Darwin does
9156not support @samp{intel}.
9157
9158@item -mieee-fp
9159@itemx -mno-ieee-fp
9160@opindex mieee-fp
9161@opindex mno-ieee-fp
9162Control whether or not the compiler uses IEEE floating point
9163comparisons. These handle correctly the case where the result of a
9164comparison is unordered.
9165
9166@item -msoft-float
9167@opindex msoft-float
9168Generate output containing library calls for floating point.
9169@strong{Warning:} the requisite libraries are not part of GCC@.
9170Normally the facilities of the machine's usual C compiler are used, but
9171this can't be done directly in cross-compilation. You must make your
9172own arrangements to provide suitable library functions for
9173cross-compilation.
9174
9175On machines where a function returns floating point results in the 80387
9176register stack, some floating point opcodes may be emitted even if
9177@option{-msoft-float} is used.
9178
9179@item -mno-fp-ret-in-387
9180@opindex mno-fp-ret-in-387
9181Do not use the FPU registers for return values of functions.
9182
9183The usual calling convention has functions return values of types
9184@code{float} and @code{double} in an FPU register, even if there
9185is no FPU@. The idea is that the operating system should emulate
9186an FPU@.
9187
9188The option @option{-mno-fp-ret-in-387} causes such values to be returned
9189in ordinary CPU registers instead.
9190
9191@item -mno-fancy-math-387
9192@opindex mno-fancy-math-387
9193Some 387 emulators do not support the @code{sin}, @code{cos} and
9194@code{sqrt} instructions for the 387. Specify this option to avoid
9195generating those instructions. This option is the default on
9196OpenBSD and NetBSD@. This option is overridden when @option{-march}
9197indicates that the target cpu will always have an FPU and so the
9198instruction will not need emulation. As of revision 2.6.1, these
9199instructions are not generated unless you also use the
9200@option{-funsafe-math-optimizations} switch.
9201
9202@item -malign-double
9203@itemx -mno-align-double
9204@opindex malign-double
9205@opindex mno-align-double
9206Control whether GCC aligns @code{double}, @code{long double}, and
9207@code{long long} variables on a two word boundary or a one word
9208boundary. Aligning @code{double} variables on a two word boundary will
9209produce code that runs somewhat faster on a @samp{Pentium} at the
9210expense of more memory.
9211
9212On x86-64, @option{-malign-double} is enabled by default.
9213
9214@strong{Warning:} if you use the @option{-malign-double} switch,
9215structures containing the above types will be aligned differently than
9216the published application binary interface specifications for the 386
9217and will not be binary compatible with structures in code compiled
9218without that switch.
9219
9220@item -m96bit-long-double
9221@itemx -m128bit-long-double
9222@opindex m96bit-long-double
9223@opindex m128bit-long-double
9224These switches control the size of @code{long double} type. The i386
9225application binary interface specifies the size to be 96 bits,
9226so @option{-m96bit-long-double} is the default in 32 bit mode.
9227
9228Modern architectures (Pentium and newer) would prefer @code{long double}
9229to be aligned to an 8 or 16 byte boundary. In arrays or structures
9230conforming to the ABI, this would not be possible. So specifying a
9231@option{-m128bit-long-double} will align @code{long double}
9232to a 16 byte boundary by padding the @code{long double} with an additional
923332 bit zero.
9234
9235In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
9236its ABI specifies that @code{long double} is to be aligned on 16 byte boundary.
9237
9238Notice that neither of these options enable any extra precision over the x87
9239standard of 80 bits for a @code{long double}.
9240
9241@strong{Warning:} if you override the default value for your target ABI, the
9242structures and arrays containing @code{long double} variables will change
9243their size as well as function calling convention for function taking
9244@code{long double} will be modified. Hence they will not be binary
9245compatible with arrays or structures in code compiled without that switch.
9246
9247@item -mmlarge-data-threshold=@var{number}
9248@opindex mlarge-data-threshold=@var{number}
9249When @option{-mcmodel=medium} is specified, the data greater than
9250@var{threshold} are placed in large data section. This value must be the
9251same across all object linked into the binary and defaults to 65535.
9252
9253@item -msvr3-shlib
9254@itemx -mno-svr3-shlib
9255@opindex msvr3-shlib
9256@opindex mno-svr3-shlib
9257Control whether GCC places uninitialized local variables into the
9258@code{bss} or @code{data} segments. @option{-msvr3-shlib} places them
9259into @code{bss}. These options are meaningful only on System V Release 3.
9260
9261@item -mrtd
9262@opindex mrtd
9263Use a different function-calling convention, in which functions that
9264take a fixed number of arguments return with the @code{ret} @var{num}
9265instruction, which pops their arguments while returning. This saves one
9266instruction in the caller since there is no need to pop the arguments
9267there.
9268
9269You can specify that an individual function is called with this calling
9270sequence with the function attribute @samp{stdcall}. You can also
9271override the @option{-mrtd} option by using the function attribute
9272@samp{cdecl}. @xref{Function Attributes}.
9273
9274@strong{Warning:} this calling convention is incompatible with the one
9275normally used on Unix, so you cannot use it if you need to call
9276libraries compiled with the Unix compiler.
9277
9278Also, you must provide function prototypes for all functions that
9279take variable numbers of arguments (including @code{printf});
9280otherwise incorrect code will be generated for calls to those
9281functions.
9282
9283In addition, seriously incorrect code will result if you call a
9284function with too many arguments. (Normally, extra arguments are
9285harmlessly ignored.)
9286
9287@item -mregparm=@var{num}
9288@opindex mregparm
9289Control how many registers are used to pass integer arguments. By
9290default, no registers are used to pass arguments, and at most 3
9291registers can be used. You can control this behavior for a specific
9292function by using the function attribute @samp{regparm}.
9293@xref{Function Attributes}.
9294
9295@strong{Warning:} if you use this switch, and
9296@var{num} is nonzero, then you must build all modules with the same
9297value, including any libraries. This includes the system libraries and
9298startup modules.
9299
9300@item -msseregparm
9301@opindex msseregparm
9302Use SSE register passing conventions for float and double arguments
9303and return values. You can control this behavior for a specific
9304function by using the function attribute @samp{sseregparm}.
9305@xref{Function Attributes}.
9306
9307@strong{Warning:} if you use this switch then you must build all
9308modules with the same value, including any libraries. This includes
9309the system libraries and startup modules.
9310
9311@item -mstackrealign
9312@opindex mstackrealign
9313Realign the stack at entry. On the Intel x86, the
9314@option{-mstackrealign} option will generate an alternate prologue and
9315epilogue that realigns the runtime stack. This supports mixing legacy
9316codes that keep a 4-byte aligned stack with modern codes that keep a
931716-byte stack for SSE compatibility. The alternate prologue and
9318epilogue are slower and bigger than the regular ones, and the
9319alternate prologue requires an extra scratch register; this lowers the
9320number of registers available if used in conjunction with the
9321@code{regparm} attribute. The @option{-mstackrealign} option is
9322incompatible with the nested function prologue; this is considered a
9323hard error. See also the attribute @code{force_align_arg_pointer},
9324applicable to individual functions.
9325
9326@item -mpreferred-stack-boundary=@var{num}
9327@opindex mpreferred-stack-boundary
9328Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
9329byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
9330the default is 4 (16 bytes or 128 bits).
9331
9332On Pentium and PentiumPro, @code{double} and @code{long double} values
9333should be aligned to an 8 byte boundary (see @option{-malign-double}) or
9334suffer significant run time performance penalties. On Pentium III, the
9335Streaming SIMD Extension (SSE) data type @code{__m128} may not work
9336properly if it is not 16 byte aligned.
9337
9338To ensure proper alignment of this values on the stack, the stack boundary
9339must be as aligned as that required by any value stored on the stack.
9340Further, every function must be generated such that it keeps the stack
9341aligned. Thus calling a function compiled with a higher preferred
9342stack boundary from a function compiled with a lower preferred stack
9343boundary will most likely misalign the stack. It is recommended that
9344libraries that use callbacks always use the default setting.
9345
9346This extra alignment does consume extra stack space, and generally
9347increases code size. Code that is sensitive to stack space usage, such
9348as embedded systems and operating system kernels, may want to reduce the
9349preferred alignment to @option{-mpreferred-stack-boundary=2}.
9350
9351@item -mmmx
9352@itemx -mno-mmx
9353@item -msse
9354@itemx -mno-sse
9355@item -msse2
9356@itemx -mno-sse2
9357@item -msse3
9358@itemx -mno-sse3
9359@item -mssse3
9360@itemx -mno-ssse3
9361@item -msse4a
9362@item -mno-sse4a
9363@item -m3dnow
9364@itemx -mno-3dnow
9365@item -mpopcnt
9366@itemx -mno-popcnt
9367@item -mabm
9368@itemx -mno-abm
9369@item -maes
9370@itemx -mno-aes
9371@opindex mmmx
9372@opindex mno-mmx
9373@opindex msse
9374@opindex mno-sse
9375@opindex m3dnow
9376@opindex mno-3dnow
9377These switches enable or disable the use of instructions in the MMX,
9378SSE, SSE2, SSE3, SSSE3, SSE4A, ABM, AES or 3DNow! extended
9379instruction sets. These extensions are also available as built-in
9380functions: see @ref{X86 Built-in Functions}, for details of the functions
9381enabled and disabled by these switches.
9382
9383To have SSE/SSE2 instructions generated automatically from floating-point
9384code (as opposed to 387 instructions), see @option{-mfpmath=sse}.
9385
9386These options will enable GCC to use these extended instructions in
9387generated code, even without @option{-mfpmath=sse}. Applications which
9388perform runtime CPU detection must compile separate files for each
9389supported architecture, using the appropriate flags. In particular,
9390the file containing the CPU detection code should be compiled without
9391these options.
9392
9393@item -mpush-args
9394@itemx -mno-push-args
9395@opindex mpush-args
9396@opindex mno-push-args
9397Use PUSH operations to store outgoing parameters. This method is shorter
9398and usually equally fast as method using SUB/MOV operations and is enabled
9399by default. In some cases disabling it may improve performance because of
9400improved scheduling and reduced dependencies.
9401
9402@item -maccumulate-outgoing-args
9403@opindex maccumulate-outgoing-args
9404If enabled, the maximum amount of space required for outgoing arguments will be
9405computed in the function prologue. This is faster on most modern CPUs
9406because of reduced dependencies, improved scheduling and reduced stack usage
9407when preferred stack boundary is not equal to 2. The drawback is a notable
9408increase in code size. This switch implies @option{-mno-push-args}.
9409
9410@item -mthreads
9411@opindex mthreads
9412Support thread-safe exception handling on @samp{Mingw32}. Code that relies
9413on thread-safe exception handling must compile and link all code with the
9414@option{-mthreads} option. When compiling, @option{-mthreads} defines
9415@option{-D_MT}; when linking, it links in a special thread helper library
9416@option{-lmingwthrd} which cleans up per thread exception handling data.
9417
9418@item -mno-align-stringops
9419@opindex mno-align-stringops
9420Do not align destination of inlined string operations. This switch reduces
9421code size and improves performance in case the destination is already aligned,
9422but GCC doesn't know about it.
9423
9424@item -minline-all-stringops
9425@opindex minline-all-stringops
9426By default GCC inlines string operations only when destination is known to be
9427aligned at least to 4 byte boundary. This enables more inlining, increase code
9428size, but may improve performance of code that depends on fast memcpy, strlen
9429and memset for short lengths.
9430
9431@item -momit-leaf-frame-pointer
9432@opindex momit-leaf-frame-pointer
9433Don't keep the frame pointer in a register for leaf functions. This
9434avoids the instructions to save, set up and restore frame pointers and
9435makes an extra register available in leaf functions. The option
9436@option{-fomit-frame-pointer} removes the frame pointer for all functions
9437which might make debugging harder.
9438
9439@item -mtls-direct-seg-refs
9440@itemx -mno-tls-direct-seg-refs
9441@opindex mtls-direct-seg-refs
9442Controls whether TLS variables may be accessed with offsets from the
9443TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
9444or whether the thread base pointer must be added. Whether or not this
9445is legal depends on the operating system, and whether it maps the
9446segment to cover the entire TLS area.
9447
9448For systems that use GNU libc, the default is on.
9449@end table
9450
9451These @samp{-m} switches are supported in addition to the above
9452on AMD x86-64 processors in 64-bit environments.
9453
9454@table @gcctabopt
9455@item -m32
9456@itemx -m64
9457@opindex m32
9458@opindex m64
9459Generate code for a 32-bit or 64-bit environment.
9460The 32-bit environment sets int, long and pointer to 32 bits and
9461generates code that runs on any i386 system.
9462The 64-bit environment sets int to 32 bits and long and pointer
9463to 64 bits and generates code for AMD's x86-64 architecture. For
9464darwin only the -m64 option turns off the @option{-fno-pic} and
9465@option{-mdynamic-no-pic} options.
9466
9467@item -mno-red-zone
9468@opindex no-red-zone
9469Do not use a so called red zone for x86-64 code. The red zone is mandated
9470by the x86-64 ABI, it is a 128-byte area beyond the location of the
9471stack pointer that will not be modified by signal or interrupt handlers
9472and therefore can be used for temporary data without adjusting the stack
9473pointer. The flag @option{-mno-red-zone} disables this red zone.
9474
9475@item -mcmodel=small
9476@opindex mcmodel=small
9477Generate code for the small code model: the program and its symbols must
9478be linked in the lower 2 GB of the address space. Pointers are 64 bits.
9479Programs can be statically or dynamically linked. This is the default
9480code model.
9481
9482@item -mcmodel=kernel
9483@opindex mcmodel=kernel
9484Generate code for the kernel code model. The kernel runs in the
9485negative 2 GB of the address space.
9486This model has to be used for Linux kernel code.
9487
9488@item -mcmodel=medium
9489@opindex mcmodel=medium
9490Generate code for the medium model: The program is linked in the lower 2
9491GB of the address space but symbols can be located anywhere in the
9492address space. Programs can be statically or dynamically linked, but
9493building of shared libraries are not supported with the medium model.
9494
9495@item -mcmodel=large
9496@opindex mcmodel=large
9497Generate code for the large model: This model makes no assumptions
9498about addresses and sizes of sections. Currently GCC does not implement
9499this model.
9500@end table
9501
9502@node IA-64 Options
9503@subsection IA-64 Options
9504@cindex IA-64 Options
9505
9506These are the @samp{-m} options defined for the Intel IA-64 architecture.
9507
9508@table @gcctabopt
9509@item -mbig-endian
9510@opindex mbig-endian
9511Generate code for a big endian target. This is the default for HP-UX@.
9512
9513@item -mlittle-endian
9514@opindex mlittle-endian
9515Generate code for a little endian target. This is the default for AIX5
9516and GNU/Linux.
9517
9518@item -mgnu-as
9519@itemx -mno-gnu-as
9520@opindex mgnu-as
9521@opindex mno-gnu-as
9522Generate (or don't) code for the GNU assembler. This is the default.
9523@c Also, this is the default if the configure option @option{--with-gnu-as}
9524@c is used.
9525
9526@item -mgnu-ld
9527@itemx -mno-gnu-ld
9528@opindex mgnu-ld
9529@opindex mno-gnu-ld
9530Generate (or don't) code for the GNU linker. This is the default.
9531@c Also, this is the default if the configure option @option{--with-gnu-ld}
9532@c is used.
9533
9534@item -mno-pic
9535@opindex mno-pic
9536Generate code that does not use a global pointer register. The result
9537is not position independent code, and violates the IA-64 ABI@.
9538
9539@item -mvolatile-asm-stop
9540@itemx -mno-volatile-asm-stop
9541@opindex mvolatile-asm-stop
9542@opindex mno-volatile-asm-stop
9543Generate (or don't) a stop bit immediately before and after volatile asm
9544statements.
9545
9546@item -mregister-names
9547@itemx -mno-register-names
9548@opindex mregister-names
9549@opindex mno-register-names
9550Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
9551the stacked registers. This may make assembler output more readable.
9552
9553@item -mno-sdata
9554@itemx -msdata
9555@opindex mno-sdata
9556@opindex msdata
9557Disable (or enable) optimizations that use the small data section. This may
9558be useful for working around optimizer bugs.
9559
9560@item -mconstant-gp
9561@opindex mconstant-gp
9562Generate code that uses a single constant global pointer value. This is
9563useful when compiling kernel code.
9564
9565@item -mauto-pic
9566@opindex mauto-pic
9567Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
9568This is useful when compiling firmware code.
9569
9570@item -minline-float-divide-min-latency
9571@opindex minline-float-divide-min-latency
9572Generate code for inline divides of floating point values
9573using the minimum latency algorithm.
9574
9575@item -minline-float-divide-max-throughput
9576@opindex minline-float-divide-max-throughput
9577Generate code for inline divides of floating point values
9578using the maximum throughput algorithm.
9579
9580@item -minline-int-divide-min-latency
9581@opindex minline-int-divide-min-latency
9582Generate code for inline divides of integer values
9583using the minimum latency algorithm.
9584
9585@item -minline-int-divide-max-throughput
9586@opindex minline-int-divide-max-throughput
9587Generate code for inline divides of integer values
9588using the maximum throughput algorithm.
9589
9590@item -minline-sqrt-min-latency
9591@opindex minline-sqrt-min-latency
9592Generate code for inline square roots
9593using the minimum latency algorithm.
9594
9595@item -minline-sqrt-max-throughput
9596@opindex minline-sqrt-max-throughput
9597Generate code for inline square roots
9598using the maximum throughput algorithm.
9599
9600@item -mno-dwarf2-asm
9601@itemx -mdwarf2-asm
9602@opindex mno-dwarf2-asm
9603@opindex mdwarf2-asm
9604Don't (or do) generate assembler code for the DWARF2 line number debugging
9605info. This may be useful when not using the GNU assembler.
9606
9607@item -mearly-stop-bits
9608@itemx -mno-early-stop-bits
9609@opindex mearly-stop-bits
9610@opindex mno-early-stop-bits
9611Allow stop bits to be placed earlier than immediately preceding the
9612instruction that triggered the stop bit. This can improve instruction
9613scheduling, but does not always do so.
9614
9615@item -mfixed-range=@var{register-range}
9616@opindex mfixed-range
9617Generate code treating the given register range as fixed registers.
9618A fixed register is one that the register allocator can not use. This is
9619useful when compiling kernel code. A register range is specified as
9620two registers separated by a dash. Multiple register ranges can be
9621specified separated by a comma.
9622
9623@item -mtls-size=@var{tls-size}
9624@opindex mtls-size
9625Specify bit size of immediate TLS offsets. Valid values are 14, 22, and
962664.
9627
9628@item -mtune=@var{cpu-type}
9629@opindex mtune
9630Tune the instruction scheduling for a particular CPU, Valid values are
9631itanium, itanium1, merced, itanium2, and mckinley.
9632
9633@item -mt
9634@itemx -pthread
9635@opindex mt
9636@opindex pthread
9637Add support for multithreading using the POSIX threads library. This
9638option sets flags for both the preprocessor and linker. It does
9639not affect the thread safety of object code produced by the compiler or
9640that of libraries supplied with it. These are HP-UX specific flags.
9641
9642@item -milp32
9643@itemx -mlp64
9644@opindex milp32
9645@opindex mlp64
9646Generate code for a 32-bit or 64-bit environment.
9647The 32-bit environment sets int, long and pointer to 32 bits.
9648The 64-bit environment sets int to 32 bits and long and pointer
9649to 64 bits. These are HP-UX specific flags.
9650
9651@item -mno-sched-br-data-spec
9652@itemx -msched-br-data-spec
9653@opindex mno-sched-br-data-spec
9654@opindex msched-br-data-spec
9655(Dis/En)able data speculative scheduling before reload.
9656This will result in generation of the ld.a instructions and
9657the corresponding check instructions (ld.c / chk.a).
9658The default is 'disable'.
9659
9660@item -msched-ar-data-spec
9661@itemx -mno-sched-ar-data-spec
9662@opindex msched-ar-data-spec
9663@opindex mno-sched-ar-data-spec
9664(En/Dis)able data speculative scheduling after reload.
9665This will result in generation of the ld.a instructions and
9666the corresponding check instructions (ld.c / chk.a).
9667The default is 'enable'.
9668
9669@item -mno-sched-control-spec
9670@itemx -msched-control-spec
9671@opindex mno-sched-control-spec
9672@opindex msched-control-spec
9673(Dis/En)able control speculative scheduling. This feature is
9674available only during region scheduling (i.e. before reload).
9675This will result in generation of the ld.s instructions and
9676the corresponding check instructions chk.s .
9677The default is 'disable'.
9678
9679@item -msched-br-in-data-spec
9680@itemx -mno-sched-br-in-data-spec
9681@opindex msched-br-in-data-spec
9682@opindex mno-sched-br-in-data-spec
9683(En/Dis)able speculative scheduling of the instructions that
9684are dependent on the data speculative loads before reload.
9685This is effective only with @option{-msched-br-data-spec} enabled.
9686The default is 'enable'.
9687
9688@item -msched-ar-in-data-spec
9689@itemx -mno-sched-ar-in-data-spec
9690@opindex msched-ar-in-data-spec
9691@opindex mno-sched-ar-in-data-spec
9692(En/Dis)able speculative scheduling of the instructions that
9693are dependent on the data speculative loads after reload.
9694This is effective only with @option{-msched-ar-data-spec} enabled.
9695The default is 'enable'.
9696
9697@item -msched-in-control-spec
9698@itemx -mno-sched-in-control-spec
9699@opindex msched-in-control-spec
9700@opindex mno-sched-in-control-spec
9701(En/Dis)able speculative scheduling of the instructions that
9702are dependent on the control speculative loads.
9703This is effective only with @option{-msched-control-spec} enabled.
9704The default is 'enable'.
9705
9706@item -msched-ldc
9707@itemx -mno-sched-ldc
9708@opindex msched-ldc
9709@opindex mno-sched-ldc
9710(En/Dis)able use of simple data speculation checks ld.c .
9711If disabled, only chk.a instructions will be emitted to check
9712data speculative loads.
9713The default is 'enable'.
9714
9715@item -mno-sched-control-ldc
9716@itemx -msched-control-ldc
9717@opindex mno-sched-control-ldc
9718@opindex msched-control-ldc
9719(Dis/En)able use of ld.c instructions to check control speculative loads.
9720If enabled, in case of control speculative load with no speculatively
9721scheduled dependent instructions this load will be emitted as ld.sa and
9722ld.c will be used to check it.
9723The default is 'disable'.
9724
9725@item -mno-sched-spec-verbose
9726@itemx -msched-spec-verbose
9727@opindex mno-sched-spec-verbose
9728@opindex msched-spec-verbose
9729(Dis/En)able printing of the information about speculative motions.
9730
9731@item -mno-sched-prefer-non-data-spec-insns
9732@itemx -msched-prefer-non-data-spec-insns
9733@opindex mno-sched-prefer-non-data-spec-insns
9734@opindex msched-prefer-non-data-spec-insns
9735If enabled, data speculative instructions will be chosen for schedule
9736only if there are no other choices at the moment. This will make
9737the use of the data speculation much more conservative.
9738The default is 'disable'.
9739
9740@item -mno-sched-prefer-non-control-spec-insns
9741@itemx -msched-prefer-non-control-spec-insns
9742@opindex mno-sched-prefer-non-control-spec-insns
9743@opindex msched-prefer-non-control-spec-insns
9744If enabled, control speculative instructions will be chosen for schedule
9745only if there are no other choices at the moment. This will make
9746the use of the control speculation much more conservative.
9747The default is 'disable'.
9748
9749@item -mno-sched-count-spec-in-critical-path
9750@itemx -msched-count-spec-in-critical-path
9751@opindex mno-sched-count-spec-in-critical-path
9752@opindex msched-count-spec-in-critical-path
9753If enabled, speculative dependencies will be considered during
9754computation of the instructions priorities. This will make the use of the
9755speculation a bit more conservative.
9756The default is 'disable'.
9757
9758@end table
9759
9760@node M32C Options
9761@subsection M32C Options
9762@cindex M32C options
9763
9764@table @gcctabopt
9765@item -mcpu=@var{name}
9766@opindex mcpu=
9767Select the CPU for which code is generated. @var{name} may be one of
9768@samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to
9769/60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for
9770the M32C/80 series.
9771
9772@item -msim
9773@opindex msim
9774Specifies that the program will be run on the simulator. This causes
9775an alternate runtime library to be linked in which supports, for
9776example, file I/O. You must not use this option when generating
9777programs that will run on real hardware; you must provide your own
9778runtime library for whatever I/O functions are needed.
9779
9780@item -memregs=@var{number}
9781@opindex memregs=
9782Specifies the number of memory-based pseudo-registers GCC will use
9783during code generation. These pseudo-registers will be used like real
9784registers, so there is a tradeoff between GCC's ability to fit the
9785code into available registers, and the performance penalty of using
9786memory instead of registers. Note that all modules in a program must
9787be compiled with the same value for this option. Because of that, you
9788must not use this option with the default runtime libraries gcc
9789builds.
9790
9791@end table
9792
9793@node M32R/D Options
9794@subsection M32R/D Options
9795@cindex M32R/D options
9796
9797These @option{-m} options are defined for Renesas M32R/D architectures:
9798
9799@table @gcctabopt
9800@item -m32r2
9801@opindex m32r2
9802Generate code for the M32R/2@.
9803
9804@item -m32rx
9805@opindex m32rx
9806Generate code for the M32R/X@.
9807
9808@item -m32r
9809@opindex m32r
9810Generate code for the M32R@. This is the default.
9811
9812@item -mmodel=small
9813@opindex mmodel=small
9814Assume all objects live in the lower 16MB of memory (so that their addresses
9815can be loaded with the @code{ld24} instruction), and assume all subroutines
9816are reachable with the @code{bl} instruction.
9817This is the default.
9818
9819The addressability of a particular object can be set with the
9820@code{model} attribute.
9821
9822@item -mmodel=medium
9823@opindex mmodel=medium
9824Assume objects may be anywhere in the 32-bit address space (the compiler
9825will generate @code{seth/add3} instructions to load their addresses), and
9826assume all subroutines are reachable with the @code{bl} instruction.
9827
9828@item -mmodel=large
9829@opindex mmodel=large
9830Assume objects may be anywhere in the 32-bit address space (the compiler
9831will generate @code{seth/add3} instructions to load their addresses), and
9832assume subroutines may not be reachable with the @code{bl} instruction
9833(the compiler will generate the much slower @code{seth/add3/jl}
9834instruction sequence).
9835
9836@item -msdata=none
9837@opindex msdata=none
9838Disable use of the small data area. Variables will be put into
9839one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
9840@code{section} attribute has been specified).
9841This is the default.
9842
9843The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
9844Objects may be explicitly put in the small data area with the
9845@code{section} attribute using one of these sections.
9846
9847@item -msdata=sdata
9848@opindex msdata=sdata
9849Put small global and static data in the small data area, but do not
9850generate special code to reference them.
9851
9852@item -msdata=use
9853@opindex msdata=use
9854Put small global and static data in the small data area, and generate
9855special instructions to reference them.
9856
9857@item -G @var{num}
9858@opindex G
9859@cindex smaller data references
9860Put global and static objects less than or equal to @var{num} bytes
9861into the small data or bss sections instead of the normal data or bss
9862sections. The default value of @var{num} is 8.
9863The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
9864for this option to have any effect.
9865
9866All modules should be compiled with the same @option{-G @var{num}} value.
9867Compiling with different values of @var{num} may or may not work; if it
9868doesn't the linker will give an error message---incorrect code will not be
9869generated.
9870
9871@item -mdebug
9872@opindex mdebug
9873Makes the M32R specific code in the compiler display some statistics
9874that might help in debugging programs.
9875
9876@item -malign-loops
9877@opindex malign-loops
9878Align all loops to a 32-byte boundary.
9879
9880@item -mno-align-loops
9881@opindex mno-align-loops
9882Do not enforce a 32-byte alignment for loops. This is the default.
9883
9884@item -missue-rate=@var{number}
9885@opindex missue-rate=@var{number}
9886Issue @var{number} instructions per cycle. @var{number} can only be 1
9887or 2.
9888
9889@item -mbranch-cost=@var{number}
9890@opindex mbranch-cost=@var{number}
9891@var{number} can only be 1 or 2. If it is 1 then branches will be
9892preferred over conditional code, if it is 2, then the opposite will
9893apply.
9894
9895@item -mflush-trap=@var{number}
9896@opindex mflush-trap=@var{number}
9897Specifies the trap number to use to flush the cache. The default is
989812. Valid numbers are between 0 and 15 inclusive.
9899
9900@item -mno-flush-trap
9901@opindex mno-flush-trap
9902Specifies that the cache cannot be flushed by using a trap.
9903
9904@item -mflush-func=@var{name}
9905@opindex mflush-func=@var{name}
9906Specifies the name of the operating system function to call to flush
9907the cache. The default is @emph{_flush_cache}, but a function call
9908will only be used if a trap is not available.
9909
9910@item -mno-flush-func
9911@opindex mno-flush-func
9912Indicates that there is no OS function for flushing the cache.
9913
9914@end table
9915
9916@node M680x0 Options
9917@subsection M680x0 Options
9918@cindex M680x0 options
9919
9920These are the @samp{-m} options defined for the 68000 series. The default
9921values for these options depends on which style of 68000 was selected when
9922the compiler was configured; the defaults for the most common choices are
9923given below.
9924
9925@table @gcctabopt
9926@item -m68000
9927@itemx -mc68000
9928@opindex m68000
9929@opindex mc68000
9930Generate output for a 68000. This is the default
9931when the compiler is configured for 68000-based systems.
9932
9933Use this option for microcontrollers with a 68000 or EC000 core,
9934including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
9935
9936@item -m68020
9937@itemx -mc68020
9938@opindex m68020
9939@opindex mc68020
9940Generate output for a 68020. This is the default
9941when the compiler is configured for 68020-based systems.
9942
9943@item -m68881
9944@opindex m68881
9945Generate output containing 68881 instructions for floating point.
9946This is the default for most 68020 systems unless @option{--nfp} was
9947specified when the compiler was configured.
9948
9949@item -m68030
9950@opindex m68030
9951Generate output for a 68030. This is the default when the compiler is
9952configured for 68030-based systems.
9953
9954@item -m68040
9955@opindex m68040
9956Generate output for a 68040. This is the default when the compiler is
9957configured for 68040-based systems.
9958
9959This option inhibits the use of 68881/68882 instructions that have to be
9960emulated by software on the 68040. Use this option if your 68040 does not
9961have code to emulate those instructions.
9962
9963@item -m68060
9964@opindex m68060
9965Generate output for a 68060. This is the default when the compiler is
9966configured for 68060-based systems.
9967
9968This option inhibits the use of 68020 and 68881/68882 instructions that
9969have to be emulated by software on the 68060. Use this option if your 68060
9970does not have code to emulate those instructions.
9971
9972@item -mcpu32
9973@opindex mcpu32
9974Generate output for a CPU32. This is the default
9975when the compiler is configured for CPU32-based systems.
9976
9977Use this option for microcontrollers with a
9978CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
997968336, 68340, 68341, 68349 and 68360.
9980
9981@item -m5200
9982@opindex m5200
9983Generate output for a 520X ``coldfire'' family cpu. This is the default
9984when the compiler is configured for 520X-based systems.
9985
9986Use this option for microcontroller with a 5200 core, including
9987the MCF5202, MCF5203, MCF5204 and MCF5202.
9988
9989@item -mcfv4e
9990@opindex mcfv4e
9991Generate output for a ColdFire V4e family cpu (e.g.@: 547x/548x).
9992This includes use of hardware floating point instructions.
9993
9994@item -m68020-40
9995@opindex m68020-40
9996Generate output for a 68040, without using any of the new instructions.
9997This results in code which can run relatively efficiently on either a
999868020/68881 or a 68030 or a 68040. The generated code does use the
999968881 instructions that are emulated on the 68040.
10000
10001@item -m68020-60
10002@opindex m68020-60
10003Generate output for a 68060, without using any of the new instructions.
10004This results in code which can run relatively efficiently on either a
1000568020/68881 or a 68030 or a 68040. The generated code does use the
1000668881 instructions that are emulated on the 68060.
10007
10008@item -msoft-float
10009@opindex msoft-float
10010Generate output containing library calls for floating point.
10011@strong{Warning:} the requisite libraries are not available for all m68k
10012targets. Normally the facilities of the machine's usual C compiler are
10013used, but this can't be done directly in cross-compilation. You must
10014make your own arrangements to provide suitable library functions for
10015cross-compilation. The embedded targets @samp{m68k-*-aout} and
10016@samp{m68k-*-coff} do provide software floating point support.
10017
10018@item -mshort
10019@opindex mshort
10020Consider type @code{int} to be 16 bits wide, like @code{short int}.
10021Additionally, parameters passed on the stack are also aligned to a
1002216-bit boundary even on targets whose API mandates promotion to 32-bit.
10023
10024@item -mnobitfield
10025@opindex mnobitfield
10026Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
10027and @option{-m5200} options imply @w{@option{-mnobitfield}}.
10028
10029@item -mbitfield
10030@opindex mbitfield
10031Do use the bit-field instructions. The @option{-m68020} option implies
10032@option{-mbitfield}. This is the default if you use a configuration
10033designed for a 68020.
10034
10035@item -mrtd
10036@opindex mrtd
10037Use a different function-calling convention, in which functions
10038that take a fixed number of arguments return with the @code{rtd}
10039instruction, which pops their arguments while returning. This
10040saves one instruction in the caller since there is no need to pop
10041the arguments there.
10042
10043This calling convention is incompatible with the one normally
10044used on Unix, so you cannot use it if you need to call libraries
10045compiled with the Unix compiler.
10046
10047Also, you must provide function prototypes for all functions that
10048take variable numbers of arguments (including @code{printf});
10049otherwise incorrect code will be generated for calls to those
10050functions.
10051
10052In addition, seriously incorrect code will result if you call a
10053function with too many arguments. (Normally, extra arguments are
10054harmlessly ignored.)
10055
10056The @code{rtd} instruction is supported by the 68010, 68020, 68030,
1005768040, 68060 and CPU32 processors, but not by the 68000 or 5200.
10058
10059@item -malign-int
10060@itemx -mno-align-int
10061@opindex malign-int
10062@opindex mno-align-int
10063Control whether GCC aligns @code{int}, @code{long}, @code{long long},
10064@code{float}, @code{double}, and @code{long double} variables on a 32-bit
10065boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
10066Aligning variables on 32-bit boundaries produces code that runs somewhat
10067faster on processors with 32-bit busses at the expense of more memory.
10068
10069@strong{Warning:} if you use the @option{-malign-int} switch, GCC will
10070align structures containing the above types differently than
10071most published application binary interface specifications for the m68k.
10072
10073@item -mpcrel
10074@opindex mpcrel
10075Use the pc-relative addressing mode of the 68000 directly, instead of
10076using a global offset table. At present, this option implies @option{-fpic},
10077allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
10078not presently supported with @option{-mpcrel}, though this could be supported for
1007968020 and higher processors.
10080
10081@item -mno-strict-align
10082@itemx -mstrict-align
10083@opindex mno-strict-align
10084@opindex mstrict-align
10085Do not (do) assume that unaligned memory references will be handled by
10086the system.
10087
10088@item -msep-data
10089Generate code that allows the data segment to be located in a different
10090area of memory from the text segment. This allows for execute in place in
10091an environment without virtual memory management. This option implies
10092@option{-fPIC}.
10093
10094@item -mno-sep-data
10095Generate code that assumes that the data segment follows the text segment.
10096This is the default.
10097
10098@item -mid-shared-library
10099Generate code that supports shared libraries via the library ID method.
10100This allows for execute in place and shared libraries in an environment
10101without virtual memory management. This option implies @option{-fPIC}.
10102
10103@item -mno-id-shared-library
10104Generate code that doesn't assume ID based shared libraries are being used.
10105This is the default.
10106
10107@item -mshared-library-id=n
10108Specified the identification number of the ID based shared library being
10109compiled. Specifying a value of 0 will generate more compact code, specifying
10110other values will force the allocation of that number to the current
10111library but is no more space or time efficient than omitting this option.
10112
10113@end table
10114
10115@node M68hc1x Options
10116@subsection M68hc1x Options
10117@cindex M68hc1x options
10118
10119These are the @samp{-m} options defined for the 68hc11 and 68hc12
10120microcontrollers. The default values for these options depends on
10121which style of microcontroller was selected when the compiler was configured;
10122the defaults for the most common choices are given below.
10123
10124@table @gcctabopt
10125@item -m6811
10126@itemx -m68hc11
10127@opindex m6811
10128@opindex m68hc11
10129Generate output for a 68HC11. This is the default
10130when the compiler is configured for 68HC11-based systems.
10131
10132@item -m6812
10133@itemx -m68hc12
10134@opindex m6812
10135@opindex m68hc12
10136Generate output for a 68HC12. This is the default
10137when the compiler is configured for 68HC12-based systems.
10138
10139@item -m68S12
10140@itemx -m68hcs12
10141@opindex m68S12
10142@opindex m68hcs12
10143Generate output for a 68HCS12.
10144
10145@item -mauto-incdec
10146@opindex mauto-incdec
10147Enable the use of 68HC12 pre and post auto-increment and auto-decrement
10148addressing modes.
10149
10150@item -minmax
10151@itemx -nominmax
10152@opindex minmax
10153@opindex mnominmax
10154Enable the use of 68HC12 min and max instructions.
10155
10156@item -mlong-calls
10157@itemx -mno-long-calls
10158@opindex mlong-calls
10159@opindex mno-long-calls
10160Treat all calls as being far away (near). If calls are assumed to be
10161far away, the compiler will use the @code{call} instruction to
10162call a function and the @code{rtc} instruction for returning.
10163
10164@item -mshort
10165@opindex mshort
10166Consider type @code{int} to be 16 bits wide, like @code{short int}.
10167
10168@item -msoft-reg-count=@var{count}
10169@opindex msoft-reg-count
10170Specify the number of pseudo-soft registers which are used for the
10171code generation. The maximum number is 32. Using more pseudo-soft
10172register may or may not result in better code depending on the program.
10173The default is 4 for 68HC11 and 2 for 68HC12.
10174
10175@end table
10176
10177@node MCore Options
10178@subsection MCore Options
10179@cindex MCore options
10180
10181These are the @samp{-m} options defined for the Motorola M*Core
10182processors.
10183
10184@table @gcctabopt
10185
10186@item -mhardlit
10187@itemx -mno-hardlit
10188@opindex mhardlit
10189@opindex mno-hardlit
10190Inline constants into the code stream if it can be done in two
10191instructions or less.
10192
10193@item -mdiv
10194@itemx -mno-div
10195@opindex mdiv
10196@opindex mno-div
10197Use the divide instruction. (Enabled by default).
10198
10199@item -mrelax-immediate
10200@itemx -mno-relax-immediate
10201@opindex mrelax-immediate
10202@opindex mno-relax-immediate
10203Allow arbitrary sized immediates in bit operations.
10204
10205@item -mwide-bitfields
10206@itemx -mno-wide-bitfields
10207@opindex mwide-bitfields
10208@opindex mno-wide-bitfields
10209Always treat bit-fields as int-sized.
10210
10211@item -m4byte-functions
10212@itemx -mno-4byte-functions
10213@opindex m4byte-functions
10214@opindex mno-4byte-functions
10215Force all functions to be aligned to a four byte boundary.
10216
10217@item -mcallgraph-data
10218@itemx -mno-callgraph-data
10219@opindex mcallgraph-data
10220@opindex mno-callgraph-data
10221Emit callgraph information.
10222
10223@item -mslow-bytes
10224@itemx -mno-slow-bytes
10225@opindex mslow-bytes
10226@opindex mno-slow-bytes
10227Prefer word access when reading byte quantities.
10228
10229@item -mlittle-endian
10230@itemx -mbig-endian
10231@opindex mlittle-endian
10232@opindex mbig-endian
10233Generate code for a little endian target.
10234
10235@item -m210
10236@itemx -m340
10237@opindex m210
10238@opindex m340
10239Generate code for the 210 processor.
10240@end table
10241
10242@node MIPS Options
10243@subsection MIPS Options
10244@cindex MIPS options
10245
10246@table @gcctabopt
10247
10248@item -EB
10249@opindex EB
10250Generate big-endian code.
10251
10252@item -EL
10253@opindex EL
10254Generate little-endian code. This is the default for @samp{mips*el-*-*}
10255configurations.
10256
10257@item -march=@var{arch}
10258@opindex march
10259Generate code that will run on @var{arch}, which can be the name of a
10260generic MIPS ISA, or the name of a particular processor.
10261The ISA names are:
10262@samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
10263@samp{mips32}, @samp{mips32r2}, and @samp{mips64}.
10264The processor names are:
10265@samp{4kc}, @samp{4km}, @samp{4kp},
10266@samp{5kc}, @samp{5kf},
10267@samp{20kc},
10268@samp{24k}, @samp{24kc}, @samp{24kf}, @samp{24kx},
10269@samp{m4k},
10270@samp{orion},
10271@samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
10272@samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000},
10273@samp{rm7000}, @samp{rm9000},
10274@samp{sb1},
10275@samp{sr71000},
10276@samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
10277@samp{vr5000}, @samp{vr5400} and @samp{vr5500}.
10278The special value @samp{from-abi} selects the
10279most compatible architecture for the selected ABI (that is,
10280@samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
10281
10282In processor names, a final @samp{000} can be abbreviated as @samp{k}
10283(for example, @samp{-march=r2k}). Prefixes are optional, and
10284@samp{vr} may be written @samp{r}.
10285
10286GCC defines two macros based on the value of this option. The first
10287is @samp{_MIPS_ARCH}, which gives the name of target architecture, as
10288a string. The second has the form @samp{_MIPS_ARCH_@var{foo}},
10289where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@.
10290For example, @samp{-march=r2000} will set @samp{_MIPS_ARCH}
10291to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}.
10292
10293Note that the @samp{_MIPS_ARCH} macro uses the processor names given
10294above. In other words, it will have the full prefix and will not
10295abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},
10296the macro names the resolved architecture (either @samp{"mips1"} or
10297@samp{"mips3"}). It names the default architecture when no
10298@option{-march} option is given.
10299
10300@item -mtune=@var{arch}
10301@opindex mtune
10302Optimize for @var{arch}. Among other things, this option controls
10303the way instructions are scheduled, and the perceived cost of arithmetic
10304operations. The list of @var{arch} values is the same as for
10305@option{-march}.
10306
10307When this option is not used, GCC will optimize for the processor
10308specified by @option{-march}. By using @option{-march} and
10309@option{-mtune} together, it is possible to generate code that will
10310run on a family of processors, but optimize the code for one
10311particular member of that family.
10312
10313@samp{-mtune} defines the macros @samp{_MIPS_TUNE} and
10314@samp{_MIPS_TUNE_@var{foo}}, which work in the same way as the
10315@samp{-march} ones described above.
10316
10317@item -mips1
10318@opindex mips1
10319Equivalent to @samp{-march=mips1}.
10320
10321@item -mips2
10322@opindex mips2
10323Equivalent to @samp{-march=mips2}.
10324
10325@item -mips3
10326@opindex mips3
10327Equivalent to @samp{-march=mips3}.
10328
10329@item -mips4
10330@opindex mips4
10331Equivalent to @samp{-march=mips4}.
10332
10333@item -mips32
10334@opindex mips32
10335Equivalent to @samp{-march=mips32}.
10336
10337@item -mips32r2
10338@opindex mips32r2
10339Equivalent to @samp{-march=mips32r2}.
10340
10341@item -mips64
10342@opindex mips64
10343Equivalent to @samp{-march=mips64}.
10344
10345@item -mips16
10346@itemx -mno-mips16
10347@opindex mips16
10348@opindex mno-mips16
10349Generate (do not generate) MIPS16 code. If GCC is targetting a
10350MIPS32 or MIPS64 architecture, it will make use of the MIPS16e ASE@.
10351
10352@item -mabi=32
10353@itemx -mabi=o64
10354@itemx -mabi=n32
10355@itemx -mabi=64
10356@itemx -mabi=eabi
10357@opindex mabi=32
10358@opindex mabi=o64
10359@opindex mabi=n32
10360@opindex mabi=64
10361@opindex mabi=eabi
10362Generate code for the given ABI@.
10363
10364Note that the EABI has a 32-bit and a 64-bit variant. GCC normally
10365generates 64-bit code when you select a 64-bit architecture, but you
10366can use @option{-mgp32} to get 32-bit code instead.
10367
10368For information about the O64 ABI, see
10369@w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
10370
10371@item -mabicalls
10372@itemx -mno-abicalls
10373@opindex mabicalls
10374@opindex mno-abicalls
10375Generate (do not generate) code that is suitable for SVR4-style
10376dynamic objects. @option{-mabicalls} is the default for SVR4-based
10377systems.
10378
10379@item -mshared
10380@itemx -mno-shared
10381Generate (do not generate) code that is fully position-independent,
10382and that can therefore be linked into shared libraries. This option
10383only affects @option{-mabicalls}.
10384
10385All @option{-mabicalls} code has traditionally been position-independent,
10386regardless of options like @option{-fPIC} and @option{-fpic}. However,
10387as an extension, the GNU toolchain allows executables to use absolute
10388accesses for locally-binding symbols. It can also use shorter GP
10389initialization sequences and generate direct calls to locally-defined
10390functions. This mode is selected by @option{-mno-shared}.
10391
10392@option{-mno-shared} depends on binutils 2.16 or higher and generates
10393objects that can only be linked by the GNU linker. However, the option
10394does not affect the ABI of the final executable; it only affects the ABI
10395of relocatable objects. Using @option{-mno-shared} will generally make
10396executables both smaller and quicker.
10397
10398@option{-mshared} is the default.
10399
10400@item -mxgot
10401@itemx -mno-xgot
10402@opindex mxgot
10403@opindex mno-xgot
10404Lift (do not lift) the usual restrictions on the size of the global
10405offset table.
10406
10407GCC normally uses a single instruction to load values from the GOT@.
10408While this is relatively efficient, it will only work if the GOT
10409is smaller than about 64k. Anything larger will cause the linker
10410to report an error such as:
10411
10412@cindex relocation truncated to fit (MIPS)
10413@smallexample
10414relocation truncated to fit: R_MIPS_GOT16 foobar
10415@end smallexample
10416
10417If this happens, you should recompile your code with @option{-mxgot}.
10418It should then work with very large GOTs, although it will also be
10419less efficient, since it will take three instructions to fetch the
10420value of a global symbol.
10421
10422Note that some linkers can create multiple GOTs. If you have such a
10423linker, you should only need to use @option{-mxgot} when a single object
10424file accesses more than 64k's worth of GOT entries. Very few do.
10425
10426These options have no effect unless GCC is generating position
10427independent code.
10428
10429@item -mgp32
10430@opindex mgp32
10431Assume that general-purpose registers are 32 bits wide.
10432
10433@item -mgp64
10434@opindex mgp64
10435Assume that general-purpose registers are 64 bits wide.
10436
10437@item -mfp32
10438@opindex mfp32
10439Assume that floating-point registers are 32 bits wide.
10440
10441@item -mfp64
10442@opindex mfp64
10443Assume that floating-point registers are 64 bits wide.
10444
10445@item -mhard-float
10446@opindex mhard-float
10447Use floating-point coprocessor instructions.
10448
10449@item -msoft-float
10450@opindex msoft-float
10451Do not use floating-point coprocessor instructions. Implement
10452floating-point calculations using library calls instead.
10453
10454@item -msingle-float
10455@opindex msingle-float
10456Assume that the floating-point coprocessor only supports single-precision
10457operations.
10458
10459@itemx -mdouble-float
10460@opindex mdouble-float
10461Assume that the floating-point coprocessor supports double-precision
10462operations. This is the default.
10463
10464@itemx -mdsp
10465@itemx -mno-dsp
10466@opindex mdsp
10467@opindex mno-dsp
10468Use (do not use) the MIPS DSP ASE. @xref{MIPS DSP Built-in Functions}.
10469
10470@itemx -mpaired-single
10471@itemx -mno-paired-single
10472@opindex mpaired-single
10473@opindex mno-paired-single
10474Use (do not use) paired-single floating-point instructions.
10475@xref{MIPS Paired-Single Support}. This option can only be used
10476when generating 64-bit code and requires hardware floating-point
10477support to be enabled.
10478
10479@itemx -mips3d
10480@itemx -mno-mips3d
10481@opindex mips3d
10482@opindex mno-mips3d
10483Use (do not use) the MIPS-3D ASE@. @xref{MIPS-3D Built-in Functions}.
10484The option @option{-mips3d} implies @option{-mpaired-single}.
10485
10486@item -mlong64
10487@opindex mlong64
10488Force @code{long} types to be 64 bits wide. See @option{-mlong32} for
10489an explanation of the default and the way that the pointer size is
10490determined.
10491
10492@item -mlong32
10493@opindex mlong32
10494Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
10495
10496The default size of @code{int}s, @code{long}s and pointers depends on
10497the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI
10498uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
1049932-bit @code{long}s. Pointers are the same size as @code{long}s,
10500or the same size as integer registers, whichever is smaller.
10501
10502@item -msym32
10503@itemx -mno-sym32
10504@opindex msym32
10505@opindex mno-sym32
10506Assume (do not assume) that all symbols have 32-bit values, regardless
10507of the selected ABI@. This option is useful in combination with
10508@option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
10509to generate shorter and faster references to symbolic addresses.
10510
10511@item -G @var{num}
10512@opindex G
10513@cindex smaller data references (MIPS)
10514@cindex gp-relative references (MIPS)
10515Put global and static items less than or equal to @var{num} bytes into
10516the small data or bss section instead of the normal data or bss section.
10517This allows the data to be accessed using a single instruction.
10518
10519All modules should be compiled with the same @option{-G @var{num}}
10520value.
10521
10522@item -membedded-data
10523@itemx -mno-embedded-data
10524@opindex membedded-data
10525@opindex mno-embedded-data
10526Allocate variables to the read-only data section first if possible, then
10527next in the small data section if possible, otherwise in data. This gives
10528slightly slower code than the default, but reduces the amount of RAM required
10529when executing, and thus may be preferred for some embedded systems.
10530
10531@item -muninit-const-in-rodata
10532@itemx -mno-uninit-const-in-rodata
10533@opindex muninit-const-in-rodata
10534@opindex mno-uninit-const-in-rodata
10535Put uninitialized @code{const} variables in the read-only data section.
10536This option is only meaningful in conjunction with @option{-membedded-data}.
10537
10538@item -msplit-addresses
10539@itemx -mno-split-addresses
10540@opindex msplit-addresses
10541@opindex mno-split-addresses
10542Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
10543relocation operators. This option has been superseded by
10544@option{-mexplicit-relocs} but is retained for backwards compatibility.
10545
10546@item -mexplicit-relocs
10547@itemx -mno-explicit-relocs
10548@opindex mexplicit-relocs
10549@opindex mno-explicit-relocs
10550Use (do not use) assembler relocation operators when dealing with symbolic
10551addresses. The alternative, selected by @option{-mno-explicit-relocs},
10552is to use assembler macros instead.
10553
10554@option{-mexplicit-relocs} is the default if GCC was configured
10555to use an assembler that supports relocation operators.
10556
10557@item -mcheck-zero-division
10558@itemx -mno-check-zero-division
10559@opindex mcheck-zero-division
10560@opindex mno-check-zero-division
10561Trap (do not trap) on integer division by zero. The default is
10562@option{-mcheck-zero-division}.
10563
10564@item -mdivide-traps
10565@itemx -mdivide-breaks
10566@opindex mdivide-traps
10567@opindex mdivide-breaks
10568MIPS systems check for division by zero by generating either a
10569conditional trap or a break instruction. Using traps results in
10570smaller code, but is only supported on MIPS II and later. Also, some
10571versions of the Linux kernel have a bug that prevents trap from
10572generating the proper signal (@code{SIGFPE}). Use @option{-mdivide-traps} to
10573allow conditional traps on architectures that support them and
10574@option{-mdivide-breaks} to force the use of breaks.
10575
10576The default is usually @option{-mdivide-traps}, but this can be
10577overridden at configure time using @option{--with-divide=breaks}.
10578Divide-by-zero checks can be completely disabled using
10579@option{-mno-check-zero-division}.
10580
10581@item -mmemcpy
10582@itemx -mno-memcpy
10583@opindex mmemcpy
10584@opindex mno-memcpy
10585Force (do not force) the use of @code{memcpy()} for non-trivial block
10586moves. The default is @option{-mno-memcpy}, which allows GCC to inline
10587most constant-sized copies.
10588
10589@item -mlong-calls
10590@itemx -mno-long-calls
10591@opindex mlong-calls
10592@opindex mno-long-calls
10593Disable (do not disable) use of the @code{jal} instruction. Calling
10594functions using @code{jal} is more efficient but requires the caller
10595and callee to be in the same 256 megabyte segment.
10596
10597This option has no effect on abicalls code. The default is
10598@option{-mno-long-calls}.
10599
10600@item -mmad
10601@itemx -mno-mad
10602@opindex mmad
10603@opindex mno-mad
10604Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
10605instructions, as provided by the R4650 ISA@.
10606
10607@item -mfused-madd
10608@itemx -mno-fused-madd
10609@opindex mfused-madd
10610@opindex mno-fused-madd
10611Enable (disable) use of the floating point multiply-accumulate
10612instructions, when they are available. The default is
10613@option{-mfused-madd}.
10614
10615When multiply-accumulate instructions are used, the intermediate
10616product is calculated to infinite precision and is not subject to
10617the FCSR Flush to Zero bit. This may be undesirable in some
10618circumstances.
10619
10620@item -nocpp
10621@opindex nocpp
10622Tell the MIPS assembler to not run its preprocessor over user
10623assembler files (with a @samp{.s} suffix) when assembling them.
10624
10625@item -mfix-r4000
10626@itemx -mno-fix-r4000
10627@opindex mfix-r4000
10628@opindex mno-fix-r4000
10629Work around certain R4000 CPU errata:
10630@itemize @minus
10631@item
10632A double-word or a variable shift may give an incorrect result if executed
10633immediately after starting an integer division.
10634@item
10635A double-word or a variable shift may give an incorrect result if executed
10636while an integer multiplication is in progress.
10637@item
10638An integer division may give an incorrect result if started in a delay slot
10639of a taken branch or a jump.
10640@end itemize
10641
10642@item -mfix-r4400
10643@itemx -mno-fix-r4400
10644@opindex mfix-r4400
10645@opindex mno-fix-r4400
10646Work around certain R4400 CPU errata:
10647@itemize @minus
10648@item
10649A double-word or a variable shift may give an incorrect result if executed
10650immediately after starting an integer division.
10651@end itemize
10652
10653@item -mfix-vr4120
10654@itemx -mno-fix-vr4120
10655@opindex mfix-vr4120
10656Work around certain VR4120 errata:
10657@itemize @minus
10658@item
10659@code{dmultu} does not always produce the correct result.
10660@item
10661@code{div} and @code{ddiv} do not always produce the correct result if one
10662of the operands is negative.
10663@end itemize
10664The workarounds for the division errata rely on special functions in
10665@file{libgcc.a}. At present, these functions are only provided by
10666the @code{mips64vr*-elf} configurations.
10667
10668Other VR4120 errata require a nop to be inserted between certain pairs of
10669instructions. These errata are handled by the assembler, not by GCC itself.
10670
10671@item -mfix-vr4130
10672@opindex mfix-vr4130
10673Work around the VR4130 @code{mflo}/@code{mfhi} errata. The
10674workarounds are implemented by the assembler rather than by GCC,
10675although GCC will avoid using @code{mflo} and @code{mfhi} if the
10676VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
10677instructions are available instead.
10678
10679@item -mfix-sb1
10680@itemx -mno-fix-sb1
10681@opindex mfix-sb1
10682Work around certain SB-1 CPU core errata.
10683(This flag currently works around the SB-1 revision 2
10684``F1'' and ``F2'' floating point errata.)
10685
10686@item -mflush-func=@var{func}
10687@itemx -mno-flush-func
10688@opindex mflush-func
10689Specifies the function to call to flush the I and D caches, or to not
10690call any such function. If called, the function must take the same
10691arguments as the common @code{_flush_func()}, that is, the address of the
10692memory range for which the cache is being flushed, the size of the
10693memory range, and the number 3 (to flush both caches). The default
10694depends on the target GCC was configured for, but commonly is either
10695@samp{_flush_func} or @samp{__cpu_flush}.
10696
10697@item -mbranch-likely
10698@itemx -mno-branch-likely
10699@opindex mbranch-likely
10700@opindex mno-branch-likely
10701Enable or disable use of Branch Likely instructions, regardless of the
10702default for the selected architecture. By default, Branch Likely
10703instructions may be generated if they are supported by the selected
10704architecture. An exception is for the MIPS32 and MIPS64 architectures
10705and processors which implement those architectures; for those, Branch
10706Likely instructions will not be generated by default because the MIPS32
10707and MIPS64 architectures specifically deprecate their use.
10708
10709@item -mfp-exceptions
10710@itemx -mno-fp-exceptions
10711@opindex mfp-exceptions
10712Specifies whether FP exceptions are enabled. This affects how we schedule
10713FP instructions for some processors. The default is that FP exceptions are
10714enabled.
10715
10716For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
1071764-bit code, then we can use both FP pipes. Otherwise, we can only use one
10718FP pipe.
10719
10720@item -mvr4130-align
10721@itemx -mno-vr4130-align
10722@opindex mvr4130-align
10723The VR4130 pipeline is two-way superscalar, but can only issue two
10724instructions together if the first one is 8-byte aligned. When this
10725option is enabled, GCC will align pairs of instructions that it
10726thinks should execute in parallel.
10727
10728This option only has an effect when optimizing for the VR4130.
10729It normally makes code faster, but at the expense of making it bigger.
10730It is enabled by default at optimization level @option{-O3}.
10731@end table
10732
10733@node MMIX Options
10734@subsection MMIX Options
10735@cindex MMIX Options
10736
10737These options are defined for the MMIX:
10738
10739@table @gcctabopt
10740@item -mlibfuncs
10741@itemx -mno-libfuncs
10742@opindex mlibfuncs
10743@opindex mno-libfuncs
10744Specify that intrinsic library functions are being compiled, passing all
10745values in registers, no matter the size.
10746
10747@item -mepsilon
10748@itemx -mno-epsilon
10749@opindex mepsilon
10750@opindex mno-epsilon
10751Generate floating-point comparison instructions that compare with respect
10752to the @code{rE} epsilon register.
10753
10754@item -mabi=mmixware
10755@itemx -mabi=gnu
10756@opindex mabi-mmixware
10757@opindex mabi=gnu
10758Generate code that passes function parameters and return values that (in
10759the called function) are seen as registers @code{$0} and up, as opposed to
10760the GNU ABI which uses global registers @code{$231} and up.
10761
10762@item -mzero-extend
10763@itemx -mno-zero-extend
10764@opindex mzero-extend
10765@opindex mno-zero-extend
10766When reading data from memory in sizes shorter than 64 bits, use (do not
10767use) zero-extending load instructions by default, rather than
10768sign-extending ones.
10769
10770@item -mknuthdiv
10771@itemx -mno-knuthdiv
10772@opindex mknuthdiv
10773@opindex mno-knuthdiv
10774Make the result of a division yielding a remainder have the same sign as
10775the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
10776remainder follows the sign of the dividend. Both methods are
10777arithmetically valid, the latter being almost exclusively used.
10778
10779@item -mtoplevel-symbols
10780@itemx -mno-toplevel-symbols
10781@opindex mtoplevel-symbols
10782@opindex mno-toplevel-symbols
10783Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
10784code can be used with the @code{PREFIX} assembly directive.
10785
10786@item -melf
10787@opindex melf
10788Generate an executable in the ELF format, rather than the default
10789@samp{mmo} format used by the @command{mmix} simulator.
10790
10791@item -mbranch-predict
10792@itemx -mno-branch-predict
10793@opindex mbranch-predict
10794@opindex mno-branch-predict
10795Use (do not use) the probable-branch instructions, when static branch
10796prediction indicates a probable branch.
10797
10798@item -mbase-addresses
10799@itemx -mno-base-addresses
10800@opindex mbase-addresses
10801@opindex mno-base-addresses
10802Generate (do not generate) code that uses @emph{base addresses}. Using a
10803base address automatically generates a request (handled by the assembler
10804and the linker) for a constant to be set up in a global register. The
10805register is used for one or more base address requests within the range 0
10806to 255 from the value held in the register. The generally leads to short
10807and fast code, but the number of different data items that can be
10808addressed is limited. This means that a program that uses lots of static
10809data may require @option{-mno-base-addresses}.
10810
10811@item -msingle-exit
10812@itemx -mno-single-exit
10813@opindex msingle-exit
10814@opindex mno-single-exit
10815Force (do not force) generated code to have a single exit point in each
10816function.
10817@end table
10818
10819@node MN10300 Options
10820@subsection MN10300 Options
10821@cindex MN10300 options
10822
10823These @option{-m} options are defined for Matsushita MN10300 architectures:
10824
10825@table @gcctabopt
10826@item -mmult-bug
10827@opindex mmult-bug
10828Generate code to avoid bugs in the multiply instructions for the MN10300
10829processors. This is the default.
10830
10831@item -mno-mult-bug
10832@opindex mno-mult-bug
10833Do not generate code to avoid bugs in the multiply instructions for the
10834MN10300 processors.
10835
10836@item -mam33
10837@opindex mam33
10838Generate code which uses features specific to the AM33 processor.
10839
10840@item -mno-am33
10841@opindex mno-am33
10842Do not generate code which uses features specific to the AM33 processor. This
10843is the default.
10844
10845@item -mreturn-pointer-on-d0
10846@opindex mreturn-pointer-on-d0
10847When generating a function which returns a pointer, return the pointer
10848in both @code{a0} and @code{d0}. Otherwise, the pointer is returned
10849only in a0, and attempts to call such functions without a prototype
10850would result in errors. Note that this option is on by default; use
10851@option{-mno-return-pointer-on-d0} to disable it.
10852
10853@item -mno-crt0
10854@opindex mno-crt0
10855Do not link in the C run-time initialization object file.
10856
10857@item -mrelax
10858@opindex mrelax
10859Indicate to the linker that it should perform a relaxation optimization pass
10860to shorten branches, calls and absolute memory addresses. This option only
10861has an effect when used on the command line for the final link step.
10862
10863This option makes symbolic debugging impossible.
10864@end table
10865
10866@node MT Options
10867@subsection MT Options
10868@cindex MT options
10869
10870These @option{-m} options are defined for Morpho MT architectures:
10871
10872@table @gcctabopt
10873
10874@item -march=@var{cpu-type}
10875@opindex march
10876Generate code that will run on @var{cpu-type}, which is the name of a system
10877representing a certain processor type. Possible values for
10878@var{cpu-type} are @samp{ms1-64-001}, @samp{ms1-16-002},
10879@samp{ms1-16-003} and @samp{ms2}.
10880
10881When this option is not used, the default is @option{-march=ms1-16-002}.
10882
10883@item -mbacc
10884@opindex mbacc
10885Use byte loads and stores when generating code.
10886
10887@item -mno-bacc
10888@opindex mno-bacc
10889Do not use byte loads and stores when generating code.
10890
10891@item -msim
10892@opindex msim
10893Use simulator runtime
10894
10895@item -mno-crt0
10896@opindex mno-crt0
10897Do not link in the C run-time initialization object file
10898@file{crti.o}. Other run-time initialization and termination files
10899such as @file{startup.o} and @file{exit.o} are still included on the
10900linker command line.
10901
10902@end table
10903
10904@node PDP-11 Options
10905@subsection PDP-11 Options
10906@cindex PDP-11 Options
10907
10908These options are defined for the PDP-11:
10909
10910@table @gcctabopt
10911@item -mfpu
10912@opindex mfpu
10913Use hardware FPP floating point. This is the default. (FIS floating
10914point on the PDP-11/40 is not supported.)
10915
10916@item -msoft-float
10917@opindex msoft-float
10918Do not use hardware floating point.
10919
10920@item -mac0
10921@opindex mac0
10922Return floating-point results in ac0 (fr0 in Unix assembler syntax).
10923
10924@item -mno-ac0
10925@opindex mno-ac0
10926Return floating-point results in memory. This is the default.
10927
10928@item -m40
10929@opindex m40
10930Generate code for a PDP-11/40.
10931
10932@item -m45
10933@opindex m45
10934Generate code for a PDP-11/45. This is the default.
10935
10936@item -m10
10937@opindex m10
10938Generate code for a PDP-11/10.
10939
10940@item -mbcopy-builtin
10941@opindex bcopy-builtin
10942Use inline @code{movmemhi} patterns for copying memory. This is the
10943default.
10944
10945@item -mbcopy
10946@opindex mbcopy
10947Do not use inline @code{movmemhi} patterns for copying memory.
10948
10949@item -mint16
10950@itemx -mno-int32
10951@opindex mint16
10952@opindex mno-int32
10953Use 16-bit @code{int}. This is the default.
10954
10955@item -mint32
10956@itemx -mno-int16
10957@opindex mint32
10958@opindex mno-int16
10959Use 32-bit @code{int}.
10960
10961@item -mfloat64
10962@itemx -mno-float32
10963@opindex mfloat64
10964@opindex mno-float32
10965Use 64-bit @code{float}. This is the default.
10966
10967@item -mfloat32
10968@itemx -mno-float64
10969@opindex mfloat32
10970@opindex mno-float64
10971Use 32-bit @code{float}.
10972
10973@item -mabshi
10974@opindex mabshi
10975Use @code{abshi2} pattern. This is the default.
10976
10977@item -mno-abshi
10978@opindex mno-abshi
10979Do not use @code{abshi2} pattern.
10980
10981@item -mbranch-expensive
10982@opindex mbranch-expensive
10983Pretend that branches are expensive. This is for experimenting with
10984code generation only.
10985
10986@item -mbranch-cheap
10987@opindex mbranch-cheap
10988Do not pretend that branches are expensive. This is the default.
10989
10990@item -msplit
10991@opindex msplit
10992Generate code for a system with split I&D@.
10993
10994@item -mno-split
10995@opindex mno-split
10996Generate code for a system without split I&D@. This is the default.
10997
10998@item -munix-asm
10999@opindex munix-asm
11000Use Unix assembler syntax. This is the default when configured for
11001@samp{pdp11-*-bsd}.
11002
11003@item -mdec-asm
11004@opindex mdec-asm
11005Use DEC assembler syntax. This is the default when configured for any
11006PDP-11 target other than @samp{pdp11-*-bsd}.
11007@end table
11008
11009@node PowerPC Options
11010@subsection PowerPC Options
11011@cindex PowerPC options
11012
11013These are listed under @xref{RS/6000 and PowerPC Options}.
11014
11015@node RS/6000 and PowerPC Options
11016@subsection IBM RS/6000 and PowerPC Options
11017@cindex RS/6000 and PowerPC Options
11018@cindex IBM RS/6000 and PowerPC Options
11019
11020These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
11021@table @gcctabopt
11022@item -mpower
11023@itemx -mno-power
11024@itemx -mpower2
11025@itemx -mno-power2
11026@itemx -mpowerpc
11027@itemx -mno-powerpc
11028@itemx -mpowerpc-gpopt
11029@itemx -mno-powerpc-gpopt
11030@itemx -mpowerpc-gfxopt
11031@itemx -mno-powerpc-gfxopt
11032@itemx -mpowerpc64
11033@itemx -mno-powerpc64
11034@itemx -mmfcrf
11035@itemx -mno-mfcrf
11036@itemx -mpopcntb
11037@itemx -mno-popcntb
11038@itemx -mfprnd
11039@itemx -mno-fprnd
11040@opindex mpower
11041@opindex mno-power
11042@opindex mpower2
11043@opindex mno-power2
11044@opindex mpowerpc
11045@opindex mno-powerpc
11046@opindex mpowerpc-gpopt
11047@opindex mno-powerpc-gpopt
11048@opindex mpowerpc-gfxopt
11049@opindex mno-powerpc-gfxopt
11050@opindex mpowerpc64
11051@opindex mno-powerpc64
11052@opindex mmfcrf
11053@opindex mno-mfcrf
11054@opindex mpopcntb
11055@opindex mno-popcntb
11056@opindex mfprnd
11057@opindex mno-fprnd
11058GCC supports two related instruction set architectures for the
11059RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those
11060instructions supported by the @samp{rios} chip set used in the original
11061RS/6000 systems and the @dfn{PowerPC} instruction set is the
11062architecture of the Freescale MPC5xx, MPC6xx, MPC8xx microprocessors, and
11063the IBM 4xx, 6xx, and follow-on microprocessors.
11064
11065Neither architecture is a subset of the other. However there is a
11066large common subset of instructions supported by both. An MQ
11067register is included in processors supporting the POWER architecture.
11068
11069You use these options to specify which instructions are available on the
11070processor you are using. The default value of these options is
11071determined when configuring GCC@. Specifying the
11072@option{-mcpu=@var{cpu_type}} overrides the specification of these
11073options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
11074rather than the options listed above.
11075
11076The @option{-mpower} option allows GCC to generate instructions that
11077are found only in the POWER architecture and to use the MQ register.
11078Specifying @option{-mpower2} implies @option{-power} and also allows GCC
11079to generate instructions that are present in the POWER2 architecture but
11080not the original POWER architecture.
11081
11082The @option{-mpowerpc} option allows GCC to generate instructions that
11083are found only in the 32-bit subset of the PowerPC architecture.
11084Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
11085GCC to use the optional PowerPC architecture instructions in the
11086General Purpose group, including floating-point square root. Specifying
11087@option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
11088use the optional PowerPC architecture instructions in the Graphics
11089group, including floating-point select.
11090
11091The @option{-mmfcrf} option allows GCC to generate the move from
11092condition register field instruction implemented on the POWER4
11093processor and other processors that support the PowerPC V2.01
11094architecture.
11095The @option{-mpopcntb} option allows GCC to generate the popcount and
11096double precision FP reciprocal estimate instruction implemented on the
11097POWER5 processor and other processors that support the PowerPC V2.02
11098architecture.
11099The @option{-mfprnd} option allows GCC to generate the FP round to
11100integer instructions implemented on the POWER5+ processor and other
11101processors that support the PowerPC V2.03 architecture.
11102
11103The @option{-mpowerpc64} option allows GCC to generate the additional
1110464-bit instructions that are found in the full PowerPC64 architecture
11105and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
11106@option{-mno-powerpc64}.
11107
11108If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
11109will use only the instructions in the common subset of both
11110architectures plus some special AIX common-mode calls, and will not use
11111the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
11112permits GCC to use any instruction from either architecture and to
11113allow use of the MQ register; specify this for the Motorola MPC601.
11114
11115@item -mnew-mnemonics
11116@itemx -mold-mnemonics
11117@opindex mnew-mnemonics
11118@opindex mold-mnemonics
11119Select which mnemonics to use in the generated assembler code. With
11120@option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
11121the PowerPC architecture. With @option{-mold-mnemonics} it uses the
11122assembler mnemonics defined for the POWER architecture. Instructions
11123defined in only one architecture have only one mnemonic; GCC uses that
11124mnemonic irrespective of which of these options is specified.
11125
11126GCC defaults to the mnemonics appropriate for the architecture in
11127use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
11128value of these option. Unless you are building a cross-compiler, you
11129should normally not specify either @option{-mnew-mnemonics} or
11130@option{-mold-mnemonics}, but should instead accept the default.
11131
11132@item -mcpu=@var{cpu_type}
11133@opindex mcpu
11134Set architecture type, register usage, choice of mnemonics, and
11135instruction scheduling parameters for machine type @var{cpu_type}.
11136Supported values for @var{cpu_type} are @samp{401}, @samp{403},
11137@samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{505},
11138@samp{601}, @samp{602}, @samp{603}, @samp{603e}, @samp{604},
11139@samp{604e}, @samp{620}, @samp{630}, @samp{740}, @samp{7400},
11140@samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
11141@samp{860}, @samp{970}, @samp{8540}, @samp{ec603e}, @samp{G3},
11142@samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3},
11143@samp{power4}, @samp{power5}, @samp{power5+}, @samp{power6},
11144@samp{common}, @samp{powerpc}, @samp{powerpc64},
11145@samp{rios}, @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64}.
11146
11147@option{-mcpu=common} selects a completely generic processor. Code
11148generated under this option will run on any POWER or PowerPC processor.
11149GCC will use only the instructions in the common subset of both
11150architectures, and will not use the MQ register. GCC assumes a generic
11151processor model for scheduling purposes.
11152
11153@option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
11154@option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
11155PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
11156types, with an appropriate, generic processor model assumed for
11157scheduling purposes.
11158
11159The other options specify a specific processor. Code generated under
11160those options will run best on that processor, and may not run at all on
11161others.
11162
11163The @option{-mcpu} options automatically enable or disable the
11164following options: @option{-maltivec}, @option{-mfprnd},
11165@option{-mhard-float}, @option{-mmfcrf}, @option{-mmultiple},
11166@option{-mnew-mnemonics}, @option{-mpopcntb}, @option{-mpower},
11167@option{-mpower2}, @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
11168@option{-mpowerpc-gfxopt}, @option{-mstring}, @option{-mmulhw}, @option{-mdlmzb}.
11169The particular options
11170set for any particular CPU will vary between compiler versions,
11171depending on what setting seems to produce optimal code for that CPU;
11172it doesn't necessarily reflect the actual hardware's capabilities. If
11173you wish to set an individual option to a particular value, you may
11174specify it after the @option{-mcpu} option, like @samp{-mcpu=970
11175-mno-altivec}.
11176
11177On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
11178not enabled or disabled by the @option{-mcpu} option at present because
11179AIX does not have full support for these options. You may still
11180enable or disable them individually if you're sure it'll work in your
11181environment.
11182
11183@item -mtune=@var{cpu_type}
11184@opindex mtune
11185Set the instruction scheduling parameters for machine type
11186@var{cpu_type}, but do not set the architecture type, register usage, or
11187choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
11188values for @var{cpu_type} are used for @option{-mtune} as for
11189@option{-mcpu}. If both are specified, the code generated will use the
11190architecture, registers, and mnemonics set by @option{-mcpu}, but the
11191scheduling parameters set by @option{-mtune}.
11192
11193@item -mswdiv
11194@itemx -mno-swdiv
11195@opindex mswdiv
11196@opindex mno-swdiv
11197Generate code to compute division as reciprocal estimate and iterative
11198refinement, creating opportunities for increased throughput. This
11199feature requires: optional PowerPC Graphics instruction set for single
11200precision and FRE instruction for double precision, assuming divides
11201cannot generate user-visible traps, and the domain values not include
11202Infinities, denormals or zero denominator.
11203
11204@item -maltivec
11205@itemx -mno-altivec
11206@opindex maltivec
11207@opindex mno-altivec
11208Generate code that uses (does not use) AltiVec instructions, and also
11209enable the use of built-in functions that allow more direct access to
11210the AltiVec instruction set. You may also need to set
11211@option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
11212enhancements.
11213
11214@item -mvrsave
11215@item -mno-vrsave
11216@opindex mvrsave
11217@opindex mno-vrsave
11218Generate VRSAVE instructions when generating AltiVec code.
11219
11220@item -msecure-plt
11221@opindex msecure-plt
11222Generate code that allows ld and ld.so to build executables and shared
11223libraries with non-exec .plt and .got sections. This is a PowerPC
1122432-bit SYSV ABI option.
11225
11226@item -mbss-plt
11227@opindex mbss-plt
11228Generate code that uses a BSS .plt section that ld.so fills in, and
11229requires .plt and .got sections that are both writable and executable.
11230This is a PowerPC 32-bit SYSV ABI option.
11231
11232@item -misel
11233@itemx -mno-isel
11234@opindex misel
11235@opindex mno-isel
11236This switch enables or disables the generation of ISEL instructions.
11237
11238@item -misel=@var{yes/no}
11239This switch has been deprecated. Use @option{-misel} and
11240@option{-mno-isel} instead.
11241
11242@item -mspe
11243@itemx -mno-spe
11244@opindex mspe
11245@opindex mno-spe
11246This switch enables or disables the generation of SPE simd
11247instructions.
11248
11249@item -mspe=@var{yes/no}
11250This option has been deprecated. Use @option{-mspe} and
11251@option{-mno-spe} instead.
11252
11253@item -mfloat-gprs=@var{yes/single/double/no}
11254@itemx -mfloat-gprs
11255@opindex mfloat-gprs
11256This switch enables or disables the generation of floating point
11257operations on the general purpose registers for architectures that
11258support it.
11259
11260The argument @var{yes} or @var{single} enables the use of
11261single-precision floating point operations.
11262
11263The argument @var{double} enables the use of single and
11264double-precision floating point operations.
11265
11266The argument @var{no} disables floating point operations on the
11267general purpose registers.
11268
11269This option is currently only available on the MPC854x.
11270
11271@item -m32
11272@itemx -m64
11273@opindex m32
11274@opindex m64
11275Generate code for 32-bit or 64-bit environments of Darwin and SVR4
11276targets (including GNU/Linux). The 32-bit environment sets int, long
11277and pointer to 32 bits and generates code that runs on any PowerPC
11278variant. The 64-bit environment sets int to 32 bits and long and
11279pointer to 64 bits, and generates code for PowerPC64, as for
11280@option{-mpowerpc64}.
11281
11282@item -mfull-toc
11283@itemx -mno-fp-in-toc
11284@itemx -mno-sum-in-toc
11285@itemx -mminimal-toc
11286@opindex mfull-toc
11287@opindex mno-fp-in-toc
11288@opindex mno-sum-in-toc
11289@opindex mminimal-toc
11290Modify generation of the TOC (Table Of Contents), which is created for
11291every executable file. The @option{-mfull-toc} option is selected by
11292default. In that case, GCC will allocate at least one TOC entry for
11293each unique non-automatic variable reference in your program. GCC
11294will also place floating-point constants in the TOC@. However, only
1129516,384 entries are available in the TOC@.
11296
11297If you receive a linker error message that saying you have overflowed
11298the available TOC space, you can reduce the amount of TOC space used
11299with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
11300@option{-mno-fp-in-toc} prevents GCC from putting floating-point
11301constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
11302generate code to calculate the sum of an address and a constant at
11303run-time instead of putting that sum into the TOC@. You may specify one
11304or both of these options. Each causes GCC to produce very slightly
11305slower and larger code at the expense of conserving TOC space.
11306
11307If you still run out of space in the TOC even when you specify both of
11308these options, specify @option{-mminimal-toc} instead. This option causes
11309GCC to make only one TOC entry for every file. When you specify this
11310option, GCC will produce code that is slower and larger but which
11311uses extremely little TOC space. You may wish to use this option
11312only on files that contain less frequently executed code.
11313
11314@item -maix64
11315@itemx -maix32
11316@opindex maix64
11317@opindex maix32
11318Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
11319@code{long} type, and the infrastructure needed to support them.
11320Specifying @option{-maix64} implies @option{-mpowerpc64} and
11321@option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
11322implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
11323
11324@item -mxl-compat
11325@itemx -mno-xl-compat
11326@opindex mxl-compat
11327@opindex mno-xl-compat
11328Produce code that conforms more closely to IBM XL compiler semantics
11329when using AIX-compatible ABI. Pass floating-point arguments to
11330prototyped functions beyond the register save area (RSA) on the stack
11331in addition to argument FPRs. Do not assume that most significant
11332double in 128-bit long double value is properly rounded when comparing
11333values and converting to double. Use XL symbol names for long double
11334support routines.
11335
11336The AIX calling convention was extended but not initially documented to
11337handle an obscure K&R C case of calling a function that takes the
11338address of its arguments with fewer arguments than declared. IBM XL
11339compilers access floating point arguments which do not fit in the
11340RSA from the stack when a subroutine is compiled without
11341optimization. Because always storing floating-point arguments on the
11342stack is inefficient and rarely needed, this option is not enabled by
11343default and only is necessary when calling subroutines compiled by IBM
11344XL compilers without optimization.
11345
11346@item -mpe
11347@opindex mpe
11348Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
11349application written to use message passing with special startup code to
11350enable the application to run. The system must have PE installed in the
11351standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
11352must be overridden with the @option{-specs=} option to specify the
11353appropriate directory location. The Parallel Environment does not
11354support threads, so the @option{-mpe} option and the @option{-pthread}
11355option are incompatible.
11356
11357@item -malign-natural
11358@itemx -malign-power
11359@opindex malign-natural
11360@opindex malign-power
11361On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
11362@option{-malign-natural} overrides the ABI-defined alignment of larger
11363types, such as floating-point doubles, on their natural size-based boundary.
11364The option @option{-malign-power} instructs GCC to follow the ABI-specified
11365alignment rules. GCC defaults to the standard alignment defined in the ABI@.
11366
11367On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
11368is not supported.
11369
11370@item -msoft-float
11371@itemx -mhard-float
11372@opindex msoft-float
11373@opindex mhard-float
11374Generate code that does not use (uses) the floating-point register set.
11375Software floating point emulation is provided if you use the
11376@option{-msoft-float} option, and pass the option to GCC when linking.
11377
11378@item -mmultiple
11379@itemx -mno-multiple
11380@opindex mmultiple
11381@opindex mno-multiple
11382Generate code that uses (does not use) the load multiple word
11383instructions and the store multiple word instructions. These
11384instructions are generated by default on POWER systems, and not
11385generated on PowerPC systems. Do not use @option{-mmultiple} on little
11386endian PowerPC systems, since those instructions do not work when the
11387processor is in little endian mode. The exceptions are PPC740 and
11388PPC750 which permit the instructions usage in little endian mode.
11389
11390@item -mstring
11391@itemx -mno-string
11392@opindex mstring
11393@opindex mno-string
11394Generate code that uses (does not use) the load string instructions
11395and the store string word instructions to save multiple registers and
11396do small block moves. These instructions are generated by default on
11397POWER systems, and not generated on PowerPC systems. Do not use
11398@option{-mstring} on little endian PowerPC systems, since those
11399instructions do not work when the processor is in little endian mode.
11400The exceptions are PPC740 and PPC750 which permit the instructions
11401usage in little endian mode.
11402
11403@item -mupdate
11404@itemx -mno-update
11405@opindex mupdate
11406@opindex mno-update
11407Generate code that uses (does not use) the load or store instructions
11408that update the base register to the address of the calculated memory
11409location. These instructions are generated by default. If you use
11410@option{-mno-update}, there is a small window between the time that the
11411stack pointer is updated and the address of the previous frame is
11412stored, which means code that walks the stack frame across interrupts or
11413signals may get corrupted data.
11414
11415@item -mfused-madd
11416@itemx -mno-fused-madd
11417@opindex mfused-madd
11418@opindex mno-fused-madd
11419Generate code that uses (does not use) the floating point multiply and
11420accumulate instructions. These instructions are generated by default if
11421hardware floating is used.
11422
11423@item -mmulhw
11424@itemx -mno-mulhw
11425@opindex mmulhw
11426@opindex mno-mulhw
11427Generate code that uses (does not use) the half-word multiply and
11428multiply-accumulate instructions on the IBM 405 and 440 processors.
11429These instructions are generated by default when targetting those
11430processors.
11431
11432@item -mdlmzb
11433@itemx -mno-dlmzb
11434@opindex mdlmzb
11435@opindex mno-dlmzb
11436Generate code that uses (does not use) the string-search @samp{dlmzb}
11437instruction on the IBM 405 and 440 processors. This instruction is
11438generated by default when targetting those processors.
11439
11440@item -mno-bit-align
11441@itemx -mbit-align
11442@opindex mno-bit-align
11443@opindex mbit-align
11444On System V.4 and embedded PowerPC systems do not (do) force structures
11445and unions that contain bit-fields to be aligned to the base type of the
11446bit-field.
11447
11448For example, by default a structure containing nothing but 8
11449@code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
11450boundary and have a size of 4 bytes. By using @option{-mno-bit-align},
11451the structure would be aligned to a 1 byte boundary and be one byte in
11452size.
11453
11454@item -mno-strict-align
11455@itemx -mstrict-align
11456@opindex mno-strict-align
11457@opindex mstrict-align
11458On System V.4 and embedded PowerPC systems do not (do) assume that
11459unaligned memory references will be handled by the system.
11460
11461@item -mrelocatable
11462@itemx -mno-relocatable
11463@opindex mrelocatable
11464@opindex mno-relocatable
11465On embedded PowerPC systems generate code that allows (does not allow)
11466the program to be relocated to a different address at runtime. If you
11467use @option{-mrelocatable} on any module, all objects linked together must
11468be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
11469
11470@item -mrelocatable-lib
11471@itemx -mno-relocatable-lib
11472@opindex mrelocatable-lib
11473@opindex mno-relocatable-lib
11474On embedded PowerPC systems generate code that allows (does not allow)
11475the program to be relocated to a different address at runtime. Modules
11476compiled with @option{-mrelocatable-lib} can be linked with either modules
11477compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
11478with modules compiled with the @option{-mrelocatable} options.
11479
11480@item -mno-toc
11481@itemx -mtoc
11482@opindex mno-toc
11483@opindex mtoc
11484On System V.4 and embedded PowerPC systems do not (do) assume that
11485register 2 contains a pointer to a global area pointing to the addresses
11486used in the program.
11487
11488@item -mlittle
11489@itemx -mlittle-endian
11490@opindex mlittle
11491@opindex mlittle-endian
11492On System V.4 and embedded PowerPC systems compile code for the
11493processor in little endian mode. The @option{-mlittle-endian} option is
11494the same as @option{-mlittle}.
11495
11496@item -mbig
11497@itemx -mbig-endian
11498@opindex mbig
11499@opindex mbig-endian
11500On System V.4 and embedded PowerPC systems compile code for the
11501processor in big endian mode. The @option{-mbig-endian} option is
11502the same as @option{-mbig}.
11503
11504@item -mdynamic-no-pic
11505@opindex mdynamic-no-pic
11506On Darwin and Mac OS X systems, compile code so that it is not
11507relocatable, but that its external references are relocatable. The
11508resulting code is suitable for applications, but not shared
11509libraries.
11510
11511@item -mprioritize-restricted-insns=@var{priority}
11512@opindex mprioritize-restricted-insns
11513This option controls the priority that is assigned to
11514dispatch-slot restricted instructions during the second scheduling
11515pass. The argument @var{priority} takes the value @var{0/1/2} to assign
11516@var{no/highest/second-highest} priority to dispatch slot restricted
11517instructions.
11518
11519@item -msched-costly-dep=@var{dependence_type}
11520@opindex msched-costly-dep
11521This option controls which dependences are considered costly
11522by the target during instruction scheduling. The argument
11523@var{dependence_type} takes one of the following values:
11524@var{no}: no dependence is costly,
11525@var{all}: all dependences are costly,
11526@var{true_store_to_load}: a true dependence from store to load is costly,
11527@var{store_to_load}: any dependence from store to load is costly,
11528@var{number}: any dependence which latency >= @var{number} is costly.
11529
11530@item -minsert-sched-nops=@var{scheme}
11531@opindex minsert-sched-nops
11532This option controls which nop insertion scheme will be used during
11533the second scheduling pass. The argument @var{scheme} takes one of the
11534following values:
11535@var{no}: Don't insert nops.
11536@var{pad}: Pad with nops any dispatch group which has vacant issue slots,
11537according to the scheduler's grouping.
11538@var{regroup_exact}: Insert nops to force costly dependent insns into
11539separate groups. Insert exactly as many nops as needed to force an insn
11540to a new group, according to the estimated processor grouping.
11541@var{number}: Insert nops to force costly dependent insns into
11542separate groups. Insert @var{number} nops to force an insn to a new group.
11543
11544@item -mcall-sysv
11545@opindex mcall-sysv
11546On System V.4 and embedded PowerPC systems compile code using calling
11547conventions that adheres to the March 1995 draft of the System V
11548Application Binary Interface, PowerPC processor supplement. This is the
11549default unless you configured GCC using @samp{powerpc-*-eabiaix}.
11550
11551@item -mcall-sysv-eabi
11552@opindex mcall-sysv-eabi
11553Specify both @option{-mcall-sysv} and @option{-meabi} options.
11554
11555@item -mcall-sysv-noeabi
11556@opindex mcall-sysv-noeabi
11557Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
11558
11559@item -mcall-solaris
11560@opindex mcall-solaris
11561On System V.4 and embedded PowerPC systems compile code for the Solaris
11562operating system.
11563
11564@item -mcall-linux
11565@opindex mcall-linux
11566On System V.4 and embedded PowerPC systems compile code for the
11567Linux-based GNU system.
11568
11569@item -mcall-gnu
11570@opindex mcall-gnu
11571On System V.4 and embedded PowerPC systems compile code for the
11572Hurd-based GNU system.
11573
11574@item -mcall-netbsd
11575@opindex mcall-netbsd
11576On System V.4 and embedded PowerPC systems compile code for the
11577NetBSD operating system.
11578
11579@item -maix-struct-return
11580@opindex maix-struct-return
11581Return all structures in memory (as specified by the AIX ABI)@.
11582
11583@item -msvr4-struct-return
11584@opindex msvr4-struct-return
11585Return structures smaller than 8 bytes in registers (as specified by the
11586SVR4 ABI)@.
11587
11588@item -mabi=@var{abi-type}
11589@opindex mabi
11590Extend the current ABI with a particular extension, or remove such extension.
11591Valid values are @var{altivec}, @var{no-altivec}, @var{spe},
11592@var{no-spe}, @var{ibmlongdouble}, @var{ieeelongdouble}@.
11593
11594@item -mabi=spe
11595@opindex mabi=spe
11596Extend the current ABI with SPE ABI extensions. This does not change
11597the default ABI, instead it adds the SPE ABI extensions to the current
11598ABI@.
11599
11600@item -mabi=no-spe
11601@opindex mabi=no-spe
11602Disable Booke SPE ABI extensions for the current ABI@.
11603
11604@item -mabi=ibmlongdouble
11605@opindex mabi=ibmlongdouble
11606Change the current ABI to use IBM extended precision long double.
11607This is a PowerPC 32-bit SYSV ABI option.
11608
11609@item -mabi=ieeelongdouble
11610@opindex mabi=ieeelongdouble
11611Change the current ABI to use IEEE extended precision long double.
11612This is a PowerPC 32-bit Linux ABI option.
11613
11614@item -mprototype
11615@itemx -mno-prototype
11616@opindex mprototype
11617@opindex mno-prototype
11618On System V.4 and embedded PowerPC systems assume that all calls to
11619variable argument functions are properly prototyped. Otherwise, the
11620compiler must insert an instruction before every non prototyped call to
11621set or clear bit 6 of the condition code register (@var{CR}) to
11622indicate whether floating point values were passed in the floating point
11623registers in case the function takes a variable arguments. With
11624@option{-mprototype}, only calls to prototyped variable argument functions
11625will set or clear the bit.
11626
11627@item -msim
11628@opindex msim
11629On embedded PowerPC systems, assume that the startup module is called
11630@file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
11631@file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
11632configurations.
11633
11634@item -mmvme
11635@opindex mmvme
11636On embedded PowerPC systems, assume that the startup module is called
11637@file{crt0.o} and the standard C libraries are @file{libmvme.a} and
11638@file{libc.a}.
11639
11640@item -mads
11641@opindex mads
11642On embedded PowerPC systems, assume that the startup module is called
11643@file{crt0.o} and the standard C libraries are @file{libads.a} and
11644@file{libc.a}.
11645
11646@item -myellowknife
11647@opindex myellowknife
11648On embedded PowerPC systems, assume that the startup module is called
11649@file{crt0.o} and the standard C libraries are @file{libyk.a} and
11650@file{libc.a}.
11651
11652@item -mvxworks
11653@opindex mvxworks
11654On System V.4 and embedded PowerPC systems, specify that you are
11655compiling for a VxWorks system.
11656
11657@item -mwindiss
11658@opindex mwindiss
11659Specify that you are compiling for the WindISS simulation environment.
11660
11661@item -memb
11662@opindex memb
11663On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
11664header to indicate that @samp{eabi} extended relocations are used.
11665
11666@item -meabi
11667@itemx -mno-eabi
11668@opindex meabi
11669@opindex mno-eabi
11670On System V.4 and embedded PowerPC systems do (do not) adhere to the
11671Embedded Applications Binary Interface (eabi) which is a set of
11672modifications to the System V.4 specifications. Selecting @option{-meabi}
11673means that the stack is aligned to an 8 byte boundary, a function
11674@code{__eabi} is called to from @code{main} to set up the eabi
11675environment, and the @option{-msdata} option can use both @code{r2} and
11676@code{r13} to point to two separate small data areas. Selecting
11677@option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
11678do not call an initialization function from @code{main}, and the
11679@option{-msdata} option will only use @code{r13} to point to a single
11680small data area. The @option{-meabi} option is on by default if you
11681configured GCC using one of the @samp{powerpc*-*-eabi*} options.
11682
11683@item -msdata=eabi
11684@opindex msdata=eabi
11685On System V.4 and embedded PowerPC systems, put small initialized
11686@code{const} global and static data in the @samp{.sdata2} section, which
11687is pointed to by register @code{r2}. Put small initialized
11688non-@code{const} global and static data in the @samp{.sdata} section,
11689which is pointed to by register @code{r13}. Put small uninitialized
11690global and static data in the @samp{.sbss} section, which is adjacent to
11691the @samp{.sdata} section. The @option{-msdata=eabi} option is
11692incompatible with the @option{-mrelocatable} option. The
11693@option{-msdata=eabi} option also sets the @option{-memb} option.
11694
11695@item -msdata=sysv
11696@opindex msdata=sysv
11697On System V.4 and embedded PowerPC systems, put small global and static
11698data in the @samp{.sdata} section, which is pointed to by register
11699@code{r13}. Put small uninitialized global and static data in the
11700@samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
11701The @option{-msdata=sysv} option is incompatible with the
11702@option{-mrelocatable} option.
11703
11704@item -msdata=default
11705@itemx -msdata
11706@opindex msdata=default
11707@opindex msdata
11708On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
11709compile code the same as @option{-msdata=eabi}, otherwise compile code the
11710same as @option{-msdata=sysv}.
11711
11712@item -msdata-data
11713@opindex msdata-data
11714On System V.4 and embedded PowerPC systems, put small global
11715data in the @samp{.sdata} section. Put small uninitialized global
11716data in the @samp{.sbss} section. Do not use register @code{r13}
11717to address small data however. This is the default behavior unless
11718other @option{-msdata} options are used.
11719
11720@item -msdata=none
11721@itemx -mno-sdata
11722@opindex msdata=none
11723@opindex mno-sdata
11724On embedded PowerPC systems, put all initialized global and static data
11725in the @samp{.data} section, and all uninitialized data in the
11726@samp{.bss} section.
11727
11728@item -G @var{num}
11729@opindex G
11730@cindex smaller data references (PowerPC)
11731@cindex .sdata/.sdata2 references (PowerPC)
11732On embedded PowerPC systems, put global and static items less than or
11733equal to @var{num} bytes into the small data or bss sections instead of
11734the normal data or bss section. By default, @var{num} is 8. The
11735@option{-G @var{num}} switch is also passed to the linker.
11736All modules should be compiled with the same @option{-G @var{num}} value.
11737
11738@item -mregnames
11739@itemx -mno-regnames
11740@opindex mregnames
11741@opindex mno-regnames
11742On System V.4 and embedded PowerPC systems do (do not) emit register
11743names in the assembly language output using symbolic forms.
11744
11745@item -mlongcall
11746@itemx -mno-longcall
11747@opindex mlongcall
11748@opindex mno-longcall
11749By default assume that all calls are far away so that a longer more
11750expensive calling sequence is required. This is required for calls
11751further than 32 megabytes (33,554,432 bytes) from the current location.
11752A short call will be generated if the compiler knows
11753the call cannot be that far away. This setting can be overridden by
11754the @code{shortcall} function attribute, or by @code{#pragma
11755longcall(0)}.
11756
11757Some linkers are capable of detecting out-of-range calls and generating
11758glue code on the fly. On these systems, long calls are unnecessary and
11759generate slower code. As of this writing, the AIX linker can do this,
11760as can the GNU linker for PowerPC/64. It is planned to add this feature
11761to the GNU linker for 32-bit PowerPC systems as well.
11762
11763On Darwin/PPC systems, @code{#pragma longcall} will generate ``jbsr
11764callee, L42'', plus a ``branch island'' (glue code). The two target
11765addresses represent the callee and the ``branch island''. The
11766Darwin/PPC linker will prefer the first address and generate a ``bl
11767callee'' if the PPC ``bl'' instruction will reach the callee directly;
11768otherwise, the linker will generate ``bl L42'' to call the ``branch
11769island''. The ``branch island'' is appended to the body of the
11770calling function; it computes the full 32-bit address of the callee
11771and jumps to it.
11772
11773On Mach-O (Darwin) systems, this option directs the compiler emit to
11774the glue for every direct call, and the Darwin linker decides whether
11775to use or discard it.
11776
11777In the future, we may cause GCC to ignore all longcall specifications
11778when the linker is known to generate glue.
11779
11780@item -pthread
11781@opindex pthread
11782Adds support for multithreading with the @dfn{pthreads} library.
11783This option sets flags for both the preprocessor and linker.
11784
11785@end table
11786
11787@node S/390 and zSeries Options
11788@subsection S/390 and zSeries Options
11789@cindex S/390 and zSeries Options
11790
11791These are the @samp{-m} options defined for the S/390 and zSeries architecture.
11792
11793@table @gcctabopt
11794@item -mhard-float
11795@itemx -msoft-float
11796@opindex mhard-float
11797@opindex msoft-float
11798Use (do not use) the hardware floating-point instructions and registers
11799for floating-point operations. When @option{-msoft-float} is specified,
11800functions in @file{libgcc.a} will be used to perform floating-point
11801operations. When @option{-mhard-float} is specified, the compiler
11802generates IEEE floating-point instructions. This is the default.
11803
11804@item -mlong-double-64
11805@itemx -mlong-double-128
11806@opindex mlong-double-64
11807@opindex mlong-double-128
11808These switches control the size of @code{long double} type. A size
11809of 64bit makes the @code{long double} type equivalent to the @code{double}
11810type. This is the default.
11811
11812@item -mbackchain
11813@itemx -mno-backchain
11814@opindex mbackchain
11815@opindex mno-backchain
11816Store (do not store) the address of the caller's frame as backchain pointer
11817into the callee's stack frame.
11818A backchain may be needed to allow debugging using tools that do not understand
11819DWARF-2 call frame information.
11820When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
11821at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
11822the backchain is placed into the topmost word of the 96/160 byte register
11823save area.
11824
11825In general, code compiled with @option{-mbackchain} is call-compatible with
11826code compiled with @option{-mmo-backchain}; however, use of the backchain
11827for debugging purposes usually requires that the whole binary is built with
11828@option{-mbackchain}. Note that the combination of @option{-mbackchain},
11829@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
11830to build a linux kernel use @option{-msoft-float}.
11831
11832The default is to not maintain the backchain.
11833
11834@item -mpacked-stack
11835@item -mno-packed-stack
11836@opindex mpacked-stack
11837@opindex mno-packed-stack
11838Use (do not use) the packed stack layout. When @option{-mno-packed-stack} is
11839specified, the compiler uses the all fields of the 96/160 byte register save
11840area only for their default purpose; unused fields still take up stack space.
11841When @option{-mpacked-stack} is specified, register save slots are densely
11842packed at the top of the register save area; unused space is reused for other
11843purposes, allowing for more efficient use of the available stack space.
11844However, when @option{-mbackchain} is also in effect, the topmost word of
11845the save area is always used to store the backchain, and the return address
11846register is always saved two words below the backchain.
11847
11848As long as the stack frame backchain is not used, code generated with
11849@option{-mpacked-stack} is call-compatible with code generated with
11850@option{-mno-packed-stack}. Note that some non-FSF releases of GCC 2.95 for
11851S/390 or zSeries generated code that uses the stack frame backchain at run
11852time, not just for debugging purposes. Such code is not call-compatible
11853with code compiled with @option{-mpacked-stack}. Also, note that the
11854combination of @option{-mbackchain},
11855@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
11856to build a linux kernel use @option{-msoft-float}.
11857
11858The default is to not use the packed stack layout.
11859
11860@item -msmall-exec
11861@itemx -mno-small-exec
11862@opindex msmall-exec
11863@opindex mno-small-exec
11864Generate (or do not generate) code using the @code{bras} instruction
11865to do subroutine calls.
11866This only works reliably if the total executable size does not
11867exceed 64k. The default is to use the @code{basr} instruction instead,
11868which does not have this limitation.
11869
11870@item -m64
11871@itemx -m31
11872@opindex m64
11873@opindex m31
11874When @option{-m31} is specified, generate code compliant to the
11875GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate
11876code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in
11877particular to generate 64-bit instructions. For the @samp{s390}
11878targets, the default is @option{-m31}, while the @samp{s390x}
11879targets default to @option{-m64}.
11880
11881@item -mzarch
11882@itemx -mesa
11883@opindex mzarch
11884@opindex mesa
11885When @option{-mzarch} is specified, generate code using the
11886instructions available on z/Architecture.
11887When @option{-mesa} is specified, generate code using the
11888instructions available on ESA/390. Note that @option{-mesa} is
11889not possible with @option{-m64}.
11890When generating code compliant to the GNU/Linux for S/390 ABI,
11891the default is @option{-mesa}. When generating code compliant
11892to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
11893
11894@item -mmvcle
11895@itemx -mno-mvcle
11896@opindex mmvcle
11897@opindex mno-mvcle
11898Generate (or do not generate) code using the @code{mvcle} instruction
11899to perform block moves. When @option{-mno-mvcle} is specified,
11900use a @code{mvc} loop instead. This is the default unless optimizing for
11901size.
11902
11903@item -mdebug
11904@itemx -mno-debug
11905@opindex mdebug
11906@opindex mno-debug
11907Print (or do not print) additional debug information when compiling.
11908The default is to not print debug information.
11909
11910@item -march=@var{cpu-type}
11911@opindex march
11912Generate code that will run on @var{cpu-type}, which is the name of a system
11913representing a certain processor type. Possible values for
11914@var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, and @samp{z990}.
11915When generating code using the instructions available on z/Architecture,
11916the default is @option{-march=z900}. Otherwise, the default is
11917@option{-march=g5}.
11918
11919@item -mtune=@var{cpu-type}
11920@opindex mtune
11921Tune to @var{cpu-type} everything applicable about the generated code,
11922except for the ABI and the set of available instructions.
11923The list of @var{cpu-type} values is the same as for @option{-march}.
11924The default is the value used for @option{-march}.
11925
11926@item -mtpf-trace
11927@itemx -mno-tpf-trace
11928@opindex mtpf-trace
11929@opindex mno-tpf-trace
11930Generate code that adds (does not add) in TPF OS specific branches to trace
11931routines in the operating system. This option is off by default, even
11932when compiling for the TPF OS@.
11933
11934@item -mfused-madd
11935@itemx -mno-fused-madd
11936@opindex mfused-madd
11937@opindex mno-fused-madd
11938Generate code that uses (does not use) the floating point multiply and
11939accumulate instructions. These instructions are generated by default if
11940hardware floating point is used.
11941
11942@item -mwarn-framesize=@var{framesize}
11943@opindex mwarn-framesize
11944Emit a warning if the current function exceeds the given frame size. Because
11945this is a compile time check it doesn't need to be a real problem when the program
11946runs. It is intended to identify functions which most probably cause
11947a stack overflow. It is useful to be used in an environment with limited stack
11948size e.g.@: the linux kernel.
11949
11950@item -mwarn-dynamicstack
11951@opindex mwarn-dynamicstack
11952Emit a warning if the function calls alloca or uses dynamically
11953sized arrays. This is generally a bad idea with a limited stack size.
11954
11955@item -mstack-guard=@var{stack-guard}
11956@item -mstack-size=@var{stack-size}
11957@opindex mstack-guard
11958@opindex mstack-size
11959These arguments always have to be used in conjunction. If they are present the s390
11960back end emits additional instructions in the function prologue which trigger a trap
11961if the stack size is @var{stack-guard} bytes above the @var{stack-size}
11962(remember that the stack on s390 grows downward). These options are intended to
11963be used to help debugging stack overflow problems. The additionally emitted code
11964causes only little overhead and hence can also be used in production like systems
11965without greater performance degradation. The given values have to be exact
11966powers of 2 and @var{stack-size} has to be greater than @var{stack-guard} without
11967exceeding 64k.
11968In order to be efficient the extra code makes the assumption that the stack starts
11969at an address aligned to the value given by @var{stack-size}.
11970@end table
11971
11972@node Score Options
11973@subsection Score Options
11974@cindex Score Options
11975
11976These options are defined for Score implementations:
11977
11978@table @gcctabopt
11979@item -meb
11980@opindex meb
11981Compile code for big endian mode. This is the default.
11982
11983@item -mel
11984@opindex mel
11985Compile code for little endian mode.
11986
11987@item -mnhwloop
11988@opindex mnhwloop
11989Disable generate bcnz instruction.
11990
11991@item -muls
11992@opindex muls
11993Enable generate unaligned load and store instruction.
11994
11995@item -mmac
11996@opindex mmac
11997Enable the use of multiply-accumulate instructions. Disabled by default.
11998
11999@item -mscore5
12000@opindex mscore5
12001Specify the SCORE5 as the target architecture.
12002
12003@item -mscore5u
12004@opindex mscore5u
12005Specify the SCORE5U of the target architecture.
12006
12007@item -mscore7
12008@opindex mscore7
12009Specify the SCORE7 as the target architecture. This is the default.
12010
12011@item -mscore7d
12012@opindex mscore7d
12013Specify the SCORE7D as the target architecture.
12014@end table
12015
12016@node SH Options
12017@subsection SH Options
12018
12019These @samp{-m} options are defined for the SH implementations:
12020
12021@table @gcctabopt
12022@item -m1
12023@opindex m1
12024Generate code for the SH1.
12025
12026@item -m2
12027@opindex m2
12028Generate code for the SH2.
12029
12030@item -m2e
12031Generate code for the SH2e.
12032
12033@item -m3
12034@opindex m3
12035Generate code for the SH3.
12036
12037@item -m3e
12038@opindex m3e
12039Generate code for the SH3e.
12040
12041@item -m4-nofpu
12042@opindex m4-nofpu
12043Generate code for the SH4 without a floating-point unit.
12044
12045@item -m4-single-only
12046@opindex m4-single-only
12047Generate code for the SH4 with a floating-point unit that only
12048supports single-precision arithmetic.
12049
12050@item -m4-single
12051@opindex m4-single
12052Generate code for the SH4 assuming the floating-point unit is in
12053single-precision mode by default.
12054
12055@item -m4
12056@opindex m4
12057Generate code for the SH4.
12058
12059@item -m4a-nofpu
12060@opindex m4a-nofpu
12061Generate code for the SH4al-dsp, or for a SH4a in such a way that the
12062floating-point unit is not used.
12063
12064@item -m4a-single-only
12065@opindex m4a-single-only
12066Generate code for the SH4a, in such a way that no double-precision
12067floating point operations are used.
12068
12069@item -m4a-single
12070@opindex m4a-single
12071Generate code for the SH4a assuming the floating-point unit is in
12072single-precision mode by default.
12073
12074@item -m4a
12075@opindex m4a
12076Generate code for the SH4a.
12077
12078@item -m4al
12079@opindex m4al
12080Same as @option{-m4a-nofpu}, except that it implicitly passes
12081@option{-dsp} to the assembler. GCC doesn't generate any DSP
12082instructions at the moment.
12083
12084@item -mb
12085@opindex mb
12086Compile code for the processor in big endian mode.
12087
12088@item -ml
12089@opindex ml
12090Compile code for the processor in little endian mode.
12091
12092@item -mdalign
12093@opindex mdalign
12094Align doubles at 64-bit boundaries. Note that this changes the calling
12095conventions, and thus some functions from the standard C library will
12096not work unless you recompile it first with @option{-mdalign}.
12097
12098@item -mrelax
12099@opindex mrelax
12100Shorten some address references at link time, when possible; uses the
12101linker option @option{-relax}.
12102
12103@item -mbigtable
12104@opindex mbigtable
12105Use 32-bit offsets in @code{switch} tables. The default is to use
1210616-bit offsets.
12107
12108@item -mfmovd
12109@opindex mfmovd
12110Enable the use of the instruction @code{fmovd}.
12111
12112@item -mhitachi
12113@opindex mhitachi
12114Comply with the calling conventions defined by Renesas.
12115
12116@item -mrenesas
12117@opindex mhitachi
12118Comply with the calling conventions defined by Renesas.
12119
12120@item -mno-renesas
12121@opindex mhitachi
12122Comply with the calling conventions defined for GCC before the Renesas
12123conventions were available. This option is the default for all
12124targets of the SH toolchain except for @samp{sh-symbianelf}.
12125
12126@item -mnomacsave
12127@opindex mnomacsave
12128Mark the @code{MAC} register as call-clobbered, even if
12129@option{-mhitachi} is given.
12130
12131@item -mieee
12132@opindex mieee
12133Increase IEEE-compliance of floating-point code.
12134At the moment, this is equivalent to @option{-fno-finite-math-only}.
12135When generating 16 bit SH opcodes, getting IEEE-conforming results for
12136comparisons of NANs / infinities incurs extra overhead in every
12137floating point comparison, therefore the default is set to
12138@option{-ffinite-math-only}.
12139
12140@item -misize
12141@opindex misize
12142Dump instruction size and location in the assembly code.
12143
12144@item -mpadstruct
12145@opindex mpadstruct
12146This option is deprecated. It pads structures to multiple of 4 bytes,
12147which is incompatible with the SH ABI@.
12148
12149@item -mspace
12150@opindex mspace
12151Optimize for space instead of speed. Implied by @option{-Os}.
12152
12153@item -mprefergot
12154@opindex mprefergot
12155When generating position-independent code, emit function calls using
12156the Global Offset Table instead of the Procedure Linkage Table.
12157
12158@item -musermode
12159@opindex musermode
12160Generate a library function call to invalidate instruction cache
12161entries, after fixing up a trampoline. This library function call
12162doesn't assume it can write to the whole memory address space. This
12163is the default when the target is @code{sh-*-linux*}.
12164
12165@item -multcost=@var{number}
12166@opindex multcost=@var{number}
12167Set the cost to assume for a multiply insn.
12168
12169@item -mdiv=@var{strategy}
12170@opindex mdiv=@var{strategy}
12171Set the division strategy to use for SHmedia code. @var{strategy} must be
12172one of: call, call2, fp, inv, inv:minlat, inv20u, inv20l, inv:call,
12173inv:call2, inv:fp .
12174"fp" performs the operation in floating point. This has a very high latency,
12175but needs only a few instructions, so it might be a good choice if
12176your code has enough easily exploitable ILP to allow the compiler to
12177schedule the floating point instructions together with other instructions.
12178Division by zero causes a floating point exception.
12179"inv" uses integer operations to calculate the inverse of the divisor,
12180and then multiplies the dividend with the inverse. This strategy allows
12181cse and hoisting of the inverse calculation. Division by zero calculates
12182an unspecified result, but does not trap.
12183"inv:minlat" is a variant of "inv" where if no cse / hoisting opportunities
12184have been found, or if the entire operation has been hoisted to the same
12185place, the last stages of the inverse calculation are intertwined with the
12186final multiply to reduce the overall latency, at the expense of using a few
12187more instructions, and thus offering fewer scheduling opportunities with
12188other code.
12189"call" calls a library function that usually implements the inv:minlat
12190strategy.
12191This gives high code density for m5-*media-nofpu compilations.
12192"call2" uses a different entry point of the same library function, where it
12193assumes that a pointer to a lookup table has already been set up, which
12194exposes the pointer load to cse / code hoisting optimizations.
12195"inv:call", "inv:call2" and "inv:fp" all use the "inv" algorithm for initial
12196code generation, but if the code stays unoptimized, revert to the "call",
12197"call2", or "fp" strategies, respectively. Note that the
12198potentially-trapping side effect of division by zero is carried by a
12199separate instruction, so it is possible that all the integer instructions
12200are hoisted out, but the marker for the side effect stays where it is.
12201A recombination to fp operations or a call is not possible in that case.
12202"inv20u" and "inv20l" are variants of the "inv:minlat" strategy. In the case
12203that the inverse calculation was nor separated from the multiply, they speed
12204up division where the dividend fits into 20 bits (plus sign where applicable),
12205by inserting a test to skip a number of operations in this case; this test
12206slows down the case of larger dividends. inv20u assumes the case of a such
12207a small dividend to be unlikely, and inv20l assumes it to be likely.
12208
12209@item -mdivsi3_libfunc=@var{name}
12210@opindex mdivsi3_libfunc=@var{name}
12211Set the name of the library function used for 32 bit signed division to
12212@var{name}. This only affect the name used in the call and inv:call
12213division strategies, and the compiler will still expect the same
12214sets of input/output/clobbered registers as if this option was not present.
12215
12216@item -madjust-unroll
12217@opindex madjust-unroll
12218Throttle unrolling to avoid thrashing target registers.
12219This option only has an effect if the gcc code base supports the
12220TARGET_ADJUST_UNROLL_MAX target hook.
12221
12222@item -mindexed-addressing
12223@opindex mindexed-addressing
12224Enable the use of the indexed addressing mode for SHmedia32/SHcompact.
12225This is only safe if the hardware and/or OS implement 32 bit wrap-around
12226semantics for the indexed addressing mode. The architecture allows the
12227implementation of processors with 64 bit MMU, which the OS could use to
12228get 32 bit addressing, but since no current hardware implementation supports
12229this or any other way to make the indexed addressing mode safe to use in
12230the 32 bit ABI, the default is -mno-indexed-addressing.
12231
12232@item -mgettrcost=@var{number}
12233@opindex mgettrcost=@var{number}
12234Set the cost assumed for the gettr instruction to @var{number}.
12235The default is 2 if @option{-mpt-fixed} is in effect, 100 otherwise.
12236
12237@item -mpt-fixed
12238@opindex mpt-fixed
12239Assume pt* instructions won't trap. This will generally generate better
12240scheduled code, but is unsafe on current hardware. The current architecture
12241definition says that ptabs and ptrel trap when the target anded with 3 is 3.
12242This has the unintentional effect of making it unsafe to schedule ptabs /
12243ptrel before a branch, or hoist it out of a loop. For example,
12244__do_global_ctors, a part of libgcc that runs constructors at program
12245startup, calls functions in a list which is delimited by -1. With the
12246-mpt-fixed option, the ptabs will be done before testing against -1.
12247That means that all the constructors will be run a bit quicker, but when
12248the loop comes to the end of the list, the program crashes because ptabs
12249loads -1 into a target register. Since this option is unsafe for any
12250hardware implementing the current architecture specification, the default
12251is -mno-pt-fixed. Unless the user specifies a specific cost with
12252@option{-mgettrcost}, -mno-pt-fixed also implies @option{-mgettrcost=100};
12253this deters register allocation using target registers for storing
12254ordinary integers.
12255
12256@item -minvalid-symbols
12257@opindex minvalid-symbols
12258Assume symbols might be invalid. Ordinary function symbols generated by
12259the compiler will always be valid to load with movi/shori/ptabs or
12260movi/shori/ptrel, but with assembler and/or linker tricks it is possible
12261to generate symbols that will cause ptabs / ptrel to trap.
12262This option is only meaningful when @option{-mno-pt-fixed} is in effect.
12263It will then prevent cross-basic-block cse, hoisting and most scheduling
12264of symbol loads. The default is @option{-mno-invalid-symbols}.
12265@end table
12266
12267@node SPARC Options
12268@subsection SPARC Options
12269@cindex SPARC options
12270
12271These @samp{-m} options are supported on the SPARC:
12272
12273@table @gcctabopt
12274@item -mno-app-regs
12275@itemx -mapp-regs
12276@opindex mno-app-regs
12277@opindex mapp-regs
12278Specify @option{-mapp-regs} to generate output using the global registers
122792 through 4, which the SPARC SVR4 ABI reserves for applications. This
12280is the default.
12281
12282To be fully SVR4 ABI compliant at the cost of some performance loss,
12283specify @option{-mno-app-regs}. You should compile libraries and system
12284software with this option.
12285
12286@item -mfpu
12287@itemx -mhard-float
12288@opindex mfpu
12289@opindex mhard-float
12290Generate output containing floating point instructions. This is the
12291default.
12292
12293@item -mno-fpu
12294@itemx -msoft-float
12295@opindex mno-fpu
12296@opindex msoft-float
12297Generate output containing library calls for floating point.
12298@strong{Warning:} the requisite libraries are not available for all SPARC
12299targets. Normally the facilities of the machine's usual C compiler are
12300used, but this cannot be done directly in cross-compilation. You must make
12301your own arrangements to provide suitable library functions for
12302cross-compilation. The embedded targets @samp{sparc-*-aout} and
12303@samp{sparclite-*-*} do provide software floating point support.
12304
12305@option{-msoft-float} changes the calling convention in the output file;
12306therefore, it is only useful if you compile @emph{all} of a program with
12307this option. In particular, you need to compile @file{libgcc.a}, the
12308library that comes with GCC, with @option{-msoft-float} in order for
12309this to work.
12310
12311@item -mhard-quad-float
12312@opindex mhard-quad-float
12313Generate output containing quad-word (long double) floating point
12314instructions.
12315
12316@item -msoft-quad-float
12317@opindex msoft-quad-float
12318Generate output containing library calls for quad-word (long double)
12319floating point instructions. The functions called are those specified
12320in the SPARC ABI@. This is the default.
12321
12322As of this writing, there are no SPARC implementations that have hardware
12323support for the quad-word floating point instructions. They all invoke
12324a trap handler for one of these instructions, and then the trap handler
12325emulates the effect of the instruction. Because of the trap handler overhead,
12326this is much slower than calling the ABI library routines. Thus the
12327@option{-msoft-quad-float} option is the default.
12328
12329@item -mno-unaligned-doubles
12330@itemx -munaligned-doubles
12331@opindex mno-unaligned-doubles
12332@opindex munaligned-doubles
12333Assume that doubles have 8 byte alignment. This is the default.
12334
12335With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
12336alignment only if they are contained in another type, or if they have an
12337absolute address. Otherwise, it assumes they have 4 byte alignment.
12338Specifying this option avoids some rare compatibility problems with code
12339generated by other compilers. It is not the default because it results
12340in a performance loss, especially for floating point code.
12341
12342@item -mno-faster-structs
12343@itemx -mfaster-structs
12344@opindex mno-faster-structs
12345@opindex mfaster-structs
12346With @option{-mfaster-structs}, the compiler assumes that structures
12347should have 8 byte alignment. This enables the use of pairs of
12348@code{ldd} and @code{std} instructions for copies in structure
12349assignment, in place of twice as many @code{ld} and @code{st} pairs.
12350However, the use of this changed alignment directly violates the SPARC
12351ABI@. Thus, it's intended only for use on targets where the developer
12352acknowledges that their resulting code will not be directly in line with
12353the rules of the ABI@.
12354
12355@item -mimpure-text
12356@opindex mimpure-text
12357@option{-mimpure-text}, used in addition to @option{-shared}, tells
12358the compiler to not pass @option{-z text} to the linker when linking a
12359shared object. Using this option, you can link position-dependent
12360code into a shared object.
12361
12362@option{-mimpure-text} suppresses the ``relocations remain against
12363allocatable but non-writable sections'' linker error message.
12364However, the necessary relocations will trigger copy-on-write, and the
12365shared object is not actually shared across processes. Instead of
12366using @option{-mimpure-text}, you should compile all source code with
12367@option{-fpic} or @option{-fPIC}.
12368
12369This option is only available on SunOS and Solaris.
12370
12371@item -mcpu=@var{cpu_type}
12372@opindex mcpu
12373Set the instruction set, register set, and instruction scheduling parameters
12374for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
12375@samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
12376@samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x},
12377@samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc},
12378@samp{ultrasparc3}, and @samp{niagara}.
12379
12380Default instruction scheduling parameters are used for values that select
12381an architecture and not an implementation. These are @samp{v7}, @samp{v8},
12382@samp{sparclite}, @samp{sparclet}, @samp{v9}.
12383
12384Here is a list of each supported architecture and their supported
12385implementations.
12386
12387@smallexample
12388 v7: cypress
12389 v8: supersparc, hypersparc
12390 sparclite: f930, f934, sparclite86x
12391 sparclet: tsc701
12392 v9: ultrasparc, ultrasparc3, niagara
12393@end smallexample
12394
12395By default (unless configured otherwise), GCC generates code for the V7
12396variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler
12397additionally optimizes it for the Cypress CY7C602 chip, as used in the
12398SPARCStation/SPARCServer 3xx series. This is also appropriate for the older
12399SPARCStation 1, 2, IPX etc.
12400
12401With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
12402architecture. The only difference from V7 code is that the compiler emits
12403the integer multiply and integer divide instructions which exist in SPARC-V8
12404but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally
12405optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
124062000 series.
12407
12408With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
12409the SPARC architecture. This adds the integer multiply, integer divide step
12410and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
12411With @option{-mcpu=f930}, the compiler additionally optimizes it for the
12412Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@. With
12413@option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
12414MB86934 chip, which is the more recent SPARClite with FPU@.
12415
12416With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
12417the SPARC architecture. This adds the integer multiply, multiply/accumulate,
12418integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
12419but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally
12420optimizes it for the TEMIC SPARClet chip.
12421
12422With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
12423architecture. This adds 64-bit integer and floating-point move instructions,
124243 additional floating-point condition code registers and conditional move
12425instructions. With @option{-mcpu=ultrasparc}, the compiler additionally
12426optimizes it for the Sun UltraSPARC I/II/IIi chips. With
12427@option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
12428Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips. With
12429@option{-mcpu=niagara}, the compiler additionally optimizes it for
12430Sun UltraSPARC T1 chips.
12431
12432@item -mtune=@var{cpu_type}
12433@opindex mtune
12434Set the instruction scheduling parameters for machine type
12435@var{cpu_type}, but do not set the instruction set or register set that the
12436option @option{-mcpu=@var{cpu_type}} would.
12437
12438The same values for @option{-mcpu=@var{cpu_type}} can be used for
12439@option{-mtune=@var{cpu_type}}, but the only useful values are those
12440that select a particular cpu implementation. Those are @samp{cypress},
12441@samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
12442@samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc},
12443@samp{ultrasparc3}, and @samp{niagara}.
12444
12445@item -mv8plus
12446@itemx -mno-v8plus
12447@opindex mv8plus
12448@opindex mno-v8plus
12449With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@. The
12450difference from the V8 ABI is that the global and out registers are
12451considered 64-bit wide. This is enabled by default on Solaris in 32-bit
12452mode for all SPARC-V9 processors.
12453
12454@item -mvis
12455@itemx -mno-vis
12456@opindex mvis
12457@opindex mno-vis
12458With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
12459Visual Instruction Set extensions. The default is @option{-mno-vis}.
12460@end table
12461
12462These @samp{-m} options are supported in addition to the above
12463on SPARC-V9 processors in 64-bit environments:
12464
12465@table @gcctabopt
12466@item -mlittle-endian
12467@opindex mlittle-endian
12468Generate code for a processor running in little-endian mode. It is only
12469available for a few configurations and most notably not on Solaris and Linux.
12470
12471@item -m32
12472@itemx -m64
12473@opindex m32
12474@opindex m64
12475Generate code for a 32-bit or 64-bit environment.
12476The 32-bit environment sets int, long and pointer to 32 bits.
12477The 64-bit environment sets int to 32 bits and long and pointer
12478to 64 bits.
12479
12480@item -mcmodel=medlow
12481@opindex mcmodel=medlow
12482Generate code for the Medium/Low code model: 64-bit addresses, programs
12483must be linked in the low 32 bits of memory. Programs can be statically
12484or dynamically linked.
12485
12486@item -mcmodel=medmid
12487@opindex mcmodel=medmid
12488Generate code for the Medium/Middle code model: 64-bit addresses, programs
12489must be linked in the low 44 bits of memory, the text and data segments must
12490be less than 2GB in size and the data segment must be located within 2GB of
12491the text segment.
12492
12493@item -mcmodel=medany
12494@opindex mcmodel=medany
12495Generate code for the Medium/Anywhere code model: 64-bit addresses, programs
12496may be linked anywhere in memory, the text and data segments must be less
12497than 2GB in size and the data segment must be located within 2GB of the
12498text segment.
12499
12500@item -mcmodel=embmedany
12501@opindex mcmodel=embmedany
12502Generate code for the Medium/Anywhere code model for embedded systems:
1250364-bit addresses, the text and data segments must be less than 2GB in
12504size, both starting anywhere in memory (determined at link time). The
12505global register %g4 points to the base of the data segment. Programs
12506are statically linked and PIC is not supported.
12507
12508@item -mstack-bias
12509@itemx -mno-stack-bias
12510@opindex mstack-bias
12511@opindex mno-stack-bias
12512With @option{-mstack-bias}, GCC assumes that the stack pointer, and
12513frame pointer if present, are offset by @minus{}2047 which must be added back
12514when making stack frame references. This is the default in 64-bit mode.
12515Otherwise, assume no such offset is present.
12516@end table
12517
12518These switches are supported in addition to the above on Solaris:
12519
12520@table @gcctabopt
12521@item -threads
12522@opindex threads
12523Add support for multithreading using the Solaris threads library. This
12524option sets flags for both the preprocessor and linker. This option does
12525not affect the thread safety of object code produced by the compiler or
12526that of libraries supplied with it.
12527
12528@item -pthreads
12529@opindex pthreads
12530Add support for multithreading using the POSIX threads library. This
12531option sets flags for both the preprocessor and linker. This option does
12532not affect the thread safety of object code produced by the compiler or
12533that of libraries supplied with it.
12534
12535@item -pthread
12536@opindex pthread
12537This is a synonym for @option{-pthreads}.
12538@end table
12539
12540@node System V Options
12541@subsection Options for System V
12542
12543These additional options are available on System V Release 4 for
12544compatibility with other compilers on those systems:
12545
12546@table @gcctabopt
12547@item -G
12548@opindex G
12549Create a shared object.
12550It is recommended that @option{-symbolic} or @option{-shared} be used instead.
12551
12552@item -Qy
12553@opindex Qy
12554Identify the versions of each tool used by the compiler, in a
12555@code{.ident} assembler directive in the output.
12556
12557@item -Qn
12558@opindex Qn
12559Refrain from adding @code{.ident} directives to the output file (this is
12560the default).
12561
12562@item -YP,@var{dirs}
12563@opindex YP
12564Search the directories @var{dirs}, and no others, for libraries
12565specified with @option{-l}.
12566
12567@item -Ym,@var{dir}
12568@opindex Ym
12569Look in the directory @var{dir} to find the M4 preprocessor.
12570The assembler uses this option.
12571@c This is supposed to go with a -Yd for predefined M4 macro files, but
12572@c the generic assembler that comes with Solaris takes just -Ym.
12573@end table
12574
12575@node TMS320C3x/C4x Options
12576@subsection TMS320C3x/C4x Options
12577@cindex TMS320C3x/C4x Options
12578
12579These @samp{-m} options are defined for TMS320C3x/C4x implementations:
12580
12581@table @gcctabopt
12582
12583@item -mcpu=@var{cpu_type}
12584@opindex mcpu
12585Set the instruction set, register set, and instruction scheduling
12586parameters for machine type @var{cpu_type}. Supported values for
12587@var{cpu_type} are @samp{c30}, @samp{c31}, @samp{c32}, @samp{c40}, and
12588@samp{c44}. The default is @samp{c40} to generate code for the
12589TMS320C40.
12590
12591@item -mbig-memory
12592@itemx -mbig
12593@itemx -msmall-memory
12594@itemx -msmall
12595@opindex mbig-memory
12596@opindex mbig
12597@opindex msmall-memory
12598@opindex msmall
12599Generates code for the big or small memory model. The small memory
12600model assumed that all data fits into one 64K word page. At run-time
12601the data page (DP) register must be set to point to the 64K page
12602containing the .bss and .data program sections. The big memory model is
12603the default and requires reloading of the DP register for every direct
12604memory access.
12605
12606@item -mbk
12607@itemx -mno-bk
12608@opindex mbk
12609@opindex mno-bk
12610Allow (disallow) allocation of general integer operands into the block
12611count register BK@.
12612
12613@item -mdb
12614@itemx -mno-db
12615@opindex mdb
12616@opindex mno-db
12617Enable (disable) generation of code using decrement and branch,
12618DBcond(D), instructions. This is enabled by default for the C4x. To be
12619on the safe side, this is disabled for the C3x, since the maximum
12620iteration count on the C3x is @math{2^{23} + 1} (but who iterates loops more than
12621@math{2^{23}} times on the C3x?). Note that GCC will try to reverse a loop so
12622that it can utilize the decrement and branch instruction, but will give
12623up if there is more than one memory reference in the loop. Thus a loop
12624where the loop counter is decremented can generate slightly more
12625efficient code, in cases where the RPTB instruction cannot be utilized.
12626
12627@item -mdp-isr-reload
12628@itemx -mparanoid
12629@opindex mdp-isr-reload
12630@opindex mparanoid
12631Force the DP register to be saved on entry to an interrupt service
12632routine (ISR), reloaded to point to the data section, and restored on
12633exit from the ISR@. This should not be required unless someone has
12634violated the small memory model by modifying the DP register, say within
12635an object library.
12636
12637@item -mmpyi
12638@itemx -mno-mpyi
12639@opindex mmpyi
12640@opindex mno-mpyi
12641For the C3x use the 24-bit MPYI instruction for integer multiplies
12642instead of a library call to guarantee 32-bit results. Note that if one
12643of the operands is a constant, then the multiplication will be performed
12644using shifts and adds. If the @option{-mmpyi} option is not specified for the C3x,
12645then squaring operations are performed inline instead of a library call.
12646
12647@item -mfast-fix
12648@itemx -mno-fast-fix
12649@opindex mfast-fix
12650@opindex mno-fast-fix
12651The C3x/C4x FIX instruction to convert a floating point value to an
12652integer value chooses the nearest integer less than or equal to the
12653floating point value rather than to the nearest integer. Thus if the
12654floating point number is negative, the result will be incorrectly
12655truncated an additional code is necessary to detect and correct this
12656case. This option can be used to disable generation of the additional
12657code required to correct the result.
12658
12659@item -mrptb
12660@itemx -mno-rptb
12661@opindex mrptb
12662@opindex mno-rptb
12663Enable (disable) generation of repeat block sequences using the RPTB
12664instruction for zero overhead looping. The RPTB construct is only used
12665for innermost loops that do not call functions or jump across the loop
12666boundaries. There is no advantage having nested RPTB loops due to the
12667overhead required to save and restore the RC, RS, and RE registers.
12668This is enabled by default with @option{-O2}.
12669
12670@item -mrpts=@var{count}
12671@itemx -mno-rpts
12672@opindex mrpts
12673@opindex mno-rpts
12674Enable (disable) the use of the single instruction repeat instruction
12675RPTS@. If a repeat block contains a single instruction, and the loop
12676count can be guaranteed to be less than the value @var{count}, GCC will
12677emit a RPTS instruction instead of a RPTB@. If no value is specified,
12678then a RPTS will be emitted even if the loop count cannot be determined
12679at compile time. Note that the repeated instruction following RPTS does
12680not have to be reloaded from memory each iteration, thus freeing up the
12681CPU buses for operands. However, since interrupts are blocked by this
12682instruction, it is disabled by default.
12683
12684@item -mloop-unsigned
12685@itemx -mno-loop-unsigned
12686@opindex mloop-unsigned
12687@opindex mno-loop-unsigned
12688The maximum iteration count when using RPTS and RPTB (and DB on the C40)
12689is @math{2^{31} + 1} since these instructions test if the iteration count is
12690negative to terminate the loop. If the iteration count is unsigned
12691there is a possibility than the @math{2^{31} + 1} maximum iteration count may be
12692exceeded. This switch allows an unsigned iteration count.
12693
12694@item -mti
12695@opindex mti
12696Try to emit an assembler syntax that the TI assembler (asm30) is happy
12697with. This also enforces compatibility with the API employed by the TI
12698C3x C compiler. For example, long doubles are passed as structures
12699rather than in floating point registers.
12700
12701@item -mregparm
12702@itemx -mmemparm
12703@opindex mregparm
12704@opindex mmemparm
12705Generate code that uses registers (stack) for passing arguments to functions.
12706By default, arguments are passed in registers where possible rather
12707than by pushing arguments on to the stack.
12708
12709@item -mparallel-insns
12710@itemx -mno-parallel-insns
12711@opindex mparallel-insns
12712@opindex mno-parallel-insns
12713Allow the generation of parallel instructions. This is enabled by
12714default with @option{-O2}.
12715
12716@item -mparallel-mpy
12717@itemx -mno-parallel-mpy
12718@opindex mparallel-mpy
12719@opindex mno-parallel-mpy
12720Allow the generation of MPY||ADD and MPY||SUB parallel instructions,
12721provided @option{-mparallel-insns} is also specified. These instructions have
12722tight register constraints which can pessimize the code generation
12723of large functions.
12724
12725@end table
12726
12727@node V850 Options
12728@subsection V850 Options
12729@cindex V850 Options
12730
12731These @samp{-m} options are defined for V850 implementations:
12732
12733@table @gcctabopt
12734@item -mlong-calls
12735@itemx -mno-long-calls
12736@opindex mlong-calls
12737@opindex mno-long-calls
12738Treat all calls as being far away (near). If calls are assumed to be
12739far away, the compiler will always load the functions address up into a
12740register, and call indirect through the pointer.
12741
12742@item -mno-ep
12743@itemx -mep
12744@opindex mno-ep
12745@opindex mep
12746Do not optimize (do optimize) basic blocks that use the same index
12747pointer 4 or more times to copy pointer into the @code{ep} register, and
12748use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
12749option is on by default if you optimize.
12750
12751@item -mno-prolog-function
12752@itemx -mprolog-function
12753@opindex mno-prolog-function
12754@opindex mprolog-function
12755Do not use (do use) external functions to save and restore registers
12756at the prologue and epilogue of a function. The external functions
12757are slower, but use less code space if more than one function saves
12758the same number of registers. The @option{-mprolog-function} option
12759is on by default if you optimize.
12760
12761@item -mspace
12762@opindex mspace
12763Try to make the code as small as possible. At present, this just turns
12764on the @option{-mep} and @option{-mprolog-function} options.
12765
12766@item -mtda=@var{n}
12767@opindex mtda
12768Put static or global variables whose size is @var{n} bytes or less into
12769the tiny data area that register @code{ep} points to. The tiny data
12770area can hold up to 256 bytes in total (128 bytes for byte references).
12771
12772@item -msda=@var{n}
12773@opindex msda
12774Put static or global variables whose size is @var{n} bytes or less into
12775the small data area that register @code{gp} points to. The small data
12776area can hold up to 64 kilobytes.
12777
12778@item -mzda=@var{n}
12779@opindex mzda
12780Put static or global variables whose size is @var{n} bytes or less into
12781the first 32 kilobytes of memory.
12782
12783@item -mv850
12784@opindex mv850
12785Specify that the target processor is the V850.
12786
12787@item -mbig-switch
12788@opindex mbig-switch
12789Generate code suitable for big switch tables. Use this option only if
12790the assembler/linker complain about out of range branches within a switch
12791table.
12792
12793@item -mapp-regs
12794@opindex mapp-regs
12795This option will cause r2 and r5 to be used in the code generated by
12796the compiler. This setting is the default.
12797
12798@item -mno-app-regs
12799@opindex mno-app-regs
12800This option will cause r2 and r5 to be treated as fixed registers.
12801
12802@item -mv850e1
12803@opindex mv850e1
12804Specify that the target processor is the V850E1. The preprocessor
12805constants @samp{__v850e1__} and @samp{__v850e__} will be defined if
12806this option is used.
12807
12808@item -mv850e
12809@opindex mv850e
12810Specify that the target processor is the V850E@. The preprocessor
12811constant @samp{__v850e__} will be defined if this option is used.
12812
12813If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
12814are defined then a default target processor will be chosen and the
12815relevant @samp{__v850*__} preprocessor constant will be defined.
12816
12817The preprocessor constants @samp{__v850} and @samp{__v851__} are always
12818defined, regardless of which processor variant is the target.
12819
12820@item -mdisable-callt
12821@opindex mdisable-callt
12822This option will suppress generation of the CALLT instruction for the
12823v850e and v850e1 flavors of the v850 architecture. The default is
12824@option{-mno-disable-callt} which allows the CALLT instruction to be used.
12825
12826@end table
12827
12828@node VAX Options
12829@subsection VAX Options
12830@cindex VAX options
12831
12832These @samp{-m} options are defined for the VAX:
12833
12834@table @gcctabopt
12835@item -munix
12836@opindex munix
12837Do not output certain jump instructions (@code{aobleq} and so on)
12838that the Unix assembler for the VAX cannot handle across long
12839ranges.
12840
12841@item -mgnu
12842@opindex mgnu
12843Do output those jump instructions, on the assumption that you
12844will assemble with the GNU assembler.
12845
12846@item -mg
12847@opindex mg
12848Output code for g-format floating point numbers instead of d-format.
12849@end table
12850
12851@node x86-64 Options
12852@subsection x86-64 Options
12853@cindex x86-64 options
12854
12855These are listed under @xref{i386 and x86-64 Options}.
12856
12857@node Xstormy16 Options
12858@subsection Xstormy16 Options
12859@cindex Xstormy16 Options
12860
12861These options are defined for Xstormy16:
12862
12863@table @gcctabopt
12864@item -msim
12865@opindex msim
12866Choose startup files and linker script suitable for the simulator.
12867@end table
12868
12869@node Xtensa Options
12870@subsection Xtensa Options
12871@cindex Xtensa Options
12872
12873These options are supported for Xtensa targets:
12874
12875@table @gcctabopt
12876@item -mconst16
12877@itemx -mno-const16
12878@opindex mconst16
12879@opindex mno-const16
12880Enable or disable use of @code{CONST16} instructions for loading
12881constant values. The @code{CONST16} instruction is currently not a
12882standard option from Tensilica. When enabled, @code{CONST16}
12883instructions are always used in place of the standard @code{L32R}
12884instructions. The use of @code{CONST16} is enabled by default only if
12885the @code{L32R} instruction is not available.
12886
12887@item -mfused-madd
12888@itemx -mno-fused-madd
12889@opindex mfused-madd
12890@opindex mno-fused-madd
12891Enable or disable use of fused multiply/add and multiply/subtract
12892instructions in the floating-point option. This has no effect if the
12893floating-point option is not also enabled. Disabling fused multiply/add
12894and multiply/subtract instructions forces the compiler to use separate
12895instructions for the multiply and add/subtract operations. This may be
12896desirable in some cases where strict IEEE 754-compliant results are
12897required: the fused multiply add/subtract instructions do not round the
12898intermediate result, thereby producing results with @emph{more} bits of
12899precision than specified by the IEEE standard. Disabling fused multiply
12900add/subtract instructions also ensures that the program output is not
12901sensitive to the compiler's ability to combine multiply and add/subtract
12902operations.
12903
12904@item -mtext-section-literals
12905@itemx -mno-text-section-literals
12906@opindex mtext-section-literals
12907@opindex mno-text-section-literals
12908Control the treatment of literal pools. The default is
12909@option{-mno-text-section-literals}, which places literals in a separate
12910section in the output file. This allows the literal pool to be placed
12911in a data RAM/ROM, and it also allows the linker to combine literal
12912pools from separate object files to remove redundant literals and
12913improve code size. With @option{-mtext-section-literals}, the literals
12914are interspersed in the text section in order to keep them as close as
12915possible to their references. This may be necessary for large assembly
12916files.
12917
12918@item -mtarget-align
12919@itemx -mno-target-align
12920@opindex mtarget-align
12921@opindex mno-target-align
12922When this option is enabled, GCC instructs the assembler to
12923automatically align instructions to reduce branch penalties at the
12924expense of some code density. The assembler attempts to widen density
12925instructions to align branch targets and the instructions following call
12926instructions. If there are not enough preceding safe density
12927instructions to align a target, no widening will be performed. The
12928default is @option{-mtarget-align}. These options do not affect the
12929treatment of auto-aligned instructions like @code{LOOP}, which the
12930assembler will always align, either by widening density instructions or
12931by inserting no-op instructions.
12932
12933@item -mlongcalls
12934@itemx -mno-longcalls
12935@opindex mlongcalls
12936@opindex mno-longcalls
12937When this option is enabled, GCC instructs the assembler to translate
12938direct calls to indirect calls unless it can determine that the target
12939of a direct call is in the range allowed by the call instruction. This
12940translation typically occurs for calls to functions in other source
12941files. Specifically, the assembler translates a direct @code{CALL}
12942instruction into an @code{L32R} followed by a @code{CALLX} instruction.
12943The default is @option{-mno-longcalls}. This option should be used in
12944programs where the call target can potentially be out of range. This
12945option is implemented in the assembler, not the compiler, so the
12946assembly code generated by GCC will still show direct call
12947instructions---look at the disassembled object code to see the actual
12948instructions. Note that the assembler will use an indirect call for
12949every cross-file call, not just those that really will be out of range.
12950@end table
12951
12952@node zSeries Options
12953@subsection zSeries Options
12954@cindex zSeries options
12955
12956These are listed under @xref{S/390 and zSeries Options}.
12957
12958@node Code Gen Options
12959@section Options for Code Generation Conventions
12960@cindex code generation conventions
12961@cindex options, code generation
12962@cindex run-time options
12963
12964These machine-independent options control the interface conventions
12965used in code generation.
12966
12967Most of them have both positive and negative forms; the negative form
12968of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
12969one of the forms is listed---the one which is not the default. You
12970can figure out the other form by either removing @samp{no-} or adding
12971it.
12972
12973@table @gcctabopt
12974@item -fbounds-check
12975@opindex fbounds-check
12976For front-ends that support it, generate additional code to check that
12977indices used to access arrays are within the declared range. This is
12978currently only supported by the Java and Fortran front-ends, where
12979this option defaults to true and false respectively.
12980
12981@item -ftrapv
12982@opindex ftrapv
12983This option generates traps for signed overflow on addition, subtraction,
12984multiplication operations.
12985
12986@item -fwrapv
12987@opindex fwrapv
12988This option instructs the compiler to assume that signed arithmetic
12989overflow of addition, subtraction and multiplication wraps around
12990using twos-complement representation. This flag enables some optimizations
12991and disables others. This option is enabled by default for the Java
12992front-end, as required by the Java language specification.
12993
12994@item -fexceptions
12995@opindex fexceptions
12996Enable exception handling. Generates extra code needed to propagate
12997exceptions. For some targets, this implies GCC will generate frame
12998unwind information for all functions, which can produce significant data
12999size overhead, although it does not affect execution. If you do not
13000specify this option, GCC will enable it by default for languages like
13001C++ which normally require exception handling, and disable it for
13002languages like C that do not normally require it. However, you may need
13003to enable this option when compiling C code that needs to interoperate
13004properly with exception handlers written in C++. You may also wish to
13005disable this option if you are compiling older C++ programs that don't
13006use exception handling.
13007
13008@item -fnon-call-exceptions
13009@opindex fnon-call-exceptions
13010Generate code that allows trapping instructions to throw exceptions.
13011Note that this requires platform-specific runtime support that does
13012not exist everywhere. Moreover, it only allows @emph{trapping}
13013instructions to throw exceptions, i.e.@: memory references or floating
13014point instructions. It does not allow exceptions to be thrown from
13015arbitrary signal handlers such as @code{SIGALRM}.
13016
13017@item -funwind-tables
13018@opindex funwind-tables
13019Similar to @option{-fexceptions}, except that it will just generate any needed
13020static data, but will not affect the generated code in any other way.
13021You will normally not enable this option; instead, a language processor
13022that needs this handling would enable it on your behalf.
13023
13024@item -fasynchronous-unwind-tables
13025@opindex fasynchronous-unwind-tables
13026Generate unwind table in dwarf2 format, if supported by target machine. The
13027table is exact at each instruction boundary, so it can be used for stack
13028unwinding from asynchronous events (such as debugger or garbage collector).
13029
13030@item -fpcc-struct-return
13031@opindex fpcc-struct-return
13032Return ``short'' @code{struct} and @code{union} values in memory like
13033longer ones, rather than in registers. This convention is less
13034efficient, but it has the advantage of allowing intercallability between
13035GCC-compiled files and files compiled with other compilers, particularly
13036the Portable C Compiler (pcc).
13037
13038The precise convention for returning structures in memory depends
13039on the target configuration macros.
13040
13041Short structures and unions are those whose size and alignment match
13042that of some integer type.
13043
13044@strong{Warning:} code compiled with the @option{-fpcc-struct-return}
13045switch is not binary compatible with code compiled with the
13046@option{-freg-struct-return} switch.
13047Use it to conform to a non-default application binary interface.
13048
13049@item -freg-struct-return
13050@opindex freg-struct-return
13051Return @code{struct} and @code{union} values in registers when possible.
13052This is more efficient for small structures than
13053@option{-fpcc-struct-return}.
13054
13055If you specify neither @option{-fpcc-struct-return} nor
13056@option{-freg-struct-return}, GCC defaults to whichever convention is
13057standard for the target. If there is no standard convention, GCC
13058defaults to @option{-fpcc-struct-return}, except on targets where GCC is
13059the principal compiler. In those cases, we can choose the standard, and
13060we chose the more efficient register return alternative.
13061
13062@strong{Warning:} code compiled with the @option{-freg-struct-return}
13063switch is not binary compatible with code compiled with the
13064@option{-fpcc-struct-return} switch.
13065Use it to conform to a non-default application binary interface.
13066
13067@item -fshort-enums
13068@opindex fshort-enums
13069Allocate to an @code{enum} type only as many bytes as it needs for the
13070declared range of possible values. Specifically, the @code{enum} type
13071will be equivalent to the smallest integer type which has enough room.
13072
13073@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
13074code that is not binary compatible with code generated without that switch.
13075Use it to conform to a non-default application binary interface.
13076
13077@item -fshort-double
13078@opindex fshort-double
13079Use the same size for @code{double} as for @code{float}.
13080
13081@strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
13082code that is not binary compatible with code generated without that switch.
13083Use it to conform to a non-default application binary interface.
13084
13085@item -fshort-wchar
13086@opindex fshort-wchar
13087Override the underlying type for @samp{wchar_t} to be @samp{short
13088unsigned int} instead of the default for the target. This option is
13089useful for building programs to run under WINE@.
13090
13091@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
13092code that is not binary compatible with code generated without that switch.
13093Use it to conform to a non-default application binary interface.
13094
13095@item -fno-common
13096@opindex fno-common
13097In C, allocate even uninitialized global variables in the data section of the
13098object file, rather than generating them as common blocks. This has the
13099effect that if the same variable is declared (without @code{extern}) in
13100two different compilations, you will get an error when you link them.
13101The only reason this might be useful is if you wish to verify that the
13102program will work on other systems which always work this way.
13103
13104@item -fno-ident
13105@opindex fno-ident
13106Ignore the @samp{#ident} directive.
13107
13108@item -finhibit-size-directive
13109@opindex finhibit-size-directive
13110Don't output a @code{.size} assembler directive, or anything else that
13111would cause trouble if the function is split in the middle, and the
13112two halves are placed at locations far apart in memory. This option is
13113used when compiling @file{crtstuff.c}; you should not need to use it
13114for anything else.
13115
13116@item -fverbose-asm
13117@opindex fverbose-asm
13118Put extra commentary information in the generated assembly code to
13119make it more readable. This option is generally only of use to those
13120who actually need to read the generated assembly code (perhaps while
13121debugging the compiler itself).
13122
13123@option{-fno-verbose-asm}, the default, causes the
13124extra information to be omitted and is useful when comparing two assembler
13125files.
13126
13127@item -fpic
13128@opindex fpic
13129@cindex global offset table
13130@cindex PIC
13131Generate position-independent code (PIC) suitable for use in a shared
13132library, if supported for the target machine. Such code accesses all
13133constant addresses through a global offset table (GOT)@. The dynamic
13134loader resolves the GOT entries when the program starts (the dynamic
13135loader is not part of GCC; it is part of the operating system). If
13136the GOT size for the linked executable exceeds a machine-specific
13137maximum size, you get an error message from the linker indicating that
13138@option{-fpic} does not work; in that case, recompile with @option{-fPIC}
13139instead. (These maximums are 8k on the SPARC and 32k
13140on the m68k and RS/6000. The 386 has no such limit.)
13141
13142Position-independent code requires special support, and therefore works
13143only on certain machines. For the 386, GCC supports PIC for System V
13144but not for the Sun 386i. Code generated for the IBM RS/6000 is always
13145position-independent.
13146
13147When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13148are defined to 1.
13149
13150@item -fPIC
13151@opindex fPIC
13152If supported for the target machine, emit position-independent code,
13153suitable for dynamic linking and avoiding any limit on the size of the
13154global offset table. This option makes a difference on the m68k,
13155PowerPC and SPARC@.
13156
13157Position-independent code requires special support, and therefore works
13158only on certain machines.
13159
13160When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13161are defined to 2.
13162
13163@item -fpie
13164@itemx -fPIE
13165@opindex fpie
13166@opindex fPIE
13167These options are similar to @option{-fpic} and @option{-fPIC}, but
13168generated position independent code can be only linked into executables.
13169Usually these options are used when @option{-pie} GCC option will be
13170used during linking.
13171
13172@item -fno-jump-tables
13173@opindex fno-jump-tables
13174Do not use jump tables for switch statements even where it would be
13175more efficient than other code generation strategies. This option is
13176of use in conjunction with @option{-fpic} or @option{-fPIC} for
13177building code which forms part of a dynamic linker and cannot
13178reference the address of a jump table. On some targets, jump tables
13179do not require a GOT and this option is not needed.
13180
13181@item -ffixed-@var{reg}
13182@opindex ffixed
13183Treat the register named @var{reg} as a fixed register; generated code
13184should never refer to it (except perhaps as a stack pointer, frame
13185pointer or in some other fixed role).
13186
13187@var{reg} must be the name of a register. The register names accepted
13188are machine-specific and are defined in the @code{REGISTER_NAMES}
13189macro in the machine description macro file.
13190
13191This flag does not have a negative form, because it specifies a
13192three-way choice.
13193
13194@item -fcall-used-@var{reg}
13195@opindex fcall-used
13196Treat the register named @var{reg} as an allocable register that is
13197clobbered by function calls. It may be allocated for temporaries or
13198variables that do not live across a call. Functions compiled this way
13199will not save and restore the register @var{reg}.
13200
13201It is an error to used this flag with the frame pointer or stack pointer.
13202Use of this flag for other registers that have fixed pervasive roles in
13203the machine's execution model will produce disastrous results.
13204
13205This flag does not have a negative form, because it specifies a
13206three-way choice.
13207
13208@item -fcall-saved-@var{reg}
13209@opindex fcall-saved
13210Treat the register named @var{reg} as an allocable register saved by
13211functions. It may be allocated even for temporaries or variables that
13212live across a call. Functions compiled this way will save and restore
13213the register @var{reg} if they use it.
13214
13215It is an error to used this flag with the frame pointer or stack pointer.
13216Use of this flag for other registers that have fixed pervasive roles in
13217the machine's execution model will produce disastrous results.
13218
13219A different sort of disaster will result from the use of this flag for
13220a register in which function values may be returned.
13221
13222This flag does not have a negative form, because it specifies a
13223three-way choice.
13224
13225@item -fpack-struct[=@var{n}]
13226@opindex fpack-struct
13227Without a value specified, pack all structure members together without
13228holes. When a value is specified (which must be a small power of two), pack
13229structure members according to this value, representing the maximum
13230alignment (that is, objects with default alignment requirements larger than
13231this will be output potentially unaligned at the next fitting location.
13232
13233@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
13234code that is not binary compatible with code generated without that switch.
13235Additionally, it makes the code suboptimal.
13236Use it to conform to a non-default application binary interface.
13237
13238@item -finstrument-functions
13239@opindex finstrument-functions
13240Generate instrumentation calls for entry and exit to functions. Just
13241after function entry and just before function exit, the following
13242profiling functions will be called with the address of the current
13243function and its call site. (On some platforms,
13244@code{__builtin_return_address} does not work beyond the current
13245function, so the call site information may not be available to the
13246profiling functions otherwise.)
13247
13248@smallexample
13249void __cyg_profile_func_enter (void *this_fn,
13250 void *call_site);
13251void __cyg_profile_func_exit (void *this_fn,
13252 void *call_site);
13253@end smallexample
13254
13255The first argument is the address of the start of the current function,
13256which may be looked up exactly in the symbol table.
13257
13258This instrumentation is also done for functions expanded inline in other
13259functions. The profiling calls will indicate where, conceptually, the
13260inline function is entered and exited. This means that addressable
13261versions of such functions must be available. If all your uses of a
13262function are expanded inline, this may mean an additional expansion of
13263code size. If you use @samp{extern inline} in your C code, an
13264addressable version of such functions must be provided. (This is
13265normally the case anyways, but if you get lucky and the optimizer always
13266expands the functions inline, you might have gotten away without
13267providing static copies.)
13268
13269A function may be given the attribute @code{no_instrument_function}, in
13270which case this instrumentation will not be done. This can be used, for
13271example, for the profiling functions listed above, high-priority
13272interrupt routines, and any functions from which the profiling functions
13273cannot safely be called (perhaps signal handlers, if the profiling
13274routines generate output or allocate memory).
13275
13276@item -fstack-check
13277@opindex fstack-check
13278Generate code to verify that you do not go beyond the boundary of the
13279stack. You should specify this flag if you are running in an
13280environment with multiple threads, but only rarely need to specify it in
13281a single-threaded environment since stack overflow is automatically
13282detected on nearly all systems if there is only one stack.
13283
13284Note that this switch does not actually cause checking to be done; the
13285operating system must do that. The switch causes generation of code
13286to ensure that the operating system sees the stack being extended.
13287
13288@item -fstack-limit-register=@var{reg}
13289@itemx -fstack-limit-symbol=@var{sym}
13290@itemx -fno-stack-limit
13291@opindex fstack-limit-register
13292@opindex fstack-limit-symbol
13293@opindex fno-stack-limit
13294Generate code to ensure that the stack does not grow beyond a certain value,
13295either the value of a register or the address of a symbol. If the stack
13296would grow beyond the value, a signal is raised. For most targets,
13297the signal is raised before the stack overruns the boundary, so
13298it is possible to catch the signal without taking special precautions.
13299
13300For instance, if the stack starts at absolute address @samp{0x80000000}
13301and grows downwards, you can use the flags
13302@option{-fstack-limit-symbol=__stack_limit} and
13303@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
13304of 128KB@. Note that this may only work with the GNU linker.
13305
13306@cindex aliasing of parameters
13307@cindex parameters, aliased
13308@item -fargument-alias
13309@itemx -fargument-noalias
13310@itemx -fargument-noalias-global
13311@itemx -fargument-noalias-anything
13312@opindex fargument-alias
13313@opindex fargument-noalias
13314@opindex fargument-noalias-global
13315@opindex fargument-noalias-anything
13316Specify the possible relationships among parameters and between
13317parameters and global data.
13318
13319@option{-fargument-alias} specifies that arguments (parameters) may
13320alias each other and may alias global storage.@*
13321@option{-fargument-noalias} specifies that arguments do not alias
13322each other, but may alias global storage.@*
13323@option{-fargument-noalias-global} specifies that arguments do not
13324alias each other and do not alias global storage.
13325@option{-fargument-noalias-anything} specifies that arguments do not
13326alias any other storage.
13327
13328Each language will automatically use whatever option is required by
13329the language standard. You should not need to use these options yourself.
13330
13331@item -fleading-underscore
13332@opindex fleading-underscore
13333This option and its counterpart, @option{-fno-leading-underscore}, forcibly
13334change the way C symbols are represented in the object file. One use
13335is to help link with legacy assembly code.
13336
13337@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
13338generate code that is not binary compatible with code generated without that
13339switch. Use it to conform to a non-default application binary interface.
13340Not all targets provide complete support for this switch.
13341
13342@item -ftls-model=@var{model}
13343Alter the thread-local storage model to be used (@pxref{Thread-Local}).
13344The @var{model} argument should be one of @code{global-dynamic},
13345@code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
13346
13347The default without @option{-fpic} is @code{initial-exec}; with
13348@option{-fpic} the default is @code{global-dynamic}.
13349
13350@item -fvisibility=@var{default|internal|hidden|protected}
13351@opindex fvisibility
13352Set the default ELF image symbol visibility to the specified option---all
13353symbols will be marked with this unless overridden within the code.
13354Using this feature can very substantially improve linking and
13355load times of shared object libraries, produce more optimized
13356code, provide near-perfect API export and prevent symbol clashes.
13357It is @strong{strongly} recommended that you use this in any shared objects
13358you distribute.
13359
13360Despite the nomenclature, @code{default} always means public ie;
13361available to be linked against from outside the shared object.
13362@code{protected} and @code{internal} are pretty useless in real-world
13363usage so the only other commonly used option will be @code{hidden}.
13364The default if @option{-fvisibility} isn't specified is
13365@code{default}, i.e., make every
13366symbol public---this causes the same behavior as previous versions of
13367GCC@.
13368
13369A good explanation of the benefits offered by ensuring ELF
13370symbols have the correct visibility is given by ``How To Write
13371Shared Libraries'' by Ulrich Drepper (which can be found at
13372@w{@uref{http://people.redhat.com/~drepper/}})---however a superior
13373solution made possible by this option to marking things hidden when
13374the default is public is to make the default hidden and mark things
13375public. This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
13376and @code{__attribute__ ((visibility("default")))} instead of
13377@code{__declspec(dllexport)} you get almost identical semantics with
13378identical syntax. This is a great boon to those working with
13379cross-platform projects.
13380
13381For those adding visibility support to existing code, you may find
13382@samp{#pragma GCC visibility} of use. This works by you enclosing
13383the declarations you wish to set visibility for with (for example)
13384@samp{#pragma GCC visibility push(hidden)} and
13385@samp{#pragma GCC visibility pop}.
13386Bear in mind that symbol visibility should be viewed @strong{as
13387part of the API interface contract} and thus all new code should
13388always specify visibility when it is not the default ie; declarations
13389only for use within the local DSO should @strong{always} be marked explicitly
13390as hidden as so to avoid PLT indirection overheads---making this
13391abundantly clear also aids readability and self-documentation of the code.
13392Note that due to ISO C++ specification requirements, operator new and
13393operator delete must always be of default visibility.
13394
13395Be aware that headers from outside your project, in particular system
13396headers and headers from any other library you use, may not be
13397expecting to be compiled with visibility other than the default. You
13398may need to explicitly say @samp{#pragma GCC visibility push(default)}
13399before including any such headers.
13400
13401@samp{extern} declarations are not affected by @samp{-fvisibility}, so
13402a lot of code can be recompiled with @samp{-fvisibility=hidden} with
13403no modifications. However, this means that calls to @samp{extern}
13404functions with no explicit visibility will use the PLT, so it is more
13405effective to use @samp{__attribute ((visibility))} and/or
13406@samp{#pragma GCC visibility} to tell the compiler which @samp{extern}
13407declarations should be treated as hidden.
13408
13409Note that @samp{-fvisibility} does affect C++ vague linkage
13410entities. This means that, for instance, an exception class that will
13411be thrown between DSOs must be explicitly marked with default
13412visibility so that the @samp{type_info} nodes will be unified between
13413the DSOs.
13414
13415An overview of these techniques, their benefits and how to use them
13416is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
13417
13418@end table
13419
13420@c man end
13421
13422@node Environment Variables
13423@section Environment Variables Affecting GCC
13424@cindex environment variables
13425
13426@c man begin ENVIRONMENT
13427This section describes several environment variables that affect how GCC
13428operates. Some of them work by specifying directories or prefixes to use
13429when searching for various kinds of files. Some are used to specify other
13430aspects of the compilation environment.
13431
13432Note that you can also specify places to search using options such as
13433@option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
13434take precedence over places specified using environment variables, which
13435in turn take precedence over those specified by the configuration of GCC@.
13436@xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
13437GNU Compiler Collection (GCC) Internals}.
13438
13439@table @env
13440@item LANG
13441@itemx LC_CTYPE
13442@c @itemx LC_COLLATE
13443@itemx LC_MESSAGES
13444@c @itemx LC_MONETARY
13445@c @itemx LC_NUMERIC
13446@c @itemx LC_TIME
13447@itemx LC_ALL
13448@findex LANG
13449@findex LC_CTYPE
13450@c @findex LC_COLLATE
13451@findex LC_MESSAGES
13452@c @findex LC_MONETARY
13453@c @findex LC_NUMERIC
13454@c @findex LC_TIME
13455@findex LC_ALL
13456@cindex locale
13457These environment variables control the way that GCC uses
13458localization information that allow GCC to work with different
13459national conventions. GCC inspects the locale categories
13460@env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
13461so. These locale categories can be set to any value supported by your
13462installation. A typical value is @samp{en_GB.UTF-8} for English in the United
13463Kingdom encoded in UTF-8.
13464
13465The @env{LC_CTYPE} environment variable specifies character
13466classification. GCC uses it to determine the character boundaries in
13467a string; this is needed for some multibyte encodings that contain quote
13468and escape characters that would otherwise be interpreted as a string
13469end or escape.
13470
13471The @env{LC_MESSAGES} environment variable specifies the language to
13472use in diagnostic messages.
13473
13474If the @env{LC_ALL} environment variable is set, it overrides the value
13475of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
13476and @env{LC_MESSAGES} default to the value of the @env{LANG}
13477environment variable. If none of these variables are set, GCC
13478defaults to traditional C English behavior.
13479
13480@item TMPDIR
13481@findex TMPDIR
13482If @env{TMPDIR} is set, it specifies the directory to use for temporary
13483files. GCC uses temporary files to hold the output of one stage of
13484compilation which is to be used as input to the next stage: for example,
13485the output of the preprocessor, which is the input to the compiler
13486proper.
13487
13488@item GCC_EXEC_PREFIX
13489@findex GCC_EXEC_PREFIX
13490If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
13491names of the subprograms executed by the compiler. No slash is added
13492when this prefix is combined with the name of a subprogram, but you can
13493specify a prefix that ends with a slash if you wish.
13494
13495If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
13496an appropriate prefix to use based on the pathname it was invoked with.
13497
13498If GCC cannot find the subprogram using the specified prefix, it
13499tries looking in the usual places for the subprogram.
13500
13501The default value of @env{GCC_EXEC_PREFIX} is
13502@file{@var{prefix}/lib/gcc/} where @var{prefix} is the value
13503of @code{prefix} when you ran the @file{configure} script.
13504
13505Other prefixes specified with @option{-B} take precedence over this prefix.
13506
13507This prefix is also used for finding files such as @file{crt0.o} that are
13508used for linking.
13509
13510In addition, the prefix is used in an unusual way in finding the
13511directories to search for header files. For each of the standard
13512directories whose name normally begins with @samp{/usr/local/lib/gcc}
13513(more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
13514replacing that beginning with the specified prefix to produce an
13515alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
13516@file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
13517These alternate directories are searched first; the standard directories
13518come next.
13519
13520@item COMPILER_PATH
13521@findex COMPILER_PATH
13522The value of @env{COMPILER_PATH} is a colon-separated list of
13523directories, much like @env{PATH}. GCC tries the directories thus
13524specified when searching for subprograms, if it can't find the
13525subprograms using @env{GCC_EXEC_PREFIX}.
13526
13527@item LIBRARY_PATH
13528@findex LIBRARY_PATH
13529The value of @env{LIBRARY_PATH} is a colon-separated list of
13530directories, much like @env{PATH}. When configured as a native compiler,
13531GCC tries the directories thus specified when searching for special
13532linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking
13533using GCC also uses these directories when searching for ordinary
13534libraries for the @option{-l} option (but directories specified with
13535@option{-L} come first).
13536
13537@item LANG
13538@findex LANG
13539@cindex locale definition
13540This variable is used to pass locale information to the compiler. One way in
13541which this information is used is to determine the character set to be used
13542when character literals, string literals and comments are parsed in C and C++.
13543When the compiler is configured to allow multibyte characters,
13544the following values for @env{LANG} are recognized:
13545
13546@table @samp
13547@item C-JIS
13548Recognize JIS characters.
13549@item C-SJIS
13550Recognize SJIS characters.
13551@item C-EUCJP
13552Recognize EUCJP characters.
13553@end table
13554
13555If @env{LANG} is not defined, or if it has some other value, then the
13556compiler will use mblen and mbtowc as defined by the default locale to
13557recognize and translate multibyte characters.
13558@end table
13559
13560@noindent
13561Some additional environments variables affect the behavior of the
13562preprocessor.
13563
13564@include cppenv.texi
13565
13566@c man end
13567
13568@node Precompiled Headers
13569@section Using Precompiled Headers
13570@cindex precompiled headers
13571@cindex speed of compilation
13572
13573Often large projects have many header files that are included in every
13574source file. The time the compiler takes to process these header files
13575over and over again can account for nearly all of the time required to
13576build the project. To make builds faster, GCC allows users to
13577`precompile' a header file; then, if builds can use the precompiled
13578header file they will be much faster.
13579
13580To create a precompiled header file, simply compile it as you would any
13581other file, if necessary using the @option{-x} option to make the driver
13582treat it as a C or C++ header file. You will probably want to use a
13583tool like @command{make} to keep the precompiled header up-to-date when
13584the headers it contains change.
13585
13586A precompiled header file will be searched for when @code{#include} is
13587seen in the compilation. As it searches for the included file
13588(@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
13589compiler looks for a precompiled header in each directory just before it
13590looks for the include file in that directory. The name searched for is
13591the name specified in the @code{#include} with @samp{.gch} appended. If
13592the precompiled header file can't be used, it is ignored.
13593
13594For instance, if you have @code{#include "all.h"}, and you have
13595@file{all.h.gch} in the same directory as @file{all.h}, then the
13596precompiled header file will be used if possible, and the original
13597header will be used otherwise.
13598
13599Alternatively, you might decide to put the precompiled header file in a
13600directory and use @option{-I} to ensure that directory is searched
13601before (or instead of) the directory containing the original header.
13602Then, if you want to check that the precompiled header file is always
13603used, you can put a file of the same name as the original header in this
13604directory containing an @code{#error} command.
13605
13606This also works with @option{-include}. So yet another way to use
13607precompiled headers, good for projects not designed with precompiled
13608header files in mind, is to simply take most of the header files used by
13609a project, include them from another header file, precompile that header
13610file, and @option{-include} the precompiled header. If the header files
13611have guards against multiple inclusion, they will be skipped because
13612they've already been included (in the precompiled header).
13613
13614If you need to precompile the same header file for different
13615languages, targets, or compiler options, you can instead make a
13616@emph{directory} named like @file{all.h.gch}, and put each precompiled
13617header in the directory, perhaps using @option{-o}. It doesn't matter
13618what you call the files in the directory, every precompiled header in
13619the directory will be considered. The first precompiled header
13620encountered in the directory that is valid for this compilation will
13621be used; they're searched in no particular order.
13622
13623There are many other possibilities, limited only by your imagination,
13624good sense, and the constraints of your build system.
13625
13626A precompiled header file can be used only when these conditions apply:
13627
13628@itemize
13629@item
13630Only one precompiled header can be used in a particular compilation.
13631
13632@item
13633A precompiled header can't be used once the first C token is seen. You
13634can have preprocessor directives before a precompiled header; you can
13635even include a precompiled header from inside another header, so long as
13636there are no C tokens before the @code{#include}.
13637
13638@item
13639The precompiled header file must be produced for the same language as
13640the current compilation. You can't use a C precompiled header for a C++
13641compilation.
13642
13643@item
13644The precompiled header file must have been produced by the same compiler
13645binary as the current compilation is using.
13646
13647@item
13648Any macros defined before the precompiled header is included must
13649either be defined in the same way as when the precompiled header was
13650generated, or must not affect the precompiled header, which usually
13651means that they don't appear in the precompiled header at all.
13652
13653The @option{-D} option is one way to define a macro before a
13654precompiled header is included; using a @code{#define} can also do it.
13655There are also some options that define macros implicitly, like
13656@option{-O} and @option{-Wdeprecated}; the same rule applies to macros
13657defined this way.
13658
13659@item If debugging information is output when using the precompiled
13660header, using @option{-g} or similar, the same kind of debugging information
13661must have been output when building the precompiled header. However,
13662a precompiled header built using @option{-g} can be used in a compilation
13663when no debugging information is being output.
13664
13665@item The same @option{-m} options must generally be used when building
13666and using the precompiled header. @xref{Submodel Options},
13667for any cases where this rule is relaxed.
13668
13669@item Each of the following options must be the same when building and using
13670the precompiled header:
13671
13672@gccoptlist{-fexceptions -funit-at-a-time}
13673
13674@item
13675Some other command-line options starting with @option{-f},
13676@option{-p}, or @option{-O} must be defined in the same way as when
13677the precompiled header was generated. At present, it's not clear
13678which options are safe to change and which are not; the safest choice
13679is to use exactly the same options when generating and using the
13680precompiled header. The following are known to be safe:
13681
13682@gccoptlist{-fmessage-length= -fpreprocessed
13683-fsched-interblock -fsched-spec -fsched-spec-load -fsched-spec-load-dangerous
13684-fsched-verbose=<number> -fschedule-insns -fvisibility=
13685-pedantic-errors}
13686
13687@end itemize
13688
13689For all of these except the last, the compiler will automatically
13690ignore the precompiled header if the conditions aren't met. If you
13691find an option combination that doesn't work and doesn't cause the
13692precompiled header to be ignored, please consider filing a bug report,
13693see @ref{Bugs}.
13694
13695If you do use differing options when generating and using the
13696precompiled header, the actual behavior will be a mixture of the
13697behavior for the options. For instance, if you use @option{-g} to
13698generate the precompiled header but not when using it, you may or may
13699not get debugging information for routines in the precompiled header.
13700
13701@node Running Protoize
13702@section Running Protoize
13703
13704The program @code{protoize} is an optional part of GCC@. You can use
13705it to add prototypes to a program, thus converting the program to ISO
13706C in one respect. The companion program @code{unprotoize} does the
13707reverse: it removes argument types from any prototypes that are found.
13708
13709When you run these programs, you must specify a set of source files as
13710command line arguments. The conversion programs start out by compiling
13711these files to see what functions they define. The information gathered
13712about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
13713
13714After scanning comes actual conversion. The specified files are all
13715eligible to be converted; any files they include (whether sources or
13716just headers) are eligible as well.
13717
13718But not all the eligible files are converted. By default,
13719@code{protoize} and @code{unprotoize} convert only source and header
13720files in the current directory. You can specify additional directories
13721whose files should be converted with the @option{-d @var{directory}}
13722option. You can also specify particular files to exclude with the
13723@option{-x @var{file}} option. A file is converted if it is eligible, its
13724directory name matches one of the specified directory names, and its
13725name within the directory has not been excluded.
13726
13727Basic conversion with @code{protoize} consists of rewriting most
13728function definitions and function declarations to specify the types of
13729the arguments. The only ones not rewritten are those for varargs
13730functions.
13731
13732@code{protoize} optionally inserts prototype declarations at the
13733beginning of the source file, to make them available for any calls that
13734precede the function's definition. Or it can insert prototype
13735declarations with block scope in the blocks where undeclared functions
13736are called.
13737
13738Basic conversion with @code{unprotoize} consists of rewriting most
13739function declarations to remove any argument types, and rewriting
13740function definitions to the old-style pre-ISO form.
13741
13742Both conversion programs print a warning for any function declaration or
13743definition that they can't convert. You can suppress these warnings
13744with @option{-q}.
13745
13746The output from @code{protoize} or @code{unprotoize} replaces the
13747original source file. The original file is renamed to a name ending
13748with @samp{.save} (for DOS, the saved filename ends in @samp{.sav}
13749without the original @samp{.c} suffix). If the @samp{.save} (@samp{.sav}
13750for DOS) file already exists, then the source file is simply discarded.
13751
13752@code{protoize} and @code{unprotoize} both depend on GCC itself to
13753scan the program and collect information about the functions it uses.
13754So neither of these programs will work until GCC is installed.
13755
13756Here is a table of the options you can use with @code{protoize} and
13757@code{unprotoize}. Each option works with both programs unless
13758otherwise stated.
13759
13760@table @code
13761@item -B @var{directory}
13762Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
13763usual directory (normally @file{/usr/local/lib}). This file contains
13764prototype information about standard system functions. This option
13765applies only to @code{protoize}.
13766
13767@item -c @var{compilation-options}
13768Use @var{compilation-options} as the options when running @command{gcc} to
13769produce the @samp{.X} files. The special option @option{-aux-info} is
13770always passed in addition, to tell @command{gcc} to write a @samp{.X} file.
13771
13772Note that the compilation options must be given as a single argument to
13773@code{protoize} or @code{unprotoize}. If you want to specify several
13774@command{gcc} options, you must quote the entire set of compilation options
13775to make them a single word in the shell.
13776
13777There are certain @command{gcc} arguments that you cannot use, because they
13778would produce the wrong kind of output. These include @option{-g},
13779@option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in
13780the @var{compilation-options}, they are ignored.
13781
13782@item -C
13783Rename files to end in @samp{.C} (@samp{.cc} for DOS-based file
13784systems) instead of @samp{.c}. This is convenient if you are converting
13785a C program to C++. This option applies only to @code{protoize}.
13786
13787@item -g
13788Add explicit global declarations. This means inserting explicit
13789declarations at the beginning of each source file for each function
13790that is called in the file and was not declared. These declarations
13791precede the first function definition that contains a call to an
13792undeclared function. This option applies only to @code{protoize}.
13793
13794@item -i @var{string}
13795Indent old-style parameter declarations with the string @var{string}.
13796This option applies only to @code{protoize}.
13797
13798@code{unprotoize} converts prototyped function definitions to old-style
13799function definitions, where the arguments are declared between the
13800argument list and the initial @samp{@{}. By default, @code{unprotoize}
13801uses five spaces as the indentation. If you want to indent with just
13802one space instead, use @option{-i " "}.
13803
13804@item -k
13805Keep the @samp{.X} files. Normally, they are deleted after conversion
13806is finished.
13807
13808@item -l
13809Add explicit local declarations. @code{protoize} with @option{-l} inserts
13810a prototype declaration for each function in each block which calls the
13811function without any declaration. This option applies only to
13812@code{protoize}.
13813
13814@item -n
13815Make no real changes. This mode just prints information about the conversions
13816that would have been done without @option{-n}.
13817
13818@item -N
13819Make no @samp{.save} files. The original files are simply deleted.
13820Use this option with caution.
13821
13822@item -p @var{program}
13823Use the program @var{program} as the compiler. Normally, the name
13824@file{gcc} is used.
13825
13826@item -q
13827Work quietly. Most warnings are suppressed.
13828
13829@item -v
13830Print the version number, just like @option{-v} for @command{gcc}.
13831@end table
13832
13833If you need special compiler options to compile one of your program's
13834source files, then you should generate that file's @samp{.X} file
13835specially, by running @command{gcc} on that source file with the
13836appropriate options and the option @option{-aux-info}. Then run
13837@code{protoize} on the entire set of files. @code{protoize} will use
13838the existing @samp{.X} file because it is newer than the source file.
13839For example:
13840
13841@smallexample
13842gcc -Dfoo=bar file1.c -aux-info file1.X
13843protoize *.c
13844@end smallexample
13845
13846@noindent
13847You need to include the special files along with the rest in the
13848@code{protoize} command, even though their @samp{.X} files already
13849exist, because otherwise they won't get converted.
13850
13851@xref{Protoize Caveats}, for more information on how to use
13852@code{protoize} successfully.
3212@item -Wvolatile-register-var
3213@opindex Wvolatile-register-var
3214@opindex Wno-volatile-register-var
3215Warn if a register variable is declared volatile. The volatile
3216modifier does not inhibit all optimizations that may eliminate reads
3217and/or writes to register variables.
3218
3219@item -Wdisabled-optimization
3220@opindex Wdisabled-optimization
3221Warn if a requested optimization pass is disabled. This warning does
3222not generally indicate that there is anything wrong with your code; it
3223merely indicates that GCC's optimizers were unable to handle the code
3224effectively. Often, the problem is that your code is too big or too
3225complex; GCC will refuse to optimize programs when the optimization
3226itself is likely to take inordinate amounts of time.
3227
3228@item -Wpointer-sign
3229@opindex Wpointer-sign
3230@opindex Wno-pointer-sign
3231Warn for pointer argument passing or assignment with different signedness.
3232This option is only supported for C. It is implied by @option{-Wall}
3233and by @option{-pedantic}, which can be disabled with
3234@option{-Wno-pointer-sign}.
3235
3236@item -Werror
3237@opindex Werror
3238Make all warnings into errors.
3239
3240@item -Werror=
3241@opindex Werror=
3242Make the specified warning into an errors. The specifier for a
3243warning is appended, for example @option{-Werror=switch} turns the
3244warnings controlled by @option{-Wswitch} into errors. This switch
3245takes a negative form, to be used to negate @option{-Werror} for
3246specific warnings, for example @option{-Wno-error=switch} makes
3247@option{-Wswitch} warnings not be errors, even when @option{-Werror}
3248is in effect. You can use the @option{-fdiagnostics-show-option}
3249option to have each controllable warning amended with the option which
3250controls it, to determine what to use with this option.
3251
3252Note that specifying @option{-Werror=}@var{foo} automatically implies
3253@option{-W}@var{foo}. However, @option{-Wno-error=}@var{foo} does not
3254imply anything.
3255
3256@item -Wstack-protector
3257@opindex Wstack-protector
3258This option is only active when @option{-fstack-protector} is active. It
3259warns about functions that will not be protected against stack smashing.
3260
3261@item -Woverlength-strings
3262@opindex Woverlength-strings
3263Warn about string constants which are longer than the ``minimum
3264maximum'' length specified in the C standard. Modern compilers
3265generally allow string constants which are much longer than the
3266standard's minimum limit, but very portable programs should avoid
3267using longer strings.
3268
3269The limit applies @emph{after} string constant concatenation, and does
3270not count the trailing NUL@. In C89, the limit was 509 characters; in
3271C99, it was raised to 4095. C++98 does not specify a normative
3272minimum maximum, so we do not diagnose overlength strings in C++@.
3273
3274This option is implied by @option{-pedantic}, and can be disabled with
3275@option{-Wno-overlength-strings}.
3276@end table
3277
3278@node Debugging Options
3279@section Options for Debugging Your Program or GCC
3280@cindex options, debugging
3281@cindex debugging information options
3282
3283GCC has various special options that are used for debugging
3284either your program or GCC:
3285
3286@table @gcctabopt
3287@item -g
3288@opindex g
3289Produce debugging information in the operating system's native format
3290(stabs, COFF, XCOFF, or DWARF 2)@. GDB can work with this debugging
3291information.
3292
3293On most systems that use stabs format, @option{-g} enables use of extra
3294debugging information that only GDB can use; this extra information
3295makes debugging work better in GDB but will probably make other debuggers
3296crash or
3297refuse to read the program. If you want to control for certain whether
3298to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
3299@option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
3300
3301GCC allows you to use @option{-g} with
3302@option{-O}. The shortcuts taken by optimized code may occasionally
3303produce surprising results: some variables you declared may not exist
3304at all; flow of control may briefly move where you did not expect it;
3305some statements may not be executed because they compute constant
3306results or their values were already at hand; some statements may
3307execute in different places because they were moved out of loops.
3308
3309Nevertheless it proves possible to debug optimized output. This makes
3310it reasonable to use the optimizer for programs that might have bugs.
3311
3312The following options are useful when GCC is generated with the
3313capability for more than one debugging format.
3314
3315@item -ggdb
3316@opindex ggdb
3317Produce debugging information for use by GDB@. This means to use the
3318most expressive format available (DWARF 2, stabs, or the native format
3319if neither of those are supported), including GDB extensions if at all
3320possible.
3321
3322@item -gstabs
3323@opindex gstabs
3324Produce debugging information in stabs format (if that is supported),
3325without GDB extensions. This is the format used by DBX on most BSD
3326systems. On MIPS, Alpha and System V Release 4 systems this option
3327produces stabs debugging output which is not understood by DBX or SDB@.
3328On System V Release 4 systems this option requires the GNU assembler.
3329
3330@item -feliminate-unused-debug-symbols
3331@opindex feliminate-unused-debug-symbols
3332Produce debugging information in stabs format (if that is supported),
3333for only symbols that are actually used.
3334
3335@item -femit-class-debug-always
3336Instead of emitting debugging information for a C++ class in only one
3337object file, emit it in all object files using the class. This option
3338should be used only with debuggers that are unable to handle the way GCC
3339normally emits debugging information for classes because using this
3340option will increase the size of debugging information by as much as a
3341factor of two.
3342
3343@item -gstabs+
3344@opindex gstabs+
3345Produce debugging information in stabs format (if that is supported),
3346using GNU extensions understood only by the GNU debugger (GDB)@. The
3347use of these extensions is likely to make other debuggers crash or
3348refuse to read the program.
3349
3350@item -gcoff
3351@opindex gcoff
3352Produce debugging information in COFF format (if that is supported).
3353This is the format used by SDB on most System V systems prior to
3354System V Release 4.
3355
3356@item -gxcoff
3357@opindex gxcoff
3358Produce debugging information in XCOFF format (if that is supported).
3359This is the format used by the DBX debugger on IBM RS/6000 systems.
3360
3361@item -gxcoff+
3362@opindex gxcoff+
3363Produce debugging information in XCOFF format (if that is supported),
3364using GNU extensions understood only by the GNU debugger (GDB)@. The
3365use of these extensions is likely to make other debuggers crash or
3366refuse to read the program, and may cause assemblers other than the GNU
3367assembler (GAS) to fail with an error.
3368
3369@item -gdwarf-2
3370@opindex gdwarf-2
3371Produce debugging information in DWARF version 2 format (if that is
3372supported). This is the format used by DBX on IRIX 6. With this
3373option, GCC uses features of DWARF version 3 when they are useful;
3374version 3 is upward compatible with version 2, but may still cause
3375problems for older debuggers.
3376
3377@item -gvms
3378@opindex gvms
3379Produce debugging information in VMS debug format (if that is
3380supported). This is the format used by DEBUG on VMS systems.
3381
3382@item -g@var{level}
3383@itemx -ggdb@var{level}
3384@itemx -gstabs@var{level}
3385@itemx -gcoff@var{level}
3386@itemx -gxcoff@var{level}
3387@itemx -gvms@var{level}
3388Request debugging information and also use @var{level} to specify how
3389much information. The default level is 2.
3390
3391Level 1 produces minimal information, enough for making backtraces in
3392parts of the program that you don't plan to debug. This includes
3393descriptions of functions and external variables, but no information
3394about local variables and no line numbers.
3395
3396Level 3 includes extra information, such as all the macro definitions
3397present in the program. Some debuggers support macro expansion when
3398you use @option{-g3}.
3399
3400@option{-gdwarf-2} does not accept a concatenated debug level, because
3401GCC used to support an option @option{-gdwarf} that meant to generate
3402debug information in version 1 of the DWARF format (which is very
3403different from version 2), and it would have been too confusing. That
3404debug format is long obsolete, but the option cannot be changed now.
3405Instead use an additional @option{-g@var{level}} option to change the
3406debug level for DWARF2.
3407
3408@item -feliminate-dwarf2-dups
3409@opindex feliminate-dwarf2-dups
3410Compress DWARF2 debugging information by eliminating duplicated
3411information about each symbol. This option only makes sense when
3412generating DWARF2 debugging information with @option{-gdwarf-2}.
3413
3414@cindex @command{prof}
3415@item -p
3416@opindex p
3417Generate extra code to write profile information suitable for the
3418analysis program @command{prof}. You must use this option when compiling
3419the source files you want data about, and you must also use it when
3420linking.
3421
3422@cindex @command{gprof}
3423@item -pg
3424@opindex pg
3425Generate extra code to write profile information suitable for the
3426analysis program @command{gprof}. You must use this option when compiling
3427the source files you want data about, and you must also use it when
3428linking.
3429
3430@item -Q
3431@opindex Q
3432Makes the compiler print out each function name as it is compiled, and
3433print some statistics about each pass when it finishes.
3434
3435@item -ftime-report
3436@opindex ftime-report
3437Makes the compiler print some statistics about the time consumed by each
3438pass when it finishes.
3439
3440@item -fmem-report
3441@opindex fmem-report
3442Makes the compiler print some statistics about permanent memory
3443allocation when it finishes.
3444
3445@item -fprofile-arcs
3446@opindex fprofile-arcs
3447Add code so that program flow @dfn{arcs} are instrumented. During
3448execution the program records how many times each branch and call is
3449executed and how many times it is taken or returns. When the compiled
3450program exits it saves this data to a file called
3451@file{@var{auxname}.gcda} for each source file. The data may be used for
3452profile-directed optimizations (@option{-fbranch-probabilities}), or for
3453test coverage analysis (@option{-ftest-coverage}). Each object file's
3454@var{auxname} is generated from the name of the output file, if
3455explicitly specified and it is not the final executable, otherwise it is
3456the basename of the source file. In both cases any suffix is removed
3457(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
3458@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
3459@xref{Cross-profiling}.
3460
3461@cindex @command{gcov}
3462@item --coverage
3463@opindex coverage
3464
3465This option is used to compile and link code instrumented for coverage
3466analysis. The option is a synonym for @option{-fprofile-arcs}
3467@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
3468linking). See the documentation for those options for more details.
3469
3470@itemize
3471
3472@item
3473Compile the source files with @option{-fprofile-arcs} plus optimization
3474and code generation options. For test coverage analysis, use the
3475additional @option{-ftest-coverage} option. You do not need to profile
3476every source file in a program.
3477
3478@item
3479Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
3480(the latter implies the former).
3481
3482@item
3483Run the program on a representative workload to generate the arc profile
3484information. This may be repeated any number of times. You can run
3485concurrent instances of your program, and provided that the file system
3486supports locking, the data files will be correctly updated. Also
3487@code{fork} calls are detected and correctly handled (double counting
3488will not happen).
3489
3490@item
3491For profile-directed optimizations, compile the source files again with
3492the same optimization and code generation options plus
3493@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
3494Control Optimization}).
3495
3496@item
3497For test coverage analysis, use @command{gcov} to produce human readable
3498information from the @file{.gcno} and @file{.gcda} files. Refer to the
3499@command{gcov} documentation for further information.
3500
3501@end itemize
3502
3503With @option{-fprofile-arcs}, for each function of your program GCC
3504creates a program flow graph, then finds a spanning tree for the graph.
3505Only arcs that are not on the spanning tree have to be instrumented: the
3506compiler adds code to count the number of times that these arcs are
3507executed. When an arc is the only exit or only entrance to a block, the
3508instrumentation code can be added to the block; otherwise, a new basic
3509block must be created to hold the instrumentation code.
3510
3511@need 2000
3512@item -ftest-coverage
3513@opindex ftest-coverage
3514Produce a notes file that the @command{gcov} code-coverage utility
3515(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
3516show program coverage. Each source file's note file is called
3517@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
3518above for a description of @var{auxname} and instructions on how to
3519generate test coverage data. Coverage data will match the source files
3520more closely, if you do not optimize.
3521
3522@item -d@var{letters}
3523@item -fdump-rtl-@var{pass}
3524@opindex d
3525Says to make debugging dumps during compilation at times specified by
3526@var{letters}. This is used for debugging the RTL-based passes of the
3527compiler. The file names for most of the dumps are made by appending a
3528pass number and a word to the @var{dumpname}. @var{dumpname} is generated
3529from the name of the output file, if explicitly specified and it is not
3530an executable, otherwise it is the basename of the source file.
3531
3532Most debug dumps can be enabled either passing a letter to the @option{-d}
3533option, or with a long @option{-fdump-rtl} switch; here are the possible
3534letters for use in @var{letters} and @var{pass}, and their meanings:
3535
3536@table @gcctabopt
3537@item -dA
3538@opindex dA
3539Annotate the assembler output with miscellaneous debugging information.
3540
3541@item -dB
3542@itemx -fdump-rtl-bbro
3543@opindex dB
3544@opindex fdump-rtl-bbro
3545Dump after block reordering, to @file{@var{file}.148r.bbro}.
3546
3547@item -dc
3548@itemx -fdump-rtl-combine
3549@opindex dc
3550@opindex fdump-rtl-combine
3551Dump after instruction combination, to the file @file{@var{file}.129r.combine}.
3552
3553@item -dC
3554@itemx -fdump-rtl-ce1
3555@itemx -fdump-rtl-ce2
3556@opindex dC
3557@opindex fdump-rtl-ce1
3558@opindex fdump-rtl-ce2
3559@option{-dC} and @option{-fdump-rtl-ce1} enable dumping after the
3560first if conversion, to the file @file{@var{file}.117r.ce1}. @option{-dC}
3561and @option{-fdump-rtl-ce2} enable dumping after the second if
3562conversion, to the file @file{@var{file}.130r.ce2}.
3563
3564@item -dd
3565@itemx -fdump-rtl-btl
3566@itemx -fdump-rtl-dbr
3567@opindex dd
3568@opindex fdump-rtl-btl
3569@opindex fdump-rtl-dbr
3570@option{-dd} and @option{-fdump-rtl-btl} enable dumping after branch
3571target load optimization, to @file{@var{file}.31.btl}. @option{-dd}
3572and @option{-fdump-rtl-dbr} enable dumping after delayed branch
3573scheduling, to @file{@var{file}.36.dbr}.
3574
3575@item -dD
3576@opindex dD
3577Dump all macro definitions, at the end of preprocessing, in addition to
3578normal output.
3579
3580@item -dE
3581@itemx -fdump-rtl-ce3
3582@opindex dE
3583@opindex fdump-rtl-ce3
3584Dump after the third if conversion, to @file{@var{file}.146r.ce3}.
3585
3586@item -df
3587@itemx -fdump-rtl-cfg
3588@itemx -fdump-rtl-life
3589@opindex df
3590@opindex fdump-rtl-cfg
3591@opindex fdump-rtl-life
3592@option{-df} and @option{-fdump-rtl-cfg} enable dumping after control
3593and data flow analysis, to @file{@var{file}.116r.cfg}. @option{-df}
3594and @option{-fdump-rtl-cfg} enable dumping dump after life analysis,
3595to @file{@var{file}.128r.life1} and @file{@var{file}.135r.life2}.
3596
3597@item -dg
3598@itemx -fdump-rtl-greg
3599@opindex dg
3600@opindex fdump-rtl-greg
3601Dump after global register allocation, to @file{@var{file}.139r.greg}.
3602
3603@item -dG
3604@itemx -fdump-rtl-gcse
3605@itemx -fdump-rtl-bypass
3606@opindex dG
3607@opindex fdump-rtl-gcse
3608@opindex fdump-rtl-bypass
3609@option{-dG} and @option{-fdump-rtl-gcse} enable dumping after GCSE, to
3610@file{@var{file}.114r.gcse}. @option{-dG} and @option{-fdump-rtl-bypass}
3611enable dumping after jump bypassing and control flow optimizations, to
3612@file{@var{file}.115r.bypass}.
3613
3614@item -dh
3615@itemx -fdump-rtl-eh
3616@opindex dh
3617@opindex fdump-rtl-eh
3618Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
3619
3620@item -di
3621@itemx -fdump-rtl-sibling
3622@opindex di
3623@opindex fdump-rtl-sibling
3624Dump after sibling call optimizations, to @file{@var{file}.106r.sibling}.
3625
3626@item -dj
3627@itemx -fdump-rtl-jump
3628@opindex dj
3629@opindex fdump-rtl-jump
3630Dump after the first jump optimization, to @file{@var{file}.112r.jump}.
3631
3632@item -dk
3633@itemx -fdump-rtl-stack
3634@opindex dk
3635@opindex fdump-rtl-stack
3636Dump after conversion from registers to stack, to @file{@var{file}.152r.stack}.
3637
3638@item -dl
3639@itemx -fdump-rtl-lreg
3640@opindex dl
3641@opindex fdump-rtl-lreg
3642Dump after local register allocation, to @file{@var{file}.138r.lreg}.
3643
3644@item -dL
3645@itemx -fdump-rtl-loop2
3646@opindex dL
3647@opindex fdump-rtl-loop2
3648@option{-dL} and @option{-fdump-rtl-loop2} enable dumping after the
3649loop optimization pass, to @file{@var{file}.119r.loop2},
3650@file{@var{file}.120r.loop2_init},
3651@file{@var{file}.121r.loop2_invariant}, and
3652@file{@var{file}.125r.loop2_done}.
3653
3654@item -dm
3655@itemx -fdump-rtl-sms
3656@opindex dm
3657@opindex fdump-rtl-sms
3658Dump after modulo scheduling, to @file{@var{file}.136r.sms}.
3659
3660@item -dM
3661@itemx -fdump-rtl-mach
3662@opindex dM
3663@opindex fdump-rtl-mach
3664Dump after performing the machine dependent reorganization pass, to
3665@file{@var{file}.155r.mach}.
3666
3667@item -dn
3668@itemx -fdump-rtl-rnreg
3669@opindex dn
3670@opindex fdump-rtl-rnreg
3671Dump after register renumbering, to @file{@var{file}.147r.rnreg}.
3672
3673@item -dN
3674@itemx -fdump-rtl-regmove
3675@opindex dN
3676@opindex fdump-rtl-regmove
3677Dump after the register move pass, to @file{@var{file}.132r.regmove}.
3678
3679@item -do
3680@itemx -fdump-rtl-postreload
3681@opindex do
3682@opindex fdump-rtl-postreload
3683Dump after post-reload optimizations, to @file{@var{file}.24.postreload}.
3684
3685@item -dr
3686@itemx -fdump-rtl-expand
3687@opindex dr
3688@opindex fdump-rtl-expand
3689Dump after RTL generation, to @file{@var{file}.104r.expand}.
3690
3691@item -dR
3692@itemx -fdump-rtl-sched2
3693@opindex dR
3694@opindex fdump-rtl-sched2
3695Dump after the second scheduling pass, to @file{@var{file}.150r.sched2}.
3696
3697@item -ds
3698@itemx -fdump-rtl-cse
3699@opindex ds
3700@opindex fdump-rtl-cse
3701Dump after CSE (including the jump optimization that sometimes follows
3702CSE), to @file{@var{file}.113r.cse}.
3703
3704@item -dS
3705@itemx -fdump-rtl-sched
3706@opindex dS
3707@opindex fdump-rtl-sched
3708Dump after the first scheduling pass, to @file{@var{file}.21.sched}.
3709
3710@item -dt
3711@itemx -fdump-rtl-cse2
3712@opindex dt
3713@opindex fdump-rtl-cse2
3714Dump after the second CSE pass (including the jump optimization that
3715sometimes follows CSE), to @file{@var{file}.127r.cse2}.
3716
3717@item -dT
3718@itemx -fdump-rtl-tracer
3719@opindex dT
3720@opindex fdump-rtl-tracer
3721Dump after running tracer, to @file{@var{file}.118r.tracer}.
3722
3723@item -dV
3724@itemx -fdump-rtl-vpt
3725@itemx -fdump-rtl-vartrack
3726@opindex dV
3727@opindex fdump-rtl-vpt
3728@opindex fdump-rtl-vartrack
3729@option{-dV} and @option{-fdump-rtl-vpt} enable dumping after the value
3730profile transformations, to @file{@var{file}.10.vpt}. @option{-dV}
3731and @option{-fdump-rtl-vartrack} enable dumping after variable tracking,
3732to @file{@var{file}.154r.vartrack}.
3733
3734@item -dw
3735@itemx -fdump-rtl-flow2
3736@opindex dw
3737@opindex fdump-rtl-flow2
3738Dump after the second flow pass, to @file{@var{file}.142r.flow2}.
3739
3740@item -dz
3741@itemx -fdump-rtl-peephole2
3742@opindex dz
3743@opindex fdump-rtl-peephole2
3744Dump after the peephole pass, to @file{@var{file}.145r.peephole2}.
3745
3746@item -dZ
3747@itemx -fdump-rtl-web
3748@opindex dZ
3749@opindex fdump-rtl-web
3750Dump after live range splitting, to @file{@var{file}.126r.web}.
3751
3752@item -da
3753@itemx -fdump-rtl-all
3754@opindex da
3755@opindex fdump-rtl-all
3756Produce all the dumps listed above.
3757
3758@item -dH
3759@opindex dH
3760Produce a core dump whenever an error occurs.
3761
3762@item -dm
3763@opindex dm
3764Print statistics on memory usage, at the end of the run, to
3765standard error.
3766
3767@item -dp
3768@opindex dp
3769Annotate the assembler output with a comment indicating which
3770pattern and alternative was used. The length of each instruction is
3771also printed.
3772
3773@item -dP
3774@opindex dP
3775Dump the RTL in the assembler output as a comment before each instruction.
3776Also turns on @option{-dp} annotation.
3777
3778@item -dv
3779@opindex dv
3780For each of the other indicated dump files (either with @option{-d} or
3781@option{-fdump-rtl-@var{pass}}), dump a representation of the control flow
3782graph suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
3783
3784@item -dx
3785@opindex dx
3786Just generate RTL for a function instead of compiling it. Usually used
3787with @samp{r} (@option{-fdump-rtl-expand}).
3788
3789@item -dy
3790@opindex dy
3791Dump debugging information during parsing, to standard error.
3792@end table
3793
3794@item -fdump-noaddr
3795@opindex fdump-noaddr
3796When doing debugging dumps (see @option{-d} option above), suppress
3797address output. This makes it more feasible to use diff on debugging
3798dumps for compiler invocations with different compiler binaries and/or
3799different text / bss / data / heap / stack / dso start locations.
3800
3801@item -fdump-unnumbered
3802@opindex fdump-unnumbered
3803When doing debugging dumps (see @option{-d} option above), suppress instruction
3804numbers, line number note and address output. This makes it more feasible to
3805use diff on debugging dumps for compiler invocations with different
3806options, in particular with and without @option{-g}.
3807
3808@item -fdump-translation-unit @r{(C++ only)}
3809@itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
3810@opindex fdump-translation-unit
3811Dump a representation of the tree structure for the entire translation
3812unit to a file. The file name is made by appending @file{.tu} to the
3813source file name. If the @samp{-@var{options}} form is used, @var{options}
3814controls the details of the dump as described for the
3815@option{-fdump-tree} options.
3816
3817@item -fdump-class-hierarchy @r{(C++ only)}
3818@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
3819@opindex fdump-class-hierarchy
3820Dump a representation of each class's hierarchy and virtual function
3821table layout to a file. The file name is made by appending @file{.class}
3822to the source file name. If the @samp{-@var{options}} form is used,
3823@var{options} controls the details of the dump as described for the
3824@option{-fdump-tree} options.
3825
3826@item -fdump-ipa-@var{switch}
3827@opindex fdump-ipa
3828Control the dumping at various stages of inter-procedural analysis
3829language tree to a file. The file name is generated by appending a switch
3830specific suffix to the source file name. The following dumps are possible:
3831
3832@table @samp
3833@item all
3834Enables all inter-procedural analysis dumps; currently the only produced
3835dump is the @samp{cgraph} dump.
3836
3837@item cgraph
3838Dumps information about call-graph optimization, unused function removal,
3839and inlining decisions.
3840@end table
3841
3842@item -fdump-tree-@var{switch}
3843@itemx -fdump-tree-@var{switch}-@var{options}
3844@opindex fdump-tree
3845Control the dumping at various stages of processing the intermediate
3846language tree to a file. The file name is generated by appending a switch
3847specific suffix to the source file name. If the @samp{-@var{options}}
3848form is used, @var{options} is a list of @samp{-} separated options that
3849control the details of the dump. Not all options are applicable to all
3850dumps, those which are not meaningful will be ignored. The following
3851options are available
3852
3853@table @samp
3854@item address
3855Print the address of each node. Usually this is not meaningful as it
3856changes according to the environment and source file. Its primary use
3857is for tying up a dump file with a debug environment.
3858@item slim
3859Inhibit dumping of members of a scope or body of a function merely
3860because that scope has been reached. Only dump such items when they
3861are directly reachable by some other path. When dumping pretty-printed
3862trees, this option inhibits dumping the bodies of control structures.
3863@item raw
3864Print a raw representation of the tree. By default, trees are
3865pretty-printed into a C-like representation.
3866@item details
3867Enable more detailed dumps (not honored by every dump option).
3868@item stats
3869Enable dumping various statistics about the pass (not honored by every dump
3870option).
3871@item blocks
3872Enable showing basic block boundaries (disabled in raw dumps).
3873@item vops
3874Enable showing virtual operands for every statement.
3875@item lineno
3876Enable showing line numbers for statements.
3877@item uid
3878Enable showing the unique ID (@code{DECL_UID}) for each variable.
3879@item all
3880Turn on all options, except @option{raw}, @option{slim} and @option{lineno}.
3881@end table
3882
3883The following tree dumps are possible:
3884@table @samp
3885
3886@item original
3887Dump before any tree based optimization, to @file{@var{file}.original}.
3888
3889@item optimized
3890Dump after all tree based optimization, to @file{@var{file}.optimized}.
3891
3892@item inlined
3893Dump after function inlining, to @file{@var{file}.inlined}.
3894
3895@item gimple
3896@opindex fdump-tree-gimple
3897Dump each function before and after the gimplification pass to a file. The
3898file name is made by appending @file{.gimple} to the source file name.
3899
3900@item cfg
3901@opindex fdump-tree-cfg
3902Dump the control flow graph of each function to a file. The file name is
3903made by appending @file{.cfg} to the source file name.
3904
3905@item vcg
3906@opindex fdump-tree-vcg
3907Dump the control flow graph of each function to a file in VCG format. The
3908file name is made by appending @file{.vcg} to the source file name. Note
3909that if the file contains more than one function, the generated file cannot
3910be used directly by VCG@. You will need to cut and paste each function's
3911graph into its own separate file first.
3912
3913@item ch
3914@opindex fdump-tree-ch
3915Dump each function after copying loop headers. The file name is made by
3916appending @file{.ch} to the source file name.
3917
3918@item ssa
3919@opindex fdump-tree-ssa
3920Dump SSA related information to a file. The file name is made by appending
3921@file{.ssa} to the source file name.
3922
3923@item salias
3924@opindex fdump-tree-salias
3925Dump structure aliasing variable information to a file. This file name
3926is made by appending @file{.salias} to the source file name.
3927
3928@item alias
3929@opindex fdump-tree-alias
3930Dump aliasing information for each function. The file name is made by
3931appending @file{.alias} to the source file name.
3932
3933@item ccp
3934@opindex fdump-tree-ccp
3935Dump each function after CCP@. The file name is made by appending
3936@file{.ccp} to the source file name.
3937
3938@item storeccp
3939@opindex fdump-tree-storeccp
3940Dump each function after STORE-CCP. The file name is made by appending
3941@file{.storeccp} to the source file name.
3942
3943@item pre
3944@opindex fdump-tree-pre
3945Dump trees after partial redundancy elimination. The file name is made
3946by appending @file{.pre} to the source file name.
3947
3948@item fre
3949@opindex fdump-tree-fre
3950Dump trees after full redundancy elimination. The file name is made
3951by appending @file{.fre} to the source file name.
3952
3953@item copyprop
3954@opindex fdump-tree-copyprop
3955Dump trees after copy propagation. The file name is made
3956by appending @file{.copyprop} to the source file name.
3957
3958@item store_copyprop
3959@opindex fdump-tree-store_copyprop
3960Dump trees after store copy-propagation. The file name is made
3961by appending @file{.store_copyprop} to the source file name.
3962
3963@item dce
3964@opindex fdump-tree-dce
3965Dump each function after dead code elimination. The file name is made by
3966appending @file{.dce} to the source file name.
3967
3968@item mudflap
3969@opindex fdump-tree-mudflap
3970Dump each function after adding mudflap instrumentation. The file name is
3971made by appending @file{.mudflap} to the source file name.
3972
3973@item sra
3974@opindex fdump-tree-sra
3975Dump each function after performing scalar replacement of aggregates. The
3976file name is made by appending @file{.sra} to the source file name.
3977
3978@item sink
3979@opindex fdump-tree-sink
3980Dump each function after performing code sinking. The file name is made
3981by appending @file{.sink} to the source file name.
3982
3983@item dom
3984@opindex fdump-tree-dom
3985Dump each function after applying dominator tree optimizations. The file
3986name is made by appending @file{.dom} to the source file name.
3987
3988@item dse
3989@opindex fdump-tree-dse
3990Dump each function after applying dead store elimination. The file
3991name is made by appending @file{.dse} to the source file name.
3992
3993@item phiopt
3994@opindex fdump-tree-phiopt
3995Dump each function after optimizing PHI nodes into straightline code. The file
3996name is made by appending @file{.phiopt} to the source file name.
3997
3998@item forwprop
3999@opindex fdump-tree-forwprop
4000Dump each function after forward propagating single use variables. The file
4001name is made by appending @file{.forwprop} to the source file name.
4002
4003@item copyrename
4004@opindex fdump-tree-copyrename
4005Dump each function after applying the copy rename optimization. The file
4006name is made by appending @file{.copyrename} to the source file name.
4007
4008@item nrv
4009@opindex fdump-tree-nrv
4010Dump each function after applying the named return value optimization on
4011generic trees. The file name is made by appending @file{.nrv} to the source
4012file name.
4013
4014@item vect
4015@opindex fdump-tree-vect
4016Dump each function after applying vectorization of loops. The file name is
4017made by appending @file{.vect} to the source file name.
4018
4019@item vrp
4020@opindex fdump-tree-vrp
4021Dump each function after Value Range Propagation (VRP). The file name
4022is made by appending @file{.vrp} to the source file name.
4023
4024@item all
4025@opindex fdump-tree-all
4026Enable all the available tree dumps with the flags provided in this option.
4027@end table
4028
4029@item -ftree-vectorizer-verbose=@var{n}
4030@opindex ftree-vectorizer-verbose
4031This option controls the amount of debugging output the vectorizer prints.
4032This information is written to standard error, unless
4033@option{-fdump-tree-all} or @option{-fdump-tree-vect} is specified,
4034in which case it is output to the usual dump listing file, @file{.vect}.
4035For @var{n}=0 no diagnostic information is reported.
4036If @var{n}=1 the vectorizer reports each loop that got vectorized,
4037and the total number of loops that got vectorized.
4038If @var{n}=2 the vectorizer also reports non-vectorized loops that passed
4039the first analysis phase (vect_analyze_loop_form) - i.e. countable,
4040inner-most, single-bb, single-entry/exit loops. This is the same verbosity
4041level that @option{-fdump-tree-vect-stats} uses.
4042Higher verbosity levels mean either more information dumped for each
4043reported loop, or same amount of information reported for more loops:
4044If @var{n}=3, alignment related information is added to the reports.
4045If @var{n}=4, data-references related information (e.g. memory dependences,
4046memory access-patterns) is added to the reports.
4047If @var{n}=5, the vectorizer reports also non-vectorized inner-most loops
4048that did not pass the first analysis phase (i.e. may not be countable, or
4049may have complicated control-flow).
4050If @var{n}=6, the vectorizer reports also non-vectorized nested loops.
4051For @var{n}=7, all the information the vectorizer generates during its
4052analysis and transformation is reported. This is the same verbosity level
4053that @option{-fdump-tree-vect-details} uses.
4054
4055@item -frandom-seed=@var{string}
4056@opindex frandom-string
4057This option provides a seed that GCC uses when it would otherwise use
4058random numbers. It is used to generate certain symbol names
4059that have to be different in every compiled file. It is also used to
4060place unique stamps in coverage data files and the object files that
4061produce them. You can use the @option{-frandom-seed} option to produce
4062reproducibly identical object files.
4063
4064The @var{string} should be different for every file you compile.
4065
4066@item -fsched-verbose=@var{n}
4067@opindex fsched-verbose
4068On targets that use instruction scheduling, this option controls the
4069amount of debugging output the scheduler prints. This information is
4070written to standard error, unless @option{-dS} or @option{-dR} is
4071specified, in which case it is output to the usual dump
4072listing file, @file{.sched} or @file{.sched2} respectively. However
4073for @var{n} greater than nine, the output is always printed to standard
4074error.
4075
4076For @var{n} greater than zero, @option{-fsched-verbose} outputs the
4077same information as @option{-dRS}. For @var{n} greater than one, it
4078also output basic block probabilities, detailed ready list information
4079and unit/insn info. For @var{n} greater than two, it includes RTL
4080at abort point, control-flow and regions info. And for @var{n} over
4081four, @option{-fsched-verbose} also includes dependence info.
4082
4083@item -save-temps
4084@opindex save-temps
4085Store the usual ``temporary'' intermediate files permanently; place them
4086in the current directory and name them based on the source file. Thus,
4087compiling @file{foo.c} with @samp{-c -save-temps} would produce files
4088@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
4089preprocessed @file{foo.i} output file even though the compiler now
4090normally uses an integrated preprocessor.
4091
4092When used in combination with the @option{-x} command line option,
4093@option{-save-temps} is sensible enough to avoid over writing an
4094input source file with the same extension as an intermediate file.
4095The corresponding intermediate file may be obtained by renaming the
4096source file before using @option{-save-temps}.
4097
4098@item -time
4099@opindex time
4100Report the CPU time taken by each subprocess in the compilation
4101sequence. For C source files, this is the compiler proper and assembler
4102(plus the linker if linking is done). The output looks like this:
4103
4104@smallexample
4105# cc1 0.12 0.01
4106# as 0.00 0.01
4107@end smallexample
4108
4109The first number on each line is the ``user time'', that is time spent
4110executing the program itself. The second number is ``system time'',
4111time spent executing operating system routines on behalf of the program.
4112Both numbers are in seconds.
4113
4114@item -fvar-tracking
4115@opindex fvar-tracking
4116Run variable tracking pass. It computes where variables are stored at each
4117position in code. Better debugging information is then generated
4118(if the debugging information format supports this information).
4119
4120It is enabled by default when compiling with optimization (@option{-Os},
4121@option{-O}, @option{-O2}, ...), debugging information (@option{-g}) and
4122the debug info format supports it.
4123
4124@item -print-file-name=@var{library}
4125@opindex print-file-name
4126Print the full absolute name of the library file @var{library} that
4127would be used when linking---and don't do anything else. With this
4128option, GCC does not compile or link anything; it just prints the
4129file name.
4130
4131@item -print-multi-directory
4132@opindex print-multi-directory
4133Print the directory name corresponding to the multilib selected by any
4134other switches present in the command line. This directory is supposed
4135to exist in @env{GCC_EXEC_PREFIX}.
4136
4137@item -print-multi-lib
4138@opindex print-multi-lib
4139Print the mapping from multilib directory names to compiler switches
4140that enable them. The directory name is separated from the switches by
4141@samp{;}, and each switch starts with an @samp{@@} instead of the
4142@samp{-}, without spaces between multiple switches. This is supposed to
4143ease shell-processing.
4144
4145@item -print-prog-name=@var{program}
4146@opindex print-prog-name
4147Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
4148
4149@item -print-libgcc-file-name
4150@opindex print-libgcc-file-name
4151Same as @option{-print-file-name=libgcc.a}.
4152
4153This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
4154but you do want to link with @file{libgcc.a}. You can do
4155
4156@smallexample
4157gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
4158@end smallexample
4159
4160@item -print-search-dirs
4161@opindex print-search-dirs
4162Print the name of the configured installation directory and a list of
4163program and library directories @command{gcc} will search---and don't do anything else.
4164
4165This is useful when @command{gcc} prints the error message
4166@samp{installation problem, cannot exec cpp0: No such file or directory}.
4167To resolve this you either need to put @file{cpp0} and the other compiler
4168components where @command{gcc} expects to find them, or you can set the environment
4169variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
4170Don't forget the trailing @samp{/}.
4171@xref{Environment Variables}.
4172
4173@item -dumpmachine
4174@opindex dumpmachine
4175Print the compiler's target machine (for example,
4176@samp{i686-pc-linux-gnu})---and don't do anything else.
4177
4178@item -dumpversion
4179@opindex dumpversion
4180Print the compiler version (for example, @samp{3.0})---and don't do
4181anything else.
4182
4183@item -dumpspecs
4184@opindex dumpspecs
4185Print the compiler's built-in specs---and don't do anything else. (This
4186is used when GCC itself is being built.) @xref{Spec Files}.
4187
4188@item -feliminate-unused-debug-types
4189@opindex feliminate-unused-debug-types
4190Normally, when producing DWARF2 output, GCC will emit debugging
4191information for all types declared in a compilation
4192unit, regardless of whether or not they are actually used
4193in that compilation unit. Sometimes this is useful, such as
4194if, in the debugger, you want to cast a value to a type that is
4195not actually used in your program (but is declared). More often,
4196however, this results in a significant amount of wasted space.
4197With this option, GCC will avoid producing debug symbol output
4198for types that are nowhere used in the source file being compiled.
4199@end table
4200
4201@node Optimize Options
4202@section Options That Control Optimization
4203@cindex optimize options
4204@cindex options, optimization
4205
4206These options control various sorts of optimizations.
4207
4208Without any optimization option, the compiler's goal is to reduce the
4209cost of compilation and to make debugging produce the expected
4210results. Statements are independent: if you stop the program with a
4211breakpoint between statements, you can then assign a new value to any
4212variable or change the program counter to any other statement in the
4213function and get exactly the results you would expect from the source
4214code.
4215
4216Turning on optimization flags makes the compiler attempt to improve
4217the performance and/or code size at the expense of compilation time
4218and possibly the ability to debug the program.
4219
4220The compiler performs optimization based on the knowledge it has of
4221the program. Optimization levels @option{-O} and above, in
4222particular, enable @emph{unit-at-a-time} mode, which allows the
4223compiler to consider information gained from later functions in
4224the file when compiling a function. Compiling multiple files at
4225once to a single output file in @emph{unit-at-a-time} mode allows
4226the compiler to use information gained from all of the files when
4227compiling each of them.
4228
4229Not all optimizations are controlled directly by a flag. Only
4230optimizations that have a flag are listed.
4231
4232@table @gcctabopt
4233@item -O
4234@itemx -O1
4235@opindex O
4236@opindex O1
4237Optimize. Optimizing compilation takes somewhat more time, and a lot
4238more memory for a large function.
4239
4240With @option{-O}, the compiler tries to reduce code size and execution
4241time, without performing any optimizations that take a great deal of
4242compilation time.
4243
4244@option{-O} turns on the following optimization flags:
4245@gccoptlist{-fdefer-pop @gol
4246-fdelayed-branch @gol
4247-fguess-branch-probability @gol
4248-fcprop-registers @gol
4249-fif-conversion @gol
4250-fif-conversion2 @gol
4251-ftree-ccp @gol
4252-ftree-dce @gol
4253-ftree-dominator-opts @gol
4254-ftree-dse @gol
4255-ftree-ter @gol
4256-ftree-lrs @gol
4257-ftree-sra @gol
4258-ftree-copyrename @gol
4259-ftree-fre @gol
4260-ftree-ch @gol
4261-funit-at-a-time @gol
4262-fmerge-constants}
4263
4264@option{-O} also turns on @option{-fomit-frame-pointer} on machines
4265where doing so does not interfere with debugging.
4266
4267@item -O2
4268@opindex O2
4269Optimize even more. GCC performs nearly all supported optimizations
4270that do not involve a space-speed tradeoff. The compiler does not
4271perform loop unrolling or function inlining when you specify @option{-O2}.
4272As compared to @option{-O}, this option increases both compilation time
4273and the performance of the generated code.
4274
4275@option{-O2} turns on all optimization flags specified by @option{-O}. It
4276also turns on the following optimization flags:
4277@gccoptlist{-fthread-jumps @gol
4278-fcrossjumping @gol
4279-foptimize-sibling-calls @gol
4280-fcse-follow-jumps -fcse-skip-blocks @gol
4281-fgcse -fgcse-lm @gol
4282-fexpensive-optimizations @gol
4283-frerun-cse-after-loop @gol
4284-fcaller-saves @gol
4285-fpeephole2 @gol
4286-fschedule-insns -fschedule-insns2 @gol
4287-fsched-interblock -fsched-spec @gol
4288-fregmove @gol
4289-fstrict-aliasing -fstrict-overflow @gol
4290-fdelete-null-pointer-checks @gol
4291-freorder-blocks -freorder-functions @gol
4292-falign-functions -falign-jumps @gol
4293-falign-loops -falign-labels @gol
4294-ftree-vrp @gol
4295-ftree-pre}
4296
4297Please note the warning under @option{-fgcse} about
4298invoking @option{-O2} on programs that use computed gotos.
4299
4300@option{-O2} doesn't turn on @option{-ftree-vrp} for the Ada compiler.
4301This option must be explicitly specified on the command line to be
4302enabled for the Ada compiler.
4303
4304@item -O3
4305@opindex O3
4306Optimize yet more. @option{-O3} turns on all optimizations specified by
4307@option{-O2} and also turns on the @option{-finline-functions},
4308@option{-funswitch-loops} and @option{-fgcse-after-reload} options.
4309
4310@item -O0
4311@opindex O0
4312Do not optimize. This is the default.
4313
4314@item -Os
4315@opindex Os
4316Optimize for size. @option{-Os} enables all @option{-O2} optimizations that
4317do not typically increase code size. It also performs further
4318optimizations designed to reduce code size.
4319
4320@option{-Os} disables the following optimization flags:
4321@gccoptlist{-falign-functions -falign-jumps -falign-loops @gol
4322-falign-labels -freorder-blocks -freorder-blocks-and-partition @gol
4323-fprefetch-loop-arrays -ftree-vect-loop-version}
4324
4325If you use multiple @option{-O} options, with or without level numbers,
4326the last such option is the one that is effective.
4327@end table
4328
4329Options of the form @option{-f@var{flag}} specify machine-independent
4330flags. Most flags have both positive and negative forms; the negative
4331form of @option{-ffoo} would be @option{-fno-foo}. In the table
4332below, only one of the forms is listed---the one you typically will
4333use. You can figure out the other form by either removing @samp{no-}
4334or adding it.
4335
4336The following options control specific optimizations. They are either
4337activated by @option{-O} options or are related to ones that are. You
4338can use the following flags in the rare cases when ``fine-tuning'' of
4339optimizations to be performed is desired.
4340
4341@table @gcctabopt
4342@item -fno-default-inline
4343@opindex fno-default-inline
4344Do not make member functions inline by default merely because they are
4345defined inside the class scope (C++ only). Otherwise, when you specify
4346@w{@option{-O}}, member functions defined inside class scope are compiled
4347inline by default; i.e., you don't need to add @samp{inline} in front of
4348the member function name.
4349
4350@item -fno-defer-pop
4351@opindex fno-defer-pop
4352Always pop the arguments to each function call as soon as that function
4353returns. For machines which must pop arguments after a function call,
4354the compiler normally lets arguments accumulate on the stack for several
4355function calls and pops them all at once.
4356
4357Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4358
4359@item -fforce-mem
4360@opindex fforce-mem
4361Force memory operands to be copied into registers before doing
4362arithmetic on them. This produces better code by making all memory
4363references potential common subexpressions. When they are not common
4364subexpressions, instruction combination should eliminate the separate
4365register-load. This option is now a nop and will be removed in 4.3.
4366
4367@item -fforce-addr
4368@opindex fforce-addr
4369Force memory address constants to be copied into registers before
4370doing arithmetic on them.
4371
4372@item -fomit-frame-pointer
4373@opindex fomit-frame-pointer
4374Don't keep the frame pointer in a register for functions that
4375don't need one. This avoids the instructions to save, set up and
4376restore frame pointers; it also makes an extra register available
4377in many functions. @strong{It also makes debugging impossible on
4378some machines.}
4379
4380On some machines, such as the VAX, this flag has no effect, because
4381the standard calling sequence automatically handles the frame pointer
4382and nothing is saved by pretending it doesn't exist. The
4383machine-description macro @code{FRAME_POINTER_REQUIRED} controls
4384whether a target machine supports this flag. @xref{Registers,,Register
4385Usage, gccint, GNU Compiler Collection (GCC) Internals}.
4386
4387Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4388
4389@item -foptimize-sibling-calls
4390@opindex foptimize-sibling-calls
4391Optimize sibling and tail recursive calls.
4392
4393Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4394
4395@item -fno-inline
4396@opindex fno-inline
4397Don't pay attention to the @code{inline} keyword. Normally this option
4398is used to keep the compiler from expanding any functions inline.
4399Note that if you are not optimizing, no functions can be expanded inline.
4400
4401@item -finline-functions
4402@opindex finline-functions
4403Integrate all simple functions into their callers. The compiler
4404heuristically decides which functions are simple enough to be worth
4405integrating in this way.
4406
4407If all calls to a given function are integrated, and the function is
4408declared @code{static}, then the function is normally not output as
4409assembler code in its own right.
4410
4411Enabled at level @option{-O3}.
4412
4413@item -finline-functions-called-once
4414@opindex finline-functions-called-once
4415Consider all @code{static} functions called once for inlining into their
4416caller even if they are not marked @code{inline}. If a call to a given
4417function is integrated, then the function is not output as assembler code
4418in its own right.
4419
4420Enabled if @option{-funit-at-a-time} is enabled.
4421
4422@item -fearly-inlining
4423@opindex fearly-inlining
4424Inline functions marked by @code{always_inline} and functions whose body seems
4425smaller than the function call overhead early before doing
4426@option{-fprofile-generate} instrumentation and real inlining pass. Doing so
4427makes profiling significantly cheaper and usually inlining faster on programs
4428having large chains of nested wrapper functions.
4429
4430Enabled by default.
4431
4432@item -finline-limit=@var{n}
4433@opindex finline-limit
4434By default, GCC limits the size of functions that can be inlined. This flag
4435allows the control of this limit for functions that are explicitly marked as
4436inline (i.e., marked with the inline keyword or defined within the class
4437definition in c++). @var{n} is the size of functions that can be inlined in
4438number of pseudo instructions (not counting parameter handling). The default
4439value of @var{n} is 600.
4440Increasing this value can result in more inlined code at
4441the cost of compilation time and memory consumption. Decreasing usually makes
4442the compilation faster and less code will be inlined (which presumably
4443means slower programs). This option is particularly useful for programs that
4444use inlining heavily such as those based on recursive templates with C++.
4445
4446Inlining is actually controlled by a number of parameters, which may be
4447specified individually by using @option{--param @var{name}=@var{value}}.
4448The @option{-finline-limit=@var{n}} option sets some of these parameters
4449as follows:
4450
4451@table @gcctabopt
4452@item max-inline-insns-single
4453 is set to @var{n}/2.
4454@item max-inline-insns-auto
4455 is set to @var{n}/2.
4456@item min-inline-insns
4457 is set to 130 or @var{n}/4, whichever is smaller.
4458@item max-inline-insns-rtl
4459 is set to @var{n}.
4460@end table
4461
4462See below for a documentation of the individual
4463parameters controlling inlining.
4464
4465@emph{Note:} pseudo instruction represents, in this particular context, an
4466abstract measurement of function's size. In no way does it represent a count
4467of assembly instructions and as such its exact meaning might change from one
4468release to an another.
4469
4470@item -fkeep-inline-functions
4471@opindex fkeep-inline-functions
4472In C, emit @code{static} functions that are declared @code{inline}
4473into the object file, even if the function has been inlined into all
4474of its callers. This switch does not affect functions using the
4475@code{extern inline} extension in GNU C@. In C++, emit any and all
4476inline functions into the object file.
4477
4478@item -fkeep-static-consts
4479@opindex fkeep-static-consts
4480Emit variables declared @code{static const} when optimization isn't turned
4481on, even if the variables aren't referenced.
4482
4483GCC enables this option by default. If you want to force the compiler to
4484check if the variable was referenced, regardless of whether or not
4485optimization is turned on, use the @option{-fno-keep-static-consts} option.
4486
4487@item -fmerge-constants
4488Attempt to merge identical constants (string constants and floating point
4489constants) across compilation units.
4490
4491This option is the default for optimized compilation if the assembler and
4492linker support it. Use @option{-fno-merge-constants} to inhibit this
4493behavior.
4494
4495Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4496
4497@item -fmerge-all-constants
4498Attempt to merge identical constants and identical variables.
4499
4500This option implies @option{-fmerge-constants}. In addition to
4501@option{-fmerge-constants} this considers e.g.@: even constant initialized
4502arrays or initialized constant variables with integral or floating point
4503types. Languages like C or C++ require each non-automatic variable to
4504have distinct location, so using this option will result in non-conforming
4505behavior.
4506
4507@item -fmodulo-sched
4508@opindex fmodulo-sched
4509Perform swing modulo scheduling immediately before the first scheduling
4510pass. This pass looks at innermost loops and reorders their
4511instructions by overlapping different iterations.
4512
4513@item -fno-branch-count-reg
4514@opindex fno-branch-count-reg
4515Do not use ``decrement and branch'' instructions on a count register,
4516but instead generate a sequence of instructions that decrement a
4517register, compare it against zero, then branch based upon the result.
4518This option is only meaningful on architectures that support such
4519instructions, which include x86, PowerPC, IA-64 and S/390.
4520
4521The default is @option{-fbranch-count-reg}.
4522
4523@item -fno-function-cse
4524@opindex fno-function-cse
4525Do not put function addresses in registers; make each instruction that
4526calls a constant function contain the function's address explicitly.
4527
4528This option results in less efficient code, but some strange hacks
4529that alter the assembler output may be confused by the optimizations
4530performed when this option is not used.
4531
4532The default is @option{-ffunction-cse}
4533
4534@item -fno-zero-initialized-in-bss
4535@opindex fno-zero-initialized-in-bss
4536If the target supports a BSS section, GCC by default puts variables that
4537are initialized to zero into BSS@. This can save space in the resulting
4538code.
4539
4540This option turns off this behavior because some programs explicitly
4541rely on variables going to the data section. E.g., so that the
4542resulting executable can find the beginning of that section and/or make
4543assumptions based on that.
4544
4545The default is @option{-fzero-initialized-in-bss}.
4546
4547@item -fbounds-check
4548@opindex fbounds-check
4549For front-ends that support it, generate additional code to check that
4550indices used to access arrays are within the declared range. This is
4551currently only supported by the Java and Fortran front-ends, where
4552this option defaults to true and false respectively.
4553
4554@item -fmudflap -fmudflapth -fmudflapir
4555@opindex fmudflap
4556@opindex fmudflapth
4557@opindex fmudflapir
4558@cindex bounds checking
4559@cindex mudflap
4560For front-ends that support it (C and C++), instrument all risky
4561pointer/array dereferencing operations, some standard library
4562string/heap functions, and some other associated constructs with
4563range/validity tests. Modules so instrumented should be immune to
4564buffer overflows, invalid heap use, and some other classes of C/C++
4565programming errors. The instrumentation relies on a separate runtime
4566library (@file{libmudflap}), which will be linked into a program if
4567@option{-fmudflap} is given at link time. Run-time behavior of the
4568instrumented program is controlled by the @env{MUDFLAP_OPTIONS}
4569environment variable. See @code{env MUDFLAP_OPTIONS=-help a.out}
4570for its options.
4571
4572Use @option{-fmudflapth} instead of @option{-fmudflap} to compile and to
4573link if your program is multi-threaded. Use @option{-fmudflapir}, in
4574addition to @option{-fmudflap} or @option{-fmudflapth}, if
4575instrumentation should ignore pointer reads. This produces less
4576instrumentation (and therefore faster execution) and still provides
4577some protection against outright memory corrupting writes, but allows
4578erroneously read data to propagate within a program.
4579
4580@item -fthread-jumps
4581@opindex fthread-jumps
4582Perform optimizations where we check to see if a jump branches to a
4583location where another comparison subsumed by the first is found. If
4584so, the first branch is redirected to either the destination of the
4585second branch or a point immediately following it, depending on whether
4586the condition is known to be true or false.
4587
4588Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4589
4590@item -fcse-follow-jumps
4591@opindex fcse-follow-jumps
4592In common subexpression elimination, scan through jump instructions
4593when the target of the jump is not reached by any other path. For
4594example, when CSE encounters an @code{if} statement with an
4595@code{else} clause, CSE will follow the jump when the condition
4596tested is false.
4597
4598Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4599
4600@item -fcse-skip-blocks
4601@opindex fcse-skip-blocks
4602This is similar to @option{-fcse-follow-jumps}, but causes CSE to
4603follow jumps which conditionally skip over blocks. When CSE
4604encounters a simple @code{if} statement with no else clause,
4605@option{-fcse-skip-blocks} causes CSE to follow the jump around the
4606body of the @code{if}.
4607
4608Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4609
4610@item -frerun-cse-after-loop
4611@opindex frerun-cse-after-loop
4612Re-run common subexpression elimination after loop optimizations has been
4613performed.
4614
4615Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4616
4617@item -fgcse
4618@opindex fgcse
4619Perform a global common subexpression elimination pass.
4620This pass also performs global constant and copy propagation.
4621
4622@emph{Note:} When compiling a program using computed gotos, a GCC
4623extension, you may get better runtime performance if you disable
4624the global common subexpression elimination pass by adding
4625@option{-fno-gcse} to the command line.
4626
4627Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4628
4629@item -fgcse-lm
4630@opindex fgcse-lm
4631When @option{-fgcse-lm} is enabled, global common subexpression elimination will
4632attempt to move loads which are only killed by stores into themselves. This
4633allows a loop containing a load/store sequence to be changed to a load outside
4634the loop, and a copy/store within the loop.
4635
4636Enabled by default when gcse is enabled.
4637
4638@item -fgcse-sm
4639@opindex fgcse-sm
4640When @option{-fgcse-sm} is enabled, a store motion pass is run after
4641global common subexpression elimination. This pass will attempt to move
4642stores out of loops. When used in conjunction with @option{-fgcse-lm},
4643loops containing a load/store sequence can be changed to a load before
4644the loop and a store after the loop.
4645
4646Not enabled at any optimization level.
4647
4648@item -fgcse-las
4649@opindex fgcse-las
4650When @option{-fgcse-las} is enabled, the global common subexpression
4651elimination pass eliminates redundant loads that come after stores to the
4652same memory location (both partial and full redundancies).
4653
4654Not enabled at any optimization level.
4655
4656@item -fgcse-after-reload
4657@opindex fgcse-after-reload
4658When @option{-fgcse-after-reload} is enabled, a redundant load elimination
4659pass is performed after reload. The purpose of this pass is to cleanup
4660redundant spilling.
4661
4662@item -funsafe-loop-optimizations
4663@opindex funsafe-loop-optimizations
4664If given, the loop optimizer will assume that loop indices do not
4665overflow, and that the loops with nontrivial exit condition are not
4666infinite. This enables a wider range of loop optimizations even if
4667the loop optimizer itself cannot prove that these assumptions are valid.
4668Using @option{-Wunsafe-loop-optimizations}, the compiler will warn you
4669if it finds this kind of loop.
4670
4671@item -fcrossjumping
4672@opindex crossjumping
4673Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
4674resulting code may or may not perform better than without cross-jumping.
4675
4676Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4677
4678@item -fif-conversion
4679@opindex if-conversion
4680Attempt to transform conditional jumps into branch-less equivalents. This
4681include use of conditional moves, min, max, set flags and abs instructions, and
4682some tricks doable by standard arithmetics. The use of conditional execution
4683on chips where it is available is controlled by @code{if-conversion2}.
4684
4685Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4686
4687@item -fif-conversion2
4688@opindex if-conversion2
4689Use conditional execution (where available) to transform conditional jumps into
4690branch-less equivalents.
4691
4692Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4693
4694@item -fdelete-null-pointer-checks
4695@opindex fdelete-null-pointer-checks
4696Use global dataflow analysis to identify and eliminate useless checks
4697for null pointers. The compiler assumes that dereferencing a null
4698pointer would have halted the program. If a pointer is checked after
4699it has already been dereferenced, it cannot be null.
4700
4701In some environments, this assumption is not true, and programs can
4702safely dereference null pointers. Use
4703@option{-fno-delete-null-pointer-checks} to disable this optimization
4704for programs which depend on that behavior.
4705
4706Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4707
4708@item -fexpensive-optimizations
4709@opindex fexpensive-optimizations
4710Perform a number of minor optimizations that are relatively expensive.
4711
4712Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4713
4714@item -foptimize-register-move
4715@itemx -fregmove
4716@opindex foptimize-register-move
4717@opindex fregmove
4718Attempt to reassign register numbers in move instructions and as
4719operands of other simple instructions in order to maximize the amount of
4720register tying. This is especially helpful on machines with two-operand
4721instructions.
4722
4723Note @option{-fregmove} and @option{-foptimize-register-move} are the same
4724optimization.
4725
4726Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4727
4728@item -fdelayed-branch
4729@opindex fdelayed-branch
4730If supported for the target machine, attempt to reorder instructions
4731to exploit instruction slots available after delayed branch
4732instructions.
4733
4734Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4735
4736@item -fschedule-insns
4737@opindex fschedule-insns
4738If supported for the target machine, attempt to reorder instructions to
4739eliminate execution stalls due to required data being unavailable. This
4740helps machines that have slow floating point or memory load instructions
4741by allowing other instructions to be issued until the result of the load
4742or floating point instruction is required.
4743
4744Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4745
4746@item -fschedule-insns2
4747@opindex fschedule-insns2
4748Similar to @option{-fschedule-insns}, but requests an additional pass of
4749instruction scheduling after register allocation has been done. This is
4750especially useful on machines with a relatively small number of
4751registers and where memory load instructions take more than one cycle.
4752
4753Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4754
4755@item -fno-sched-interblock
4756@opindex fno-sched-interblock
4757Don't schedule instructions across basic blocks. This is normally
4758enabled by default when scheduling before register allocation, i.e.@:
4759with @option{-fschedule-insns} or at @option{-O2} or higher.
4760
4761@item -fno-sched-spec
4762@opindex fno-sched-spec
4763Don't allow speculative motion of non-load instructions. This is normally
4764enabled by default when scheduling before register allocation, i.e.@:
4765with @option{-fschedule-insns} or at @option{-O2} or higher.
4766
4767@item -fsched-spec-load
4768@opindex fsched-spec-load
4769Allow speculative motion of some load instructions. This only makes
4770sense when scheduling before register allocation, i.e.@: with
4771@option{-fschedule-insns} or at @option{-O2} or higher.
4772
4773@item -fsched-spec-load-dangerous
4774@opindex fsched-spec-load-dangerous
4775Allow speculative motion of more load instructions. This only makes
4776sense when scheduling before register allocation, i.e.@: with
4777@option{-fschedule-insns} or at @option{-O2} or higher.
4778
4779@item -fsched-stalled-insns=@var{n}
4780@opindex fsched-stalled-insns
4781Define how many insns (if any) can be moved prematurely from the queue
4782of stalled insns into the ready list, during the second scheduling pass.
4783
4784@item -fsched-stalled-insns-dep=@var{n}
4785@opindex fsched-stalled-insns-dep
4786Define how many insn groups (cycles) will be examined for a dependency
4787on a stalled insn that is candidate for premature removal from the queue
4788of stalled insns. Has an effect only during the second scheduling pass,
4789and only if @option{-fsched-stalled-insns} is used and its value is not zero.
4790
4791@item -fsched2-use-superblocks
4792@opindex fsched2-use-superblocks
4793When scheduling after register allocation, do use superblock scheduling
4794algorithm. Superblock scheduling allows motion across basic block boundaries
4795resulting on faster schedules. This option is experimental, as not all machine
4796descriptions used by GCC model the CPU closely enough to avoid unreliable
4797results from the algorithm.
4798
4799This only makes sense when scheduling after register allocation, i.e.@: with
4800@option{-fschedule-insns2} or at @option{-O2} or higher.
4801
4802@item -fsched2-use-traces
4803@opindex fsched2-use-traces
4804Use @option{-fsched2-use-superblocks} algorithm when scheduling after register
4805allocation and additionally perform code duplication in order to increase the
4806size of superblocks using tracer pass. See @option{-ftracer} for details on
4807trace formation.
4808
4809This mode should produce faster but significantly longer programs. Also
4810without @option{-fbranch-probabilities} the traces constructed may not
4811match the reality and hurt the performance. This only makes
4812sense when scheduling after register allocation, i.e.@: with
4813@option{-fschedule-insns2} or at @option{-O2} or higher.
4814
4815@item -fsee
4816@opindex fsee
4817Eliminates redundant extension instructions and move the non redundant
4818ones to optimal placement using LCM.
4819
4820@item -freschedule-modulo-scheduled-loops
4821@opindex fscheduling-in-modulo-scheduled-loops
4822The modulo scheduling comes before the traditional scheduling, if a loop was modulo scheduled
4823we may want to prevent the later scheduling passes from changing its schedule, we use this
4824option to control that.
4825
4826@item -fcaller-saves
4827@opindex fcaller-saves
4828Enable values to be allocated in registers that will be clobbered by
4829function calls, by emitting extra instructions to save and restore the
4830registers around such calls. Such allocation is done only when it
4831seems to result in better code than would otherwise be produced.
4832
4833This option is always enabled by default on certain machines, usually
4834those which have no call-preserved registers to use instead.
4835
4836Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4837
4838@item -ftree-pre
4839Perform Partial Redundancy Elimination (PRE) on trees. This flag is
4840enabled by default at @option{-O2} and @option{-O3}.
4841
4842@item -ftree-fre
4843Perform Full Redundancy Elimination (FRE) on trees. The difference
4844between FRE and PRE is that FRE only considers expressions
4845that are computed on all paths leading to the redundant computation.
4846This analysis faster than PRE, though it exposes fewer redundancies.
4847This flag is enabled by default at @option{-O} and higher.
4848
4849@item -ftree-copy-prop
4850Perform copy propagation on trees. This pass eliminates unnecessary
4851copy operations. This flag is enabled by default at @option{-O} and
4852higher.
4853
4854@item -ftree-store-copy-prop
4855Perform copy propagation of memory loads and stores. This pass
4856eliminates unnecessary copy operations in memory references
4857(structures, global variables, arrays, etc). This flag is enabled by
4858default at @option{-O2} and higher.
4859
4860@item -ftree-salias
4861Perform structural alias analysis on trees. This flag
4862is enabled by default at @option{-O} and higher.
4863
4864@item -fipa-pta
4865Perform interprocedural pointer analysis.
4866
4867@item -ftree-sink
4868Perform forward store motion on trees. This flag is
4869enabled by default at @option{-O} and higher.
4870
4871@item -ftree-ccp
4872Perform sparse conditional constant propagation (CCP) on trees. This
4873pass only operates on local scalar variables and is enabled by default
4874at @option{-O} and higher.
4875
4876@item -ftree-store-ccp
4877Perform sparse conditional constant propagation (CCP) on trees. This
4878pass operates on both local scalar variables and memory stores and
4879loads (global variables, structures, arrays, etc). This flag is
4880enabled by default at @option{-O2} and higher.
4881
4882@item -ftree-dce
4883Perform dead code elimination (DCE) on trees. This flag is enabled by
4884default at @option{-O} and higher.
4885
4886@item -ftree-dominator-opts
4887Perform a variety of simple scalar cleanups (constant/copy
4888propagation, redundancy elimination, range propagation and expression
4889simplification) based on a dominator tree traversal. This also
4890performs jump threading (to reduce jumps to jumps). This flag is
4891enabled by default at @option{-O} and higher.
4892
4893@item -ftree-ch
4894Perform loop header copying on trees. This is beneficial since it increases
4895effectiveness of code motion optimizations. It also saves one jump. This flag
4896is enabled by default at @option{-O} and higher. It is not enabled
4897for @option{-Os}, since it usually increases code size.
4898
4899@item -ftree-loop-optimize
4900Perform loop optimizations on trees. This flag is enabled by default
4901at @option{-O} and higher.
4902
4903@item -ftree-loop-linear
4904Perform linear loop transformations on tree. This flag can improve cache
4905performance and allow further loop optimizations to take place.
4906
4907@item -ftree-loop-im
4908Perform loop invariant motion on trees. This pass moves only invariants that
4909would be hard to handle at RTL level (function calls, operations that expand to
4910nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
4911operands of conditions that are invariant out of the loop, so that we can use
4912just trivial invariantness analysis in loop unswitching. The pass also includes
4913store motion.
4914
4915@item -ftree-loop-ivcanon
4916Create a canonical counter for number of iterations in the loop for that
4917determining number of iterations requires complicated analysis. Later
4918optimizations then may determine the number easily. Useful especially
4919in connection with unrolling.
4920
4921@item -fivopts
4922Perform induction variable optimizations (strength reduction, induction
4923variable merging and induction variable elimination) on trees.
4924
4925@item -ftree-sra
4926Perform scalar replacement of aggregates. This pass replaces structure
4927references with scalars to prevent committing structures to memory too
4928early. This flag is enabled by default at @option{-O} and higher.
4929
4930@item -ftree-copyrename
4931Perform copy renaming on trees. This pass attempts to rename compiler
4932temporaries to other variables at copy locations, usually resulting in
4933variable names which more closely resemble the original variables. This flag
4934is enabled by default at @option{-O} and higher.
4935
4936@item -ftree-ter
4937Perform temporary expression replacement during the SSA->normal phase. Single
4938use/single def temporaries are replaced at their use location with their
4939defining expression. This results in non-GIMPLE code, but gives the expanders
4940much more complex trees to work on resulting in better RTL generation. This is
4941enabled by default at @option{-O} and higher.
4942
4943@item -ftree-lrs
4944Perform live range splitting during the SSA->normal phase. Distinct live
4945ranges of a variable are split into unique variables, allowing for better
4946optimization later. This is enabled by default at @option{-O} and higher.
4947
4948@item -ftree-vectorize
4949Perform loop vectorization on trees.
4950
4951@item -ftree-vect-loop-version
4952@opindex ftree-vect-loop-version
4953Perform loop versioning when doing loop vectorization on trees. When a loop
4954appears to be vectorizable except that data alignment or data dependence cannot
4955be determined at compile time then vectorized and non-vectorized versions of
4956the loop are generated along with runtime checks for alignment or dependence
4957to control which version is executed. This option is enabled by default
4958except at level @option{-Os} where it is disabled.
4959
4960@item -ftree-vrp
4961Perform Value Range Propagation on trees. This is similar to the
4962constant propagation pass, but instead of values, ranges of values are
4963propagated. This allows the optimizers to remove unnecessary range
4964checks like array bound checks and null pointer checks. This is
4965enabled by default at @option{-O2} and higher. Null pointer check
4966elimination is only done if @option{-fdelete-null-pointer-checks} is
4967enabled.
4968
4969@item -ftracer
4970@opindex ftracer
4971Perform tail duplication to enlarge superblock size. This transformation
4972simplifies the control flow of the function allowing other optimizations to do
4973better job.
4974
4975@item -funroll-loops
4976@opindex funroll-loops
4977Unroll loops whose number of iterations can be determined at compile
4978time or upon entry to the loop. @option{-funroll-loops} implies
4979@option{-frerun-cse-after-loop}. This option makes code larger,
4980and may or may not make it run faster.
4981
4982@item -funroll-all-loops
4983@opindex funroll-all-loops
4984Unroll all loops, even if their number of iterations is uncertain when
4985the loop is entered. This usually makes programs run more slowly.
4986@option{-funroll-all-loops} implies the same options as
4987@option{-funroll-loops},
4988
4989@item -fsplit-ivs-in-unroller
4990@opindex fsplit-ivs-in-unroller
4991Enables expressing of values of induction variables in later iterations
4992of the unrolled loop using the value in the first iteration. This breaks
4993long dependency chains, thus improving efficiency of the scheduling passes.
4994
4995Combination of @option{-fweb} and CSE is often sufficient to obtain the
4996same effect. However in cases the loop body is more complicated than
4997a single basic block, this is not reliable. It also does not work at all
4998on some of the architectures due to restrictions in the CSE pass.
4999
5000This optimization is enabled by default.
5001
5002@item -fvariable-expansion-in-unroller
5003@opindex fvariable-expansion-in-unroller
5004With this option, the compiler will create multiple copies of some
5005local variables when unrolling a loop which can result in superior code.
5006
5007@item -fprefetch-loop-arrays
5008@opindex fprefetch-loop-arrays
5009If supported by the target machine, generate instructions to prefetch
5010memory to improve the performance of loops that access large arrays.
5011
5012This option may generate better or worse code; results are highly
5013dependent on the structure of loops within the source code.
5014
5015Disabled at level @option{-Os}.
5016
5017@item -fno-peephole
5018@itemx -fno-peephole2
5019@opindex fno-peephole
5020@opindex fno-peephole2
5021Disable any machine-specific peephole optimizations. The difference
5022between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
5023are implemented in the compiler; some targets use one, some use the
5024other, a few use both.
5025
5026@option{-fpeephole} is enabled by default.
5027@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5028
5029@item -fno-guess-branch-probability
5030@opindex fno-guess-branch-probability
5031Do not guess branch probabilities using heuristics.
5032
5033GCC will use heuristics to guess branch probabilities if they are
5034not provided by profiling feedback (@option{-fprofile-arcs}). These
5035heuristics are based on the control flow graph. If some branch probabilities
5036are specified by @samp{__builtin_expect}, then the heuristics will be
5037used to guess branch probabilities for the rest of the control flow graph,
5038taking the @samp{__builtin_expect} info into account. The interactions
5039between the heuristics and @samp{__builtin_expect} can be complex, and in
5040some cases, it may be useful to disable the heuristics so that the effects
5041of @samp{__builtin_expect} are easier to understand.
5042
5043The default is @option{-fguess-branch-probability} at levels
5044@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5045
5046@item -freorder-blocks
5047@opindex freorder-blocks
5048Reorder basic blocks in the compiled function in order to reduce number of
5049taken branches and improve code locality.
5050
5051Enabled at levels @option{-O2}, @option{-O3}.
5052
5053@item -freorder-blocks-and-partition
5054@opindex freorder-blocks-and-partition
5055In addition to reordering basic blocks in the compiled function, in order
5056to reduce number of taken branches, partitions hot and cold basic blocks
5057into separate sections of the assembly and .o files, to improve
5058paging and cache locality performance.
5059
5060This optimization is automatically turned off in the presence of
5061exception handling, for linkonce sections, for functions with a user-defined
5062section attribute and on any architecture that does not support named
5063sections.
5064
5065@item -freorder-functions
5066@opindex freorder-functions
5067Reorder functions in the object file in order to
5068improve code locality. This is implemented by using special
5069subsections @code{.text.hot} for most frequently executed functions and
5070@code{.text.unlikely} for unlikely executed functions. Reordering is done by
5071the linker so object file format must support named sections and linker must
5072place them in a reasonable way.
5073
5074Also profile feedback must be available in to make this option effective. See
5075@option{-fprofile-arcs} for details.
5076
5077Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5078
5079@item -fstrict-aliasing
5080@opindex fstrict-aliasing
5081Allows the compiler to assume the strictest aliasing rules applicable to
5082the language being compiled. For C (and C++), this activates
5083optimizations based on the type of expressions. In particular, an
5084object of one type is assumed never to reside at the same address as an
5085object of a different type, unless the types are almost the same. For
5086example, an @code{unsigned int} can alias an @code{int}, but not a
5087@code{void*} or a @code{double}. A character type may alias any other
5088type.
5089
5090Pay special attention to code like this:
5091@smallexample
5092union a_union @{
5093 int i;
5094 double d;
5095@};
5096
5097int f() @{
5098 a_union t;
5099 t.d = 3.0;
5100 return t.i;
5101@}
5102@end smallexample
5103The practice of reading from a different union member than the one most
5104recently written to (called ``type-punning'') is common. Even with
5105@option{-fstrict-aliasing}, type-punning is allowed, provided the memory
5106is accessed through the union type. So, the code above will work as
5107expected. However, this code might not:
5108@smallexample
5109int f() @{
5110 a_union t;
5111 int* ip;
5112 t.d = 3.0;
5113 ip = &t.i;
5114 return *ip;
5115@}
5116@end smallexample
5117
5118Every language that wishes to perform language-specific alias analysis
5119should define a function that computes, given an @code{tree}
5120node, an alias set for the node. Nodes in different alias sets are not
5121allowed to alias. For an example, see the C front-end function
5122@code{c_get_alias_set}.
5123
5124Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5125
5126@item -fstrict-overflow
5127@opindex fstrict-overflow
5128Allow the compiler to assume strict signed overflow rules, depending
5129on the language being compiled. For C (and C++) this means that
5130overflow when doing arithmetic with signed numbers is undefined, which
5131means that the compiler may assume that it will not happen. This
5132permits various optimizations. For example, the compiler will assume
5133that an expression like @code{i + 10 > i} will always be true for
5134signed @code{i}. This assumption is only valid if signed overflow is
5135undefined, as the expression is false if @code{i + 10} overflows when
5136using twos complement arithmetic. When this option is in effect any
5137attempt to determine whether an operation on signed numbers will
5138overflow must be written carefully to not actually involve overflow.
5139
5140See also the @option{-fwrapv} option. Using @option{-fwrapv} means
5141that signed overflow is fully defined: it wraps. When
5142@option{-fwrapv} is used, there is no difference between
5143@option{-fstrict-overflow} and @option{-fno-strict-overflow}. With
5144@option{-fwrapv} certain types of overflow are permitted. For
5145example, if the compiler gets an overflow when doing arithmetic on
5146constants, the overflowed value can still be used with
5147@option{-fwrapv}, but not otherwise.
5148
5149The @option{-fstrict-overflow} option is enabled at levels
5150@option{-O2}, @option{-O3}, @option{-Os}.
5151
5152@item -falign-functions
5153@itemx -falign-functions=@var{n}
5154@opindex falign-functions
5155Align the start of functions to the next power-of-two greater than
5156@var{n}, skipping up to @var{n} bytes. For instance,
5157@option{-falign-functions=32} aligns functions to the next 32-byte
5158boundary, but @option{-falign-functions=24} would align to the next
515932-byte boundary only if this can be done by skipping 23 bytes or less.
5160
5161@option{-fno-align-functions} and @option{-falign-functions=1} are
5162equivalent and mean that functions will not be aligned.
5163
5164Some assemblers only support this flag when @var{n} is a power of two;
5165in that case, it is rounded up.
5166
5167If @var{n} is not specified or is zero, use a machine-dependent default.
5168
5169Enabled at levels @option{-O2}, @option{-O3}.
5170
5171@item -falign-labels
5172@itemx -falign-labels=@var{n}
5173@opindex falign-labels
5174Align all branch targets to a power-of-two boundary, skipping up to
5175@var{n} bytes like @option{-falign-functions}. This option can easily
5176make code slower, because it must insert dummy operations for when the
5177branch target is reached in the usual flow of the code.
5178
5179@option{-fno-align-labels} and @option{-falign-labels=1} are
5180equivalent and mean that labels will not be aligned.
5181
5182If @option{-falign-loops} or @option{-falign-jumps} are applicable and
5183are greater than this value, then their values are used instead.
5184
5185If @var{n} is not specified or is zero, use a machine-dependent default
5186which is very likely to be @samp{1}, meaning no alignment.
5187
5188Enabled at levels @option{-O2}, @option{-O3}.
5189
5190@item -falign-loops
5191@itemx -falign-loops=@var{n}
5192@opindex falign-loops
5193Align loops to a power-of-two boundary, skipping up to @var{n} bytes
5194like @option{-falign-functions}. The hope is that the loop will be
5195executed many times, which will make up for any execution of the dummy
5196operations.
5197
5198@option{-fno-align-loops} and @option{-falign-loops=1} are
5199equivalent and mean that loops will not be aligned.
5200
5201If @var{n} is not specified or is zero, use a machine-dependent default.
5202
5203Enabled at levels @option{-O2}, @option{-O3}.
5204
5205@item -falign-jumps
5206@itemx -falign-jumps=@var{n}
5207@opindex falign-jumps
5208Align branch targets to a power-of-two boundary, for branch targets
5209where the targets can only be reached by jumping, skipping up to @var{n}
5210bytes like @option{-falign-functions}. In this case, no dummy operations
5211need be executed.
5212
5213@option{-fno-align-jumps} and @option{-falign-jumps=1} are
5214equivalent and mean that loops will not be aligned.
5215
5216If @var{n} is not specified or is zero, use a machine-dependent default.
5217
5218Enabled at levels @option{-O2}, @option{-O3}.
5219
5220@item -funit-at-a-time
5221@opindex funit-at-a-time
5222Parse the whole compilation unit before starting to produce code.
5223This allows some extra optimizations to take place but consumes
5224more memory (in general). There are some compatibility issues
5225with @emph{unit-at-a-time} mode:
5226@itemize @bullet
5227@item
5228enabling @emph{unit-at-a-time} mode may change the order
5229in which functions, variables, and top-level @code{asm} statements
5230are emitted, and will likely break code relying on some particular
5231ordering. The majority of such top-level @code{asm} statements,
5232though, can be replaced by @code{section} attributes. The
5233@option{fno-toplevel-reorder} option may be used to keep the ordering
5234used in the input file, at the cost of some optimizations.
5235
5236@item
5237@emph{unit-at-a-time} mode removes unreferenced static variables
5238and functions. This may result in undefined references
5239when an @code{asm} statement refers directly to variables or functions
5240that are otherwise unused. In that case either the variable/function
5241shall be listed as an operand of the @code{asm} statement operand or,
5242in the case of top-level @code{asm} statements the attribute @code{used}
5243shall be used on the declaration.
5244
5245@item
5246Static functions now can use non-standard passing conventions that
5247may break @code{asm} statements calling functions directly. Again,
5248attribute @code{used} will prevent this behavior.
5249@end itemize
5250
5251As a temporary workaround, @option{-fno-unit-at-a-time} can be used,
5252but this scheme may not be supported by future releases of GCC@.
5253
5254Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5255
5256@item -fno-toplevel-reorder
5257Do not reorder top-level functions, variables, and @code{asm}
5258statements. Output them in the same order that they appear in the
5259input file. When this option is used, unreferenced static variables
5260will not be removed. This option is intended to support existing code
5261which relies on a particular ordering. For new code, it is better to
5262use attributes.
5263
5264@item -fweb
5265@opindex fweb
5266Constructs webs as commonly used for register allocation purposes and assign
5267each web individual pseudo register. This allows the register allocation pass
5268to operate on pseudos directly, but also strengthens several other optimization
5269passes, such as CSE, loop optimizer and trivial dead code remover. It can,
5270however, make debugging impossible, since variables will no longer stay in a
5271``home register''.
5272
5273Enabled by default with @option{-funroll-loops}.
5274
5275@item -fwhole-program
5276@opindex fwhole-program
5277Assume that the current compilation unit represents whole program being
5278compiled. All public functions and variables with the exception of @code{main}
5279and those merged by attribute @code{externally_visible} become static functions
5280and in a affect gets more aggressively optimized by interprocedural optimizers.
5281While this option is equivalent to proper use of @code{static} keyword for
5282programs consisting of single file, in combination with option
5283@option{--combine} this flag can be used to compile most of smaller scale C
5284programs since the functions and variables become local for the whole combined
5285compilation unit, not for the single source file itself.
5286
5287
5288@item -fno-cprop-registers
5289@opindex fno-cprop-registers
5290After register allocation and post-register allocation instruction splitting,
5291we perform a copy-propagation pass to try to reduce scheduling dependencies
5292and occasionally eliminate the copy.
5293
5294Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5295
5296@item -fprofile-generate
5297@opindex fprofile-generate
5298
5299Enable options usually used for instrumenting application to produce
5300profile useful for later recompilation with profile feedback based
5301optimization. You must use @option{-fprofile-generate} both when
5302compiling and when linking your program.
5303
5304The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
5305
5306@item -fprofile-use
5307@opindex fprofile-use
5308Enable profile feedback directed optimizations, and optimizations
5309generally profitable only with profile feedback available.
5310
5311The following options are enabled: @code{-fbranch-probabilities}, @code{-fvpt},
5312@code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}
5313
5314@end table
5315
5316The following options control compiler behavior regarding floating
5317point arithmetic. These options trade off between speed and
5318correctness. All must be specifically enabled.
5319
5320@table @gcctabopt
5321@item -ffloat-store
5322@opindex ffloat-store
5323Do not store floating point variables in registers, and inhibit other
5324options that might change whether a floating point value is taken from a
5325register or memory.
5326
5327@cindex floating point precision
5328This option prevents undesirable excess precision on machines such as
5329the 68000 where the floating registers (of the 68881) keep more
5330precision than a @code{double} is supposed to have. Similarly for the
5331x86 architecture. For most programs, the excess precision does only
5332good, but a few programs rely on the precise definition of IEEE floating
5333point. Use @option{-ffloat-store} for such programs, after modifying
5334them to store all pertinent intermediate computations into variables.
5335
5336@item -ffast-math
5337@opindex ffast-math
5338Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
5339@option{-fno-trapping-math}, @option{-ffinite-math-only},
5340@option{-fno-rounding-math}, @option{-fno-signaling-nans}
5341and @option{fcx-limited-range}.
5342
5343This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
5344
5345This option should never be turned on by any @option{-O} option since
5346it can result in incorrect output for programs which depend on
5347an exact implementation of IEEE or ISO rules/specifications for
5348math functions.
5349
5350@item -fno-math-errno
5351@opindex fno-math-errno
5352Do not set ERRNO after calling math functions that are executed
5353with a single instruction, e.g., sqrt. A program that relies on
5354IEEE exceptions for math error handling may want to use this flag
5355for speed while maintaining IEEE arithmetic compatibility.
5356
5357This option should never be turned on by any @option{-O} option since
5358it can result in incorrect output for programs which depend on
5359an exact implementation of IEEE or ISO rules/specifications for
5360math functions.
5361
5362The default is @option{-fmath-errno}.
5363
5364On Darwin and FreeBSD systems, the math library never sets @code{errno}.
5365There is therefore
5366no reason for the compiler to consider the possibility that it might,
5367and @option{-fno-math-errno} is the default.
5368
5369@item -funsafe-math-optimizations
5370@opindex funsafe-math-optimizations
5371Allow optimizations for floating-point arithmetic that (a) assume
5372that arguments and results are valid and (b) may violate IEEE or
5373ANSI standards. When used at link-time, it may include libraries
5374or startup files that change the default FPU control word or other
5375similar optimizations.
5376
5377This option should never be turned on by any @option{-O} option since
5378it can result in incorrect output for programs which depend on
5379an exact implementation of IEEE or ISO rules/specifications for
5380math functions.
5381
5382The default is @option{-fno-unsafe-math-optimizations}.
5383
5384@item -ffinite-math-only
5385@opindex ffinite-math-only
5386Allow optimizations for floating-point arithmetic that assume
5387that arguments and results are not NaNs or +-Infs.
5388
5389This option should never be turned on by any @option{-O} option since
5390it can result in incorrect output for programs which depend on
5391an exact implementation of IEEE or ISO rules/specifications.
5392
5393The default is @option{-fno-finite-math-only}.
5394
5395@item -fno-trapping-math
5396@opindex fno-trapping-math
5397Compile code assuming that floating-point operations cannot generate
5398user-visible traps. These traps include division by zero, overflow,
5399underflow, inexact result and invalid operation. This option implies
5400@option{-fno-signaling-nans}. Setting this option may allow faster
5401code if one relies on ``non-stop'' IEEE arithmetic, for example.
5402
5403This option should never be turned on by any @option{-O} option since
5404it can result in incorrect output for programs which depend on
5405an exact implementation of IEEE or ISO rules/specifications for
5406math functions.
5407
5408The default is @option{-ftrapping-math}.
5409
5410@item -frounding-math
5411@opindex frounding-math
5412Disable transformations and optimizations that assume default floating
5413point rounding behavior. This is round-to-zero for all floating point
5414to integer conversions, and round-to-nearest for all other arithmetic
5415truncations. This option should be specified for programs that change
5416the FP rounding mode dynamically, or that may be executed with a
5417non-default rounding mode. This option disables constant folding of
5418floating point expressions at compile-time (which may be affected by
5419rounding mode) and arithmetic transformations that are unsafe in the
5420presence of sign-dependent rounding modes.
5421
5422The default is @option{-fno-rounding-math}.
5423
5424This option is experimental and does not currently guarantee to
5425disable all GCC optimizations that are affected by rounding mode.
5426Future versions of GCC may provide finer control of this setting
5427using C99's @code{FENV_ACCESS} pragma. This command line option
5428will be used to specify the default state for @code{FENV_ACCESS}.
5429
5430@item -frtl-abstract-sequences
5431@opindex frtl-abstract-sequences
5432It is a size optimization method. This option is to find identical
5433sequences of code, which can be turned into pseudo-procedures and
5434then replace all occurrences with calls to the newly created
5435subroutine. It is kind of an opposite of @option{-finline-functions}.
5436This optimization runs at RTL level.
5437
5438@item -fsignaling-nans
5439@opindex fsignaling-nans
5440Compile code assuming that IEEE signaling NaNs may generate user-visible
5441traps during floating-point operations. Setting this option disables
5442optimizations that may change the number of exceptions visible with
5443signaling NaNs. This option implies @option{-ftrapping-math}.
5444
5445This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
5446be defined.
5447
5448The default is @option{-fno-signaling-nans}.
5449
5450This option is experimental and does not currently guarantee to
5451disable all GCC optimizations that affect signaling NaN behavior.
5452
5453@item -fsingle-precision-constant
5454@opindex fsingle-precision-constant
5455Treat floating point constant as single precision constant instead of
5456implicitly converting it to double precision constant.
5457
5458@item -fcx-limited-range
5459@itemx -fno-cx-limited-range
5460@opindex fcx-limited-range
5461@opindex fno-cx-limited-range
5462When enabled, this option states that a range reduction step is not
5463needed when performing complex division. The default is
5464@option{-fno-cx-limited-range}, but is enabled by @option{-ffast-math}.
5465
5466This option controls the default setting of the ISO C99
5467@code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to
5468all languages.
5469
5470@end table
5471
5472The following options control optimizations that may improve
5473performance, but are not enabled by any @option{-O} options. This
5474section includes experimental options that may produce broken code.
5475
5476@table @gcctabopt
5477@item -fbranch-probabilities
5478@opindex fbranch-probabilities
5479After running a program compiled with @option{-fprofile-arcs}
5480(@pxref{Debugging Options,, Options for Debugging Your Program or
5481@command{gcc}}), you can compile it a second time using
5482@option{-fbranch-probabilities}, to improve optimizations based on
5483the number of times each branch was taken. When the program
5484compiled with @option{-fprofile-arcs} exits it saves arc execution
5485counts to a file called @file{@var{sourcename}.gcda} for each source
5486file The information in this data file is very dependent on the
5487structure of the generated code, so you must use the same source code
5488and the same optimization options for both compilations.
5489
5490With @option{-fbranch-probabilities}, GCC puts a
5491@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
5492These can be used to improve optimization. Currently, they are only
5493used in one place: in @file{reorg.c}, instead of guessing which path a
5494branch is mostly to take, the @samp{REG_BR_PROB} values are used to
5495exactly determine which path is taken more often.
5496
5497@item -fprofile-values
5498@opindex fprofile-values
5499If combined with @option{-fprofile-arcs}, it adds code so that some
5500data about values of expressions in the program is gathered.
5501
5502With @option{-fbranch-probabilities}, it reads back the data gathered
5503from profiling values of expressions and adds @samp{REG_VALUE_PROFILE}
5504notes to instructions for their later usage in optimizations.
5505
5506Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
5507
5508@item -fvpt
5509@opindex fvpt
5510If combined with @option{-fprofile-arcs}, it instructs the compiler to add
5511a code to gather information about values of expressions.
5512
5513With @option{-fbranch-probabilities}, it reads back the data gathered
5514and actually performs the optimizations based on them.
5515Currently the optimizations include specialization of division operation
5516using the knowledge about the value of the denominator.
5517
5518@item -frename-registers
5519@opindex frename-registers
5520Attempt to avoid false dependencies in scheduled code by making use
5521of registers left over after register allocation. This optimization
5522will most benefit processors with lots of registers. Depending on the
5523debug information format adopted by the target, however, it can
5524make debugging impossible, since variables will no longer stay in
5525a ``home register''.
5526
5527Enabled by default with @option{-funroll-loops}.
5528
5529@item -ftracer
5530@opindex ftracer
5531Perform tail duplication to enlarge superblock size. This transformation
5532simplifies the control flow of the function allowing other optimizations to do
5533better job.
5534
5535Enabled with @option{-fprofile-use}.
5536
5537@item -funroll-loops
5538@opindex funroll-loops
5539Unroll loops whose number of iterations can be determined at compile time or
5540upon entry to the loop. @option{-funroll-loops} implies
5541@option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.
5542It also turns on complete loop peeling (i.e.@: complete removal of loops with
5543small constant number of iterations). This option makes code larger, and may
5544or may not make it run faster.
5545
5546Enabled with @option{-fprofile-use}.
5547
5548@item -funroll-all-loops
5549@opindex funroll-all-loops
5550Unroll all loops, even if their number of iterations is uncertain when
5551the loop is entered. This usually makes programs run more slowly.
5552@option{-funroll-all-loops} implies the same options as
5553@option{-funroll-loops}.
5554
5555@item -fpeel-loops
5556@opindex fpeel-loops
5557Peels the loops for that there is enough information that they do not
5558roll much (from profile feedback). It also turns on complete loop peeling
5559(i.e.@: complete removal of loops with small constant number of iterations).
5560
5561Enabled with @option{-fprofile-use}.
5562
5563@item -fmove-loop-invariants
5564@opindex fmove-loop-invariants
5565Enables the loop invariant motion pass in the RTL loop optimizer. Enabled
5566at level @option{-O1}
5567
5568@item -funswitch-loops
5569@opindex funswitch-loops
5570Move branches with loop invariant conditions out of the loop, with duplicates
5571of the loop on both branches (modified according to result of the condition).
5572
5573@item -ffunction-sections
5574@itemx -fdata-sections
5575@opindex ffunction-sections
5576@opindex fdata-sections
5577Place each function or data item into its own section in the output
5578file if the target supports arbitrary sections. The name of the
5579function or the name of the data item determines the section's name
5580in the output file.
5581
5582Use these options on systems where the linker can perform optimizations
5583to improve locality of reference in the instruction space. Most systems
5584using the ELF object format and SPARC processors running Solaris 2 have
5585linkers with such optimizations. AIX may have these optimizations in
5586the future.
5587
5588Only use these options when there are significant benefits from doing
5589so. When you specify these options, the assembler and linker will
5590create larger object and executable files and will also be slower.
5591You will not be able to use @code{gprof} on all systems if you
5592specify this option and you may have problems with debugging if
5593you specify both this option and @option{-g}.
5594
5595@item -fbranch-target-load-optimize
5596@opindex fbranch-target-load-optimize
5597Perform branch target register load optimization before prologue / epilogue
5598threading.
5599The use of target registers can typically be exposed only during reload,
5600thus hoisting loads out of loops and doing inter-block scheduling needs
5601a separate optimization pass.
5602
5603@item -fbranch-target-load-optimize2
5604@opindex fbranch-target-load-optimize2
5605Perform branch target register load optimization after prologue / epilogue
5606threading.
5607
5608@item -fbtr-bb-exclusive
5609@opindex fbtr-bb-exclusive
5610When performing branch target register load optimization, don't reuse
5611branch target registers in within any basic block.
5612
5613@item -fstack-protector
5614Emit extra code to check for buffer overflows, such as stack smashing
5615attacks. This is done by adding a guard variable to functions with
5616vulnerable objects. This includes functions that call alloca, and
5617functions with buffers larger than 8 bytes. The guards are initialized
5618when a function is entered and then checked when the function exits.
5619If a guard check fails, an error message is printed and the program exits.
5620
5621@item -fstack-protector-all
5622Like @option{-fstack-protector} except that all functions are protected.
5623
5624@item -fsection-anchors
5625@opindex fsection-anchors
5626Try to reduce the number of symbolic address calculations by using
5627shared ``anchor'' symbols to address nearby objects. This transformation
5628can help to reduce the number of GOT entries and GOT accesses on some
5629targets.
5630
5631For example, the implementation of the following function @code{foo}:
5632
5633@smallexample
5634static int a, b, c;
5635int foo (void) @{ return a + b + c; @}
5636@end smallexample
5637
5638would usually calculate the addresses of all three variables, but if you
5639compile it with @option{-fsection-anchors}, it will access the variables
5640from a common anchor point instead. The effect is similar to the
5641following pseudocode (which isn't valid C):
5642
5643@smallexample
5644int foo (void)
5645@{
5646 register int *xr = &x;
5647 return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
5648@}
5649@end smallexample
5650
5651Not all targets support this option.
5652
5653@item --param @var{name}=@var{value}
5654@opindex param
5655In some places, GCC uses various constants to control the amount of
5656optimization that is done. For example, GCC will not inline functions
5657that contain more that a certain number of instructions. You can
5658control some of these constants on the command-line using the
5659@option{--param} option.
5660
5661The names of specific parameters, and the meaning of the values, are
5662tied to the internals of the compiler, and are subject to change
5663without notice in future releases.
5664
5665In each case, the @var{value} is an integer. The allowable choices for
5666@var{name} are given in the following table:
5667
5668@table @gcctabopt
5669@item salias-max-implicit-fields
5670The maximum number of fields in a variable without direct
5671structure accesses for which structure aliasing will consider trying
5672to track each field. The default is 5
5673
5674@item salias-max-array-elements
5675The maximum number of elements an array can have and its elements
5676still be tracked individually by structure aliasing. The default is 4
5677
5678@item sra-max-structure-size
5679The maximum structure size, in bytes, at which the scalar replacement
5680of aggregates (SRA) optimization will perform block copies. The
5681default value, 0, implies that GCC will select the most appropriate
5682size itself.
5683
5684@item sra-field-structure-ratio
5685The threshold ratio (as a percentage) between instantiated fields and
5686the complete structure size. We say that if the ratio of the number
5687of bytes in instantiated fields to the number of bytes in the complete
5688structure exceeds this parameter, then block copies are not used. The
5689default is 75.
5690
5691@item max-crossjump-edges
5692The maximum number of incoming edges to consider for crossjumping.
5693The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
5694the number of edges incoming to each block. Increasing values mean
5695more aggressive optimization, making the compile time increase with
5696probably small improvement in executable size.
5697
5698@item min-crossjump-insns
5699The minimum number of instructions which must be matched at the end
5700of two blocks before crossjumping will be performed on them. This
5701value is ignored in the case where all instructions in the block being
5702crossjumped from are matched. The default value is 5.
5703
5704@item max-grow-copy-bb-insns
5705The maximum code size expansion factor when copying basic blocks
5706instead of jumping. The expansion is relative to a jump instruction.
5707The default value is 8.
5708
5709@item max-goto-duplication-insns
5710The maximum number of instructions to duplicate to a block that jumps
5711to a computed goto. To avoid @math{O(N^2)} behavior in a number of
5712passes, GCC factors computed gotos early in the compilation process,
5713and unfactors them as late as possible. Only computed jumps at the
5714end of a basic blocks with no more than max-goto-duplication-insns are
5715unfactored. The default value is 8.
5716
5717@item max-delay-slot-insn-search
5718The maximum number of instructions to consider when looking for an
5719instruction to fill a delay slot. If more than this arbitrary number of
5720instructions is searched, the time savings from filling the delay slot
5721will be minimal so stop searching. Increasing values mean more
5722aggressive optimization, making the compile time increase with probably
5723small improvement in executable run time.
5724
5725@item max-delay-slot-live-search
5726When trying to fill delay slots, the maximum number of instructions to
5727consider when searching for a block with valid live register
5728information. Increasing this arbitrarily chosen value means more
5729aggressive optimization, increasing the compile time. This parameter
5730should be removed when the delay slot code is rewritten to maintain the
5731control-flow graph.
5732
5733@item max-gcse-memory
5734The approximate maximum amount of memory that will be allocated in
5735order to perform the global common subexpression elimination
5736optimization. If more memory than specified is required, the
5737optimization will not be done.
5738
5739@item max-gcse-passes
5740The maximum number of passes of GCSE to run. The default is 1.
5741
5742@item max-pending-list-length
5743The maximum number of pending dependencies scheduling will allow
5744before flushing the current state and starting over. Large functions
5745with few branches or calls can create excessively large lists which
5746needlessly consume memory and resources.
5747
5748@item max-inline-insns-single
5749Several parameters control the tree inliner used in gcc.
5750This number sets the maximum number of instructions (counted in GCC's
5751internal representation) in a single function that the tree inliner
5752will consider for inlining. This only affects functions declared
5753inline and methods implemented in a class declaration (C++).
5754The default value is 450.
5755
5756@item max-inline-insns-auto
5757When you use @option{-finline-functions} (included in @option{-O3}),
5758a lot of functions that would otherwise not be considered for inlining
5759by the compiler will be investigated. To those functions, a different
5760(more restrictive) limit compared to functions declared inline can
5761be applied.
5762The default value is 90.
5763
5764@item large-function-insns
5765The limit specifying really large functions. For functions larger than this
5766limit after inlining inlining is constrained by
5767@option{--param large-function-growth}. This parameter is useful primarily
5768to avoid extreme compilation time caused by non-linear algorithms used by the
5769backend.
5770This parameter is ignored when @option{-funit-at-a-time} is not used.
5771The default value is 2700.
5772
5773@item large-function-growth
5774Specifies maximal growth of large function caused by inlining in percents.
5775This parameter is ignored when @option{-funit-at-a-time} is not used.
5776The default value is 100 which limits large function growth to 2.0 times
5777the original size.
5778
5779@item large-unit-insns
5780The limit specifying large translation unit. Growth caused by inlining of
5781units larger than this limit is limited by @option{--param inline-unit-growth}.
5782For small units this might be too tight (consider unit consisting of function A
5783that is inline and B that just calls A three time. If B is small relative to
5784A, the growth of unit is 300\% and yet such inlining is very sane. For very
5785large units consisting of small inlininable functions however the overall unit
5786growth limit is needed to avoid exponential explosion of code size. Thus for
5787smaller units, the size is increased to @option{--param large-unit-insns}
5788before applying @option{--param inline-unit-growth}. The default is 10000
5789
5790@item inline-unit-growth
5791Specifies maximal overall growth of the compilation unit caused by inlining.
5792This parameter is ignored when @option{-funit-at-a-time} is not used.
5793The default value is 50 which limits unit growth to 1.5 times the original
5794size.
5795
5796@item max-inline-insns-recursive
5797@itemx max-inline-insns-recursive-auto
5798Specifies maximum number of instructions out-of-line copy of self recursive inline
5799function can grow into by performing recursive inlining.
5800
5801For functions declared inline @option{--param max-inline-insns-recursive} is
5802taken into account. For function not declared inline, recursive inlining
5803happens only when @option{-finline-functions} (included in @option{-O3}) is
5804enabled and @option{--param max-inline-insns-recursive-auto} is used. The
5805default value is 450.
5806
5807@item max-inline-recursive-depth
5808@itemx max-inline-recursive-depth-auto
5809Specifies maximum recursion depth used by the recursive inlining.
5810
5811For functions declared inline @option{--param max-inline-recursive-depth} is
5812taken into account. For function not declared inline, recursive inlining
5813happens only when @option{-finline-functions} (included in @option{-O3}) is
5814enabled and @option{--param max-inline-recursive-depth-auto} is used. The
5815default value is 450.
5816
5817@item min-inline-recursive-probability
5818Recursive inlining is profitable only for function having deep recursion
5819in average and can hurt for function having little recursion depth by
5820increasing the prologue size or complexity of function body to other
5821optimizers.
5822
5823When profile feedback is available (see @option{-fprofile-generate}) the actual
5824recursion depth can be guessed from probability that function will recurse via
5825given call expression. This parameter limits inlining only to call expression
5826whose probability exceeds given threshold (in percents). The default value is
582710.
5828
5829@item inline-call-cost
5830Specify cost of call instruction relative to simple arithmetics operations
5831(having cost of 1). Increasing this cost disqualifies inlining of non-leaf
5832functions and at the same time increases size of leaf function that is believed to
5833reduce function size by being inlined. In effect it increases amount of
5834inlining for code having large abstraction penalty (many functions that just
5835pass the arguments to other functions) and decrease inlining for code with low
5836abstraction penalty. The default value is 16.
5837
5838@item max-unrolled-insns
5839The maximum number of instructions that a loop should have if that loop
5840is unrolled, and if the loop is unrolled, it determines how many times
5841the loop code is unrolled.
5842
5843@item max-average-unrolled-insns
5844The maximum number of instructions biased by probabilities of their execution
5845that a loop should have if that loop is unrolled, and if the loop is unrolled,
5846it determines how many times the loop code is unrolled.
5847
5848@item max-unroll-times
5849The maximum number of unrollings of a single loop.
5850
5851@item max-peeled-insns
5852The maximum number of instructions that a loop should have if that loop
5853is peeled, and if the loop is peeled, it determines how many times
5854the loop code is peeled.
5855
5856@item max-peel-times
5857The maximum number of peelings of a single loop.
5858
5859@item max-completely-peeled-insns
5860The maximum number of insns of a completely peeled loop.
5861
5862@item max-completely-peel-times
5863The maximum number of iterations of a loop to be suitable for complete peeling.
5864
5865@item max-unswitch-insns
5866The maximum number of insns of an unswitched loop.
5867
5868@item max-unswitch-level
5869The maximum number of branches unswitched in a single loop.
5870
5871@item lim-expensive
5872The minimum cost of an expensive expression in the loop invariant motion.
5873
5874@item iv-consider-all-candidates-bound
5875Bound on number of candidates for induction variables below that
5876all candidates are considered for each use in induction variable
5877optimizations. Only the most relevant candidates are considered
5878if there are more candidates, to avoid quadratic time complexity.
5879
5880@item iv-max-considered-uses
5881The induction variable optimizations give up on loops that contain more
5882induction variable uses.
5883
5884@item iv-always-prune-cand-set-bound
5885If number of candidates in the set is smaller than this value,
5886we always try to remove unnecessary ivs from the set during its
5887optimization when a new iv is added to the set.
5888
5889@item scev-max-expr-size
5890Bound on size of expressions used in the scalar evolutions analyzer.
5891Large expressions slow the analyzer.
5892
5893@item vect-max-version-checks
5894The maximum number of runtime checks that can be performed when doing
5895loop versioning in the vectorizer. See option ftree-vect-loop-version
5896for more information.
5897
5898@item max-iterations-to-track
5899
5900The maximum number of iterations of a loop the brute force algorithm
5901for analysis of # of iterations of the loop tries to evaluate.
5902
5903@item hot-bb-count-fraction
5904Select fraction of the maximal count of repetitions of basic block in program
5905given basic block needs to have to be considered hot.
5906
5907@item hot-bb-frequency-fraction
5908Select fraction of the maximal frequency of executions of basic block in
5909function given basic block needs to have to be considered hot
5910
5911@item max-predicted-iterations
5912The maximum number of loop iterations we predict statically. This is useful
5913in cases where function contain single loop with known bound and other loop
5914with unknown. We predict the known number of iterations correctly, while
5915the unknown number of iterations average to roughly 10. This means that the
5916loop without bounds would appear artificially cold relative to the other one.
5917
5918@item tracer-dynamic-coverage
5919@itemx tracer-dynamic-coverage-feedback
5920
5921This value is used to limit superblock formation once the given percentage of
5922executed instructions is covered. This limits unnecessary code size
5923expansion.
5924
5925The @option{tracer-dynamic-coverage-feedback} is used only when profile
5926feedback is available. The real profiles (as opposed to statically estimated
5927ones) are much less balanced allowing the threshold to be larger value.
5928
5929@item tracer-max-code-growth
5930Stop tail duplication once code growth has reached given percentage. This is
5931rather hokey argument, as most of the duplicates will be eliminated later in
5932cross jumping, so it may be set to much higher values than is the desired code
5933growth.
5934
5935@item tracer-min-branch-ratio
5936
5937Stop reverse growth when the reverse probability of best edge is less than this
5938threshold (in percent).
5939
5940@item tracer-min-branch-ratio
5941@itemx tracer-min-branch-ratio-feedback
5942
5943Stop forward growth if the best edge do have probability lower than this
5944threshold.
5945
5946Similarly to @option{tracer-dynamic-coverage} two values are present, one for
5947compilation for profile feedback and one for compilation without. The value
5948for compilation with profile feedback needs to be more conservative (higher) in
5949order to make tracer effective.
5950
5951@item max-cse-path-length
5952
5953Maximum number of basic blocks on path that cse considers. The default is 10.
5954
5955@item max-cse-insns
5956The maximum instructions CSE process before flushing. The default is 1000.
5957
5958@item global-var-threshold
5959
5960Counts the number of function calls (@var{n}) and the number of
5961call-clobbered variables (@var{v}). If @var{n}x@var{v} is larger than this limit, a
5962single artificial variable will be created to represent all the
5963call-clobbered variables at function call sites. This artificial
5964variable will then be made to alias every call-clobbered variable.
5965(done as @code{int * size_t} on the host machine; beware overflow).
5966
5967@item max-aliased-vops
5968
5969Maximum number of virtual operands allowed to represent aliases
5970before triggering the alias grouping heuristic. Alias grouping
5971reduces compile times and memory consumption needed for aliasing at
5972the expense of precision loss in alias information.
5973
5974@item ggc-min-expand
5975
5976GCC uses a garbage collector to manage its own memory allocation. This
5977parameter specifies the minimum percentage by which the garbage
5978collector's heap should be allowed to expand between collections.
5979Tuning this may improve compilation speed; it has no effect on code
5980generation.
5981
5982The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
5983RAM >= 1GB@. If @code{getrlimit} is available, the notion of "RAM" is
5984the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If
5985GCC is not able to calculate RAM on a particular platform, the lower
5986bound of 30% is used. Setting this parameter and
5987@option{ggc-min-heapsize} to zero causes a full collection to occur at
5988every opportunity. This is extremely slow, but can be useful for
5989debugging.
5990
5991@item ggc-min-heapsize
5992
5993Minimum size of the garbage collector's heap before it begins bothering
5994to collect garbage. The first collection occurs after the heap expands
5995by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again,
5996tuning this may improve compilation speed, and has no effect on code
5997generation.
5998
5999The default is the smaller of RAM/8, RLIMIT_RSS, or a limit which
6000tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
6001with a lower bound of 4096 (four megabytes) and an upper bound of
6002131072 (128 megabytes). If GCC is not able to calculate RAM on a
6003particular platform, the lower bound is used. Setting this parameter
6004very large effectively disables garbage collection. Setting this
6005parameter and @option{ggc-min-expand} to zero causes a full collection
6006to occur at every opportunity.
6007
6008@item max-reload-search-insns
6009The maximum number of instruction reload should look backward for equivalent
6010register. Increasing values mean more aggressive optimization, making the
6011compile time increase with probably slightly better performance. The default
6012value is 100.
6013
6014@item max-cselib-memory-locations
6015The maximum number of memory locations cselib should take into account.
6016Increasing values mean more aggressive optimization, making the compile time
6017increase with probably slightly better performance. The default value is 500.
6018
6019@item max-flow-memory-locations
6020Similar as @option{max-cselib-memory-locations} but for dataflow liveness.
6021The default value is 100.
6022
6023@item reorder-blocks-duplicate
6024@itemx reorder-blocks-duplicate-feedback
6025
6026Used by basic block reordering pass to decide whether to use unconditional
6027branch or duplicate the code on its destination. Code is duplicated when its
6028estimated size is smaller than this value multiplied by the estimated size of
6029unconditional jump in the hot spots of the program.
6030
6031The @option{reorder-block-duplicate-feedback} is used only when profile
6032feedback is available and may be set to higher values than
6033@option{reorder-block-duplicate} since information about the hot spots is more
6034accurate.
6035
6036@item max-sched-ready-insns
6037The maximum number of instructions ready to be issued the scheduler should
6038consider at any given time during the first scheduling pass. Increasing
6039values mean more thorough searches, making the compilation time increase
6040with probably little benefit. The default value is 100.
6041
6042@item max-sched-region-blocks
6043The maximum number of blocks in a region to be considered for
6044interblock scheduling. The default value is 10.
6045
6046@item max-sched-region-insns
6047The maximum number of insns in a region to be considered for
6048interblock scheduling. The default value is 100.
6049
6050@item min-spec-prob
6051The minimum probability (in percents) of reaching a source block
6052for interblock speculative scheduling. The default value is 40.
6053
6054@item max-sched-extend-regions-iters
6055The maximum number of iterations through CFG to extend regions.
60560 - disable region extension,
6057N - do at most N iterations.
6058The default value is 0.
6059
6060@item max-sched-insn-conflict-delay
6061The maximum conflict delay for an insn to be considered for speculative motion.
6062The default value is 3.
6063
6064@item sched-spec-prob-cutoff
6065The minimal probability of speculation success (in percents), so that
6066speculative insn will be scheduled.
6067The default value is 40.
6068
6069@item max-last-value-rtl
6070
6071The maximum size measured as number of RTLs that can be recorded in an expression
6072in combiner for a pseudo register as last known value of that register. The default
6073is 10000.
6074
6075@item integer-share-limit
6076Small integer constants can use a shared data structure, reducing the
6077compiler's memory usage and increasing its speed. This sets the maximum
6078value of a shared integer constant's. The default value is 256.
6079
6080@item min-virtual-mappings
6081Specifies the minimum number of virtual mappings in the incremental
6082SSA updater that should be registered to trigger the virtual mappings
6083heuristic defined by virtual-mappings-ratio. The default value is
6084100.
6085
6086@item virtual-mappings-ratio
6087If the number of virtual mappings is virtual-mappings-ratio bigger
6088than the number of virtual symbols to be updated, then the incremental
6089SSA updater switches to a full update for those symbols. The default
6090ratio is 3.
6091
6092@item ssp-buffer-size
6093The minimum size of buffers (i.e. arrays) that will receive stack smashing
6094protection when @option{-fstack-protection} is used.
6095
6096@item max-jump-thread-duplication-stmts
6097Maximum number of statements allowed in a block that needs to be
6098duplicated when threading jumps.
6099
6100@item max-fields-for-field-sensitive
6101Maximum number of fields in a structure we will treat in
6102a field sensitive manner during pointer analysis.
6103
6104@end table
6105@end table
6106
6107@node Preprocessor Options
6108@section Options Controlling the Preprocessor
6109@cindex preprocessor options
6110@cindex options, preprocessor
6111
6112These options control the C preprocessor, which is run on each C source
6113file before actual compilation.
6114
6115If you use the @option{-E} option, nothing is done except preprocessing.
6116Some of these options make sense only together with @option{-E} because
6117they cause the preprocessor output to be unsuitable for actual
6118compilation.
6119
6120@table @gcctabopt
6121@opindex Wp
6122You can use @option{-Wp,@var{option}} to bypass the compiler driver
6123and pass @var{option} directly through to the preprocessor. If
6124@var{option} contains commas, it is split into multiple options at the
6125commas. However, many options are modified, translated or interpreted
6126by the compiler driver before being passed to the preprocessor, and
6127@option{-Wp} forcibly bypasses this phase. The preprocessor's direct
6128interface is undocumented and subject to change, so whenever possible
6129you should avoid using @option{-Wp} and let the driver handle the
6130options instead.
6131
6132@item -Xpreprocessor @var{option}
6133@opindex preprocessor
6134Pass @var{option} as an option to the preprocessor. You can use this to
6135supply system-specific preprocessor options which GCC does not know how to
6136recognize.
6137
6138If you want to pass an option that takes an argument, you must use
6139@option{-Xpreprocessor} twice, once for the option and once for the argument.
6140@end table
6141
6142@include cppopts.texi
6143
6144@node Assembler Options
6145@section Passing Options to the Assembler
6146
6147@c prevent bad page break with this line
6148You can pass options to the assembler.
6149
6150@table @gcctabopt
6151@item -Wa,@var{option}
6152@opindex Wa
6153Pass @var{option} as an option to the assembler. If @var{option}
6154contains commas, it is split into multiple options at the commas.
6155
6156@item -Xassembler @var{option}
6157@opindex Xassembler
6158Pass @var{option} as an option to the assembler. You can use this to
6159supply system-specific assembler options which GCC does not know how to
6160recognize.
6161
6162If you want to pass an option that takes an argument, you must use
6163@option{-Xassembler} twice, once for the option and once for the argument.
6164
6165@end table
6166
6167@node Link Options
6168@section Options for Linking
6169@cindex link options
6170@cindex options, linking
6171
6172These options come into play when the compiler links object files into
6173an executable output file. They are meaningless if the compiler is
6174not doing a link step.
6175
6176@table @gcctabopt
6177@cindex file names
6178@item @var{object-file-name}
6179A file name that does not end in a special recognized suffix is
6180considered to name an object file or library. (Object files are
6181distinguished from libraries by the linker according to the file
6182contents.) If linking is done, these object files are used as input
6183to the linker.
6184
6185@item -c
6186@itemx -S
6187@itemx -E
6188@opindex c
6189@opindex S
6190@opindex E
6191If any of these options is used, then the linker is not run, and
6192object file names should not be used as arguments. @xref{Overall
6193Options}.
6194
6195@cindex Libraries
6196@item -l@var{library}
6197@itemx -l @var{library}
6198@opindex l
6199Search the library named @var{library} when linking. (The second
6200alternative with the library as a separate argument is only for
6201POSIX compliance and is not recommended.)
6202
6203It makes a difference where in the command you write this option; the
6204linker searches and processes libraries and object files in the order they
6205are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
6206after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
6207to functions in @samp{z}, those functions may not be loaded.
6208
6209The linker searches a standard list of directories for the library,
6210which is actually a file named @file{lib@var{library}.a}. The linker
6211then uses this file as if it had been specified precisely by name.
6212
6213The directories searched include several standard system directories
6214plus any that you specify with @option{-L}.
6215
6216Normally the files found this way are library files---archive files
6217whose members are object files. The linker handles an archive file by
6218scanning through it for members which define symbols that have so far
6219been referenced but not defined. But if the file that is found is an
6220ordinary object file, it is linked in the usual fashion. The only
6221difference between using an @option{-l} option and specifying a file name
6222is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
6223and searches several directories.
6224
6225@item -nostartfiles
6226@opindex nostartfiles
6227Do not use the standard system startup files when linking.
6228The standard system libraries are used normally, unless @option{-nostdlib}
6229or @option{-nodefaultlibs} is used.
6230
6231@item -nodefaultlibs
6232@opindex nodefaultlibs
6233Do not use the standard system libraries when linking.
6234Only the libraries you specify will be passed to the linker.
6235The standard startup files are used normally, unless @option{-nostartfiles}
6236is used. The compiler may generate calls to @code{memcmp},
6237@code{memset}, @code{memcpy} and @code{memmove}.
6238These entries are usually resolved by entries in
6239libc. These entry points should be supplied through some other
6240mechanism when this option is specified.
6241
6242@item -nostdlib
6243@opindex nostdlib
6244Do not use the standard system startup files or libraries when linking.
6245No startup files and only the libraries you specify will be passed to
6246the linker. The compiler may generate calls to @code{memcmp}, @code{memset},
6247@code{memcpy} and @code{memmove}.
6248These entries are usually resolved by entries in
6249libc. These entry points should be supplied through some other
6250mechanism when this option is specified.
6251
6252@cindex @option{-lgcc}, use with @option{-nostdlib}
6253@cindex @option{-nostdlib} and unresolved references
6254@cindex unresolved references and @option{-nostdlib}
6255@cindex @option{-lgcc}, use with @option{-nodefaultlibs}
6256@cindex @option{-nodefaultlibs} and unresolved references
6257@cindex unresolved references and @option{-nodefaultlibs}
6258One of the standard libraries bypassed by @option{-nostdlib} and
6259@option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
6260that GCC uses to overcome shortcomings of particular machines, or special
6261needs for some languages.
6262(@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
6263Collection (GCC) Internals},
6264for more discussion of @file{libgcc.a}.)
6265In most cases, you need @file{libgcc.a} even when you want to avoid
6266other standard libraries. In other words, when you specify @option{-nostdlib}
6267or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
6268This ensures that you have no unresolved references to internal GCC
6269library subroutines. (For example, @samp{__main}, used to ensure C++
6270constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
6271GNU Compiler Collection (GCC) Internals}.)
6272
6273@item -pie
6274@opindex pie
6275Produce a position independent executable on targets which support it.
6276For predictable results, you must also specify the same set of options
6277that were used to generate code (@option{-fpie}, @option{-fPIE},
6278or model suboptions) when you specify this option.
6279
6280@item -rdynamic
6281@opindex rdynamic
6282Pass the flag @option{-export-dynamic} to the ELF linker, on targets
6283that support it. This instructs the linker to add all symbols, not
6284only used ones, to the dynamic symbol table. This option is needed
6285for some uses of @code{dlopen} or to allow obtaining backtraces
6286from within a program.
6287
6288@item -s
6289@opindex s
6290Remove all symbol table and relocation information from the executable.
6291
6292@item -static
6293@opindex static
6294On systems that support dynamic linking, this prevents linking with the shared
6295libraries. On other systems, this option has no effect.
6296
6297@item -shared
6298@opindex shared
6299Produce a shared object which can then be linked with other objects to
6300form an executable. Not all systems support this option. For predictable
6301results, you must also specify the same set of options that were used to
6302generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
6303when you specify this option.@footnote{On some systems, @samp{gcc -shared}
6304needs to build supplementary stub code for constructors to work. On
6305multi-libbed systems, @samp{gcc -shared} must select the correct support
6306libraries to link against. Failing to supply the correct flags may lead
6307to subtle defects. Supplying them in cases where they are not necessary
6308is innocuous.}
6309
6310@item -shared-libgcc
6311@itemx -static-libgcc
6312@opindex shared-libgcc
6313@opindex static-libgcc
6314On systems that provide @file{libgcc} as a shared library, these options
6315force the use of either the shared or static version respectively.
6316If no shared version of @file{libgcc} was built when the compiler was
6317configured, these options have no effect.
6318
6319There are several situations in which an application should use the
6320shared @file{libgcc} instead of the static version. The most common
6321of these is when the application wishes to throw and catch exceptions
6322across different shared libraries. In that case, each of the libraries
6323as well as the application itself should use the shared @file{libgcc}.
6324
6325Therefore, the G++ and GCJ drivers automatically add
6326@option{-shared-libgcc} whenever you build a shared library or a main
6327executable, because C++ and Java programs typically use exceptions, so
6328this is the right thing to do.
6329
6330If, instead, you use the GCC driver to create shared libraries, you may
6331find that they will not always be linked with the shared @file{libgcc}.
6332If GCC finds, at its configuration time, that you have a non-GNU linker
6333or a GNU linker that does not support option @option{--eh-frame-hdr},
6334it will link the shared version of @file{libgcc} into shared libraries
6335by default. Otherwise, it will take advantage of the linker and optimize
6336away the linking with the shared version of @file{libgcc}, linking with
6337the static version of libgcc by default. This allows exceptions to
6338propagate through such shared libraries, without incurring relocation
6339costs at library load time.
6340
6341However, if a library or main executable is supposed to throw or catch
6342exceptions, you must link it using the G++ or GCJ driver, as appropriate
6343for the languages used in the program, or using the option
6344@option{-shared-libgcc}, such that it is linked with the shared
6345@file{libgcc}.
6346
6347@item -symbolic
6348@opindex symbolic
6349Bind references to global symbols when building a shared object. Warn
6350about any unresolved references (unless overridden by the link editor
6351option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
6352this option.
6353
6354@item -Xlinker @var{option}
6355@opindex Xlinker
6356Pass @var{option} as an option to the linker. You can use this to
6357supply system-specific linker options which GCC does not know how to
6358recognize.
6359
6360If you want to pass an option that takes an argument, you must use
6361@option{-Xlinker} twice, once for the option and once for the argument.
6362For example, to pass @option{-assert definitions}, you must write
6363@samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
6364@option{-Xlinker "-assert definitions"}, because this passes the entire
6365string as a single argument, which is not what the linker expects.
6366
6367@item -Wl,@var{option}
6368@opindex Wl
6369Pass @var{option} as an option to the linker. If @var{option} contains
6370commas, it is split into multiple options at the commas.
6371
6372@item -u @var{symbol}
6373@opindex u
6374Pretend the symbol @var{symbol} is undefined, to force linking of
6375library modules to define it. You can use @option{-u} multiple times with
6376different symbols to force loading of additional library modules.
6377@end table
6378
6379@node Directory Options
6380@section Options for Directory Search
6381@cindex directory options
6382@cindex options, directory search
6383@cindex search path
6384
6385These options specify directories to search for header files, for
6386libraries and for parts of the compiler:
6387
6388@table @gcctabopt
6389@item -I@var{dir}
6390@opindex I
6391Add the directory @var{dir} to the head of the list of directories to be
6392searched for header files. This can be used to override a system header
6393file, substituting your own version, since these directories are
6394searched before the system header file directories. However, you should
6395not use this option to add directories that contain vendor-supplied
6396system header files (use @option{-isystem} for that). If you use more than
6397one @option{-I} option, the directories are scanned in left-to-right
6398order; the standard system directories come after.
6399
6400If a standard system include directory, or a directory specified with
6401@option{-isystem}, is also specified with @option{-I}, the @option{-I}
6402option will be ignored. The directory will still be searched but as a
6403system directory at its normal position in the system include chain.
6404This is to ensure that GCC's procedure to fix buggy system headers and
6405the ordering for the include_next directive are not inadvertently changed.
6406If you really need to change the search order for system directories,
6407use the @option{-nostdinc} and/or @option{-isystem} options.
6408
6409@item -iquote@var{dir}
6410@opindex iquote
6411Add the directory @var{dir} to the head of the list of directories to
6412be searched for header files only for the case of @samp{#include
6413"@var{file}"}; they are not searched for @samp{#include <@var{file}>},
6414otherwise just like @option{-I}.
6415
6416@item -L@var{dir}
6417@opindex L
6418Add directory @var{dir} to the list of directories to be searched
6419for @option{-l}.
6420
6421@item -B@var{prefix}
6422@opindex B
6423This option specifies where to find the executables, libraries,
6424include files, and data files of the compiler itself.
6425
6426The compiler driver program runs one or more of the subprograms
6427@file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
6428@var{prefix} as a prefix for each program it tries to run, both with and
6429without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
6430
6431For each subprogram to be run, the compiler driver first tries the
6432@option{-B} prefix, if any. If that name is not found, or if @option{-B}
6433was not specified, the driver tries two standard prefixes, which are
6434@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of
6435those results in a file name that is found, the unmodified program
6436name is searched for using the directories specified in your
6437@env{PATH} environment variable.
6438
6439The compiler will check to see if the path provided by the @option{-B}
6440refers to a directory, and if necessary it will add a directory
6441separator character at the end of the path.
6442
6443@option{-B} prefixes that effectively specify directory names also apply
6444to libraries in the linker, because the compiler translates these
6445options into @option{-L} options for the linker. They also apply to
6446includes files in the preprocessor, because the compiler translates these
6447options into @option{-isystem} options for the preprocessor. In this case,
6448the compiler appends @samp{include} to the prefix.
6449
6450The run-time support file @file{libgcc.a} can also be searched for using
6451the @option{-B} prefix, if needed. If it is not found there, the two
6452standard prefixes above are tried, and that is all. The file is left
6453out of the link if it is not found by those means.
6454
6455Another way to specify a prefix much like the @option{-B} prefix is to use
6456the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
6457Variables}.
6458
6459As a special kludge, if the path provided by @option{-B} is
6460@file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
64619, then it will be replaced by @file{[dir/]include}. This is to help
6462with boot-strapping the compiler.
6463
6464@item -specs=@var{file}
6465@opindex specs
6466Process @var{file} after the compiler reads in the standard @file{specs}
6467file, in order to override the defaults that the @file{gcc} driver
6468program uses when determining what switches to pass to @file{cc1},
6469@file{cc1plus}, @file{as}, @file{ld}, etc. More than one
6470@option{-specs=@var{file}} can be specified on the command line, and they
6471are processed in order, from left to right.
6472
6473@item --sysroot=@var{dir}
6474@opindex sysroot
6475Use @var{dir} as the logical root directory for headers and libraries.
6476For example, if the compiler would normally search for headers in
6477@file{/usr/include} and libraries in @file{/usr/lib}, it will instead
6478search @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
6479
6480If you use both this option and the @option{-isysroot} option, then
6481the @option{--sysroot} option will apply to libraries, but the
6482@option{-isysroot} option will apply to header files.
6483
6484The GNU linker (beginning with version 2.16) has the necessary support
6485for this option. If your linker does not support this option, the
6486header file aspect of @option{--sysroot} will still work, but the
6487library aspect will not.
6488
6489@item -I-
6490@opindex I-
6491This option has been deprecated. Please use @option{-iquote} instead for
6492@option{-I} directories before the @option{-I-} and remove the @option{-I-}.
6493Any directories you specify with @option{-I} options before the @option{-I-}
6494option are searched only for the case of @samp{#include "@var{file}"};
6495they are not searched for @samp{#include <@var{file}>}.
6496
6497If additional directories are specified with @option{-I} options after
6498the @option{-I-}, these directories are searched for all @samp{#include}
6499directives. (Ordinarily @emph{all} @option{-I} directories are used
6500this way.)
6501
6502In addition, the @option{-I-} option inhibits the use of the current
6503directory (where the current input file came from) as the first search
6504directory for @samp{#include "@var{file}"}. There is no way to
6505override this effect of @option{-I-}. With @option{-I.} you can specify
6506searching the directory which was current when the compiler was
6507invoked. That is not exactly the same as what the preprocessor does
6508by default, but it is often satisfactory.
6509
6510@option{-I-} does not inhibit the use of the standard system directories
6511for header files. Thus, @option{-I-} and @option{-nostdinc} are
6512independent.
6513@end table
6514
6515@c man end
6516
6517@node Spec Files
6518@section Specifying subprocesses and the switches to pass to them
6519@cindex Spec Files
6520
6521@command{gcc} is a driver program. It performs its job by invoking a
6522sequence of other programs to do the work of compiling, assembling and
6523linking. GCC interprets its command-line parameters and uses these to
6524deduce which programs it should invoke, and which command-line options
6525it ought to place on their command lines. This behavior is controlled
6526by @dfn{spec strings}. In most cases there is one spec string for each
6527program that GCC can invoke, but a few programs have multiple spec
6528strings to control their behavior. The spec strings built into GCC can
6529be overridden by using the @option{-specs=} command-line switch to specify
6530a spec file.
6531
6532@dfn{Spec files} are plaintext files that are used to construct spec
6533strings. They consist of a sequence of directives separated by blank
6534lines. The type of directive is determined by the first non-whitespace
6535character on the line and it can be one of the following:
6536
6537@table @code
6538@item %@var{command}
6539Issues a @var{command} to the spec file processor. The commands that can
6540appear here are:
6541
6542@table @code
6543@item %include <@var{file}>
6544@cindex %include
6545Search for @var{file} and insert its text at the current point in the
6546specs file.
6547
6548@item %include_noerr <@var{file}>
6549@cindex %include_noerr
6550Just like @samp{%include}, but do not generate an error message if the include
6551file cannot be found.
6552
6553@item %rename @var{old_name} @var{new_name}
6554@cindex %rename
6555Rename the spec string @var{old_name} to @var{new_name}.
6556
6557@end table
6558
6559@item *[@var{spec_name}]:
6560This tells the compiler to create, override or delete the named spec
6561string. All lines after this directive up to the next directive or
6562blank line are considered to be the text for the spec string. If this
6563results in an empty string then the spec will be deleted. (Or, if the
6564spec did not exist, then nothing will happened.) Otherwise, if the spec
6565does not currently exist a new spec will be created. If the spec does
6566exist then its contents will be overridden by the text of this
6567directive, unless the first character of that text is the @samp{+}
6568character, in which case the text will be appended to the spec.
6569
6570@item [@var{suffix}]:
6571Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
6572and up to the next directive or blank line are considered to make up the
6573spec string for the indicated suffix. When the compiler encounters an
6574input file with the named suffix, it will processes the spec string in
6575order to work out how to compile that file. For example:
6576
6577@smallexample
6578.ZZ:
6579z-compile -input %i
6580@end smallexample
6581
6582This says that any input file whose name ends in @samp{.ZZ} should be
6583passed to the program @samp{z-compile}, which should be invoked with the
6584command-line switch @option{-input} and with the result of performing the
6585@samp{%i} substitution. (See below.)
6586
6587As an alternative to providing a spec string, the text that follows a
6588suffix directive can be one of the following:
6589
6590@table @code
6591@item @@@var{language}
6592This says that the suffix is an alias for a known @var{language}. This is
6593similar to using the @option{-x} command-line switch to GCC to specify a
6594language explicitly. For example:
6595
6596@smallexample
6597.ZZ:
6598@@c++
6599@end smallexample
6600
6601Says that .ZZ files are, in fact, C++ source files.
6602
6603@item #@var{name}
6604This causes an error messages saying:
6605
6606@smallexample
6607@var{name} compiler not installed on this system.
6608@end smallexample
6609@end table
6610
6611GCC already has an extensive list of suffixes built into it.
6612This directive will add an entry to the end of the list of suffixes, but
6613since the list is searched from the end backwards, it is effectively
6614possible to override earlier entries using this technique.
6615
6616@end table
6617
6618GCC has the following spec strings built into it. Spec files can
6619override these strings or create their own. Note that individual
6620targets can also add their own spec strings to this list.
6621
6622@smallexample
6623asm Options to pass to the assembler
6624asm_final Options to pass to the assembler post-processor
6625cpp Options to pass to the C preprocessor
6626cc1 Options to pass to the C compiler
6627cc1plus Options to pass to the C++ compiler
6628endfile Object files to include at the end of the link
6629link Options to pass to the linker
6630lib Libraries to include on the command line to the linker
6631libgcc Decides which GCC support library to pass to the linker
6632linker Sets the name of the linker
6633predefines Defines to be passed to the C preprocessor
6634signed_char Defines to pass to CPP to say whether @code{char} is signed
6635 by default
6636startfile Object files to include at the start of the link
6637@end smallexample
6638
6639Here is a small example of a spec file:
6640
6641@smallexample
6642%rename lib old_lib
6643
6644*lib:
6645--start-group -lgcc -lc -leval1 --end-group %(old_lib)
6646@end smallexample
6647
6648This example renames the spec called @samp{lib} to @samp{old_lib} and
6649then overrides the previous definition of @samp{lib} with a new one.
6650The new definition adds in some extra command-line options before
6651including the text of the old definition.
6652
6653@dfn{Spec strings} are a list of command-line options to be passed to their
6654corresponding program. In addition, the spec strings can contain
6655@samp{%}-prefixed sequences to substitute variable text or to
6656conditionally insert text into the command line. Using these constructs
6657it is possible to generate quite complex command lines.
6658
6659Here is a table of all defined @samp{%}-sequences for spec
6660strings. Note that spaces are not generated automatically around the
6661results of expanding these sequences. Therefore you can concatenate them
6662together or combine them with constant text in a single argument.
6663
6664@table @code
6665@item %%
6666Substitute one @samp{%} into the program name or argument.
6667
6668@item %i
6669Substitute the name of the input file being processed.
6670
6671@item %b
6672Substitute the basename of the input file being processed.
6673This is the substring up to (and not including) the last period
6674and not including the directory.
6675
6676@item %B
6677This is the same as @samp{%b}, but include the file suffix (text after
6678the last period).
6679
6680@item %d
6681Marks the argument containing or following the @samp{%d} as a
6682temporary file name, so that that file will be deleted if GCC exits
6683successfully. Unlike @samp{%g}, this contributes no text to the
6684argument.
6685
6686@item %g@var{suffix}
6687Substitute a file name that has suffix @var{suffix} and is chosen
6688once per compilation, and mark the argument in the same way as
6689@samp{%d}. To reduce exposure to denial-of-service attacks, the file
6690name is now chosen in a way that is hard to predict even when previously
6691chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
6692might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
6693the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
6694treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
6695was simply substituted with a file name chosen once per compilation,
6696without regard to any appended suffix (which was therefore treated
6697just like ordinary text), making such attacks more likely to succeed.
6698
6699@item %u@var{suffix}
6700Like @samp{%g}, but generates a new temporary file name even if
6701@samp{%u@var{suffix}} was already seen.
6702
6703@item %U@var{suffix}
6704Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
6705new one if there is no such last file name. In the absence of any
6706@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
6707the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
6708would involve the generation of two distinct file names, one
6709for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
6710simply substituted with a file name chosen for the previous @samp{%u},
6711without regard to any appended suffix.
6712
6713@item %j@var{suffix}
6714Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
6715writable, and if save-temps is off; otherwise, substitute the name
6716of a temporary file, just like @samp{%u}. This temporary file is not
6717meant for communication between processes, but rather as a junk
6718disposal mechanism.
6719
6720@item %|@var{suffix}
6721@itemx %m@var{suffix}
6722Like @samp{%g}, except if @option{-pipe} is in effect. In that case
6723@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
6724all. These are the two most common ways to instruct a program that it
6725should read from standard input or write to standard output. If you
6726need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
6727construct: see for example @file{f/lang-specs.h}.
6728
6729@item %.@var{SUFFIX}
6730Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
6731when it is subsequently output with @samp{%*}. @var{SUFFIX} is
6732terminated by the next space or %.
6733
6734@item %w
6735Marks the argument containing or following the @samp{%w} as the
6736designated output file of this compilation. This puts the argument
6737into the sequence of arguments that @samp{%o} will substitute later.
6738
6739@item %o
6740Substitutes the names of all the output files, with spaces
6741automatically placed around them. You should write spaces
6742around the @samp{%o} as well or the results are undefined.
6743@samp{%o} is for use in the specs for running the linker.
6744Input files whose names have no recognized suffix are not compiled
6745at all, but they are included among the output files, so they will
6746be linked.
6747
6748@item %O
6749Substitutes the suffix for object files. Note that this is
6750handled specially when it immediately follows @samp{%g, %u, or %U},
6751because of the need for those to form complete file names. The
6752handling is such that @samp{%O} is treated exactly as if it had already
6753been substituted, except that @samp{%g, %u, and %U} do not currently
6754support additional @var{suffix} characters following @samp{%O} as they would
6755following, for example, @samp{.o}.
6756
6757@item %p
6758Substitutes the standard macro predefinitions for the
6759current target machine. Use this when running @code{cpp}.
6760
6761@item %P
6762Like @samp{%p}, but puts @samp{__} before and after the name of each
6763predefined macro, except for macros that start with @samp{__} or with
6764@samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
6765C@.
6766
6767@item %I
6768Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
6769@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
6770@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
6771and @option{-imultilib} as necessary.
6772
6773@item %s
6774Current argument is the name of a library or startup file of some sort.
6775Search for that file in a standard list of directories and substitute
6776the full name found.
6777
6778@item %e@var{str}
6779Print @var{str} as an error message. @var{str} is terminated by a newline.
6780Use this when inconsistent options are detected.
6781
6782@item %(@var{name})
6783Substitute the contents of spec string @var{name} at this point.
6784
6785@item %[@var{name}]
6786Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
6787
6788@item %x@{@var{option}@}
6789Accumulate an option for @samp{%X}.
6790
6791@item %X
6792Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
6793spec string.
6794
6795@item %Y
6796Output the accumulated assembler options specified by @option{-Wa}.
6797
6798@item %Z
6799Output the accumulated preprocessor options specified by @option{-Wp}.
6800
6801@item %a
6802Process the @code{asm} spec. This is used to compute the
6803switches to be passed to the assembler.
6804
6805@item %A
6806Process the @code{asm_final} spec. This is a spec string for
6807passing switches to an assembler post-processor, if such a program is
6808needed.
6809
6810@item %l
6811Process the @code{link} spec. This is the spec for computing the
6812command line passed to the linker. Typically it will make use of the
6813@samp{%L %G %S %D and %E} sequences.
6814
6815@item %D
6816Dump out a @option{-L} option for each directory that GCC believes might
6817contain startup files. If the target supports multilibs then the
6818current multilib directory will be prepended to each of these paths.
6819
6820@item %L
6821Process the @code{lib} spec. This is a spec string for deciding which
6822libraries should be included on the command line to the linker.
6823
6824@item %G
6825Process the @code{libgcc} spec. This is a spec string for deciding
6826which GCC support library should be included on the command line to the linker.
6827
6828@item %S
6829Process the @code{startfile} spec. This is a spec for deciding which
6830object files should be the first ones passed to the linker. Typically
6831this might be a file named @file{crt0.o}.
6832
6833@item %E
6834Process the @code{endfile} spec. This is a spec string that specifies
6835the last object files that will be passed to the linker.
6836
6837@item %C
6838Process the @code{cpp} spec. This is used to construct the arguments
6839to be passed to the C preprocessor.
6840
6841@item %1
6842Process the @code{cc1} spec. This is used to construct the options to be
6843passed to the actual C compiler (@samp{cc1}).
6844
6845@item %2
6846Process the @code{cc1plus} spec. This is used to construct the options to be
6847passed to the actual C++ compiler (@samp{cc1plus}).
6848
6849@item %*
6850Substitute the variable part of a matched option. See below.
6851Note that each comma in the substituted string is replaced by
6852a single space.
6853
6854@item %<@code{S}
6855Remove all occurrences of @code{-S} from the command line. Note---this
6856command is position dependent. @samp{%} commands in the spec string
6857before this one will see @code{-S}, @samp{%} commands in the spec string
6858after this one will not.
6859
6860@item %:@var{function}(@var{args})
6861Call the named function @var{function}, passing it @var{args}.
6862@var{args} is first processed as a nested spec string, then split
6863into an argument vector in the usual fashion. The function returns
6864a string which is processed as if it had appeared literally as part
6865of the current spec.
6866
6867The following built-in spec functions are provided:
6868
6869@table @code
6870@item @code{if-exists}
6871The @code{if-exists} spec function takes one argument, an absolute
6872pathname to a file. If the file exists, @code{if-exists} returns the
6873pathname. Here is a small example of its usage:
6874
6875@smallexample
6876*startfile:
6877crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
6878@end smallexample
6879
6880@item @code{if-exists-else}
6881The @code{if-exists-else} spec function is similar to the @code{if-exists}
6882spec function, except that it takes two arguments. The first argument is
6883an absolute pathname to a file. If the file exists, @code{if-exists-else}
6884returns the pathname. If it does not exist, it returns the second argument.
6885This way, @code{if-exists-else} can be used to select one file or another,
6886based on the existence of the first. Here is a small example of its usage:
6887
6888@smallexample
6889*startfile:
6890crt0%O%s %:if-exists(crti%O%s) \
6891%:if-exists-else(crtbeginT%O%s crtbegin%O%s)
6892@end smallexample
6893
6894@item @code{replace-outfile}
6895The @code{replace-outfile} spec function takes two arguments. It looks for the
6896first argument in the outfiles array and replaces it with the second argument. Here
6897is a small example of its usage:
6898
6899@smallexample
6900%@{static|static-libgcc|static-libstdc++:%:replace-outfile(-lstdc++ \
6901libstdc++.a%s)@}
6902
6903@end smallexample
6904
6905@end table
6906
6907@item %@{@code{S}@}
6908Substitutes the @code{-S} switch, if that switch was given to GCC@.
6909If that switch was not specified, this substitutes nothing. Note that
6910the leading dash is omitted when specifying this option, and it is
6911automatically inserted if the substitution is performed. Thus the spec
6912string @samp{%@{foo@}} would match the command-line option @option{-foo}
6913and would output the command line option @option{-foo}.
6914
6915@item %W@{@code{S}@}
6916Like %@{@code{S}@} but mark last argument supplied within as a file to be
6917deleted on failure.
6918
6919@item %@{@code{S}*@}
6920Substitutes all the switches specified to GCC whose names start
6921with @code{-S}, but which also take an argument. This is used for
6922switches like @option{-o}, @option{-D}, @option{-I}, etc.
6923GCC considers @option{-o foo} as being
6924one switch whose names starts with @samp{o}. %@{o*@} would substitute this
6925text, including the space. Thus two arguments would be generated.
6926
6927@item %@{@code{S}*&@code{T}*@}
6928Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
6929(the order of @code{S} and @code{T} in the spec is not significant).
6930There can be any number of ampersand-separated variables; for each the
6931wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
6932
6933@item %@{@code{S}:@code{X}@}
6934Substitutes @code{X}, if the @samp{-S} switch was given to GCC@.
6935
6936@item %@{!@code{S}:@code{X}@}
6937Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@.
6938
6939@item %@{@code{S}*:@code{X}@}
6940Substitutes @code{X} if one or more switches whose names start with
6941@code{-S} are specified to GCC@. Normally @code{X} is substituted only
6942once, no matter how many such switches appeared. However, if @code{%*}
6943appears somewhere in @code{X}, then @code{X} will be substituted once
6944for each matching switch, with the @code{%*} replaced by the part of
6945that switch that matched the @code{*}.
6946
6947@item %@{.@code{S}:@code{X}@}
6948Substitutes @code{X}, if processing a file with suffix @code{S}.
6949
6950@item %@{!.@code{S}:@code{X}@}
6951Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
6952
6953@item %@{@code{S}|@code{P}:@code{X}@}
6954Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@.
6955This may be combined with @samp{!}, @samp{.}, and @code{*} sequences as well,
6956although they have a stronger binding than the @samp{|}. If @code{%*}
6957appears in @code{X}, all of the alternatives must be starred, and only
6958the first matching alternative is substituted.
6959
6960For example, a spec string like this:
6961
6962@smallexample
6963%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
6964@end smallexample
6965
6966will output the following command-line options from the following input
6967command-line options:
6968
6969@smallexample
6970fred.c -foo -baz
6971jim.d -bar -boggle
6972-d fred.c -foo -baz -boggle
6973-d jim.d -bar -baz -boggle
6974@end smallexample
6975
6976@item %@{S:X; T:Y; :D@}
6977
6978If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was
6979given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
6980be as many clauses as you need. This may be combined with @code{.},
6981@code{!}, @code{|}, and @code{*} as needed.
6982
6983
6984@end table
6985
6986The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
6987construct may contain other nested @samp{%} constructs or spaces, or
6988even newlines. They are processed as usual, as described above.
6989Trailing white space in @code{X} is ignored. White space may also
6990appear anywhere on the left side of the colon in these constructs,
6991except between @code{.} or @code{*} and the corresponding word.
6992
6993The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
6994handled specifically in these constructs. If another value of
6995@option{-O} or the negated form of a @option{-f}, @option{-m}, or
6996@option{-W} switch is found later in the command line, the earlier
6997switch value is ignored, except with @{@code{S}*@} where @code{S} is
6998just one letter, which passes all matching options.
6999
7000The character @samp{|} at the beginning of the predicate text is used to
7001indicate that a command should be piped to the following command, but
7002only if @option{-pipe} is specified.
7003
7004It is built into GCC which switches take arguments and which do not.
7005(You might think it would be useful to generalize this to allow each
7006compiler's spec to say which switches take arguments. But this cannot
7007be done in a consistent fashion. GCC cannot even decide which input
7008files have been specified without knowing which switches take arguments,
7009and it must know which input files to compile in order to tell which
7010compilers to run).
7011
7012GCC also knows implicitly that arguments starting in @option{-l} are to be
7013treated as compiler output files, and passed to the linker in their
7014proper position among the other output files.
7015
7016@c man begin OPTIONS
7017
7018@node Target Options
7019@section Specifying Target Machine and Compiler Version
7020@cindex target options
7021@cindex cross compiling
7022@cindex specifying machine version
7023@cindex specifying compiler version and target machine
7024@cindex compiler version, specifying
7025@cindex target machine, specifying
7026
7027The usual way to run GCC is to run the executable called @file{gcc}, or
7028@file{<machine>-gcc} when cross-compiling, or
7029@file{<machine>-gcc-<version>} to run a version other than the one that
7030was installed last. Sometimes this is inconvenient, so GCC provides
7031options that will switch to another cross-compiler or version.
7032
7033@table @gcctabopt
7034@item -b @var{machine}
7035@opindex b
7036The argument @var{machine} specifies the target machine for compilation.
7037
7038The value to use for @var{machine} is the same as was specified as the
7039machine type when configuring GCC as a cross-compiler. For
7040example, if a cross-compiler was configured with @samp{configure
7041arm-elf}, meaning to compile for an arm processor with elf binaries,
7042then you would specify @option{-b arm-elf} to run that cross compiler.
7043Because there are other options beginning with @option{-b}, the
7044configuration must contain a hyphen.
7045
7046@item -V @var{version}
7047@opindex V
7048The argument @var{version} specifies which version of GCC to run.
7049This is useful when multiple versions are installed. For example,
7050@var{version} might be @samp{4.0}, meaning to run GCC version 4.0.
7051@end table
7052
7053The @option{-V} and @option{-b} options work by running the
7054@file{<machine>-gcc-<version>} executable, so there's no real reason to
7055use them if you can just run that directly.
7056
7057@node Submodel Options
7058@section Hardware Models and Configurations
7059@cindex submodel options
7060@cindex specifying hardware config
7061@cindex hardware models and configurations, specifying
7062@cindex machine dependent options
7063
7064Earlier we discussed the standard option @option{-b} which chooses among
7065different installed compilers for completely different target
7066machines, such as VAX vs.@: 68000 vs.@: 80386.
7067
7068In addition, each of these target machine types can have its own
7069special options, starting with @samp{-m}, to choose among various
7070hardware models or configurations---for example, 68010 vs 68020,
7071floating coprocessor or none. A single installed version of the
7072compiler can compile for any model or configuration, according to the
7073options specified.
7074
7075Some configurations of the compiler also support additional special
7076options, usually for compatibility with other compilers on the same
7077platform.
7078
7079@c This list is ordered alphanumerically by subsection name.
7080@c It should be the same order and spelling as these options are listed
7081@c in Machine Dependent Options
7082
7083@menu
7084* ARC Options::
7085* ARM Options::
7086* AVR Options::
7087* Blackfin Options::
7088* CRIS Options::
7089* CRX Options::
7090* Darwin Options::
7091* DEC Alpha Options::
7092* DEC Alpha/VMS Options::
7093* FRV Options::
7094* GNU/Linux Options::
7095* H8/300 Options::
7096* HPPA Options::
7097* i386 and x86-64 Options::
7098* IA-64 Options::
7099* M32C Options::
7100* M32R/D Options::
7101* M680x0 Options::
7102* M68hc1x Options::
7103* MCore Options::
7104* MIPS Options::
7105* MMIX Options::
7106* MN10300 Options::
7107* MT Options::
7108* PDP-11 Options::
7109* PowerPC Options::
7110* RS/6000 and PowerPC Options::
7111* S/390 and zSeries Options::
7112* Score Options::
7113* SH Options::
7114* SPARC Options::
7115* System V Options::
7116* TMS320C3x/C4x Options::
7117* V850 Options::
7118* VAX Options::
7119* x86-64 Options::
7120* Xstormy16 Options::
7121* Xtensa Options::
7122* zSeries Options::
7123@end menu
7124
7125@node ARC Options
7126@subsection ARC Options
7127@cindex ARC Options
7128
7129These options are defined for ARC implementations:
7130
7131@table @gcctabopt
7132@item -EL
7133@opindex EL
7134Compile code for little endian mode. This is the default.
7135
7136@item -EB
7137@opindex EB
7138Compile code for big endian mode.
7139
7140@item -mmangle-cpu
7141@opindex mmangle-cpu
7142Prepend the name of the cpu to all public symbol names.
7143In multiple-processor systems, there are many ARC variants with different
7144instruction and register set characteristics. This flag prevents code
7145compiled for one cpu to be linked with code compiled for another.
7146No facility exists for handling variants that are ``almost identical''.
7147This is an all or nothing option.
7148
7149@item -mcpu=@var{cpu}
7150@opindex mcpu
7151Compile code for ARC variant @var{cpu}.
7152Which variants are supported depend on the configuration.
7153All variants support @option{-mcpu=base}, this is the default.
7154
7155@item -mtext=@var{text-section}
7156@itemx -mdata=@var{data-section}
7157@itemx -mrodata=@var{readonly-data-section}
7158@opindex mtext
7159@opindex mdata
7160@opindex mrodata
7161Put functions, data, and readonly data in @var{text-section},
7162@var{data-section}, and @var{readonly-data-section} respectively
7163by default. This can be overridden with the @code{section} attribute.
7164@xref{Variable Attributes}.
7165
7166@end table
7167
7168@node ARM Options
7169@subsection ARM Options
7170@cindex ARM options
7171
7172These @samp{-m} options are defined for Advanced RISC Machines (ARM)
7173architectures:
7174
7175@table @gcctabopt
7176@item -mabi=@var{name}
7177@opindex mabi
7178Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu},
7179@samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.
7180
7181@item -mapcs-frame
7182@opindex mapcs-frame
7183Generate a stack frame that is compliant with the ARM Procedure Call
7184Standard for all functions, even if this is not strictly necessary for
7185correct execution of the code. Specifying @option{-fomit-frame-pointer}
7186with this option will cause the stack frames not to be generated for
7187leaf functions. The default is @option{-mno-apcs-frame}.
7188
7189@item -mapcs
7190@opindex mapcs
7191This is a synonym for @option{-mapcs-frame}.
7192
7193@ignore
7194@c not currently implemented
7195@item -mapcs-stack-check
7196@opindex mapcs-stack-check
7197Generate code to check the amount of stack space available upon entry to
7198every function (that actually uses some stack space). If there is
7199insufficient space available then either the function
7200@samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
7201called, depending upon the amount of stack space required. The run time
7202system is required to provide these functions. The default is
7203@option{-mno-apcs-stack-check}, since this produces smaller code.
7204
7205@c not currently implemented
7206@item -mapcs-float
7207@opindex mapcs-float
7208Pass floating point arguments using the float point registers. This is
7209one of the variants of the APCS@. This option is recommended if the
7210target hardware has a floating point unit or if a lot of floating point
7211arithmetic is going to be performed by the code. The default is
7212@option{-mno-apcs-float}, since integer only code is slightly increased in
7213size if @option{-mapcs-float} is used.
7214
7215@c not currently implemented
7216@item -mapcs-reentrant
7217@opindex mapcs-reentrant
7218Generate reentrant, position independent code. The default is
7219@option{-mno-apcs-reentrant}.
7220@end ignore
7221
7222@item -mthumb-interwork
7223@opindex mthumb-interwork
7224Generate code which supports calling between the ARM and Thumb
7225instruction sets. Without this option the two instruction sets cannot
7226be reliably used inside one program. The default is
7227@option{-mno-thumb-interwork}, since slightly larger code is generated
7228when @option{-mthumb-interwork} is specified.
7229
7230@item -mno-sched-prolog
7231@opindex mno-sched-prolog
7232Prevent the reordering of instructions in the function prolog, or the
7233merging of those instruction with the instructions in the function's
7234body. This means that all functions will start with a recognizable set
7235of instructions (or in fact one of a choice from a small set of
7236different function prologues), and this information can be used to
7237locate the start if functions inside an executable piece of code. The
7238default is @option{-msched-prolog}.
7239
7240@item -mhard-float
7241@opindex mhard-float
7242Generate output containing floating point instructions. This is the
7243default.
7244
7245@item -msoft-float
7246@opindex msoft-float
7247Generate output containing library calls for floating point.
7248@strong{Warning:} the requisite libraries are not available for all ARM
7249targets. Normally the facilities of the machine's usual C compiler are
7250used, but this cannot be done directly in cross-compilation. You must make
7251your own arrangements to provide suitable library functions for
7252cross-compilation.
7253
7254@option{-msoft-float} changes the calling convention in the output file;
7255therefore, it is only useful if you compile @emph{all} of a program with
7256this option. In particular, you need to compile @file{libgcc.a}, the
7257library that comes with GCC, with @option{-msoft-float} in order for
7258this to work.
7259
7260@item -mfloat-abi=@var{name}
7261@opindex mfloat-abi
7262Specifies which ABI to use for floating point values. Permissible values
7263are: @samp{soft}, @samp{softfp} and @samp{hard}.
7264
7265@samp{soft} and @samp{hard} are equivalent to @option{-msoft-float}
7266and @option{-mhard-float} respectively. @samp{softfp} allows the generation
7267of floating point instructions, but still uses the soft-float calling
7268conventions.
7269
7270@item -mlittle-endian
7271@opindex mlittle-endian
7272Generate code for a processor running in little-endian mode. This is
7273the default for all standard configurations.
7274
7275@item -mbig-endian
7276@opindex mbig-endian
7277Generate code for a processor running in big-endian mode; the default is
7278to compile code for a little-endian processor.
7279
7280@item -mwords-little-endian
7281@opindex mwords-little-endian
7282This option only applies when generating code for big-endian processors.
7283Generate code for a little-endian word order but a big-endian byte
7284order. That is, a byte order of the form @samp{32107654}. Note: this
7285option should only be used if you require compatibility with code for
7286big-endian ARM processors generated by versions of the compiler prior to
72872.8.
7288
7289@item -mcpu=@var{name}
7290@opindex mcpu
7291This specifies the name of the target ARM processor. GCC uses this name
7292to determine what kind of instructions it can emit when generating
7293assembly code. Permissible names are: @samp{arm2}, @samp{arm250},
7294@samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
7295@samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
7296@samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
7297@samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
7298@samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},
7299@samp{arm8}, @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
7300@samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
7301@samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},
7302@samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},
7303@samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},
7304@samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
7305@samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
7306@samp{arm1176jz-s}, @samp{arm1176jzf-s}, @samp{xscale}, @samp{iwmmxt},
7307@samp{ep9312}.
7308
7309@itemx -mtune=@var{name}
7310@opindex mtune
7311This option is very similar to the @option{-mcpu=} option, except that
7312instead of specifying the actual target processor type, and hence
7313restricting which instructions can be used, it specifies that GCC should
7314tune the performance of the code as if the target were of the type
7315specified in this option, but still choosing the instructions that it
7316will generate based on the cpu specified by a @option{-mcpu=} option.
7317For some ARM implementations better performance can be obtained by using
7318this option.
7319
7320@item -march=@var{name}
7321@opindex march
7322This specifies the name of the target ARM architecture. GCC uses this
7323name to determine what kind of instructions it can emit when generating
7324assembly code. This option can be used in conjunction with or instead
7325of the @option{-mcpu=} option. Permissible names are: @samp{armv2},
7326@samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
7327@samp{armv5}, @samp{armv5t}, @samp{armv5te}, @samp{armv6}, @samp{armv6j},
7328@samp{iwmmxt}, @samp{ep9312}.
7329
7330@item -mfpu=@var{name}
7331@itemx -mfpe=@var{number}
7332@itemx -mfp=@var{number}
7333@opindex mfpu
7334@opindex mfpe
7335@opindex mfp
7336This specifies what floating point hardware (or hardware emulation) is
7337available on the target. Permissible names are: @samp{fpa}, @samp{fpe2},
7338@samp{fpe3}, @samp{maverick}, @samp{vfp}. @option{-mfp} and @option{-mfpe}
7339are synonyms for @option{-mfpu}=@samp{fpe}@var{number}, for compatibility
7340with older versions of GCC@.
7341
7342If @option{-msoft-float} is specified this specifies the format of
7343floating point values.
7344
7345@item -mstructure-size-boundary=@var{n}
7346@opindex mstructure-size-boundary
7347The size of all structures and unions will be rounded up to a multiple
7348of the number of bits set by this option. Permissible values are 8, 32
7349and 64. The default value varies for different toolchains. For the COFF
7350targeted toolchain the default value is 8. A value of 64 is only allowed
7351if the underlying ABI supports it.
7352
7353Specifying the larger number can produce faster, more efficient code, but
7354can also increase the size of the program. Different values are potentially
7355incompatible. Code compiled with one value cannot necessarily expect to
7356work with code or libraries compiled with another value, if they exchange
7357information using structures or unions.
7358
7359@item -mabort-on-noreturn
7360@opindex mabort-on-noreturn
7361Generate a call to the function @code{abort} at the end of a
7362@code{noreturn} function. It will be executed if the function tries to
7363return.
7364
7365@item -mlong-calls
7366@itemx -mno-long-calls
7367@opindex mlong-calls
7368@opindex mno-long-calls
7369Tells the compiler to perform function calls by first loading the
7370address of the function into a register and then performing a subroutine
7371call on this register. This switch is needed if the target function
7372will lie outside of the 64 megabyte addressing range of the offset based
7373version of subroutine call instruction.
7374
7375Even if this switch is enabled, not all function calls will be turned
7376into long calls. The heuristic is that static functions, functions
7377which have the @samp{short-call} attribute, functions that are inside
7378the scope of a @samp{#pragma no_long_calls} directive and functions whose
7379definitions have already been compiled within the current compilation
7380unit, will not be turned into long calls. The exception to this rule is
7381that weak function definitions, functions with the @samp{long-call}
7382attribute or the @samp{section} attribute, and functions that are within
7383the scope of a @samp{#pragma long_calls} directive, will always be
7384turned into long calls.
7385
7386This feature is not enabled by default. Specifying
7387@option{-mno-long-calls} will restore the default behavior, as will
7388placing the function calls within the scope of a @samp{#pragma
7389long_calls_off} directive. Note these switches have no effect on how
7390the compiler generates code to handle function calls via function
7391pointers.
7392
7393@item -mnop-fun-dllimport
7394@opindex mnop-fun-dllimport
7395Disable support for the @code{dllimport} attribute.
7396
7397@item -msingle-pic-base
7398@opindex msingle-pic-base
7399Treat the register used for PIC addressing as read-only, rather than
7400loading it in the prologue for each function. The run-time system is
7401responsible for initializing this register with an appropriate value
7402before execution begins.
7403
7404@item -mpic-register=@var{reg}
7405@opindex mpic-register
7406Specify the register to be used for PIC addressing. The default is R10
7407unless stack-checking is enabled, when R9 is used.
7408
7409@item -mcirrus-fix-invalid-insns
7410@opindex mcirrus-fix-invalid-insns
7411@opindex mno-cirrus-fix-invalid-insns
7412Insert NOPs into the instruction stream to in order to work around
7413problems with invalid Maverick instruction combinations. This option
7414is only valid if the @option{-mcpu=ep9312} option has been used to
7415enable generation of instructions for the Cirrus Maverick floating
7416point co-processor. This option is not enabled by default, since the
7417problem is only present in older Maverick implementations. The default
7418can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns}
7419switch.
7420
7421@item -mpoke-function-name
7422@opindex mpoke-function-name
7423Write the name of each function into the text section, directly
7424preceding the function prologue. The generated code is similar to this:
7425
7426@smallexample
7427 t0
7428 .ascii "arm_poke_function_name", 0
7429 .align
7430 t1
7431 .word 0xff000000 + (t1 - t0)
7432 arm_poke_function_name
7433 mov ip, sp
7434 stmfd sp!, @{fp, ip, lr, pc@}
7435 sub fp, ip, #4
7436@end smallexample
7437
7438When performing a stack backtrace, code can inspect the value of
7439@code{pc} stored at @code{fp + 0}. If the trace function then looks at
7440location @code{pc - 12} and the top 8 bits are set, then we know that
7441there is a function name embedded immediately preceding this location
7442and has length @code{((pc[-3]) & 0xff000000)}.
7443
7444@item -mthumb
7445@opindex mthumb
7446Generate code for the 16-bit Thumb instruction set. The default is to
7447use the 32-bit ARM instruction set.
7448
7449@item -mtpcs-frame
7450@opindex mtpcs-frame
7451Generate a stack frame that is compliant with the Thumb Procedure Call
7452Standard for all non-leaf functions. (A leaf function is one that does
7453not call any other functions.) The default is @option{-mno-tpcs-frame}.
7454
7455@item -mtpcs-leaf-frame
7456@opindex mtpcs-leaf-frame
7457Generate a stack frame that is compliant with the Thumb Procedure Call
7458Standard for all leaf functions. (A leaf function is one that does
7459not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
7460
7461@item -mcallee-super-interworking
7462@opindex mcallee-super-interworking
7463Gives all externally visible functions in the file being compiled an ARM
7464instruction set header which switches to Thumb mode before executing the
7465rest of the function. This allows these functions to be called from
7466non-interworking code.
7467
7468@item -mcaller-super-interworking
7469@opindex mcaller-super-interworking
7470Allows calls via function pointers (including virtual functions) to
7471execute correctly regardless of whether the target code has been
7472compiled for interworking or not. There is a small overhead in the cost
7473of executing a function pointer if this option is enabled.
7474
7475@item -mtp=@var{name}
7476@opindex mtp
7477Specify the access model for the thread local storage pointer. The valid
7478models are @option{soft}, which generates calls to @code{__aeabi_read_tp},
7479@option{cp15}, which fetches the thread pointer from @code{cp15} directly
7480(supported in the arm6k architecture), and @option{auto}, which uses the
7481best available method for the selected processor. The default setting is
7482@option{auto}.
7483
7484@end table
7485
7486@node AVR Options
7487@subsection AVR Options
7488@cindex AVR Options
7489
7490These options are defined for AVR implementations:
7491
7492@table @gcctabopt
7493@item -mmcu=@var{mcu}
7494@opindex mmcu
7495Specify ATMEL AVR instruction set or MCU type.
7496
7497Instruction set avr1 is for the minimal AVR core, not supported by the C
7498compiler, only for assembler programs (MCU types: at90s1200, attiny10,
7499attiny11, attiny12, attiny15, attiny28).
7500
7501Instruction set avr2 (default) is for the classic AVR core with up to
75028K program memory space (MCU types: at90s2313, at90s2323, attiny22,
7503at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
7504at90c8534, at90s8535).
7505
7506Instruction set avr3 is for the classic AVR core with up to 128K program
7507memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
7508
7509Instruction set avr4 is for the enhanced AVR core with up to 8K program
7510memory space (MCU types: atmega8, atmega83, atmega85).
7511
7512Instruction set avr5 is for the enhanced AVR core with up to 128K program
7513memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
7514atmega64, atmega128, at43usb355, at94k).
7515
7516@item -msize
7517@opindex msize
7518Output instruction sizes to the asm file.
7519
7520@item -minit-stack=@var{N}
7521@opindex minit-stack
7522Specify the initial stack address, which may be a symbol or numeric value,
7523@samp{__stack} is the default.
7524
7525@item -mno-interrupts
7526@opindex mno-interrupts
7527Generated code is not compatible with hardware interrupts.
7528Code size will be smaller.
7529
7530@item -mcall-prologues
7531@opindex mcall-prologues
7532Functions prologues/epilogues expanded as call to appropriate
7533subroutines. Code size will be smaller.
7534
7535@item -mno-tablejump
7536@opindex mno-tablejump
7537Do not generate tablejump insns which sometimes increase code size.
7538
7539@item -mtiny-stack
7540@opindex mtiny-stack
7541Change only the low 8 bits of the stack pointer.
7542
7543@item -mint8
7544@opindex mint8
7545Assume int to be 8 bit integer. This affects the sizes of all types: A
7546char will be 1 byte, an int will be 1 byte, an long will be 2 bytes
7547and long long will be 4 bytes. Please note that this option does not
7548comply to the C standards, but it will provide you with smaller code
7549size.
7550@end table
7551
7552@node Blackfin Options
7553@subsection Blackfin Options
7554@cindex Blackfin Options
7555
7556@table @gcctabopt
7557@item -momit-leaf-frame-pointer
7558@opindex momit-leaf-frame-pointer
7559Don't keep the frame pointer in a register for leaf functions. This
7560avoids the instructions to save, set up and restore frame pointers and
7561makes an extra register available in leaf functions. The option
7562@option{-fomit-frame-pointer} removes the frame pointer for all functions
7563which might make debugging harder.
7564
7565@item -mspecld-anomaly
7566@opindex mspecld-anomaly
7567When enabled, the compiler will ensure that the generated code does not
7568contain speculative loads after jump instructions. This option is enabled
7569by default.
7570
7571@item -mno-specld-anomaly
7572@opindex mno-specld-anomaly
7573Don't generate extra code to prevent speculative loads from occurring.
7574
7575@item -mcsync-anomaly
7576@opindex mcsync-anomaly
7577When enabled, the compiler will ensure that the generated code does not
7578contain CSYNC or SSYNC instructions too soon after conditional branches.
7579This option is enabled by default.
7580
7581@item -mno-csync-anomaly
7582@opindex mno-csync-anomaly
7583Don't generate extra code to prevent CSYNC or SSYNC instructions from
7584occurring too soon after a conditional branch.
7585
7586@item -mlow-64k
7587@opindex mlow-64k
7588When enabled, the compiler is free to take advantage of the knowledge that
7589the entire program fits into the low 64k of memory.
7590
7591@item -mno-low-64k
7592@opindex mno-low-64k
7593Assume that the program is arbitrarily large. This is the default.
7594
7595@item -mid-shared-library
7596@opindex mid-shared-library
7597Generate code that supports shared libraries via the library ID method.
7598This allows for execute in place and shared libraries in an environment
7599without virtual memory management. This option implies @option{-fPIC}.
7600
7601@item -mno-id-shared-library
7602@opindex mno-id-shared-library
7603Generate code that doesn't assume ID based shared libraries are being used.
7604This is the default.
7605
7606@item -mshared-library-id=n
7607@opindex mshared-library-id
7608Specified the identification number of the ID based shared library being
7609compiled. Specifying a value of 0 will generate more compact code, specifying
7610other values will force the allocation of that number to the current
7611library but is no more space or time efficient than omitting this option.
7612
7613@item -mlong-calls
7614@itemx -mno-long-calls
7615@opindex mlong-calls
7616@opindex mno-long-calls
7617Tells the compiler to perform function calls by first loading the
7618address of the function into a register and then performing a subroutine
7619call on this register. This switch is needed if the target function
7620will lie outside of the 24 bit addressing range of the offset based
7621version of subroutine call instruction.
7622
7623This feature is not enabled by default. Specifying
7624@option{-mno-long-calls} will restore the default behavior. Note these
7625switches have no effect on how the compiler generates code to handle
7626function calls via function pointers.
7627@end table
7628
7629@node CRIS Options
7630@subsection CRIS Options
7631@cindex CRIS Options
7632
7633These options are defined specifically for the CRIS ports.
7634
7635@table @gcctabopt
7636@item -march=@var{architecture-type}
7637@itemx -mcpu=@var{architecture-type}
7638@opindex march
7639@opindex mcpu
7640Generate code for the specified architecture. The choices for
7641@var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
7642respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
7643Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
7644@samp{v10}.
7645
7646@item -mtune=@var{architecture-type}
7647@opindex mtune
7648Tune to @var{architecture-type} everything applicable about the generated
7649code, except for the ABI and the set of available instructions. The
7650choices for @var{architecture-type} are the same as for
7651@option{-march=@var{architecture-type}}.
7652
7653@item -mmax-stack-frame=@var{n}
7654@opindex mmax-stack-frame
7655Warn when the stack frame of a function exceeds @var{n} bytes.
7656
7657@item -melinux-stacksize=@var{n}
7658@opindex melinux-stacksize
7659Only available with the @samp{cris-axis-aout} target. Arranges for
7660indications in the program to the kernel loader that the stack of the
7661program should be set to @var{n} bytes.
7662
7663@item -metrax4
7664@itemx -metrax100
7665@opindex metrax4
7666@opindex metrax100
7667The options @option{-metrax4} and @option{-metrax100} are synonyms for
7668@option{-march=v3} and @option{-march=v8} respectively.
7669
7670@item -mmul-bug-workaround
7671@itemx -mno-mul-bug-workaround
7672@opindex mmul-bug-workaround
7673@opindex mno-mul-bug-workaround
7674Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
7675models where it applies. This option is active by default.
7676
7677@item -mpdebug
7678@opindex mpdebug
7679Enable CRIS-specific verbose debug-related information in the assembly
7680code. This option also has the effect to turn off the @samp{#NO_APP}
7681formatted-code indicator to the assembler at the beginning of the
7682assembly file.
7683
7684@item -mcc-init
7685@opindex mcc-init
7686Do not use condition-code results from previous instruction; always emit
7687compare and test instructions before use of condition codes.
7688
7689@item -mno-side-effects
7690@opindex mno-side-effects
7691Do not emit instructions with side-effects in addressing modes other than
7692post-increment.
7693
7694@item -mstack-align
7695@itemx -mno-stack-align
7696@itemx -mdata-align
7697@itemx -mno-data-align
7698@itemx -mconst-align
7699@itemx -mno-const-align
7700@opindex mstack-align
7701@opindex mno-stack-align
7702@opindex mdata-align
7703@opindex mno-data-align
7704@opindex mconst-align
7705@opindex mno-const-align
7706These options (no-options) arranges (eliminate arrangements) for the
7707stack-frame, individual data and constants to be aligned for the maximum
7708single data access size for the chosen CPU model. The default is to
7709arrange for 32-bit alignment. ABI details such as structure layout are
7710not affected by these options.
7711
7712@item -m32-bit
7713@itemx -m16-bit
7714@itemx -m8-bit
7715@opindex m32-bit
7716@opindex m16-bit
7717@opindex m8-bit
7718Similar to the stack- data- and const-align options above, these options
7719arrange for stack-frame, writable data and constants to all be 32-bit,
772016-bit or 8-bit aligned. The default is 32-bit alignment.
7721
7722@item -mno-prologue-epilogue
7723@itemx -mprologue-epilogue
7724@opindex mno-prologue-epilogue
7725@opindex mprologue-epilogue
7726With @option{-mno-prologue-epilogue}, the normal function prologue and
7727epilogue that sets up the stack-frame are omitted and no return
7728instructions or return sequences are generated in the code. Use this
7729option only together with visual inspection of the compiled code: no
7730warnings or errors are generated when call-saved registers must be saved,
7731or storage for local variable needs to be allocated.
7732
7733@item -mno-gotplt
7734@itemx -mgotplt
7735@opindex mno-gotplt
7736@opindex mgotplt
7737With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
7738instruction sequences that load addresses for functions from the PLT part
7739of the GOT rather than (traditional on other architectures) calls to the
7740PLT@. The default is @option{-mgotplt}.
7741
7742@item -maout
7743@opindex maout
7744Legacy no-op option only recognized with the cris-axis-aout target.
7745
7746@item -melf
7747@opindex melf
7748Legacy no-op option only recognized with the cris-axis-elf and
7749cris-axis-linux-gnu targets.
7750
7751@item -melinux
7752@opindex melinux
7753Only recognized with the cris-axis-aout target, where it selects a
7754GNU/linux-like multilib, include files and instruction set for
7755@option{-march=v8}.
7756
7757@item -mlinux
7758@opindex mlinux
7759Legacy no-op option only recognized with the cris-axis-linux-gnu target.
7760
7761@item -sim
7762@opindex sim
7763This option, recognized for the cris-axis-aout and cris-axis-elf arranges
7764to link with input-output functions from a simulator library. Code,
7765initialized data and zero-initialized data are allocated consecutively.
7766
7767@item -sim2
7768@opindex sim2
7769Like @option{-sim}, but pass linker options to locate initialized data at
77700x40000000 and zero-initialized data at 0x80000000.
7771@end table
7772
7773@node CRX Options
7774@subsection CRX Options
7775@cindex CRX Options
7776
7777These options are defined specifically for the CRX ports.
7778
7779@table @gcctabopt
7780
7781@item -mmac
7782@opindex mmac
7783Enable the use of multiply-accumulate instructions. Disabled by default.
7784
7785@item -mpush-args
7786@opindex mpush-args
7787Push instructions will be used to pass outgoing arguments when functions
7788are called. Enabled by default.
7789@end table
7790
7791@node Darwin Options
7792@subsection Darwin Options
7793@cindex Darwin options
7794
7795These options are defined for all architectures running the Darwin operating
7796system.
7797
7798FSF GCC on Darwin does not create ``fat'' object files; it will create
7799an object file for the single architecture that it was built to
7800target. Apple's GCC on Darwin does create ``fat'' files if multiple
7801@option{-arch} options are used; it does so by running the compiler or
7802linker multiple times and joining the results together with
7803@file{lipo}.
7804
7805The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
7806@samp{i686}) is determined by the flags that specify the ISA
7807that GCC is targetting, like @option{-mcpu} or @option{-march}. The
7808@option{-force_cpusubtype_ALL} option can be used to override this.
7809
7810The Darwin tools vary in their behavior when presented with an ISA
7811mismatch. The assembler, @file{as}, will only permit instructions to
7812be used that are valid for the subtype of the file it is generating,
7813so you cannot put 64-bit instructions in an @samp{ppc750} object file.
7814The linker for shared libraries, @file{/usr/bin/libtool}, will fail
7815and print an error if asked to create a shared library with a less
7816restrictive subtype than its input files (for instance, trying to put
7817a @samp{ppc970} object file in a @samp{ppc7400} library). The linker
7818for executables, @file{ld}, will quietly give the executable the most
7819restrictive subtype of any of its input files.
7820
7821@table @gcctabopt
7822@item -F@var{dir}
7823@opindex F
7824Add the framework directory @var{dir} to the head of the list of
7825directories to be searched for header files. These directories are
7826interleaved with those specified by @option{-I} options and are
7827scanned in a left-to-right order.
7828
7829A framework directory is a directory with frameworks in it. A
7830framework is a directory with a @samp{"Headers"} and/or
7831@samp{"PrivateHeaders"} directory contained directly in it that ends
7832in @samp{".framework"}. The name of a framework is the name of this
7833directory excluding the @samp{".framework"}. Headers associated with
7834the framework are found in one of those two directories, with
7835@samp{"Headers"} being searched first. A subframework is a framework
7836directory that is in a framework's @samp{"Frameworks"} directory.
7837Includes of subframework headers can only appear in a header of a
7838framework that contains the subframework, or in a sibling subframework
7839header. Two subframeworks are siblings if they occur in the same
7840framework. A subframework should not have the same name as a
7841framework, a warning will be issued if this is violated. Currently a
7842subframework cannot have subframeworks, in the future, the mechanism
7843may be extended to support this. The standard frameworks can be found
7844in @samp{"/System/Library/Frameworks"} and
7845@samp{"/Library/Frameworks"}. An example include looks like
7846@code{#include <Framework/header.h>}, where @samp{Framework} denotes
7847the name of the framework and header.h is found in the
7848@samp{"PrivateHeaders"} or @samp{"Headers"} directory.
7849
7850@item -gused
7851@opindex gused
7852Emit debugging information for symbols that are used. For STABS
7853debugging format, this enables @option{-feliminate-unused-debug-symbols}.
7854This is by default ON@.
7855
7856@item -gfull
7857@opindex gfull
7858Emit debugging information for all symbols and types.
7859
7860@item -mmacosx-version-min=@var{version}
7861The earliest version of MacOS X that this executable will run on
7862is @var{version}. Typical values of @var{version} include @code{10.1},
7863@code{10.2}, and @code{10.3.9}.
7864
7865The default for this option is to make choices that seem to be most
7866useful.
7867
7868@item -mkernel
7869@opindex mkernel
7870Enable kernel development mode. The @option{-mkernel} option sets
7871@option{-static}, @option{-fno-common}, @option{-fno-cxa-atexit},
7872@option{-fno-exceptions}, @option{-fno-non-call-exceptions},
7873@option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where
7874applicable. This mode also sets @option{-mno-altivec},
7875@option{-msoft-float}, @option{-fno-builtin} and
7876@option{-mlong-branch} for PowerPC targets.
7877
7878@item -mone-byte-bool
7879@opindex mone-byte-bool
7880Override the defaults for @samp{bool} so that @samp{sizeof(bool)==1}.
7881By default @samp{sizeof(bool)} is @samp{4} when compiling for
7882Darwin/PowerPC and @samp{1} when compiling for Darwin/x86, so this
7883option has no effect on x86.
7884
7885@strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
7886to generate code that is not binary compatible with code generated
7887without that switch. Using this switch may require recompiling all
7888other modules in a program, including system libraries. Use this
7889switch to conform to a non-default data model.
7890
7891@item -mfix-and-continue
7892@itemx -ffix-and-continue
7893@itemx -findirect-data
7894@opindex mfix-and-continue
7895@opindex ffix-and-continue
7896@opindex findirect-data
7897Generate code suitable for fast turn around development. Needed to
7898enable gdb to dynamically load @code{.o} files into already running
7899programs. @option{-findirect-data} and @option{-ffix-and-continue}
7900are provided for backwards compatibility.
7901
7902@item -all_load
7903@opindex all_load
7904Loads all members of static archive libraries.
7905See man ld(1) for more information.
7906
7907@item -arch_errors_fatal
7908@opindex arch_errors_fatal
7909Cause the errors having to do with files that have the wrong architecture
7910to be fatal.
7911
7912@item -bind_at_load
7913@opindex bind_at_load
7914Causes the output file to be marked such that the dynamic linker will
7915bind all undefined references when the file is loaded or launched.
7916
7917@item -bundle
7918@opindex bundle
7919Produce a Mach-o bundle format file.
7920See man ld(1) for more information.
7921
7922@item -bundle_loader @var{executable}
7923@opindex bundle_loader
7924This option specifies the @var{executable} that will be loading the build
7925output file being linked. See man ld(1) for more information.
7926
7927@item -dynamiclib
7928@opindex dynamiclib
7929When passed this option, GCC will produce a dynamic library instead of
7930an executable when linking, using the Darwin @file{libtool} command.
7931
7932@item -force_cpusubtype_ALL
7933@opindex force_cpusubtype_ALL
7934This causes GCC's output file to have the @var{ALL} subtype, instead of
7935one controlled by the @option{-mcpu} or @option{-march} option.
7936
7937@item -allowable_client @var{client_name}
7938@itemx -client_name
7939@itemx -compatibility_version
7940@itemx -current_version
7941@itemx -dead_strip
7942@itemx -dependency-file
7943@itemx -dylib_file
7944@itemx -dylinker_install_name
7945@itemx -dynamic
7946@itemx -exported_symbols_list
7947@itemx -filelist
7948@itemx -flat_namespace
7949@itemx -force_flat_namespace
7950@itemx -headerpad_max_install_names
7951@itemx -image_base
7952@itemx -init
7953@itemx -install_name
7954@itemx -keep_private_externs
7955@itemx -multi_module
7956@itemx -multiply_defined
7957@itemx -multiply_defined_unused
7958@itemx -noall_load
7959@itemx -no_dead_strip_inits_and_terms
7960@itemx -nofixprebinding
7961@itemx -nomultidefs
7962@itemx -noprebind
7963@itemx -noseglinkedit
7964@itemx -pagezero_size
7965@itemx -prebind
7966@itemx -prebind_all_twolevel_modules
7967@itemx -private_bundle
7968@itemx -read_only_relocs
7969@itemx -sectalign
7970@itemx -sectobjectsymbols
7971@itemx -whyload
7972@itemx -seg1addr
7973@itemx -sectcreate
7974@itemx -sectobjectsymbols
7975@itemx -sectorder
7976@itemx -segaddr
7977@itemx -segs_read_only_addr
7978@itemx -segs_read_write_addr
7979@itemx -seg_addr_table
7980@itemx -seg_addr_table_filename
7981@itemx -seglinkedit
7982@itemx -segprot
7983@itemx -segs_read_only_addr
7984@itemx -segs_read_write_addr
7985@itemx -single_module
7986@itemx -static
7987@itemx -sub_library
7988@itemx -sub_umbrella
7989@itemx -twolevel_namespace
7990@itemx -umbrella
7991@itemx -undefined
7992@itemx -unexported_symbols_list
7993@itemx -weak_reference_mismatches
7994@itemx -whatsloaded
7995
7996@opindex allowable_client
7997@opindex client_name
7998@opindex compatibility_version
7999@opindex current_version
8000@opindex dead_strip
8001@opindex dependency-file
8002@opindex dylib_file
8003@opindex dylinker_install_name
8004@opindex dynamic
8005@opindex exported_symbols_list
8006@opindex filelist
8007@opindex flat_namespace
8008@opindex force_flat_namespace
8009@opindex headerpad_max_install_names
8010@opindex image_base
8011@opindex init
8012@opindex install_name
8013@opindex keep_private_externs
8014@opindex multi_module
8015@opindex multiply_defined
8016@opindex multiply_defined_unused
8017@opindex noall_load
8018@opindex no_dead_strip_inits_and_terms
8019@opindex nofixprebinding
8020@opindex nomultidefs
8021@opindex noprebind
8022@opindex noseglinkedit
8023@opindex pagezero_size
8024@opindex prebind
8025@opindex prebind_all_twolevel_modules
8026@opindex private_bundle
8027@opindex read_only_relocs
8028@opindex sectalign
8029@opindex sectobjectsymbols
8030@opindex whyload
8031@opindex seg1addr
8032@opindex sectcreate
8033@opindex sectobjectsymbols
8034@opindex sectorder
8035@opindex segaddr
8036@opindex segs_read_only_addr
8037@opindex segs_read_write_addr
8038@opindex seg_addr_table
8039@opindex seg_addr_table_filename
8040@opindex seglinkedit
8041@opindex segprot
8042@opindex segs_read_only_addr
8043@opindex segs_read_write_addr
8044@opindex single_module
8045@opindex static
8046@opindex sub_library
8047@opindex sub_umbrella
8048@opindex twolevel_namespace
8049@opindex umbrella
8050@opindex undefined
8051@opindex unexported_symbols_list
8052@opindex weak_reference_mismatches
8053@opindex whatsloaded
8054
8055These options are passed to the Darwin linker. The Darwin linker man page
8056describes them in detail.
8057@end table
8058
8059@node DEC Alpha Options
8060@subsection DEC Alpha Options
8061
8062These @samp{-m} options are defined for the DEC Alpha implementations:
8063
8064@table @gcctabopt
8065@item -mno-soft-float
8066@itemx -msoft-float
8067@opindex mno-soft-float
8068@opindex msoft-float
8069Use (do not use) the hardware floating-point instructions for
8070floating-point operations. When @option{-msoft-float} is specified,
8071functions in @file{libgcc.a} will be used to perform floating-point
8072operations. Unless they are replaced by routines that emulate the
8073floating-point operations, or compiled in such a way as to call such
8074emulations routines, these routines will issue floating-point
8075operations. If you are compiling for an Alpha without floating-point
8076operations, you must ensure that the library is built so as not to call
8077them.
8078
8079Note that Alpha implementations without floating-point operations are
8080required to have floating-point registers.
8081
8082@item -mfp-reg
8083@itemx -mno-fp-regs
8084@opindex mfp-reg
8085@opindex mno-fp-regs
8086Generate code that uses (does not use) the floating-point register set.
8087@option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
8088register set is not used, floating point operands are passed in integer
8089registers as if they were integers and floating-point results are passed
8090in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
8091so any function with a floating-point argument or return value called by code
8092compiled with @option{-mno-fp-regs} must also be compiled with that
8093option.
8094
8095A typical use of this option is building a kernel that does not use,
8096and hence need not save and restore, any floating-point registers.
8097
8098@item -mieee
8099@opindex mieee
8100The Alpha architecture implements floating-point hardware optimized for
8101maximum performance. It is mostly compliant with the IEEE floating
8102point standard. However, for full compliance, software assistance is
8103required. This option generates code fully IEEE compliant code
8104@emph{except} that the @var{inexact-flag} is not maintained (see below).
8105If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
8106defined during compilation. The resulting code is less efficient but is
8107able to correctly support denormalized numbers and exceptional IEEE
8108values such as not-a-number and plus/minus infinity. Other Alpha
8109compilers call this option @option{-ieee_with_no_inexact}.
8110
8111@item -mieee-with-inexact
8112@opindex mieee-with-inexact
8113This is like @option{-mieee} except the generated code also maintains
8114the IEEE @var{inexact-flag}. Turning on this option causes the
8115generated code to implement fully-compliant IEEE math. In addition to
8116@code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
8117macro. On some Alpha implementations the resulting code may execute
8118significantly slower than the code generated by default. Since there is
8119very little code that depends on the @var{inexact-flag}, you should
8120normally not specify this option. Other Alpha compilers call this
8121option @option{-ieee_with_inexact}.
8122
8123@item -mfp-trap-mode=@var{trap-mode}
8124@opindex mfp-trap-mode
8125This option controls what floating-point related traps are enabled.
8126Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
8127The trap mode can be set to one of four values:
8128
8129@table @samp
8130@item n
8131This is the default (normal) setting. The only traps that are enabled
8132are the ones that cannot be disabled in software (e.g., division by zero
8133trap).
8134
8135@item u
8136In addition to the traps enabled by @samp{n}, underflow traps are enabled
8137as well.
8138
8139@item su
8140Like @samp{u}, but the instructions are marked to be safe for software
8141completion (see Alpha architecture manual for details).
8142
8143@item sui
8144Like @samp{su}, but inexact traps are enabled as well.
8145@end table
8146
8147@item -mfp-rounding-mode=@var{rounding-mode}
8148@opindex mfp-rounding-mode
8149Selects the IEEE rounding mode. Other Alpha compilers call this option
8150@option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
8151of:
8152
8153@table @samp
8154@item n
8155Normal IEEE rounding mode. Floating point numbers are rounded towards
8156the nearest machine number or towards the even machine number in case
8157of a tie.
8158
8159@item m
8160Round towards minus infinity.
8161
8162@item c
8163Chopped rounding mode. Floating point numbers are rounded towards zero.
8164
8165@item d
8166Dynamic rounding mode. A field in the floating point control register
8167(@var{fpcr}, see Alpha architecture reference manual) controls the
8168rounding mode in effect. The C library initializes this register for
8169rounding towards plus infinity. Thus, unless your program modifies the
8170@var{fpcr}, @samp{d} corresponds to round towards plus infinity.
8171@end table
8172
8173@item -mtrap-precision=@var{trap-precision}
8174@opindex mtrap-precision
8175In the Alpha architecture, floating point traps are imprecise. This
8176means without software assistance it is impossible to recover from a
8177floating trap and program execution normally needs to be terminated.
8178GCC can generate code that can assist operating system trap handlers
8179in determining the exact location that caused a floating point trap.
8180Depending on the requirements of an application, different levels of
8181precisions can be selected:
8182
8183@table @samp
8184@item p
8185Program precision. This option is the default and means a trap handler
8186can only identify which program caused a floating point exception.
8187
8188@item f
8189Function precision. The trap handler can determine the function that
8190caused a floating point exception.
8191
8192@item i
8193Instruction precision. The trap handler can determine the exact
8194instruction that caused a floating point exception.
8195@end table
8196
8197Other Alpha compilers provide the equivalent options called
8198@option{-scope_safe} and @option{-resumption_safe}.
8199
8200@item -mieee-conformant
8201@opindex mieee-conformant
8202This option marks the generated code as IEEE conformant. You must not
8203use this option unless you also specify @option{-mtrap-precision=i} and either
8204@option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
8205is to emit the line @samp{.eflag 48} in the function prologue of the
8206generated assembly file. Under DEC Unix, this has the effect that
8207IEEE-conformant math library routines will be linked in.
8208
8209@item -mbuild-constants
8210@opindex mbuild-constants
8211Normally GCC examines a 32- or 64-bit integer constant to
8212see if it can construct it from smaller constants in two or three
8213instructions. If it cannot, it will output the constant as a literal and
8214generate code to load it from the data segment at runtime.
8215
8216Use this option to require GCC to construct @emph{all} integer constants
8217using code, even if it takes more instructions (the maximum is six).
8218
8219You would typically use this option to build a shared library dynamic
8220loader. Itself a shared library, it must relocate itself in memory
8221before it can find the variables and constants in its own data segment.
8222
8223@item -malpha-as
8224@itemx -mgas
8225@opindex malpha-as
8226@opindex mgas
8227Select whether to generate code to be assembled by the vendor-supplied
8228assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
8229
8230@item -mbwx
8231@itemx -mno-bwx
8232@itemx -mcix
8233@itemx -mno-cix
8234@itemx -mfix
8235@itemx -mno-fix
8236@itemx -mmax
8237@itemx -mno-max
8238@opindex mbwx
8239@opindex mno-bwx
8240@opindex mcix
8241@opindex mno-cix
8242@opindex mfix
8243@opindex mno-fix
8244@opindex mmax
8245@opindex mno-max
8246Indicate whether GCC should generate code to use the optional BWX,
8247CIX, FIX and MAX instruction sets. The default is to use the instruction
8248sets supported by the CPU type specified via @option{-mcpu=} option or that
8249of the CPU on which GCC was built if none was specified.
8250
8251@item -mfloat-vax
8252@itemx -mfloat-ieee
8253@opindex mfloat-vax
8254@opindex mfloat-ieee
8255Generate code that uses (does not use) VAX F and G floating point
8256arithmetic instead of IEEE single and double precision.
8257
8258@item -mexplicit-relocs
8259@itemx -mno-explicit-relocs
8260@opindex mexplicit-relocs
8261@opindex mno-explicit-relocs
8262Older Alpha assemblers provided no way to generate symbol relocations
8263except via assembler macros. Use of these macros does not allow
8264optimal instruction scheduling. GNU binutils as of version 2.12
8265supports a new syntax that allows the compiler to explicitly mark
8266which relocations should apply to which instructions. This option
8267is mostly useful for debugging, as GCC detects the capabilities of
8268the assembler when it is built and sets the default accordingly.
8269
8270@item -msmall-data
8271@itemx -mlarge-data
8272@opindex msmall-data
8273@opindex mlarge-data
8274When @option{-mexplicit-relocs} is in effect, static data is
8275accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
8276is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
8277(the @code{.sdata} and @code{.sbss} sections) and are accessed via
827816-bit relocations off of the @code{$gp} register. This limits the
8279size of the small data area to 64KB, but allows the variables to be
8280directly accessed via a single instruction.
8281
8282The default is @option{-mlarge-data}. With this option the data area
8283is limited to just below 2GB@. Programs that require more than 2GB of
8284data must use @code{malloc} or @code{mmap} to allocate the data in the
8285heap instead of in the program's data segment.
8286
8287When generating code for shared libraries, @option{-fpic} implies
8288@option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
8289
8290@item -msmall-text
8291@itemx -mlarge-text
8292@opindex msmall-text
8293@opindex mlarge-text
8294When @option{-msmall-text} is used, the compiler assumes that the
8295code of the entire program (or shared library) fits in 4MB, and is
8296thus reachable with a branch instruction. When @option{-msmall-data}
8297is used, the compiler can assume that all local symbols share the
8298same @code{$gp} value, and thus reduce the number of instructions
8299required for a function call from 4 to 1.
8300
8301The default is @option{-mlarge-text}.
8302
8303@item -mcpu=@var{cpu_type}
8304@opindex mcpu
8305Set the instruction set and instruction scheduling parameters for
8306machine type @var{cpu_type}. You can specify either the @samp{EV}
8307style name or the corresponding chip number. GCC supports scheduling
8308parameters for the EV4, EV5 and EV6 family of processors and will
8309choose the default values for the instruction set from the processor
8310you specify. If you do not specify a processor type, GCC will default
8311to the processor on which the compiler was built.
8312
8313Supported values for @var{cpu_type} are
8314
8315@table @samp
8316@item ev4
8317@itemx ev45
8318@itemx 21064
8319Schedules as an EV4 and has no instruction set extensions.
8320
8321@item ev5
8322@itemx 21164
8323Schedules as an EV5 and has no instruction set extensions.
8324
8325@item ev56
8326@itemx 21164a
8327Schedules as an EV5 and supports the BWX extension.
8328
8329@item pca56
8330@itemx 21164pc
8331@itemx 21164PC
8332Schedules as an EV5 and supports the BWX and MAX extensions.
8333
8334@item ev6
8335@itemx 21264
8336Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
8337
8338@item ev67
8339@itemx 21264a
8340Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
8341@end table
8342
8343@item -mtune=@var{cpu_type}
8344@opindex mtune
8345Set only the instruction scheduling parameters for machine type
8346@var{cpu_type}. The instruction set is not changed.
8347
8348@item -mmemory-latency=@var{time}
8349@opindex mmemory-latency
8350Sets the latency the scheduler should assume for typical memory
8351references as seen by the application. This number is highly
8352dependent on the memory access patterns used by the application
8353and the size of the external cache on the machine.
8354
8355Valid options for @var{time} are
8356
8357@table @samp
8358@item @var{number}
8359A decimal number representing clock cycles.
8360
8361@item L1
8362@itemx L2
8363@itemx L3
8364@itemx main
8365The compiler contains estimates of the number of clock cycles for
8366``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
8367(also called Dcache, Scache, and Bcache), as well as to main memory.
8368Note that L3 is only valid for EV5.
8369
8370@end table
8371@end table
8372
8373@node DEC Alpha/VMS Options
8374@subsection DEC Alpha/VMS Options
8375
8376These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
8377
8378@table @gcctabopt
8379@item -mvms-return-codes
8380@opindex mvms-return-codes
8381Return VMS condition codes from main. The default is to return POSIX
8382style condition (e.g.@ error) codes.
8383@end table
8384
8385@node FRV Options
8386@subsection FRV Options
8387@cindex FRV Options
8388
8389@table @gcctabopt
8390@item -mgpr-32
8391@opindex mgpr-32
8392
8393Only use the first 32 general purpose registers.
8394
8395@item -mgpr-64
8396@opindex mgpr-64
8397
8398Use all 64 general purpose registers.
8399
8400@item -mfpr-32
8401@opindex mfpr-32
8402
8403Use only the first 32 floating point registers.
8404
8405@item -mfpr-64
8406@opindex mfpr-64
8407
8408Use all 64 floating point registers
8409
8410@item -mhard-float
8411@opindex mhard-float
8412
8413Use hardware instructions for floating point operations.
8414
8415@item -msoft-float
8416@opindex msoft-float
8417
8418Use library routines for floating point operations.
8419
8420@item -malloc-cc
8421@opindex malloc-cc
8422
8423Dynamically allocate condition code registers.
8424
8425@item -mfixed-cc
8426@opindex mfixed-cc
8427
8428Do not try to dynamically allocate condition code registers, only
8429use @code{icc0} and @code{fcc0}.
8430
8431@item -mdword
8432@opindex mdword
8433
8434Change ABI to use double word insns.
8435
8436@item -mno-dword
8437@opindex mno-dword
8438
8439Do not use double word instructions.
8440
8441@item -mdouble
8442@opindex mdouble
8443
8444Use floating point double instructions.
8445
8446@item -mno-double
8447@opindex mno-double
8448
8449Do not use floating point double instructions.
8450
8451@item -mmedia
8452@opindex mmedia
8453
8454Use media instructions.
8455
8456@item -mno-media
8457@opindex mno-media
8458
8459Do not use media instructions.
8460
8461@item -mmuladd
8462@opindex mmuladd
8463
8464Use multiply and add/subtract instructions.
8465
8466@item -mno-muladd
8467@opindex mno-muladd
8468
8469Do not use multiply and add/subtract instructions.
8470
8471@item -mfdpic
8472@opindex mfdpic
8473
8474Select the FDPIC ABI, that uses function descriptors to represent
8475pointers to functions. Without any PIC/PIE-related options, it
8476implies @option{-fPIE}. With @option{-fpic} or @option{-fpie}, it
8477assumes GOT entries and small data are within a 12-bit range from the
8478GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
8479are computed with 32 bits.
8480
8481@item -minline-plt
8482@opindex minline-plt
8483
8484Enable inlining of PLT entries in function calls to functions that are
8485not known to bind locally. It has no effect without @option{-mfdpic}.
8486It's enabled by default if optimizing for speed and compiling for
8487shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
8488optimization option such as @option{-O3} or above is present in the
8489command line.
8490
8491@item -mTLS
8492@opindex TLS
8493
8494Assume a large TLS segment when generating thread-local code.
8495
8496@item -mtls
8497@opindex tls
8498
8499Do not assume a large TLS segment when generating thread-local code.
8500
8501@item -mgprel-ro
8502@opindex mgprel-ro
8503
8504Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
8505that is known to be in read-only sections. It's enabled by default,
8506except for @option{-fpic} or @option{-fpie}: even though it may help
8507make the global offset table smaller, it trades 1 instruction for 4.
8508With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
8509one of which may be shared by multiple symbols, and it avoids the need
8510for a GOT entry for the referenced symbol, so it's more likely to be a
8511win. If it is not, @option{-mno-gprel-ro} can be used to disable it.
8512
8513@item -multilib-library-pic
8514@opindex multilib-library-pic
8515
8516Link with the (library, not FD) pic libraries. It's implied by
8517@option{-mlibrary-pic}, as well as by @option{-fPIC} and
8518@option{-fpic} without @option{-mfdpic}. You should never have to use
8519it explicitly.
8520
8521@item -mlinked-fp
8522@opindex mlinked-fp
8523
8524Follow the EABI requirement of always creating a frame pointer whenever
8525a stack frame is allocated. This option is enabled by default and can
8526be disabled with @option{-mno-linked-fp}.
8527
8528@item -mlong-calls
8529@opindex mlong-calls
8530
8531Use indirect addressing to call functions outside the current
8532compilation unit. This allows the functions to be placed anywhere
8533within the 32-bit address space.
8534
8535@item -malign-labels
8536@opindex malign-labels
8537
8538Try to align labels to an 8-byte boundary by inserting nops into the
8539previous packet. This option only has an effect when VLIW packing
8540is enabled. It doesn't create new packets; it merely adds nops to
8541existing ones.
8542
8543@item -mlibrary-pic
8544@opindex mlibrary-pic
8545
8546Generate position-independent EABI code.
8547
8548@item -macc-4
8549@opindex macc-4
8550
8551Use only the first four media accumulator registers.
8552
8553@item -macc-8
8554@opindex macc-8
8555
8556Use all eight media accumulator registers.
8557
8558@item -mpack
8559@opindex mpack
8560
8561Pack VLIW instructions.
8562
8563@item -mno-pack
8564@opindex mno-pack
8565
8566Do not pack VLIW instructions.
8567
8568@item -mno-eflags
8569@opindex mno-eflags
8570
8571Do not mark ABI switches in e_flags.
8572
8573@item -mcond-move
8574@opindex mcond-move
8575
8576Enable the use of conditional-move instructions (default).
8577
8578This switch is mainly for debugging the compiler and will likely be removed
8579in a future version.
8580
8581@item -mno-cond-move
8582@opindex mno-cond-move
8583
8584Disable the use of conditional-move instructions.
8585
8586This switch is mainly for debugging the compiler and will likely be removed
8587in a future version.
8588
8589@item -mscc
8590@opindex mscc
8591
8592Enable the use of conditional set instructions (default).
8593
8594This switch is mainly for debugging the compiler and will likely be removed
8595in a future version.
8596
8597@item -mno-scc
8598@opindex mno-scc
8599
8600Disable the use of conditional set instructions.
8601
8602This switch is mainly for debugging the compiler and will likely be removed
8603in a future version.
8604
8605@item -mcond-exec
8606@opindex mcond-exec
8607
8608Enable the use of conditional execution (default).
8609
8610This switch is mainly for debugging the compiler and will likely be removed
8611in a future version.
8612
8613@item -mno-cond-exec
8614@opindex mno-cond-exec
8615
8616Disable the use of conditional execution.
8617
8618This switch is mainly for debugging the compiler and will likely be removed
8619in a future version.
8620
8621@item -mvliw-branch
8622@opindex mvliw-branch
8623
8624Run a pass to pack branches into VLIW instructions (default).
8625
8626This switch is mainly for debugging the compiler and will likely be removed
8627in a future version.
8628
8629@item -mno-vliw-branch
8630@opindex mno-vliw-branch
8631
8632Do not run a pass to pack branches into VLIW instructions.
8633
8634This switch is mainly for debugging the compiler and will likely be removed
8635in a future version.
8636
8637@item -mmulti-cond-exec
8638@opindex mmulti-cond-exec
8639
8640Enable optimization of @code{&&} and @code{||} in conditional execution
8641(default).
8642
8643This switch is mainly for debugging the compiler and will likely be removed
8644in a future version.
8645
8646@item -mno-multi-cond-exec
8647@opindex mno-multi-cond-exec
8648
8649Disable optimization of @code{&&} and @code{||} in conditional execution.
8650
8651This switch is mainly for debugging the compiler and will likely be removed
8652in a future version.
8653
8654@item -mnested-cond-exec
8655@opindex mnested-cond-exec
8656
8657Enable nested conditional execution optimizations (default).
8658
8659This switch is mainly for debugging the compiler and will likely be removed
8660in a future version.
8661
8662@item -mno-nested-cond-exec
8663@opindex mno-nested-cond-exec
8664
8665Disable nested conditional execution optimizations.
8666
8667This switch is mainly for debugging the compiler and will likely be removed
8668in a future version.
8669
8670@item -moptimize-membar
8671@opindex moptimize-membar
8672
8673This switch removes redundant @code{membar} instructions from the
8674compiler generated code. It is enabled by default.
8675
8676@item -mno-optimize-membar
8677@opindex mno-optimize-membar
8678
8679This switch disables the automatic removal of redundant @code{membar}
8680instructions from the generated code.
8681
8682@item -mtomcat-stats
8683@opindex mtomcat-stats
8684
8685Cause gas to print out tomcat statistics.
8686
8687@item -mcpu=@var{cpu}
8688@opindex mcpu
8689
8690Select the processor type for which to generate code. Possible values are
8691@samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
8692@samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
8693
8694@end table
8695
8696@node GNU/Linux Options
8697@subsection GNU/Linux Options
8698
8699These @samp{-m} options are defined for GNU/Linux targets:
8700
8701@table @gcctabopt
8702@item -mglibc
8703@opindex mglibc
8704Use the GNU C library instead of uClibc. This is the default except
8705on @samp{*-*-linux-*uclibc*} targets.
8706
8707@item -muclibc
8708@opindex muclibc
8709Use uClibc instead of the GNU C library. This is the default on
8710@samp{*-*-linux-*uclibc*} targets.
8711@end table
8712
8713@node H8/300 Options
8714@subsection H8/300 Options
8715
8716These @samp{-m} options are defined for the H8/300 implementations:
8717
8718@table @gcctabopt
8719@item -mrelax
8720@opindex mrelax
8721Shorten some address references at link time, when possible; uses the
8722linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
8723ld, Using ld}, for a fuller description.
8724
8725@item -mh
8726@opindex mh
8727Generate code for the H8/300H@.
8728
8729@item -ms
8730@opindex ms
8731Generate code for the H8S@.
8732
8733@item -mn
8734@opindex mn
8735Generate code for the H8S and H8/300H in the normal mode. This switch
8736must be used either with @option{-mh} or @option{-ms}.
8737
8738@item -ms2600
8739@opindex ms2600
8740Generate code for the H8S/2600. This switch must be used with @option{-ms}.
8741
8742@item -mint32
8743@opindex mint32
8744Make @code{int} data 32 bits by default.
8745
8746@item -malign-300
8747@opindex malign-300
8748On the H8/300H and H8S, use the same alignment rules as for the H8/300.
8749The default for the H8/300H and H8S is to align longs and floats on 4
8750byte boundaries.
8751@option{-malign-300} causes them to be aligned on 2 byte boundaries.
8752This option has no effect on the H8/300.
8753@end table
8754
8755@node HPPA Options
8756@subsection HPPA Options
8757@cindex HPPA Options
8758
8759These @samp{-m} options are defined for the HPPA family of computers:
8760
8761@table @gcctabopt
8762@item -march=@var{architecture-type}
8763@opindex march
8764Generate code for the specified architecture. The choices for
8765@var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
87661.1, and @samp{2.0} for PA 2.0 processors. Refer to
8767@file{/usr/lib/sched.models} on an HP-UX system to determine the proper
8768architecture option for your machine. Code compiled for lower numbered
8769architectures will run on higher numbered architectures, but not the
8770other way around.
8771
8772@item -mpa-risc-1-0
8773@itemx -mpa-risc-1-1
8774@itemx -mpa-risc-2-0
8775@opindex mpa-risc-1-0
8776@opindex mpa-risc-1-1
8777@opindex mpa-risc-2-0
8778Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
8779
8780@item -mbig-switch
8781@opindex mbig-switch
8782Generate code suitable for big switch tables. Use this option only if
8783the assembler/linker complain about out of range branches within a switch
8784table.
8785
8786@item -mjump-in-delay
8787@opindex mjump-in-delay
8788Fill delay slots of function calls with unconditional jump instructions
8789by modifying the return pointer for the function call to be the target
8790of the conditional jump.
8791
8792@item -mdisable-fpregs
8793@opindex mdisable-fpregs
8794Prevent floating point registers from being used in any manner. This is
8795necessary for compiling kernels which perform lazy context switching of
8796floating point registers. If you use this option and attempt to perform
8797floating point operations, the compiler will abort.
8798
8799@item -mdisable-indexing
8800@opindex mdisable-indexing
8801Prevent the compiler from using indexing address modes. This avoids some
8802rather obscure problems when compiling MIG generated code under MACH@.
8803
8804@item -mno-space-regs
8805@opindex mno-space-regs
8806Generate code that assumes the target has no space registers. This allows
8807GCC to generate faster indirect calls and use unscaled index address modes.
8808
8809Such code is suitable for level 0 PA systems and kernels.
8810
8811@item -mfast-indirect-calls
8812@opindex mfast-indirect-calls
8813Generate code that assumes calls never cross space boundaries. This
8814allows GCC to emit code which performs faster indirect calls.
8815
8816This option will not work in the presence of shared libraries or nested
8817functions.
8818
8819@item -mfixed-range=@var{register-range}
8820@opindex mfixed-range
8821Generate code treating the given register range as fixed registers.
8822A fixed register is one that the register allocator can not use. This is
8823useful when compiling kernel code. A register range is specified as
8824two registers separated by a dash. Multiple register ranges can be
8825specified separated by a comma.
8826
8827@item -mlong-load-store
8828@opindex mlong-load-store
8829Generate 3-instruction load and store sequences as sometimes required by
8830the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
8831the HP compilers.
8832
8833@item -mportable-runtime
8834@opindex mportable-runtime
8835Use the portable calling conventions proposed by HP for ELF systems.
8836
8837@item -mgas
8838@opindex mgas
8839Enable the use of assembler directives only GAS understands.
8840
8841@item -mschedule=@var{cpu-type}
8842@opindex mschedule
8843Schedule code according to the constraints for the machine type
8844@var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
8845@samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer
8846to @file{/usr/lib/sched.models} on an HP-UX system to determine the
8847proper scheduling option for your machine. The default scheduling is
8848@samp{8000}.
8849
8850@item -mlinker-opt
8851@opindex mlinker-opt
8852Enable the optimization pass in the HP-UX linker. Note this makes symbolic
8853debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9
8854linkers in which they give bogus error messages when linking some programs.
8855
8856@item -msoft-float
8857@opindex msoft-float
8858Generate output containing library calls for floating point.
8859@strong{Warning:} the requisite libraries are not available for all HPPA
8860targets. Normally the facilities of the machine's usual C compiler are
8861used, but this cannot be done directly in cross-compilation. You must make
8862your own arrangements to provide suitable library functions for
8863cross-compilation. The embedded target @samp{hppa1.1-*-pro}
8864does provide software floating point support.
8865
8866@option{-msoft-float} changes the calling convention in the output file;
8867therefore, it is only useful if you compile @emph{all} of a program with
8868this option. In particular, you need to compile @file{libgcc.a}, the
8869library that comes with GCC, with @option{-msoft-float} in order for
8870this to work.
8871
8872@item -msio
8873@opindex msio
8874Generate the predefine, @code{_SIO}, for server IO@. The default is
8875@option{-mwsio}. This generates the predefines, @code{__hp9000s700},
8876@code{__hp9000s700__} and @code{_WSIO}, for workstation IO@. These
8877options are available under HP-UX and HI-UX@.
8878
8879@item -mgnu-ld
8880@opindex gnu-ld
8881Use GNU ld specific options. This passes @option{-shared} to ld when
8882building a shared library. It is the default when GCC is configured,
8883explicitly or implicitly, with the GNU linker. This option does not
8884have any affect on which ld is called, it only changes what parameters
8885are passed to that ld. The ld that is called is determined by the
8886@option{--with-ld} configure option, GCC's program search path, and
8887finally by the user's @env{PATH}. The linker used by GCC can be printed
8888using @samp{which `gcc -print-prog-name=ld`}. This option is only available
8889on the 64 bit HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
8890
8891@item -mhp-ld
8892@opindex hp-ld
8893Use HP ld specific options. This passes @option{-b} to ld when building
8894a shared library and passes @option{+Accept TypeMismatch} to ld on all
8895links. It is the default when GCC is configured, explicitly or
8896implicitly, with the HP linker. This option does not have any affect on
8897which ld is called, it only changes what parameters are passed to that
8898ld. The ld that is called is determined by the @option{--with-ld}
8899configure option, GCC's program search path, and finally by the user's
8900@env{PATH}. The linker used by GCC can be printed using @samp{which
8901`gcc -print-prog-name=ld`}. This option is only available on the 64 bit
8902HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
8903
8904@item -mlong-calls
8905@opindex mno-long-calls
8906Generate code that uses long call sequences. This ensures that a call
8907is always able to reach linker generated stubs. The default is to generate
8908long calls only when the distance from the call site to the beginning
8909of the function or translation unit, as the case may be, exceeds a
8910predefined limit set by the branch type being used. The limits for
8911normal calls are 7,600,000 and 240,000 bytes, respectively for the
8912PA 2.0 and PA 1.X architectures. Sibcalls are always limited at
8913240,000 bytes.
8914
8915Distances are measured from the beginning of functions when using the
8916@option{-ffunction-sections} option, or when using the @option{-mgas}
8917and @option{-mno-portable-runtime} options together under HP-UX with
8918the SOM linker.
8919
8920It is normally not desirable to use this option as it will degrade
8921performance. However, it may be useful in large applications,
8922particularly when partial linking is used to build the application.
8923
8924The types of long calls used depends on the capabilities of the
8925assembler and linker, and the type of code being generated. The
8926impact on systems that support long absolute calls, and long pic
8927symbol-difference or pc-relative calls should be relatively small.
8928However, an indirect call is used on 32-bit ELF systems in pic code
8929and it is quite long.
8930
8931@item -munix=@var{unix-std}
8932@opindex march
8933Generate compiler predefines and select a startfile for the specified
8934UNIX standard. The choices for @var{unix-std} are @samp{93}, @samp{95}
8935and @samp{98}. @samp{93} is supported on all HP-UX versions. @samp{95}
8936is available on HP-UX 10.10 and later. @samp{98} is available on HP-UX
893711.11 and later. The default values are @samp{93} for HP-UX 10.00,
8938@samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
8939and later.
8940
8941@option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
8942@option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
8943and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
8944@option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
8945@code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
8946@code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
8947
8948It is @emph{important} to note that this option changes the interfaces
8949for various library routines. It also affects the operational behavior
8950of the C library. Thus, @emph{extreme} care is needed in using this
8951option.
8952
8953Library code that is intended to operate with more than one UNIX
8954standard must test, set and restore the variable @var{__xpg4_extended_mask}
8955as appropriate. Most GNU software doesn't provide this capability.
8956
8957@item -nolibdld
8958@opindex nolibdld
8959Suppress the generation of link options to search libdld.sl when the
8960@option{-static} option is specified on HP-UX 10 and later.
8961
8962@item -static
8963@opindex static
8964The HP-UX implementation of setlocale in libc has a dependency on
8965libdld.sl. There isn't an archive version of libdld.sl. Thus,
8966when the @option{-static} option is specified, special link options
8967are needed to resolve this dependency.
8968
8969On HP-UX 10 and later, the GCC driver adds the necessary options to
8970link with libdld.sl when the @option{-static} option is specified.
8971This causes the resulting binary to be dynamic. On the 64-bit port,
8972the linkers generate dynamic binaries by default in any case. The
8973@option{-nolibdld} option can be used to prevent the GCC driver from
8974adding these link options.
8975
8976@item -threads
8977@opindex threads
8978Add support for multithreading with the @dfn{dce thread} library
8979under HP-UX@. This option sets flags for both the preprocessor and
8980linker.
8981@end table
8982
8983@node i386 and x86-64 Options
8984@subsection Intel 386 and AMD x86-64 Options
8985@cindex i386 Options
8986@cindex x86-64 Options
8987@cindex Intel 386 Options
8988@cindex AMD x86-64 Options
8989
8990These @samp{-m} options are defined for the i386 and x86-64 family of
8991computers:
8992
8993@table @gcctabopt
8994@item -mtune=@var{cpu-type}
8995@opindex mtune
8996Tune to @var{cpu-type} everything applicable about the generated code, except
8997for the ABI and the set of available instructions. The choices for
8998@var{cpu-type} are:
8999@table @emph
9000@item generic
9001Produce code optimized for the most common IA32/AMD64/EM64T processors.
9002If you know the CPU on which your code will run, then you should use
9003the corresponding @option{-mtune} option instead of
9004@option{-mtune=generic}. But, if you do not know exactly what CPU users
9005of your application will have, then you should use this option.
9006
9007As new processors are deployed in the marketplace, the behavior of this
9008option will change. Therefore, if you upgrade to a newer version of
9009GCC, the code generated option will change to reflect the processors
9010that were most common when that version of GCC was released.
9011
9012There is no @option{-march=generic} option because @option{-march}
9013indicates the instruction set the compiler can use, and there is no
9014generic instruction set applicable to all processors. In contrast,
9015@option{-mtune} indicates the processor (or, in this case, collection of
9016processors) for which the code is optimized.
9017@item native
9018This selects the CPU to tune for at compilation time by determining
9019the processor type of the compiling machine. Using @option{-mtune=native}
9020will produce code optimized for the local machine under the constraints
9021of the selected instruction set. Using @option{-march=native} will
9022enable all instruction subsets supported by the local machine (hence
9023the result might not run on different machines).
9024@item i386
9025Original Intel's i386 CPU@.
9026@item i486
9027Intel's i486 CPU@. (No scheduling is implemented for this chip.)
9028@item i586, pentium
9029Intel Pentium CPU with no MMX support.
9030@item pentium-mmx
9031Intel PentiumMMX CPU based on Pentium core with MMX instruction set support.
9032@item pentiumpro
9033Intel PentiumPro CPU@.
9034@item i686
9035Same as @code{generic}, but when used as @code{march} option, PentiumPro
9036instruction set will be used, so the code will run on all i686 family chips.
9037@item pentium2
9038Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support.
9039@item pentium3, pentium3m
9040Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set
9041support.
9042@item pentium-m
9043Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set
9044support. Used by Centrino notebooks.
9045@item pentium4, pentium4m
9046Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support.
9047@item prescott
9048Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction
9049set support.
9050@item nocona
9051Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE,
9052SSE2 and SSE3 instruction set support.
9053@item core2
9054Intel Core2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3
9055instruction set support.
9056@item k6
9057AMD K6 CPU with MMX instruction set support.
9058@item k6-2, k6-3
9059Improved versions of AMD K6 CPU with MMX and 3dNOW! instruction set support.
9060@item athlon, athlon-tbird
9061AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and SSE prefetch instructions
9062support.
9063@item athlon-4, athlon-xp, athlon-mp
9064Improved AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and full SSE
9065instruction set support.
9066@item k8, opteron, athlon64, athlon-fx
9067AMD K8 core based CPUs with x86-64 instruction set support. (This supersets
9068MMX, SSE, SSE2, 3dNOW!, enhanced 3dNOW! and 64-bit instruction set extensions.)
9069@item k8-sse3, opteron-sse3, athlon64-sse3
9070Improved versions of k8, opteron and athlon64 with SSE3 instruction set support.
9071@item amdfam10, barcelona
9072AMD Family 10h core based CPUs with x86-64 instruction set support. (This
9073supersets MMX, SSE, SSE2, SSE3, SSE4A, 3dNOW!, enhanced 3dNOW!, ABM and 64-bit
9074instruction set extensions.)
9075@item winchip-c6
9076IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction
9077set support.
9078@item winchip2
9079IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3dNOW!
9080instruction set support.
9081@item c3
9082Via C3 CPU with MMX and 3dNOW! instruction set support. (No scheduling is
9083implemented for this chip.)
9084@item c3-2
9085Via C3-2 CPU with MMX and SSE instruction set support. (No scheduling is
9086implemented for this chip.)
9087@item geode
9088Embedded AMD CPU with MMX and 3dNOW! instruction set support.
9089@end table
9090
9091While picking a specific @var{cpu-type} will schedule things appropriately
9092for that particular chip, the compiler will not generate any code that
9093does not run on the i386 without the @option{-march=@var{cpu-type}} option
9094being used.
9095
9096@item -march=@var{cpu-type}
9097@opindex march
9098Generate instructions for the machine type @var{cpu-type}. The choices
9099for @var{cpu-type} are the same as for @option{-mtune}. Moreover,
9100specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}.
9101
9102@item -mcpu=@var{cpu-type}
9103@opindex mcpu
9104A deprecated synonym for @option{-mtune}.
9105
9106@item -m386
9107@itemx -m486
9108@itemx -mpentium
9109@itemx -mpentiumpro
9110@opindex m386
9111@opindex m486
9112@opindex mpentium
9113@opindex mpentiumpro
9114These options are synonyms for @option{-mtune=i386}, @option{-mtune=i486},
9115@option{-mtune=pentium}, and @option{-mtune=pentiumpro} respectively.
9116These synonyms are deprecated.
9117
9118@item -mfpmath=@var{unit}
9119@opindex march
9120Generate floating point arithmetics for selected unit @var{unit}. The choices
9121for @var{unit} are:
9122
9123@table @samp
9124@item 387
9125Use the standard 387 floating point coprocessor present majority of chips and
9126emulated otherwise. Code compiled with this option will run almost everywhere.
9127The temporary results are computed in 80bit precision instead of precision
9128specified by the type resulting in slightly different results compared to most
9129of other chips. See @option{-ffloat-store} for more detailed description.
9130
9131This is the default choice for i386 compiler.
9132
9133@item sse
9134Use scalar floating point instructions present in the SSE instruction set.
9135This instruction set is supported by Pentium3 and newer chips, in the AMD line
9136by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE
9137instruction set supports only single precision arithmetics, thus the double and
9138extended precision arithmetics is still done using 387. Later version, present
9139only in Pentium4 and the future AMD x86-64 chips supports double precision
9140arithmetics too.
9141
9142For the i386 compiler, you need to use @option{-march=@var{cpu-type}}, @option{-msse}
9143or @option{-msse2} switches to enable SSE extensions and make this option
9144effective. For the x86-64 compiler, these extensions are enabled by default.
9145
9146The resulting code should be considerably faster in the majority of cases and avoid
9147the numerical instability problems of 387 code, but may break some existing
9148code that expects temporaries to be 80bit.
9149
9150This is the default choice for the x86-64 compiler.
9151
9152@item sse,387
9153Attempt to utilize both instruction sets at once. This effectively double the
9154amount of available registers and on chips with separate execution units for
9155387 and SSE the execution resources too. Use this option with care, as it is
9156still experimental, because the GCC register allocator does not model separate
9157functional units well resulting in instable performance.
9158@end table
9159
9160@item -masm=@var{dialect}
9161@opindex masm=@var{dialect}
9162Output asm instructions using selected @var{dialect}. Supported
9163choices are @samp{intel} or @samp{att} (the default one). Darwin does
9164not support @samp{intel}.
9165
9166@item -mieee-fp
9167@itemx -mno-ieee-fp
9168@opindex mieee-fp
9169@opindex mno-ieee-fp
9170Control whether or not the compiler uses IEEE floating point
9171comparisons. These handle correctly the case where the result of a
9172comparison is unordered.
9173
9174@item -msoft-float
9175@opindex msoft-float
9176Generate output containing library calls for floating point.
9177@strong{Warning:} the requisite libraries are not part of GCC@.
9178Normally the facilities of the machine's usual C compiler are used, but
9179this can't be done directly in cross-compilation. You must make your
9180own arrangements to provide suitable library functions for
9181cross-compilation.
9182
9183On machines where a function returns floating point results in the 80387
9184register stack, some floating point opcodes may be emitted even if
9185@option{-msoft-float} is used.
9186
9187@item -mno-fp-ret-in-387
9188@opindex mno-fp-ret-in-387
9189Do not use the FPU registers for return values of functions.
9190
9191The usual calling convention has functions return values of types
9192@code{float} and @code{double} in an FPU register, even if there
9193is no FPU@. The idea is that the operating system should emulate
9194an FPU@.
9195
9196The option @option{-mno-fp-ret-in-387} causes such values to be returned
9197in ordinary CPU registers instead.
9198
9199@item -mno-fancy-math-387
9200@opindex mno-fancy-math-387
9201Some 387 emulators do not support the @code{sin}, @code{cos} and
9202@code{sqrt} instructions for the 387. Specify this option to avoid
9203generating those instructions. This option is the default on
9204OpenBSD and NetBSD@. This option is overridden when @option{-march}
9205indicates that the target cpu will always have an FPU and so the
9206instruction will not need emulation. As of revision 2.6.1, these
9207instructions are not generated unless you also use the
9208@option{-funsafe-math-optimizations} switch.
9209
9210@item -malign-double
9211@itemx -mno-align-double
9212@opindex malign-double
9213@opindex mno-align-double
9214Control whether GCC aligns @code{double}, @code{long double}, and
9215@code{long long} variables on a two word boundary or a one word
9216boundary. Aligning @code{double} variables on a two word boundary will
9217produce code that runs somewhat faster on a @samp{Pentium} at the
9218expense of more memory.
9219
9220On x86-64, @option{-malign-double} is enabled by default.
9221
9222@strong{Warning:} if you use the @option{-malign-double} switch,
9223structures containing the above types will be aligned differently than
9224the published application binary interface specifications for the 386
9225and will not be binary compatible with structures in code compiled
9226without that switch.
9227
9228@item -m96bit-long-double
9229@itemx -m128bit-long-double
9230@opindex m96bit-long-double
9231@opindex m128bit-long-double
9232These switches control the size of @code{long double} type. The i386
9233application binary interface specifies the size to be 96 bits,
9234so @option{-m96bit-long-double} is the default in 32 bit mode.
9235
9236Modern architectures (Pentium and newer) would prefer @code{long double}
9237to be aligned to an 8 or 16 byte boundary. In arrays or structures
9238conforming to the ABI, this would not be possible. So specifying a
9239@option{-m128bit-long-double} will align @code{long double}
9240to a 16 byte boundary by padding the @code{long double} with an additional
924132 bit zero.
9242
9243In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
9244its ABI specifies that @code{long double} is to be aligned on 16 byte boundary.
9245
9246Notice that neither of these options enable any extra precision over the x87
9247standard of 80 bits for a @code{long double}.
9248
9249@strong{Warning:} if you override the default value for your target ABI, the
9250structures and arrays containing @code{long double} variables will change
9251their size as well as function calling convention for function taking
9252@code{long double} will be modified. Hence they will not be binary
9253compatible with arrays or structures in code compiled without that switch.
9254
9255@item -mmlarge-data-threshold=@var{number}
9256@opindex mlarge-data-threshold=@var{number}
9257When @option{-mcmodel=medium} is specified, the data greater than
9258@var{threshold} are placed in large data section. This value must be the
9259same across all object linked into the binary and defaults to 65535.
9260
9261@item -msvr3-shlib
9262@itemx -mno-svr3-shlib
9263@opindex msvr3-shlib
9264@opindex mno-svr3-shlib
9265Control whether GCC places uninitialized local variables into the
9266@code{bss} or @code{data} segments. @option{-msvr3-shlib} places them
9267into @code{bss}. These options are meaningful only on System V Release 3.
9268
9269@item -mrtd
9270@opindex mrtd
9271Use a different function-calling convention, in which functions that
9272take a fixed number of arguments return with the @code{ret} @var{num}
9273instruction, which pops their arguments while returning. This saves one
9274instruction in the caller since there is no need to pop the arguments
9275there.
9276
9277You can specify that an individual function is called with this calling
9278sequence with the function attribute @samp{stdcall}. You can also
9279override the @option{-mrtd} option by using the function attribute
9280@samp{cdecl}. @xref{Function Attributes}.
9281
9282@strong{Warning:} this calling convention is incompatible with the one
9283normally used on Unix, so you cannot use it if you need to call
9284libraries compiled with the Unix compiler.
9285
9286Also, you must provide function prototypes for all functions that
9287take variable numbers of arguments (including @code{printf});
9288otherwise incorrect code will be generated for calls to those
9289functions.
9290
9291In addition, seriously incorrect code will result if you call a
9292function with too many arguments. (Normally, extra arguments are
9293harmlessly ignored.)
9294
9295@item -mregparm=@var{num}
9296@opindex mregparm
9297Control how many registers are used to pass integer arguments. By
9298default, no registers are used to pass arguments, and at most 3
9299registers can be used. You can control this behavior for a specific
9300function by using the function attribute @samp{regparm}.
9301@xref{Function Attributes}.
9302
9303@strong{Warning:} if you use this switch, and
9304@var{num} is nonzero, then you must build all modules with the same
9305value, including any libraries. This includes the system libraries and
9306startup modules.
9307
9308@item -msseregparm
9309@opindex msseregparm
9310Use SSE register passing conventions for float and double arguments
9311and return values. You can control this behavior for a specific
9312function by using the function attribute @samp{sseregparm}.
9313@xref{Function Attributes}.
9314
9315@strong{Warning:} if you use this switch then you must build all
9316modules with the same value, including any libraries. This includes
9317the system libraries and startup modules.
9318
9319@item -mstackrealign
9320@opindex mstackrealign
9321Realign the stack at entry. On the Intel x86, the
9322@option{-mstackrealign} option will generate an alternate prologue and
9323epilogue that realigns the runtime stack. This supports mixing legacy
9324codes that keep a 4-byte aligned stack with modern codes that keep a
932516-byte stack for SSE compatibility. The alternate prologue and
9326epilogue are slower and bigger than the regular ones, and the
9327alternate prologue requires an extra scratch register; this lowers the
9328number of registers available if used in conjunction with the
9329@code{regparm} attribute. The @option{-mstackrealign} option is
9330incompatible with the nested function prologue; this is considered a
9331hard error. See also the attribute @code{force_align_arg_pointer},
9332applicable to individual functions.
9333
9334@item -mpreferred-stack-boundary=@var{num}
9335@opindex mpreferred-stack-boundary
9336Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
9337byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
9338the default is 4 (16 bytes or 128 bits).
9339
9340On Pentium and PentiumPro, @code{double} and @code{long double} values
9341should be aligned to an 8 byte boundary (see @option{-malign-double}) or
9342suffer significant run time performance penalties. On Pentium III, the
9343Streaming SIMD Extension (SSE) data type @code{__m128} may not work
9344properly if it is not 16 byte aligned.
9345
9346To ensure proper alignment of this values on the stack, the stack boundary
9347must be as aligned as that required by any value stored on the stack.
9348Further, every function must be generated such that it keeps the stack
9349aligned. Thus calling a function compiled with a higher preferred
9350stack boundary from a function compiled with a lower preferred stack
9351boundary will most likely misalign the stack. It is recommended that
9352libraries that use callbacks always use the default setting.
9353
9354This extra alignment does consume extra stack space, and generally
9355increases code size. Code that is sensitive to stack space usage, such
9356as embedded systems and operating system kernels, may want to reduce the
9357preferred alignment to @option{-mpreferred-stack-boundary=2}.
9358
9359@item -mmmx
9360@itemx -mno-mmx
9361@item -msse
9362@itemx -mno-sse
9363@item -msse2
9364@itemx -mno-sse2
9365@item -msse3
9366@itemx -mno-sse3
9367@item -mssse3
9368@itemx -mno-ssse3
9369@item -msse4a
9370@item -mno-sse4a
9371@item -m3dnow
9372@itemx -mno-3dnow
9373@item -mpopcnt
9374@itemx -mno-popcnt
9375@item -mabm
9376@itemx -mno-abm
9377@item -maes
9378@itemx -mno-aes
9379@opindex mmmx
9380@opindex mno-mmx
9381@opindex msse
9382@opindex mno-sse
9383@opindex m3dnow
9384@opindex mno-3dnow
9385These switches enable or disable the use of instructions in the MMX,
9386SSE, SSE2, SSE3, SSSE3, SSE4A, ABM, AES or 3DNow! extended
9387instruction sets. These extensions are also available as built-in
9388functions: see @ref{X86 Built-in Functions}, for details of the functions
9389enabled and disabled by these switches.
9390
9391To have SSE/SSE2 instructions generated automatically from floating-point
9392code (as opposed to 387 instructions), see @option{-mfpmath=sse}.
9393
9394These options will enable GCC to use these extended instructions in
9395generated code, even without @option{-mfpmath=sse}. Applications which
9396perform runtime CPU detection must compile separate files for each
9397supported architecture, using the appropriate flags. In particular,
9398the file containing the CPU detection code should be compiled without
9399these options.
9400
9401@item -mpush-args
9402@itemx -mno-push-args
9403@opindex mpush-args
9404@opindex mno-push-args
9405Use PUSH operations to store outgoing parameters. This method is shorter
9406and usually equally fast as method using SUB/MOV operations and is enabled
9407by default. In some cases disabling it may improve performance because of
9408improved scheduling and reduced dependencies.
9409
9410@item -maccumulate-outgoing-args
9411@opindex maccumulate-outgoing-args
9412If enabled, the maximum amount of space required for outgoing arguments will be
9413computed in the function prologue. This is faster on most modern CPUs
9414because of reduced dependencies, improved scheduling and reduced stack usage
9415when preferred stack boundary is not equal to 2. The drawback is a notable
9416increase in code size. This switch implies @option{-mno-push-args}.
9417
9418@item -mthreads
9419@opindex mthreads
9420Support thread-safe exception handling on @samp{Mingw32}. Code that relies
9421on thread-safe exception handling must compile and link all code with the
9422@option{-mthreads} option. When compiling, @option{-mthreads} defines
9423@option{-D_MT}; when linking, it links in a special thread helper library
9424@option{-lmingwthrd} which cleans up per thread exception handling data.
9425
9426@item -mno-align-stringops
9427@opindex mno-align-stringops
9428Do not align destination of inlined string operations. This switch reduces
9429code size and improves performance in case the destination is already aligned,
9430but GCC doesn't know about it.
9431
9432@item -minline-all-stringops
9433@opindex minline-all-stringops
9434By default GCC inlines string operations only when destination is known to be
9435aligned at least to 4 byte boundary. This enables more inlining, increase code
9436size, but may improve performance of code that depends on fast memcpy, strlen
9437and memset for short lengths.
9438
9439@item -momit-leaf-frame-pointer
9440@opindex momit-leaf-frame-pointer
9441Don't keep the frame pointer in a register for leaf functions. This
9442avoids the instructions to save, set up and restore frame pointers and
9443makes an extra register available in leaf functions. The option
9444@option{-fomit-frame-pointer} removes the frame pointer for all functions
9445which might make debugging harder.
9446
9447@item -mtls-direct-seg-refs
9448@itemx -mno-tls-direct-seg-refs
9449@opindex mtls-direct-seg-refs
9450Controls whether TLS variables may be accessed with offsets from the
9451TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
9452or whether the thread base pointer must be added. Whether or not this
9453is legal depends on the operating system, and whether it maps the
9454segment to cover the entire TLS area.
9455
9456For systems that use GNU libc, the default is on.
9457@end table
9458
9459These @samp{-m} switches are supported in addition to the above
9460on AMD x86-64 processors in 64-bit environments.
9461
9462@table @gcctabopt
9463@item -m32
9464@itemx -m64
9465@opindex m32
9466@opindex m64
9467Generate code for a 32-bit or 64-bit environment.
9468The 32-bit environment sets int, long and pointer to 32 bits and
9469generates code that runs on any i386 system.
9470The 64-bit environment sets int to 32 bits and long and pointer
9471to 64 bits and generates code for AMD's x86-64 architecture. For
9472darwin only the -m64 option turns off the @option{-fno-pic} and
9473@option{-mdynamic-no-pic} options.
9474
9475@item -mno-red-zone
9476@opindex no-red-zone
9477Do not use a so called red zone for x86-64 code. The red zone is mandated
9478by the x86-64 ABI, it is a 128-byte area beyond the location of the
9479stack pointer that will not be modified by signal or interrupt handlers
9480and therefore can be used for temporary data without adjusting the stack
9481pointer. The flag @option{-mno-red-zone} disables this red zone.
9482
9483@item -mcmodel=small
9484@opindex mcmodel=small
9485Generate code for the small code model: the program and its symbols must
9486be linked in the lower 2 GB of the address space. Pointers are 64 bits.
9487Programs can be statically or dynamically linked. This is the default
9488code model.
9489
9490@item -mcmodel=kernel
9491@opindex mcmodel=kernel
9492Generate code for the kernel code model. The kernel runs in the
9493negative 2 GB of the address space.
9494This model has to be used for Linux kernel code.
9495
9496@item -mcmodel=medium
9497@opindex mcmodel=medium
9498Generate code for the medium model: The program is linked in the lower 2
9499GB of the address space but symbols can be located anywhere in the
9500address space. Programs can be statically or dynamically linked, but
9501building of shared libraries are not supported with the medium model.
9502
9503@item -mcmodel=large
9504@opindex mcmodel=large
9505Generate code for the large model: This model makes no assumptions
9506about addresses and sizes of sections. Currently GCC does not implement
9507this model.
9508@end table
9509
9510@node IA-64 Options
9511@subsection IA-64 Options
9512@cindex IA-64 Options
9513
9514These are the @samp{-m} options defined for the Intel IA-64 architecture.
9515
9516@table @gcctabopt
9517@item -mbig-endian
9518@opindex mbig-endian
9519Generate code for a big endian target. This is the default for HP-UX@.
9520
9521@item -mlittle-endian
9522@opindex mlittle-endian
9523Generate code for a little endian target. This is the default for AIX5
9524and GNU/Linux.
9525
9526@item -mgnu-as
9527@itemx -mno-gnu-as
9528@opindex mgnu-as
9529@opindex mno-gnu-as
9530Generate (or don't) code for the GNU assembler. This is the default.
9531@c Also, this is the default if the configure option @option{--with-gnu-as}
9532@c is used.
9533
9534@item -mgnu-ld
9535@itemx -mno-gnu-ld
9536@opindex mgnu-ld
9537@opindex mno-gnu-ld
9538Generate (or don't) code for the GNU linker. This is the default.
9539@c Also, this is the default if the configure option @option{--with-gnu-ld}
9540@c is used.
9541
9542@item -mno-pic
9543@opindex mno-pic
9544Generate code that does not use a global pointer register. The result
9545is not position independent code, and violates the IA-64 ABI@.
9546
9547@item -mvolatile-asm-stop
9548@itemx -mno-volatile-asm-stop
9549@opindex mvolatile-asm-stop
9550@opindex mno-volatile-asm-stop
9551Generate (or don't) a stop bit immediately before and after volatile asm
9552statements.
9553
9554@item -mregister-names
9555@itemx -mno-register-names
9556@opindex mregister-names
9557@opindex mno-register-names
9558Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
9559the stacked registers. This may make assembler output more readable.
9560
9561@item -mno-sdata
9562@itemx -msdata
9563@opindex mno-sdata
9564@opindex msdata
9565Disable (or enable) optimizations that use the small data section. This may
9566be useful for working around optimizer bugs.
9567
9568@item -mconstant-gp
9569@opindex mconstant-gp
9570Generate code that uses a single constant global pointer value. This is
9571useful when compiling kernel code.
9572
9573@item -mauto-pic
9574@opindex mauto-pic
9575Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
9576This is useful when compiling firmware code.
9577
9578@item -minline-float-divide-min-latency
9579@opindex minline-float-divide-min-latency
9580Generate code for inline divides of floating point values
9581using the minimum latency algorithm.
9582
9583@item -minline-float-divide-max-throughput
9584@opindex minline-float-divide-max-throughput
9585Generate code for inline divides of floating point values
9586using the maximum throughput algorithm.
9587
9588@item -minline-int-divide-min-latency
9589@opindex minline-int-divide-min-latency
9590Generate code for inline divides of integer values
9591using the minimum latency algorithm.
9592
9593@item -minline-int-divide-max-throughput
9594@opindex minline-int-divide-max-throughput
9595Generate code for inline divides of integer values
9596using the maximum throughput algorithm.
9597
9598@item -minline-sqrt-min-latency
9599@opindex minline-sqrt-min-latency
9600Generate code for inline square roots
9601using the minimum latency algorithm.
9602
9603@item -minline-sqrt-max-throughput
9604@opindex minline-sqrt-max-throughput
9605Generate code for inline square roots
9606using the maximum throughput algorithm.
9607
9608@item -mno-dwarf2-asm
9609@itemx -mdwarf2-asm
9610@opindex mno-dwarf2-asm
9611@opindex mdwarf2-asm
9612Don't (or do) generate assembler code for the DWARF2 line number debugging
9613info. This may be useful when not using the GNU assembler.
9614
9615@item -mearly-stop-bits
9616@itemx -mno-early-stop-bits
9617@opindex mearly-stop-bits
9618@opindex mno-early-stop-bits
9619Allow stop bits to be placed earlier than immediately preceding the
9620instruction that triggered the stop bit. This can improve instruction
9621scheduling, but does not always do so.
9622
9623@item -mfixed-range=@var{register-range}
9624@opindex mfixed-range
9625Generate code treating the given register range as fixed registers.
9626A fixed register is one that the register allocator can not use. This is
9627useful when compiling kernel code. A register range is specified as
9628two registers separated by a dash. Multiple register ranges can be
9629specified separated by a comma.
9630
9631@item -mtls-size=@var{tls-size}
9632@opindex mtls-size
9633Specify bit size of immediate TLS offsets. Valid values are 14, 22, and
963464.
9635
9636@item -mtune=@var{cpu-type}
9637@opindex mtune
9638Tune the instruction scheduling for a particular CPU, Valid values are
9639itanium, itanium1, merced, itanium2, and mckinley.
9640
9641@item -mt
9642@itemx -pthread
9643@opindex mt
9644@opindex pthread
9645Add support for multithreading using the POSIX threads library. This
9646option sets flags for both the preprocessor and linker. It does
9647not affect the thread safety of object code produced by the compiler or
9648that of libraries supplied with it. These are HP-UX specific flags.
9649
9650@item -milp32
9651@itemx -mlp64
9652@opindex milp32
9653@opindex mlp64
9654Generate code for a 32-bit or 64-bit environment.
9655The 32-bit environment sets int, long and pointer to 32 bits.
9656The 64-bit environment sets int to 32 bits and long and pointer
9657to 64 bits. These are HP-UX specific flags.
9658
9659@item -mno-sched-br-data-spec
9660@itemx -msched-br-data-spec
9661@opindex mno-sched-br-data-spec
9662@opindex msched-br-data-spec
9663(Dis/En)able data speculative scheduling before reload.
9664This will result in generation of the ld.a instructions and
9665the corresponding check instructions (ld.c / chk.a).
9666The default is 'disable'.
9667
9668@item -msched-ar-data-spec
9669@itemx -mno-sched-ar-data-spec
9670@opindex msched-ar-data-spec
9671@opindex mno-sched-ar-data-spec
9672(En/Dis)able data speculative scheduling after reload.
9673This will result in generation of the ld.a instructions and
9674the corresponding check instructions (ld.c / chk.a).
9675The default is 'enable'.
9676
9677@item -mno-sched-control-spec
9678@itemx -msched-control-spec
9679@opindex mno-sched-control-spec
9680@opindex msched-control-spec
9681(Dis/En)able control speculative scheduling. This feature is
9682available only during region scheduling (i.e. before reload).
9683This will result in generation of the ld.s instructions and
9684the corresponding check instructions chk.s .
9685The default is 'disable'.
9686
9687@item -msched-br-in-data-spec
9688@itemx -mno-sched-br-in-data-spec
9689@opindex msched-br-in-data-spec
9690@opindex mno-sched-br-in-data-spec
9691(En/Dis)able speculative scheduling of the instructions that
9692are dependent on the data speculative loads before reload.
9693This is effective only with @option{-msched-br-data-spec} enabled.
9694The default is 'enable'.
9695
9696@item -msched-ar-in-data-spec
9697@itemx -mno-sched-ar-in-data-spec
9698@opindex msched-ar-in-data-spec
9699@opindex mno-sched-ar-in-data-spec
9700(En/Dis)able speculative scheduling of the instructions that
9701are dependent on the data speculative loads after reload.
9702This is effective only with @option{-msched-ar-data-spec} enabled.
9703The default is 'enable'.
9704
9705@item -msched-in-control-spec
9706@itemx -mno-sched-in-control-spec
9707@opindex msched-in-control-spec
9708@opindex mno-sched-in-control-spec
9709(En/Dis)able speculative scheduling of the instructions that
9710are dependent on the control speculative loads.
9711This is effective only with @option{-msched-control-spec} enabled.
9712The default is 'enable'.
9713
9714@item -msched-ldc
9715@itemx -mno-sched-ldc
9716@opindex msched-ldc
9717@opindex mno-sched-ldc
9718(En/Dis)able use of simple data speculation checks ld.c .
9719If disabled, only chk.a instructions will be emitted to check
9720data speculative loads.
9721The default is 'enable'.
9722
9723@item -mno-sched-control-ldc
9724@itemx -msched-control-ldc
9725@opindex mno-sched-control-ldc
9726@opindex msched-control-ldc
9727(Dis/En)able use of ld.c instructions to check control speculative loads.
9728If enabled, in case of control speculative load with no speculatively
9729scheduled dependent instructions this load will be emitted as ld.sa and
9730ld.c will be used to check it.
9731The default is 'disable'.
9732
9733@item -mno-sched-spec-verbose
9734@itemx -msched-spec-verbose
9735@opindex mno-sched-spec-verbose
9736@opindex msched-spec-verbose
9737(Dis/En)able printing of the information about speculative motions.
9738
9739@item -mno-sched-prefer-non-data-spec-insns
9740@itemx -msched-prefer-non-data-spec-insns
9741@opindex mno-sched-prefer-non-data-spec-insns
9742@opindex msched-prefer-non-data-spec-insns
9743If enabled, data speculative instructions will be chosen for schedule
9744only if there are no other choices at the moment. This will make
9745the use of the data speculation much more conservative.
9746The default is 'disable'.
9747
9748@item -mno-sched-prefer-non-control-spec-insns
9749@itemx -msched-prefer-non-control-spec-insns
9750@opindex mno-sched-prefer-non-control-spec-insns
9751@opindex msched-prefer-non-control-spec-insns
9752If enabled, control speculative instructions will be chosen for schedule
9753only if there are no other choices at the moment. This will make
9754the use of the control speculation much more conservative.
9755The default is 'disable'.
9756
9757@item -mno-sched-count-spec-in-critical-path
9758@itemx -msched-count-spec-in-critical-path
9759@opindex mno-sched-count-spec-in-critical-path
9760@opindex msched-count-spec-in-critical-path
9761If enabled, speculative dependencies will be considered during
9762computation of the instructions priorities. This will make the use of the
9763speculation a bit more conservative.
9764The default is 'disable'.
9765
9766@end table
9767
9768@node M32C Options
9769@subsection M32C Options
9770@cindex M32C options
9771
9772@table @gcctabopt
9773@item -mcpu=@var{name}
9774@opindex mcpu=
9775Select the CPU for which code is generated. @var{name} may be one of
9776@samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to
9777/60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for
9778the M32C/80 series.
9779
9780@item -msim
9781@opindex msim
9782Specifies that the program will be run on the simulator. This causes
9783an alternate runtime library to be linked in which supports, for
9784example, file I/O. You must not use this option when generating
9785programs that will run on real hardware; you must provide your own
9786runtime library for whatever I/O functions are needed.
9787
9788@item -memregs=@var{number}
9789@opindex memregs=
9790Specifies the number of memory-based pseudo-registers GCC will use
9791during code generation. These pseudo-registers will be used like real
9792registers, so there is a tradeoff between GCC's ability to fit the
9793code into available registers, and the performance penalty of using
9794memory instead of registers. Note that all modules in a program must
9795be compiled with the same value for this option. Because of that, you
9796must not use this option with the default runtime libraries gcc
9797builds.
9798
9799@end table
9800
9801@node M32R/D Options
9802@subsection M32R/D Options
9803@cindex M32R/D options
9804
9805These @option{-m} options are defined for Renesas M32R/D architectures:
9806
9807@table @gcctabopt
9808@item -m32r2
9809@opindex m32r2
9810Generate code for the M32R/2@.
9811
9812@item -m32rx
9813@opindex m32rx
9814Generate code for the M32R/X@.
9815
9816@item -m32r
9817@opindex m32r
9818Generate code for the M32R@. This is the default.
9819
9820@item -mmodel=small
9821@opindex mmodel=small
9822Assume all objects live in the lower 16MB of memory (so that their addresses
9823can be loaded with the @code{ld24} instruction), and assume all subroutines
9824are reachable with the @code{bl} instruction.
9825This is the default.
9826
9827The addressability of a particular object can be set with the
9828@code{model} attribute.
9829
9830@item -mmodel=medium
9831@opindex mmodel=medium
9832Assume objects may be anywhere in the 32-bit address space (the compiler
9833will generate @code{seth/add3} instructions to load their addresses), and
9834assume all subroutines are reachable with the @code{bl} instruction.
9835
9836@item -mmodel=large
9837@opindex mmodel=large
9838Assume objects may be anywhere in the 32-bit address space (the compiler
9839will generate @code{seth/add3} instructions to load their addresses), and
9840assume subroutines may not be reachable with the @code{bl} instruction
9841(the compiler will generate the much slower @code{seth/add3/jl}
9842instruction sequence).
9843
9844@item -msdata=none
9845@opindex msdata=none
9846Disable use of the small data area. Variables will be put into
9847one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
9848@code{section} attribute has been specified).
9849This is the default.
9850
9851The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
9852Objects may be explicitly put in the small data area with the
9853@code{section} attribute using one of these sections.
9854
9855@item -msdata=sdata
9856@opindex msdata=sdata
9857Put small global and static data in the small data area, but do not
9858generate special code to reference them.
9859
9860@item -msdata=use
9861@opindex msdata=use
9862Put small global and static data in the small data area, and generate
9863special instructions to reference them.
9864
9865@item -G @var{num}
9866@opindex G
9867@cindex smaller data references
9868Put global and static objects less than or equal to @var{num} bytes
9869into the small data or bss sections instead of the normal data or bss
9870sections. The default value of @var{num} is 8.
9871The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
9872for this option to have any effect.
9873
9874All modules should be compiled with the same @option{-G @var{num}} value.
9875Compiling with different values of @var{num} may or may not work; if it
9876doesn't the linker will give an error message---incorrect code will not be
9877generated.
9878
9879@item -mdebug
9880@opindex mdebug
9881Makes the M32R specific code in the compiler display some statistics
9882that might help in debugging programs.
9883
9884@item -malign-loops
9885@opindex malign-loops
9886Align all loops to a 32-byte boundary.
9887
9888@item -mno-align-loops
9889@opindex mno-align-loops
9890Do not enforce a 32-byte alignment for loops. This is the default.
9891
9892@item -missue-rate=@var{number}
9893@opindex missue-rate=@var{number}
9894Issue @var{number} instructions per cycle. @var{number} can only be 1
9895or 2.
9896
9897@item -mbranch-cost=@var{number}
9898@opindex mbranch-cost=@var{number}
9899@var{number} can only be 1 or 2. If it is 1 then branches will be
9900preferred over conditional code, if it is 2, then the opposite will
9901apply.
9902
9903@item -mflush-trap=@var{number}
9904@opindex mflush-trap=@var{number}
9905Specifies the trap number to use to flush the cache. The default is
990612. Valid numbers are between 0 and 15 inclusive.
9907
9908@item -mno-flush-trap
9909@opindex mno-flush-trap
9910Specifies that the cache cannot be flushed by using a trap.
9911
9912@item -mflush-func=@var{name}
9913@opindex mflush-func=@var{name}
9914Specifies the name of the operating system function to call to flush
9915the cache. The default is @emph{_flush_cache}, but a function call
9916will only be used if a trap is not available.
9917
9918@item -mno-flush-func
9919@opindex mno-flush-func
9920Indicates that there is no OS function for flushing the cache.
9921
9922@end table
9923
9924@node M680x0 Options
9925@subsection M680x0 Options
9926@cindex M680x0 options
9927
9928These are the @samp{-m} options defined for the 68000 series. The default
9929values for these options depends on which style of 68000 was selected when
9930the compiler was configured; the defaults for the most common choices are
9931given below.
9932
9933@table @gcctabopt
9934@item -m68000
9935@itemx -mc68000
9936@opindex m68000
9937@opindex mc68000
9938Generate output for a 68000. This is the default
9939when the compiler is configured for 68000-based systems.
9940
9941Use this option for microcontrollers with a 68000 or EC000 core,
9942including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
9943
9944@item -m68020
9945@itemx -mc68020
9946@opindex m68020
9947@opindex mc68020
9948Generate output for a 68020. This is the default
9949when the compiler is configured for 68020-based systems.
9950
9951@item -m68881
9952@opindex m68881
9953Generate output containing 68881 instructions for floating point.
9954This is the default for most 68020 systems unless @option{--nfp} was
9955specified when the compiler was configured.
9956
9957@item -m68030
9958@opindex m68030
9959Generate output for a 68030. This is the default when the compiler is
9960configured for 68030-based systems.
9961
9962@item -m68040
9963@opindex m68040
9964Generate output for a 68040. This is the default when the compiler is
9965configured for 68040-based systems.
9966
9967This option inhibits the use of 68881/68882 instructions that have to be
9968emulated by software on the 68040. Use this option if your 68040 does not
9969have code to emulate those instructions.
9970
9971@item -m68060
9972@opindex m68060
9973Generate output for a 68060. This is the default when the compiler is
9974configured for 68060-based systems.
9975
9976This option inhibits the use of 68020 and 68881/68882 instructions that
9977have to be emulated by software on the 68060. Use this option if your 68060
9978does not have code to emulate those instructions.
9979
9980@item -mcpu32
9981@opindex mcpu32
9982Generate output for a CPU32. This is the default
9983when the compiler is configured for CPU32-based systems.
9984
9985Use this option for microcontrollers with a
9986CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
998768336, 68340, 68341, 68349 and 68360.
9988
9989@item -m5200
9990@opindex m5200
9991Generate output for a 520X ``coldfire'' family cpu. This is the default
9992when the compiler is configured for 520X-based systems.
9993
9994Use this option for microcontroller with a 5200 core, including
9995the MCF5202, MCF5203, MCF5204 and MCF5202.
9996
9997@item -mcfv4e
9998@opindex mcfv4e
9999Generate output for a ColdFire V4e family cpu (e.g.@: 547x/548x).
10000This includes use of hardware floating point instructions.
10001
10002@item -m68020-40
10003@opindex m68020-40
10004Generate output for a 68040, without using any of the new instructions.
10005This results in code which can run relatively efficiently on either a
1000668020/68881 or a 68030 or a 68040. The generated code does use the
1000768881 instructions that are emulated on the 68040.
10008
10009@item -m68020-60
10010@opindex m68020-60
10011Generate output for a 68060, without using any of the new instructions.
10012This results in code which can run relatively efficiently on either a
1001368020/68881 or a 68030 or a 68040. The generated code does use the
1001468881 instructions that are emulated on the 68060.
10015
10016@item -msoft-float
10017@opindex msoft-float
10018Generate output containing library calls for floating point.
10019@strong{Warning:} the requisite libraries are not available for all m68k
10020targets. Normally the facilities of the machine's usual C compiler are
10021used, but this can't be done directly in cross-compilation. You must
10022make your own arrangements to provide suitable library functions for
10023cross-compilation. The embedded targets @samp{m68k-*-aout} and
10024@samp{m68k-*-coff} do provide software floating point support.
10025
10026@item -mshort
10027@opindex mshort
10028Consider type @code{int} to be 16 bits wide, like @code{short int}.
10029Additionally, parameters passed on the stack are also aligned to a
1003016-bit boundary even on targets whose API mandates promotion to 32-bit.
10031
10032@item -mnobitfield
10033@opindex mnobitfield
10034Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
10035and @option{-m5200} options imply @w{@option{-mnobitfield}}.
10036
10037@item -mbitfield
10038@opindex mbitfield
10039Do use the bit-field instructions. The @option{-m68020} option implies
10040@option{-mbitfield}. This is the default if you use a configuration
10041designed for a 68020.
10042
10043@item -mrtd
10044@opindex mrtd
10045Use a different function-calling convention, in which functions
10046that take a fixed number of arguments return with the @code{rtd}
10047instruction, which pops their arguments while returning. This
10048saves one instruction in the caller since there is no need to pop
10049the arguments there.
10050
10051This calling convention is incompatible with the one normally
10052used on Unix, so you cannot use it if you need to call libraries
10053compiled with the Unix compiler.
10054
10055Also, you must provide function prototypes for all functions that
10056take variable numbers of arguments (including @code{printf});
10057otherwise incorrect code will be generated for calls to those
10058functions.
10059
10060In addition, seriously incorrect code will result if you call a
10061function with too many arguments. (Normally, extra arguments are
10062harmlessly ignored.)
10063
10064The @code{rtd} instruction is supported by the 68010, 68020, 68030,
1006568040, 68060 and CPU32 processors, but not by the 68000 or 5200.
10066
10067@item -malign-int
10068@itemx -mno-align-int
10069@opindex malign-int
10070@opindex mno-align-int
10071Control whether GCC aligns @code{int}, @code{long}, @code{long long},
10072@code{float}, @code{double}, and @code{long double} variables on a 32-bit
10073boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
10074Aligning variables on 32-bit boundaries produces code that runs somewhat
10075faster on processors with 32-bit busses at the expense of more memory.
10076
10077@strong{Warning:} if you use the @option{-malign-int} switch, GCC will
10078align structures containing the above types differently than
10079most published application binary interface specifications for the m68k.
10080
10081@item -mpcrel
10082@opindex mpcrel
10083Use the pc-relative addressing mode of the 68000 directly, instead of
10084using a global offset table. At present, this option implies @option{-fpic},
10085allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
10086not presently supported with @option{-mpcrel}, though this could be supported for
1008768020 and higher processors.
10088
10089@item -mno-strict-align
10090@itemx -mstrict-align
10091@opindex mno-strict-align
10092@opindex mstrict-align
10093Do not (do) assume that unaligned memory references will be handled by
10094the system.
10095
10096@item -msep-data
10097Generate code that allows the data segment to be located in a different
10098area of memory from the text segment. This allows for execute in place in
10099an environment without virtual memory management. This option implies
10100@option{-fPIC}.
10101
10102@item -mno-sep-data
10103Generate code that assumes that the data segment follows the text segment.
10104This is the default.
10105
10106@item -mid-shared-library
10107Generate code that supports shared libraries via the library ID method.
10108This allows for execute in place and shared libraries in an environment
10109without virtual memory management. This option implies @option{-fPIC}.
10110
10111@item -mno-id-shared-library
10112Generate code that doesn't assume ID based shared libraries are being used.
10113This is the default.
10114
10115@item -mshared-library-id=n
10116Specified the identification number of the ID based shared library being
10117compiled. Specifying a value of 0 will generate more compact code, specifying
10118other values will force the allocation of that number to the current
10119library but is no more space or time efficient than omitting this option.
10120
10121@end table
10122
10123@node M68hc1x Options
10124@subsection M68hc1x Options
10125@cindex M68hc1x options
10126
10127These are the @samp{-m} options defined for the 68hc11 and 68hc12
10128microcontrollers. The default values for these options depends on
10129which style of microcontroller was selected when the compiler was configured;
10130the defaults for the most common choices are given below.
10131
10132@table @gcctabopt
10133@item -m6811
10134@itemx -m68hc11
10135@opindex m6811
10136@opindex m68hc11
10137Generate output for a 68HC11. This is the default
10138when the compiler is configured for 68HC11-based systems.
10139
10140@item -m6812
10141@itemx -m68hc12
10142@opindex m6812
10143@opindex m68hc12
10144Generate output for a 68HC12. This is the default
10145when the compiler is configured for 68HC12-based systems.
10146
10147@item -m68S12
10148@itemx -m68hcs12
10149@opindex m68S12
10150@opindex m68hcs12
10151Generate output for a 68HCS12.
10152
10153@item -mauto-incdec
10154@opindex mauto-incdec
10155Enable the use of 68HC12 pre and post auto-increment and auto-decrement
10156addressing modes.
10157
10158@item -minmax
10159@itemx -nominmax
10160@opindex minmax
10161@opindex mnominmax
10162Enable the use of 68HC12 min and max instructions.
10163
10164@item -mlong-calls
10165@itemx -mno-long-calls
10166@opindex mlong-calls
10167@opindex mno-long-calls
10168Treat all calls as being far away (near). If calls are assumed to be
10169far away, the compiler will use the @code{call} instruction to
10170call a function and the @code{rtc} instruction for returning.
10171
10172@item -mshort
10173@opindex mshort
10174Consider type @code{int} to be 16 bits wide, like @code{short int}.
10175
10176@item -msoft-reg-count=@var{count}
10177@opindex msoft-reg-count
10178Specify the number of pseudo-soft registers which are used for the
10179code generation. The maximum number is 32. Using more pseudo-soft
10180register may or may not result in better code depending on the program.
10181The default is 4 for 68HC11 and 2 for 68HC12.
10182
10183@end table
10184
10185@node MCore Options
10186@subsection MCore Options
10187@cindex MCore options
10188
10189These are the @samp{-m} options defined for the Motorola M*Core
10190processors.
10191
10192@table @gcctabopt
10193
10194@item -mhardlit
10195@itemx -mno-hardlit
10196@opindex mhardlit
10197@opindex mno-hardlit
10198Inline constants into the code stream if it can be done in two
10199instructions or less.
10200
10201@item -mdiv
10202@itemx -mno-div
10203@opindex mdiv
10204@opindex mno-div
10205Use the divide instruction. (Enabled by default).
10206
10207@item -mrelax-immediate
10208@itemx -mno-relax-immediate
10209@opindex mrelax-immediate
10210@opindex mno-relax-immediate
10211Allow arbitrary sized immediates in bit operations.
10212
10213@item -mwide-bitfields
10214@itemx -mno-wide-bitfields
10215@opindex mwide-bitfields
10216@opindex mno-wide-bitfields
10217Always treat bit-fields as int-sized.
10218
10219@item -m4byte-functions
10220@itemx -mno-4byte-functions
10221@opindex m4byte-functions
10222@opindex mno-4byte-functions
10223Force all functions to be aligned to a four byte boundary.
10224
10225@item -mcallgraph-data
10226@itemx -mno-callgraph-data
10227@opindex mcallgraph-data
10228@opindex mno-callgraph-data
10229Emit callgraph information.
10230
10231@item -mslow-bytes
10232@itemx -mno-slow-bytes
10233@opindex mslow-bytes
10234@opindex mno-slow-bytes
10235Prefer word access when reading byte quantities.
10236
10237@item -mlittle-endian
10238@itemx -mbig-endian
10239@opindex mlittle-endian
10240@opindex mbig-endian
10241Generate code for a little endian target.
10242
10243@item -m210
10244@itemx -m340
10245@opindex m210
10246@opindex m340
10247Generate code for the 210 processor.
10248@end table
10249
10250@node MIPS Options
10251@subsection MIPS Options
10252@cindex MIPS options
10253
10254@table @gcctabopt
10255
10256@item -EB
10257@opindex EB
10258Generate big-endian code.
10259
10260@item -EL
10261@opindex EL
10262Generate little-endian code. This is the default for @samp{mips*el-*-*}
10263configurations.
10264
10265@item -march=@var{arch}
10266@opindex march
10267Generate code that will run on @var{arch}, which can be the name of a
10268generic MIPS ISA, or the name of a particular processor.
10269The ISA names are:
10270@samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
10271@samp{mips32}, @samp{mips32r2}, and @samp{mips64}.
10272The processor names are:
10273@samp{4kc}, @samp{4km}, @samp{4kp},
10274@samp{5kc}, @samp{5kf},
10275@samp{20kc},
10276@samp{24k}, @samp{24kc}, @samp{24kf}, @samp{24kx},
10277@samp{m4k},
10278@samp{orion},
10279@samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
10280@samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000},
10281@samp{rm7000}, @samp{rm9000},
10282@samp{sb1},
10283@samp{sr71000},
10284@samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
10285@samp{vr5000}, @samp{vr5400} and @samp{vr5500}.
10286The special value @samp{from-abi} selects the
10287most compatible architecture for the selected ABI (that is,
10288@samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
10289
10290In processor names, a final @samp{000} can be abbreviated as @samp{k}
10291(for example, @samp{-march=r2k}). Prefixes are optional, and
10292@samp{vr} may be written @samp{r}.
10293
10294GCC defines two macros based on the value of this option. The first
10295is @samp{_MIPS_ARCH}, which gives the name of target architecture, as
10296a string. The second has the form @samp{_MIPS_ARCH_@var{foo}},
10297where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@.
10298For example, @samp{-march=r2000} will set @samp{_MIPS_ARCH}
10299to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}.
10300
10301Note that the @samp{_MIPS_ARCH} macro uses the processor names given
10302above. In other words, it will have the full prefix and will not
10303abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},
10304the macro names the resolved architecture (either @samp{"mips1"} or
10305@samp{"mips3"}). It names the default architecture when no
10306@option{-march} option is given.
10307
10308@item -mtune=@var{arch}
10309@opindex mtune
10310Optimize for @var{arch}. Among other things, this option controls
10311the way instructions are scheduled, and the perceived cost of arithmetic
10312operations. The list of @var{arch} values is the same as for
10313@option{-march}.
10314
10315When this option is not used, GCC will optimize for the processor
10316specified by @option{-march}. By using @option{-march} and
10317@option{-mtune} together, it is possible to generate code that will
10318run on a family of processors, but optimize the code for one
10319particular member of that family.
10320
10321@samp{-mtune} defines the macros @samp{_MIPS_TUNE} and
10322@samp{_MIPS_TUNE_@var{foo}}, which work in the same way as the
10323@samp{-march} ones described above.
10324
10325@item -mips1
10326@opindex mips1
10327Equivalent to @samp{-march=mips1}.
10328
10329@item -mips2
10330@opindex mips2
10331Equivalent to @samp{-march=mips2}.
10332
10333@item -mips3
10334@opindex mips3
10335Equivalent to @samp{-march=mips3}.
10336
10337@item -mips4
10338@opindex mips4
10339Equivalent to @samp{-march=mips4}.
10340
10341@item -mips32
10342@opindex mips32
10343Equivalent to @samp{-march=mips32}.
10344
10345@item -mips32r2
10346@opindex mips32r2
10347Equivalent to @samp{-march=mips32r2}.
10348
10349@item -mips64
10350@opindex mips64
10351Equivalent to @samp{-march=mips64}.
10352
10353@item -mips16
10354@itemx -mno-mips16
10355@opindex mips16
10356@opindex mno-mips16
10357Generate (do not generate) MIPS16 code. If GCC is targetting a
10358MIPS32 or MIPS64 architecture, it will make use of the MIPS16e ASE@.
10359
10360@item -mabi=32
10361@itemx -mabi=o64
10362@itemx -mabi=n32
10363@itemx -mabi=64
10364@itemx -mabi=eabi
10365@opindex mabi=32
10366@opindex mabi=o64
10367@opindex mabi=n32
10368@opindex mabi=64
10369@opindex mabi=eabi
10370Generate code for the given ABI@.
10371
10372Note that the EABI has a 32-bit and a 64-bit variant. GCC normally
10373generates 64-bit code when you select a 64-bit architecture, but you
10374can use @option{-mgp32} to get 32-bit code instead.
10375
10376For information about the O64 ABI, see
10377@w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
10378
10379@item -mabicalls
10380@itemx -mno-abicalls
10381@opindex mabicalls
10382@opindex mno-abicalls
10383Generate (do not generate) code that is suitable for SVR4-style
10384dynamic objects. @option{-mabicalls} is the default for SVR4-based
10385systems.
10386
10387@item -mshared
10388@itemx -mno-shared
10389Generate (do not generate) code that is fully position-independent,
10390and that can therefore be linked into shared libraries. This option
10391only affects @option{-mabicalls}.
10392
10393All @option{-mabicalls} code has traditionally been position-independent,
10394regardless of options like @option{-fPIC} and @option{-fpic}. However,
10395as an extension, the GNU toolchain allows executables to use absolute
10396accesses for locally-binding symbols. It can also use shorter GP
10397initialization sequences and generate direct calls to locally-defined
10398functions. This mode is selected by @option{-mno-shared}.
10399
10400@option{-mno-shared} depends on binutils 2.16 or higher and generates
10401objects that can only be linked by the GNU linker. However, the option
10402does not affect the ABI of the final executable; it only affects the ABI
10403of relocatable objects. Using @option{-mno-shared} will generally make
10404executables both smaller and quicker.
10405
10406@option{-mshared} is the default.
10407
10408@item -mxgot
10409@itemx -mno-xgot
10410@opindex mxgot
10411@opindex mno-xgot
10412Lift (do not lift) the usual restrictions on the size of the global
10413offset table.
10414
10415GCC normally uses a single instruction to load values from the GOT@.
10416While this is relatively efficient, it will only work if the GOT
10417is smaller than about 64k. Anything larger will cause the linker
10418to report an error such as:
10419
10420@cindex relocation truncated to fit (MIPS)
10421@smallexample
10422relocation truncated to fit: R_MIPS_GOT16 foobar
10423@end smallexample
10424
10425If this happens, you should recompile your code with @option{-mxgot}.
10426It should then work with very large GOTs, although it will also be
10427less efficient, since it will take three instructions to fetch the
10428value of a global symbol.
10429
10430Note that some linkers can create multiple GOTs. If you have such a
10431linker, you should only need to use @option{-mxgot} when a single object
10432file accesses more than 64k's worth of GOT entries. Very few do.
10433
10434These options have no effect unless GCC is generating position
10435independent code.
10436
10437@item -mgp32
10438@opindex mgp32
10439Assume that general-purpose registers are 32 bits wide.
10440
10441@item -mgp64
10442@opindex mgp64
10443Assume that general-purpose registers are 64 bits wide.
10444
10445@item -mfp32
10446@opindex mfp32
10447Assume that floating-point registers are 32 bits wide.
10448
10449@item -mfp64
10450@opindex mfp64
10451Assume that floating-point registers are 64 bits wide.
10452
10453@item -mhard-float
10454@opindex mhard-float
10455Use floating-point coprocessor instructions.
10456
10457@item -msoft-float
10458@opindex msoft-float
10459Do not use floating-point coprocessor instructions. Implement
10460floating-point calculations using library calls instead.
10461
10462@item -msingle-float
10463@opindex msingle-float
10464Assume that the floating-point coprocessor only supports single-precision
10465operations.
10466
10467@itemx -mdouble-float
10468@opindex mdouble-float
10469Assume that the floating-point coprocessor supports double-precision
10470operations. This is the default.
10471
10472@itemx -mdsp
10473@itemx -mno-dsp
10474@opindex mdsp
10475@opindex mno-dsp
10476Use (do not use) the MIPS DSP ASE. @xref{MIPS DSP Built-in Functions}.
10477
10478@itemx -mpaired-single
10479@itemx -mno-paired-single
10480@opindex mpaired-single
10481@opindex mno-paired-single
10482Use (do not use) paired-single floating-point instructions.
10483@xref{MIPS Paired-Single Support}. This option can only be used
10484when generating 64-bit code and requires hardware floating-point
10485support to be enabled.
10486
10487@itemx -mips3d
10488@itemx -mno-mips3d
10489@opindex mips3d
10490@opindex mno-mips3d
10491Use (do not use) the MIPS-3D ASE@. @xref{MIPS-3D Built-in Functions}.
10492The option @option{-mips3d} implies @option{-mpaired-single}.
10493
10494@item -mlong64
10495@opindex mlong64
10496Force @code{long} types to be 64 bits wide. See @option{-mlong32} for
10497an explanation of the default and the way that the pointer size is
10498determined.
10499
10500@item -mlong32
10501@opindex mlong32
10502Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
10503
10504The default size of @code{int}s, @code{long}s and pointers depends on
10505the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI
10506uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
1050732-bit @code{long}s. Pointers are the same size as @code{long}s,
10508or the same size as integer registers, whichever is smaller.
10509
10510@item -msym32
10511@itemx -mno-sym32
10512@opindex msym32
10513@opindex mno-sym32
10514Assume (do not assume) that all symbols have 32-bit values, regardless
10515of the selected ABI@. This option is useful in combination with
10516@option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
10517to generate shorter and faster references to symbolic addresses.
10518
10519@item -G @var{num}
10520@opindex G
10521@cindex smaller data references (MIPS)
10522@cindex gp-relative references (MIPS)
10523Put global and static items less than or equal to @var{num} bytes into
10524the small data or bss section instead of the normal data or bss section.
10525This allows the data to be accessed using a single instruction.
10526
10527All modules should be compiled with the same @option{-G @var{num}}
10528value.
10529
10530@item -membedded-data
10531@itemx -mno-embedded-data
10532@opindex membedded-data
10533@opindex mno-embedded-data
10534Allocate variables to the read-only data section first if possible, then
10535next in the small data section if possible, otherwise in data. This gives
10536slightly slower code than the default, but reduces the amount of RAM required
10537when executing, and thus may be preferred for some embedded systems.
10538
10539@item -muninit-const-in-rodata
10540@itemx -mno-uninit-const-in-rodata
10541@opindex muninit-const-in-rodata
10542@opindex mno-uninit-const-in-rodata
10543Put uninitialized @code{const} variables in the read-only data section.
10544This option is only meaningful in conjunction with @option{-membedded-data}.
10545
10546@item -msplit-addresses
10547@itemx -mno-split-addresses
10548@opindex msplit-addresses
10549@opindex mno-split-addresses
10550Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
10551relocation operators. This option has been superseded by
10552@option{-mexplicit-relocs} but is retained for backwards compatibility.
10553
10554@item -mexplicit-relocs
10555@itemx -mno-explicit-relocs
10556@opindex mexplicit-relocs
10557@opindex mno-explicit-relocs
10558Use (do not use) assembler relocation operators when dealing with symbolic
10559addresses. The alternative, selected by @option{-mno-explicit-relocs},
10560is to use assembler macros instead.
10561
10562@option{-mexplicit-relocs} is the default if GCC was configured
10563to use an assembler that supports relocation operators.
10564
10565@item -mcheck-zero-division
10566@itemx -mno-check-zero-division
10567@opindex mcheck-zero-division
10568@opindex mno-check-zero-division
10569Trap (do not trap) on integer division by zero. The default is
10570@option{-mcheck-zero-division}.
10571
10572@item -mdivide-traps
10573@itemx -mdivide-breaks
10574@opindex mdivide-traps
10575@opindex mdivide-breaks
10576MIPS systems check for division by zero by generating either a
10577conditional trap or a break instruction. Using traps results in
10578smaller code, but is only supported on MIPS II and later. Also, some
10579versions of the Linux kernel have a bug that prevents trap from
10580generating the proper signal (@code{SIGFPE}). Use @option{-mdivide-traps} to
10581allow conditional traps on architectures that support them and
10582@option{-mdivide-breaks} to force the use of breaks.
10583
10584The default is usually @option{-mdivide-traps}, but this can be
10585overridden at configure time using @option{--with-divide=breaks}.
10586Divide-by-zero checks can be completely disabled using
10587@option{-mno-check-zero-division}.
10588
10589@item -mmemcpy
10590@itemx -mno-memcpy
10591@opindex mmemcpy
10592@opindex mno-memcpy
10593Force (do not force) the use of @code{memcpy()} for non-trivial block
10594moves. The default is @option{-mno-memcpy}, which allows GCC to inline
10595most constant-sized copies.
10596
10597@item -mlong-calls
10598@itemx -mno-long-calls
10599@opindex mlong-calls
10600@opindex mno-long-calls
10601Disable (do not disable) use of the @code{jal} instruction. Calling
10602functions using @code{jal} is more efficient but requires the caller
10603and callee to be in the same 256 megabyte segment.
10604
10605This option has no effect on abicalls code. The default is
10606@option{-mno-long-calls}.
10607
10608@item -mmad
10609@itemx -mno-mad
10610@opindex mmad
10611@opindex mno-mad
10612Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
10613instructions, as provided by the R4650 ISA@.
10614
10615@item -mfused-madd
10616@itemx -mno-fused-madd
10617@opindex mfused-madd
10618@opindex mno-fused-madd
10619Enable (disable) use of the floating point multiply-accumulate
10620instructions, when they are available. The default is
10621@option{-mfused-madd}.
10622
10623When multiply-accumulate instructions are used, the intermediate
10624product is calculated to infinite precision and is not subject to
10625the FCSR Flush to Zero bit. This may be undesirable in some
10626circumstances.
10627
10628@item -nocpp
10629@opindex nocpp
10630Tell the MIPS assembler to not run its preprocessor over user
10631assembler files (with a @samp{.s} suffix) when assembling them.
10632
10633@item -mfix-r4000
10634@itemx -mno-fix-r4000
10635@opindex mfix-r4000
10636@opindex mno-fix-r4000
10637Work around certain R4000 CPU errata:
10638@itemize @minus
10639@item
10640A double-word or a variable shift may give an incorrect result if executed
10641immediately after starting an integer division.
10642@item
10643A double-word or a variable shift may give an incorrect result if executed
10644while an integer multiplication is in progress.
10645@item
10646An integer division may give an incorrect result if started in a delay slot
10647of a taken branch or a jump.
10648@end itemize
10649
10650@item -mfix-r4400
10651@itemx -mno-fix-r4400
10652@opindex mfix-r4400
10653@opindex mno-fix-r4400
10654Work around certain R4400 CPU errata:
10655@itemize @minus
10656@item
10657A double-word or a variable shift may give an incorrect result if executed
10658immediately after starting an integer division.
10659@end itemize
10660
10661@item -mfix-vr4120
10662@itemx -mno-fix-vr4120
10663@opindex mfix-vr4120
10664Work around certain VR4120 errata:
10665@itemize @minus
10666@item
10667@code{dmultu} does not always produce the correct result.
10668@item
10669@code{div} and @code{ddiv} do not always produce the correct result if one
10670of the operands is negative.
10671@end itemize
10672The workarounds for the division errata rely on special functions in
10673@file{libgcc.a}. At present, these functions are only provided by
10674the @code{mips64vr*-elf} configurations.
10675
10676Other VR4120 errata require a nop to be inserted between certain pairs of
10677instructions. These errata are handled by the assembler, not by GCC itself.
10678
10679@item -mfix-vr4130
10680@opindex mfix-vr4130
10681Work around the VR4130 @code{mflo}/@code{mfhi} errata. The
10682workarounds are implemented by the assembler rather than by GCC,
10683although GCC will avoid using @code{mflo} and @code{mfhi} if the
10684VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
10685instructions are available instead.
10686
10687@item -mfix-sb1
10688@itemx -mno-fix-sb1
10689@opindex mfix-sb1
10690Work around certain SB-1 CPU core errata.
10691(This flag currently works around the SB-1 revision 2
10692``F1'' and ``F2'' floating point errata.)
10693
10694@item -mflush-func=@var{func}
10695@itemx -mno-flush-func
10696@opindex mflush-func
10697Specifies the function to call to flush the I and D caches, or to not
10698call any such function. If called, the function must take the same
10699arguments as the common @code{_flush_func()}, that is, the address of the
10700memory range for which the cache is being flushed, the size of the
10701memory range, and the number 3 (to flush both caches). The default
10702depends on the target GCC was configured for, but commonly is either
10703@samp{_flush_func} or @samp{__cpu_flush}.
10704
10705@item -mbranch-likely
10706@itemx -mno-branch-likely
10707@opindex mbranch-likely
10708@opindex mno-branch-likely
10709Enable or disable use of Branch Likely instructions, regardless of the
10710default for the selected architecture. By default, Branch Likely
10711instructions may be generated if they are supported by the selected
10712architecture. An exception is for the MIPS32 and MIPS64 architectures
10713and processors which implement those architectures; for those, Branch
10714Likely instructions will not be generated by default because the MIPS32
10715and MIPS64 architectures specifically deprecate their use.
10716
10717@item -mfp-exceptions
10718@itemx -mno-fp-exceptions
10719@opindex mfp-exceptions
10720Specifies whether FP exceptions are enabled. This affects how we schedule
10721FP instructions for some processors. The default is that FP exceptions are
10722enabled.
10723
10724For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
1072564-bit code, then we can use both FP pipes. Otherwise, we can only use one
10726FP pipe.
10727
10728@item -mvr4130-align
10729@itemx -mno-vr4130-align
10730@opindex mvr4130-align
10731The VR4130 pipeline is two-way superscalar, but can only issue two
10732instructions together if the first one is 8-byte aligned. When this
10733option is enabled, GCC will align pairs of instructions that it
10734thinks should execute in parallel.
10735
10736This option only has an effect when optimizing for the VR4130.
10737It normally makes code faster, but at the expense of making it bigger.
10738It is enabled by default at optimization level @option{-O3}.
10739@end table
10740
10741@node MMIX Options
10742@subsection MMIX Options
10743@cindex MMIX Options
10744
10745These options are defined for the MMIX:
10746
10747@table @gcctabopt
10748@item -mlibfuncs
10749@itemx -mno-libfuncs
10750@opindex mlibfuncs
10751@opindex mno-libfuncs
10752Specify that intrinsic library functions are being compiled, passing all
10753values in registers, no matter the size.
10754
10755@item -mepsilon
10756@itemx -mno-epsilon
10757@opindex mepsilon
10758@opindex mno-epsilon
10759Generate floating-point comparison instructions that compare with respect
10760to the @code{rE} epsilon register.
10761
10762@item -mabi=mmixware
10763@itemx -mabi=gnu
10764@opindex mabi-mmixware
10765@opindex mabi=gnu
10766Generate code that passes function parameters and return values that (in
10767the called function) are seen as registers @code{$0} and up, as opposed to
10768the GNU ABI which uses global registers @code{$231} and up.
10769
10770@item -mzero-extend
10771@itemx -mno-zero-extend
10772@opindex mzero-extend
10773@opindex mno-zero-extend
10774When reading data from memory in sizes shorter than 64 bits, use (do not
10775use) zero-extending load instructions by default, rather than
10776sign-extending ones.
10777
10778@item -mknuthdiv
10779@itemx -mno-knuthdiv
10780@opindex mknuthdiv
10781@opindex mno-knuthdiv
10782Make the result of a division yielding a remainder have the same sign as
10783the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
10784remainder follows the sign of the dividend. Both methods are
10785arithmetically valid, the latter being almost exclusively used.
10786
10787@item -mtoplevel-symbols
10788@itemx -mno-toplevel-symbols
10789@opindex mtoplevel-symbols
10790@opindex mno-toplevel-symbols
10791Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
10792code can be used with the @code{PREFIX} assembly directive.
10793
10794@item -melf
10795@opindex melf
10796Generate an executable in the ELF format, rather than the default
10797@samp{mmo} format used by the @command{mmix} simulator.
10798
10799@item -mbranch-predict
10800@itemx -mno-branch-predict
10801@opindex mbranch-predict
10802@opindex mno-branch-predict
10803Use (do not use) the probable-branch instructions, when static branch
10804prediction indicates a probable branch.
10805
10806@item -mbase-addresses
10807@itemx -mno-base-addresses
10808@opindex mbase-addresses
10809@opindex mno-base-addresses
10810Generate (do not generate) code that uses @emph{base addresses}. Using a
10811base address automatically generates a request (handled by the assembler
10812and the linker) for a constant to be set up in a global register. The
10813register is used for one or more base address requests within the range 0
10814to 255 from the value held in the register. The generally leads to short
10815and fast code, but the number of different data items that can be
10816addressed is limited. This means that a program that uses lots of static
10817data may require @option{-mno-base-addresses}.
10818
10819@item -msingle-exit
10820@itemx -mno-single-exit
10821@opindex msingle-exit
10822@opindex mno-single-exit
10823Force (do not force) generated code to have a single exit point in each
10824function.
10825@end table
10826
10827@node MN10300 Options
10828@subsection MN10300 Options
10829@cindex MN10300 options
10830
10831These @option{-m} options are defined for Matsushita MN10300 architectures:
10832
10833@table @gcctabopt
10834@item -mmult-bug
10835@opindex mmult-bug
10836Generate code to avoid bugs in the multiply instructions for the MN10300
10837processors. This is the default.
10838
10839@item -mno-mult-bug
10840@opindex mno-mult-bug
10841Do not generate code to avoid bugs in the multiply instructions for the
10842MN10300 processors.
10843
10844@item -mam33
10845@opindex mam33
10846Generate code which uses features specific to the AM33 processor.
10847
10848@item -mno-am33
10849@opindex mno-am33
10850Do not generate code which uses features specific to the AM33 processor. This
10851is the default.
10852
10853@item -mreturn-pointer-on-d0
10854@opindex mreturn-pointer-on-d0
10855When generating a function which returns a pointer, return the pointer
10856in both @code{a0} and @code{d0}. Otherwise, the pointer is returned
10857only in a0, and attempts to call such functions without a prototype
10858would result in errors. Note that this option is on by default; use
10859@option{-mno-return-pointer-on-d0} to disable it.
10860
10861@item -mno-crt0
10862@opindex mno-crt0
10863Do not link in the C run-time initialization object file.
10864
10865@item -mrelax
10866@opindex mrelax
10867Indicate to the linker that it should perform a relaxation optimization pass
10868to shorten branches, calls and absolute memory addresses. This option only
10869has an effect when used on the command line for the final link step.
10870
10871This option makes symbolic debugging impossible.
10872@end table
10873
10874@node MT Options
10875@subsection MT Options
10876@cindex MT options
10877
10878These @option{-m} options are defined for Morpho MT architectures:
10879
10880@table @gcctabopt
10881
10882@item -march=@var{cpu-type}
10883@opindex march
10884Generate code that will run on @var{cpu-type}, which is the name of a system
10885representing a certain processor type. Possible values for
10886@var{cpu-type} are @samp{ms1-64-001}, @samp{ms1-16-002},
10887@samp{ms1-16-003} and @samp{ms2}.
10888
10889When this option is not used, the default is @option{-march=ms1-16-002}.
10890
10891@item -mbacc
10892@opindex mbacc
10893Use byte loads and stores when generating code.
10894
10895@item -mno-bacc
10896@opindex mno-bacc
10897Do not use byte loads and stores when generating code.
10898
10899@item -msim
10900@opindex msim
10901Use simulator runtime
10902
10903@item -mno-crt0
10904@opindex mno-crt0
10905Do not link in the C run-time initialization object file
10906@file{crti.o}. Other run-time initialization and termination files
10907such as @file{startup.o} and @file{exit.o} are still included on the
10908linker command line.
10909
10910@end table
10911
10912@node PDP-11 Options
10913@subsection PDP-11 Options
10914@cindex PDP-11 Options
10915
10916These options are defined for the PDP-11:
10917
10918@table @gcctabopt
10919@item -mfpu
10920@opindex mfpu
10921Use hardware FPP floating point. This is the default. (FIS floating
10922point on the PDP-11/40 is not supported.)
10923
10924@item -msoft-float
10925@opindex msoft-float
10926Do not use hardware floating point.
10927
10928@item -mac0
10929@opindex mac0
10930Return floating-point results in ac0 (fr0 in Unix assembler syntax).
10931
10932@item -mno-ac0
10933@opindex mno-ac0
10934Return floating-point results in memory. This is the default.
10935
10936@item -m40
10937@opindex m40
10938Generate code for a PDP-11/40.
10939
10940@item -m45
10941@opindex m45
10942Generate code for a PDP-11/45. This is the default.
10943
10944@item -m10
10945@opindex m10
10946Generate code for a PDP-11/10.
10947
10948@item -mbcopy-builtin
10949@opindex bcopy-builtin
10950Use inline @code{movmemhi} patterns for copying memory. This is the
10951default.
10952
10953@item -mbcopy
10954@opindex mbcopy
10955Do not use inline @code{movmemhi} patterns for copying memory.
10956
10957@item -mint16
10958@itemx -mno-int32
10959@opindex mint16
10960@opindex mno-int32
10961Use 16-bit @code{int}. This is the default.
10962
10963@item -mint32
10964@itemx -mno-int16
10965@opindex mint32
10966@opindex mno-int16
10967Use 32-bit @code{int}.
10968
10969@item -mfloat64
10970@itemx -mno-float32
10971@opindex mfloat64
10972@opindex mno-float32
10973Use 64-bit @code{float}. This is the default.
10974
10975@item -mfloat32
10976@itemx -mno-float64
10977@opindex mfloat32
10978@opindex mno-float64
10979Use 32-bit @code{float}.
10980
10981@item -mabshi
10982@opindex mabshi
10983Use @code{abshi2} pattern. This is the default.
10984
10985@item -mno-abshi
10986@opindex mno-abshi
10987Do not use @code{abshi2} pattern.
10988
10989@item -mbranch-expensive
10990@opindex mbranch-expensive
10991Pretend that branches are expensive. This is for experimenting with
10992code generation only.
10993
10994@item -mbranch-cheap
10995@opindex mbranch-cheap
10996Do not pretend that branches are expensive. This is the default.
10997
10998@item -msplit
10999@opindex msplit
11000Generate code for a system with split I&D@.
11001
11002@item -mno-split
11003@opindex mno-split
11004Generate code for a system without split I&D@. This is the default.
11005
11006@item -munix-asm
11007@opindex munix-asm
11008Use Unix assembler syntax. This is the default when configured for
11009@samp{pdp11-*-bsd}.
11010
11011@item -mdec-asm
11012@opindex mdec-asm
11013Use DEC assembler syntax. This is the default when configured for any
11014PDP-11 target other than @samp{pdp11-*-bsd}.
11015@end table
11016
11017@node PowerPC Options
11018@subsection PowerPC Options
11019@cindex PowerPC options
11020
11021These are listed under @xref{RS/6000 and PowerPC Options}.
11022
11023@node RS/6000 and PowerPC Options
11024@subsection IBM RS/6000 and PowerPC Options
11025@cindex RS/6000 and PowerPC Options
11026@cindex IBM RS/6000 and PowerPC Options
11027
11028These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
11029@table @gcctabopt
11030@item -mpower
11031@itemx -mno-power
11032@itemx -mpower2
11033@itemx -mno-power2
11034@itemx -mpowerpc
11035@itemx -mno-powerpc
11036@itemx -mpowerpc-gpopt
11037@itemx -mno-powerpc-gpopt
11038@itemx -mpowerpc-gfxopt
11039@itemx -mno-powerpc-gfxopt
11040@itemx -mpowerpc64
11041@itemx -mno-powerpc64
11042@itemx -mmfcrf
11043@itemx -mno-mfcrf
11044@itemx -mpopcntb
11045@itemx -mno-popcntb
11046@itemx -mfprnd
11047@itemx -mno-fprnd
11048@opindex mpower
11049@opindex mno-power
11050@opindex mpower2
11051@opindex mno-power2
11052@opindex mpowerpc
11053@opindex mno-powerpc
11054@opindex mpowerpc-gpopt
11055@opindex mno-powerpc-gpopt
11056@opindex mpowerpc-gfxopt
11057@opindex mno-powerpc-gfxopt
11058@opindex mpowerpc64
11059@opindex mno-powerpc64
11060@opindex mmfcrf
11061@opindex mno-mfcrf
11062@opindex mpopcntb
11063@opindex mno-popcntb
11064@opindex mfprnd
11065@opindex mno-fprnd
11066GCC supports two related instruction set architectures for the
11067RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those
11068instructions supported by the @samp{rios} chip set used in the original
11069RS/6000 systems and the @dfn{PowerPC} instruction set is the
11070architecture of the Freescale MPC5xx, MPC6xx, MPC8xx microprocessors, and
11071the IBM 4xx, 6xx, and follow-on microprocessors.
11072
11073Neither architecture is a subset of the other. However there is a
11074large common subset of instructions supported by both. An MQ
11075register is included in processors supporting the POWER architecture.
11076
11077You use these options to specify which instructions are available on the
11078processor you are using. The default value of these options is
11079determined when configuring GCC@. Specifying the
11080@option{-mcpu=@var{cpu_type}} overrides the specification of these
11081options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
11082rather than the options listed above.
11083
11084The @option{-mpower} option allows GCC to generate instructions that
11085are found only in the POWER architecture and to use the MQ register.
11086Specifying @option{-mpower2} implies @option{-power} and also allows GCC
11087to generate instructions that are present in the POWER2 architecture but
11088not the original POWER architecture.
11089
11090The @option{-mpowerpc} option allows GCC to generate instructions that
11091are found only in the 32-bit subset of the PowerPC architecture.
11092Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
11093GCC to use the optional PowerPC architecture instructions in the
11094General Purpose group, including floating-point square root. Specifying
11095@option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
11096use the optional PowerPC architecture instructions in the Graphics
11097group, including floating-point select.
11098
11099The @option{-mmfcrf} option allows GCC to generate the move from
11100condition register field instruction implemented on the POWER4
11101processor and other processors that support the PowerPC V2.01
11102architecture.
11103The @option{-mpopcntb} option allows GCC to generate the popcount and
11104double precision FP reciprocal estimate instruction implemented on the
11105POWER5 processor and other processors that support the PowerPC V2.02
11106architecture.
11107The @option{-mfprnd} option allows GCC to generate the FP round to
11108integer instructions implemented on the POWER5+ processor and other
11109processors that support the PowerPC V2.03 architecture.
11110
11111The @option{-mpowerpc64} option allows GCC to generate the additional
1111264-bit instructions that are found in the full PowerPC64 architecture
11113and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
11114@option{-mno-powerpc64}.
11115
11116If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
11117will use only the instructions in the common subset of both
11118architectures plus some special AIX common-mode calls, and will not use
11119the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
11120permits GCC to use any instruction from either architecture and to
11121allow use of the MQ register; specify this for the Motorola MPC601.
11122
11123@item -mnew-mnemonics
11124@itemx -mold-mnemonics
11125@opindex mnew-mnemonics
11126@opindex mold-mnemonics
11127Select which mnemonics to use in the generated assembler code. With
11128@option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
11129the PowerPC architecture. With @option{-mold-mnemonics} it uses the
11130assembler mnemonics defined for the POWER architecture. Instructions
11131defined in only one architecture have only one mnemonic; GCC uses that
11132mnemonic irrespective of which of these options is specified.
11133
11134GCC defaults to the mnemonics appropriate for the architecture in
11135use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
11136value of these option. Unless you are building a cross-compiler, you
11137should normally not specify either @option{-mnew-mnemonics} or
11138@option{-mold-mnemonics}, but should instead accept the default.
11139
11140@item -mcpu=@var{cpu_type}
11141@opindex mcpu
11142Set architecture type, register usage, choice of mnemonics, and
11143instruction scheduling parameters for machine type @var{cpu_type}.
11144Supported values for @var{cpu_type} are @samp{401}, @samp{403},
11145@samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{505},
11146@samp{601}, @samp{602}, @samp{603}, @samp{603e}, @samp{604},
11147@samp{604e}, @samp{620}, @samp{630}, @samp{740}, @samp{7400},
11148@samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
11149@samp{860}, @samp{970}, @samp{8540}, @samp{ec603e}, @samp{G3},
11150@samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3},
11151@samp{power4}, @samp{power5}, @samp{power5+}, @samp{power6},
11152@samp{common}, @samp{powerpc}, @samp{powerpc64},
11153@samp{rios}, @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64}.
11154
11155@option{-mcpu=common} selects a completely generic processor. Code
11156generated under this option will run on any POWER or PowerPC processor.
11157GCC will use only the instructions in the common subset of both
11158architectures, and will not use the MQ register. GCC assumes a generic
11159processor model for scheduling purposes.
11160
11161@option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
11162@option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
11163PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
11164types, with an appropriate, generic processor model assumed for
11165scheduling purposes.
11166
11167The other options specify a specific processor. Code generated under
11168those options will run best on that processor, and may not run at all on
11169others.
11170
11171The @option{-mcpu} options automatically enable or disable the
11172following options: @option{-maltivec}, @option{-mfprnd},
11173@option{-mhard-float}, @option{-mmfcrf}, @option{-mmultiple},
11174@option{-mnew-mnemonics}, @option{-mpopcntb}, @option{-mpower},
11175@option{-mpower2}, @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
11176@option{-mpowerpc-gfxopt}, @option{-mstring}, @option{-mmulhw}, @option{-mdlmzb}.
11177The particular options
11178set for any particular CPU will vary between compiler versions,
11179depending on what setting seems to produce optimal code for that CPU;
11180it doesn't necessarily reflect the actual hardware's capabilities. If
11181you wish to set an individual option to a particular value, you may
11182specify it after the @option{-mcpu} option, like @samp{-mcpu=970
11183-mno-altivec}.
11184
11185On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
11186not enabled or disabled by the @option{-mcpu} option at present because
11187AIX does not have full support for these options. You may still
11188enable or disable them individually if you're sure it'll work in your
11189environment.
11190
11191@item -mtune=@var{cpu_type}
11192@opindex mtune
11193Set the instruction scheduling parameters for machine type
11194@var{cpu_type}, but do not set the architecture type, register usage, or
11195choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
11196values for @var{cpu_type} are used for @option{-mtune} as for
11197@option{-mcpu}. If both are specified, the code generated will use the
11198architecture, registers, and mnemonics set by @option{-mcpu}, but the
11199scheduling parameters set by @option{-mtune}.
11200
11201@item -mswdiv
11202@itemx -mno-swdiv
11203@opindex mswdiv
11204@opindex mno-swdiv
11205Generate code to compute division as reciprocal estimate and iterative
11206refinement, creating opportunities for increased throughput. This
11207feature requires: optional PowerPC Graphics instruction set for single
11208precision and FRE instruction for double precision, assuming divides
11209cannot generate user-visible traps, and the domain values not include
11210Infinities, denormals or zero denominator.
11211
11212@item -maltivec
11213@itemx -mno-altivec
11214@opindex maltivec
11215@opindex mno-altivec
11216Generate code that uses (does not use) AltiVec instructions, and also
11217enable the use of built-in functions that allow more direct access to
11218the AltiVec instruction set. You may also need to set
11219@option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
11220enhancements.
11221
11222@item -mvrsave
11223@item -mno-vrsave
11224@opindex mvrsave
11225@opindex mno-vrsave
11226Generate VRSAVE instructions when generating AltiVec code.
11227
11228@item -msecure-plt
11229@opindex msecure-plt
11230Generate code that allows ld and ld.so to build executables and shared
11231libraries with non-exec .plt and .got sections. This is a PowerPC
1123232-bit SYSV ABI option.
11233
11234@item -mbss-plt
11235@opindex mbss-plt
11236Generate code that uses a BSS .plt section that ld.so fills in, and
11237requires .plt and .got sections that are both writable and executable.
11238This is a PowerPC 32-bit SYSV ABI option.
11239
11240@item -misel
11241@itemx -mno-isel
11242@opindex misel
11243@opindex mno-isel
11244This switch enables or disables the generation of ISEL instructions.
11245
11246@item -misel=@var{yes/no}
11247This switch has been deprecated. Use @option{-misel} and
11248@option{-mno-isel} instead.
11249
11250@item -mspe
11251@itemx -mno-spe
11252@opindex mspe
11253@opindex mno-spe
11254This switch enables or disables the generation of SPE simd
11255instructions.
11256
11257@item -mspe=@var{yes/no}
11258This option has been deprecated. Use @option{-mspe} and
11259@option{-mno-spe} instead.
11260
11261@item -mfloat-gprs=@var{yes/single/double/no}
11262@itemx -mfloat-gprs
11263@opindex mfloat-gprs
11264This switch enables or disables the generation of floating point
11265operations on the general purpose registers for architectures that
11266support it.
11267
11268The argument @var{yes} or @var{single} enables the use of
11269single-precision floating point operations.
11270
11271The argument @var{double} enables the use of single and
11272double-precision floating point operations.
11273
11274The argument @var{no} disables floating point operations on the
11275general purpose registers.
11276
11277This option is currently only available on the MPC854x.
11278
11279@item -m32
11280@itemx -m64
11281@opindex m32
11282@opindex m64
11283Generate code for 32-bit or 64-bit environments of Darwin and SVR4
11284targets (including GNU/Linux). The 32-bit environment sets int, long
11285and pointer to 32 bits and generates code that runs on any PowerPC
11286variant. The 64-bit environment sets int to 32 bits and long and
11287pointer to 64 bits, and generates code for PowerPC64, as for
11288@option{-mpowerpc64}.
11289
11290@item -mfull-toc
11291@itemx -mno-fp-in-toc
11292@itemx -mno-sum-in-toc
11293@itemx -mminimal-toc
11294@opindex mfull-toc
11295@opindex mno-fp-in-toc
11296@opindex mno-sum-in-toc
11297@opindex mminimal-toc
11298Modify generation of the TOC (Table Of Contents), which is created for
11299every executable file. The @option{-mfull-toc} option is selected by
11300default. In that case, GCC will allocate at least one TOC entry for
11301each unique non-automatic variable reference in your program. GCC
11302will also place floating-point constants in the TOC@. However, only
1130316,384 entries are available in the TOC@.
11304
11305If you receive a linker error message that saying you have overflowed
11306the available TOC space, you can reduce the amount of TOC space used
11307with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
11308@option{-mno-fp-in-toc} prevents GCC from putting floating-point
11309constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
11310generate code to calculate the sum of an address and a constant at
11311run-time instead of putting that sum into the TOC@. You may specify one
11312or both of these options. Each causes GCC to produce very slightly
11313slower and larger code at the expense of conserving TOC space.
11314
11315If you still run out of space in the TOC even when you specify both of
11316these options, specify @option{-mminimal-toc} instead. This option causes
11317GCC to make only one TOC entry for every file. When you specify this
11318option, GCC will produce code that is slower and larger but which
11319uses extremely little TOC space. You may wish to use this option
11320only on files that contain less frequently executed code.
11321
11322@item -maix64
11323@itemx -maix32
11324@opindex maix64
11325@opindex maix32
11326Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
11327@code{long} type, and the infrastructure needed to support them.
11328Specifying @option{-maix64} implies @option{-mpowerpc64} and
11329@option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
11330implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
11331
11332@item -mxl-compat
11333@itemx -mno-xl-compat
11334@opindex mxl-compat
11335@opindex mno-xl-compat
11336Produce code that conforms more closely to IBM XL compiler semantics
11337when using AIX-compatible ABI. Pass floating-point arguments to
11338prototyped functions beyond the register save area (RSA) on the stack
11339in addition to argument FPRs. Do not assume that most significant
11340double in 128-bit long double value is properly rounded when comparing
11341values and converting to double. Use XL symbol names for long double
11342support routines.
11343
11344The AIX calling convention was extended but not initially documented to
11345handle an obscure K&R C case of calling a function that takes the
11346address of its arguments with fewer arguments than declared. IBM XL
11347compilers access floating point arguments which do not fit in the
11348RSA from the stack when a subroutine is compiled without
11349optimization. Because always storing floating-point arguments on the
11350stack is inefficient and rarely needed, this option is not enabled by
11351default and only is necessary when calling subroutines compiled by IBM
11352XL compilers without optimization.
11353
11354@item -mpe
11355@opindex mpe
11356Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
11357application written to use message passing with special startup code to
11358enable the application to run. The system must have PE installed in the
11359standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
11360must be overridden with the @option{-specs=} option to specify the
11361appropriate directory location. The Parallel Environment does not
11362support threads, so the @option{-mpe} option and the @option{-pthread}
11363option are incompatible.
11364
11365@item -malign-natural
11366@itemx -malign-power
11367@opindex malign-natural
11368@opindex malign-power
11369On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
11370@option{-malign-natural} overrides the ABI-defined alignment of larger
11371types, such as floating-point doubles, on their natural size-based boundary.
11372The option @option{-malign-power} instructs GCC to follow the ABI-specified
11373alignment rules. GCC defaults to the standard alignment defined in the ABI@.
11374
11375On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
11376is not supported.
11377
11378@item -msoft-float
11379@itemx -mhard-float
11380@opindex msoft-float
11381@opindex mhard-float
11382Generate code that does not use (uses) the floating-point register set.
11383Software floating point emulation is provided if you use the
11384@option{-msoft-float} option, and pass the option to GCC when linking.
11385
11386@item -mmultiple
11387@itemx -mno-multiple
11388@opindex mmultiple
11389@opindex mno-multiple
11390Generate code that uses (does not use) the load multiple word
11391instructions and the store multiple word instructions. These
11392instructions are generated by default on POWER systems, and not
11393generated on PowerPC systems. Do not use @option{-mmultiple} on little
11394endian PowerPC systems, since those instructions do not work when the
11395processor is in little endian mode. The exceptions are PPC740 and
11396PPC750 which permit the instructions usage in little endian mode.
11397
11398@item -mstring
11399@itemx -mno-string
11400@opindex mstring
11401@opindex mno-string
11402Generate code that uses (does not use) the load string instructions
11403and the store string word instructions to save multiple registers and
11404do small block moves. These instructions are generated by default on
11405POWER systems, and not generated on PowerPC systems. Do not use
11406@option{-mstring} on little endian PowerPC systems, since those
11407instructions do not work when the processor is in little endian mode.
11408The exceptions are PPC740 and PPC750 which permit the instructions
11409usage in little endian mode.
11410
11411@item -mupdate
11412@itemx -mno-update
11413@opindex mupdate
11414@opindex mno-update
11415Generate code that uses (does not use) the load or store instructions
11416that update the base register to the address of the calculated memory
11417location. These instructions are generated by default. If you use
11418@option{-mno-update}, there is a small window between the time that the
11419stack pointer is updated and the address of the previous frame is
11420stored, which means code that walks the stack frame across interrupts or
11421signals may get corrupted data.
11422
11423@item -mfused-madd
11424@itemx -mno-fused-madd
11425@opindex mfused-madd
11426@opindex mno-fused-madd
11427Generate code that uses (does not use) the floating point multiply and
11428accumulate instructions. These instructions are generated by default if
11429hardware floating is used.
11430
11431@item -mmulhw
11432@itemx -mno-mulhw
11433@opindex mmulhw
11434@opindex mno-mulhw
11435Generate code that uses (does not use) the half-word multiply and
11436multiply-accumulate instructions on the IBM 405 and 440 processors.
11437These instructions are generated by default when targetting those
11438processors.
11439
11440@item -mdlmzb
11441@itemx -mno-dlmzb
11442@opindex mdlmzb
11443@opindex mno-dlmzb
11444Generate code that uses (does not use) the string-search @samp{dlmzb}
11445instruction on the IBM 405 and 440 processors. This instruction is
11446generated by default when targetting those processors.
11447
11448@item -mno-bit-align
11449@itemx -mbit-align
11450@opindex mno-bit-align
11451@opindex mbit-align
11452On System V.4 and embedded PowerPC systems do not (do) force structures
11453and unions that contain bit-fields to be aligned to the base type of the
11454bit-field.
11455
11456For example, by default a structure containing nothing but 8
11457@code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
11458boundary and have a size of 4 bytes. By using @option{-mno-bit-align},
11459the structure would be aligned to a 1 byte boundary and be one byte in
11460size.
11461
11462@item -mno-strict-align
11463@itemx -mstrict-align
11464@opindex mno-strict-align
11465@opindex mstrict-align
11466On System V.4 and embedded PowerPC systems do not (do) assume that
11467unaligned memory references will be handled by the system.
11468
11469@item -mrelocatable
11470@itemx -mno-relocatable
11471@opindex mrelocatable
11472@opindex mno-relocatable
11473On embedded PowerPC systems generate code that allows (does not allow)
11474the program to be relocated to a different address at runtime. If you
11475use @option{-mrelocatable} on any module, all objects linked together must
11476be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
11477
11478@item -mrelocatable-lib
11479@itemx -mno-relocatable-lib
11480@opindex mrelocatable-lib
11481@opindex mno-relocatable-lib
11482On embedded PowerPC systems generate code that allows (does not allow)
11483the program to be relocated to a different address at runtime. Modules
11484compiled with @option{-mrelocatable-lib} can be linked with either modules
11485compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
11486with modules compiled with the @option{-mrelocatable} options.
11487
11488@item -mno-toc
11489@itemx -mtoc
11490@opindex mno-toc
11491@opindex mtoc
11492On System V.4 and embedded PowerPC systems do not (do) assume that
11493register 2 contains a pointer to a global area pointing to the addresses
11494used in the program.
11495
11496@item -mlittle
11497@itemx -mlittle-endian
11498@opindex mlittle
11499@opindex mlittle-endian
11500On System V.4 and embedded PowerPC systems compile code for the
11501processor in little endian mode. The @option{-mlittle-endian} option is
11502the same as @option{-mlittle}.
11503
11504@item -mbig
11505@itemx -mbig-endian
11506@opindex mbig
11507@opindex mbig-endian
11508On System V.4 and embedded PowerPC systems compile code for the
11509processor in big endian mode. The @option{-mbig-endian} option is
11510the same as @option{-mbig}.
11511
11512@item -mdynamic-no-pic
11513@opindex mdynamic-no-pic
11514On Darwin and Mac OS X systems, compile code so that it is not
11515relocatable, but that its external references are relocatable. The
11516resulting code is suitable for applications, but not shared
11517libraries.
11518
11519@item -mprioritize-restricted-insns=@var{priority}
11520@opindex mprioritize-restricted-insns
11521This option controls the priority that is assigned to
11522dispatch-slot restricted instructions during the second scheduling
11523pass. The argument @var{priority} takes the value @var{0/1/2} to assign
11524@var{no/highest/second-highest} priority to dispatch slot restricted
11525instructions.
11526
11527@item -msched-costly-dep=@var{dependence_type}
11528@opindex msched-costly-dep
11529This option controls which dependences are considered costly
11530by the target during instruction scheduling. The argument
11531@var{dependence_type} takes one of the following values:
11532@var{no}: no dependence is costly,
11533@var{all}: all dependences are costly,
11534@var{true_store_to_load}: a true dependence from store to load is costly,
11535@var{store_to_load}: any dependence from store to load is costly,
11536@var{number}: any dependence which latency >= @var{number} is costly.
11537
11538@item -minsert-sched-nops=@var{scheme}
11539@opindex minsert-sched-nops
11540This option controls which nop insertion scheme will be used during
11541the second scheduling pass. The argument @var{scheme} takes one of the
11542following values:
11543@var{no}: Don't insert nops.
11544@var{pad}: Pad with nops any dispatch group which has vacant issue slots,
11545according to the scheduler's grouping.
11546@var{regroup_exact}: Insert nops to force costly dependent insns into
11547separate groups. Insert exactly as many nops as needed to force an insn
11548to a new group, according to the estimated processor grouping.
11549@var{number}: Insert nops to force costly dependent insns into
11550separate groups. Insert @var{number} nops to force an insn to a new group.
11551
11552@item -mcall-sysv
11553@opindex mcall-sysv
11554On System V.4 and embedded PowerPC systems compile code using calling
11555conventions that adheres to the March 1995 draft of the System V
11556Application Binary Interface, PowerPC processor supplement. This is the
11557default unless you configured GCC using @samp{powerpc-*-eabiaix}.
11558
11559@item -mcall-sysv-eabi
11560@opindex mcall-sysv-eabi
11561Specify both @option{-mcall-sysv} and @option{-meabi} options.
11562
11563@item -mcall-sysv-noeabi
11564@opindex mcall-sysv-noeabi
11565Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
11566
11567@item -mcall-solaris
11568@opindex mcall-solaris
11569On System V.4 and embedded PowerPC systems compile code for the Solaris
11570operating system.
11571
11572@item -mcall-linux
11573@opindex mcall-linux
11574On System V.4 and embedded PowerPC systems compile code for the
11575Linux-based GNU system.
11576
11577@item -mcall-gnu
11578@opindex mcall-gnu
11579On System V.4 and embedded PowerPC systems compile code for the
11580Hurd-based GNU system.
11581
11582@item -mcall-netbsd
11583@opindex mcall-netbsd
11584On System V.4 and embedded PowerPC systems compile code for the
11585NetBSD operating system.
11586
11587@item -maix-struct-return
11588@opindex maix-struct-return
11589Return all structures in memory (as specified by the AIX ABI)@.
11590
11591@item -msvr4-struct-return
11592@opindex msvr4-struct-return
11593Return structures smaller than 8 bytes in registers (as specified by the
11594SVR4 ABI)@.
11595
11596@item -mabi=@var{abi-type}
11597@opindex mabi
11598Extend the current ABI with a particular extension, or remove such extension.
11599Valid values are @var{altivec}, @var{no-altivec}, @var{spe},
11600@var{no-spe}, @var{ibmlongdouble}, @var{ieeelongdouble}@.
11601
11602@item -mabi=spe
11603@opindex mabi=spe
11604Extend the current ABI with SPE ABI extensions. This does not change
11605the default ABI, instead it adds the SPE ABI extensions to the current
11606ABI@.
11607
11608@item -mabi=no-spe
11609@opindex mabi=no-spe
11610Disable Booke SPE ABI extensions for the current ABI@.
11611
11612@item -mabi=ibmlongdouble
11613@opindex mabi=ibmlongdouble
11614Change the current ABI to use IBM extended precision long double.
11615This is a PowerPC 32-bit SYSV ABI option.
11616
11617@item -mabi=ieeelongdouble
11618@opindex mabi=ieeelongdouble
11619Change the current ABI to use IEEE extended precision long double.
11620This is a PowerPC 32-bit Linux ABI option.
11621
11622@item -mprototype
11623@itemx -mno-prototype
11624@opindex mprototype
11625@opindex mno-prototype
11626On System V.4 and embedded PowerPC systems assume that all calls to
11627variable argument functions are properly prototyped. Otherwise, the
11628compiler must insert an instruction before every non prototyped call to
11629set or clear bit 6 of the condition code register (@var{CR}) to
11630indicate whether floating point values were passed in the floating point
11631registers in case the function takes a variable arguments. With
11632@option{-mprototype}, only calls to prototyped variable argument functions
11633will set or clear the bit.
11634
11635@item -msim
11636@opindex msim
11637On embedded PowerPC systems, assume that the startup module is called
11638@file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
11639@file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
11640configurations.
11641
11642@item -mmvme
11643@opindex mmvme
11644On embedded PowerPC systems, assume that the startup module is called
11645@file{crt0.o} and the standard C libraries are @file{libmvme.a} and
11646@file{libc.a}.
11647
11648@item -mads
11649@opindex mads
11650On embedded PowerPC systems, assume that the startup module is called
11651@file{crt0.o} and the standard C libraries are @file{libads.a} and
11652@file{libc.a}.
11653
11654@item -myellowknife
11655@opindex myellowknife
11656On embedded PowerPC systems, assume that the startup module is called
11657@file{crt0.o} and the standard C libraries are @file{libyk.a} and
11658@file{libc.a}.
11659
11660@item -mvxworks
11661@opindex mvxworks
11662On System V.4 and embedded PowerPC systems, specify that you are
11663compiling for a VxWorks system.
11664
11665@item -mwindiss
11666@opindex mwindiss
11667Specify that you are compiling for the WindISS simulation environment.
11668
11669@item -memb
11670@opindex memb
11671On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
11672header to indicate that @samp{eabi} extended relocations are used.
11673
11674@item -meabi
11675@itemx -mno-eabi
11676@opindex meabi
11677@opindex mno-eabi
11678On System V.4 and embedded PowerPC systems do (do not) adhere to the
11679Embedded Applications Binary Interface (eabi) which is a set of
11680modifications to the System V.4 specifications. Selecting @option{-meabi}
11681means that the stack is aligned to an 8 byte boundary, a function
11682@code{__eabi} is called to from @code{main} to set up the eabi
11683environment, and the @option{-msdata} option can use both @code{r2} and
11684@code{r13} to point to two separate small data areas. Selecting
11685@option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
11686do not call an initialization function from @code{main}, and the
11687@option{-msdata} option will only use @code{r13} to point to a single
11688small data area. The @option{-meabi} option is on by default if you
11689configured GCC using one of the @samp{powerpc*-*-eabi*} options.
11690
11691@item -msdata=eabi
11692@opindex msdata=eabi
11693On System V.4 and embedded PowerPC systems, put small initialized
11694@code{const} global and static data in the @samp{.sdata2} section, which
11695is pointed to by register @code{r2}. Put small initialized
11696non-@code{const} global and static data in the @samp{.sdata} section,
11697which is pointed to by register @code{r13}. Put small uninitialized
11698global and static data in the @samp{.sbss} section, which is adjacent to
11699the @samp{.sdata} section. The @option{-msdata=eabi} option is
11700incompatible with the @option{-mrelocatable} option. The
11701@option{-msdata=eabi} option also sets the @option{-memb} option.
11702
11703@item -msdata=sysv
11704@opindex msdata=sysv
11705On System V.4 and embedded PowerPC systems, put small global and static
11706data in the @samp{.sdata} section, which is pointed to by register
11707@code{r13}. Put small uninitialized global and static data in the
11708@samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
11709The @option{-msdata=sysv} option is incompatible with the
11710@option{-mrelocatable} option.
11711
11712@item -msdata=default
11713@itemx -msdata
11714@opindex msdata=default
11715@opindex msdata
11716On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
11717compile code the same as @option{-msdata=eabi}, otherwise compile code the
11718same as @option{-msdata=sysv}.
11719
11720@item -msdata-data
11721@opindex msdata-data
11722On System V.4 and embedded PowerPC systems, put small global
11723data in the @samp{.sdata} section. Put small uninitialized global
11724data in the @samp{.sbss} section. Do not use register @code{r13}
11725to address small data however. This is the default behavior unless
11726other @option{-msdata} options are used.
11727
11728@item -msdata=none
11729@itemx -mno-sdata
11730@opindex msdata=none
11731@opindex mno-sdata
11732On embedded PowerPC systems, put all initialized global and static data
11733in the @samp{.data} section, and all uninitialized data in the
11734@samp{.bss} section.
11735
11736@item -G @var{num}
11737@opindex G
11738@cindex smaller data references (PowerPC)
11739@cindex .sdata/.sdata2 references (PowerPC)
11740On embedded PowerPC systems, put global and static items less than or
11741equal to @var{num} bytes into the small data or bss sections instead of
11742the normal data or bss section. By default, @var{num} is 8. The
11743@option{-G @var{num}} switch is also passed to the linker.
11744All modules should be compiled with the same @option{-G @var{num}} value.
11745
11746@item -mregnames
11747@itemx -mno-regnames
11748@opindex mregnames
11749@opindex mno-regnames
11750On System V.4 and embedded PowerPC systems do (do not) emit register
11751names in the assembly language output using symbolic forms.
11752
11753@item -mlongcall
11754@itemx -mno-longcall
11755@opindex mlongcall
11756@opindex mno-longcall
11757By default assume that all calls are far away so that a longer more
11758expensive calling sequence is required. This is required for calls
11759further than 32 megabytes (33,554,432 bytes) from the current location.
11760A short call will be generated if the compiler knows
11761the call cannot be that far away. This setting can be overridden by
11762the @code{shortcall} function attribute, or by @code{#pragma
11763longcall(0)}.
11764
11765Some linkers are capable of detecting out-of-range calls and generating
11766glue code on the fly. On these systems, long calls are unnecessary and
11767generate slower code. As of this writing, the AIX linker can do this,
11768as can the GNU linker for PowerPC/64. It is planned to add this feature
11769to the GNU linker for 32-bit PowerPC systems as well.
11770
11771On Darwin/PPC systems, @code{#pragma longcall} will generate ``jbsr
11772callee, L42'', plus a ``branch island'' (glue code). The two target
11773addresses represent the callee and the ``branch island''. The
11774Darwin/PPC linker will prefer the first address and generate a ``bl
11775callee'' if the PPC ``bl'' instruction will reach the callee directly;
11776otherwise, the linker will generate ``bl L42'' to call the ``branch
11777island''. The ``branch island'' is appended to the body of the
11778calling function; it computes the full 32-bit address of the callee
11779and jumps to it.
11780
11781On Mach-O (Darwin) systems, this option directs the compiler emit to
11782the glue for every direct call, and the Darwin linker decides whether
11783to use or discard it.
11784
11785In the future, we may cause GCC to ignore all longcall specifications
11786when the linker is known to generate glue.
11787
11788@item -pthread
11789@opindex pthread
11790Adds support for multithreading with the @dfn{pthreads} library.
11791This option sets flags for both the preprocessor and linker.
11792
11793@end table
11794
11795@node S/390 and zSeries Options
11796@subsection S/390 and zSeries Options
11797@cindex S/390 and zSeries Options
11798
11799These are the @samp{-m} options defined for the S/390 and zSeries architecture.
11800
11801@table @gcctabopt
11802@item -mhard-float
11803@itemx -msoft-float
11804@opindex mhard-float
11805@opindex msoft-float
11806Use (do not use) the hardware floating-point instructions and registers
11807for floating-point operations. When @option{-msoft-float} is specified,
11808functions in @file{libgcc.a} will be used to perform floating-point
11809operations. When @option{-mhard-float} is specified, the compiler
11810generates IEEE floating-point instructions. This is the default.
11811
11812@item -mlong-double-64
11813@itemx -mlong-double-128
11814@opindex mlong-double-64
11815@opindex mlong-double-128
11816These switches control the size of @code{long double} type. A size
11817of 64bit makes the @code{long double} type equivalent to the @code{double}
11818type. This is the default.
11819
11820@item -mbackchain
11821@itemx -mno-backchain
11822@opindex mbackchain
11823@opindex mno-backchain
11824Store (do not store) the address of the caller's frame as backchain pointer
11825into the callee's stack frame.
11826A backchain may be needed to allow debugging using tools that do not understand
11827DWARF-2 call frame information.
11828When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
11829at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
11830the backchain is placed into the topmost word of the 96/160 byte register
11831save area.
11832
11833In general, code compiled with @option{-mbackchain} is call-compatible with
11834code compiled with @option{-mmo-backchain}; however, use of the backchain
11835for debugging purposes usually requires that the whole binary is built with
11836@option{-mbackchain}. Note that the combination of @option{-mbackchain},
11837@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
11838to build a linux kernel use @option{-msoft-float}.
11839
11840The default is to not maintain the backchain.
11841
11842@item -mpacked-stack
11843@item -mno-packed-stack
11844@opindex mpacked-stack
11845@opindex mno-packed-stack
11846Use (do not use) the packed stack layout. When @option{-mno-packed-stack} is
11847specified, the compiler uses the all fields of the 96/160 byte register save
11848area only for their default purpose; unused fields still take up stack space.
11849When @option{-mpacked-stack} is specified, register save slots are densely
11850packed at the top of the register save area; unused space is reused for other
11851purposes, allowing for more efficient use of the available stack space.
11852However, when @option{-mbackchain} is also in effect, the topmost word of
11853the save area is always used to store the backchain, and the return address
11854register is always saved two words below the backchain.
11855
11856As long as the stack frame backchain is not used, code generated with
11857@option{-mpacked-stack} is call-compatible with code generated with
11858@option{-mno-packed-stack}. Note that some non-FSF releases of GCC 2.95 for
11859S/390 or zSeries generated code that uses the stack frame backchain at run
11860time, not just for debugging purposes. Such code is not call-compatible
11861with code compiled with @option{-mpacked-stack}. Also, note that the
11862combination of @option{-mbackchain},
11863@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
11864to build a linux kernel use @option{-msoft-float}.
11865
11866The default is to not use the packed stack layout.
11867
11868@item -msmall-exec
11869@itemx -mno-small-exec
11870@opindex msmall-exec
11871@opindex mno-small-exec
11872Generate (or do not generate) code using the @code{bras} instruction
11873to do subroutine calls.
11874This only works reliably if the total executable size does not
11875exceed 64k. The default is to use the @code{basr} instruction instead,
11876which does not have this limitation.
11877
11878@item -m64
11879@itemx -m31
11880@opindex m64
11881@opindex m31
11882When @option{-m31} is specified, generate code compliant to the
11883GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate
11884code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in
11885particular to generate 64-bit instructions. For the @samp{s390}
11886targets, the default is @option{-m31}, while the @samp{s390x}
11887targets default to @option{-m64}.
11888
11889@item -mzarch
11890@itemx -mesa
11891@opindex mzarch
11892@opindex mesa
11893When @option{-mzarch} is specified, generate code using the
11894instructions available on z/Architecture.
11895When @option{-mesa} is specified, generate code using the
11896instructions available on ESA/390. Note that @option{-mesa} is
11897not possible with @option{-m64}.
11898When generating code compliant to the GNU/Linux for S/390 ABI,
11899the default is @option{-mesa}. When generating code compliant
11900to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
11901
11902@item -mmvcle
11903@itemx -mno-mvcle
11904@opindex mmvcle
11905@opindex mno-mvcle
11906Generate (or do not generate) code using the @code{mvcle} instruction
11907to perform block moves. When @option{-mno-mvcle} is specified,
11908use a @code{mvc} loop instead. This is the default unless optimizing for
11909size.
11910
11911@item -mdebug
11912@itemx -mno-debug
11913@opindex mdebug
11914@opindex mno-debug
11915Print (or do not print) additional debug information when compiling.
11916The default is to not print debug information.
11917
11918@item -march=@var{cpu-type}
11919@opindex march
11920Generate code that will run on @var{cpu-type}, which is the name of a system
11921representing a certain processor type. Possible values for
11922@var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, and @samp{z990}.
11923When generating code using the instructions available on z/Architecture,
11924the default is @option{-march=z900}. Otherwise, the default is
11925@option{-march=g5}.
11926
11927@item -mtune=@var{cpu-type}
11928@opindex mtune
11929Tune to @var{cpu-type} everything applicable about the generated code,
11930except for the ABI and the set of available instructions.
11931The list of @var{cpu-type} values is the same as for @option{-march}.
11932The default is the value used for @option{-march}.
11933
11934@item -mtpf-trace
11935@itemx -mno-tpf-trace
11936@opindex mtpf-trace
11937@opindex mno-tpf-trace
11938Generate code that adds (does not add) in TPF OS specific branches to trace
11939routines in the operating system. This option is off by default, even
11940when compiling for the TPF OS@.
11941
11942@item -mfused-madd
11943@itemx -mno-fused-madd
11944@opindex mfused-madd
11945@opindex mno-fused-madd
11946Generate code that uses (does not use) the floating point multiply and
11947accumulate instructions. These instructions are generated by default if
11948hardware floating point is used.
11949
11950@item -mwarn-framesize=@var{framesize}
11951@opindex mwarn-framesize
11952Emit a warning if the current function exceeds the given frame size. Because
11953this is a compile time check it doesn't need to be a real problem when the program
11954runs. It is intended to identify functions which most probably cause
11955a stack overflow. It is useful to be used in an environment with limited stack
11956size e.g.@: the linux kernel.
11957
11958@item -mwarn-dynamicstack
11959@opindex mwarn-dynamicstack
11960Emit a warning if the function calls alloca or uses dynamically
11961sized arrays. This is generally a bad idea with a limited stack size.
11962
11963@item -mstack-guard=@var{stack-guard}
11964@item -mstack-size=@var{stack-size}
11965@opindex mstack-guard
11966@opindex mstack-size
11967These arguments always have to be used in conjunction. If they are present the s390
11968back end emits additional instructions in the function prologue which trigger a trap
11969if the stack size is @var{stack-guard} bytes above the @var{stack-size}
11970(remember that the stack on s390 grows downward). These options are intended to
11971be used to help debugging stack overflow problems. The additionally emitted code
11972causes only little overhead and hence can also be used in production like systems
11973without greater performance degradation. The given values have to be exact
11974powers of 2 and @var{stack-size} has to be greater than @var{stack-guard} without
11975exceeding 64k.
11976In order to be efficient the extra code makes the assumption that the stack starts
11977at an address aligned to the value given by @var{stack-size}.
11978@end table
11979
11980@node Score Options
11981@subsection Score Options
11982@cindex Score Options
11983
11984These options are defined for Score implementations:
11985
11986@table @gcctabopt
11987@item -meb
11988@opindex meb
11989Compile code for big endian mode. This is the default.
11990
11991@item -mel
11992@opindex mel
11993Compile code for little endian mode.
11994
11995@item -mnhwloop
11996@opindex mnhwloop
11997Disable generate bcnz instruction.
11998
11999@item -muls
12000@opindex muls
12001Enable generate unaligned load and store instruction.
12002
12003@item -mmac
12004@opindex mmac
12005Enable the use of multiply-accumulate instructions. Disabled by default.
12006
12007@item -mscore5
12008@opindex mscore5
12009Specify the SCORE5 as the target architecture.
12010
12011@item -mscore5u
12012@opindex mscore5u
12013Specify the SCORE5U of the target architecture.
12014
12015@item -mscore7
12016@opindex mscore7
12017Specify the SCORE7 as the target architecture. This is the default.
12018
12019@item -mscore7d
12020@opindex mscore7d
12021Specify the SCORE7D as the target architecture.
12022@end table
12023
12024@node SH Options
12025@subsection SH Options
12026
12027These @samp{-m} options are defined for the SH implementations:
12028
12029@table @gcctabopt
12030@item -m1
12031@opindex m1
12032Generate code for the SH1.
12033
12034@item -m2
12035@opindex m2
12036Generate code for the SH2.
12037
12038@item -m2e
12039Generate code for the SH2e.
12040
12041@item -m3
12042@opindex m3
12043Generate code for the SH3.
12044
12045@item -m3e
12046@opindex m3e
12047Generate code for the SH3e.
12048
12049@item -m4-nofpu
12050@opindex m4-nofpu
12051Generate code for the SH4 without a floating-point unit.
12052
12053@item -m4-single-only
12054@opindex m4-single-only
12055Generate code for the SH4 with a floating-point unit that only
12056supports single-precision arithmetic.
12057
12058@item -m4-single
12059@opindex m4-single
12060Generate code for the SH4 assuming the floating-point unit is in
12061single-precision mode by default.
12062
12063@item -m4
12064@opindex m4
12065Generate code for the SH4.
12066
12067@item -m4a-nofpu
12068@opindex m4a-nofpu
12069Generate code for the SH4al-dsp, or for a SH4a in such a way that the
12070floating-point unit is not used.
12071
12072@item -m4a-single-only
12073@opindex m4a-single-only
12074Generate code for the SH4a, in such a way that no double-precision
12075floating point operations are used.
12076
12077@item -m4a-single
12078@opindex m4a-single
12079Generate code for the SH4a assuming the floating-point unit is in
12080single-precision mode by default.
12081
12082@item -m4a
12083@opindex m4a
12084Generate code for the SH4a.
12085
12086@item -m4al
12087@opindex m4al
12088Same as @option{-m4a-nofpu}, except that it implicitly passes
12089@option{-dsp} to the assembler. GCC doesn't generate any DSP
12090instructions at the moment.
12091
12092@item -mb
12093@opindex mb
12094Compile code for the processor in big endian mode.
12095
12096@item -ml
12097@opindex ml
12098Compile code for the processor in little endian mode.
12099
12100@item -mdalign
12101@opindex mdalign
12102Align doubles at 64-bit boundaries. Note that this changes the calling
12103conventions, and thus some functions from the standard C library will
12104not work unless you recompile it first with @option{-mdalign}.
12105
12106@item -mrelax
12107@opindex mrelax
12108Shorten some address references at link time, when possible; uses the
12109linker option @option{-relax}.
12110
12111@item -mbigtable
12112@opindex mbigtable
12113Use 32-bit offsets in @code{switch} tables. The default is to use
1211416-bit offsets.
12115
12116@item -mfmovd
12117@opindex mfmovd
12118Enable the use of the instruction @code{fmovd}.
12119
12120@item -mhitachi
12121@opindex mhitachi
12122Comply with the calling conventions defined by Renesas.
12123
12124@item -mrenesas
12125@opindex mhitachi
12126Comply with the calling conventions defined by Renesas.
12127
12128@item -mno-renesas
12129@opindex mhitachi
12130Comply with the calling conventions defined for GCC before the Renesas
12131conventions were available. This option is the default for all
12132targets of the SH toolchain except for @samp{sh-symbianelf}.
12133
12134@item -mnomacsave
12135@opindex mnomacsave
12136Mark the @code{MAC} register as call-clobbered, even if
12137@option{-mhitachi} is given.
12138
12139@item -mieee
12140@opindex mieee
12141Increase IEEE-compliance of floating-point code.
12142At the moment, this is equivalent to @option{-fno-finite-math-only}.
12143When generating 16 bit SH opcodes, getting IEEE-conforming results for
12144comparisons of NANs / infinities incurs extra overhead in every
12145floating point comparison, therefore the default is set to
12146@option{-ffinite-math-only}.
12147
12148@item -misize
12149@opindex misize
12150Dump instruction size and location in the assembly code.
12151
12152@item -mpadstruct
12153@opindex mpadstruct
12154This option is deprecated. It pads structures to multiple of 4 bytes,
12155which is incompatible with the SH ABI@.
12156
12157@item -mspace
12158@opindex mspace
12159Optimize for space instead of speed. Implied by @option{-Os}.
12160
12161@item -mprefergot
12162@opindex mprefergot
12163When generating position-independent code, emit function calls using
12164the Global Offset Table instead of the Procedure Linkage Table.
12165
12166@item -musermode
12167@opindex musermode
12168Generate a library function call to invalidate instruction cache
12169entries, after fixing up a trampoline. This library function call
12170doesn't assume it can write to the whole memory address space. This
12171is the default when the target is @code{sh-*-linux*}.
12172
12173@item -multcost=@var{number}
12174@opindex multcost=@var{number}
12175Set the cost to assume for a multiply insn.
12176
12177@item -mdiv=@var{strategy}
12178@opindex mdiv=@var{strategy}
12179Set the division strategy to use for SHmedia code. @var{strategy} must be
12180one of: call, call2, fp, inv, inv:minlat, inv20u, inv20l, inv:call,
12181inv:call2, inv:fp .
12182"fp" performs the operation in floating point. This has a very high latency,
12183but needs only a few instructions, so it might be a good choice if
12184your code has enough easily exploitable ILP to allow the compiler to
12185schedule the floating point instructions together with other instructions.
12186Division by zero causes a floating point exception.
12187"inv" uses integer operations to calculate the inverse of the divisor,
12188and then multiplies the dividend with the inverse. This strategy allows
12189cse and hoisting of the inverse calculation. Division by zero calculates
12190an unspecified result, but does not trap.
12191"inv:minlat" is a variant of "inv" where if no cse / hoisting opportunities
12192have been found, or if the entire operation has been hoisted to the same
12193place, the last stages of the inverse calculation are intertwined with the
12194final multiply to reduce the overall latency, at the expense of using a few
12195more instructions, and thus offering fewer scheduling opportunities with
12196other code.
12197"call" calls a library function that usually implements the inv:minlat
12198strategy.
12199This gives high code density for m5-*media-nofpu compilations.
12200"call2" uses a different entry point of the same library function, where it
12201assumes that a pointer to a lookup table has already been set up, which
12202exposes the pointer load to cse / code hoisting optimizations.
12203"inv:call", "inv:call2" and "inv:fp" all use the "inv" algorithm for initial
12204code generation, but if the code stays unoptimized, revert to the "call",
12205"call2", or "fp" strategies, respectively. Note that the
12206potentially-trapping side effect of division by zero is carried by a
12207separate instruction, so it is possible that all the integer instructions
12208are hoisted out, but the marker for the side effect stays where it is.
12209A recombination to fp operations or a call is not possible in that case.
12210"inv20u" and "inv20l" are variants of the "inv:minlat" strategy. In the case
12211that the inverse calculation was nor separated from the multiply, they speed
12212up division where the dividend fits into 20 bits (plus sign where applicable),
12213by inserting a test to skip a number of operations in this case; this test
12214slows down the case of larger dividends. inv20u assumes the case of a such
12215a small dividend to be unlikely, and inv20l assumes it to be likely.
12216
12217@item -mdivsi3_libfunc=@var{name}
12218@opindex mdivsi3_libfunc=@var{name}
12219Set the name of the library function used for 32 bit signed division to
12220@var{name}. This only affect the name used in the call and inv:call
12221division strategies, and the compiler will still expect the same
12222sets of input/output/clobbered registers as if this option was not present.
12223
12224@item -madjust-unroll
12225@opindex madjust-unroll
12226Throttle unrolling to avoid thrashing target registers.
12227This option only has an effect if the gcc code base supports the
12228TARGET_ADJUST_UNROLL_MAX target hook.
12229
12230@item -mindexed-addressing
12231@opindex mindexed-addressing
12232Enable the use of the indexed addressing mode for SHmedia32/SHcompact.
12233This is only safe if the hardware and/or OS implement 32 bit wrap-around
12234semantics for the indexed addressing mode. The architecture allows the
12235implementation of processors with 64 bit MMU, which the OS could use to
12236get 32 bit addressing, but since no current hardware implementation supports
12237this or any other way to make the indexed addressing mode safe to use in
12238the 32 bit ABI, the default is -mno-indexed-addressing.
12239
12240@item -mgettrcost=@var{number}
12241@opindex mgettrcost=@var{number}
12242Set the cost assumed for the gettr instruction to @var{number}.
12243The default is 2 if @option{-mpt-fixed} is in effect, 100 otherwise.
12244
12245@item -mpt-fixed
12246@opindex mpt-fixed
12247Assume pt* instructions won't trap. This will generally generate better
12248scheduled code, but is unsafe on current hardware. The current architecture
12249definition says that ptabs and ptrel trap when the target anded with 3 is 3.
12250This has the unintentional effect of making it unsafe to schedule ptabs /
12251ptrel before a branch, or hoist it out of a loop. For example,
12252__do_global_ctors, a part of libgcc that runs constructors at program
12253startup, calls functions in a list which is delimited by -1. With the
12254-mpt-fixed option, the ptabs will be done before testing against -1.
12255That means that all the constructors will be run a bit quicker, but when
12256the loop comes to the end of the list, the program crashes because ptabs
12257loads -1 into a target register. Since this option is unsafe for any
12258hardware implementing the current architecture specification, the default
12259is -mno-pt-fixed. Unless the user specifies a specific cost with
12260@option{-mgettrcost}, -mno-pt-fixed also implies @option{-mgettrcost=100};
12261this deters register allocation using target registers for storing
12262ordinary integers.
12263
12264@item -minvalid-symbols
12265@opindex minvalid-symbols
12266Assume symbols might be invalid. Ordinary function symbols generated by
12267the compiler will always be valid to load with movi/shori/ptabs or
12268movi/shori/ptrel, but with assembler and/or linker tricks it is possible
12269to generate symbols that will cause ptabs / ptrel to trap.
12270This option is only meaningful when @option{-mno-pt-fixed} is in effect.
12271It will then prevent cross-basic-block cse, hoisting and most scheduling
12272of symbol loads. The default is @option{-mno-invalid-symbols}.
12273@end table
12274
12275@node SPARC Options
12276@subsection SPARC Options
12277@cindex SPARC options
12278
12279These @samp{-m} options are supported on the SPARC:
12280
12281@table @gcctabopt
12282@item -mno-app-regs
12283@itemx -mapp-regs
12284@opindex mno-app-regs
12285@opindex mapp-regs
12286Specify @option{-mapp-regs} to generate output using the global registers
122872 through 4, which the SPARC SVR4 ABI reserves for applications. This
12288is the default.
12289
12290To be fully SVR4 ABI compliant at the cost of some performance loss,
12291specify @option{-mno-app-regs}. You should compile libraries and system
12292software with this option.
12293
12294@item -mfpu
12295@itemx -mhard-float
12296@opindex mfpu
12297@opindex mhard-float
12298Generate output containing floating point instructions. This is the
12299default.
12300
12301@item -mno-fpu
12302@itemx -msoft-float
12303@opindex mno-fpu
12304@opindex msoft-float
12305Generate output containing library calls for floating point.
12306@strong{Warning:} the requisite libraries are not available for all SPARC
12307targets. Normally the facilities of the machine's usual C compiler are
12308used, but this cannot be done directly in cross-compilation. You must make
12309your own arrangements to provide suitable library functions for
12310cross-compilation. The embedded targets @samp{sparc-*-aout} and
12311@samp{sparclite-*-*} do provide software floating point support.
12312
12313@option{-msoft-float} changes the calling convention in the output file;
12314therefore, it is only useful if you compile @emph{all} of a program with
12315this option. In particular, you need to compile @file{libgcc.a}, the
12316library that comes with GCC, with @option{-msoft-float} in order for
12317this to work.
12318
12319@item -mhard-quad-float
12320@opindex mhard-quad-float
12321Generate output containing quad-word (long double) floating point
12322instructions.
12323
12324@item -msoft-quad-float
12325@opindex msoft-quad-float
12326Generate output containing library calls for quad-word (long double)
12327floating point instructions. The functions called are those specified
12328in the SPARC ABI@. This is the default.
12329
12330As of this writing, there are no SPARC implementations that have hardware
12331support for the quad-word floating point instructions. They all invoke
12332a trap handler for one of these instructions, and then the trap handler
12333emulates the effect of the instruction. Because of the trap handler overhead,
12334this is much slower than calling the ABI library routines. Thus the
12335@option{-msoft-quad-float} option is the default.
12336
12337@item -mno-unaligned-doubles
12338@itemx -munaligned-doubles
12339@opindex mno-unaligned-doubles
12340@opindex munaligned-doubles
12341Assume that doubles have 8 byte alignment. This is the default.
12342
12343With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
12344alignment only if they are contained in another type, or if they have an
12345absolute address. Otherwise, it assumes they have 4 byte alignment.
12346Specifying this option avoids some rare compatibility problems with code
12347generated by other compilers. It is not the default because it results
12348in a performance loss, especially for floating point code.
12349
12350@item -mno-faster-structs
12351@itemx -mfaster-structs
12352@opindex mno-faster-structs
12353@opindex mfaster-structs
12354With @option{-mfaster-structs}, the compiler assumes that structures
12355should have 8 byte alignment. This enables the use of pairs of
12356@code{ldd} and @code{std} instructions for copies in structure
12357assignment, in place of twice as many @code{ld} and @code{st} pairs.
12358However, the use of this changed alignment directly violates the SPARC
12359ABI@. Thus, it's intended only for use on targets where the developer
12360acknowledges that their resulting code will not be directly in line with
12361the rules of the ABI@.
12362
12363@item -mimpure-text
12364@opindex mimpure-text
12365@option{-mimpure-text}, used in addition to @option{-shared}, tells
12366the compiler to not pass @option{-z text} to the linker when linking a
12367shared object. Using this option, you can link position-dependent
12368code into a shared object.
12369
12370@option{-mimpure-text} suppresses the ``relocations remain against
12371allocatable but non-writable sections'' linker error message.
12372However, the necessary relocations will trigger copy-on-write, and the
12373shared object is not actually shared across processes. Instead of
12374using @option{-mimpure-text}, you should compile all source code with
12375@option{-fpic} or @option{-fPIC}.
12376
12377This option is only available on SunOS and Solaris.
12378
12379@item -mcpu=@var{cpu_type}
12380@opindex mcpu
12381Set the instruction set, register set, and instruction scheduling parameters
12382for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
12383@samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
12384@samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x},
12385@samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc},
12386@samp{ultrasparc3}, and @samp{niagara}.
12387
12388Default instruction scheduling parameters are used for values that select
12389an architecture and not an implementation. These are @samp{v7}, @samp{v8},
12390@samp{sparclite}, @samp{sparclet}, @samp{v9}.
12391
12392Here is a list of each supported architecture and their supported
12393implementations.
12394
12395@smallexample
12396 v7: cypress
12397 v8: supersparc, hypersparc
12398 sparclite: f930, f934, sparclite86x
12399 sparclet: tsc701
12400 v9: ultrasparc, ultrasparc3, niagara
12401@end smallexample
12402
12403By default (unless configured otherwise), GCC generates code for the V7
12404variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler
12405additionally optimizes it for the Cypress CY7C602 chip, as used in the
12406SPARCStation/SPARCServer 3xx series. This is also appropriate for the older
12407SPARCStation 1, 2, IPX etc.
12408
12409With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
12410architecture. The only difference from V7 code is that the compiler emits
12411the integer multiply and integer divide instructions which exist in SPARC-V8
12412but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally
12413optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
124142000 series.
12415
12416With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
12417the SPARC architecture. This adds the integer multiply, integer divide step
12418and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
12419With @option{-mcpu=f930}, the compiler additionally optimizes it for the
12420Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@. With
12421@option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
12422MB86934 chip, which is the more recent SPARClite with FPU@.
12423
12424With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
12425the SPARC architecture. This adds the integer multiply, multiply/accumulate,
12426integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
12427but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally
12428optimizes it for the TEMIC SPARClet chip.
12429
12430With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
12431architecture. This adds 64-bit integer and floating-point move instructions,
124323 additional floating-point condition code registers and conditional move
12433instructions. With @option{-mcpu=ultrasparc}, the compiler additionally
12434optimizes it for the Sun UltraSPARC I/II/IIi chips. With
12435@option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
12436Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips. With
12437@option{-mcpu=niagara}, the compiler additionally optimizes it for
12438Sun UltraSPARC T1 chips.
12439
12440@item -mtune=@var{cpu_type}
12441@opindex mtune
12442Set the instruction scheduling parameters for machine type
12443@var{cpu_type}, but do not set the instruction set or register set that the
12444option @option{-mcpu=@var{cpu_type}} would.
12445
12446The same values for @option{-mcpu=@var{cpu_type}} can be used for
12447@option{-mtune=@var{cpu_type}}, but the only useful values are those
12448that select a particular cpu implementation. Those are @samp{cypress},
12449@samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
12450@samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc},
12451@samp{ultrasparc3}, and @samp{niagara}.
12452
12453@item -mv8plus
12454@itemx -mno-v8plus
12455@opindex mv8plus
12456@opindex mno-v8plus
12457With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@. The
12458difference from the V8 ABI is that the global and out registers are
12459considered 64-bit wide. This is enabled by default on Solaris in 32-bit
12460mode for all SPARC-V9 processors.
12461
12462@item -mvis
12463@itemx -mno-vis
12464@opindex mvis
12465@opindex mno-vis
12466With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
12467Visual Instruction Set extensions. The default is @option{-mno-vis}.
12468@end table
12469
12470These @samp{-m} options are supported in addition to the above
12471on SPARC-V9 processors in 64-bit environments:
12472
12473@table @gcctabopt
12474@item -mlittle-endian
12475@opindex mlittle-endian
12476Generate code for a processor running in little-endian mode. It is only
12477available for a few configurations and most notably not on Solaris and Linux.
12478
12479@item -m32
12480@itemx -m64
12481@opindex m32
12482@opindex m64
12483Generate code for a 32-bit or 64-bit environment.
12484The 32-bit environment sets int, long and pointer to 32 bits.
12485The 64-bit environment sets int to 32 bits and long and pointer
12486to 64 bits.
12487
12488@item -mcmodel=medlow
12489@opindex mcmodel=medlow
12490Generate code for the Medium/Low code model: 64-bit addresses, programs
12491must be linked in the low 32 bits of memory. Programs can be statically
12492or dynamically linked.
12493
12494@item -mcmodel=medmid
12495@opindex mcmodel=medmid
12496Generate code for the Medium/Middle code model: 64-bit addresses, programs
12497must be linked in the low 44 bits of memory, the text and data segments must
12498be less than 2GB in size and the data segment must be located within 2GB of
12499the text segment.
12500
12501@item -mcmodel=medany
12502@opindex mcmodel=medany
12503Generate code for the Medium/Anywhere code model: 64-bit addresses, programs
12504may be linked anywhere in memory, the text and data segments must be less
12505than 2GB in size and the data segment must be located within 2GB of the
12506text segment.
12507
12508@item -mcmodel=embmedany
12509@opindex mcmodel=embmedany
12510Generate code for the Medium/Anywhere code model for embedded systems:
1251164-bit addresses, the text and data segments must be less than 2GB in
12512size, both starting anywhere in memory (determined at link time). The
12513global register %g4 points to the base of the data segment. Programs
12514are statically linked and PIC is not supported.
12515
12516@item -mstack-bias
12517@itemx -mno-stack-bias
12518@opindex mstack-bias
12519@opindex mno-stack-bias
12520With @option{-mstack-bias}, GCC assumes that the stack pointer, and
12521frame pointer if present, are offset by @minus{}2047 which must be added back
12522when making stack frame references. This is the default in 64-bit mode.
12523Otherwise, assume no such offset is present.
12524@end table
12525
12526These switches are supported in addition to the above on Solaris:
12527
12528@table @gcctabopt
12529@item -threads
12530@opindex threads
12531Add support for multithreading using the Solaris threads library. This
12532option sets flags for both the preprocessor and linker. This option does
12533not affect the thread safety of object code produced by the compiler or
12534that of libraries supplied with it.
12535
12536@item -pthreads
12537@opindex pthreads
12538Add support for multithreading using the POSIX threads library. This
12539option sets flags for both the preprocessor and linker. This option does
12540not affect the thread safety of object code produced by the compiler or
12541that of libraries supplied with it.
12542
12543@item -pthread
12544@opindex pthread
12545This is a synonym for @option{-pthreads}.
12546@end table
12547
12548@node System V Options
12549@subsection Options for System V
12550
12551These additional options are available on System V Release 4 for
12552compatibility with other compilers on those systems:
12553
12554@table @gcctabopt
12555@item -G
12556@opindex G
12557Create a shared object.
12558It is recommended that @option{-symbolic} or @option{-shared} be used instead.
12559
12560@item -Qy
12561@opindex Qy
12562Identify the versions of each tool used by the compiler, in a
12563@code{.ident} assembler directive in the output.
12564
12565@item -Qn
12566@opindex Qn
12567Refrain from adding @code{.ident} directives to the output file (this is
12568the default).
12569
12570@item -YP,@var{dirs}
12571@opindex YP
12572Search the directories @var{dirs}, and no others, for libraries
12573specified with @option{-l}.
12574
12575@item -Ym,@var{dir}
12576@opindex Ym
12577Look in the directory @var{dir} to find the M4 preprocessor.
12578The assembler uses this option.
12579@c This is supposed to go with a -Yd for predefined M4 macro files, but
12580@c the generic assembler that comes with Solaris takes just -Ym.
12581@end table
12582
12583@node TMS320C3x/C4x Options
12584@subsection TMS320C3x/C4x Options
12585@cindex TMS320C3x/C4x Options
12586
12587These @samp{-m} options are defined for TMS320C3x/C4x implementations:
12588
12589@table @gcctabopt
12590
12591@item -mcpu=@var{cpu_type}
12592@opindex mcpu
12593Set the instruction set, register set, and instruction scheduling
12594parameters for machine type @var{cpu_type}. Supported values for
12595@var{cpu_type} are @samp{c30}, @samp{c31}, @samp{c32}, @samp{c40}, and
12596@samp{c44}. The default is @samp{c40} to generate code for the
12597TMS320C40.
12598
12599@item -mbig-memory
12600@itemx -mbig
12601@itemx -msmall-memory
12602@itemx -msmall
12603@opindex mbig-memory
12604@opindex mbig
12605@opindex msmall-memory
12606@opindex msmall
12607Generates code for the big or small memory model. The small memory
12608model assumed that all data fits into one 64K word page. At run-time
12609the data page (DP) register must be set to point to the 64K page
12610containing the .bss and .data program sections. The big memory model is
12611the default and requires reloading of the DP register for every direct
12612memory access.
12613
12614@item -mbk
12615@itemx -mno-bk
12616@opindex mbk
12617@opindex mno-bk
12618Allow (disallow) allocation of general integer operands into the block
12619count register BK@.
12620
12621@item -mdb
12622@itemx -mno-db
12623@opindex mdb
12624@opindex mno-db
12625Enable (disable) generation of code using decrement and branch,
12626DBcond(D), instructions. This is enabled by default for the C4x. To be
12627on the safe side, this is disabled for the C3x, since the maximum
12628iteration count on the C3x is @math{2^{23} + 1} (but who iterates loops more than
12629@math{2^{23}} times on the C3x?). Note that GCC will try to reverse a loop so
12630that it can utilize the decrement and branch instruction, but will give
12631up if there is more than one memory reference in the loop. Thus a loop
12632where the loop counter is decremented can generate slightly more
12633efficient code, in cases where the RPTB instruction cannot be utilized.
12634
12635@item -mdp-isr-reload
12636@itemx -mparanoid
12637@opindex mdp-isr-reload
12638@opindex mparanoid
12639Force the DP register to be saved on entry to an interrupt service
12640routine (ISR), reloaded to point to the data section, and restored on
12641exit from the ISR@. This should not be required unless someone has
12642violated the small memory model by modifying the DP register, say within
12643an object library.
12644
12645@item -mmpyi
12646@itemx -mno-mpyi
12647@opindex mmpyi
12648@opindex mno-mpyi
12649For the C3x use the 24-bit MPYI instruction for integer multiplies
12650instead of a library call to guarantee 32-bit results. Note that if one
12651of the operands is a constant, then the multiplication will be performed
12652using shifts and adds. If the @option{-mmpyi} option is not specified for the C3x,
12653then squaring operations are performed inline instead of a library call.
12654
12655@item -mfast-fix
12656@itemx -mno-fast-fix
12657@opindex mfast-fix
12658@opindex mno-fast-fix
12659The C3x/C4x FIX instruction to convert a floating point value to an
12660integer value chooses the nearest integer less than or equal to the
12661floating point value rather than to the nearest integer. Thus if the
12662floating point number is negative, the result will be incorrectly
12663truncated an additional code is necessary to detect and correct this
12664case. This option can be used to disable generation of the additional
12665code required to correct the result.
12666
12667@item -mrptb
12668@itemx -mno-rptb
12669@opindex mrptb
12670@opindex mno-rptb
12671Enable (disable) generation of repeat block sequences using the RPTB
12672instruction for zero overhead looping. The RPTB construct is only used
12673for innermost loops that do not call functions or jump across the loop
12674boundaries. There is no advantage having nested RPTB loops due to the
12675overhead required to save and restore the RC, RS, and RE registers.
12676This is enabled by default with @option{-O2}.
12677
12678@item -mrpts=@var{count}
12679@itemx -mno-rpts
12680@opindex mrpts
12681@opindex mno-rpts
12682Enable (disable) the use of the single instruction repeat instruction
12683RPTS@. If a repeat block contains a single instruction, and the loop
12684count can be guaranteed to be less than the value @var{count}, GCC will
12685emit a RPTS instruction instead of a RPTB@. If no value is specified,
12686then a RPTS will be emitted even if the loop count cannot be determined
12687at compile time. Note that the repeated instruction following RPTS does
12688not have to be reloaded from memory each iteration, thus freeing up the
12689CPU buses for operands. However, since interrupts are blocked by this
12690instruction, it is disabled by default.
12691
12692@item -mloop-unsigned
12693@itemx -mno-loop-unsigned
12694@opindex mloop-unsigned
12695@opindex mno-loop-unsigned
12696The maximum iteration count when using RPTS and RPTB (and DB on the C40)
12697is @math{2^{31} + 1} since these instructions test if the iteration count is
12698negative to terminate the loop. If the iteration count is unsigned
12699there is a possibility than the @math{2^{31} + 1} maximum iteration count may be
12700exceeded. This switch allows an unsigned iteration count.
12701
12702@item -mti
12703@opindex mti
12704Try to emit an assembler syntax that the TI assembler (asm30) is happy
12705with. This also enforces compatibility with the API employed by the TI
12706C3x C compiler. For example, long doubles are passed as structures
12707rather than in floating point registers.
12708
12709@item -mregparm
12710@itemx -mmemparm
12711@opindex mregparm
12712@opindex mmemparm
12713Generate code that uses registers (stack) for passing arguments to functions.
12714By default, arguments are passed in registers where possible rather
12715than by pushing arguments on to the stack.
12716
12717@item -mparallel-insns
12718@itemx -mno-parallel-insns
12719@opindex mparallel-insns
12720@opindex mno-parallel-insns
12721Allow the generation of parallel instructions. This is enabled by
12722default with @option{-O2}.
12723
12724@item -mparallel-mpy
12725@itemx -mno-parallel-mpy
12726@opindex mparallel-mpy
12727@opindex mno-parallel-mpy
12728Allow the generation of MPY||ADD and MPY||SUB parallel instructions,
12729provided @option{-mparallel-insns} is also specified. These instructions have
12730tight register constraints which can pessimize the code generation
12731of large functions.
12732
12733@end table
12734
12735@node V850 Options
12736@subsection V850 Options
12737@cindex V850 Options
12738
12739These @samp{-m} options are defined for V850 implementations:
12740
12741@table @gcctabopt
12742@item -mlong-calls
12743@itemx -mno-long-calls
12744@opindex mlong-calls
12745@opindex mno-long-calls
12746Treat all calls as being far away (near). If calls are assumed to be
12747far away, the compiler will always load the functions address up into a
12748register, and call indirect through the pointer.
12749
12750@item -mno-ep
12751@itemx -mep
12752@opindex mno-ep
12753@opindex mep
12754Do not optimize (do optimize) basic blocks that use the same index
12755pointer 4 or more times to copy pointer into the @code{ep} register, and
12756use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
12757option is on by default if you optimize.
12758
12759@item -mno-prolog-function
12760@itemx -mprolog-function
12761@opindex mno-prolog-function
12762@opindex mprolog-function
12763Do not use (do use) external functions to save and restore registers
12764at the prologue and epilogue of a function. The external functions
12765are slower, but use less code space if more than one function saves
12766the same number of registers. The @option{-mprolog-function} option
12767is on by default if you optimize.
12768
12769@item -mspace
12770@opindex mspace
12771Try to make the code as small as possible. At present, this just turns
12772on the @option{-mep} and @option{-mprolog-function} options.
12773
12774@item -mtda=@var{n}
12775@opindex mtda
12776Put static or global variables whose size is @var{n} bytes or less into
12777the tiny data area that register @code{ep} points to. The tiny data
12778area can hold up to 256 bytes in total (128 bytes for byte references).
12779
12780@item -msda=@var{n}
12781@opindex msda
12782Put static or global variables whose size is @var{n} bytes or less into
12783the small data area that register @code{gp} points to. The small data
12784area can hold up to 64 kilobytes.
12785
12786@item -mzda=@var{n}
12787@opindex mzda
12788Put static or global variables whose size is @var{n} bytes or less into
12789the first 32 kilobytes of memory.
12790
12791@item -mv850
12792@opindex mv850
12793Specify that the target processor is the V850.
12794
12795@item -mbig-switch
12796@opindex mbig-switch
12797Generate code suitable for big switch tables. Use this option only if
12798the assembler/linker complain about out of range branches within a switch
12799table.
12800
12801@item -mapp-regs
12802@opindex mapp-regs
12803This option will cause r2 and r5 to be used in the code generated by
12804the compiler. This setting is the default.
12805
12806@item -mno-app-regs
12807@opindex mno-app-regs
12808This option will cause r2 and r5 to be treated as fixed registers.
12809
12810@item -mv850e1
12811@opindex mv850e1
12812Specify that the target processor is the V850E1. The preprocessor
12813constants @samp{__v850e1__} and @samp{__v850e__} will be defined if
12814this option is used.
12815
12816@item -mv850e
12817@opindex mv850e
12818Specify that the target processor is the V850E@. The preprocessor
12819constant @samp{__v850e__} will be defined if this option is used.
12820
12821If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
12822are defined then a default target processor will be chosen and the
12823relevant @samp{__v850*__} preprocessor constant will be defined.
12824
12825The preprocessor constants @samp{__v850} and @samp{__v851__} are always
12826defined, regardless of which processor variant is the target.
12827
12828@item -mdisable-callt
12829@opindex mdisable-callt
12830This option will suppress generation of the CALLT instruction for the
12831v850e and v850e1 flavors of the v850 architecture. The default is
12832@option{-mno-disable-callt} which allows the CALLT instruction to be used.
12833
12834@end table
12835
12836@node VAX Options
12837@subsection VAX Options
12838@cindex VAX options
12839
12840These @samp{-m} options are defined for the VAX:
12841
12842@table @gcctabopt
12843@item -munix
12844@opindex munix
12845Do not output certain jump instructions (@code{aobleq} and so on)
12846that the Unix assembler for the VAX cannot handle across long
12847ranges.
12848
12849@item -mgnu
12850@opindex mgnu
12851Do output those jump instructions, on the assumption that you
12852will assemble with the GNU assembler.
12853
12854@item -mg
12855@opindex mg
12856Output code for g-format floating point numbers instead of d-format.
12857@end table
12858
12859@node x86-64 Options
12860@subsection x86-64 Options
12861@cindex x86-64 options
12862
12863These are listed under @xref{i386 and x86-64 Options}.
12864
12865@node Xstormy16 Options
12866@subsection Xstormy16 Options
12867@cindex Xstormy16 Options
12868
12869These options are defined for Xstormy16:
12870
12871@table @gcctabopt
12872@item -msim
12873@opindex msim
12874Choose startup files and linker script suitable for the simulator.
12875@end table
12876
12877@node Xtensa Options
12878@subsection Xtensa Options
12879@cindex Xtensa Options
12880
12881These options are supported for Xtensa targets:
12882
12883@table @gcctabopt
12884@item -mconst16
12885@itemx -mno-const16
12886@opindex mconst16
12887@opindex mno-const16
12888Enable or disable use of @code{CONST16} instructions for loading
12889constant values. The @code{CONST16} instruction is currently not a
12890standard option from Tensilica. When enabled, @code{CONST16}
12891instructions are always used in place of the standard @code{L32R}
12892instructions. The use of @code{CONST16} is enabled by default only if
12893the @code{L32R} instruction is not available.
12894
12895@item -mfused-madd
12896@itemx -mno-fused-madd
12897@opindex mfused-madd
12898@opindex mno-fused-madd
12899Enable or disable use of fused multiply/add and multiply/subtract
12900instructions in the floating-point option. This has no effect if the
12901floating-point option is not also enabled. Disabling fused multiply/add
12902and multiply/subtract instructions forces the compiler to use separate
12903instructions for the multiply and add/subtract operations. This may be
12904desirable in some cases where strict IEEE 754-compliant results are
12905required: the fused multiply add/subtract instructions do not round the
12906intermediate result, thereby producing results with @emph{more} bits of
12907precision than specified by the IEEE standard. Disabling fused multiply
12908add/subtract instructions also ensures that the program output is not
12909sensitive to the compiler's ability to combine multiply and add/subtract
12910operations.
12911
12912@item -mtext-section-literals
12913@itemx -mno-text-section-literals
12914@opindex mtext-section-literals
12915@opindex mno-text-section-literals
12916Control the treatment of literal pools. The default is
12917@option{-mno-text-section-literals}, which places literals in a separate
12918section in the output file. This allows the literal pool to be placed
12919in a data RAM/ROM, and it also allows the linker to combine literal
12920pools from separate object files to remove redundant literals and
12921improve code size. With @option{-mtext-section-literals}, the literals
12922are interspersed in the text section in order to keep them as close as
12923possible to their references. This may be necessary for large assembly
12924files.
12925
12926@item -mtarget-align
12927@itemx -mno-target-align
12928@opindex mtarget-align
12929@opindex mno-target-align
12930When this option is enabled, GCC instructs the assembler to
12931automatically align instructions to reduce branch penalties at the
12932expense of some code density. The assembler attempts to widen density
12933instructions to align branch targets and the instructions following call
12934instructions. If there are not enough preceding safe density
12935instructions to align a target, no widening will be performed. The
12936default is @option{-mtarget-align}. These options do not affect the
12937treatment of auto-aligned instructions like @code{LOOP}, which the
12938assembler will always align, either by widening density instructions or
12939by inserting no-op instructions.
12940
12941@item -mlongcalls
12942@itemx -mno-longcalls
12943@opindex mlongcalls
12944@opindex mno-longcalls
12945When this option is enabled, GCC instructs the assembler to translate
12946direct calls to indirect calls unless it can determine that the target
12947of a direct call is in the range allowed by the call instruction. This
12948translation typically occurs for calls to functions in other source
12949files. Specifically, the assembler translates a direct @code{CALL}
12950instruction into an @code{L32R} followed by a @code{CALLX} instruction.
12951The default is @option{-mno-longcalls}. This option should be used in
12952programs where the call target can potentially be out of range. This
12953option is implemented in the assembler, not the compiler, so the
12954assembly code generated by GCC will still show direct call
12955instructions---look at the disassembled object code to see the actual
12956instructions. Note that the assembler will use an indirect call for
12957every cross-file call, not just those that really will be out of range.
12958@end table
12959
12960@node zSeries Options
12961@subsection zSeries Options
12962@cindex zSeries options
12963
12964These are listed under @xref{S/390 and zSeries Options}.
12965
12966@node Code Gen Options
12967@section Options for Code Generation Conventions
12968@cindex code generation conventions
12969@cindex options, code generation
12970@cindex run-time options
12971
12972These machine-independent options control the interface conventions
12973used in code generation.
12974
12975Most of them have both positive and negative forms; the negative form
12976of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
12977one of the forms is listed---the one which is not the default. You
12978can figure out the other form by either removing @samp{no-} or adding
12979it.
12980
12981@table @gcctabopt
12982@item -fbounds-check
12983@opindex fbounds-check
12984For front-ends that support it, generate additional code to check that
12985indices used to access arrays are within the declared range. This is
12986currently only supported by the Java and Fortran front-ends, where
12987this option defaults to true and false respectively.
12988
12989@item -ftrapv
12990@opindex ftrapv
12991This option generates traps for signed overflow on addition, subtraction,
12992multiplication operations.
12993
12994@item -fwrapv
12995@opindex fwrapv
12996This option instructs the compiler to assume that signed arithmetic
12997overflow of addition, subtraction and multiplication wraps around
12998using twos-complement representation. This flag enables some optimizations
12999and disables others. This option is enabled by default for the Java
13000front-end, as required by the Java language specification.
13001
13002@item -fexceptions
13003@opindex fexceptions
13004Enable exception handling. Generates extra code needed to propagate
13005exceptions. For some targets, this implies GCC will generate frame
13006unwind information for all functions, which can produce significant data
13007size overhead, although it does not affect execution. If you do not
13008specify this option, GCC will enable it by default for languages like
13009C++ which normally require exception handling, and disable it for
13010languages like C that do not normally require it. However, you may need
13011to enable this option when compiling C code that needs to interoperate
13012properly with exception handlers written in C++. You may also wish to
13013disable this option if you are compiling older C++ programs that don't
13014use exception handling.
13015
13016@item -fnon-call-exceptions
13017@opindex fnon-call-exceptions
13018Generate code that allows trapping instructions to throw exceptions.
13019Note that this requires platform-specific runtime support that does
13020not exist everywhere. Moreover, it only allows @emph{trapping}
13021instructions to throw exceptions, i.e.@: memory references or floating
13022point instructions. It does not allow exceptions to be thrown from
13023arbitrary signal handlers such as @code{SIGALRM}.
13024
13025@item -funwind-tables
13026@opindex funwind-tables
13027Similar to @option{-fexceptions}, except that it will just generate any needed
13028static data, but will not affect the generated code in any other way.
13029You will normally not enable this option; instead, a language processor
13030that needs this handling would enable it on your behalf.
13031
13032@item -fasynchronous-unwind-tables
13033@opindex fasynchronous-unwind-tables
13034Generate unwind table in dwarf2 format, if supported by target machine. The
13035table is exact at each instruction boundary, so it can be used for stack
13036unwinding from asynchronous events (such as debugger or garbage collector).
13037
13038@item -fpcc-struct-return
13039@opindex fpcc-struct-return
13040Return ``short'' @code{struct} and @code{union} values in memory like
13041longer ones, rather than in registers. This convention is less
13042efficient, but it has the advantage of allowing intercallability between
13043GCC-compiled files and files compiled with other compilers, particularly
13044the Portable C Compiler (pcc).
13045
13046The precise convention for returning structures in memory depends
13047on the target configuration macros.
13048
13049Short structures and unions are those whose size and alignment match
13050that of some integer type.
13051
13052@strong{Warning:} code compiled with the @option{-fpcc-struct-return}
13053switch is not binary compatible with code compiled with the
13054@option{-freg-struct-return} switch.
13055Use it to conform to a non-default application binary interface.
13056
13057@item -freg-struct-return
13058@opindex freg-struct-return
13059Return @code{struct} and @code{union} values in registers when possible.
13060This is more efficient for small structures than
13061@option{-fpcc-struct-return}.
13062
13063If you specify neither @option{-fpcc-struct-return} nor
13064@option{-freg-struct-return}, GCC defaults to whichever convention is
13065standard for the target. If there is no standard convention, GCC
13066defaults to @option{-fpcc-struct-return}, except on targets where GCC is
13067the principal compiler. In those cases, we can choose the standard, and
13068we chose the more efficient register return alternative.
13069
13070@strong{Warning:} code compiled with the @option{-freg-struct-return}
13071switch is not binary compatible with code compiled with the
13072@option{-fpcc-struct-return} switch.
13073Use it to conform to a non-default application binary interface.
13074
13075@item -fshort-enums
13076@opindex fshort-enums
13077Allocate to an @code{enum} type only as many bytes as it needs for the
13078declared range of possible values. Specifically, the @code{enum} type
13079will be equivalent to the smallest integer type which has enough room.
13080
13081@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
13082code that is not binary compatible with code generated without that switch.
13083Use it to conform to a non-default application binary interface.
13084
13085@item -fshort-double
13086@opindex fshort-double
13087Use the same size for @code{double} as for @code{float}.
13088
13089@strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
13090code that is not binary compatible with code generated without that switch.
13091Use it to conform to a non-default application binary interface.
13092
13093@item -fshort-wchar
13094@opindex fshort-wchar
13095Override the underlying type for @samp{wchar_t} to be @samp{short
13096unsigned int} instead of the default for the target. This option is
13097useful for building programs to run under WINE@.
13098
13099@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
13100code that is not binary compatible with code generated without that switch.
13101Use it to conform to a non-default application binary interface.
13102
13103@item -fno-common
13104@opindex fno-common
13105In C, allocate even uninitialized global variables in the data section of the
13106object file, rather than generating them as common blocks. This has the
13107effect that if the same variable is declared (without @code{extern}) in
13108two different compilations, you will get an error when you link them.
13109The only reason this might be useful is if you wish to verify that the
13110program will work on other systems which always work this way.
13111
13112@item -fno-ident
13113@opindex fno-ident
13114Ignore the @samp{#ident} directive.
13115
13116@item -finhibit-size-directive
13117@opindex finhibit-size-directive
13118Don't output a @code{.size} assembler directive, or anything else that
13119would cause trouble if the function is split in the middle, and the
13120two halves are placed at locations far apart in memory. This option is
13121used when compiling @file{crtstuff.c}; you should not need to use it
13122for anything else.
13123
13124@item -fverbose-asm
13125@opindex fverbose-asm
13126Put extra commentary information in the generated assembly code to
13127make it more readable. This option is generally only of use to those
13128who actually need to read the generated assembly code (perhaps while
13129debugging the compiler itself).
13130
13131@option{-fno-verbose-asm}, the default, causes the
13132extra information to be omitted and is useful when comparing two assembler
13133files.
13134
13135@item -fpic
13136@opindex fpic
13137@cindex global offset table
13138@cindex PIC
13139Generate position-independent code (PIC) suitable for use in a shared
13140library, if supported for the target machine. Such code accesses all
13141constant addresses through a global offset table (GOT)@. The dynamic
13142loader resolves the GOT entries when the program starts (the dynamic
13143loader is not part of GCC; it is part of the operating system). If
13144the GOT size for the linked executable exceeds a machine-specific
13145maximum size, you get an error message from the linker indicating that
13146@option{-fpic} does not work; in that case, recompile with @option{-fPIC}
13147instead. (These maximums are 8k on the SPARC and 32k
13148on the m68k and RS/6000. The 386 has no such limit.)
13149
13150Position-independent code requires special support, and therefore works
13151only on certain machines. For the 386, GCC supports PIC for System V
13152but not for the Sun 386i. Code generated for the IBM RS/6000 is always
13153position-independent.
13154
13155When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13156are defined to 1.
13157
13158@item -fPIC
13159@opindex fPIC
13160If supported for the target machine, emit position-independent code,
13161suitable for dynamic linking and avoiding any limit on the size of the
13162global offset table. This option makes a difference on the m68k,
13163PowerPC and SPARC@.
13164
13165Position-independent code requires special support, and therefore works
13166only on certain machines.
13167
13168When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13169are defined to 2.
13170
13171@item -fpie
13172@itemx -fPIE
13173@opindex fpie
13174@opindex fPIE
13175These options are similar to @option{-fpic} and @option{-fPIC}, but
13176generated position independent code can be only linked into executables.
13177Usually these options are used when @option{-pie} GCC option will be
13178used during linking.
13179
13180@item -fno-jump-tables
13181@opindex fno-jump-tables
13182Do not use jump tables for switch statements even where it would be
13183more efficient than other code generation strategies. This option is
13184of use in conjunction with @option{-fpic} or @option{-fPIC} for
13185building code which forms part of a dynamic linker and cannot
13186reference the address of a jump table. On some targets, jump tables
13187do not require a GOT and this option is not needed.
13188
13189@item -ffixed-@var{reg}
13190@opindex ffixed
13191Treat the register named @var{reg} as a fixed register; generated code
13192should never refer to it (except perhaps as a stack pointer, frame
13193pointer or in some other fixed role).
13194
13195@var{reg} must be the name of a register. The register names accepted
13196are machine-specific and are defined in the @code{REGISTER_NAMES}
13197macro in the machine description macro file.
13198
13199This flag does not have a negative form, because it specifies a
13200three-way choice.
13201
13202@item -fcall-used-@var{reg}
13203@opindex fcall-used
13204Treat the register named @var{reg} as an allocable register that is
13205clobbered by function calls. It may be allocated for temporaries or
13206variables that do not live across a call. Functions compiled this way
13207will not save and restore the register @var{reg}.
13208
13209It is an error to used this flag with the frame pointer or stack pointer.
13210Use of this flag for other registers that have fixed pervasive roles in
13211the machine's execution model will produce disastrous results.
13212
13213This flag does not have a negative form, because it specifies a
13214three-way choice.
13215
13216@item -fcall-saved-@var{reg}
13217@opindex fcall-saved
13218Treat the register named @var{reg} as an allocable register saved by
13219functions. It may be allocated even for temporaries or variables that
13220live across a call. Functions compiled this way will save and restore
13221the register @var{reg} if they use it.
13222
13223It is an error to used this flag with the frame pointer or stack pointer.
13224Use of this flag for other registers that have fixed pervasive roles in
13225the machine's execution model will produce disastrous results.
13226
13227A different sort of disaster will result from the use of this flag for
13228a register in which function values may be returned.
13229
13230This flag does not have a negative form, because it specifies a
13231three-way choice.
13232
13233@item -fpack-struct[=@var{n}]
13234@opindex fpack-struct
13235Without a value specified, pack all structure members together without
13236holes. When a value is specified (which must be a small power of two), pack
13237structure members according to this value, representing the maximum
13238alignment (that is, objects with default alignment requirements larger than
13239this will be output potentially unaligned at the next fitting location.
13240
13241@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
13242code that is not binary compatible with code generated without that switch.
13243Additionally, it makes the code suboptimal.
13244Use it to conform to a non-default application binary interface.
13245
13246@item -finstrument-functions
13247@opindex finstrument-functions
13248Generate instrumentation calls for entry and exit to functions. Just
13249after function entry and just before function exit, the following
13250profiling functions will be called with the address of the current
13251function and its call site. (On some platforms,
13252@code{__builtin_return_address} does not work beyond the current
13253function, so the call site information may not be available to the
13254profiling functions otherwise.)
13255
13256@smallexample
13257void __cyg_profile_func_enter (void *this_fn,
13258 void *call_site);
13259void __cyg_profile_func_exit (void *this_fn,
13260 void *call_site);
13261@end smallexample
13262
13263The first argument is the address of the start of the current function,
13264which may be looked up exactly in the symbol table.
13265
13266This instrumentation is also done for functions expanded inline in other
13267functions. The profiling calls will indicate where, conceptually, the
13268inline function is entered and exited. This means that addressable
13269versions of such functions must be available. If all your uses of a
13270function are expanded inline, this may mean an additional expansion of
13271code size. If you use @samp{extern inline} in your C code, an
13272addressable version of such functions must be provided. (This is
13273normally the case anyways, but if you get lucky and the optimizer always
13274expands the functions inline, you might have gotten away without
13275providing static copies.)
13276
13277A function may be given the attribute @code{no_instrument_function}, in
13278which case this instrumentation will not be done. This can be used, for
13279example, for the profiling functions listed above, high-priority
13280interrupt routines, and any functions from which the profiling functions
13281cannot safely be called (perhaps signal handlers, if the profiling
13282routines generate output or allocate memory).
13283
13284@item -fstack-check
13285@opindex fstack-check
13286Generate code to verify that you do not go beyond the boundary of the
13287stack. You should specify this flag if you are running in an
13288environment with multiple threads, but only rarely need to specify it in
13289a single-threaded environment since stack overflow is automatically
13290detected on nearly all systems if there is only one stack.
13291
13292Note that this switch does not actually cause checking to be done; the
13293operating system must do that. The switch causes generation of code
13294to ensure that the operating system sees the stack being extended.
13295
13296@item -fstack-limit-register=@var{reg}
13297@itemx -fstack-limit-symbol=@var{sym}
13298@itemx -fno-stack-limit
13299@opindex fstack-limit-register
13300@opindex fstack-limit-symbol
13301@opindex fno-stack-limit
13302Generate code to ensure that the stack does not grow beyond a certain value,
13303either the value of a register or the address of a symbol. If the stack
13304would grow beyond the value, a signal is raised. For most targets,
13305the signal is raised before the stack overruns the boundary, so
13306it is possible to catch the signal without taking special precautions.
13307
13308For instance, if the stack starts at absolute address @samp{0x80000000}
13309and grows downwards, you can use the flags
13310@option{-fstack-limit-symbol=__stack_limit} and
13311@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
13312of 128KB@. Note that this may only work with the GNU linker.
13313
13314@cindex aliasing of parameters
13315@cindex parameters, aliased
13316@item -fargument-alias
13317@itemx -fargument-noalias
13318@itemx -fargument-noalias-global
13319@itemx -fargument-noalias-anything
13320@opindex fargument-alias
13321@opindex fargument-noalias
13322@opindex fargument-noalias-global
13323@opindex fargument-noalias-anything
13324Specify the possible relationships among parameters and between
13325parameters and global data.
13326
13327@option{-fargument-alias} specifies that arguments (parameters) may
13328alias each other and may alias global storage.@*
13329@option{-fargument-noalias} specifies that arguments do not alias
13330each other, but may alias global storage.@*
13331@option{-fargument-noalias-global} specifies that arguments do not
13332alias each other and do not alias global storage.
13333@option{-fargument-noalias-anything} specifies that arguments do not
13334alias any other storage.
13335
13336Each language will automatically use whatever option is required by
13337the language standard. You should not need to use these options yourself.
13338
13339@item -fleading-underscore
13340@opindex fleading-underscore
13341This option and its counterpart, @option{-fno-leading-underscore}, forcibly
13342change the way C symbols are represented in the object file. One use
13343is to help link with legacy assembly code.
13344
13345@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
13346generate code that is not binary compatible with code generated without that
13347switch. Use it to conform to a non-default application binary interface.
13348Not all targets provide complete support for this switch.
13349
13350@item -ftls-model=@var{model}
13351Alter the thread-local storage model to be used (@pxref{Thread-Local}).
13352The @var{model} argument should be one of @code{global-dynamic},
13353@code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
13354
13355The default without @option{-fpic} is @code{initial-exec}; with
13356@option{-fpic} the default is @code{global-dynamic}.
13357
13358@item -fvisibility=@var{default|internal|hidden|protected}
13359@opindex fvisibility
13360Set the default ELF image symbol visibility to the specified option---all
13361symbols will be marked with this unless overridden within the code.
13362Using this feature can very substantially improve linking and
13363load times of shared object libraries, produce more optimized
13364code, provide near-perfect API export and prevent symbol clashes.
13365It is @strong{strongly} recommended that you use this in any shared objects
13366you distribute.
13367
13368Despite the nomenclature, @code{default} always means public ie;
13369available to be linked against from outside the shared object.
13370@code{protected} and @code{internal} are pretty useless in real-world
13371usage so the only other commonly used option will be @code{hidden}.
13372The default if @option{-fvisibility} isn't specified is
13373@code{default}, i.e., make every
13374symbol public---this causes the same behavior as previous versions of
13375GCC@.
13376
13377A good explanation of the benefits offered by ensuring ELF
13378symbols have the correct visibility is given by ``How To Write
13379Shared Libraries'' by Ulrich Drepper (which can be found at
13380@w{@uref{http://people.redhat.com/~drepper/}})---however a superior
13381solution made possible by this option to marking things hidden when
13382the default is public is to make the default hidden and mark things
13383public. This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
13384and @code{__attribute__ ((visibility("default")))} instead of
13385@code{__declspec(dllexport)} you get almost identical semantics with
13386identical syntax. This is a great boon to those working with
13387cross-platform projects.
13388
13389For those adding visibility support to existing code, you may find
13390@samp{#pragma GCC visibility} of use. This works by you enclosing
13391the declarations you wish to set visibility for with (for example)
13392@samp{#pragma GCC visibility push(hidden)} and
13393@samp{#pragma GCC visibility pop}.
13394Bear in mind that symbol visibility should be viewed @strong{as
13395part of the API interface contract} and thus all new code should
13396always specify visibility when it is not the default ie; declarations
13397only for use within the local DSO should @strong{always} be marked explicitly
13398as hidden as so to avoid PLT indirection overheads---making this
13399abundantly clear also aids readability and self-documentation of the code.
13400Note that due to ISO C++ specification requirements, operator new and
13401operator delete must always be of default visibility.
13402
13403Be aware that headers from outside your project, in particular system
13404headers and headers from any other library you use, may not be
13405expecting to be compiled with visibility other than the default. You
13406may need to explicitly say @samp{#pragma GCC visibility push(default)}
13407before including any such headers.
13408
13409@samp{extern} declarations are not affected by @samp{-fvisibility}, so
13410a lot of code can be recompiled with @samp{-fvisibility=hidden} with
13411no modifications. However, this means that calls to @samp{extern}
13412functions with no explicit visibility will use the PLT, so it is more
13413effective to use @samp{__attribute ((visibility))} and/or
13414@samp{#pragma GCC visibility} to tell the compiler which @samp{extern}
13415declarations should be treated as hidden.
13416
13417Note that @samp{-fvisibility} does affect C++ vague linkage
13418entities. This means that, for instance, an exception class that will
13419be thrown between DSOs must be explicitly marked with default
13420visibility so that the @samp{type_info} nodes will be unified between
13421the DSOs.
13422
13423An overview of these techniques, their benefits and how to use them
13424is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
13425
13426@end table
13427
13428@c man end
13429
13430@node Environment Variables
13431@section Environment Variables Affecting GCC
13432@cindex environment variables
13433
13434@c man begin ENVIRONMENT
13435This section describes several environment variables that affect how GCC
13436operates. Some of them work by specifying directories or prefixes to use
13437when searching for various kinds of files. Some are used to specify other
13438aspects of the compilation environment.
13439
13440Note that you can also specify places to search using options such as
13441@option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
13442take precedence over places specified using environment variables, which
13443in turn take precedence over those specified by the configuration of GCC@.
13444@xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
13445GNU Compiler Collection (GCC) Internals}.
13446
13447@table @env
13448@item LANG
13449@itemx LC_CTYPE
13450@c @itemx LC_COLLATE
13451@itemx LC_MESSAGES
13452@c @itemx LC_MONETARY
13453@c @itemx LC_NUMERIC
13454@c @itemx LC_TIME
13455@itemx LC_ALL
13456@findex LANG
13457@findex LC_CTYPE
13458@c @findex LC_COLLATE
13459@findex LC_MESSAGES
13460@c @findex LC_MONETARY
13461@c @findex LC_NUMERIC
13462@c @findex LC_TIME
13463@findex LC_ALL
13464@cindex locale
13465These environment variables control the way that GCC uses
13466localization information that allow GCC to work with different
13467national conventions. GCC inspects the locale categories
13468@env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
13469so. These locale categories can be set to any value supported by your
13470installation. A typical value is @samp{en_GB.UTF-8} for English in the United
13471Kingdom encoded in UTF-8.
13472
13473The @env{LC_CTYPE} environment variable specifies character
13474classification. GCC uses it to determine the character boundaries in
13475a string; this is needed for some multibyte encodings that contain quote
13476and escape characters that would otherwise be interpreted as a string
13477end or escape.
13478
13479The @env{LC_MESSAGES} environment variable specifies the language to
13480use in diagnostic messages.
13481
13482If the @env{LC_ALL} environment variable is set, it overrides the value
13483of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
13484and @env{LC_MESSAGES} default to the value of the @env{LANG}
13485environment variable. If none of these variables are set, GCC
13486defaults to traditional C English behavior.
13487
13488@item TMPDIR
13489@findex TMPDIR
13490If @env{TMPDIR} is set, it specifies the directory to use for temporary
13491files. GCC uses temporary files to hold the output of one stage of
13492compilation which is to be used as input to the next stage: for example,
13493the output of the preprocessor, which is the input to the compiler
13494proper.
13495
13496@item GCC_EXEC_PREFIX
13497@findex GCC_EXEC_PREFIX
13498If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
13499names of the subprograms executed by the compiler. No slash is added
13500when this prefix is combined with the name of a subprogram, but you can
13501specify a prefix that ends with a slash if you wish.
13502
13503If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
13504an appropriate prefix to use based on the pathname it was invoked with.
13505
13506If GCC cannot find the subprogram using the specified prefix, it
13507tries looking in the usual places for the subprogram.
13508
13509The default value of @env{GCC_EXEC_PREFIX} is
13510@file{@var{prefix}/lib/gcc/} where @var{prefix} is the value
13511of @code{prefix} when you ran the @file{configure} script.
13512
13513Other prefixes specified with @option{-B} take precedence over this prefix.
13514
13515This prefix is also used for finding files such as @file{crt0.o} that are
13516used for linking.
13517
13518In addition, the prefix is used in an unusual way in finding the
13519directories to search for header files. For each of the standard
13520directories whose name normally begins with @samp{/usr/local/lib/gcc}
13521(more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
13522replacing that beginning with the specified prefix to produce an
13523alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
13524@file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
13525These alternate directories are searched first; the standard directories
13526come next.
13527
13528@item COMPILER_PATH
13529@findex COMPILER_PATH
13530The value of @env{COMPILER_PATH} is a colon-separated list of
13531directories, much like @env{PATH}. GCC tries the directories thus
13532specified when searching for subprograms, if it can't find the
13533subprograms using @env{GCC_EXEC_PREFIX}.
13534
13535@item LIBRARY_PATH
13536@findex LIBRARY_PATH
13537The value of @env{LIBRARY_PATH} is a colon-separated list of
13538directories, much like @env{PATH}. When configured as a native compiler,
13539GCC tries the directories thus specified when searching for special
13540linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking
13541using GCC also uses these directories when searching for ordinary
13542libraries for the @option{-l} option (but directories specified with
13543@option{-L} come first).
13544
13545@item LANG
13546@findex LANG
13547@cindex locale definition
13548This variable is used to pass locale information to the compiler. One way in
13549which this information is used is to determine the character set to be used
13550when character literals, string literals and comments are parsed in C and C++.
13551When the compiler is configured to allow multibyte characters,
13552the following values for @env{LANG} are recognized:
13553
13554@table @samp
13555@item C-JIS
13556Recognize JIS characters.
13557@item C-SJIS
13558Recognize SJIS characters.
13559@item C-EUCJP
13560Recognize EUCJP characters.
13561@end table
13562
13563If @env{LANG} is not defined, or if it has some other value, then the
13564compiler will use mblen and mbtowc as defined by the default locale to
13565recognize and translate multibyte characters.
13566@end table
13567
13568@noindent
13569Some additional environments variables affect the behavior of the
13570preprocessor.
13571
13572@include cppenv.texi
13573
13574@c man end
13575
13576@node Precompiled Headers
13577@section Using Precompiled Headers
13578@cindex precompiled headers
13579@cindex speed of compilation
13580
13581Often large projects have many header files that are included in every
13582source file. The time the compiler takes to process these header files
13583over and over again can account for nearly all of the time required to
13584build the project. To make builds faster, GCC allows users to
13585`precompile' a header file; then, if builds can use the precompiled
13586header file they will be much faster.
13587
13588To create a precompiled header file, simply compile it as you would any
13589other file, if necessary using the @option{-x} option to make the driver
13590treat it as a C or C++ header file. You will probably want to use a
13591tool like @command{make} to keep the precompiled header up-to-date when
13592the headers it contains change.
13593
13594A precompiled header file will be searched for when @code{#include} is
13595seen in the compilation. As it searches for the included file
13596(@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
13597compiler looks for a precompiled header in each directory just before it
13598looks for the include file in that directory. The name searched for is
13599the name specified in the @code{#include} with @samp{.gch} appended. If
13600the precompiled header file can't be used, it is ignored.
13601
13602For instance, if you have @code{#include "all.h"}, and you have
13603@file{all.h.gch} in the same directory as @file{all.h}, then the
13604precompiled header file will be used if possible, and the original
13605header will be used otherwise.
13606
13607Alternatively, you might decide to put the precompiled header file in a
13608directory and use @option{-I} to ensure that directory is searched
13609before (or instead of) the directory containing the original header.
13610Then, if you want to check that the precompiled header file is always
13611used, you can put a file of the same name as the original header in this
13612directory containing an @code{#error} command.
13613
13614This also works with @option{-include}. So yet another way to use
13615precompiled headers, good for projects not designed with precompiled
13616header files in mind, is to simply take most of the header files used by
13617a project, include them from another header file, precompile that header
13618file, and @option{-include} the precompiled header. If the header files
13619have guards against multiple inclusion, they will be skipped because
13620they've already been included (in the precompiled header).
13621
13622If you need to precompile the same header file for different
13623languages, targets, or compiler options, you can instead make a
13624@emph{directory} named like @file{all.h.gch}, and put each precompiled
13625header in the directory, perhaps using @option{-o}. It doesn't matter
13626what you call the files in the directory, every precompiled header in
13627the directory will be considered. The first precompiled header
13628encountered in the directory that is valid for this compilation will
13629be used; they're searched in no particular order.
13630
13631There are many other possibilities, limited only by your imagination,
13632good sense, and the constraints of your build system.
13633
13634A precompiled header file can be used only when these conditions apply:
13635
13636@itemize
13637@item
13638Only one precompiled header can be used in a particular compilation.
13639
13640@item
13641A precompiled header can't be used once the first C token is seen. You
13642can have preprocessor directives before a precompiled header; you can
13643even include a precompiled header from inside another header, so long as
13644there are no C tokens before the @code{#include}.
13645
13646@item
13647The precompiled header file must be produced for the same language as
13648the current compilation. You can't use a C precompiled header for a C++
13649compilation.
13650
13651@item
13652The precompiled header file must have been produced by the same compiler
13653binary as the current compilation is using.
13654
13655@item
13656Any macros defined before the precompiled header is included must
13657either be defined in the same way as when the precompiled header was
13658generated, or must not affect the precompiled header, which usually
13659means that they don't appear in the precompiled header at all.
13660
13661The @option{-D} option is one way to define a macro before a
13662precompiled header is included; using a @code{#define} can also do it.
13663There are also some options that define macros implicitly, like
13664@option{-O} and @option{-Wdeprecated}; the same rule applies to macros
13665defined this way.
13666
13667@item If debugging information is output when using the precompiled
13668header, using @option{-g} or similar, the same kind of debugging information
13669must have been output when building the precompiled header. However,
13670a precompiled header built using @option{-g} can be used in a compilation
13671when no debugging information is being output.
13672
13673@item The same @option{-m} options must generally be used when building
13674and using the precompiled header. @xref{Submodel Options},
13675for any cases where this rule is relaxed.
13676
13677@item Each of the following options must be the same when building and using
13678the precompiled header:
13679
13680@gccoptlist{-fexceptions -funit-at-a-time}
13681
13682@item
13683Some other command-line options starting with @option{-f},
13684@option{-p}, or @option{-O} must be defined in the same way as when
13685the precompiled header was generated. At present, it's not clear
13686which options are safe to change and which are not; the safest choice
13687is to use exactly the same options when generating and using the
13688precompiled header. The following are known to be safe:
13689
13690@gccoptlist{-fmessage-length= -fpreprocessed
13691-fsched-interblock -fsched-spec -fsched-spec-load -fsched-spec-load-dangerous
13692-fsched-verbose=<number> -fschedule-insns -fvisibility=
13693-pedantic-errors}
13694
13695@end itemize
13696
13697For all of these except the last, the compiler will automatically
13698ignore the precompiled header if the conditions aren't met. If you
13699find an option combination that doesn't work and doesn't cause the
13700precompiled header to be ignored, please consider filing a bug report,
13701see @ref{Bugs}.
13702
13703If you do use differing options when generating and using the
13704precompiled header, the actual behavior will be a mixture of the
13705behavior for the options. For instance, if you use @option{-g} to
13706generate the precompiled header but not when using it, you may or may
13707not get debugging information for routines in the precompiled header.
13708
13709@node Running Protoize
13710@section Running Protoize
13711
13712The program @code{protoize} is an optional part of GCC@. You can use
13713it to add prototypes to a program, thus converting the program to ISO
13714C in one respect. The companion program @code{unprotoize} does the
13715reverse: it removes argument types from any prototypes that are found.
13716
13717When you run these programs, you must specify a set of source files as
13718command line arguments. The conversion programs start out by compiling
13719these files to see what functions they define. The information gathered
13720about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
13721
13722After scanning comes actual conversion. The specified files are all
13723eligible to be converted; any files they include (whether sources or
13724just headers) are eligible as well.
13725
13726But not all the eligible files are converted. By default,
13727@code{protoize} and @code{unprotoize} convert only source and header
13728files in the current directory. You can specify additional directories
13729whose files should be converted with the @option{-d @var{directory}}
13730option. You can also specify particular files to exclude with the
13731@option{-x @var{file}} option. A file is converted if it is eligible, its
13732directory name matches one of the specified directory names, and its
13733name within the directory has not been excluded.
13734
13735Basic conversion with @code{protoize} consists of rewriting most
13736function definitions and function declarations to specify the types of
13737the arguments. The only ones not rewritten are those for varargs
13738functions.
13739
13740@code{protoize} optionally inserts prototype declarations at the
13741beginning of the source file, to make them available for any calls that
13742precede the function's definition. Or it can insert prototype
13743declarations with block scope in the blocks where undeclared functions
13744are called.
13745
13746Basic conversion with @code{unprotoize} consists of rewriting most
13747function declarations to remove any argument types, and rewriting
13748function definitions to the old-style pre-ISO form.
13749
13750Both conversion programs print a warning for any function declaration or
13751definition that they can't convert. You can suppress these warnings
13752with @option{-q}.
13753
13754The output from @code{protoize} or @code{unprotoize} replaces the
13755original source file. The original file is renamed to a name ending
13756with @samp{.save} (for DOS, the saved filename ends in @samp{.sav}
13757without the original @samp{.c} suffix). If the @samp{.save} (@samp{.sav}
13758for DOS) file already exists, then the source file is simply discarded.
13759
13760@code{protoize} and @code{unprotoize} both depend on GCC itself to
13761scan the program and collect information about the functions it uses.
13762So neither of these programs will work until GCC is installed.
13763
13764Here is a table of the options you can use with @code{protoize} and
13765@code{unprotoize}. Each option works with both programs unless
13766otherwise stated.
13767
13768@table @code
13769@item -B @var{directory}
13770Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
13771usual directory (normally @file{/usr/local/lib}). This file contains
13772prototype information about standard system functions. This option
13773applies only to @code{protoize}.
13774
13775@item -c @var{compilation-options}
13776Use @var{compilation-options} as the options when running @command{gcc} to
13777produce the @samp{.X} files. The special option @option{-aux-info} is
13778always passed in addition, to tell @command{gcc} to write a @samp{.X} file.
13779
13780Note that the compilation options must be given as a single argument to
13781@code{protoize} or @code{unprotoize}. If you want to specify several
13782@command{gcc} options, you must quote the entire set of compilation options
13783to make them a single word in the shell.
13784
13785There are certain @command{gcc} arguments that you cannot use, because they
13786would produce the wrong kind of output. These include @option{-g},
13787@option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in
13788the @var{compilation-options}, they are ignored.
13789
13790@item -C
13791Rename files to end in @samp{.C} (@samp{.cc} for DOS-based file
13792systems) instead of @samp{.c}. This is convenient if you are converting
13793a C program to C++. This option applies only to @code{protoize}.
13794
13795@item -g
13796Add explicit global declarations. This means inserting explicit
13797declarations at the beginning of each source file for each function
13798that is called in the file and was not declared. These declarations
13799precede the first function definition that contains a call to an
13800undeclared function. This option applies only to @code{protoize}.
13801
13802@item -i @var{string}
13803Indent old-style parameter declarations with the string @var{string}.
13804This option applies only to @code{protoize}.
13805
13806@code{unprotoize} converts prototyped function definitions to old-style
13807function definitions, where the arguments are declared between the
13808argument list and the initial @samp{@{}. By default, @code{unprotoize}
13809uses five spaces as the indentation. If you want to indent with just
13810one space instead, use @option{-i " "}.
13811
13812@item -k
13813Keep the @samp{.X} files. Normally, they are deleted after conversion
13814is finished.
13815
13816@item -l
13817Add explicit local declarations. @code{protoize} with @option{-l} inserts
13818a prototype declaration for each function in each block which calls the
13819function without any declaration. This option applies only to
13820@code{protoize}.
13821
13822@item -n
13823Make no real changes. This mode just prints information about the conversions
13824that would have been done without @option{-n}.
13825
13826@item -N
13827Make no @samp{.save} files. The original files are simply deleted.
13828Use this option with caution.
13829
13830@item -p @var{program}
13831Use the program @var{program} as the compiler. Normally, the name
13832@file{gcc} is used.
13833
13834@item -q
13835Work quietly. Most warnings are suppressed.
13836
13837@item -v
13838Print the version number, just like @option{-v} for @command{gcc}.
13839@end table
13840
13841If you need special compiler options to compile one of your program's
13842source files, then you should generate that file's @samp{.X} file
13843specially, by running @command{gcc} on that source file with the
13844appropriate options and the option @option{-aux-info}. Then run
13845@code{protoize} on the entire set of files. @code{protoize} will use
13846the existing @samp{.X} file because it is newer than the source file.
13847For example:
13848
13849@smallexample
13850gcc -Dfoo=bar file1.c -aux-info file1.X
13851protoize *.c
13852@end smallexample
13853
13854@noindent
13855You need to include the special files along with the rest in the
13856@code{protoize} command, even though their @samp{.X} files already
13857exist, because otherwise they won't get converted.
13858
13859@xref{Protoize Caveats}, for more information on how to use
13860@code{protoize} successfully.