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* Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
128 and Objective-C++.
129* Language Independent Options:: Controlling how diagnostics should be
130 formatted.
131* Warning Options:: How picky should the compiler be?
132* Debugging Options:: Symbol tables, measurements, and debugging dumps.
133* Optimize Options:: How much optimization?
134* Preprocessor Options:: Controlling header files and macro definitions.
135 Also, getting dependency information for Make.
136* Assembler Options:: Passing options to the assembler.
137* Link Options:: Specifying libraries and so on.
138* Directory Options:: Where to find header files and libraries.
139 Where to find the compiler executable files.
140* Spec Files:: How to pass switches to sub-processes.
141* Target Options:: Running a cross-compiler, or an old version of GCC.
142* Submodel Options:: Specifying minor hardware or convention variations,
143 such as 68010 vs 68020.
144* Code Gen Options:: Specifying conventions for function calls, data layout
145 and register usage.
146* Environment Variables:: Env vars that affect GCC.
147* Precompiled Headers:: Compiling a header once, and using it many times.
148* Running Protoize:: Automatically adding or removing function prototypes.
149@end menu
150
151@c man begin OPTIONS
152
153@node Option Summary
154@section Option Summary
155
156Here is a summary of all the options, grouped by type. Explanations are
157in the following sections.
158
159@table @emph
160@item Overall Options
161@xref{Overall Options,,Options Controlling the Kind of Output}.
162@gccoptlist{-c -S -E -o @var{file} -combine -pipe -pass-exit-codes @gol
163-x @var{language} -v -### --help --target-help --version @@@var{file}}
164
165@item C Language Options
166@xref{C Dialect Options,,Options Controlling C Dialect}.
167@gccoptlist{-ansi -std=@var{standard} -fgnu89-inline @gol
168-aux-info @var{filename} @gol
169-fno-asm -fno-builtin -fno-builtin-@var{function} @gol
170-fhosted -ffreestanding -fopenmp -fms-extensions @gol
171-trigraphs -no-integrated-cpp -traditional -traditional-cpp @gol
172-fallow-single-precision -fcond-mismatch @gol
173-fsigned-bitfields -fsigned-char @gol
174-funsigned-bitfields -funsigned-char}
175
176@item C++ Language Options
177@xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
178@gccoptlist{-fabi-version=@var{n} -fno-access-control -fcheck-new @gol
179-fconserve-space -ffriend-injection @gol
180-fno-elide-constructors @gol
181-fno-enforce-eh-specs @gol
182-ffor-scope -fno-for-scope -fno-gnu-keywords @gol
183-fno-implicit-templates @gol
184-fno-implicit-inline-templates @gol
185-fno-implement-inlines -fms-extensions @gol
186-fno-nonansi-builtins -fno-operator-names @gol
187-fno-optional-diags -fpermissive @gol
188-frepo -fno-rtti -fstats -ftemplate-depth-@var{n} @gol
189-fno-threadsafe-statics -fuse-cxa-atexit -fno-weak -nostdinc++ @gol
190-fno-default-inline -fvisibility-inlines-hidden @gol
191-Wabi -Wctor-dtor-privacy @gol
192-Wnon-virtual-dtor -Wreorder @gol
193-Weffc++ -Wno-deprecated -Wstrict-null-sentinel @gol
194-Wno-non-template-friend -Wold-style-cast @gol
195-Woverloaded-virtual -Wno-pmf-conversions @gol
196-Wsign-promo}
197
198@item Objective-C and Objective-C++ Language Options
199@xref{Objective-C and Objective-C++ Dialect Options,,Options Controlling
200Objective-C and Objective-C++ Dialects}.
201@gccoptlist{-fconstant-string-class=@var{class-name} @gol
202-fgnu-runtime -fnext-runtime @gol
203-fno-nil-receivers @gol
204-fobjc-call-cxx-cdtors @gol
205-fobjc-direct-dispatch @gol
206-fobjc-exceptions @gol
207-fobjc-gc @gol
208-freplace-objc-classes @gol
209-fzero-link @gol
210-gen-decls @gol
211-Wassign-intercept @gol
212-Wno-protocol -Wselector @gol
213-Wstrict-selector-match @gol
214-Wundeclared-selector}
215
216@item Language Independent Options
217@xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}.
218@gccoptlist{-fmessage-length=@var{n} @gol
219-fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]} @gol
220-fdiagnostics-show-option}
221
222@item Warning Options
223@xref{Warning Options,,Options to Request or Suppress Warnings}.
224@gccoptlist{-fsyntax-only -pedantic -pedantic-errors @gol
225-w -Wextra -Wall -Waddress -Waggregate-return -Wno-attributes @gol
226-Wc++-compat -Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment @gol
227-Wconversion -Wno-deprecated-declarations @gol
228-Wdisabled-optimization -Wno-div-by-zero -Wno-endif-labels @gol
229-Werror -Werror=* -Werror-implicit-function-declaration @gol
230-Wfatal-errors -Wfloat-equal -Wformat -Wformat=2 @gol
231-Wno-format-extra-args -Wformat-nonliteral @gol
232-Wformat-security -Wformat-y2k @gol
233-Wimplicit -Wimplicit-function-declaration -Wimplicit-int @gol
234-Wimport -Wno-import -Winit-self -Winline @gol
235-Wno-int-to-pointer-cast @gol
236-Wno-invalid-offsetof -Winvalid-pch @gol
237-Wlarger-than-@var{len} -Wunsafe-loop-optimizations -Wlong-long @gol
238-Wmain -Wmissing-braces -Wmissing-field-initializers @gol
239-Wmissing-format-attribute -Wmissing-include-dirs @gol
240-Wmissing-noreturn @gol
241-Wno-multichar -Wnonnull -Wno-overflow @gol
242-Woverlength-strings -Wpacked -Wpadded @gol
243-Wparentheses -Wpointer-arith -Wno-pointer-to-int-cast @gol
244-Wredundant-decls @gol
245-Wreturn-type -Wsequence-point -Wshadow @gol
246-Wsign-compare -Wstack-protector @gol
247-Wstrict-aliasing -Wstrict-aliasing=2 @gol
248-Wstrict-overflow -Wstrict-overflow=@var{n} @gol
249-Wswitch -Wswitch-default -Wswitch-enum @gol
250-Wsystem-headers -Wtrigraphs -Wundef -Wuninitialized @gol
251-Wunknown-pragmas -Wno-pragmas -Wunreachable-code @gol
252-Wunused -Wunused-function -Wunused-label -Wunused-parameter @gol
253-Wunused-value -Wunused-variable -Wvariadic-macros @gol
254-Wvolatile-register-var -Wwrite-strings}
255
256@item C-only Warning Options
257@gccoptlist{-Wbad-function-cast -Wmissing-declarations @gol
258-Wmissing-prototypes -Wnested-externs -Wold-style-definition @gol
259-Wstrict-prototypes -Wtraditional @gol
260-Wdeclaration-after-statement -Wpointer-sign}
261
262@item Debugging Options
263@xref{Debugging Options,,Options for Debugging Your Program or GCC}.
264@gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
265-fdump-noaddr -fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} @gol
266-fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
267-fdump-ipa-all -fdump-ipa-cgraph @gol
268-fdump-tree-all @gol
269-fdump-tree-original@r{[}-@var{n}@r{]} @gol
270-fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
271-fdump-tree-inlined@r{[}-@var{n}@r{]} @gol
272-fdump-tree-cfg -fdump-tree-vcg -fdump-tree-alias @gol
273-fdump-tree-ch @gol
274-fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol
275-fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol
276-fdump-tree-gimple@r{[}-raw@r{]} -fdump-tree-mudflap@r{[}-@var{n}@r{]} @gol
277-fdump-tree-dom@r{[}-@var{n}@r{]} @gol
278-fdump-tree-dse@r{[}-@var{n}@r{]} @gol
279-fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol
280-fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
281-fdump-tree-copyrename@r{[}-@var{n}@r{]} @gol
282-fdump-tree-nrv -fdump-tree-vect @gol
283-fdump-tree-sink @gol
284-fdump-tree-sra@r{[}-@var{n}@r{]} @gol
285-fdump-tree-salias @gol
286-fdump-tree-fre@r{[}-@var{n}@r{]} @gol
287-fdump-tree-vrp@r{[}-@var{n}@r{]} @gol
288-ftree-vectorizer-verbose=@var{n} @gol
289-fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol
290-feliminate-dwarf2-dups -feliminate-unused-debug-types @gol
291-feliminate-unused-debug-symbols -femit-class-debug-always @gol
292-fmem-report -fprofile-arcs @gol
293-frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
294-ftest-coverage -ftime-report -fvar-tracking @gol
295-g -g@var{level} -gcoff -gdwarf-2 @gol
296-ggdb -gstabs -gstabs+ -gvms -gxcoff -gxcoff+ @gol
297-p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol
298-print-multi-directory -print-multi-lib @gol
299-print-prog-name=@var{program} -print-search-dirs -Q @gol
300-save-temps -time}
301
302@item Optimization Options
303@xref{Optimize Options,,Options that Control Optimization}.
304@gccoptlist{-falign-functions=@var{n} -falign-jumps=@var{n} @gol
305-falign-labels=@var{n} -falign-loops=@var{n} @gol
306-fbounds-check -fmudflap -fmudflapth -fmudflapir @gol
307-fbranch-probabilities -fprofile-values -fvpt -fbranch-target-load-optimize @gol
308-fbranch-target-load-optimize2 -fbtr-bb-exclusive @gol
309-fcaller-saves -fcprop-registers -fcse-follow-jumps @gol
310-fcse-skip-blocks -fcx-limited-range -fdata-sections @gol
311-fdelayed-branch -fdelete-null-pointer-checks -fearly-inlining @gol
312-fexpensive-optimizations -ffast-math -ffloat-store @gol
313-fforce-addr -ffunction-sections @gol
314-fgcse -fgcse-lm -fgcse-sm -fgcse-las -fgcse-after-reload @gol
315-fcrossjumping -fif-conversion -fif-conversion2 @gol
316-finline-functions -finline-functions-called-once @gol
317-finline-limit=@var{n} -fkeep-inline-functions @gol
318-fkeep-static-consts -fmerge-constants -fmerge-all-constants @gol
319-fmodulo-sched -fno-branch-count-reg @gol
320-fno-default-inline -fno-defer-pop -fmove-loop-invariants @gol
321-fno-function-cse -fno-guess-branch-probability @gol
322-fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol
323-funsafe-math-optimizations -funsafe-loop-optimizations -ffinite-math-only @gol
324-fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol
325-fomit-frame-pointer -foptimize-register-move @gol
326-foptimize-sibling-calls -fprefetch-loop-arrays @gol
327-fprofile-generate -fprofile-use @gol
328-fregmove -frename-registers @gol
329-freorder-blocks -freorder-blocks-and-partition -freorder-functions @gol
330-frerun-cse-after-loop @gol
331-frounding-math -frtl-abstract-sequences @gol
332-fschedule-insns -fschedule-insns2 @gol
333-fno-sched-interblock -fno-sched-spec -fsched-spec-load @gol
334-fsched-spec-load-dangerous @gol
335-fsched-stalled-insns=@var{n} -fsched-stalled-insns-dep=@var{n} @gol
336-fsched2-use-superblocks @gol
337-fsched2-use-traces -fsee -freschedule-modulo-scheduled-loops @gol
338-fsection-anchors -fsignaling-nans -fsingle-precision-constant @gol
339-fstack-protector -fstack-protector-all @gol
340-fstrict-aliasing -fstrict-overflow -ftracer -fthread-jumps @gol
341-funroll-all-loops -funroll-loops -fpeel-loops @gol
342-fsplit-ivs-in-unroller -funswitch-loops @gol
343-fvariable-expansion-in-unroller @gol
344-ftree-pre -ftree-ccp -ftree-dce -ftree-loop-optimize @gol
345-ftree-loop-linear -ftree-loop-im -ftree-loop-ivcanon -fivopts @gol
346-ftree-dominator-opts -ftree-dse -ftree-copyrename -ftree-sink @gol
347-ftree-ch -ftree-sra -ftree-ter -ftree-lrs -ftree-fre -ftree-vectorize @gol
348-ftree-vect-loop-version -ftree-salias -fipa-pta -fweb @gol
349-ftree-copy-prop -ftree-store-ccp -ftree-store-copy-prop -fwhole-program @gol
350--param @var{name}=@var{value}
351-O -O0 -O1 -O2 -O3 -Os}
352
353@item Preprocessor Options
354@xref{Preprocessor Options,,Options Controlling the Preprocessor}.
355@gccoptlist{-A@var{question}=@var{answer} @gol
356-A-@var{question}@r{[}=@var{answer}@r{]} @gol
357-C -dD -dI -dM -dN @gol
358-D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol
359-idirafter @var{dir} @gol
360-include @var{file} -imacros @var{file} @gol
361-iprefix @var{file} -iwithprefix @var{dir} @gol
362-iwithprefixbefore @var{dir} -isystem @var{dir} @gol
363-imultilib @var{dir} -isysroot @var{dir} @gol
364-M -MM -MF -MG -MP -MQ -MT -nostdinc @gol
365-P -fworking-directory -remap @gol
366-trigraphs -undef -U@var{macro} -Wp,@var{option} @gol
367-Xpreprocessor @var{option}}
368
369@item Assembler Option
370@xref{Assembler Options,,Passing Options to the Assembler}.
371@gccoptlist{-Wa,@var{option} -Xassembler @var{option}}
372
373@item Linker Options
374@xref{Link Options,,Options for Linking}.
375@gccoptlist{@var{object-file-name} -l@var{library} @gol
376-nostartfiles -nodefaultlibs -nostdlib -pie -rdynamic @gol
377-s -static -static-libgcc -shared -shared-libgcc -symbolic @gol
378-Wl,@var{option} -Xlinker @var{option} @gol
379-u @var{symbol}}
380
381@item Directory Options
382@xref{Directory Options,,Options for Directory Search}.
383@gccoptlist{-B@var{prefix} -I@var{dir} -iquote@var{dir} -L@var{dir}
384-specs=@var{file} -I- --sysroot=@var{dir}}
385
386@item Target Options
387@c I wrote this xref this way to avoid overfull hbox. -- rms
388@xref{Target Options}.
389@gccoptlist{-V @var{version} -b @var{machine}}
390
391@item Machine Dependent Options
392@xref{Submodel Options,,Hardware Models and Configurations}.
393@c This list is ordered alphanumerically by subsection name.
394@c Try and put the significant identifier (CPU or system) first,
395@c so users have a clue at guessing where the ones they want will be.
396
397@emph{ARC Options}
398@gccoptlist{-EB -EL @gol
399-mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text-section} @gol
400-mdata=@var{data-section} -mrodata=@var{readonly-data-section}}
401
402@emph{ARM Options}
403@gccoptlist{-mapcs-frame -mno-apcs-frame @gol
404-mabi=@var{name} @gol
405-mapcs-stack-check -mno-apcs-stack-check @gol
406-mapcs-float -mno-apcs-float @gol
407-mapcs-reentrant -mno-apcs-reentrant @gol
408-msched-prolog -mno-sched-prolog @gol
409-mlittle-endian -mbig-endian -mwords-little-endian @gol
410-mfloat-abi=@var{name} -msoft-float -mhard-float -mfpe @gol
411-mthumb-interwork -mno-thumb-interwork @gol
412-mcpu=@var{name} -march=@var{name} -mfpu=@var{name} @gol
413-mstructure-size-boundary=@var{n} @gol
414-mabort-on-noreturn @gol
415-mlong-calls -mno-long-calls @gol
416-msingle-pic-base -mno-single-pic-base @gol
417-mpic-register=@var{reg} @gol
418-mnop-fun-dllimport @gol
419-mcirrus-fix-invalid-insns -mno-cirrus-fix-invalid-insns @gol
420-mpoke-function-name @gol
421-mthumb -marm @gol
422-mtpcs-frame -mtpcs-leaf-frame @gol
423-mcaller-super-interworking -mcallee-super-interworking @gol
424-mtp=@var{name}}
425
426@emph{AVR Options}
427@gccoptlist{-mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts @gol
428-mcall-prologues -mno-tablejump -mtiny-stack -mint8}
429
430@emph{Blackfin Options}
431@gccoptlist{-momit-leaf-frame-pointer -mno-omit-leaf-frame-pointer @gol
432-mspecld-anomaly -mno-specld-anomaly -mcsync-anomaly -mno-csync-anomaly @gol
433-mlow-64k -mno-low64k -mid-shared-library @gol
434-mno-id-shared-library -mshared-library-id=@var{n} @gol
435-mlong-calls -mno-long-calls}
436
437@emph{CRIS Options}
438@gccoptlist{-mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol
439-mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol
440-metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol
441-mstack-align -mdata-align -mconst-align @gol
442-m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol
443-melf -maout -melinux -mlinux -sim -sim2 @gol
444-mmul-bug-workaround -mno-mul-bug-workaround}
445
446@emph{CRX Options}
447@gccoptlist{-mmac -mpush-args}
448
449@emph{Darwin Options}
450@gccoptlist{-all_load -allowable_client -arch -arch_errors_fatal @gol
451-arch_only -bind_at_load -bundle -bundle_loader @gol
452-client_name -compatibility_version -current_version @gol
453-dead_strip @gol
454-dependency-file -dylib_file -dylinker_install_name @gol
455-dynamic -dynamiclib -exported_symbols_list @gol
456-filelist -flat_namespace -force_cpusubtype_ALL @gol
457-force_flat_namespace -headerpad_max_install_names @gol
458-image_base -init -install_name -keep_private_externs @gol
459-multi_module -multiply_defined -multiply_defined_unused @gol
460-noall_load -no_dead_strip_inits_and_terms @gol
461-nofixprebinding -nomultidefs -noprebind -noseglinkedit @gol
462-pagezero_size -prebind -prebind_all_twolevel_modules @gol
463-private_bundle -read_only_relocs -sectalign @gol
464-sectobjectsymbols -whyload -seg1addr @gol
465-sectcreate -sectobjectsymbols -sectorder @gol
466-segaddr -segs_read_only_addr -segs_read_write_addr @gol
467-seg_addr_table -seg_addr_table_filename -seglinkedit @gol
468-segprot -segs_read_only_addr -segs_read_write_addr @gol
469-single_module -static -sub_library -sub_umbrella @gol
470-twolevel_namespace -umbrella -undefined @gol
471-unexported_symbols_list -weak_reference_mismatches @gol
472-whatsloaded -F -gused -gfull -mmacosx-version-min=@var{version} @gol
473-mkernel -mone-byte-bool}
474
475@emph{DEC Alpha Options}
476@gccoptlist{-mno-fp-regs -msoft-float -malpha-as -mgas @gol
477-mieee -mieee-with-inexact -mieee-conformant @gol
478-mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} @gol
479-mtrap-precision=@var{mode} -mbuild-constants @gol
480-mcpu=@var{cpu-type} -mtune=@var{cpu-type} @gol
481-mbwx -mmax -mfix -mcix @gol
482-mfloat-vax -mfloat-ieee @gol
483-mexplicit-relocs -msmall-data -mlarge-data @gol
484-msmall-text -mlarge-text @gol
485-mmemory-latency=@var{time}}
486
487@emph{DEC Alpha/VMS Options}
488@gccoptlist{-mvms-return-codes}
489
490@emph{FRV Options}
491@gccoptlist{-mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 @gol
492-mhard-float -msoft-float @gol
493-malloc-cc -mfixed-cc -mdword -mno-dword @gol
494-mdouble -mno-double @gol
495-mmedia -mno-media -mmuladd -mno-muladd @gol
496-mfdpic -minline-plt -mgprel-ro -multilib-library-pic @gol
497-mlinked-fp -mlong-calls -malign-labels @gol
498-mlibrary-pic -macc-4 -macc-8 @gol
499-mpack -mno-pack -mno-eflags -mcond-move -mno-cond-move @gol
500-moptimize-membar -mno-optimize-membar @gol
501-mscc -mno-scc -mcond-exec -mno-cond-exec @gol
502-mvliw-branch -mno-vliw-branch @gol
503-mmulti-cond-exec -mno-multi-cond-exec -mnested-cond-exec @gol
504-mno-nested-cond-exec -mtomcat-stats @gol
505-mTLS -mtls @gol
506-mcpu=@var{cpu}}
507
508@emph{GNU/Linux Options}
509@gccoptlist{-muclibc}
510
511@emph{H8/300 Options}
512@gccoptlist{-mrelax -mh -ms -mn -mint32 -malign-300}
513
514@emph{HPPA Options}
515@gccoptlist{-march=@var{architecture-type} @gol
516-mbig-switch -mdisable-fpregs -mdisable-indexing @gol
517-mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol
518-mfixed-range=@var{register-range} @gol
519-mjump-in-delay -mlinker-opt -mlong-calls @gol
520-mlong-load-store -mno-big-switch -mno-disable-fpregs @gol
521-mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol
522-mno-jump-in-delay -mno-long-load-store @gol
523-mno-portable-runtime -mno-soft-float @gol
524-mno-space-regs -msoft-float -mpa-risc-1-0 @gol
525-mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime @gol
526-mschedule=@var{cpu-type} -mspace-regs -msio -mwsio @gol
527-munix=@var{unix-std} -nolibdld -static -threads}
528
529@emph{i386 and x86-64 Options}
530@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
531-mfpmath=@var{unit} @gol
532-masm=@var{dialect} -mno-fancy-math-387 @gol
533-mno-fp-ret-in-387 -msoft-float -msvr3-shlib @gol
534-mno-wide-multiply -mrtd -malign-double @gol
535-mpreferred-stack-boundary=@var{num} @gol
536-mmmx -msse -msse2 -msse3 -m3dnow @gol
537-mthreads -mno-align-stringops -minline-all-stringops @gol
538-mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol
539-m96bit-long-double -mregparm=@var{num} -msseregparm @gol
540-mstackrealign @gol
541-momit-leaf-frame-pointer -mno-red-zone -mno-tls-direct-seg-refs @gol
542-mcmodel=@var{code-model} @gol
543-m32 -m64 -mlarge-data-threshold=@var{num}}
544
545@emph{IA-64 Options}
546@gccoptlist{-mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol
547-mvolatile-asm-stop -mregister-names -mno-sdata @gol
548-mconstant-gp -mauto-pic -minline-float-divide-min-latency @gol
549-minline-float-divide-max-throughput @gol
550-minline-int-divide-min-latency @gol
551-minline-int-divide-max-throughput @gol
552-minline-sqrt-min-latency -minline-sqrt-max-throughput @gol
553-mno-dwarf2-asm -mearly-stop-bits @gol
554-mfixed-range=@var{register-range} -mtls-size=@var{tls-size} @gol
555-mtune=@var{cpu-type} -mt -pthread -milp32 -mlp64 @gol
556-mno-sched-br-data-spec -msched-ar-data-spec -mno-sched-control-spec @gol
557-msched-br-in-data-spec -msched-ar-in-data-spec -msched-in-control-spec @gol
558-msched-ldc -mno-sched-control-ldc -mno-sched-spec-verbose @gol
559-mno-sched-prefer-non-data-spec-insns @gol
560-mno-sched-prefer-non-control-spec-insns @gol
561-mno-sched-count-spec-in-critical-path}
562
563@emph{M32R/D Options}
564@gccoptlist{-m32r2 -m32rx -m32r @gol
565-mdebug @gol
566-malign-loops -mno-align-loops @gol
567-missue-rate=@var{number} @gol
568-mbranch-cost=@var{number} @gol
569-mmodel=@var{code-size-model-type} @gol
570-msdata=@var{sdata-type} @gol
571-mno-flush-func -mflush-func=@var{name} @gol
572-mno-flush-trap -mflush-trap=@var{number} @gol
573-G @var{num}}
574
575@emph{M32C Options}
576@gccoptlist{-mcpu=@var{cpu} -msim -memregs=@var{number}}
577
578@emph{M680x0 Options}
579@gccoptlist{-m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol
580-m68060 -mcpu32 -m5200 -mcfv4e -m68881 -mbitfield @gol
581-mc68000 -mc68020 @gol
582-mnobitfield -mrtd -mshort -msoft-float -mpcrel @gol
583-malign-int -mstrict-align -msep-data -mno-sep-data @gol
584-mshared-library-id=n -mid-shared-library -mno-id-shared-library}
585
586@emph{M68hc1x Options}
587@gccoptlist{-m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 @gol
588-mauto-incdec -minmax -mlong-calls -mshort @gol
589-msoft-reg-count=@var{count}}
590
591@emph{MCore Options}
592@gccoptlist{-mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol
593-mno-relax-immediates -mwide-bitfields -mno-wide-bitfields @gol
594-m4byte-functions -mno-4byte-functions -mcallgraph-data @gol
595-mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim @gol
596-mlittle-endian -mbig-endian -m210 -m340 -mstack-increment}
597
598@emph{MIPS Options}
599@gccoptlist{-EL -EB -march=@var{arch} -mtune=@var{arch} @gol
600-mips1 -mips2 -mips3 -mips4 -mips32 -mips32r2 -mips64 @gol
601-mips16 -mno-mips16 -mabi=@var{abi} -mabicalls -mno-abicalls @gol
602-mshared -mno-shared -mxgot -mno-xgot -mgp32 -mgp64 @gol
603-mfp32 -mfp64 -mhard-float -msoft-float @gol
604-msingle-float -mdouble-float -mdsp -mpaired-single -mips3d @gol
605-mlong64 -mlong32 -msym32 -mno-sym32 @gol
606-G@var{num} -membedded-data -mno-embedded-data @gol
607-muninit-const-in-rodata -mno-uninit-const-in-rodata @gol
608-msplit-addresses -mno-split-addresses @gol
609-mexplicit-relocs -mno-explicit-relocs @gol
610-mcheck-zero-division -mno-check-zero-division @gol
611-mdivide-traps -mdivide-breaks @gol
612-mmemcpy -mno-memcpy -mlong-calls -mno-long-calls @gol
613-mmad -mno-mad -mfused-madd -mno-fused-madd -nocpp @gol
614-mfix-r4000 -mno-fix-r4000 -mfix-r4400 -mno-fix-r4400 @gol
615-mfix-vr4120 -mno-fix-vr4120 -mfix-vr4130 @gol
616-mfix-sb1 -mno-fix-sb1 @gol
617-mflush-func=@var{func} -mno-flush-func @gol
618-mbranch-likely -mno-branch-likely @gol
619-mfp-exceptions -mno-fp-exceptions @gol
620-mvr4130-align -mno-vr4130-align}
621
622@emph{MMIX Options}
623@gccoptlist{-mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol
624-mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol
625-melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol
626-mno-base-addresses -msingle-exit -mno-single-exit}
627
628@emph{MN10300 Options}
629@gccoptlist{-mmult-bug -mno-mult-bug @gol
630-mam33 -mno-am33 @gol
631-mam33-2 -mno-am33-2 @gol
632-mreturn-pointer-on-d0 @gol
633-mno-crt0 -mrelax}
634
635@emph{MT Options}
636@gccoptlist{-mno-crt0 -mbacc -msim @gol
637-march=@var{cpu-type} }
638
639@emph{PDP-11 Options}
640@gccoptlist{-mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol
641-mbcopy -mbcopy-builtin -mint32 -mno-int16 @gol
642-mint16 -mno-int32 -mfloat32 -mno-float64 @gol
643-mfloat64 -mno-float32 -mabshi -mno-abshi @gol
644-mbranch-expensive -mbranch-cheap @gol
645-msplit -mno-split -munix-asm -mdec-asm}
646
647@emph{PowerPC Options}
648See RS/6000 and PowerPC Options.
649
650@emph{RS/6000 and PowerPC Options}
651@gccoptlist{-mcpu=@var{cpu-type} @gol
652-mtune=@var{cpu-type} @gol
653-mpower -mno-power -mpower2 -mno-power2 @gol
654-mpowerpc -mpowerpc64 -mno-powerpc @gol
655-maltivec -mno-altivec @gol
656-mpowerpc-gpopt -mno-powerpc-gpopt @gol
657-mpowerpc-gfxopt -mno-powerpc-gfxopt @gol
658-mmfcrf -mno-mfcrf -mpopcntb -mno-popcntb -mfprnd -mno-fprnd @gol
659-mnew-mnemonics -mold-mnemonics @gol
660-mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc @gol
661-m64 -m32 -mxl-compat -mno-xl-compat -mpe @gol
662-malign-power -malign-natural @gol
663-msoft-float -mhard-float -mmultiple -mno-multiple @gol
664-mstring -mno-string -mupdate -mno-update @gol
665-mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol
666-mstrict-align -mno-strict-align -mrelocatable @gol
667-mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol
668-mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol
669-mdynamic-no-pic -maltivec -mswdiv @gol
670-mprioritize-restricted-insns=@var{priority} @gol
671-msched-costly-dep=@var{dependence_type} @gol
672-minsert-sched-nops=@var{scheme} @gol
673-mcall-sysv -mcall-netbsd @gol
674-maix-struct-return -msvr4-struct-return @gol
675-mabi=@var{abi-type} -msecure-plt -mbss-plt @gol
676-misel -mno-isel @gol
677-misel=yes -misel=no @gol
678-mspe -mno-spe @gol
679-mspe=yes -mspe=no @gol
680-mvrsave -mno-vrsave @gol
681-mmulhw -mno-mulhw @gol
682-mdlmzb -mno-dlmzb @gol
683-mfloat-gprs=yes -mfloat-gprs=no -mfloat-gprs=single -mfloat-gprs=double @gol
684-mprototype -mno-prototype @gol
685-msim -mmvme -mads -myellowknife -memb -msdata @gol
686-msdata=@var{opt} -mvxworks -mwindiss -G @var{num} -pthread}
687
688@emph{S/390 and zSeries Options}
689@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
690-mhard-float -msoft-float -mlong-double-64 -mlong-double-128 @gol
691-mbackchain -mno-backchain -mpacked-stack -mno-packed-stack @gol
692-msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol
693-m64 -m31 -mdebug -mno-debug -mesa -mzarch @gol
694-mtpf-trace -mno-tpf-trace -mfused-madd -mno-fused-madd @gol
695-mwarn-framesize -mwarn-dynamicstack -mstack-size -mstack-guard}
696
697@emph{Score Options}
698@gccoptlist{-meb -mel @gol
699-mnhwloop @gol
700-muls @gol
701-mmac @gol
702-mscore5 -mscore5u -mscore7 -mscore7d}
703
704@emph{SH Options}
705@gccoptlist{-m1 -m2 -m2e -m3 -m3e @gol
706-m4-nofpu -m4-single-only -m4-single -m4 @gol
707-m4a-nofpu -m4a-single-only -m4a-single -m4a -m4al @gol
708-m5-64media -m5-64media-nofpu @gol
709-m5-32media -m5-32media-nofpu @gol
710-m5-compact -m5-compact-nofpu @gol
711-mb -ml -mdalign -mrelax @gol
712-mbigtable -mfmovd -mhitachi -mrenesas -mno-renesas -mnomacsave @gol
713-mieee -misize -mpadstruct -mspace @gol
714-mprefergot -musermode -multcost=@var{number} -mdiv=@var{strategy} @gol
715-mdivsi3_libfunc=@var{name} @gol
716-madjust-unroll -mindexed-addressing -mgettrcost=@var{number} -mpt-fixed @gol
717 -minvalid-symbols}
718
719@emph{SPARC Options}
720@gccoptlist{-mcpu=@var{cpu-type} @gol
721-mtune=@var{cpu-type} @gol
722-mcmodel=@var{code-model} @gol
723-m32 -m64 -mapp-regs -mno-app-regs @gol
724-mfaster-structs -mno-faster-structs @gol
725-mfpu -mno-fpu -mhard-float -msoft-float @gol
726-mhard-quad-float -msoft-quad-float @gol
727-mimpure-text -mno-impure-text -mlittle-endian @gol
728-mstack-bias -mno-stack-bias @gol
729-munaligned-doubles -mno-unaligned-doubles @gol
730-mv8plus -mno-v8plus -mvis -mno-vis
731-threads -pthreads -pthread}
732
733@emph{System V Options}
734@gccoptlist{-Qy -Qn -YP,@var{paths} -Ym,@var{dir}}
735
736@emph{TMS320C3x/C4x Options}
737@gccoptlist{-mcpu=@var{cpu} -mbig -msmall -mregparm -mmemparm @gol
738-mfast-fix -mmpyi -mbk -mti -mdp-isr-reload @gol
739-mrpts=@var{count} -mrptb -mdb -mloop-unsigned @gol
740-mparallel-insns -mparallel-mpy -mpreserve-float}
741
742@emph{V850 Options}
743@gccoptlist{-mlong-calls -mno-long-calls -mep -mno-ep @gol
744-mprolog-function -mno-prolog-function -mspace @gol
745-mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol
746-mapp-regs -mno-app-regs @gol
747-mdisable-callt -mno-disable-callt @gol
748-mv850e1 @gol
749-mv850e @gol
750-mv850 -mbig-switch}
751
752@emph{VAX Options}
753@gccoptlist{-mg -mgnu -munix}
754
755@emph{x86-64 Options}
756See i386 and x86-64 Options.
757
758@emph{Xstormy16 Options}
759@gccoptlist{-msim}
760
761@emph{Xtensa Options}
762@gccoptlist{-mconst16 -mno-const16 @gol
763-mfused-madd -mno-fused-madd @gol
764-mtext-section-literals -mno-text-section-literals @gol
765-mtarget-align -mno-target-align @gol
766-mlongcalls -mno-longcalls}
767
768@emph{zSeries Options}
769See S/390 and zSeries Options.
770
771@item Code Generation Options
772@xref{Code Gen Options,,Options for Code Generation Conventions}.
773@gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol
774-ffixed-@var{reg} -fexceptions @gol
775-fnon-call-exceptions -funwind-tables @gol
776-fasynchronous-unwind-tables @gol
777-finhibit-size-directive -finstrument-functions @gol
778-fno-common -fno-ident @gol
779-fpcc-struct-return -fpic -fPIC -fpie -fPIE @gol
780-fno-jump-tables @gol
781-freg-struct-return -fshort-enums @gol
782-fshort-double -fshort-wchar @gol
783-fverbose-asm -fpack-struct[=@var{n}] -fstack-check @gol
784-fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
785-fargument-alias -fargument-noalias @gol
786-fargument-noalias-global -fargument-noalias-anything
787-fleading-underscore -ftls-model=@var{model} @gol
788-ftrapv -fwrapv -fbounds-check @gol
789-fvisibility}
790@end table
791
792@menu
793* Overall Options:: Controlling the kind of output:
794 an executable, object files, assembler files,
795 or preprocessed source.
796* C Dialect Options:: Controlling the variant of C language compiled.
797* C++ Dialect Options:: Variations on C++.
798* Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
799 and Objective-C++.
800* Language Independent Options:: Controlling how diagnostics should be
801 formatted.
802* Warning Options:: How picky should the compiler be?
803* Debugging Options:: Symbol tables, measurements, and debugging dumps.
804* Optimize Options:: How much optimization?
805* Preprocessor Options:: Controlling header files and macro definitions.
806 Also, getting dependency information for Make.
807* Assembler Options:: Passing options to the assembler.
808* Link Options:: Specifying libraries and so on.
809* Directory Options:: Where to find header files and libraries.
810 Where to find the compiler executable files.
811* Spec Files:: How to pass switches to sub-processes.
812* Target Options:: Running a cross-compiler, or an old version of GCC.
813@end menu
814
815@node Overall Options
816@section Options Controlling the Kind of Output
817
818Compilation can involve up to four stages: preprocessing, compilation
819proper, assembly and linking, always in that order. GCC is capable of
820preprocessing and compiling several files either into several
821assembler input files, or into one assembler input file; then each
822assembler input file produces an object file, and linking combines all
823the object files (those newly compiled, and those specified as input)
824into an executable file.
825
826@cindex file name suffix
827For any given input file, the file name suffix determines what kind of
828compilation is done:
829
830@table @gcctabopt
831@item @var{file}.c
832C source code which must be preprocessed.
833
834@item @var{file}.i
835C source code which should not be preprocessed.
836
837@item @var{file}.ii
838C++ source code which should not be preprocessed.
839
840@item @var{file}.m
841Objective-C source code. Note that you must link with the @file{libobjc}
842library to make an Objective-C program work.
843
844@item @var{file}.mi
845Objective-C source code which should not be preprocessed.
846
847@item @var{file}.mm
848@itemx @var{file}.M
849Objective-C++ source code. Note that you must link with the @file{libobjc}
850library to make an Objective-C++ program work. Note that @samp{.M} refers
851to a literal capital M@.
852
853@item @var{file}.mii
854Objective-C++ source code which should not be preprocessed.
855
856@item @var{file}.h
857C, C++, Objective-C or Objective-C++ header file to be turned into a
858precompiled header.
859
860@item @var{file}.cc
861@itemx @var{file}.cp
862@itemx @var{file}.cxx
863@itemx @var{file}.cpp
864@itemx @var{file}.CPP
865@itemx @var{file}.c++
866@itemx @var{file}.C
867C++ source code which must be preprocessed. Note that in @samp{.cxx},
868the last two letters must both be literally @samp{x}. Likewise,
869@samp{.C} refers to a literal capital C@.
870
871@item @var{file}.mm
872@itemx @var{file}.M
873Objective-C++ source code which must be preprocessed.
874
875@item @var{file}.mii
876Objective-C++ source code which should not be preprocessed.
877
878@item @var{file}.hh
879@itemx @var{file}.H
880C++ header file to be turned into a precompiled header.
881
882@item @var{file}.f
883@itemx @var{file}.for
884@itemx @var{file}.FOR
885Fixed form Fortran source code which should not be preprocessed.
886
887@item @var{file}.F
888@itemx @var{file}.fpp
889@itemx @var{file}.FPP
890Fixed form Fortran source code which must be preprocessed (with the traditional
891preprocessor).
892
893@item @var{file}.f90
894@itemx @var{file}.f95
895Free form Fortran source code which should not be preprocessed.
896
897@item @var{file}.F90
898@itemx @var{file}.F95
899Free form Fortran source code which must be preprocessed (with the
900traditional preprocessor).
901
902@c FIXME: Descriptions of Java file types.
903@c @var{file}.java
904@c @var{file}.class
905@c @var{file}.zip
906@c @var{file}.jar
907
908@item @var{file}.ads
909Ada source code file which contains a library unit declaration (a
910declaration of a package, subprogram, or generic, or a generic
911instantiation), or a library unit renaming declaration (a package,
912generic, or subprogram renaming declaration). Such files are also
913called @dfn{specs}.
914
915@itemx @var{file}.adb
916Ada source code file containing a library unit body (a subprogram or
917package body). Such files are also called @dfn{bodies}.
918
919@c GCC also knows about some suffixes for languages not yet included:
920@c Pascal:
921@c @var{file}.p
922@c @var{file}.pas
923@c Ratfor:
924@c @var{file}.r
925
926@item @var{file}.s
927Assembler code.
928
929@item @var{file}.S
930Assembler code which must be preprocessed.
931
932@item @var{other}
933An object file to be fed straight into linking.
934Any file name with no recognized suffix is treated this way.
935@end table
936
937@opindex x
938You can specify the input language explicitly with the @option{-x} option:
939
940@table @gcctabopt
941@item -x @var{language}
942Specify explicitly the @var{language} for the following input files
943(rather than letting the compiler choose a default based on the file
944name suffix). This option applies to all following input files until
945the next @option{-x} option. Possible values for @var{language} are:
946@smallexample
947c c-header c-cpp-output
948c++ c++-header c++-cpp-output
949objective-c objective-c-header objective-c-cpp-output
950objective-c++ objective-c++-header objective-c++-cpp-output
951assembler assembler-with-cpp
952ada
953f95 f95-cpp-input
954java
955treelang
956@end smallexample
957
958@item -x none
959Turn off any specification of a language, so that subsequent files are
960handled according to their file name suffixes (as they are if @option{-x}
961has not been used at all).
962
963@item -pass-exit-codes
964@opindex pass-exit-codes
965Normally the @command{gcc} program will exit with the code of 1 if any
966phase of the compiler returns a non-success return code. If you specify
967@option{-pass-exit-codes}, the @command{gcc} program will instead return with
968numerically highest error produced by any phase that returned an error
969indication. The C, C++, and Fortran frontends return 4, if an internal
970compiler error is encountered.
971@end table
972
973If you only want some of the stages of compilation, you can use
974@option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
975one of the options @option{-c}, @option{-S}, or @option{-E} to say where
976@command{gcc} is to stop. Note that some combinations (for example,
977@samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
978
979@table @gcctabopt
980@item -c
981@opindex c
982Compile or assemble the source files, but do not link. The linking
983stage simply is not done. The ultimate output is in the form of an
984object file for each source file.
985
986By default, the object file name for a source file is made by replacing
987the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
988
989Unrecognized input files, not requiring compilation or assembly, are
990ignored.
991
992@item -S
993@opindex S
994Stop after the stage of compilation proper; do not assemble. The output
995is in the form of an assembler code file for each non-assembler input
996file specified.
997
998By default, the assembler file name for a source file is made by
999replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
1000
1001Input files that don't require compilation are ignored.
1002
1003@item -E
1004@opindex E
1005Stop after the preprocessing stage; do not run the compiler proper. The
1006output is in the form of preprocessed source code, which is sent to the
1007standard output.
1008
1009Input files which don't require preprocessing are ignored.
1010
1011@cindex output file option
1012@item -o @var{file}
1013@opindex o
1014Place output in file @var{file}. This applies regardless to whatever
1015sort of output is being produced, whether it be an executable file,
1016an object file, an assembler file or preprocessed C code.
1017
1018If @option{-o} is not specified, the default is to put an executable
1019file in @file{a.out}, the object file for
1020@file{@var{source}.@var{suffix}} in @file{@var{source}.o}, its
1021assembler file in @file{@var{source}.s}, a precompiled header file in
1022@file{@var{source}.@var{suffix}.gch}, and all preprocessed C source on
1023standard output.
1024
1025@item -v
1026@opindex v
1027Print (on standard error output) the commands executed to run the stages
1028of compilation. Also print the version number of the compiler driver
1029program and of the preprocessor and the compiler proper.
1030
1031@item -###
1032@opindex ###
1033Like @option{-v} except the commands are not executed and all command
1034arguments are quoted. This is useful for shell scripts to capture the
1035driver-generated command lines.
1036
1037@item -pipe
1038@opindex pipe
1039Use pipes rather than temporary files for communication between the
1040various stages of compilation. This fails to work on some systems where
1041the assembler is unable to read from a pipe; but the GNU assembler has
1042no trouble.
1043
1044@item -combine
1045@opindex combine
1046If you are compiling multiple source files, this option tells the driver
1047to pass all the source files to the compiler at once (for those
1048languages for which the compiler can handle this). This will allow
1049intermodule analysis (IMA) to be performed by the compiler. Currently the only
1050language for which this is supported is C@. If you pass source files for
1051multiple languages to the driver, using this option, the driver will invoke
1052the compiler(s) that support IMA once each, passing each compiler all the
1053source files appropriate for it. For those languages that do not support
1054IMA this option will be ignored, and the compiler will be invoked once for
1055each source file in that language. If you use this option in conjunction
1056with @option{-save-temps}, the compiler will generate multiple
1057pre-processed files
1058(one for each source file), but only one (combined) @file{.o} or
1059@file{.s} file.
1060
1061@item --help
1062@opindex help
1063Print (on the standard output) a description of the command line options
1064understood by @command{gcc}. If the @option{-v} option is also specified
1065then @option{--help} will also be passed on to the various processes
1066invoked by @command{gcc}, so that they can display the command line options
1067they accept. If the @option{-Wextra} option is also specified then command
1068line options which have no documentation associated with them will also
1069be displayed.
1070
1071@item --target-help
1072@opindex target-help
1073Print (on the standard output) a description of target specific command
1074line options for each tool.
1075
1076@item --version
1077@opindex version
1078Display the version number and copyrights of the invoked GCC@.
1079
1080@include @value{srcdir}/../libiberty/at-file.texi
1081@end table
1082
1083@node Invoking G++
1084@section Compiling C++ Programs
1085
1086@cindex suffixes for C++ source
1087@cindex C++ source file suffixes
1088C++ source files conventionally use one of the suffixes @samp{.C},
1089@samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or
1090@samp{.cxx}; C++ header files often use @samp{.hh} or @samp{.H}; and
1091preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes
1092files with these names and compiles them as C++ programs even if you
1093call the compiler the same way as for compiling C programs (usually
1094with the name @command{gcc}).
1095
1096@findex g++
1097@findex c++
1098However, the use of @command{gcc} does not add the C++ library.
1099@command{g++} is a program that calls GCC and treats @samp{.c},
1100@samp{.h} and @samp{.i} files as C++ source files instead of C source
1101files unless @option{-x} is used, and automatically specifies linking
1102against the C++ library. This program is also useful when
1103precompiling a C header file with a @samp{.h} extension for use in C++
1104compilations. On many systems, @command{g++} is also installed with
1105the name @command{c++}.
1106
1107@cindex invoking @command{g++}
1108When you compile C++ programs, you may specify many of the same
1109command-line options that you use for compiling programs in any
1110language; or command-line options meaningful for C and related
1111languages; or options that are meaningful only for C++ programs.
1112@xref{C Dialect Options,,Options Controlling C Dialect}, for
1113explanations of options for languages related to C@.
1114@xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
1115explanations of options that are meaningful only for C++ programs.
1116
1117@node C Dialect Options
1118@section Options Controlling C Dialect
1119@cindex dialect options
1120@cindex language dialect options
1121@cindex options, dialect
1122
1123The following options control the dialect of C (or languages derived
1124from C, such as C++, Objective-C and Objective-C++) that the compiler
1125accepts:
1126
1127@table @gcctabopt
1128@cindex ANSI support
1129@cindex ISO support
1130@item -ansi
1131@opindex ansi
1132In C mode, support all ISO C90 programs. In C++ mode,
1133remove GNU extensions that conflict with ISO C++.
1134
1135This turns off certain features of GCC that are incompatible with ISO
1136C90 (when compiling C code), or of standard C++ (when compiling C++ code),
1137such as the @code{asm} and @code{typeof} keywords, and
1138predefined macros such as @code{unix} and @code{vax} that identify the
1139type of system you are using. It also enables the undesirable and
1140rarely used ISO trigraph feature. For the C compiler,
1141it disables recognition of C++ style @samp{//} comments as well as
1142the @code{inline} keyword.
1143
1144The alternate keywords @code{__asm__}, @code{__extension__},
1145@code{__inline__} and @code{__typeof__} continue to work despite
1146@option{-ansi}. You would not want to use them in an ISO C program, of
1147course, but it is useful to put them in header files that might be included
1148in compilations done with @option{-ansi}. Alternate predefined macros
1149such as @code{__unix__} and @code{__vax__} are also available, with or
1150without @option{-ansi}.
1151
1152The @option{-ansi} option does not cause non-ISO programs to be
1153rejected gratuitously. For that, @option{-pedantic} is required in
1154addition to @option{-ansi}. @xref{Warning Options}.
1155
1156The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
1157option is used. Some header files may notice this macro and refrain
1158from declaring certain functions or defining certain macros that the
1159ISO standard doesn't call for; this is to avoid interfering with any
1160programs that might use these names for other things.
1161
1162Functions which would normally be built in but do not have semantics
1163defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
1164functions with @option{-ansi} is used. @xref{Other Builtins,,Other
1165built-in functions provided by GCC}, for details of the functions
1166affected.
1167
1168@item -std=
1169@opindex std
1170Determine the language standard. This option is currently only
1171supported when compiling C or C++. A value for this option must be
1172provided; possible values are
1173
1174@table @samp
1175@item c89
1176@itemx iso9899:1990
1177ISO C90 (same as @option{-ansi}).
1178
1179@item iso9899:199409
1180ISO C90 as modified in amendment 1.
1181
1182@item c99
1183@itemx c9x
1184@itemx iso9899:1999
1185@itemx iso9899:199x
1186ISO C99. Note that this standard is not yet fully supported; see
1187@w{@uref{http://gcc.gnu.org/gcc-4.2/c99status.html}} for more information. The
1188names @samp{c9x} and @samp{iso9899:199x} are deprecated.
1189
1190@item gnu89
1191Default, ISO C90 plus GNU extensions (including some C99 features).
1192
1193@item gnu99
1194@itemx gnu9x
1195ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC,
1196this will become the default. The name @samp{gnu9x} is deprecated.
1197
1198@item c++98
1199The 1998 ISO C++ standard plus amendments.
1200
1201@item gnu++98
1202The same as @option{-std=c++98} plus GNU extensions. This is the
1203default for C++ code.
1204@end table
1205
1206Even when this option is not specified, you can still use some of the
1207features of newer standards in so far as they do not conflict with
1208previous C standards. For example, you may use @code{__restrict__} even
1209when @option{-std=c99} is not specified.
1210
1211The @option{-std} options specifying some version of ISO C have the same
1212effects as @option{-ansi}, except that features that were not in ISO C90
1213but are in the specified version (for example, @samp{//} comments and
1214the @code{inline} keyword in ISO C99) are not disabled.
1215
1216@xref{Standards,,Language Standards Supported by GCC}, for details of
1217these standard versions.
1218
1219@item -fgnu89-inline
1220@opindex fgnu89-inline
1221The option @option{-fgnu89-inline} tells GCC to use the traditional
1222GNU semantics for @code{inline} functions when in C99 mode.
1223@xref{Inline,,An Inline Function is As Fast As a Macro}. Using this
1224option is roughly equivalent to adding the @code{gnu_inline} function
1225attribute to all inline functions (@pxref{Function Attributes}).
1226
1227This option is accepted by GCC versions 4.1.3 and up. In GCC versions
1228prior to 4.3, C99 inline semantics are not supported, and thus this
1229option is effectively assumed to be present regardless of whether or not
1230it is specified; the only effect of specifying it explicitly is to
1231disable warnings about using inline functions in C99 mode. Likewise,
1232the option @option{-fno-gnu89-inline} is not supported in versions of
1233GCC before 4.3. It will be supported only in C99 or gnu99 mode, not in
1234C89 or gnu89 mode.
1235
1236The preprocesor macros @code{__GNUC_GNU_INLINE__} and
1237@code{__GNUC_STDC_INLINE__} may be used to check which semantics are
1238in effect for @code{inline} functions. @xref{Common Predefined
1239Macros,,,cpp,The C Preprocessor}.
1240
1241@item -aux-info @var{filename}
1242@opindex aux-info
1243Output to the given filename prototyped declarations for all functions
1244declared and/or defined in a translation unit, including those in header
1245files. This option is silently ignored in any language other than C@.
1246
1247Besides declarations, the file indicates, in comments, the origin of
1248each declaration (source file and line), whether the declaration was
1249implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
1250@samp{O} for old, respectively, in the first character after the line
1251number and the colon), and whether it came from a declaration or a
1252definition (@samp{C} or @samp{F}, respectively, in the following
1253character). In the case of function definitions, a K&R-style list of
1254arguments followed by their declarations is also provided, inside
1255comments, after the declaration.
1256
1257@item -fno-asm
1258@opindex fno-asm
1259Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1260keyword, so that code can use these words as identifiers. You can use
1261the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
1262instead. @option{-ansi} implies @option{-fno-asm}.
1263
1264In C++, this switch only affects the @code{typeof} keyword, since
1265@code{asm} and @code{inline} are standard keywords. You may want to
1266use the @option{-fno-gnu-keywords} flag instead, which has the same
1267effect. In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
1268switch only affects the @code{asm} and @code{typeof} keywords, since
1269@code{inline} is a standard keyword in ISO C99.
1270
1271@item -fno-builtin
1272@itemx -fno-builtin-@var{function}
1273@opindex fno-builtin
1274@cindex built-in functions
1275Don't recognize built-in functions that do not begin with
1276@samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in
1277functions provided by GCC}, for details of the functions affected,
1278including those which are not built-in functions when @option{-ansi} or
1279@option{-std} options for strict ISO C conformance are used because they
1280do not have an ISO standard meaning.
1281
1282GCC normally generates special code to handle certain built-in functions
1283more efficiently; for instance, calls to @code{alloca} may become single
1284instructions that adjust the stack directly, and calls to @code{memcpy}
1285may become inline copy loops. The resulting code is often both smaller
1286and faster, but since the function calls no longer appear as such, you
1287cannot set a breakpoint on those calls, nor can you change the behavior
1288of the functions by linking with a different library. In addition,
1289when a function is recognized as a built-in function, GCC may use
1290information about that function to warn about problems with calls to
1291that function, or to generate more efficient code, even if the
1292resulting code still contains calls to that function. For example,
1293warnings are given with @option{-Wformat} for bad calls to
1294@code{printf}, when @code{printf} is built in, and @code{strlen} is
1295known not to modify global memory.
1296
1297With the @option{-fno-builtin-@var{function}} option
1298only the built-in function @var{function} is
1299disabled. @var{function} must not begin with @samp{__builtin_}. If a
1300function is named this is not built-in in this version of GCC, this
1301option is ignored. There is no corresponding
1302@option{-fbuiltin-@var{function}} option; if you wish to enable
1303built-in functions selectively when using @option{-fno-builtin} or
1304@option{-ffreestanding}, you may define macros such as:
1305
1306@smallexample
1307#define abs(n) __builtin_abs ((n))
1308#define strcpy(d, s) __builtin_strcpy ((d), (s))
1309@end smallexample
1310
1311@item -fhosted
1312@opindex fhosted
1313@cindex hosted environment
1314
1315Assert that compilation takes place in a hosted environment. This implies
1316@option{-fbuiltin}. A hosted environment is one in which the
1317entire standard library is available, and in which @code{main} has a return
1318type of @code{int}. Examples are nearly everything except a kernel.
1319This is equivalent to @option{-fno-freestanding}.
1320
1321@item -ffreestanding
1322@opindex ffreestanding
1323@cindex hosted environment
1324
1325Assert that compilation takes place in a freestanding environment. This
1326implies @option{-fno-builtin}. A freestanding environment
1327is one in which the standard library may not exist, and program startup may
1328not necessarily be at @code{main}. The most obvious example is an OS kernel.
1329This is equivalent to @option{-fno-hosted}.
1330
1331@xref{Standards,,Language Standards Supported by GCC}, for details of
1332freestanding and hosted environments.
1333
1334@item -fopenmp
1335@opindex fopenmp
1336@cindex openmp parallel
1337Enable handling of OpenMP directives @code{#pragma omp} in C/C++ and
1338@code{!$omp} in Fortran. When @option{-fopenmp} is specified, the
1339compiler generates parallel code according to the OpenMP Application
1340Program Interface v2.5 @w{@uref{http://www.openmp.org/}}.
1341
1342@item -fms-extensions
1343@opindex fms-extensions
1344Accept some non-standard constructs used in Microsoft header files.
1345
1346Some cases of unnamed fields in structures and unions are only
1347accepted with this option. @xref{Unnamed Fields,,Unnamed struct/union
1348fields within structs/unions}, for details.
1349
1350@item -trigraphs
1351@opindex trigraphs
1352Support ISO C trigraphs. The @option{-ansi} option (and @option{-std}
1353options for strict ISO C conformance) implies @option{-trigraphs}.
1354
1355@item -no-integrated-cpp
1356@opindex no-integrated-cpp
1357Performs a compilation in two passes: preprocessing and compiling. This
1358option allows a user supplied "cc1", "cc1plus", or "cc1obj" via the
1359@option{-B} option. The user supplied compilation step can then add in
1360an additional preprocessing step after normal preprocessing but before
1361compiling. The default is to use the integrated cpp (internal cpp)
1362
1363The semantics of this option will change if "cc1", "cc1plus", and
1364"cc1obj" are merged.
1365
1366@cindex traditional C language
1367@cindex C language, traditional
1368@item -traditional
1369@itemx -traditional-cpp
1370@opindex traditional-cpp
1371@opindex traditional
1372Formerly, these options caused GCC to attempt to emulate a pre-standard
1373C compiler. They are now only supported with the @option{-E} switch.
1374The preprocessor continues to support a pre-standard mode. See the GNU
1375CPP manual for details.
1376
1377@item -fcond-mismatch
1378@opindex fcond-mismatch
1379Allow conditional expressions with mismatched types in the second and
1380third arguments. The value of such an expression is void. This option
1381is not supported for C++.
1382
1383@item -funsigned-char
1384@opindex funsigned-char
1385Let the type @code{char} be unsigned, like @code{unsigned char}.
1386
1387Each kind of machine has a default for what @code{char} should
1388be. It is either like @code{unsigned char} by default or like
1389@code{signed char} by default.
1390
1391Ideally, a portable program should always use @code{signed char} or
1392@code{unsigned char} when it depends on the signedness of an object.
1393But many programs have been written to use plain @code{char} and
1394expect it to be signed, or expect it to be unsigned, depending on the
1395machines they were written for. This option, and its inverse, let you
1396make such a program work with the opposite default.
1397
1398The type @code{char} is always a distinct type from each of
1399@code{signed char} or @code{unsigned char}, even though its behavior
1400is always just like one of those two.
1401
1402@item -fsigned-char
1403@opindex fsigned-char
1404Let the type @code{char} be signed, like @code{signed char}.
1405
1406Note that this is equivalent to @option{-fno-unsigned-char}, which is
1407the negative form of @option{-funsigned-char}. Likewise, the option
1408@option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
1409
1410@item -fsigned-bitfields
1411@itemx -funsigned-bitfields
1412@itemx -fno-signed-bitfields
1413@itemx -fno-unsigned-bitfields
1414@opindex fsigned-bitfields
1415@opindex funsigned-bitfields
1416@opindex fno-signed-bitfields
1417@opindex fno-unsigned-bitfields
1418These options control whether a bit-field is signed or unsigned, when the
1419declaration does not use either @code{signed} or @code{unsigned}. By
1420default, such a bit-field is signed, because this is consistent: the
1421basic integer types such as @code{int} are signed types.
1422@end table
1423
1424@node C++ Dialect Options
1425@section Options Controlling C++ Dialect
1426
1427@cindex compiler options, C++
1428@cindex C++ options, command line
1429@cindex options, C++
1430This section describes the command-line options that are only meaningful
1431for C++ programs; but you can also use most of the GNU compiler options
1432regardless of what language your program is in. For example, you
1433might compile a file @code{firstClass.C} like this:
1434
1435@smallexample
1436g++ -g -frepo -O -c firstClass.C
1437@end smallexample
1438
1439@noindent
1440In this example, only @option{-frepo} is an option meant
1441only for C++ programs; you can use the other options with any
1442language supported by GCC@.
1443
1444Here is a list of options that are @emph{only} for compiling C++ programs:
1445
1446@table @gcctabopt
1447
1448@item -fabi-version=@var{n}
1449@opindex fabi-version
1450Use version @var{n} of the C++ ABI@. Version 2 is the version of the
1451C++ ABI that first appeared in G++ 3.4. Version 1 is the version of
1452the C++ ABI that first appeared in G++ 3.2. Version 0 will always be
1453the version that conforms most closely to the C++ ABI specification.
1454Therefore, the ABI obtained using version 0 will change as ABI bugs
1455are fixed.
1456
1457The default is version 2.
1458
1459@item -fno-access-control
1460@opindex fno-access-control
1461Turn off all access checking. This switch is mainly useful for working
1462around bugs in the access control code.
1463
1464@item -fcheck-new
1465@opindex fcheck-new
1466Check that the pointer returned by @code{operator new} is non-null
1467before attempting to modify the storage allocated. This check is
1468normally unnecessary because the C++ standard specifies that
1469@code{operator new} will only return @code{0} if it is declared
1470@samp{throw()}, in which case the compiler will always check the
1471return value even without this option. In all other cases, when
1472@code{operator new} has a non-empty exception specification, memory
1473exhaustion is signalled by throwing @code{std::bad_alloc}. See also
1474@samp{new (nothrow)}.
1475
1476@item -fconserve-space
1477@opindex fconserve-space
1478Put uninitialized or runtime-initialized global variables into the
1479common segment, as C does. This saves space in the executable at the
1480cost of not diagnosing duplicate definitions. If you compile with this
1481flag and your program mysteriously crashes after @code{main()} has
1482completed, you may have an object that is being destroyed twice because
1483two definitions were merged.
1484
1485This option is no longer useful on most targets, now that support has
1486been added for putting variables into BSS without making them common.
1487
1488@item -ffriend-injection
1489@opindex ffriend-injection
1490Inject friend functions into the enclosing namespace, so that they are
1491visible outside the scope of the class in which they are declared.
1492Friend functions were documented to work this way in the old Annotated
1493C++ Reference Manual, and versions of G++ before 4.1 always worked
1494that way. However, in ISO C++ a friend function which is not declared
1495in an enclosing scope can only be found using argument dependent
1496lookup. This option causes friends to be injected as they were in
1497earlier releases.
1498
1499This option is for compatibility, and may be removed in a future
1500release of G++.
1501
1502@item -fno-elide-constructors
1503@opindex fno-elide-constructors
1504The C++ standard allows an implementation to omit creating a temporary
1505which is only used to initialize another object of the same type.
1506Specifying this option disables that optimization, and forces G++ to
1507call the copy constructor in all cases.
1508
1509@item -fno-enforce-eh-specs
1510@opindex fno-enforce-eh-specs
1511Don't generate code to check for violation of exception specifications
1512at runtime. This option violates the C++ standard, but may be useful
1513for reducing code size in production builds, much like defining
1514@samp{NDEBUG}. This does not give user code permission to throw
1515exceptions in violation of the exception specifications; the compiler
1516will still optimize based on the specifications, so throwing an
1517unexpected exception will result in undefined behavior.
1518
1519@item -ffor-scope
1520@itemx -fno-for-scope
1521@opindex ffor-scope
1522@opindex fno-for-scope
1523If @option{-ffor-scope} is specified, the scope of variables declared in
1524a @i{for-init-statement} is limited to the @samp{for} loop itself,
1525as specified by the C++ standard.
1526If @option{-fno-for-scope} is specified, the scope of variables declared in
1527a @i{for-init-statement} extends to the end of the enclosing scope,
1528as was the case in old versions of G++, and other (traditional)
1529implementations of C++.
1530
1531The default if neither flag is given to follow the standard,
1532but to allow and give a warning for old-style code that would
1533otherwise be invalid, or have different behavior.
1534
1535@item -fno-gnu-keywords
1536@opindex fno-gnu-keywords
1537Do not recognize @code{typeof} as a keyword, so that code can use this
1538word as an identifier. You can use the keyword @code{__typeof__} instead.
1539@option{-ansi} implies @option{-fno-gnu-keywords}.
1540
1541@item -fno-implicit-templates
1542@opindex fno-implicit-templates
1543Never emit code for non-inline templates which are instantiated
1544implicitly (i.e.@: by use); only emit code for explicit instantiations.
1545@xref{Template Instantiation}, for more information.
1546
1547@item -fno-implicit-inline-templates
1548@opindex fno-implicit-inline-templates
1549Don't emit code for implicit instantiations of inline templates, either.
1550The default is to handle inlines differently so that compiles with and
1551without optimization will need the same set of explicit instantiations.
1552
1553@item -fno-implement-inlines
1554@opindex fno-implement-inlines
1555To save space, do not emit out-of-line copies of inline functions
1556controlled by @samp{#pragma implementation}. This will cause linker
1557errors if these functions are not inlined everywhere they are called.
1558
1559@item -fms-extensions
1560@opindex fms-extensions
1561Disable pedantic warnings about constructs used in MFC, such as implicit
1562int and getting a pointer to member function via non-standard syntax.
1563
1564@item -fno-nonansi-builtins
1565@opindex fno-nonansi-builtins
1566Disable built-in declarations of functions that are not mandated by
1567ANSI/ISO C@. These include @code{ffs}, @code{alloca}, @code{_exit},
1568@code{index}, @code{bzero}, @code{conjf}, and other related functions.
1569
1570@item -fno-operator-names
1571@opindex fno-operator-names
1572Do not treat the operator name keywords @code{and}, @code{bitand},
1573@code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1574synonyms as keywords.
1575
1576@item -fno-optional-diags
1577@opindex fno-optional-diags
1578Disable diagnostics that the standard says a compiler does not need to
1579issue. Currently, the only such diagnostic issued by G++ is the one for
1580a name having multiple meanings within a class.
1581
1582@item -fpermissive
1583@opindex fpermissive
1584Downgrade some diagnostics about nonconformant code from errors to
1585warnings. Thus, using @option{-fpermissive} will allow some
1586nonconforming code to compile.
1587
1588@item -frepo
1589@opindex frepo
1590Enable automatic template instantiation at link time. This option also
1591implies @option{-fno-implicit-templates}. @xref{Template
1592Instantiation}, for more information.
1593
1594@item -fno-rtti
1595@opindex fno-rtti
1596Disable generation of information about every class with virtual
1597functions for use by the C++ runtime type identification features
1598(@samp{dynamic_cast} and @samp{typeid}). If you don't use those parts
1599of the language, you can save some space by using this flag. Note that
1600exception handling uses the same information, but it will generate it as
1601needed. The @samp{dynamic_cast} operator can still be used for casts that
1602do not require runtime type information, i.e. casts to @code{void *} or to
1603unambiguous base classes.
1604
1605@item -fstats
1606@opindex fstats
1607Emit statistics about front-end processing at the end of the compilation.
1608This information is generally only useful to the G++ development team.
1609
1610@item -ftemplate-depth-@var{n}
1611@opindex ftemplate-depth
1612Set the maximum instantiation depth for template classes to @var{n}.
1613A limit on the template instantiation depth is needed to detect
1614endless recursions during template class instantiation. ANSI/ISO C++
1615conforming programs must not rely on a maximum depth greater than 17.
1616
1617@item -fno-threadsafe-statics
1618@opindex fno-threadsafe-statics
1619Do not emit the extra code to use the routines specified in the C++
1620ABI for thread-safe initialization of local statics. You can use this
1621option to reduce code size slightly in code that doesn't need to be
1622thread-safe.
1623
1624@item -fuse-cxa-atexit
1625@opindex fuse-cxa-atexit
1626Register destructors for objects with static storage duration with the
1627@code{__cxa_atexit} function rather than the @code{atexit} function.
1628This option is required for fully standards-compliant handling of static
1629destructors, but will only work if your C library supports
1630@code{__cxa_atexit}.
1631
1632@item -fno-use-cxa-get-exception-ptr
1633@opindex fno-use-cxa-get-exception-ptr
1634Don't use the @code{__cxa_get_exception_ptr} runtime routine. This
1635will cause @code{std::uncaught_exception} to be incorrect, but is necessary
1636if the runtime routine is not available.
1637
1638@item -fvisibility-inlines-hidden
1639@opindex fvisibility-inlines-hidden
1640This switch declares that the user does not attempt to compare
1641pointers to inline methods where the addresses of the two functions
1642were taken in different shared objects.
1643
1644The effect of this is that GCC may, effectively, mark inline methods with
1645@code{__attribute__ ((visibility ("hidden")))} so that they do not
1646appear in the export table of a DSO and do not require a PLT indirection
1647when used within the DSO@. Enabling this option can have a dramatic effect
1648on load and link times of a DSO as it massively reduces the size of the
1649dynamic export table when the library makes heavy use of templates.
1650
1651The behaviour of this switch is not quite the same as marking the
1652methods as hidden directly, because it does not affect static variables
1653local to the function or cause the compiler to deduce that
1654the function is defined in only one shared object.
1655
1656You may mark a method as having a visibility explicitly to negate the
1657effect of the switch for that method. For example, if you do want to
1658compare pointers to a particular inline method, you might mark it as
1659having default visibility. Marking the enclosing class with explicit
1660visibility will have no effect.
1661
1662Explicitly instantiated inline methods are unaffected by this option
1663as their linkage might otherwise cross a shared library boundary.
1664@xref{Template Instantiation}.
1665
1666@item -fno-weak
1667@opindex fno-weak
1668Do not use weak symbol support, even if it is provided by the linker.
1669By default, G++ will use weak symbols if they are available. This
1670option exists only for testing, and should not be used by end-users;
1671it will result in inferior code and has no benefits. This option may
1672be removed in a future release of G++.
1673
1674@item -nostdinc++
1675@opindex nostdinc++
1676Do not search for header files in the standard directories specific to
1677C++, but do still search the other standard directories. (This option
1678is used when building the C++ library.)
1679@end table
1680
1681In addition, these optimization, warning, and code generation options
1682have meanings only for C++ programs:
1683
1684@table @gcctabopt
1685@item -fno-default-inline
1686@opindex fno-default-inline
1687Do not assume @samp{inline} for functions defined inside a class scope.
1688@xref{Optimize Options,,Options That Control Optimization}. Note that these
1689functions will have linkage like inline functions; they just won't be
1690inlined by default.
1691
1692@item -Wabi @r{(C++ only)}
1693@opindex Wabi
1694Warn when G++ generates code that is probably not compatible with the
1695vendor-neutral C++ ABI@. Although an effort has been made to warn about
1696all such cases, there are probably some cases that are not warned about,
1697even though G++ is generating incompatible code. There may also be
1698cases where warnings are emitted even though the code that is generated
1699will be compatible.
1700
1701You should rewrite your code to avoid these warnings if you are
1702concerned about the fact that code generated by G++ may not be binary
1703compatible with code generated by other compilers.
1704
1705The known incompatibilities at this point include:
1706
1707@itemize @bullet
1708
1709@item
1710Incorrect handling of tail-padding for bit-fields. G++ may attempt to
1711pack data into the same byte as a base class. For example:
1712
1713@smallexample
1714struct A @{ virtual void f(); int f1 : 1; @};
1715struct B : public A @{ int f2 : 1; @};
1716@end smallexample
1717
1718@noindent
1719In this case, G++ will place @code{B::f2} into the same byte
1720as@code{A::f1}; other compilers will not. You can avoid this problem
1721by explicitly padding @code{A} so that its size is a multiple of the
1722byte size on your platform; that will cause G++ and other compilers to
1723layout @code{B} identically.
1724
1725@item
1726Incorrect handling of tail-padding for virtual bases. G++ does not use
1727tail padding when laying out virtual bases. For example:
1728
1729@smallexample
1730struct A @{ virtual void f(); char c1; @};
1731struct B @{ B(); char c2; @};
1732struct C : public A, public virtual B @{@};
1733@end smallexample
1734
1735@noindent
1736In this case, G++ will not place @code{B} into the tail-padding for
1737@code{A}; other compilers will. You can avoid this problem by
1738explicitly padding @code{A} so that its size is a multiple of its
1739alignment (ignoring virtual base classes); that will cause G++ and other
1740compilers to layout @code{C} identically.
1741
1742@item
1743Incorrect handling of bit-fields with declared widths greater than that
1744of their underlying types, when the bit-fields appear in a union. For
1745example:
1746
1747@smallexample
1748union U @{ int i : 4096; @};
1749@end smallexample
1750
1751@noindent
1752Assuming that an @code{int} does not have 4096 bits, G++ will make the
1753union too small by the number of bits in an @code{int}.
1754
1755@item
1756Empty classes can be placed at incorrect offsets. For example:
1757
1758@smallexample
1759struct A @{@};
1760
1761struct B @{
1762 A a;
1763 virtual void f ();
1764@};
1765
1766struct C : public B, public A @{@};
1767@end smallexample
1768
1769@noindent
1770G++ will place the @code{A} base class of @code{C} at a nonzero offset;
1771it should be placed at offset zero. G++ mistakenly believes that the
1772@code{A} data member of @code{B} is already at offset zero.
1773
1774@item
1775Names of template functions whose types involve @code{typename} or
1776template template parameters can be mangled incorrectly.
1777
1778@smallexample
1779template <typename Q>
1780void f(typename Q::X) @{@}
1781
1782template <template <typename> class Q>
1783void f(typename Q<int>::X) @{@}
1784@end smallexample
1785
1786@noindent
1787Instantiations of these templates may be mangled incorrectly.
1788
1789@end itemize
1790
1791@item -Wctor-dtor-privacy @r{(C++ only)}
1792@opindex Wctor-dtor-privacy
1793Warn when a class seems unusable because all the constructors or
1794destructors in that class are private, and it has neither friends nor
1795public static member functions.
1796
1797@item -Wnon-virtual-dtor @r{(C++ only)}
1798@opindex Wnon-virtual-dtor
1799Warn when a class appears to be polymorphic, thereby requiring a virtual
1800destructor, yet it declares a non-virtual one. This warning is also
1801enabled if -Weffc++ is specified.
1802
1803@item -Wreorder @r{(C++ only)}
1804@opindex Wreorder
1805@cindex reordering, warning
1806@cindex warning for reordering of member initializers
1807Warn when the order of member initializers given in the code does not
1808match the order in which they must be executed. For instance:
1809
1810@smallexample
1811struct A @{
1812 int i;
1813 int j;
1814 A(): j (0), i (1) @{ @}
1815@};
1816@end smallexample
1817
1818The compiler will rearrange the member initializers for @samp{i}
1819and @samp{j} to match the declaration order of the members, emitting
1820a warning to that effect. This warning is enabled by @option{-Wall}.
1821@end table
1822
1823The following @option{-W@dots{}} options are not affected by @option{-Wall}.
1824
1825@table @gcctabopt
1826@item -Weffc++ @r{(C++ only)}
1827@opindex Weffc++
1828Warn about violations of the following style guidelines from Scott Meyers'
1829@cite{Effective C++} book:
1830
1831@itemize @bullet
1832@item
1833Item 11: Define a copy constructor and an assignment operator for classes
1834with dynamically allocated memory.
1835
1836@item
1837Item 12: Prefer initialization to assignment in constructors.
1838
1839@item
1840Item 14: Make destructors virtual in base classes.
1841
1842@item
1843Item 15: Have @code{operator=} return a reference to @code{*this}.
1844
1845@item
1846Item 23: Don't try to return a reference when you must return an object.
1847
1848@end itemize
1849
1850Also warn about violations of the following style guidelines from
1851Scott Meyers' @cite{More Effective C++} book:
1852
1853@itemize @bullet
1854@item
1855Item 6: Distinguish between prefix and postfix forms of increment and
1856decrement operators.
1857
1858@item
1859Item 7: Never overload @code{&&}, @code{||}, or @code{,}.
1860
1861@end itemize
1862
1863When selecting this option, be aware that the standard library
1864headers do not obey all of these guidelines; use @samp{grep -v}
1865to filter out those warnings.
1866
1867@item -Wno-deprecated @r{(C++ only)}
1868@opindex Wno-deprecated
1869Do not warn about usage of deprecated features. @xref{Deprecated Features}.
1870
1871@item -Wstrict-null-sentinel @r{(C++ only)}
1872@opindex Wstrict-null-sentinel
1873Warn also about the use of an uncasted @code{NULL} as sentinel. When
1874compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
1875to @code{__null}. Although it is a null pointer constant not a null pointer,
1876it is guaranteed to of the same size as a pointer. But this use is
1877not portable across different compilers.
1878
1879@item -Wno-non-template-friend @r{(C++ only)}
1880@opindex Wno-non-template-friend
1881Disable warnings when non-templatized friend functions are declared
1882within a template. Since the advent of explicit template specification
1883support in G++, if the name of the friend is an unqualified-id (i.e.,
1884@samp{friend foo(int)}), the C++ language specification demands that the
1885friend declare or define an ordinary, nontemplate function. (Section
188614.5.3). Before G++ implemented explicit specification, unqualified-ids
1887could be interpreted as a particular specialization of a templatized
1888function. Because this non-conforming behavior is no longer the default
1889behavior for G++, @option{-Wnon-template-friend} allows the compiler to
1890check existing code for potential trouble spots and is on by default.
1891This new compiler behavior can be turned off with
1892@option{-Wno-non-template-friend} which keeps the conformant compiler code
1893but disables the helpful warning.
1894
1895@item -Wold-style-cast @r{(C++ only)}
1896@opindex Wold-style-cast
1897Warn if an old-style (C-style) cast to a non-void type is used within
1898a C++ program. The new-style casts (@samp{dynamic_cast},
1899@samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are
1900less vulnerable to unintended effects and much easier to search for.
1901
1902@item -Woverloaded-virtual @r{(C++ only)}
1903@opindex Woverloaded-virtual
1904@cindex overloaded virtual fn, warning
1905@cindex warning for overloaded virtual fn
1906Warn when a function declaration hides virtual functions from a
1907base class. For example, in:
1908
1909@smallexample
1910struct A @{
1911 virtual void f();
1912@};
1913
1914struct B: public A @{
1915 void f(int);
1916@};
1917@end smallexample
1918
1919the @code{A} class version of @code{f} is hidden in @code{B}, and code
1920like:
1921
1922@smallexample
1923B* b;
1924b->f();
1925@end smallexample
1926
1927will fail to compile.
1928
1929@item -Wno-pmf-conversions @r{(C++ only)}
1930@opindex Wno-pmf-conversions
1931Disable the diagnostic for converting a bound pointer to member function
1932to a plain pointer.
1933
1934@item -Wsign-promo @r{(C++ only)}
1935@opindex Wsign-promo
1936Warn when overload resolution chooses a promotion from unsigned or
1937enumerated type to a signed type, over a conversion to an unsigned type of
1938the same size. Previous versions of G++ would try to preserve
1939unsignedness, but the standard mandates the current behavior.
1940
1941@smallexample
1942struct A @{
1943 operator int ();
1944 A& operator = (int);
1945@};
1946
1947main ()
1948@{
1949 A a,b;
1950 a = b;
1951@}
1952@end smallexample
1953
1954In this example, G++ will synthesize a default @samp{A& operator =
1955(const A&);}, while cfront will use the user-defined @samp{operator =}.
1956@end table
1957
1958@node Objective-C and Objective-C++ Dialect Options
1959@section Options Controlling Objective-C and Objective-C++ Dialects
1960
1961@cindex compiler options, Objective-C and Objective-C++
1962@cindex Objective-C and Objective-C++ options, command line
1963@cindex options, Objective-C and Objective-C++
1964(NOTE: This manual does not describe the Objective-C and Objective-C++
1965languages themselves. See @xref{Standards,,Language Standards
1966Supported by GCC}, for references.)
1967
1968This section describes the command-line options that are only meaningful
1969for Objective-C and Objective-C++ programs, but you can also use most of
1970the language-independent GNU compiler options.
1971For example, you might compile a file @code{some_class.m} like this:
1972
1973@smallexample
1974gcc -g -fgnu-runtime -O -c some_class.m
1975@end smallexample
1976
1977@noindent
1978In this example, @option{-fgnu-runtime} is an option meant only for
1979Objective-C and Objective-C++ programs; you can use the other options with
1980any language supported by GCC@.
1981
1982Note that since Objective-C is an extension of the C language, Objective-C
1983compilations may also use options specific to the C front-end (e.g.,
1984@option{-Wtraditional}). Similarly, Objective-C++ compilations may use
1985C++-specific options (e.g., @option{-Wabi}).
1986
1987Here is a list of options that are @emph{only} for compiling Objective-C
1988and Objective-C++ programs:
1989
1990@table @gcctabopt
1991@item -fconstant-string-class=@var{class-name}
1992@opindex fconstant-string-class
1993Use @var{class-name} as the name of the class to instantiate for each
1994literal string specified with the syntax @code{@@"@dots{}"}. The default
1995class name is @code{NXConstantString} if the GNU runtime is being used, and
1996@code{NSConstantString} if the NeXT runtime is being used (see below). The
1997@option{-fconstant-cfstrings} option, if also present, will override the
1998@option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} literals
1999to be laid out as constant CoreFoundation strings.
2000
2001@item -fgnu-runtime
2002@opindex fgnu-runtime
2003Generate object code compatible with the standard GNU Objective-C
2004runtime. This is the default for most types of systems.
2005
2006@item -fnext-runtime
2007@opindex fnext-runtime
2008Generate output compatible with the NeXT runtime. This is the default
2009for NeXT-based systems, including Darwin and Mac OS X@. The macro
2010@code{__NEXT_RUNTIME__} is predefined if (and only if) this option is
2011used.
2012
2013@item -fno-nil-receivers
2014@opindex fno-nil-receivers
2015Assume that all Objective-C message dispatches (e.g.,
2016@code{[receiver message:arg]}) in this translation unit ensure that the receiver
2017is not @code{nil}. This allows for more efficient entry points in the runtime
2018to be used. Currently, this option is only available in conjunction with
2019the NeXT runtime on Mac OS X 10.3 and later.
2020
2021@item -fobjc-call-cxx-cdtors
2022@opindex fobjc-call-cxx-cdtors
2023For each Objective-C class, check if any of its instance variables is a
2024C++ object with a non-trivial default constructor. If so, synthesize a
2025special @code{- (id) .cxx_construct} instance method that will run
2026non-trivial default constructors on any such instance variables, in order,
2027and then return @code{self}. Similarly, check if any instance variable
2028is a C++ object with a non-trivial destructor, and if so, synthesize a
2029special @code{- (void) .cxx_destruct} method that will run
2030all such default destructors, in reverse order.
2031
2032The @code{- (id) .cxx_construct} and/or @code{- (void) .cxx_destruct} methods
2033thusly generated will only operate on instance variables declared in the
2034current Objective-C class, and not those inherited from superclasses. It
2035is the responsibility of the Objective-C runtime to invoke all such methods
2036in an object's inheritance hierarchy. The @code{- (id) .cxx_construct} methods
2037will be invoked by the runtime immediately after a new object
2038instance is allocated; the @code{- (void) .cxx_destruct} methods will
2039be invoked immediately before the runtime deallocates an object instance.
2040
2041As of this writing, only the NeXT runtime on Mac OS X 10.4 and later has
2042support for invoking the @code{- (id) .cxx_construct} and
2043@code{- (void) .cxx_destruct} methods.
2044
2045@item -fobjc-direct-dispatch
2046@opindex fobjc-direct-dispatch
2047Allow fast jumps to the message dispatcher. On Darwin this is
2048accomplished via the comm page.
2049
2050@item -fobjc-exceptions
2051@opindex fobjc-exceptions
2052Enable syntactic support for structured exception handling in Objective-C,
2053similar to what is offered by C++ and Java. This option is
2054unavailable in conjunction with the NeXT runtime on Mac OS X 10.2 and
2055earlier.
2056
2057@smallexample
2058 @@try @{
2059 @dots{}
2060 @@throw expr;
2061 @dots{}
2062 @}
2063 @@catch (AnObjCClass *exc) @{
2064 @dots{}
2065 @@throw expr;
2066 @dots{}
2067 @@throw;
2068 @dots{}
2069 @}
2070 @@catch (AnotherClass *exc) @{
2071 @dots{}
2072 @}
2073 @@catch (id allOthers) @{
2074 @dots{}
2075 @}
2076 @@finally @{
2077 @dots{}
2078 @@throw expr;
2079 @dots{}
2080 @}
2081@end smallexample
2082
2083The @code{@@throw} statement may appear anywhere in an Objective-C or
2084Objective-C++ program; when used inside of a @code{@@catch} block, the
2085@code{@@throw} may appear without an argument (as shown above), in which case
2086the object caught by the @code{@@catch} will be rethrown.
2087
2088Note that only (pointers to) Objective-C objects may be thrown and
2089caught using this scheme. When an object is thrown, it will be caught
2090by the nearest @code{@@catch} clause capable of handling objects of that type,
2091analogously to how @code{catch} blocks work in C++ and Java. A
2092@code{@@catch(id @dots{})} clause (as shown above) may also be provided to catch
2093any and all Objective-C exceptions not caught by previous @code{@@catch}
2094clauses (if any).
2095
2096The @code{@@finally} clause, if present, will be executed upon exit from the
2097immediately preceding @code{@@try @dots{} @@catch} section. This will happen
2098regardless of whether any exceptions are thrown, caught or rethrown
2099inside the @code{@@try @dots{} @@catch} section, analogously to the behavior
2100of the @code{finally} clause in Java.
2101
2102There are several caveats to using the new exception mechanism:
2103
2104@itemize @bullet
2105@item
2106Although currently designed to be binary compatible with @code{NS_HANDLER}-style
2107idioms provided by the @code{NSException} class, the new
2108exceptions can only be used on Mac OS X 10.3 (Panther) and later
2109systems, due to additional functionality needed in the (NeXT) Objective-C
2110runtime.
2111
2112@item
2113As mentioned above, the new exceptions do not support handling
2114types other than Objective-C objects. Furthermore, when used from
2115Objective-C++, the Objective-C exception model does not interoperate with C++
2116exceptions at this time. This means you cannot @code{@@throw} an exception
2117from Objective-C and @code{catch} it in C++, or vice versa
2118(i.e., @code{throw @dots{} @@catch}).
2119@end itemize
2120
2121The @option{-fobjc-exceptions} switch also enables the use of synchronization
2122blocks for thread-safe execution:
2123
2124@smallexample
2125 @@synchronized (ObjCClass *guard) @{
2126 @dots{}
2127 @}
2128@end smallexample
2129
2130Upon entering the @code{@@synchronized} block, a thread of execution shall
2131first check whether a lock has been placed on the corresponding @code{guard}
2132object by another thread. If it has, the current thread shall wait until
2133the other thread relinquishes its lock. Once @code{guard} becomes available,
2134the current thread will place its own lock on it, execute the code contained in
2135the @code{@@synchronized} block, and finally relinquish the lock (thereby
2136making @code{guard} available to other threads).
2137
2138Unlike Java, Objective-C does not allow for entire methods to be marked
2139@code{@@synchronized}. Note that throwing exceptions out of
2140@code{@@synchronized} blocks is allowed, and will cause the guarding object
2141to be unlocked properly.
2142
2143@item -fobjc-gc
2144@opindex fobjc-gc
2145Enable garbage collection (GC) in Objective-C and Objective-C++ programs.
2146
2147@item -freplace-objc-classes
2148@opindex freplace-objc-classes
2149Emit a special marker instructing @command{ld(1)} not to statically link in
2150the resulting object file, and allow @command{dyld(1)} to load it in at
2151run time instead. This is used in conjunction with the Fix-and-Continue
2152debugging mode, where the object file in question may be recompiled and
2153dynamically reloaded in the course of program execution, without the need
2154to restart the program itself. Currently, Fix-and-Continue functionality
2155is only available in conjunction with the NeXT runtime on Mac OS X 10.3
2156and later.
2157
2158@item -fzero-link
2159@opindex fzero-link
2160When compiling for the NeXT runtime, the compiler ordinarily replaces calls
2161to @code{objc_getClass("@dots{}")} (when the name of the class is known at
2162compile time) with static class references that get initialized at load time,
2163which improves run-time performance. Specifying the @option{-fzero-link} flag
2164suppresses this behavior and causes calls to @code{objc_getClass("@dots{}")}
2165to be retained. This is useful in Zero-Link debugging mode, since it allows
2166for individual class implementations to be modified during program execution.
2167
2168@item -gen-decls
2169@opindex gen-decls
2170Dump interface declarations for all classes seen in the source file to a
2171file named @file{@var{sourcename}.decl}.
2172
2173@item -Wassign-intercept
2174@opindex Wassign-intercept
2175Warn whenever an Objective-C assignment is being intercepted by the
2176garbage collector.
2177
2178@item -Wno-protocol
2179@opindex Wno-protocol
2180If a class is declared to implement a protocol, a warning is issued for
2181every method in the protocol that is not implemented by the class. The
2182default behavior is to issue a warning for every method not explicitly
2183implemented in the class, even if a method implementation is inherited
2184from the superclass. If you use the @option{-Wno-protocol} option, then
2185methods inherited from the superclass are considered to be implemented,
2186and no warning is issued for them.
2187
2188@item -Wselector
2189@opindex Wselector
2190Warn if multiple methods of different types for the same selector are
2191found during compilation. The check is performed on the list of methods
2192in the final stage of compilation. Additionally, a check is performed
2193for each selector appearing in a @code{@@selector(@dots{})}
2194expression, and a corresponding method for that selector has been found
2195during compilation. Because these checks scan the method table only at
2196the end of compilation, these warnings are not produced if the final
2197stage of compilation is not reached, for example because an error is
2198found during compilation, or because the @option{-fsyntax-only} option is
2199being used.
2200
2201@item -Wstrict-selector-match
2202@opindex Wstrict-selector-match
2203Warn if multiple methods with differing argument and/or return types are
2204found for a given selector when attempting to send a message using this
2205selector to a receiver of type @code{id} or @code{Class}. When this flag
2206is off (which is the default behavior), the compiler will omit such warnings
2207if any differences found are confined to types which share the same size
2208and alignment.
2209
2210@item -Wundeclared-selector
2211@opindex Wundeclared-selector
2212Warn if a @code{@@selector(@dots{})} expression referring to an
2213undeclared selector is found. A selector is considered undeclared if no
2214method with that name has been declared before the
2215@code{@@selector(@dots{})} expression, either explicitly in an
2216@code{@@interface} or @code{@@protocol} declaration, or implicitly in
2217an @code{@@implementation} section. This option always performs its
2218checks as soon as a @code{@@selector(@dots{})} expression is found,
2219while @option{-Wselector} only performs its checks in the final stage of
2220compilation. This also enforces the coding style convention
2221that methods and selectors must be declared before being used.
2222
2223@item -print-objc-runtime-info
2224@opindex print-objc-runtime-info
2225Generate C header describing the largest structure that is passed by
2226value, if any.
2227
2228@end table
2229
2230@node Language Independent Options
2231@section Options to Control Diagnostic Messages Formatting
2232@cindex options to control diagnostics formatting
2233@cindex diagnostic messages
2234@cindex message formatting
2235
2236Traditionally, diagnostic messages have been formatted irrespective of
2237the output device's aspect (e.g.@: its width, @dots{}). The options described
2238below can be used to control the diagnostic messages formatting
2239algorithm, e.g.@: how many characters per line, how often source location
2240information should be reported. Right now, only the C++ front end can
2241honor these options. However it is expected, in the near future, that
2242the remaining front ends would be able to digest them correctly.
2243
2244@table @gcctabopt
2245@item -fmessage-length=@var{n}
2246@opindex fmessage-length
2247Try to format error messages so that they fit on lines of about @var{n}
2248characters. The default is 72 characters for @command{g++} and 0 for the rest of
2249the front ends supported by GCC@. If @var{n} is zero, then no
2250line-wrapping will be done; each error message will appear on a single
2251line.
2252
2253@opindex fdiagnostics-show-location
2254@item -fdiagnostics-show-location=once
2255Only meaningful in line-wrapping mode. Instructs the diagnostic messages
2256reporter to emit @emph{once} source location information; that is, in
2257case the message is too long to fit on a single physical line and has to
2258be wrapped, the source location won't be emitted (as prefix) again,
2259over and over, in subsequent continuation lines. This is the default
2260behavior.
2261
2262@item -fdiagnostics-show-location=every-line
2263Only meaningful in line-wrapping mode. Instructs the diagnostic
2264messages reporter to emit the same source location information (as
2265prefix) for physical lines that result from the process of breaking
2266a message which is too long to fit on a single line.
2267
2268@item -fdiagnostics-show-option
2269@opindex fdiagnostics-show-option
2270This option instructs the diagnostic machinery to add text to each
2271diagnostic emitted, which indicates which command line option directly
2272controls that diagnostic, when such an option is known to the
2273diagnostic machinery.
2274
2275@end table
2276
2277@node Warning Options
2278@section Options to Request or Suppress Warnings
2279@cindex options to control warnings
2280@cindex warning messages
2281@cindex messages, warning
2282@cindex suppressing warnings
2283
2284Warnings are diagnostic messages that report constructions which
2285are not inherently erroneous but which are risky or suggest there
2286may have been an error.
2287
2288You can request many specific warnings with options beginning @samp{-W},
2289for example @option{-Wimplicit} to request warnings on implicit
2290declarations. Each of these specific warning options also has a
2291negative form beginning @samp{-Wno-} to turn off warnings;
2292for example, @option{-Wno-implicit}. This manual lists only one of the
2293two forms, whichever is not the default.
2294
2295The following options control the amount and kinds of warnings produced
2296by GCC; for further, language-specific options also refer to
2297@ref{C++ Dialect Options} and @ref{Objective-C and Objective-C++ Dialect
2298Options}.
2299
2300@table @gcctabopt
2301@cindex syntax checking
2302@item -fsyntax-only
2303@opindex fsyntax-only
2304Check the code for syntax errors, but don't do anything beyond that.
2305
2306@item -pedantic
2307@opindex pedantic
2308Issue all the warnings demanded by strict ISO C and ISO C++;
2309reject all programs that use forbidden extensions, and some other
2310programs that do not follow ISO C and ISO C++. For ISO C, follows the
2311version of the ISO C standard specified by any @option{-std} option used.
2312
2313Valid ISO C and ISO C++ programs should compile properly with or without
2314this option (though a rare few will require @option{-ansi} or a
2315@option{-std} option specifying the required version of ISO C)@. However,
2316without this option, certain GNU extensions and traditional C and C++
2317features are supported as well. With this option, they are rejected.
2318
2319@option{-pedantic} does not cause warning messages for use of the
2320alternate keywords whose names begin and end with @samp{__}. Pedantic
2321warnings are also disabled in the expression that follows
2322@code{__extension__}. However, only system header files should use
2323these escape routes; application programs should avoid them.
2324@xref{Alternate Keywords}.
2325
2326Some users try to use @option{-pedantic} to check programs for strict ISO
2327C conformance. They soon find that it does not do quite what they want:
2328it finds some non-ISO practices, but not all---only those for which
2329ISO C @emph{requires} a diagnostic, and some others for which
2330diagnostics have been added.
2331
2332A feature to report any failure to conform to ISO C might be useful in
2333some instances, but would require considerable additional work and would
2334be quite different from @option{-pedantic}. We don't have plans to
2335support such a feature in the near future.
2336
2337Where the standard specified with @option{-std} represents a GNU
2338extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
2339corresponding @dfn{base standard}, the version of ISO C on which the GNU
2340extended dialect is based. Warnings from @option{-pedantic} are given
2341where they are required by the base standard. (It would not make sense
2342for such warnings to be given only for features not in the specified GNU
2343C dialect, since by definition the GNU dialects of C include all
2344features the compiler supports with the given option, and there would be
2345nothing to warn about.)
2346
2347@item -pedantic-errors
2348@opindex pedantic-errors
2349Like @option{-pedantic}, except that errors are produced rather than
2350warnings.
2351
2352@item -w
2353@opindex w
2354Inhibit all warning messages.
2355
2356@item -Wno-import
2357@opindex Wno-import
2358Inhibit warning messages about the use of @samp{#import}.
2359
2360@item -Wchar-subscripts
2361@opindex Wchar-subscripts
2362Warn if an array subscript has type @code{char}. This is a common cause
2363of error, as programmers often forget that this type is signed on some
2364machines.
2365This warning is enabled by @option{-Wall}.
2366
2367@item -Wcomment
2368@opindex Wcomment
2369Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
2370comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
2371This warning is enabled by @option{-Wall}.
2372
2373@item -Wfatal-errors
2374@opindex Wfatal-errors
2375This option causes the compiler to abort compilation on the first error
2376occurred rather than trying to keep going and printing further error
2377messages.
2378
2379@item -Wformat
2380@opindex Wformat
2381@opindex ffreestanding
2382@opindex fno-builtin
2383Check calls to @code{printf} and @code{scanf}, etc., to make sure that
2384the arguments supplied have types appropriate to the format string
2385specified, and that the conversions specified in the format string make
2386sense. This includes standard functions, and others specified by format
2387attributes (@pxref{Function Attributes}), in the @code{printf},
2388@code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
2389not in the C standard) families (or other target-specific families).
2390Which functions are checked without format attributes having been
2391specified depends on the standard version selected, and such checks of
2392functions without the attribute specified are disabled by
2393@option{-ffreestanding} or @option{-fno-builtin}.
2394
2395The formats are checked against the format features supported by GNU
2396libc version 2.2. These include all ISO C90 and C99 features, as well
2397as features from the Single Unix Specification and some BSD and GNU
2398extensions. Other library implementations may not support all these
2399features; GCC does not support warning about features that go beyond a
2400particular library's limitations. However, if @option{-pedantic} is used
2401with @option{-Wformat}, warnings will be given about format features not
2402in the selected standard version (but not for @code{strfmon} formats,
2403since those are not in any version of the C standard). @xref{C Dialect
2404Options,,Options Controlling C Dialect}.
2405
2406Since @option{-Wformat} also checks for null format arguments for
2407several functions, @option{-Wformat} also implies @option{-Wnonnull}.
2408
2409@option{-Wformat} is included in @option{-Wall}. For more control over some
2410aspects of format checking, the options @option{-Wformat-y2k},
2411@option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
2412@option{-Wformat-nonliteral}, @option{-Wformat-security}, and
2413@option{-Wformat=2} are available, but are not included in @option{-Wall}.
2414
2415@item -Wformat-y2k
2416@opindex Wformat-y2k
2417If @option{-Wformat} is specified, also warn about @code{strftime}
2418formats which may yield only a two-digit year.
2419
2420@item -Wno-format-extra-args
2421@opindex Wno-format-extra-args
2422If @option{-Wformat} is specified, do not warn about excess arguments to a
2423@code{printf} or @code{scanf} format function. The C standard specifies
2424that such arguments are ignored.
2425
2426Where the unused arguments lie between used arguments that are
2427specified with @samp{$} operand number specifications, normally
2428warnings are still given, since the implementation could not know what
2429type to pass to @code{va_arg} to skip the unused arguments. However,
2430in the case of @code{scanf} formats, this option will suppress the
2431warning if the unused arguments are all pointers, since the Single
2432Unix Specification says that such unused arguments are allowed.
2433
2434@item -Wno-format-zero-length
2435@opindex Wno-format-zero-length
2436If @option{-Wformat} is specified, do not warn about zero-length formats.
2437The C standard specifies that zero-length formats are allowed.
2438
2439@item -Wformat-nonliteral
2440@opindex Wformat-nonliteral
2441If @option{-Wformat} is specified, also warn if the format string is not a
2442string literal and so cannot be checked, unless the format function
2443takes its format arguments as a @code{va_list}.
2444
2445@item -Wformat-security
2446@opindex Wformat-security
2447If @option{-Wformat} is specified, also warn about uses of format
2448functions that represent possible security problems. At present, this
2449warns about calls to @code{printf} and @code{scanf} functions where the
2450format string is not a string literal and there are no format arguments,
2451as in @code{printf (foo);}. This may be a security hole if the format
2452string came from untrusted input and contains @samp{%n}. (This is
2453currently a subset of what @option{-Wformat-nonliteral} warns about, but
2454in future warnings may be added to @option{-Wformat-security} that are not
2455included in @option{-Wformat-nonliteral}.)
2456
2457@item -Wformat=2
2458@opindex Wformat=2
2459Enable @option{-Wformat} plus format checks not included in
2460@option{-Wformat}. Currently equivalent to @samp{-Wformat
2461-Wformat-nonliteral -Wformat-security -Wformat-y2k}.
2462
2463@item -Wnonnull
2464@opindex Wnonnull
2465Warn about passing a null pointer for arguments marked as
2466requiring a non-null value by the @code{nonnull} function attribute.
2467
2468@option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It
2469can be disabled with the @option{-Wno-nonnull} option.
2470
2471@item -Winit-self @r{(C, C++, Objective-C and Objective-C++ only)}
2472@opindex Winit-self
2473Warn about uninitialized variables which are initialized with themselves.
2474Note this option can only be used with the @option{-Wuninitialized} option,
2475which in turn only works with @option{-O1} and above.
2476
2477For example, GCC will warn about @code{i} being uninitialized in the
2478following snippet only when @option{-Winit-self} has been specified:
2479@smallexample
2480@group
2481int f()
2482@{
2483 int i = i;
2484 return i;
2485@}
2486@end group
2487@end smallexample
2488
2489@item -Wimplicit-int
2490@opindex Wimplicit-int
2491Warn when a declaration does not specify a type.
2492This warning is enabled by @option{-Wall}.
2493
2494@item -Wimplicit-function-declaration
2495@itemx -Werror-implicit-function-declaration
2496@opindex Wimplicit-function-declaration
2497@opindex Werror-implicit-function-declaration
2498Give a warning (or error) whenever a function is used before being
2499declared. The form @option{-Wno-error-implicit-function-declaration}
2500is not supported.
2501This warning is enabled by @option{-Wall} (as a warning, not an error).
2502
2503@item -Wimplicit
2504@opindex Wimplicit
2505Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
2506This warning is enabled by @option{-Wall}.
2507
2508@item -Wmain
2509@opindex Wmain
2510Warn if the type of @samp{main} is suspicious. @samp{main} should be a
2511function with external linkage, returning int, taking either zero
2512arguments, two, or three arguments of appropriate types.
2513This warning is enabled by @option{-Wall}.
2514
2515@item -Wmissing-braces
2516@opindex Wmissing-braces
2517Warn if an aggregate or union initializer is not fully bracketed. In
2518the following example, the initializer for @samp{a} is not fully
2519bracketed, but that for @samp{b} is fully bracketed.
2520
2521@smallexample
2522int a[2][2] = @{ 0, 1, 2, 3 @};
2523int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
2524@end smallexample
2525
2526This warning is enabled by @option{-Wall}.
2527
2528@item -Wmissing-include-dirs @r{(C, C++, Objective-C and Objective-C++ only)}
2529@opindex Wmissing-include-dirs
2530Warn if a user-supplied include directory does not exist.
2531
2532@item -Wparentheses
2533@opindex Wparentheses
2534Warn if parentheses are omitted in certain contexts, such
2535as when there is an assignment in a context where a truth value
2536is expected, or when operators are nested whose precedence people
2537often get confused about. Only the warning for an assignment used as
2538a truth value is supported when compiling C++; the other warnings are
2539only supported when compiling C@.
2540
2541Also warn if a comparison like @samp{x<=y<=z} appears; this is
2542equivalent to @samp{(x<=y ? 1 : 0) <= z}, which is a different
2543interpretation from that of ordinary mathematical notation.
2544
2545Also warn about constructions where there may be confusion to which
2546@code{if} statement an @code{else} branch belongs. Here is an example of
2547such a case:
2548
2549@smallexample
2550@group
2551@{
2552 if (a)
2553 if (b)
2554 foo ();
2555 else
2556 bar ();
2557@}
2558@end group
2559@end smallexample
2560
2561In C, every @code{else} branch belongs to the innermost possible @code{if}
2562statement, which in this example is @code{if (b)}. This is often not
2563what the programmer expected, as illustrated in the above example by
2564indentation the programmer chose. When there is the potential for this
2565confusion, GCC will issue a warning when this flag is specified.
2566To eliminate the warning, add explicit braces around the innermost
2567@code{if} statement so there is no way the @code{else} could belong to
2568the enclosing @code{if}. The resulting code would look like this:
2569
2570@smallexample
2571@group
2572@{
2573 if (a)
2574 @{
2575 if (b)
2576 foo ();
2577 else
2578 bar ();
2579 @}
2580@}
2581@end group
2582@end smallexample
2583
2584This warning is enabled by @option{-Wall}.
2585
2586@item -Wsequence-point
2587@opindex Wsequence-point
2588Warn about code that may have undefined semantics because of violations
2589of sequence point rules in the C and C++ standards.
2590
2591The C and C++ standards defines the order in which expressions in a C/C++
2592program are evaluated in terms of @dfn{sequence points}, which represent
2593a partial ordering between the execution of parts of the program: those
2594executed before the sequence point, and those executed after it. These
2595occur after the evaluation of a full expression (one which is not part
2596of a larger expression), after the evaluation of the first operand of a
2597@code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
2598function is called (but after the evaluation of its arguments and the
2599expression denoting the called function), and in certain other places.
2600Other than as expressed by the sequence point rules, the order of
2601evaluation of subexpressions of an expression is not specified. All
2602these rules describe only a partial order rather than a total order,
2603since, for example, if two functions are called within one expression
2604with no sequence point between them, the order in which the functions
2605are called is not specified. However, the standards committee have
2606ruled that function calls do not overlap.
2607
2608It is not specified when between sequence points modifications to the
2609values of objects take effect. Programs whose behavior depends on this
2610have undefined behavior; the C and C++ standards specify that ``Between
2611the previous and next sequence point an object shall have its stored
2612value modified at most once by the evaluation of an expression.
2613Furthermore, the prior value shall be read only to determine the value
2614to be stored.''. If a program breaks these rules, the results on any
2615particular implementation are entirely unpredictable.
2616
2617Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
2618= b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
2619diagnosed by this option, and it may give an occasional false positive
2620result, but in general it has been found fairly effective at detecting
2621this sort of problem in programs.
2622
2623The standard is worded confusingly, therefore there is some debate
2624over the precise meaning of the sequence point rules in subtle cases.
2625Links to discussions of the problem, including proposed formal
2626definitions, may be found on the GCC readings page, at
2627@w{@uref{http://gcc.gnu.org/readings.html}}.
2628
2629This warning is enabled by @option{-Wall} for C and C++.
2630
2631@item -Wreturn-type
2632@opindex Wreturn-type
2633Warn whenever a function is defined with a return-type that defaults to
2634@code{int}. Also warn about any @code{return} statement with no
2635return-value in a function whose return-type is not @code{void}.
2636
2637For C, also warn if the return type of a function has a type qualifier
2638such as @code{const}. Such a type qualifier has no effect, since the
2639value returned by a function is not an lvalue. ISO C prohibits
2640qualified @code{void} return types on function definitions, so such
2641return types always receive a warning even without this option.
2642
2643For C++, a function without return type always produces a diagnostic
2644message, even when @option{-Wno-return-type} is specified. The only
2645exceptions are @samp{main} and functions defined in system headers.
2646
2647This warning is enabled by @option{-Wall}.
2648
2649@item -Wswitch
2650@opindex Wswitch
2651Warn whenever a @code{switch} statement has an index of enumerated type
2652and lacks a @code{case} for one or more of the named codes of that
2653enumeration. (The presence of a @code{default} label prevents this
2654warning.) @code{case} labels outside the enumeration range also
2655provoke warnings when this option is used.
2656This warning is enabled by @option{-Wall}.
2657
2658@item -Wswitch-default
2659@opindex Wswitch-switch
2660Warn whenever a @code{switch} statement does not have a @code{default}
2661case.
2662
2663@item -Wswitch-enum
2664@opindex Wswitch-enum
2665Warn whenever a @code{switch} statement has an index of enumerated type
2666and lacks a @code{case} for one or more of the named codes of that
2667enumeration. @code{case} labels outside the enumeration range also
2668provoke warnings when this option is used.
2669
2670@item -Wtrigraphs
2671@opindex Wtrigraphs
2672Warn if any trigraphs are encountered that might change the meaning of
2673the program (trigraphs within comments are not warned about).
2674This warning is enabled by @option{-Wall}.
2675
2676@item -Wunused-function
2677@opindex Wunused-function
2678Warn whenever a static function is declared but not defined or a
2679non-inline static function is unused.
2680This warning is enabled by @option{-Wall}.
2681
2682@item -Wunused-label
2683@opindex Wunused-label
2684Warn whenever a label is declared but not used.
2685This warning is enabled by @option{-Wall}.
2686
2687To suppress this warning use the @samp{unused} attribute
2688(@pxref{Variable Attributes}).
2689
2690@item -Wunused-parameter
2691@opindex Wunused-parameter
2692Warn whenever a function parameter is unused aside from its declaration.
2693
2694To suppress this warning use the @samp{unused} attribute
2695(@pxref{Variable Attributes}).
2696
2697@item -Wunused-variable
2698@opindex Wunused-variable
2699Warn whenever a local variable or non-constant static variable is unused
2700aside from its declaration.
2701This warning is enabled by @option{-Wall}.
2702
2703To suppress this warning use the @samp{unused} attribute
2704(@pxref{Variable Attributes}).
2705
2706@item -Wunused-value
2707@opindex Wunused-value
2708Warn whenever a statement computes a result that is explicitly not used.
2709This warning is enabled by @option{-Wall}.
2710
2711To suppress this warning cast the expression to @samp{void}.
2712
2713@item -Wunused
2714@opindex Wunused
2715All the above @option{-Wunused} options combined.
2716
2717In order to get a warning about an unused function parameter, you must
2718either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
2719@samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
2720
2721@item -Wuninitialized
2722@opindex Wuninitialized
2723Warn if an automatic variable is used without first being initialized or
2724if a variable may be clobbered by a @code{setjmp} call.
2725
2726These warnings are possible only in optimizing compilation,
2727because they require data flow information that is computed only
2728when optimizing. If you do not specify @option{-O}, you will not get
2729these warnings. Instead, GCC will issue a warning about @option{-Wuninitialized}
2730requiring @option{-O}.
2731
2732If you want to warn about code which uses the uninitialized value of the
2733variable in its own initializer, use the @option{-Winit-self} option.
2734
2735These warnings occur for individual uninitialized or clobbered
2736elements of structure, union or array variables as well as for
2737variables which are uninitialized or clobbered as a whole. They do
2738not occur for variables or elements declared @code{volatile}. Because
2739these warnings depend on optimization, the exact variables or elements
2740for which there are warnings will depend on the precise optimization
2741options and version of GCC used.
2742
2743Note that there may be no warning about a variable that is used only
2744to compute a value that itself is never used, because such
2745computations may be deleted by data flow analysis before the warnings
2746are printed.
2747
2748These warnings are made optional because GCC is not smart
2749enough to see all the reasons why the code might be correct
2750despite appearing to have an error. Here is one example of how
2751this can happen:
2752
2753@smallexample
2754@group
2755@{
2756 int x;
2757 switch (y)
2758 @{
2759 case 1: x = 1;
2760 break;
2761 case 2: x = 4;
2762 break;
2763 case 3: x = 5;
2764 @}
2765 foo (x);
2766@}
2767@end group
2768@end smallexample
2769
2770@noindent
2771If the value of @code{y} is always 1, 2 or 3, then @code{x} is
2772always initialized, but GCC doesn't know this. Here is
2773another common case:
2774
2775@smallexample
2776@{
2777 int save_y;
2778 if (change_y) save_y = y, y = new_y;
2779 @dots{}
2780 if (change_y) y = save_y;
2781@}
2782@end smallexample
2783
2784@noindent
2785This has no bug because @code{save_y} is used only if it is set.
2786
2787@cindex @code{longjmp} warnings
2788This option also warns when a non-volatile automatic variable might be
2789changed by a call to @code{longjmp}. These warnings as well are possible
2790only in optimizing compilation.
2791
2792The compiler sees only the calls to @code{setjmp}. It cannot know
2793where @code{longjmp} will be called; in fact, a signal handler could
2794call it at any point in the code. As a result, you may get a warning
2795even when there is in fact no problem because @code{longjmp} cannot
2796in fact be called at the place which would cause a problem.
2797
2798Some spurious warnings can be avoided if you declare all the functions
2799you use that never return as @code{noreturn}. @xref{Function
2800Attributes}.
2801
2802This warning is enabled by @option{-Wall}.
2803
2804@item -Wunknown-pragmas
2805@opindex Wunknown-pragmas
2806@cindex warning for unknown pragmas
2807@cindex unknown pragmas, warning
2808@cindex pragmas, warning of unknown
2809Warn when a #pragma directive is encountered which is not understood by
2810GCC@. If this command line option is used, warnings will even be issued
2811for unknown pragmas in system header files. This is not the case if
2812the warnings were only enabled by the @option{-Wall} command line option.
2813
2814@item -Wno-pragmas
2815@opindex Wno-pragmas
2816@opindex Wpragmas
2817Do not warn about misuses of pragmas, such as incorrect parameters,
2818invalid syntax, or conflicts between pragmas. See also
2819@samp{-Wunknown-pragmas}.
2820
2821@item -Wstrict-aliasing
2822@opindex Wstrict-aliasing
2823This option is only active when @option{-fstrict-aliasing} is active.
2824It warns about code which might break the strict aliasing rules that the
2825compiler is using for optimization. The warning does not catch all
2826cases, but does attempt to catch the more common pitfalls. It is
2827included in @option{-Wall}.
2828
2829@item -Wstrict-aliasing=2
2830@opindex Wstrict-aliasing=2
2831This option is only active when @option{-fstrict-aliasing} is active.
2832It warns about code which might break the strict aliasing rules that the
2833compiler is using for optimization. This warning catches more cases than
2834@option{-Wstrict-aliasing}, but it will also give a warning for some ambiguous
2835cases that are safe.
2836
2837@item -Wstrict-overflow
2838@item -Wstrict-overflow=@var{n}
2839@opindex Wstrict-overflow
2840This option is only active when @option{-fstrict-overflow} is active.
2841It warns about cases where the compiler optimizes based on the
2842assumption that signed overflow does not occur. Note that it does not
2843warn about all cases where the code might overflow: it only warns
2844about cases where the compiler implements some optimization. Thus
2845this warning depends on the optimization level.
2846
2847An optimization which assumes that signed overflow does not occur is
2848perfectly safe if the values of the variables involved are such that
2849overflow never does, in fact, occur. Therefore this warning can
2850easily give a false positive: a warning about code which is not
2851actually a problem. To help focus on important issues, several
2852warning levels are defined. No warnings are issued for the use of
2853undefined signed overflow when estimating how many iterations a loop
2854will require, in particular when determining whether a loop will be
2855executed at all.
2856
2857@table @option
2858@item -Wstrict-overflow=1
2859Warn about cases which are both questionable and easy to avoid. For
2860example: @code{x + 1 > x}; with @option{-fstrict-overflow}, the
2861compiler will simplify this to @code{1}. This level of
2862@option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
2863are not, and must be explicitly requested.
2864
2865@item -Wstrict-overflow=2
2866Also warn about other cases where a comparison is simplified to a
2867constant. For example: @code{abs (x) >= 0}. This can only be
2868simplified when @option{-fstrict-overflow} is in effect, because
2869@code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
2870zero. @option{-Wstrict-overflow} (with no level) is the same as
2871@option{-Wstrict-overflow=2}.
2872
2873@item -Wstrict-overflow=3
2874Also warn about other cases where a comparison is simplified. For
2875example: @code{x + 1 > 1} will be simplified to @code{x > 0}.
2876
2877@item -Wstrict-overflow=4
2878Also warn about other simplifications not covered by the above cases.
2879For example: @code{(x * 10) / 5} will be simplified to @code{x * 2}.
2880
2881@item -Wstrict-overflow=5
2882Also warn about cases where the compiler reduces the magnitude of a
2883constant involved in a comparison. For example: @code{x + 2 > y} will
2884be simplified to @code{x + 1 >= y}. This is reported only at the
2885highest warning level because this simplification applies to many
2886comparisons, so this warning level will give a very large number of
2887false positives.
2888@end table
2889
2890@item -Wall
2891@opindex Wall
2892All of the above @samp{-W} options combined. This enables all the
2893warnings about constructions that some users consider questionable, and
2894that are easy to avoid (or modify to prevent the warning), even in
2895conjunction with macros. This also enables some language-specific
2896warnings described in @ref{C++ Dialect Options} and
2897@ref{Objective-C and Objective-C++ Dialect Options}.
2898@end table
2899
2900The following @option{-W@dots{}} options are not implied by @option{-Wall}.
2901Some of them warn about constructions that users generally do not
2902consider questionable, but which occasionally you might wish to check
2903for; others warn about constructions that are necessary or hard to avoid
2904in some cases, and there is no simple way to modify the code to suppress
2905the warning.
2906
2907@table @gcctabopt
2908@item -Wextra
2909@opindex W
2910@opindex Wextra
2911(This option used to be called @option{-W}. The older name is still
2912supported, but the newer name is more descriptive.) Print extra warning
2913messages for these events:
2914
2915@itemize @bullet
2916@item
2917A function can return either with or without a value. (Falling
2918off the end of the function body is considered returning without
2919a value.) For example, this function would evoke such a
2920warning:
2921
2922@smallexample
2923@group
2924foo (a)
2925@{
2926 if (a > 0)
2927 return a;
2928@}
2929@end group
2930@end smallexample
2931
2932@item
2933An expression-statement or the left-hand side of a comma expression
2934contains no side effects.
2935To suppress the warning, cast the unused expression to void.
2936For example, an expression such as @samp{x[i,j]} will cause a warning,
2937but @samp{x[(void)i,j]} will not.
2938
2939@item
2940An unsigned value is compared against zero with @samp{<} or @samp{>=}.
2941
2942@item
2943Storage-class specifiers like @code{static} are not the first things in
2944a declaration. According to the C Standard, this usage is obsolescent.
2945
2946@item
2947If @option{-Wall} or @option{-Wunused} is also specified, warn about unused
2948arguments.
2949
2950@item
2951A comparison between signed and unsigned values could produce an
2952incorrect result when the signed value is converted to unsigned.
2953(But don't warn if @option{-Wno-sign-compare} is also specified.)
2954
2955@item
2956An aggregate has an initializer which does not initialize all members.
2957This warning can be independently controlled by
2958@option{-Wmissing-field-initializers}.
2959
2960@item
2961An initialized field without side effects is overridden when using
2962designated initializers (@pxref{Designated Inits, , Designated
2963Initializers}). This warning can be independently controlled by
2964@option{-Woverride-init}.
2965
2966@item
2967A function parameter is declared without a type specifier in K&R-style
2968functions:
2969
2970@smallexample
2971void foo(bar) @{ @}
2972@end smallexample
2973
2974@item
2975An empty body occurs in an @samp{if} or @samp{else} statement.
2976
2977@item
2978A pointer is compared against integer zero with @samp{<}, @samp{<=},
2979@samp{>}, or @samp{>=}.
2980
2981@item
2982A variable might be changed by @samp{longjmp} or @samp{vfork}.
2983
2984@item @r{(C++ only)}
2985An enumerator and a non-enumerator both appear in a conditional expression.
2986
2987@item @r{(C++ only)}
2988A non-static reference or non-static @samp{const} member appears in a
2989class without constructors.
2990
2991@item @r{(C++ only)}
2992Ambiguous virtual bases.
2993
2994@item @r{(C++ only)}
2995Subscripting an array which has been declared @samp{register}.
2996
2997@item @r{(C++ only)}
2998Taking the address of a variable which has been declared @samp{register}.
2999
3000@item @r{(C++ only)}
3001A base class is not initialized in a derived class' copy constructor.
3002@end itemize
3003
3004@item -Wno-div-by-zero
3005@opindex Wno-div-by-zero
3006@opindex Wdiv-by-zero
3007Do not warn about compile-time integer division by zero. Floating point
3008division by zero is not warned about, as it can be a legitimate way of
3009obtaining infinities and NaNs.
3010
3011@item -Wsystem-headers
3012@opindex Wsystem-headers
3013@cindex warnings from system headers
3014@cindex system headers, warnings from
3015Print warning messages for constructs found in system header files.
3016Warnings from system headers are normally suppressed, on the assumption
3017that they usually do not indicate real problems and would only make the
3018compiler output harder to read. Using this command line option tells
3019GCC to emit warnings from system headers as if they occurred in user
3020code. However, note that using @option{-Wall} in conjunction with this
3021option will @emph{not} warn about unknown pragmas in system
3022headers---for that, @option{-Wunknown-pragmas} must also be used.
3023
3024@item -Wfloat-equal
3025@opindex Wfloat-equal
3026Warn if floating point values are used in equality comparisons.
3027
3028The idea behind this is that sometimes it is convenient (for the
3029programmer) to consider floating-point values as approximations to
3030infinitely precise real numbers. If you are doing this, then you need
3031to compute (by analyzing the code, or in some other way) the maximum or
3032likely maximum error that the computation introduces, and allow for it
3033when performing comparisons (and when producing output, but that's a
3034different problem). In particular, instead of testing for equality, you
3035would check to see whether the two values have ranges that overlap; and
3036this is done with the relational operators, so equality comparisons are
3037probably mistaken.
3038
3039@item -Wtraditional @r{(C only)}
3040@opindex Wtraditional
3041Warn about certain constructs that behave differently in traditional and
3042ISO C@. Also warn about ISO C constructs that have no traditional C
3043equivalent, and/or problematic constructs which should be avoided.
3044
3045@itemize @bullet
3046@item
3047Macro parameters that appear within string literals in the macro body.
3048In traditional C macro replacement takes place within string literals,
3049but does not in ISO C@.
3050
3051@item
3052In traditional C, some preprocessor directives did not exist.
3053Traditional preprocessors would only consider a line to be a directive
3054if the @samp{#} appeared in column 1 on the line. Therefore
3055@option{-Wtraditional} warns about directives that traditional C
3056understands but would ignore because the @samp{#} does not appear as the
3057first character on the line. It also suggests you hide directives like
3058@samp{#pragma} not understood by traditional C by indenting them. Some
3059traditional implementations would not recognize @samp{#elif}, so it
3060suggests avoiding it altogether.
3061
3062@item
3063A function-like macro that appears without arguments.
3064
3065@item
3066The unary plus operator.
3067
3068@item
3069The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
3070constant suffixes. (Traditional C does support the @samp{L} suffix on integer
3071constants.) Note, these suffixes appear in macros defined in the system
3072headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
3073Use of these macros in user code might normally lead to spurious
3074warnings, however GCC's integrated preprocessor has enough context to
3075avoid warning in these cases.
3076
3077@item
3078A function declared external in one block and then used after the end of
3079the block.
3080
3081@item
3082A @code{switch} statement has an operand of type @code{long}.
3083
3084@item
3085A non-@code{static} function declaration follows a @code{static} one.
3086This construct is not accepted by some traditional C compilers.
3087
3088@item
3089The ISO type of an integer constant has a different width or
3090signedness from its traditional type. This warning is only issued if
3091the base of the constant is ten. I.e.@: hexadecimal or octal values, which
3092typically represent bit patterns, are not warned about.
3093
3094@item
3095Usage of ISO string concatenation is detected.
3096
3097@item
3098Initialization of automatic aggregates.
3099
3100@item
3101Identifier conflicts with labels. Traditional C lacks a separate
3102namespace for labels.
3103
3104@item
3105Initialization of unions. If the initializer is zero, the warning is
3106omitted. This is done under the assumption that the zero initializer in
3107user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
3108initializer warnings and relies on default initialization to zero in the
3109traditional C case.
3110
3111@item
3112Conversions by prototypes between fixed/floating point values and vice
3113versa. The absence of these prototypes when compiling with traditional
3114C would cause serious problems. This is a subset of the possible
3115conversion warnings, for the full set use @option{-Wconversion}.
3116
3117@item
3118Use of ISO C style function definitions. This warning intentionally is
3119@emph{not} issued for prototype declarations or variadic functions
3120because these ISO C features will appear in your code when using
3121libiberty's traditional C compatibility macros, @code{PARAMS} and
3122@code{VPARAMS}. This warning is also bypassed for nested functions
3123because that feature is already a GCC extension and thus not relevant to
3124traditional C compatibility.
3125@end itemize
3126
3127@item -Wdeclaration-after-statement @r{(C only)}
3128@opindex Wdeclaration-after-statement
3129Warn when a declaration is found after a statement in a block. This
3130construct, known from C++, was introduced with ISO C99 and is by default
3131allowed in GCC@. It is not supported by ISO C90 and was not supported by
3132GCC versions before GCC 3.0. @xref{Mixed Declarations}.
3133
3134@item -Wundef
3135@opindex Wundef
3136Warn if an undefined identifier is evaluated in an @samp{#if} directive.
3137
3138@item -Wno-endif-labels
3139@opindex Wno-endif-labels
3140@opindex Wendif-labels
3141Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
3142
3143@item -Wshadow
3144@opindex Wshadow
3145Warn whenever a local variable shadows another local variable, parameter or
3146global variable or whenever a built-in function is shadowed.
3147
3148@item -Wlarger-than-@var{len}
3149@opindex Wlarger-than
3150Warn whenever an object of larger than @var{len} bytes is defined.
3151
3152@item -Wunsafe-loop-optimizations
3153@opindex Wunsafe-loop-optimizations
3154Warn if the loop cannot be optimized because the compiler could not
3155assume anything on the bounds of the loop indices. With
3156@option{-funsafe-loop-optimizations} warn if the compiler made
3157such assumptions.
3158
3159@item -Wpointer-arith
3160@opindex Wpointer-arith
3161Warn about anything that depends on the ``size of'' a function type or
3162of @code{void}. GNU C assigns these types a size of 1, for
3163convenience in calculations with @code{void *} pointers and pointers
3164to functions.
3165
3166@item -Wbad-function-cast @r{(C only)}
3167@opindex Wbad-function-cast
3168Warn whenever a function call is cast to a non-matching type.
3169For example, warn if @code{int malloc()} is cast to @code{anything *}.
3170
3171@item -Wc++-compat
3172Warn about ISO C constructs that are outside of the common subset of
3173ISO C and ISO C++, e.g.@: request for implicit conversion from
3174@code{void *} to a pointer to non-@code{void} type.
3175
3176@item -Wcast-qual
3177@opindex Wcast-qual
3178Warn whenever a pointer is cast so as to remove a type qualifier from
3179the target type. For example, warn if a @code{const char *} is cast
3180to an ordinary @code{char *}.
3181
3182@item -Wcast-align
3183@opindex Wcast-align
3184Warn whenever a pointer is cast such that the required alignment of the
3185target is increased. For example, warn if a @code{char *} is cast to
3186an @code{int *} on machines where integers can only be accessed at
3187two- or four-byte boundaries.
3188
3189@item -Wwrite-strings
3190@opindex Wwrite-strings
3191When compiling C, give string constants the type @code{const
3192char[@var{length}]} so that
3193copying the address of one into a non-@code{const} @code{char *}
3194pointer will get a warning; when compiling C++, warn about the
3195deprecated conversion from string literals to @code{char *}. This
3196warning, by default, is enabled for C++ programs.
3197These warnings will help you find at
3198compile time code that can try to write into a string constant, but
3199only if you have been very careful about using @code{const} in
3200declarations and prototypes. Otherwise, it will just be a nuisance;
3201this is why we did not make @option{-Wall} request these warnings.
3202
3203@item -Wconversion
3204@opindex Wconversion
3205Warn if a prototype causes a type conversion that is different from what
3206would happen to the same argument in the absence of a prototype. This
3207includes conversions of fixed point to floating and vice versa, and
3208conversions changing the width or signedness of a fixed point argument
3209except when the same as the default promotion.
3210
3211Also, warn if a negative integer constant expression is implicitly
3212converted to an unsigned type. For example, warn about the assignment
3213@code{x = -1} if @code{x} is unsigned. But do not warn about explicit
3214casts like @code{(unsigned) -1}.
3215
3216@item -Wsign-compare
3217@opindex Wsign-compare
3218@cindex warning for comparison of signed and unsigned values
3219@cindex comparison of signed and unsigned values, warning
3220@cindex signed and unsigned values, comparison warning
3221Warn when a comparison between signed and unsigned values could produce
3222an incorrect result when the signed value is converted to unsigned.
3223This warning is also enabled by @option{-Wextra}; to get the other warnings
3224of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
3225
3226@item -Waddress
3227@opindex Waddress
3228@opindex Wno-address
3229Warn about suspicious uses of memory addresses. These include using
3230the address of a function in a conditional expression, such as
3231@code{void func(void); if (func)}, and comparisons against the memory
3232address of a string literal, such as @code{if (x == "abc")}. Such
3233uses typically indicate a programmer error: the address of a function
3234always evaluates to true, so their use in a conditional usually
3235indicate that the programmer forgot the parentheses in a function
3236call; and comparisons against string literals result in unspecified
3237behavior and are not portable in C, so they usually indicate that the
3238programmer intended to use @code{strcmp}. This warning is enabled by
3239@option{-Wall}.
3240
3241@item -Waggregate-return
3242@opindex Waggregate-return
3243Warn if any functions that return structures or unions are defined or
3244called. (In languages where you can return an array, this also elicits
3245a warning.)
3246
3247@item -Wno-attributes
3248@opindex Wno-attributes
3249@opindex Wattributes
3250Do not warn if an unexpected @code{__attribute__} is used, such as
3251unrecognized attributes, function attributes applied to variables,
3252etc. This will not stop errors for incorrect use of supported
3253attributes.
3254
3255@item -Wstrict-prototypes @r{(C only)}
3256@opindex Wstrict-prototypes
3257Warn if a function is declared or defined without specifying the
3258argument types. (An old-style function definition is permitted without
3259a warning if preceded by a declaration which specifies the argument
3260types.)
3261
3262@item -Wold-style-definition @r{(C only)}
3263@opindex Wold-style-definition
3264Warn if an old-style function definition is used. A warning is given
3265even if there is a previous prototype.
3266
3267@item -Wmissing-prototypes @r{(C only)}
3268@opindex Wmissing-prototypes
3269Warn if a global function is defined without a previous prototype
3270declaration. This warning is issued even if the definition itself
3271provides a prototype. The aim is to detect global functions that fail
3272to be declared in header files.
3273
3274@item -Wmissing-declarations @r{(C only)}
3275@opindex Wmissing-declarations
3276Warn if a global function is defined without a previous declaration.
3277Do so even if the definition itself provides a prototype.
3278Use this option to detect global functions that are not declared in
3279header files.
3280
3281@item -Wmissing-field-initializers
3282@opindex Wmissing-field-initializers
3283@opindex W
3284@opindex Wextra
3285Warn if a structure's initializer has some fields missing. For
3286example, the following code would cause such a warning, because
3287@code{x.h} is implicitly zero:
3288
3289@smallexample
3290struct s @{ int f, g, h; @};
3291struct s x = @{ 3, 4 @};
3292@end smallexample
3293
3294This option does not warn about designated initializers, so the following
3295modification would not trigger a warning:
3296
3297@smallexample
3298struct s @{ int f, g, h; @};
3299struct s x = @{ .f = 3, .g = 4 @};
3300@end smallexample
3301
3302This warning is included in @option{-Wextra}. To get other @option{-Wextra}
3303warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
3304
3305@item -Wmissing-noreturn
3306@opindex Wmissing-noreturn
3307Warn about functions which might be candidates for attribute @code{noreturn}.
3308Note these are only possible candidates, not absolute ones. Care should
3309be taken to manually verify functions actually do not ever return before
3310adding the @code{noreturn} attribute, otherwise subtle code generation
3311bugs could be introduced. You will not get a warning for @code{main} in
3312hosted C environments.
3313
3314@item -Wmissing-format-attribute
3315@opindex Wmissing-format-attribute
3316@opindex Wformat
3317Warn about function pointers which might be candidates for @code{format}
3318attributes. Note these are only possible candidates, not absolute ones.
3319GCC will guess that function pointers with @code{format} attributes that
3320are used in assignment, initialization, parameter passing or return
3321statements should have a corresponding @code{format} attribute in the
3322resulting type. I.e.@: the left-hand side of the assignment or
3323initialization, the type of the parameter variable, or the return type
3324of the containing function respectively should also have a @code{format}
3325attribute to avoid the warning.
3326
3327GCC will also warn about function definitions which might be
3328candidates for @code{format} attributes. Again, these are only
3329possible candidates. GCC will guess that @code{format} attributes
3330might be appropriate for any function that calls a function like
3331@code{vprintf} or @code{vscanf}, but this might not always be the
3332case, and some functions for which @code{format} attributes are
3333appropriate may not be detected.
3334
3335@item -Wno-multichar
3336@opindex Wno-multichar
3337@opindex Wmultichar
3338Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
3339Usually they indicate a typo in the user's code, as they have
3340implementation-defined values, and should not be used in portable code.
3341
3342@item -Wnormalized=<none|id|nfc|nfkc>
3343@opindex Wnormalized
3344@cindex NFC
3345@cindex NFKC
3346@cindex character set, input normalization
3347In ISO C and ISO C++, two identifiers are different if they are
3348different sequences of characters. However, sometimes when characters
3349outside the basic ASCII character set are used, you can have two
3350different character sequences that look the same. To avoid confusion,
3351the ISO 10646 standard sets out some @dfn{normalization rules} which
3352when applied ensure that two sequences that look the same are turned into
3353the same sequence. GCC can warn you if you are using identifiers which
3354have not been normalized; this option controls that warning.
3355
3356There are four levels of warning that GCC supports. The default is
3357@option{-Wnormalized=nfc}, which warns about any identifier which is
3358not in the ISO 10646 ``C'' normalized form, @dfn{NFC}. NFC is the
3359recommended form for most uses.
3360
3361Unfortunately, there are some characters which ISO C and ISO C++ allow
3362in identifiers that when turned into NFC aren't allowable as
3363identifiers. That is, there's no way to use these symbols in portable
3364ISO C or C++ and have all your identifiers in NFC.
3365@option{-Wnormalized=id} suppresses the warning for these characters.
3366It is hoped that future versions of the standards involved will correct
3367this, which is why this option is not the default.
3368
3369You can switch the warning off for all characters by writing
3370@option{-Wnormalized=none}. You would only want to do this if you
3371were using some other normalization scheme (like ``D''), because
3372otherwise you can easily create bugs that are literally impossible to see.
3373
3374Some characters in ISO 10646 have distinct meanings but look identical
3375in some fonts or display methodologies, especially once formatting has
3376been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
3377LETTER N'', will display just like a regular @code{n} which has been
3378placed in a superscript. ISO 10646 defines the @dfn{NFKC}
3379normalization scheme to convert all these into a standard form as
3380well, and GCC will warn if your code is not in NFKC if you use
3381@option{-Wnormalized=nfkc}. This warning is comparable to warning
3382about every identifier that contains the letter O because it might be
3383confused with the digit 0, and so is not the default, but may be
3384useful as a local coding convention if the programming environment is
3385unable to be fixed to display these characters distinctly.
3386
3387@item -Wno-deprecated-declarations
3388@opindex Wno-deprecated-declarations
3389Do not warn about uses of functions (@pxref{Function Attributes}),
3390variables (@pxref{Variable Attributes}), and types (@pxref{Type
3391Attributes}) marked as deprecated by using the @code{deprecated}
3392attribute.
3393
3394@item -Wno-overflow
3395@opindex Wno-overflow
3396Do not warn about compile-time overflow in constant expressions.
3397
3398@item -Woverride-init
3399@opindex Woverride-init
3400@opindex W
3401@opindex Wextra
3402Warn if an initialized field without side effects is overridden when
3403using designated initializers (@pxref{Designated Inits, , Designated
3404Initializers}).
3405
3406This warning is included in @option{-Wextra}. To get other
3407@option{-Wextra} warnings without this one, use @samp{-Wextra
3408-Wno-override-init}.
3409
3410@item -Wpacked
3411@opindex Wpacked
3412Warn if a structure is given the packed attribute, but the packed
3413attribute has no effect on the layout or size of the structure.
3414Such structures may be mis-aligned for little benefit. For
3415instance, in this code, the variable @code{f.x} in @code{struct bar}
3416will be misaligned even though @code{struct bar} does not itself
3417have the packed attribute:
3418
3419@smallexample
3420@group
3421struct foo @{
3422 int x;
3423 char a, b, c, d;
3424@} __attribute__((packed));
3425struct bar @{
3426 char z;
3427 struct foo f;
3428@};
3429@end group
3430@end smallexample
3431
3432@item -Wpadded
3433@opindex Wpadded
3434Warn if padding is included in a structure, either to align an element
3435of the structure or to align the whole structure. Sometimes when this
3436happens it is possible to rearrange the fields of the structure to
3437reduce the padding and so make the structure smaller.
3438
3439@item -Wredundant-decls
3440@opindex Wredundant-decls
3441Warn if anything is declared more than once in the same scope, even in
3442cases where multiple declaration is valid and changes nothing.
3443
3444@item -Wnested-externs @r{(C only)}
3445@opindex Wnested-externs
3446Warn if an @code{extern} declaration is encountered within a function.
3447
3448@item -Wunreachable-code
3449@opindex Wunreachable-code
3450Warn if the compiler detects that code will never be executed.
3451
3452This option is intended to warn when the compiler detects that at
3453least a whole line of source code will never be executed, because
3454some condition is never satisfied or because it is after a
3455procedure that never returns.
3456
3457It is possible for this option to produce a warning even though there
3458are circumstances under which part of the affected line can be executed,
3459so care should be taken when removing apparently-unreachable code.
3460
3461For instance, when a function is inlined, a warning may mean that the
3462line is unreachable in only one inlined copy of the function.
3463
3464This option is not made part of @option{-Wall} because in a debugging
3465version of a program there is often substantial code which checks
3466correct functioning of the program and is, hopefully, unreachable
3467because the program does work. Another common use of unreachable
3468code is to provide behavior which is selectable at compile-time.
3469
3470@item -Winline
3471@opindex Winline
3472Warn if a function can not be inlined and it was declared as inline.
3473Even with this option, the compiler will not warn about failures to
3474inline functions declared in system headers.
3475
3476The compiler uses a variety of heuristics to determine whether or not
3477to inline a function. For example, the compiler takes into account
3478the size of the function being inlined and the amount of inlining
3479that has already been done in the current function. Therefore,
3480seemingly insignificant changes in the source program can cause the
3481warnings produced by @option{-Winline} to appear or disappear.
3482
3483@item -Wno-invalid-offsetof @r{(C++ only)}
3484@opindex Wno-invalid-offsetof
3485Suppress warnings from applying the @samp{offsetof} macro to a non-POD
3486type. According to the 1998 ISO C++ standard, applying @samp{offsetof}
3487to a non-POD type is undefined. In existing C++ implementations,
3488however, @samp{offsetof} typically gives meaningful results even when
3489applied to certain kinds of non-POD types. (Such as a simple
3490@samp{struct} that fails to be a POD type only by virtue of having a
3491constructor.) This flag is for users who are aware that they are
3492writing nonportable code and who have deliberately chosen to ignore the
3493warning about it.
3494
3495The restrictions on @samp{offsetof} may be relaxed in a future version
3496of the C++ standard.
3497
3498@item -Wno-int-to-pointer-cast @r{(C only)}
3499@opindex Wno-int-to-pointer-cast
3500Suppress warnings from casts to pointer type of an integer of a
3501different size.
3502
3503@item -Wno-pointer-to-int-cast @r{(C only)}
3504@opindex Wno-pointer-to-int-cast
3505Suppress warnings from casts from a pointer to an integer type of a
3506different size.
3507
3508@item -Winvalid-pch
3509@opindex Winvalid-pch
3510Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
3511the search path but can't be used.
3512
3513@item -Wlong-long
3514@opindex Wlong-long
3515@opindex Wno-long-long
3516Warn if @samp{long long} type is used. This is default. To inhibit
3517the warning messages, use @option{-Wno-long-long}. Flags
3518@option{-Wlong-long} and @option{-Wno-long-long} are taken into account
3519only when @option{-pedantic} flag is used.
3520
3521@item -Wvariadic-macros
3522@opindex Wvariadic-macros
3523@opindex Wno-variadic-macros
3524Warn if variadic macros are used in pedantic ISO C90 mode, or the GNU
3525alternate syntax when in pedantic ISO C99 mode. This is default.
3526To inhibit the warning messages, use @option{-Wno-variadic-macros}.
3527
3528@item -Wvolatile-register-var
3529@opindex Wvolatile-register-var
3530@opindex Wno-volatile-register-var
3531Warn if a register variable is declared volatile. The volatile
3532modifier does not inhibit all optimizations that may eliminate reads
3533and/or writes to register variables.
3534
3535@item -Wdisabled-optimization
3536@opindex Wdisabled-optimization
3537Warn if a requested optimization pass is disabled. This warning does
3538not generally indicate that there is anything wrong with your code; it
3539merely indicates that GCC's optimizers were unable to handle the code
3540effectively. Often, the problem is that your code is too big or too
3541complex; GCC will refuse to optimize programs when the optimization
3542itself is likely to take inordinate amounts of time.
3543
3544@item -Wpointer-sign
3545@opindex Wpointer-sign
3546@opindex Wno-pointer-sign
3547Warn for pointer argument passing or assignment with different signedness.
3548This option is only supported for C and Objective-C@. It is implied by
3549@option{-Wall} and by @option{-pedantic}, which can be disabled with
3550@option{-Wno-pointer-sign}.
3551
3552@item -Werror
3553@opindex Werror
3554Make all warnings into errors.
3555
3556@item -Werror=
3557@opindex Werror=
3558Make the specified warning into an errors. The specifier for a
3559warning is appended, for example @option{-Werror=switch} turns the
3560warnings controlled by @option{-Wswitch} into errors. This switch
3561takes a negative form, to be used to negate @option{-Werror} for
3562specific warnings, for example @option{-Wno-error=switch} makes
3563@option{-Wswitch} warnings not be errors, even when @option{-Werror}
3564is in effect. You can use the @option{-fdiagnostics-show-option}
3565option to have each controllable warning amended with the option which
3566controls it, to determine what to use with this option.
3567
3568Note that specifying @option{-Werror=}@var{foo} automatically implies
3569@option{-W}@var{foo}. However, @option{-Wno-error=}@var{foo} does not
3570imply anything.
3571
3572@item -Wstack-protector
3573@opindex Wstack-protector
3574This option is only active when @option{-fstack-protector} is active. It
3575warns about functions that will not be protected against stack smashing.
3576
3577@item -Woverlength-strings
3578@opindex Woverlength-strings
3579Warn about string constants which are longer than the ``minimum
3580maximum'' length specified in the C standard. Modern compilers
3581generally allow string constants which are much longer than the
3582standard's minimum limit, but very portable programs should avoid
3583using longer strings.
3584
3585The limit applies @emph{after} string constant concatenation, and does
3586not count the trailing NUL@. In C89, the limit was 509 characters; in
3587C99, it was raised to 4095. C++98 does not specify a normative
3588minimum maximum, so we do not diagnose overlength strings in C++@.
3589
3590This option is implied by @option{-pedantic}, and can be disabled with
3591@option{-Wno-overlength-strings}.
3592@end table
3593
3594@node Debugging Options
3595@section Options for Debugging Your Program or GCC
3596@cindex options, debugging
3597@cindex debugging information options
3598
3599GCC has various special options that are used for debugging
3600either your program or GCC:
3601
3602@table @gcctabopt
3603@item -g
3604@opindex g
3605Produce debugging information in the operating system's native format
3606(stabs, COFF, XCOFF, or DWARF 2)@. GDB can work with this debugging
3607information.
3608
3609On most systems that use stabs format, @option{-g} enables use of extra
3610debugging information that only GDB can use; this extra information
3611makes debugging work better in GDB but will probably make other debuggers
3612crash or
3613refuse to read the program. If you want to control for certain whether
3614to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
3615@option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
3616
3617GCC allows you to use @option{-g} with
3618@option{-O}. The shortcuts taken by optimized code may occasionally
3619produce surprising results: some variables you declared may not exist
3620at all; flow of control may briefly move where you did not expect it;
3621some statements may not be executed because they compute constant
3622results or their values were already at hand; some statements may
3623execute in different places because they were moved out of loops.
3624
3625Nevertheless it proves possible to debug optimized output. This makes
3626it reasonable to use the optimizer for programs that might have bugs.
3627
3628The following options are useful when GCC is generated with the
3629capability for more than one debugging format.
3630
3631@item -ggdb
3632@opindex ggdb
3633Produce debugging information for use by GDB@. This means to use the
3634most expressive format available (DWARF 2, stabs, or the native format
3635if neither of those are supported), including GDB extensions if at all
3636possible.
3637
3638@item -gstabs
3639@opindex gstabs
3640Produce debugging information in stabs format (if that is supported),
3641without GDB extensions. This is the format used by DBX on most BSD
3642systems. On MIPS, Alpha and System V Release 4 systems this option
3643produces stabs debugging output which is not understood by DBX or SDB@.
3644On System V Release 4 systems this option requires the GNU assembler.
3645
3646@item -feliminate-unused-debug-symbols
3647@opindex feliminate-unused-debug-symbols
3648Produce debugging information in stabs format (if that is supported),
3649for only symbols that are actually used.
3650
3651@item -femit-class-debug-always
3652Instead of emitting debugging information for a C++ class in only one
3653object file, emit it in all object files using the class. This option
3654should be used only with debuggers that are unable to handle the way GCC
3655normally emits debugging information for classes because using this
3656option will increase the size of debugging information by as much as a
3657factor of two.
3658
3659@item -gstabs+
3660@opindex gstabs+
3661Produce debugging information in stabs format (if that is supported),
3662using GNU extensions understood only by the GNU debugger (GDB)@. The
3663use of these extensions is likely to make other debuggers crash or
3664refuse to read the program.
3665
3666@item -gcoff
3667@opindex gcoff
3668Produce debugging information in COFF format (if that is supported).
3669This is the format used by SDB on most System V systems prior to
3670System V Release 4.
3671
3672@item -gxcoff
3673@opindex gxcoff
3674Produce debugging information in XCOFF format (if that is supported).
3675This is the format used by the DBX debugger on IBM RS/6000 systems.
3676
3677@item -gxcoff+
3678@opindex gxcoff+
3679Produce debugging information in XCOFF format (if that is supported),
3680using GNU extensions understood only by the GNU debugger (GDB)@. The
3681use of these extensions is likely to make other debuggers crash or
3682refuse to read the program, and may cause assemblers other than the GNU
3683assembler (GAS) to fail with an error.
3684
3685@item -gdwarf-2
3686@opindex gdwarf-2
3687Produce debugging information in DWARF version 2 format (if that is
3688supported). This is the format used by DBX on IRIX 6. With this
3689option, GCC uses features of DWARF version 3 when they are useful;
3690version 3 is upward compatible with version 2, but may still cause
3691problems for older debuggers.
3692
3693@item -gvms
3694@opindex gvms
3695Produce debugging information in VMS debug format (if that is
3696supported). This is the format used by DEBUG on VMS systems.
3697
3698@item -g@var{level}
3699@itemx -ggdb@var{level}
3700@itemx -gstabs@var{level}
3701@itemx -gcoff@var{level}
3702@itemx -gxcoff@var{level}
3703@itemx -gvms@var{level}
3704Request debugging information and also use @var{level} to specify how
3705much information. The default level is 2.
3706
3707Level 1 produces minimal information, enough for making backtraces in
3708parts of the program that you don't plan to debug. This includes
3709descriptions of functions and external variables, but no information
3710about local variables and no line numbers.
3711
3712Level 3 includes extra information, such as all the macro definitions
3713present in the program. Some debuggers support macro expansion when
3714you use @option{-g3}.
3715
3716@option{-gdwarf-2} does not accept a concatenated debug level, because
3717GCC used to support an option @option{-gdwarf} that meant to generate
3718debug information in version 1 of the DWARF format (which is very
3719different from version 2), and it would have been too confusing. That
3720debug format is long obsolete, but the option cannot be changed now.
3721Instead use an additional @option{-g@var{level}} option to change the
3722debug level for DWARF2.
3723
3724@item -feliminate-dwarf2-dups
3725@opindex feliminate-dwarf2-dups
3726Compress DWARF2 debugging information by eliminating duplicated
3727information about each symbol. This option only makes sense when
3728generating DWARF2 debugging information with @option{-gdwarf-2}.
3729
3730@cindex @command{prof}
3731@item -p
3732@opindex p
3733Generate extra code to write profile information suitable for the
3734analysis program @command{prof}. You must use this option when compiling
3735the source files you want data about, and you must also use it when
3736linking.
3737
3738@cindex @command{gprof}
3739@item -pg
3740@opindex pg
3741Generate extra code to write profile information suitable for the
3742analysis program @command{gprof}. You must use this option when compiling
3743the source files you want data about, and you must also use it when
3744linking.
3745
3746@item -Q
3747@opindex Q
3748Makes the compiler print out each function name as it is compiled, and
3749print some statistics about each pass when it finishes.
3750
3751@item -ftime-report
3752@opindex ftime-report
3753Makes the compiler print some statistics about the time consumed by each
3754pass when it finishes.
3755
3756@item -fmem-report
3757@opindex fmem-report
3758Makes the compiler print some statistics about permanent memory
3759allocation when it finishes.
3760
3761@item -fprofile-arcs
3762@opindex fprofile-arcs
3763Add code so that program flow @dfn{arcs} are instrumented. During
3764execution the program records how many times each branch and call is
3765executed and how many times it is taken or returns. When the compiled
3766program exits it saves this data to a file called
3767@file{@var{auxname}.gcda} for each source file. The data may be used for
3768profile-directed optimizations (@option{-fbranch-probabilities}), or for
3769test coverage analysis (@option{-ftest-coverage}). Each object file's
3770@var{auxname} is generated from the name of the output file, if
3771explicitly specified and it is not the final executable, otherwise it is
3772the basename of the source file. In both cases any suffix is removed
3773(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
3774@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
3775@xref{Cross-profiling}.
3776
3777@cindex @command{gcov}
3778@item --coverage
3779@opindex coverage
3780
3781This option is used to compile and link code instrumented for coverage
3782analysis. The option is a synonym for @option{-fprofile-arcs}
3783@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
3784linking). See the documentation for those options for more details.
3785
3786@itemize
3787
3788@item
3789Compile the source files with @option{-fprofile-arcs} plus optimization
3790and code generation options. For test coverage analysis, use the
3791additional @option{-ftest-coverage} option. You do not need to profile
3792every source file in a program.
3793
3794@item
3795Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
3796(the latter implies the former).
3797
3798@item
3799Run the program on a representative workload to generate the arc profile
3800information. This may be repeated any number of times. You can run
3801concurrent instances of your program, and provided that the file system
3802supports locking, the data files will be correctly updated. Also
3803@code{fork} calls are detected and correctly handled (double counting
3804will not happen).
3805
3806@item
3807For profile-directed optimizations, compile the source files again with
3808the same optimization and code generation options plus
3809@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
3810Control Optimization}).
3811
3812@item
3813For test coverage analysis, use @command{gcov} to produce human readable
3814information from the @file{.gcno} and @file{.gcda} files. Refer to the
3815@command{gcov} documentation for further information.
3816
3817@end itemize
3818
3819With @option{-fprofile-arcs}, for each function of your program GCC
3820creates a program flow graph, then finds a spanning tree for the graph.
3821Only arcs that are not on the spanning tree have to be instrumented: the
3822compiler adds code to count the number of times that these arcs are
3823executed. When an arc is the only exit or only entrance to a block, the
3824instrumentation code can be added to the block; otherwise, a new basic
3825block must be created to hold the instrumentation code.
3826
3827@need 2000
3828@item -ftest-coverage
3829@opindex ftest-coverage
3830Produce a notes file that the @command{gcov} code-coverage utility
3831(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
3832show program coverage. Each source file's note file is called
3833@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
3834above for a description of @var{auxname} and instructions on how to
3835generate test coverage data. Coverage data will match the source files
3836more closely, if you do not optimize.
3837
3838@item -d@var{letters}
3839@item -fdump-rtl-@var{pass}
3840@opindex d
3841Says to make debugging dumps during compilation at times specified by
3842@var{letters}. This is used for debugging the RTL-based passes of the
3843compiler. The file names for most of the dumps are made by appending a
3844pass number and a word to the @var{dumpname}. @var{dumpname} is generated
3845from the name of the output file, if explicitly specified and it is not
3846an executable, otherwise it is the basename of the source file.
3847
3848Most debug dumps can be enabled either passing a letter to the @option{-d}
3849option, or with a long @option{-fdump-rtl} switch; here are the possible
3850letters for use in @var{letters} and @var{pass}, and their meanings:
3851
3852@table @gcctabopt
3853@item -dA
3854@opindex dA
3855Annotate the assembler output with miscellaneous debugging information.
3856
3857@item -dB
3858@itemx -fdump-rtl-bbro
3859@opindex dB
3860@opindex fdump-rtl-bbro
3861Dump after block reordering, to @file{@var{file}.148r.bbro}.
3862
3863@item -dc
3864@itemx -fdump-rtl-combine
3865@opindex dc
3866@opindex fdump-rtl-combine
3867Dump after instruction combination, to the file @file{@var{file}.129r.combine}.
3868
3869@item -dC
3870@itemx -fdump-rtl-ce1
3871@itemx -fdump-rtl-ce2
3872@opindex dC
3873@opindex fdump-rtl-ce1
3874@opindex fdump-rtl-ce2
3875@option{-dC} and @option{-fdump-rtl-ce1} enable dumping after the
3876first if conversion, to the file @file{@var{file}.117r.ce1}. @option{-dC}
3877and @option{-fdump-rtl-ce2} enable dumping after the second if
3878conversion, to the file @file{@var{file}.130r.ce2}.
3879
3880@item -dd
3881@itemx -fdump-rtl-btl
3882@itemx -fdump-rtl-dbr
3883@opindex dd
3884@opindex fdump-rtl-btl
3885@opindex fdump-rtl-dbr
3886@option{-dd} and @option{-fdump-rtl-btl} enable dumping after branch
3887target load optimization, to @file{@var{file}.31.btl}. @option{-dd}
3888and @option{-fdump-rtl-dbr} enable dumping after delayed branch
3889scheduling, to @file{@var{file}.36.dbr}.
3890
3891@item -dD
3892@opindex dD
3893Dump all macro definitions, at the end of preprocessing, in addition to
3894normal output.
3895
3896@item -dE
3897@itemx -fdump-rtl-ce3
3898@opindex dE
3899@opindex fdump-rtl-ce3
3900Dump after the third if conversion, to @file{@var{file}.146r.ce3}.
3901
3902@item -df
3903@itemx -fdump-rtl-cfg
3904@itemx -fdump-rtl-life
3905@opindex df
3906@opindex fdump-rtl-cfg
3907@opindex fdump-rtl-life
3908@option{-df} and @option{-fdump-rtl-cfg} enable dumping after control
3909and data flow analysis, to @file{@var{file}.116r.cfg}. @option{-df}
3910and @option{-fdump-rtl-cfg} enable dumping dump after life analysis,
3911to @file{@var{file}.128r.life1} and @file{@var{file}.135r.life2}.
3912
3913@item -dg
3914@itemx -fdump-rtl-greg
3915@opindex dg
3916@opindex fdump-rtl-greg
3917Dump after global register allocation, to @file{@var{file}.139r.greg}.
3918
3919@item -dG
3920@itemx -fdump-rtl-gcse
3921@itemx -fdump-rtl-bypass
3922@opindex dG
3923@opindex fdump-rtl-gcse
3924@opindex fdump-rtl-bypass
3925@option{-dG} and @option{-fdump-rtl-gcse} enable dumping after GCSE, to
3926@file{@var{file}.114r.gcse}. @option{-dG} and @option{-fdump-rtl-bypass}
3927enable dumping after jump bypassing and control flow optimizations, to
3928@file{@var{file}.115r.bypass}.
3929
3930@item -dh
3931@itemx -fdump-rtl-eh
3932@opindex dh
3933@opindex fdump-rtl-eh
3934Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
3935
3936@item -di
3937@itemx -fdump-rtl-sibling
3938@opindex di
3939@opindex fdump-rtl-sibling
3940Dump after sibling call optimizations, to @file{@var{file}.106r.sibling}.
3941
3942@item -dj
3943@itemx -fdump-rtl-jump
3944@opindex dj
3945@opindex fdump-rtl-jump
3946Dump after the first jump optimization, to @file{@var{file}.112r.jump}.
3947
3948@item -dk
3949@itemx -fdump-rtl-stack
3950@opindex dk
3951@opindex fdump-rtl-stack
3952Dump after conversion from registers to stack, to @file{@var{file}.152r.stack}.
3953
3954@item -dl
3955@itemx -fdump-rtl-lreg
3956@opindex dl
3957@opindex fdump-rtl-lreg
3958Dump after local register allocation, to @file{@var{file}.138r.lreg}.
3959
3960@item -dL
3961@itemx -fdump-rtl-loop2
3962@opindex dL
3963@opindex fdump-rtl-loop2
3964@option{-dL} and @option{-fdump-rtl-loop2} enable dumping after the
3965loop optimization pass, to @file{@var{file}.119r.loop2},
3966@file{@var{file}.120r.loop2_init},
3967@file{@var{file}.121r.loop2_invariant}, and
3968@file{@var{file}.125r.loop2_done}.
3969
3970@item -dm
3971@itemx -fdump-rtl-sms
3972@opindex dm
3973@opindex fdump-rtl-sms
3974Dump after modulo scheduling, to @file{@var{file}.136r.sms}.
3975
3976@item -dM
3977@itemx -fdump-rtl-mach
3978@opindex dM
3979@opindex fdump-rtl-mach
3980Dump after performing the machine dependent reorganization pass, to
3981@file{@var{file}.155r.mach}.
3982
3983@item -dn
3984@itemx -fdump-rtl-rnreg
3985@opindex dn
3986@opindex fdump-rtl-rnreg
3987Dump after register renumbering, to @file{@var{file}.147r.rnreg}.
3988
3989@item -dN
3990@itemx -fdump-rtl-regmove
3991@opindex dN
3992@opindex fdump-rtl-regmove
3993Dump after the register move pass, to @file{@var{file}.132r.regmove}.
3994
3995@item -do
3996@itemx -fdump-rtl-postreload
3997@opindex do
3998@opindex fdump-rtl-postreload
3999Dump after post-reload optimizations, to @file{@var{file}.24.postreload}.
4000
4001@item -dr
4002@itemx -fdump-rtl-expand
4003@opindex dr
4004@opindex fdump-rtl-expand
4005Dump after RTL generation, to @file{@var{file}.104r.expand}.
4006
4007@item -dR
4008@itemx -fdump-rtl-sched2
4009@opindex dR
4010@opindex fdump-rtl-sched2
4011Dump after the second scheduling pass, to @file{@var{file}.150r.sched2}.
4012
4013@item -ds
4014@itemx -fdump-rtl-cse
4015@opindex ds
4016@opindex fdump-rtl-cse
4017Dump after CSE (including the jump optimization that sometimes follows
4018CSE), to @file{@var{file}.113r.cse}.
4019
4020@item -dS
4021@itemx -fdump-rtl-sched
4022@opindex dS
4023@opindex fdump-rtl-sched
4024Dump after the first scheduling pass, to @file{@var{file}.21.sched}.
4025
4026@item -dt
4027@itemx -fdump-rtl-cse2
4028@opindex dt
4029@opindex fdump-rtl-cse2
4030Dump after the second CSE pass (including the jump optimization that
4031sometimes follows CSE), to @file{@var{file}.127r.cse2}.
4032
4033@item -dT
4034@itemx -fdump-rtl-tracer
4035@opindex dT
4036@opindex fdump-rtl-tracer
4037Dump after running tracer, to @file{@var{file}.118r.tracer}.
4038
4039@item -dV
4040@itemx -fdump-rtl-vpt
4041@itemx -fdump-rtl-vartrack
4042@opindex dV
4043@opindex fdump-rtl-vpt
4044@opindex fdump-rtl-vartrack
4045@option{-dV} and @option{-fdump-rtl-vpt} enable dumping after the value
4046profile transformations, to @file{@var{file}.10.vpt}. @option{-dV}
4047and @option{-fdump-rtl-vartrack} enable dumping after variable tracking,
4048to @file{@var{file}.154r.vartrack}.
4049
4050@item -dw
4051@itemx -fdump-rtl-flow2
4052@opindex dw
4053@opindex fdump-rtl-flow2
4054Dump after the second flow pass, to @file{@var{file}.142r.flow2}.
4055
4056@item -dz
4057@itemx -fdump-rtl-peephole2
4058@opindex dz
4059@opindex fdump-rtl-peephole2
4060Dump after the peephole pass, to @file{@var{file}.145r.peephole2}.
4061
4062@item -dZ
4063@itemx -fdump-rtl-web
4064@opindex dZ
4065@opindex fdump-rtl-web
4066Dump after live range splitting, to @file{@var{file}.126r.web}.
4067
4068@item -da
4069@itemx -fdump-rtl-all
4070@opindex da
4071@opindex fdump-rtl-all
4072Produce all the dumps listed above.
4073
4074@item -dH
4075@opindex dH
4076Produce a core dump whenever an error occurs.
4077
4078@item -dm
4079@opindex dm
4080Print statistics on memory usage, at the end of the run, to
4081standard error.
4082
4083@item -dp
4084@opindex dp
4085Annotate the assembler output with a comment indicating which
4086pattern and alternative was used. The length of each instruction is
4087also printed.
4088
4089@item -dP
4090@opindex dP
4091Dump the RTL in the assembler output as a comment before each instruction.
4092Also turns on @option{-dp} annotation.
4093
4094@item -dv
4095@opindex dv
4096For each of the other indicated dump files (either with @option{-d} or
4097@option{-fdump-rtl-@var{pass}}), dump a representation of the control flow
4098graph suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
4099
4100@item -dx
4101@opindex dx
4102Just generate RTL for a function instead of compiling it. Usually used
4103with @samp{r} (@option{-fdump-rtl-expand}).
4104
4105@item -dy
4106@opindex dy
4107Dump debugging information during parsing, to standard error.
4108@end table
4109
4110@item -fdump-noaddr
4111@opindex fdump-noaddr
4112When doing debugging dumps (see @option{-d} option above), suppress
4113address output. This makes it more feasible to use diff on debugging
4114dumps for compiler invocations with different compiler binaries and/or
4115different text / bss / data / heap / stack / dso start locations.
4116
4117@item -fdump-unnumbered
4118@opindex fdump-unnumbered
4119When doing debugging dumps (see @option{-d} option above), suppress instruction
4120numbers, line number note and address output. This makes it more feasible to
4121use diff on debugging dumps for compiler invocations with different
4122options, in particular with and without @option{-g}.
4123
4124@item -fdump-translation-unit @r{(C++ only)}
4125@itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
4126@opindex fdump-translation-unit
4127Dump a representation of the tree structure for the entire translation
4128unit to a file. The file name is made by appending @file{.tu} to the
4129source file name. If the @samp{-@var{options}} form is used, @var{options}
4130controls the details of the dump as described for the
4131@option{-fdump-tree} options.
4132
4133@item -fdump-class-hierarchy @r{(C++ only)}
4134@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
4135@opindex fdump-class-hierarchy
4136Dump a representation of each class's hierarchy and virtual function
4137table layout to a file. The file name is made by appending @file{.class}
4138to the source file name. If the @samp{-@var{options}} form is used,
4139@var{options} controls the details of the dump as described for the
4140@option{-fdump-tree} options.
4141
4142@item -fdump-ipa-@var{switch}
4143@opindex fdump-ipa
4144Control the dumping at various stages of inter-procedural analysis
4145language tree to a file. The file name is generated by appending a switch
4146specific suffix to the source file name. The following dumps are possible:
4147
4148@table @samp
4149@item all
4150Enables all inter-procedural analysis dumps; currently the only produced
4151dump is the @samp{cgraph} dump.
4152
4153@item cgraph
4154Dumps information about call-graph optimization, unused function removal,
4155and inlining decisions.
4156@end table
4157
4158@item -fdump-tree-@var{switch}
4159@itemx -fdump-tree-@var{switch}-@var{options}
4160@opindex fdump-tree
4161Control the dumping at various stages of processing the intermediate
4162language tree to a file. The file name is generated by appending a switch
4163specific suffix to the source file name. If the @samp{-@var{options}}
4164form is used, @var{options} is a list of @samp{-} separated options that
4165control the details of the dump. Not all options are applicable to all
4166dumps, those which are not meaningful will be ignored. The following
4167options are available
4168
4169@table @samp
4170@item address
4171Print the address of each node. Usually this is not meaningful as it
4172changes according to the environment and source file. Its primary use
4173is for tying up a dump file with a debug environment.
4174@item slim
4175Inhibit dumping of members of a scope or body of a function merely
4176because that scope has been reached. Only dump such items when they
4177are directly reachable by some other path. When dumping pretty-printed
4178trees, this option inhibits dumping the bodies of control structures.
4179@item raw
4180Print a raw representation of the tree. By default, trees are
4181pretty-printed into a C-like representation.
4182@item details
4183Enable more detailed dumps (not honored by every dump option).
4184@item stats
4185Enable dumping various statistics about the pass (not honored by every dump
4186option).
4187@item blocks
4188Enable showing basic block boundaries (disabled in raw dumps).
4189@item vops
4190Enable showing virtual operands for every statement.
4191@item lineno
4192Enable showing line numbers for statements.
4193@item uid
4194Enable showing the unique ID (@code{DECL_UID}) for each variable.
4195@item all
4196Turn on all options, except @option{raw}, @option{slim} and @option{lineno}.
4197@end table
4198
4199The following tree dumps are possible:
4200@table @samp
4201
4202@item original
4203Dump before any tree based optimization, to @file{@var{file}.original}.
4204
4205@item optimized
4206Dump after all tree based optimization, to @file{@var{file}.optimized}.
4207
4208@item inlined
4209Dump after function inlining, to @file{@var{file}.inlined}.
4210
4211@item gimple
4212@opindex fdump-tree-gimple
4213Dump each function before and after the gimplification pass to a file. The
4214file name is made by appending @file{.gimple} to the source file name.
4215
4216@item cfg
4217@opindex fdump-tree-cfg
4218Dump the control flow graph of each function to a file. The file name is
4219made by appending @file{.cfg} to the source file name.
4220
4221@item vcg
4222@opindex fdump-tree-vcg
4223Dump the control flow graph of each function to a file in VCG format. The
4224file name is made by appending @file{.vcg} to the source file name. Note
4225that if the file contains more than one function, the generated file cannot
4226be used directly by VCG@. You will need to cut and paste each function's
4227graph into its own separate file first.
4228
4229@item ch
4230@opindex fdump-tree-ch
4231Dump each function after copying loop headers. The file name is made by
4232appending @file{.ch} to the source file name.
4233
4234@item ssa
4235@opindex fdump-tree-ssa
4236Dump SSA related information to a file. The file name is made by appending
4237@file{.ssa} to the source file name.
4238
4239@item salias
4240@opindex fdump-tree-salias
4241Dump structure aliasing variable information to a file. This file name
4242is made by appending @file{.salias} to the source file name.
4243
4244@item alias
4245@opindex fdump-tree-alias
4246Dump aliasing information for each function. The file name is made by
4247appending @file{.alias} to the source file name.
4248
4249@item ccp
4250@opindex fdump-tree-ccp
4251Dump each function after CCP@. The file name is made by appending
4252@file{.ccp} to the source file name.
4253
4254@item storeccp
4255@opindex fdump-tree-storeccp
4256Dump each function after STORE-CCP. The file name is made by appending
4257@file{.storeccp} to the source file name.
4258
4259@item pre
4260@opindex fdump-tree-pre
4261Dump trees after partial redundancy elimination. The file name is made
4262by appending @file{.pre} to the source file name.
4263
4264@item fre
4265@opindex fdump-tree-fre
4266Dump trees after full redundancy elimination. The file name is made
4267by appending @file{.fre} to the source file name.
4268
4269@item copyprop
4270@opindex fdump-tree-copyprop
4271Dump trees after copy propagation. The file name is made
4272by appending @file{.copyprop} to the source file name.
4273
4274@item store_copyprop
4275@opindex fdump-tree-store_copyprop
4276Dump trees after store copy-propagation. The file name is made
4277by appending @file{.store_copyprop} to the source file name.
4278
4279@item dce
4280@opindex fdump-tree-dce
4281Dump each function after dead code elimination. The file name is made by
4282appending @file{.dce} to the source file name.
4283
4284@item mudflap
4285@opindex fdump-tree-mudflap
4286Dump each function after adding mudflap instrumentation. The file name is
4287made by appending @file{.mudflap} to the source file name.
4288
4289@item sra
4290@opindex fdump-tree-sra
4291Dump each function after performing scalar replacement of aggregates. The
4292file name is made by appending @file{.sra} to the source file name.
4293
4294@item sink
4295@opindex fdump-tree-sink
4296Dump each function after performing code sinking. The file name is made
4297by appending @file{.sink} to the source file name.
4298
4299@item dom
4300@opindex fdump-tree-dom
4301Dump each function after applying dominator tree optimizations. The file
4302name is made by appending @file{.dom} to the source file name.
4303
4304@item dse
4305@opindex fdump-tree-dse
4306Dump each function after applying dead store elimination. The file
4307name is made by appending @file{.dse} to the source file name.
4308
4309@item phiopt
4310@opindex fdump-tree-phiopt
4311Dump each function after optimizing PHI nodes into straightline code. The file
4312name is made by appending @file{.phiopt} to the source file name.
4313
4314@item forwprop
4315@opindex fdump-tree-forwprop
4316Dump each function after forward propagating single use variables. The file
4317name is made by appending @file{.forwprop} to the source file name.
4318
4319@item copyrename
4320@opindex fdump-tree-copyrename
4321Dump each function after applying the copy rename optimization. The file
4322name is made by appending @file{.copyrename} to the source file name.
4323
4324@item nrv
4325@opindex fdump-tree-nrv
4326Dump each function after applying the named return value optimization on
4327generic trees. The file name is made by appending @file{.nrv} to the source
4328file name.
4329
4330@item vect
4331@opindex fdump-tree-vect
4332Dump each function after applying vectorization of loops. The file name is
4333made by appending @file{.vect} to the source file name.
4334
4335@item vrp
4336@opindex fdump-tree-vrp
4337Dump each function after Value Range Propagation (VRP). The file name
4338is made by appending @file{.vrp} to the source file name.
4339
4340@item all
4341@opindex fdump-tree-all
4342Enable all the available tree dumps with the flags provided in this option.
4343@end table
4344
4345@item -ftree-vectorizer-verbose=@var{n}
4346@opindex ftree-vectorizer-verbose
4347This option controls the amount of debugging output the vectorizer prints.
4348This information is written to standard error, unless
4349@option{-fdump-tree-all} or @option{-fdump-tree-vect} is specified,
4350in which case it is output to the usual dump listing file, @file{.vect}.
4351For @var{n}=0 no diagnostic information is reported.
4352If @var{n}=1 the vectorizer reports each loop that got vectorized,
4353and the total number of loops that got vectorized.
4354If @var{n}=2 the vectorizer also reports non-vectorized loops that passed
4355the first analysis phase (vect_analyze_loop_form) - i.e. countable,
4356inner-most, single-bb, single-entry/exit loops. This is the same verbosity
4357level that @option{-fdump-tree-vect-stats} uses.
4358Higher verbosity levels mean either more information dumped for each
4359reported loop, or same amount of information reported for more loops:
4360If @var{n}=3, alignment related information is added to the reports.
4361If @var{n}=4, data-references related information (e.g. memory dependences,
4362memory access-patterns) is added to the reports.
4363If @var{n}=5, the vectorizer reports also non-vectorized inner-most loops
4364that did not pass the first analysis phase (i.e. may not be countable, or
4365may have complicated control-flow).
4366If @var{n}=6, the vectorizer reports also non-vectorized nested loops.
4367For @var{n}=7, all the information the vectorizer generates during its
4368analysis and transformation is reported. This is the same verbosity level
4369that @option{-fdump-tree-vect-details} uses.
4370
4371@item -frandom-seed=@var{string}
4372@opindex frandom-string
4373This option provides a seed that GCC uses when it would otherwise use
4374random numbers. It is used to generate certain symbol names
4375that have to be different in every compiled file. It is also used to
4376place unique stamps in coverage data files and the object files that
4377produce them. You can use the @option{-frandom-seed} option to produce
4378reproducibly identical object files.
4379
4380The @var{string} should be different for every file you compile.
4381
4382@item -fsched-verbose=@var{n}
4383@opindex fsched-verbose
4384On targets that use instruction scheduling, this option controls the
4385amount of debugging output the scheduler prints. This information is
4386written to standard error, unless @option{-dS} or @option{-dR} is
4387specified, in which case it is output to the usual dump
4388listing file, @file{.sched} or @file{.sched2} respectively. However
4389for @var{n} greater than nine, the output is always printed to standard
4390error.
4391
4392For @var{n} greater than zero, @option{-fsched-verbose} outputs the
4393same information as @option{-dRS}. For @var{n} greater than one, it
4394also output basic block probabilities, detailed ready list information
4395and unit/insn info. For @var{n} greater than two, it includes RTL
4396at abort point, control-flow and regions info. And for @var{n} over
4397four, @option{-fsched-verbose} also includes dependence info.
4398
4399@item -save-temps
4400@opindex save-temps
4401Store the usual ``temporary'' intermediate files permanently; place them
4402in the current directory and name them based on the source file. Thus,
4403compiling @file{foo.c} with @samp{-c -save-temps} would produce files
4404@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
4405preprocessed @file{foo.i} output file even though the compiler now
4406normally uses an integrated preprocessor.
4407
4408When used in combination with the @option{-x} command line option,
4409@option{-save-temps} is sensible enough to avoid over writing an
4410input source file with the same extension as an intermediate file.
4411The corresponding intermediate file may be obtained by renaming the
4412source file before using @option{-save-temps}.
4413
4414@item -time
4415@opindex time
4416Report the CPU time taken by each subprocess in the compilation
4417sequence. For C source files, this is the compiler proper and assembler
4418(plus the linker if linking is done). The output looks like this:
4419
4420@smallexample
4421# cc1 0.12 0.01
4422# as 0.00 0.01
4423@end smallexample
4424
4425The first number on each line is the ``user time'', that is time spent
4426executing the program itself. The second number is ``system time'',
4427time spent executing operating system routines on behalf of the program.
4428Both numbers are in seconds.
4429
4430@item -fvar-tracking
4431@opindex fvar-tracking
4432Run variable tracking pass. It computes where variables are stored at each
4433position in code. Better debugging information is then generated
4434(if the debugging information format supports this information).
4435
4436It is enabled by default when compiling with optimization (@option{-Os},
4437@option{-O}, @option{-O2}, ...), debugging information (@option{-g}) and
4438the debug info format supports it.
4439
4440@item -print-file-name=@var{library}
4441@opindex print-file-name
4442Print the full absolute name of the library file @var{library} that
4443would be used when linking---and don't do anything else. With this
4444option, GCC does not compile or link anything; it just prints the
4445file name.
4446
4447@item -print-multi-directory
4448@opindex print-multi-directory
4449Print the directory name corresponding to the multilib selected by any
4450other switches present in the command line. This directory is supposed
4451to exist in @env{GCC_EXEC_PREFIX}.
4452
4453@item -print-multi-lib
4454@opindex print-multi-lib
4455Print the mapping from multilib directory names to compiler switches
4456that enable them. The directory name is separated from the switches by
4457@samp{;}, and each switch starts with an @samp{@@} instead of the
4458@samp{-}, without spaces between multiple switches. This is supposed to
4459ease shell-processing.
4460
4461@item -print-prog-name=@var{program}
4462@opindex print-prog-name
4463Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
4464
4465@item -print-libgcc-file-name
4466@opindex print-libgcc-file-name
4467Same as @option{-print-file-name=libgcc.a}.
4468
4469This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
4470but you do want to link with @file{libgcc.a}. You can do
4471
4472@smallexample
4473gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
4474@end smallexample
4475
4476@item -print-search-dirs
4477@opindex print-search-dirs
4478Print the name of the configured installation directory and a list of
4479program and library directories @command{gcc} will search---and don't do anything else.
4480
4481This is useful when @command{gcc} prints the error message
4482@samp{installation problem, cannot exec cpp0: No such file or directory}.
4483To resolve this you either need to put @file{cpp0} and the other compiler
4484components where @command{gcc} expects to find them, or you can set the environment
4485variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
4486Don't forget the trailing @samp{/}.
4487@xref{Environment Variables}.
4488
4489@item -dumpmachine
4490@opindex dumpmachine
4491Print the compiler's target machine (for example,
4492@samp{i686-pc-linux-gnu})---and don't do anything else.
4493
4494@item -dumpversion
4495@opindex dumpversion
4496Print the compiler version (for example, @samp{3.0})---and don't do
4497anything else.
4498
4499@item -dumpspecs
4500@opindex dumpspecs
4501Print the compiler's built-in specs---and don't do anything else. (This
4502is used when GCC itself is being built.) @xref{Spec Files}.
4503
4504@item -feliminate-unused-debug-types
4505@opindex feliminate-unused-debug-types
4506Normally, when producing DWARF2 output, GCC will emit debugging
4507information for all types declared in a compilation
4508unit, regardless of whether or not they are actually used
4509in that compilation unit. Sometimes this is useful, such as
4510if, in the debugger, you want to cast a value to a type that is
4511not actually used in your program (but is declared). More often,
4512however, this results in a significant amount of wasted space.
4513With this option, GCC will avoid producing debug symbol output
4514for types that are nowhere used in the source file being compiled.
4515@end table
4516
4517@node Optimize Options
4518@section Options That Control Optimization
4519@cindex optimize options
4520@cindex options, optimization
4521
4522These options control various sorts of optimizations.
4523
4524Without any optimization option, the compiler's goal is to reduce the
4525cost of compilation and to make debugging produce the expected
4526results. Statements are independent: if you stop the program with a
4527breakpoint between statements, you can then assign a new value to any
4528variable or change the program counter to any other statement in the
4529function and get exactly the results you would expect from the source
4530code.
4531
4532Turning on optimization flags makes the compiler attempt to improve
4533the performance and/or code size at the expense of compilation time
4534and possibly the ability to debug the program.
4535
4536The compiler performs optimization based on the knowledge it has of
4537the program. Optimization levels @option{-O} and above, in
4538particular, enable @emph{unit-at-a-time} mode, which allows the
4539compiler to consider information gained from later functions in
4540the file when compiling a function. Compiling multiple files at
4541once to a single output file in @emph{unit-at-a-time} mode allows
4542the compiler to use information gained from all of the files when
4543compiling each of them.
4544
4545Not all optimizations are controlled directly by a flag. Only
4546optimizations that have a flag are listed.
4547
4548@table @gcctabopt
4549@item -O
4550@itemx -O1
4551@opindex O
4552@opindex O1
4553Optimize. Optimizing compilation takes somewhat more time, and a lot
4554more memory for a large function.
4555
4556With @option{-O}, the compiler tries to reduce code size and execution
4557time, without performing any optimizations that take a great deal of
4558compilation time.
4559
4560@option{-O} turns on the following optimization flags:
4561@gccoptlist{-fdefer-pop @gol
4562-fdelayed-branch @gol
4563-fguess-branch-probability @gol
4564-fcprop-registers @gol
4565-fif-conversion @gol
4566-fif-conversion2 @gol
4567-ftree-ccp @gol
4568-ftree-dce @gol
4569-ftree-dominator-opts @gol
4570-ftree-dse @gol
4571-ftree-ter @gol
4572-ftree-lrs @gol
4573-ftree-sra @gol
4574-ftree-copyrename @gol
4575-ftree-fre @gol
4576-ftree-ch @gol
4577-funit-at-a-time @gol
4578-fmerge-constants}
4579
4580@option{-O} also turns on @option{-fomit-frame-pointer} on machines
4581where doing so does not interfere with debugging.
4582
4583@item -O2
4584@opindex O2
4585Optimize even more. GCC performs nearly all supported optimizations
4586that do not involve a space-speed tradeoff. The compiler does not
4587perform loop unrolling or function inlining when you specify @option{-O2}.
4588As compared to @option{-O}, this option increases both compilation time
4589and the performance of the generated code.
4590
4591@option{-O2} turns on all optimization flags specified by @option{-O}. It
4592also turns on the following optimization flags:
4593@gccoptlist{-fthread-jumps @gol
4594-fcrossjumping @gol
4595-foptimize-sibling-calls @gol
4596-fcse-follow-jumps -fcse-skip-blocks @gol
4597-fgcse -fgcse-lm @gol
4598-fexpensive-optimizations @gol
4599-frerun-cse-after-loop @gol
4600-fcaller-saves @gol
4601-fpeephole2 @gol
4602-fschedule-insns -fschedule-insns2 @gol
4603-fsched-interblock -fsched-spec @gol
4604-fregmove @gol
4605-fstrict-aliasing -fstrict-overflow @gol
4606-fdelete-null-pointer-checks @gol
4607-freorder-blocks -freorder-functions @gol
4608-falign-functions -falign-jumps @gol
4609-falign-loops -falign-labels @gol
4610-ftree-vrp @gol
4611-ftree-pre}
4612
4613Please note the warning under @option{-fgcse} about
4614invoking @option{-O2} on programs that use computed gotos.
4615
4616@option{-O2} doesn't turn on @option{-ftree-vrp} for the Ada compiler.
4617This option must be explicitly specified on the command line to be
4618enabled for the Ada compiler.
4619
4620@item -O3
4621@opindex O3
4622Optimize yet more. @option{-O3} turns on all optimizations specified by
4623@option{-O2} and also turns on the @option{-finline-functions},
4624@option{-funswitch-loops} and @option{-fgcse-after-reload} options.
4625
4626@item -O0
4627@opindex O0
4628Do not optimize. This is the default.
4629
4630@item -Os
4631@opindex Os
4632Optimize for size. @option{-Os} enables all @option{-O2} optimizations that
4633do not typically increase code size. It also performs further
4634optimizations designed to reduce code size.
4635
4636@option{-Os} disables the following optimization flags:
4637@gccoptlist{-falign-functions -falign-jumps -falign-loops @gol
4638-falign-labels -freorder-blocks -freorder-blocks-and-partition @gol
4639-fprefetch-loop-arrays -ftree-vect-loop-version}
4640
4641If you use multiple @option{-O} options, with or without level numbers,
4642the last such option is the one that is effective.
4643@end table
4644
4645Options of the form @option{-f@var{flag}} specify machine-independent
4646flags. Most flags have both positive and negative forms; the negative
4647form of @option{-ffoo} would be @option{-fno-foo}. In the table
4648below, only one of the forms is listed---the one you typically will
4649use. You can figure out the other form by either removing @samp{no-}
4650or adding it.
4651
4652The following options control specific optimizations. They are either
4653activated by @option{-O} options or are related to ones that are. You
4654can use the following flags in the rare cases when ``fine-tuning'' of
4655optimizations to be performed is desired.
4656
4657@table @gcctabopt
4658@item -fno-default-inline
4659@opindex fno-default-inline
4660Do not make member functions inline by default merely because they are
4661defined inside the class scope (C++ only). Otherwise, when you specify
4662@w{@option{-O}}, member functions defined inside class scope are compiled
4663inline by default; i.e., you don't need to add @samp{inline} in front of
4664the member function name.
4665
4666@item -fno-defer-pop
4667@opindex fno-defer-pop
4668Always pop the arguments to each function call as soon as that function
4669returns. For machines which must pop arguments after a function call,
4670the compiler normally lets arguments accumulate on the stack for several
4671function calls and pops them all at once.
4672
4673Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4674
4675@item -fforce-mem
4676@opindex fforce-mem
4677Force memory operands to be copied into registers before doing
4678arithmetic on them. This produces better code by making all memory
4679references potential common subexpressions. When they are not common
4680subexpressions, instruction combination should eliminate the separate
4681register-load. This option is now a nop and will be removed in 4.3.
4682
4683@item -fforce-addr
4684@opindex fforce-addr
4685Force memory address constants to be copied into registers before
4686doing arithmetic on them.
4687
4688@item -fomit-frame-pointer
4689@opindex fomit-frame-pointer
4690Don't keep the frame pointer in a register for functions that
4691don't need one. This avoids the instructions to save, set up and
4692restore frame pointers; it also makes an extra register available
4693in many functions. @strong{It also makes debugging impossible on
4694some machines.}
4695
4696On some machines, such as the VAX, this flag has no effect, because
4697the standard calling sequence automatically handles the frame pointer
4698and nothing is saved by pretending it doesn't exist. The
4699machine-description macro @code{FRAME_POINTER_REQUIRED} controls
4700whether a target machine supports this flag. @xref{Registers,,Register
4701Usage, gccint, GNU Compiler Collection (GCC) Internals}.
4702
4703Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4704
4705@item -foptimize-sibling-calls
4706@opindex foptimize-sibling-calls
4707Optimize sibling and tail recursive calls.
4708
4709Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4710
4711@item -fno-inline
4712@opindex fno-inline
4713Don't pay attention to the @code{inline} keyword. Normally this option
4714is used to keep the compiler from expanding any functions inline.
4715Note that if you are not optimizing, no functions can be expanded inline.
4716
4717@item -finline-functions
4718@opindex finline-functions
4719Integrate all simple functions into their callers. The compiler
4720heuristically decides which functions are simple enough to be worth
4721integrating in this way.
4722
4723If all calls to a given function are integrated, and the function is
4724declared @code{static}, then the function is normally not output as
4725assembler code in its own right.
4726
4727Enabled at level @option{-O3}.
4728
4729@item -finline-functions-called-once
4730@opindex finline-functions-called-once
4731Consider all @code{static} functions called once for inlining into their
4732caller even if they are not marked @code{inline}. If a call to a given
4733function is integrated, then the function is not output as assembler code
4734in its own right.
4735
4736Enabled if @option{-funit-at-a-time} is enabled.
4737
4738@item -fearly-inlining
4739@opindex fearly-inlining
4740Inline functions marked by @code{always_inline} and functions whose body seems
4741smaller than the function call overhead early before doing
4742@option{-fprofile-generate} instrumentation and real inlining pass. Doing so
4743makes profiling significantly cheaper and usually inlining faster on programs
4744having large chains of nested wrapper functions.
4745
4746Enabled by default.
4747
4748@item -finline-limit=@var{n}
4749@opindex finline-limit
4750By default, GCC limits the size of functions that can be inlined. This flag
4751allows the control of this limit for functions that are explicitly marked as
4752inline (i.e., marked with the inline keyword or defined within the class
4753definition in c++). @var{n} is the size of functions that can be inlined in
4754number of pseudo instructions (not counting parameter handling). The default
4755value of @var{n} is 600.
4756Increasing this value can result in more inlined code at
4757the cost of compilation time and memory consumption. Decreasing usually makes
4758the compilation faster and less code will be inlined (which presumably
4759means slower programs). This option is particularly useful for programs that
4760use inlining heavily such as those based on recursive templates with C++.
4761
4762Inlining is actually controlled by a number of parameters, which may be
4763specified individually by using @option{--param @var{name}=@var{value}}.
4764The @option{-finline-limit=@var{n}} option sets some of these parameters
4765as follows:
4766
4767@table @gcctabopt
4768@item max-inline-insns-single
4769 is set to @var{n}/2.
4770@item max-inline-insns-auto
4771 is set to @var{n}/2.
4772@item min-inline-insns
4773 is set to 130 or @var{n}/4, whichever is smaller.
4774@item max-inline-insns-rtl
4775 is set to @var{n}.
4776@end table
4777
4778See below for a documentation of the individual
4779parameters controlling inlining.
4780
4781@emph{Note:} pseudo instruction represents, in this particular context, an
4782abstract measurement of function's size. In no way does it represent a count
4783of assembly instructions and as such its exact meaning might change from one
4784release to an another.
4785
4786@item -fkeep-inline-functions
4787@opindex fkeep-inline-functions
4788In C, emit @code{static} functions that are declared @code{inline}
4789into the object file, even if the function has been inlined into all
4790of its callers. This switch does not affect functions using the
4791@code{extern inline} extension in GNU C@. In C++, emit any and all
4792inline functions into the object file.
4793
4794@item -fkeep-static-consts
4795@opindex fkeep-static-consts
4796Emit variables declared @code{static const} when optimization isn't turned
4797on, even if the variables aren't referenced.
4798
4799GCC enables this option by default. If you want to force the compiler to
4800check if the variable was referenced, regardless of whether or not
4801optimization is turned on, use the @option{-fno-keep-static-consts} option.
4802
4803@item -fmerge-constants
4804Attempt to merge identical constants (string constants and floating point
4805constants) across compilation units.
4806
4807This option is the default for optimized compilation if the assembler and
4808linker support it. Use @option{-fno-merge-constants} to inhibit this
4809behavior.
4810
4811Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4812
4813@item -fmerge-all-constants
4814Attempt to merge identical constants and identical variables.
4815
4816This option implies @option{-fmerge-constants}. In addition to
4817@option{-fmerge-constants} this considers e.g.@: even constant initialized
4818arrays or initialized constant variables with integral or floating point
4819types. Languages like C or C++ require each non-automatic variable to
4820have distinct location, so using this option will result in non-conforming
4821behavior.
4822
4823@item -fmodulo-sched
4824@opindex fmodulo-sched
4825Perform swing modulo scheduling immediately before the first scheduling
4826pass. This pass looks at innermost loops and reorders their
4827instructions by overlapping different iterations.
4828
4829@item -fno-branch-count-reg
4830@opindex fno-branch-count-reg
4831Do not use ``decrement and branch'' instructions on a count register,
4832but instead generate a sequence of instructions that decrement a
4833register, compare it against zero, then branch based upon the result.
4834This option is only meaningful on architectures that support such
4835instructions, which include x86, PowerPC, IA-64 and S/390.
4836
4837The default is @option{-fbranch-count-reg}.
4838
4839@item -fno-function-cse
4840@opindex fno-function-cse
4841Do not put function addresses in registers; make each instruction that
4842calls a constant function contain the function's address explicitly.
4843
4844This option results in less efficient code, but some strange hacks
4845that alter the assembler output may be confused by the optimizations
4846performed when this option is not used.
4847
4848The default is @option{-ffunction-cse}
4849
4850@item -fno-zero-initialized-in-bss
4851@opindex fno-zero-initialized-in-bss
4852If the target supports a BSS section, GCC by default puts variables that
4853are initialized to zero into BSS@. This can save space in the resulting
4854code.
4855
4856This option turns off this behavior because some programs explicitly
4857rely on variables going to the data section. E.g., so that the
4858resulting executable can find the beginning of that section and/or make
4859assumptions based on that.
4860
4861The default is @option{-fzero-initialized-in-bss}.
4862
4863@item -fbounds-check
4864@opindex fbounds-check
4865For front-ends that support it, generate additional code to check that
4866indices used to access arrays are within the declared range. This is
4867currently only supported by the Java and Fortran front-ends, where
4868this option defaults to true and false respectively.
4869
4870@item -fmudflap -fmudflapth -fmudflapir
4871@opindex fmudflap
4872@opindex fmudflapth
4873@opindex fmudflapir
4874@cindex bounds checking
4875@cindex mudflap
4876For front-ends that support it (C and C++), instrument all risky
4877pointer/array dereferencing operations, some standard library
4878string/heap functions, and some other associated constructs with
4879range/validity tests. Modules so instrumented should be immune to
4880buffer overflows, invalid heap use, and some other classes of C/C++
4881programming errors. The instrumentation relies on a separate runtime
4882library (@file{libmudflap}), which will be linked into a program if
4883@option{-fmudflap} is given at link time. Run-time behavior of the
4884instrumented program is controlled by the @env{MUDFLAP_OPTIONS}
4885environment variable. See @code{env MUDFLAP_OPTIONS=-help a.out}
4886for its options.
4887
4888Use @option{-fmudflapth} instead of @option{-fmudflap} to compile and to
4889link if your program is multi-threaded. Use @option{-fmudflapir}, in
4890addition to @option{-fmudflap} or @option{-fmudflapth}, if
4891instrumentation should ignore pointer reads. This produces less
4892instrumentation (and therefore faster execution) and still provides
4893some protection against outright memory corrupting writes, but allows
4894erroneously read data to propagate within a program.
4895
4896@item -fthread-jumps
4897@opindex fthread-jumps
4898Perform optimizations where we check to see if a jump branches to a
4899location where another comparison subsumed by the first is found. If
4900so, the first branch is redirected to either the destination of the
4901second branch or a point immediately following it, depending on whether
4902the condition is known to be true or false.
4903
4904Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4905
4906@item -fcse-follow-jumps
4907@opindex fcse-follow-jumps
4908In common subexpression elimination, scan through jump instructions
4909when the target of the jump is not reached by any other path. For
4910example, when CSE encounters an @code{if} statement with an
4911@code{else} clause, CSE will follow the jump when the condition
4912tested is false.
4913
4914Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4915
4916@item -fcse-skip-blocks
4917@opindex fcse-skip-blocks
4918This is similar to @option{-fcse-follow-jumps}, but causes CSE to
4919follow jumps which conditionally skip over blocks. When CSE
4920encounters a simple @code{if} statement with no else clause,
4921@option{-fcse-skip-blocks} causes CSE to follow the jump around the
4922body of the @code{if}.
4923
4924Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4925
4926@item -frerun-cse-after-loop
4927@opindex frerun-cse-after-loop
4928Re-run common subexpression elimination after loop optimizations has been
4929performed.
4930
4931Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4932
4933@item -fgcse
4934@opindex fgcse
4935Perform a global common subexpression elimination pass.
4936This pass also performs global constant and copy propagation.
4937
4938@emph{Note:} When compiling a program using computed gotos, a GCC
4939extension, you may get better runtime performance if you disable
4940the global common subexpression elimination pass by adding
4941@option{-fno-gcse} to the command line.
4942
4943Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4944
4945@item -fgcse-lm
4946@opindex fgcse-lm
4947When @option{-fgcse-lm} is enabled, global common subexpression elimination will
4948attempt to move loads which are only killed by stores into themselves. This
4949allows a loop containing a load/store sequence to be changed to a load outside
4950the loop, and a copy/store within the loop.
4951
4952Enabled by default when gcse is enabled.
4953
4954@item -fgcse-sm
4955@opindex fgcse-sm
4956When @option{-fgcse-sm} is enabled, a store motion pass is run after
4957global common subexpression elimination. This pass will attempt to move
4958stores out of loops. When used in conjunction with @option{-fgcse-lm},
4959loops containing a load/store sequence can be changed to a load before
4960the loop and a store after the loop.
4961
4962Not enabled at any optimization level.
4963
4964@item -fgcse-las
4965@opindex fgcse-las
4966When @option{-fgcse-las} is enabled, the global common subexpression
4967elimination pass eliminates redundant loads that come after stores to the
4968same memory location (both partial and full redundancies).
4969
4970Not enabled at any optimization level.
4971
4972@item -fgcse-after-reload
4973@opindex fgcse-after-reload
4974When @option{-fgcse-after-reload} is enabled, a redundant load elimination
4975pass is performed after reload. The purpose of this pass is to cleanup
4976redundant spilling.
4977
4978@item -funsafe-loop-optimizations
4979@opindex funsafe-loop-optimizations
4980If given, the loop optimizer will assume that loop indices do not
4981overflow, and that the loops with nontrivial exit condition are not
4982infinite. This enables a wider range of loop optimizations even if
4983the loop optimizer itself cannot prove that these assumptions are valid.
4984Using @option{-Wunsafe-loop-optimizations}, the compiler will warn you
4985if it finds this kind of loop.
4986
4987@item -fcrossjumping
4988@opindex crossjumping
4989Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
4990resulting code may or may not perform better than without cross-jumping.
4991
4992Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4993
4994@item -fif-conversion
4995@opindex if-conversion
4996Attempt to transform conditional jumps into branch-less equivalents. This
4997include use of conditional moves, min, max, set flags and abs instructions, and
4998some tricks doable by standard arithmetics. The use of conditional execution
4999on chips where it is available is controlled by @code{if-conversion2}.
5000
5001Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5002
5003@item -fif-conversion2
5004@opindex if-conversion2
5005Use conditional execution (where available) to transform conditional jumps into
5006branch-less equivalents.
5007
5008Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5009
5010@item -fdelete-null-pointer-checks
5011@opindex fdelete-null-pointer-checks
5012Use global dataflow analysis to identify and eliminate useless checks
5013for null pointers. The compiler assumes that dereferencing a null
5014pointer would have halted the program. If a pointer is checked after
5015it has already been dereferenced, it cannot be null.
5016
5017In some environments, this assumption is not true, and programs can
5018safely dereference null pointers. Use
5019@option{-fno-delete-null-pointer-checks} to disable this optimization
5020for programs which depend on that behavior.
5021
5022Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5023
5024@item -fexpensive-optimizations
5025@opindex fexpensive-optimizations
5026Perform a number of minor optimizations that are relatively expensive.
5027
5028Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5029
5030@item -foptimize-register-move
5031@itemx -fregmove
5032@opindex foptimize-register-move
5033@opindex fregmove
5034Attempt to reassign register numbers in move instructions and as
5035operands of other simple instructions in order to maximize the amount of
5036register tying. This is especially helpful on machines with two-operand
5037instructions.
5038
5039Note @option{-fregmove} and @option{-foptimize-register-move} are the same
5040optimization.
5041
5042Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5043
5044@item -fdelayed-branch
5045@opindex fdelayed-branch
5046If supported for the target machine, attempt to reorder instructions
5047to exploit instruction slots available after delayed branch
5048instructions.
5049
5050Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5051
5052@item -fschedule-insns
5053@opindex fschedule-insns
5054If supported for the target machine, attempt to reorder instructions to
5055eliminate execution stalls due to required data being unavailable. This
5056helps machines that have slow floating point or memory load instructions
5057by allowing other instructions to be issued until the result of the load
5058or floating point instruction is required.
5059
5060Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5061
5062@item -fschedule-insns2
5063@opindex fschedule-insns2
5064Similar to @option{-fschedule-insns}, but requests an additional pass of
5065instruction scheduling after register allocation has been done. This is
5066especially useful on machines with a relatively small number of
5067registers and where memory load instructions take more than one cycle.
5068
5069Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5070
5071@item -fno-sched-interblock
5072@opindex fno-sched-interblock
5073Don't schedule instructions across basic blocks. This is normally
5074enabled by default when scheduling before register allocation, i.e.@:
5075with @option{-fschedule-insns} or at @option{-O2} or higher.
5076
5077@item -fno-sched-spec
5078@opindex fno-sched-spec
5079Don't allow speculative motion of non-load instructions. This is normally
5080enabled by default when scheduling before register allocation, i.e.@:
5081with @option{-fschedule-insns} or at @option{-O2} or higher.
5082
5083@item -fsched-spec-load
5084@opindex fsched-spec-load
5085Allow speculative motion of some load instructions. This only makes
5086sense when scheduling before register allocation, i.e.@: with
5087@option{-fschedule-insns} or at @option{-O2} or higher.
5088
5089@item -fsched-spec-load-dangerous
5090@opindex fsched-spec-load-dangerous
5091Allow speculative motion of more load instructions. This only makes
5092sense when scheduling before register allocation, i.e.@: with
5093@option{-fschedule-insns} or at @option{-O2} or higher.
5094
5095@item -fsched-stalled-insns=@var{n}
5096@opindex fsched-stalled-insns
5097Define how many insns (if any) can be moved prematurely from the queue
5098of stalled insns into the ready list, during the second scheduling pass.
5099
5100@item -fsched-stalled-insns-dep=@var{n}
5101@opindex fsched-stalled-insns-dep
5102Define how many insn groups (cycles) will be examined for a dependency
5103on a stalled insn that is candidate for premature removal from the queue
5104of stalled insns. Has an effect only during the second scheduling pass,
5105and only if @option{-fsched-stalled-insns} is used and its value is not zero.
5106
5107@item -fsched2-use-superblocks
5108@opindex fsched2-use-superblocks
5109When scheduling after register allocation, do use superblock scheduling
5110algorithm. Superblock scheduling allows motion across basic block boundaries
5111resulting on faster schedules. This option is experimental, as not all machine
5112descriptions used by GCC model the CPU closely enough to avoid unreliable
5113results from the algorithm.
5114
5115This only makes sense when scheduling after register allocation, i.e.@: with
5116@option{-fschedule-insns2} or at @option{-O2} or higher.
5117
5118@item -fsched2-use-traces
5119@opindex fsched2-use-traces
5120Use @option{-fsched2-use-superblocks} algorithm when scheduling after register
5121allocation and additionally perform code duplication in order to increase the
5122size of superblocks using tracer pass. See @option{-ftracer} for details on
5123trace formation.
5124
5125This mode should produce faster but significantly longer programs. Also
5126without @option{-fbranch-probabilities} the traces constructed may not
5127match the reality and hurt the performance. This only makes
5128sense when scheduling after register allocation, i.e.@: with
5129@option{-fschedule-insns2} or at @option{-O2} or higher.
5130
5131@item -fsee
5132@opindex fsee
5133Eliminates redundant extension instructions and move the non redundant
5134ones to optimal placement using LCM.
5135
5136@item -freschedule-modulo-scheduled-loops
5137@opindex fscheduling-in-modulo-scheduled-loops
5138The modulo scheduling comes before the traditional scheduling, if a loop was modulo scheduled
5139we may want to prevent the later scheduling passes from changing its schedule, we use this
5140option to control that.
5141
5142@item -fcaller-saves
5143@opindex fcaller-saves
5144Enable values to be allocated in registers that will be clobbered by
5145function calls, by emitting extra instructions to save and restore the
5146registers around such calls. Such allocation is done only when it
5147seems to result in better code than would otherwise be produced.
5148
5149This option is always enabled by default on certain machines, usually
5150those which have no call-preserved registers to use instead.
5151
5152Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5153
5154@item -ftree-pre
5155Perform Partial Redundancy Elimination (PRE) on trees. This flag is
5156enabled by default at @option{-O2} and @option{-O3}.
5157
5158@item -ftree-fre
5159Perform Full Redundancy Elimination (FRE) on trees. The difference
5160between FRE and PRE is that FRE only considers expressions
5161that are computed on all paths leading to the redundant computation.
5162This analysis faster than PRE, though it exposes fewer redundancies.
5163This flag is enabled by default at @option{-O} and higher.
5164
5165@item -ftree-copy-prop
5166Perform copy propagation on trees. This pass eliminates unnecessary
5167copy operations. This flag is enabled by default at @option{-O} and
5168higher.
5169
5170@item -ftree-store-copy-prop
5171Perform copy propagation of memory loads and stores. This pass
5172eliminates unnecessary copy operations in memory references
5173(structures, global variables, arrays, etc). This flag is enabled by
5174default at @option{-O2} and higher.
5175
5176@item -ftree-salias
5177Perform structural alias analysis on trees. This flag
5178is enabled by default at @option{-O} and higher.
5179
5180@item -fipa-pta
5181Perform interprocedural pointer analysis.
5182
5183@item -ftree-sink
5184Perform forward store motion on trees. This flag is
5185enabled by default at @option{-O} and higher.
5186
5187@item -ftree-ccp
5188Perform sparse conditional constant propagation (CCP) on trees. This
5189pass only operates on local scalar variables and is enabled by default
5190at @option{-O} and higher.
5191
5192@item -ftree-store-ccp
5193Perform sparse conditional constant propagation (CCP) on trees. This
5194pass operates on both local scalar variables and memory stores and
5195loads (global variables, structures, arrays, etc). This flag is
5196enabled by default at @option{-O2} and higher.
5197
5198@item -ftree-dce
5199Perform dead code elimination (DCE) on trees. This flag is enabled by
5200default at @option{-O} and higher.
5201
5202@item -ftree-dominator-opts
5203Perform a variety of simple scalar cleanups (constant/copy
5204propagation, redundancy elimination, range propagation and expression
5205simplification) based on a dominator tree traversal. This also
5206performs jump threading (to reduce jumps to jumps). This flag is
5207enabled by default at @option{-O} and higher.
5208
5209@item -ftree-ch
5210Perform loop header copying on trees. This is beneficial since it increases
5211effectiveness of code motion optimizations. It also saves one jump. This flag
5212is enabled by default at @option{-O} and higher. It is not enabled
5213for @option{-Os}, since it usually increases code size.
5214
5215@item -ftree-loop-optimize
5216Perform loop optimizations on trees. This flag is enabled by default
5217at @option{-O} and higher.
5218
5219@item -ftree-loop-linear
5220Perform linear loop transformations on tree. This flag can improve cache
5221performance and allow further loop optimizations to take place.
5222
5223@item -ftree-loop-im
5224Perform loop invariant motion on trees. This pass moves only invariants that
5225would be hard to handle at RTL level (function calls, operations that expand to
5226nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
5227operands of conditions that are invariant out of the loop, so that we can use
5228just trivial invariantness analysis in loop unswitching. The pass also includes
5229store motion.
5230
5231@item -ftree-loop-ivcanon
5232Create a canonical counter for number of iterations in the loop for that
5233determining number of iterations requires complicated analysis. Later
5234optimizations then may determine the number easily. Useful especially
5235in connection with unrolling.
5236
5237@item -fivopts
5238Perform induction variable optimizations (strength reduction, induction
5239variable merging and induction variable elimination) on trees.
5240
5241@item -ftree-sra
5242Perform scalar replacement of aggregates. This pass replaces structure
5243references with scalars to prevent committing structures to memory too
5244early. This flag is enabled by default at @option{-O} and higher.
5245
5246@item -ftree-copyrename
5247Perform copy renaming on trees. This pass attempts to rename compiler
5248temporaries to other variables at copy locations, usually resulting in
5249variable names which more closely resemble the original variables. This flag
5250is enabled by default at @option{-O} and higher.
5251
5252@item -ftree-ter
5253Perform temporary expression replacement during the SSA->normal phase. Single
5254use/single def temporaries are replaced at their use location with their
5255defining expression. This results in non-GIMPLE code, but gives the expanders
5256much more complex trees to work on resulting in better RTL generation. This is
5257enabled by default at @option{-O} and higher.
5258
5259@item -ftree-lrs
5260Perform live range splitting during the SSA->normal phase. Distinct live
5261ranges of a variable are split into unique variables, allowing for better
5262optimization later. This is enabled by default at @option{-O} and higher.
5263
5264@item -ftree-vectorize
5265Perform loop vectorization on trees.
5266
5267@item -ftree-vect-loop-version
5268@opindex ftree-vect-loop-version
5269Perform loop versioning when doing loop vectorization on trees. When a loop
5270appears to be vectorizable except that data alignment or data dependence cannot
5271be determined at compile time then vectorized and non-vectorized versions of
5272the loop are generated along with runtime checks for alignment or dependence
5273to control which version is executed. This option is enabled by default
5274except at level @option{-Os} where it is disabled.
5275
5276@item -ftree-vrp
5277Perform Value Range Propagation on trees. This is similar to the
5278constant propagation pass, but instead of values, ranges of values are
5279propagated. This allows the optimizers to remove unnecessary range
5280checks like array bound checks and null pointer checks. This is
5281enabled by default at @option{-O2} and higher. Null pointer check
5282elimination is only done if @option{-fdelete-null-pointer-checks} is
5283enabled.
5284
5285@item -ftracer
5286@opindex ftracer
5287Perform tail duplication to enlarge superblock size. This transformation
5288simplifies the control flow of the function allowing other optimizations to do
5289better job.
5290
5291@item -funroll-loops
5292@opindex funroll-loops
5293Unroll loops whose number of iterations can be determined at compile
5294time or upon entry to the loop. @option{-funroll-loops} implies
5295@option{-frerun-cse-after-loop}. This option makes code larger,
5296and may or may not make it run faster.
5297
5298@item -funroll-all-loops
5299@opindex funroll-all-loops
5300Unroll all loops, even if their number of iterations is uncertain when
5301the loop is entered. This usually makes programs run more slowly.
5302@option{-funroll-all-loops} implies the same options as
5303@option{-funroll-loops},
5304
5305@item -fsplit-ivs-in-unroller
5306@opindex fsplit-ivs-in-unroller
5307Enables expressing of values of induction variables in later iterations
5308of the unrolled loop using the value in the first iteration. This breaks
5309long dependency chains, thus improving efficiency of the scheduling passes.
5310
5311Combination of @option{-fweb} and CSE is often sufficient to obtain the
5312same effect. However in cases the loop body is more complicated than
5313a single basic block, this is not reliable. It also does not work at all
5314on some of the architectures due to restrictions in the CSE pass.
5315
5316This optimization is enabled by default.
5317
5318@item -fvariable-expansion-in-unroller
5319@opindex fvariable-expansion-in-unroller
5320With this option, the compiler will create multiple copies of some
5321local variables when unrolling a loop which can result in superior code.
5322
5323@item -fprefetch-loop-arrays
5324@opindex fprefetch-loop-arrays
5325If supported by the target machine, generate instructions to prefetch
5326memory to improve the performance of loops that access large arrays.
5327
5328This option may generate better or worse code; results are highly
5329dependent on the structure of loops within the source code.
5330
5331Disabled at level @option{-Os}.
5332
5333@item -fno-peephole
5334@itemx -fno-peephole2
5335@opindex fno-peephole
5336@opindex fno-peephole2
5337Disable any machine-specific peephole optimizations. The difference
5338between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
5339are implemented in the compiler; some targets use one, some use the
5340other, a few use both.
5341
5342@option{-fpeephole} is enabled by default.
5343@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5344
5345@item -fno-guess-branch-probability
5346@opindex fno-guess-branch-probability
5347Do not guess branch probabilities using heuristics.
5348
5349GCC will use heuristics to guess branch probabilities if they are
5350not provided by profiling feedback (@option{-fprofile-arcs}). These
5351heuristics are based on the control flow graph. If some branch probabilities
5352are specified by @samp{__builtin_expect}, then the heuristics will be
5353used to guess branch probabilities for the rest of the control flow graph,
5354taking the @samp{__builtin_expect} info into account. The interactions
5355between the heuristics and @samp{__builtin_expect} can be complex, and in
5356some cases, it may be useful to disable the heuristics so that the effects
5357of @samp{__builtin_expect} are easier to understand.
5358
5359The default is @option{-fguess-branch-probability} at levels
5360@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5361
5362@item -freorder-blocks
5363@opindex freorder-blocks
5364Reorder basic blocks in the compiled function in order to reduce number of
5365taken branches and improve code locality.
5366
5367Enabled at levels @option{-O2}, @option{-O3}.
5368
5369@item -freorder-blocks-and-partition
5370@opindex freorder-blocks-and-partition
5371In addition to reordering basic blocks in the compiled function, in order
5372to reduce number of taken branches, partitions hot and cold basic blocks
5373into separate sections of the assembly and .o files, to improve
5374paging and cache locality performance.
5375
5376This optimization is automatically turned off in the presence of
5377exception handling, for linkonce sections, for functions with a user-defined
5378section attribute and on any architecture that does not support named
5379sections.
5380
5381@item -freorder-functions
5382@opindex freorder-functions
5383Reorder functions in the object file in order to
5384improve code locality. This is implemented by using special
5385subsections @code{.text.hot} for most frequently executed functions and
5386@code{.text.unlikely} for unlikely executed functions. Reordering is done by
5387the linker so object file format must support named sections and linker must
5388place them in a reasonable way.
5389
5390Also profile feedback must be available in to make this option effective. See
5391@option{-fprofile-arcs} for details.
5392
5393Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5394
5395@item -fstrict-aliasing
5396@opindex fstrict-aliasing
5397Allows the compiler to assume the strictest aliasing rules applicable to
5398the language being compiled. For C (and C++), this activates
5399optimizations based on the type of expressions. In particular, an
5400object of one type is assumed never to reside at the same address as an
5401object of a different type, unless the types are almost the same. For
5402example, an @code{unsigned int} can alias an @code{int}, but not a
5403@code{void*} or a @code{double}. A character type may alias any other
5404type.
5405
5406Pay special attention to code like this:
5407@smallexample
5408union a_union @{
5409 int i;
5410 double d;
5411@};
5412
5413int f() @{
5414 a_union t;
5415 t.d = 3.0;
5416 return t.i;
5417@}
5418@end smallexample
5419The practice of reading from a different union member than the one most
5420recently written to (called ``type-punning'') is common. Even with
5421@option{-fstrict-aliasing}, type-punning is allowed, provided the memory
5422is accessed through the union type. So, the code above will work as
5423expected. However, this code might not:
5424@smallexample
5425int f() @{
5426 a_union t;
5427 int* ip;
5428 t.d = 3.0;
5429 ip = &t.i;
5430 return *ip;
5431@}
5432@end smallexample
5433
5434Every language that wishes to perform language-specific alias analysis
5435should define a function that computes, given an @code{tree}
5436node, an alias set for the node. Nodes in different alias sets are not
5437allowed to alias. For an example, see the C front-end function
5438@code{c_get_alias_set}.
5439
5440Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5441
5442@item -fstrict-overflow
5443@opindex fstrict-overflow
5444Allow the compiler to assume strict signed overflow rules, depending
5445on the language being compiled. For C (and C++) this means that
5446overflow when doing arithmetic with signed numbers is undefined, which
5447means that the compiler may assume that it will not happen. This
5448permits various optimizations. For example, the compiler will assume
5449that an expression like @code{i + 10 > i} will always be true for
5450signed @code{i}. This assumption is only valid if signed overflow is
5451undefined, as the expression is false if @code{i + 10} overflows when
5452using twos complement arithmetic. When this option is in effect any
5453attempt to determine whether an operation on signed numbers will
5454overflow must be written carefully to not actually involve overflow.
5455
5456See also the @option{-fwrapv} option. Using @option{-fwrapv} means
5457that signed overflow is fully defined: it wraps. When
5458@option{-fwrapv} is used, there is no difference between
5459@option{-fstrict-overflow} and @option{-fno-strict-overflow}. With
5460@option{-fwrapv} certain types of overflow are permitted. For
5461example, if the compiler gets an overflow when doing arithmetic on
5462constants, the overflowed value can still be used with
5463@option{-fwrapv}, but not otherwise.
5464
5465The @option{-fstrict-overflow} option is enabled at levels
5466@option{-O2}, @option{-O3}, @option{-Os}.
5467
5468@item -falign-functions
5469@itemx -falign-functions=@var{n}
5470@opindex falign-functions
5471Align the start of functions to the next power-of-two greater than
5472@var{n}, skipping up to @var{n} bytes. For instance,
5473@option{-falign-functions=32} aligns functions to the next 32-byte
5474boundary, but @option{-falign-functions=24} would align to the next
547532-byte boundary only if this can be done by skipping 23 bytes or less.
5476
5477@option{-fno-align-functions} and @option{-falign-functions=1} are
5478equivalent and mean that functions will not be aligned.
5479
5480Some assemblers only support this flag when @var{n} is a power of two;
5481in that case, it is rounded up.
5482
5483If @var{n} is not specified or is zero, use a machine-dependent default.
5484
5485Enabled at levels @option{-O2}, @option{-O3}.
5486
5487@item -falign-labels
5488@itemx -falign-labels=@var{n}
5489@opindex falign-labels
5490Align all branch targets to a power-of-two boundary, skipping up to
5491@var{n} bytes like @option{-falign-functions}. This option can easily
5492make code slower, because it must insert dummy operations for when the
5493branch target is reached in the usual flow of the code.
5494
5495@option{-fno-align-labels} and @option{-falign-labels=1} are
5496equivalent and mean that labels will not be aligned.
5497
5498If @option{-falign-loops} or @option{-falign-jumps} are applicable and
5499are greater than this value, then their values are used instead.
5500
5501If @var{n} is not specified or is zero, use a machine-dependent default
5502which is very likely to be @samp{1}, meaning no alignment.
5503
5504Enabled at levels @option{-O2}, @option{-O3}.
5505
5506@item -falign-loops
5507@itemx -falign-loops=@var{n}
5508@opindex falign-loops
5509Align loops to a power-of-two boundary, skipping up to @var{n} bytes
5510like @option{-falign-functions}. The hope is that the loop will be
5511executed many times, which will make up for any execution of the dummy
5512operations.
5513
5514@option{-fno-align-loops} and @option{-falign-loops=1} are
5515equivalent and mean that loops will not be aligned.
5516
5517If @var{n} is not specified or is zero, use a machine-dependent default.
5518
5519Enabled at levels @option{-O2}, @option{-O3}.
5520
5521@item -falign-jumps
5522@itemx -falign-jumps=@var{n}
5523@opindex falign-jumps
5524Align branch targets to a power-of-two boundary, for branch targets
5525where the targets can only be reached by jumping, skipping up to @var{n}
5526bytes like @option{-falign-functions}. In this case, no dummy operations
5527need be executed.
5528
5529@option{-fno-align-jumps} and @option{-falign-jumps=1} are
5530equivalent and mean that loops will not be aligned.
5531
5532If @var{n} is not specified or is zero, use a machine-dependent default.
5533
5534Enabled at levels @option{-O2}, @option{-O3}.
5535
5536@item -funit-at-a-time
5537@opindex funit-at-a-time
5538Parse the whole compilation unit before starting to produce code.
5539This allows some extra optimizations to take place but consumes
5540more memory (in general). There are some compatibility issues
5541with @emph{unit-at-a-time} mode:
5542@itemize @bullet
5543@item
5544enabling @emph{unit-at-a-time} mode may change the order
5545in which functions, variables, and top-level @code{asm} statements
5546are emitted, and will likely break code relying on some particular
5547ordering. The majority of such top-level @code{asm} statements,
5548though, can be replaced by @code{section} attributes. The
5549@option{fno-toplevel-reorder} option may be used to keep the ordering
5550used in the input file, at the cost of some optimizations.
5551
5552@item
5553@emph{unit-at-a-time} mode removes unreferenced static variables
5554and functions. This may result in undefined references
5555when an @code{asm} statement refers directly to variables or functions
5556that are otherwise unused. In that case either the variable/function
5557shall be listed as an operand of the @code{asm} statement operand or,
5558in the case of top-level @code{asm} statements the attribute @code{used}
5559shall be used on the declaration.
5560
5561@item
5562Static functions now can use non-standard passing conventions that
5563may break @code{asm} statements calling functions directly. Again,
5564attribute @code{used} will prevent this behavior.
5565@end itemize
5566
5567As a temporary workaround, @option{-fno-unit-at-a-time} can be used,
5568but this scheme may not be supported by future releases of GCC@.
5569
5570Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5571
5572@item -fno-toplevel-reorder
5573Do not reorder top-level functions, variables, and @code{asm}
5574statements. Output them in the same order that they appear in the
5575input file. When this option is used, unreferenced static variables
5576will not be removed. This option is intended to support existing code
5577which relies on a particular ordering. For new code, it is better to
5578use attributes.
5579
5580@item -fweb
5581@opindex fweb
5582Constructs webs as commonly used for register allocation purposes and assign
5583each web individual pseudo register. This allows the register allocation pass
5584to operate on pseudos directly, but also strengthens several other optimization
5585passes, such as CSE, loop optimizer and trivial dead code remover. It can,
5586however, make debugging impossible, since variables will no longer stay in a
5587``home register''.
5588
5589Enabled by default with @option{-funroll-loops}.
5590
5591@item -fwhole-program
5592@opindex fwhole-program
5593Assume that the current compilation unit represents whole program being
5594compiled. All public functions and variables with the exception of @code{main}
5595and those merged by attribute @code{externally_visible} become static functions
5596and in a affect gets more aggressively optimized by interprocedural optimizers.
5597While this option is equivalent to proper use of @code{static} keyword for
5598programs consisting of single file, in combination with option
5599@option{--combine} this flag can be used to compile most of smaller scale C
5600programs since the functions and variables become local for the whole combined
5601compilation unit, not for the single source file itself.
5602
5603
5604@item -fno-cprop-registers
5605@opindex fno-cprop-registers
5606After register allocation and post-register allocation instruction splitting,
5607we perform a copy-propagation pass to try to reduce scheduling dependencies
5608and occasionally eliminate the copy.
5609
5610Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5611
5612@item -fprofile-generate
5613@opindex fprofile-generate
5614
5615Enable options usually used for instrumenting application to produce
5616profile useful for later recompilation with profile feedback based
5617optimization. You must use @option{-fprofile-generate} both when
5618compiling and when linking your program.
5619
5620The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
5621
5622@item -fprofile-use
5623@opindex fprofile-use
5624Enable profile feedback directed optimizations, and optimizations
5625generally profitable only with profile feedback available.
5626
5627The following options are enabled: @code{-fbranch-probabilities}, @code{-fvpt},
5628@code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}
5629
5630@end table
5631
5632The following options control compiler behavior regarding floating
5633point arithmetic. These options trade off between speed and
5634correctness. All must be specifically enabled.
5635
5636@table @gcctabopt
5637@item -ffloat-store
5638@opindex ffloat-store
5639Do not store floating point variables in registers, and inhibit other
5640options that might change whether a floating point value is taken from a
5641register or memory.
5642
5643@cindex floating point precision
5644This option prevents undesirable excess precision on machines such as
5645the 68000 where the floating registers (of the 68881) keep more
5646precision than a @code{double} is supposed to have. Similarly for the
5647x86 architecture. For most programs, the excess precision does only
5648good, but a few programs rely on the precise definition of IEEE floating
5649point. Use @option{-ffloat-store} for such programs, after modifying
5650them to store all pertinent intermediate computations into variables.
5651
5652@item -ffast-math
5653@opindex ffast-math
5654Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
5655@option{-fno-trapping-math}, @option{-ffinite-math-only},
5656@option{-fno-rounding-math}, @option{-fno-signaling-nans}
5657and @option{fcx-limited-range}.
5658
5659This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
5660
5661This option should never be turned on by any @option{-O} option since
5662it can result in incorrect output for programs which depend on
5663an exact implementation of IEEE or ISO rules/specifications for
5664math functions.
5665
5666@item -fno-math-errno
5667@opindex fno-math-errno
5668Do not set ERRNO after calling math functions that are executed
5669with a single instruction, e.g., sqrt. A program that relies on
5670IEEE exceptions for math error handling may want to use this flag
5671for speed while maintaining IEEE arithmetic compatibility.
5672
5673This option should never be turned on by any @option{-O} option since
5674it can result in incorrect output for programs which depend on
5675an exact implementation of IEEE or ISO rules/specifications for
5676math functions.
5677
5678The default is @option{-fmath-errno}.
5679
| 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* Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
128 and Objective-C++.
129* Language Independent Options:: Controlling how diagnostics should be
130 formatted.
131* Warning Options:: How picky should the compiler be?
132* Debugging Options:: Symbol tables, measurements, and debugging dumps.
133* Optimize Options:: How much optimization?
134* Preprocessor Options:: Controlling header files and macro definitions.
135 Also, getting dependency information for Make.
136* Assembler Options:: Passing options to the assembler.
137* Link Options:: Specifying libraries and so on.
138* Directory Options:: Where to find header files and libraries.
139 Where to find the compiler executable files.
140* Spec Files:: How to pass switches to sub-processes.
141* Target Options:: Running a cross-compiler, or an old version of GCC.
142* Submodel Options:: Specifying minor hardware or convention variations,
143 such as 68010 vs 68020.
144* Code Gen Options:: Specifying conventions for function calls, data layout
145 and register usage.
146* Environment Variables:: Env vars that affect GCC.
147* Precompiled Headers:: Compiling a header once, and using it many times.
148* Running Protoize:: Automatically adding or removing function prototypes.
149@end menu
150
151@c man begin OPTIONS
152
153@node Option Summary
154@section Option Summary
155
156Here is a summary of all the options, grouped by type. Explanations are
157in the following sections.
158
159@table @emph
160@item Overall Options
161@xref{Overall Options,,Options Controlling the Kind of Output}.
162@gccoptlist{-c -S -E -o @var{file} -combine -pipe -pass-exit-codes @gol
163-x @var{language} -v -### --help --target-help --version @@@var{file}}
164
165@item C Language Options
166@xref{C Dialect Options,,Options Controlling C Dialect}.
167@gccoptlist{-ansi -std=@var{standard} -fgnu89-inline @gol
168-aux-info @var{filename} @gol
169-fno-asm -fno-builtin -fno-builtin-@var{function} @gol
170-fhosted -ffreestanding -fopenmp -fms-extensions @gol
171-trigraphs -no-integrated-cpp -traditional -traditional-cpp @gol
172-fallow-single-precision -fcond-mismatch @gol
173-fsigned-bitfields -fsigned-char @gol
174-funsigned-bitfields -funsigned-char}
175
176@item C++ Language Options
177@xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
178@gccoptlist{-fabi-version=@var{n} -fno-access-control -fcheck-new @gol
179-fconserve-space -ffriend-injection @gol
180-fno-elide-constructors @gol
181-fno-enforce-eh-specs @gol
182-ffor-scope -fno-for-scope -fno-gnu-keywords @gol
183-fno-implicit-templates @gol
184-fno-implicit-inline-templates @gol
185-fno-implement-inlines -fms-extensions @gol
186-fno-nonansi-builtins -fno-operator-names @gol
187-fno-optional-diags -fpermissive @gol
188-frepo -fno-rtti -fstats -ftemplate-depth-@var{n} @gol
189-fno-threadsafe-statics -fuse-cxa-atexit -fno-weak -nostdinc++ @gol
190-fno-default-inline -fvisibility-inlines-hidden @gol
191-Wabi -Wctor-dtor-privacy @gol
192-Wnon-virtual-dtor -Wreorder @gol
193-Weffc++ -Wno-deprecated -Wstrict-null-sentinel @gol
194-Wno-non-template-friend -Wold-style-cast @gol
195-Woverloaded-virtual -Wno-pmf-conversions @gol
196-Wsign-promo}
197
198@item Objective-C and Objective-C++ Language Options
199@xref{Objective-C and Objective-C++ Dialect Options,,Options Controlling
200Objective-C and Objective-C++ Dialects}.
201@gccoptlist{-fconstant-string-class=@var{class-name} @gol
202-fgnu-runtime -fnext-runtime @gol
203-fno-nil-receivers @gol
204-fobjc-call-cxx-cdtors @gol
205-fobjc-direct-dispatch @gol
206-fobjc-exceptions @gol
207-fobjc-gc @gol
208-freplace-objc-classes @gol
209-fzero-link @gol
210-gen-decls @gol
211-Wassign-intercept @gol
212-Wno-protocol -Wselector @gol
213-Wstrict-selector-match @gol
214-Wundeclared-selector}
215
216@item Language Independent Options
217@xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}.
218@gccoptlist{-fmessage-length=@var{n} @gol
219-fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]} @gol
220-fdiagnostics-show-option}
221
222@item Warning Options
223@xref{Warning Options,,Options to Request or Suppress Warnings}.
224@gccoptlist{-fsyntax-only -pedantic -pedantic-errors @gol
225-w -Wextra -Wall -Waddress -Waggregate-return -Wno-attributes @gol
226-Wc++-compat -Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment @gol
227-Wconversion -Wno-deprecated-declarations @gol
228-Wdisabled-optimization -Wno-div-by-zero -Wno-endif-labels @gol
229-Werror -Werror=* -Werror-implicit-function-declaration @gol
230-Wfatal-errors -Wfloat-equal -Wformat -Wformat=2 @gol
231-Wno-format-extra-args -Wformat-nonliteral @gol
232-Wformat-security -Wformat-y2k @gol
233-Wimplicit -Wimplicit-function-declaration -Wimplicit-int @gol
234-Wimport -Wno-import -Winit-self -Winline @gol
235-Wno-int-to-pointer-cast @gol
236-Wno-invalid-offsetof -Winvalid-pch @gol
237-Wlarger-than-@var{len} -Wunsafe-loop-optimizations -Wlong-long @gol
238-Wmain -Wmissing-braces -Wmissing-field-initializers @gol
239-Wmissing-format-attribute -Wmissing-include-dirs @gol
240-Wmissing-noreturn @gol
241-Wno-multichar -Wnonnull -Wno-overflow @gol
242-Woverlength-strings -Wpacked -Wpadded @gol
243-Wparentheses -Wpointer-arith -Wno-pointer-to-int-cast @gol
244-Wredundant-decls @gol
245-Wreturn-type -Wsequence-point -Wshadow @gol
246-Wsign-compare -Wstack-protector @gol
247-Wstrict-aliasing -Wstrict-aliasing=2 @gol
248-Wstrict-overflow -Wstrict-overflow=@var{n} @gol
249-Wswitch -Wswitch-default -Wswitch-enum @gol
250-Wsystem-headers -Wtrigraphs -Wundef -Wuninitialized @gol
251-Wunknown-pragmas -Wno-pragmas -Wunreachable-code @gol
252-Wunused -Wunused-function -Wunused-label -Wunused-parameter @gol
253-Wunused-value -Wunused-variable -Wvariadic-macros @gol
254-Wvolatile-register-var -Wwrite-strings}
255
256@item C-only Warning Options
257@gccoptlist{-Wbad-function-cast -Wmissing-declarations @gol
258-Wmissing-prototypes -Wnested-externs -Wold-style-definition @gol
259-Wstrict-prototypes -Wtraditional @gol
260-Wdeclaration-after-statement -Wpointer-sign}
261
262@item Debugging Options
263@xref{Debugging Options,,Options for Debugging Your Program or GCC}.
264@gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
265-fdump-noaddr -fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} @gol
266-fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
267-fdump-ipa-all -fdump-ipa-cgraph @gol
268-fdump-tree-all @gol
269-fdump-tree-original@r{[}-@var{n}@r{]} @gol
270-fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
271-fdump-tree-inlined@r{[}-@var{n}@r{]} @gol
272-fdump-tree-cfg -fdump-tree-vcg -fdump-tree-alias @gol
273-fdump-tree-ch @gol
274-fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol
275-fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol
276-fdump-tree-gimple@r{[}-raw@r{]} -fdump-tree-mudflap@r{[}-@var{n}@r{]} @gol
277-fdump-tree-dom@r{[}-@var{n}@r{]} @gol
278-fdump-tree-dse@r{[}-@var{n}@r{]} @gol
279-fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol
280-fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
281-fdump-tree-copyrename@r{[}-@var{n}@r{]} @gol
282-fdump-tree-nrv -fdump-tree-vect @gol
283-fdump-tree-sink @gol
284-fdump-tree-sra@r{[}-@var{n}@r{]} @gol
285-fdump-tree-salias @gol
286-fdump-tree-fre@r{[}-@var{n}@r{]} @gol
287-fdump-tree-vrp@r{[}-@var{n}@r{]} @gol
288-ftree-vectorizer-verbose=@var{n} @gol
289-fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol
290-feliminate-dwarf2-dups -feliminate-unused-debug-types @gol
291-feliminate-unused-debug-symbols -femit-class-debug-always @gol
292-fmem-report -fprofile-arcs @gol
293-frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
294-ftest-coverage -ftime-report -fvar-tracking @gol
295-g -g@var{level} -gcoff -gdwarf-2 @gol
296-ggdb -gstabs -gstabs+ -gvms -gxcoff -gxcoff+ @gol
297-p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol
298-print-multi-directory -print-multi-lib @gol
299-print-prog-name=@var{program} -print-search-dirs -Q @gol
300-save-temps -time}
301
302@item Optimization Options
303@xref{Optimize Options,,Options that Control Optimization}.
304@gccoptlist{-falign-functions=@var{n} -falign-jumps=@var{n} @gol
305-falign-labels=@var{n} -falign-loops=@var{n} @gol
306-fbounds-check -fmudflap -fmudflapth -fmudflapir @gol
307-fbranch-probabilities -fprofile-values -fvpt -fbranch-target-load-optimize @gol
308-fbranch-target-load-optimize2 -fbtr-bb-exclusive @gol
309-fcaller-saves -fcprop-registers -fcse-follow-jumps @gol
310-fcse-skip-blocks -fcx-limited-range -fdata-sections @gol
311-fdelayed-branch -fdelete-null-pointer-checks -fearly-inlining @gol
312-fexpensive-optimizations -ffast-math -ffloat-store @gol
313-fforce-addr -ffunction-sections @gol
314-fgcse -fgcse-lm -fgcse-sm -fgcse-las -fgcse-after-reload @gol
315-fcrossjumping -fif-conversion -fif-conversion2 @gol
316-finline-functions -finline-functions-called-once @gol
317-finline-limit=@var{n} -fkeep-inline-functions @gol
318-fkeep-static-consts -fmerge-constants -fmerge-all-constants @gol
319-fmodulo-sched -fno-branch-count-reg @gol
320-fno-default-inline -fno-defer-pop -fmove-loop-invariants @gol
321-fno-function-cse -fno-guess-branch-probability @gol
322-fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol
323-funsafe-math-optimizations -funsafe-loop-optimizations -ffinite-math-only @gol
324-fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol
325-fomit-frame-pointer -foptimize-register-move @gol
326-foptimize-sibling-calls -fprefetch-loop-arrays @gol
327-fprofile-generate -fprofile-use @gol
328-fregmove -frename-registers @gol
329-freorder-blocks -freorder-blocks-and-partition -freorder-functions @gol
330-frerun-cse-after-loop @gol
331-frounding-math -frtl-abstract-sequences @gol
332-fschedule-insns -fschedule-insns2 @gol
333-fno-sched-interblock -fno-sched-spec -fsched-spec-load @gol
334-fsched-spec-load-dangerous @gol
335-fsched-stalled-insns=@var{n} -fsched-stalled-insns-dep=@var{n} @gol
336-fsched2-use-superblocks @gol
337-fsched2-use-traces -fsee -freschedule-modulo-scheduled-loops @gol
338-fsection-anchors -fsignaling-nans -fsingle-precision-constant @gol
339-fstack-protector -fstack-protector-all @gol
340-fstrict-aliasing -fstrict-overflow -ftracer -fthread-jumps @gol
341-funroll-all-loops -funroll-loops -fpeel-loops @gol
342-fsplit-ivs-in-unroller -funswitch-loops @gol
343-fvariable-expansion-in-unroller @gol
344-ftree-pre -ftree-ccp -ftree-dce -ftree-loop-optimize @gol
345-ftree-loop-linear -ftree-loop-im -ftree-loop-ivcanon -fivopts @gol
346-ftree-dominator-opts -ftree-dse -ftree-copyrename -ftree-sink @gol
347-ftree-ch -ftree-sra -ftree-ter -ftree-lrs -ftree-fre -ftree-vectorize @gol
348-ftree-vect-loop-version -ftree-salias -fipa-pta -fweb @gol
349-ftree-copy-prop -ftree-store-ccp -ftree-store-copy-prop -fwhole-program @gol
350--param @var{name}=@var{value}
351-O -O0 -O1 -O2 -O3 -Os}
352
353@item Preprocessor Options
354@xref{Preprocessor Options,,Options Controlling the Preprocessor}.
355@gccoptlist{-A@var{question}=@var{answer} @gol
356-A-@var{question}@r{[}=@var{answer}@r{]} @gol
357-C -dD -dI -dM -dN @gol
358-D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol
359-idirafter @var{dir} @gol
360-include @var{file} -imacros @var{file} @gol
361-iprefix @var{file} -iwithprefix @var{dir} @gol
362-iwithprefixbefore @var{dir} -isystem @var{dir} @gol
363-imultilib @var{dir} -isysroot @var{dir} @gol
364-M -MM -MF -MG -MP -MQ -MT -nostdinc @gol
365-P -fworking-directory -remap @gol
366-trigraphs -undef -U@var{macro} -Wp,@var{option} @gol
367-Xpreprocessor @var{option}}
368
369@item Assembler Option
370@xref{Assembler Options,,Passing Options to the Assembler}.
371@gccoptlist{-Wa,@var{option} -Xassembler @var{option}}
372
373@item Linker Options
374@xref{Link Options,,Options for Linking}.
375@gccoptlist{@var{object-file-name} -l@var{library} @gol
376-nostartfiles -nodefaultlibs -nostdlib -pie -rdynamic @gol
377-s -static -static-libgcc -shared -shared-libgcc -symbolic @gol
378-Wl,@var{option} -Xlinker @var{option} @gol
379-u @var{symbol}}
380
381@item Directory Options
382@xref{Directory Options,,Options for Directory Search}.
383@gccoptlist{-B@var{prefix} -I@var{dir} -iquote@var{dir} -L@var{dir}
384-specs=@var{file} -I- --sysroot=@var{dir}}
385
386@item Target Options
387@c I wrote this xref this way to avoid overfull hbox. -- rms
388@xref{Target Options}.
389@gccoptlist{-V @var{version} -b @var{machine}}
390
391@item Machine Dependent Options
392@xref{Submodel Options,,Hardware Models and Configurations}.
393@c This list is ordered alphanumerically by subsection name.
394@c Try and put the significant identifier (CPU or system) first,
395@c so users have a clue at guessing where the ones they want will be.
396
397@emph{ARC Options}
398@gccoptlist{-EB -EL @gol
399-mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text-section} @gol
400-mdata=@var{data-section} -mrodata=@var{readonly-data-section}}
401
402@emph{ARM Options}
403@gccoptlist{-mapcs-frame -mno-apcs-frame @gol
404-mabi=@var{name} @gol
405-mapcs-stack-check -mno-apcs-stack-check @gol
406-mapcs-float -mno-apcs-float @gol
407-mapcs-reentrant -mno-apcs-reentrant @gol
408-msched-prolog -mno-sched-prolog @gol
409-mlittle-endian -mbig-endian -mwords-little-endian @gol
410-mfloat-abi=@var{name} -msoft-float -mhard-float -mfpe @gol
411-mthumb-interwork -mno-thumb-interwork @gol
412-mcpu=@var{name} -march=@var{name} -mfpu=@var{name} @gol
413-mstructure-size-boundary=@var{n} @gol
414-mabort-on-noreturn @gol
415-mlong-calls -mno-long-calls @gol
416-msingle-pic-base -mno-single-pic-base @gol
417-mpic-register=@var{reg} @gol
418-mnop-fun-dllimport @gol
419-mcirrus-fix-invalid-insns -mno-cirrus-fix-invalid-insns @gol
420-mpoke-function-name @gol
421-mthumb -marm @gol
422-mtpcs-frame -mtpcs-leaf-frame @gol
423-mcaller-super-interworking -mcallee-super-interworking @gol
424-mtp=@var{name}}
425
426@emph{AVR Options}
427@gccoptlist{-mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts @gol
428-mcall-prologues -mno-tablejump -mtiny-stack -mint8}
429
430@emph{Blackfin Options}
431@gccoptlist{-momit-leaf-frame-pointer -mno-omit-leaf-frame-pointer @gol
432-mspecld-anomaly -mno-specld-anomaly -mcsync-anomaly -mno-csync-anomaly @gol
433-mlow-64k -mno-low64k -mid-shared-library @gol
434-mno-id-shared-library -mshared-library-id=@var{n} @gol
435-mlong-calls -mno-long-calls}
436
437@emph{CRIS Options}
438@gccoptlist{-mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol
439-mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol
440-metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol
441-mstack-align -mdata-align -mconst-align @gol
442-m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol
443-melf -maout -melinux -mlinux -sim -sim2 @gol
444-mmul-bug-workaround -mno-mul-bug-workaround}
445
446@emph{CRX Options}
447@gccoptlist{-mmac -mpush-args}
448
449@emph{Darwin Options}
450@gccoptlist{-all_load -allowable_client -arch -arch_errors_fatal @gol
451-arch_only -bind_at_load -bundle -bundle_loader @gol
452-client_name -compatibility_version -current_version @gol
453-dead_strip @gol
454-dependency-file -dylib_file -dylinker_install_name @gol
455-dynamic -dynamiclib -exported_symbols_list @gol
456-filelist -flat_namespace -force_cpusubtype_ALL @gol
457-force_flat_namespace -headerpad_max_install_names @gol
458-image_base -init -install_name -keep_private_externs @gol
459-multi_module -multiply_defined -multiply_defined_unused @gol
460-noall_load -no_dead_strip_inits_and_terms @gol
461-nofixprebinding -nomultidefs -noprebind -noseglinkedit @gol
462-pagezero_size -prebind -prebind_all_twolevel_modules @gol
463-private_bundle -read_only_relocs -sectalign @gol
464-sectobjectsymbols -whyload -seg1addr @gol
465-sectcreate -sectobjectsymbols -sectorder @gol
466-segaddr -segs_read_only_addr -segs_read_write_addr @gol
467-seg_addr_table -seg_addr_table_filename -seglinkedit @gol
468-segprot -segs_read_only_addr -segs_read_write_addr @gol
469-single_module -static -sub_library -sub_umbrella @gol
470-twolevel_namespace -umbrella -undefined @gol
471-unexported_symbols_list -weak_reference_mismatches @gol
472-whatsloaded -F -gused -gfull -mmacosx-version-min=@var{version} @gol
473-mkernel -mone-byte-bool}
474
475@emph{DEC Alpha Options}
476@gccoptlist{-mno-fp-regs -msoft-float -malpha-as -mgas @gol
477-mieee -mieee-with-inexact -mieee-conformant @gol
478-mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} @gol
479-mtrap-precision=@var{mode} -mbuild-constants @gol
480-mcpu=@var{cpu-type} -mtune=@var{cpu-type} @gol
481-mbwx -mmax -mfix -mcix @gol
482-mfloat-vax -mfloat-ieee @gol
483-mexplicit-relocs -msmall-data -mlarge-data @gol
484-msmall-text -mlarge-text @gol
485-mmemory-latency=@var{time}}
486
487@emph{DEC Alpha/VMS Options}
488@gccoptlist{-mvms-return-codes}
489
490@emph{FRV Options}
491@gccoptlist{-mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 @gol
492-mhard-float -msoft-float @gol
493-malloc-cc -mfixed-cc -mdword -mno-dword @gol
494-mdouble -mno-double @gol
495-mmedia -mno-media -mmuladd -mno-muladd @gol
496-mfdpic -minline-plt -mgprel-ro -multilib-library-pic @gol
497-mlinked-fp -mlong-calls -malign-labels @gol
498-mlibrary-pic -macc-4 -macc-8 @gol
499-mpack -mno-pack -mno-eflags -mcond-move -mno-cond-move @gol
500-moptimize-membar -mno-optimize-membar @gol
501-mscc -mno-scc -mcond-exec -mno-cond-exec @gol
502-mvliw-branch -mno-vliw-branch @gol
503-mmulti-cond-exec -mno-multi-cond-exec -mnested-cond-exec @gol
504-mno-nested-cond-exec -mtomcat-stats @gol
505-mTLS -mtls @gol
506-mcpu=@var{cpu}}
507
508@emph{GNU/Linux Options}
509@gccoptlist{-muclibc}
510
511@emph{H8/300 Options}
512@gccoptlist{-mrelax -mh -ms -mn -mint32 -malign-300}
513
514@emph{HPPA Options}
515@gccoptlist{-march=@var{architecture-type} @gol
516-mbig-switch -mdisable-fpregs -mdisable-indexing @gol
517-mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol
518-mfixed-range=@var{register-range} @gol
519-mjump-in-delay -mlinker-opt -mlong-calls @gol
520-mlong-load-store -mno-big-switch -mno-disable-fpregs @gol
521-mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol
522-mno-jump-in-delay -mno-long-load-store @gol
523-mno-portable-runtime -mno-soft-float @gol
524-mno-space-regs -msoft-float -mpa-risc-1-0 @gol
525-mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime @gol
526-mschedule=@var{cpu-type} -mspace-regs -msio -mwsio @gol
527-munix=@var{unix-std} -nolibdld -static -threads}
528
529@emph{i386 and x86-64 Options}
530@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
531-mfpmath=@var{unit} @gol
532-masm=@var{dialect} -mno-fancy-math-387 @gol
533-mno-fp-ret-in-387 -msoft-float -msvr3-shlib @gol
534-mno-wide-multiply -mrtd -malign-double @gol
535-mpreferred-stack-boundary=@var{num} @gol
536-mmmx -msse -msse2 -msse3 -m3dnow @gol
537-mthreads -mno-align-stringops -minline-all-stringops @gol
538-mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol
539-m96bit-long-double -mregparm=@var{num} -msseregparm @gol
540-mstackrealign @gol
541-momit-leaf-frame-pointer -mno-red-zone -mno-tls-direct-seg-refs @gol
542-mcmodel=@var{code-model} @gol
543-m32 -m64 -mlarge-data-threshold=@var{num}}
544
545@emph{IA-64 Options}
546@gccoptlist{-mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol
547-mvolatile-asm-stop -mregister-names -mno-sdata @gol
548-mconstant-gp -mauto-pic -minline-float-divide-min-latency @gol
549-minline-float-divide-max-throughput @gol
550-minline-int-divide-min-latency @gol
551-minline-int-divide-max-throughput @gol
552-minline-sqrt-min-latency -minline-sqrt-max-throughput @gol
553-mno-dwarf2-asm -mearly-stop-bits @gol
554-mfixed-range=@var{register-range} -mtls-size=@var{tls-size} @gol
555-mtune=@var{cpu-type} -mt -pthread -milp32 -mlp64 @gol
556-mno-sched-br-data-spec -msched-ar-data-spec -mno-sched-control-spec @gol
557-msched-br-in-data-spec -msched-ar-in-data-spec -msched-in-control-spec @gol
558-msched-ldc -mno-sched-control-ldc -mno-sched-spec-verbose @gol
559-mno-sched-prefer-non-data-spec-insns @gol
560-mno-sched-prefer-non-control-spec-insns @gol
561-mno-sched-count-spec-in-critical-path}
562
563@emph{M32R/D Options}
564@gccoptlist{-m32r2 -m32rx -m32r @gol
565-mdebug @gol
566-malign-loops -mno-align-loops @gol
567-missue-rate=@var{number} @gol
568-mbranch-cost=@var{number} @gol
569-mmodel=@var{code-size-model-type} @gol
570-msdata=@var{sdata-type} @gol
571-mno-flush-func -mflush-func=@var{name} @gol
572-mno-flush-trap -mflush-trap=@var{number} @gol
573-G @var{num}}
574
575@emph{M32C Options}
576@gccoptlist{-mcpu=@var{cpu} -msim -memregs=@var{number}}
577
578@emph{M680x0 Options}
579@gccoptlist{-m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol
580-m68060 -mcpu32 -m5200 -mcfv4e -m68881 -mbitfield @gol
581-mc68000 -mc68020 @gol
582-mnobitfield -mrtd -mshort -msoft-float -mpcrel @gol
583-malign-int -mstrict-align -msep-data -mno-sep-data @gol
584-mshared-library-id=n -mid-shared-library -mno-id-shared-library}
585
586@emph{M68hc1x Options}
587@gccoptlist{-m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 @gol
588-mauto-incdec -minmax -mlong-calls -mshort @gol
589-msoft-reg-count=@var{count}}
590
591@emph{MCore Options}
592@gccoptlist{-mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol
593-mno-relax-immediates -mwide-bitfields -mno-wide-bitfields @gol
594-m4byte-functions -mno-4byte-functions -mcallgraph-data @gol
595-mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim @gol
596-mlittle-endian -mbig-endian -m210 -m340 -mstack-increment}
597
598@emph{MIPS Options}
599@gccoptlist{-EL -EB -march=@var{arch} -mtune=@var{arch} @gol
600-mips1 -mips2 -mips3 -mips4 -mips32 -mips32r2 -mips64 @gol
601-mips16 -mno-mips16 -mabi=@var{abi} -mabicalls -mno-abicalls @gol
602-mshared -mno-shared -mxgot -mno-xgot -mgp32 -mgp64 @gol
603-mfp32 -mfp64 -mhard-float -msoft-float @gol
604-msingle-float -mdouble-float -mdsp -mpaired-single -mips3d @gol
605-mlong64 -mlong32 -msym32 -mno-sym32 @gol
606-G@var{num} -membedded-data -mno-embedded-data @gol
607-muninit-const-in-rodata -mno-uninit-const-in-rodata @gol
608-msplit-addresses -mno-split-addresses @gol
609-mexplicit-relocs -mno-explicit-relocs @gol
610-mcheck-zero-division -mno-check-zero-division @gol
611-mdivide-traps -mdivide-breaks @gol
612-mmemcpy -mno-memcpy -mlong-calls -mno-long-calls @gol
613-mmad -mno-mad -mfused-madd -mno-fused-madd -nocpp @gol
614-mfix-r4000 -mno-fix-r4000 -mfix-r4400 -mno-fix-r4400 @gol
615-mfix-vr4120 -mno-fix-vr4120 -mfix-vr4130 @gol
616-mfix-sb1 -mno-fix-sb1 @gol
617-mflush-func=@var{func} -mno-flush-func @gol
618-mbranch-likely -mno-branch-likely @gol
619-mfp-exceptions -mno-fp-exceptions @gol
620-mvr4130-align -mno-vr4130-align}
621
622@emph{MMIX Options}
623@gccoptlist{-mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol
624-mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol
625-melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol
626-mno-base-addresses -msingle-exit -mno-single-exit}
627
628@emph{MN10300 Options}
629@gccoptlist{-mmult-bug -mno-mult-bug @gol
630-mam33 -mno-am33 @gol
631-mam33-2 -mno-am33-2 @gol
632-mreturn-pointer-on-d0 @gol
633-mno-crt0 -mrelax}
634
635@emph{MT Options}
636@gccoptlist{-mno-crt0 -mbacc -msim @gol
637-march=@var{cpu-type} }
638
639@emph{PDP-11 Options}
640@gccoptlist{-mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol
641-mbcopy -mbcopy-builtin -mint32 -mno-int16 @gol
642-mint16 -mno-int32 -mfloat32 -mno-float64 @gol
643-mfloat64 -mno-float32 -mabshi -mno-abshi @gol
644-mbranch-expensive -mbranch-cheap @gol
645-msplit -mno-split -munix-asm -mdec-asm}
646
647@emph{PowerPC Options}
648See RS/6000 and PowerPC Options.
649
650@emph{RS/6000 and PowerPC Options}
651@gccoptlist{-mcpu=@var{cpu-type} @gol
652-mtune=@var{cpu-type} @gol
653-mpower -mno-power -mpower2 -mno-power2 @gol
654-mpowerpc -mpowerpc64 -mno-powerpc @gol
655-maltivec -mno-altivec @gol
656-mpowerpc-gpopt -mno-powerpc-gpopt @gol
657-mpowerpc-gfxopt -mno-powerpc-gfxopt @gol
658-mmfcrf -mno-mfcrf -mpopcntb -mno-popcntb -mfprnd -mno-fprnd @gol
659-mnew-mnemonics -mold-mnemonics @gol
660-mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc @gol
661-m64 -m32 -mxl-compat -mno-xl-compat -mpe @gol
662-malign-power -malign-natural @gol
663-msoft-float -mhard-float -mmultiple -mno-multiple @gol
664-mstring -mno-string -mupdate -mno-update @gol
665-mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol
666-mstrict-align -mno-strict-align -mrelocatable @gol
667-mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol
668-mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol
669-mdynamic-no-pic -maltivec -mswdiv @gol
670-mprioritize-restricted-insns=@var{priority} @gol
671-msched-costly-dep=@var{dependence_type} @gol
672-minsert-sched-nops=@var{scheme} @gol
673-mcall-sysv -mcall-netbsd @gol
674-maix-struct-return -msvr4-struct-return @gol
675-mabi=@var{abi-type} -msecure-plt -mbss-plt @gol
676-misel -mno-isel @gol
677-misel=yes -misel=no @gol
678-mspe -mno-spe @gol
679-mspe=yes -mspe=no @gol
680-mvrsave -mno-vrsave @gol
681-mmulhw -mno-mulhw @gol
682-mdlmzb -mno-dlmzb @gol
683-mfloat-gprs=yes -mfloat-gprs=no -mfloat-gprs=single -mfloat-gprs=double @gol
684-mprototype -mno-prototype @gol
685-msim -mmvme -mads -myellowknife -memb -msdata @gol
686-msdata=@var{opt} -mvxworks -mwindiss -G @var{num} -pthread}
687
688@emph{S/390 and zSeries Options}
689@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
690-mhard-float -msoft-float -mlong-double-64 -mlong-double-128 @gol
691-mbackchain -mno-backchain -mpacked-stack -mno-packed-stack @gol
692-msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol
693-m64 -m31 -mdebug -mno-debug -mesa -mzarch @gol
694-mtpf-trace -mno-tpf-trace -mfused-madd -mno-fused-madd @gol
695-mwarn-framesize -mwarn-dynamicstack -mstack-size -mstack-guard}
696
697@emph{Score Options}
698@gccoptlist{-meb -mel @gol
699-mnhwloop @gol
700-muls @gol
701-mmac @gol
702-mscore5 -mscore5u -mscore7 -mscore7d}
703
704@emph{SH Options}
705@gccoptlist{-m1 -m2 -m2e -m3 -m3e @gol
706-m4-nofpu -m4-single-only -m4-single -m4 @gol
707-m4a-nofpu -m4a-single-only -m4a-single -m4a -m4al @gol
708-m5-64media -m5-64media-nofpu @gol
709-m5-32media -m5-32media-nofpu @gol
710-m5-compact -m5-compact-nofpu @gol
711-mb -ml -mdalign -mrelax @gol
712-mbigtable -mfmovd -mhitachi -mrenesas -mno-renesas -mnomacsave @gol
713-mieee -misize -mpadstruct -mspace @gol
714-mprefergot -musermode -multcost=@var{number} -mdiv=@var{strategy} @gol
715-mdivsi3_libfunc=@var{name} @gol
716-madjust-unroll -mindexed-addressing -mgettrcost=@var{number} -mpt-fixed @gol
717 -minvalid-symbols}
718
719@emph{SPARC Options}
720@gccoptlist{-mcpu=@var{cpu-type} @gol
721-mtune=@var{cpu-type} @gol
722-mcmodel=@var{code-model} @gol
723-m32 -m64 -mapp-regs -mno-app-regs @gol
724-mfaster-structs -mno-faster-structs @gol
725-mfpu -mno-fpu -mhard-float -msoft-float @gol
726-mhard-quad-float -msoft-quad-float @gol
727-mimpure-text -mno-impure-text -mlittle-endian @gol
728-mstack-bias -mno-stack-bias @gol
729-munaligned-doubles -mno-unaligned-doubles @gol
730-mv8plus -mno-v8plus -mvis -mno-vis
731-threads -pthreads -pthread}
732
733@emph{System V Options}
734@gccoptlist{-Qy -Qn -YP,@var{paths} -Ym,@var{dir}}
735
736@emph{TMS320C3x/C4x Options}
737@gccoptlist{-mcpu=@var{cpu} -mbig -msmall -mregparm -mmemparm @gol
738-mfast-fix -mmpyi -mbk -mti -mdp-isr-reload @gol
739-mrpts=@var{count} -mrptb -mdb -mloop-unsigned @gol
740-mparallel-insns -mparallel-mpy -mpreserve-float}
741
742@emph{V850 Options}
743@gccoptlist{-mlong-calls -mno-long-calls -mep -mno-ep @gol
744-mprolog-function -mno-prolog-function -mspace @gol
745-mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol
746-mapp-regs -mno-app-regs @gol
747-mdisable-callt -mno-disable-callt @gol
748-mv850e1 @gol
749-mv850e @gol
750-mv850 -mbig-switch}
751
752@emph{VAX Options}
753@gccoptlist{-mg -mgnu -munix}
754
755@emph{x86-64 Options}
756See i386 and x86-64 Options.
757
758@emph{Xstormy16 Options}
759@gccoptlist{-msim}
760
761@emph{Xtensa Options}
762@gccoptlist{-mconst16 -mno-const16 @gol
763-mfused-madd -mno-fused-madd @gol
764-mtext-section-literals -mno-text-section-literals @gol
765-mtarget-align -mno-target-align @gol
766-mlongcalls -mno-longcalls}
767
768@emph{zSeries Options}
769See S/390 and zSeries Options.
770
771@item Code Generation Options
772@xref{Code Gen Options,,Options for Code Generation Conventions}.
773@gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol
774-ffixed-@var{reg} -fexceptions @gol
775-fnon-call-exceptions -funwind-tables @gol
776-fasynchronous-unwind-tables @gol
777-finhibit-size-directive -finstrument-functions @gol
778-fno-common -fno-ident @gol
779-fpcc-struct-return -fpic -fPIC -fpie -fPIE @gol
780-fno-jump-tables @gol
781-freg-struct-return -fshort-enums @gol
782-fshort-double -fshort-wchar @gol
783-fverbose-asm -fpack-struct[=@var{n}] -fstack-check @gol
784-fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
785-fargument-alias -fargument-noalias @gol
786-fargument-noalias-global -fargument-noalias-anything
787-fleading-underscore -ftls-model=@var{model} @gol
788-ftrapv -fwrapv -fbounds-check @gol
789-fvisibility}
790@end table
791
792@menu
793* Overall Options:: Controlling the kind of output:
794 an executable, object files, assembler files,
795 or preprocessed source.
796* C Dialect Options:: Controlling the variant of C language compiled.
797* C++ Dialect Options:: Variations on C++.
798* Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
799 and Objective-C++.
800* Language Independent Options:: Controlling how diagnostics should be
801 formatted.
802* Warning Options:: How picky should the compiler be?
803* Debugging Options:: Symbol tables, measurements, and debugging dumps.
804* Optimize Options:: How much optimization?
805* Preprocessor Options:: Controlling header files and macro definitions.
806 Also, getting dependency information for Make.
807* Assembler Options:: Passing options to the assembler.
808* Link Options:: Specifying libraries and so on.
809* Directory Options:: Where to find header files and libraries.
810 Where to find the compiler executable files.
811* Spec Files:: How to pass switches to sub-processes.
812* Target Options:: Running a cross-compiler, or an old version of GCC.
813@end menu
814
815@node Overall Options
816@section Options Controlling the Kind of Output
817
818Compilation can involve up to four stages: preprocessing, compilation
819proper, assembly and linking, always in that order. GCC is capable of
820preprocessing and compiling several files either into several
821assembler input files, or into one assembler input file; then each
822assembler input file produces an object file, and linking combines all
823the object files (those newly compiled, and those specified as input)
824into an executable file.
825
826@cindex file name suffix
827For any given input file, the file name suffix determines what kind of
828compilation is done:
829
830@table @gcctabopt
831@item @var{file}.c
832C source code which must be preprocessed.
833
834@item @var{file}.i
835C source code which should not be preprocessed.
836
837@item @var{file}.ii
838C++ source code which should not be preprocessed.
839
840@item @var{file}.m
841Objective-C source code. Note that you must link with the @file{libobjc}
842library to make an Objective-C program work.
843
844@item @var{file}.mi
845Objective-C source code which should not be preprocessed.
846
847@item @var{file}.mm
848@itemx @var{file}.M
849Objective-C++ source code. Note that you must link with the @file{libobjc}
850library to make an Objective-C++ program work. Note that @samp{.M} refers
851to a literal capital M@.
852
853@item @var{file}.mii
854Objective-C++ source code which should not be preprocessed.
855
856@item @var{file}.h
857C, C++, Objective-C or Objective-C++ header file to be turned into a
858precompiled header.
859
860@item @var{file}.cc
861@itemx @var{file}.cp
862@itemx @var{file}.cxx
863@itemx @var{file}.cpp
864@itemx @var{file}.CPP
865@itemx @var{file}.c++
866@itemx @var{file}.C
867C++ source code which must be preprocessed. Note that in @samp{.cxx},
868the last two letters must both be literally @samp{x}. Likewise,
869@samp{.C} refers to a literal capital C@.
870
871@item @var{file}.mm
872@itemx @var{file}.M
873Objective-C++ source code which must be preprocessed.
874
875@item @var{file}.mii
876Objective-C++ source code which should not be preprocessed.
877
878@item @var{file}.hh
879@itemx @var{file}.H
880C++ header file to be turned into a precompiled header.
881
882@item @var{file}.f
883@itemx @var{file}.for
884@itemx @var{file}.FOR
885Fixed form Fortran source code which should not be preprocessed.
886
887@item @var{file}.F
888@itemx @var{file}.fpp
889@itemx @var{file}.FPP
890Fixed form Fortran source code which must be preprocessed (with the traditional
891preprocessor).
892
893@item @var{file}.f90
894@itemx @var{file}.f95
895Free form Fortran source code which should not be preprocessed.
896
897@item @var{file}.F90
898@itemx @var{file}.F95
899Free form Fortran source code which must be preprocessed (with the
900traditional preprocessor).
901
902@c FIXME: Descriptions of Java file types.
903@c @var{file}.java
904@c @var{file}.class
905@c @var{file}.zip
906@c @var{file}.jar
907
908@item @var{file}.ads
909Ada source code file which contains a library unit declaration (a
910declaration of a package, subprogram, or generic, or a generic
911instantiation), or a library unit renaming declaration (a package,
912generic, or subprogram renaming declaration). Such files are also
913called @dfn{specs}.
914
915@itemx @var{file}.adb
916Ada source code file containing a library unit body (a subprogram or
917package body). Such files are also called @dfn{bodies}.
918
919@c GCC also knows about some suffixes for languages not yet included:
920@c Pascal:
921@c @var{file}.p
922@c @var{file}.pas
923@c Ratfor:
924@c @var{file}.r
925
926@item @var{file}.s
927Assembler code.
928
929@item @var{file}.S
930Assembler code which must be preprocessed.
931
932@item @var{other}
933An object file to be fed straight into linking.
934Any file name with no recognized suffix is treated this way.
935@end table
936
937@opindex x
938You can specify the input language explicitly with the @option{-x} option:
939
940@table @gcctabopt
941@item -x @var{language}
942Specify explicitly the @var{language} for the following input files
943(rather than letting the compiler choose a default based on the file
944name suffix). This option applies to all following input files until
945the next @option{-x} option. Possible values for @var{language} are:
946@smallexample
947c c-header c-cpp-output
948c++ c++-header c++-cpp-output
949objective-c objective-c-header objective-c-cpp-output
950objective-c++ objective-c++-header objective-c++-cpp-output
951assembler assembler-with-cpp
952ada
953f95 f95-cpp-input
954java
955treelang
956@end smallexample
957
958@item -x none
959Turn off any specification of a language, so that subsequent files are
960handled according to their file name suffixes (as they are if @option{-x}
961has not been used at all).
962
963@item -pass-exit-codes
964@opindex pass-exit-codes
965Normally the @command{gcc} program will exit with the code of 1 if any
966phase of the compiler returns a non-success return code. If you specify
967@option{-pass-exit-codes}, the @command{gcc} program will instead return with
968numerically highest error produced by any phase that returned an error
969indication. The C, C++, and Fortran frontends return 4, if an internal
970compiler error is encountered.
971@end table
972
973If you only want some of the stages of compilation, you can use
974@option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
975one of the options @option{-c}, @option{-S}, or @option{-E} to say where
976@command{gcc} is to stop. Note that some combinations (for example,
977@samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
978
979@table @gcctabopt
980@item -c
981@opindex c
982Compile or assemble the source files, but do not link. The linking
983stage simply is not done. The ultimate output is in the form of an
984object file for each source file.
985
986By default, the object file name for a source file is made by replacing
987the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
988
989Unrecognized input files, not requiring compilation or assembly, are
990ignored.
991
992@item -S
993@opindex S
994Stop after the stage of compilation proper; do not assemble. The output
995is in the form of an assembler code file for each non-assembler input
996file specified.
997
998By default, the assembler file name for a source file is made by
999replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
1000
1001Input files that don't require compilation are ignored.
1002
1003@item -E
1004@opindex E
1005Stop after the preprocessing stage; do not run the compiler proper. The
1006output is in the form of preprocessed source code, which is sent to the
1007standard output.
1008
1009Input files which don't require preprocessing are ignored.
1010
1011@cindex output file option
1012@item -o @var{file}
1013@opindex o
1014Place output in file @var{file}. This applies regardless to whatever
1015sort of output is being produced, whether it be an executable file,
1016an object file, an assembler file or preprocessed C code.
1017
1018If @option{-o} is not specified, the default is to put an executable
1019file in @file{a.out}, the object file for
1020@file{@var{source}.@var{suffix}} in @file{@var{source}.o}, its
1021assembler file in @file{@var{source}.s}, a precompiled header file in
1022@file{@var{source}.@var{suffix}.gch}, and all preprocessed C source on
1023standard output.
1024
1025@item -v
1026@opindex v
1027Print (on standard error output) the commands executed to run the stages
1028of compilation. Also print the version number of the compiler driver
1029program and of the preprocessor and the compiler proper.
1030
1031@item -###
1032@opindex ###
1033Like @option{-v} except the commands are not executed and all command
1034arguments are quoted. This is useful for shell scripts to capture the
1035driver-generated command lines.
1036
1037@item -pipe
1038@opindex pipe
1039Use pipes rather than temporary files for communication between the
1040various stages of compilation. This fails to work on some systems where
1041the assembler is unable to read from a pipe; but the GNU assembler has
1042no trouble.
1043
1044@item -combine
1045@opindex combine
1046If you are compiling multiple source files, this option tells the driver
1047to pass all the source files to the compiler at once (for those
1048languages for which the compiler can handle this). This will allow
1049intermodule analysis (IMA) to be performed by the compiler. Currently the only
1050language for which this is supported is C@. If you pass source files for
1051multiple languages to the driver, using this option, the driver will invoke
1052the compiler(s) that support IMA once each, passing each compiler all the
1053source files appropriate for it. For those languages that do not support
1054IMA this option will be ignored, and the compiler will be invoked once for
1055each source file in that language. If you use this option in conjunction
1056with @option{-save-temps}, the compiler will generate multiple
1057pre-processed files
1058(one for each source file), but only one (combined) @file{.o} or
1059@file{.s} file.
1060
1061@item --help
1062@opindex help
1063Print (on the standard output) a description of the command line options
1064understood by @command{gcc}. If the @option{-v} option is also specified
1065then @option{--help} will also be passed on to the various processes
1066invoked by @command{gcc}, so that they can display the command line options
1067they accept. If the @option{-Wextra} option is also specified then command
1068line options which have no documentation associated with them will also
1069be displayed.
1070
1071@item --target-help
1072@opindex target-help
1073Print (on the standard output) a description of target specific command
1074line options for each tool.
1075
1076@item --version
1077@opindex version
1078Display the version number and copyrights of the invoked GCC@.
1079
1080@include @value{srcdir}/../libiberty/at-file.texi
1081@end table
1082
1083@node Invoking G++
1084@section Compiling C++ Programs
1085
1086@cindex suffixes for C++ source
1087@cindex C++ source file suffixes
1088C++ source files conventionally use one of the suffixes @samp{.C},
1089@samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or
1090@samp{.cxx}; C++ header files often use @samp{.hh} or @samp{.H}; and
1091preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes
1092files with these names and compiles them as C++ programs even if you
1093call the compiler the same way as for compiling C programs (usually
1094with the name @command{gcc}).
1095
1096@findex g++
1097@findex c++
1098However, the use of @command{gcc} does not add the C++ library.
1099@command{g++} is a program that calls GCC and treats @samp{.c},
1100@samp{.h} and @samp{.i} files as C++ source files instead of C source
1101files unless @option{-x} is used, and automatically specifies linking
1102against the C++ library. This program is also useful when
1103precompiling a C header file with a @samp{.h} extension for use in C++
1104compilations. On many systems, @command{g++} is also installed with
1105the name @command{c++}.
1106
1107@cindex invoking @command{g++}
1108When you compile C++ programs, you may specify many of the same
1109command-line options that you use for compiling programs in any
1110language; or command-line options meaningful for C and related
1111languages; or options that are meaningful only for C++ programs.
1112@xref{C Dialect Options,,Options Controlling C Dialect}, for
1113explanations of options for languages related to C@.
1114@xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
1115explanations of options that are meaningful only for C++ programs.
1116
1117@node C Dialect Options
1118@section Options Controlling C Dialect
1119@cindex dialect options
1120@cindex language dialect options
1121@cindex options, dialect
1122
1123The following options control the dialect of C (or languages derived
1124from C, such as C++, Objective-C and Objective-C++) that the compiler
1125accepts:
1126
1127@table @gcctabopt
1128@cindex ANSI support
1129@cindex ISO support
1130@item -ansi
1131@opindex ansi
1132In C mode, support all ISO C90 programs. In C++ mode,
1133remove GNU extensions that conflict with ISO C++.
1134
1135This turns off certain features of GCC that are incompatible with ISO
1136C90 (when compiling C code), or of standard C++ (when compiling C++ code),
1137such as the @code{asm} and @code{typeof} keywords, and
1138predefined macros such as @code{unix} and @code{vax} that identify the
1139type of system you are using. It also enables the undesirable and
1140rarely used ISO trigraph feature. For the C compiler,
1141it disables recognition of C++ style @samp{//} comments as well as
1142the @code{inline} keyword.
1143
1144The alternate keywords @code{__asm__}, @code{__extension__},
1145@code{__inline__} and @code{__typeof__} continue to work despite
1146@option{-ansi}. You would not want to use them in an ISO C program, of
1147course, but it is useful to put them in header files that might be included
1148in compilations done with @option{-ansi}. Alternate predefined macros
1149such as @code{__unix__} and @code{__vax__} are also available, with or
1150without @option{-ansi}.
1151
1152The @option{-ansi} option does not cause non-ISO programs to be
1153rejected gratuitously. For that, @option{-pedantic} is required in
1154addition to @option{-ansi}. @xref{Warning Options}.
1155
1156The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
1157option is used. Some header files may notice this macro and refrain
1158from declaring certain functions or defining certain macros that the
1159ISO standard doesn't call for; this is to avoid interfering with any
1160programs that might use these names for other things.
1161
1162Functions which would normally be built in but do not have semantics
1163defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
1164functions with @option{-ansi} is used. @xref{Other Builtins,,Other
1165built-in functions provided by GCC}, for details of the functions
1166affected.
1167
1168@item -std=
1169@opindex std
1170Determine the language standard. This option is currently only
1171supported when compiling C or C++. A value for this option must be
1172provided; possible values are
1173
1174@table @samp
1175@item c89
1176@itemx iso9899:1990
1177ISO C90 (same as @option{-ansi}).
1178
1179@item iso9899:199409
1180ISO C90 as modified in amendment 1.
1181
1182@item c99
1183@itemx c9x
1184@itemx iso9899:1999
1185@itemx iso9899:199x
1186ISO C99. Note that this standard is not yet fully supported; see
1187@w{@uref{http://gcc.gnu.org/gcc-4.2/c99status.html}} for more information. The
1188names @samp{c9x} and @samp{iso9899:199x} are deprecated.
1189
1190@item gnu89
1191Default, ISO C90 plus GNU extensions (including some C99 features).
1192
1193@item gnu99
1194@itemx gnu9x
1195ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC,
1196this will become the default. The name @samp{gnu9x} is deprecated.
1197
1198@item c++98
1199The 1998 ISO C++ standard plus amendments.
1200
1201@item gnu++98
1202The same as @option{-std=c++98} plus GNU extensions. This is the
1203default for C++ code.
1204@end table
1205
1206Even when this option is not specified, you can still use some of the
1207features of newer standards in so far as they do not conflict with
1208previous C standards. For example, you may use @code{__restrict__} even
1209when @option{-std=c99} is not specified.
1210
1211The @option{-std} options specifying some version of ISO C have the same
1212effects as @option{-ansi}, except that features that were not in ISO C90
1213but are in the specified version (for example, @samp{//} comments and
1214the @code{inline} keyword in ISO C99) are not disabled.
1215
1216@xref{Standards,,Language Standards Supported by GCC}, for details of
1217these standard versions.
1218
1219@item -fgnu89-inline
1220@opindex fgnu89-inline
1221The option @option{-fgnu89-inline} tells GCC to use the traditional
1222GNU semantics for @code{inline} functions when in C99 mode.
1223@xref{Inline,,An Inline Function is As Fast As a Macro}. Using this
1224option is roughly equivalent to adding the @code{gnu_inline} function
1225attribute to all inline functions (@pxref{Function Attributes}).
1226
1227This option is accepted by GCC versions 4.1.3 and up. In GCC versions
1228prior to 4.3, C99 inline semantics are not supported, and thus this
1229option is effectively assumed to be present regardless of whether or not
1230it is specified; the only effect of specifying it explicitly is to
1231disable warnings about using inline functions in C99 mode. Likewise,
1232the option @option{-fno-gnu89-inline} is not supported in versions of
1233GCC before 4.3. It will be supported only in C99 or gnu99 mode, not in
1234C89 or gnu89 mode.
1235
1236The preprocesor macros @code{__GNUC_GNU_INLINE__} and
1237@code{__GNUC_STDC_INLINE__} may be used to check which semantics are
1238in effect for @code{inline} functions. @xref{Common Predefined
1239Macros,,,cpp,The C Preprocessor}.
1240
1241@item -aux-info @var{filename}
1242@opindex aux-info
1243Output to the given filename prototyped declarations for all functions
1244declared and/or defined in a translation unit, including those in header
1245files. This option is silently ignored in any language other than C@.
1246
1247Besides declarations, the file indicates, in comments, the origin of
1248each declaration (source file and line), whether the declaration was
1249implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
1250@samp{O} for old, respectively, in the first character after the line
1251number and the colon), and whether it came from a declaration or a
1252definition (@samp{C} or @samp{F}, respectively, in the following
1253character). In the case of function definitions, a K&R-style list of
1254arguments followed by their declarations is also provided, inside
1255comments, after the declaration.
1256
1257@item -fno-asm
1258@opindex fno-asm
1259Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1260keyword, so that code can use these words as identifiers. You can use
1261the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
1262instead. @option{-ansi} implies @option{-fno-asm}.
1263
1264In C++, this switch only affects the @code{typeof} keyword, since
1265@code{asm} and @code{inline} are standard keywords. You may want to
1266use the @option{-fno-gnu-keywords} flag instead, which has the same
1267effect. In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
1268switch only affects the @code{asm} and @code{typeof} keywords, since
1269@code{inline} is a standard keyword in ISO C99.
1270
1271@item -fno-builtin
1272@itemx -fno-builtin-@var{function}
1273@opindex fno-builtin
1274@cindex built-in functions
1275Don't recognize built-in functions that do not begin with
1276@samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in
1277functions provided by GCC}, for details of the functions affected,
1278including those which are not built-in functions when @option{-ansi} or
1279@option{-std} options for strict ISO C conformance are used because they
1280do not have an ISO standard meaning.
1281
1282GCC normally generates special code to handle certain built-in functions
1283more efficiently; for instance, calls to @code{alloca} may become single
1284instructions that adjust the stack directly, and calls to @code{memcpy}
1285may become inline copy loops. The resulting code is often both smaller
1286and faster, but since the function calls no longer appear as such, you
1287cannot set a breakpoint on those calls, nor can you change the behavior
1288of the functions by linking with a different library. In addition,
1289when a function is recognized as a built-in function, GCC may use
1290information about that function to warn about problems with calls to
1291that function, or to generate more efficient code, even if the
1292resulting code still contains calls to that function. For example,
1293warnings are given with @option{-Wformat} for bad calls to
1294@code{printf}, when @code{printf} is built in, and @code{strlen} is
1295known not to modify global memory.
1296
1297With the @option{-fno-builtin-@var{function}} option
1298only the built-in function @var{function} is
1299disabled. @var{function} must not begin with @samp{__builtin_}. If a
1300function is named this is not built-in in this version of GCC, this
1301option is ignored. There is no corresponding
1302@option{-fbuiltin-@var{function}} option; if you wish to enable
1303built-in functions selectively when using @option{-fno-builtin} or
1304@option{-ffreestanding}, you may define macros such as:
1305
1306@smallexample
1307#define abs(n) __builtin_abs ((n))
1308#define strcpy(d, s) __builtin_strcpy ((d), (s))
1309@end smallexample
1310
1311@item -fhosted
1312@opindex fhosted
1313@cindex hosted environment
1314
1315Assert that compilation takes place in a hosted environment. This implies
1316@option{-fbuiltin}. A hosted environment is one in which the
1317entire standard library is available, and in which @code{main} has a return
1318type of @code{int}. Examples are nearly everything except a kernel.
1319This is equivalent to @option{-fno-freestanding}.
1320
1321@item -ffreestanding
1322@opindex ffreestanding
1323@cindex hosted environment
1324
1325Assert that compilation takes place in a freestanding environment. This
1326implies @option{-fno-builtin}. A freestanding environment
1327is one in which the standard library may not exist, and program startup may
1328not necessarily be at @code{main}. The most obvious example is an OS kernel.
1329This is equivalent to @option{-fno-hosted}.
1330
1331@xref{Standards,,Language Standards Supported by GCC}, for details of
1332freestanding and hosted environments.
1333
1334@item -fopenmp
1335@opindex fopenmp
1336@cindex openmp parallel
1337Enable handling of OpenMP directives @code{#pragma omp} in C/C++ and
1338@code{!$omp} in Fortran. When @option{-fopenmp} is specified, the
1339compiler generates parallel code according to the OpenMP Application
1340Program Interface v2.5 @w{@uref{http://www.openmp.org/}}.
1341
1342@item -fms-extensions
1343@opindex fms-extensions
1344Accept some non-standard constructs used in Microsoft header files.
1345
1346Some cases of unnamed fields in structures and unions are only
1347accepted with this option. @xref{Unnamed Fields,,Unnamed struct/union
1348fields within structs/unions}, for details.
1349
1350@item -trigraphs
1351@opindex trigraphs
1352Support ISO C trigraphs. The @option{-ansi} option (and @option{-std}
1353options for strict ISO C conformance) implies @option{-trigraphs}.
1354
1355@item -no-integrated-cpp
1356@opindex no-integrated-cpp
1357Performs a compilation in two passes: preprocessing and compiling. This
1358option allows a user supplied "cc1", "cc1plus", or "cc1obj" via the
1359@option{-B} option. The user supplied compilation step can then add in
1360an additional preprocessing step after normal preprocessing but before
1361compiling. The default is to use the integrated cpp (internal cpp)
1362
1363The semantics of this option will change if "cc1", "cc1plus", and
1364"cc1obj" are merged.
1365
1366@cindex traditional C language
1367@cindex C language, traditional
1368@item -traditional
1369@itemx -traditional-cpp
1370@opindex traditional-cpp
1371@opindex traditional
1372Formerly, these options caused GCC to attempt to emulate a pre-standard
1373C compiler. They are now only supported with the @option{-E} switch.
1374The preprocessor continues to support a pre-standard mode. See the GNU
1375CPP manual for details.
1376
1377@item -fcond-mismatch
1378@opindex fcond-mismatch
1379Allow conditional expressions with mismatched types in the second and
1380third arguments. The value of such an expression is void. This option
1381is not supported for C++.
1382
1383@item -funsigned-char
1384@opindex funsigned-char
1385Let the type @code{char} be unsigned, like @code{unsigned char}.
1386
1387Each kind of machine has a default for what @code{char} should
1388be. It is either like @code{unsigned char} by default or like
1389@code{signed char} by default.
1390
1391Ideally, a portable program should always use @code{signed char} or
1392@code{unsigned char} when it depends on the signedness of an object.
1393But many programs have been written to use plain @code{char} and
1394expect it to be signed, or expect it to be unsigned, depending on the
1395machines they were written for. This option, and its inverse, let you
1396make such a program work with the opposite default.
1397
1398The type @code{char} is always a distinct type from each of
1399@code{signed char} or @code{unsigned char}, even though its behavior
1400is always just like one of those two.
1401
1402@item -fsigned-char
1403@opindex fsigned-char
1404Let the type @code{char} be signed, like @code{signed char}.
1405
1406Note that this is equivalent to @option{-fno-unsigned-char}, which is
1407the negative form of @option{-funsigned-char}. Likewise, the option
1408@option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
1409
1410@item -fsigned-bitfields
1411@itemx -funsigned-bitfields
1412@itemx -fno-signed-bitfields
1413@itemx -fno-unsigned-bitfields
1414@opindex fsigned-bitfields
1415@opindex funsigned-bitfields
1416@opindex fno-signed-bitfields
1417@opindex fno-unsigned-bitfields
1418These options control whether a bit-field is signed or unsigned, when the
1419declaration does not use either @code{signed} or @code{unsigned}. By
1420default, such a bit-field is signed, because this is consistent: the
1421basic integer types such as @code{int} are signed types.
1422@end table
1423
1424@node C++ Dialect Options
1425@section Options Controlling C++ Dialect
1426
1427@cindex compiler options, C++
1428@cindex C++ options, command line
1429@cindex options, C++
1430This section describes the command-line options that are only meaningful
1431for C++ programs; but you can also use most of the GNU compiler options
1432regardless of what language your program is in. For example, you
1433might compile a file @code{firstClass.C} like this:
1434
1435@smallexample
1436g++ -g -frepo -O -c firstClass.C
1437@end smallexample
1438
1439@noindent
1440In this example, only @option{-frepo} is an option meant
1441only for C++ programs; you can use the other options with any
1442language supported by GCC@.
1443
1444Here is a list of options that are @emph{only} for compiling C++ programs:
1445
1446@table @gcctabopt
1447
1448@item -fabi-version=@var{n}
1449@opindex fabi-version
1450Use version @var{n} of the C++ ABI@. Version 2 is the version of the
1451C++ ABI that first appeared in G++ 3.4. Version 1 is the version of
1452the C++ ABI that first appeared in G++ 3.2. Version 0 will always be
1453the version that conforms most closely to the C++ ABI specification.
1454Therefore, the ABI obtained using version 0 will change as ABI bugs
1455are fixed.
1456
1457The default is version 2.
1458
1459@item -fno-access-control
1460@opindex fno-access-control
1461Turn off all access checking. This switch is mainly useful for working
1462around bugs in the access control code.
1463
1464@item -fcheck-new
1465@opindex fcheck-new
1466Check that the pointer returned by @code{operator new} is non-null
1467before attempting to modify the storage allocated. This check is
1468normally unnecessary because the C++ standard specifies that
1469@code{operator new} will only return @code{0} if it is declared
1470@samp{throw()}, in which case the compiler will always check the
1471return value even without this option. In all other cases, when
1472@code{operator new} has a non-empty exception specification, memory
1473exhaustion is signalled by throwing @code{std::bad_alloc}. See also
1474@samp{new (nothrow)}.
1475
1476@item -fconserve-space
1477@opindex fconserve-space
1478Put uninitialized or runtime-initialized global variables into the
1479common segment, as C does. This saves space in the executable at the
1480cost of not diagnosing duplicate definitions. If you compile with this
1481flag and your program mysteriously crashes after @code{main()} has
1482completed, you may have an object that is being destroyed twice because
1483two definitions were merged.
1484
1485This option is no longer useful on most targets, now that support has
1486been added for putting variables into BSS without making them common.
1487
1488@item -ffriend-injection
1489@opindex ffriend-injection
1490Inject friend functions into the enclosing namespace, so that they are
1491visible outside the scope of the class in which they are declared.
1492Friend functions were documented to work this way in the old Annotated
1493C++ Reference Manual, and versions of G++ before 4.1 always worked
1494that way. However, in ISO C++ a friend function which is not declared
1495in an enclosing scope can only be found using argument dependent
1496lookup. This option causes friends to be injected as they were in
1497earlier releases.
1498
1499This option is for compatibility, and may be removed in a future
1500release of G++.
1501
1502@item -fno-elide-constructors
1503@opindex fno-elide-constructors
1504The C++ standard allows an implementation to omit creating a temporary
1505which is only used to initialize another object of the same type.
1506Specifying this option disables that optimization, and forces G++ to
1507call the copy constructor in all cases.
1508
1509@item -fno-enforce-eh-specs
1510@opindex fno-enforce-eh-specs
1511Don't generate code to check for violation of exception specifications
1512at runtime. This option violates the C++ standard, but may be useful
1513for reducing code size in production builds, much like defining
1514@samp{NDEBUG}. This does not give user code permission to throw
1515exceptions in violation of the exception specifications; the compiler
1516will still optimize based on the specifications, so throwing an
1517unexpected exception will result in undefined behavior.
1518
1519@item -ffor-scope
1520@itemx -fno-for-scope
1521@opindex ffor-scope
1522@opindex fno-for-scope
1523If @option{-ffor-scope} is specified, the scope of variables declared in
1524a @i{for-init-statement} is limited to the @samp{for} loop itself,
1525as specified by the C++ standard.
1526If @option{-fno-for-scope} is specified, the scope of variables declared in
1527a @i{for-init-statement} extends to the end of the enclosing scope,
1528as was the case in old versions of G++, and other (traditional)
1529implementations of C++.
1530
1531The default if neither flag is given to follow the standard,
1532but to allow and give a warning for old-style code that would
1533otherwise be invalid, or have different behavior.
1534
1535@item -fno-gnu-keywords
1536@opindex fno-gnu-keywords
1537Do not recognize @code{typeof} as a keyword, so that code can use this
1538word as an identifier. You can use the keyword @code{__typeof__} instead.
1539@option{-ansi} implies @option{-fno-gnu-keywords}.
1540
1541@item -fno-implicit-templates
1542@opindex fno-implicit-templates
1543Never emit code for non-inline templates which are instantiated
1544implicitly (i.e.@: by use); only emit code for explicit instantiations.
1545@xref{Template Instantiation}, for more information.
1546
1547@item -fno-implicit-inline-templates
1548@opindex fno-implicit-inline-templates
1549Don't emit code for implicit instantiations of inline templates, either.
1550The default is to handle inlines differently so that compiles with and
1551without optimization will need the same set of explicit instantiations.
1552
1553@item -fno-implement-inlines
1554@opindex fno-implement-inlines
1555To save space, do not emit out-of-line copies of inline functions
1556controlled by @samp{#pragma implementation}. This will cause linker
1557errors if these functions are not inlined everywhere they are called.
1558
1559@item -fms-extensions
1560@opindex fms-extensions
1561Disable pedantic warnings about constructs used in MFC, such as implicit
1562int and getting a pointer to member function via non-standard syntax.
1563
1564@item -fno-nonansi-builtins
1565@opindex fno-nonansi-builtins
1566Disable built-in declarations of functions that are not mandated by
1567ANSI/ISO C@. These include @code{ffs}, @code{alloca}, @code{_exit},
1568@code{index}, @code{bzero}, @code{conjf}, and other related functions.
1569
1570@item -fno-operator-names
1571@opindex fno-operator-names
1572Do not treat the operator name keywords @code{and}, @code{bitand},
1573@code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1574synonyms as keywords.
1575
1576@item -fno-optional-diags
1577@opindex fno-optional-diags
1578Disable diagnostics that the standard says a compiler does not need to
1579issue. Currently, the only such diagnostic issued by G++ is the one for
1580a name having multiple meanings within a class.
1581
1582@item -fpermissive
1583@opindex fpermissive
1584Downgrade some diagnostics about nonconformant code from errors to
1585warnings. Thus, using @option{-fpermissive} will allow some
1586nonconforming code to compile.
1587
1588@item -frepo
1589@opindex frepo
1590Enable automatic template instantiation at link time. This option also
1591implies @option{-fno-implicit-templates}. @xref{Template
1592Instantiation}, for more information.
1593
1594@item -fno-rtti
1595@opindex fno-rtti
1596Disable generation of information about every class with virtual
1597functions for use by the C++ runtime type identification features
1598(@samp{dynamic_cast} and @samp{typeid}). If you don't use those parts
1599of the language, you can save some space by using this flag. Note that
1600exception handling uses the same information, but it will generate it as
1601needed. The @samp{dynamic_cast} operator can still be used for casts that
1602do not require runtime type information, i.e. casts to @code{void *} or to
1603unambiguous base classes.
1604
1605@item -fstats
1606@opindex fstats
1607Emit statistics about front-end processing at the end of the compilation.
1608This information is generally only useful to the G++ development team.
1609
1610@item -ftemplate-depth-@var{n}
1611@opindex ftemplate-depth
1612Set the maximum instantiation depth for template classes to @var{n}.
1613A limit on the template instantiation depth is needed to detect
1614endless recursions during template class instantiation. ANSI/ISO C++
1615conforming programs must not rely on a maximum depth greater than 17.
1616
1617@item -fno-threadsafe-statics
1618@opindex fno-threadsafe-statics
1619Do not emit the extra code to use the routines specified in the C++
1620ABI for thread-safe initialization of local statics. You can use this
1621option to reduce code size slightly in code that doesn't need to be
1622thread-safe.
1623
1624@item -fuse-cxa-atexit
1625@opindex fuse-cxa-atexit
1626Register destructors for objects with static storage duration with the
1627@code{__cxa_atexit} function rather than the @code{atexit} function.
1628This option is required for fully standards-compliant handling of static
1629destructors, but will only work if your C library supports
1630@code{__cxa_atexit}.
1631
1632@item -fno-use-cxa-get-exception-ptr
1633@opindex fno-use-cxa-get-exception-ptr
1634Don't use the @code{__cxa_get_exception_ptr} runtime routine. This
1635will cause @code{std::uncaught_exception} to be incorrect, but is necessary
1636if the runtime routine is not available.
1637
1638@item -fvisibility-inlines-hidden
1639@opindex fvisibility-inlines-hidden
1640This switch declares that the user does not attempt to compare
1641pointers to inline methods where the addresses of the two functions
1642were taken in different shared objects.
1643
1644The effect of this is that GCC may, effectively, mark inline methods with
1645@code{__attribute__ ((visibility ("hidden")))} so that they do not
1646appear in the export table of a DSO and do not require a PLT indirection
1647when used within the DSO@. Enabling this option can have a dramatic effect
1648on load and link times of a DSO as it massively reduces the size of the
1649dynamic export table when the library makes heavy use of templates.
1650
1651The behaviour of this switch is not quite the same as marking the
1652methods as hidden directly, because it does not affect static variables
1653local to the function or cause the compiler to deduce that
1654the function is defined in only one shared object.
1655
1656You may mark a method as having a visibility explicitly to negate the
1657effect of the switch for that method. For example, if you do want to
1658compare pointers to a particular inline method, you might mark it as
1659having default visibility. Marking the enclosing class with explicit
1660visibility will have no effect.
1661
1662Explicitly instantiated inline methods are unaffected by this option
1663as their linkage might otherwise cross a shared library boundary.
1664@xref{Template Instantiation}.
1665
1666@item -fno-weak
1667@opindex fno-weak
1668Do not use weak symbol support, even if it is provided by the linker.
1669By default, G++ will use weak symbols if they are available. This
1670option exists only for testing, and should not be used by end-users;
1671it will result in inferior code and has no benefits. This option may
1672be removed in a future release of G++.
1673
1674@item -nostdinc++
1675@opindex nostdinc++
1676Do not search for header files in the standard directories specific to
1677C++, but do still search the other standard directories. (This option
1678is used when building the C++ library.)
1679@end table
1680
1681In addition, these optimization, warning, and code generation options
1682have meanings only for C++ programs:
1683
1684@table @gcctabopt
1685@item -fno-default-inline
1686@opindex fno-default-inline
1687Do not assume @samp{inline} for functions defined inside a class scope.
1688@xref{Optimize Options,,Options That Control Optimization}. Note that these
1689functions will have linkage like inline functions; they just won't be
1690inlined by default.
1691
1692@item -Wabi @r{(C++ only)}
1693@opindex Wabi
1694Warn when G++ generates code that is probably not compatible with the
1695vendor-neutral C++ ABI@. Although an effort has been made to warn about
1696all such cases, there are probably some cases that are not warned about,
1697even though G++ is generating incompatible code. There may also be
1698cases where warnings are emitted even though the code that is generated
1699will be compatible.
1700
1701You should rewrite your code to avoid these warnings if you are
1702concerned about the fact that code generated by G++ may not be binary
1703compatible with code generated by other compilers.
1704
1705The known incompatibilities at this point include:
1706
1707@itemize @bullet
1708
1709@item
1710Incorrect handling of tail-padding for bit-fields. G++ may attempt to
1711pack data into the same byte as a base class. For example:
1712
1713@smallexample
1714struct A @{ virtual void f(); int f1 : 1; @};
1715struct B : public A @{ int f2 : 1; @};
1716@end smallexample
1717
1718@noindent
1719In this case, G++ will place @code{B::f2} into the same byte
1720as@code{A::f1}; other compilers will not. You can avoid this problem
1721by explicitly padding @code{A} so that its size is a multiple of the
1722byte size on your platform; that will cause G++ and other compilers to
1723layout @code{B} identically.
1724
1725@item
1726Incorrect handling of tail-padding for virtual bases. G++ does not use
1727tail padding when laying out virtual bases. For example:
1728
1729@smallexample
1730struct A @{ virtual void f(); char c1; @};
1731struct B @{ B(); char c2; @};
1732struct C : public A, public virtual B @{@};
1733@end smallexample
1734
1735@noindent
1736In this case, G++ will not place @code{B} into the tail-padding for
1737@code{A}; other compilers will. You can avoid this problem by
1738explicitly padding @code{A} so that its size is a multiple of its
1739alignment (ignoring virtual base classes); that will cause G++ and other
1740compilers to layout @code{C} identically.
1741
1742@item
1743Incorrect handling of bit-fields with declared widths greater than that
1744of their underlying types, when the bit-fields appear in a union. For
1745example:
1746
1747@smallexample
1748union U @{ int i : 4096; @};
1749@end smallexample
1750
1751@noindent
1752Assuming that an @code{int} does not have 4096 bits, G++ will make the
1753union too small by the number of bits in an @code{int}.
1754
1755@item
1756Empty classes can be placed at incorrect offsets. For example:
1757
1758@smallexample
1759struct A @{@};
1760
1761struct B @{
1762 A a;
1763 virtual void f ();
1764@};
1765
1766struct C : public B, public A @{@};
1767@end smallexample
1768
1769@noindent
1770G++ will place the @code{A} base class of @code{C} at a nonzero offset;
1771it should be placed at offset zero. G++ mistakenly believes that the
1772@code{A} data member of @code{B} is already at offset zero.
1773
1774@item
1775Names of template functions whose types involve @code{typename} or
1776template template parameters can be mangled incorrectly.
1777
1778@smallexample
1779template <typename Q>
1780void f(typename Q::X) @{@}
1781
1782template <template <typename> class Q>
1783void f(typename Q<int>::X) @{@}
1784@end smallexample
1785
1786@noindent
1787Instantiations of these templates may be mangled incorrectly.
1788
1789@end itemize
1790
1791@item -Wctor-dtor-privacy @r{(C++ only)}
1792@opindex Wctor-dtor-privacy
1793Warn when a class seems unusable because all the constructors or
1794destructors in that class are private, and it has neither friends nor
1795public static member functions.
1796
1797@item -Wnon-virtual-dtor @r{(C++ only)}
1798@opindex Wnon-virtual-dtor
1799Warn when a class appears to be polymorphic, thereby requiring a virtual
1800destructor, yet it declares a non-virtual one. This warning is also
1801enabled if -Weffc++ is specified.
1802
1803@item -Wreorder @r{(C++ only)}
1804@opindex Wreorder
1805@cindex reordering, warning
1806@cindex warning for reordering of member initializers
1807Warn when the order of member initializers given in the code does not
1808match the order in which they must be executed. For instance:
1809
1810@smallexample
1811struct A @{
1812 int i;
1813 int j;
1814 A(): j (0), i (1) @{ @}
1815@};
1816@end smallexample
1817
1818The compiler will rearrange the member initializers for @samp{i}
1819and @samp{j} to match the declaration order of the members, emitting
1820a warning to that effect. This warning is enabled by @option{-Wall}.
1821@end table
1822
1823The following @option{-W@dots{}} options are not affected by @option{-Wall}.
1824
1825@table @gcctabopt
1826@item -Weffc++ @r{(C++ only)}
1827@opindex Weffc++
1828Warn about violations of the following style guidelines from Scott Meyers'
1829@cite{Effective C++} book:
1830
1831@itemize @bullet
1832@item
1833Item 11: Define a copy constructor and an assignment operator for classes
1834with dynamically allocated memory.
1835
1836@item
1837Item 12: Prefer initialization to assignment in constructors.
1838
1839@item
1840Item 14: Make destructors virtual in base classes.
1841
1842@item
1843Item 15: Have @code{operator=} return a reference to @code{*this}.
1844
1845@item
1846Item 23: Don't try to return a reference when you must return an object.
1847
1848@end itemize
1849
1850Also warn about violations of the following style guidelines from
1851Scott Meyers' @cite{More Effective C++} book:
1852
1853@itemize @bullet
1854@item
1855Item 6: Distinguish between prefix and postfix forms of increment and
1856decrement operators.
1857
1858@item
1859Item 7: Never overload @code{&&}, @code{||}, or @code{,}.
1860
1861@end itemize
1862
1863When selecting this option, be aware that the standard library
1864headers do not obey all of these guidelines; use @samp{grep -v}
1865to filter out those warnings.
1866
1867@item -Wno-deprecated @r{(C++ only)}
1868@opindex Wno-deprecated
1869Do not warn about usage of deprecated features. @xref{Deprecated Features}.
1870
1871@item -Wstrict-null-sentinel @r{(C++ only)}
1872@opindex Wstrict-null-sentinel
1873Warn also about the use of an uncasted @code{NULL} as sentinel. When
1874compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
1875to @code{__null}. Although it is a null pointer constant not a null pointer,
1876it is guaranteed to of the same size as a pointer. But this use is
1877not portable across different compilers.
1878
1879@item -Wno-non-template-friend @r{(C++ only)}
1880@opindex Wno-non-template-friend
1881Disable warnings when non-templatized friend functions are declared
1882within a template. Since the advent of explicit template specification
1883support in G++, if the name of the friend is an unqualified-id (i.e.,
1884@samp{friend foo(int)}), the C++ language specification demands that the
1885friend declare or define an ordinary, nontemplate function. (Section
188614.5.3). Before G++ implemented explicit specification, unqualified-ids
1887could be interpreted as a particular specialization of a templatized
1888function. Because this non-conforming behavior is no longer the default
1889behavior for G++, @option{-Wnon-template-friend} allows the compiler to
1890check existing code for potential trouble spots and is on by default.
1891This new compiler behavior can be turned off with
1892@option{-Wno-non-template-friend} which keeps the conformant compiler code
1893but disables the helpful warning.
1894
1895@item -Wold-style-cast @r{(C++ only)}
1896@opindex Wold-style-cast
1897Warn if an old-style (C-style) cast to a non-void type is used within
1898a C++ program. The new-style casts (@samp{dynamic_cast},
1899@samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are
1900less vulnerable to unintended effects and much easier to search for.
1901
1902@item -Woverloaded-virtual @r{(C++ only)}
1903@opindex Woverloaded-virtual
1904@cindex overloaded virtual fn, warning
1905@cindex warning for overloaded virtual fn
1906Warn when a function declaration hides virtual functions from a
1907base class. For example, in:
1908
1909@smallexample
1910struct A @{
1911 virtual void f();
1912@};
1913
1914struct B: public A @{
1915 void f(int);
1916@};
1917@end smallexample
1918
1919the @code{A} class version of @code{f} is hidden in @code{B}, and code
1920like:
1921
1922@smallexample
1923B* b;
1924b->f();
1925@end smallexample
1926
1927will fail to compile.
1928
1929@item -Wno-pmf-conversions @r{(C++ only)}
1930@opindex Wno-pmf-conversions
1931Disable the diagnostic for converting a bound pointer to member function
1932to a plain pointer.
1933
1934@item -Wsign-promo @r{(C++ only)}
1935@opindex Wsign-promo
1936Warn when overload resolution chooses a promotion from unsigned or
1937enumerated type to a signed type, over a conversion to an unsigned type of
1938the same size. Previous versions of G++ would try to preserve
1939unsignedness, but the standard mandates the current behavior.
1940
1941@smallexample
1942struct A @{
1943 operator int ();
1944 A& operator = (int);
1945@};
1946
1947main ()
1948@{
1949 A a,b;
1950 a = b;
1951@}
1952@end smallexample
1953
1954In this example, G++ will synthesize a default @samp{A& operator =
1955(const A&);}, while cfront will use the user-defined @samp{operator =}.
1956@end table
1957
1958@node Objective-C and Objective-C++ Dialect Options
1959@section Options Controlling Objective-C and Objective-C++ Dialects
1960
1961@cindex compiler options, Objective-C and Objective-C++
1962@cindex Objective-C and Objective-C++ options, command line
1963@cindex options, Objective-C and Objective-C++
1964(NOTE: This manual does not describe the Objective-C and Objective-C++
1965languages themselves. See @xref{Standards,,Language Standards
1966Supported by GCC}, for references.)
1967
1968This section describes the command-line options that are only meaningful
1969for Objective-C and Objective-C++ programs, but you can also use most of
1970the language-independent GNU compiler options.
1971For example, you might compile a file @code{some_class.m} like this:
1972
1973@smallexample
1974gcc -g -fgnu-runtime -O -c some_class.m
1975@end smallexample
1976
1977@noindent
1978In this example, @option{-fgnu-runtime} is an option meant only for
1979Objective-C and Objective-C++ programs; you can use the other options with
1980any language supported by GCC@.
1981
1982Note that since Objective-C is an extension of the C language, Objective-C
1983compilations may also use options specific to the C front-end (e.g.,
1984@option{-Wtraditional}). Similarly, Objective-C++ compilations may use
1985C++-specific options (e.g., @option{-Wabi}).
1986
1987Here is a list of options that are @emph{only} for compiling Objective-C
1988and Objective-C++ programs:
1989
1990@table @gcctabopt
1991@item -fconstant-string-class=@var{class-name}
1992@opindex fconstant-string-class
1993Use @var{class-name} as the name of the class to instantiate for each
1994literal string specified with the syntax @code{@@"@dots{}"}. The default
1995class name is @code{NXConstantString} if the GNU runtime is being used, and
1996@code{NSConstantString} if the NeXT runtime is being used (see below). The
1997@option{-fconstant-cfstrings} option, if also present, will override the
1998@option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} literals
1999to be laid out as constant CoreFoundation strings.
2000
2001@item -fgnu-runtime
2002@opindex fgnu-runtime
2003Generate object code compatible with the standard GNU Objective-C
2004runtime. This is the default for most types of systems.
2005
2006@item -fnext-runtime
2007@opindex fnext-runtime
2008Generate output compatible with the NeXT runtime. This is the default
2009for NeXT-based systems, including Darwin and Mac OS X@. The macro
2010@code{__NEXT_RUNTIME__} is predefined if (and only if) this option is
2011used.
2012
2013@item -fno-nil-receivers
2014@opindex fno-nil-receivers
2015Assume that all Objective-C message dispatches (e.g.,
2016@code{[receiver message:arg]}) in this translation unit ensure that the receiver
2017is not @code{nil}. This allows for more efficient entry points in the runtime
2018to be used. Currently, this option is only available in conjunction with
2019the NeXT runtime on Mac OS X 10.3 and later.
2020
2021@item -fobjc-call-cxx-cdtors
2022@opindex fobjc-call-cxx-cdtors
2023For each Objective-C class, check if any of its instance variables is a
2024C++ object with a non-trivial default constructor. If so, synthesize a
2025special @code{- (id) .cxx_construct} instance method that will run
2026non-trivial default constructors on any such instance variables, in order,
2027and then return @code{self}. Similarly, check if any instance variable
2028is a C++ object with a non-trivial destructor, and if so, synthesize a
2029special @code{- (void) .cxx_destruct} method that will run
2030all such default destructors, in reverse order.
2031
2032The @code{- (id) .cxx_construct} and/or @code{- (void) .cxx_destruct} methods
2033thusly generated will only operate on instance variables declared in the
2034current Objective-C class, and not those inherited from superclasses. It
2035is the responsibility of the Objective-C runtime to invoke all such methods
2036in an object's inheritance hierarchy. The @code{- (id) .cxx_construct} methods
2037will be invoked by the runtime immediately after a new object
2038instance is allocated; the @code{- (void) .cxx_destruct} methods will
2039be invoked immediately before the runtime deallocates an object instance.
2040
2041As of this writing, only the NeXT runtime on Mac OS X 10.4 and later has
2042support for invoking the @code{- (id) .cxx_construct} and
2043@code{- (void) .cxx_destruct} methods.
2044
2045@item -fobjc-direct-dispatch
2046@opindex fobjc-direct-dispatch
2047Allow fast jumps to the message dispatcher. On Darwin this is
2048accomplished via the comm page.
2049
2050@item -fobjc-exceptions
2051@opindex fobjc-exceptions
2052Enable syntactic support for structured exception handling in Objective-C,
2053similar to what is offered by C++ and Java. This option is
2054unavailable in conjunction with the NeXT runtime on Mac OS X 10.2 and
2055earlier.
2056
2057@smallexample
2058 @@try @{
2059 @dots{}
2060 @@throw expr;
2061 @dots{}
2062 @}
2063 @@catch (AnObjCClass *exc) @{
2064 @dots{}
2065 @@throw expr;
2066 @dots{}
2067 @@throw;
2068 @dots{}
2069 @}
2070 @@catch (AnotherClass *exc) @{
2071 @dots{}
2072 @}
2073 @@catch (id allOthers) @{
2074 @dots{}
2075 @}
2076 @@finally @{
2077 @dots{}
2078 @@throw expr;
2079 @dots{}
2080 @}
2081@end smallexample
2082
2083The @code{@@throw} statement may appear anywhere in an Objective-C or
2084Objective-C++ program; when used inside of a @code{@@catch} block, the
2085@code{@@throw} may appear without an argument (as shown above), in which case
2086the object caught by the @code{@@catch} will be rethrown.
2087
2088Note that only (pointers to) Objective-C objects may be thrown and
2089caught using this scheme. When an object is thrown, it will be caught
2090by the nearest @code{@@catch} clause capable of handling objects of that type,
2091analogously to how @code{catch} blocks work in C++ and Java. A
2092@code{@@catch(id @dots{})} clause (as shown above) may also be provided to catch
2093any and all Objective-C exceptions not caught by previous @code{@@catch}
2094clauses (if any).
2095
2096The @code{@@finally} clause, if present, will be executed upon exit from the
2097immediately preceding @code{@@try @dots{} @@catch} section. This will happen
2098regardless of whether any exceptions are thrown, caught or rethrown
2099inside the @code{@@try @dots{} @@catch} section, analogously to the behavior
2100of the @code{finally} clause in Java.
2101
2102There are several caveats to using the new exception mechanism:
2103
2104@itemize @bullet
2105@item
2106Although currently designed to be binary compatible with @code{NS_HANDLER}-style
2107idioms provided by the @code{NSException} class, the new
2108exceptions can only be used on Mac OS X 10.3 (Panther) and later
2109systems, due to additional functionality needed in the (NeXT) Objective-C
2110runtime.
2111
2112@item
2113As mentioned above, the new exceptions do not support handling
2114types other than Objective-C objects. Furthermore, when used from
2115Objective-C++, the Objective-C exception model does not interoperate with C++
2116exceptions at this time. This means you cannot @code{@@throw} an exception
2117from Objective-C and @code{catch} it in C++, or vice versa
2118(i.e., @code{throw @dots{} @@catch}).
2119@end itemize
2120
2121The @option{-fobjc-exceptions} switch also enables the use of synchronization
2122blocks for thread-safe execution:
2123
2124@smallexample
2125 @@synchronized (ObjCClass *guard) @{
2126 @dots{}
2127 @}
2128@end smallexample
2129
2130Upon entering the @code{@@synchronized} block, a thread of execution shall
2131first check whether a lock has been placed on the corresponding @code{guard}
2132object by another thread. If it has, the current thread shall wait until
2133the other thread relinquishes its lock. Once @code{guard} becomes available,
2134the current thread will place its own lock on it, execute the code contained in
2135the @code{@@synchronized} block, and finally relinquish the lock (thereby
2136making @code{guard} available to other threads).
2137
2138Unlike Java, Objective-C does not allow for entire methods to be marked
2139@code{@@synchronized}. Note that throwing exceptions out of
2140@code{@@synchronized} blocks is allowed, and will cause the guarding object
2141to be unlocked properly.
2142
2143@item -fobjc-gc
2144@opindex fobjc-gc
2145Enable garbage collection (GC) in Objective-C and Objective-C++ programs.
2146
2147@item -freplace-objc-classes
2148@opindex freplace-objc-classes
2149Emit a special marker instructing @command{ld(1)} not to statically link in
2150the resulting object file, and allow @command{dyld(1)} to load it in at
2151run time instead. This is used in conjunction with the Fix-and-Continue
2152debugging mode, where the object file in question may be recompiled and
2153dynamically reloaded in the course of program execution, without the need
2154to restart the program itself. Currently, Fix-and-Continue functionality
2155is only available in conjunction with the NeXT runtime on Mac OS X 10.3
2156and later.
2157
2158@item -fzero-link
2159@opindex fzero-link
2160When compiling for the NeXT runtime, the compiler ordinarily replaces calls
2161to @code{objc_getClass("@dots{}")} (when the name of the class is known at
2162compile time) with static class references that get initialized at load time,
2163which improves run-time performance. Specifying the @option{-fzero-link} flag
2164suppresses this behavior and causes calls to @code{objc_getClass("@dots{}")}
2165to be retained. This is useful in Zero-Link debugging mode, since it allows
2166for individual class implementations to be modified during program execution.
2167
2168@item -gen-decls
2169@opindex gen-decls
2170Dump interface declarations for all classes seen in the source file to a
2171file named @file{@var{sourcename}.decl}.
2172
2173@item -Wassign-intercept
2174@opindex Wassign-intercept
2175Warn whenever an Objective-C assignment is being intercepted by the
2176garbage collector.
2177
2178@item -Wno-protocol
2179@opindex Wno-protocol
2180If a class is declared to implement a protocol, a warning is issued for
2181every method in the protocol that is not implemented by the class. The
2182default behavior is to issue a warning for every method not explicitly
2183implemented in the class, even if a method implementation is inherited
2184from the superclass. If you use the @option{-Wno-protocol} option, then
2185methods inherited from the superclass are considered to be implemented,
2186and no warning is issued for them.
2187
2188@item -Wselector
2189@opindex Wselector
2190Warn if multiple methods of different types for the same selector are
2191found during compilation. The check is performed on the list of methods
2192in the final stage of compilation. Additionally, a check is performed
2193for each selector appearing in a @code{@@selector(@dots{})}
2194expression, and a corresponding method for that selector has been found
2195during compilation. Because these checks scan the method table only at
2196the end of compilation, these warnings are not produced if the final
2197stage of compilation is not reached, for example because an error is
2198found during compilation, or because the @option{-fsyntax-only} option is
2199being used.
2200
2201@item -Wstrict-selector-match
2202@opindex Wstrict-selector-match
2203Warn if multiple methods with differing argument and/or return types are
2204found for a given selector when attempting to send a message using this
2205selector to a receiver of type @code{id} or @code{Class}. When this flag
2206is off (which is the default behavior), the compiler will omit such warnings
2207if any differences found are confined to types which share the same size
2208and alignment.
2209
2210@item -Wundeclared-selector
2211@opindex Wundeclared-selector
2212Warn if a @code{@@selector(@dots{})} expression referring to an
2213undeclared selector is found. A selector is considered undeclared if no
2214method with that name has been declared before the
2215@code{@@selector(@dots{})} expression, either explicitly in an
2216@code{@@interface} or @code{@@protocol} declaration, or implicitly in
2217an @code{@@implementation} section. This option always performs its
2218checks as soon as a @code{@@selector(@dots{})} expression is found,
2219while @option{-Wselector} only performs its checks in the final stage of
2220compilation. This also enforces the coding style convention
2221that methods and selectors must be declared before being used.
2222
2223@item -print-objc-runtime-info
2224@opindex print-objc-runtime-info
2225Generate C header describing the largest structure that is passed by
2226value, if any.
2227
2228@end table
2229
2230@node Language Independent Options
2231@section Options to Control Diagnostic Messages Formatting
2232@cindex options to control diagnostics formatting
2233@cindex diagnostic messages
2234@cindex message formatting
2235
2236Traditionally, diagnostic messages have been formatted irrespective of
2237the output device's aspect (e.g.@: its width, @dots{}). The options described
2238below can be used to control the diagnostic messages formatting
2239algorithm, e.g.@: how many characters per line, how often source location
2240information should be reported. Right now, only the C++ front end can
2241honor these options. However it is expected, in the near future, that
2242the remaining front ends would be able to digest them correctly.
2243
2244@table @gcctabopt
2245@item -fmessage-length=@var{n}
2246@opindex fmessage-length
2247Try to format error messages so that they fit on lines of about @var{n}
2248characters. The default is 72 characters for @command{g++} and 0 for the rest of
2249the front ends supported by GCC@. If @var{n} is zero, then no
2250line-wrapping will be done; each error message will appear on a single
2251line.
2252
2253@opindex fdiagnostics-show-location
2254@item -fdiagnostics-show-location=once
2255Only meaningful in line-wrapping mode. Instructs the diagnostic messages
2256reporter to emit @emph{once} source location information; that is, in
2257case the message is too long to fit on a single physical line and has to
2258be wrapped, the source location won't be emitted (as prefix) again,
2259over and over, in subsequent continuation lines. This is the default
2260behavior.
2261
2262@item -fdiagnostics-show-location=every-line
2263Only meaningful in line-wrapping mode. Instructs the diagnostic
2264messages reporter to emit the same source location information (as
2265prefix) for physical lines that result from the process of breaking
2266a message which is too long to fit on a single line.
2267
2268@item -fdiagnostics-show-option
2269@opindex fdiagnostics-show-option
2270This option instructs the diagnostic machinery to add text to each
2271diagnostic emitted, which indicates which command line option directly
2272controls that diagnostic, when such an option is known to the
2273diagnostic machinery.
2274
2275@end table
2276
2277@node Warning Options
2278@section Options to Request or Suppress Warnings
2279@cindex options to control warnings
2280@cindex warning messages
2281@cindex messages, warning
2282@cindex suppressing warnings
2283
2284Warnings are diagnostic messages that report constructions which
2285are not inherently erroneous but which are risky or suggest there
2286may have been an error.
2287
2288You can request many specific warnings with options beginning @samp{-W},
2289for example @option{-Wimplicit} to request warnings on implicit
2290declarations. Each of these specific warning options also has a
2291negative form beginning @samp{-Wno-} to turn off warnings;
2292for example, @option{-Wno-implicit}. This manual lists only one of the
2293two forms, whichever is not the default.
2294
2295The following options control the amount and kinds of warnings produced
2296by GCC; for further, language-specific options also refer to
2297@ref{C++ Dialect Options} and @ref{Objective-C and Objective-C++ Dialect
2298Options}.
2299
2300@table @gcctabopt
2301@cindex syntax checking
2302@item -fsyntax-only
2303@opindex fsyntax-only
2304Check the code for syntax errors, but don't do anything beyond that.
2305
2306@item -pedantic
2307@opindex pedantic
2308Issue all the warnings demanded by strict ISO C and ISO C++;
2309reject all programs that use forbidden extensions, and some other
2310programs that do not follow ISO C and ISO C++. For ISO C, follows the
2311version of the ISO C standard specified by any @option{-std} option used.
2312
2313Valid ISO C and ISO C++ programs should compile properly with or without
2314this option (though a rare few will require @option{-ansi} or a
2315@option{-std} option specifying the required version of ISO C)@. However,
2316without this option, certain GNU extensions and traditional C and C++
2317features are supported as well. With this option, they are rejected.
2318
2319@option{-pedantic} does not cause warning messages for use of the
2320alternate keywords whose names begin and end with @samp{__}. Pedantic
2321warnings are also disabled in the expression that follows
2322@code{__extension__}. However, only system header files should use
2323these escape routes; application programs should avoid them.
2324@xref{Alternate Keywords}.
2325
2326Some users try to use @option{-pedantic} to check programs for strict ISO
2327C conformance. They soon find that it does not do quite what they want:
2328it finds some non-ISO practices, but not all---only those for which
2329ISO C @emph{requires} a diagnostic, and some others for which
2330diagnostics have been added.
2331
2332A feature to report any failure to conform to ISO C might be useful in
2333some instances, but would require considerable additional work and would
2334be quite different from @option{-pedantic}. We don't have plans to
2335support such a feature in the near future.
2336
2337Where the standard specified with @option{-std} represents a GNU
2338extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
2339corresponding @dfn{base standard}, the version of ISO C on which the GNU
2340extended dialect is based. Warnings from @option{-pedantic} are given
2341where they are required by the base standard. (It would not make sense
2342for such warnings to be given only for features not in the specified GNU
2343C dialect, since by definition the GNU dialects of C include all
2344features the compiler supports with the given option, and there would be
2345nothing to warn about.)
2346
2347@item -pedantic-errors
2348@opindex pedantic-errors
2349Like @option{-pedantic}, except that errors are produced rather than
2350warnings.
2351
2352@item -w
2353@opindex w
2354Inhibit all warning messages.
2355
2356@item -Wno-import
2357@opindex Wno-import
2358Inhibit warning messages about the use of @samp{#import}.
2359
2360@item -Wchar-subscripts
2361@opindex Wchar-subscripts
2362Warn if an array subscript has type @code{char}. This is a common cause
2363of error, as programmers often forget that this type is signed on some
2364machines.
2365This warning is enabled by @option{-Wall}.
2366
2367@item -Wcomment
2368@opindex Wcomment
2369Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
2370comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
2371This warning is enabled by @option{-Wall}.
2372
2373@item -Wfatal-errors
2374@opindex Wfatal-errors
2375This option causes the compiler to abort compilation on the first error
2376occurred rather than trying to keep going and printing further error
2377messages.
2378
2379@item -Wformat
2380@opindex Wformat
2381@opindex ffreestanding
2382@opindex fno-builtin
2383Check calls to @code{printf} and @code{scanf}, etc., to make sure that
2384the arguments supplied have types appropriate to the format string
2385specified, and that the conversions specified in the format string make
2386sense. This includes standard functions, and others specified by format
2387attributes (@pxref{Function Attributes}), in the @code{printf},
2388@code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
2389not in the C standard) families (or other target-specific families).
2390Which functions are checked without format attributes having been
2391specified depends on the standard version selected, and such checks of
2392functions without the attribute specified are disabled by
2393@option{-ffreestanding} or @option{-fno-builtin}.
2394
2395The formats are checked against the format features supported by GNU
2396libc version 2.2. These include all ISO C90 and C99 features, as well
2397as features from the Single Unix Specification and some BSD and GNU
2398extensions. Other library implementations may not support all these
2399features; GCC does not support warning about features that go beyond a
2400particular library's limitations. However, if @option{-pedantic} is used
2401with @option{-Wformat}, warnings will be given about format features not
2402in the selected standard version (but not for @code{strfmon} formats,
2403since those are not in any version of the C standard). @xref{C Dialect
2404Options,,Options Controlling C Dialect}.
2405
2406Since @option{-Wformat} also checks for null format arguments for
2407several functions, @option{-Wformat} also implies @option{-Wnonnull}.
2408
2409@option{-Wformat} is included in @option{-Wall}. For more control over some
2410aspects of format checking, the options @option{-Wformat-y2k},
2411@option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
2412@option{-Wformat-nonliteral}, @option{-Wformat-security}, and
2413@option{-Wformat=2} are available, but are not included in @option{-Wall}.
2414
2415@item -Wformat-y2k
2416@opindex Wformat-y2k
2417If @option{-Wformat} is specified, also warn about @code{strftime}
2418formats which may yield only a two-digit year.
2419
2420@item -Wno-format-extra-args
2421@opindex Wno-format-extra-args
2422If @option{-Wformat} is specified, do not warn about excess arguments to a
2423@code{printf} or @code{scanf} format function. The C standard specifies
2424that such arguments are ignored.
2425
2426Where the unused arguments lie between used arguments that are
2427specified with @samp{$} operand number specifications, normally
2428warnings are still given, since the implementation could not know what
2429type to pass to @code{va_arg} to skip the unused arguments. However,
2430in the case of @code{scanf} formats, this option will suppress the
2431warning if the unused arguments are all pointers, since the Single
2432Unix Specification says that such unused arguments are allowed.
2433
2434@item -Wno-format-zero-length
2435@opindex Wno-format-zero-length
2436If @option{-Wformat} is specified, do not warn about zero-length formats.
2437The C standard specifies that zero-length formats are allowed.
2438
2439@item -Wformat-nonliteral
2440@opindex Wformat-nonliteral
2441If @option{-Wformat} is specified, also warn if the format string is not a
2442string literal and so cannot be checked, unless the format function
2443takes its format arguments as a @code{va_list}.
2444
2445@item -Wformat-security
2446@opindex Wformat-security
2447If @option{-Wformat} is specified, also warn about uses of format
2448functions that represent possible security problems. At present, this
2449warns about calls to @code{printf} and @code{scanf} functions where the
2450format string is not a string literal and there are no format arguments,
2451as in @code{printf (foo);}. This may be a security hole if the format
2452string came from untrusted input and contains @samp{%n}. (This is
2453currently a subset of what @option{-Wformat-nonliteral} warns about, but
2454in future warnings may be added to @option{-Wformat-security} that are not
2455included in @option{-Wformat-nonliteral}.)
2456
2457@item -Wformat=2
2458@opindex Wformat=2
2459Enable @option{-Wformat} plus format checks not included in
2460@option{-Wformat}. Currently equivalent to @samp{-Wformat
2461-Wformat-nonliteral -Wformat-security -Wformat-y2k}.
2462
2463@item -Wnonnull
2464@opindex Wnonnull
2465Warn about passing a null pointer for arguments marked as
2466requiring a non-null value by the @code{nonnull} function attribute.
2467
2468@option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It
2469can be disabled with the @option{-Wno-nonnull} option.
2470
2471@item -Winit-self @r{(C, C++, Objective-C and Objective-C++ only)}
2472@opindex Winit-self
2473Warn about uninitialized variables which are initialized with themselves.
2474Note this option can only be used with the @option{-Wuninitialized} option,
2475which in turn only works with @option{-O1} and above.
2476
2477For example, GCC will warn about @code{i} being uninitialized in the
2478following snippet only when @option{-Winit-self} has been specified:
2479@smallexample
2480@group
2481int f()
2482@{
2483 int i = i;
2484 return i;
2485@}
2486@end group
2487@end smallexample
2488
2489@item -Wimplicit-int
2490@opindex Wimplicit-int
2491Warn when a declaration does not specify a type.
2492This warning is enabled by @option{-Wall}.
2493
2494@item -Wimplicit-function-declaration
2495@itemx -Werror-implicit-function-declaration
2496@opindex Wimplicit-function-declaration
2497@opindex Werror-implicit-function-declaration
2498Give a warning (or error) whenever a function is used before being
2499declared. The form @option{-Wno-error-implicit-function-declaration}
2500is not supported.
2501This warning is enabled by @option{-Wall} (as a warning, not an error).
2502
2503@item -Wimplicit
2504@opindex Wimplicit
2505Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
2506This warning is enabled by @option{-Wall}.
2507
2508@item -Wmain
2509@opindex Wmain
2510Warn if the type of @samp{main} is suspicious. @samp{main} should be a
2511function with external linkage, returning int, taking either zero
2512arguments, two, or three arguments of appropriate types.
2513This warning is enabled by @option{-Wall}.
2514
2515@item -Wmissing-braces
2516@opindex Wmissing-braces
2517Warn if an aggregate or union initializer is not fully bracketed. In
2518the following example, the initializer for @samp{a} is not fully
2519bracketed, but that for @samp{b} is fully bracketed.
2520
2521@smallexample
2522int a[2][2] = @{ 0, 1, 2, 3 @};
2523int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
2524@end smallexample
2525
2526This warning is enabled by @option{-Wall}.
2527
2528@item -Wmissing-include-dirs @r{(C, C++, Objective-C and Objective-C++ only)}
2529@opindex Wmissing-include-dirs
2530Warn if a user-supplied include directory does not exist.
2531
2532@item -Wparentheses
2533@opindex Wparentheses
2534Warn if parentheses are omitted in certain contexts, such
2535as when there is an assignment in a context where a truth value
2536is expected, or when operators are nested whose precedence people
2537often get confused about. Only the warning for an assignment used as
2538a truth value is supported when compiling C++; the other warnings are
2539only supported when compiling C@.
2540
2541Also warn if a comparison like @samp{x<=y<=z} appears; this is
2542equivalent to @samp{(x<=y ? 1 : 0) <= z}, which is a different
2543interpretation from that of ordinary mathematical notation.
2544
2545Also warn about constructions where there may be confusion to which
2546@code{if} statement an @code{else} branch belongs. Here is an example of
2547such a case:
2548
2549@smallexample
2550@group
2551@{
2552 if (a)
2553 if (b)
2554 foo ();
2555 else
2556 bar ();
2557@}
2558@end group
2559@end smallexample
2560
2561In C, every @code{else} branch belongs to the innermost possible @code{if}
2562statement, which in this example is @code{if (b)}. This is often not
2563what the programmer expected, as illustrated in the above example by
2564indentation the programmer chose. When there is the potential for this
2565confusion, GCC will issue a warning when this flag is specified.
2566To eliminate the warning, add explicit braces around the innermost
2567@code{if} statement so there is no way the @code{else} could belong to
2568the enclosing @code{if}. The resulting code would look like this:
2569
2570@smallexample
2571@group
2572@{
2573 if (a)
2574 @{
2575 if (b)
2576 foo ();
2577 else
2578 bar ();
2579 @}
2580@}
2581@end group
2582@end smallexample
2583
2584This warning is enabled by @option{-Wall}.
2585
2586@item -Wsequence-point
2587@opindex Wsequence-point
2588Warn about code that may have undefined semantics because of violations
2589of sequence point rules in the C and C++ standards.
2590
2591The C and C++ standards defines the order in which expressions in a C/C++
2592program are evaluated in terms of @dfn{sequence points}, which represent
2593a partial ordering between the execution of parts of the program: those
2594executed before the sequence point, and those executed after it. These
2595occur after the evaluation of a full expression (one which is not part
2596of a larger expression), after the evaluation of the first operand of a
2597@code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
2598function is called (but after the evaluation of its arguments and the
2599expression denoting the called function), and in certain other places.
2600Other than as expressed by the sequence point rules, the order of
2601evaluation of subexpressions of an expression is not specified. All
2602these rules describe only a partial order rather than a total order,
2603since, for example, if two functions are called within one expression
2604with no sequence point between them, the order in which the functions
2605are called is not specified. However, the standards committee have
2606ruled that function calls do not overlap.
2607
2608It is not specified when between sequence points modifications to the
2609values of objects take effect. Programs whose behavior depends on this
2610have undefined behavior; the C and C++ standards specify that ``Between
2611the previous and next sequence point an object shall have its stored
2612value modified at most once by the evaluation of an expression.
2613Furthermore, the prior value shall be read only to determine the value
2614to be stored.''. If a program breaks these rules, the results on any
2615particular implementation are entirely unpredictable.
2616
2617Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
2618= b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
2619diagnosed by this option, and it may give an occasional false positive
2620result, but in general it has been found fairly effective at detecting
2621this sort of problem in programs.
2622
2623The standard is worded confusingly, therefore there is some debate
2624over the precise meaning of the sequence point rules in subtle cases.
2625Links to discussions of the problem, including proposed formal
2626definitions, may be found on the GCC readings page, at
2627@w{@uref{http://gcc.gnu.org/readings.html}}.
2628
2629This warning is enabled by @option{-Wall} for C and C++.
2630
2631@item -Wreturn-type
2632@opindex Wreturn-type
2633Warn whenever a function is defined with a return-type that defaults to
2634@code{int}. Also warn about any @code{return} statement with no
2635return-value in a function whose return-type is not @code{void}.
2636
2637For C, also warn if the return type of a function has a type qualifier
2638such as @code{const}. Such a type qualifier has no effect, since the
2639value returned by a function is not an lvalue. ISO C prohibits
2640qualified @code{void} return types on function definitions, so such
2641return types always receive a warning even without this option.
2642
2643For C++, a function without return type always produces a diagnostic
2644message, even when @option{-Wno-return-type} is specified. The only
2645exceptions are @samp{main} and functions defined in system headers.
2646
2647This warning is enabled by @option{-Wall}.
2648
2649@item -Wswitch
2650@opindex Wswitch
2651Warn whenever a @code{switch} statement has an index of enumerated type
2652and lacks a @code{case} for one or more of the named codes of that
2653enumeration. (The presence of a @code{default} label prevents this
2654warning.) @code{case} labels outside the enumeration range also
2655provoke warnings when this option is used.
2656This warning is enabled by @option{-Wall}.
2657
2658@item -Wswitch-default
2659@opindex Wswitch-switch
2660Warn whenever a @code{switch} statement does not have a @code{default}
2661case.
2662
2663@item -Wswitch-enum
2664@opindex Wswitch-enum
2665Warn whenever a @code{switch} statement has an index of enumerated type
2666and lacks a @code{case} for one or more of the named codes of that
2667enumeration. @code{case} labels outside the enumeration range also
2668provoke warnings when this option is used.
2669
2670@item -Wtrigraphs
2671@opindex Wtrigraphs
2672Warn if any trigraphs are encountered that might change the meaning of
2673the program (trigraphs within comments are not warned about).
2674This warning is enabled by @option{-Wall}.
2675
2676@item -Wunused-function
2677@opindex Wunused-function
2678Warn whenever a static function is declared but not defined or a
2679non-inline static function is unused.
2680This warning is enabled by @option{-Wall}.
2681
2682@item -Wunused-label
2683@opindex Wunused-label
2684Warn whenever a label is declared but not used.
2685This warning is enabled by @option{-Wall}.
2686
2687To suppress this warning use the @samp{unused} attribute
2688(@pxref{Variable Attributes}).
2689
2690@item -Wunused-parameter
2691@opindex Wunused-parameter
2692Warn whenever a function parameter is unused aside from its declaration.
2693
2694To suppress this warning use the @samp{unused} attribute
2695(@pxref{Variable Attributes}).
2696
2697@item -Wunused-variable
2698@opindex Wunused-variable
2699Warn whenever a local variable or non-constant static variable is unused
2700aside from its declaration.
2701This warning is enabled by @option{-Wall}.
2702
2703To suppress this warning use the @samp{unused} attribute
2704(@pxref{Variable Attributes}).
2705
2706@item -Wunused-value
2707@opindex Wunused-value
2708Warn whenever a statement computes a result that is explicitly not used.
2709This warning is enabled by @option{-Wall}.
2710
2711To suppress this warning cast the expression to @samp{void}.
2712
2713@item -Wunused
2714@opindex Wunused
2715All the above @option{-Wunused} options combined.
2716
2717In order to get a warning about an unused function parameter, you must
2718either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
2719@samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
2720
2721@item -Wuninitialized
2722@opindex Wuninitialized
2723Warn if an automatic variable is used without first being initialized or
2724if a variable may be clobbered by a @code{setjmp} call.
2725
2726These warnings are possible only in optimizing compilation,
2727because they require data flow information that is computed only
2728when optimizing. If you do not specify @option{-O}, you will not get
2729these warnings. Instead, GCC will issue a warning about @option{-Wuninitialized}
2730requiring @option{-O}.
2731
2732If you want to warn about code which uses the uninitialized value of the
2733variable in its own initializer, use the @option{-Winit-self} option.
2734
2735These warnings occur for individual uninitialized or clobbered
2736elements of structure, union or array variables as well as for
2737variables which are uninitialized or clobbered as a whole. They do
2738not occur for variables or elements declared @code{volatile}. Because
2739these warnings depend on optimization, the exact variables or elements
2740for which there are warnings will depend on the precise optimization
2741options and version of GCC used.
2742
2743Note that there may be no warning about a variable that is used only
2744to compute a value that itself is never used, because such
2745computations may be deleted by data flow analysis before the warnings
2746are printed.
2747
2748These warnings are made optional because GCC is not smart
2749enough to see all the reasons why the code might be correct
2750despite appearing to have an error. Here is one example of how
2751this can happen:
2752
2753@smallexample
2754@group
2755@{
2756 int x;
2757 switch (y)
2758 @{
2759 case 1: x = 1;
2760 break;
2761 case 2: x = 4;
2762 break;
2763 case 3: x = 5;
2764 @}
2765 foo (x);
2766@}
2767@end group
2768@end smallexample
2769
2770@noindent
2771If the value of @code{y} is always 1, 2 or 3, then @code{x} is
2772always initialized, but GCC doesn't know this. Here is
2773another common case:
2774
2775@smallexample
2776@{
2777 int save_y;
2778 if (change_y) save_y = y, y = new_y;
2779 @dots{}
2780 if (change_y) y = save_y;
2781@}
2782@end smallexample
2783
2784@noindent
2785This has no bug because @code{save_y} is used only if it is set.
2786
2787@cindex @code{longjmp} warnings
2788This option also warns when a non-volatile automatic variable might be
2789changed by a call to @code{longjmp}. These warnings as well are possible
2790only in optimizing compilation.
2791
2792The compiler sees only the calls to @code{setjmp}. It cannot know
2793where @code{longjmp} will be called; in fact, a signal handler could
2794call it at any point in the code. As a result, you may get a warning
2795even when there is in fact no problem because @code{longjmp} cannot
2796in fact be called at the place which would cause a problem.
2797
2798Some spurious warnings can be avoided if you declare all the functions
2799you use that never return as @code{noreturn}. @xref{Function
2800Attributes}.
2801
2802This warning is enabled by @option{-Wall}.
2803
2804@item -Wunknown-pragmas
2805@opindex Wunknown-pragmas
2806@cindex warning for unknown pragmas
2807@cindex unknown pragmas, warning
2808@cindex pragmas, warning of unknown
2809Warn when a #pragma directive is encountered which is not understood by
2810GCC@. If this command line option is used, warnings will even be issued
2811for unknown pragmas in system header files. This is not the case if
2812the warnings were only enabled by the @option{-Wall} command line option.
2813
2814@item -Wno-pragmas
2815@opindex Wno-pragmas
2816@opindex Wpragmas
2817Do not warn about misuses of pragmas, such as incorrect parameters,
2818invalid syntax, or conflicts between pragmas. See also
2819@samp{-Wunknown-pragmas}.
2820
2821@item -Wstrict-aliasing
2822@opindex Wstrict-aliasing
2823This option is only active when @option{-fstrict-aliasing} is active.
2824It warns about code which might break the strict aliasing rules that the
2825compiler is using for optimization. The warning does not catch all
2826cases, but does attempt to catch the more common pitfalls. It is
2827included in @option{-Wall}.
2828
2829@item -Wstrict-aliasing=2
2830@opindex Wstrict-aliasing=2
2831This option is only active when @option{-fstrict-aliasing} is active.
2832It warns about code which might break the strict aliasing rules that the
2833compiler is using for optimization. This warning catches more cases than
2834@option{-Wstrict-aliasing}, but it will also give a warning for some ambiguous
2835cases that are safe.
2836
2837@item -Wstrict-overflow
2838@item -Wstrict-overflow=@var{n}
2839@opindex Wstrict-overflow
2840This option is only active when @option{-fstrict-overflow} is active.
2841It warns about cases where the compiler optimizes based on the
2842assumption that signed overflow does not occur. Note that it does not
2843warn about all cases where the code might overflow: it only warns
2844about cases where the compiler implements some optimization. Thus
2845this warning depends on the optimization level.
2846
2847An optimization which assumes that signed overflow does not occur is
2848perfectly safe if the values of the variables involved are such that
2849overflow never does, in fact, occur. Therefore this warning can
2850easily give a false positive: a warning about code which is not
2851actually a problem. To help focus on important issues, several
2852warning levels are defined. No warnings are issued for the use of
2853undefined signed overflow when estimating how many iterations a loop
2854will require, in particular when determining whether a loop will be
2855executed at all.
2856
2857@table @option
2858@item -Wstrict-overflow=1
2859Warn about cases which are both questionable and easy to avoid. For
2860example: @code{x + 1 > x}; with @option{-fstrict-overflow}, the
2861compiler will simplify this to @code{1}. This level of
2862@option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
2863are not, and must be explicitly requested.
2864
2865@item -Wstrict-overflow=2
2866Also warn about other cases where a comparison is simplified to a
2867constant. For example: @code{abs (x) >= 0}. This can only be
2868simplified when @option{-fstrict-overflow} is in effect, because
2869@code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
2870zero. @option{-Wstrict-overflow} (with no level) is the same as
2871@option{-Wstrict-overflow=2}.
2872
2873@item -Wstrict-overflow=3
2874Also warn about other cases where a comparison is simplified. For
2875example: @code{x + 1 > 1} will be simplified to @code{x > 0}.
2876
2877@item -Wstrict-overflow=4
2878Also warn about other simplifications not covered by the above cases.
2879For example: @code{(x * 10) / 5} will be simplified to @code{x * 2}.
2880
2881@item -Wstrict-overflow=5
2882Also warn about cases where the compiler reduces the magnitude of a
2883constant involved in a comparison. For example: @code{x + 2 > y} will
2884be simplified to @code{x + 1 >= y}. This is reported only at the
2885highest warning level because this simplification applies to many
2886comparisons, so this warning level will give a very large number of
2887false positives.
2888@end table
2889
2890@item -Wall
2891@opindex Wall
2892All of the above @samp{-W} options combined. This enables all the
2893warnings about constructions that some users consider questionable, and
2894that are easy to avoid (or modify to prevent the warning), even in
2895conjunction with macros. This also enables some language-specific
2896warnings described in @ref{C++ Dialect Options} and
2897@ref{Objective-C and Objective-C++ Dialect Options}.
2898@end table
2899
2900The following @option{-W@dots{}} options are not implied by @option{-Wall}.
2901Some of them warn about constructions that users generally do not
2902consider questionable, but which occasionally you might wish to check
2903for; others warn about constructions that are necessary or hard to avoid
2904in some cases, and there is no simple way to modify the code to suppress
2905the warning.
2906
2907@table @gcctabopt
2908@item -Wextra
2909@opindex W
2910@opindex Wextra
2911(This option used to be called @option{-W}. The older name is still
2912supported, but the newer name is more descriptive.) Print extra warning
2913messages for these events:
2914
2915@itemize @bullet
2916@item
2917A function can return either with or without a value. (Falling
2918off the end of the function body is considered returning without
2919a value.) For example, this function would evoke such a
2920warning:
2921
2922@smallexample
2923@group
2924foo (a)
2925@{
2926 if (a > 0)
2927 return a;
2928@}
2929@end group
2930@end smallexample
2931
2932@item
2933An expression-statement or the left-hand side of a comma expression
2934contains no side effects.
2935To suppress the warning, cast the unused expression to void.
2936For example, an expression such as @samp{x[i,j]} will cause a warning,
2937but @samp{x[(void)i,j]} will not.
2938
2939@item
2940An unsigned value is compared against zero with @samp{<} or @samp{>=}.
2941
2942@item
2943Storage-class specifiers like @code{static} are not the first things in
2944a declaration. According to the C Standard, this usage is obsolescent.
2945
2946@item
2947If @option{-Wall} or @option{-Wunused} is also specified, warn about unused
2948arguments.
2949
2950@item
2951A comparison between signed and unsigned values could produce an
2952incorrect result when the signed value is converted to unsigned.
2953(But don't warn if @option{-Wno-sign-compare} is also specified.)
2954
2955@item
2956An aggregate has an initializer which does not initialize all members.
2957This warning can be independently controlled by
2958@option{-Wmissing-field-initializers}.
2959
2960@item
2961An initialized field without side effects is overridden when using
2962designated initializers (@pxref{Designated Inits, , Designated
2963Initializers}). This warning can be independently controlled by
2964@option{-Woverride-init}.
2965
2966@item
2967A function parameter is declared without a type specifier in K&R-style
2968functions:
2969
2970@smallexample
2971void foo(bar) @{ @}
2972@end smallexample
2973
2974@item
2975An empty body occurs in an @samp{if} or @samp{else} statement.
2976
2977@item
2978A pointer is compared against integer zero with @samp{<}, @samp{<=},
2979@samp{>}, or @samp{>=}.
2980
2981@item
2982A variable might be changed by @samp{longjmp} or @samp{vfork}.
2983
2984@item @r{(C++ only)}
2985An enumerator and a non-enumerator both appear in a conditional expression.
2986
2987@item @r{(C++ only)}
2988A non-static reference or non-static @samp{const} member appears in a
2989class without constructors.
2990
2991@item @r{(C++ only)}
2992Ambiguous virtual bases.
2993
2994@item @r{(C++ only)}
2995Subscripting an array which has been declared @samp{register}.
2996
2997@item @r{(C++ only)}
2998Taking the address of a variable which has been declared @samp{register}.
2999
3000@item @r{(C++ only)}
3001A base class is not initialized in a derived class' copy constructor.
3002@end itemize
3003
3004@item -Wno-div-by-zero
3005@opindex Wno-div-by-zero
3006@opindex Wdiv-by-zero
3007Do not warn about compile-time integer division by zero. Floating point
3008division by zero is not warned about, as it can be a legitimate way of
3009obtaining infinities and NaNs.
3010
3011@item -Wsystem-headers
3012@opindex Wsystem-headers
3013@cindex warnings from system headers
3014@cindex system headers, warnings from
3015Print warning messages for constructs found in system header files.
3016Warnings from system headers are normally suppressed, on the assumption
3017that they usually do not indicate real problems and would only make the
3018compiler output harder to read. Using this command line option tells
3019GCC to emit warnings from system headers as if they occurred in user
3020code. However, note that using @option{-Wall} in conjunction with this
3021option will @emph{not} warn about unknown pragmas in system
3022headers---for that, @option{-Wunknown-pragmas} must also be used.
3023
3024@item -Wfloat-equal
3025@opindex Wfloat-equal
3026Warn if floating point values are used in equality comparisons.
3027
3028The idea behind this is that sometimes it is convenient (for the
3029programmer) to consider floating-point values as approximations to
3030infinitely precise real numbers. If you are doing this, then you need
3031to compute (by analyzing the code, or in some other way) the maximum or
3032likely maximum error that the computation introduces, and allow for it
3033when performing comparisons (and when producing output, but that's a
3034different problem). In particular, instead of testing for equality, you
3035would check to see whether the two values have ranges that overlap; and
3036this is done with the relational operators, so equality comparisons are
3037probably mistaken.
3038
3039@item -Wtraditional @r{(C only)}
3040@opindex Wtraditional
3041Warn about certain constructs that behave differently in traditional and
3042ISO C@. Also warn about ISO C constructs that have no traditional C
3043equivalent, and/or problematic constructs which should be avoided.
3044
3045@itemize @bullet
3046@item
3047Macro parameters that appear within string literals in the macro body.
3048In traditional C macro replacement takes place within string literals,
3049but does not in ISO C@.
3050
3051@item
3052In traditional C, some preprocessor directives did not exist.
3053Traditional preprocessors would only consider a line to be a directive
3054if the @samp{#} appeared in column 1 on the line. Therefore
3055@option{-Wtraditional} warns about directives that traditional C
3056understands but would ignore because the @samp{#} does not appear as the
3057first character on the line. It also suggests you hide directives like
3058@samp{#pragma} not understood by traditional C by indenting them. Some
3059traditional implementations would not recognize @samp{#elif}, so it
3060suggests avoiding it altogether.
3061
3062@item
3063A function-like macro that appears without arguments.
3064
3065@item
3066The unary plus operator.
3067
3068@item
3069The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
3070constant suffixes. (Traditional C does support the @samp{L} suffix on integer
3071constants.) Note, these suffixes appear in macros defined in the system
3072headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
3073Use of these macros in user code might normally lead to spurious
3074warnings, however GCC's integrated preprocessor has enough context to
3075avoid warning in these cases.
3076
3077@item
3078A function declared external in one block and then used after the end of
3079the block.
3080
3081@item
3082A @code{switch} statement has an operand of type @code{long}.
3083
3084@item
3085A non-@code{static} function declaration follows a @code{static} one.
3086This construct is not accepted by some traditional C compilers.
3087
3088@item
3089The ISO type of an integer constant has a different width or
3090signedness from its traditional type. This warning is only issued if
3091the base of the constant is ten. I.e.@: hexadecimal or octal values, which
3092typically represent bit patterns, are not warned about.
3093
3094@item
3095Usage of ISO string concatenation is detected.
3096
3097@item
3098Initialization of automatic aggregates.
3099
3100@item
3101Identifier conflicts with labels. Traditional C lacks a separate
3102namespace for labels.
3103
3104@item
3105Initialization of unions. If the initializer is zero, the warning is
3106omitted. This is done under the assumption that the zero initializer in
3107user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
3108initializer warnings and relies on default initialization to zero in the
3109traditional C case.
3110
3111@item
3112Conversions by prototypes between fixed/floating point values and vice
3113versa. The absence of these prototypes when compiling with traditional
3114C would cause serious problems. This is a subset of the possible
3115conversion warnings, for the full set use @option{-Wconversion}.
3116
3117@item
3118Use of ISO C style function definitions. This warning intentionally is
3119@emph{not} issued for prototype declarations or variadic functions
3120because these ISO C features will appear in your code when using
3121libiberty's traditional C compatibility macros, @code{PARAMS} and
3122@code{VPARAMS}. This warning is also bypassed for nested functions
3123because that feature is already a GCC extension and thus not relevant to
3124traditional C compatibility.
3125@end itemize
3126
3127@item -Wdeclaration-after-statement @r{(C only)}
3128@opindex Wdeclaration-after-statement
3129Warn when a declaration is found after a statement in a block. This
3130construct, known from C++, was introduced with ISO C99 and is by default
3131allowed in GCC@. It is not supported by ISO C90 and was not supported by
3132GCC versions before GCC 3.0. @xref{Mixed Declarations}.
3133
3134@item -Wundef
3135@opindex Wundef
3136Warn if an undefined identifier is evaluated in an @samp{#if} directive.
3137
3138@item -Wno-endif-labels
3139@opindex Wno-endif-labels
3140@opindex Wendif-labels
3141Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
3142
3143@item -Wshadow
3144@opindex Wshadow
3145Warn whenever a local variable shadows another local variable, parameter or
3146global variable or whenever a built-in function is shadowed.
3147
3148@item -Wlarger-than-@var{len}
3149@opindex Wlarger-than
3150Warn whenever an object of larger than @var{len} bytes is defined.
3151
3152@item -Wunsafe-loop-optimizations
3153@opindex Wunsafe-loop-optimizations
3154Warn if the loop cannot be optimized because the compiler could not
3155assume anything on the bounds of the loop indices. With
3156@option{-funsafe-loop-optimizations} warn if the compiler made
3157such assumptions.
3158
3159@item -Wpointer-arith
3160@opindex Wpointer-arith
3161Warn about anything that depends on the ``size of'' a function type or
3162of @code{void}. GNU C assigns these types a size of 1, for
3163convenience in calculations with @code{void *} pointers and pointers
3164to functions.
3165
3166@item -Wbad-function-cast @r{(C only)}
3167@opindex Wbad-function-cast
3168Warn whenever a function call is cast to a non-matching type.
3169For example, warn if @code{int malloc()} is cast to @code{anything *}.
3170
3171@item -Wc++-compat
3172Warn about ISO C constructs that are outside of the common subset of
3173ISO C and ISO C++, e.g.@: request for implicit conversion from
3174@code{void *} to a pointer to non-@code{void} type.
3175
3176@item -Wcast-qual
3177@opindex Wcast-qual
3178Warn whenever a pointer is cast so as to remove a type qualifier from
3179the target type. For example, warn if a @code{const char *} is cast
3180to an ordinary @code{char *}.
3181
3182@item -Wcast-align
3183@opindex Wcast-align
3184Warn whenever a pointer is cast such that the required alignment of the
3185target is increased. For example, warn if a @code{char *} is cast to
3186an @code{int *} on machines where integers can only be accessed at
3187two- or four-byte boundaries.
3188
3189@item -Wwrite-strings
3190@opindex Wwrite-strings
3191When compiling C, give string constants the type @code{const
3192char[@var{length}]} so that
3193copying the address of one into a non-@code{const} @code{char *}
3194pointer will get a warning; when compiling C++, warn about the
3195deprecated conversion from string literals to @code{char *}. This
3196warning, by default, is enabled for C++ programs.
3197These warnings will help you find at
3198compile time code that can try to write into a string constant, but
3199only if you have been very careful about using @code{const} in
3200declarations and prototypes. Otherwise, it will just be a nuisance;
3201this is why we did not make @option{-Wall} request these warnings.
3202
3203@item -Wconversion
3204@opindex Wconversion
3205Warn if a prototype causes a type conversion that is different from what
3206would happen to the same argument in the absence of a prototype. This
3207includes conversions of fixed point to floating and vice versa, and
3208conversions changing the width or signedness of a fixed point argument
3209except when the same as the default promotion.
3210
3211Also, warn if a negative integer constant expression is implicitly
3212converted to an unsigned type. For example, warn about the assignment
3213@code{x = -1} if @code{x} is unsigned. But do not warn about explicit
3214casts like @code{(unsigned) -1}.
3215
3216@item -Wsign-compare
3217@opindex Wsign-compare
3218@cindex warning for comparison of signed and unsigned values
3219@cindex comparison of signed and unsigned values, warning
3220@cindex signed and unsigned values, comparison warning
3221Warn when a comparison between signed and unsigned values could produce
3222an incorrect result when the signed value is converted to unsigned.
3223This warning is also enabled by @option{-Wextra}; to get the other warnings
3224of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
3225
3226@item -Waddress
3227@opindex Waddress
3228@opindex Wno-address
3229Warn about suspicious uses of memory addresses. These include using
3230the address of a function in a conditional expression, such as
3231@code{void func(void); if (func)}, and comparisons against the memory
3232address of a string literal, such as @code{if (x == "abc")}. Such
3233uses typically indicate a programmer error: the address of a function
3234always evaluates to true, so their use in a conditional usually
3235indicate that the programmer forgot the parentheses in a function
3236call; and comparisons against string literals result in unspecified
3237behavior and are not portable in C, so they usually indicate that the
3238programmer intended to use @code{strcmp}. This warning is enabled by
3239@option{-Wall}.
3240
3241@item -Waggregate-return
3242@opindex Waggregate-return
3243Warn if any functions that return structures or unions are defined or
3244called. (In languages where you can return an array, this also elicits
3245a warning.)
3246
3247@item -Wno-attributes
3248@opindex Wno-attributes
3249@opindex Wattributes
3250Do not warn if an unexpected @code{__attribute__} is used, such as
3251unrecognized attributes, function attributes applied to variables,
3252etc. This will not stop errors for incorrect use of supported
3253attributes.
3254
3255@item -Wstrict-prototypes @r{(C only)}
3256@opindex Wstrict-prototypes
3257Warn if a function is declared or defined without specifying the
3258argument types. (An old-style function definition is permitted without
3259a warning if preceded by a declaration which specifies the argument
3260types.)
3261
3262@item -Wold-style-definition @r{(C only)}
3263@opindex Wold-style-definition
3264Warn if an old-style function definition is used. A warning is given
3265even if there is a previous prototype.
3266
3267@item -Wmissing-prototypes @r{(C only)}
3268@opindex Wmissing-prototypes
3269Warn if a global function is defined without a previous prototype
3270declaration. This warning is issued even if the definition itself
3271provides a prototype. The aim is to detect global functions that fail
3272to be declared in header files.
3273
3274@item -Wmissing-declarations @r{(C only)}
3275@opindex Wmissing-declarations
3276Warn if a global function is defined without a previous declaration.
3277Do so even if the definition itself provides a prototype.
3278Use this option to detect global functions that are not declared in
3279header files.
3280
3281@item -Wmissing-field-initializers
3282@opindex Wmissing-field-initializers
3283@opindex W
3284@opindex Wextra
3285Warn if a structure's initializer has some fields missing. For
3286example, the following code would cause such a warning, because
3287@code{x.h} is implicitly zero:
3288
3289@smallexample
3290struct s @{ int f, g, h; @};
3291struct s x = @{ 3, 4 @};
3292@end smallexample
3293
3294This option does not warn about designated initializers, so the following
3295modification would not trigger a warning:
3296
3297@smallexample
3298struct s @{ int f, g, h; @};
3299struct s x = @{ .f = 3, .g = 4 @};
3300@end smallexample
3301
3302This warning is included in @option{-Wextra}. To get other @option{-Wextra}
3303warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
3304
3305@item -Wmissing-noreturn
3306@opindex Wmissing-noreturn
3307Warn about functions which might be candidates for attribute @code{noreturn}.
3308Note these are only possible candidates, not absolute ones. Care should
3309be taken to manually verify functions actually do not ever return before
3310adding the @code{noreturn} attribute, otherwise subtle code generation
3311bugs could be introduced. You will not get a warning for @code{main} in
3312hosted C environments.
3313
3314@item -Wmissing-format-attribute
3315@opindex Wmissing-format-attribute
3316@opindex Wformat
3317Warn about function pointers which might be candidates for @code{format}
3318attributes. Note these are only possible candidates, not absolute ones.
3319GCC will guess that function pointers with @code{format} attributes that
3320are used in assignment, initialization, parameter passing or return
3321statements should have a corresponding @code{format} attribute in the
3322resulting type. I.e.@: the left-hand side of the assignment or
3323initialization, the type of the parameter variable, or the return type
3324of the containing function respectively should also have a @code{format}
3325attribute to avoid the warning.
3326
3327GCC will also warn about function definitions which might be
3328candidates for @code{format} attributes. Again, these are only
3329possible candidates. GCC will guess that @code{format} attributes
3330might be appropriate for any function that calls a function like
3331@code{vprintf} or @code{vscanf}, but this might not always be the
3332case, and some functions for which @code{format} attributes are
3333appropriate may not be detected.
3334
3335@item -Wno-multichar
3336@opindex Wno-multichar
3337@opindex Wmultichar
3338Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
3339Usually they indicate a typo in the user's code, as they have
3340implementation-defined values, and should not be used in portable code.
3341
3342@item -Wnormalized=<none|id|nfc|nfkc>
3343@opindex Wnormalized
3344@cindex NFC
3345@cindex NFKC
3346@cindex character set, input normalization
3347In ISO C and ISO C++, two identifiers are different if they are
3348different sequences of characters. However, sometimes when characters
3349outside the basic ASCII character set are used, you can have two
3350different character sequences that look the same. To avoid confusion,
3351the ISO 10646 standard sets out some @dfn{normalization rules} which
3352when applied ensure that two sequences that look the same are turned into
3353the same sequence. GCC can warn you if you are using identifiers which
3354have not been normalized; this option controls that warning.
3355
3356There are four levels of warning that GCC supports. The default is
3357@option{-Wnormalized=nfc}, which warns about any identifier which is
3358not in the ISO 10646 ``C'' normalized form, @dfn{NFC}. NFC is the
3359recommended form for most uses.
3360
3361Unfortunately, there are some characters which ISO C and ISO C++ allow
3362in identifiers that when turned into NFC aren't allowable as
3363identifiers. That is, there's no way to use these symbols in portable
3364ISO C or C++ and have all your identifiers in NFC.
3365@option{-Wnormalized=id} suppresses the warning for these characters.
3366It is hoped that future versions of the standards involved will correct
3367this, which is why this option is not the default.
3368
3369You can switch the warning off for all characters by writing
3370@option{-Wnormalized=none}. You would only want to do this if you
3371were using some other normalization scheme (like ``D''), because
3372otherwise you can easily create bugs that are literally impossible to see.
3373
3374Some characters in ISO 10646 have distinct meanings but look identical
3375in some fonts or display methodologies, especially once formatting has
3376been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
3377LETTER N'', will display just like a regular @code{n} which has been
3378placed in a superscript. ISO 10646 defines the @dfn{NFKC}
3379normalization scheme to convert all these into a standard form as
3380well, and GCC will warn if your code is not in NFKC if you use
3381@option{-Wnormalized=nfkc}. This warning is comparable to warning
3382about every identifier that contains the letter O because it might be
3383confused with the digit 0, and so is not the default, but may be
3384useful as a local coding convention if the programming environment is
3385unable to be fixed to display these characters distinctly.
3386
3387@item -Wno-deprecated-declarations
3388@opindex Wno-deprecated-declarations
3389Do not warn about uses of functions (@pxref{Function Attributes}),
3390variables (@pxref{Variable Attributes}), and types (@pxref{Type
3391Attributes}) marked as deprecated by using the @code{deprecated}
3392attribute.
3393
3394@item -Wno-overflow
3395@opindex Wno-overflow
3396Do not warn about compile-time overflow in constant expressions.
3397
3398@item -Woverride-init
3399@opindex Woverride-init
3400@opindex W
3401@opindex Wextra
3402Warn if an initialized field without side effects is overridden when
3403using designated initializers (@pxref{Designated Inits, , Designated
3404Initializers}).
3405
3406This warning is included in @option{-Wextra}. To get other
3407@option{-Wextra} warnings without this one, use @samp{-Wextra
3408-Wno-override-init}.
3409
3410@item -Wpacked
3411@opindex Wpacked
3412Warn if a structure is given the packed attribute, but the packed
3413attribute has no effect on the layout or size of the structure.
3414Such structures may be mis-aligned for little benefit. For
3415instance, in this code, the variable @code{f.x} in @code{struct bar}
3416will be misaligned even though @code{struct bar} does not itself
3417have the packed attribute:
3418
3419@smallexample
3420@group
3421struct foo @{
3422 int x;
3423 char a, b, c, d;
3424@} __attribute__((packed));
3425struct bar @{
3426 char z;
3427 struct foo f;
3428@};
3429@end group
3430@end smallexample
3431
3432@item -Wpadded
3433@opindex Wpadded
3434Warn if padding is included in a structure, either to align an element
3435of the structure or to align the whole structure. Sometimes when this
3436happens it is possible to rearrange the fields of the structure to
3437reduce the padding and so make the structure smaller.
3438
3439@item -Wredundant-decls
3440@opindex Wredundant-decls
3441Warn if anything is declared more than once in the same scope, even in
3442cases where multiple declaration is valid and changes nothing.
3443
3444@item -Wnested-externs @r{(C only)}
3445@opindex Wnested-externs
3446Warn if an @code{extern} declaration is encountered within a function.
3447
3448@item -Wunreachable-code
3449@opindex Wunreachable-code
3450Warn if the compiler detects that code will never be executed.
3451
3452This option is intended to warn when the compiler detects that at
3453least a whole line of source code will never be executed, because
3454some condition is never satisfied or because it is after a
3455procedure that never returns.
3456
3457It is possible for this option to produce a warning even though there
3458are circumstances under which part of the affected line can be executed,
3459so care should be taken when removing apparently-unreachable code.
3460
3461For instance, when a function is inlined, a warning may mean that the
3462line is unreachable in only one inlined copy of the function.
3463
3464This option is not made part of @option{-Wall} because in a debugging
3465version of a program there is often substantial code which checks
3466correct functioning of the program and is, hopefully, unreachable
3467because the program does work. Another common use of unreachable
3468code is to provide behavior which is selectable at compile-time.
3469
3470@item -Winline
3471@opindex Winline
3472Warn if a function can not be inlined and it was declared as inline.
3473Even with this option, the compiler will not warn about failures to
3474inline functions declared in system headers.
3475
3476The compiler uses a variety of heuristics to determine whether or not
3477to inline a function. For example, the compiler takes into account
3478the size of the function being inlined and the amount of inlining
3479that has already been done in the current function. Therefore,
3480seemingly insignificant changes in the source program can cause the
3481warnings produced by @option{-Winline} to appear or disappear.
3482
3483@item -Wno-invalid-offsetof @r{(C++ only)}
3484@opindex Wno-invalid-offsetof
3485Suppress warnings from applying the @samp{offsetof} macro to a non-POD
3486type. According to the 1998 ISO C++ standard, applying @samp{offsetof}
3487to a non-POD type is undefined. In existing C++ implementations,
3488however, @samp{offsetof} typically gives meaningful results even when
3489applied to certain kinds of non-POD types. (Such as a simple
3490@samp{struct} that fails to be a POD type only by virtue of having a
3491constructor.) This flag is for users who are aware that they are
3492writing nonportable code and who have deliberately chosen to ignore the
3493warning about it.
3494
3495The restrictions on @samp{offsetof} may be relaxed in a future version
3496of the C++ standard.
3497
3498@item -Wno-int-to-pointer-cast @r{(C only)}
3499@opindex Wno-int-to-pointer-cast
3500Suppress warnings from casts to pointer type of an integer of a
3501different size.
3502
3503@item -Wno-pointer-to-int-cast @r{(C only)}
3504@opindex Wno-pointer-to-int-cast
3505Suppress warnings from casts from a pointer to an integer type of a
3506different size.
3507
3508@item -Winvalid-pch
3509@opindex Winvalid-pch
3510Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
3511the search path but can't be used.
3512
3513@item -Wlong-long
3514@opindex Wlong-long
3515@opindex Wno-long-long
3516Warn if @samp{long long} type is used. This is default. To inhibit
3517the warning messages, use @option{-Wno-long-long}. Flags
3518@option{-Wlong-long} and @option{-Wno-long-long} are taken into account
3519only when @option{-pedantic} flag is used.
3520
3521@item -Wvariadic-macros
3522@opindex Wvariadic-macros
3523@opindex Wno-variadic-macros
3524Warn if variadic macros are used in pedantic ISO C90 mode, or the GNU
3525alternate syntax when in pedantic ISO C99 mode. This is default.
3526To inhibit the warning messages, use @option{-Wno-variadic-macros}.
3527
3528@item -Wvolatile-register-var
3529@opindex Wvolatile-register-var
3530@opindex Wno-volatile-register-var
3531Warn if a register variable is declared volatile. The volatile
3532modifier does not inhibit all optimizations that may eliminate reads
3533and/or writes to register variables.
3534
3535@item -Wdisabled-optimization
3536@opindex Wdisabled-optimization
3537Warn if a requested optimization pass is disabled. This warning does
3538not generally indicate that there is anything wrong with your code; it
3539merely indicates that GCC's optimizers were unable to handle the code
3540effectively. Often, the problem is that your code is too big or too
3541complex; GCC will refuse to optimize programs when the optimization
3542itself is likely to take inordinate amounts of time.
3543
3544@item -Wpointer-sign
3545@opindex Wpointer-sign
3546@opindex Wno-pointer-sign
3547Warn for pointer argument passing or assignment with different signedness.
3548This option is only supported for C and Objective-C@. It is implied by
3549@option{-Wall} and by @option{-pedantic}, which can be disabled with
3550@option{-Wno-pointer-sign}.
3551
3552@item -Werror
3553@opindex Werror
3554Make all warnings into errors.
3555
3556@item -Werror=
3557@opindex Werror=
3558Make the specified warning into an errors. The specifier for a
3559warning is appended, for example @option{-Werror=switch} turns the
3560warnings controlled by @option{-Wswitch} into errors. This switch
3561takes a negative form, to be used to negate @option{-Werror} for
3562specific warnings, for example @option{-Wno-error=switch} makes
3563@option{-Wswitch} warnings not be errors, even when @option{-Werror}
3564is in effect. You can use the @option{-fdiagnostics-show-option}
3565option to have each controllable warning amended with the option which
3566controls it, to determine what to use with this option.
3567
3568Note that specifying @option{-Werror=}@var{foo} automatically implies
3569@option{-W}@var{foo}. However, @option{-Wno-error=}@var{foo} does not
3570imply anything.
3571
3572@item -Wstack-protector
3573@opindex Wstack-protector
3574This option is only active when @option{-fstack-protector} is active. It
3575warns about functions that will not be protected against stack smashing.
3576
3577@item -Woverlength-strings
3578@opindex Woverlength-strings
3579Warn about string constants which are longer than the ``minimum
3580maximum'' length specified in the C standard. Modern compilers
3581generally allow string constants which are much longer than the
3582standard's minimum limit, but very portable programs should avoid
3583using longer strings.
3584
3585The limit applies @emph{after} string constant concatenation, and does
3586not count the trailing NUL@. In C89, the limit was 509 characters; in
3587C99, it was raised to 4095. C++98 does not specify a normative
3588minimum maximum, so we do not diagnose overlength strings in C++@.
3589
3590This option is implied by @option{-pedantic}, and can be disabled with
3591@option{-Wno-overlength-strings}.
3592@end table
3593
3594@node Debugging Options
3595@section Options for Debugging Your Program or GCC
3596@cindex options, debugging
3597@cindex debugging information options
3598
3599GCC has various special options that are used for debugging
3600either your program or GCC:
3601
3602@table @gcctabopt
3603@item -g
3604@opindex g
3605Produce debugging information in the operating system's native format
3606(stabs, COFF, XCOFF, or DWARF 2)@. GDB can work with this debugging
3607information.
3608
3609On most systems that use stabs format, @option{-g} enables use of extra
3610debugging information that only GDB can use; this extra information
3611makes debugging work better in GDB but will probably make other debuggers
3612crash or
3613refuse to read the program. If you want to control for certain whether
3614to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
3615@option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
3616
3617GCC allows you to use @option{-g} with
3618@option{-O}. The shortcuts taken by optimized code may occasionally
3619produce surprising results: some variables you declared may not exist
3620at all; flow of control may briefly move where you did not expect it;
3621some statements may not be executed because they compute constant
3622results or their values were already at hand; some statements may
3623execute in different places because they were moved out of loops.
3624
3625Nevertheless it proves possible to debug optimized output. This makes
3626it reasonable to use the optimizer for programs that might have bugs.
3627
3628The following options are useful when GCC is generated with the
3629capability for more than one debugging format.
3630
3631@item -ggdb
3632@opindex ggdb
3633Produce debugging information for use by GDB@. This means to use the
3634most expressive format available (DWARF 2, stabs, or the native format
3635if neither of those are supported), including GDB extensions if at all
3636possible.
3637
3638@item -gstabs
3639@opindex gstabs
3640Produce debugging information in stabs format (if that is supported),
3641without GDB extensions. This is the format used by DBX on most BSD
3642systems. On MIPS, Alpha and System V Release 4 systems this option
3643produces stabs debugging output which is not understood by DBX or SDB@.
3644On System V Release 4 systems this option requires the GNU assembler.
3645
3646@item -feliminate-unused-debug-symbols
3647@opindex feliminate-unused-debug-symbols
3648Produce debugging information in stabs format (if that is supported),
3649for only symbols that are actually used.
3650
3651@item -femit-class-debug-always
3652Instead of emitting debugging information for a C++ class in only one
3653object file, emit it in all object files using the class. This option
3654should be used only with debuggers that are unable to handle the way GCC
3655normally emits debugging information for classes because using this
3656option will increase the size of debugging information by as much as a
3657factor of two.
3658
3659@item -gstabs+
3660@opindex gstabs+
3661Produce debugging information in stabs format (if that is supported),
3662using GNU extensions understood only by the GNU debugger (GDB)@. The
3663use of these extensions is likely to make other debuggers crash or
3664refuse to read the program.
3665
3666@item -gcoff
3667@opindex gcoff
3668Produce debugging information in COFF format (if that is supported).
3669This is the format used by SDB on most System V systems prior to
3670System V Release 4.
3671
3672@item -gxcoff
3673@opindex gxcoff
3674Produce debugging information in XCOFF format (if that is supported).
3675This is the format used by the DBX debugger on IBM RS/6000 systems.
3676
3677@item -gxcoff+
3678@opindex gxcoff+
3679Produce debugging information in XCOFF format (if that is supported),
3680using GNU extensions understood only by the GNU debugger (GDB)@. The
3681use of these extensions is likely to make other debuggers crash or
3682refuse to read the program, and may cause assemblers other than the GNU
3683assembler (GAS) to fail with an error.
3684
3685@item -gdwarf-2
3686@opindex gdwarf-2
3687Produce debugging information in DWARF version 2 format (if that is
3688supported). This is the format used by DBX on IRIX 6. With this
3689option, GCC uses features of DWARF version 3 when they are useful;
3690version 3 is upward compatible with version 2, but may still cause
3691problems for older debuggers.
3692
3693@item -gvms
3694@opindex gvms
3695Produce debugging information in VMS debug format (if that is
3696supported). This is the format used by DEBUG on VMS systems.
3697
3698@item -g@var{level}
3699@itemx -ggdb@var{level}
3700@itemx -gstabs@var{level}
3701@itemx -gcoff@var{level}
3702@itemx -gxcoff@var{level}
3703@itemx -gvms@var{level}
3704Request debugging information and also use @var{level} to specify how
3705much information. The default level is 2.
3706
3707Level 1 produces minimal information, enough for making backtraces in
3708parts of the program that you don't plan to debug. This includes
3709descriptions of functions and external variables, but no information
3710about local variables and no line numbers.
3711
3712Level 3 includes extra information, such as all the macro definitions
3713present in the program. Some debuggers support macro expansion when
3714you use @option{-g3}.
3715
3716@option{-gdwarf-2} does not accept a concatenated debug level, because
3717GCC used to support an option @option{-gdwarf} that meant to generate
3718debug information in version 1 of the DWARF format (which is very
3719different from version 2), and it would have been too confusing. That
3720debug format is long obsolete, but the option cannot be changed now.
3721Instead use an additional @option{-g@var{level}} option to change the
3722debug level for DWARF2.
3723
3724@item -feliminate-dwarf2-dups
3725@opindex feliminate-dwarf2-dups
3726Compress DWARF2 debugging information by eliminating duplicated
3727information about each symbol. This option only makes sense when
3728generating DWARF2 debugging information with @option{-gdwarf-2}.
3729
3730@cindex @command{prof}
3731@item -p
3732@opindex p
3733Generate extra code to write profile information suitable for the
3734analysis program @command{prof}. You must use this option when compiling
3735the source files you want data about, and you must also use it when
3736linking.
3737
3738@cindex @command{gprof}
3739@item -pg
3740@opindex pg
3741Generate extra code to write profile information suitable for the
3742analysis program @command{gprof}. You must use this option when compiling
3743the source files you want data about, and you must also use it when
3744linking.
3745
3746@item -Q
3747@opindex Q
3748Makes the compiler print out each function name as it is compiled, and
3749print some statistics about each pass when it finishes.
3750
3751@item -ftime-report
3752@opindex ftime-report
3753Makes the compiler print some statistics about the time consumed by each
3754pass when it finishes.
3755
3756@item -fmem-report
3757@opindex fmem-report
3758Makes the compiler print some statistics about permanent memory
3759allocation when it finishes.
3760
3761@item -fprofile-arcs
3762@opindex fprofile-arcs
3763Add code so that program flow @dfn{arcs} are instrumented. During
3764execution the program records how many times each branch and call is
3765executed and how many times it is taken or returns. When the compiled
3766program exits it saves this data to a file called
3767@file{@var{auxname}.gcda} for each source file. The data may be used for
3768profile-directed optimizations (@option{-fbranch-probabilities}), or for
3769test coverage analysis (@option{-ftest-coverage}). Each object file's
3770@var{auxname} is generated from the name of the output file, if
3771explicitly specified and it is not the final executable, otherwise it is
3772the basename of the source file. In both cases any suffix is removed
3773(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
3774@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
3775@xref{Cross-profiling}.
3776
3777@cindex @command{gcov}
3778@item --coverage
3779@opindex coverage
3780
3781This option is used to compile and link code instrumented for coverage
3782analysis. The option is a synonym for @option{-fprofile-arcs}
3783@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
3784linking). See the documentation for those options for more details.
3785
3786@itemize
3787
3788@item
3789Compile the source files with @option{-fprofile-arcs} plus optimization
3790and code generation options. For test coverage analysis, use the
3791additional @option{-ftest-coverage} option. You do not need to profile
3792every source file in a program.
3793
3794@item
3795Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
3796(the latter implies the former).
3797
3798@item
3799Run the program on a representative workload to generate the arc profile
3800information. This may be repeated any number of times. You can run
3801concurrent instances of your program, and provided that the file system
3802supports locking, the data files will be correctly updated. Also
3803@code{fork} calls are detected and correctly handled (double counting
3804will not happen).
3805
3806@item
3807For profile-directed optimizations, compile the source files again with
3808the same optimization and code generation options plus
3809@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
3810Control Optimization}).
3811
3812@item
3813For test coverage analysis, use @command{gcov} to produce human readable
3814information from the @file{.gcno} and @file{.gcda} files. Refer to the
3815@command{gcov} documentation for further information.
3816
3817@end itemize
3818
3819With @option{-fprofile-arcs}, for each function of your program GCC
3820creates a program flow graph, then finds a spanning tree for the graph.
3821Only arcs that are not on the spanning tree have to be instrumented: the
3822compiler adds code to count the number of times that these arcs are
3823executed. When an arc is the only exit or only entrance to a block, the
3824instrumentation code can be added to the block; otherwise, a new basic
3825block must be created to hold the instrumentation code.
3826
3827@need 2000
3828@item -ftest-coverage
3829@opindex ftest-coverage
3830Produce a notes file that the @command{gcov} code-coverage utility
3831(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
3832show program coverage. Each source file's note file is called
3833@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
3834above for a description of @var{auxname} and instructions on how to
3835generate test coverage data. Coverage data will match the source files
3836more closely, if you do not optimize.
3837
3838@item -d@var{letters}
3839@item -fdump-rtl-@var{pass}
3840@opindex d
3841Says to make debugging dumps during compilation at times specified by
3842@var{letters}. This is used for debugging the RTL-based passes of the
3843compiler. The file names for most of the dumps are made by appending a
3844pass number and a word to the @var{dumpname}. @var{dumpname} is generated
3845from the name of the output file, if explicitly specified and it is not
3846an executable, otherwise it is the basename of the source file.
3847
3848Most debug dumps can be enabled either passing a letter to the @option{-d}
3849option, or with a long @option{-fdump-rtl} switch; here are the possible
3850letters for use in @var{letters} and @var{pass}, and their meanings:
3851
3852@table @gcctabopt
3853@item -dA
3854@opindex dA
3855Annotate the assembler output with miscellaneous debugging information.
3856
3857@item -dB
3858@itemx -fdump-rtl-bbro
3859@opindex dB
3860@opindex fdump-rtl-bbro
3861Dump after block reordering, to @file{@var{file}.148r.bbro}.
3862
3863@item -dc
3864@itemx -fdump-rtl-combine
3865@opindex dc
3866@opindex fdump-rtl-combine
3867Dump after instruction combination, to the file @file{@var{file}.129r.combine}.
3868
3869@item -dC
3870@itemx -fdump-rtl-ce1
3871@itemx -fdump-rtl-ce2
3872@opindex dC
3873@opindex fdump-rtl-ce1
3874@opindex fdump-rtl-ce2
3875@option{-dC} and @option{-fdump-rtl-ce1} enable dumping after the
3876first if conversion, to the file @file{@var{file}.117r.ce1}. @option{-dC}
3877and @option{-fdump-rtl-ce2} enable dumping after the second if
3878conversion, to the file @file{@var{file}.130r.ce2}.
3879
3880@item -dd
3881@itemx -fdump-rtl-btl
3882@itemx -fdump-rtl-dbr
3883@opindex dd
3884@opindex fdump-rtl-btl
3885@opindex fdump-rtl-dbr
3886@option{-dd} and @option{-fdump-rtl-btl} enable dumping after branch
3887target load optimization, to @file{@var{file}.31.btl}. @option{-dd}
3888and @option{-fdump-rtl-dbr} enable dumping after delayed branch
3889scheduling, to @file{@var{file}.36.dbr}.
3890
3891@item -dD
3892@opindex dD
3893Dump all macro definitions, at the end of preprocessing, in addition to
3894normal output.
3895
3896@item -dE
3897@itemx -fdump-rtl-ce3
3898@opindex dE
3899@opindex fdump-rtl-ce3
3900Dump after the third if conversion, to @file{@var{file}.146r.ce3}.
3901
3902@item -df
3903@itemx -fdump-rtl-cfg
3904@itemx -fdump-rtl-life
3905@opindex df
3906@opindex fdump-rtl-cfg
3907@opindex fdump-rtl-life
3908@option{-df} and @option{-fdump-rtl-cfg} enable dumping after control
3909and data flow analysis, to @file{@var{file}.116r.cfg}. @option{-df}
3910and @option{-fdump-rtl-cfg} enable dumping dump after life analysis,
3911to @file{@var{file}.128r.life1} and @file{@var{file}.135r.life2}.
3912
3913@item -dg
3914@itemx -fdump-rtl-greg
3915@opindex dg
3916@opindex fdump-rtl-greg
3917Dump after global register allocation, to @file{@var{file}.139r.greg}.
3918
3919@item -dG
3920@itemx -fdump-rtl-gcse
3921@itemx -fdump-rtl-bypass
3922@opindex dG
3923@opindex fdump-rtl-gcse
3924@opindex fdump-rtl-bypass
3925@option{-dG} and @option{-fdump-rtl-gcse} enable dumping after GCSE, to
3926@file{@var{file}.114r.gcse}. @option{-dG} and @option{-fdump-rtl-bypass}
3927enable dumping after jump bypassing and control flow optimizations, to
3928@file{@var{file}.115r.bypass}.
3929
3930@item -dh
3931@itemx -fdump-rtl-eh
3932@opindex dh
3933@opindex fdump-rtl-eh
3934Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
3935
3936@item -di
3937@itemx -fdump-rtl-sibling
3938@opindex di
3939@opindex fdump-rtl-sibling
3940Dump after sibling call optimizations, to @file{@var{file}.106r.sibling}.
3941
3942@item -dj
3943@itemx -fdump-rtl-jump
3944@opindex dj
3945@opindex fdump-rtl-jump
3946Dump after the first jump optimization, to @file{@var{file}.112r.jump}.
3947
3948@item -dk
3949@itemx -fdump-rtl-stack
3950@opindex dk
3951@opindex fdump-rtl-stack
3952Dump after conversion from registers to stack, to @file{@var{file}.152r.stack}.
3953
3954@item -dl
3955@itemx -fdump-rtl-lreg
3956@opindex dl
3957@opindex fdump-rtl-lreg
3958Dump after local register allocation, to @file{@var{file}.138r.lreg}.
3959
3960@item -dL
3961@itemx -fdump-rtl-loop2
3962@opindex dL
3963@opindex fdump-rtl-loop2
3964@option{-dL} and @option{-fdump-rtl-loop2} enable dumping after the
3965loop optimization pass, to @file{@var{file}.119r.loop2},
3966@file{@var{file}.120r.loop2_init},
3967@file{@var{file}.121r.loop2_invariant}, and
3968@file{@var{file}.125r.loop2_done}.
3969
3970@item -dm
3971@itemx -fdump-rtl-sms
3972@opindex dm
3973@opindex fdump-rtl-sms
3974Dump after modulo scheduling, to @file{@var{file}.136r.sms}.
3975
3976@item -dM
3977@itemx -fdump-rtl-mach
3978@opindex dM
3979@opindex fdump-rtl-mach
3980Dump after performing the machine dependent reorganization pass, to
3981@file{@var{file}.155r.mach}.
3982
3983@item -dn
3984@itemx -fdump-rtl-rnreg
3985@opindex dn
3986@opindex fdump-rtl-rnreg
3987Dump after register renumbering, to @file{@var{file}.147r.rnreg}.
3988
3989@item -dN
3990@itemx -fdump-rtl-regmove
3991@opindex dN
3992@opindex fdump-rtl-regmove
3993Dump after the register move pass, to @file{@var{file}.132r.regmove}.
3994
3995@item -do
3996@itemx -fdump-rtl-postreload
3997@opindex do
3998@opindex fdump-rtl-postreload
3999Dump after post-reload optimizations, to @file{@var{file}.24.postreload}.
4000
4001@item -dr
4002@itemx -fdump-rtl-expand
4003@opindex dr
4004@opindex fdump-rtl-expand
4005Dump after RTL generation, to @file{@var{file}.104r.expand}.
4006
4007@item -dR
4008@itemx -fdump-rtl-sched2
4009@opindex dR
4010@opindex fdump-rtl-sched2
4011Dump after the second scheduling pass, to @file{@var{file}.150r.sched2}.
4012
4013@item -ds
4014@itemx -fdump-rtl-cse
4015@opindex ds
4016@opindex fdump-rtl-cse
4017Dump after CSE (including the jump optimization that sometimes follows
4018CSE), to @file{@var{file}.113r.cse}.
4019
4020@item -dS
4021@itemx -fdump-rtl-sched
4022@opindex dS
4023@opindex fdump-rtl-sched
4024Dump after the first scheduling pass, to @file{@var{file}.21.sched}.
4025
4026@item -dt
4027@itemx -fdump-rtl-cse2
4028@opindex dt
4029@opindex fdump-rtl-cse2
4030Dump after the second CSE pass (including the jump optimization that
4031sometimes follows CSE), to @file{@var{file}.127r.cse2}.
4032
4033@item -dT
4034@itemx -fdump-rtl-tracer
4035@opindex dT
4036@opindex fdump-rtl-tracer
4037Dump after running tracer, to @file{@var{file}.118r.tracer}.
4038
4039@item -dV
4040@itemx -fdump-rtl-vpt
4041@itemx -fdump-rtl-vartrack
4042@opindex dV
4043@opindex fdump-rtl-vpt
4044@opindex fdump-rtl-vartrack
4045@option{-dV} and @option{-fdump-rtl-vpt} enable dumping after the value
4046profile transformations, to @file{@var{file}.10.vpt}. @option{-dV}
4047and @option{-fdump-rtl-vartrack} enable dumping after variable tracking,
4048to @file{@var{file}.154r.vartrack}.
4049
4050@item -dw
4051@itemx -fdump-rtl-flow2
4052@opindex dw
4053@opindex fdump-rtl-flow2
4054Dump after the second flow pass, to @file{@var{file}.142r.flow2}.
4055
4056@item -dz
4057@itemx -fdump-rtl-peephole2
4058@opindex dz
4059@opindex fdump-rtl-peephole2
4060Dump after the peephole pass, to @file{@var{file}.145r.peephole2}.
4061
4062@item -dZ
4063@itemx -fdump-rtl-web
4064@opindex dZ
4065@opindex fdump-rtl-web
4066Dump after live range splitting, to @file{@var{file}.126r.web}.
4067
4068@item -da
4069@itemx -fdump-rtl-all
4070@opindex da
4071@opindex fdump-rtl-all
4072Produce all the dumps listed above.
4073
4074@item -dH
4075@opindex dH
4076Produce a core dump whenever an error occurs.
4077
4078@item -dm
4079@opindex dm
4080Print statistics on memory usage, at the end of the run, to
4081standard error.
4082
4083@item -dp
4084@opindex dp
4085Annotate the assembler output with a comment indicating which
4086pattern and alternative was used. The length of each instruction is
4087also printed.
4088
4089@item -dP
4090@opindex dP
4091Dump the RTL in the assembler output as a comment before each instruction.
4092Also turns on @option{-dp} annotation.
4093
4094@item -dv
4095@opindex dv
4096For each of the other indicated dump files (either with @option{-d} or
4097@option{-fdump-rtl-@var{pass}}), dump a representation of the control flow
4098graph suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
4099
4100@item -dx
4101@opindex dx
4102Just generate RTL for a function instead of compiling it. Usually used
4103with @samp{r} (@option{-fdump-rtl-expand}).
4104
4105@item -dy
4106@opindex dy
4107Dump debugging information during parsing, to standard error.
4108@end table
4109
4110@item -fdump-noaddr
4111@opindex fdump-noaddr
4112When doing debugging dumps (see @option{-d} option above), suppress
4113address output. This makes it more feasible to use diff on debugging
4114dumps for compiler invocations with different compiler binaries and/or
4115different text / bss / data / heap / stack / dso start locations.
4116
4117@item -fdump-unnumbered
4118@opindex fdump-unnumbered
4119When doing debugging dumps (see @option{-d} option above), suppress instruction
4120numbers, line number note and address output. This makes it more feasible to
4121use diff on debugging dumps for compiler invocations with different
4122options, in particular with and without @option{-g}.
4123
4124@item -fdump-translation-unit @r{(C++ only)}
4125@itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
4126@opindex fdump-translation-unit
4127Dump a representation of the tree structure for the entire translation
4128unit to a file. The file name is made by appending @file{.tu} to the
4129source file name. If the @samp{-@var{options}} form is used, @var{options}
4130controls the details of the dump as described for the
4131@option{-fdump-tree} options.
4132
4133@item -fdump-class-hierarchy @r{(C++ only)}
4134@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
4135@opindex fdump-class-hierarchy
4136Dump a representation of each class's hierarchy and virtual function
4137table layout to a file. The file name is made by appending @file{.class}
4138to the source file name. If the @samp{-@var{options}} form is used,
4139@var{options} controls the details of the dump as described for the
4140@option{-fdump-tree} options.
4141
4142@item -fdump-ipa-@var{switch}
4143@opindex fdump-ipa
4144Control the dumping at various stages of inter-procedural analysis
4145language tree to a file. The file name is generated by appending a switch
4146specific suffix to the source file name. The following dumps are possible:
4147
4148@table @samp
4149@item all
4150Enables all inter-procedural analysis dumps; currently the only produced
4151dump is the @samp{cgraph} dump.
4152
4153@item cgraph
4154Dumps information about call-graph optimization, unused function removal,
4155and inlining decisions.
4156@end table
4157
4158@item -fdump-tree-@var{switch}
4159@itemx -fdump-tree-@var{switch}-@var{options}
4160@opindex fdump-tree
4161Control the dumping at various stages of processing the intermediate
4162language tree to a file. The file name is generated by appending a switch
4163specific suffix to the source file name. If the @samp{-@var{options}}
4164form is used, @var{options} is a list of @samp{-} separated options that
4165control the details of the dump. Not all options are applicable to all
4166dumps, those which are not meaningful will be ignored. The following
4167options are available
4168
4169@table @samp
4170@item address
4171Print the address of each node. Usually this is not meaningful as it
4172changes according to the environment and source file. Its primary use
4173is for tying up a dump file with a debug environment.
4174@item slim
4175Inhibit dumping of members of a scope or body of a function merely
4176because that scope has been reached. Only dump such items when they
4177are directly reachable by some other path. When dumping pretty-printed
4178trees, this option inhibits dumping the bodies of control structures.
4179@item raw
4180Print a raw representation of the tree. By default, trees are
4181pretty-printed into a C-like representation.
4182@item details
4183Enable more detailed dumps (not honored by every dump option).
4184@item stats
4185Enable dumping various statistics about the pass (not honored by every dump
4186option).
4187@item blocks
4188Enable showing basic block boundaries (disabled in raw dumps).
4189@item vops
4190Enable showing virtual operands for every statement.
4191@item lineno
4192Enable showing line numbers for statements.
4193@item uid
4194Enable showing the unique ID (@code{DECL_UID}) for each variable.
4195@item all
4196Turn on all options, except @option{raw}, @option{slim} and @option{lineno}.
4197@end table
4198
4199The following tree dumps are possible:
4200@table @samp
4201
4202@item original
4203Dump before any tree based optimization, to @file{@var{file}.original}.
4204
4205@item optimized
4206Dump after all tree based optimization, to @file{@var{file}.optimized}.
4207
4208@item inlined
4209Dump after function inlining, to @file{@var{file}.inlined}.
4210
4211@item gimple
4212@opindex fdump-tree-gimple
4213Dump each function before and after the gimplification pass to a file. The
4214file name is made by appending @file{.gimple} to the source file name.
4215
4216@item cfg
4217@opindex fdump-tree-cfg
4218Dump the control flow graph of each function to a file. The file name is
4219made by appending @file{.cfg} to the source file name.
4220
4221@item vcg
4222@opindex fdump-tree-vcg
4223Dump the control flow graph of each function to a file in VCG format. The
4224file name is made by appending @file{.vcg} to the source file name. Note
4225that if the file contains more than one function, the generated file cannot
4226be used directly by VCG@. You will need to cut and paste each function's
4227graph into its own separate file first.
4228
4229@item ch
4230@opindex fdump-tree-ch
4231Dump each function after copying loop headers. The file name is made by
4232appending @file{.ch} to the source file name.
4233
4234@item ssa
4235@opindex fdump-tree-ssa
4236Dump SSA related information to a file. The file name is made by appending
4237@file{.ssa} to the source file name.
4238
4239@item salias
4240@opindex fdump-tree-salias
4241Dump structure aliasing variable information to a file. This file name
4242is made by appending @file{.salias} to the source file name.
4243
4244@item alias
4245@opindex fdump-tree-alias
4246Dump aliasing information for each function. The file name is made by
4247appending @file{.alias} to the source file name.
4248
4249@item ccp
4250@opindex fdump-tree-ccp
4251Dump each function after CCP@. The file name is made by appending
4252@file{.ccp} to the source file name.
4253
4254@item storeccp
4255@opindex fdump-tree-storeccp
4256Dump each function after STORE-CCP. The file name is made by appending
4257@file{.storeccp} to the source file name.
4258
4259@item pre
4260@opindex fdump-tree-pre
4261Dump trees after partial redundancy elimination. The file name is made
4262by appending @file{.pre} to the source file name.
4263
4264@item fre
4265@opindex fdump-tree-fre
4266Dump trees after full redundancy elimination. The file name is made
4267by appending @file{.fre} to the source file name.
4268
4269@item copyprop
4270@opindex fdump-tree-copyprop
4271Dump trees after copy propagation. The file name is made
4272by appending @file{.copyprop} to the source file name.
4273
4274@item store_copyprop
4275@opindex fdump-tree-store_copyprop
4276Dump trees after store copy-propagation. The file name is made
4277by appending @file{.store_copyprop} to the source file name.
4278
4279@item dce
4280@opindex fdump-tree-dce
4281Dump each function after dead code elimination. The file name is made by
4282appending @file{.dce} to the source file name.
4283
4284@item mudflap
4285@opindex fdump-tree-mudflap
4286Dump each function after adding mudflap instrumentation. The file name is
4287made by appending @file{.mudflap} to the source file name.
4288
4289@item sra
4290@opindex fdump-tree-sra
4291Dump each function after performing scalar replacement of aggregates. The
4292file name is made by appending @file{.sra} to the source file name.
4293
4294@item sink
4295@opindex fdump-tree-sink
4296Dump each function after performing code sinking. The file name is made
4297by appending @file{.sink} to the source file name.
4298
4299@item dom
4300@opindex fdump-tree-dom
4301Dump each function after applying dominator tree optimizations. The file
4302name is made by appending @file{.dom} to the source file name.
4303
4304@item dse
4305@opindex fdump-tree-dse
4306Dump each function after applying dead store elimination. The file
4307name is made by appending @file{.dse} to the source file name.
4308
4309@item phiopt
4310@opindex fdump-tree-phiopt
4311Dump each function after optimizing PHI nodes into straightline code. The file
4312name is made by appending @file{.phiopt} to the source file name.
4313
4314@item forwprop
4315@opindex fdump-tree-forwprop
4316Dump each function after forward propagating single use variables. The file
4317name is made by appending @file{.forwprop} to the source file name.
4318
4319@item copyrename
4320@opindex fdump-tree-copyrename
4321Dump each function after applying the copy rename optimization. The file
4322name is made by appending @file{.copyrename} to the source file name.
4323
4324@item nrv
4325@opindex fdump-tree-nrv
4326Dump each function after applying the named return value optimization on
4327generic trees. The file name is made by appending @file{.nrv} to the source
4328file name.
4329
4330@item vect
4331@opindex fdump-tree-vect
4332Dump each function after applying vectorization of loops. The file name is
4333made by appending @file{.vect} to the source file name.
4334
4335@item vrp
4336@opindex fdump-tree-vrp
4337Dump each function after Value Range Propagation (VRP). The file name
4338is made by appending @file{.vrp} to the source file name.
4339
4340@item all
4341@opindex fdump-tree-all
4342Enable all the available tree dumps with the flags provided in this option.
4343@end table
4344
4345@item -ftree-vectorizer-verbose=@var{n}
4346@opindex ftree-vectorizer-verbose
4347This option controls the amount of debugging output the vectorizer prints.
4348This information is written to standard error, unless
4349@option{-fdump-tree-all} or @option{-fdump-tree-vect} is specified,
4350in which case it is output to the usual dump listing file, @file{.vect}.
4351For @var{n}=0 no diagnostic information is reported.
4352If @var{n}=1 the vectorizer reports each loop that got vectorized,
4353and the total number of loops that got vectorized.
4354If @var{n}=2 the vectorizer also reports non-vectorized loops that passed
4355the first analysis phase (vect_analyze_loop_form) - i.e. countable,
4356inner-most, single-bb, single-entry/exit loops. This is the same verbosity
4357level that @option{-fdump-tree-vect-stats} uses.
4358Higher verbosity levels mean either more information dumped for each
4359reported loop, or same amount of information reported for more loops:
4360If @var{n}=3, alignment related information is added to the reports.
4361If @var{n}=4, data-references related information (e.g. memory dependences,
4362memory access-patterns) is added to the reports.
4363If @var{n}=5, the vectorizer reports also non-vectorized inner-most loops
4364that did not pass the first analysis phase (i.e. may not be countable, or
4365may have complicated control-flow).
4366If @var{n}=6, the vectorizer reports also non-vectorized nested loops.
4367For @var{n}=7, all the information the vectorizer generates during its
4368analysis and transformation is reported. This is the same verbosity level
4369that @option{-fdump-tree-vect-details} uses.
4370
4371@item -frandom-seed=@var{string}
4372@opindex frandom-string
4373This option provides a seed that GCC uses when it would otherwise use
4374random numbers. It is used to generate certain symbol names
4375that have to be different in every compiled file. It is also used to
4376place unique stamps in coverage data files and the object files that
4377produce them. You can use the @option{-frandom-seed} option to produce
4378reproducibly identical object files.
4379
4380The @var{string} should be different for every file you compile.
4381
4382@item -fsched-verbose=@var{n}
4383@opindex fsched-verbose
4384On targets that use instruction scheduling, this option controls the
4385amount of debugging output the scheduler prints. This information is
4386written to standard error, unless @option{-dS} or @option{-dR} is
4387specified, in which case it is output to the usual dump
4388listing file, @file{.sched} or @file{.sched2} respectively. However
4389for @var{n} greater than nine, the output is always printed to standard
4390error.
4391
4392For @var{n} greater than zero, @option{-fsched-verbose} outputs the
4393same information as @option{-dRS}. For @var{n} greater than one, it
4394also output basic block probabilities, detailed ready list information
4395and unit/insn info. For @var{n} greater than two, it includes RTL
4396at abort point, control-flow and regions info. And for @var{n} over
4397four, @option{-fsched-verbose} also includes dependence info.
4398
4399@item -save-temps
4400@opindex save-temps
4401Store the usual ``temporary'' intermediate files permanently; place them
4402in the current directory and name them based on the source file. Thus,
4403compiling @file{foo.c} with @samp{-c -save-temps} would produce files
4404@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
4405preprocessed @file{foo.i} output file even though the compiler now
4406normally uses an integrated preprocessor.
4407
4408When used in combination with the @option{-x} command line option,
4409@option{-save-temps} is sensible enough to avoid over writing an
4410input source file with the same extension as an intermediate file.
4411The corresponding intermediate file may be obtained by renaming the
4412source file before using @option{-save-temps}.
4413
4414@item -time
4415@opindex time
4416Report the CPU time taken by each subprocess in the compilation
4417sequence. For C source files, this is the compiler proper and assembler
4418(plus the linker if linking is done). The output looks like this:
4419
4420@smallexample
4421# cc1 0.12 0.01
4422# as 0.00 0.01
4423@end smallexample
4424
4425The first number on each line is the ``user time'', that is time spent
4426executing the program itself. The second number is ``system time'',
4427time spent executing operating system routines on behalf of the program.
4428Both numbers are in seconds.
4429
4430@item -fvar-tracking
4431@opindex fvar-tracking
4432Run variable tracking pass. It computes where variables are stored at each
4433position in code. Better debugging information is then generated
4434(if the debugging information format supports this information).
4435
4436It is enabled by default when compiling with optimization (@option{-Os},
4437@option{-O}, @option{-O2}, ...), debugging information (@option{-g}) and
4438the debug info format supports it.
4439
4440@item -print-file-name=@var{library}
4441@opindex print-file-name
4442Print the full absolute name of the library file @var{library} that
4443would be used when linking---and don't do anything else. With this
4444option, GCC does not compile or link anything; it just prints the
4445file name.
4446
4447@item -print-multi-directory
4448@opindex print-multi-directory
4449Print the directory name corresponding to the multilib selected by any
4450other switches present in the command line. This directory is supposed
4451to exist in @env{GCC_EXEC_PREFIX}.
4452
4453@item -print-multi-lib
4454@opindex print-multi-lib
4455Print the mapping from multilib directory names to compiler switches
4456that enable them. The directory name is separated from the switches by
4457@samp{;}, and each switch starts with an @samp{@@} instead of the
4458@samp{-}, without spaces between multiple switches. This is supposed to
4459ease shell-processing.
4460
4461@item -print-prog-name=@var{program}
4462@opindex print-prog-name
4463Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
4464
4465@item -print-libgcc-file-name
4466@opindex print-libgcc-file-name
4467Same as @option{-print-file-name=libgcc.a}.
4468
4469This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
4470but you do want to link with @file{libgcc.a}. You can do
4471
4472@smallexample
4473gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
4474@end smallexample
4475
4476@item -print-search-dirs
4477@opindex print-search-dirs
4478Print the name of the configured installation directory and a list of
4479program and library directories @command{gcc} will search---and don't do anything else.
4480
4481This is useful when @command{gcc} prints the error message
4482@samp{installation problem, cannot exec cpp0: No such file or directory}.
4483To resolve this you either need to put @file{cpp0} and the other compiler
4484components where @command{gcc} expects to find them, or you can set the environment
4485variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
4486Don't forget the trailing @samp{/}.
4487@xref{Environment Variables}.
4488
4489@item -dumpmachine
4490@opindex dumpmachine
4491Print the compiler's target machine (for example,
4492@samp{i686-pc-linux-gnu})---and don't do anything else.
4493
4494@item -dumpversion
4495@opindex dumpversion
4496Print the compiler version (for example, @samp{3.0})---and don't do
4497anything else.
4498
4499@item -dumpspecs
4500@opindex dumpspecs
4501Print the compiler's built-in specs---and don't do anything else. (This
4502is used when GCC itself is being built.) @xref{Spec Files}.
4503
4504@item -feliminate-unused-debug-types
4505@opindex feliminate-unused-debug-types
4506Normally, when producing DWARF2 output, GCC will emit debugging
4507information for all types declared in a compilation
4508unit, regardless of whether or not they are actually used
4509in that compilation unit. Sometimes this is useful, such as
4510if, in the debugger, you want to cast a value to a type that is
4511not actually used in your program (but is declared). More often,
4512however, this results in a significant amount of wasted space.
4513With this option, GCC will avoid producing debug symbol output
4514for types that are nowhere used in the source file being compiled.
4515@end table
4516
4517@node Optimize Options
4518@section Options That Control Optimization
4519@cindex optimize options
4520@cindex options, optimization
4521
4522These options control various sorts of optimizations.
4523
4524Without any optimization option, the compiler's goal is to reduce the
4525cost of compilation and to make debugging produce the expected
4526results. Statements are independent: if you stop the program with a
4527breakpoint between statements, you can then assign a new value to any
4528variable or change the program counter to any other statement in the
4529function and get exactly the results you would expect from the source
4530code.
4531
4532Turning on optimization flags makes the compiler attempt to improve
4533the performance and/or code size at the expense of compilation time
4534and possibly the ability to debug the program.
4535
4536The compiler performs optimization based on the knowledge it has of
4537the program. Optimization levels @option{-O} and above, in
4538particular, enable @emph{unit-at-a-time} mode, which allows the
4539compiler to consider information gained from later functions in
4540the file when compiling a function. Compiling multiple files at
4541once to a single output file in @emph{unit-at-a-time} mode allows
4542the compiler to use information gained from all of the files when
4543compiling each of them.
4544
4545Not all optimizations are controlled directly by a flag. Only
4546optimizations that have a flag are listed.
4547
4548@table @gcctabopt
4549@item -O
4550@itemx -O1
4551@opindex O
4552@opindex O1
4553Optimize. Optimizing compilation takes somewhat more time, and a lot
4554more memory for a large function.
4555
4556With @option{-O}, the compiler tries to reduce code size and execution
4557time, without performing any optimizations that take a great deal of
4558compilation time.
4559
4560@option{-O} turns on the following optimization flags:
4561@gccoptlist{-fdefer-pop @gol
4562-fdelayed-branch @gol
4563-fguess-branch-probability @gol
4564-fcprop-registers @gol
4565-fif-conversion @gol
4566-fif-conversion2 @gol
4567-ftree-ccp @gol
4568-ftree-dce @gol
4569-ftree-dominator-opts @gol
4570-ftree-dse @gol
4571-ftree-ter @gol
4572-ftree-lrs @gol
4573-ftree-sra @gol
4574-ftree-copyrename @gol
4575-ftree-fre @gol
4576-ftree-ch @gol
4577-funit-at-a-time @gol
4578-fmerge-constants}
4579
4580@option{-O} also turns on @option{-fomit-frame-pointer} on machines
4581where doing so does not interfere with debugging.
4582
4583@item -O2
4584@opindex O2
4585Optimize even more. GCC performs nearly all supported optimizations
4586that do not involve a space-speed tradeoff. The compiler does not
4587perform loop unrolling or function inlining when you specify @option{-O2}.
4588As compared to @option{-O}, this option increases both compilation time
4589and the performance of the generated code.
4590
4591@option{-O2} turns on all optimization flags specified by @option{-O}. It
4592also turns on the following optimization flags:
4593@gccoptlist{-fthread-jumps @gol
4594-fcrossjumping @gol
4595-foptimize-sibling-calls @gol
4596-fcse-follow-jumps -fcse-skip-blocks @gol
4597-fgcse -fgcse-lm @gol
4598-fexpensive-optimizations @gol
4599-frerun-cse-after-loop @gol
4600-fcaller-saves @gol
4601-fpeephole2 @gol
4602-fschedule-insns -fschedule-insns2 @gol
4603-fsched-interblock -fsched-spec @gol
4604-fregmove @gol
4605-fstrict-aliasing -fstrict-overflow @gol
4606-fdelete-null-pointer-checks @gol
4607-freorder-blocks -freorder-functions @gol
4608-falign-functions -falign-jumps @gol
4609-falign-loops -falign-labels @gol
4610-ftree-vrp @gol
4611-ftree-pre}
4612
4613Please note the warning under @option{-fgcse} about
4614invoking @option{-O2} on programs that use computed gotos.
4615
4616@option{-O2} doesn't turn on @option{-ftree-vrp} for the Ada compiler.
4617This option must be explicitly specified on the command line to be
4618enabled for the Ada compiler.
4619
4620@item -O3
4621@opindex O3
4622Optimize yet more. @option{-O3} turns on all optimizations specified by
4623@option{-O2} and also turns on the @option{-finline-functions},
4624@option{-funswitch-loops} and @option{-fgcse-after-reload} options.
4625
4626@item -O0
4627@opindex O0
4628Do not optimize. This is the default.
4629
4630@item -Os
4631@opindex Os
4632Optimize for size. @option{-Os} enables all @option{-O2} optimizations that
4633do not typically increase code size. It also performs further
4634optimizations designed to reduce code size.
4635
4636@option{-Os} disables the following optimization flags:
4637@gccoptlist{-falign-functions -falign-jumps -falign-loops @gol
4638-falign-labels -freorder-blocks -freorder-blocks-and-partition @gol
4639-fprefetch-loop-arrays -ftree-vect-loop-version}
4640
4641If you use multiple @option{-O} options, with or without level numbers,
4642the last such option is the one that is effective.
4643@end table
4644
4645Options of the form @option{-f@var{flag}} specify machine-independent
4646flags. Most flags have both positive and negative forms; the negative
4647form of @option{-ffoo} would be @option{-fno-foo}. In the table
4648below, only one of the forms is listed---the one you typically will
4649use. You can figure out the other form by either removing @samp{no-}
4650or adding it.
4651
4652The following options control specific optimizations. They are either
4653activated by @option{-O} options or are related to ones that are. You
4654can use the following flags in the rare cases when ``fine-tuning'' of
4655optimizations to be performed is desired.
4656
4657@table @gcctabopt
4658@item -fno-default-inline
4659@opindex fno-default-inline
4660Do not make member functions inline by default merely because they are
4661defined inside the class scope (C++ only). Otherwise, when you specify
4662@w{@option{-O}}, member functions defined inside class scope are compiled
4663inline by default; i.e., you don't need to add @samp{inline} in front of
4664the member function name.
4665
4666@item -fno-defer-pop
4667@opindex fno-defer-pop
4668Always pop the arguments to each function call as soon as that function
4669returns. For machines which must pop arguments after a function call,
4670the compiler normally lets arguments accumulate on the stack for several
4671function calls and pops them all at once.
4672
4673Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4674
4675@item -fforce-mem
4676@opindex fforce-mem
4677Force memory operands to be copied into registers before doing
4678arithmetic on them. This produces better code by making all memory
4679references potential common subexpressions. When they are not common
4680subexpressions, instruction combination should eliminate the separate
4681register-load. This option is now a nop and will be removed in 4.3.
4682
4683@item -fforce-addr
4684@opindex fforce-addr
4685Force memory address constants to be copied into registers before
4686doing arithmetic on them.
4687
4688@item -fomit-frame-pointer
4689@opindex fomit-frame-pointer
4690Don't keep the frame pointer in a register for functions that
4691don't need one. This avoids the instructions to save, set up and
4692restore frame pointers; it also makes an extra register available
4693in many functions. @strong{It also makes debugging impossible on
4694some machines.}
4695
4696On some machines, such as the VAX, this flag has no effect, because
4697the standard calling sequence automatically handles the frame pointer
4698and nothing is saved by pretending it doesn't exist. The
4699machine-description macro @code{FRAME_POINTER_REQUIRED} controls
4700whether a target machine supports this flag. @xref{Registers,,Register
4701Usage, gccint, GNU Compiler Collection (GCC) Internals}.
4702
4703Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4704
4705@item -foptimize-sibling-calls
4706@opindex foptimize-sibling-calls
4707Optimize sibling and tail recursive calls.
4708
4709Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4710
4711@item -fno-inline
4712@opindex fno-inline
4713Don't pay attention to the @code{inline} keyword. Normally this option
4714is used to keep the compiler from expanding any functions inline.
4715Note that if you are not optimizing, no functions can be expanded inline.
4716
4717@item -finline-functions
4718@opindex finline-functions
4719Integrate all simple functions into their callers. The compiler
4720heuristically decides which functions are simple enough to be worth
4721integrating in this way.
4722
4723If all calls to a given function are integrated, and the function is
4724declared @code{static}, then the function is normally not output as
4725assembler code in its own right.
4726
4727Enabled at level @option{-O3}.
4728
4729@item -finline-functions-called-once
4730@opindex finline-functions-called-once
4731Consider all @code{static} functions called once for inlining into their
4732caller even if they are not marked @code{inline}. If a call to a given
4733function is integrated, then the function is not output as assembler code
4734in its own right.
4735
4736Enabled if @option{-funit-at-a-time} is enabled.
4737
4738@item -fearly-inlining
4739@opindex fearly-inlining
4740Inline functions marked by @code{always_inline} and functions whose body seems
4741smaller than the function call overhead early before doing
4742@option{-fprofile-generate} instrumentation and real inlining pass. Doing so
4743makes profiling significantly cheaper and usually inlining faster on programs
4744having large chains of nested wrapper functions.
4745
4746Enabled by default.
4747
4748@item -finline-limit=@var{n}
4749@opindex finline-limit
4750By default, GCC limits the size of functions that can be inlined. This flag
4751allows the control of this limit for functions that are explicitly marked as
4752inline (i.e., marked with the inline keyword or defined within the class
4753definition in c++). @var{n} is the size of functions that can be inlined in
4754number of pseudo instructions (not counting parameter handling). The default
4755value of @var{n} is 600.
4756Increasing this value can result in more inlined code at
4757the cost of compilation time and memory consumption. Decreasing usually makes
4758the compilation faster and less code will be inlined (which presumably
4759means slower programs). This option is particularly useful for programs that
4760use inlining heavily such as those based on recursive templates with C++.
4761
4762Inlining is actually controlled by a number of parameters, which may be
4763specified individually by using @option{--param @var{name}=@var{value}}.
4764The @option{-finline-limit=@var{n}} option sets some of these parameters
4765as follows:
4766
4767@table @gcctabopt
4768@item max-inline-insns-single
4769 is set to @var{n}/2.
4770@item max-inline-insns-auto
4771 is set to @var{n}/2.
4772@item min-inline-insns
4773 is set to 130 or @var{n}/4, whichever is smaller.
4774@item max-inline-insns-rtl
4775 is set to @var{n}.
4776@end table
4777
4778See below for a documentation of the individual
4779parameters controlling inlining.
4780
4781@emph{Note:} pseudo instruction represents, in this particular context, an
4782abstract measurement of function's size. In no way does it represent a count
4783of assembly instructions and as such its exact meaning might change from one
4784release to an another.
4785
4786@item -fkeep-inline-functions
4787@opindex fkeep-inline-functions
4788In C, emit @code{static} functions that are declared @code{inline}
4789into the object file, even if the function has been inlined into all
4790of its callers. This switch does not affect functions using the
4791@code{extern inline} extension in GNU C@. In C++, emit any and all
4792inline functions into the object file.
4793
4794@item -fkeep-static-consts
4795@opindex fkeep-static-consts
4796Emit variables declared @code{static const} when optimization isn't turned
4797on, even if the variables aren't referenced.
4798
4799GCC enables this option by default. If you want to force the compiler to
4800check if the variable was referenced, regardless of whether or not
4801optimization is turned on, use the @option{-fno-keep-static-consts} option.
4802
4803@item -fmerge-constants
4804Attempt to merge identical constants (string constants and floating point
4805constants) across compilation units.
4806
4807This option is the default for optimized compilation if the assembler and
4808linker support it. Use @option{-fno-merge-constants} to inhibit this
4809behavior.
4810
4811Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4812
4813@item -fmerge-all-constants
4814Attempt to merge identical constants and identical variables.
4815
4816This option implies @option{-fmerge-constants}. In addition to
4817@option{-fmerge-constants} this considers e.g.@: even constant initialized
4818arrays or initialized constant variables with integral or floating point
4819types. Languages like C or C++ require each non-automatic variable to
4820have distinct location, so using this option will result in non-conforming
4821behavior.
4822
4823@item -fmodulo-sched
4824@opindex fmodulo-sched
4825Perform swing modulo scheduling immediately before the first scheduling
4826pass. This pass looks at innermost loops and reorders their
4827instructions by overlapping different iterations.
4828
4829@item -fno-branch-count-reg
4830@opindex fno-branch-count-reg
4831Do not use ``decrement and branch'' instructions on a count register,
4832but instead generate a sequence of instructions that decrement a
4833register, compare it against zero, then branch based upon the result.
4834This option is only meaningful on architectures that support such
4835instructions, which include x86, PowerPC, IA-64 and S/390.
4836
4837The default is @option{-fbranch-count-reg}.
4838
4839@item -fno-function-cse
4840@opindex fno-function-cse
4841Do not put function addresses in registers; make each instruction that
4842calls a constant function contain the function's address explicitly.
4843
4844This option results in less efficient code, but some strange hacks
4845that alter the assembler output may be confused by the optimizations
4846performed when this option is not used.
4847
4848The default is @option{-ffunction-cse}
4849
4850@item -fno-zero-initialized-in-bss
4851@opindex fno-zero-initialized-in-bss
4852If the target supports a BSS section, GCC by default puts variables that
4853are initialized to zero into BSS@. This can save space in the resulting
4854code.
4855
4856This option turns off this behavior because some programs explicitly
4857rely on variables going to the data section. E.g., so that the
4858resulting executable can find the beginning of that section and/or make
4859assumptions based on that.
4860
4861The default is @option{-fzero-initialized-in-bss}.
4862
4863@item -fbounds-check
4864@opindex fbounds-check
4865For front-ends that support it, generate additional code to check that
4866indices used to access arrays are within the declared range. This is
4867currently only supported by the Java and Fortran front-ends, where
4868this option defaults to true and false respectively.
4869
4870@item -fmudflap -fmudflapth -fmudflapir
4871@opindex fmudflap
4872@opindex fmudflapth
4873@opindex fmudflapir
4874@cindex bounds checking
4875@cindex mudflap
4876For front-ends that support it (C and C++), instrument all risky
4877pointer/array dereferencing operations, some standard library
4878string/heap functions, and some other associated constructs with
4879range/validity tests. Modules so instrumented should be immune to
4880buffer overflows, invalid heap use, and some other classes of C/C++
4881programming errors. The instrumentation relies on a separate runtime
4882library (@file{libmudflap}), which will be linked into a program if
4883@option{-fmudflap} is given at link time. Run-time behavior of the
4884instrumented program is controlled by the @env{MUDFLAP_OPTIONS}
4885environment variable. See @code{env MUDFLAP_OPTIONS=-help a.out}
4886for its options.
4887
4888Use @option{-fmudflapth} instead of @option{-fmudflap} to compile and to
4889link if your program is multi-threaded. Use @option{-fmudflapir}, in
4890addition to @option{-fmudflap} or @option{-fmudflapth}, if
4891instrumentation should ignore pointer reads. This produces less
4892instrumentation (and therefore faster execution) and still provides
4893some protection against outright memory corrupting writes, but allows
4894erroneously read data to propagate within a program.
4895
4896@item -fthread-jumps
4897@opindex fthread-jumps
4898Perform optimizations where we check to see if a jump branches to a
4899location where another comparison subsumed by the first is found. If
4900so, the first branch is redirected to either the destination of the
4901second branch or a point immediately following it, depending on whether
4902the condition is known to be true or false.
4903
4904Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4905
4906@item -fcse-follow-jumps
4907@opindex fcse-follow-jumps
4908In common subexpression elimination, scan through jump instructions
4909when the target of the jump is not reached by any other path. For
4910example, when CSE encounters an @code{if} statement with an
4911@code{else} clause, CSE will follow the jump when the condition
4912tested is false.
4913
4914Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4915
4916@item -fcse-skip-blocks
4917@opindex fcse-skip-blocks
4918This is similar to @option{-fcse-follow-jumps}, but causes CSE to
4919follow jumps which conditionally skip over blocks. When CSE
4920encounters a simple @code{if} statement with no else clause,
4921@option{-fcse-skip-blocks} causes CSE to follow the jump around the
4922body of the @code{if}.
4923
4924Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4925
4926@item -frerun-cse-after-loop
4927@opindex frerun-cse-after-loop
4928Re-run common subexpression elimination after loop optimizations has been
4929performed.
4930
4931Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4932
4933@item -fgcse
4934@opindex fgcse
4935Perform a global common subexpression elimination pass.
4936This pass also performs global constant and copy propagation.
4937
4938@emph{Note:} When compiling a program using computed gotos, a GCC
4939extension, you may get better runtime performance if you disable
4940the global common subexpression elimination pass by adding
4941@option{-fno-gcse} to the command line.
4942
4943Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4944
4945@item -fgcse-lm
4946@opindex fgcse-lm
4947When @option{-fgcse-lm} is enabled, global common subexpression elimination will
4948attempt to move loads which are only killed by stores into themselves. This
4949allows a loop containing a load/store sequence to be changed to a load outside
4950the loop, and a copy/store within the loop.
4951
4952Enabled by default when gcse is enabled.
4953
4954@item -fgcse-sm
4955@opindex fgcse-sm
4956When @option{-fgcse-sm} is enabled, a store motion pass is run after
4957global common subexpression elimination. This pass will attempt to move
4958stores out of loops. When used in conjunction with @option{-fgcse-lm},
4959loops containing a load/store sequence can be changed to a load before
4960the loop and a store after the loop.
4961
4962Not enabled at any optimization level.
4963
4964@item -fgcse-las
4965@opindex fgcse-las
4966When @option{-fgcse-las} is enabled, the global common subexpression
4967elimination pass eliminates redundant loads that come after stores to the
4968same memory location (both partial and full redundancies).
4969
4970Not enabled at any optimization level.
4971
4972@item -fgcse-after-reload
4973@opindex fgcse-after-reload
4974When @option{-fgcse-after-reload} is enabled, a redundant load elimination
4975pass is performed after reload. The purpose of this pass is to cleanup
4976redundant spilling.
4977
4978@item -funsafe-loop-optimizations
4979@opindex funsafe-loop-optimizations
4980If given, the loop optimizer will assume that loop indices do not
4981overflow, and that the loops with nontrivial exit condition are not
4982infinite. This enables a wider range of loop optimizations even if
4983the loop optimizer itself cannot prove that these assumptions are valid.
4984Using @option{-Wunsafe-loop-optimizations}, the compiler will warn you
4985if it finds this kind of loop.
4986
4987@item -fcrossjumping
4988@opindex crossjumping
4989Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
4990resulting code may or may not perform better than without cross-jumping.
4991
4992Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4993
4994@item -fif-conversion
4995@opindex if-conversion
4996Attempt to transform conditional jumps into branch-less equivalents. This
4997include use of conditional moves, min, max, set flags and abs instructions, and
4998some tricks doable by standard arithmetics. The use of conditional execution
4999on chips where it is available is controlled by @code{if-conversion2}.
5000
5001Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5002
5003@item -fif-conversion2
5004@opindex if-conversion2
5005Use conditional execution (where available) to transform conditional jumps into
5006branch-less equivalents.
5007
5008Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5009
5010@item -fdelete-null-pointer-checks
5011@opindex fdelete-null-pointer-checks
5012Use global dataflow analysis to identify and eliminate useless checks
5013for null pointers. The compiler assumes that dereferencing a null
5014pointer would have halted the program. If a pointer is checked after
5015it has already been dereferenced, it cannot be null.
5016
5017In some environments, this assumption is not true, and programs can
5018safely dereference null pointers. Use
5019@option{-fno-delete-null-pointer-checks} to disable this optimization
5020for programs which depend on that behavior.
5021
5022Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5023
5024@item -fexpensive-optimizations
5025@opindex fexpensive-optimizations
5026Perform a number of minor optimizations that are relatively expensive.
5027
5028Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5029
5030@item -foptimize-register-move
5031@itemx -fregmove
5032@opindex foptimize-register-move
5033@opindex fregmove
5034Attempt to reassign register numbers in move instructions and as
5035operands of other simple instructions in order to maximize the amount of
5036register tying. This is especially helpful on machines with two-operand
5037instructions.
5038
5039Note @option{-fregmove} and @option{-foptimize-register-move} are the same
5040optimization.
5041
5042Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5043
5044@item -fdelayed-branch
5045@opindex fdelayed-branch
5046If supported for the target machine, attempt to reorder instructions
5047to exploit instruction slots available after delayed branch
5048instructions.
5049
5050Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5051
5052@item -fschedule-insns
5053@opindex fschedule-insns
5054If supported for the target machine, attempt to reorder instructions to
5055eliminate execution stalls due to required data being unavailable. This
5056helps machines that have slow floating point or memory load instructions
5057by allowing other instructions to be issued until the result of the load
5058or floating point instruction is required.
5059
5060Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5061
5062@item -fschedule-insns2
5063@opindex fschedule-insns2
5064Similar to @option{-fschedule-insns}, but requests an additional pass of
5065instruction scheduling after register allocation has been done. This is
5066especially useful on machines with a relatively small number of
5067registers and where memory load instructions take more than one cycle.
5068
5069Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5070
5071@item -fno-sched-interblock
5072@opindex fno-sched-interblock
5073Don't schedule instructions across basic blocks. This is normally
5074enabled by default when scheduling before register allocation, i.e.@:
5075with @option{-fschedule-insns} or at @option{-O2} or higher.
5076
5077@item -fno-sched-spec
5078@opindex fno-sched-spec
5079Don't allow speculative motion of non-load instructions. This is normally
5080enabled by default when scheduling before register allocation, i.e.@:
5081with @option{-fschedule-insns} or at @option{-O2} or higher.
5082
5083@item -fsched-spec-load
5084@opindex fsched-spec-load
5085Allow speculative motion of some load instructions. This only makes
5086sense when scheduling before register allocation, i.e.@: with
5087@option{-fschedule-insns} or at @option{-O2} or higher.
5088
5089@item -fsched-spec-load-dangerous
5090@opindex fsched-spec-load-dangerous
5091Allow speculative motion of more load instructions. This only makes
5092sense when scheduling before register allocation, i.e.@: with
5093@option{-fschedule-insns} or at @option{-O2} or higher.
5094
5095@item -fsched-stalled-insns=@var{n}
5096@opindex fsched-stalled-insns
5097Define how many insns (if any) can be moved prematurely from the queue
5098of stalled insns into the ready list, during the second scheduling pass.
5099
5100@item -fsched-stalled-insns-dep=@var{n}
5101@opindex fsched-stalled-insns-dep
5102Define how many insn groups (cycles) will be examined for a dependency
5103on a stalled insn that is candidate for premature removal from the queue
5104of stalled insns. Has an effect only during the second scheduling pass,
5105and only if @option{-fsched-stalled-insns} is used and its value is not zero.
5106
5107@item -fsched2-use-superblocks
5108@opindex fsched2-use-superblocks
5109When scheduling after register allocation, do use superblock scheduling
5110algorithm. Superblock scheduling allows motion across basic block boundaries
5111resulting on faster schedules. This option is experimental, as not all machine
5112descriptions used by GCC model the CPU closely enough to avoid unreliable
5113results from the algorithm.
5114
5115This only makes sense when scheduling after register allocation, i.e.@: with
5116@option{-fschedule-insns2} or at @option{-O2} or higher.
5117
5118@item -fsched2-use-traces
5119@opindex fsched2-use-traces
5120Use @option{-fsched2-use-superblocks} algorithm when scheduling after register
5121allocation and additionally perform code duplication in order to increase the
5122size of superblocks using tracer pass. See @option{-ftracer} for details on
5123trace formation.
5124
5125This mode should produce faster but significantly longer programs. Also
5126without @option{-fbranch-probabilities} the traces constructed may not
5127match the reality and hurt the performance. This only makes
5128sense when scheduling after register allocation, i.e.@: with
5129@option{-fschedule-insns2} or at @option{-O2} or higher.
5130
5131@item -fsee
5132@opindex fsee
5133Eliminates redundant extension instructions and move the non redundant
5134ones to optimal placement using LCM.
5135
5136@item -freschedule-modulo-scheduled-loops
5137@opindex fscheduling-in-modulo-scheduled-loops
5138The modulo scheduling comes before the traditional scheduling, if a loop was modulo scheduled
5139we may want to prevent the later scheduling passes from changing its schedule, we use this
5140option to control that.
5141
5142@item -fcaller-saves
5143@opindex fcaller-saves
5144Enable values to be allocated in registers that will be clobbered by
5145function calls, by emitting extra instructions to save and restore the
5146registers around such calls. Such allocation is done only when it
5147seems to result in better code than would otherwise be produced.
5148
5149This option is always enabled by default on certain machines, usually
5150those which have no call-preserved registers to use instead.
5151
5152Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5153
5154@item -ftree-pre
5155Perform Partial Redundancy Elimination (PRE) on trees. This flag is
5156enabled by default at @option{-O2} and @option{-O3}.
5157
5158@item -ftree-fre
5159Perform Full Redundancy Elimination (FRE) on trees. The difference
5160between FRE and PRE is that FRE only considers expressions
5161that are computed on all paths leading to the redundant computation.
5162This analysis faster than PRE, though it exposes fewer redundancies.
5163This flag is enabled by default at @option{-O} and higher.
5164
5165@item -ftree-copy-prop
5166Perform copy propagation on trees. This pass eliminates unnecessary
5167copy operations. This flag is enabled by default at @option{-O} and
5168higher.
5169
5170@item -ftree-store-copy-prop
5171Perform copy propagation of memory loads and stores. This pass
5172eliminates unnecessary copy operations in memory references
5173(structures, global variables, arrays, etc). This flag is enabled by
5174default at @option{-O2} and higher.
5175
5176@item -ftree-salias
5177Perform structural alias analysis on trees. This flag
5178is enabled by default at @option{-O} and higher.
5179
5180@item -fipa-pta
5181Perform interprocedural pointer analysis.
5182
5183@item -ftree-sink
5184Perform forward store motion on trees. This flag is
5185enabled by default at @option{-O} and higher.
5186
5187@item -ftree-ccp
5188Perform sparse conditional constant propagation (CCP) on trees. This
5189pass only operates on local scalar variables and is enabled by default
5190at @option{-O} and higher.
5191
5192@item -ftree-store-ccp
5193Perform sparse conditional constant propagation (CCP) on trees. This
5194pass operates on both local scalar variables and memory stores and
5195loads (global variables, structures, arrays, etc). This flag is
5196enabled by default at @option{-O2} and higher.
5197
5198@item -ftree-dce
5199Perform dead code elimination (DCE) on trees. This flag is enabled by
5200default at @option{-O} and higher.
5201
5202@item -ftree-dominator-opts
5203Perform a variety of simple scalar cleanups (constant/copy
5204propagation, redundancy elimination, range propagation and expression
5205simplification) based on a dominator tree traversal. This also
5206performs jump threading (to reduce jumps to jumps). This flag is
5207enabled by default at @option{-O} and higher.
5208
5209@item -ftree-ch
5210Perform loop header copying on trees. This is beneficial since it increases
5211effectiveness of code motion optimizations. It also saves one jump. This flag
5212is enabled by default at @option{-O} and higher. It is not enabled
5213for @option{-Os}, since it usually increases code size.
5214
5215@item -ftree-loop-optimize
5216Perform loop optimizations on trees. This flag is enabled by default
5217at @option{-O} and higher.
5218
5219@item -ftree-loop-linear
5220Perform linear loop transformations on tree. This flag can improve cache
5221performance and allow further loop optimizations to take place.
5222
5223@item -ftree-loop-im
5224Perform loop invariant motion on trees. This pass moves only invariants that
5225would be hard to handle at RTL level (function calls, operations that expand to
5226nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
5227operands of conditions that are invariant out of the loop, so that we can use
5228just trivial invariantness analysis in loop unswitching. The pass also includes
5229store motion.
5230
5231@item -ftree-loop-ivcanon
5232Create a canonical counter for number of iterations in the loop for that
5233determining number of iterations requires complicated analysis. Later
5234optimizations then may determine the number easily. Useful especially
5235in connection with unrolling.
5236
5237@item -fivopts
5238Perform induction variable optimizations (strength reduction, induction
5239variable merging and induction variable elimination) on trees.
5240
5241@item -ftree-sra
5242Perform scalar replacement of aggregates. This pass replaces structure
5243references with scalars to prevent committing structures to memory too
5244early. This flag is enabled by default at @option{-O} and higher.
5245
5246@item -ftree-copyrename
5247Perform copy renaming on trees. This pass attempts to rename compiler
5248temporaries to other variables at copy locations, usually resulting in
5249variable names which more closely resemble the original variables. This flag
5250is enabled by default at @option{-O} and higher.
5251
5252@item -ftree-ter
5253Perform temporary expression replacement during the SSA->normal phase. Single
5254use/single def temporaries are replaced at their use location with their
5255defining expression. This results in non-GIMPLE code, but gives the expanders
5256much more complex trees to work on resulting in better RTL generation. This is
5257enabled by default at @option{-O} and higher.
5258
5259@item -ftree-lrs
5260Perform live range splitting during the SSA->normal phase. Distinct live
5261ranges of a variable are split into unique variables, allowing for better
5262optimization later. This is enabled by default at @option{-O} and higher.
5263
5264@item -ftree-vectorize
5265Perform loop vectorization on trees.
5266
5267@item -ftree-vect-loop-version
5268@opindex ftree-vect-loop-version
5269Perform loop versioning when doing loop vectorization on trees. When a loop
5270appears to be vectorizable except that data alignment or data dependence cannot
5271be determined at compile time then vectorized and non-vectorized versions of
5272the loop are generated along with runtime checks for alignment or dependence
5273to control which version is executed. This option is enabled by default
5274except at level @option{-Os} where it is disabled.
5275
5276@item -ftree-vrp
5277Perform Value Range Propagation on trees. This is similar to the
5278constant propagation pass, but instead of values, ranges of values are
5279propagated. This allows the optimizers to remove unnecessary range
5280checks like array bound checks and null pointer checks. This is
5281enabled by default at @option{-O2} and higher. Null pointer check
5282elimination is only done if @option{-fdelete-null-pointer-checks} is
5283enabled.
5284
5285@item -ftracer
5286@opindex ftracer
5287Perform tail duplication to enlarge superblock size. This transformation
5288simplifies the control flow of the function allowing other optimizations to do
5289better job.
5290
5291@item -funroll-loops
5292@opindex funroll-loops
5293Unroll loops whose number of iterations can be determined at compile
5294time or upon entry to the loop. @option{-funroll-loops} implies
5295@option{-frerun-cse-after-loop}. This option makes code larger,
5296and may or may not make it run faster.
5297
5298@item -funroll-all-loops
5299@opindex funroll-all-loops
5300Unroll all loops, even if their number of iterations is uncertain when
5301the loop is entered. This usually makes programs run more slowly.
5302@option{-funroll-all-loops} implies the same options as
5303@option{-funroll-loops},
5304
5305@item -fsplit-ivs-in-unroller
5306@opindex fsplit-ivs-in-unroller
5307Enables expressing of values of induction variables in later iterations
5308of the unrolled loop using the value in the first iteration. This breaks
5309long dependency chains, thus improving efficiency of the scheduling passes.
5310
5311Combination of @option{-fweb} and CSE is often sufficient to obtain the
5312same effect. However in cases the loop body is more complicated than
5313a single basic block, this is not reliable. It also does not work at all
5314on some of the architectures due to restrictions in the CSE pass.
5315
5316This optimization is enabled by default.
5317
5318@item -fvariable-expansion-in-unroller
5319@opindex fvariable-expansion-in-unroller
5320With this option, the compiler will create multiple copies of some
5321local variables when unrolling a loop which can result in superior code.
5322
5323@item -fprefetch-loop-arrays
5324@opindex fprefetch-loop-arrays
5325If supported by the target machine, generate instructions to prefetch
5326memory to improve the performance of loops that access large arrays.
5327
5328This option may generate better or worse code; results are highly
5329dependent on the structure of loops within the source code.
5330
5331Disabled at level @option{-Os}.
5332
5333@item -fno-peephole
5334@itemx -fno-peephole2
5335@opindex fno-peephole
5336@opindex fno-peephole2
5337Disable any machine-specific peephole optimizations. The difference
5338between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
5339are implemented in the compiler; some targets use one, some use the
5340other, a few use both.
5341
5342@option{-fpeephole} is enabled by default.
5343@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5344
5345@item -fno-guess-branch-probability
5346@opindex fno-guess-branch-probability
5347Do not guess branch probabilities using heuristics.
5348
5349GCC will use heuristics to guess branch probabilities if they are
5350not provided by profiling feedback (@option{-fprofile-arcs}). These
5351heuristics are based on the control flow graph. If some branch probabilities
5352are specified by @samp{__builtin_expect}, then the heuristics will be
5353used to guess branch probabilities for the rest of the control flow graph,
5354taking the @samp{__builtin_expect} info into account. The interactions
5355between the heuristics and @samp{__builtin_expect} can be complex, and in
5356some cases, it may be useful to disable the heuristics so that the effects
5357of @samp{__builtin_expect} are easier to understand.
5358
5359The default is @option{-fguess-branch-probability} at levels
5360@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5361
5362@item -freorder-blocks
5363@opindex freorder-blocks
5364Reorder basic blocks in the compiled function in order to reduce number of
5365taken branches and improve code locality.
5366
5367Enabled at levels @option{-O2}, @option{-O3}.
5368
5369@item -freorder-blocks-and-partition
5370@opindex freorder-blocks-and-partition
5371In addition to reordering basic blocks in the compiled function, in order
5372to reduce number of taken branches, partitions hot and cold basic blocks
5373into separate sections of the assembly and .o files, to improve
5374paging and cache locality performance.
5375
5376This optimization is automatically turned off in the presence of
5377exception handling, for linkonce sections, for functions with a user-defined
5378section attribute and on any architecture that does not support named
5379sections.
5380
5381@item -freorder-functions
5382@opindex freorder-functions
5383Reorder functions in the object file in order to
5384improve code locality. This is implemented by using special
5385subsections @code{.text.hot} for most frequently executed functions and
5386@code{.text.unlikely} for unlikely executed functions. Reordering is done by
5387the linker so object file format must support named sections and linker must
5388place them in a reasonable way.
5389
5390Also profile feedback must be available in to make this option effective. See
5391@option{-fprofile-arcs} for details.
5392
5393Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5394
5395@item -fstrict-aliasing
5396@opindex fstrict-aliasing
5397Allows the compiler to assume the strictest aliasing rules applicable to
5398the language being compiled. For C (and C++), this activates
5399optimizations based on the type of expressions. In particular, an
5400object of one type is assumed never to reside at the same address as an
5401object of a different type, unless the types are almost the same. For
5402example, an @code{unsigned int} can alias an @code{int}, but not a
5403@code{void*} or a @code{double}. A character type may alias any other
5404type.
5405
5406Pay special attention to code like this:
5407@smallexample
5408union a_union @{
5409 int i;
5410 double d;
5411@};
5412
5413int f() @{
5414 a_union t;
5415 t.d = 3.0;
5416 return t.i;
5417@}
5418@end smallexample
5419The practice of reading from a different union member than the one most
5420recently written to (called ``type-punning'') is common. Even with
5421@option{-fstrict-aliasing}, type-punning is allowed, provided the memory
5422is accessed through the union type. So, the code above will work as
5423expected. However, this code might not:
5424@smallexample
5425int f() @{
5426 a_union t;
5427 int* ip;
5428 t.d = 3.0;
5429 ip = &t.i;
5430 return *ip;
5431@}
5432@end smallexample
5433
5434Every language that wishes to perform language-specific alias analysis
5435should define a function that computes, given an @code{tree}
5436node, an alias set for the node. Nodes in different alias sets are not
5437allowed to alias. For an example, see the C front-end function
5438@code{c_get_alias_set}.
5439
5440Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5441
5442@item -fstrict-overflow
5443@opindex fstrict-overflow
5444Allow the compiler to assume strict signed overflow rules, depending
5445on the language being compiled. For C (and C++) this means that
5446overflow when doing arithmetic with signed numbers is undefined, which
5447means that the compiler may assume that it will not happen. This
5448permits various optimizations. For example, the compiler will assume
5449that an expression like @code{i + 10 > i} will always be true for
5450signed @code{i}. This assumption is only valid if signed overflow is
5451undefined, as the expression is false if @code{i + 10} overflows when
5452using twos complement arithmetic. When this option is in effect any
5453attempt to determine whether an operation on signed numbers will
5454overflow must be written carefully to not actually involve overflow.
5455
5456See also the @option{-fwrapv} option. Using @option{-fwrapv} means
5457that signed overflow is fully defined: it wraps. When
5458@option{-fwrapv} is used, there is no difference between
5459@option{-fstrict-overflow} and @option{-fno-strict-overflow}. With
5460@option{-fwrapv} certain types of overflow are permitted. For
5461example, if the compiler gets an overflow when doing arithmetic on
5462constants, the overflowed value can still be used with
5463@option{-fwrapv}, but not otherwise.
5464
5465The @option{-fstrict-overflow} option is enabled at levels
5466@option{-O2}, @option{-O3}, @option{-Os}.
5467
5468@item -falign-functions
5469@itemx -falign-functions=@var{n}
5470@opindex falign-functions
5471Align the start of functions to the next power-of-two greater than
5472@var{n}, skipping up to @var{n} bytes. For instance,
5473@option{-falign-functions=32} aligns functions to the next 32-byte
5474boundary, but @option{-falign-functions=24} would align to the next
547532-byte boundary only if this can be done by skipping 23 bytes or less.
5476
5477@option{-fno-align-functions} and @option{-falign-functions=1} are
5478equivalent and mean that functions will not be aligned.
5479
5480Some assemblers only support this flag when @var{n} is a power of two;
5481in that case, it is rounded up.
5482
5483If @var{n} is not specified or is zero, use a machine-dependent default.
5484
5485Enabled at levels @option{-O2}, @option{-O3}.
5486
5487@item -falign-labels
5488@itemx -falign-labels=@var{n}
5489@opindex falign-labels
5490Align all branch targets to a power-of-two boundary, skipping up to
5491@var{n} bytes like @option{-falign-functions}. This option can easily
5492make code slower, because it must insert dummy operations for when the
5493branch target is reached in the usual flow of the code.
5494
5495@option{-fno-align-labels} and @option{-falign-labels=1} are
5496equivalent and mean that labels will not be aligned.
5497
5498If @option{-falign-loops} or @option{-falign-jumps} are applicable and
5499are greater than this value, then their values are used instead.
5500
5501If @var{n} is not specified or is zero, use a machine-dependent default
5502which is very likely to be @samp{1}, meaning no alignment.
5503
5504Enabled at levels @option{-O2}, @option{-O3}.
5505
5506@item -falign-loops
5507@itemx -falign-loops=@var{n}
5508@opindex falign-loops
5509Align loops to a power-of-two boundary, skipping up to @var{n} bytes
5510like @option{-falign-functions}. The hope is that the loop will be
5511executed many times, which will make up for any execution of the dummy
5512operations.
5513
5514@option{-fno-align-loops} and @option{-falign-loops=1} are
5515equivalent and mean that loops will not be aligned.
5516
5517If @var{n} is not specified or is zero, use a machine-dependent default.
5518
5519Enabled at levels @option{-O2}, @option{-O3}.
5520
5521@item -falign-jumps
5522@itemx -falign-jumps=@var{n}
5523@opindex falign-jumps
5524Align branch targets to a power-of-two boundary, for branch targets
5525where the targets can only be reached by jumping, skipping up to @var{n}
5526bytes like @option{-falign-functions}. In this case, no dummy operations
5527need be executed.
5528
5529@option{-fno-align-jumps} and @option{-falign-jumps=1} are
5530equivalent and mean that loops will not be aligned.
5531
5532If @var{n} is not specified or is zero, use a machine-dependent default.
5533
5534Enabled at levels @option{-O2}, @option{-O3}.
5535
5536@item -funit-at-a-time
5537@opindex funit-at-a-time
5538Parse the whole compilation unit before starting to produce code.
5539This allows some extra optimizations to take place but consumes
5540more memory (in general). There are some compatibility issues
5541with @emph{unit-at-a-time} mode:
5542@itemize @bullet
5543@item
5544enabling @emph{unit-at-a-time} mode may change the order
5545in which functions, variables, and top-level @code{asm} statements
5546are emitted, and will likely break code relying on some particular
5547ordering. The majority of such top-level @code{asm} statements,
5548though, can be replaced by @code{section} attributes. The
5549@option{fno-toplevel-reorder} option may be used to keep the ordering
5550used in the input file, at the cost of some optimizations.
5551
5552@item
5553@emph{unit-at-a-time} mode removes unreferenced static variables
5554and functions. This may result in undefined references
5555when an @code{asm} statement refers directly to variables or functions
5556that are otherwise unused. In that case either the variable/function
5557shall be listed as an operand of the @code{asm} statement operand or,
5558in the case of top-level @code{asm} statements the attribute @code{used}
5559shall be used on the declaration.
5560
5561@item
5562Static functions now can use non-standard passing conventions that
5563may break @code{asm} statements calling functions directly. Again,
5564attribute @code{used} will prevent this behavior.
5565@end itemize
5566
5567As a temporary workaround, @option{-fno-unit-at-a-time} can be used,
5568but this scheme may not be supported by future releases of GCC@.
5569
5570Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5571
5572@item -fno-toplevel-reorder
5573Do not reorder top-level functions, variables, and @code{asm}
5574statements. Output them in the same order that they appear in the
5575input file. When this option is used, unreferenced static variables
5576will not be removed. This option is intended to support existing code
5577which relies on a particular ordering. For new code, it is better to
5578use attributes.
5579
5580@item -fweb
5581@opindex fweb
5582Constructs webs as commonly used for register allocation purposes and assign
5583each web individual pseudo register. This allows the register allocation pass
5584to operate on pseudos directly, but also strengthens several other optimization
5585passes, such as CSE, loop optimizer and trivial dead code remover. It can,
5586however, make debugging impossible, since variables will no longer stay in a
5587``home register''.
5588
5589Enabled by default with @option{-funroll-loops}.
5590
5591@item -fwhole-program
5592@opindex fwhole-program
5593Assume that the current compilation unit represents whole program being
5594compiled. All public functions and variables with the exception of @code{main}
5595and those merged by attribute @code{externally_visible} become static functions
5596and in a affect gets more aggressively optimized by interprocedural optimizers.
5597While this option is equivalent to proper use of @code{static} keyword for
5598programs consisting of single file, in combination with option
5599@option{--combine} this flag can be used to compile most of smaller scale C
5600programs since the functions and variables become local for the whole combined
5601compilation unit, not for the single source file itself.
5602
5603
5604@item -fno-cprop-registers
5605@opindex fno-cprop-registers
5606After register allocation and post-register allocation instruction splitting,
5607we perform a copy-propagation pass to try to reduce scheduling dependencies
5608and occasionally eliminate the copy.
5609
5610Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5611
5612@item -fprofile-generate
5613@opindex fprofile-generate
5614
5615Enable options usually used for instrumenting application to produce
5616profile useful for later recompilation with profile feedback based
5617optimization. You must use @option{-fprofile-generate} both when
5618compiling and when linking your program.
5619
5620The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
5621
5622@item -fprofile-use
5623@opindex fprofile-use
5624Enable profile feedback directed optimizations, and optimizations
5625generally profitable only with profile feedback available.
5626
5627The following options are enabled: @code{-fbranch-probabilities}, @code{-fvpt},
5628@code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}
5629
5630@end table
5631
5632The following options control compiler behavior regarding floating
5633point arithmetic. These options trade off between speed and
5634correctness. All must be specifically enabled.
5635
5636@table @gcctabopt
5637@item -ffloat-store
5638@opindex ffloat-store
5639Do not store floating point variables in registers, and inhibit other
5640options that might change whether a floating point value is taken from a
5641register or memory.
5642
5643@cindex floating point precision
5644This option prevents undesirable excess precision on machines such as
5645the 68000 where the floating registers (of the 68881) keep more
5646precision than a @code{double} is supposed to have. Similarly for the
5647x86 architecture. For most programs, the excess precision does only
5648good, but a few programs rely on the precise definition of IEEE floating
5649point. Use @option{-ffloat-store} for such programs, after modifying
5650them to store all pertinent intermediate computations into variables.
5651
5652@item -ffast-math
5653@opindex ffast-math
5654Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
5655@option{-fno-trapping-math}, @option{-ffinite-math-only},
5656@option{-fno-rounding-math}, @option{-fno-signaling-nans}
5657and @option{fcx-limited-range}.
5658
5659This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
5660
5661This option should never be turned on by any @option{-O} option since
5662it can result in incorrect output for programs which depend on
5663an exact implementation of IEEE or ISO rules/specifications for
5664math functions.
5665
5666@item -fno-math-errno
5667@opindex fno-math-errno
5668Do not set ERRNO after calling math functions that are executed
5669with a single instruction, e.g., sqrt. A program that relies on
5670IEEE exceptions for math error handling may want to use this flag
5671for speed while maintaining IEEE arithmetic compatibility.
5672
5673This option should never be turned on by any @option{-O} option since
5674it can result in incorrect output for programs which depend on
5675an exact implementation of IEEE or ISO rules/specifications for
5676math functions.
5677
5678The default is @option{-fmath-errno}.
5679
|
5680On Darwin systems, the math library never sets @code{errno}. There is therefore
| 5680On Darwin and FreeBSD systems, the math library never sets @code{errno}.
5681There is therefore
|
5681no reason for the compiler to consider the possibility that it might,
5682and @option{-fno-math-errno} is the default.
5683
5684@item -funsafe-math-optimizations
5685@opindex funsafe-math-optimizations
5686Allow optimizations for floating-point arithmetic that (a) assume
5687that arguments and results are valid and (b) may violate IEEE or
5688ANSI standards. When used at link-time, it may include libraries
5689or startup files that change the default FPU control word or other
5690similar optimizations.
5691
5692This option should never be turned on by any @option{-O} option since
5693it can result in incorrect output for programs which depend on
5694an exact implementation of IEEE or ISO rules/specifications for
5695math functions.
5696
5697The default is @option{-fno-unsafe-math-optimizations}.
5698
5699@item -ffinite-math-only
5700@opindex ffinite-math-only
5701Allow optimizations for floating-point arithmetic that assume
5702that arguments and results are not NaNs or +-Infs.
5703
5704This option should never be turned on by any @option{-O} option since
5705it can result in incorrect output for programs which depend on
5706an exact implementation of IEEE or ISO rules/specifications.
5707
5708The default is @option{-fno-finite-math-only}.
5709
5710@item -fno-trapping-math
5711@opindex fno-trapping-math
5712Compile code assuming that floating-point operations cannot generate
5713user-visible traps. These traps include division by zero, overflow,
5714underflow, inexact result and invalid operation. This option implies
5715@option{-fno-signaling-nans}. Setting this option may allow faster
5716code if one relies on ``non-stop'' IEEE arithmetic, for example.
5717
5718This option should never be turned on by any @option{-O} option since
5719it can result in incorrect output for programs which depend on
5720an exact implementation of IEEE or ISO rules/specifications for
5721math functions.
5722
5723The default is @option{-ftrapping-math}.
5724
5725@item -frounding-math
5726@opindex frounding-math
5727Disable transformations and optimizations that assume default floating
5728point rounding behavior. This is round-to-zero for all floating point
5729to integer conversions, and round-to-nearest for all other arithmetic
5730truncations. This option should be specified for programs that change
5731the FP rounding mode dynamically, or that may be executed with a
5732non-default rounding mode. This option disables constant folding of
5733floating point expressions at compile-time (which may be affected by
5734rounding mode) and arithmetic transformations that are unsafe in the
5735presence of sign-dependent rounding modes.
5736
5737The default is @option{-fno-rounding-math}.
5738
5739This option is experimental and does not currently guarantee to
5740disable all GCC optimizations that are affected by rounding mode.
5741Future versions of GCC may provide finer control of this setting
5742using C99's @code{FENV_ACCESS} pragma. This command line option
5743will be used to specify the default state for @code{FENV_ACCESS}.
5744
5745@item -frtl-abstract-sequences
5746@opindex frtl-abstract-sequences
5747It is a size optimization method. This option is to find identical
5748sequences of code, which can be turned into pseudo-procedures and
5749then replace all occurrences with calls to the newly created
5750subroutine. It is kind of an opposite of @option{-finline-functions}.
5751This optimization runs at RTL level.
5752
5753@item -fsignaling-nans
5754@opindex fsignaling-nans
5755Compile code assuming that IEEE signaling NaNs may generate user-visible
5756traps during floating-point operations. Setting this option disables
5757optimizations that may change the number of exceptions visible with
5758signaling NaNs. This option implies @option{-ftrapping-math}.
5759
5760This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
5761be defined.
5762
5763The default is @option{-fno-signaling-nans}.
5764
5765This option is experimental and does not currently guarantee to
5766disable all GCC optimizations that affect signaling NaN behavior.
5767
5768@item -fsingle-precision-constant
5769@opindex fsingle-precision-constant
5770Treat floating point constant as single precision constant instead of
5771implicitly converting it to double precision constant.
5772
5773@item -fcx-limited-range
5774@itemx -fno-cx-limited-range
5775@opindex fcx-limited-range
5776@opindex fno-cx-limited-range
5777When enabled, this option states that a range reduction step is not
5778needed when performing complex division. The default is
5779@option{-fno-cx-limited-range}, but is enabled by @option{-ffast-math}.
5780
5781This option controls the default setting of the ISO C99
5782@code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to
5783all languages.
5784
5785@end table
5786
5787The following options control optimizations that may improve
5788performance, but are not enabled by any @option{-O} options. This
5789section includes experimental options that may produce broken code.
5790
5791@table @gcctabopt
5792@item -fbranch-probabilities
5793@opindex fbranch-probabilities
5794After running a program compiled with @option{-fprofile-arcs}
5795(@pxref{Debugging Options,, Options for Debugging Your Program or
5796@command{gcc}}), you can compile it a second time using
5797@option{-fbranch-probabilities}, to improve optimizations based on
5798the number of times each branch was taken. When the program
5799compiled with @option{-fprofile-arcs} exits it saves arc execution
5800counts to a file called @file{@var{sourcename}.gcda} for each source
5801file The information in this data file is very dependent on the
5802structure of the generated code, so you must use the same source code
5803and the same optimization options for both compilations.
5804
5805With @option{-fbranch-probabilities}, GCC puts a
5806@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
5807These can be used to improve optimization. Currently, they are only
5808used in one place: in @file{reorg.c}, instead of guessing which path a
5809branch is mostly to take, the @samp{REG_BR_PROB} values are used to
5810exactly determine which path is taken more often.
5811
5812@item -fprofile-values
5813@opindex fprofile-values
5814If combined with @option{-fprofile-arcs}, it adds code so that some
5815data about values of expressions in the program is gathered.
5816
5817With @option{-fbranch-probabilities}, it reads back the data gathered
5818from profiling values of expressions and adds @samp{REG_VALUE_PROFILE}
5819notes to instructions for their later usage in optimizations.
5820
5821Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
5822
5823@item -fvpt
5824@opindex fvpt
5825If combined with @option{-fprofile-arcs}, it instructs the compiler to add
5826a code to gather information about values of expressions.
5827
5828With @option{-fbranch-probabilities}, it reads back the data gathered
5829and actually performs the optimizations based on them.
5830Currently the optimizations include specialization of division operation
5831using the knowledge about the value of the denominator.
5832
5833@item -frename-registers
5834@opindex frename-registers
5835Attempt to avoid false dependencies in scheduled code by making use
5836of registers left over after register allocation. This optimization
5837will most benefit processors with lots of registers. Depending on the
5838debug information format adopted by the target, however, it can
5839make debugging impossible, since variables will no longer stay in
5840a ``home register''.
5841
5842Enabled by default with @option{-funroll-loops}.
5843
5844@item -ftracer
5845@opindex ftracer
5846Perform tail duplication to enlarge superblock size. This transformation
5847simplifies the control flow of the function allowing other optimizations to do
5848better job.
5849
5850Enabled with @option{-fprofile-use}.
5851
5852@item -funroll-loops
5853@opindex funroll-loops
5854Unroll loops whose number of iterations can be determined at compile time or
5855upon entry to the loop. @option{-funroll-loops} implies
5856@option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.
5857It also turns on complete loop peeling (i.e.@: complete removal of loops with
5858small constant number of iterations). This option makes code larger, and may
5859or may not make it run faster.
5860
5861Enabled with @option{-fprofile-use}.
5862
5863@item -funroll-all-loops
5864@opindex funroll-all-loops
5865Unroll all loops, even if their number of iterations is uncertain when
5866the loop is entered. This usually makes programs run more slowly.
5867@option{-funroll-all-loops} implies the same options as
5868@option{-funroll-loops}.
5869
5870@item -fpeel-loops
5871@opindex fpeel-loops
5872Peels the loops for that there is enough information that they do not
5873roll much (from profile feedback). It also turns on complete loop peeling
5874(i.e.@: complete removal of loops with small constant number of iterations).
5875
5876Enabled with @option{-fprofile-use}.
5877
5878@item -fmove-loop-invariants
5879@opindex fmove-loop-invariants
5880Enables the loop invariant motion pass in the RTL loop optimizer. Enabled
5881at level @option{-O1}
5882
5883@item -funswitch-loops
5884@opindex funswitch-loops
5885Move branches with loop invariant conditions out of the loop, with duplicates
5886of the loop on both branches (modified according to result of the condition).
5887
5888@item -ffunction-sections
5889@itemx -fdata-sections
5890@opindex ffunction-sections
5891@opindex fdata-sections
5892Place each function or data item into its own section in the output
5893file if the target supports arbitrary sections. The name of the
5894function or the name of the data item determines the section's name
5895in the output file.
5896
5897Use these options on systems where the linker can perform optimizations
5898to improve locality of reference in the instruction space. Most systems
5899using the ELF object format and SPARC processors running Solaris 2 have
5900linkers with such optimizations. AIX may have these optimizations in
5901the future.
5902
5903Only use these options when there are significant benefits from doing
5904so. When you specify these options, the assembler and linker will
5905create larger object and executable files and will also be slower.
5906You will not be able to use @code{gprof} on all systems if you
5907specify this option and you may have problems with debugging if
5908you specify both this option and @option{-g}.
5909
5910@item -fbranch-target-load-optimize
5911@opindex fbranch-target-load-optimize
5912Perform branch target register load optimization before prologue / epilogue
5913threading.
5914The use of target registers can typically be exposed only during reload,
5915thus hoisting loads out of loops and doing inter-block scheduling needs
5916a separate optimization pass.
5917
5918@item -fbranch-target-load-optimize2
5919@opindex fbranch-target-load-optimize2
5920Perform branch target register load optimization after prologue / epilogue
5921threading.
5922
5923@item -fbtr-bb-exclusive
5924@opindex fbtr-bb-exclusive
5925When performing branch target register load optimization, don't reuse
5926branch target registers in within any basic block.
5927
5928@item -fstack-protector
5929Emit extra code to check for buffer overflows, such as stack smashing
5930attacks. This is done by adding a guard variable to functions with
5931vulnerable objects. This includes functions that call alloca, and
5932functions with buffers larger than 8 bytes. The guards are initialized
5933when a function is entered and then checked when the function exits.
5934If a guard check fails, an error message is printed and the program exits.
5935
5936@item -fstack-protector-all
5937Like @option{-fstack-protector} except that all functions are protected.
5938
5939@item -fsection-anchors
5940@opindex fsection-anchors
5941Try to reduce the number of symbolic address calculations by using
5942shared ``anchor'' symbols to address nearby objects. This transformation
5943can help to reduce the number of GOT entries and GOT accesses on some
5944targets.
5945
5946For example, the implementation of the following function @code{foo}:
5947
5948@smallexample
5949static int a, b, c;
5950int foo (void) @{ return a + b + c; @}
5951@end smallexample
5952
5953would usually calculate the addresses of all three variables, but if you
5954compile it with @option{-fsection-anchors}, it will access the variables
5955from a common anchor point instead. The effect is similar to the
5956following pseudocode (which isn't valid C):
5957
5958@smallexample
5959int foo (void)
5960@{
5961 register int *xr = &x;
5962 return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
5963@}
5964@end smallexample
5965
5966Not all targets support this option.
5967
5968@item --param @var{name}=@var{value}
5969@opindex param
5970In some places, GCC uses various constants to control the amount of
5971optimization that is done. For example, GCC will not inline functions
5972that contain more that a certain number of instructions. You can
5973control some of these constants on the command-line using the
5974@option{--param} option.
5975
5976The names of specific parameters, and the meaning of the values, are
5977tied to the internals of the compiler, and are subject to change
5978without notice in future releases.
5979
5980In each case, the @var{value} is an integer. The allowable choices for
5981@var{name} are given in the following table:
5982
5983@table @gcctabopt
5984@item salias-max-implicit-fields
5985The maximum number of fields in a variable without direct
5986structure accesses for which structure aliasing will consider trying
5987to track each field. The default is 5
5988
5989@item salias-max-array-elements
5990The maximum number of elements an array can have and its elements
5991still be tracked individually by structure aliasing. The default is 4
5992
5993@item sra-max-structure-size
5994The maximum structure size, in bytes, at which the scalar replacement
5995of aggregates (SRA) optimization will perform block copies. The
5996default value, 0, implies that GCC will select the most appropriate
5997size itself.
5998
5999@item sra-field-structure-ratio
6000The threshold ratio (as a percentage) between instantiated fields and
6001the complete structure size. We say that if the ratio of the number
6002of bytes in instantiated fields to the number of bytes in the complete
6003structure exceeds this parameter, then block copies are not used. The
6004default is 75.
6005
6006@item max-crossjump-edges
6007The maximum number of incoming edges to consider for crossjumping.
6008The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
6009the number of edges incoming to each block. Increasing values mean
6010more aggressive optimization, making the compile time increase with
6011probably small improvement in executable size.
6012
6013@item min-crossjump-insns
6014The minimum number of instructions which must be matched at the end
6015of two blocks before crossjumping will be performed on them. This
6016value is ignored in the case where all instructions in the block being
6017crossjumped from are matched. The default value is 5.
6018
6019@item max-grow-copy-bb-insns
6020The maximum code size expansion factor when copying basic blocks
6021instead of jumping. The expansion is relative to a jump instruction.
6022The default value is 8.
6023
6024@item max-goto-duplication-insns
6025The maximum number of instructions to duplicate to a block that jumps
6026to a computed goto. To avoid @math{O(N^2)} behavior in a number of
6027passes, GCC factors computed gotos early in the compilation process,
6028and unfactors them as late as possible. Only computed jumps at the
6029end of a basic blocks with no more than max-goto-duplication-insns are
6030unfactored. The default value is 8.
6031
6032@item max-delay-slot-insn-search
6033The maximum number of instructions to consider when looking for an
6034instruction to fill a delay slot. If more than this arbitrary number of
6035instructions is searched, the time savings from filling the delay slot
6036will be minimal so stop searching. Increasing values mean more
6037aggressive optimization, making the compile time increase with probably
6038small improvement in executable run time.
6039
6040@item max-delay-slot-live-search
6041When trying to fill delay slots, the maximum number of instructions to
6042consider when searching for a block with valid live register
6043information. Increasing this arbitrarily chosen value means more
6044aggressive optimization, increasing the compile time. This parameter
6045should be removed when the delay slot code is rewritten to maintain the
6046control-flow graph.
6047
6048@item max-gcse-memory
6049The approximate maximum amount of memory that will be allocated in
6050order to perform the global common subexpression elimination
6051optimization. If more memory than specified is required, the
6052optimization will not be done.
6053
6054@item max-gcse-passes
6055The maximum number of passes of GCSE to run. The default is 1.
6056
6057@item max-pending-list-length
6058The maximum number of pending dependencies scheduling will allow
6059before flushing the current state and starting over. Large functions
6060with few branches or calls can create excessively large lists which
6061needlessly consume memory and resources.
6062
6063@item max-inline-insns-single
6064Several parameters control the tree inliner used in gcc.
6065This number sets the maximum number of instructions (counted in GCC's
6066internal representation) in a single function that the tree inliner
6067will consider for inlining. This only affects functions declared
6068inline and methods implemented in a class declaration (C++).
6069The default value is 450.
6070
6071@item max-inline-insns-auto
6072When you use @option{-finline-functions} (included in @option{-O3}),
6073a lot of functions that would otherwise not be considered for inlining
6074by the compiler will be investigated. To those functions, a different
6075(more restrictive) limit compared to functions declared inline can
6076be applied.
6077The default value is 90.
6078
6079@item large-function-insns
6080The limit specifying really large functions. For functions larger than this
6081limit after inlining inlining is constrained by
6082@option{--param large-function-growth}. This parameter is useful primarily
6083to avoid extreme compilation time caused by non-linear algorithms used by the
6084backend.
6085This parameter is ignored when @option{-funit-at-a-time} is not used.
6086The default value is 2700.
6087
6088@item large-function-growth
6089Specifies maximal growth of large function caused by inlining in percents.
6090This parameter is ignored when @option{-funit-at-a-time} is not used.
6091The default value is 100 which limits large function growth to 2.0 times
6092the original size.
6093
6094@item large-unit-insns
6095The limit specifying large translation unit. Growth caused by inlining of
6096units larger than this limit is limited by @option{--param inline-unit-growth}.
6097For small units this might be too tight (consider unit consisting of function A
6098that is inline and B that just calls A three time. If B is small relative to
6099A, the growth of unit is 300\% and yet such inlining is very sane. For very
6100large units consisting of small inlininable functions however the overall unit
6101growth limit is needed to avoid exponential explosion of code size. Thus for
6102smaller units, the size is increased to @option{--param large-unit-insns}
6103before applying @option{--param inline-unit-growth}. The default is 10000
6104
6105@item inline-unit-growth
6106Specifies maximal overall growth of the compilation unit caused by inlining.
6107This parameter is ignored when @option{-funit-at-a-time} is not used.
6108The default value is 50 which limits unit growth to 1.5 times the original
6109size.
6110
6111@item max-inline-insns-recursive
6112@itemx max-inline-insns-recursive-auto
6113Specifies maximum number of instructions out-of-line copy of self recursive inline
6114function can grow into by performing recursive inlining.
6115
6116For functions declared inline @option{--param max-inline-insns-recursive} is
6117taken into account. For function not declared inline, recursive inlining
6118happens only when @option{-finline-functions} (included in @option{-O3}) is
6119enabled and @option{--param max-inline-insns-recursive-auto} is used. The
6120default value is 450.
6121
6122@item max-inline-recursive-depth
6123@itemx max-inline-recursive-depth-auto
6124Specifies maximum recursion depth used by the recursive inlining.
6125
6126For functions declared inline @option{--param max-inline-recursive-depth} is
6127taken into account. For function not declared inline, recursive inlining
6128happens only when @option{-finline-functions} (included in @option{-O3}) is
6129enabled and @option{--param max-inline-recursive-depth-auto} is used. The
6130default value is 450.
6131
6132@item min-inline-recursive-probability
6133Recursive inlining is profitable only for function having deep recursion
6134in average and can hurt for function having little recursion depth by
6135increasing the prologue size or complexity of function body to other
6136optimizers.
6137
6138When profile feedback is available (see @option{-fprofile-generate}) the actual
6139recursion depth can be guessed from probability that function will recurse via
6140given call expression. This parameter limits inlining only to call expression
6141whose probability exceeds given threshold (in percents). The default value is
614210.
6143
6144@item inline-call-cost
6145Specify cost of call instruction relative to simple arithmetics operations
6146(having cost of 1). Increasing this cost disqualifies inlining of non-leaf
6147functions and at the same time increases size of leaf function that is believed to
6148reduce function size by being inlined. In effect it increases amount of
6149inlining for code having large abstraction penalty (many functions that just
6150pass the arguments to other functions) and decrease inlining for code with low
6151abstraction penalty. The default value is 16.
6152
6153@item max-unrolled-insns
6154The maximum number of instructions that a loop should have if that loop
6155is unrolled, and if the loop is unrolled, it determines how many times
6156the loop code is unrolled.
6157
6158@item max-average-unrolled-insns
6159The maximum number of instructions biased by probabilities of their execution
6160that a loop should have if that loop is unrolled, and if the loop is unrolled,
6161it determines how many times the loop code is unrolled.
6162
6163@item max-unroll-times
6164The maximum number of unrollings of a single loop.
6165
6166@item max-peeled-insns
6167The maximum number of instructions that a loop should have if that loop
6168is peeled, and if the loop is peeled, it determines how many times
6169the loop code is peeled.
6170
6171@item max-peel-times
6172The maximum number of peelings of a single loop.
6173
6174@item max-completely-peeled-insns
6175The maximum number of insns of a completely peeled loop.
6176
6177@item max-completely-peel-times
6178The maximum number of iterations of a loop to be suitable for complete peeling.
6179
6180@item max-unswitch-insns
6181The maximum number of insns of an unswitched loop.
6182
6183@item max-unswitch-level
6184The maximum number of branches unswitched in a single loop.
6185
6186@item lim-expensive
6187The minimum cost of an expensive expression in the loop invariant motion.
6188
6189@item iv-consider-all-candidates-bound
6190Bound on number of candidates for induction variables below that
6191all candidates are considered for each use in induction variable
6192optimizations. Only the most relevant candidates are considered
6193if there are more candidates, to avoid quadratic time complexity.
6194
6195@item iv-max-considered-uses
6196The induction variable optimizations give up on loops that contain more
6197induction variable uses.
6198
6199@item iv-always-prune-cand-set-bound
6200If number of candidates in the set is smaller than this value,
6201we always try to remove unnecessary ivs from the set during its
6202optimization when a new iv is added to the set.
6203
6204@item scev-max-expr-size
6205Bound on size of expressions used in the scalar evolutions analyzer.
6206Large expressions slow the analyzer.
6207
6208@item vect-max-version-checks
6209The maximum number of runtime checks that can be performed when doing
6210loop versioning in the vectorizer. See option ftree-vect-loop-version
6211for more information.
6212
6213@item max-iterations-to-track
6214
6215The maximum number of iterations of a loop the brute force algorithm
6216for analysis of # of iterations of the loop tries to evaluate.
6217
6218@item hot-bb-count-fraction
6219Select fraction of the maximal count of repetitions of basic block in program
6220given basic block needs to have to be considered hot.
6221
6222@item hot-bb-frequency-fraction
6223Select fraction of the maximal frequency of executions of basic block in
6224function given basic block needs to have to be considered hot
6225
6226@item max-predicted-iterations
6227The maximum number of loop iterations we predict statically. This is useful
6228in cases where function contain single loop with known bound and other loop
6229with unknown. We predict the known number of iterations correctly, while
6230the unknown number of iterations average to roughly 10. This means that the
6231loop without bounds would appear artificially cold relative to the other one.
6232
6233@item tracer-dynamic-coverage
6234@itemx tracer-dynamic-coverage-feedback
6235
6236This value is used to limit superblock formation once the given percentage of
6237executed instructions is covered. This limits unnecessary code size
6238expansion.
6239
6240The @option{tracer-dynamic-coverage-feedback} is used only when profile
6241feedback is available. The real profiles (as opposed to statically estimated
6242ones) are much less balanced allowing the threshold to be larger value.
6243
6244@item tracer-max-code-growth
6245Stop tail duplication once code growth has reached given percentage. This is
6246rather hokey argument, as most of the duplicates will be eliminated later in
6247cross jumping, so it may be set to much higher values than is the desired code
6248growth.
6249
6250@item tracer-min-branch-ratio
6251
6252Stop reverse growth when the reverse probability of best edge is less than this
6253threshold (in percent).
6254
6255@item tracer-min-branch-ratio
6256@itemx tracer-min-branch-ratio-feedback
6257
6258Stop forward growth if the best edge do have probability lower than this
6259threshold.
6260
6261Similarly to @option{tracer-dynamic-coverage} two values are present, one for
6262compilation for profile feedback and one for compilation without. The value
6263for compilation with profile feedback needs to be more conservative (higher) in
6264order to make tracer effective.
6265
6266@item max-cse-path-length
6267
6268Maximum number of basic blocks on path that cse considers. The default is 10.
6269
6270@item max-cse-insns
6271The maximum instructions CSE process before flushing. The default is 1000.
6272
6273@item global-var-threshold
6274
6275Counts the number of function calls (@var{n}) and the number of
6276call-clobbered variables (@var{v}). If @var{n}x@var{v} is larger than this limit, a
6277single artificial variable will be created to represent all the
6278call-clobbered variables at function call sites. This artificial
6279variable will then be made to alias every call-clobbered variable.
6280(done as @code{int * size_t} on the host machine; beware overflow).
6281
6282@item max-aliased-vops
6283
6284Maximum number of virtual operands allowed to represent aliases
6285before triggering the alias grouping heuristic. Alias grouping
6286reduces compile times and memory consumption needed for aliasing at
6287the expense of precision loss in alias information.
6288
6289@item ggc-min-expand
6290
6291GCC uses a garbage collector to manage its own memory allocation. This
6292parameter specifies the minimum percentage by which the garbage
6293collector's heap should be allowed to expand between collections.
6294Tuning this may improve compilation speed; it has no effect on code
6295generation.
6296
6297The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
6298RAM >= 1GB@. If @code{getrlimit} is available, the notion of "RAM" is
6299the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If
6300GCC is not able to calculate RAM on a particular platform, the lower
6301bound of 30% is used. Setting this parameter and
6302@option{ggc-min-heapsize} to zero causes a full collection to occur at
6303every opportunity. This is extremely slow, but can be useful for
6304debugging.
6305
6306@item ggc-min-heapsize
6307
6308Minimum size of the garbage collector's heap before it begins bothering
6309to collect garbage. The first collection occurs after the heap expands
6310by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again,
6311tuning this may improve compilation speed, and has no effect on code
6312generation.
6313
6314The default is the smaller of RAM/8, RLIMIT_RSS, or a limit which
6315tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
6316with a lower bound of 4096 (four megabytes) and an upper bound of
6317131072 (128 megabytes). If GCC is not able to calculate RAM on a
6318particular platform, the lower bound is used. Setting this parameter
6319very large effectively disables garbage collection. Setting this
6320parameter and @option{ggc-min-expand} to zero causes a full collection
6321to occur at every opportunity.
6322
6323@item max-reload-search-insns
6324The maximum number of instruction reload should look backward for equivalent
6325register. Increasing values mean more aggressive optimization, making the
6326compile time increase with probably slightly better performance. The default
6327value is 100.
6328
6329@item max-cselib-memory-locations
6330The maximum number of memory locations cselib should take into account.
6331Increasing values mean more aggressive optimization, making the compile time
6332increase with probably slightly better performance. The default value is 500.
6333
6334@item max-flow-memory-locations
6335Similar as @option{max-cselib-memory-locations} but for dataflow liveness.
6336The default value is 100.
6337
6338@item reorder-blocks-duplicate
6339@itemx reorder-blocks-duplicate-feedback
6340
6341Used by basic block reordering pass to decide whether to use unconditional
6342branch or duplicate the code on its destination. Code is duplicated when its
6343estimated size is smaller than this value multiplied by the estimated size of
6344unconditional jump in the hot spots of the program.
6345
6346The @option{reorder-block-duplicate-feedback} is used only when profile
6347feedback is available and may be set to higher values than
6348@option{reorder-block-duplicate} since information about the hot spots is more
6349accurate.
6350
6351@item max-sched-ready-insns
6352The maximum number of instructions ready to be issued the scheduler should
6353consider at any given time during the first scheduling pass. Increasing
6354values mean more thorough searches, making the compilation time increase
6355with probably little benefit. The default value is 100.
6356
6357@item max-sched-region-blocks
6358The maximum number of blocks in a region to be considered for
6359interblock scheduling. The default value is 10.
6360
6361@item max-sched-region-insns
6362The maximum number of insns in a region to be considered for
6363interblock scheduling. The default value is 100.
6364
6365@item min-spec-prob
6366The minimum probability (in percents) of reaching a source block
6367for interblock speculative scheduling. The default value is 40.
6368
6369@item max-sched-extend-regions-iters
6370The maximum number of iterations through CFG to extend regions.
63710 - disable region extension,
6372N - do at most N iterations.
6373The default value is 0.
6374
6375@item max-sched-insn-conflict-delay
6376The maximum conflict delay for an insn to be considered for speculative motion.
6377The default value is 3.
6378
6379@item sched-spec-prob-cutoff
6380The minimal probability of speculation success (in percents), so that
6381speculative insn will be scheduled.
6382The default value is 40.
6383
6384@item max-last-value-rtl
6385
6386The maximum size measured as number of RTLs that can be recorded in an expression
6387in combiner for a pseudo register as last known value of that register. The default
6388is 10000.
6389
6390@item integer-share-limit
6391Small integer constants can use a shared data structure, reducing the
6392compiler's memory usage and increasing its speed. This sets the maximum
6393value of a shared integer constant's. The default value is 256.
6394
6395@item min-virtual-mappings
6396Specifies the minimum number of virtual mappings in the incremental
6397SSA updater that should be registered to trigger the virtual mappings
6398heuristic defined by virtual-mappings-ratio. The default value is
6399100.
6400
6401@item virtual-mappings-ratio
6402If the number of virtual mappings is virtual-mappings-ratio bigger
6403than the number of virtual symbols to be updated, then the incremental
6404SSA updater switches to a full update for those symbols. The default
6405ratio is 3.
6406
6407@item ssp-buffer-size
6408The minimum size of buffers (i.e. arrays) that will receive stack smashing
6409protection when @option{-fstack-protection} is used.
6410
6411@item max-jump-thread-duplication-stmts
6412Maximum number of statements allowed in a block that needs to be
6413duplicated when threading jumps.
6414
6415@item max-fields-for-field-sensitive
6416Maximum number of fields in a structure we will treat in
6417a field sensitive manner during pointer analysis.
6418
6419@end table
6420@end table
6421
6422@node Preprocessor Options
6423@section Options Controlling the Preprocessor
6424@cindex preprocessor options
6425@cindex options, preprocessor
6426
6427These options control the C preprocessor, which is run on each C source
6428file before actual compilation.
6429
6430If you use the @option{-E} option, nothing is done except preprocessing.
6431Some of these options make sense only together with @option{-E} because
6432they cause the preprocessor output to be unsuitable for actual
6433compilation.
6434
6435@table @gcctabopt
6436@opindex Wp
6437You can use @option{-Wp,@var{option}} to bypass the compiler driver
6438and pass @var{option} directly through to the preprocessor. If
6439@var{option} contains commas, it is split into multiple options at the
6440commas. However, many options are modified, translated or interpreted
6441by the compiler driver before being passed to the preprocessor, and
6442@option{-Wp} forcibly bypasses this phase. The preprocessor's direct
6443interface is undocumented and subject to change, so whenever possible
6444you should avoid using @option{-Wp} and let the driver handle the
6445options instead.
6446
6447@item -Xpreprocessor @var{option}
6448@opindex preprocessor
6449Pass @var{option} as an option to the preprocessor. You can use this to
6450supply system-specific preprocessor options which GCC does not know how to
6451recognize.
6452
6453If you want to pass an option that takes an argument, you must use
6454@option{-Xpreprocessor} twice, once for the option and once for the argument.
6455@end table
6456
6457@include cppopts.texi
6458
6459@node Assembler Options
6460@section Passing Options to the Assembler
6461
6462@c prevent bad page break with this line
6463You can pass options to the assembler.
6464
6465@table @gcctabopt
6466@item -Wa,@var{option}
6467@opindex Wa
6468Pass @var{option} as an option to the assembler. If @var{option}
6469contains commas, it is split into multiple options at the commas.
6470
6471@item -Xassembler @var{option}
6472@opindex Xassembler
6473Pass @var{option} as an option to the assembler. You can use this to
6474supply system-specific assembler options which GCC does not know how to
6475recognize.
6476
6477If you want to pass an option that takes an argument, you must use
6478@option{-Xassembler} twice, once for the option and once for the argument.
6479
6480@end table
6481
6482@node Link Options
6483@section Options for Linking
6484@cindex link options
6485@cindex options, linking
6486
6487These options come into play when the compiler links object files into
6488an executable output file. They are meaningless if the compiler is
6489not doing a link step.
6490
6491@table @gcctabopt
6492@cindex file names
6493@item @var{object-file-name}
6494A file name that does not end in a special recognized suffix is
6495considered to name an object file or library. (Object files are
6496distinguished from libraries by the linker according to the file
6497contents.) If linking is done, these object files are used as input
6498to the linker.
6499
6500@item -c
6501@itemx -S
6502@itemx -E
6503@opindex c
6504@opindex S
6505@opindex E
6506If any of these options is used, then the linker is not run, and
6507object file names should not be used as arguments. @xref{Overall
6508Options}.
6509
6510@cindex Libraries
6511@item -l@var{library}
6512@itemx -l @var{library}
6513@opindex l
6514Search the library named @var{library} when linking. (The second
6515alternative with the library as a separate argument is only for
6516POSIX compliance and is not recommended.)
6517
6518It makes a difference where in the command you write this option; the
6519linker searches and processes libraries and object files in the order they
6520are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
6521after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
6522to functions in @samp{z}, those functions may not be loaded.
6523
6524The linker searches a standard list of directories for the library,
6525which is actually a file named @file{lib@var{library}.a}. The linker
6526then uses this file as if it had been specified precisely by name.
6527
6528The directories searched include several standard system directories
6529plus any that you specify with @option{-L}.
6530
6531Normally the files found this way are library files---archive files
6532whose members are object files. The linker handles an archive file by
6533scanning through it for members which define symbols that have so far
6534been referenced but not defined. But if the file that is found is an
6535ordinary object file, it is linked in the usual fashion. The only
6536difference between using an @option{-l} option and specifying a file name
6537is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
6538and searches several directories.
6539
6540@item -lobjc
6541@opindex lobjc
6542You need this special case of the @option{-l} option in order to
6543link an Objective-C or Objective-C++ program.
6544
6545@item -nostartfiles
6546@opindex nostartfiles
6547Do not use the standard system startup files when linking.
6548The standard system libraries are used normally, unless @option{-nostdlib}
6549or @option{-nodefaultlibs} is used.
6550
6551@item -nodefaultlibs
6552@opindex nodefaultlibs
6553Do not use the standard system libraries when linking.
6554Only the libraries you specify will be passed to the linker.
6555The standard startup files are used normally, unless @option{-nostartfiles}
6556is used. The compiler may generate calls to @code{memcmp},
6557@code{memset}, @code{memcpy} and @code{memmove}.
6558These entries are usually resolved by entries in
6559libc. These entry points should be supplied through some other
6560mechanism when this option is specified.
6561
6562@item -nostdlib
6563@opindex nostdlib
6564Do not use the standard system startup files or libraries when linking.
6565No startup files and only the libraries you specify will be passed to
6566the linker. The compiler may generate calls to @code{memcmp}, @code{memset},
6567@code{memcpy} and @code{memmove}.
6568These entries are usually resolved by entries in
6569libc. These entry points should be supplied through some other
6570mechanism when this option is specified.
6571
6572@cindex @option{-lgcc}, use with @option{-nostdlib}
6573@cindex @option{-nostdlib} and unresolved references
6574@cindex unresolved references and @option{-nostdlib}
6575@cindex @option{-lgcc}, use with @option{-nodefaultlibs}
6576@cindex @option{-nodefaultlibs} and unresolved references
6577@cindex unresolved references and @option{-nodefaultlibs}
6578One of the standard libraries bypassed by @option{-nostdlib} and
6579@option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
6580that GCC uses to overcome shortcomings of particular machines, or special
6581needs for some languages.
6582(@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
6583Collection (GCC) Internals},
6584for more discussion of @file{libgcc.a}.)
6585In most cases, you need @file{libgcc.a} even when you want to avoid
6586other standard libraries. In other words, when you specify @option{-nostdlib}
6587or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
6588This ensures that you have no unresolved references to internal GCC
6589library subroutines. (For example, @samp{__main}, used to ensure C++
6590constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
6591GNU Compiler Collection (GCC) Internals}.)
6592
6593@item -pie
6594@opindex pie
6595Produce a position independent executable on targets which support it.
6596For predictable results, you must also specify the same set of options
6597that were used to generate code (@option{-fpie}, @option{-fPIE},
6598or model suboptions) when you specify this option.
6599
6600@item -rdynamic
6601@opindex rdynamic
6602Pass the flag @option{-export-dynamic} to the ELF linker, on targets
6603that support it. This instructs the linker to add all symbols, not
6604only used ones, to the dynamic symbol table. This option is needed
6605for some uses of @code{dlopen} or to allow obtaining backtraces
6606from within a program.
6607
6608@item -s
6609@opindex s
6610Remove all symbol table and relocation information from the executable.
6611
6612@item -static
6613@opindex static
6614On systems that support dynamic linking, this prevents linking with the shared
6615libraries. On other systems, this option has no effect.
6616
6617@item -shared
6618@opindex shared
6619Produce a shared object which can then be linked with other objects to
6620form an executable. Not all systems support this option. For predictable
6621results, you must also specify the same set of options that were used to
6622generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
6623when you specify this option.@footnote{On some systems, @samp{gcc -shared}
6624needs to build supplementary stub code for constructors to work. On
6625multi-libbed systems, @samp{gcc -shared} must select the correct support
6626libraries to link against. Failing to supply the correct flags may lead
6627to subtle defects. Supplying them in cases where they are not necessary
6628is innocuous.}
6629
6630@item -shared-libgcc
6631@itemx -static-libgcc
6632@opindex shared-libgcc
6633@opindex static-libgcc
6634On systems that provide @file{libgcc} as a shared library, these options
6635force the use of either the shared or static version respectively.
6636If no shared version of @file{libgcc} was built when the compiler was
6637configured, these options have no effect.
6638
6639There are several situations in which an application should use the
6640shared @file{libgcc} instead of the static version. The most common
6641of these is when the application wishes to throw and catch exceptions
6642across different shared libraries. In that case, each of the libraries
6643as well as the application itself should use the shared @file{libgcc}.
6644
6645Therefore, the G++ and GCJ drivers automatically add
6646@option{-shared-libgcc} whenever you build a shared library or a main
6647executable, because C++ and Java programs typically use exceptions, so
6648this is the right thing to do.
6649
6650If, instead, you use the GCC driver to create shared libraries, you may
6651find that they will not always be linked with the shared @file{libgcc}.
6652If GCC finds, at its configuration time, that you have a non-GNU linker
6653or a GNU linker that does not support option @option{--eh-frame-hdr},
6654it will link the shared version of @file{libgcc} into shared libraries
6655by default. Otherwise, it will take advantage of the linker and optimize
6656away the linking with the shared version of @file{libgcc}, linking with
6657the static version of libgcc by default. This allows exceptions to
6658propagate through such shared libraries, without incurring relocation
6659costs at library load time.
6660
6661However, if a library or main executable is supposed to throw or catch
6662exceptions, you must link it using the G++ or GCJ driver, as appropriate
6663for the languages used in the program, or using the option
6664@option{-shared-libgcc}, such that it is linked with the shared
6665@file{libgcc}.
6666
6667@item -symbolic
6668@opindex symbolic
6669Bind references to global symbols when building a shared object. Warn
6670about any unresolved references (unless overridden by the link editor
6671option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
6672this option.
6673
6674@item -Xlinker @var{option}
6675@opindex Xlinker
6676Pass @var{option} as an option to the linker. You can use this to
6677supply system-specific linker options which GCC does not know how to
6678recognize.
6679
6680If you want to pass an option that takes an argument, you must use
6681@option{-Xlinker} twice, once for the option and once for the argument.
6682For example, to pass @option{-assert definitions}, you must write
6683@samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
6684@option{-Xlinker "-assert definitions"}, because this passes the entire
6685string as a single argument, which is not what the linker expects.
6686
6687@item -Wl,@var{option}
6688@opindex Wl
6689Pass @var{option} as an option to the linker. If @var{option} contains
6690commas, it is split into multiple options at the commas.
6691
6692@item -u @var{symbol}
6693@opindex u
6694Pretend the symbol @var{symbol} is undefined, to force linking of
6695library modules to define it. You can use @option{-u} multiple times with
6696different symbols to force loading of additional library modules.
6697@end table
6698
6699@node Directory Options
6700@section Options for Directory Search
6701@cindex directory options
6702@cindex options, directory search
6703@cindex search path
6704
6705These options specify directories to search for header files, for
6706libraries and for parts of the compiler:
6707
6708@table @gcctabopt
6709@item -I@var{dir}
6710@opindex I
6711Add the directory @var{dir} to the head of the list of directories to be
6712searched for header files. This can be used to override a system header
6713file, substituting your own version, since these directories are
6714searched before the system header file directories. However, you should
6715not use this option to add directories that contain vendor-supplied
6716system header files (use @option{-isystem} for that). If you use more than
6717one @option{-I} option, the directories are scanned in left-to-right
6718order; the standard system directories come after.
6719
6720If a standard system include directory, or a directory specified with
6721@option{-isystem}, is also specified with @option{-I}, the @option{-I}
6722option will be ignored. The directory will still be searched but as a
6723system directory at its normal position in the system include chain.
6724This is to ensure that GCC's procedure to fix buggy system headers and
6725the ordering for the include_next directive are not inadvertently changed.
6726If you really need to change the search order for system directories,
6727use the @option{-nostdinc} and/or @option{-isystem} options.
6728
6729@item -iquote@var{dir}
6730@opindex iquote
6731Add the directory @var{dir} to the head of the list of directories to
6732be searched for header files only for the case of @samp{#include
6733"@var{file}"}; they are not searched for @samp{#include <@var{file}>},
6734otherwise just like @option{-I}.
6735
6736@item -L@var{dir}
6737@opindex L
6738Add directory @var{dir} to the list of directories to be searched
6739for @option{-l}.
6740
6741@item -B@var{prefix}
6742@opindex B
6743This option specifies where to find the executables, libraries,
6744include files, and data files of the compiler itself.
6745
6746The compiler driver program runs one or more of the subprograms
6747@file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
6748@var{prefix} as a prefix for each program it tries to run, both with and
6749without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
6750
6751For each subprogram to be run, the compiler driver first tries the
6752@option{-B} prefix, if any. If that name is not found, or if @option{-B}
6753was not specified, the driver tries two standard prefixes, which are
6754@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of
6755those results in a file name that is found, the unmodified program
6756name is searched for using the directories specified in your
6757@env{PATH} environment variable.
6758
6759The compiler will check to see if the path provided by the @option{-B}
6760refers to a directory, and if necessary it will add a directory
6761separator character at the end of the path.
6762
6763@option{-B} prefixes that effectively specify directory names also apply
6764to libraries in the linker, because the compiler translates these
6765options into @option{-L} options for the linker. They also apply to
6766includes files in the preprocessor, because the compiler translates these
6767options into @option{-isystem} options for the preprocessor. In this case,
6768the compiler appends @samp{include} to the prefix.
6769
6770The run-time support file @file{libgcc.a} can also be searched for using
6771the @option{-B} prefix, if needed. If it is not found there, the two
6772standard prefixes above are tried, and that is all. The file is left
6773out of the link if it is not found by those means.
6774
6775Another way to specify a prefix much like the @option{-B} prefix is to use
6776the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
6777Variables}.
6778
6779As a special kludge, if the path provided by @option{-B} is
6780@file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
67819, then it will be replaced by @file{[dir/]include}. This is to help
6782with boot-strapping the compiler.
6783
6784@item -specs=@var{file}
6785@opindex specs
6786Process @var{file} after the compiler reads in the standard @file{specs}
6787file, in order to override the defaults that the @file{gcc} driver
6788program uses when determining what switches to pass to @file{cc1},
6789@file{cc1plus}, @file{as}, @file{ld}, etc. More than one
6790@option{-specs=@var{file}} can be specified on the command line, and they
6791are processed in order, from left to right.
6792
6793@item --sysroot=@var{dir}
6794@opindex sysroot
6795Use @var{dir} as the logical root directory for headers and libraries.
6796For example, if the compiler would normally search for headers in
6797@file{/usr/include} and libraries in @file{/usr/lib}, it will instead
6798search @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
6799
6800If you use both this option and the @option{-isysroot} option, then
6801the @option{--sysroot} option will apply to libraries, but the
6802@option{-isysroot} option will apply to header files.
6803
6804The GNU linker (beginning with version 2.16) has the necessary support
6805for this option. If your linker does not support this option, the
6806header file aspect of @option{--sysroot} will still work, but the
6807library aspect will not.
6808
6809@item -I-
6810@opindex I-
6811This option has been deprecated. Please use @option{-iquote} instead for
6812@option{-I} directories before the @option{-I-} and remove the @option{-I-}.
6813Any directories you specify with @option{-I} options before the @option{-I-}
6814option are searched only for the case of @samp{#include "@var{file}"};
6815they are not searched for @samp{#include <@var{file}>}.
6816
6817If additional directories are specified with @option{-I} options after
6818the @option{-I-}, these directories are searched for all @samp{#include}
6819directives. (Ordinarily @emph{all} @option{-I} directories are used
6820this way.)
6821
6822In addition, the @option{-I-} option inhibits the use of the current
6823directory (where the current input file came from) as the first search
6824directory for @samp{#include "@var{file}"}. There is no way to
6825override this effect of @option{-I-}. With @option{-I.} you can specify
6826searching the directory which was current when the compiler was
6827invoked. That is not exactly the same as what the preprocessor does
6828by default, but it is often satisfactory.
6829
6830@option{-I-} does not inhibit the use of the standard system directories
6831for header files. Thus, @option{-I-} and @option{-nostdinc} are
6832independent.
6833@end table
6834
6835@c man end
6836
6837@node Spec Files
6838@section Specifying subprocesses and the switches to pass to them
6839@cindex Spec Files
6840
6841@command{gcc} is a driver program. It performs its job by invoking a
6842sequence of other programs to do the work of compiling, assembling and
6843linking. GCC interprets its command-line parameters and uses these to
6844deduce which programs it should invoke, and which command-line options
6845it ought to place on their command lines. This behavior is controlled
6846by @dfn{spec strings}. In most cases there is one spec string for each
6847program that GCC can invoke, but a few programs have multiple spec
6848strings to control their behavior. The spec strings built into GCC can
6849be overridden by using the @option{-specs=} command-line switch to specify
6850a spec file.
6851
6852@dfn{Spec files} are plaintext files that are used to construct spec
6853strings. They consist of a sequence of directives separated by blank
6854lines. The type of directive is determined by the first non-whitespace
6855character on the line and it can be one of the following:
6856
6857@table @code
6858@item %@var{command}
6859Issues a @var{command} to the spec file processor. The commands that can
6860appear here are:
6861
6862@table @code
6863@item %include <@var{file}>
6864@cindex %include
6865Search for @var{file} and insert its text at the current point in the
6866specs file.
6867
6868@item %include_noerr <@var{file}>
6869@cindex %include_noerr
6870Just like @samp{%include}, but do not generate an error message if the include
6871file cannot be found.
6872
6873@item %rename @var{old_name} @var{new_name}
6874@cindex %rename
6875Rename the spec string @var{old_name} to @var{new_name}.
6876
6877@end table
6878
6879@item *[@var{spec_name}]:
6880This tells the compiler to create, override or delete the named spec
6881string. All lines after this directive up to the next directive or
6882blank line are considered to be the text for the spec string. If this
6883results in an empty string then the spec will be deleted. (Or, if the
6884spec did not exist, then nothing will happened.) Otherwise, if the spec
6885does not currently exist a new spec will be created. If the spec does
6886exist then its contents will be overridden by the text of this
6887directive, unless the first character of that text is the @samp{+}
6888character, in which case the text will be appended to the spec.
6889
6890@item [@var{suffix}]:
6891Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
6892and up to the next directive or blank line are considered to make up the
6893spec string for the indicated suffix. When the compiler encounters an
6894input file with the named suffix, it will processes the spec string in
6895order to work out how to compile that file. For example:
6896
6897@smallexample
6898.ZZ:
6899z-compile -input %i
6900@end smallexample
6901
6902This says that any input file whose name ends in @samp{.ZZ} should be
6903passed to the program @samp{z-compile}, which should be invoked with the
6904command-line switch @option{-input} and with the result of performing the
6905@samp{%i} substitution. (See below.)
6906
6907As an alternative to providing a spec string, the text that follows a
6908suffix directive can be one of the following:
6909
6910@table @code
6911@item @@@var{language}
6912This says that the suffix is an alias for a known @var{language}. This is
6913similar to using the @option{-x} command-line switch to GCC to specify a
6914language explicitly. For example:
6915
6916@smallexample
6917.ZZ:
6918@@c++
6919@end smallexample
6920
6921Says that .ZZ files are, in fact, C++ source files.
6922
6923@item #@var{name}
6924This causes an error messages saying:
6925
6926@smallexample
6927@var{name} compiler not installed on this system.
6928@end smallexample
6929@end table
6930
6931GCC already has an extensive list of suffixes built into it.
6932This directive will add an entry to the end of the list of suffixes, but
6933since the list is searched from the end backwards, it is effectively
6934possible to override earlier entries using this technique.
6935
6936@end table
6937
6938GCC has the following spec strings built into it. Spec files can
6939override these strings or create their own. Note that individual
6940targets can also add their own spec strings to this list.
6941
6942@smallexample
6943asm Options to pass to the assembler
6944asm_final Options to pass to the assembler post-processor
6945cpp Options to pass to the C preprocessor
6946cc1 Options to pass to the C compiler
6947cc1plus Options to pass to the C++ compiler
6948endfile Object files to include at the end of the link
6949link Options to pass to the linker
6950lib Libraries to include on the command line to the linker
6951libgcc Decides which GCC support library to pass to the linker
6952linker Sets the name of the linker
6953predefines Defines to be passed to the C preprocessor
6954signed_char Defines to pass to CPP to say whether @code{char} is signed
6955 by default
6956startfile Object files to include at the start of the link
6957@end smallexample
6958
6959Here is a small example of a spec file:
6960
6961@smallexample
6962%rename lib old_lib
6963
6964*lib:
6965--start-group -lgcc -lc -leval1 --end-group %(old_lib)
6966@end smallexample
6967
6968This example renames the spec called @samp{lib} to @samp{old_lib} and
6969then overrides the previous definition of @samp{lib} with a new one.
6970The new definition adds in some extra command-line options before
6971including the text of the old definition.
6972
6973@dfn{Spec strings} are a list of command-line options to be passed to their
6974corresponding program. In addition, the spec strings can contain
6975@samp{%}-prefixed sequences to substitute variable text or to
6976conditionally insert text into the command line. Using these constructs
6977it is possible to generate quite complex command lines.
6978
6979Here is a table of all defined @samp{%}-sequences for spec
6980strings. Note that spaces are not generated automatically around the
6981results of expanding these sequences. Therefore you can concatenate them
6982together or combine them with constant text in a single argument.
6983
6984@table @code
6985@item %%
6986Substitute one @samp{%} into the program name or argument.
6987
6988@item %i
6989Substitute the name of the input file being processed.
6990
6991@item %b
6992Substitute the basename of the input file being processed.
6993This is the substring up to (and not including) the last period
6994and not including the directory.
6995
6996@item %B
6997This is the same as @samp{%b}, but include the file suffix (text after
6998the last period).
6999
7000@item %d
7001Marks the argument containing or following the @samp{%d} as a
7002temporary file name, so that that file will be deleted if GCC exits
7003successfully. Unlike @samp{%g}, this contributes no text to the
7004argument.
7005
7006@item %g@var{suffix}
7007Substitute a file name that has suffix @var{suffix} and is chosen
7008once per compilation, and mark the argument in the same way as
7009@samp{%d}. To reduce exposure to denial-of-service attacks, the file
7010name is now chosen in a way that is hard to predict even when previously
7011chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
7012might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
7013the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
7014treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
7015was simply substituted with a file name chosen once per compilation,
7016without regard to any appended suffix (which was therefore treated
7017just like ordinary text), making such attacks more likely to succeed.
7018
7019@item %u@var{suffix}
7020Like @samp{%g}, but generates a new temporary file name even if
7021@samp{%u@var{suffix}} was already seen.
7022
7023@item %U@var{suffix}
7024Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
7025new one if there is no such last file name. In the absence of any
7026@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
7027the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
7028would involve the generation of two distinct file names, one
7029for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
7030simply substituted with a file name chosen for the previous @samp{%u},
7031without regard to any appended suffix.
7032
7033@item %j@var{suffix}
7034Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
7035writable, and if save-temps is off; otherwise, substitute the name
7036of a temporary file, just like @samp{%u}. This temporary file is not
7037meant for communication between processes, but rather as a junk
7038disposal mechanism.
7039
7040@item %|@var{suffix}
7041@itemx %m@var{suffix}
7042Like @samp{%g}, except if @option{-pipe} is in effect. In that case
7043@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
7044all. These are the two most common ways to instruct a program that it
7045should read from standard input or write to standard output. If you
7046need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
7047construct: see for example @file{f/lang-specs.h}.
7048
7049@item %.@var{SUFFIX}
7050Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
7051when it is subsequently output with @samp{%*}. @var{SUFFIX} is
7052terminated by the next space or %.
7053
7054@item %w
7055Marks the argument containing or following the @samp{%w} as the
7056designated output file of this compilation. This puts the argument
7057into the sequence of arguments that @samp{%o} will substitute later.
7058
7059@item %o
7060Substitutes the names of all the output files, with spaces
7061automatically placed around them. You should write spaces
7062around the @samp{%o} as well or the results are undefined.
7063@samp{%o} is for use in the specs for running the linker.
7064Input files whose names have no recognized suffix are not compiled
7065at all, but they are included among the output files, so they will
7066be linked.
7067
7068@item %O
7069Substitutes the suffix for object files. Note that this is
7070handled specially when it immediately follows @samp{%g, %u, or %U},
7071because of the need for those to form complete file names. The
7072handling is such that @samp{%O} is treated exactly as if it had already
7073been substituted, except that @samp{%g, %u, and %U} do not currently
7074support additional @var{suffix} characters following @samp{%O} as they would
7075following, for example, @samp{.o}.
7076
7077@item %p
7078Substitutes the standard macro predefinitions for the
7079current target machine. Use this when running @code{cpp}.
7080
7081@item %P
7082Like @samp{%p}, but puts @samp{__} before and after the name of each
7083predefined macro, except for macros that start with @samp{__} or with
7084@samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
7085C@.
7086
7087@item %I
7088Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
7089@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
7090@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
7091and @option{-imultilib} as necessary.
7092
7093@item %s
7094Current argument is the name of a library or startup file of some sort.
7095Search for that file in a standard list of directories and substitute
7096the full name found.
7097
7098@item %e@var{str}
7099Print @var{str} as an error message. @var{str} is terminated by a newline.
7100Use this when inconsistent options are detected.
7101
7102@item %(@var{name})
7103Substitute the contents of spec string @var{name} at this point.
7104
7105@item %[@var{name}]
7106Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
7107
7108@item %x@{@var{option}@}
7109Accumulate an option for @samp{%X}.
7110
7111@item %X
7112Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
7113spec string.
7114
7115@item %Y
7116Output the accumulated assembler options specified by @option{-Wa}.
7117
7118@item %Z
7119Output the accumulated preprocessor options specified by @option{-Wp}.
7120
7121@item %a
7122Process the @code{asm} spec. This is used to compute the
7123switches to be passed to the assembler.
7124
7125@item %A
7126Process the @code{asm_final} spec. This is a spec string for
7127passing switches to an assembler post-processor, if such a program is
7128needed.
7129
7130@item %l
7131Process the @code{link} spec. This is the spec for computing the
7132command line passed to the linker. Typically it will make use of the
7133@samp{%L %G %S %D and %E} sequences.
7134
7135@item %D
7136Dump out a @option{-L} option for each directory that GCC believes might
7137contain startup files. If the target supports multilibs then the
7138current multilib directory will be prepended to each of these paths.
7139
7140@item %L
7141Process the @code{lib} spec. This is a spec string for deciding which
7142libraries should be included on the command line to the linker.
7143
7144@item %G
7145Process the @code{libgcc} spec. This is a spec string for deciding
7146which GCC support library should be included on the command line to the linker.
7147
7148@item %S
7149Process the @code{startfile} spec. This is a spec for deciding which
7150object files should be the first ones passed to the linker. Typically
7151this might be a file named @file{crt0.o}.
7152
7153@item %E
7154Process the @code{endfile} spec. This is a spec string that specifies
7155the last object files that will be passed to the linker.
7156
7157@item %C
7158Process the @code{cpp} spec. This is used to construct the arguments
7159to be passed to the C preprocessor.
7160
7161@item %1
7162Process the @code{cc1} spec. This is used to construct the options to be
7163passed to the actual C compiler (@samp{cc1}).
7164
7165@item %2
7166Process the @code{cc1plus} spec. This is used to construct the options to be
7167passed to the actual C++ compiler (@samp{cc1plus}).
7168
7169@item %*
7170Substitute the variable part of a matched option. See below.
7171Note that each comma in the substituted string is replaced by
7172a single space.
7173
7174@item %<@code{S}
7175Remove all occurrences of @code{-S} from the command line. Note---this
7176command is position dependent. @samp{%} commands in the spec string
7177before this one will see @code{-S}, @samp{%} commands in the spec string
7178after this one will not.
7179
7180@item %:@var{function}(@var{args})
7181Call the named function @var{function}, passing it @var{args}.
7182@var{args} is first processed as a nested spec string, then split
7183into an argument vector in the usual fashion. The function returns
7184a string which is processed as if it had appeared literally as part
7185of the current spec.
7186
7187The following built-in spec functions are provided:
7188
7189@table @code
7190@item @code{if-exists}
7191The @code{if-exists} spec function takes one argument, an absolute
7192pathname to a file. If the file exists, @code{if-exists} returns the
7193pathname. Here is a small example of its usage:
7194
7195@smallexample
7196*startfile:
7197crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
7198@end smallexample
7199
7200@item @code{if-exists-else}
7201The @code{if-exists-else} spec function is similar to the @code{if-exists}
7202spec function, except that it takes two arguments. The first argument is
7203an absolute pathname to a file. If the file exists, @code{if-exists-else}
7204returns the pathname. If it does not exist, it returns the second argument.
7205This way, @code{if-exists-else} can be used to select one file or another,
7206based on the existence of the first. Here is a small example of its usage:
7207
7208@smallexample
7209*startfile:
7210crt0%O%s %:if-exists(crti%O%s) \
7211%:if-exists-else(crtbeginT%O%s crtbegin%O%s)
7212@end smallexample
7213
7214@item @code{replace-outfile}
7215The @code{replace-outfile} spec function takes two arguments. It looks for the
7216first argument in the outfiles array and replaces it with the second argument. Here
7217is a small example of its usage:
7218
7219@smallexample
7220%@{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)@}
7221@end smallexample
7222
7223@end table
7224
7225@item %@{@code{S}@}
7226Substitutes the @code{-S} switch, if that switch was given to GCC@.
7227If that switch was not specified, this substitutes nothing. Note that
7228the leading dash is omitted when specifying this option, and it is
7229automatically inserted if the substitution is performed. Thus the spec
7230string @samp{%@{foo@}} would match the command-line option @option{-foo}
7231and would output the command line option @option{-foo}.
7232
7233@item %W@{@code{S}@}
7234Like %@{@code{S}@} but mark last argument supplied within as a file to be
7235deleted on failure.
7236
7237@item %@{@code{S}*@}
7238Substitutes all the switches specified to GCC whose names start
7239with @code{-S}, but which also take an argument. This is used for
7240switches like @option{-o}, @option{-D}, @option{-I}, etc.
7241GCC considers @option{-o foo} as being
7242one switch whose names starts with @samp{o}. %@{o*@} would substitute this
7243text, including the space. Thus two arguments would be generated.
7244
7245@item %@{@code{S}*&@code{T}*@}
7246Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
7247(the order of @code{S} and @code{T} in the spec is not significant).
7248There can be any number of ampersand-separated variables; for each the
7249wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
7250
7251@item %@{@code{S}:@code{X}@}
7252Substitutes @code{X}, if the @samp{-S} switch was given to GCC@.
7253
7254@item %@{!@code{S}:@code{X}@}
7255Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@.
7256
7257@item %@{@code{S}*:@code{X}@}
7258Substitutes @code{X} if one or more switches whose names start with
7259@code{-S} are specified to GCC@. Normally @code{X} is substituted only
7260once, no matter how many such switches appeared. However, if @code{%*}
7261appears somewhere in @code{X}, then @code{X} will be substituted once
7262for each matching switch, with the @code{%*} replaced by the part of
7263that switch that matched the @code{*}.
7264
7265@item %@{.@code{S}:@code{X}@}
7266Substitutes @code{X}, if processing a file with suffix @code{S}.
7267
7268@item %@{!.@code{S}:@code{X}@}
7269Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
7270
7271@item %@{@code{S}|@code{P}:@code{X}@}
7272Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@.
7273This may be combined with @samp{!}, @samp{.}, and @code{*} sequences as well,
7274although they have a stronger binding than the @samp{|}. If @code{%*}
7275appears in @code{X}, all of the alternatives must be starred, and only
7276the first matching alternative is substituted.
7277
7278For example, a spec string like this:
7279
7280@smallexample
7281%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
7282@end smallexample
7283
7284will output the following command-line options from the following input
7285command-line options:
7286
7287@smallexample
7288fred.c -foo -baz
7289jim.d -bar -boggle
7290-d fred.c -foo -baz -boggle
7291-d jim.d -bar -baz -boggle
7292@end smallexample
7293
7294@item %@{S:X; T:Y; :D@}
7295
7296If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was
7297given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
7298be as many clauses as you need. This may be combined with @code{.},
7299@code{!}, @code{|}, and @code{*} as needed.
7300
7301
7302@end table
7303
7304The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
7305construct may contain other nested @samp{%} constructs or spaces, or
7306even newlines. They are processed as usual, as described above.
7307Trailing white space in @code{X} is ignored. White space may also
7308appear anywhere on the left side of the colon in these constructs,
7309except between @code{.} or @code{*} and the corresponding word.
7310
7311The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
7312handled specifically in these constructs. If another value of
7313@option{-O} or the negated form of a @option{-f}, @option{-m}, or
7314@option{-W} switch is found later in the command line, the earlier
7315switch value is ignored, except with @{@code{S}*@} where @code{S} is
7316just one letter, which passes all matching options.
7317
7318The character @samp{|} at the beginning of the predicate text is used to
7319indicate that a command should be piped to the following command, but
7320only if @option{-pipe} is specified.
7321
7322It is built into GCC which switches take arguments and which do not.
7323(You might think it would be useful to generalize this to allow each
7324compiler's spec to say which switches take arguments. But this cannot
7325be done in a consistent fashion. GCC cannot even decide which input
7326files have been specified without knowing which switches take arguments,
7327and it must know which input files to compile in order to tell which
7328compilers to run).
7329
7330GCC also knows implicitly that arguments starting in @option{-l} are to be
7331treated as compiler output files, and passed to the linker in their
7332proper position among the other output files.
7333
7334@c man begin OPTIONS
7335
7336@node Target Options
7337@section Specifying Target Machine and Compiler Version
7338@cindex target options
7339@cindex cross compiling
7340@cindex specifying machine version
7341@cindex specifying compiler version and target machine
7342@cindex compiler version, specifying
7343@cindex target machine, specifying
7344
7345The usual way to run GCC is to run the executable called @file{gcc}, or
7346@file{<machine>-gcc} when cross-compiling, or
7347@file{<machine>-gcc-<version>} to run a version other than the one that
7348was installed last. Sometimes this is inconvenient, so GCC provides
7349options that will switch to another cross-compiler or version.
7350
7351@table @gcctabopt
7352@item -b @var{machine}
7353@opindex b
7354The argument @var{machine} specifies the target machine for compilation.
7355
7356The value to use for @var{machine} is the same as was specified as the
7357machine type when configuring GCC as a cross-compiler. For
7358example, if a cross-compiler was configured with @samp{configure
7359arm-elf}, meaning to compile for an arm processor with elf binaries,
7360then you would specify @option{-b arm-elf} to run that cross compiler.
7361Because there are other options beginning with @option{-b}, the
7362configuration must contain a hyphen.
7363
7364@item -V @var{version}
7365@opindex V
7366The argument @var{version} specifies which version of GCC to run.
7367This is useful when multiple versions are installed. For example,
7368@var{version} might be @samp{4.0}, meaning to run GCC version 4.0.
7369@end table
7370
7371The @option{-V} and @option{-b} options work by running the
7372@file{<machine>-gcc-<version>} executable, so there's no real reason to
7373use them if you can just run that directly.
7374
7375@node Submodel Options
7376@section Hardware Models and Configurations
7377@cindex submodel options
7378@cindex specifying hardware config
7379@cindex hardware models and configurations, specifying
7380@cindex machine dependent options
7381
7382Earlier we discussed the standard option @option{-b} which chooses among
7383different installed compilers for completely different target
7384machines, such as VAX vs.@: 68000 vs.@: 80386.
7385
7386In addition, each of these target machine types can have its own
7387special options, starting with @samp{-m}, to choose among various
7388hardware models or configurations---for example, 68010 vs 68020,
7389floating coprocessor or none. A single installed version of the
7390compiler can compile for any model or configuration, according to the
7391options specified.
7392
7393Some configurations of the compiler also support additional special
7394options, usually for compatibility with other compilers on the same
7395platform.
7396
7397@c This list is ordered alphanumerically by subsection name.
7398@c It should be the same order and spelling as these options are listed
7399@c in Machine Dependent Options
7400
7401@menu
7402* ARC Options::
7403* ARM Options::
7404* AVR Options::
7405* Blackfin Options::
7406* CRIS Options::
7407* CRX Options::
7408* Darwin Options::
7409* DEC Alpha Options::
7410* DEC Alpha/VMS Options::
7411* FRV Options::
7412* GNU/Linux Options::
7413* H8/300 Options::
7414* HPPA Options::
7415* i386 and x86-64 Options::
7416* IA-64 Options::
7417* M32C Options::
7418* M32R/D Options::
7419* M680x0 Options::
7420* M68hc1x Options::
7421* MCore Options::
7422* MIPS Options::
7423* MMIX Options::
7424* MN10300 Options::
7425* MT Options::
7426* PDP-11 Options::
7427* PowerPC Options::
7428* RS/6000 and PowerPC Options::
7429* S/390 and zSeries Options::
7430* Score Options::
7431* SH Options::
7432* SPARC Options::
7433* System V Options::
7434* TMS320C3x/C4x Options::
7435* V850 Options::
7436* VAX Options::
7437* x86-64 Options::
7438* Xstormy16 Options::
7439* Xtensa Options::
7440* zSeries Options::
7441@end menu
7442
7443@node ARC Options
7444@subsection ARC Options
7445@cindex ARC Options
7446
7447These options are defined for ARC implementations:
7448
7449@table @gcctabopt
7450@item -EL
7451@opindex EL
7452Compile code for little endian mode. This is the default.
7453
7454@item -EB
7455@opindex EB
7456Compile code for big endian mode.
7457
7458@item -mmangle-cpu
7459@opindex mmangle-cpu
7460Prepend the name of the cpu to all public symbol names.
7461In multiple-processor systems, there are many ARC variants with different
7462instruction and register set characteristics. This flag prevents code
7463compiled for one cpu to be linked with code compiled for another.
7464No facility exists for handling variants that are ``almost identical''.
7465This is an all or nothing option.
7466
7467@item -mcpu=@var{cpu}
7468@opindex mcpu
7469Compile code for ARC variant @var{cpu}.
7470Which variants are supported depend on the configuration.
7471All variants support @option{-mcpu=base}, this is the default.
7472
7473@item -mtext=@var{text-section}
7474@itemx -mdata=@var{data-section}
7475@itemx -mrodata=@var{readonly-data-section}
7476@opindex mtext
7477@opindex mdata
7478@opindex mrodata
7479Put functions, data, and readonly data in @var{text-section},
7480@var{data-section}, and @var{readonly-data-section} respectively
7481by default. This can be overridden with the @code{section} attribute.
7482@xref{Variable Attributes}.
7483
7484@end table
7485
7486@node ARM Options
7487@subsection ARM Options
7488@cindex ARM options
7489
7490These @samp{-m} options are defined for Advanced RISC Machines (ARM)
7491architectures:
7492
7493@table @gcctabopt
7494@item -mabi=@var{name}
7495@opindex mabi
7496Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu},
7497@samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.
7498
7499@item -mapcs-frame
7500@opindex mapcs-frame
7501Generate a stack frame that is compliant with the ARM Procedure Call
7502Standard for all functions, even if this is not strictly necessary for
7503correct execution of the code. Specifying @option{-fomit-frame-pointer}
7504with this option will cause the stack frames not to be generated for
7505leaf functions. The default is @option{-mno-apcs-frame}.
7506
7507@item -mapcs
7508@opindex mapcs
7509This is a synonym for @option{-mapcs-frame}.
7510
7511@ignore
7512@c not currently implemented
7513@item -mapcs-stack-check
7514@opindex mapcs-stack-check
7515Generate code to check the amount of stack space available upon entry to
7516every function (that actually uses some stack space). If there is
7517insufficient space available then either the function
7518@samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
7519called, depending upon the amount of stack space required. The run time
7520system is required to provide these functions. The default is
7521@option{-mno-apcs-stack-check}, since this produces smaller code.
7522
7523@c not currently implemented
7524@item -mapcs-float
7525@opindex mapcs-float
7526Pass floating point arguments using the float point registers. This is
7527one of the variants of the APCS@. This option is recommended if the
7528target hardware has a floating point unit or if a lot of floating point
7529arithmetic is going to be performed by the code. The default is
7530@option{-mno-apcs-float}, since integer only code is slightly increased in
7531size if @option{-mapcs-float} is used.
7532
7533@c not currently implemented
7534@item -mapcs-reentrant
7535@opindex mapcs-reentrant
7536Generate reentrant, position independent code. The default is
7537@option{-mno-apcs-reentrant}.
7538@end ignore
7539
7540@item -mthumb-interwork
7541@opindex mthumb-interwork
7542Generate code which supports calling between the ARM and Thumb
7543instruction sets. Without this option the two instruction sets cannot
7544be reliably used inside one program. The default is
7545@option{-mno-thumb-interwork}, since slightly larger code is generated
7546when @option{-mthumb-interwork} is specified.
7547
7548@item -mno-sched-prolog
7549@opindex mno-sched-prolog
7550Prevent the reordering of instructions in the function prolog, or the
7551merging of those instruction with the instructions in the function's
7552body. This means that all functions will start with a recognizable set
7553of instructions (or in fact one of a choice from a small set of
7554different function prologues), and this information can be used to
7555locate the start if functions inside an executable piece of code. The
7556default is @option{-msched-prolog}.
7557
7558@item -mhard-float
7559@opindex mhard-float
7560Generate output containing floating point instructions. This is the
7561default.
7562
7563@item -msoft-float
7564@opindex msoft-float
7565Generate output containing library calls for floating point.
7566@strong{Warning:} the requisite libraries are not available for all ARM
7567targets. Normally the facilities of the machine's usual C compiler are
7568used, but this cannot be done directly in cross-compilation. You must make
7569your own arrangements to provide suitable library functions for
7570cross-compilation.
7571
7572@option{-msoft-float} changes the calling convention in the output file;
7573therefore, it is only useful if you compile @emph{all} of a program with
7574this option. In particular, you need to compile @file{libgcc.a}, the
7575library that comes with GCC, with @option{-msoft-float} in order for
7576this to work.
7577
7578@item -mfloat-abi=@var{name}
7579@opindex mfloat-abi
7580Specifies which ABI to use for floating point values. Permissible values
7581are: @samp{soft}, @samp{softfp} and @samp{hard}.
7582
7583@samp{soft} and @samp{hard} are equivalent to @option{-msoft-float}
7584and @option{-mhard-float} respectively. @samp{softfp} allows the generation
7585of floating point instructions, but still uses the soft-float calling
7586conventions.
7587
7588@item -mlittle-endian
7589@opindex mlittle-endian
7590Generate code for a processor running in little-endian mode. This is
7591the default for all standard configurations.
7592
7593@item -mbig-endian
7594@opindex mbig-endian
7595Generate code for a processor running in big-endian mode; the default is
7596to compile code for a little-endian processor.
7597
7598@item -mwords-little-endian
7599@opindex mwords-little-endian
7600This option only applies when generating code for big-endian processors.
7601Generate code for a little-endian word order but a big-endian byte
7602order. That is, a byte order of the form @samp{32107654}. Note: this
7603option should only be used if you require compatibility with code for
7604big-endian ARM processors generated by versions of the compiler prior to
76052.8.
7606
7607@item -mcpu=@var{name}
7608@opindex mcpu
7609This specifies the name of the target ARM processor. GCC uses this name
7610to determine what kind of instructions it can emit when generating
7611assembly code. Permissible names are: @samp{arm2}, @samp{arm250},
7612@samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
7613@samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
7614@samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
7615@samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
7616@samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},
7617@samp{arm8}, @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
7618@samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
7619@samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},
7620@samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},
7621@samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},
7622@samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
7623@samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
7624@samp{arm1176jz-s}, @samp{arm1176jzf-s}, @samp{xscale}, @samp{iwmmxt},
7625@samp{ep9312}.
7626
7627@itemx -mtune=@var{name}
7628@opindex mtune
7629This option is very similar to the @option{-mcpu=} option, except that
7630instead of specifying the actual target processor type, and hence
7631restricting which instructions can be used, it specifies that GCC should
7632tune the performance of the code as if the target were of the type
7633specified in this option, but still choosing the instructions that it
7634will generate based on the cpu specified by a @option{-mcpu=} option.
7635For some ARM implementations better performance can be obtained by using
7636this option.
7637
7638@item -march=@var{name}
7639@opindex march
7640This specifies the name of the target ARM architecture. GCC uses this
7641name to determine what kind of instructions it can emit when generating
7642assembly code. This option can be used in conjunction with or instead
7643of the @option{-mcpu=} option. Permissible names are: @samp{armv2},
7644@samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
7645@samp{armv5}, @samp{armv5t}, @samp{armv5te}, @samp{armv6}, @samp{armv6j},
7646@samp{iwmmxt}, @samp{ep9312}.
7647
7648@item -mfpu=@var{name}
7649@itemx -mfpe=@var{number}
7650@itemx -mfp=@var{number}
7651@opindex mfpu
7652@opindex mfpe
7653@opindex mfp
7654This specifies what floating point hardware (or hardware emulation) is
7655available on the target. Permissible names are: @samp{fpa}, @samp{fpe2},
7656@samp{fpe3}, @samp{maverick}, @samp{vfp}. @option{-mfp} and @option{-mfpe}
7657are synonyms for @option{-mfpu}=@samp{fpe}@var{number}, for compatibility
7658with older versions of GCC@.
7659
7660If @option{-msoft-float} is specified this specifies the format of
7661floating point values.
7662
7663@item -mstructure-size-boundary=@var{n}
7664@opindex mstructure-size-boundary
7665The size of all structures and unions will be rounded up to a multiple
7666of the number of bits set by this option. Permissible values are 8, 32
7667and 64. The default value varies for different toolchains. For the COFF
7668targeted toolchain the default value is 8. A value of 64 is only allowed
7669if the underlying ABI supports it.
7670
7671Specifying the larger number can produce faster, more efficient code, but
7672can also increase the size of the program. Different values are potentially
7673incompatible. Code compiled with one value cannot necessarily expect to
7674work with code or libraries compiled with another value, if they exchange
7675information using structures or unions.
7676
7677@item -mabort-on-noreturn
7678@opindex mabort-on-noreturn
7679Generate a call to the function @code{abort} at the end of a
7680@code{noreturn} function. It will be executed if the function tries to
7681return.
7682
7683@item -mlong-calls
7684@itemx -mno-long-calls
7685@opindex mlong-calls
7686@opindex mno-long-calls
7687Tells the compiler to perform function calls by first loading the
7688address of the function into a register and then performing a subroutine
7689call on this register. This switch is needed if the target function
7690will lie outside of the 64 megabyte addressing range of the offset based
7691version of subroutine call instruction.
7692
7693Even if this switch is enabled, not all function calls will be turned
7694into long calls. The heuristic is that static functions, functions
7695which have the @samp{short-call} attribute, functions that are inside
7696the scope of a @samp{#pragma no_long_calls} directive and functions whose
7697definitions have already been compiled within the current compilation
7698unit, will not be turned into long calls. The exception to this rule is
7699that weak function definitions, functions with the @samp{long-call}
7700attribute or the @samp{section} attribute, and functions that are within
7701the scope of a @samp{#pragma long_calls} directive, will always be
7702turned into long calls.
7703
7704This feature is not enabled by default. Specifying
7705@option{-mno-long-calls} will restore the default behavior, as will
7706placing the function calls within the scope of a @samp{#pragma
7707long_calls_off} directive. Note these switches have no effect on how
7708the compiler generates code to handle function calls via function
7709pointers.
7710
7711@item -mnop-fun-dllimport
7712@opindex mnop-fun-dllimport
7713Disable support for the @code{dllimport} attribute.
7714
7715@item -msingle-pic-base
7716@opindex msingle-pic-base
7717Treat the register used for PIC addressing as read-only, rather than
7718loading it in the prologue for each function. The run-time system is
7719responsible for initializing this register with an appropriate value
7720before execution begins.
7721
7722@item -mpic-register=@var{reg}
7723@opindex mpic-register
7724Specify the register to be used for PIC addressing. The default is R10
7725unless stack-checking is enabled, when R9 is used.
7726
7727@item -mcirrus-fix-invalid-insns
7728@opindex mcirrus-fix-invalid-insns
7729@opindex mno-cirrus-fix-invalid-insns
7730Insert NOPs into the instruction stream to in order to work around
7731problems with invalid Maverick instruction combinations. This option
7732is only valid if the @option{-mcpu=ep9312} option has been used to
7733enable generation of instructions for the Cirrus Maverick floating
7734point co-processor. This option is not enabled by default, since the
7735problem is only present in older Maverick implementations. The default
7736can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns}
7737switch.
7738
7739@item -mpoke-function-name
7740@opindex mpoke-function-name
7741Write the name of each function into the text section, directly
7742preceding the function prologue. The generated code is similar to this:
7743
7744@smallexample
7745 t0
7746 .ascii "arm_poke_function_name", 0
7747 .align
7748 t1
7749 .word 0xff000000 + (t1 - t0)
7750 arm_poke_function_name
7751 mov ip, sp
7752 stmfd sp!, @{fp, ip, lr, pc@}
7753 sub fp, ip, #4
7754@end smallexample
7755
7756When performing a stack backtrace, code can inspect the value of
7757@code{pc} stored at @code{fp + 0}. If the trace function then looks at
7758location @code{pc - 12} and the top 8 bits are set, then we know that
7759there is a function name embedded immediately preceding this location
7760and has length @code{((pc[-3]) & 0xff000000)}.
7761
7762@item -mthumb
7763@opindex mthumb
7764Generate code for the 16-bit Thumb instruction set. The default is to
7765use the 32-bit ARM instruction set.
7766
7767@item -mtpcs-frame
7768@opindex mtpcs-frame
7769Generate a stack frame that is compliant with the Thumb Procedure Call
7770Standard for all non-leaf functions. (A leaf function is one that does
7771not call any other functions.) The default is @option{-mno-tpcs-frame}.
7772
7773@item -mtpcs-leaf-frame
7774@opindex mtpcs-leaf-frame
7775Generate a stack frame that is compliant with the Thumb Procedure Call
7776Standard for all leaf functions. (A leaf function is one that does
7777not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
7778
7779@item -mcallee-super-interworking
7780@opindex mcallee-super-interworking
7781Gives all externally visible functions in the file being compiled an ARM
7782instruction set header which switches to Thumb mode before executing the
7783rest of the function. This allows these functions to be called from
7784non-interworking code.
7785
7786@item -mcaller-super-interworking
7787@opindex mcaller-super-interworking
7788Allows calls via function pointers (including virtual functions) to
7789execute correctly regardless of whether the target code has been
7790compiled for interworking or not. There is a small overhead in the cost
7791of executing a function pointer if this option is enabled.
7792
7793@item -mtp=@var{name}
7794@opindex mtp
7795Specify the access model for the thread local storage pointer. The valid
7796models are @option{soft}, which generates calls to @code{__aeabi_read_tp},
7797@option{cp15}, which fetches the thread pointer from @code{cp15} directly
7798(supported in the arm6k architecture), and @option{auto}, which uses the
7799best available method for the selected processor. The default setting is
7800@option{auto}.
7801
7802@end table
7803
7804@node AVR Options
7805@subsection AVR Options
7806@cindex AVR Options
7807
7808These options are defined for AVR implementations:
7809
7810@table @gcctabopt
7811@item -mmcu=@var{mcu}
7812@opindex mmcu
7813Specify ATMEL AVR instruction set or MCU type.
7814
7815Instruction set avr1 is for the minimal AVR core, not supported by the C
7816compiler, only for assembler programs (MCU types: at90s1200, attiny10,
7817attiny11, attiny12, attiny15, attiny28).
7818
7819Instruction set avr2 (default) is for the classic AVR core with up to
78208K program memory space (MCU types: at90s2313, at90s2323, attiny22,
7821at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
7822at90c8534, at90s8535).
7823
7824Instruction set avr3 is for the classic AVR core with up to 128K program
7825memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
7826
7827Instruction set avr4 is for the enhanced AVR core with up to 8K program
7828memory space (MCU types: atmega8, atmega83, atmega85).
7829
7830Instruction set avr5 is for the enhanced AVR core with up to 128K program
7831memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
7832atmega64, atmega128, at43usb355, at94k).
7833
7834@item -msize
7835@opindex msize
7836Output instruction sizes to the asm file.
7837
7838@item -minit-stack=@var{N}
7839@opindex minit-stack
7840Specify the initial stack address, which may be a symbol or numeric value,
7841@samp{__stack} is the default.
7842
7843@item -mno-interrupts
7844@opindex mno-interrupts
7845Generated code is not compatible with hardware interrupts.
7846Code size will be smaller.
7847
7848@item -mcall-prologues
7849@opindex mcall-prologues
7850Functions prologues/epilogues expanded as call to appropriate
7851subroutines. Code size will be smaller.
7852
7853@item -mno-tablejump
7854@opindex mno-tablejump
7855Do not generate tablejump insns which sometimes increase code size.
7856
7857@item -mtiny-stack
7858@opindex mtiny-stack
7859Change only the low 8 bits of the stack pointer.
7860
7861@item -mint8
7862@opindex mint8
7863Assume int to be 8 bit integer. This affects the sizes of all types: A
7864char will be 1 byte, an int will be 1 byte, an long will be 2 bytes
7865and long long will be 4 bytes. Please note that this option does not
7866comply to the C standards, but it will provide you with smaller code
7867size.
7868@end table
7869
7870@node Blackfin Options
7871@subsection Blackfin Options
7872@cindex Blackfin Options
7873
7874@table @gcctabopt
7875@item -momit-leaf-frame-pointer
7876@opindex momit-leaf-frame-pointer
7877Don't keep the frame pointer in a register for leaf functions. This
7878avoids the instructions to save, set up and restore frame pointers and
7879makes an extra register available in leaf functions. The option
7880@option{-fomit-frame-pointer} removes the frame pointer for all functions
7881which might make debugging harder.
7882
7883@item -mspecld-anomaly
7884@opindex mspecld-anomaly
7885When enabled, the compiler will ensure that the generated code does not
7886contain speculative loads after jump instructions. This option is enabled
7887by default.
7888
7889@item -mno-specld-anomaly
7890@opindex mno-specld-anomaly
7891Don't generate extra code to prevent speculative loads from occurring.
7892
7893@item -mcsync-anomaly
7894@opindex mcsync-anomaly
7895When enabled, the compiler will ensure that the generated code does not
7896contain CSYNC or SSYNC instructions too soon after conditional branches.
7897This option is enabled by default.
7898
7899@item -mno-csync-anomaly
7900@opindex mno-csync-anomaly
7901Don't generate extra code to prevent CSYNC or SSYNC instructions from
7902occurring too soon after a conditional branch.
7903
7904@item -mlow-64k
7905@opindex mlow-64k
7906When enabled, the compiler is free to take advantage of the knowledge that
7907the entire program fits into the low 64k of memory.
7908
7909@item -mno-low-64k
7910@opindex mno-low-64k
7911Assume that the program is arbitrarily large. This is the default.
7912
7913@item -mid-shared-library
7914@opindex mid-shared-library
7915Generate code that supports shared libraries via the library ID method.
7916This allows for execute in place and shared libraries in an environment
7917without virtual memory management. This option implies @option{-fPIC}.
7918
7919@item -mno-id-shared-library
7920@opindex mno-id-shared-library
7921Generate code that doesn't assume ID based shared libraries are being used.
7922This is the default.
7923
7924@item -mshared-library-id=n
7925@opindex mshared-library-id
7926Specified the identification number of the ID based shared library being
7927compiled. Specifying a value of 0 will generate more compact code, specifying
7928other values will force the allocation of that number to the current
7929library but is no more space or time efficient than omitting this option.
7930
7931@item -mlong-calls
7932@itemx -mno-long-calls
7933@opindex mlong-calls
7934@opindex mno-long-calls
7935Tells the compiler to perform function calls by first loading the
7936address of the function into a register and then performing a subroutine
7937call on this register. This switch is needed if the target function
7938will lie outside of the 24 bit addressing range of the offset based
7939version of subroutine call instruction.
7940
7941This feature is not enabled by default. Specifying
7942@option{-mno-long-calls} will restore the default behavior. Note these
7943switches have no effect on how the compiler generates code to handle
7944function calls via function pointers.
7945@end table
7946
7947@node CRIS Options
7948@subsection CRIS Options
7949@cindex CRIS Options
7950
7951These options are defined specifically for the CRIS ports.
7952
7953@table @gcctabopt
7954@item -march=@var{architecture-type}
7955@itemx -mcpu=@var{architecture-type}
7956@opindex march
7957@opindex mcpu
7958Generate code for the specified architecture. The choices for
7959@var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
7960respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
7961Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
7962@samp{v10}.
7963
7964@item -mtune=@var{architecture-type}
7965@opindex mtune
7966Tune to @var{architecture-type} everything applicable about the generated
7967code, except for the ABI and the set of available instructions. The
7968choices for @var{architecture-type} are the same as for
7969@option{-march=@var{architecture-type}}.
7970
7971@item -mmax-stack-frame=@var{n}
7972@opindex mmax-stack-frame
7973Warn when the stack frame of a function exceeds @var{n} bytes.
7974
7975@item -melinux-stacksize=@var{n}
7976@opindex melinux-stacksize
7977Only available with the @samp{cris-axis-aout} target. Arranges for
7978indications in the program to the kernel loader that the stack of the
7979program should be set to @var{n} bytes.
7980
7981@item -metrax4
7982@itemx -metrax100
7983@opindex metrax4
7984@opindex metrax100
7985The options @option{-metrax4} and @option{-metrax100} are synonyms for
7986@option{-march=v3} and @option{-march=v8} respectively.
7987
7988@item -mmul-bug-workaround
7989@itemx -mno-mul-bug-workaround
7990@opindex mmul-bug-workaround
7991@opindex mno-mul-bug-workaround
7992Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
7993models where it applies. This option is active by default.
7994
7995@item -mpdebug
7996@opindex mpdebug
7997Enable CRIS-specific verbose debug-related information in the assembly
7998code. This option also has the effect to turn off the @samp{#NO_APP}
7999formatted-code indicator to the assembler at the beginning of the
8000assembly file.
8001
8002@item -mcc-init
8003@opindex mcc-init
8004Do not use condition-code results from previous instruction; always emit
8005compare and test instructions before use of condition codes.
8006
8007@item -mno-side-effects
8008@opindex mno-side-effects
8009Do not emit instructions with side-effects in addressing modes other than
8010post-increment.
8011
8012@item -mstack-align
8013@itemx -mno-stack-align
8014@itemx -mdata-align
8015@itemx -mno-data-align
8016@itemx -mconst-align
8017@itemx -mno-const-align
8018@opindex mstack-align
8019@opindex mno-stack-align
8020@opindex mdata-align
8021@opindex mno-data-align
8022@opindex mconst-align
8023@opindex mno-const-align
8024These options (no-options) arranges (eliminate arrangements) for the
8025stack-frame, individual data and constants to be aligned for the maximum
8026single data access size for the chosen CPU model. The default is to
8027arrange for 32-bit alignment. ABI details such as structure layout are
8028not affected by these options.
8029
8030@item -m32-bit
8031@itemx -m16-bit
8032@itemx -m8-bit
8033@opindex m32-bit
8034@opindex m16-bit
8035@opindex m8-bit
8036Similar to the stack- data- and const-align options above, these options
8037arrange for stack-frame, writable data and constants to all be 32-bit,
803816-bit or 8-bit aligned. The default is 32-bit alignment.
8039
8040@item -mno-prologue-epilogue
8041@itemx -mprologue-epilogue
8042@opindex mno-prologue-epilogue
8043@opindex mprologue-epilogue
8044With @option{-mno-prologue-epilogue}, the normal function prologue and
8045epilogue that sets up the stack-frame are omitted and no return
8046instructions or return sequences are generated in the code. Use this
8047option only together with visual inspection of the compiled code: no
8048warnings or errors are generated when call-saved registers must be saved,
8049or storage for local variable needs to be allocated.
8050
8051@item -mno-gotplt
8052@itemx -mgotplt
8053@opindex mno-gotplt
8054@opindex mgotplt
8055With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
8056instruction sequences that load addresses for functions from the PLT part
8057of the GOT rather than (traditional on other architectures) calls to the
8058PLT@. The default is @option{-mgotplt}.
8059
8060@item -maout
8061@opindex maout
8062Legacy no-op option only recognized with the cris-axis-aout target.
8063
8064@item -melf
8065@opindex melf
8066Legacy no-op option only recognized with the cris-axis-elf and
8067cris-axis-linux-gnu targets.
8068
8069@item -melinux
8070@opindex melinux
8071Only recognized with the cris-axis-aout target, where it selects a
8072GNU/linux-like multilib, include files and instruction set for
8073@option{-march=v8}.
8074
8075@item -mlinux
8076@opindex mlinux
8077Legacy no-op option only recognized with the cris-axis-linux-gnu target.
8078
8079@item -sim
8080@opindex sim
8081This option, recognized for the cris-axis-aout and cris-axis-elf arranges
8082to link with input-output functions from a simulator library. Code,
8083initialized data and zero-initialized data are allocated consecutively.
8084
8085@item -sim2
8086@opindex sim2
8087Like @option{-sim}, but pass linker options to locate initialized data at
80880x40000000 and zero-initialized data at 0x80000000.
8089@end table
8090
8091@node CRX Options
8092@subsection CRX Options
8093@cindex CRX Options
8094
8095These options are defined specifically for the CRX ports.
8096
8097@table @gcctabopt
8098
8099@item -mmac
8100@opindex mmac
8101Enable the use of multiply-accumulate instructions. Disabled by default.
8102
8103@item -mpush-args
8104@opindex mpush-args
8105Push instructions will be used to pass outgoing arguments when functions
8106are called. Enabled by default.
8107@end table
8108
8109@node Darwin Options
8110@subsection Darwin Options
8111@cindex Darwin options
8112
8113These options are defined for all architectures running the Darwin operating
8114system.
8115
8116FSF GCC on Darwin does not create ``fat'' object files; it will create
8117an object file for the single architecture that it was built to
8118target. Apple's GCC on Darwin does create ``fat'' files if multiple
8119@option{-arch} options are used; it does so by running the compiler or
8120linker multiple times and joining the results together with
8121@file{lipo}.
8122
8123The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
8124@samp{i686}) is determined by the flags that specify the ISA
8125that GCC is targetting, like @option{-mcpu} or @option{-march}. The
8126@option{-force_cpusubtype_ALL} option can be used to override this.
8127
8128The Darwin tools vary in their behavior when presented with an ISA
8129mismatch. The assembler, @file{as}, will only permit instructions to
8130be used that are valid for the subtype of the file it is generating,
8131so you cannot put 64-bit instructions in an @samp{ppc750} object file.
8132The linker for shared libraries, @file{/usr/bin/libtool}, will fail
8133and print an error if asked to create a shared library with a less
8134restrictive subtype than its input files (for instance, trying to put
8135a @samp{ppc970} object file in a @samp{ppc7400} library). The linker
8136for executables, @file{ld}, will quietly give the executable the most
8137restrictive subtype of any of its input files.
8138
8139@table @gcctabopt
8140@item -F@var{dir}
8141@opindex F
8142Add the framework directory @var{dir} to the head of the list of
8143directories to be searched for header files. These directories are
8144interleaved with those specified by @option{-I} options and are
8145scanned in a left-to-right order.
8146
8147A framework directory is a directory with frameworks in it. A
8148framework is a directory with a @samp{"Headers"} and/or
8149@samp{"PrivateHeaders"} directory contained directly in it that ends
8150in @samp{".framework"}. The name of a framework is the name of this
8151directory excluding the @samp{".framework"}. Headers associated with
8152the framework are found in one of those two directories, with
8153@samp{"Headers"} being searched first. A subframework is a framework
8154directory that is in a framework's @samp{"Frameworks"} directory.
8155Includes of subframework headers can only appear in a header of a
8156framework that contains the subframework, or in a sibling subframework
8157header. Two subframeworks are siblings if they occur in the same
8158framework. A subframework should not have the same name as a
8159framework, a warning will be issued if this is violated. Currently a
8160subframework cannot have subframeworks, in the future, the mechanism
8161may be extended to support this. The standard frameworks can be found
8162in @samp{"/System/Library/Frameworks"} and
8163@samp{"/Library/Frameworks"}. An example include looks like
8164@code{#include <Framework/header.h>}, where @samp{Framework} denotes
8165the name of the framework and header.h is found in the
8166@samp{"PrivateHeaders"} or @samp{"Headers"} directory.
8167
8168@item -gused
8169@opindex gused
8170Emit debugging information for symbols that are used. For STABS
8171debugging format, this enables @option{-feliminate-unused-debug-symbols}.
8172This is by default ON@.
8173
8174@item -gfull
8175@opindex gfull
8176Emit debugging information for all symbols and types.
8177
8178@item -mmacosx-version-min=@var{version}
8179The earliest version of MacOS X that this executable will run on
8180is @var{version}. Typical values of @var{version} include @code{10.1},
8181@code{10.2}, and @code{10.3.9}.
8182
8183The default for this option is to make choices that seem to be most
8184useful.
8185
8186@item -mkernel
8187@opindex mkernel
8188Enable kernel development mode. The @option{-mkernel} option sets
8189@option{-static}, @option{-fno-common}, @option{-fno-cxa-atexit},
8190@option{-fno-exceptions}, @option{-fno-non-call-exceptions},
8191@option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where
8192applicable. This mode also sets @option{-mno-altivec},
8193@option{-msoft-float}, @option{-fno-builtin} and
8194@option{-mlong-branch} for PowerPC targets.
8195
8196@item -mone-byte-bool
8197@opindex mone-byte-bool
8198Override the defaults for @samp{bool} so that @samp{sizeof(bool)==1}.
8199By default @samp{sizeof(bool)} is @samp{4} when compiling for
8200Darwin/PowerPC and @samp{1} when compiling for Darwin/x86, so this
8201option has no effect on x86.
8202
8203@strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
8204to generate code that is not binary compatible with code generated
8205without that switch. Using this switch may require recompiling all
8206other modules in a program, including system libraries. Use this
8207switch to conform to a non-default data model.
8208
8209@item -mfix-and-continue
8210@itemx -ffix-and-continue
8211@itemx -findirect-data
8212@opindex mfix-and-continue
8213@opindex ffix-and-continue
8214@opindex findirect-data
8215Generate code suitable for fast turn around development. Needed to
8216enable gdb to dynamically load @code{.o} files into already running
8217programs. @option{-findirect-data} and @option{-ffix-and-continue}
8218are provided for backwards compatibility.
8219
8220@item -all_load
8221@opindex all_load
8222Loads all members of static archive libraries.
8223See man ld(1) for more information.
8224
8225@item -arch_errors_fatal
8226@opindex arch_errors_fatal
8227Cause the errors having to do with files that have the wrong architecture
8228to be fatal.
8229
8230@item -bind_at_load
8231@opindex bind_at_load
8232Causes the output file to be marked such that the dynamic linker will
8233bind all undefined references when the file is loaded or launched.
8234
8235@item -bundle
8236@opindex bundle
8237Produce a Mach-o bundle format file.
8238See man ld(1) for more information.
8239
8240@item -bundle_loader @var{executable}
8241@opindex bundle_loader
8242This option specifies the @var{executable} that will be loading the build
8243output file being linked. See man ld(1) for more information.
8244
8245@item -dynamiclib
8246@opindex dynamiclib
8247When passed this option, GCC will produce a dynamic library instead of
8248an executable when linking, using the Darwin @file{libtool} command.
8249
8250@item -force_cpusubtype_ALL
8251@opindex force_cpusubtype_ALL
8252This causes GCC's output file to have the @var{ALL} subtype, instead of
8253one controlled by the @option{-mcpu} or @option{-march} option.
8254
8255@item -allowable_client @var{client_name}
8256@itemx -client_name
8257@itemx -compatibility_version
8258@itemx -current_version
8259@itemx -dead_strip
8260@itemx -dependency-file
8261@itemx -dylib_file
8262@itemx -dylinker_install_name
8263@itemx -dynamic
8264@itemx -exported_symbols_list
8265@itemx -filelist
8266@itemx -flat_namespace
8267@itemx -force_flat_namespace
8268@itemx -headerpad_max_install_names
8269@itemx -image_base
8270@itemx -init
8271@itemx -install_name
8272@itemx -keep_private_externs
8273@itemx -multi_module
8274@itemx -multiply_defined
8275@itemx -multiply_defined_unused
8276@itemx -noall_load
8277@itemx -no_dead_strip_inits_and_terms
8278@itemx -nofixprebinding
8279@itemx -nomultidefs
8280@itemx -noprebind
8281@itemx -noseglinkedit
8282@itemx -pagezero_size
8283@itemx -prebind
8284@itemx -prebind_all_twolevel_modules
8285@itemx -private_bundle
8286@itemx -read_only_relocs
8287@itemx -sectalign
8288@itemx -sectobjectsymbols
8289@itemx -whyload
8290@itemx -seg1addr
8291@itemx -sectcreate
8292@itemx -sectobjectsymbols
8293@itemx -sectorder
8294@itemx -segaddr
8295@itemx -segs_read_only_addr
8296@itemx -segs_read_write_addr
8297@itemx -seg_addr_table
8298@itemx -seg_addr_table_filename
8299@itemx -seglinkedit
8300@itemx -segprot
8301@itemx -segs_read_only_addr
8302@itemx -segs_read_write_addr
8303@itemx -single_module
8304@itemx -static
8305@itemx -sub_library
8306@itemx -sub_umbrella
8307@itemx -twolevel_namespace
8308@itemx -umbrella
8309@itemx -undefined
8310@itemx -unexported_symbols_list
8311@itemx -weak_reference_mismatches
8312@itemx -whatsloaded
8313
8314@opindex allowable_client
8315@opindex client_name
8316@opindex compatibility_version
8317@opindex current_version
8318@opindex dead_strip
8319@opindex dependency-file
8320@opindex dylib_file
8321@opindex dylinker_install_name
8322@opindex dynamic
8323@opindex exported_symbols_list
8324@opindex filelist
8325@opindex flat_namespace
8326@opindex force_flat_namespace
8327@opindex headerpad_max_install_names
8328@opindex image_base
8329@opindex init
8330@opindex install_name
8331@opindex keep_private_externs
8332@opindex multi_module
8333@opindex multiply_defined
8334@opindex multiply_defined_unused
8335@opindex noall_load
8336@opindex no_dead_strip_inits_and_terms
8337@opindex nofixprebinding
8338@opindex nomultidefs
8339@opindex noprebind
8340@opindex noseglinkedit
8341@opindex pagezero_size
8342@opindex prebind
8343@opindex prebind_all_twolevel_modules
8344@opindex private_bundle
8345@opindex read_only_relocs
8346@opindex sectalign
8347@opindex sectobjectsymbols
8348@opindex whyload
8349@opindex seg1addr
8350@opindex sectcreate
8351@opindex sectobjectsymbols
8352@opindex sectorder
8353@opindex segaddr
8354@opindex segs_read_only_addr
8355@opindex segs_read_write_addr
8356@opindex seg_addr_table
8357@opindex seg_addr_table_filename
8358@opindex seglinkedit
8359@opindex segprot
8360@opindex segs_read_only_addr
8361@opindex segs_read_write_addr
8362@opindex single_module
8363@opindex static
8364@opindex sub_library
8365@opindex sub_umbrella
8366@opindex twolevel_namespace
8367@opindex umbrella
8368@opindex undefined
8369@opindex unexported_symbols_list
8370@opindex weak_reference_mismatches
8371@opindex whatsloaded
8372
8373These options are passed to the Darwin linker. The Darwin linker man page
8374describes them in detail.
8375@end table
8376
8377@node DEC Alpha Options
8378@subsection DEC Alpha Options
8379
8380These @samp{-m} options are defined for the DEC Alpha implementations:
8381
8382@table @gcctabopt
8383@item -mno-soft-float
8384@itemx -msoft-float
8385@opindex mno-soft-float
8386@opindex msoft-float
8387Use (do not use) the hardware floating-point instructions for
8388floating-point operations. When @option{-msoft-float} is specified,
8389functions in @file{libgcc.a} will be used to perform floating-point
8390operations. Unless they are replaced by routines that emulate the
8391floating-point operations, or compiled in such a way as to call such
8392emulations routines, these routines will issue floating-point
8393operations. If you are compiling for an Alpha without floating-point
8394operations, you must ensure that the library is built so as not to call
8395them.
8396
8397Note that Alpha implementations without floating-point operations are
8398required to have floating-point registers.
8399
8400@item -mfp-reg
8401@itemx -mno-fp-regs
8402@opindex mfp-reg
8403@opindex mno-fp-regs
8404Generate code that uses (does not use) the floating-point register set.
8405@option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
8406register set is not used, floating point operands are passed in integer
8407registers as if they were integers and floating-point results are passed
8408in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
8409so any function with a floating-point argument or return value called by code
8410compiled with @option{-mno-fp-regs} must also be compiled with that
8411option.
8412
8413A typical use of this option is building a kernel that does not use,
8414and hence need not save and restore, any floating-point registers.
8415
8416@item -mieee
8417@opindex mieee
8418The Alpha architecture implements floating-point hardware optimized for
8419maximum performance. It is mostly compliant with the IEEE floating
8420point standard. However, for full compliance, software assistance is
8421required. This option generates code fully IEEE compliant code
8422@emph{except} that the @var{inexact-flag} is not maintained (see below).
8423If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
8424defined during compilation. The resulting code is less efficient but is
8425able to correctly support denormalized numbers and exceptional IEEE
8426values such as not-a-number and plus/minus infinity. Other Alpha
8427compilers call this option @option{-ieee_with_no_inexact}.
8428
8429@item -mieee-with-inexact
8430@opindex mieee-with-inexact
8431This is like @option{-mieee} except the generated code also maintains
8432the IEEE @var{inexact-flag}. Turning on this option causes the
8433generated code to implement fully-compliant IEEE math. In addition to
8434@code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
8435macro. On some Alpha implementations the resulting code may execute
8436significantly slower than the code generated by default. Since there is
8437very little code that depends on the @var{inexact-flag}, you should
8438normally not specify this option. Other Alpha compilers call this
8439option @option{-ieee_with_inexact}.
8440
8441@item -mfp-trap-mode=@var{trap-mode}
8442@opindex mfp-trap-mode
8443This option controls what floating-point related traps are enabled.
8444Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
8445The trap mode can be set to one of four values:
8446
8447@table @samp
8448@item n
8449This is the default (normal) setting. The only traps that are enabled
8450are the ones that cannot be disabled in software (e.g., division by zero
8451trap).
8452
8453@item u
8454In addition to the traps enabled by @samp{n}, underflow traps are enabled
8455as well.
8456
8457@item su
8458Like @samp{u}, but the instructions are marked to be safe for software
8459completion (see Alpha architecture manual for details).
8460
8461@item sui
8462Like @samp{su}, but inexact traps are enabled as well.
8463@end table
8464
8465@item -mfp-rounding-mode=@var{rounding-mode}
8466@opindex mfp-rounding-mode
8467Selects the IEEE rounding mode. Other Alpha compilers call this option
8468@option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
8469of:
8470
8471@table @samp
8472@item n
8473Normal IEEE rounding mode. Floating point numbers are rounded towards
8474the nearest machine number or towards the even machine number in case
8475of a tie.
8476
8477@item m
8478Round towards minus infinity.
8479
8480@item c
8481Chopped rounding mode. Floating point numbers are rounded towards zero.
8482
8483@item d
8484Dynamic rounding mode. A field in the floating point control register
8485(@var{fpcr}, see Alpha architecture reference manual) controls the
8486rounding mode in effect. The C library initializes this register for
8487rounding towards plus infinity. Thus, unless your program modifies the
8488@var{fpcr}, @samp{d} corresponds to round towards plus infinity.
8489@end table
8490
8491@item -mtrap-precision=@var{trap-precision}
8492@opindex mtrap-precision
8493In the Alpha architecture, floating point traps are imprecise. This
8494means without software assistance it is impossible to recover from a
8495floating trap and program execution normally needs to be terminated.
8496GCC can generate code that can assist operating system trap handlers
8497in determining the exact location that caused a floating point trap.
8498Depending on the requirements of an application, different levels of
8499precisions can be selected:
8500
8501@table @samp
8502@item p
8503Program precision. This option is the default and means a trap handler
8504can only identify which program caused a floating point exception.
8505
8506@item f
8507Function precision. The trap handler can determine the function that
8508caused a floating point exception.
8509
8510@item i
8511Instruction precision. The trap handler can determine the exact
8512instruction that caused a floating point exception.
8513@end table
8514
8515Other Alpha compilers provide the equivalent options called
8516@option{-scope_safe} and @option{-resumption_safe}.
8517
8518@item -mieee-conformant
8519@opindex mieee-conformant
8520This option marks the generated code as IEEE conformant. You must not
8521use this option unless you also specify @option{-mtrap-precision=i} and either
8522@option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
8523is to emit the line @samp{.eflag 48} in the function prologue of the
8524generated assembly file. Under DEC Unix, this has the effect that
8525IEEE-conformant math library routines will be linked in.
8526
8527@item -mbuild-constants
8528@opindex mbuild-constants
8529Normally GCC examines a 32- or 64-bit integer constant to
8530see if it can construct it from smaller constants in two or three
8531instructions. If it cannot, it will output the constant as a literal and
8532generate code to load it from the data segment at runtime.
8533
8534Use this option to require GCC to construct @emph{all} integer constants
8535using code, even if it takes more instructions (the maximum is six).
8536
8537You would typically use this option to build a shared library dynamic
8538loader. Itself a shared library, it must relocate itself in memory
8539before it can find the variables and constants in its own data segment.
8540
8541@item -malpha-as
8542@itemx -mgas
8543@opindex malpha-as
8544@opindex mgas
8545Select whether to generate code to be assembled by the vendor-supplied
8546assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
8547
8548@item -mbwx
8549@itemx -mno-bwx
8550@itemx -mcix
8551@itemx -mno-cix
8552@itemx -mfix
8553@itemx -mno-fix
8554@itemx -mmax
8555@itemx -mno-max
8556@opindex mbwx
8557@opindex mno-bwx
8558@opindex mcix
8559@opindex mno-cix
8560@opindex mfix
8561@opindex mno-fix
8562@opindex mmax
8563@opindex mno-max
8564Indicate whether GCC should generate code to use the optional BWX,
8565CIX, FIX and MAX instruction sets. The default is to use the instruction
8566sets supported by the CPU type specified via @option{-mcpu=} option or that
8567of the CPU on which GCC was built if none was specified.
8568
8569@item -mfloat-vax
8570@itemx -mfloat-ieee
8571@opindex mfloat-vax
8572@opindex mfloat-ieee
8573Generate code that uses (does not use) VAX F and G floating point
8574arithmetic instead of IEEE single and double precision.
8575
8576@item -mexplicit-relocs
8577@itemx -mno-explicit-relocs
8578@opindex mexplicit-relocs
8579@opindex mno-explicit-relocs
8580Older Alpha assemblers provided no way to generate symbol relocations
8581except via assembler macros. Use of these macros does not allow
8582optimal instruction scheduling. GNU binutils as of version 2.12
8583supports a new syntax that allows the compiler to explicitly mark
8584which relocations should apply to which instructions. This option
8585is mostly useful for debugging, as GCC detects the capabilities of
8586the assembler when it is built and sets the default accordingly.
8587
8588@item -msmall-data
8589@itemx -mlarge-data
8590@opindex msmall-data
8591@opindex mlarge-data
8592When @option{-mexplicit-relocs} is in effect, static data is
8593accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
8594is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
8595(the @code{.sdata} and @code{.sbss} sections) and are accessed via
859616-bit relocations off of the @code{$gp} register. This limits the
8597size of the small data area to 64KB, but allows the variables to be
8598directly accessed via a single instruction.
8599
8600The default is @option{-mlarge-data}. With this option the data area
8601is limited to just below 2GB@. Programs that require more than 2GB of
8602data must use @code{malloc} or @code{mmap} to allocate the data in the
8603heap instead of in the program's data segment.
8604
8605When generating code for shared libraries, @option{-fpic} implies
8606@option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
8607
8608@item -msmall-text
8609@itemx -mlarge-text
8610@opindex msmall-text
8611@opindex mlarge-text
8612When @option{-msmall-text} is used, the compiler assumes that the
8613code of the entire program (or shared library) fits in 4MB, and is
8614thus reachable with a branch instruction. When @option{-msmall-data}
8615is used, the compiler can assume that all local symbols share the
8616same @code{$gp} value, and thus reduce the number of instructions
8617required for a function call from 4 to 1.
8618
8619The default is @option{-mlarge-text}.
8620
8621@item -mcpu=@var{cpu_type}
8622@opindex mcpu
8623Set the instruction set and instruction scheduling parameters for
8624machine type @var{cpu_type}. You can specify either the @samp{EV}
8625style name or the corresponding chip number. GCC supports scheduling
8626parameters for the EV4, EV5 and EV6 family of processors and will
8627choose the default values for the instruction set from the processor
8628you specify. If you do not specify a processor type, GCC will default
8629to the processor on which the compiler was built.
8630
8631Supported values for @var{cpu_type} are
8632
8633@table @samp
8634@item ev4
8635@itemx ev45
8636@itemx 21064
8637Schedules as an EV4 and has no instruction set extensions.
8638
8639@item ev5
8640@itemx 21164
8641Schedules as an EV5 and has no instruction set extensions.
8642
8643@item ev56
8644@itemx 21164a
8645Schedules as an EV5 and supports the BWX extension.
8646
8647@item pca56
8648@itemx 21164pc
8649@itemx 21164PC
8650Schedules as an EV5 and supports the BWX and MAX extensions.
8651
8652@item ev6
8653@itemx 21264
8654Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
8655
8656@item ev67
8657@itemx 21264a
8658Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
8659@end table
8660
8661@item -mtune=@var{cpu_type}
8662@opindex mtune
8663Set only the instruction scheduling parameters for machine type
8664@var{cpu_type}. The instruction set is not changed.
8665
8666@item -mmemory-latency=@var{time}
8667@opindex mmemory-latency
8668Sets the latency the scheduler should assume for typical memory
8669references as seen by the application. This number is highly
8670dependent on the memory access patterns used by the application
8671and the size of the external cache on the machine.
8672
8673Valid options for @var{time} are
8674
8675@table @samp
8676@item @var{number}
8677A decimal number representing clock cycles.
8678
8679@item L1
8680@itemx L2
8681@itemx L3
8682@itemx main
8683The compiler contains estimates of the number of clock cycles for
8684``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
8685(also called Dcache, Scache, and Bcache), as well as to main memory.
8686Note that L3 is only valid for EV5.
8687
8688@end table
8689@end table
8690
8691@node DEC Alpha/VMS Options
8692@subsection DEC Alpha/VMS Options
8693
8694These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
8695
8696@table @gcctabopt
8697@item -mvms-return-codes
8698@opindex mvms-return-codes
8699Return VMS condition codes from main. The default is to return POSIX
8700style condition (e.g.@ error) codes.
8701@end table
8702
8703@node FRV Options
8704@subsection FRV Options
8705@cindex FRV Options
8706
8707@table @gcctabopt
8708@item -mgpr-32
8709@opindex mgpr-32
8710
8711Only use the first 32 general purpose registers.
8712
8713@item -mgpr-64
8714@opindex mgpr-64
8715
8716Use all 64 general purpose registers.
8717
8718@item -mfpr-32
8719@opindex mfpr-32
8720
8721Use only the first 32 floating point registers.
8722
8723@item -mfpr-64
8724@opindex mfpr-64
8725
8726Use all 64 floating point registers
8727
8728@item -mhard-float
8729@opindex mhard-float
8730
8731Use hardware instructions for floating point operations.
8732
8733@item -msoft-float
8734@opindex msoft-float
8735
8736Use library routines for floating point operations.
8737
8738@item -malloc-cc
8739@opindex malloc-cc
8740
8741Dynamically allocate condition code registers.
8742
8743@item -mfixed-cc
8744@opindex mfixed-cc
8745
8746Do not try to dynamically allocate condition code registers, only
8747use @code{icc0} and @code{fcc0}.
8748
8749@item -mdword
8750@opindex mdword
8751
8752Change ABI to use double word insns.
8753
8754@item -mno-dword
8755@opindex mno-dword
8756
8757Do not use double word instructions.
8758
8759@item -mdouble
8760@opindex mdouble
8761
8762Use floating point double instructions.
8763
8764@item -mno-double
8765@opindex mno-double
8766
8767Do not use floating point double instructions.
8768
8769@item -mmedia
8770@opindex mmedia
8771
8772Use media instructions.
8773
8774@item -mno-media
8775@opindex mno-media
8776
8777Do not use media instructions.
8778
8779@item -mmuladd
8780@opindex mmuladd
8781
8782Use multiply and add/subtract instructions.
8783
8784@item -mno-muladd
8785@opindex mno-muladd
8786
8787Do not use multiply and add/subtract instructions.
8788
8789@item -mfdpic
8790@opindex mfdpic
8791
8792Select the FDPIC ABI, that uses function descriptors to represent
8793pointers to functions. Without any PIC/PIE-related options, it
8794implies @option{-fPIE}. With @option{-fpic} or @option{-fpie}, it
8795assumes GOT entries and small data are within a 12-bit range from the
8796GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
8797are computed with 32 bits.
8798
8799@item -minline-plt
8800@opindex minline-plt
8801
8802Enable inlining of PLT entries in function calls to functions that are
8803not known to bind locally. It has no effect without @option{-mfdpic}.
8804It's enabled by default if optimizing for speed and compiling for
8805shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
8806optimization option such as @option{-O3} or above is present in the
8807command line.
8808
8809@item -mTLS
8810@opindex TLS
8811
8812Assume a large TLS segment when generating thread-local code.
8813
8814@item -mtls
8815@opindex tls
8816
8817Do not assume a large TLS segment when generating thread-local code.
8818
8819@item -mgprel-ro
8820@opindex mgprel-ro
8821
8822Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
8823that is known to be in read-only sections. It's enabled by default,
8824except for @option{-fpic} or @option{-fpie}: even though it may help
8825make the global offset table smaller, it trades 1 instruction for 4.
8826With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
8827one of which may be shared by multiple symbols, and it avoids the need
8828for a GOT entry for the referenced symbol, so it's more likely to be a
8829win. If it is not, @option{-mno-gprel-ro} can be used to disable it.
8830
8831@item -multilib-library-pic
8832@opindex multilib-library-pic
8833
8834Link with the (library, not FD) pic libraries. It's implied by
8835@option{-mlibrary-pic}, as well as by @option{-fPIC} and
8836@option{-fpic} without @option{-mfdpic}. You should never have to use
8837it explicitly.
8838
8839@item -mlinked-fp
8840@opindex mlinked-fp
8841
8842Follow the EABI requirement of always creating a frame pointer whenever
8843a stack frame is allocated. This option is enabled by default and can
8844be disabled with @option{-mno-linked-fp}.
8845
8846@item -mlong-calls
8847@opindex mlong-calls
8848
8849Use indirect addressing to call functions outside the current
8850compilation unit. This allows the functions to be placed anywhere
8851within the 32-bit address space.
8852
8853@item -malign-labels
8854@opindex malign-labels
8855
8856Try to align labels to an 8-byte boundary by inserting nops into the
8857previous packet. This option only has an effect when VLIW packing
8858is enabled. It doesn't create new packets; it merely adds nops to
8859existing ones.
8860
8861@item -mlibrary-pic
8862@opindex mlibrary-pic
8863
8864Generate position-independent EABI code.
8865
8866@item -macc-4
8867@opindex macc-4
8868
8869Use only the first four media accumulator registers.
8870
8871@item -macc-8
8872@opindex macc-8
8873
8874Use all eight media accumulator registers.
8875
8876@item -mpack
8877@opindex mpack
8878
8879Pack VLIW instructions.
8880
8881@item -mno-pack
8882@opindex mno-pack
8883
8884Do not pack VLIW instructions.
8885
8886@item -mno-eflags
8887@opindex mno-eflags
8888
8889Do not mark ABI switches in e_flags.
8890
8891@item -mcond-move
8892@opindex mcond-move
8893
8894Enable the use of conditional-move instructions (default).
8895
8896This switch is mainly for debugging the compiler and will likely be removed
8897in a future version.
8898
8899@item -mno-cond-move
8900@opindex mno-cond-move
8901
8902Disable the use of conditional-move instructions.
8903
8904This switch is mainly for debugging the compiler and will likely be removed
8905in a future version.
8906
8907@item -mscc
8908@opindex mscc
8909
8910Enable the use of conditional set instructions (default).
8911
8912This switch is mainly for debugging the compiler and will likely be removed
8913in a future version.
8914
8915@item -mno-scc
8916@opindex mno-scc
8917
8918Disable the use of conditional set instructions.
8919
8920This switch is mainly for debugging the compiler and will likely be removed
8921in a future version.
8922
8923@item -mcond-exec
8924@opindex mcond-exec
8925
8926Enable the use of conditional execution (default).
8927
8928This switch is mainly for debugging the compiler and will likely be removed
8929in a future version.
8930
8931@item -mno-cond-exec
8932@opindex mno-cond-exec
8933
8934Disable the use of conditional execution.
8935
8936This switch is mainly for debugging the compiler and will likely be removed
8937in a future version.
8938
8939@item -mvliw-branch
8940@opindex mvliw-branch
8941
8942Run a pass to pack branches into VLIW instructions (default).
8943
8944This switch is mainly for debugging the compiler and will likely be removed
8945in a future version.
8946
8947@item -mno-vliw-branch
8948@opindex mno-vliw-branch
8949
8950Do not run a pass to pack branches into VLIW instructions.
8951
8952This switch is mainly for debugging the compiler and will likely be removed
8953in a future version.
8954
8955@item -mmulti-cond-exec
8956@opindex mmulti-cond-exec
8957
8958Enable optimization of @code{&&} and @code{||} in conditional execution
8959(default).
8960
8961This switch is mainly for debugging the compiler and will likely be removed
8962in a future version.
8963
8964@item -mno-multi-cond-exec
8965@opindex mno-multi-cond-exec
8966
8967Disable optimization of @code{&&} and @code{||} in conditional execution.
8968
8969This switch is mainly for debugging the compiler and will likely be removed
8970in a future version.
8971
8972@item -mnested-cond-exec
8973@opindex mnested-cond-exec
8974
8975Enable nested conditional execution optimizations (default).
8976
8977This switch is mainly for debugging the compiler and will likely be removed
8978in a future version.
8979
8980@item -mno-nested-cond-exec
8981@opindex mno-nested-cond-exec
8982
8983Disable nested conditional execution optimizations.
8984
8985This switch is mainly for debugging the compiler and will likely be removed
8986in a future version.
8987
8988@item -moptimize-membar
8989@opindex moptimize-membar
8990
8991This switch removes redundant @code{membar} instructions from the
8992compiler generated code. It is enabled by default.
8993
8994@item -mno-optimize-membar
8995@opindex mno-optimize-membar
8996
8997This switch disables the automatic removal of redundant @code{membar}
8998instructions from the generated code.
8999
9000@item -mtomcat-stats
9001@opindex mtomcat-stats
9002
9003Cause gas to print out tomcat statistics.
9004
9005@item -mcpu=@var{cpu}
9006@opindex mcpu
9007
9008Select the processor type for which to generate code. Possible values are
9009@samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
9010@samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
9011
9012@end table
9013
9014@node GNU/Linux Options
9015@subsection GNU/Linux Options
9016
9017These @samp{-m} options are defined for GNU/Linux targets:
9018
9019@table @gcctabopt
9020@item -mglibc
9021@opindex mglibc
9022Use the GNU C library instead of uClibc. This is the default except
9023on @samp{*-*-linux-*uclibc*} targets.
9024
9025@item -muclibc
9026@opindex muclibc
9027Use uClibc instead of the GNU C library. This is the default on
9028@samp{*-*-linux-*uclibc*} targets.
9029@end table
9030
9031@node H8/300 Options
9032@subsection H8/300 Options
9033
9034These @samp{-m} options are defined for the H8/300 implementations:
9035
9036@table @gcctabopt
9037@item -mrelax
9038@opindex mrelax
9039Shorten some address references at link time, when possible; uses the
9040linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
9041ld, Using ld}, for a fuller description.
9042
9043@item -mh
9044@opindex mh
9045Generate code for the H8/300H@.
9046
9047@item -ms
9048@opindex ms
9049Generate code for the H8S@.
9050
9051@item -mn
9052@opindex mn
9053Generate code for the H8S and H8/300H in the normal mode. This switch
9054must be used either with @option{-mh} or @option{-ms}.
9055
9056@item -ms2600
9057@opindex ms2600
9058Generate code for the H8S/2600. This switch must be used with @option{-ms}.
9059
9060@item -mint32
9061@opindex mint32
9062Make @code{int} data 32 bits by default.
9063
9064@item -malign-300
9065@opindex malign-300
9066On the H8/300H and H8S, use the same alignment rules as for the H8/300.
9067The default for the H8/300H and H8S is to align longs and floats on 4
9068byte boundaries.
9069@option{-malign-300} causes them to be aligned on 2 byte boundaries.
9070This option has no effect on the H8/300.
9071@end table
9072
9073@node HPPA Options
9074@subsection HPPA Options
9075@cindex HPPA Options
9076
9077These @samp{-m} options are defined for the HPPA family of computers:
9078
9079@table @gcctabopt
9080@item -march=@var{architecture-type}
9081@opindex march
9082Generate code for the specified architecture. The choices for
9083@var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
90841.1, and @samp{2.0} for PA 2.0 processors. Refer to
9085@file{/usr/lib/sched.models} on an HP-UX system to determine the proper
9086architecture option for your machine. Code compiled for lower numbered
9087architectures will run on higher numbered architectures, but not the
9088other way around.
9089
9090@item -mpa-risc-1-0
9091@itemx -mpa-risc-1-1
9092@itemx -mpa-risc-2-0
9093@opindex mpa-risc-1-0
9094@opindex mpa-risc-1-1
9095@opindex mpa-risc-2-0
9096Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
9097
9098@item -mbig-switch
9099@opindex mbig-switch
9100Generate code suitable for big switch tables. Use this option only if
9101the assembler/linker complain about out of range branches within a switch
9102table.
9103
9104@item -mjump-in-delay
9105@opindex mjump-in-delay
9106Fill delay slots of function calls with unconditional jump instructions
9107by modifying the return pointer for the function call to be the target
9108of the conditional jump.
9109
9110@item -mdisable-fpregs
9111@opindex mdisable-fpregs
9112Prevent floating point registers from being used in any manner. This is
9113necessary for compiling kernels which perform lazy context switching of
9114floating point registers. If you use this option and attempt to perform
9115floating point operations, the compiler will abort.
9116
9117@item -mdisable-indexing
9118@opindex mdisable-indexing
9119Prevent the compiler from using indexing address modes. This avoids some
9120rather obscure problems when compiling MIG generated code under MACH@.
9121
9122@item -mno-space-regs
9123@opindex mno-space-regs
9124Generate code that assumes the target has no space registers. This allows
9125GCC to generate faster indirect calls and use unscaled index address modes.
9126
9127Such code is suitable for level 0 PA systems and kernels.
9128
9129@item -mfast-indirect-calls
9130@opindex mfast-indirect-calls
9131Generate code that assumes calls never cross space boundaries. This
9132allows GCC to emit code which performs faster indirect calls.
9133
9134This option will not work in the presence of shared libraries or nested
9135functions.
9136
9137@item -mfixed-range=@var{register-range}
9138@opindex mfixed-range
9139Generate code treating the given register range as fixed registers.
9140A fixed register is one that the register allocator can not use. This is
9141useful when compiling kernel code. A register range is specified as
9142two registers separated by a dash. Multiple register ranges can be
9143specified separated by a comma.
9144
9145@item -mlong-load-store
9146@opindex mlong-load-store
9147Generate 3-instruction load and store sequences as sometimes required by
9148the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
9149the HP compilers.
9150
9151@item -mportable-runtime
9152@opindex mportable-runtime
9153Use the portable calling conventions proposed by HP for ELF systems.
9154
9155@item -mgas
9156@opindex mgas
9157Enable the use of assembler directives only GAS understands.
9158
9159@item -mschedule=@var{cpu-type}
9160@opindex mschedule
9161Schedule code according to the constraints for the machine type
9162@var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
9163@samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer
9164to @file{/usr/lib/sched.models} on an HP-UX system to determine the
9165proper scheduling option for your machine. The default scheduling is
9166@samp{8000}.
9167
9168@item -mlinker-opt
9169@opindex mlinker-opt
9170Enable the optimization pass in the HP-UX linker. Note this makes symbolic
9171debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9
9172linkers in which they give bogus error messages when linking some programs.
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 available for all HPPA
9178targets. Normally the facilities of the machine's usual C compiler are
9179used, but this cannot be done directly in cross-compilation. You must make
9180your own arrangements to provide suitable library functions for
9181cross-compilation. The embedded target @samp{hppa1.1-*-pro}
9182does provide software floating point support.
9183
9184@option{-msoft-float} changes the calling convention in the output file;
9185therefore, it is only useful if you compile @emph{all} of a program with
9186this option. In particular, you need to compile @file{libgcc.a}, the
9187library that comes with GCC, with @option{-msoft-float} in order for
9188this to work.
9189
9190@item -msio
9191@opindex msio
9192Generate the predefine, @code{_SIO}, for server IO@. The default is
9193@option{-mwsio}. This generates the predefines, @code{__hp9000s700},
9194@code{__hp9000s700__} and @code{_WSIO}, for workstation IO@. These
9195options are available under HP-UX and HI-UX@.
9196
9197@item -mgnu-ld
9198@opindex gnu-ld
9199Use GNU ld specific options. This passes @option{-shared} to ld when
9200building a shared library. It is the default when GCC is configured,
9201explicitly or implicitly, with the GNU linker. This option does not
9202have any affect on which ld is called, it only changes what parameters
9203are passed to that ld. The ld that is called is determined by the
9204@option{--with-ld} configure option, GCC's program search path, and
9205finally by the user's @env{PATH}. The linker used by GCC can be printed
9206using @samp{which `gcc -print-prog-name=ld`}. This option is only available
9207on the 64 bit HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
9208
9209@item -mhp-ld
9210@opindex hp-ld
9211Use HP ld specific options. This passes @option{-b} to ld when building
9212a shared library and passes @option{+Accept TypeMismatch} to ld on all
9213links. It is the default when GCC is configured, explicitly or
9214implicitly, with the HP linker. This option does not have any affect on
9215which ld is called, it only changes what parameters are passed to that
9216ld. The ld that is called is determined by the @option{--with-ld}
9217configure option, GCC's program search path, and finally by the user's
9218@env{PATH}. The linker used by GCC can be printed using @samp{which
9219`gcc -print-prog-name=ld`}. This option is only available on the 64 bit
9220HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
9221
9222@item -mlong-calls
9223@opindex mno-long-calls
9224Generate code that uses long call sequences. This ensures that a call
9225is always able to reach linker generated stubs. The default is to generate
9226long calls only when the distance from the call site to the beginning
9227of the function or translation unit, as the case may be, exceeds a
9228predefined limit set by the branch type being used. The limits for
9229normal calls are 7,600,000 and 240,000 bytes, respectively for the
9230PA 2.0 and PA 1.X architectures. Sibcalls are always limited at
9231240,000 bytes.
9232
9233Distances are measured from the beginning of functions when using the
9234@option{-ffunction-sections} option, or when using the @option{-mgas}
9235and @option{-mno-portable-runtime} options together under HP-UX with
9236the SOM linker.
9237
9238It is normally not desirable to use this option as it will degrade
9239performance. However, it may be useful in large applications,
9240particularly when partial linking is used to build the application.
9241
9242The types of long calls used depends on the capabilities of the
9243assembler and linker, and the type of code being generated. The
9244impact on systems that support long absolute calls, and long pic
9245symbol-difference or pc-relative calls should be relatively small.
9246However, an indirect call is used on 32-bit ELF systems in pic code
9247and it is quite long.
9248
9249@item -munix=@var{unix-std}
9250@opindex march
9251Generate compiler predefines and select a startfile for the specified
9252UNIX standard. The choices for @var{unix-std} are @samp{93}, @samp{95}
9253and @samp{98}. @samp{93} is supported on all HP-UX versions. @samp{95}
9254is available on HP-UX 10.10 and later. @samp{98} is available on HP-UX
925511.11 and later. The default values are @samp{93} for HP-UX 10.00,
9256@samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
9257and later.
9258
9259@option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
9260@option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
9261and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
9262@option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
9263@code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
9264@code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
9265
9266It is @emph{important} to note that this option changes the interfaces
9267for various library routines. It also affects the operational behavior
9268of the C library. Thus, @emph{extreme} care is needed in using this
9269option.
9270
9271Library code that is intended to operate with more than one UNIX
9272standard must test, set and restore the variable @var{__xpg4_extended_mask}
9273as appropriate. Most GNU software doesn't provide this capability.
9274
9275@item -nolibdld
9276@opindex nolibdld
9277Suppress the generation of link options to search libdld.sl when the
9278@option{-static} option is specified on HP-UX 10 and later.
9279
9280@item -static
9281@opindex static
9282The HP-UX implementation of setlocale in libc has a dependency on
9283libdld.sl. There isn't an archive version of libdld.sl. Thus,
9284when the @option{-static} option is specified, special link options
9285are needed to resolve this dependency.
9286
9287On HP-UX 10 and later, the GCC driver adds the necessary options to
9288link with libdld.sl when the @option{-static} option is specified.
9289This causes the resulting binary to be dynamic. On the 64-bit port,
9290the linkers generate dynamic binaries by default in any case. The
9291@option{-nolibdld} option can be used to prevent the GCC driver from
9292adding these link options.
9293
9294@item -threads
9295@opindex threads
9296Add support for multithreading with the @dfn{dce thread} library
9297under HP-UX@. This option sets flags for both the preprocessor and
9298linker.
9299@end table
9300
9301@node i386 and x86-64 Options
9302@subsection Intel 386 and AMD x86-64 Options
9303@cindex i386 Options
9304@cindex x86-64 Options
9305@cindex Intel 386 Options
9306@cindex AMD x86-64 Options
9307
9308These @samp{-m} options are defined for the i386 and x86-64 family of
9309computers:
9310
9311@table @gcctabopt
9312@item -mtune=@var{cpu-type}
9313@opindex mtune
9314Tune to @var{cpu-type} everything applicable about the generated code, except
9315for the ABI and the set of available instructions. The choices for
9316@var{cpu-type} are:
9317@table @emph
9318@item generic
9319Produce code optimized for the most common IA32/AMD64/EM64T processors.
9320If you know the CPU on which your code will run, then you should use
9321the corresponding @option{-mtune} option instead of
9322@option{-mtune=generic}. But, if you do not know exactly what CPU users
9323of your application will have, then you should use this option.
9324
9325As new processors are deployed in the marketplace, the behavior of this
9326option will change. Therefore, if you upgrade to a newer version of
9327GCC, the code generated option will change to reflect the processors
9328that were most common when that version of GCC was released.
9329
9330There is no @option{-march=generic} option because @option{-march}
9331indicates the instruction set the compiler can use, and there is no
9332generic instruction set applicable to all processors. In contrast,
9333@option{-mtune} indicates the processor (or, in this case, collection of
9334processors) for which the code is optimized.
9335@item native
9336This selects the CPU to tune for at compilation time by determining
9337the processor type of the compiling machine. Using @option{-mtune=native}
9338will produce code optimized for the local machine under the constraints
9339of the selected instruction set. Using @option{-march=native} will
9340enable all instruction subsets supported by the local machine (hence
9341the result might not run on different machines).
9342@item i386
9343Original Intel's i386 CPU@.
9344@item i486
9345Intel's i486 CPU@. (No scheduling is implemented for this chip.)
9346@item i586, pentium
9347Intel Pentium CPU with no MMX support.
9348@item pentium-mmx
9349Intel PentiumMMX CPU based on Pentium core with MMX instruction set support.
9350@item pentiumpro
9351Intel PentiumPro CPU@.
9352@item i686
9353Same as @code{generic}, but when used as @code{march} option, PentiumPro
9354instruction set will be used, so the code will run on all i686 family chips.
9355@item pentium2
9356Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support.
9357@item pentium3, pentium3m
9358Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set
9359support.
9360@item pentium-m
9361Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set
9362support. Used by Centrino notebooks.
9363@item pentium4, pentium4m
9364Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support.
9365@item prescott
9366Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction
9367set support.
9368@item nocona
9369Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE,
9370SSE2 and SSE3 instruction set support.
9371@item k6
9372AMD K6 CPU with MMX instruction set support.
9373@item k6-2, k6-3
9374Improved versions of AMD K6 CPU with MMX and 3dNOW! instruction set support.
9375@item athlon, athlon-tbird
9376AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and SSE prefetch instructions
9377support.
9378@item athlon-4, athlon-xp, athlon-mp
9379Improved AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and full SSE
9380instruction set support.
9381@item k8, opteron, athlon64, athlon-fx
9382AMD K8 core based CPUs with x86-64 instruction set support. (This supersets
9383MMX, SSE, SSE2, 3dNOW!, enhanced 3dNOW! and 64-bit instruction set extensions.)
9384@item winchip-c6
9385IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction
9386set support.
9387@item winchip2
9388IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3dNOW!
9389instruction set support.
9390@item c3
9391Via C3 CPU with MMX and 3dNOW! instruction set support. (No scheduling is
9392implemented for this chip.)
9393@item c3-2
9394Via C3-2 CPU with MMX and SSE instruction set support. (No scheduling is
9395implemented for this chip.)
9396@end table
9397
9398While picking a specific @var{cpu-type} will schedule things appropriately
9399for that particular chip, the compiler will not generate any code that
9400does not run on the i386 without the @option{-march=@var{cpu-type}} option
9401being used.
9402
9403@item -march=@var{cpu-type}
9404@opindex march
9405Generate instructions for the machine type @var{cpu-type}. The choices
9406for @var{cpu-type} are the same as for @option{-mtune}. Moreover,
9407specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}.
9408
9409@item -mcpu=@var{cpu-type}
9410@opindex mcpu
9411A deprecated synonym for @option{-mtune}.
9412
9413@item -m386
9414@itemx -m486
9415@itemx -mpentium
9416@itemx -mpentiumpro
9417@opindex m386
9418@opindex m486
9419@opindex mpentium
9420@opindex mpentiumpro
9421These options are synonyms for @option{-mtune=i386}, @option{-mtune=i486},
9422@option{-mtune=pentium}, and @option{-mtune=pentiumpro} respectively.
9423These synonyms are deprecated.
9424
9425@item -mfpmath=@var{unit}
9426@opindex march
9427Generate floating point arithmetics for selected unit @var{unit}. The choices
9428for @var{unit} are:
9429
9430@table @samp
9431@item 387
9432Use the standard 387 floating point coprocessor present majority of chips and
9433emulated otherwise. Code compiled with this option will run almost everywhere.
9434The temporary results are computed in 80bit precision instead of precision
9435specified by the type resulting in slightly different results compared to most
9436of other chips. See @option{-ffloat-store} for more detailed description.
9437
9438This is the default choice for i386 compiler.
9439
9440@item sse
9441Use scalar floating point instructions present in the SSE instruction set.
9442This instruction set is supported by Pentium3 and newer chips, in the AMD line
9443by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE
9444instruction set supports only single precision arithmetics, thus the double and
9445extended precision arithmetics is still done using 387. Later version, present
9446only in Pentium4 and the future AMD x86-64 chips supports double precision
9447arithmetics too.
9448
9449For the i386 compiler, you need to use @option{-march=@var{cpu-type}}, @option{-msse}
9450or @option{-msse2} switches to enable SSE extensions and make this option
9451effective. For the x86-64 compiler, these extensions are enabled by default.
9452
9453The resulting code should be considerably faster in the majority of cases and avoid
9454the numerical instability problems of 387 code, but may break some existing
9455code that expects temporaries to be 80bit.
9456
9457This is the default choice for the x86-64 compiler.
9458
9459@item sse,387
9460Attempt to utilize both instruction sets at once. This effectively double the
9461amount of available registers and on chips with separate execution units for
9462387 and SSE the execution resources too. Use this option with care, as it is
9463still experimental, because the GCC register allocator does not model separate
9464functional units well resulting in instable performance.
9465@end table
9466
9467@item -masm=@var{dialect}
9468@opindex masm=@var{dialect}
9469Output asm instructions using selected @var{dialect}. Supported
9470choices are @samp{intel} or @samp{att} (the default one). Darwin does
9471not support @samp{intel}.
9472
9473@item -mieee-fp
9474@itemx -mno-ieee-fp
9475@opindex mieee-fp
9476@opindex mno-ieee-fp
9477Control whether or not the compiler uses IEEE floating point
9478comparisons. These handle correctly the case where the result of a
9479comparison is unordered.
9480
9481@item -msoft-float
9482@opindex msoft-float
9483Generate output containing library calls for floating point.
9484@strong{Warning:} the requisite libraries are not part of GCC@.
9485Normally the facilities of the machine's usual C compiler are used, but
9486this can't be done directly in cross-compilation. You must make your
9487own arrangements to provide suitable library functions for
9488cross-compilation.
9489
9490On machines where a function returns floating point results in the 80387
9491register stack, some floating point opcodes may be emitted even if
9492@option{-msoft-float} is used.
9493
9494@item -mno-fp-ret-in-387
9495@opindex mno-fp-ret-in-387
9496Do not use the FPU registers for return values of functions.
9497
9498The usual calling convention has functions return values of types
9499@code{float} and @code{double} in an FPU register, even if there
9500is no FPU@. The idea is that the operating system should emulate
9501an FPU@.
9502
9503The option @option{-mno-fp-ret-in-387} causes such values to be returned
9504in ordinary CPU registers instead.
9505
9506@item -mno-fancy-math-387
9507@opindex mno-fancy-math-387
9508Some 387 emulators do not support the @code{sin}, @code{cos} and
9509@code{sqrt} instructions for the 387. Specify this option to avoid
| 5682no reason for the compiler to consider the possibility that it might,
5683and @option{-fno-math-errno} is the default.
5684
5685@item -funsafe-math-optimizations
5686@opindex funsafe-math-optimizations
5687Allow optimizations for floating-point arithmetic that (a) assume
5688that arguments and results are valid and (b) may violate IEEE or
5689ANSI standards. When used at link-time, it may include libraries
5690or startup files that change the default FPU control word or other
5691similar optimizations.
5692
5693This option should never be turned on by any @option{-O} option since
5694it can result in incorrect output for programs which depend on
5695an exact implementation of IEEE or ISO rules/specifications for
5696math functions.
5697
5698The default is @option{-fno-unsafe-math-optimizations}.
5699
5700@item -ffinite-math-only
5701@opindex ffinite-math-only
5702Allow optimizations for floating-point arithmetic that assume
5703that arguments and results are not NaNs or +-Infs.
5704
5705This option should never be turned on by any @option{-O} option since
5706it can result in incorrect output for programs which depend on
5707an exact implementation of IEEE or ISO rules/specifications.
5708
5709The default is @option{-fno-finite-math-only}.
5710
5711@item -fno-trapping-math
5712@opindex fno-trapping-math
5713Compile code assuming that floating-point operations cannot generate
5714user-visible traps. These traps include division by zero, overflow,
5715underflow, inexact result and invalid operation. This option implies
5716@option{-fno-signaling-nans}. Setting this option may allow faster
5717code if one relies on ``non-stop'' IEEE arithmetic, for example.
5718
5719This option should never be turned on by any @option{-O} option since
5720it can result in incorrect output for programs which depend on
5721an exact implementation of IEEE or ISO rules/specifications for
5722math functions.
5723
5724The default is @option{-ftrapping-math}.
5725
5726@item -frounding-math
5727@opindex frounding-math
5728Disable transformations and optimizations that assume default floating
5729point rounding behavior. This is round-to-zero for all floating point
5730to integer conversions, and round-to-nearest for all other arithmetic
5731truncations. This option should be specified for programs that change
5732the FP rounding mode dynamically, or that may be executed with a
5733non-default rounding mode. This option disables constant folding of
5734floating point expressions at compile-time (which may be affected by
5735rounding mode) and arithmetic transformations that are unsafe in the
5736presence of sign-dependent rounding modes.
5737
5738The default is @option{-fno-rounding-math}.
5739
5740This option is experimental and does not currently guarantee to
5741disable all GCC optimizations that are affected by rounding mode.
5742Future versions of GCC may provide finer control of this setting
5743using C99's @code{FENV_ACCESS} pragma. This command line option
5744will be used to specify the default state for @code{FENV_ACCESS}.
5745
5746@item -frtl-abstract-sequences
5747@opindex frtl-abstract-sequences
5748It is a size optimization method. This option is to find identical
5749sequences of code, which can be turned into pseudo-procedures and
5750then replace all occurrences with calls to the newly created
5751subroutine. It is kind of an opposite of @option{-finline-functions}.
5752This optimization runs at RTL level.
5753
5754@item -fsignaling-nans
5755@opindex fsignaling-nans
5756Compile code assuming that IEEE signaling NaNs may generate user-visible
5757traps during floating-point operations. Setting this option disables
5758optimizations that may change the number of exceptions visible with
5759signaling NaNs. This option implies @option{-ftrapping-math}.
5760
5761This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
5762be defined.
5763
5764The default is @option{-fno-signaling-nans}.
5765
5766This option is experimental and does not currently guarantee to
5767disable all GCC optimizations that affect signaling NaN behavior.
5768
5769@item -fsingle-precision-constant
5770@opindex fsingle-precision-constant
5771Treat floating point constant as single precision constant instead of
5772implicitly converting it to double precision constant.
5773
5774@item -fcx-limited-range
5775@itemx -fno-cx-limited-range
5776@opindex fcx-limited-range
5777@opindex fno-cx-limited-range
5778When enabled, this option states that a range reduction step is not
5779needed when performing complex division. The default is
5780@option{-fno-cx-limited-range}, but is enabled by @option{-ffast-math}.
5781
5782This option controls the default setting of the ISO C99
5783@code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to
5784all languages.
5785
5786@end table
5787
5788The following options control optimizations that may improve
5789performance, but are not enabled by any @option{-O} options. This
5790section includes experimental options that may produce broken code.
5791
5792@table @gcctabopt
5793@item -fbranch-probabilities
5794@opindex fbranch-probabilities
5795After running a program compiled with @option{-fprofile-arcs}
5796(@pxref{Debugging Options,, Options for Debugging Your Program or
5797@command{gcc}}), you can compile it a second time using
5798@option{-fbranch-probabilities}, to improve optimizations based on
5799the number of times each branch was taken. When the program
5800compiled with @option{-fprofile-arcs} exits it saves arc execution
5801counts to a file called @file{@var{sourcename}.gcda} for each source
5802file The information in this data file is very dependent on the
5803structure of the generated code, so you must use the same source code
5804and the same optimization options for both compilations.
5805
5806With @option{-fbranch-probabilities}, GCC puts a
5807@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
5808These can be used to improve optimization. Currently, they are only
5809used in one place: in @file{reorg.c}, instead of guessing which path a
5810branch is mostly to take, the @samp{REG_BR_PROB} values are used to
5811exactly determine which path is taken more often.
5812
5813@item -fprofile-values
5814@opindex fprofile-values
5815If combined with @option{-fprofile-arcs}, it adds code so that some
5816data about values of expressions in the program is gathered.
5817
5818With @option{-fbranch-probabilities}, it reads back the data gathered
5819from profiling values of expressions and adds @samp{REG_VALUE_PROFILE}
5820notes to instructions for their later usage in optimizations.
5821
5822Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
5823
5824@item -fvpt
5825@opindex fvpt
5826If combined with @option{-fprofile-arcs}, it instructs the compiler to add
5827a code to gather information about values of expressions.
5828
5829With @option{-fbranch-probabilities}, it reads back the data gathered
5830and actually performs the optimizations based on them.
5831Currently the optimizations include specialization of division operation
5832using the knowledge about the value of the denominator.
5833
5834@item -frename-registers
5835@opindex frename-registers
5836Attempt to avoid false dependencies in scheduled code by making use
5837of registers left over after register allocation. This optimization
5838will most benefit processors with lots of registers. Depending on the
5839debug information format adopted by the target, however, it can
5840make debugging impossible, since variables will no longer stay in
5841a ``home register''.
5842
5843Enabled by default with @option{-funroll-loops}.
5844
5845@item -ftracer
5846@opindex ftracer
5847Perform tail duplication to enlarge superblock size. This transformation
5848simplifies the control flow of the function allowing other optimizations to do
5849better job.
5850
5851Enabled with @option{-fprofile-use}.
5852
5853@item -funroll-loops
5854@opindex funroll-loops
5855Unroll loops whose number of iterations can be determined at compile time or
5856upon entry to the loop. @option{-funroll-loops} implies
5857@option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.
5858It also turns on complete loop peeling (i.e.@: complete removal of loops with
5859small constant number of iterations). This option makes code larger, and may
5860or may not make it run faster.
5861
5862Enabled with @option{-fprofile-use}.
5863
5864@item -funroll-all-loops
5865@opindex funroll-all-loops
5866Unroll all loops, even if their number of iterations is uncertain when
5867the loop is entered. This usually makes programs run more slowly.
5868@option{-funroll-all-loops} implies the same options as
5869@option{-funroll-loops}.
5870
5871@item -fpeel-loops
5872@opindex fpeel-loops
5873Peels the loops for that there is enough information that they do not
5874roll much (from profile feedback). It also turns on complete loop peeling
5875(i.e.@: complete removal of loops with small constant number of iterations).
5876
5877Enabled with @option{-fprofile-use}.
5878
5879@item -fmove-loop-invariants
5880@opindex fmove-loop-invariants
5881Enables the loop invariant motion pass in the RTL loop optimizer. Enabled
5882at level @option{-O1}
5883
5884@item -funswitch-loops
5885@opindex funswitch-loops
5886Move branches with loop invariant conditions out of the loop, with duplicates
5887of the loop on both branches (modified according to result of the condition).
5888
5889@item -ffunction-sections
5890@itemx -fdata-sections
5891@opindex ffunction-sections
5892@opindex fdata-sections
5893Place each function or data item into its own section in the output
5894file if the target supports arbitrary sections. The name of the
5895function or the name of the data item determines the section's name
5896in the output file.
5897
5898Use these options on systems where the linker can perform optimizations
5899to improve locality of reference in the instruction space. Most systems
5900using the ELF object format and SPARC processors running Solaris 2 have
5901linkers with such optimizations. AIX may have these optimizations in
5902the future.
5903
5904Only use these options when there are significant benefits from doing
5905so. When you specify these options, the assembler and linker will
5906create larger object and executable files and will also be slower.
5907You will not be able to use @code{gprof} on all systems if you
5908specify this option and you may have problems with debugging if
5909you specify both this option and @option{-g}.
5910
5911@item -fbranch-target-load-optimize
5912@opindex fbranch-target-load-optimize
5913Perform branch target register load optimization before prologue / epilogue
5914threading.
5915The use of target registers can typically be exposed only during reload,
5916thus hoisting loads out of loops and doing inter-block scheduling needs
5917a separate optimization pass.
5918
5919@item -fbranch-target-load-optimize2
5920@opindex fbranch-target-load-optimize2
5921Perform branch target register load optimization after prologue / epilogue
5922threading.
5923
5924@item -fbtr-bb-exclusive
5925@opindex fbtr-bb-exclusive
5926When performing branch target register load optimization, don't reuse
5927branch target registers in within any basic block.
5928
5929@item -fstack-protector
5930Emit extra code to check for buffer overflows, such as stack smashing
5931attacks. This is done by adding a guard variable to functions with
5932vulnerable objects. This includes functions that call alloca, and
5933functions with buffers larger than 8 bytes. The guards are initialized
5934when a function is entered and then checked when the function exits.
5935If a guard check fails, an error message is printed and the program exits.
5936
5937@item -fstack-protector-all
5938Like @option{-fstack-protector} except that all functions are protected.
5939
5940@item -fsection-anchors
5941@opindex fsection-anchors
5942Try to reduce the number of symbolic address calculations by using
5943shared ``anchor'' symbols to address nearby objects. This transformation
5944can help to reduce the number of GOT entries and GOT accesses on some
5945targets.
5946
5947For example, the implementation of the following function @code{foo}:
5948
5949@smallexample
5950static int a, b, c;
5951int foo (void) @{ return a + b + c; @}
5952@end smallexample
5953
5954would usually calculate the addresses of all three variables, but if you
5955compile it with @option{-fsection-anchors}, it will access the variables
5956from a common anchor point instead. The effect is similar to the
5957following pseudocode (which isn't valid C):
5958
5959@smallexample
5960int foo (void)
5961@{
5962 register int *xr = &x;
5963 return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
5964@}
5965@end smallexample
5966
5967Not all targets support this option.
5968
5969@item --param @var{name}=@var{value}
5970@opindex param
5971In some places, GCC uses various constants to control the amount of
5972optimization that is done. For example, GCC will not inline functions
5973that contain more that a certain number of instructions. You can
5974control some of these constants on the command-line using the
5975@option{--param} option.
5976
5977The names of specific parameters, and the meaning of the values, are
5978tied to the internals of the compiler, and are subject to change
5979without notice in future releases.
5980
5981In each case, the @var{value} is an integer. The allowable choices for
5982@var{name} are given in the following table:
5983
5984@table @gcctabopt
5985@item salias-max-implicit-fields
5986The maximum number of fields in a variable without direct
5987structure accesses for which structure aliasing will consider trying
5988to track each field. The default is 5
5989
5990@item salias-max-array-elements
5991The maximum number of elements an array can have and its elements
5992still be tracked individually by structure aliasing. The default is 4
5993
5994@item sra-max-structure-size
5995The maximum structure size, in bytes, at which the scalar replacement
5996of aggregates (SRA) optimization will perform block copies. The
5997default value, 0, implies that GCC will select the most appropriate
5998size itself.
5999
6000@item sra-field-structure-ratio
6001The threshold ratio (as a percentage) between instantiated fields and
6002the complete structure size. We say that if the ratio of the number
6003of bytes in instantiated fields to the number of bytes in the complete
6004structure exceeds this parameter, then block copies are not used. The
6005default is 75.
6006
6007@item max-crossjump-edges
6008The maximum number of incoming edges to consider for crossjumping.
6009The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
6010the number of edges incoming to each block. Increasing values mean
6011more aggressive optimization, making the compile time increase with
6012probably small improvement in executable size.
6013
6014@item min-crossjump-insns
6015The minimum number of instructions which must be matched at the end
6016of two blocks before crossjumping will be performed on them. This
6017value is ignored in the case where all instructions in the block being
6018crossjumped from are matched. The default value is 5.
6019
6020@item max-grow-copy-bb-insns
6021The maximum code size expansion factor when copying basic blocks
6022instead of jumping. The expansion is relative to a jump instruction.
6023The default value is 8.
6024
6025@item max-goto-duplication-insns
6026The maximum number of instructions to duplicate to a block that jumps
6027to a computed goto. To avoid @math{O(N^2)} behavior in a number of
6028passes, GCC factors computed gotos early in the compilation process,
6029and unfactors them as late as possible. Only computed jumps at the
6030end of a basic blocks with no more than max-goto-duplication-insns are
6031unfactored. The default value is 8.
6032
6033@item max-delay-slot-insn-search
6034The maximum number of instructions to consider when looking for an
6035instruction to fill a delay slot. If more than this arbitrary number of
6036instructions is searched, the time savings from filling the delay slot
6037will be minimal so stop searching. Increasing values mean more
6038aggressive optimization, making the compile time increase with probably
6039small improvement in executable run time.
6040
6041@item max-delay-slot-live-search
6042When trying to fill delay slots, the maximum number of instructions to
6043consider when searching for a block with valid live register
6044information. Increasing this arbitrarily chosen value means more
6045aggressive optimization, increasing the compile time. This parameter
6046should be removed when the delay slot code is rewritten to maintain the
6047control-flow graph.
6048
6049@item max-gcse-memory
6050The approximate maximum amount of memory that will be allocated in
6051order to perform the global common subexpression elimination
6052optimization. If more memory than specified is required, the
6053optimization will not be done.
6054
6055@item max-gcse-passes
6056The maximum number of passes of GCSE to run. The default is 1.
6057
6058@item max-pending-list-length
6059The maximum number of pending dependencies scheduling will allow
6060before flushing the current state and starting over. Large functions
6061with few branches or calls can create excessively large lists which
6062needlessly consume memory and resources.
6063
6064@item max-inline-insns-single
6065Several parameters control the tree inliner used in gcc.
6066This number sets the maximum number of instructions (counted in GCC's
6067internal representation) in a single function that the tree inliner
6068will consider for inlining. This only affects functions declared
6069inline and methods implemented in a class declaration (C++).
6070The default value is 450.
6071
6072@item max-inline-insns-auto
6073When you use @option{-finline-functions} (included in @option{-O3}),
6074a lot of functions that would otherwise not be considered for inlining
6075by the compiler will be investigated. To those functions, a different
6076(more restrictive) limit compared to functions declared inline can
6077be applied.
6078The default value is 90.
6079
6080@item large-function-insns
6081The limit specifying really large functions. For functions larger than this
6082limit after inlining inlining is constrained by
6083@option{--param large-function-growth}. This parameter is useful primarily
6084to avoid extreme compilation time caused by non-linear algorithms used by the
6085backend.
6086This parameter is ignored when @option{-funit-at-a-time} is not used.
6087The default value is 2700.
6088
6089@item large-function-growth
6090Specifies maximal growth of large function caused by inlining in percents.
6091This parameter is ignored when @option{-funit-at-a-time} is not used.
6092The default value is 100 which limits large function growth to 2.0 times
6093the original size.
6094
6095@item large-unit-insns
6096The limit specifying large translation unit. Growth caused by inlining of
6097units larger than this limit is limited by @option{--param inline-unit-growth}.
6098For small units this might be too tight (consider unit consisting of function A
6099that is inline and B that just calls A three time. If B is small relative to
6100A, the growth of unit is 300\% and yet such inlining is very sane. For very
6101large units consisting of small inlininable functions however the overall unit
6102growth limit is needed to avoid exponential explosion of code size. Thus for
6103smaller units, the size is increased to @option{--param large-unit-insns}
6104before applying @option{--param inline-unit-growth}. The default is 10000
6105
6106@item inline-unit-growth
6107Specifies maximal overall growth of the compilation unit caused by inlining.
6108This parameter is ignored when @option{-funit-at-a-time} is not used.
6109The default value is 50 which limits unit growth to 1.5 times the original
6110size.
6111
6112@item max-inline-insns-recursive
6113@itemx max-inline-insns-recursive-auto
6114Specifies maximum number of instructions out-of-line copy of self recursive inline
6115function can grow into by performing recursive inlining.
6116
6117For functions declared inline @option{--param max-inline-insns-recursive} is
6118taken into account. For function not declared inline, recursive inlining
6119happens only when @option{-finline-functions} (included in @option{-O3}) is
6120enabled and @option{--param max-inline-insns-recursive-auto} is used. The
6121default value is 450.
6122
6123@item max-inline-recursive-depth
6124@itemx max-inline-recursive-depth-auto
6125Specifies maximum recursion depth used by the recursive inlining.
6126
6127For functions declared inline @option{--param max-inline-recursive-depth} is
6128taken into account. For function not declared inline, recursive inlining
6129happens only when @option{-finline-functions} (included in @option{-O3}) is
6130enabled and @option{--param max-inline-recursive-depth-auto} is used. The
6131default value is 450.
6132
6133@item min-inline-recursive-probability
6134Recursive inlining is profitable only for function having deep recursion
6135in average and can hurt for function having little recursion depth by
6136increasing the prologue size or complexity of function body to other
6137optimizers.
6138
6139When profile feedback is available (see @option{-fprofile-generate}) the actual
6140recursion depth can be guessed from probability that function will recurse via
6141given call expression. This parameter limits inlining only to call expression
6142whose probability exceeds given threshold (in percents). The default value is
614310.
6144
6145@item inline-call-cost
6146Specify cost of call instruction relative to simple arithmetics operations
6147(having cost of 1). Increasing this cost disqualifies inlining of non-leaf
6148functions and at the same time increases size of leaf function that is believed to
6149reduce function size by being inlined. In effect it increases amount of
6150inlining for code having large abstraction penalty (many functions that just
6151pass the arguments to other functions) and decrease inlining for code with low
6152abstraction penalty. The default value is 16.
6153
6154@item max-unrolled-insns
6155The maximum number of instructions that a loop should have if that loop
6156is unrolled, and if the loop is unrolled, it determines how many times
6157the loop code is unrolled.
6158
6159@item max-average-unrolled-insns
6160The maximum number of instructions biased by probabilities of their execution
6161that a loop should have if that loop is unrolled, and if the loop is unrolled,
6162it determines how many times the loop code is unrolled.
6163
6164@item max-unroll-times
6165The maximum number of unrollings of a single loop.
6166
6167@item max-peeled-insns
6168The maximum number of instructions that a loop should have if that loop
6169is peeled, and if the loop is peeled, it determines how many times
6170the loop code is peeled.
6171
6172@item max-peel-times
6173The maximum number of peelings of a single loop.
6174
6175@item max-completely-peeled-insns
6176The maximum number of insns of a completely peeled loop.
6177
6178@item max-completely-peel-times
6179The maximum number of iterations of a loop to be suitable for complete peeling.
6180
6181@item max-unswitch-insns
6182The maximum number of insns of an unswitched loop.
6183
6184@item max-unswitch-level
6185The maximum number of branches unswitched in a single loop.
6186
6187@item lim-expensive
6188The minimum cost of an expensive expression in the loop invariant motion.
6189
6190@item iv-consider-all-candidates-bound
6191Bound on number of candidates for induction variables below that
6192all candidates are considered for each use in induction variable
6193optimizations. Only the most relevant candidates are considered
6194if there are more candidates, to avoid quadratic time complexity.
6195
6196@item iv-max-considered-uses
6197The induction variable optimizations give up on loops that contain more
6198induction variable uses.
6199
6200@item iv-always-prune-cand-set-bound
6201If number of candidates in the set is smaller than this value,
6202we always try to remove unnecessary ivs from the set during its
6203optimization when a new iv is added to the set.
6204
6205@item scev-max-expr-size
6206Bound on size of expressions used in the scalar evolutions analyzer.
6207Large expressions slow the analyzer.
6208
6209@item vect-max-version-checks
6210The maximum number of runtime checks that can be performed when doing
6211loop versioning in the vectorizer. See option ftree-vect-loop-version
6212for more information.
6213
6214@item max-iterations-to-track
6215
6216The maximum number of iterations of a loop the brute force algorithm
6217for analysis of # of iterations of the loop tries to evaluate.
6218
6219@item hot-bb-count-fraction
6220Select fraction of the maximal count of repetitions of basic block in program
6221given basic block needs to have to be considered hot.
6222
6223@item hot-bb-frequency-fraction
6224Select fraction of the maximal frequency of executions of basic block in
6225function given basic block needs to have to be considered hot
6226
6227@item max-predicted-iterations
6228The maximum number of loop iterations we predict statically. This is useful
6229in cases where function contain single loop with known bound and other loop
6230with unknown. We predict the known number of iterations correctly, while
6231the unknown number of iterations average to roughly 10. This means that the
6232loop without bounds would appear artificially cold relative to the other one.
6233
6234@item tracer-dynamic-coverage
6235@itemx tracer-dynamic-coverage-feedback
6236
6237This value is used to limit superblock formation once the given percentage of
6238executed instructions is covered. This limits unnecessary code size
6239expansion.
6240
6241The @option{tracer-dynamic-coverage-feedback} is used only when profile
6242feedback is available. The real profiles (as opposed to statically estimated
6243ones) are much less balanced allowing the threshold to be larger value.
6244
6245@item tracer-max-code-growth
6246Stop tail duplication once code growth has reached given percentage. This is
6247rather hokey argument, as most of the duplicates will be eliminated later in
6248cross jumping, so it may be set to much higher values than is the desired code
6249growth.
6250
6251@item tracer-min-branch-ratio
6252
6253Stop reverse growth when the reverse probability of best edge is less than this
6254threshold (in percent).
6255
6256@item tracer-min-branch-ratio
6257@itemx tracer-min-branch-ratio-feedback
6258
6259Stop forward growth if the best edge do have probability lower than this
6260threshold.
6261
6262Similarly to @option{tracer-dynamic-coverage} two values are present, one for
6263compilation for profile feedback and one for compilation without. The value
6264for compilation with profile feedback needs to be more conservative (higher) in
6265order to make tracer effective.
6266
6267@item max-cse-path-length
6268
6269Maximum number of basic blocks on path that cse considers. The default is 10.
6270
6271@item max-cse-insns
6272The maximum instructions CSE process before flushing. The default is 1000.
6273
6274@item global-var-threshold
6275
6276Counts the number of function calls (@var{n}) and the number of
6277call-clobbered variables (@var{v}). If @var{n}x@var{v} is larger than this limit, a
6278single artificial variable will be created to represent all the
6279call-clobbered variables at function call sites. This artificial
6280variable will then be made to alias every call-clobbered variable.
6281(done as @code{int * size_t} on the host machine; beware overflow).
6282
6283@item max-aliased-vops
6284
6285Maximum number of virtual operands allowed to represent aliases
6286before triggering the alias grouping heuristic. Alias grouping
6287reduces compile times and memory consumption needed for aliasing at
6288the expense of precision loss in alias information.
6289
6290@item ggc-min-expand
6291
6292GCC uses a garbage collector to manage its own memory allocation. This
6293parameter specifies the minimum percentage by which the garbage
6294collector's heap should be allowed to expand between collections.
6295Tuning this may improve compilation speed; it has no effect on code
6296generation.
6297
6298The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
6299RAM >= 1GB@. If @code{getrlimit} is available, the notion of "RAM" is
6300the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If
6301GCC is not able to calculate RAM on a particular platform, the lower
6302bound of 30% is used. Setting this parameter and
6303@option{ggc-min-heapsize} to zero causes a full collection to occur at
6304every opportunity. This is extremely slow, but can be useful for
6305debugging.
6306
6307@item ggc-min-heapsize
6308
6309Minimum size of the garbage collector's heap before it begins bothering
6310to collect garbage. The first collection occurs after the heap expands
6311by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again,
6312tuning this may improve compilation speed, and has no effect on code
6313generation.
6314
6315The default is the smaller of RAM/8, RLIMIT_RSS, or a limit which
6316tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
6317with a lower bound of 4096 (four megabytes) and an upper bound of
6318131072 (128 megabytes). If GCC is not able to calculate RAM on a
6319particular platform, the lower bound is used. Setting this parameter
6320very large effectively disables garbage collection. Setting this
6321parameter and @option{ggc-min-expand} to zero causes a full collection
6322to occur at every opportunity.
6323
6324@item max-reload-search-insns
6325The maximum number of instruction reload should look backward for equivalent
6326register. Increasing values mean more aggressive optimization, making the
6327compile time increase with probably slightly better performance. The default
6328value is 100.
6329
6330@item max-cselib-memory-locations
6331The maximum number of memory locations cselib should take into account.
6332Increasing values mean more aggressive optimization, making the compile time
6333increase with probably slightly better performance. The default value is 500.
6334
6335@item max-flow-memory-locations
6336Similar as @option{max-cselib-memory-locations} but for dataflow liveness.
6337The default value is 100.
6338
6339@item reorder-blocks-duplicate
6340@itemx reorder-blocks-duplicate-feedback
6341
6342Used by basic block reordering pass to decide whether to use unconditional
6343branch or duplicate the code on its destination. Code is duplicated when its
6344estimated size is smaller than this value multiplied by the estimated size of
6345unconditional jump in the hot spots of the program.
6346
6347The @option{reorder-block-duplicate-feedback} is used only when profile
6348feedback is available and may be set to higher values than
6349@option{reorder-block-duplicate} since information about the hot spots is more
6350accurate.
6351
6352@item max-sched-ready-insns
6353The maximum number of instructions ready to be issued the scheduler should
6354consider at any given time during the first scheduling pass. Increasing
6355values mean more thorough searches, making the compilation time increase
6356with probably little benefit. The default value is 100.
6357
6358@item max-sched-region-blocks
6359The maximum number of blocks in a region to be considered for
6360interblock scheduling. The default value is 10.
6361
6362@item max-sched-region-insns
6363The maximum number of insns in a region to be considered for
6364interblock scheduling. The default value is 100.
6365
6366@item min-spec-prob
6367The minimum probability (in percents) of reaching a source block
6368for interblock speculative scheduling. The default value is 40.
6369
6370@item max-sched-extend-regions-iters
6371The maximum number of iterations through CFG to extend regions.
63720 - disable region extension,
6373N - do at most N iterations.
6374The default value is 0.
6375
6376@item max-sched-insn-conflict-delay
6377The maximum conflict delay for an insn to be considered for speculative motion.
6378The default value is 3.
6379
6380@item sched-spec-prob-cutoff
6381The minimal probability of speculation success (in percents), so that
6382speculative insn will be scheduled.
6383The default value is 40.
6384
6385@item max-last-value-rtl
6386
6387The maximum size measured as number of RTLs that can be recorded in an expression
6388in combiner for a pseudo register as last known value of that register. The default
6389is 10000.
6390
6391@item integer-share-limit
6392Small integer constants can use a shared data structure, reducing the
6393compiler's memory usage and increasing its speed. This sets the maximum
6394value of a shared integer constant's. The default value is 256.
6395
6396@item min-virtual-mappings
6397Specifies the minimum number of virtual mappings in the incremental
6398SSA updater that should be registered to trigger the virtual mappings
6399heuristic defined by virtual-mappings-ratio. The default value is
6400100.
6401
6402@item virtual-mappings-ratio
6403If the number of virtual mappings is virtual-mappings-ratio bigger
6404than the number of virtual symbols to be updated, then the incremental
6405SSA updater switches to a full update for those symbols. The default
6406ratio is 3.
6407
6408@item ssp-buffer-size
6409The minimum size of buffers (i.e. arrays) that will receive stack smashing
6410protection when @option{-fstack-protection} is used.
6411
6412@item max-jump-thread-duplication-stmts
6413Maximum number of statements allowed in a block that needs to be
6414duplicated when threading jumps.
6415
6416@item max-fields-for-field-sensitive
6417Maximum number of fields in a structure we will treat in
6418a field sensitive manner during pointer analysis.
6419
6420@end table
6421@end table
6422
6423@node Preprocessor Options
6424@section Options Controlling the Preprocessor
6425@cindex preprocessor options
6426@cindex options, preprocessor
6427
6428These options control the C preprocessor, which is run on each C source
6429file before actual compilation.
6430
6431If you use the @option{-E} option, nothing is done except preprocessing.
6432Some of these options make sense only together with @option{-E} because
6433they cause the preprocessor output to be unsuitable for actual
6434compilation.
6435
6436@table @gcctabopt
6437@opindex Wp
6438You can use @option{-Wp,@var{option}} to bypass the compiler driver
6439and pass @var{option} directly through to the preprocessor. If
6440@var{option} contains commas, it is split into multiple options at the
6441commas. However, many options are modified, translated or interpreted
6442by the compiler driver before being passed to the preprocessor, and
6443@option{-Wp} forcibly bypasses this phase. The preprocessor's direct
6444interface is undocumented and subject to change, so whenever possible
6445you should avoid using @option{-Wp} and let the driver handle the
6446options instead.
6447
6448@item -Xpreprocessor @var{option}
6449@opindex preprocessor
6450Pass @var{option} as an option to the preprocessor. You can use this to
6451supply system-specific preprocessor options which GCC does not know how to
6452recognize.
6453
6454If you want to pass an option that takes an argument, you must use
6455@option{-Xpreprocessor} twice, once for the option and once for the argument.
6456@end table
6457
6458@include cppopts.texi
6459
6460@node Assembler Options
6461@section Passing Options to the Assembler
6462
6463@c prevent bad page break with this line
6464You can pass options to the assembler.
6465
6466@table @gcctabopt
6467@item -Wa,@var{option}
6468@opindex Wa
6469Pass @var{option} as an option to the assembler. If @var{option}
6470contains commas, it is split into multiple options at the commas.
6471
6472@item -Xassembler @var{option}
6473@opindex Xassembler
6474Pass @var{option} as an option to the assembler. You can use this to
6475supply system-specific assembler options which GCC does not know how to
6476recognize.
6477
6478If you want to pass an option that takes an argument, you must use
6479@option{-Xassembler} twice, once for the option and once for the argument.
6480
6481@end table
6482
6483@node Link Options
6484@section Options for Linking
6485@cindex link options
6486@cindex options, linking
6487
6488These options come into play when the compiler links object files into
6489an executable output file. They are meaningless if the compiler is
6490not doing a link step.
6491
6492@table @gcctabopt
6493@cindex file names
6494@item @var{object-file-name}
6495A file name that does not end in a special recognized suffix is
6496considered to name an object file or library. (Object files are
6497distinguished from libraries by the linker according to the file
6498contents.) If linking is done, these object files are used as input
6499to the linker.
6500
6501@item -c
6502@itemx -S
6503@itemx -E
6504@opindex c
6505@opindex S
6506@opindex E
6507If any of these options is used, then the linker is not run, and
6508object file names should not be used as arguments. @xref{Overall
6509Options}.
6510
6511@cindex Libraries
6512@item -l@var{library}
6513@itemx -l @var{library}
6514@opindex l
6515Search the library named @var{library} when linking. (The second
6516alternative with the library as a separate argument is only for
6517POSIX compliance and is not recommended.)
6518
6519It makes a difference where in the command you write this option; the
6520linker searches and processes libraries and object files in the order they
6521are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
6522after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
6523to functions in @samp{z}, those functions may not be loaded.
6524
6525The linker searches a standard list of directories for the library,
6526which is actually a file named @file{lib@var{library}.a}. The linker
6527then uses this file as if it had been specified precisely by name.
6528
6529The directories searched include several standard system directories
6530plus any that you specify with @option{-L}.
6531
6532Normally the files found this way are library files---archive files
6533whose members are object files. The linker handles an archive file by
6534scanning through it for members which define symbols that have so far
6535been referenced but not defined. But if the file that is found is an
6536ordinary object file, it is linked in the usual fashion. The only
6537difference between using an @option{-l} option and specifying a file name
6538is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
6539and searches several directories.
6540
6541@item -lobjc
6542@opindex lobjc
6543You need this special case of the @option{-l} option in order to
6544link an Objective-C or Objective-C++ program.
6545
6546@item -nostartfiles
6547@opindex nostartfiles
6548Do not use the standard system startup files when linking.
6549The standard system libraries are used normally, unless @option{-nostdlib}
6550or @option{-nodefaultlibs} is used.
6551
6552@item -nodefaultlibs
6553@opindex nodefaultlibs
6554Do not use the standard system libraries when linking.
6555Only the libraries you specify will be passed to the linker.
6556The standard startup files are used normally, unless @option{-nostartfiles}
6557is used. The compiler may generate calls to @code{memcmp},
6558@code{memset}, @code{memcpy} and @code{memmove}.
6559These entries are usually resolved by entries in
6560libc. These entry points should be supplied through some other
6561mechanism when this option is specified.
6562
6563@item -nostdlib
6564@opindex nostdlib
6565Do not use the standard system startup files or libraries when linking.
6566No startup files and only the libraries you specify will be passed to
6567the linker. The compiler may generate calls to @code{memcmp}, @code{memset},
6568@code{memcpy} and @code{memmove}.
6569These entries are usually resolved by entries in
6570libc. These entry points should be supplied through some other
6571mechanism when this option is specified.
6572
6573@cindex @option{-lgcc}, use with @option{-nostdlib}
6574@cindex @option{-nostdlib} and unresolved references
6575@cindex unresolved references and @option{-nostdlib}
6576@cindex @option{-lgcc}, use with @option{-nodefaultlibs}
6577@cindex @option{-nodefaultlibs} and unresolved references
6578@cindex unresolved references and @option{-nodefaultlibs}
6579One of the standard libraries bypassed by @option{-nostdlib} and
6580@option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
6581that GCC uses to overcome shortcomings of particular machines, or special
6582needs for some languages.
6583(@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
6584Collection (GCC) Internals},
6585for more discussion of @file{libgcc.a}.)
6586In most cases, you need @file{libgcc.a} even when you want to avoid
6587other standard libraries. In other words, when you specify @option{-nostdlib}
6588or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
6589This ensures that you have no unresolved references to internal GCC
6590library subroutines. (For example, @samp{__main}, used to ensure C++
6591constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
6592GNU Compiler Collection (GCC) Internals}.)
6593
6594@item -pie
6595@opindex pie
6596Produce a position independent executable on targets which support it.
6597For predictable results, you must also specify the same set of options
6598that were used to generate code (@option{-fpie}, @option{-fPIE},
6599or model suboptions) when you specify this option.
6600
6601@item -rdynamic
6602@opindex rdynamic
6603Pass the flag @option{-export-dynamic} to the ELF linker, on targets
6604that support it. This instructs the linker to add all symbols, not
6605only used ones, to the dynamic symbol table. This option is needed
6606for some uses of @code{dlopen} or to allow obtaining backtraces
6607from within a program.
6608
6609@item -s
6610@opindex s
6611Remove all symbol table and relocation information from the executable.
6612
6613@item -static
6614@opindex static
6615On systems that support dynamic linking, this prevents linking with the shared
6616libraries. On other systems, this option has no effect.
6617
6618@item -shared
6619@opindex shared
6620Produce a shared object which can then be linked with other objects to
6621form an executable. Not all systems support this option. For predictable
6622results, you must also specify the same set of options that were used to
6623generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
6624when you specify this option.@footnote{On some systems, @samp{gcc -shared}
6625needs to build supplementary stub code for constructors to work. On
6626multi-libbed systems, @samp{gcc -shared} must select the correct support
6627libraries to link against. Failing to supply the correct flags may lead
6628to subtle defects. Supplying them in cases where they are not necessary
6629is innocuous.}
6630
6631@item -shared-libgcc
6632@itemx -static-libgcc
6633@opindex shared-libgcc
6634@opindex static-libgcc
6635On systems that provide @file{libgcc} as a shared library, these options
6636force the use of either the shared or static version respectively.
6637If no shared version of @file{libgcc} was built when the compiler was
6638configured, these options have no effect.
6639
6640There are several situations in which an application should use the
6641shared @file{libgcc} instead of the static version. The most common
6642of these is when the application wishes to throw and catch exceptions
6643across different shared libraries. In that case, each of the libraries
6644as well as the application itself should use the shared @file{libgcc}.
6645
6646Therefore, the G++ and GCJ drivers automatically add
6647@option{-shared-libgcc} whenever you build a shared library or a main
6648executable, because C++ and Java programs typically use exceptions, so
6649this is the right thing to do.
6650
6651If, instead, you use the GCC driver to create shared libraries, you may
6652find that they will not always be linked with the shared @file{libgcc}.
6653If GCC finds, at its configuration time, that you have a non-GNU linker
6654or a GNU linker that does not support option @option{--eh-frame-hdr},
6655it will link the shared version of @file{libgcc} into shared libraries
6656by default. Otherwise, it will take advantage of the linker and optimize
6657away the linking with the shared version of @file{libgcc}, linking with
6658the static version of libgcc by default. This allows exceptions to
6659propagate through such shared libraries, without incurring relocation
6660costs at library load time.
6661
6662However, if a library or main executable is supposed to throw or catch
6663exceptions, you must link it using the G++ or GCJ driver, as appropriate
6664for the languages used in the program, or using the option
6665@option{-shared-libgcc}, such that it is linked with the shared
6666@file{libgcc}.
6667
6668@item -symbolic
6669@opindex symbolic
6670Bind references to global symbols when building a shared object. Warn
6671about any unresolved references (unless overridden by the link editor
6672option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
6673this option.
6674
6675@item -Xlinker @var{option}
6676@opindex Xlinker
6677Pass @var{option} as an option to the linker. You can use this to
6678supply system-specific linker options which GCC does not know how to
6679recognize.
6680
6681If you want to pass an option that takes an argument, you must use
6682@option{-Xlinker} twice, once for the option and once for the argument.
6683For example, to pass @option{-assert definitions}, you must write
6684@samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
6685@option{-Xlinker "-assert definitions"}, because this passes the entire
6686string as a single argument, which is not what the linker expects.
6687
6688@item -Wl,@var{option}
6689@opindex Wl
6690Pass @var{option} as an option to the linker. If @var{option} contains
6691commas, it is split into multiple options at the commas.
6692
6693@item -u @var{symbol}
6694@opindex u
6695Pretend the symbol @var{symbol} is undefined, to force linking of
6696library modules to define it. You can use @option{-u} multiple times with
6697different symbols to force loading of additional library modules.
6698@end table
6699
6700@node Directory Options
6701@section Options for Directory Search
6702@cindex directory options
6703@cindex options, directory search
6704@cindex search path
6705
6706These options specify directories to search for header files, for
6707libraries and for parts of the compiler:
6708
6709@table @gcctabopt
6710@item -I@var{dir}
6711@opindex I
6712Add the directory @var{dir} to the head of the list of directories to be
6713searched for header files. This can be used to override a system header
6714file, substituting your own version, since these directories are
6715searched before the system header file directories. However, you should
6716not use this option to add directories that contain vendor-supplied
6717system header files (use @option{-isystem} for that). If you use more than
6718one @option{-I} option, the directories are scanned in left-to-right
6719order; the standard system directories come after.
6720
6721If a standard system include directory, or a directory specified with
6722@option{-isystem}, is also specified with @option{-I}, the @option{-I}
6723option will be ignored. The directory will still be searched but as a
6724system directory at its normal position in the system include chain.
6725This is to ensure that GCC's procedure to fix buggy system headers and
6726the ordering for the include_next directive are not inadvertently changed.
6727If you really need to change the search order for system directories,
6728use the @option{-nostdinc} and/or @option{-isystem} options.
6729
6730@item -iquote@var{dir}
6731@opindex iquote
6732Add the directory @var{dir} to the head of the list of directories to
6733be searched for header files only for the case of @samp{#include
6734"@var{file}"}; they are not searched for @samp{#include <@var{file}>},
6735otherwise just like @option{-I}.
6736
6737@item -L@var{dir}
6738@opindex L
6739Add directory @var{dir} to the list of directories to be searched
6740for @option{-l}.
6741
6742@item -B@var{prefix}
6743@opindex B
6744This option specifies where to find the executables, libraries,
6745include files, and data files of the compiler itself.
6746
6747The compiler driver program runs one or more of the subprograms
6748@file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
6749@var{prefix} as a prefix for each program it tries to run, both with and
6750without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
6751
6752For each subprogram to be run, the compiler driver first tries the
6753@option{-B} prefix, if any. If that name is not found, or if @option{-B}
6754was not specified, the driver tries two standard prefixes, which are
6755@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of
6756those results in a file name that is found, the unmodified program
6757name is searched for using the directories specified in your
6758@env{PATH} environment variable.
6759
6760The compiler will check to see if the path provided by the @option{-B}
6761refers to a directory, and if necessary it will add a directory
6762separator character at the end of the path.
6763
6764@option{-B} prefixes that effectively specify directory names also apply
6765to libraries in the linker, because the compiler translates these
6766options into @option{-L} options for the linker. They also apply to
6767includes files in the preprocessor, because the compiler translates these
6768options into @option{-isystem} options for the preprocessor. In this case,
6769the compiler appends @samp{include} to the prefix.
6770
6771The run-time support file @file{libgcc.a} can also be searched for using
6772the @option{-B} prefix, if needed. If it is not found there, the two
6773standard prefixes above are tried, and that is all. The file is left
6774out of the link if it is not found by those means.
6775
6776Another way to specify a prefix much like the @option{-B} prefix is to use
6777the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
6778Variables}.
6779
6780As a special kludge, if the path provided by @option{-B} is
6781@file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
67829, then it will be replaced by @file{[dir/]include}. This is to help
6783with boot-strapping the compiler.
6784
6785@item -specs=@var{file}
6786@opindex specs
6787Process @var{file} after the compiler reads in the standard @file{specs}
6788file, in order to override the defaults that the @file{gcc} driver
6789program uses when determining what switches to pass to @file{cc1},
6790@file{cc1plus}, @file{as}, @file{ld}, etc. More than one
6791@option{-specs=@var{file}} can be specified on the command line, and they
6792are processed in order, from left to right.
6793
6794@item --sysroot=@var{dir}
6795@opindex sysroot
6796Use @var{dir} as the logical root directory for headers and libraries.
6797For example, if the compiler would normally search for headers in
6798@file{/usr/include} and libraries in @file{/usr/lib}, it will instead
6799search @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
6800
6801If you use both this option and the @option{-isysroot} option, then
6802the @option{--sysroot} option will apply to libraries, but the
6803@option{-isysroot} option will apply to header files.
6804
6805The GNU linker (beginning with version 2.16) has the necessary support
6806for this option. If your linker does not support this option, the
6807header file aspect of @option{--sysroot} will still work, but the
6808library aspect will not.
6809
6810@item -I-
6811@opindex I-
6812This option has been deprecated. Please use @option{-iquote} instead for
6813@option{-I} directories before the @option{-I-} and remove the @option{-I-}.
6814Any directories you specify with @option{-I} options before the @option{-I-}
6815option are searched only for the case of @samp{#include "@var{file}"};
6816they are not searched for @samp{#include <@var{file}>}.
6817
6818If additional directories are specified with @option{-I} options after
6819the @option{-I-}, these directories are searched for all @samp{#include}
6820directives. (Ordinarily @emph{all} @option{-I} directories are used
6821this way.)
6822
6823In addition, the @option{-I-} option inhibits the use of the current
6824directory (where the current input file came from) as the first search
6825directory for @samp{#include "@var{file}"}. There is no way to
6826override this effect of @option{-I-}. With @option{-I.} you can specify
6827searching the directory which was current when the compiler was
6828invoked. That is not exactly the same as what the preprocessor does
6829by default, but it is often satisfactory.
6830
6831@option{-I-} does not inhibit the use of the standard system directories
6832for header files. Thus, @option{-I-} and @option{-nostdinc} are
6833independent.
6834@end table
6835
6836@c man end
6837
6838@node Spec Files
6839@section Specifying subprocesses and the switches to pass to them
6840@cindex Spec Files
6841
6842@command{gcc} is a driver program. It performs its job by invoking a
6843sequence of other programs to do the work of compiling, assembling and
6844linking. GCC interprets its command-line parameters and uses these to
6845deduce which programs it should invoke, and which command-line options
6846it ought to place on their command lines. This behavior is controlled
6847by @dfn{spec strings}. In most cases there is one spec string for each
6848program that GCC can invoke, but a few programs have multiple spec
6849strings to control their behavior. The spec strings built into GCC can
6850be overridden by using the @option{-specs=} command-line switch to specify
6851a spec file.
6852
6853@dfn{Spec files} are plaintext files that are used to construct spec
6854strings. They consist of a sequence of directives separated by blank
6855lines. The type of directive is determined by the first non-whitespace
6856character on the line and it can be one of the following:
6857
6858@table @code
6859@item %@var{command}
6860Issues a @var{command} to the spec file processor. The commands that can
6861appear here are:
6862
6863@table @code
6864@item %include <@var{file}>
6865@cindex %include
6866Search for @var{file} and insert its text at the current point in the
6867specs file.
6868
6869@item %include_noerr <@var{file}>
6870@cindex %include_noerr
6871Just like @samp{%include}, but do not generate an error message if the include
6872file cannot be found.
6873
6874@item %rename @var{old_name} @var{new_name}
6875@cindex %rename
6876Rename the spec string @var{old_name} to @var{new_name}.
6877
6878@end table
6879
6880@item *[@var{spec_name}]:
6881This tells the compiler to create, override or delete the named spec
6882string. All lines after this directive up to the next directive or
6883blank line are considered to be the text for the spec string. If this
6884results in an empty string then the spec will be deleted. (Or, if the
6885spec did not exist, then nothing will happened.) Otherwise, if the spec
6886does not currently exist a new spec will be created. If the spec does
6887exist then its contents will be overridden by the text of this
6888directive, unless the first character of that text is the @samp{+}
6889character, in which case the text will be appended to the spec.
6890
6891@item [@var{suffix}]:
6892Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
6893and up to the next directive or blank line are considered to make up the
6894spec string for the indicated suffix. When the compiler encounters an
6895input file with the named suffix, it will processes the spec string in
6896order to work out how to compile that file. For example:
6897
6898@smallexample
6899.ZZ:
6900z-compile -input %i
6901@end smallexample
6902
6903This says that any input file whose name ends in @samp{.ZZ} should be
6904passed to the program @samp{z-compile}, which should be invoked with the
6905command-line switch @option{-input} and with the result of performing the
6906@samp{%i} substitution. (See below.)
6907
6908As an alternative to providing a spec string, the text that follows a
6909suffix directive can be one of the following:
6910
6911@table @code
6912@item @@@var{language}
6913This says that the suffix is an alias for a known @var{language}. This is
6914similar to using the @option{-x} command-line switch to GCC to specify a
6915language explicitly. For example:
6916
6917@smallexample
6918.ZZ:
6919@@c++
6920@end smallexample
6921
6922Says that .ZZ files are, in fact, C++ source files.
6923
6924@item #@var{name}
6925This causes an error messages saying:
6926
6927@smallexample
6928@var{name} compiler not installed on this system.
6929@end smallexample
6930@end table
6931
6932GCC already has an extensive list of suffixes built into it.
6933This directive will add an entry to the end of the list of suffixes, but
6934since the list is searched from the end backwards, it is effectively
6935possible to override earlier entries using this technique.
6936
6937@end table
6938
6939GCC has the following spec strings built into it. Spec files can
6940override these strings or create their own. Note that individual
6941targets can also add their own spec strings to this list.
6942
6943@smallexample
6944asm Options to pass to the assembler
6945asm_final Options to pass to the assembler post-processor
6946cpp Options to pass to the C preprocessor
6947cc1 Options to pass to the C compiler
6948cc1plus Options to pass to the C++ compiler
6949endfile Object files to include at the end of the link
6950link Options to pass to the linker
6951lib Libraries to include on the command line to the linker
6952libgcc Decides which GCC support library to pass to the linker
6953linker Sets the name of the linker
6954predefines Defines to be passed to the C preprocessor
6955signed_char Defines to pass to CPP to say whether @code{char} is signed
6956 by default
6957startfile Object files to include at the start of the link
6958@end smallexample
6959
6960Here is a small example of a spec file:
6961
6962@smallexample
6963%rename lib old_lib
6964
6965*lib:
6966--start-group -lgcc -lc -leval1 --end-group %(old_lib)
6967@end smallexample
6968
6969This example renames the spec called @samp{lib} to @samp{old_lib} and
6970then overrides the previous definition of @samp{lib} with a new one.
6971The new definition adds in some extra command-line options before
6972including the text of the old definition.
6973
6974@dfn{Spec strings} are a list of command-line options to be passed to their
6975corresponding program. In addition, the spec strings can contain
6976@samp{%}-prefixed sequences to substitute variable text or to
6977conditionally insert text into the command line. Using these constructs
6978it is possible to generate quite complex command lines.
6979
6980Here is a table of all defined @samp{%}-sequences for spec
6981strings. Note that spaces are not generated automatically around the
6982results of expanding these sequences. Therefore you can concatenate them
6983together or combine them with constant text in a single argument.
6984
6985@table @code
6986@item %%
6987Substitute one @samp{%} into the program name or argument.
6988
6989@item %i
6990Substitute the name of the input file being processed.
6991
6992@item %b
6993Substitute the basename of the input file being processed.
6994This is the substring up to (and not including) the last period
6995and not including the directory.
6996
6997@item %B
6998This is the same as @samp{%b}, but include the file suffix (text after
6999the last period).
7000
7001@item %d
7002Marks the argument containing or following the @samp{%d} as a
7003temporary file name, so that that file will be deleted if GCC exits
7004successfully. Unlike @samp{%g}, this contributes no text to the
7005argument.
7006
7007@item %g@var{suffix}
7008Substitute a file name that has suffix @var{suffix} and is chosen
7009once per compilation, and mark the argument in the same way as
7010@samp{%d}. To reduce exposure to denial-of-service attacks, the file
7011name is now chosen in a way that is hard to predict even when previously
7012chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
7013might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
7014the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
7015treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
7016was simply substituted with a file name chosen once per compilation,
7017without regard to any appended suffix (which was therefore treated
7018just like ordinary text), making such attacks more likely to succeed.
7019
7020@item %u@var{suffix}
7021Like @samp{%g}, but generates a new temporary file name even if
7022@samp{%u@var{suffix}} was already seen.
7023
7024@item %U@var{suffix}
7025Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
7026new one if there is no such last file name. In the absence of any
7027@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
7028the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
7029would involve the generation of two distinct file names, one
7030for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
7031simply substituted with a file name chosen for the previous @samp{%u},
7032without regard to any appended suffix.
7033
7034@item %j@var{suffix}
7035Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
7036writable, and if save-temps is off; otherwise, substitute the name
7037of a temporary file, just like @samp{%u}. This temporary file is not
7038meant for communication between processes, but rather as a junk
7039disposal mechanism.
7040
7041@item %|@var{suffix}
7042@itemx %m@var{suffix}
7043Like @samp{%g}, except if @option{-pipe} is in effect. In that case
7044@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
7045all. These are the two most common ways to instruct a program that it
7046should read from standard input or write to standard output. If you
7047need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
7048construct: see for example @file{f/lang-specs.h}.
7049
7050@item %.@var{SUFFIX}
7051Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
7052when it is subsequently output with @samp{%*}. @var{SUFFIX} is
7053terminated by the next space or %.
7054
7055@item %w
7056Marks the argument containing or following the @samp{%w} as the
7057designated output file of this compilation. This puts the argument
7058into the sequence of arguments that @samp{%o} will substitute later.
7059
7060@item %o
7061Substitutes the names of all the output files, with spaces
7062automatically placed around them. You should write spaces
7063around the @samp{%o} as well or the results are undefined.
7064@samp{%o} is for use in the specs for running the linker.
7065Input files whose names have no recognized suffix are not compiled
7066at all, but they are included among the output files, so they will
7067be linked.
7068
7069@item %O
7070Substitutes the suffix for object files. Note that this is
7071handled specially when it immediately follows @samp{%g, %u, or %U},
7072because of the need for those to form complete file names. The
7073handling is such that @samp{%O} is treated exactly as if it had already
7074been substituted, except that @samp{%g, %u, and %U} do not currently
7075support additional @var{suffix} characters following @samp{%O} as they would
7076following, for example, @samp{.o}.
7077
7078@item %p
7079Substitutes the standard macro predefinitions for the
7080current target machine. Use this when running @code{cpp}.
7081
7082@item %P
7083Like @samp{%p}, but puts @samp{__} before and after the name of each
7084predefined macro, except for macros that start with @samp{__} or with
7085@samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
7086C@.
7087
7088@item %I
7089Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
7090@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
7091@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
7092and @option{-imultilib} as necessary.
7093
7094@item %s
7095Current argument is the name of a library or startup file of some sort.
7096Search for that file in a standard list of directories and substitute
7097the full name found.
7098
7099@item %e@var{str}
7100Print @var{str} as an error message. @var{str} is terminated by a newline.
7101Use this when inconsistent options are detected.
7102
7103@item %(@var{name})
7104Substitute the contents of spec string @var{name} at this point.
7105
7106@item %[@var{name}]
7107Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
7108
7109@item %x@{@var{option}@}
7110Accumulate an option for @samp{%X}.
7111
7112@item %X
7113Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
7114spec string.
7115
7116@item %Y
7117Output the accumulated assembler options specified by @option{-Wa}.
7118
7119@item %Z
7120Output the accumulated preprocessor options specified by @option{-Wp}.
7121
7122@item %a
7123Process the @code{asm} spec. This is used to compute the
7124switches to be passed to the assembler.
7125
7126@item %A
7127Process the @code{asm_final} spec. This is a spec string for
7128passing switches to an assembler post-processor, if such a program is
7129needed.
7130
7131@item %l
7132Process the @code{link} spec. This is the spec for computing the
7133command line passed to the linker. Typically it will make use of the
7134@samp{%L %G %S %D and %E} sequences.
7135
7136@item %D
7137Dump out a @option{-L} option for each directory that GCC believes might
7138contain startup files. If the target supports multilibs then the
7139current multilib directory will be prepended to each of these paths.
7140
7141@item %L
7142Process the @code{lib} spec. This is a spec string for deciding which
7143libraries should be included on the command line to the linker.
7144
7145@item %G
7146Process the @code{libgcc} spec. This is a spec string for deciding
7147which GCC support library should be included on the command line to the linker.
7148
7149@item %S
7150Process the @code{startfile} spec. This is a spec for deciding which
7151object files should be the first ones passed to the linker. Typically
7152this might be a file named @file{crt0.o}.
7153
7154@item %E
7155Process the @code{endfile} spec. This is a spec string that specifies
7156the last object files that will be passed to the linker.
7157
7158@item %C
7159Process the @code{cpp} spec. This is used to construct the arguments
7160to be passed to the C preprocessor.
7161
7162@item %1
7163Process the @code{cc1} spec. This is used to construct the options to be
7164passed to the actual C compiler (@samp{cc1}).
7165
7166@item %2
7167Process the @code{cc1plus} spec. This is used to construct the options to be
7168passed to the actual C++ compiler (@samp{cc1plus}).
7169
7170@item %*
7171Substitute the variable part of a matched option. See below.
7172Note that each comma in the substituted string is replaced by
7173a single space.
7174
7175@item %<@code{S}
7176Remove all occurrences of @code{-S} from the command line. Note---this
7177command is position dependent. @samp{%} commands in the spec string
7178before this one will see @code{-S}, @samp{%} commands in the spec string
7179after this one will not.
7180
7181@item %:@var{function}(@var{args})
7182Call the named function @var{function}, passing it @var{args}.
7183@var{args} is first processed as a nested spec string, then split
7184into an argument vector in the usual fashion. The function returns
7185a string which is processed as if it had appeared literally as part
7186of the current spec.
7187
7188The following built-in spec functions are provided:
7189
7190@table @code
7191@item @code{if-exists}
7192The @code{if-exists} spec function takes one argument, an absolute
7193pathname to a file. If the file exists, @code{if-exists} returns the
7194pathname. Here is a small example of its usage:
7195
7196@smallexample
7197*startfile:
7198crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
7199@end smallexample
7200
7201@item @code{if-exists-else}
7202The @code{if-exists-else} spec function is similar to the @code{if-exists}
7203spec function, except that it takes two arguments. The first argument is
7204an absolute pathname to a file. If the file exists, @code{if-exists-else}
7205returns the pathname. If it does not exist, it returns the second argument.
7206This way, @code{if-exists-else} can be used to select one file or another,
7207based on the existence of the first. Here is a small example of its usage:
7208
7209@smallexample
7210*startfile:
7211crt0%O%s %:if-exists(crti%O%s) \
7212%:if-exists-else(crtbeginT%O%s crtbegin%O%s)
7213@end smallexample
7214
7215@item @code{replace-outfile}
7216The @code{replace-outfile} spec function takes two arguments. It looks for the
7217first argument in the outfiles array and replaces it with the second argument. Here
7218is a small example of its usage:
7219
7220@smallexample
7221%@{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)@}
7222@end smallexample
7223
7224@end table
7225
7226@item %@{@code{S}@}
7227Substitutes the @code{-S} switch, if that switch was given to GCC@.
7228If that switch was not specified, this substitutes nothing. Note that
7229the leading dash is omitted when specifying this option, and it is
7230automatically inserted if the substitution is performed. Thus the spec
7231string @samp{%@{foo@}} would match the command-line option @option{-foo}
7232and would output the command line option @option{-foo}.
7233
7234@item %W@{@code{S}@}
7235Like %@{@code{S}@} but mark last argument supplied within as a file to be
7236deleted on failure.
7237
7238@item %@{@code{S}*@}
7239Substitutes all the switches specified to GCC whose names start
7240with @code{-S}, but which also take an argument. This is used for
7241switches like @option{-o}, @option{-D}, @option{-I}, etc.
7242GCC considers @option{-o foo} as being
7243one switch whose names starts with @samp{o}. %@{o*@} would substitute this
7244text, including the space. Thus two arguments would be generated.
7245
7246@item %@{@code{S}*&@code{T}*@}
7247Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
7248(the order of @code{S} and @code{T} in the spec is not significant).
7249There can be any number of ampersand-separated variables; for each the
7250wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
7251
7252@item %@{@code{S}:@code{X}@}
7253Substitutes @code{X}, if the @samp{-S} switch was given to GCC@.
7254
7255@item %@{!@code{S}:@code{X}@}
7256Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@.
7257
7258@item %@{@code{S}*:@code{X}@}
7259Substitutes @code{X} if one or more switches whose names start with
7260@code{-S} are specified to GCC@. Normally @code{X} is substituted only
7261once, no matter how many such switches appeared. However, if @code{%*}
7262appears somewhere in @code{X}, then @code{X} will be substituted once
7263for each matching switch, with the @code{%*} replaced by the part of
7264that switch that matched the @code{*}.
7265
7266@item %@{.@code{S}:@code{X}@}
7267Substitutes @code{X}, if processing a file with suffix @code{S}.
7268
7269@item %@{!.@code{S}:@code{X}@}
7270Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
7271
7272@item %@{@code{S}|@code{P}:@code{X}@}
7273Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@.
7274This may be combined with @samp{!}, @samp{.}, and @code{*} sequences as well,
7275although they have a stronger binding than the @samp{|}. If @code{%*}
7276appears in @code{X}, all of the alternatives must be starred, and only
7277the first matching alternative is substituted.
7278
7279For example, a spec string like this:
7280
7281@smallexample
7282%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
7283@end smallexample
7284
7285will output the following command-line options from the following input
7286command-line options:
7287
7288@smallexample
7289fred.c -foo -baz
7290jim.d -bar -boggle
7291-d fred.c -foo -baz -boggle
7292-d jim.d -bar -baz -boggle
7293@end smallexample
7294
7295@item %@{S:X; T:Y; :D@}
7296
7297If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was
7298given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
7299be as many clauses as you need. This may be combined with @code{.},
7300@code{!}, @code{|}, and @code{*} as needed.
7301
7302
7303@end table
7304
7305The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
7306construct may contain other nested @samp{%} constructs or spaces, or
7307even newlines. They are processed as usual, as described above.
7308Trailing white space in @code{X} is ignored. White space may also
7309appear anywhere on the left side of the colon in these constructs,
7310except between @code{.} or @code{*} and the corresponding word.
7311
7312The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
7313handled specifically in these constructs. If another value of
7314@option{-O} or the negated form of a @option{-f}, @option{-m}, or
7315@option{-W} switch is found later in the command line, the earlier
7316switch value is ignored, except with @{@code{S}*@} where @code{S} is
7317just one letter, which passes all matching options.
7318
7319The character @samp{|} at the beginning of the predicate text is used to
7320indicate that a command should be piped to the following command, but
7321only if @option{-pipe} is specified.
7322
7323It is built into GCC which switches take arguments and which do not.
7324(You might think it would be useful to generalize this to allow each
7325compiler's spec to say which switches take arguments. But this cannot
7326be done in a consistent fashion. GCC cannot even decide which input
7327files have been specified without knowing which switches take arguments,
7328and it must know which input files to compile in order to tell which
7329compilers to run).
7330
7331GCC also knows implicitly that arguments starting in @option{-l} are to be
7332treated as compiler output files, and passed to the linker in their
7333proper position among the other output files.
7334
7335@c man begin OPTIONS
7336
7337@node Target Options
7338@section Specifying Target Machine and Compiler Version
7339@cindex target options
7340@cindex cross compiling
7341@cindex specifying machine version
7342@cindex specifying compiler version and target machine
7343@cindex compiler version, specifying
7344@cindex target machine, specifying
7345
7346The usual way to run GCC is to run the executable called @file{gcc}, or
7347@file{<machine>-gcc} when cross-compiling, or
7348@file{<machine>-gcc-<version>} to run a version other than the one that
7349was installed last. Sometimes this is inconvenient, so GCC provides
7350options that will switch to another cross-compiler or version.
7351
7352@table @gcctabopt
7353@item -b @var{machine}
7354@opindex b
7355The argument @var{machine} specifies the target machine for compilation.
7356
7357The value to use for @var{machine} is the same as was specified as the
7358machine type when configuring GCC as a cross-compiler. For
7359example, if a cross-compiler was configured with @samp{configure
7360arm-elf}, meaning to compile for an arm processor with elf binaries,
7361then you would specify @option{-b arm-elf} to run that cross compiler.
7362Because there are other options beginning with @option{-b}, the
7363configuration must contain a hyphen.
7364
7365@item -V @var{version}
7366@opindex V
7367The argument @var{version} specifies which version of GCC to run.
7368This is useful when multiple versions are installed. For example,
7369@var{version} might be @samp{4.0}, meaning to run GCC version 4.0.
7370@end table
7371
7372The @option{-V} and @option{-b} options work by running the
7373@file{<machine>-gcc-<version>} executable, so there's no real reason to
7374use them if you can just run that directly.
7375
7376@node Submodel Options
7377@section Hardware Models and Configurations
7378@cindex submodel options
7379@cindex specifying hardware config
7380@cindex hardware models and configurations, specifying
7381@cindex machine dependent options
7382
7383Earlier we discussed the standard option @option{-b} which chooses among
7384different installed compilers for completely different target
7385machines, such as VAX vs.@: 68000 vs.@: 80386.
7386
7387In addition, each of these target machine types can have its own
7388special options, starting with @samp{-m}, to choose among various
7389hardware models or configurations---for example, 68010 vs 68020,
7390floating coprocessor or none. A single installed version of the
7391compiler can compile for any model or configuration, according to the
7392options specified.
7393
7394Some configurations of the compiler also support additional special
7395options, usually for compatibility with other compilers on the same
7396platform.
7397
7398@c This list is ordered alphanumerically by subsection name.
7399@c It should be the same order and spelling as these options are listed
7400@c in Machine Dependent Options
7401
7402@menu
7403* ARC Options::
7404* ARM Options::
7405* AVR Options::
7406* Blackfin Options::
7407* CRIS Options::
7408* CRX Options::
7409* Darwin Options::
7410* DEC Alpha Options::
7411* DEC Alpha/VMS Options::
7412* FRV Options::
7413* GNU/Linux Options::
7414* H8/300 Options::
7415* HPPA Options::
7416* i386 and x86-64 Options::
7417* IA-64 Options::
7418* M32C Options::
7419* M32R/D Options::
7420* M680x0 Options::
7421* M68hc1x Options::
7422* MCore Options::
7423* MIPS Options::
7424* MMIX Options::
7425* MN10300 Options::
7426* MT Options::
7427* PDP-11 Options::
7428* PowerPC Options::
7429* RS/6000 and PowerPC Options::
7430* S/390 and zSeries Options::
7431* Score Options::
7432* SH Options::
7433* SPARC Options::
7434* System V Options::
7435* TMS320C3x/C4x Options::
7436* V850 Options::
7437* VAX Options::
7438* x86-64 Options::
7439* Xstormy16 Options::
7440* Xtensa Options::
7441* zSeries Options::
7442@end menu
7443
7444@node ARC Options
7445@subsection ARC Options
7446@cindex ARC Options
7447
7448These options are defined for ARC implementations:
7449
7450@table @gcctabopt
7451@item -EL
7452@opindex EL
7453Compile code for little endian mode. This is the default.
7454
7455@item -EB
7456@opindex EB
7457Compile code for big endian mode.
7458
7459@item -mmangle-cpu
7460@opindex mmangle-cpu
7461Prepend the name of the cpu to all public symbol names.
7462In multiple-processor systems, there are many ARC variants with different
7463instruction and register set characteristics. This flag prevents code
7464compiled for one cpu to be linked with code compiled for another.
7465No facility exists for handling variants that are ``almost identical''.
7466This is an all or nothing option.
7467
7468@item -mcpu=@var{cpu}
7469@opindex mcpu
7470Compile code for ARC variant @var{cpu}.
7471Which variants are supported depend on the configuration.
7472All variants support @option{-mcpu=base}, this is the default.
7473
7474@item -mtext=@var{text-section}
7475@itemx -mdata=@var{data-section}
7476@itemx -mrodata=@var{readonly-data-section}
7477@opindex mtext
7478@opindex mdata
7479@opindex mrodata
7480Put functions, data, and readonly data in @var{text-section},
7481@var{data-section}, and @var{readonly-data-section} respectively
7482by default. This can be overridden with the @code{section} attribute.
7483@xref{Variable Attributes}.
7484
7485@end table
7486
7487@node ARM Options
7488@subsection ARM Options
7489@cindex ARM options
7490
7491These @samp{-m} options are defined for Advanced RISC Machines (ARM)
7492architectures:
7493
7494@table @gcctabopt
7495@item -mabi=@var{name}
7496@opindex mabi
7497Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu},
7498@samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.
7499
7500@item -mapcs-frame
7501@opindex mapcs-frame
7502Generate a stack frame that is compliant with the ARM Procedure Call
7503Standard for all functions, even if this is not strictly necessary for
7504correct execution of the code. Specifying @option{-fomit-frame-pointer}
7505with this option will cause the stack frames not to be generated for
7506leaf functions. The default is @option{-mno-apcs-frame}.
7507
7508@item -mapcs
7509@opindex mapcs
7510This is a synonym for @option{-mapcs-frame}.
7511
7512@ignore
7513@c not currently implemented
7514@item -mapcs-stack-check
7515@opindex mapcs-stack-check
7516Generate code to check the amount of stack space available upon entry to
7517every function (that actually uses some stack space). If there is
7518insufficient space available then either the function
7519@samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
7520called, depending upon the amount of stack space required. The run time
7521system is required to provide these functions. The default is
7522@option{-mno-apcs-stack-check}, since this produces smaller code.
7523
7524@c not currently implemented
7525@item -mapcs-float
7526@opindex mapcs-float
7527Pass floating point arguments using the float point registers. This is
7528one of the variants of the APCS@. This option is recommended if the
7529target hardware has a floating point unit or if a lot of floating point
7530arithmetic is going to be performed by the code. The default is
7531@option{-mno-apcs-float}, since integer only code is slightly increased in
7532size if @option{-mapcs-float} is used.
7533
7534@c not currently implemented
7535@item -mapcs-reentrant
7536@opindex mapcs-reentrant
7537Generate reentrant, position independent code. The default is
7538@option{-mno-apcs-reentrant}.
7539@end ignore
7540
7541@item -mthumb-interwork
7542@opindex mthumb-interwork
7543Generate code which supports calling between the ARM and Thumb
7544instruction sets. Without this option the two instruction sets cannot
7545be reliably used inside one program. The default is
7546@option{-mno-thumb-interwork}, since slightly larger code is generated
7547when @option{-mthumb-interwork} is specified.
7548
7549@item -mno-sched-prolog
7550@opindex mno-sched-prolog
7551Prevent the reordering of instructions in the function prolog, or the
7552merging of those instruction with the instructions in the function's
7553body. This means that all functions will start with a recognizable set
7554of instructions (or in fact one of a choice from a small set of
7555different function prologues), and this information can be used to
7556locate the start if functions inside an executable piece of code. The
7557default is @option{-msched-prolog}.
7558
7559@item -mhard-float
7560@opindex mhard-float
7561Generate output containing floating point instructions. This is the
7562default.
7563
7564@item -msoft-float
7565@opindex msoft-float
7566Generate output containing library calls for floating point.
7567@strong{Warning:} the requisite libraries are not available for all ARM
7568targets. Normally the facilities of the machine's usual C compiler are
7569used, but this cannot be done directly in cross-compilation. You must make
7570your own arrangements to provide suitable library functions for
7571cross-compilation.
7572
7573@option{-msoft-float} changes the calling convention in the output file;
7574therefore, it is only useful if you compile @emph{all} of a program with
7575this option. In particular, you need to compile @file{libgcc.a}, the
7576library that comes with GCC, with @option{-msoft-float} in order for
7577this to work.
7578
7579@item -mfloat-abi=@var{name}
7580@opindex mfloat-abi
7581Specifies which ABI to use for floating point values. Permissible values
7582are: @samp{soft}, @samp{softfp} and @samp{hard}.
7583
7584@samp{soft} and @samp{hard} are equivalent to @option{-msoft-float}
7585and @option{-mhard-float} respectively. @samp{softfp} allows the generation
7586of floating point instructions, but still uses the soft-float calling
7587conventions.
7588
7589@item -mlittle-endian
7590@opindex mlittle-endian
7591Generate code for a processor running in little-endian mode. This is
7592the default for all standard configurations.
7593
7594@item -mbig-endian
7595@opindex mbig-endian
7596Generate code for a processor running in big-endian mode; the default is
7597to compile code for a little-endian processor.
7598
7599@item -mwords-little-endian
7600@opindex mwords-little-endian
7601This option only applies when generating code for big-endian processors.
7602Generate code for a little-endian word order but a big-endian byte
7603order. That is, a byte order of the form @samp{32107654}. Note: this
7604option should only be used if you require compatibility with code for
7605big-endian ARM processors generated by versions of the compiler prior to
76062.8.
7607
7608@item -mcpu=@var{name}
7609@opindex mcpu
7610This specifies the name of the target ARM processor. GCC uses this name
7611to determine what kind of instructions it can emit when generating
7612assembly code. Permissible names are: @samp{arm2}, @samp{arm250},
7613@samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
7614@samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
7615@samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
7616@samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
7617@samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},
7618@samp{arm8}, @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
7619@samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
7620@samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},
7621@samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},
7622@samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},
7623@samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
7624@samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
7625@samp{arm1176jz-s}, @samp{arm1176jzf-s}, @samp{xscale}, @samp{iwmmxt},
7626@samp{ep9312}.
7627
7628@itemx -mtune=@var{name}
7629@opindex mtune
7630This option is very similar to the @option{-mcpu=} option, except that
7631instead of specifying the actual target processor type, and hence
7632restricting which instructions can be used, it specifies that GCC should
7633tune the performance of the code as if the target were of the type
7634specified in this option, but still choosing the instructions that it
7635will generate based on the cpu specified by a @option{-mcpu=} option.
7636For some ARM implementations better performance can be obtained by using
7637this option.
7638
7639@item -march=@var{name}
7640@opindex march
7641This specifies the name of the target ARM architecture. GCC uses this
7642name to determine what kind of instructions it can emit when generating
7643assembly code. This option can be used in conjunction with or instead
7644of the @option{-mcpu=} option. Permissible names are: @samp{armv2},
7645@samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
7646@samp{armv5}, @samp{armv5t}, @samp{armv5te}, @samp{armv6}, @samp{armv6j},
7647@samp{iwmmxt}, @samp{ep9312}.
7648
7649@item -mfpu=@var{name}
7650@itemx -mfpe=@var{number}
7651@itemx -mfp=@var{number}
7652@opindex mfpu
7653@opindex mfpe
7654@opindex mfp
7655This specifies what floating point hardware (or hardware emulation) is
7656available on the target. Permissible names are: @samp{fpa}, @samp{fpe2},
7657@samp{fpe3}, @samp{maverick}, @samp{vfp}. @option{-mfp} and @option{-mfpe}
7658are synonyms for @option{-mfpu}=@samp{fpe}@var{number}, for compatibility
7659with older versions of GCC@.
7660
7661If @option{-msoft-float} is specified this specifies the format of
7662floating point values.
7663
7664@item -mstructure-size-boundary=@var{n}
7665@opindex mstructure-size-boundary
7666The size of all structures and unions will be rounded up to a multiple
7667of the number of bits set by this option. Permissible values are 8, 32
7668and 64. The default value varies for different toolchains. For the COFF
7669targeted toolchain the default value is 8. A value of 64 is only allowed
7670if the underlying ABI supports it.
7671
7672Specifying the larger number can produce faster, more efficient code, but
7673can also increase the size of the program. Different values are potentially
7674incompatible. Code compiled with one value cannot necessarily expect to
7675work with code or libraries compiled with another value, if they exchange
7676information using structures or unions.
7677
7678@item -mabort-on-noreturn
7679@opindex mabort-on-noreturn
7680Generate a call to the function @code{abort} at the end of a
7681@code{noreturn} function. It will be executed if the function tries to
7682return.
7683
7684@item -mlong-calls
7685@itemx -mno-long-calls
7686@opindex mlong-calls
7687@opindex mno-long-calls
7688Tells the compiler to perform function calls by first loading the
7689address of the function into a register and then performing a subroutine
7690call on this register. This switch is needed if the target function
7691will lie outside of the 64 megabyte addressing range of the offset based
7692version of subroutine call instruction.
7693
7694Even if this switch is enabled, not all function calls will be turned
7695into long calls. The heuristic is that static functions, functions
7696which have the @samp{short-call} attribute, functions that are inside
7697the scope of a @samp{#pragma no_long_calls} directive and functions whose
7698definitions have already been compiled within the current compilation
7699unit, will not be turned into long calls. The exception to this rule is
7700that weak function definitions, functions with the @samp{long-call}
7701attribute or the @samp{section} attribute, and functions that are within
7702the scope of a @samp{#pragma long_calls} directive, will always be
7703turned into long calls.
7704
7705This feature is not enabled by default. Specifying
7706@option{-mno-long-calls} will restore the default behavior, as will
7707placing the function calls within the scope of a @samp{#pragma
7708long_calls_off} directive. Note these switches have no effect on how
7709the compiler generates code to handle function calls via function
7710pointers.
7711
7712@item -mnop-fun-dllimport
7713@opindex mnop-fun-dllimport
7714Disable support for the @code{dllimport} attribute.
7715
7716@item -msingle-pic-base
7717@opindex msingle-pic-base
7718Treat the register used for PIC addressing as read-only, rather than
7719loading it in the prologue for each function. The run-time system is
7720responsible for initializing this register with an appropriate value
7721before execution begins.
7722
7723@item -mpic-register=@var{reg}
7724@opindex mpic-register
7725Specify the register to be used for PIC addressing. The default is R10
7726unless stack-checking is enabled, when R9 is used.
7727
7728@item -mcirrus-fix-invalid-insns
7729@opindex mcirrus-fix-invalid-insns
7730@opindex mno-cirrus-fix-invalid-insns
7731Insert NOPs into the instruction stream to in order to work around
7732problems with invalid Maverick instruction combinations. This option
7733is only valid if the @option{-mcpu=ep9312} option has been used to
7734enable generation of instructions for the Cirrus Maverick floating
7735point co-processor. This option is not enabled by default, since the
7736problem is only present in older Maverick implementations. The default
7737can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns}
7738switch.
7739
7740@item -mpoke-function-name
7741@opindex mpoke-function-name
7742Write the name of each function into the text section, directly
7743preceding the function prologue. The generated code is similar to this:
7744
7745@smallexample
7746 t0
7747 .ascii "arm_poke_function_name", 0
7748 .align
7749 t1
7750 .word 0xff000000 + (t1 - t0)
7751 arm_poke_function_name
7752 mov ip, sp
7753 stmfd sp!, @{fp, ip, lr, pc@}
7754 sub fp, ip, #4
7755@end smallexample
7756
7757When performing a stack backtrace, code can inspect the value of
7758@code{pc} stored at @code{fp + 0}. If the trace function then looks at
7759location @code{pc - 12} and the top 8 bits are set, then we know that
7760there is a function name embedded immediately preceding this location
7761and has length @code{((pc[-3]) & 0xff000000)}.
7762
7763@item -mthumb
7764@opindex mthumb
7765Generate code for the 16-bit Thumb instruction set. The default is to
7766use the 32-bit ARM instruction set.
7767
7768@item -mtpcs-frame
7769@opindex mtpcs-frame
7770Generate a stack frame that is compliant with the Thumb Procedure Call
7771Standard for all non-leaf functions. (A leaf function is one that does
7772not call any other functions.) The default is @option{-mno-tpcs-frame}.
7773
7774@item -mtpcs-leaf-frame
7775@opindex mtpcs-leaf-frame
7776Generate a stack frame that is compliant with the Thumb Procedure Call
7777Standard for all leaf functions. (A leaf function is one that does
7778not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
7779
7780@item -mcallee-super-interworking
7781@opindex mcallee-super-interworking
7782Gives all externally visible functions in the file being compiled an ARM
7783instruction set header which switches to Thumb mode before executing the
7784rest of the function. This allows these functions to be called from
7785non-interworking code.
7786
7787@item -mcaller-super-interworking
7788@opindex mcaller-super-interworking
7789Allows calls via function pointers (including virtual functions) to
7790execute correctly regardless of whether the target code has been
7791compiled for interworking or not. There is a small overhead in the cost
7792of executing a function pointer if this option is enabled.
7793
7794@item -mtp=@var{name}
7795@opindex mtp
7796Specify the access model for the thread local storage pointer. The valid
7797models are @option{soft}, which generates calls to @code{__aeabi_read_tp},
7798@option{cp15}, which fetches the thread pointer from @code{cp15} directly
7799(supported in the arm6k architecture), and @option{auto}, which uses the
7800best available method for the selected processor. The default setting is
7801@option{auto}.
7802
7803@end table
7804
7805@node AVR Options
7806@subsection AVR Options
7807@cindex AVR Options
7808
7809These options are defined for AVR implementations:
7810
7811@table @gcctabopt
7812@item -mmcu=@var{mcu}
7813@opindex mmcu
7814Specify ATMEL AVR instruction set or MCU type.
7815
7816Instruction set avr1 is for the minimal AVR core, not supported by the C
7817compiler, only for assembler programs (MCU types: at90s1200, attiny10,
7818attiny11, attiny12, attiny15, attiny28).
7819
7820Instruction set avr2 (default) is for the classic AVR core with up to
78218K program memory space (MCU types: at90s2313, at90s2323, attiny22,
7822at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
7823at90c8534, at90s8535).
7824
7825Instruction set avr3 is for the classic AVR core with up to 128K program
7826memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
7827
7828Instruction set avr4 is for the enhanced AVR core with up to 8K program
7829memory space (MCU types: atmega8, atmega83, atmega85).
7830
7831Instruction set avr5 is for the enhanced AVR core with up to 128K program
7832memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
7833atmega64, atmega128, at43usb355, at94k).
7834
7835@item -msize
7836@opindex msize
7837Output instruction sizes to the asm file.
7838
7839@item -minit-stack=@var{N}
7840@opindex minit-stack
7841Specify the initial stack address, which may be a symbol or numeric value,
7842@samp{__stack} is the default.
7843
7844@item -mno-interrupts
7845@opindex mno-interrupts
7846Generated code is not compatible with hardware interrupts.
7847Code size will be smaller.
7848
7849@item -mcall-prologues
7850@opindex mcall-prologues
7851Functions prologues/epilogues expanded as call to appropriate
7852subroutines. Code size will be smaller.
7853
7854@item -mno-tablejump
7855@opindex mno-tablejump
7856Do not generate tablejump insns which sometimes increase code size.
7857
7858@item -mtiny-stack
7859@opindex mtiny-stack
7860Change only the low 8 bits of the stack pointer.
7861
7862@item -mint8
7863@opindex mint8
7864Assume int to be 8 bit integer. This affects the sizes of all types: A
7865char will be 1 byte, an int will be 1 byte, an long will be 2 bytes
7866and long long will be 4 bytes. Please note that this option does not
7867comply to the C standards, but it will provide you with smaller code
7868size.
7869@end table
7870
7871@node Blackfin Options
7872@subsection Blackfin Options
7873@cindex Blackfin Options
7874
7875@table @gcctabopt
7876@item -momit-leaf-frame-pointer
7877@opindex momit-leaf-frame-pointer
7878Don't keep the frame pointer in a register for leaf functions. This
7879avoids the instructions to save, set up and restore frame pointers and
7880makes an extra register available in leaf functions. The option
7881@option{-fomit-frame-pointer} removes the frame pointer for all functions
7882which might make debugging harder.
7883
7884@item -mspecld-anomaly
7885@opindex mspecld-anomaly
7886When enabled, the compiler will ensure that the generated code does not
7887contain speculative loads after jump instructions. This option is enabled
7888by default.
7889
7890@item -mno-specld-anomaly
7891@opindex mno-specld-anomaly
7892Don't generate extra code to prevent speculative loads from occurring.
7893
7894@item -mcsync-anomaly
7895@opindex mcsync-anomaly
7896When enabled, the compiler will ensure that the generated code does not
7897contain CSYNC or SSYNC instructions too soon after conditional branches.
7898This option is enabled by default.
7899
7900@item -mno-csync-anomaly
7901@opindex mno-csync-anomaly
7902Don't generate extra code to prevent CSYNC or SSYNC instructions from
7903occurring too soon after a conditional branch.
7904
7905@item -mlow-64k
7906@opindex mlow-64k
7907When enabled, the compiler is free to take advantage of the knowledge that
7908the entire program fits into the low 64k of memory.
7909
7910@item -mno-low-64k
7911@opindex mno-low-64k
7912Assume that the program is arbitrarily large. This is the default.
7913
7914@item -mid-shared-library
7915@opindex mid-shared-library
7916Generate code that supports shared libraries via the library ID method.
7917This allows for execute in place and shared libraries in an environment
7918without virtual memory management. This option implies @option{-fPIC}.
7919
7920@item -mno-id-shared-library
7921@opindex mno-id-shared-library
7922Generate code that doesn't assume ID based shared libraries are being used.
7923This is the default.
7924
7925@item -mshared-library-id=n
7926@opindex mshared-library-id
7927Specified the identification number of the ID based shared library being
7928compiled. Specifying a value of 0 will generate more compact code, specifying
7929other values will force the allocation of that number to the current
7930library but is no more space or time efficient than omitting this option.
7931
7932@item -mlong-calls
7933@itemx -mno-long-calls
7934@opindex mlong-calls
7935@opindex mno-long-calls
7936Tells the compiler to perform function calls by first loading the
7937address of the function into a register and then performing a subroutine
7938call on this register. This switch is needed if the target function
7939will lie outside of the 24 bit addressing range of the offset based
7940version of subroutine call instruction.
7941
7942This feature is not enabled by default. Specifying
7943@option{-mno-long-calls} will restore the default behavior. Note these
7944switches have no effect on how the compiler generates code to handle
7945function calls via function pointers.
7946@end table
7947
7948@node CRIS Options
7949@subsection CRIS Options
7950@cindex CRIS Options
7951
7952These options are defined specifically for the CRIS ports.
7953
7954@table @gcctabopt
7955@item -march=@var{architecture-type}
7956@itemx -mcpu=@var{architecture-type}
7957@opindex march
7958@opindex mcpu
7959Generate code for the specified architecture. The choices for
7960@var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
7961respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
7962Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
7963@samp{v10}.
7964
7965@item -mtune=@var{architecture-type}
7966@opindex mtune
7967Tune to @var{architecture-type} everything applicable about the generated
7968code, except for the ABI and the set of available instructions. The
7969choices for @var{architecture-type} are the same as for
7970@option{-march=@var{architecture-type}}.
7971
7972@item -mmax-stack-frame=@var{n}
7973@opindex mmax-stack-frame
7974Warn when the stack frame of a function exceeds @var{n} bytes.
7975
7976@item -melinux-stacksize=@var{n}
7977@opindex melinux-stacksize
7978Only available with the @samp{cris-axis-aout} target. Arranges for
7979indications in the program to the kernel loader that the stack of the
7980program should be set to @var{n} bytes.
7981
7982@item -metrax4
7983@itemx -metrax100
7984@opindex metrax4
7985@opindex metrax100
7986The options @option{-metrax4} and @option{-metrax100} are synonyms for
7987@option{-march=v3} and @option{-march=v8} respectively.
7988
7989@item -mmul-bug-workaround
7990@itemx -mno-mul-bug-workaround
7991@opindex mmul-bug-workaround
7992@opindex mno-mul-bug-workaround
7993Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
7994models where it applies. This option is active by default.
7995
7996@item -mpdebug
7997@opindex mpdebug
7998Enable CRIS-specific verbose debug-related information in the assembly
7999code. This option also has the effect to turn off the @samp{#NO_APP}
8000formatted-code indicator to the assembler at the beginning of the
8001assembly file.
8002
8003@item -mcc-init
8004@opindex mcc-init
8005Do not use condition-code results from previous instruction; always emit
8006compare and test instructions before use of condition codes.
8007
8008@item -mno-side-effects
8009@opindex mno-side-effects
8010Do not emit instructions with side-effects in addressing modes other than
8011post-increment.
8012
8013@item -mstack-align
8014@itemx -mno-stack-align
8015@itemx -mdata-align
8016@itemx -mno-data-align
8017@itemx -mconst-align
8018@itemx -mno-const-align
8019@opindex mstack-align
8020@opindex mno-stack-align
8021@opindex mdata-align
8022@opindex mno-data-align
8023@opindex mconst-align
8024@opindex mno-const-align
8025These options (no-options) arranges (eliminate arrangements) for the
8026stack-frame, individual data and constants to be aligned for the maximum
8027single data access size for the chosen CPU model. The default is to
8028arrange for 32-bit alignment. ABI details such as structure layout are
8029not affected by these options.
8030
8031@item -m32-bit
8032@itemx -m16-bit
8033@itemx -m8-bit
8034@opindex m32-bit
8035@opindex m16-bit
8036@opindex m8-bit
8037Similar to the stack- data- and const-align options above, these options
8038arrange for stack-frame, writable data and constants to all be 32-bit,
803916-bit or 8-bit aligned. The default is 32-bit alignment.
8040
8041@item -mno-prologue-epilogue
8042@itemx -mprologue-epilogue
8043@opindex mno-prologue-epilogue
8044@opindex mprologue-epilogue
8045With @option{-mno-prologue-epilogue}, the normal function prologue and
8046epilogue that sets up the stack-frame are omitted and no return
8047instructions or return sequences are generated in the code. Use this
8048option only together with visual inspection of the compiled code: no
8049warnings or errors are generated when call-saved registers must be saved,
8050or storage for local variable needs to be allocated.
8051
8052@item -mno-gotplt
8053@itemx -mgotplt
8054@opindex mno-gotplt
8055@opindex mgotplt
8056With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
8057instruction sequences that load addresses for functions from the PLT part
8058of the GOT rather than (traditional on other architectures) calls to the
8059PLT@. The default is @option{-mgotplt}.
8060
8061@item -maout
8062@opindex maout
8063Legacy no-op option only recognized with the cris-axis-aout target.
8064
8065@item -melf
8066@opindex melf
8067Legacy no-op option only recognized with the cris-axis-elf and
8068cris-axis-linux-gnu targets.
8069
8070@item -melinux
8071@opindex melinux
8072Only recognized with the cris-axis-aout target, where it selects a
8073GNU/linux-like multilib, include files and instruction set for
8074@option{-march=v8}.
8075
8076@item -mlinux
8077@opindex mlinux
8078Legacy no-op option only recognized with the cris-axis-linux-gnu target.
8079
8080@item -sim
8081@opindex sim
8082This option, recognized for the cris-axis-aout and cris-axis-elf arranges
8083to link with input-output functions from a simulator library. Code,
8084initialized data and zero-initialized data are allocated consecutively.
8085
8086@item -sim2
8087@opindex sim2
8088Like @option{-sim}, but pass linker options to locate initialized data at
80890x40000000 and zero-initialized data at 0x80000000.
8090@end table
8091
8092@node CRX Options
8093@subsection CRX Options
8094@cindex CRX Options
8095
8096These options are defined specifically for the CRX ports.
8097
8098@table @gcctabopt
8099
8100@item -mmac
8101@opindex mmac
8102Enable the use of multiply-accumulate instructions. Disabled by default.
8103
8104@item -mpush-args
8105@opindex mpush-args
8106Push instructions will be used to pass outgoing arguments when functions
8107are called. Enabled by default.
8108@end table
8109
8110@node Darwin Options
8111@subsection Darwin Options
8112@cindex Darwin options
8113
8114These options are defined for all architectures running the Darwin operating
8115system.
8116
8117FSF GCC on Darwin does not create ``fat'' object files; it will create
8118an object file for the single architecture that it was built to
8119target. Apple's GCC on Darwin does create ``fat'' files if multiple
8120@option{-arch} options are used; it does so by running the compiler or
8121linker multiple times and joining the results together with
8122@file{lipo}.
8123
8124The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
8125@samp{i686}) is determined by the flags that specify the ISA
8126that GCC is targetting, like @option{-mcpu} or @option{-march}. The
8127@option{-force_cpusubtype_ALL} option can be used to override this.
8128
8129The Darwin tools vary in their behavior when presented with an ISA
8130mismatch. The assembler, @file{as}, will only permit instructions to
8131be used that are valid for the subtype of the file it is generating,
8132so you cannot put 64-bit instructions in an @samp{ppc750} object file.
8133The linker for shared libraries, @file{/usr/bin/libtool}, will fail
8134and print an error if asked to create a shared library with a less
8135restrictive subtype than its input files (for instance, trying to put
8136a @samp{ppc970} object file in a @samp{ppc7400} library). The linker
8137for executables, @file{ld}, will quietly give the executable the most
8138restrictive subtype of any of its input files.
8139
8140@table @gcctabopt
8141@item -F@var{dir}
8142@opindex F
8143Add the framework directory @var{dir} to the head of the list of
8144directories to be searched for header files. These directories are
8145interleaved with those specified by @option{-I} options and are
8146scanned in a left-to-right order.
8147
8148A framework directory is a directory with frameworks in it. A
8149framework is a directory with a @samp{"Headers"} and/or
8150@samp{"PrivateHeaders"} directory contained directly in it that ends
8151in @samp{".framework"}. The name of a framework is the name of this
8152directory excluding the @samp{".framework"}. Headers associated with
8153the framework are found in one of those two directories, with
8154@samp{"Headers"} being searched first. A subframework is a framework
8155directory that is in a framework's @samp{"Frameworks"} directory.
8156Includes of subframework headers can only appear in a header of a
8157framework that contains the subframework, or in a sibling subframework
8158header. Two subframeworks are siblings if they occur in the same
8159framework. A subframework should not have the same name as a
8160framework, a warning will be issued if this is violated. Currently a
8161subframework cannot have subframeworks, in the future, the mechanism
8162may be extended to support this. The standard frameworks can be found
8163in @samp{"/System/Library/Frameworks"} and
8164@samp{"/Library/Frameworks"}. An example include looks like
8165@code{#include <Framework/header.h>}, where @samp{Framework} denotes
8166the name of the framework and header.h is found in the
8167@samp{"PrivateHeaders"} or @samp{"Headers"} directory.
8168
8169@item -gused
8170@opindex gused
8171Emit debugging information for symbols that are used. For STABS
8172debugging format, this enables @option{-feliminate-unused-debug-symbols}.
8173This is by default ON@.
8174
8175@item -gfull
8176@opindex gfull
8177Emit debugging information for all symbols and types.
8178
8179@item -mmacosx-version-min=@var{version}
8180The earliest version of MacOS X that this executable will run on
8181is @var{version}. Typical values of @var{version} include @code{10.1},
8182@code{10.2}, and @code{10.3.9}.
8183
8184The default for this option is to make choices that seem to be most
8185useful.
8186
8187@item -mkernel
8188@opindex mkernel
8189Enable kernel development mode. The @option{-mkernel} option sets
8190@option{-static}, @option{-fno-common}, @option{-fno-cxa-atexit},
8191@option{-fno-exceptions}, @option{-fno-non-call-exceptions},
8192@option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where
8193applicable. This mode also sets @option{-mno-altivec},
8194@option{-msoft-float}, @option{-fno-builtin} and
8195@option{-mlong-branch} for PowerPC targets.
8196
8197@item -mone-byte-bool
8198@opindex mone-byte-bool
8199Override the defaults for @samp{bool} so that @samp{sizeof(bool)==1}.
8200By default @samp{sizeof(bool)} is @samp{4} when compiling for
8201Darwin/PowerPC and @samp{1} when compiling for Darwin/x86, so this
8202option has no effect on x86.
8203
8204@strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
8205to generate code that is not binary compatible with code generated
8206without that switch. Using this switch may require recompiling all
8207other modules in a program, including system libraries. Use this
8208switch to conform to a non-default data model.
8209
8210@item -mfix-and-continue
8211@itemx -ffix-and-continue
8212@itemx -findirect-data
8213@opindex mfix-and-continue
8214@opindex ffix-and-continue
8215@opindex findirect-data
8216Generate code suitable for fast turn around development. Needed to
8217enable gdb to dynamically load @code{.o} files into already running
8218programs. @option{-findirect-data} and @option{-ffix-and-continue}
8219are provided for backwards compatibility.
8220
8221@item -all_load
8222@opindex all_load
8223Loads all members of static archive libraries.
8224See man ld(1) for more information.
8225
8226@item -arch_errors_fatal
8227@opindex arch_errors_fatal
8228Cause the errors having to do with files that have the wrong architecture
8229to be fatal.
8230
8231@item -bind_at_load
8232@opindex bind_at_load
8233Causes the output file to be marked such that the dynamic linker will
8234bind all undefined references when the file is loaded or launched.
8235
8236@item -bundle
8237@opindex bundle
8238Produce a Mach-o bundle format file.
8239See man ld(1) for more information.
8240
8241@item -bundle_loader @var{executable}
8242@opindex bundle_loader
8243This option specifies the @var{executable} that will be loading the build
8244output file being linked. See man ld(1) for more information.
8245
8246@item -dynamiclib
8247@opindex dynamiclib
8248When passed this option, GCC will produce a dynamic library instead of
8249an executable when linking, using the Darwin @file{libtool} command.
8250
8251@item -force_cpusubtype_ALL
8252@opindex force_cpusubtype_ALL
8253This causes GCC's output file to have the @var{ALL} subtype, instead of
8254one controlled by the @option{-mcpu} or @option{-march} option.
8255
8256@item -allowable_client @var{client_name}
8257@itemx -client_name
8258@itemx -compatibility_version
8259@itemx -current_version
8260@itemx -dead_strip
8261@itemx -dependency-file
8262@itemx -dylib_file
8263@itemx -dylinker_install_name
8264@itemx -dynamic
8265@itemx -exported_symbols_list
8266@itemx -filelist
8267@itemx -flat_namespace
8268@itemx -force_flat_namespace
8269@itemx -headerpad_max_install_names
8270@itemx -image_base
8271@itemx -init
8272@itemx -install_name
8273@itemx -keep_private_externs
8274@itemx -multi_module
8275@itemx -multiply_defined
8276@itemx -multiply_defined_unused
8277@itemx -noall_load
8278@itemx -no_dead_strip_inits_and_terms
8279@itemx -nofixprebinding
8280@itemx -nomultidefs
8281@itemx -noprebind
8282@itemx -noseglinkedit
8283@itemx -pagezero_size
8284@itemx -prebind
8285@itemx -prebind_all_twolevel_modules
8286@itemx -private_bundle
8287@itemx -read_only_relocs
8288@itemx -sectalign
8289@itemx -sectobjectsymbols
8290@itemx -whyload
8291@itemx -seg1addr
8292@itemx -sectcreate
8293@itemx -sectobjectsymbols
8294@itemx -sectorder
8295@itemx -segaddr
8296@itemx -segs_read_only_addr
8297@itemx -segs_read_write_addr
8298@itemx -seg_addr_table
8299@itemx -seg_addr_table_filename
8300@itemx -seglinkedit
8301@itemx -segprot
8302@itemx -segs_read_only_addr
8303@itemx -segs_read_write_addr
8304@itemx -single_module
8305@itemx -static
8306@itemx -sub_library
8307@itemx -sub_umbrella
8308@itemx -twolevel_namespace
8309@itemx -umbrella
8310@itemx -undefined
8311@itemx -unexported_symbols_list
8312@itemx -weak_reference_mismatches
8313@itemx -whatsloaded
8314
8315@opindex allowable_client
8316@opindex client_name
8317@opindex compatibility_version
8318@opindex current_version
8319@opindex dead_strip
8320@opindex dependency-file
8321@opindex dylib_file
8322@opindex dylinker_install_name
8323@opindex dynamic
8324@opindex exported_symbols_list
8325@opindex filelist
8326@opindex flat_namespace
8327@opindex force_flat_namespace
8328@opindex headerpad_max_install_names
8329@opindex image_base
8330@opindex init
8331@opindex install_name
8332@opindex keep_private_externs
8333@opindex multi_module
8334@opindex multiply_defined
8335@opindex multiply_defined_unused
8336@opindex noall_load
8337@opindex no_dead_strip_inits_and_terms
8338@opindex nofixprebinding
8339@opindex nomultidefs
8340@opindex noprebind
8341@opindex noseglinkedit
8342@opindex pagezero_size
8343@opindex prebind
8344@opindex prebind_all_twolevel_modules
8345@opindex private_bundle
8346@opindex read_only_relocs
8347@opindex sectalign
8348@opindex sectobjectsymbols
8349@opindex whyload
8350@opindex seg1addr
8351@opindex sectcreate
8352@opindex sectobjectsymbols
8353@opindex sectorder
8354@opindex segaddr
8355@opindex segs_read_only_addr
8356@opindex segs_read_write_addr
8357@opindex seg_addr_table
8358@opindex seg_addr_table_filename
8359@opindex seglinkedit
8360@opindex segprot
8361@opindex segs_read_only_addr
8362@opindex segs_read_write_addr
8363@opindex single_module
8364@opindex static
8365@opindex sub_library
8366@opindex sub_umbrella
8367@opindex twolevel_namespace
8368@opindex umbrella
8369@opindex undefined
8370@opindex unexported_symbols_list
8371@opindex weak_reference_mismatches
8372@opindex whatsloaded
8373
8374These options are passed to the Darwin linker. The Darwin linker man page
8375describes them in detail.
8376@end table
8377
8378@node DEC Alpha Options
8379@subsection DEC Alpha Options
8380
8381These @samp{-m} options are defined for the DEC Alpha implementations:
8382
8383@table @gcctabopt
8384@item -mno-soft-float
8385@itemx -msoft-float
8386@opindex mno-soft-float
8387@opindex msoft-float
8388Use (do not use) the hardware floating-point instructions for
8389floating-point operations. When @option{-msoft-float} is specified,
8390functions in @file{libgcc.a} will be used to perform floating-point
8391operations. Unless they are replaced by routines that emulate the
8392floating-point operations, or compiled in such a way as to call such
8393emulations routines, these routines will issue floating-point
8394operations. If you are compiling for an Alpha without floating-point
8395operations, you must ensure that the library is built so as not to call
8396them.
8397
8398Note that Alpha implementations without floating-point operations are
8399required to have floating-point registers.
8400
8401@item -mfp-reg
8402@itemx -mno-fp-regs
8403@opindex mfp-reg
8404@opindex mno-fp-regs
8405Generate code that uses (does not use) the floating-point register set.
8406@option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
8407register set is not used, floating point operands are passed in integer
8408registers as if they were integers and floating-point results are passed
8409in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
8410so any function with a floating-point argument or return value called by code
8411compiled with @option{-mno-fp-regs} must also be compiled with that
8412option.
8413
8414A typical use of this option is building a kernel that does not use,
8415and hence need not save and restore, any floating-point registers.
8416
8417@item -mieee
8418@opindex mieee
8419The Alpha architecture implements floating-point hardware optimized for
8420maximum performance. It is mostly compliant with the IEEE floating
8421point standard. However, for full compliance, software assistance is
8422required. This option generates code fully IEEE compliant code
8423@emph{except} that the @var{inexact-flag} is not maintained (see below).
8424If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
8425defined during compilation. The resulting code is less efficient but is
8426able to correctly support denormalized numbers and exceptional IEEE
8427values such as not-a-number and plus/minus infinity. Other Alpha
8428compilers call this option @option{-ieee_with_no_inexact}.
8429
8430@item -mieee-with-inexact
8431@opindex mieee-with-inexact
8432This is like @option{-mieee} except the generated code also maintains
8433the IEEE @var{inexact-flag}. Turning on this option causes the
8434generated code to implement fully-compliant IEEE math. In addition to
8435@code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
8436macro. On some Alpha implementations the resulting code may execute
8437significantly slower than the code generated by default. Since there is
8438very little code that depends on the @var{inexact-flag}, you should
8439normally not specify this option. Other Alpha compilers call this
8440option @option{-ieee_with_inexact}.
8441
8442@item -mfp-trap-mode=@var{trap-mode}
8443@opindex mfp-trap-mode
8444This option controls what floating-point related traps are enabled.
8445Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
8446The trap mode can be set to one of four values:
8447
8448@table @samp
8449@item n
8450This is the default (normal) setting. The only traps that are enabled
8451are the ones that cannot be disabled in software (e.g., division by zero
8452trap).
8453
8454@item u
8455In addition to the traps enabled by @samp{n}, underflow traps are enabled
8456as well.
8457
8458@item su
8459Like @samp{u}, but the instructions are marked to be safe for software
8460completion (see Alpha architecture manual for details).
8461
8462@item sui
8463Like @samp{su}, but inexact traps are enabled as well.
8464@end table
8465
8466@item -mfp-rounding-mode=@var{rounding-mode}
8467@opindex mfp-rounding-mode
8468Selects the IEEE rounding mode. Other Alpha compilers call this option
8469@option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
8470of:
8471
8472@table @samp
8473@item n
8474Normal IEEE rounding mode. Floating point numbers are rounded towards
8475the nearest machine number or towards the even machine number in case
8476of a tie.
8477
8478@item m
8479Round towards minus infinity.
8480
8481@item c
8482Chopped rounding mode. Floating point numbers are rounded towards zero.
8483
8484@item d
8485Dynamic rounding mode. A field in the floating point control register
8486(@var{fpcr}, see Alpha architecture reference manual) controls the
8487rounding mode in effect. The C library initializes this register for
8488rounding towards plus infinity. Thus, unless your program modifies the
8489@var{fpcr}, @samp{d} corresponds to round towards plus infinity.
8490@end table
8491
8492@item -mtrap-precision=@var{trap-precision}
8493@opindex mtrap-precision
8494In the Alpha architecture, floating point traps are imprecise. This
8495means without software assistance it is impossible to recover from a
8496floating trap and program execution normally needs to be terminated.
8497GCC can generate code that can assist operating system trap handlers
8498in determining the exact location that caused a floating point trap.
8499Depending on the requirements of an application, different levels of
8500precisions can be selected:
8501
8502@table @samp
8503@item p
8504Program precision. This option is the default and means a trap handler
8505can only identify which program caused a floating point exception.
8506
8507@item f
8508Function precision. The trap handler can determine the function that
8509caused a floating point exception.
8510
8511@item i
8512Instruction precision. The trap handler can determine the exact
8513instruction that caused a floating point exception.
8514@end table
8515
8516Other Alpha compilers provide the equivalent options called
8517@option{-scope_safe} and @option{-resumption_safe}.
8518
8519@item -mieee-conformant
8520@opindex mieee-conformant
8521This option marks the generated code as IEEE conformant. You must not
8522use this option unless you also specify @option{-mtrap-precision=i} and either
8523@option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
8524is to emit the line @samp{.eflag 48} in the function prologue of the
8525generated assembly file. Under DEC Unix, this has the effect that
8526IEEE-conformant math library routines will be linked in.
8527
8528@item -mbuild-constants
8529@opindex mbuild-constants
8530Normally GCC examines a 32- or 64-bit integer constant to
8531see if it can construct it from smaller constants in two or three
8532instructions. If it cannot, it will output the constant as a literal and
8533generate code to load it from the data segment at runtime.
8534
8535Use this option to require GCC to construct @emph{all} integer constants
8536using code, even if it takes more instructions (the maximum is six).
8537
8538You would typically use this option to build a shared library dynamic
8539loader. Itself a shared library, it must relocate itself in memory
8540before it can find the variables and constants in its own data segment.
8541
8542@item -malpha-as
8543@itemx -mgas
8544@opindex malpha-as
8545@opindex mgas
8546Select whether to generate code to be assembled by the vendor-supplied
8547assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
8548
8549@item -mbwx
8550@itemx -mno-bwx
8551@itemx -mcix
8552@itemx -mno-cix
8553@itemx -mfix
8554@itemx -mno-fix
8555@itemx -mmax
8556@itemx -mno-max
8557@opindex mbwx
8558@opindex mno-bwx
8559@opindex mcix
8560@opindex mno-cix
8561@opindex mfix
8562@opindex mno-fix
8563@opindex mmax
8564@opindex mno-max
8565Indicate whether GCC should generate code to use the optional BWX,
8566CIX, FIX and MAX instruction sets. The default is to use the instruction
8567sets supported by the CPU type specified via @option{-mcpu=} option or that
8568of the CPU on which GCC was built if none was specified.
8569
8570@item -mfloat-vax
8571@itemx -mfloat-ieee
8572@opindex mfloat-vax
8573@opindex mfloat-ieee
8574Generate code that uses (does not use) VAX F and G floating point
8575arithmetic instead of IEEE single and double precision.
8576
8577@item -mexplicit-relocs
8578@itemx -mno-explicit-relocs
8579@opindex mexplicit-relocs
8580@opindex mno-explicit-relocs
8581Older Alpha assemblers provided no way to generate symbol relocations
8582except via assembler macros. Use of these macros does not allow
8583optimal instruction scheduling. GNU binutils as of version 2.12
8584supports a new syntax that allows the compiler to explicitly mark
8585which relocations should apply to which instructions. This option
8586is mostly useful for debugging, as GCC detects the capabilities of
8587the assembler when it is built and sets the default accordingly.
8588
8589@item -msmall-data
8590@itemx -mlarge-data
8591@opindex msmall-data
8592@opindex mlarge-data
8593When @option{-mexplicit-relocs} is in effect, static data is
8594accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
8595is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
8596(the @code{.sdata} and @code{.sbss} sections) and are accessed via
859716-bit relocations off of the @code{$gp} register. This limits the
8598size of the small data area to 64KB, but allows the variables to be
8599directly accessed via a single instruction.
8600
8601The default is @option{-mlarge-data}. With this option the data area
8602is limited to just below 2GB@. Programs that require more than 2GB of
8603data must use @code{malloc} or @code{mmap} to allocate the data in the
8604heap instead of in the program's data segment.
8605
8606When generating code for shared libraries, @option{-fpic} implies
8607@option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
8608
8609@item -msmall-text
8610@itemx -mlarge-text
8611@opindex msmall-text
8612@opindex mlarge-text
8613When @option{-msmall-text} is used, the compiler assumes that the
8614code of the entire program (or shared library) fits in 4MB, and is
8615thus reachable with a branch instruction. When @option{-msmall-data}
8616is used, the compiler can assume that all local symbols share the
8617same @code{$gp} value, and thus reduce the number of instructions
8618required for a function call from 4 to 1.
8619
8620The default is @option{-mlarge-text}.
8621
8622@item -mcpu=@var{cpu_type}
8623@opindex mcpu
8624Set the instruction set and instruction scheduling parameters for
8625machine type @var{cpu_type}. You can specify either the @samp{EV}
8626style name or the corresponding chip number. GCC supports scheduling
8627parameters for the EV4, EV5 and EV6 family of processors and will
8628choose the default values for the instruction set from the processor
8629you specify. If you do not specify a processor type, GCC will default
8630to the processor on which the compiler was built.
8631
8632Supported values for @var{cpu_type} are
8633
8634@table @samp
8635@item ev4
8636@itemx ev45
8637@itemx 21064
8638Schedules as an EV4 and has no instruction set extensions.
8639
8640@item ev5
8641@itemx 21164
8642Schedules as an EV5 and has no instruction set extensions.
8643
8644@item ev56
8645@itemx 21164a
8646Schedules as an EV5 and supports the BWX extension.
8647
8648@item pca56
8649@itemx 21164pc
8650@itemx 21164PC
8651Schedules as an EV5 and supports the BWX and MAX extensions.
8652
8653@item ev6
8654@itemx 21264
8655Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
8656
8657@item ev67
8658@itemx 21264a
8659Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
8660@end table
8661
8662@item -mtune=@var{cpu_type}
8663@opindex mtune
8664Set only the instruction scheduling parameters for machine type
8665@var{cpu_type}. The instruction set is not changed.
8666
8667@item -mmemory-latency=@var{time}
8668@opindex mmemory-latency
8669Sets the latency the scheduler should assume for typical memory
8670references as seen by the application. This number is highly
8671dependent on the memory access patterns used by the application
8672and the size of the external cache on the machine.
8673
8674Valid options for @var{time} are
8675
8676@table @samp
8677@item @var{number}
8678A decimal number representing clock cycles.
8679
8680@item L1
8681@itemx L2
8682@itemx L3
8683@itemx main
8684The compiler contains estimates of the number of clock cycles for
8685``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
8686(also called Dcache, Scache, and Bcache), as well as to main memory.
8687Note that L3 is only valid for EV5.
8688
8689@end table
8690@end table
8691
8692@node DEC Alpha/VMS Options
8693@subsection DEC Alpha/VMS Options
8694
8695These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
8696
8697@table @gcctabopt
8698@item -mvms-return-codes
8699@opindex mvms-return-codes
8700Return VMS condition codes from main. The default is to return POSIX
8701style condition (e.g.@ error) codes.
8702@end table
8703
8704@node FRV Options
8705@subsection FRV Options
8706@cindex FRV Options
8707
8708@table @gcctabopt
8709@item -mgpr-32
8710@opindex mgpr-32
8711
8712Only use the first 32 general purpose registers.
8713
8714@item -mgpr-64
8715@opindex mgpr-64
8716
8717Use all 64 general purpose registers.
8718
8719@item -mfpr-32
8720@opindex mfpr-32
8721
8722Use only the first 32 floating point registers.
8723
8724@item -mfpr-64
8725@opindex mfpr-64
8726
8727Use all 64 floating point registers
8728
8729@item -mhard-float
8730@opindex mhard-float
8731
8732Use hardware instructions for floating point operations.
8733
8734@item -msoft-float
8735@opindex msoft-float
8736
8737Use library routines for floating point operations.
8738
8739@item -malloc-cc
8740@opindex malloc-cc
8741
8742Dynamically allocate condition code registers.
8743
8744@item -mfixed-cc
8745@opindex mfixed-cc
8746
8747Do not try to dynamically allocate condition code registers, only
8748use @code{icc0} and @code{fcc0}.
8749
8750@item -mdword
8751@opindex mdword
8752
8753Change ABI to use double word insns.
8754
8755@item -mno-dword
8756@opindex mno-dword
8757
8758Do not use double word instructions.
8759
8760@item -mdouble
8761@opindex mdouble
8762
8763Use floating point double instructions.
8764
8765@item -mno-double
8766@opindex mno-double
8767
8768Do not use floating point double instructions.
8769
8770@item -mmedia
8771@opindex mmedia
8772
8773Use media instructions.
8774
8775@item -mno-media
8776@opindex mno-media
8777
8778Do not use media instructions.
8779
8780@item -mmuladd
8781@opindex mmuladd
8782
8783Use multiply and add/subtract instructions.
8784
8785@item -mno-muladd
8786@opindex mno-muladd
8787
8788Do not use multiply and add/subtract instructions.
8789
8790@item -mfdpic
8791@opindex mfdpic
8792
8793Select the FDPIC ABI, that uses function descriptors to represent
8794pointers to functions. Without any PIC/PIE-related options, it
8795implies @option{-fPIE}. With @option{-fpic} or @option{-fpie}, it
8796assumes GOT entries and small data are within a 12-bit range from the
8797GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
8798are computed with 32 bits.
8799
8800@item -minline-plt
8801@opindex minline-plt
8802
8803Enable inlining of PLT entries in function calls to functions that are
8804not known to bind locally. It has no effect without @option{-mfdpic}.
8805It's enabled by default if optimizing for speed and compiling for
8806shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
8807optimization option such as @option{-O3} or above is present in the
8808command line.
8809
8810@item -mTLS
8811@opindex TLS
8812
8813Assume a large TLS segment when generating thread-local code.
8814
8815@item -mtls
8816@opindex tls
8817
8818Do not assume a large TLS segment when generating thread-local code.
8819
8820@item -mgprel-ro
8821@opindex mgprel-ro
8822
8823Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
8824that is known to be in read-only sections. It's enabled by default,
8825except for @option{-fpic} or @option{-fpie}: even though it may help
8826make the global offset table smaller, it trades 1 instruction for 4.
8827With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
8828one of which may be shared by multiple symbols, and it avoids the need
8829for a GOT entry for the referenced symbol, so it's more likely to be a
8830win. If it is not, @option{-mno-gprel-ro} can be used to disable it.
8831
8832@item -multilib-library-pic
8833@opindex multilib-library-pic
8834
8835Link with the (library, not FD) pic libraries. It's implied by
8836@option{-mlibrary-pic}, as well as by @option{-fPIC} and
8837@option{-fpic} without @option{-mfdpic}. You should never have to use
8838it explicitly.
8839
8840@item -mlinked-fp
8841@opindex mlinked-fp
8842
8843Follow the EABI requirement of always creating a frame pointer whenever
8844a stack frame is allocated. This option is enabled by default and can
8845be disabled with @option{-mno-linked-fp}.
8846
8847@item -mlong-calls
8848@opindex mlong-calls
8849
8850Use indirect addressing to call functions outside the current
8851compilation unit. This allows the functions to be placed anywhere
8852within the 32-bit address space.
8853
8854@item -malign-labels
8855@opindex malign-labels
8856
8857Try to align labels to an 8-byte boundary by inserting nops into the
8858previous packet. This option only has an effect when VLIW packing
8859is enabled. It doesn't create new packets; it merely adds nops to
8860existing ones.
8861
8862@item -mlibrary-pic
8863@opindex mlibrary-pic
8864
8865Generate position-independent EABI code.
8866
8867@item -macc-4
8868@opindex macc-4
8869
8870Use only the first four media accumulator registers.
8871
8872@item -macc-8
8873@opindex macc-8
8874
8875Use all eight media accumulator registers.
8876
8877@item -mpack
8878@opindex mpack
8879
8880Pack VLIW instructions.
8881
8882@item -mno-pack
8883@opindex mno-pack
8884
8885Do not pack VLIW instructions.
8886
8887@item -mno-eflags
8888@opindex mno-eflags
8889
8890Do not mark ABI switches in e_flags.
8891
8892@item -mcond-move
8893@opindex mcond-move
8894
8895Enable the use of conditional-move instructions (default).
8896
8897This switch is mainly for debugging the compiler and will likely be removed
8898in a future version.
8899
8900@item -mno-cond-move
8901@opindex mno-cond-move
8902
8903Disable the use of conditional-move instructions.
8904
8905This switch is mainly for debugging the compiler and will likely be removed
8906in a future version.
8907
8908@item -mscc
8909@opindex mscc
8910
8911Enable the use of conditional set instructions (default).
8912
8913This switch is mainly for debugging the compiler and will likely be removed
8914in a future version.
8915
8916@item -mno-scc
8917@opindex mno-scc
8918
8919Disable the use of conditional set instructions.
8920
8921This switch is mainly for debugging the compiler and will likely be removed
8922in a future version.
8923
8924@item -mcond-exec
8925@opindex mcond-exec
8926
8927Enable the use of conditional execution (default).
8928
8929This switch is mainly for debugging the compiler and will likely be removed
8930in a future version.
8931
8932@item -mno-cond-exec
8933@opindex mno-cond-exec
8934
8935Disable the use of conditional execution.
8936
8937This switch is mainly for debugging the compiler and will likely be removed
8938in a future version.
8939
8940@item -mvliw-branch
8941@opindex mvliw-branch
8942
8943Run a pass to pack branches into VLIW instructions (default).
8944
8945This switch is mainly for debugging the compiler and will likely be removed
8946in a future version.
8947
8948@item -mno-vliw-branch
8949@opindex mno-vliw-branch
8950
8951Do not run a pass to pack branches into VLIW instructions.
8952
8953This switch is mainly for debugging the compiler and will likely be removed
8954in a future version.
8955
8956@item -mmulti-cond-exec
8957@opindex mmulti-cond-exec
8958
8959Enable optimization of @code{&&} and @code{||} in conditional execution
8960(default).
8961
8962This switch is mainly for debugging the compiler and will likely be removed
8963in a future version.
8964
8965@item -mno-multi-cond-exec
8966@opindex mno-multi-cond-exec
8967
8968Disable optimization of @code{&&} and @code{||} in conditional execution.
8969
8970This switch is mainly for debugging the compiler and will likely be removed
8971in a future version.
8972
8973@item -mnested-cond-exec
8974@opindex mnested-cond-exec
8975
8976Enable nested conditional execution optimizations (default).
8977
8978This switch is mainly for debugging the compiler and will likely be removed
8979in a future version.
8980
8981@item -mno-nested-cond-exec
8982@opindex mno-nested-cond-exec
8983
8984Disable nested conditional execution optimizations.
8985
8986This switch is mainly for debugging the compiler and will likely be removed
8987in a future version.
8988
8989@item -moptimize-membar
8990@opindex moptimize-membar
8991
8992This switch removes redundant @code{membar} instructions from the
8993compiler generated code. It is enabled by default.
8994
8995@item -mno-optimize-membar
8996@opindex mno-optimize-membar
8997
8998This switch disables the automatic removal of redundant @code{membar}
8999instructions from the generated code.
9000
9001@item -mtomcat-stats
9002@opindex mtomcat-stats
9003
9004Cause gas to print out tomcat statistics.
9005
9006@item -mcpu=@var{cpu}
9007@opindex mcpu
9008
9009Select the processor type for which to generate code. Possible values are
9010@samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
9011@samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
9012
9013@end table
9014
9015@node GNU/Linux Options
9016@subsection GNU/Linux Options
9017
9018These @samp{-m} options are defined for GNU/Linux targets:
9019
9020@table @gcctabopt
9021@item -mglibc
9022@opindex mglibc
9023Use the GNU C library instead of uClibc. This is the default except
9024on @samp{*-*-linux-*uclibc*} targets.
9025
9026@item -muclibc
9027@opindex muclibc
9028Use uClibc instead of the GNU C library. This is the default on
9029@samp{*-*-linux-*uclibc*} targets.
9030@end table
9031
9032@node H8/300 Options
9033@subsection H8/300 Options
9034
9035These @samp{-m} options are defined for the H8/300 implementations:
9036
9037@table @gcctabopt
9038@item -mrelax
9039@opindex mrelax
9040Shorten some address references at link time, when possible; uses the
9041linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
9042ld, Using ld}, for a fuller description.
9043
9044@item -mh
9045@opindex mh
9046Generate code for the H8/300H@.
9047
9048@item -ms
9049@opindex ms
9050Generate code for the H8S@.
9051
9052@item -mn
9053@opindex mn
9054Generate code for the H8S and H8/300H in the normal mode. This switch
9055must be used either with @option{-mh} or @option{-ms}.
9056
9057@item -ms2600
9058@opindex ms2600
9059Generate code for the H8S/2600. This switch must be used with @option{-ms}.
9060
9061@item -mint32
9062@opindex mint32
9063Make @code{int} data 32 bits by default.
9064
9065@item -malign-300
9066@opindex malign-300
9067On the H8/300H and H8S, use the same alignment rules as for the H8/300.
9068The default for the H8/300H and H8S is to align longs and floats on 4
9069byte boundaries.
9070@option{-malign-300} causes them to be aligned on 2 byte boundaries.
9071This option has no effect on the H8/300.
9072@end table
9073
9074@node HPPA Options
9075@subsection HPPA Options
9076@cindex HPPA Options
9077
9078These @samp{-m} options are defined for the HPPA family of computers:
9079
9080@table @gcctabopt
9081@item -march=@var{architecture-type}
9082@opindex march
9083Generate code for the specified architecture. The choices for
9084@var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
90851.1, and @samp{2.0} for PA 2.0 processors. Refer to
9086@file{/usr/lib/sched.models} on an HP-UX system to determine the proper
9087architecture option for your machine. Code compiled for lower numbered
9088architectures will run on higher numbered architectures, but not the
9089other way around.
9090
9091@item -mpa-risc-1-0
9092@itemx -mpa-risc-1-1
9093@itemx -mpa-risc-2-0
9094@opindex mpa-risc-1-0
9095@opindex mpa-risc-1-1
9096@opindex mpa-risc-2-0
9097Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
9098
9099@item -mbig-switch
9100@opindex mbig-switch
9101Generate code suitable for big switch tables. Use this option only if
9102the assembler/linker complain about out of range branches within a switch
9103table.
9104
9105@item -mjump-in-delay
9106@opindex mjump-in-delay
9107Fill delay slots of function calls with unconditional jump instructions
9108by modifying the return pointer for the function call to be the target
9109of the conditional jump.
9110
9111@item -mdisable-fpregs
9112@opindex mdisable-fpregs
9113Prevent floating point registers from being used in any manner. This is
9114necessary for compiling kernels which perform lazy context switching of
9115floating point registers. If you use this option and attempt to perform
9116floating point operations, the compiler will abort.
9117
9118@item -mdisable-indexing
9119@opindex mdisable-indexing
9120Prevent the compiler from using indexing address modes. This avoids some
9121rather obscure problems when compiling MIG generated code under MACH@.
9122
9123@item -mno-space-regs
9124@opindex mno-space-regs
9125Generate code that assumes the target has no space registers. This allows
9126GCC to generate faster indirect calls and use unscaled index address modes.
9127
9128Such code is suitable for level 0 PA systems and kernels.
9129
9130@item -mfast-indirect-calls
9131@opindex mfast-indirect-calls
9132Generate code that assumes calls never cross space boundaries. This
9133allows GCC to emit code which performs faster indirect calls.
9134
9135This option will not work in the presence of shared libraries or nested
9136functions.
9137
9138@item -mfixed-range=@var{register-range}
9139@opindex mfixed-range
9140Generate code treating the given register range as fixed registers.
9141A fixed register is one that the register allocator can not use. This is
9142useful when compiling kernel code. A register range is specified as
9143two registers separated by a dash. Multiple register ranges can be
9144specified separated by a comma.
9145
9146@item -mlong-load-store
9147@opindex mlong-load-store
9148Generate 3-instruction load and store sequences as sometimes required by
9149the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
9150the HP compilers.
9151
9152@item -mportable-runtime
9153@opindex mportable-runtime
9154Use the portable calling conventions proposed by HP for ELF systems.
9155
9156@item -mgas
9157@opindex mgas
9158Enable the use of assembler directives only GAS understands.
9159
9160@item -mschedule=@var{cpu-type}
9161@opindex mschedule
9162Schedule code according to the constraints for the machine type
9163@var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
9164@samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer
9165to @file{/usr/lib/sched.models} on an HP-UX system to determine the
9166proper scheduling option for your machine. The default scheduling is
9167@samp{8000}.
9168
9169@item -mlinker-opt
9170@opindex mlinker-opt
9171Enable the optimization pass in the HP-UX linker. Note this makes symbolic
9172debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9
9173linkers in which they give bogus error messages when linking some programs.
9174
9175@item -msoft-float
9176@opindex msoft-float
9177Generate output containing library calls for floating point.
9178@strong{Warning:} the requisite libraries are not available for all HPPA
9179targets. Normally the facilities of the machine's usual C compiler are
9180used, but this cannot be done directly in cross-compilation. You must make
9181your own arrangements to provide suitable library functions for
9182cross-compilation. The embedded target @samp{hppa1.1-*-pro}
9183does provide software floating point support.
9184
9185@option{-msoft-float} changes the calling convention in the output file;
9186therefore, it is only useful if you compile @emph{all} of a program with
9187this option. In particular, you need to compile @file{libgcc.a}, the
9188library that comes with GCC, with @option{-msoft-float} in order for
9189this to work.
9190
9191@item -msio
9192@opindex msio
9193Generate the predefine, @code{_SIO}, for server IO@. The default is
9194@option{-mwsio}. This generates the predefines, @code{__hp9000s700},
9195@code{__hp9000s700__} and @code{_WSIO}, for workstation IO@. These
9196options are available under HP-UX and HI-UX@.
9197
9198@item -mgnu-ld
9199@opindex gnu-ld
9200Use GNU ld specific options. This passes @option{-shared} to ld when
9201building a shared library. It is the default when GCC is configured,
9202explicitly or implicitly, with the GNU linker. This option does not
9203have any affect on which ld is called, it only changes what parameters
9204are passed to that ld. The ld that is called is determined by the
9205@option{--with-ld} configure option, GCC's program search path, and
9206finally by the user's @env{PATH}. The linker used by GCC can be printed
9207using @samp{which `gcc -print-prog-name=ld`}. This option is only available
9208on the 64 bit HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
9209
9210@item -mhp-ld
9211@opindex hp-ld
9212Use HP ld specific options. This passes @option{-b} to ld when building
9213a shared library and passes @option{+Accept TypeMismatch} to ld on all
9214links. It is the default when GCC is configured, explicitly or
9215implicitly, with the HP linker. This option does not have any affect on
9216which ld is called, it only changes what parameters are passed to that
9217ld. The ld that is called is determined by the @option{--with-ld}
9218configure option, GCC's program search path, and finally by the user's
9219@env{PATH}. The linker used by GCC can be printed using @samp{which
9220`gcc -print-prog-name=ld`}. This option is only available on the 64 bit
9221HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
9222
9223@item -mlong-calls
9224@opindex mno-long-calls
9225Generate code that uses long call sequences. This ensures that a call
9226is always able to reach linker generated stubs. The default is to generate
9227long calls only when the distance from the call site to the beginning
9228of the function or translation unit, as the case may be, exceeds a
9229predefined limit set by the branch type being used. The limits for
9230normal calls are 7,600,000 and 240,000 bytes, respectively for the
9231PA 2.0 and PA 1.X architectures. Sibcalls are always limited at
9232240,000 bytes.
9233
9234Distances are measured from the beginning of functions when using the
9235@option{-ffunction-sections} option, or when using the @option{-mgas}
9236and @option{-mno-portable-runtime} options together under HP-UX with
9237the SOM linker.
9238
9239It is normally not desirable to use this option as it will degrade
9240performance. However, it may be useful in large applications,
9241particularly when partial linking is used to build the application.
9242
9243The types of long calls used depends on the capabilities of the
9244assembler and linker, and the type of code being generated. The
9245impact on systems that support long absolute calls, and long pic
9246symbol-difference or pc-relative calls should be relatively small.
9247However, an indirect call is used on 32-bit ELF systems in pic code
9248and it is quite long.
9249
9250@item -munix=@var{unix-std}
9251@opindex march
9252Generate compiler predefines and select a startfile for the specified
9253UNIX standard. The choices for @var{unix-std} are @samp{93}, @samp{95}
9254and @samp{98}. @samp{93} is supported on all HP-UX versions. @samp{95}
9255is available on HP-UX 10.10 and later. @samp{98} is available on HP-UX
925611.11 and later. The default values are @samp{93} for HP-UX 10.00,
9257@samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
9258and later.
9259
9260@option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
9261@option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
9262and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
9263@option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
9264@code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
9265@code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
9266
9267It is @emph{important} to note that this option changes the interfaces
9268for various library routines. It also affects the operational behavior
9269of the C library. Thus, @emph{extreme} care is needed in using this
9270option.
9271
9272Library code that is intended to operate with more than one UNIX
9273standard must test, set and restore the variable @var{__xpg4_extended_mask}
9274as appropriate. Most GNU software doesn't provide this capability.
9275
9276@item -nolibdld
9277@opindex nolibdld
9278Suppress the generation of link options to search libdld.sl when the
9279@option{-static} option is specified on HP-UX 10 and later.
9280
9281@item -static
9282@opindex static
9283The HP-UX implementation of setlocale in libc has a dependency on
9284libdld.sl. There isn't an archive version of libdld.sl. Thus,
9285when the @option{-static} option is specified, special link options
9286are needed to resolve this dependency.
9287
9288On HP-UX 10 and later, the GCC driver adds the necessary options to
9289link with libdld.sl when the @option{-static} option is specified.
9290This causes the resulting binary to be dynamic. On the 64-bit port,
9291the linkers generate dynamic binaries by default in any case. The
9292@option{-nolibdld} option can be used to prevent the GCC driver from
9293adding these link options.
9294
9295@item -threads
9296@opindex threads
9297Add support for multithreading with the @dfn{dce thread} library
9298under HP-UX@. This option sets flags for both the preprocessor and
9299linker.
9300@end table
9301
9302@node i386 and x86-64 Options
9303@subsection Intel 386 and AMD x86-64 Options
9304@cindex i386 Options
9305@cindex x86-64 Options
9306@cindex Intel 386 Options
9307@cindex AMD x86-64 Options
9308
9309These @samp{-m} options are defined for the i386 and x86-64 family of
9310computers:
9311
9312@table @gcctabopt
9313@item -mtune=@var{cpu-type}
9314@opindex mtune
9315Tune to @var{cpu-type} everything applicable about the generated code, except
9316for the ABI and the set of available instructions. The choices for
9317@var{cpu-type} are:
9318@table @emph
9319@item generic
9320Produce code optimized for the most common IA32/AMD64/EM64T processors.
9321If you know the CPU on which your code will run, then you should use
9322the corresponding @option{-mtune} option instead of
9323@option{-mtune=generic}. But, if you do not know exactly what CPU users
9324of your application will have, then you should use this option.
9325
9326As new processors are deployed in the marketplace, the behavior of this
9327option will change. Therefore, if you upgrade to a newer version of
9328GCC, the code generated option will change to reflect the processors
9329that were most common when that version of GCC was released.
9330
9331There is no @option{-march=generic} option because @option{-march}
9332indicates the instruction set the compiler can use, and there is no
9333generic instruction set applicable to all processors. In contrast,
9334@option{-mtune} indicates the processor (or, in this case, collection of
9335processors) for which the code is optimized.
9336@item native
9337This selects the CPU to tune for at compilation time by determining
9338the processor type of the compiling machine. Using @option{-mtune=native}
9339will produce code optimized for the local machine under the constraints
9340of the selected instruction set. Using @option{-march=native} will
9341enable all instruction subsets supported by the local machine (hence
9342the result might not run on different machines).
9343@item i386
9344Original Intel's i386 CPU@.
9345@item i486
9346Intel's i486 CPU@. (No scheduling is implemented for this chip.)
9347@item i586, pentium
9348Intel Pentium CPU with no MMX support.
9349@item pentium-mmx
9350Intel PentiumMMX CPU based on Pentium core with MMX instruction set support.
9351@item pentiumpro
9352Intel PentiumPro CPU@.
9353@item i686
9354Same as @code{generic}, but when used as @code{march} option, PentiumPro
9355instruction set will be used, so the code will run on all i686 family chips.
9356@item pentium2
9357Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support.
9358@item pentium3, pentium3m
9359Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set
9360support.
9361@item pentium-m
9362Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set
9363support. Used by Centrino notebooks.
9364@item pentium4, pentium4m
9365Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support.
9366@item prescott
9367Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction
9368set support.
9369@item nocona
9370Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE,
9371SSE2 and SSE3 instruction set support.
9372@item k6
9373AMD K6 CPU with MMX instruction set support.
9374@item k6-2, k6-3
9375Improved versions of AMD K6 CPU with MMX and 3dNOW! instruction set support.
9376@item athlon, athlon-tbird
9377AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and SSE prefetch instructions
9378support.
9379@item athlon-4, athlon-xp, athlon-mp
9380Improved AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and full SSE
9381instruction set support.
9382@item k8, opteron, athlon64, athlon-fx
9383AMD K8 core based CPUs with x86-64 instruction set support. (This supersets
9384MMX, SSE, SSE2, 3dNOW!, enhanced 3dNOW! and 64-bit instruction set extensions.)
9385@item winchip-c6
9386IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction
9387set support.
9388@item winchip2
9389IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3dNOW!
9390instruction set support.
9391@item c3
9392Via C3 CPU with MMX and 3dNOW! instruction set support. (No scheduling is
9393implemented for this chip.)
9394@item c3-2
9395Via C3-2 CPU with MMX and SSE instruction set support. (No scheduling is
9396implemented for this chip.)
9397@end table
9398
9399While picking a specific @var{cpu-type} will schedule things appropriately
9400for that particular chip, the compiler will not generate any code that
9401does not run on the i386 without the @option{-march=@var{cpu-type}} option
9402being used.
9403
9404@item -march=@var{cpu-type}
9405@opindex march
9406Generate instructions for the machine type @var{cpu-type}. The choices
9407for @var{cpu-type} are the same as for @option{-mtune}. Moreover,
9408specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}.
9409
9410@item -mcpu=@var{cpu-type}
9411@opindex mcpu
9412A deprecated synonym for @option{-mtune}.
9413
9414@item -m386
9415@itemx -m486
9416@itemx -mpentium
9417@itemx -mpentiumpro
9418@opindex m386
9419@opindex m486
9420@opindex mpentium
9421@opindex mpentiumpro
9422These options are synonyms for @option{-mtune=i386}, @option{-mtune=i486},
9423@option{-mtune=pentium}, and @option{-mtune=pentiumpro} respectively.
9424These synonyms are deprecated.
9425
9426@item -mfpmath=@var{unit}
9427@opindex march
9428Generate floating point arithmetics for selected unit @var{unit}. The choices
9429for @var{unit} are:
9430
9431@table @samp
9432@item 387
9433Use the standard 387 floating point coprocessor present majority of chips and
9434emulated otherwise. Code compiled with this option will run almost everywhere.
9435The temporary results are computed in 80bit precision instead of precision
9436specified by the type resulting in slightly different results compared to most
9437of other chips. See @option{-ffloat-store} for more detailed description.
9438
9439This is the default choice for i386 compiler.
9440
9441@item sse
9442Use scalar floating point instructions present in the SSE instruction set.
9443This instruction set is supported by Pentium3 and newer chips, in the AMD line
9444by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE
9445instruction set supports only single precision arithmetics, thus the double and
9446extended precision arithmetics is still done using 387. Later version, present
9447only in Pentium4 and the future AMD x86-64 chips supports double precision
9448arithmetics too.
9449
9450For the i386 compiler, you need to use @option{-march=@var{cpu-type}}, @option{-msse}
9451or @option{-msse2} switches to enable SSE extensions and make this option
9452effective. For the x86-64 compiler, these extensions are enabled by default.
9453
9454The resulting code should be considerably faster in the majority of cases and avoid
9455the numerical instability problems of 387 code, but may break some existing
9456code that expects temporaries to be 80bit.
9457
9458This is the default choice for the x86-64 compiler.
9459
9460@item sse,387
9461Attempt to utilize both instruction sets at once. This effectively double the
9462amount of available registers and on chips with separate execution units for
9463387 and SSE the execution resources too. Use this option with care, as it is
9464still experimental, because the GCC register allocator does not model separate
9465functional units well resulting in instable performance.
9466@end table
9467
9468@item -masm=@var{dialect}
9469@opindex masm=@var{dialect}
9470Output asm instructions using selected @var{dialect}. Supported
9471choices are @samp{intel} or @samp{att} (the default one). Darwin does
9472not support @samp{intel}.
9473
9474@item -mieee-fp
9475@itemx -mno-ieee-fp
9476@opindex mieee-fp
9477@opindex mno-ieee-fp
9478Control whether or not the compiler uses IEEE floating point
9479comparisons. These handle correctly the case where the result of a
9480comparison is unordered.
9481
9482@item -msoft-float
9483@opindex msoft-float
9484Generate output containing library calls for floating point.
9485@strong{Warning:} the requisite libraries are not part of GCC@.
9486Normally the facilities of the machine's usual C compiler are used, but
9487this can't be done directly in cross-compilation. You must make your
9488own arrangements to provide suitable library functions for
9489cross-compilation.
9490
9491On machines where a function returns floating point results in the 80387
9492register stack, some floating point opcodes may be emitted even if
9493@option{-msoft-float} is used.
9494
9495@item -mno-fp-ret-in-387
9496@opindex mno-fp-ret-in-387
9497Do not use the FPU registers for return values of functions.
9498
9499The usual calling convention has functions return values of types
9500@code{float} and @code{double} in an FPU register, even if there
9501is no FPU@. The idea is that the operating system should emulate
9502an FPU@.
9503
9504The option @option{-mno-fp-ret-in-387} causes such values to be returned
9505in ordinary CPU registers instead.
9506
9507@item -mno-fancy-math-387
9508@opindex mno-fancy-math-387
9509Some 387 emulators do not support the @code{sin}, @code{cos} and
9510@code{sqrt} instructions for the 387. Specify this option to avoid
|
9510generating those instructions. This option is the default on FreeBSD,
| 9511generating those instructions. This option is the default on
|
9511OpenBSD and NetBSD@. This option is overridden when @option{-march}
9512indicates that the target cpu will always have an FPU and so the
9513instruction will not need emulation. As of revision 2.6.1, these
9514instructions are not generated unless you also use the
9515@option{-funsafe-math-optimizations} switch.
9516
9517@item -malign-double
9518@itemx -mno-align-double
9519@opindex malign-double
9520@opindex mno-align-double
9521Control whether GCC aligns @code{double}, @code{long double}, and
9522@code{long long} variables on a two word boundary or a one word
9523boundary. Aligning @code{double} variables on a two word boundary will
9524produce code that runs somewhat faster on a @samp{Pentium} at the
9525expense of more memory.
9526
9527On x86-64, @option{-malign-double} is enabled by default.
9528
9529@strong{Warning:} if you use the @option{-malign-double} switch,
9530structures containing the above types will be aligned differently than
9531the published application binary interface specifications for the 386
9532and will not be binary compatible with structures in code compiled
9533without that switch.
9534
9535@item -m96bit-long-double
9536@itemx -m128bit-long-double
9537@opindex m96bit-long-double
9538@opindex m128bit-long-double
9539These switches control the size of @code{long double} type. The i386
9540application binary interface specifies the size to be 96 bits,
9541so @option{-m96bit-long-double} is the default in 32 bit mode.
9542
9543Modern architectures (Pentium and newer) would prefer @code{long double}
9544to be aligned to an 8 or 16 byte boundary. In arrays or structures
9545conforming to the ABI, this would not be possible. So specifying a
9546@option{-m128bit-long-double} will align @code{long double}
9547to a 16 byte boundary by padding the @code{long double} with an additional
954832 bit zero.
9549
9550In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
9551its ABI specifies that @code{long double} is to be aligned on 16 byte boundary.
9552
9553Notice that neither of these options enable any extra precision over the x87
9554standard of 80 bits for a @code{long double}.
9555
9556@strong{Warning:} if you override the default value for your target ABI, the
9557structures and arrays containing @code{long double} variables will change
9558their size as well as function calling convention for function taking
9559@code{long double} will be modified. Hence they will not be binary
9560compatible with arrays or structures in code compiled without that switch.
9561
9562@item -mmlarge-data-threshold=@var{number}
9563@opindex mlarge-data-threshold=@var{number}
9564When @option{-mcmodel=medium} is specified, the data greater than
9565@var{threshold} are placed in large data section. This value must be the
9566same across all object linked into the binary and defaults to 65535.
9567
9568@item -msvr3-shlib
9569@itemx -mno-svr3-shlib
9570@opindex msvr3-shlib
9571@opindex mno-svr3-shlib
9572Control whether GCC places uninitialized local variables into the
9573@code{bss} or @code{data} segments. @option{-msvr3-shlib} places them
9574into @code{bss}. These options are meaningful only on System V Release 3.
9575
9576@item -mrtd
9577@opindex mrtd
9578Use a different function-calling convention, in which functions that
9579take a fixed number of arguments return with the @code{ret} @var{num}
9580instruction, which pops their arguments while returning. This saves one
9581instruction in the caller since there is no need to pop the arguments
9582there.
9583
9584You can specify that an individual function is called with this calling
9585sequence with the function attribute @samp{stdcall}. You can also
9586override the @option{-mrtd} option by using the function attribute
9587@samp{cdecl}. @xref{Function Attributes}.
9588
9589@strong{Warning:} this calling convention is incompatible with the one
9590normally used on Unix, so you cannot use it if you need to call
9591libraries compiled with the Unix compiler.
9592
9593Also, you must provide function prototypes for all functions that
9594take variable numbers of arguments (including @code{printf});
9595otherwise incorrect code will be generated for calls to those
9596functions.
9597
9598In addition, seriously incorrect code will result if you call a
9599function with too many arguments. (Normally, extra arguments are
9600harmlessly ignored.)
9601
9602@item -mregparm=@var{num}
9603@opindex mregparm
9604Control how many registers are used to pass integer arguments. By
9605default, no registers are used to pass arguments, and at most 3
9606registers can be used. You can control this behavior for a specific
9607function by using the function attribute @samp{regparm}.
9608@xref{Function Attributes}.
9609
9610@strong{Warning:} if you use this switch, and
9611@var{num} is nonzero, then you must build all modules with the same
9612value, including any libraries. This includes the system libraries and
9613startup modules.
9614
9615@item -msseregparm
9616@opindex msseregparm
9617Use SSE register passing conventions for float and double arguments
9618and return values. You can control this behavior for a specific
9619function by using the function attribute @samp{sseregparm}.
9620@xref{Function Attributes}.
9621
9622@strong{Warning:} if you use this switch then you must build all
9623modules with the same value, including any libraries. This includes
9624the system libraries and startup modules.
9625
9626@item -mstackrealign
9627@opindex mstackrealign
9628Realign the stack at entry. On the Intel x86, the
9629@option{-mstackrealign} option will generate an alternate prologue and
9630epilogue that realigns the runtime stack. This supports mixing legacy
9631codes that keep a 4-byte aligned stack with modern codes that keep a
963216-byte stack for SSE compatibility. The alternate prologue and
9633epilogue are slower and bigger than the regular ones, and the
9634alternate prologue requires an extra scratch register; this lowers the
9635number of registers available if used in conjunction with the
9636@code{regparm} attribute. The @option{-mstackrealign} option is
9637incompatible with the nested function prologue; this is considered a
9638hard error. See also the attribute @code{force_align_arg_pointer},
9639applicable to individual functions.
9640
9641@item -mpreferred-stack-boundary=@var{num}
9642@opindex mpreferred-stack-boundary
9643Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
9644byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
9645the default is 4 (16 bytes or 128 bits).
9646
9647On Pentium and PentiumPro, @code{double} and @code{long double} values
9648should be aligned to an 8 byte boundary (see @option{-malign-double}) or
9649suffer significant run time performance penalties. On Pentium III, the
9650Streaming SIMD Extension (SSE) data type @code{__m128} may not work
9651properly if it is not 16 byte aligned.
9652
9653To ensure proper alignment of this values on the stack, the stack boundary
9654must be as aligned as that required by any value stored on the stack.
9655Further, every function must be generated such that it keeps the stack
9656aligned. Thus calling a function compiled with a higher preferred
9657stack boundary from a function compiled with a lower preferred stack
9658boundary will most likely misalign the stack. It is recommended that
9659libraries that use callbacks always use the default setting.
9660
9661This extra alignment does consume extra stack space, and generally
9662increases code size. Code that is sensitive to stack space usage, such
9663as embedded systems and operating system kernels, may want to reduce the
9664preferred alignment to @option{-mpreferred-stack-boundary=2}.
9665
9666@item -mmmx
9667@itemx -mno-mmx
9668@item -msse
9669@itemx -mno-sse
9670@item -msse2
9671@itemx -mno-sse2
9672@item -msse3
9673@itemx -mno-sse3
9674@item -m3dnow
9675@itemx -mno-3dnow
9676@opindex mmmx
9677@opindex mno-mmx
9678@opindex msse
9679@opindex mno-sse
9680@opindex m3dnow
9681@opindex mno-3dnow
9682These switches enable or disable the use of instructions in the MMX,
9683SSE, SSE2 or 3DNow! extended instruction sets. These extensions are
9684also available as built-in functions: see @ref{X86 Built-in Functions},
9685for details of the functions enabled and disabled by these switches.
9686
9687To have SSE/SSE2 instructions generated automatically from floating-point
9688code (as opposed to 387 instructions), see @option{-mfpmath=sse}.
9689
9690These options will enable GCC to use these extended instructions in
9691generated code, even without @option{-mfpmath=sse}. Applications which
9692perform runtime CPU detection must compile separate files for each
9693supported architecture, using the appropriate flags. In particular,
9694the file containing the CPU detection code should be compiled without
9695these options.
9696
9697@item -mpush-args
9698@itemx -mno-push-args
9699@opindex mpush-args
9700@opindex mno-push-args
9701Use PUSH operations to store outgoing parameters. This method is shorter
9702and usually equally fast as method using SUB/MOV operations and is enabled
9703by default. In some cases disabling it may improve performance because of
9704improved scheduling and reduced dependencies.
9705
9706@item -maccumulate-outgoing-args
9707@opindex maccumulate-outgoing-args
9708If enabled, the maximum amount of space required for outgoing arguments will be
9709computed in the function prologue. This is faster on most modern CPUs
9710because of reduced dependencies, improved scheduling and reduced stack usage
9711when preferred stack boundary is not equal to 2. The drawback is a notable
9712increase in code size. This switch implies @option{-mno-push-args}.
9713
9714@item -mthreads
9715@opindex mthreads
9716Support thread-safe exception handling on @samp{Mingw32}. Code that relies
9717on thread-safe exception handling must compile and link all code with the
9718@option{-mthreads} option. When compiling, @option{-mthreads} defines
9719@option{-D_MT}; when linking, it links in a special thread helper library
9720@option{-lmingwthrd} which cleans up per thread exception handling data.
9721
9722@item -mno-align-stringops
9723@opindex mno-align-stringops
9724Do not align destination of inlined string operations. This switch reduces
9725code size and improves performance in case the destination is already aligned,
9726but GCC doesn't know about it.
9727
9728@item -minline-all-stringops
9729@opindex minline-all-stringops
9730By default GCC inlines string operations only when destination is known to be
9731aligned at least to 4 byte boundary. This enables more inlining, increase code
9732size, but may improve performance of code that depends on fast memcpy, strlen
9733and memset for short lengths.
9734
9735@item -momit-leaf-frame-pointer
9736@opindex momit-leaf-frame-pointer
9737Don't keep the frame pointer in a register for leaf functions. This
9738avoids the instructions to save, set up and restore frame pointers and
9739makes an extra register available in leaf functions. The option
9740@option{-fomit-frame-pointer} removes the frame pointer for all functions
9741which might make debugging harder.
9742
9743@item -mtls-direct-seg-refs
9744@itemx -mno-tls-direct-seg-refs
9745@opindex mtls-direct-seg-refs
9746Controls whether TLS variables may be accessed with offsets from the
9747TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
9748or whether the thread base pointer must be added. Whether or not this
9749is legal depends on the operating system, and whether it maps the
9750segment to cover the entire TLS area.
9751
9752For systems that use GNU libc, the default is on.
9753@end table
9754
9755These @samp{-m} switches are supported in addition to the above
9756on AMD x86-64 processors in 64-bit environments.
9757
9758@table @gcctabopt
9759@item -m32
9760@itemx -m64
9761@opindex m32
9762@opindex m64
9763Generate code for a 32-bit or 64-bit environment.
9764The 32-bit environment sets int, long and pointer to 32 bits and
9765generates code that runs on any i386 system.
9766The 64-bit environment sets int to 32 bits and long and pointer
9767to 64 bits and generates code for AMD's x86-64 architecture. For
9768darwin only the -m64 option turns off the @option{-fno-pic} and
9769@option{-mdynamic-no-pic} options.
9770
9771@item -mno-red-zone
9772@opindex no-red-zone
9773Do not use a so called red zone for x86-64 code. The red zone is mandated
9774by the x86-64 ABI, it is a 128-byte area beyond the location of the
9775stack pointer that will not be modified by signal or interrupt handlers
9776and therefore can be used for temporary data without adjusting the stack
9777pointer. The flag @option{-mno-red-zone} disables this red zone.
9778
9779@item -mcmodel=small
9780@opindex mcmodel=small
9781Generate code for the small code model: the program and its symbols must
9782be linked in the lower 2 GB of the address space. Pointers are 64 bits.
9783Programs can be statically or dynamically linked. This is the default
9784code model.
9785
9786@item -mcmodel=kernel
9787@opindex mcmodel=kernel
9788Generate code for the kernel code model. The kernel runs in the
9789negative 2 GB of the address space.
9790This model has to be used for Linux kernel code.
9791
9792@item -mcmodel=medium
9793@opindex mcmodel=medium
9794Generate code for the medium model: The program is linked in the lower 2
9795GB of the address space but symbols can be located anywhere in the
9796address space. Programs can be statically or dynamically linked, but
9797building of shared libraries are not supported with the medium model.
9798
9799@item -mcmodel=large
9800@opindex mcmodel=large
9801Generate code for the large model: This model makes no assumptions
9802about addresses and sizes of sections. Currently GCC does not implement
9803this model.
9804@end table
9805
9806@node IA-64 Options
9807@subsection IA-64 Options
9808@cindex IA-64 Options
9809
9810These are the @samp{-m} options defined for the Intel IA-64 architecture.
9811
9812@table @gcctabopt
9813@item -mbig-endian
9814@opindex mbig-endian
9815Generate code for a big endian target. This is the default for HP-UX@.
9816
9817@item -mlittle-endian
9818@opindex mlittle-endian
9819Generate code for a little endian target. This is the default for AIX5
9820and GNU/Linux.
9821
9822@item -mgnu-as
9823@itemx -mno-gnu-as
9824@opindex mgnu-as
9825@opindex mno-gnu-as
9826Generate (or don't) code for the GNU assembler. This is the default.
9827@c Also, this is the default if the configure option @option{--with-gnu-as}
9828@c is used.
9829
9830@item -mgnu-ld
9831@itemx -mno-gnu-ld
9832@opindex mgnu-ld
9833@opindex mno-gnu-ld
9834Generate (or don't) code for the GNU linker. This is the default.
9835@c Also, this is the default if the configure option @option{--with-gnu-ld}
9836@c is used.
9837
9838@item -mno-pic
9839@opindex mno-pic
9840Generate code that does not use a global pointer register. The result
9841is not position independent code, and violates the IA-64 ABI@.
9842
9843@item -mvolatile-asm-stop
9844@itemx -mno-volatile-asm-stop
9845@opindex mvolatile-asm-stop
9846@opindex mno-volatile-asm-stop
9847Generate (or don't) a stop bit immediately before and after volatile asm
9848statements.
9849
9850@item -mregister-names
9851@itemx -mno-register-names
9852@opindex mregister-names
9853@opindex mno-register-names
9854Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
9855the stacked registers. This may make assembler output more readable.
9856
9857@item -mno-sdata
9858@itemx -msdata
9859@opindex mno-sdata
9860@opindex msdata
9861Disable (or enable) optimizations that use the small data section. This may
9862be useful for working around optimizer bugs.
9863
9864@item -mconstant-gp
9865@opindex mconstant-gp
9866Generate code that uses a single constant global pointer value. This is
9867useful when compiling kernel code.
9868
9869@item -mauto-pic
9870@opindex mauto-pic
9871Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
9872This is useful when compiling firmware code.
9873
9874@item -minline-float-divide-min-latency
9875@opindex minline-float-divide-min-latency
9876Generate code for inline divides of floating point values
9877using the minimum latency algorithm.
9878
9879@item -minline-float-divide-max-throughput
9880@opindex minline-float-divide-max-throughput
9881Generate code for inline divides of floating point values
9882using the maximum throughput algorithm.
9883
9884@item -minline-int-divide-min-latency
9885@opindex minline-int-divide-min-latency
9886Generate code for inline divides of integer values
9887using the minimum latency algorithm.
9888
9889@item -minline-int-divide-max-throughput
9890@opindex minline-int-divide-max-throughput
9891Generate code for inline divides of integer values
9892using the maximum throughput algorithm.
9893
9894@item -minline-sqrt-min-latency
9895@opindex minline-sqrt-min-latency
9896Generate code for inline square roots
9897using the minimum latency algorithm.
9898
9899@item -minline-sqrt-max-throughput
9900@opindex minline-sqrt-max-throughput
9901Generate code for inline square roots
9902using the maximum throughput algorithm.
9903
9904@item -mno-dwarf2-asm
9905@itemx -mdwarf2-asm
9906@opindex mno-dwarf2-asm
9907@opindex mdwarf2-asm
9908Don't (or do) generate assembler code for the DWARF2 line number debugging
9909info. This may be useful when not using the GNU assembler.
9910
9911@item -mearly-stop-bits
9912@itemx -mno-early-stop-bits
9913@opindex mearly-stop-bits
9914@opindex mno-early-stop-bits
9915Allow stop bits to be placed earlier than immediately preceding the
9916instruction that triggered the stop bit. This can improve instruction
9917scheduling, but does not always do so.
9918
9919@item -mfixed-range=@var{register-range}
9920@opindex mfixed-range
9921Generate code treating the given register range as fixed registers.
9922A fixed register is one that the register allocator can not use. This is
9923useful when compiling kernel code. A register range is specified as
9924two registers separated by a dash. Multiple register ranges can be
9925specified separated by a comma.
9926
9927@item -mtls-size=@var{tls-size}
9928@opindex mtls-size
9929Specify bit size of immediate TLS offsets. Valid values are 14, 22, and
993064.
9931
9932@item -mtune=@var{cpu-type}
9933@opindex mtune
9934Tune the instruction scheduling for a particular CPU, Valid values are
9935itanium, itanium1, merced, itanium2, and mckinley.
9936
9937@item -mt
9938@itemx -pthread
9939@opindex mt
9940@opindex pthread
9941Add support for multithreading using the POSIX threads library. This
9942option sets flags for both the preprocessor and linker. It does
9943not affect the thread safety of object code produced by the compiler or
9944that of libraries supplied with it. These are HP-UX specific flags.
9945
9946@item -milp32
9947@itemx -mlp64
9948@opindex milp32
9949@opindex mlp64
9950Generate code for a 32-bit or 64-bit environment.
9951The 32-bit environment sets int, long and pointer to 32 bits.
9952The 64-bit environment sets int to 32 bits and long and pointer
9953to 64 bits. These are HP-UX specific flags.
9954
9955@item -mno-sched-br-data-spec
9956@itemx -msched-br-data-spec
9957@opindex mno-sched-br-data-spec
9958@opindex msched-br-data-spec
9959(Dis/En)able data speculative scheduling before reload.
9960This will result in generation of the ld.a instructions and
9961the corresponding check instructions (ld.c / chk.a).
9962The default is 'disable'.
9963
9964@item -msched-ar-data-spec
9965@itemx -mno-sched-ar-data-spec
9966@opindex msched-ar-data-spec
9967@opindex mno-sched-ar-data-spec
9968(En/Dis)able data speculative scheduling after reload.
9969This will result in generation of the ld.a instructions and
9970the corresponding check instructions (ld.c / chk.a).
9971The default is 'enable'.
9972
9973@item -mno-sched-control-spec
9974@itemx -msched-control-spec
9975@opindex mno-sched-control-spec
9976@opindex msched-control-spec
9977(Dis/En)able control speculative scheduling. This feature is
9978available only during region scheduling (i.e. before reload).
9979This will result in generation of the ld.s instructions and
9980the corresponding check instructions chk.s .
9981The default is 'disable'.
9982
9983@item -msched-br-in-data-spec
9984@itemx -mno-sched-br-in-data-spec
9985@opindex msched-br-in-data-spec
9986@opindex mno-sched-br-in-data-spec
9987(En/Dis)able speculative scheduling of the instructions that
9988are dependent on the data speculative loads before reload.
9989This is effective only with @option{-msched-br-data-spec} enabled.
9990The default is 'enable'.
9991
9992@item -msched-ar-in-data-spec
9993@itemx -mno-sched-ar-in-data-spec
9994@opindex msched-ar-in-data-spec
9995@opindex mno-sched-ar-in-data-spec
9996(En/Dis)able speculative scheduling of the instructions that
9997are dependent on the data speculative loads after reload.
9998This is effective only with @option{-msched-ar-data-spec} enabled.
9999The default is 'enable'.
10000
10001@item -msched-in-control-spec
10002@itemx -mno-sched-in-control-spec
10003@opindex msched-in-control-spec
10004@opindex mno-sched-in-control-spec
10005(En/Dis)able speculative scheduling of the instructions that
10006are dependent on the control speculative loads.
10007This is effective only with @option{-msched-control-spec} enabled.
10008The default is 'enable'.
10009
10010@item -msched-ldc
10011@itemx -mno-sched-ldc
10012@opindex msched-ldc
10013@opindex mno-sched-ldc
10014(En/Dis)able use of simple data speculation checks ld.c .
10015If disabled, only chk.a instructions will be emitted to check
10016data speculative loads.
10017The default is 'enable'.
10018
10019@item -mno-sched-control-ldc
10020@itemx -msched-control-ldc
10021@opindex mno-sched-control-ldc
10022@opindex msched-control-ldc
10023(Dis/En)able use of ld.c instructions to check control speculative loads.
10024If enabled, in case of control speculative load with no speculatively
10025scheduled dependent instructions this load will be emitted as ld.sa and
10026ld.c will be used to check it.
10027The default is 'disable'.
10028
10029@item -mno-sched-spec-verbose
10030@itemx -msched-spec-verbose
10031@opindex mno-sched-spec-verbose
10032@opindex msched-spec-verbose
10033(Dis/En)able printing of the information about speculative motions.
10034
10035@item -mno-sched-prefer-non-data-spec-insns
10036@itemx -msched-prefer-non-data-spec-insns
10037@opindex mno-sched-prefer-non-data-spec-insns
10038@opindex msched-prefer-non-data-spec-insns
10039If enabled, data speculative instructions will be chosen for schedule
10040only if there are no other choices at the moment. This will make
10041the use of the data speculation much more conservative.
10042The default is 'disable'.
10043
10044@item -mno-sched-prefer-non-control-spec-insns
10045@itemx -msched-prefer-non-control-spec-insns
10046@opindex mno-sched-prefer-non-control-spec-insns
10047@opindex msched-prefer-non-control-spec-insns
10048If enabled, control speculative instructions will be chosen for schedule
10049only if there are no other choices at the moment. This will make
10050the use of the control speculation much more conservative.
10051The default is 'disable'.
10052
10053@item -mno-sched-count-spec-in-critical-path
10054@itemx -msched-count-spec-in-critical-path
10055@opindex mno-sched-count-spec-in-critical-path
10056@opindex msched-count-spec-in-critical-path
10057If enabled, speculative dependencies will be considered during
10058computation of the instructions priorities. This will make the use of the
10059speculation a bit more conservative.
10060The default is 'disable'.
10061
10062@end table
10063
10064@node M32C Options
10065@subsection M32C Options
10066@cindex M32C options
10067
10068@table @gcctabopt
10069@item -mcpu=@var{name}
10070@opindex mcpu=
10071Select the CPU for which code is generated. @var{name} may be one of
10072@samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to
10073/60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for
10074the M32C/80 series.
10075
10076@item -msim
10077@opindex msim
10078Specifies that the program will be run on the simulator. This causes
10079an alternate runtime library to be linked in which supports, for
10080example, file I/O. You must not use this option when generating
10081programs that will run on real hardware; you must provide your own
10082runtime library for whatever I/O functions are needed.
10083
10084@item -memregs=@var{number}
10085@opindex memregs=
10086Specifies the number of memory-based pseudo-registers GCC will use
10087during code generation. These pseudo-registers will be used like real
10088registers, so there is a tradeoff between GCC's ability to fit the
10089code into available registers, and the performance penalty of using
10090memory instead of registers. Note that all modules in a program must
10091be compiled with the same value for this option. Because of that, you
10092must not use this option with the default runtime libraries gcc
10093builds.
10094
10095@end table
10096
10097@node M32R/D Options
10098@subsection M32R/D Options
10099@cindex M32R/D options
10100
10101These @option{-m} options are defined for Renesas M32R/D architectures:
10102
10103@table @gcctabopt
10104@item -m32r2
10105@opindex m32r2
10106Generate code for the M32R/2@.
10107
10108@item -m32rx
10109@opindex m32rx
10110Generate code for the M32R/X@.
10111
10112@item -m32r
10113@opindex m32r
10114Generate code for the M32R@. This is the default.
10115
10116@item -mmodel=small
10117@opindex mmodel=small
10118Assume all objects live in the lower 16MB of memory (so that their addresses
10119can be loaded with the @code{ld24} instruction), and assume all subroutines
10120are reachable with the @code{bl} instruction.
10121This is the default.
10122
10123The addressability of a particular object can be set with the
10124@code{model} attribute.
10125
10126@item -mmodel=medium
10127@opindex mmodel=medium
10128Assume objects may be anywhere in the 32-bit address space (the compiler
10129will generate @code{seth/add3} instructions to load their addresses), and
10130assume all subroutines are reachable with the @code{bl} instruction.
10131
10132@item -mmodel=large
10133@opindex mmodel=large
10134Assume objects may be anywhere in the 32-bit address space (the compiler
10135will generate @code{seth/add3} instructions to load their addresses), and
10136assume subroutines may not be reachable with the @code{bl} instruction
10137(the compiler will generate the much slower @code{seth/add3/jl}
10138instruction sequence).
10139
10140@item -msdata=none
10141@opindex msdata=none
10142Disable use of the small data area. Variables will be put into
10143one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
10144@code{section} attribute has been specified).
10145This is the default.
10146
10147The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
10148Objects may be explicitly put in the small data area with the
10149@code{section} attribute using one of these sections.
10150
10151@item -msdata=sdata
10152@opindex msdata=sdata
10153Put small global and static data in the small data area, but do not
10154generate special code to reference them.
10155
10156@item -msdata=use
10157@opindex msdata=use
10158Put small global and static data in the small data area, and generate
10159special instructions to reference them.
10160
10161@item -G @var{num}
10162@opindex G
10163@cindex smaller data references
10164Put global and static objects less than or equal to @var{num} bytes
10165into the small data or bss sections instead of the normal data or bss
10166sections. The default value of @var{num} is 8.
10167The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
10168for this option to have any effect.
10169
10170All modules should be compiled with the same @option{-G @var{num}} value.
10171Compiling with different values of @var{num} may or may not work; if it
10172doesn't the linker will give an error message---incorrect code will not be
10173generated.
10174
10175@item -mdebug
10176@opindex mdebug
10177Makes the M32R specific code in the compiler display some statistics
10178that might help in debugging programs.
10179
10180@item -malign-loops
10181@opindex malign-loops
10182Align all loops to a 32-byte boundary.
10183
10184@item -mno-align-loops
10185@opindex mno-align-loops
10186Do not enforce a 32-byte alignment for loops. This is the default.
10187
10188@item -missue-rate=@var{number}
10189@opindex missue-rate=@var{number}
10190Issue @var{number} instructions per cycle. @var{number} can only be 1
10191or 2.
10192
10193@item -mbranch-cost=@var{number}
10194@opindex mbranch-cost=@var{number}
10195@var{number} can only be 1 or 2. If it is 1 then branches will be
10196preferred over conditional code, if it is 2, then the opposite will
10197apply.
10198
10199@item -mflush-trap=@var{number}
10200@opindex mflush-trap=@var{number}
10201Specifies the trap number to use to flush the cache. The default is
1020212. Valid numbers are between 0 and 15 inclusive.
10203
10204@item -mno-flush-trap
10205@opindex mno-flush-trap
10206Specifies that the cache cannot be flushed by using a trap.
10207
10208@item -mflush-func=@var{name}
10209@opindex mflush-func=@var{name}
10210Specifies the name of the operating system function to call to flush
10211the cache. The default is @emph{_flush_cache}, but a function call
10212will only be used if a trap is not available.
10213
10214@item -mno-flush-func
10215@opindex mno-flush-func
10216Indicates that there is no OS function for flushing the cache.
10217
10218@end table
10219
10220@node M680x0 Options
10221@subsection M680x0 Options
10222@cindex M680x0 options
10223
10224These are the @samp{-m} options defined for the 68000 series. The default
10225values for these options depends on which style of 68000 was selected when
10226the compiler was configured; the defaults for the most common choices are
10227given below.
10228
10229@table @gcctabopt
10230@item -m68000
10231@itemx -mc68000
10232@opindex m68000
10233@opindex mc68000
10234Generate output for a 68000. This is the default
10235when the compiler is configured for 68000-based systems.
10236
10237Use this option for microcontrollers with a 68000 or EC000 core,
10238including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
10239
10240@item -m68020
10241@itemx -mc68020
10242@opindex m68020
10243@opindex mc68020
10244Generate output for a 68020. This is the default
10245when the compiler is configured for 68020-based systems.
10246
10247@item -m68881
10248@opindex m68881
10249Generate output containing 68881 instructions for floating point.
10250This is the default for most 68020 systems unless @option{--nfp} was
10251specified when the compiler was configured.
10252
10253@item -m68030
10254@opindex m68030
10255Generate output for a 68030. This is the default when the compiler is
10256configured for 68030-based systems.
10257
10258@item -m68040
10259@opindex m68040
10260Generate output for a 68040. This is the default when the compiler is
10261configured for 68040-based systems.
10262
10263This option inhibits the use of 68881/68882 instructions that have to be
10264emulated by software on the 68040. Use this option if your 68040 does not
10265have code to emulate those instructions.
10266
10267@item -m68060
10268@opindex m68060
10269Generate output for a 68060. This is the default when the compiler is
10270configured for 68060-based systems.
10271
10272This option inhibits the use of 68020 and 68881/68882 instructions that
10273have to be emulated by software on the 68060. Use this option if your 68060
10274does not have code to emulate those instructions.
10275
10276@item -mcpu32
10277@opindex mcpu32
10278Generate output for a CPU32. This is the default
10279when the compiler is configured for CPU32-based systems.
10280
10281Use this option for microcontrollers with a
10282CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
1028368336, 68340, 68341, 68349 and 68360.
10284
10285@item -m5200
10286@opindex m5200
10287Generate output for a 520X ``coldfire'' family cpu. This is the default
10288when the compiler is configured for 520X-based systems.
10289
10290Use this option for microcontroller with a 5200 core, including
10291the MCF5202, MCF5203, MCF5204 and MCF5202.
10292
10293@item -mcfv4e
10294@opindex mcfv4e
10295Generate output for a ColdFire V4e family cpu (e.g.@: 547x/548x).
10296This includes use of hardware floating point instructions.
10297
10298@item -m68020-40
10299@opindex m68020-40
10300Generate output for a 68040, without using any of the new instructions.
10301This results in code which can run relatively efficiently on either a
1030268020/68881 or a 68030 or a 68040. The generated code does use the
1030368881 instructions that are emulated on the 68040.
10304
10305@item -m68020-60
10306@opindex m68020-60
10307Generate output for a 68060, without using any of the new instructions.
10308This results in code which can run relatively efficiently on either a
1030968020/68881 or a 68030 or a 68040. The generated code does use the
1031068881 instructions that are emulated on the 68060.
10311
10312@item -msoft-float
10313@opindex msoft-float
10314Generate output containing library calls for floating point.
10315@strong{Warning:} the requisite libraries are not available for all m68k
10316targets. Normally the facilities of the machine's usual C compiler are
10317used, but this can't be done directly in cross-compilation. You must
10318make your own arrangements to provide suitable library functions for
10319cross-compilation. The embedded targets @samp{m68k-*-aout} and
10320@samp{m68k-*-coff} do provide software floating point support.
10321
10322@item -mshort
10323@opindex mshort
10324Consider type @code{int} to be 16 bits wide, like @code{short int}.
10325Additionally, parameters passed on the stack are also aligned to a
1032616-bit boundary even on targets whose API mandates promotion to 32-bit.
10327
10328@item -mnobitfield
10329@opindex mnobitfield
10330Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
10331and @option{-m5200} options imply @w{@option{-mnobitfield}}.
10332
10333@item -mbitfield
10334@opindex mbitfield
10335Do use the bit-field instructions. The @option{-m68020} option implies
10336@option{-mbitfield}. This is the default if you use a configuration
10337designed for a 68020.
10338
10339@item -mrtd
10340@opindex mrtd
10341Use a different function-calling convention, in which functions
10342that take a fixed number of arguments return with the @code{rtd}
10343instruction, which pops their arguments while returning. This
10344saves one instruction in the caller since there is no need to pop
10345the arguments there.
10346
10347This calling convention is incompatible with the one normally
10348used on Unix, so you cannot use it if you need to call libraries
10349compiled with the Unix compiler.
10350
10351Also, you must provide function prototypes for all functions that
10352take variable numbers of arguments (including @code{printf});
10353otherwise incorrect code will be generated for calls to those
10354functions.
10355
10356In addition, seriously incorrect code will result if you call a
10357function with too many arguments. (Normally, extra arguments are
10358harmlessly ignored.)
10359
10360The @code{rtd} instruction is supported by the 68010, 68020, 68030,
1036168040, 68060 and CPU32 processors, but not by the 68000 or 5200.
10362
10363@item -malign-int
10364@itemx -mno-align-int
10365@opindex malign-int
10366@opindex mno-align-int
10367Control whether GCC aligns @code{int}, @code{long}, @code{long long},
10368@code{float}, @code{double}, and @code{long double} variables on a 32-bit
10369boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
10370Aligning variables on 32-bit boundaries produces code that runs somewhat
10371faster on processors with 32-bit busses at the expense of more memory.
10372
10373@strong{Warning:} if you use the @option{-malign-int} switch, GCC will
10374align structures containing the above types differently than
10375most published application binary interface specifications for the m68k.
10376
10377@item -mpcrel
10378@opindex mpcrel
10379Use the pc-relative addressing mode of the 68000 directly, instead of
10380using a global offset table. At present, this option implies @option{-fpic},
10381allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
10382not presently supported with @option{-mpcrel}, though this could be supported for
1038368020 and higher processors.
10384
10385@item -mno-strict-align
10386@itemx -mstrict-align
10387@opindex mno-strict-align
10388@opindex mstrict-align
10389Do not (do) assume that unaligned memory references will be handled by
10390the system.
10391
10392@item -msep-data
10393Generate code that allows the data segment to be located in a different
10394area of memory from the text segment. This allows for execute in place in
10395an environment without virtual memory management. This option implies
10396@option{-fPIC}.
10397
10398@item -mno-sep-data
10399Generate code that assumes that the data segment follows the text segment.
10400This is the default.
10401
10402@item -mid-shared-library
10403Generate code that supports shared libraries via the library ID method.
10404This allows for execute in place and shared libraries in an environment
10405without virtual memory management. This option implies @option{-fPIC}.
10406
10407@item -mno-id-shared-library
10408Generate code that doesn't assume ID based shared libraries are being used.
10409This is the default.
10410
10411@item -mshared-library-id=n
10412Specified the identification number of the ID based shared library being
10413compiled. Specifying a value of 0 will generate more compact code, specifying
10414other values will force the allocation of that number to the current
10415library but is no more space or time efficient than omitting this option.
10416
10417@end table
10418
10419@node M68hc1x Options
10420@subsection M68hc1x Options
10421@cindex M68hc1x options
10422
10423These are the @samp{-m} options defined for the 68hc11 and 68hc12
10424microcontrollers. The default values for these options depends on
10425which style of microcontroller was selected when the compiler was configured;
10426the defaults for the most common choices are given below.
10427
10428@table @gcctabopt
10429@item -m6811
10430@itemx -m68hc11
10431@opindex m6811
10432@opindex m68hc11
10433Generate output for a 68HC11. This is the default
10434when the compiler is configured for 68HC11-based systems.
10435
10436@item -m6812
10437@itemx -m68hc12
10438@opindex m6812
10439@opindex m68hc12
10440Generate output for a 68HC12. This is the default
10441when the compiler is configured for 68HC12-based systems.
10442
10443@item -m68S12
10444@itemx -m68hcs12
10445@opindex m68S12
10446@opindex m68hcs12
10447Generate output for a 68HCS12.
10448
10449@item -mauto-incdec
10450@opindex mauto-incdec
10451Enable the use of 68HC12 pre and post auto-increment and auto-decrement
10452addressing modes.
10453
10454@item -minmax
10455@itemx -nominmax
10456@opindex minmax
10457@opindex mnominmax
10458Enable the use of 68HC12 min and max instructions.
10459
10460@item -mlong-calls
10461@itemx -mno-long-calls
10462@opindex mlong-calls
10463@opindex mno-long-calls
10464Treat all calls as being far away (near). If calls are assumed to be
10465far away, the compiler will use the @code{call} instruction to
10466call a function and the @code{rtc} instruction for returning.
10467
10468@item -mshort
10469@opindex mshort
10470Consider type @code{int} to be 16 bits wide, like @code{short int}.
10471
10472@item -msoft-reg-count=@var{count}
10473@opindex msoft-reg-count
10474Specify the number of pseudo-soft registers which are used for the
10475code generation. The maximum number is 32. Using more pseudo-soft
10476register may or may not result in better code depending on the program.
10477The default is 4 for 68HC11 and 2 for 68HC12.
10478
10479@end table
10480
10481@node MCore Options
10482@subsection MCore Options
10483@cindex MCore options
10484
10485These are the @samp{-m} options defined for the Motorola M*Core
10486processors.
10487
10488@table @gcctabopt
10489
10490@item -mhardlit
10491@itemx -mno-hardlit
10492@opindex mhardlit
10493@opindex mno-hardlit
10494Inline constants into the code stream if it can be done in two
10495instructions or less.
10496
10497@item -mdiv
10498@itemx -mno-div
10499@opindex mdiv
10500@opindex mno-div
10501Use the divide instruction. (Enabled by default).
10502
10503@item -mrelax-immediate
10504@itemx -mno-relax-immediate
10505@opindex mrelax-immediate
10506@opindex mno-relax-immediate
10507Allow arbitrary sized immediates in bit operations.
10508
10509@item -mwide-bitfields
10510@itemx -mno-wide-bitfields
10511@opindex mwide-bitfields
10512@opindex mno-wide-bitfields
10513Always treat bit-fields as int-sized.
10514
10515@item -m4byte-functions
10516@itemx -mno-4byte-functions
10517@opindex m4byte-functions
10518@opindex mno-4byte-functions
10519Force all functions to be aligned to a four byte boundary.
10520
10521@item -mcallgraph-data
10522@itemx -mno-callgraph-data
10523@opindex mcallgraph-data
10524@opindex mno-callgraph-data
10525Emit callgraph information.
10526
10527@item -mslow-bytes
10528@itemx -mno-slow-bytes
10529@opindex mslow-bytes
10530@opindex mno-slow-bytes
10531Prefer word access when reading byte quantities.
10532
10533@item -mlittle-endian
10534@itemx -mbig-endian
10535@opindex mlittle-endian
10536@opindex mbig-endian
10537Generate code for a little endian target.
10538
10539@item -m210
10540@itemx -m340
10541@opindex m210
10542@opindex m340
10543Generate code for the 210 processor.
10544@end table
10545
10546@node MIPS Options
10547@subsection MIPS Options
10548@cindex MIPS options
10549
10550@table @gcctabopt
10551
10552@item -EB
10553@opindex EB
10554Generate big-endian code.
10555
10556@item -EL
10557@opindex EL
10558Generate little-endian code. This is the default for @samp{mips*el-*-*}
10559configurations.
10560
10561@item -march=@var{arch}
10562@opindex march
10563Generate code that will run on @var{arch}, which can be the name of a
10564generic MIPS ISA, or the name of a particular processor.
10565The ISA names are:
10566@samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
10567@samp{mips32}, @samp{mips32r2}, and @samp{mips64}.
10568The processor names are:
10569@samp{4kc}, @samp{4km}, @samp{4kp},
10570@samp{5kc}, @samp{5kf},
10571@samp{20kc},
10572@samp{24k}, @samp{24kc}, @samp{24kf}, @samp{24kx},
10573@samp{m4k},
10574@samp{orion},
10575@samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
10576@samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000},
10577@samp{rm7000}, @samp{rm9000},
10578@samp{sb1},
10579@samp{sr71000},
10580@samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
10581@samp{vr5000}, @samp{vr5400} and @samp{vr5500}.
10582The special value @samp{from-abi} selects the
10583most compatible architecture for the selected ABI (that is,
10584@samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
10585
10586In processor names, a final @samp{000} can be abbreviated as @samp{k}
10587(for example, @samp{-march=r2k}). Prefixes are optional, and
10588@samp{vr} may be written @samp{r}.
10589
10590GCC defines two macros based on the value of this option. The first
10591is @samp{_MIPS_ARCH}, which gives the name of target architecture, as
10592a string. The second has the form @samp{_MIPS_ARCH_@var{foo}},
10593where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@.
10594For example, @samp{-march=r2000} will set @samp{_MIPS_ARCH}
10595to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}.
10596
10597Note that the @samp{_MIPS_ARCH} macro uses the processor names given
10598above. In other words, it will have the full prefix and will not
10599abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},
10600the macro names the resolved architecture (either @samp{"mips1"} or
10601@samp{"mips3"}). It names the default architecture when no
10602@option{-march} option is given.
10603
10604@item -mtune=@var{arch}
10605@opindex mtune
10606Optimize for @var{arch}. Among other things, this option controls
10607the way instructions are scheduled, and the perceived cost of arithmetic
10608operations. The list of @var{arch} values is the same as for
10609@option{-march}.
10610
10611When this option is not used, GCC will optimize for the processor
10612specified by @option{-march}. By using @option{-march} and
10613@option{-mtune} together, it is possible to generate code that will
10614run on a family of processors, but optimize the code for one
10615particular member of that family.
10616
10617@samp{-mtune} defines the macros @samp{_MIPS_TUNE} and
10618@samp{_MIPS_TUNE_@var{foo}}, which work in the same way as the
10619@samp{-march} ones described above.
10620
10621@item -mips1
10622@opindex mips1
10623Equivalent to @samp{-march=mips1}.
10624
10625@item -mips2
10626@opindex mips2
10627Equivalent to @samp{-march=mips2}.
10628
10629@item -mips3
10630@opindex mips3
10631Equivalent to @samp{-march=mips3}.
10632
10633@item -mips4
10634@opindex mips4
10635Equivalent to @samp{-march=mips4}.
10636
10637@item -mips32
10638@opindex mips32
10639Equivalent to @samp{-march=mips32}.
10640
10641@item -mips32r2
10642@opindex mips32r2
10643Equivalent to @samp{-march=mips32r2}.
10644
10645@item -mips64
10646@opindex mips64
10647Equivalent to @samp{-march=mips64}.
10648
10649@item -mips16
10650@itemx -mno-mips16
10651@opindex mips16
10652@opindex mno-mips16
10653Generate (do not generate) MIPS16 code. If GCC is targetting a
10654MIPS32 or MIPS64 architecture, it will make use of the MIPS16e ASE@.
10655
10656@item -mabi=32
10657@itemx -mabi=o64
10658@itemx -mabi=n32
10659@itemx -mabi=64
10660@itemx -mabi=eabi
10661@opindex mabi=32
10662@opindex mabi=o64
10663@opindex mabi=n32
10664@opindex mabi=64
10665@opindex mabi=eabi
10666Generate code for the given ABI@.
10667
10668Note that the EABI has a 32-bit and a 64-bit variant. GCC normally
10669generates 64-bit code when you select a 64-bit architecture, but you
10670can use @option{-mgp32} to get 32-bit code instead.
10671
10672For information about the O64 ABI, see
10673@w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
10674
10675@item -mabicalls
10676@itemx -mno-abicalls
10677@opindex mabicalls
10678@opindex mno-abicalls
10679Generate (do not generate) code that is suitable for SVR4-style
10680dynamic objects. @option{-mabicalls} is the default for SVR4-based
10681systems.
10682
10683@item -mshared
10684@itemx -mno-shared
10685Generate (do not generate) code that is fully position-independent,
10686and that can therefore be linked into shared libraries. This option
10687only affects @option{-mabicalls}.
10688
10689All @option{-mabicalls} code has traditionally been position-independent,
10690regardless of options like @option{-fPIC} and @option{-fpic}. However,
10691as an extension, the GNU toolchain allows executables to use absolute
10692accesses for locally-binding symbols. It can also use shorter GP
10693initialization sequences and generate direct calls to locally-defined
10694functions. This mode is selected by @option{-mno-shared}.
10695
10696@option{-mno-shared} depends on binutils 2.16 or higher and generates
10697objects that can only be linked by the GNU linker. However, the option
10698does not affect the ABI of the final executable; it only affects the ABI
10699of relocatable objects. Using @option{-mno-shared} will generally make
10700executables both smaller and quicker.
10701
10702@option{-mshared} is the default.
10703
10704@item -mxgot
10705@itemx -mno-xgot
10706@opindex mxgot
10707@opindex mno-xgot
10708Lift (do not lift) the usual restrictions on the size of the global
10709offset table.
10710
10711GCC normally uses a single instruction to load values from the GOT@.
10712While this is relatively efficient, it will only work if the GOT
10713is smaller than about 64k. Anything larger will cause the linker
10714to report an error such as:
10715
10716@cindex relocation truncated to fit (MIPS)
10717@smallexample
10718relocation truncated to fit: R_MIPS_GOT16 foobar
10719@end smallexample
10720
10721If this happens, you should recompile your code with @option{-mxgot}.
10722It should then work with very large GOTs, although it will also be
10723less efficient, since it will take three instructions to fetch the
10724value of a global symbol.
10725
10726Note that some linkers can create multiple GOTs. If you have such a
10727linker, you should only need to use @option{-mxgot} when a single object
10728file accesses more than 64k's worth of GOT entries. Very few do.
10729
10730These options have no effect unless GCC is generating position
10731independent code.
10732
10733@item -mgp32
10734@opindex mgp32
10735Assume that general-purpose registers are 32 bits wide.
10736
10737@item -mgp64
10738@opindex mgp64
10739Assume that general-purpose registers are 64 bits wide.
10740
10741@item -mfp32
10742@opindex mfp32
10743Assume that floating-point registers are 32 bits wide.
10744
10745@item -mfp64
10746@opindex mfp64
10747Assume that floating-point registers are 64 bits wide.
10748
10749@item -mhard-float
10750@opindex mhard-float
10751Use floating-point coprocessor instructions.
10752
10753@item -msoft-float
10754@opindex msoft-float
10755Do not use floating-point coprocessor instructions. Implement
10756floating-point calculations using library calls instead.
10757
10758@item -msingle-float
10759@opindex msingle-float
10760Assume that the floating-point coprocessor only supports single-precision
10761operations.
10762
10763@itemx -mdouble-float
10764@opindex mdouble-float
10765Assume that the floating-point coprocessor supports double-precision
10766operations. This is the default.
10767
10768@itemx -mdsp
10769@itemx -mno-dsp
10770@opindex mdsp
10771@opindex mno-dsp
10772Use (do not use) the MIPS DSP ASE. @xref{MIPS DSP Built-in Functions}.
10773
10774@itemx -mpaired-single
10775@itemx -mno-paired-single
10776@opindex mpaired-single
10777@opindex mno-paired-single
10778Use (do not use) paired-single floating-point instructions.
10779@xref{MIPS Paired-Single Support}. This option can only be used
10780when generating 64-bit code and requires hardware floating-point
10781support to be enabled.
10782
10783@itemx -mips3d
10784@itemx -mno-mips3d
10785@opindex mips3d
10786@opindex mno-mips3d
10787Use (do not use) the MIPS-3D ASE@. @xref{MIPS-3D Built-in Functions}.
10788The option @option{-mips3d} implies @option{-mpaired-single}.
10789
10790@item -mlong64
10791@opindex mlong64
10792Force @code{long} types to be 64 bits wide. See @option{-mlong32} for
10793an explanation of the default and the way that the pointer size is
10794determined.
10795
10796@item -mlong32
10797@opindex mlong32
10798Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
10799
10800The default size of @code{int}s, @code{long}s and pointers depends on
10801the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI
10802uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
1080332-bit @code{long}s. Pointers are the same size as @code{long}s,
10804or the same size as integer registers, whichever is smaller.
10805
10806@item -msym32
10807@itemx -mno-sym32
10808@opindex msym32
10809@opindex mno-sym32
10810Assume (do not assume) that all symbols have 32-bit values, regardless
10811of the selected ABI@. This option is useful in combination with
10812@option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
10813to generate shorter and faster references to symbolic addresses.
10814
10815@item -G @var{num}
10816@opindex G
10817@cindex smaller data references (MIPS)
10818@cindex gp-relative references (MIPS)
10819Put global and static items less than or equal to @var{num} bytes into
10820the small data or bss section instead of the normal data or bss section.
10821This allows the data to be accessed using a single instruction.
10822
10823All modules should be compiled with the same @option{-G @var{num}}
10824value.
10825
10826@item -membedded-data
10827@itemx -mno-embedded-data
10828@opindex membedded-data
10829@opindex mno-embedded-data
10830Allocate variables to the read-only data section first if possible, then
10831next in the small data section if possible, otherwise in data. This gives
10832slightly slower code than the default, but reduces the amount of RAM required
10833when executing, and thus may be preferred for some embedded systems.
10834
10835@item -muninit-const-in-rodata
10836@itemx -mno-uninit-const-in-rodata
10837@opindex muninit-const-in-rodata
10838@opindex mno-uninit-const-in-rodata
10839Put uninitialized @code{const} variables in the read-only data section.
10840This option is only meaningful in conjunction with @option{-membedded-data}.
10841
10842@item -msplit-addresses
10843@itemx -mno-split-addresses
10844@opindex msplit-addresses
10845@opindex mno-split-addresses
10846Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
10847relocation operators. This option has been superseded by
10848@option{-mexplicit-relocs} but is retained for backwards compatibility.
10849
10850@item -mexplicit-relocs
10851@itemx -mno-explicit-relocs
10852@opindex mexplicit-relocs
10853@opindex mno-explicit-relocs
10854Use (do not use) assembler relocation operators when dealing with symbolic
10855addresses. The alternative, selected by @option{-mno-explicit-relocs},
10856is to use assembler macros instead.
10857
10858@option{-mexplicit-relocs} is the default if GCC was configured
10859to use an assembler that supports relocation operators.
10860
10861@item -mcheck-zero-division
10862@itemx -mno-check-zero-division
10863@opindex mcheck-zero-division
10864@opindex mno-check-zero-division
10865Trap (do not trap) on integer division by zero. The default is
10866@option{-mcheck-zero-division}.
10867
10868@item -mdivide-traps
10869@itemx -mdivide-breaks
10870@opindex mdivide-traps
10871@opindex mdivide-breaks
10872MIPS systems check for division by zero by generating either a
10873conditional trap or a break instruction. Using traps results in
10874smaller code, but is only supported on MIPS II and later. Also, some
10875versions of the Linux kernel have a bug that prevents trap from
10876generating the proper signal (@code{SIGFPE}). Use @option{-mdivide-traps} to
10877allow conditional traps on architectures that support them and
10878@option{-mdivide-breaks} to force the use of breaks.
10879
10880The default is usually @option{-mdivide-traps}, but this can be
10881overridden at configure time using @option{--with-divide=breaks}.
10882Divide-by-zero checks can be completely disabled using
10883@option{-mno-check-zero-division}.
10884
10885@item -mmemcpy
10886@itemx -mno-memcpy
10887@opindex mmemcpy
10888@opindex mno-memcpy
10889Force (do not force) the use of @code{memcpy()} for non-trivial block
10890moves. The default is @option{-mno-memcpy}, which allows GCC to inline
10891most constant-sized copies.
10892
10893@item -mlong-calls
10894@itemx -mno-long-calls
10895@opindex mlong-calls
10896@opindex mno-long-calls
10897Disable (do not disable) use of the @code{jal} instruction. Calling
10898functions using @code{jal} is more efficient but requires the caller
10899and callee to be in the same 256 megabyte segment.
10900
10901This option has no effect on abicalls code. The default is
10902@option{-mno-long-calls}.
10903
10904@item -mmad
10905@itemx -mno-mad
10906@opindex mmad
10907@opindex mno-mad
10908Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
10909instructions, as provided by the R4650 ISA@.
10910
10911@item -mfused-madd
10912@itemx -mno-fused-madd
10913@opindex mfused-madd
10914@opindex mno-fused-madd
10915Enable (disable) use of the floating point multiply-accumulate
10916instructions, when they are available. The default is
10917@option{-mfused-madd}.
10918
10919When multiply-accumulate instructions are used, the intermediate
10920product is calculated to infinite precision and is not subject to
10921the FCSR Flush to Zero bit. This may be undesirable in some
10922circumstances.
10923
10924@item -nocpp
10925@opindex nocpp
10926Tell the MIPS assembler to not run its preprocessor over user
10927assembler files (with a @samp{.s} suffix) when assembling them.
10928
10929@item -mfix-r4000
10930@itemx -mno-fix-r4000
10931@opindex mfix-r4000
10932@opindex mno-fix-r4000
10933Work around certain R4000 CPU errata:
10934@itemize @minus
10935@item
10936A double-word or a variable shift may give an incorrect result if executed
10937immediately after starting an integer division.
10938@item
10939A double-word or a variable shift may give an incorrect result if executed
10940while an integer multiplication is in progress.
10941@item
10942An integer division may give an incorrect result if started in a delay slot
10943of a taken branch or a jump.
10944@end itemize
10945
10946@item -mfix-r4400
10947@itemx -mno-fix-r4400
10948@opindex mfix-r4400
10949@opindex mno-fix-r4400
10950Work around certain R4400 CPU errata:
10951@itemize @minus
10952@item
10953A double-word or a variable shift may give an incorrect result if executed
10954immediately after starting an integer division.
10955@end itemize
10956
10957@item -mfix-vr4120
10958@itemx -mno-fix-vr4120
10959@opindex mfix-vr4120
10960Work around certain VR4120 errata:
10961@itemize @minus
10962@item
10963@code{dmultu} does not always produce the correct result.
10964@item
10965@code{div} and @code{ddiv} do not always produce the correct result if one
10966of the operands is negative.
10967@end itemize
10968The workarounds for the division errata rely on special functions in
10969@file{libgcc.a}. At present, these functions are only provided by
10970the @code{mips64vr*-elf} configurations.
10971
10972Other VR4120 errata require a nop to be inserted between certain pairs of
10973instructions. These errata are handled by the assembler, not by GCC itself.
10974
10975@item -mfix-vr4130
10976@opindex mfix-vr4130
10977Work around the VR4130 @code{mflo}/@code{mfhi} errata. The
10978workarounds are implemented by the assembler rather than by GCC,
10979although GCC will avoid using @code{mflo} and @code{mfhi} if the
10980VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
10981instructions are available instead.
10982
10983@item -mfix-sb1
10984@itemx -mno-fix-sb1
10985@opindex mfix-sb1
10986Work around certain SB-1 CPU core errata.
10987(This flag currently works around the SB-1 revision 2
10988``F1'' and ``F2'' floating point errata.)
10989
10990@item -mflush-func=@var{func}
10991@itemx -mno-flush-func
10992@opindex mflush-func
10993Specifies the function to call to flush the I and D caches, or to not
10994call any such function. If called, the function must take the same
10995arguments as the common @code{_flush_func()}, that is, the address of the
10996memory range for which the cache is being flushed, the size of the
10997memory range, and the number 3 (to flush both caches). The default
10998depends on the target GCC was configured for, but commonly is either
10999@samp{_flush_func} or @samp{__cpu_flush}.
11000
11001@item -mbranch-likely
11002@itemx -mno-branch-likely
11003@opindex mbranch-likely
11004@opindex mno-branch-likely
11005Enable or disable use of Branch Likely instructions, regardless of the
11006default for the selected architecture. By default, Branch Likely
11007instructions may be generated if they are supported by the selected
11008architecture. An exception is for the MIPS32 and MIPS64 architectures
11009and processors which implement those architectures; for those, Branch
11010Likely instructions will not be generated by default because the MIPS32
11011and MIPS64 architectures specifically deprecate their use.
11012
11013@item -mfp-exceptions
11014@itemx -mno-fp-exceptions
11015@opindex mfp-exceptions
11016Specifies whether FP exceptions are enabled. This affects how we schedule
11017FP instructions for some processors. The default is that FP exceptions are
11018enabled.
11019
11020For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
1102164-bit code, then we can use both FP pipes. Otherwise, we can only use one
11022FP pipe.
11023
11024@item -mvr4130-align
11025@itemx -mno-vr4130-align
11026@opindex mvr4130-align
11027The VR4130 pipeline is two-way superscalar, but can only issue two
11028instructions together if the first one is 8-byte aligned. When this
11029option is enabled, GCC will align pairs of instructions that it
11030thinks should execute in parallel.
11031
11032This option only has an effect when optimizing for the VR4130.
11033It normally makes code faster, but at the expense of making it bigger.
11034It is enabled by default at optimization level @option{-O3}.
11035@end table
11036
11037@node MMIX Options
11038@subsection MMIX Options
11039@cindex MMIX Options
11040
11041These options are defined for the MMIX:
11042
11043@table @gcctabopt
11044@item -mlibfuncs
11045@itemx -mno-libfuncs
11046@opindex mlibfuncs
11047@opindex mno-libfuncs
11048Specify that intrinsic library functions are being compiled, passing all
11049values in registers, no matter the size.
11050
11051@item -mepsilon
11052@itemx -mno-epsilon
11053@opindex mepsilon
11054@opindex mno-epsilon
11055Generate floating-point comparison instructions that compare with respect
11056to the @code{rE} epsilon register.
11057
11058@item -mabi=mmixware
11059@itemx -mabi=gnu
11060@opindex mabi-mmixware
11061@opindex mabi=gnu
11062Generate code that passes function parameters and return values that (in
11063the called function) are seen as registers @code{$0} and up, as opposed to
11064the GNU ABI which uses global registers @code{$231} and up.
11065
11066@item -mzero-extend
11067@itemx -mno-zero-extend
11068@opindex mzero-extend
11069@opindex mno-zero-extend
11070When reading data from memory in sizes shorter than 64 bits, use (do not
11071use) zero-extending load instructions by default, rather than
11072sign-extending ones.
11073
11074@item -mknuthdiv
11075@itemx -mno-knuthdiv
11076@opindex mknuthdiv
11077@opindex mno-knuthdiv
11078Make the result of a division yielding a remainder have the same sign as
11079the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
11080remainder follows the sign of the dividend. Both methods are
11081arithmetically valid, the latter being almost exclusively used.
11082
11083@item -mtoplevel-symbols
11084@itemx -mno-toplevel-symbols
11085@opindex mtoplevel-symbols
11086@opindex mno-toplevel-symbols
11087Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
11088code can be used with the @code{PREFIX} assembly directive.
11089
11090@item -melf
11091@opindex melf
11092Generate an executable in the ELF format, rather than the default
11093@samp{mmo} format used by the @command{mmix} simulator.
11094
11095@item -mbranch-predict
11096@itemx -mno-branch-predict
11097@opindex mbranch-predict
11098@opindex mno-branch-predict
11099Use (do not use) the probable-branch instructions, when static branch
11100prediction indicates a probable branch.
11101
11102@item -mbase-addresses
11103@itemx -mno-base-addresses
11104@opindex mbase-addresses
11105@opindex mno-base-addresses
11106Generate (do not generate) code that uses @emph{base addresses}. Using a
11107base address automatically generates a request (handled by the assembler
11108and the linker) for a constant to be set up in a global register. The
11109register is used for one or more base address requests within the range 0
11110to 255 from the value held in the register. The generally leads to short
11111and fast code, but the number of different data items that can be
11112addressed is limited. This means that a program that uses lots of static
11113data may require @option{-mno-base-addresses}.
11114
11115@item -msingle-exit
11116@itemx -mno-single-exit
11117@opindex msingle-exit
11118@opindex mno-single-exit
11119Force (do not force) generated code to have a single exit point in each
11120function.
11121@end table
11122
11123@node MN10300 Options
11124@subsection MN10300 Options
11125@cindex MN10300 options
11126
11127These @option{-m} options are defined for Matsushita MN10300 architectures:
11128
11129@table @gcctabopt
11130@item -mmult-bug
11131@opindex mmult-bug
11132Generate code to avoid bugs in the multiply instructions for the MN10300
11133processors. This is the default.
11134
11135@item -mno-mult-bug
11136@opindex mno-mult-bug
11137Do not generate code to avoid bugs in the multiply instructions for the
11138MN10300 processors.
11139
11140@item -mam33
11141@opindex mam33
11142Generate code which uses features specific to the AM33 processor.
11143
11144@item -mno-am33
11145@opindex mno-am33
11146Do not generate code which uses features specific to the AM33 processor. This
11147is the default.
11148
11149@item -mreturn-pointer-on-d0
11150@opindex mreturn-pointer-on-d0
11151When generating a function which returns a pointer, return the pointer
11152in both @code{a0} and @code{d0}. Otherwise, the pointer is returned
11153only in a0, and attempts to call such functions without a prototype
11154would result in errors. Note that this option is on by default; use
11155@option{-mno-return-pointer-on-d0} to disable it.
11156
11157@item -mno-crt0
11158@opindex mno-crt0
11159Do not link in the C run-time initialization object file.
11160
11161@item -mrelax
11162@opindex mrelax
11163Indicate to the linker that it should perform a relaxation optimization pass
11164to shorten branches, calls and absolute memory addresses. This option only
11165has an effect when used on the command line for the final link step.
11166
11167This option makes symbolic debugging impossible.
11168@end table
11169
11170@node MT Options
11171@subsection MT Options
11172@cindex MT options
11173
11174These @option{-m} options are defined for Morpho MT architectures:
11175
11176@table @gcctabopt
11177
11178@item -march=@var{cpu-type}
11179@opindex march
11180Generate code that will run on @var{cpu-type}, which is the name of a system
11181representing a certain processor type. Possible values for
11182@var{cpu-type} are @samp{ms1-64-001}, @samp{ms1-16-002},
11183@samp{ms1-16-003} and @samp{ms2}.
11184
11185When this option is not used, the default is @option{-march=ms1-16-002}.
11186
11187@item -mbacc
11188@opindex mbacc
11189Use byte loads and stores when generating code.
11190
11191@item -mno-bacc
11192@opindex mno-bacc
11193Do not use byte loads and stores when generating code.
11194
11195@item -msim
11196@opindex msim
11197Use simulator runtime
11198
11199@item -mno-crt0
11200@opindex mno-crt0
11201Do not link in the C run-time initialization object file
11202@file{crti.o}. Other run-time initialization and termination files
11203such as @file{startup.o} and @file{exit.o} are still included on the
11204linker command line.
11205
11206@end table
11207
11208@node PDP-11 Options
11209@subsection PDP-11 Options
11210@cindex PDP-11 Options
11211
11212These options are defined for the PDP-11:
11213
11214@table @gcctabopt
11215@item -mfpu
11216@opindex mfpu
11217Use hardware FPP floating point. This is the default. (FIS floating
11218point on the PDP-11/40 is not supported.)
11219
11220@item -msoft-float
11221@opindex msoft-float
11222Do not use hardware floating point.
11223
11224@item -mac0
11225@opindex mac0
11226Return floating-point results in ac0 (fr0 in Unix assembler syntax).
11227
11228@item -mno-ac0
11229@opindex mno-ac0
11230Return floating-point results in memory. This is the default.
11231
11232@item -m40
11233@opindex m40
11234Generate code for a PDP-11/40.
11235
11236@item -m45
11237@opindex m45
11238Generate code for a PDP-11/45. This is the default.
11239
11240@item -m10
11241@opindex m10
11242Generate code for a PDP-11/10.
11243
11244@item -mbcopy-builtin
11245@opindex bcopy-builtin
11246Use inline @code{movmemhi} patterns for copying memory. This is the
11247default.
11248
11249@item -mbcopy
11250@opindex mbcopy
11251Do not use inline @code{movmemhi} patterns for copying memory.
11252
11253@item -mint16
11254@itemx -mno-int32
11255@opindex mint16
11256@opindex mno-int32
11257Use 16-bit @code{int}. This is the default.
11258
11259@item -mint32
11260@itemx -mno-int16
11261@opindex mint32
11262@opindex mno-int16
11263Use 32-bit @code{int}.
11264
11265@item -mfloat64
11266@itemx -mno-float32
11267@opindex mfloat64
11268@opindex mno-float32
11269Use 64-bit @code{float}. This is the default.
11270
11271@item -mfloat32
11272@itemx -mno-float64
11273@opindex mfloat32
11274@opindex mno-float64
11275Use 32-bit @code{float}.
11276
11277@item -mabshi
11278@opindex mabshi
11279Use @code{abshi2} pattern. This is the default.
11280
11281@item -mno-abshi
11282@opindex mno-abshi
11283Do not use @code{abshi2} pattern.
11284
11285@item -mbranch-expensive
11286@opindex mbranch-expensive
11287Pretend that branches are expensive. This is for experimenting with
11288code generation only.
11289
11290@item -mbranch-cheap
11291@opindex mbranch-cheap
11292Do not pretend that branches are expensive. This is the default.
11293
11294@item -msplit
11295@opindex msplit
11296Generate code for a system with split I&D@.
11297
11298@item -mno-split
11299@opindex mno-split
11300Generate code for a system without split I&D@. This is the default.
11301
11302@item -munix-asm
11303@opindex munix-asm
11304Use Unix assembler syntax. This is the default when configured for
11305@samp{pdp11-*-bsd}.
11306
11307@item -mdec-asm
11308@opindex mdec-asm
11309Use DEC assembler syntax. This is the default when configured for any
11310PDP-11 target other than @samp{pdp11-*-bsd}.
11311@end table
11312
11313@node PowerPC Options
11314@subsection PowerPC Options
11315@cindex PowerPC options
11316
11317These are listed under @xref{RS/6000 and PowerPC Options}.
11318
11319@node RS/6000 and PowerPC Options
11320@subsection IBM RS/6000 and PowerPC Options
11321@cindex RS/6000 and PowerPC Options
11322@cindex IBM RS/6000 and PowerPC Options
11323
11324These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
11325@table @gcctabopt
11326@item -mpower
11327@itemx -mno-power
11328@itemx -mpower2
11329@itemx -mno-power2
11330@itemx -mpowerpc
11331@itemx -mno-powerpc
11332@itemx -mpowerpc-gpopt
11333@itemx -mno-powerpc-gpopt
11334@itemx -mpowerpc-gfxopt
11335@itemx -mno-powerpc-gfxopt
11336@itemx -mpowerpc64
11337@itemx -mno-powerpc64
11338@itemx -mmfcrf
11339@itemx -mno-mfcrf
11340@itemx -mpopcntb
11341@itemx -mno-popcntb
11342@itemx -mfprnd
11343@itemx -mno-fprnd
11344@opindex mpower
11345@opindex mno-power
11346@opindex mpower2
11347@opindex mno-power2
11348@opindex mpowerpc
11349@opindex mno-powerpc
11350@opindex mpowerpc-gpopt
11351@opindex mno-powerpc-gpopt
11352@opindex mpowerpc-gfxopt
11353@opindex mno-powerpc-gfxopt
11354@opindex mpowerpc64
11355@opindex mno-powerpc64
11356@opindex mmfcrf
11357@opindex mno-mfcrf
11358@opindex mpopcntb
11359@opindex mno-popcntb
11360@opindex mfprnd
11361@opindex mno-fprnd
11362GCC supports two related instruction set architectures for the
11363RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those
11364instructions supported by the @samp{rios} chip set used in the original
11365RS/6000 systems and the @dfn{PowerPC} instruction set is the
11366architecture of the Freescale MPC5xx, MPC6xx, MPC8xx microprocessors, and
11367the IBM 4xx, 6xx, and follow-on microprocessors.
11368
11369Neither architecture is a subset of the other. However there is a
11370large common subset of instructions supported by both. An MQ
11371register is included in processors supporting the POWER architecture.
11372
11373You use these options to specify which instructions are available on the
11374processor you are using. The default value of these options is
11375determined when configuring GCC@. Specifying the
11376@option{-mcpu=@var{cpu_type}} overrides the specification of these
11377options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
11378rather than the options listed above.
11379
11380The @option{-mpower} option allows GCC to generate instructions that
11381are found only in the POWER architecture and to use the MQ register.
11382Specifying @option{-mpower2} implies @option{-power} and also allows GCC
11383to generate instructions that are present in the POWER2 architecture but
11384not the original POWER architecture.
11385
11386The @option{-mpowerpc} option allows GCC to generate instructions that
11387are found only in the 32-bit subset of the PowerPC architecture.
11388Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
11389GCC to use the optional PowerPC architecture instructions in the
11390General Purpose group, including floating-point square root. Specifying
11391@option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
11392use the optional PowerPC architecture instructions in the Graphics
11393group, including floating-point select.
11394
11395The @option{-mmfcrf} option allows GCC to generate the move from
11396condition register field instruction implemented on the POWER4
11397processor and other processors that support the PowerPC V2.01
11398architecture.
11399The @option{-mpopcntb} option allows GCC to generate the popcount and
11400double precision FP reciprocal estimate instruction implemented on the
11401POWER5 processor and other processors that support the PowerPC V2.02
11402architecture.
11403The @option{-mfprnd} option allows GCC to generate the FP round to
11404integer instructions implemented on the POWER5+ processor and other
11405processors that support the PowerPC V2.03 architecture.
11406
11407The @option{-mpowerpc64} option allows GCC to generate the additional
1140864-bit instructions that are found in the full PowerPC64 architecture
11409and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
11410@option{-mno-powerpc64}.
11411
11412If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
11413will use only the instructions in the common subset of both
11414architectures plus some special AIX common-mode calls, and will not use
11415the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
11416permits GCC to use any instruction from either architecture and to
11417allow use of the MQ register; specify this for the Motorola MPC601.
11418
11419@item -mnew-mnemonics
11420@itemx -mold-mnemonics
11421@opindex mnew-mnemonics
11422@opindex mold-mnemonics
11423Select which mnemonics to use in the generated assembler code. With
11424@option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
11425the PowerPC architecture. With @option{-mold-mnemonics} it uses the
11426assembler mnemonics defined for the POWER architecture. Instructions
11427defined in only one architecture have only one mnemonic; GCC uses that
11428mnemonic irrespective of which of these options is specified.
11429
11430GCC defaults to the mnemonics appropriate for the architecture in
11431use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
11432value of these option. Unless you are building a cross-compiler, you
11433should normally not specify either @option{-mnew-mnemonics} or
11434@option{-mold-mnemonics}, but should instead accept the default.
11435
11436@item -mcpu=@var{cpu_type}
11437@opindex mcpu
11438Set architecture type, register usage, choice of mnemonics, and
11439instruction scheduling parameters for machine type @var{cpu_type}.
11440Supported values for @var{cpu_type} are @samp{401}, @samp{403},
11441@samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{505},
11442@samp{601}, @samp{602}, @samp{603}, @samp{603e}, @samp{604},
11443@samp{604e}, @samp{620}, @samp{630}, @samp{740}, @samp{7400},
11444@samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
11445@samp{860}, @samp{970}, @samp{8540}, @samp{ec603e}, @samp{G3},
11446@samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3},
11447@samp{power4}, @samp{power5}, @samp{power5+}, @samp{power6},
11448@samp{common}, @samp{powerpc}, @samp{powerpc64},
11449@samp{rios}, @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64}.
11450
11451@option{-mcpu=common} selects a completely generic processor. Code
11452generated under this option will run on any POWER or PowerPC processor.
11453GCC will use only the instructions in the common subset of both
11454architectures, and will not use the MQ register. GCC assumes a generic
11455processor model for scheduling purposes.
11456
11457@option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
11458@option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
11459PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
11460types, with an appropriate, generic processor model assumed for
11461scheduling purposes.
11462
11463The other options specify a specific processor. Code generated under
11464those options will run best on that processor, and may not run at all on
11465others.
11466
11467The @option{-mcpu} options automatically enable or disable the
11468following options: @option{-maltivec}, @option{-mfprnd},
11469@option{-mhard-float}, @option{-mmfcrf}, @option{-mmultiple},
11470@option{-mnew-mnemonics}, @option{-mpopcntb}, @option{-mpower},
11471@option{-mpower2}, @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
11472@option{-mpowerpc-gfxopt}, @option{-mstring}, @option{-mmulhw}, @option{-mdlmzb}.
11473The particular options
11474set for any particular CPU will vary between compiler versions,
11475depending on what setting seems to produce optimal code for that CPU;
11476it doesn't necessarily reflect the actual hardware's capabilities. If
11477you wish to set an individual option to a particular value, you may
11478specify it after the @option{-mcpu} option, like @samp{-mcpu=970
11479-mno-altivec}.
11480
11481On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
11482not enabled or disabled by the @option{-mcpu} option at present because
11483AIX does not have full support for these options. You may still
11484enable or disable them individually if you're sure it'll work in your
11485environment.
11486
11487@item -mtune=@var{cpu_type}
11488@opindex mtune
11489Set the instruction scheduling parameters for machine type
11490@var{cpu_type}, but do not set the architecture type, register usage, or
11491choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
11492values for @var{cpu_type} are used for @option{-mtune} as for
11493@option{-mcpu}. If both are specified, the code generated will use the
11494architecture, registers, and mnemonics set by @option{-mcpu}, but the
11495scheduling parameters set by @option{-mtune}.
11496
11497@item -mswdiv
11498@itemx -mno-swdiv
11499@opindex mswdiv
11500@opindex mno-swdiv
11501Generate code to compute division as reciprocal estimate and iterative
11502refinement, creating opportunities for increased throughput. This
11503feature requires: optional PowerPC Graphics instruction set for single
11504precision and FRE instruction for double precision, assuming divides
11505cannot generate user-visible traps, and the domain values not include
11506Infinities, denormals or zero denominator.
11507
11508@item -maltivec
11509@itemx -mno-altivec
11510@opindex maltivec
11511@opindex mno-altivec
11512Generate code that uses (does not use) AltiVec instructions, and also
11513enable the use of built-in functions that allow more direct access to
11514the AltiVec instruction set. You may also need to set
11515@option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
11516enhancements.
11517
11518@item -mvrsave
11519@item -mno-vrsave
11520@opindex mvrsave
11521@opindex mno-vrsave
11522Generate VRSAVE instructions when generating AltiVec code.
11523
11524@item -msecure-plt
11525@opindex msecure-plt
11526Generate code that allows ld and ld.so to build executables and shared
11527libraries with non-exec .plt and .got sections. This is a PowerPC
1152832-bit SYSV ABI option.
11529
11530@item -mbss-plt
11531@opindex mbss-plt
11532Generate code that uses a BSS .plt section that ld.so fills in, and
11533requires .plt and .got sections that are both writable and executable.
11534This is a PowerPC 32-bit SYSV ABI option.
11535
11536@item -misel
11537@itemx -mno-isel
11538@opindex misel
11539@opindex mno-isel
11540This switch enables or disables the generation of ISEL instructions.
11541
11542@item -misel=@var{yes/no}
11543This switch has been deprecated. Use @option{-misel} and
11544@option{-mno-isel} instead.
11545
11546@item -mspe
11547@itemx -mno-spe
11548@opindex mspe
11549@opindex mno-spe
11550This switch enables or disables the generation of SPE simd
11551instructions.
11552
11553@item -mspe=@var{yes/no}
11554This option has been deprecated. Use @option{-mspe} and
11555@option{-mno-spe} instead.
11556
11557@item -mfloat-gprs=@var{yes/single/double/no}
11558@itemx -mfloat-gprs
11559@opindex mfloat-gprs
11560This switch enables or disables the generation of floating point
11561operations on the general purpose registers for architectures that
11562support it.
11563
11564The argument @var{yes} or @var{single} enables the use of
11565single-precision floating point operations.
11566
11567The argument @var{double} enables the use of single and
11568double-precision floating point operations.
11569
11570The argument @var{no} disables floating point operations on the
11571general purpose registers.
11572
11573This option is currently only available on the MPC854x.
11574
11575@item -m32
11576@itemx -m64
11577@opindex m32
11578@opindex m64
11579Generate code for 32-bit or 64-bit environments of Darwin and SVR4
11580targets (including GNU/Linux). The 32-bit environment sets int, long
11581and pointer to 32 bits and generates code that runs on any PowerPC
11582variant. The 64-bit environment sets int to 32 bits and long and
11583pointer to 64 bits, and generates code for PowerPC64, as for
11584@option{-mpowerpc64}.
11585
11586@item -mfull-toc
11587@itemx -mno-fp-in-toc
11588@itemx -mno-sum-in-toc
11589@itemx -mminimal-toc
11590@opindex mfull-toc
11591@opindex mno-fp-in-toc
11592@opindex mno-sum-in-toc
11593@opindex mminimal-toc
11594Modify generation of the TOC (Table Of Contents), which is created for
11595every executable file. The @option{-mfull-toc} option is selected by
11596default. In that case, GCC will allocate at least one TOC entry for
11597each unique non-automatic variable reference in your program. GCC
11598will also place floating-point constants in the TOC@. However, only
1159916,384 entries are available in the TOC@.
11600
11601If you receive a linker error message that saying you have overflowed
11602the available TOC space, you can reduce the amount of TOC space used
11603with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
11604@option{-mno-fp-in-toc} prevents GCC from putting floating-point
11605constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
11606generate code to calculate the sum of an address and a constant at
11607run-time instead of putting that sum into the TOC@. You may specify one
11608or both of these options. Each causes GCC to produce very slightly
11609slower and larger code at the expense of conserving TOC space.
11610
11611If you still run out of space in the TOC even when you specify both of
11612these options, specify @option{-mminimal-toc} instead. This option causes
11613GCC to make only one TOC entry for every file. When you specify this
11614option, GCC will produce code that is slower and larger but which
11615uses extremely little TOC space. You may wish to use this option
11616only on files that contain less frequently executed code.
11617
11618@item -maix64
11619@itemx -maix32
11620@opindex maix64
11621@opindex maix32
11622Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
11623@code{long} type, and the infrastructure needed to support them.
11624Specifying @option{-maix64} implies @option{-mpowerpc64} and
11625@option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
11626implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
11627
11628@item -mxl-compat
11629@itemx -mno-xl-compat
11630@opindex mxl-compat
11631@opindex mno-xl-compat
11632Produce code that conforms more closely to IBM XL compiler semantics
11633when using AIX-compatible ABI. Pass floating-point arguments to
11634prototyped functions beyond the register save area (RSA) on the stack
11635in addition to argument FPRs. Do not assume that most significant
11636double in 128-bit long double value is properly rounded when comparing
11637values and converting to double. Use XL symbol names for long double
11638support routines.
11639
11640The AIX calling convention was extended but not initially documented to
11641handle an obscure K&R C case of calling a function that takes the
11642address of its arguments with fewer arguments than declared. IBM XL
11643compilers access floating point arguments which do not fit in the
11644RSA from the stack when a subroutine is compiled without
11645optimization. Because always storing floating-point arguments on the
11646stack is inefficient and rarely needed, this option is not enabled by
11647default and only is necessary when calling subroutines compiled by IBM
11648XL compilers without optimization.
11649
11650@item -mpe
11651@opindex mpe
11652Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
11653application written to use message passing with special startup code to
11654enable the application to run. The system must have PE installed in the
11655standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
11656must be overridden with the @option{-specs=} option to specify the
11657appropriate directory location. The Parallel Environment does not
11658support threads, so the @option{-mpe} option and the @option{-pthread}
11659option are incompatible.
11660
11661@item -malign-natural
11662@itemx -malign-power
11663@opindex malign-natural
11664@opindex malign-power
11665On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
11666@option{-malign-natural} overrides the ABI-defined alignment of larger
11667types, such as floating-point doubles, on their natural size-based boundary.
11668The option @option{-malign-power} instructs GCC to follow the ABI-specified
11669alignment rules. GCC defaults to the standard alignment defined in the ABI@.
11670
11671On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
11672is not supported.
11673
11674@item -msoft-float
11675@itemx -mhard-float
11676@opindex msoft-float
11677@opindex mhard-float
11678Generate code that does not use (uses) the floating-point register set.
11679Software floating point emulation is provided if you use the
11680@option{-msoft-float} option, and pass the option to GCC when linking.
11681
11682@item -mmultiple
11683@itemx -mno-multiple
11684@opindex mmultiple
11685@opindex mno-multiple
11686Generate code that uses (does not use) the load multiple word
11687instructions and the store multiple word instructions. These
11688instructions are generated by default on POWER systems, and not
11689generated on PowerPC systems. Do not use @option{-mmultiple} on little
11690endian PowerPC systems, since those instructions do not work when the
11691processor is in little endian mode. The exceptions are PPC740 and
11692PPC750 which permit the instructions usage in little endian mode.
11693
11694@item -mstring
11695@itemx -mno-string
11696@opindex mstring
11697@opindex mno-string
11698Generate code that uses (does not use) the load string instructions
11699and the store string word instructions to save multiple registers and
11700do small block moves. These instructions are generated by default on
11701POWER systems, and not generated on PowerPC systems. Do not use
11702@option{-mstring} on little endian PowerPC systems, since those
11703instructions do not work when the processor is in little endian mode.
11704The exceptions are PPC740 and PPC750 which permit the instructions
11705usage in little endian mode.
11706
11707@item -mupdate
11708@itemx -mno-update
11709@opindex mupdate
11710@opindex mno-update
11711Generate code that uses (does not use) the load or store instructions
11712that update the base register to the address of the calculated memory
11713location. These instructions are generated by default. If you use
11714@option{-mno-update}, there is a small window between the time that the
11715stack pointer is updated and the address of the previous frame is
11716stored, which means code that walks the stack frame across interrupts or
11717signals may get corrupted data.
11718
11719@item -mfused-madd
11720@itemx -mno-fused-madd
11721@opindex mfused-madd
11722@opindex mno-fused-madd
11723Generate code that uses (does not use) the floating point multiply and
11724accumulate instructions. These instructions are generated by default if
11725hardware floating is used.
11726
11727@item -mmulhw
11728@itemx -mno-mulhw
11729@opindex mmulhw
11730@opindex mno-mulhw
11731Generate code that uses (does not use) the half-word multiply and
11732multiply-accumulate instructions on the IBM 405 and 440 processors.
11733These instructions are generated by default when targetting those
11734processors.
11735
11736@item -mdlmzb
11737@itemx -mno-dlmzb
11738@opindex mdlmzb
11739@opindex mno-dlmzb
11740Generate code that uses (does not use) the string-search @samp{dlmzb}
11741instruction on the IBM 405 and 440 processors. This instruction is
11742generated by default when targetting those processors.
11743
11744@item -mno-bit-align
11745@itemx -mbit-align
11746@opindex mno-bit-align
11747@opindex mbit-align
11748On System V.4 and embedded PowerPC systems do not (do) force structures
11749and unions that contain bit-fields to be aligned to the base type of the
11750bit-field.
11751
11752For example, by default a structure containing nothing but 8
11753@code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
11754boundary and have a size of 4 bytes. By using @option{-mno-bit-align},
11755the structure would be aligned to a 1 byte boundary and be one byte in
11756size.
11757
11758@item -mno-strict-align
11759@itemx -mstrict-align
11760@opindex mno-strict-align
11761@opindex mstrict-align
11762On System V.4 and embedded PowerPC systems do not (do) assume that
11763unaligned memory references will be handled by the system.
11764
11765@item -mrelocatable
11766@itemx -mno-relocatable
11767@opindex mrelocatable
11768@opindex mno-relocatable
11769On embedded PowerPC systems generate code that allows (does not allow)
11770the program to be relocated to a different address at runtime. If you
11771use @option{-mrelocatable} on any module, all objects linked together must
11772be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
11773
11774@item -mrelocatable-lib
11775@itemx -mno-relocatable-lib
11776@opindex mrelocatable-lib
11777@opindex mno-relocatable-lib
11778On embedded PowerPC systems generate code that allows (does not allow)
11779the program to be relocated to a different address at runtime. Modules
11780compiled with @option{-mrelocatable-lib} can be linked with either modules
11781compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
11782with modules compiled with the @option{-mrelocatable} options.
11783
11784@item -mno-toc
11785@itemx -mtoc
11786@opindex mno-toc
11787@opindex mtoc
11788On System V.4 and embedded PowerPC systems do not (do) assume that
11789register 2 contains a pointer to a global area pointing to the addresses
11790used in the program.
11791
11792@item -mlittle
11793@itemx -mlittle-endian
11794@opindex mlittle
11795@opindex mlittle-endian
11796On System V.4 and embedded PowerPC systems compile code for the
11797processor in little endian mode. The @option{-mlittle-endian} option is
11798the same as @option{-mlittle}.
11799
11800@item -mbig
11801@itemx -mbig-endian
11802@opindex mbig
11803@opindex mbig-endian
11804On System V.4 and embedded PowerPC systems compile code for the
11805processor in big endian mode. The @option{-mbig-endian} option is
11806the same as @option{-mbig}.
11807
11808@item -mdynamic-no-pic
11809@opindex mdynamic-no-pic
11810On Darwin and Mac OS X systems, compile code so that it is not
11811relocatable, but that its external references are relocatable. The
11812resulting code is suitable for applications, but not shared
11813libraries.
11814
11815@item -mprioritize-restricted-insns=@var{priority}
11816@opindex mprioritize-restricted-insns
11817This option controls the priority that is assigned to
11818dispatch-slot restricted instructions during the second scheduling
11819pass. The argument @var{priority} takes the value @var{0/1/2} to assign
11820@var{no/highest/second-highest} priority to dispatch slot restricted
11821instructions.
11822
11823@item -msched-costly-dep=@var{dependence_type}
11824@opindex msched-costly-dep
11825This option controls which dependences are considered costly
11826by the target during instruction scheduling. The argument
11827@var{dependence_type} takes one of the following values:
11828@var{no}: no dependence is costly,
11829@var{all}: all dependences are costly,
11830@var{true_store_to_load}: a true dependence from store to load is costly,
11831@var{store_to_load}: any dependence from store to load is costly,
11832@var{number}: any dependence which latency >= @var{number} is costly.
11833
11834@item -minsert-sched-nops=@var{scheme}
11835@opindex minsert-sched-nops
11836This option controls which nop insertion scheme will be used during
11837the second scheduling pass. The argument @var{scheme} takes one of the
11838following values:
11839@var{no}: Don't insert nops.
11840@var{pad}: Pad with nops any dispatch group which has vacant issue slots,
11841according to the scheduler's grouping.
11842@var{regroup_exact}: Insert nops to force costly dependent insns into
11843separate groups. Insert exactly as many nops as needed to force an insn
11844to a new group, according to the estimated processor grouping.
11845@var{number}: Insert nops to force costly dependent insns into
11846separate groups. Insert @var{number} nops to force an insn to a new group.
11847
11848@item -mcall-sysv
11849@opindex mcall-sysv
11850On System V.4 and embedded PowerPC systems compile code using calling
11851conventions that adheres to the March 1995 draft of the System V
11852Application Binary Interface, PowerPC processor supplement. This is the
11853default unless you configured GCC using @samp{powerpc-*-eabiaix}.
11854
11855@item -mcall-sysv-eabi
11856@opindex mcall-sysv-eabi
11857Specify both @option{-mcall-sysv} and @option{-meabi} options.
11858
11859@item -mcall-sysv-noeabi
11860@opindex mcall-sysv-noeabi
11861Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
11862
11863@item -mcall-solaris
11864@opindex mcall-solaris
11865On System V.4 and embedded PowerPC systems compile code for the Solaris
11866operating system.
11867
11868@item -mcall-linux
11869@opindex mcall-linux
11870On System V.4 and embedded PowerPC systems compile code for the
11871Linux-based GNU system.
11872
11873@item -mcall-gnu
11874@opindex mcall-gnu
11875On System V.4 and embedded PowerPC systems compile code for the
11876Hurd-based GNU system.
11877
11878@item -mcall-netbsd
11879@opindex mcall-netbsd
11880On System V.4 and embedded PowerPC systems compile code for the
11881NetBSD operating system.
11882
11883@item -maix-struct-return
11884@opindex maix-struct-return
11885Return all structures in memory (as specified by the AIX ABI)@.
11886
11887@item -msvr4-struct-return
11888@opindex msvr4-struct-return
11889Return structures smaller than 8 bytes in registers (as specified by the
11890SVR4 ABI)@.
11891
11892@item -mabi=@var{abi-type}
11893@opindex mabi
11894Extend the current ABI with a particular extension, or remove such extension.
11895Valid values are @var{altivec}, @var{no-altivec}, @var{spe},
11896@var{no-spe}, @var{ibmlongdouble}, @var{ieeelongdouble}@.
11897
11898@item -mabi=spe
11899@opindex mabi=spe
11900Extend the current ABI with SPE ABI extensions. This does not change
11901the default ABI, instead it adds the SPE ABI extensions to the current
11902ABI@.
11903
11904@item -mabi=no-spe
11905@opindex mabi=no-spe
11906Disable Booke SPE ABI extensions for the current ABI@.
11907
11908@item -mabi=ibmlongdouble
11909@opindex mabi=ibmlongdouble
11910Change the current ABI to use IBM extended precision long double.
11911This is a PowerPC 32-bit SYSV ABI option.
11912
11913@item -mabi=ieeelongdouble
11914@opindex mabi=ieeelongdouble
11915Change the current ABI to use IEEE extended precision long double.
11916This is a PowerPC 32-bit Linux ABI option.
11917
11918@item -mprototype
11919@itemx -mno-prototype
11920@opindex mprototype
11921@opindex mno-prototype
11922On System V.4 and embedded PowerPC systems assume that all calls to
11923variable argument functions are properly prototyped. Otherwise, the
11924compiler must insert an instruction before every non prototyped call to
11925set or clear bit 6 of the condition code register (@var{CR}) to
11926indicate whether floating point values were passed in the floating point
11927registers in case the function takes a variable arguments. With
11928@option{-mprototype}, only calls to prototyped variable argument functions
11929will set or clear the bit.
11930
11931@item -msim
11932@opindex msim
11933On embedded PowerPC systems, assume that the startup module is called
11934@file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
11935@file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
11936configurations.
11937
11938@item -mmvme
11939@opindex mmvme
11940On embedded PowerPC systems, assume that the startup module is called
11941@file{crt0.o} and the standard C libraries are @file{libmvme.a} and
11942@file{libc.a}.
11943
11944@item -mads
11945@opindex mads
11946On embedded PowerPC systems, assume that the startup module is called
11947@file{crt0.o} and the standard C libraries are @file{libads.a} and
11948@file{libc.a}.
11949
11950@item -myellowknife
11951@opindex myellowknife
11952On embedded PowerPC systems, assume that the startup module is called
11953@file{crt0.o} and the standard C libraries are @file{libyk.a} and
11954@file{libc.a}.
11955
11956@item -mvxworks
11957@opindex mvxworks
11958On System V.4 and embedded PowerPC systems, specify that you are
11959compiling for a VxWorks system.
11960
11961@item -mwindiss
11962@opindex mwindiss
11963Specify that you are compiling for the WindISS simulation environment.
11964
11965@item -memb
11966@opindex memb
11967On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
11968header to indicate that @samp{eabi} extended relocations are used.
11969
11970@item -meabi
11971@itemx -mno-eabi
11972@opindex meabi
11973@opindex mno-eabi
11974On System V.4 and embedded PowerPC systems do (do not) adhere to the
11975Embedded Applications Binary Interface (eabi) which is a set of
11976modifications to the System V.4 specifications. Selecting @option{-meabi}
11977means that the stack is aligned to an 8 byte boundary, a function
11978@code{__eabi} is called to from @code{main} to set up the eabi
11979environment, and the @option{-msdata} option can use both @code{r2} and
11980@code{r13} to point to two separate small data areas. Selecting
11981@option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
11982do not call an initialization function from @code{main}, and the
11983@option{-msdata} option will only use @code{r13} to point to a single
11984small data area. The @option{-meabi} option is on by default if you
11985configured GCC using one of the @samp{powerpc*-*-eabi*} options.
11986
11987@item -msdata=eabi
11988@opindex msdata=eabi
11989On System V.4 and embedded PowerPC systems, put small initialized
11990@code{const} global and static data in the @samp{.sdata2} section, which
11991is pointed to by register @code{r2}. Put small initialized
11992non-@code{const} global and static data in the @samp{.sdata} section,
11993which is pointed to by register @code{r13}. Put small uninitialized
11994global and static data in the @samp{.sbss} section, which is adjacent to
11995the @samp{.sdata} section. The @option{-msdata=eabi} option is
11996incompatible with the @option{-mrelocatable} option. The
11997@option{-msdata=eabi} option also sets the @option{-memb} option.
11998
11999@item -msdata=sysv
12000@opindex msdata=sysv
12001On System V.4 and embedded PowerPC systems, put small global and static
12002data in the @samp{.sdata} section, which is pointed to by register
12003@code{r13}. Put small uninitialized global and static data in the
12004@samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
12005The @option{-msdata=sysv} option is incompatible with the
12006@option{-mrelocatable} option.
12007
12008@item -msdata=default
12009@itemx -msdata
12010@opindex msdata=default
12011@opindex msdata
12012On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
12013compile code the same as @option{-msdata=eabi}, otherwise compile code the
12014same as @option{-msdata=sysv}.
12015
12016@item -msdata-data
12017@opindex msdata-data
12018On System V.4 and embedded PowerPC systems, put small global
12019data in the @samp{.sdata} section. Put small uninitialized global
12020data in the @samp{.sbss} section. Do not use register @code{r13}
12021to address small data however. This is the default behavior unless
12022other @option{-msdata} options are used.
12023
12024@item -msdata=none
12025@itemx -mno-sdata
12026@opindex msdata=none
12027@opindex mno-sdata
12028On embedded PowerPC systems, put all initialized global and static data
12029in the @samp{.data} section, and all uninitialized data in the
12030@samp{.bss} section.
12031
12032@item -G @var{num}
12033@opindex G
12034@cindex smaller data references (PowerPC)
12035@cindex .sdata/.sdata2 references (PowerPC)
12036On embedded PowerPC systems, put global and static items less than or
12037equal to @var{num} bytes into the small data or bss sections instead of
12038the normal data or bss section. By default, @var{num} is 8. The
12039@option{-G @var{num}} switch is also passed to the linker.
12040All modules should be compiled with the same @option{-G @var{num}} value.
12041
12042@item -mregnames
12043@itemx -mno-regnames
12044@opindex mregnames
12045@opindex mno-regnames
12046On System V.4 and embedded PowerPC systems do (do not) emit register
12047names in the assembly language output using symbolic forms.
12048
12049@item -mlongcall
12050@itemx -mno-longcall
12051@opindex mlongcall
12052@opindex mno-longcall
12053By default assume that all calls are far away so that a longer more
12054expensive calling sequence is required. This is required for calls
12055further than 32 megabytes (33,554,432 bytes) from the current location.
12056A short call will be generated if the compiler knows
12057the call cannot be that far away. This setting can be overridden by
12058the @code{shortcall} function attribute, or by @code{#pragma
12059longcall(0)}.
12060
12061Some linkers are capable of detecting out-of-range calls and generating
12062glue code on the fly. On these systems, long calls are unnecessary and
12063generate slower code. As of this writing, the AIX linker can do this,
12064as can the GNU linker for PowerPC/64. It is planned to add this feature
12065to the GNU linker for 32-bit PowerPC systems as well.
12066
12067On Darwin/PPC systems, @code{#pragma longcall} will generate ``jbsr
12068callee, L42'', plus a ``branch island'' (glue code). The two target
12069addresses represent the callee and the ``branch island''. The
12070Darwin/PPC linker will prefer the first address and generate a ``bl
12071callee'' if the PPC ``bl'' instruction will reach the callee directly;
12072otherwise, the linker will generate ``bl L42'' to call the ``branch
12073island''. The ``branch island'' is appended to the body of the
12074calling function; it computes the full 32-bit address of the callee
12075and jumps to it.
12076
12077On Mach-O (Darwin) systems, this option directs the compiler emit to
12078the glue for every direct call, and the Darwin linker decides whether
12079to use or discard it.
12080
12081In the future, we may cause GCC to ignore all longcall specifications
12082when the linker is known to generate glue.
12083
12084@item -pthread
12085@opindex pthread
12086Adds support for multithreading with the @dfn{pthreads} library.
12087This option sets flags for both the preprocessor and linker.
12088
12089@end table
12090
12091@node S/390 and zSeries Options
12092@subsection S/390 and zSeries Options
12093@cindex S/390 and zSeries Options
12094
12095These are the @samp{-m} options defined for the S/390 and zSeries architecture.
12096
12097@table @gcctabopt
12098@item -mhard-float
12099@itemx -msoft-float
12100@opindex mhard-float
12101@opindex msoft-float
12102Use (do not use) the hardware floating-point instructions and registers
12103for floating-point operations. When @option{-msoft-float} is specified,
12104functions in @file{libgcc.a} will be used to perform floating-point
12105operations. When @option{-mhard-float} is specified, the compiler
12106generates IEEE floating-point instructions. This is the default.
12107
12108@item -mlong-double-64
12109@itemx -mlong-double-128
12110@opindex mlong-double-64
12111@opindex mlong-double-128
12112These switches control the size of @code{long double} type. A size
12113of 64bit makes the @code{long double} type equivalent to the @code{double}
12114type. This is the default.
12115
12116@item -mbackchain
12117@itemx -mno-backchain
12118@opindex mbackchain
12119@opindex mno-backchain
12120Store (do not store) the address of the caller's frame as backchain pointer
12121into the callee's stack frame.
12122A backchain may be needed to allow debugging using tools that do not understand
12123DWARF-2 call frame information.
12124When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
12125at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
12126the backchain is placed into the topmost word of the 96/160 byte register
12127save area.
12128
12129In general, code compiled with @option{-mbackchain} is call-compatible with
12130code compiled with @option{-mmo-backchain}; however, use of the backchain
12131for debugging purposes usually requires that the whole binary is built with
12132@option{-mbackchain}. Note that the combination of @option{-mbackchain},
12133@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
12134to build a linux kernel use @option{-msoft-float}.
12135
12136The default is to not maintain the backchain.
12137
12138@item -mpacked-stack
12139@item -mno-packed-stack
12140@opindex mpacked-stack
12141@opindex mno-packed-stack
12142Use (do not use) the packed stack layout. When @option{-mno-packed-stack} is
12143specified, the compiler uses the all fields of the 96/160 byte register save
12144area only for their default purpose; unused fields still take up stack space.
12145When @option{-mpacked-stack} is specified, register save slots are densely
12146packed at the top of the register save area; unused space is reused for other
12147purposes, allowing for more efficient use of the available stack space.
12148However, when @option{-mbackchain} is also in effect, the topmost word of
12149the save area is always used to store the backchain, and the return address
12150register is always saved two words below the backchain.
12151
12152As long as the stack frame backchain is not used, code generated with
12153@option{-mpacked-stack} is call-compatible with code generated with
12154@option{-mno-packed-stack}. Note that some non-FSF releases of GCC 2.95 for
12155S/390 or zSeries generated code that uses the stack frame backchain at run
12156time, not just for debugging purposes. Such code is not call-compatible
12157with code compiled with @option{-mpacked-stack}. Also, note that the
12158combination of @option{-mbackchain},
12159@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
12160to build a linux kernel use @option{-msoft-float}.
12161
12162The default is to not use the packed stack layout.
12163
12164@item -msmall-exec
12165@itemx -mno-small-exec
12166@opindex msmall-exec
12167@opindex mno-small-exec
12168Generate (or do not generate) code using the @code{bras} instruction
12169to do subroutine calls.
12170This only works reliably if the total executable size does not
12171exceed 64k. The default is to use the @code{basr} instruction instead,
12172which does not have this limitation.
12173
12174@item -m64
12175@itemx -m31
12176@opindex m64
12177@opindex m31
12178When @option{-m31} is specified, generate code compliant to the
12179GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate
12180code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in
12181particular to generate 64-bit instructions. For the @samp{s390}
12182targets, the default is @option{-m31}, while the @samp{s390x}
12183targets default to @option{-m64}.
12184
12185@item -mzarch
12186@itemx -mesa
12187@opindex mzarch
12188@opindex mesa
12189When @option{-mzarch} is specified, generate code using the
12190instructions available on z/Architecture.
12191When @option{-mesa} is specified, generate code using the
12192instructions available on ESA/390. Note that @option{-mesa} is
12193not possible with @option{-m64}.
12194When generating code compliant to the GNU/Linux for S/390 ABI,
12195the default is @option{-mesa}. When generating code compliant
12196to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
12197
12198@item -mmvcle
12199@itemx -mno-mvcle
12200@opindex mmvcle
12201@opindex mno-mvcle
12202Generate (or do not generate) code using the @code{mvcle} instruction
12203to perform block moves. When @option{-mno-mvcle} is specified,
12204use a @code{mvc} loop instead. This is the default unless optimizing for
12205size.
12206
12207@item -mdebug
12208@itemx -mno-debug
12209@opindex mdebug
12210@opindex mno-debug
12211Print (or do not print) additional debug information when compiling.
12212The default is to not print debug information.
12213
12214@item -march=@var{cpu-type}
12215@opindex march
12216Generate code that will run on @var{cpu-type}, which is the name of a system
12217representing a certain processor type. Possible values for
12218@var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, and @samp{z990}.
12219When generating code using the instructions available on z/Architecture,
12220the default is @option{-march=z900}. Otherwise, the default is
12221@option{-march=g5}.
12222
12223@item -mtune=@var{cpu-type}
12224@opindex mtune
12225Tune to @var{cpu-type} everything applicable about the generated code,
12226except for the ABI and the set of available instructions.
12227The list of @var{cpu-type} values is the same as for @option{-march}.
12228The default is the value used for @option{-march}.
12229
12230@item -mtpf-trace
12231@itemx -mno-tpf-trace
12232@opindex mtpf-trace
12233@opindex mno-tpf-trace
12234Generate code that adds (does not add) in TPF OS specific branches to trace
12235routines in the operating system. This option is off by default, even
12236when compiling for the TPF OS@.
12237
12238@item -mfused-madd
12239@itemx -mno-fused-madd
12240@opindex mfused-madd
12241@opindex mno-fused-madd
12242Generate code that uses (does not use) the floating point multiply and
12243accumulate instructions. These instructions are generated by default if
12244hardware floating point is used.
12245
12246@item -mwarn-framesize=@var{framesize}
12247@opindex mwarn-framesize
12248Emit a warning if the current function exceeds the given frame size. Because
12249this is a compile time check it doesn't need to be a real problem when the program
12250runs. It is intended to identify functions which most probably cause
12251a stack overflow. It is useful to be used in an environment with limited stack
12252size e.g.@: the linux kernel.
12253
12254@item -mwarn-dynamicstack
12255@opindex mwarn-dynamicstack
12256Emit a warning if the function calls alloca or uses dynamically
12257sized arrays. This is generally a bad idea with a limited stack size.
12258
12259@item -mstack-guard=@var{stack-guard}
12260@item -mstack-size=@var{stack-size}
12261@opindex mstack-guard
12262@opindex mstack-size
12263These arguments always have to be used in conjunction. If they are present the s390
12264back end emits additional instructions in the function prologue which trigger a trap
12265if the stack size is @var{stack-guard} bytes above the @var{stack-size}
12266(remember that the stack on s390 grows downward). These options are intended to
12267be used to help debugging stack overflow problems. The additionally emitted code
12268causes only little overhead and hence can also be used in production like systems
12269without greater performance degradation. The given values have to be exact
12270powers of 2 and @var{stack-size} has to be greater than @var{stack-guard} without
12271exceeding 64k.
12272In order to be efficient the extra code makes the assumption that the stack starts
12273at an address aligned to the value given by @var{stack-size}.
12274@end table
12275
12276@node Score Options
12277@subsection Score Options
12278@cindex Score Options
12279
12280These options are defined for Score implementations:
12281
12282@table @gcctabopt
12283@item -meb
12284@opindex meb
12285Compile code for big endian mode. This is the default.
12286
12287@item -mel
12288@opindex mel
12289Compile code for little endian mode.
12290
12291@item -mnhwloop
12292@opindex mnhwloop
12293Disable generate bcnz instruction.
12294
12295@item -muls
12296@opindex muls
12297Enable generate unaligned load and store instruction.
12298
12299@item -mmac
12300@opindex mmac
12301Enable the use of multiply-accumulate instructions. Disabled by default.
12302
12303@item -mscore5
12304@opindex mscore5
12305Specify the SCORE5 as the target architecture.
12306
12307@item -mscore5u
12308@opindex mscore5u
12309Specify the SCORE5U of the target architecture.
12310
12311@item -mscore7
12312@opindex mscore7
12313Specify the SCORE7 as the target architecture. This is the default.
12314
12315@item -mscore7d
12316@opindex mscore7d
12317Specify the SCORE7D as the target architecture.
12318@end table
12319
12320@node SH Options
12321@subsection SH Options
12322
12323These @samp{-m} options are defined for the SH implementations:
12324
12325@table @gcctabopt
12326@item -m1
12327@opindex m1
12328Generate code for the SH1.
12329
12330@item -m2
12331@opindex m2
12332Generate code for the SH2.
12333
12334@item -m2e
12335Generate code for the SH2e.
12336
12337@item -m3
12338@opindex m3
12339Generate code for the SH3.
12340
12341@item -m3e
12342@opindex m3e
12343Generate code for the SH3e.
12344
12345@item -m4-nofpu
12346@opindex m4-nofpu
12347Generate code for the SH4 without a floating-point unit.
12348
12349@item -m4-single-only
12350@opindex m4-single-only
12351Generate code for the SH4 with a floating-point unit that only
12352supports single-precision arithmetic.
12353
12354@item -m4-single
12355@opindex m4-single
12356Generate code for the SH4 assuming the floating-point unit is in
12357single-precision mode by default.
12358
12359@item -m4
12360@opindex m4
12361Generate code for the SH4.
12362
12363@item -m4a-nofpu
12364@opindex m4a-nofpu
12365Generate code for the SH4al-dsp, or for a SH4a in such a way that the
12366floating-point unit is not used.
12367
12368@item -m4a-single-only
12369@opindex m4a-single-only
12370Generate code for the SH4a, in such a way that no double-precision
12371floating point operations are used.
12372
12373@item -m4a-single
12374@opindex m4a-single
12375Generate code for the SH4a assuming the floating-point unit is in
12376single-precision mode by default.
12377
12378@item -m4a
12379@opindex m4a
12380Generate code for the SH4a.
12381
12382@item -m4al
12383@opindex m4al
12384Same as @option{-m4a-nofpu}, except that it implicitly passes
12385@option{-dsp} to the assembler. GCC doesn't generate any DSP
12386instructions at the moment.
12387
12388@item -mb
12389@opindex mb
12390Compile code for the processor in big endian mode.
12391
12392@item -ml
12393@opindex ml
12394Compile code for the processor in little endian mode.
12395
12396@item -mdalign
12397@opindex mdalign
12398Align doubles at 64-bit boundaries. Note that this changes the calling
12399conventions, and thus some functions from the standard C library will
12400not work unless you recompile it first with @option{-mdalign}.
12401
12402@item -mrelax
12403@opindex mrelax
12404Shorten some address references at link time, when possible; uses the
12405linker option @option{-relax}.
12406
12407@item -mbigtable
12408@opindex mbigtable
12409Use 32-bit offsets in @code{switch} tables. The default is to use
1241016-bit offsets.
12411
12412@item -mfmovd
12413@opindex mfmovd
12414Enable the use of the instruction @code{fmovd}.
12415
12416@item -mhitachi
12417@opindex mhitachi
12418Comply with the calling conventions defined by Renesas.
12419
12420@item -mrenesas
12421@opindex mhitachi
12422Comply with the calling conventions defined by Renesas.
12423
12424@item -mno-renesas
12425@opindex mhitachi
12426Comply with the calling conventions defined for GCC before the Renesas
12427conventions were available. This option is the default for all
12428targets of the SH toolchain except for @samp{sh-symbianelf}.
12429
12430@item -mnomacsave
12431@opindex mnomacsave
12432Mark the @code{MAC} register as call-clobbered, even if
12433@option{-mhitachi} is given.
12434
12435@item -mieee
12436@opindex mieee
12437Increase IEEE-compliance of floating-point code.
12438At the moment, this is equivalent to @option{-fno-finite-math-only}.
12439When generating 16 bit SH opcodes, getting IEEE-conforming results for
12440comparisons of NANs / infinities incurs extra overhead in every
12441floating point comparison, therefore the default is set to
12442@option{-ffinite-math-only}.
12443
12444@item -misize
12445@opindex misize
12446Dump instruction size and location in the assembly code.
12447
12448@item -mpadstruct
12449@opindex mpadstruct
12450This option is deprecated. It pads structures to multiple of 4 bytes,
12451which is incompatible with the SH ABI@.
12452
12453@item -mspace
12454@opindex mspace
12455Optimize for space instead of speed. Implied by @option{-Os}.
12456
12457@item -mprefergot
12458@opindex mprefergot
12459When generating position-independent code, emit function calls using
12460the Global Offset Table instead of the Procedure Linkage Table.
12461
12462@item -musermode
12463@opindex musermode
12464Generate a library function call to invalidate instruction cache
12465entries, after fixing up a trampoline. This library function call
12466doesn't assume it can write to the whole memory address space. This
12467is the default when the target is @code{sh-*-linux*}.
12468
12469@item -multcost=@var{number}
12470@opindex multcost=@var{number}
12471Set the cost to assume for a multiply insn.
12472
12473@item -mdiv=@var{strategy}
12474@opindex mdiv=@var{strategy}
12475Set the division strategy to use for SHmedia code. @var{strategy} must be
12476one of: call, call2, fp, inv, inv:minlat, inv20u, inv20l, inv:call,
12477inv:call2, inv:fp .
12478"fp" performs the operation in floating point. This has a very high latency,
12479but needs only a few instructions, so it might be a good choice if
12480your code has enough easily exploitable ILP to allow the compiler to
12481schedule the floating point instructions together with other instructions.
12482Division by zero causes a floating point exception.
12483"inv" uses integer operations to calculate the inverse of the divisor,
12484and then multiplies the dividend with the inverse. This strategy allows
12485cse and hoisting of the inverse calculation. Division by zero calculates
12486an unspecified result, but does not trap.
12487"inv:minlat" is a variant of "inv" where if no cse / hoisting opportunities
12488have been found, or if the entire operation has been hoisted to the same
12489place, the last stages of the inverse calculation are intertwined with the
12490final multiply to reduce the overall latency, at the expense of using a few
12491more instructions, and thus offering fewer scheduling opportunities with
12492other code.
12493"call" calls a library function that usually implements the inv:minlat
12494strategy.
12495This gives high code density for m5-*media-nofpu compilations.
12496"call2" uses a different entry point of the same library function, where it
12497assumes that a pointer to a lookup table has already been set up, which
12498exposes the pointer load to cse / code hoisting optimizations.
12499"inv:call", "inv:call2" and "inv:fp" all use the "inv" algorithm for initial
12500code generation, but if the code stays unoptimized, revert to the "call",
12501"call2", or "fp" strategies, respectively. Note that the
12502potentially-trapping side effect of division by zero is carried by a
12503separate instruction, so it is possible that all the integer instructions
12504are hoisted out, but the marker for the side effect stays where it is.
12505A recombination to fp operations or a call is not possible in that case.
12506"inv20u" and "inv20l" are variants of the "inv:minlat" strategy. In the case
12507that the inverse calculation was nor separated from the multiply, they speed
12508up division where the dividend fits into 20 bits (plus sign where applicable),
12509by inserting a test to skip a number of operations in this case; this test
12510slows down the case of larger dividends. inv20u assumes the case of a such
12511a small dividend to be unlikely, and inv20l assumes it to be likely.
12512
12513@item -mdivsi3_libfunc=@var{name}
12514@opindex mdivsi3_libfunc=@var{name}
12515Set the name of the library function used for 32 bit signed division to
12516@var{name}. This only affect the name used in the call and inv:call
12517division strategies, and the compiler will still expect the same
12518sets of input/output/clobbered registers as if this option was not present.
12519
12520@item -madjust-unroll
12521@opindex madjust-unroll
12522Throttle unrolling to avoid thrashing target registers.
12523This option only has an effect if the gcc code base supports the
12524TARGET_ADJUST_UNROLL_MAX target hook.
12525
12526@item -mindexed-addressing
12527@opindex mindexed-addressing
12528Enable the use of the indexed addressing mode for SHmedia32/SHcompact.
12529This is only safe if the hardware and/or OS implement 32 bit wrap-around
12530semantics for the indexed addressing mode. The architecture allows the
12531implementation of processors with 64 bit MMU, which the OS could use to
12532get 32 bit addressing, but since no current hardware implementation supports
12533this or any other way to make the indexed addressing mode safe to use in
12534the 32 bit ABI, the default is -mno-indexed-addressing.
12535
12536@item -mgettrcost=@var{number}
12537@opindex mgettrcost=@var{number}
12538Set the cost assumed for the gettr instruction to @var{number}.
12539The default is 2 if @option{-mpt-fixed} is in effect, 100 otherwise.
12540
12541@item -mpt-fixed
12542@opindex mpt-fixed
12543Assume pt* instructions won't trap. This will generally generate better
12544scheduled code, but is unsafe on current hardware. The current architecture
12545definition says that ptabs and ptrel trap when the target anded with 3 is 3.
12546This has the unintentional effect of making it unsafe to schedule ptabs /
12547ptrel before a branch, or hoist it out of a loop. For example,
12548__do_global_ctors, a part of libgcc that runs constructors at program
12549startup, calls functions in a list which is delimited by -1. With the
12550-mpt-fixed option, the ptabs will be done before testing against -1.
12551That means that all the constructors will be run a bit quicker, but when
12552the loop comes to the end of the list, the program crashes because ptabs
12553loads -1 into a target register. Since this option is unsafe for any
12554hardware implementing the current architecture specification, the default
12555is -mno-pt-fixed. Unless the user specifies a specific cost with
12556@option{-mgettrcost}, -mno-pt-fixed also implies @option{-mgettrcost=100};
12557this deters register allocation using target registers for storing
12558ordinary integers.
12559
12560@item -minvalid-symbols
12561@opindex minvalid-symbols
12562Assume symbols might be invalid. Ordinary function symbols generated by
12563the compiler will always be valid to load with movi/shori/ptabs or
12564movi/shori/ptrel, but with assembler and/or linker tricks it is possible
12565to generate symbols that will cause ptabs / ptrel to trap.
12566This option is only meaningful when @option{-mno-pt-fixed} is in effect.
12567It will then prevent cross-basic-block cse, hoisting and most scheduling
12568of symbol loads. The default is @option{-mno-invalid-symbols}.
12569@end table
12570
12571@node SPARC Options
12572@subsection SPARC Options
12573@cindex SPARC options
12574
12575These @samp{-m} options are supported on the SPARC:
12576
12577@table @gcctabopt
12578@item -mno-app-regs
12579@itemx -mapp-regs
12580@opindex mno-app-regs
12581@opindex mapp-regs
12582Specify @option{-mapp-regs} to generate output using the global registers
125832 through 4, which the SPARC SVR4 ABI reserves for applications. This
12584is the default.
12585
12586To be fully SVR4 ABI compliant at the cost of some performance loss,
12587specify @option{-mno-app-regs}. You should compile libraries and system
12588software with this option.
12589
12590@item -mfpu
12591@itemx -mhard-float
12592@opindex mfpu
12593@opindex mhard-float
12594Generate output containing floating point instructions. This is the
12595default.
12596
12597@item -mno-fpu
12598@itemx -msoft-float
12599@opindex mno-fpu
12600@opindex msoft-float
12601Generate output containing library calls for floating point.
12602@strong{Warning:} the requisite libraries are not available for all SPARC
12603targets. Normally the facilities of the machine's usual C compiler are
12604used, but this cannot be done directly in cross-compilation. You must make
12605your own arrangements to provide suitable library functions for
12606cross-compilation. The embedded targets @samp{sparc-*-aout} and
12607@samp{sparclite-*-*} do provide software floating point support.
12608
12609@option{-msoft-float} changes the calling convention in the output file;
12610therefore, it is only useful if you compile @emph{all} of a program with
12611this option. In particular, you need to compile @file{libgcc.a}, the
12612library that comes with GCC, with @option{-msoft-float} in order for
12613this to work.
12614
12615@item -mhard-quad-float
12616@opindex mhard-quad-float
12617Generate output containing quad-word (long double) floating point
12618instructions.
12619
12620@item -msoft-quad-float
12621@opindex msoft-quad-float
12622Generate output containing library calls for quad-word (long double)
12623floating point instructions. The functions called are those specified
12624in the SPARC ABI@. This is the default.
12625
12626As of this writing, there are no SPARC implementations that have hardware
12627support for the quad-word floating point instructions. They all invoke
12628a trap handler for one of these instructions, and then the trap handler
12629emulates the effect of the instruction. Because of the trap handler overhead,
12630this is much slower than calling the ABI library routines. Thus the
12631@option{-msoft-quad-float} option is the default.
12632
12633@item -mno-unaligned-doubles
12634@itemx -munaligned-doubles
12635@opindex mno-unaligned-doubles
12636@opindex munaligned-doubles
12637Assume that doubles have 8 byte alignment. This is the default.
12638
12639With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
12640alignment only if they are contained in another type, or if they have an
12641absolute address. Otherwise, it assumes they have 4 byte alignment.
12642Specifying this option avoids some rare compatibility problems with code
12643generated by other compilers. It is not the default because it results
12644in a performance loss, especially for floating point code.
12645
12646@item -mno-faster-structs
12647@itemx -mfaster-structs
12648@opindex mno-faster-structs
12649@opindex mfaster-structs
12650With @option{-mfaster-structs}, the compiler assumes that structures
12651should have 8 byte alignment. This enables the use of pairs of
12652@code{ldd} and @code{std} instructions for copies in structure
12653assignment, in place of twice as many @code{ld} and @code{st} pairs.
12654However, the use of this changed alignment directly violates the SPARC
12655ABI@. Thus, it's intended only for use on targets where the developer
12656acknowledges that their resulting code will not be directly in line with
12657the rules of the ABI@.
12658
12659@item -mimpure-text
12660@opindex mimpure-text
12661@option{-mimpure-text}, used in addition to @option{-shared}, tells
12662the compiler to not pass @option{-z text} to the linker when linking a
12663shared object. Using this option, you can link position-dependent
12664code into a shared object.
12665
12666@option{-mimpure-text} suppresses the ``relocations remain against
12667allocatable but non-writable sections'' linker error message.
12668However, the necessary relocations will trigger copy-on-write, and the
12669shared object is not actually shared across processes. Instead of
12670using @option{-mimpure-text}, you should compile all source code with
12671@option{-fpic} or @option{-fPIC}.
12672
12673This option is only available on SunOS and Solaris.
12674
12675@item -mcpu=@var{cpu_type}
12676@opindex mcpu
12677Set the instruction set, register set, and instruction scheduling parameters
12678for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
12679@samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
12680@samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x},
12681@samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc},
12682@samp{ultrasparc3}, and @samp{niagara}.
12683
12684Default instruction scheduling parameters are used for values that select
12685an architecture and not an implementation. These are @samp{v7}, @samp{v8},
12686@samp{sparclite}, @samp{sparclet}, @samp{v9}.
12687
12688Here is a list of each supported architecture and their supported
12689implementations.
12690
12691@smallexample
12692 v7: cypress
12693 v8: supersparc, hypersparc
12694 sparclite: f930, f934, sparclite86x
12695 sparclet: tsc701
12696 v9: ultrasparc, ultrasparc3, niagara
12697@end smallexample
12698
12699By default (unless configured otherwise), GCC generates code for the V7
12700variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler
12701additionally optimizes it for the Cypress CY7C602 chip, as used in the
12702SPARCStation/SPARCServer 3xx series. This is also appropriate for the older
12703SPARCStation 1, 2, IPX etc.
12704
12705With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
12706architecture. The only difference from V7 code is that the compiler emits
12707the integer multiply and integer divide instructions which exist in SPARC-V8
12708but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally
12709optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
127102000 series.
12711
12712With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
12713the SPARC architecture. This adds the integer multiply, integer divide step
12714and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
12715With @option{-mcpu=f930}, the compiler additionally optimizes it for the
12716Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@. With
12717@option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
12718MB86934 chip, which is the more recent SPARClite with FPU@.
12719
12720With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
12721the SPARC architecture. This adds the integer multiply, multiply/accumulate,
12722integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
12723but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally
12724optimizes it for the TEMIC SPARClet chip.
12725
12726With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
12727architecture. This adds 64-bit integer and floating-point move instructions,
127283 additional floating-point condition code registers and conditional move
12729instructions. With @option{-mcpu=ultrasparc}, the compiler additionally
12730optimizes it for the Sun UltraSPARC I/II/IIi chips. With
12731@option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
12732Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips. With
12733@option{-mcpu=niagara}, the compiler additionally optimizes it for
12734Sun UltraSPARC T1 chips.
12735
12736@item -mtune=@var{cpu_type}
12737@opindex mtune
12738Set the instruction scheduling parameters for machine type
12739@var{cpu_type}, but do not set the instruction set or register set that the
12740option @option{-mcpu=@var{cpu_type}} would.
12741
12742The same values for @option{-mcpu=@var{cpu_type}} can be used for
12743@option{-mtune=@var{cpu_type}}, but the only useful values are those
12744that select a particular cpu implementation. Those are @samp{cypress},
12745@samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
12746@samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc},
12747@samp{ultrasparc3}, and @samp{niagara}.
12748
12749@item -mv8plus
12750@itemx -mno-v8plus
12751@opindex mv8plus
12752@opindex mno-v8plus
12753With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@. The
12754difference from the V8 ABI is that the global and out registers are
12755considered 64-bit wide. This is enabled by default on Solaris in 32-bit
12756mode for all SPARC-V9 processors.
12757
12758@item -mvis
12759@itemx -mno-vis
12760@opindex mvis
12761@opindex mno-vis
12762With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
12763Visual Instruction Set extensions. The default is @option{-mno-vis}.
12764@end table
12765
12766These @samp{-m} options are supported in addition to the above
12767on SPARC-V9 processors in 64-bit environments:
12768
12769@table @gcctabopt
12770@item -mlittle-endian
12771@opindex mlittle-endian
12772Generate code for a processor running in little-endian mode. It is only
12773available for a few configurations and most notably not on Solaris and Linux.
12774
12775@item -m32
12776@itemx -m64
12777@opindex m32
12778@opindex m64
12779Generate code for a 32-bit or 64-bit environment.
12780The 32-bit environment sets int, long and pointer to 32 bits.
12781The 64-bit environment sets int to 32 bits and long and pointer
12782to 64 bits.
12783
12784@item -mcmodel=medlow
12785@opindex mcmodel=medlow
12786Generate code for the Medium/Low code model: 64-bit addresses, programs
12787must be linked in the low 32 bits of memory. Programs can be statically
12788or dynamically linked.
12789
12790@item -mcmodel=medmid
12791@opindex mcmodel=medmid
12792Generate code for the Medium/Middle code model: 64-bit addresses, programs
12793must be linked in the low 44 bits of memory, the text and data segments must
12794be less than 2GB in size and the data segment must be located within 2GB of
12795the text segment.
12796
12797@item -mcmodel=medany
12798@opindex mcmodel=medany
12799Generate code for the Medium/Anywhere code model: 64-bit addresses, programs
12800may be linked anywhere in memory, the text and data segments must be less
12801than 2GB in size and the data segment must be located within 2GB of the
12802text segment.
12803
12804@item -mcmodel=embmedany
12805@opindex mcmodel=embmedany
12806Generate code for the Medium/Anywhere code model for embedded systems:
1280764-bit addresses, the text and data segments must be less than 2GB in
12808size, both starting anywhere in memory (determined at link time). The
12809global register %g4 points to the base of the data segment. Programs
12810are statically linked and PIC is not supported.
12811
12812@item -mstack-bias
12813@itemx -mno-stack-bias
12814@opindex mstack-bias
12815@opindex mno-stack-bias
12816With @option{-mstack-bias}, GCC assumes that the stack pointer, and
12817frame pointer if present, are offset by @minus{}2047 which must be added back
12818when making stack frame references. This is the default in 64-bit mode.
12819Otherwise, assume no such offset is present.
12820@end table
12821
12822These switches are supported in addition to the above on Solaris:
12823
12824@table @gcctabopt
12825@item -threads
12826@opindex threads
12827Add support for multithreading using the Solaris threads library. This
12828option sets flags for both the preprocessor and linker. This option does
12829not affect the thread safety of object code produced by the compiler or
12830that of libraries supplied with it.
12831
12832@item -pthreads
12833@opindex pthreads
12834Add support for multithreading using the POSIX threads library. This
12835option sets flags for both the preprocessor and linker. This option does
12836not affect the thread safety of object code produced by the compiler or
12837that of libraries supplied with it.
12838
12839@item -pthread
12840@opindex pthread
12841This is a synonym for @option{-pthreads}.
12842@end table
12843
12844@node System V Options
12845@subsection Options for System V
12846
12847These additional options are available on System V Release 4 for
12848compatibility with other compilers on those systems:
12849
12850@table @gcctabopt
12851@item -G
12852@opindex G
12853Create a shared object.
12854It is recommended that @option{-symbolic} or @option{-shared} be used instead.
12855
12856@item -Qy
12857@opindex Qy
12858Identify the versions of each tool used by the compiler, in a
12859@code{.ident} assembler directive in the output.
12860
12861@item -Qn
12862@opindex Qn
12863Refrain from adding @code{.ident} directives to the output file (this is
12864the default).
12865
12866@item -YP,@var{dirs}
12867@opindex YP
12868Search the directories @var{dirs}, and no others, for libraries
12869specified with @option{-l}.
12870
12871@item -Ym,@var{dir}
12872@opindex Ym
12873Look in the directory @var{dir} to find the M4 preprocessor.
12874The assembler uses this option.
12875@c This is supposed to go with a -Yd for predefined M4 macro files, but
12876@c the generic assembler that comes with Solaris takes just -Ym.
12877@end table
12878
12879@node TMS320C3x/C4x Options
12880@subsection TMS320C3x/C4x Options
12881@cindex TMS320C3x/C4x Options
12882
12883These @samp{-m} options are defined for TMS320C3x/C4x implementations:
12884
12885@table @gcctabopt
12886
12887@item -mcpu=@var{cpu_type}
12888@opindex mcpu
12889Set the instruction set, register set, and instruction scheduling
12890parameters for machine type @var{cpu_type}. Supported values for
12891@var{cpu_type} are @samp{c30}, @samp{c31}, @samp{c32}, @samp{c40}, and
12892@samp{c44}. The default is @samp{c40} to generate code for the
12893TMS320C40.
12894
12895@item -mbig-memory
12896@itemx -mbig
12897@itemx -msmall-memory
12898@itemx -msmall
12899@opindex mbig-memory
12900@opindex mbig
12901@opindex msmall-memory
12902@opindex msmall
12903Generates code for the big or small memory model. The small memory
12904model assumed that all data fits into one 64K word page. At run-time
12905the data page (DP) register must be set to point to the 64K page
12906containing the .bss and .data program sections. The big memory model is
12907the default and requires reloading of the DP register for every direct
12908memory access.
12909
12910@item -mbk
12911@itemx -mno-bk
12912@opindex mbk
12913@opindex mno-bk
12914Allow (disallow) allocation of general integer operands into the block
12915count register BK@.
12916
12917@item -mdb
12918@itemx -mno-db
12919@opindex mdb
12920@opindex mno-db
12921Enable (disable) generation of code using decrement and branch,
12922DBcond(D), instructions. This is enabled by default for the C4x. To be
12923on the safe side, this is disabled for the C3x, since the maximum
12924iteration count on the C3x is @math{2^{23} + 1} (but who iterates loops more than
12925@math{2^{23}} times on the C3x?). Note that GCC will try to reverse a loop so
12926that it can utilize the decrement and branch instruction, but will give
12927up if there is more than one memory reference in the loop. Thus a loop
12928where the loop counter is decremented can generate slightly more
12929efficient code, in cases where the RPTB instruction cannot be utilized.
12930
12931@item -mdp-isr-reload
12932@itemx -mparanoid
12933@opindex mdp-isr-reload
12934@opindex mparanoid
12935Force the DP register to be saved on entry to an interrupt service
12936routine (ISR), reloaded to point to the data section, and restored on
12937exit from the ISR@. This should not be required unless someone has
12938violated the small memory model by modifying the DP register, say within
12939an object library.
12940
12941@item -mmpyi
12942@itemx -mno-mpyi
12943@opindex mmpyi
12944@opindex mno-mpyi
12945For the C3x use the 24-bit MPYI instruction for integer multiplies
12946instead of a library call to guarantee 32-bit results. Note that if one
12947of the operands is a constant, then the multiplication will be performed
12948using shifts and adds. If the @option{-mmpyi} option is not specified for the C3x,
12949then squaring operations are performed inline instead of a library call.
12950
12951@item -mfast-fix
12952@itemx -mno-fast-fix
12953@opindex mfast-fix
12954@opindex mno-fast-fix
12955The C3x/C4x FIX instruction to convert a floating point value to an
12956integer value chooses the nearest integer less than or equal to the
12957floating point value rather than to the nearest integer. Thus if the
12958floating point number is negative, the result will be incorrectly
12959truncated an additional code is necessary to detect and correct this
12960case. This option can be used to disable generation of the additional
12961code required to correct the result.
12962
12963@item -mrptb
12964@itemx -mno-rptb
12965@opindex mrptb
12966@opindex mno-rptb
12967Enable (disable) generation of repeat block sequences using the RPTB
12968instruction for zero overhead looping. The RPTB construct is only used
12969for innermost loops that do not call functions or jump across the loop
12970boundaries. There is no advantage having nested RPTB loops due to the
12971overhead required to save and restore the RC, RS, and RE registers.
12972This is enabled by default with @option{-O2}.
12973
12974@item -mrpts=@var{count}
12975@itemx -mno-rpts
12976@opindex mrpts
12977@opindex mno-rpts
12978Enable (disable) the use of the single instruction repeat instruction
12979RPTS@. If a repeat block contains a single instruction, and the loop
12980count can be guaranteed to be less than the value @var{count}, GCC will
12981emit a RPTS instruction instead of a RPTB@. If no value is specified,
12982then a RPTS will be emitted even if the loop count cannot be determined
12983at compile time. Note that the repeated instruction following RPTS does
12984not have to be reloaded from memory each iteration, thus freeing up the
12985CPU buses for operands. However, since interrupts are blocked by this
12986instruction, it is disabled by default.
12987
12988@item -mloop-unsigned
12989@itemx -mno-loop-unsigned
12990@opindex mloop-unsigned
12991@opindex mno-loop-unsigned
12992The maximum iteration count when using RPTS and RPTB (and DB on the C40)
12993is @math{2^{31} + 1} since these instructions test if the iteration count is
12994negative to terminate the loop. If the iteration count is unsigned
12995there is a possibility than the @math{2^{31} + 1} maximum iteration count may be
12996exceeded. This switch allows an unsigned iteration count.
12997
12998@item -mti
12999@opindex mti
13000Try to emit an assembler syntax that the TI assembler (asm30) is happy
13001with. This also enforces compatibility with the API employed by the TI
13002C3x C compiler. For example, long doubles are passed as structures
13003rather than in floating point registers.
13004
13005@item -mregparm
13006@itemx -mmemparm
13007@opindex mregparm
13008@opindex mmemparm
13009Generate code that uses registers (stack) for passing arguments to functions.
13010By default, arguments are passed in registers where possible rather
13011than by pushing arguments on to the stack.
13012
13013@item -mparallel-insns
13014@itemx -mno-parallel-insns
13015@opindex mparallel-insns
13016@opindex mno-parallel-insns
13017Allow the generation of parallel instructions. This is enabled by
13018default with @option{-O2}.
13019
13020@item -mparallel-mpy
13021@itemx -mno-parallel-mpy
13022@opindex mparallel-mpy
13023@opindex mno-parallel-mpy
13024Allow the generation of MPY||ADD and MPY||SUB parallel instructions,
13025provided @option{-mparallel-insns} is also specified. These instructions have
13026tight register constraints which can pessimize the code generation
13027of large functions.
13028
13029@end table
13030
13031@node V850 Options
13032@subsection V850 Options
13033@cindex V850 Options
13034
13035These @samp{-m} options are defined for V850 implementations:
13036
13037@table @gcctabopt
13038@item -mlong-calls
13039@itemx -mno-long-calls
13040@opindex mlong-calls
13041@opindex mno-long-calls
13042Treat all calls as being far away (near). If calls are assumed to be
13043far away, the compiler will always load the functions address up into a
13044register, and call indirect through the pointer.
13045
13046@item -mno-ep
13047@itemx -mep
13048@opindex mno-ep
13049@opindex mep
13050Do not optimize (do optimize) basic blocks that use the same index
13051pointer 4 or more times to copy pointer into the @code{ep} register, and
13052use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
13053option is on by default if you optimize.
13054
13055@item -mno-prolog-function
13056@itemx -mprolog-function
13057@opindex mno-prolog-function
13058@opindex mprolog-function
13059Do not use (do use) external functions to save and restore registers
13060at the prologue and epilogue of a function. The external functions
13061are slower, but use less code space if more than one function saves
13062the same number of registers. The @option{-mprolog-function} option
13063is on by default if you optimize.
13064
13065@item -mspace
13066@opindex mspace
13067Try to make the code as small as possible. At present, this just turns
13068on the @option{-mep} and @option{-mprolog-function} options.
13069
13070@item -mtda=@var{n}
13071@opindex mtda
13072Put static or global variables whose size is @var{n} bytes or less into
13073the tiny data area that register @code{ep} points to. The tiny data
13074area can hold up to 256 bytes in total (128 bytes for byte references).
13075
13076@item -msda=@var{n}
13077@opindex msda
13078Put static or global variables whose size is @var{n} bytes or less into
13079the small data area that register @code{gp} points to. The small data
13080area can hold up to 64 kilobytes.
13081
13082@item -mzda=@var{n}
13083@opindex mzda
13084Put static or global variables whose size is @var{n} bytes or less into
13085the first 32 kilobytes of memory.
13086
13087@item -mv850
13088@opindex mv850
13089Specify that the target processor is the V850.
13090
13091@item -mbig-switch
13092@opindex mbig-switch
13093Generate code suitable for big switch tables. Use this option only if
13094the assembler/linker complain about out of range branches within a switch
13095table.
13096
13097@item -mapp-regs
13098@opindex mapp-regs
13099This option will cause r2 and r5 to be used in the code generated by
13100the compiler. This setting is the default.
13101
13102@item -mno-app-regs
13103@opindex mno-app-regs
13104This option will cause r2 and r5 to be treated as fixed registers.
13105
13106@item -mv850e1
13107@opindex mv850e1
13108Specify that the target processor is the V850E1. The preprocessor
13109constants @samp{__v850e1__} and @samp{__v850e__} will be defined if
13110this option is used.
13111
13112@item -mv850e
13113@opindex mv850e
13114Specify that the target processor is the V850E@. The preprocessor
13115constant @samp{__v850e__} will be defined if this option is used.
13116
13117If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
13118are defined then a default target processor will be chosen and the
13119relevant @samp{__v850*__} preprocessor constant will be defined.
13120
13121The preprocessor constants @samp{__v850} and @samp{__v851__} are always
13122defined, regardless of which processor variant is the target.
13123
13124@item -mdisable-callt
13125@opindex mdisable-callt
13126This option will suppress generation of the CALLT instruction for the
13127v850e and v850e1 flavors of the v850 architecture. The default is
13128@option{-mno-disable-callt} which allows the CALLT instruction to be used.
13129
13130@end table
13131
13132@node VAX Options
13133@subsection VAX Options
13134@cindex VAX options
13135
13136These @samp{-m} options are defined for the VAX:
13137
13138@table @gcctabopt
13139@item -munix
13140@opindex munix
13141Do not output certain jump instructions (@code{aobleq} and so on)
13142that the Unix assembler for the VAX cannot handle across long
13143ranges.
13144
13145@item -mgnu
13146@opindex mgnu
13147Do output those jump instructions, on the assumption that you
13148will assemble with the GNU assembler.
13149
13150@item -mg
13151@opindex mg
13152Output code for g-format floating point numbers instead of d-format.
13153@end table
13154
13155@node x86-64 Options
13156@subsection x86-64 Options
13157@cindex x86-64 options
13158
13159These are listed under @xref{i386 and x86-64 Options}.
13160
13161@node Xstormy16 Options
13162@subsection Xstormy16 Options
13163@cindex Xstormy16 Options
13164
13165These options are defined for Xstormy16:
13166
13167@table @gcctabopt
13168@item -msim
13169@opindex msim
13170Choose startup files and linker script suitable for the simulator.
13171@end table
13172
13173@node Xtensa Options
13174@subsection Xtensa Options
13175@cindex Xtensa Options
13176
13177These options are supported for Xtensa targets:
13178
13179@table @gcctabopt
13180@item -mconst16
13181@itemx -mno-const16
13182@opindex mconst16
13183@opindex mno-const16
13184Enable or disable use of @code{CONST16} instructions for loading
13185constant values. The @code{CONST16} instruction is currently not a
13186standard option from Tensilica. When enabled, @code{CONST16}
13187instructions are always used in place of the standard @code{L32R}
13188instructions. The use of @code{CONST16} is enabled by default only if
13189the @code{L32R} instruction is not available.
13190
13191@item -mfused-madd
13192@itemx -mno-fused-madd
13193@opindex mfused-madd
13194@opindex mno-fused-madd
13195Enable or disable use of fused multiply/add and multiply/subtract
13196instructions in the floating-point option. This has no effect if the
13197floating-point option is not also enabled. Disabling fused multiply/add
13198and multiply/subtract instructions forces the compiler to use separate
13199instructions for the multiply and add/subtract operations. This may be
13200desirable in some cases where strict IEEE 754-compliant results are
13201required: the fused multiply add/subtract instructions do not round the
13202intermediate result, thereby producing results with @emph{more} bits of
13203precision than specified by the IEEE standard. Disabling fused multiply
13204add/subtract instructions also ensures that the program output is not
13205sensitive to the compiler's ability to combine multiply and add/subtract
13206operations.
13207
13208@item -mtext-section-literals
13209@itemx -mno-text-section-literals
13210@opindex mtext-section-literals
13211@opindex mno-text-section-literals
13212Control the treatment of literal pools. The default is
13213@option{-mno-text-section-literals}, which places literals in a separate
13214section in the output file. This allows the literal pool to be placed
13215in a data RAM/ROM, and it also allows the linker to combine literal
13216pools from separate object files to remove redundant literals and
13217improve code size. With @option{-mtext-section-literals}, the literals
13218are interspersed in the text section in order to keep them as close as
13219possible to their references. This may be necessary for large assembly
13220files.
13221
13222@item -mtarget-align
13223@itemx -mno-target-align
13224@opindex mtarget-align
13225@opindex mno-target-align
13226When this option is enabled, GCC instructs the assembler to
13227automatically align instructions to reduce branch penalties at the
13228expense of some code density. The assembler attempts to widen density
13229instructions to align branch targets and the instructions following call
13230instructions. If there are not enough preceding safe density
13231instructions to align a target, no widening will be performed. The
13232default is @option{-mtarget-align}. These options do not affect the
13233treatment of auto-aligned instructions like @code{LOOP}, which the
13234assembler will always align, either by widening density instructions or
13235by inserting no-op instructions.
13236
13237@item -mlongcalls
13238@itemx -mno-longcalls
13239@opindex mlongcalls
13240@opindex mno-longcalls
13241When this option is enabled, GCC instructs the assembler to translate
13242direct calls to indirect calls unless it can determine that the target
13243of a direct call is in the range allowed by the call instruction. This
13244translation typically occurs for calls to functions in other source
13245files. Specifically, the assembler translates a direct @code{CALL}
13246instruction into an @code{L32R} followed by a @code{CALLX} instruction.
13247The default is @option{-mno-longcalls}. This option should be used in
13248programs where the call target can potentially be out of range. This
13249option is implemented in the assembler, not the compiler, so the
13250assembly code generated by GCC will still show direct call
13251instructions---look at the disassembled object code to see the actual
13252instructions. Note that the assembler will use an indirect call for
13253every cross-file call, not just those that really will be out of range.
13254@end table
13255
13256@node zSeries Options
13257@subsection zSeries Options
13258@cindex zSeries options
13259
13260These are listed under @xref{S/390 and zSeries Options}.
13261
13262@node Code Gen Options
13263@section Options for Code Generation Conventions
13264@cindex code generation conventions
13265@cindex options, code generation
13266@cindex run-time options
13267
13268These machine-independent options control the interface conventions
13269used in code generation.
13270
13271Most of them have both positive and negative forms; the negative form
13272of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
13273one of the forms is listed---the one which is not the default. You
13274can figure out the other form by either removing @samp{no-} or adding
13275it.
13276
13277@table @gcctabopt
13278@item -fbounds-check
13279@opindex fbounds-check
13280For front-ends that support it, generate additional code to check that
13281indices used to access arrays are within the declared range. This is
13282currently only supported by the Java and Fortran front-ends, where
13283this option defaults to true and false respectively.
13284
13285@item -ftrapv
13286@opindex ftrapv
13287This option generates traps for signed overflow on addition, subtraction,
13288multiplication operations.
13289
13290@item -fwrapv
13291@opindex fwrapv
13292This option instructs the compiler to assume that signed arithmetic
13293overflow of addition, subtraction and multiplication wraps around
13294using twos-complement representation. This flag enables some optimizations
13295and disables others. This option is enabled by default for the Java
13296front-end, as required by the Java language specification.
13297
13298@item -fexceptions
13299@opindex fexceptions
13300Enable exception handling. Generates extra code needed to propagate
13301exceptions. For some targets, this implies GCC will generate frame
13302unwind information for all functions, which can produce significant data
13303size overhead, although it does not affect execution. If you do not
13304specify this option, GCC will enable it by default for languages like
13305C++ which normally require exception handling, and disable it for
13306languages like C that do not normally require it. However, you may need
13307to enable this option when compiling C code that needs to interoperate
13308properly with exception handlers written in C++. You may also wish to
13309disable this option if you are compiling older C++ programs that don't
13310use exception handling.
13311
13312@item -fnon-call-exceptions
13313@opindex fnon-call-exceptions
13314Generate code that allows trapping instructions to throw exceptions.
13315Note that this requires platform-specific runtime support that does
13316not exist everywhere. Moreover, it only allows @emph{trapping}
13317instructions to throw exceptions, i.e.@: memory references or floating
13318point instructions. It does not allow exceptions to be thrown from
13319arbitrary signal handlers such as @code{SIGALRM}.
13320
13321@item -funwind-tables
13322@opindex funwind-tables
13323Similar to @option{-fexceptions}, except that it will just generate any needed
13324static data, but will not affect the generated code in any other way.
13325You will normally not enable this option; instead, a language processor
13326that needs this handling would enable it on your behalf.
13327
13328@item -fasynchronous-unwind-tables
13329@opindex fasynchronous-unwind-tables
13330Generate unwind table in dwarf2 format, if supported by target machine. The
13331table is exact at each instruction boundary, so it can be used for stack
13332unwinding from asynchronous events (such as debugger or garbage collector).
13333
13334@item -fpcc-struct-return
13335@opindex fpcc-struct-return
13336Return ``short'' @code{struct} and @code{union} values in memory like
13337longer ones, rather than in registers. This convention is less
13338efficient, but it has the advantage of allowing intercallability between
13339GCC-compiled files and files compiled with other compilers, particularly
13340the Portable C Compiler (pcc).
13341
13342The precise convention for returning structures in memory depends
13343on the target configuration macros.
13344
13345Short structures and unions are those whose size and alignment match
13346that of some integer type.
13347
13348@strong{Warning:} code compiled with the @option{-fpcc-struct-return}
13349switch is not binary compatible with code compiled with the
13350@option{-freg-struct-return} switch.
13351Use it to conform to a non-default application binary interface.
13352
13353@item -freg-struct-return
13354@opindex freg-struct-return
13355Return @code{struct} and @code{union} values in registers when possible.
13356This is more efficient for small structures than
13357@option{-fpcc-struct-return}.
13358
13359If you specify neither @option{-fpcc-struct-return} nor
13360@option{-freg-struct-return}, GCC defaults to whichever convention is
13361standard for the target. If there is no standard convention, GCC
13362defaults to @option{-fpcc-struct-return}, except on targets where GCC is
13363the principal compiler. In those cases, we can choose the standard, and
13364we chose the more efficient register return alternative.
13365
13366@strong{Warning:} code compiled with the @option{-freg-struct-return}
13367switch is not binary compatible with code compiled with the
13368@option{-fpcc-struct-return} switch.
13369Use it to conform to a non-default application binary interface.
13370
13371@item -fshort-enums
13372@opindex fshort-enums
13373Allocate to an @code{enum} type only as many bytes as it needs for the
13374declared range of possible values. Specifically, the @code{enum} type
13375will be equivalent to the smallest integer type which has enough room.
13376
13377@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
13378code that is not binary compatible with code generated without that switch.
13379Use it to conform to a non-default application binary interface.
13380
13381@item -fshort-double
13382@opindex fshort-double
13383Use the same size for @code{double} as for @code{float}.
13384
13385@strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
13386code that is not binary compatible with code generated without that switch.
13387Use it to conform to a non-default application binary interface.
13388
13389@item -fshort-wchar
13390@opindex fshort-wchar
13391Override the underlying type for @samp{wchar_t} to be @samp{short
13392unsigned int} instead of the default for the target. This option is
13393useful for building programs to run under WINE@.
13394
13395@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
13396code that is not binary compatible with code generated without that switch.
13397Use it to conform to a non-default application binary interface.
13398
13399@item -fno-common
13400@opindex fno-common
13401In C, allocate even uninitialized global variables in the data section of the
13402object file, rather than generating them as common blocks. This has the
13403effect that if the same variable is declared (without @code{extern}) in
13404two different compilations, you will get an error when you link them.
13405The only reason this might be useful is if you wish to verify that the
13406program will work on other systems which always work this way.
13407
13408@item -fno-ident
13409@opindex fno-ident
13410Ignore the @samp{#ident} directive.
13411
13412@item -finhibit-size-directive
13413@opindex finhibit-size-directive
13414Don't output a @code{.size} assembler directive, or anything else that
13415would cause trouble if the function is split in the middle, and the
13416two halves are placed at locations far apart in memory. This option is
13417used when compiling @file{crtstuff.c}; you should not need to use it
13418for anything else.
13419
13420@item -fverbose-asm
13421@opindex fverbose-asm
13422Put extra commentary information in the generated assembly code to
13423make it more readable. This option is generally only of use to those
13424who actually need to read the generated assembly code (perhaps while
13425debugging the compiler itself).
13426
13427@option{-fno-verbose-asm}, the default, causes the
13428extra information to be omitted and is useful when comparing two assembler
13429files.
13430
13431@item -fpic
13432@opindex fpic
13433@cindex global offset table
13434@cindex PIC
13435Generate position-independent code (PIC) suitable for use in a shared
13436library, if supported for the target machine. Such code accesses all
13437constant addresses through a global offset table (GOT)@. The dynamic
13438loader resolves the GOT entries when the program starts (the dynamic
13439loader is not part of GCC; it is part of the operating system). If
13440the GOT size for the linked executable exceeds a machine-specific
13441maximum size, you get an error message from the linker indicating that
13442@option{-fpic} does not work; in that case, recompile with @option{-fPIC}
13443instead. (These maximums are 8k on the SPARC and 32k
13444on the m68k and RS/6000. The 386 has no such limit.)
13445
13446Position-independent code requires special support, and therefore works
13447only on certain machines. For the 386, GCC supports PIC for System V
13448but not for the Sun 386i. Code generated for the IBM RS/6000 is always
13449position-independent.
13450
13451When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13452are defined to 1.
13453
13454@item -fPIC
13455@opindex fPIC
13456If supported for the target machine, emit position-independent code,
13457suitable for dynamic linking and avoiding any limit on the size of the
13458global offset table. This option makes a difference on the m68k,
13459PowerPC and SPARC@.
13460
13461Position-independent code requires special support, and therefore works
13462only on certain machines.
13463
13464When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13465are defined to 2.
13466
13467@item -fpie
13468@itemx -fPIE
13469@opindex fpie
13470@opindex fPIE
13471These options are similar to @option{-fpic} and @option{-fPIC}, but
13472generated position independent code can be only linked into executables.
13473Usually these options are used when @option{-pie} GCC option will be
13474used during linking.
13475
13476@item -fno-jump-tables
13477@opindex fno-jump-tables
13478Do not use jump tables for switch statements even where it would be
13479more efficient than other code generation strategies. This option is
13480of use in conjunction with @option{-fpic} or @option{-fPIC} for
13481building code which forms part of a dynamic linker and cannot
13482reference the address of a jump table. On some targets, jump tables
13483do not require a GOT and this option is not needed.
13484
13485@item -ffixed-@var{reg}
13486@opindex ffixed
13487Treat the register named @var{reg} as a fixed register; generated code
13488should never refer to it (except perhaps as a stack pointer, frame
13489pointer or in some other fixed role).
13490
13491@var{reg} must be the name of a register. The register names accepted
13492are machine-specific and are defined in the @code{REGISTER_NAMES}
13493macro in the machine description macro file.
13494
13495This flag does not have a negative form, because it specifies a
13496three-way choice.
13497
13498@item -fcall-used-@var{reg}
13499@opindex fcall-used
13500Treat the register named @var{reg} as an allocable register that is
13501clobbered by function calls. It may be allocated for temporaries or
13502variables that do not live across a call. Functions compiled this way
13503will not save and restore the register @var{reg}.
13504
13505It is an error to used this flag with the frame pointer or stack pointer.
13506Use of this flag for other registers that have fixed pervasive roles in
13507the machine's execution model will produce disastrous results.
13508
13509This flag does not have a negative form, because it specifies a
13510three-way choice.
13511
13512@item -fcall-saved-@var{reg}
13513@opindex fcall-saved
13514Treat the register named @var{reg} as an allocable register saved by
13515functions. It may be allocated even for temporaries or variables that
13516live across a call. Functions compiled this way will save and restore
13517the register @var{reg} if they use it.
13518
13519It is an error to used this flag with the frame pointer or stack pointer.
13520Use of this flag for other registers that have fixed pervasive roles in
13521the machine's execution model will produce disastrous results.
13522
13523A different sort of disaster will result from the use of this flag for
13524a register in which function values may be returned.
13525
13526This flag does not have a negative form, because it specifies a
13527three-way choice.
13528
13529@item -fpack-struct[=@var{n}]
13530@opindex fpack-struct
13531Without a value specified, pack all structure members together without
13532holes. When a value is specified (which must be a small power of two), pack
13533structure members according to this value, representing the maximum
13534alignment (that is, objects with default alignment requirements larger than
13535this will be output potentially unaligned at the next fitting location.
13536
13537@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
13538code that is not binary compatible with code generated without that switch.
13539Additionally, it makes the code suboptimal.
13540Use it to conform to a non-default application binary interface.
13541
13542@item -finstrument-functions
13543@opindex finstrument-functions
13544Generate instrumentation calls for entry and exit to functions. Just
13545after function entry and just before function exit, the following
13546profiling functions will be called with the address of the current
13547function and its call site. (On some platforms,
13548@code{__builtin_return_address} does not work beyond the current
13549function, so the call site information may not be available to the
13550profiling functions otherwise.)
13551
13552@smallexample
13553void __cyg_profile_func_enter (void *this_fn,
13554 void *call_site);
13555void __cyg_profile_func_exit (void *this_fn,
13556 void *call_site);
13557@end smallexample
13558
13559The first argument is the address of the start of the current function,
13560which may be looked up exactly in the symbol table.
13561
13562This instrumentation is also done for functions expanded inline in other
13563functions. The profiling calls will indicate where, conceptually, the
13564inline function is entered and exited. This means that addressable
13565versions of such functions must be available. If all your uses of a
13566function are expanded inline, this may mean an additional expansion of
13567code size. If you use @samp{extern inline} in your C code, an
13568addressable version of such functions must be provided. (This is
13569normally the case anyways, but if you get lucky and the optimizer always
13570expands the functions inline, you might have gotten away without
13571providing static copies.)
13572
13573A function may be given the attribute @code{no_instrument_function}, in
13574which case this instrumentation will not be done. This can be used, for
13575example, for the profiling functions listed above, high-priority
13576interrupt routines, and any functions from which the profiling functions
13577cannot safely be called (perhaps signal handlers, if the profiling
13578routines generate output or allocate memory).
13579
13580@item -fstack-check
13581@opindex fstack-check
13582Generate code to verify that you do not go beyond the boundary of the
13583stack. You should specify this flag if you are running in an
13584environment with multiple threads, but only rarely need to specify it in
13585a single-threaded environment since stack overflow is automatically
13586detected on nearly all systems if there is only one stack.
13587
13588Note that this switch does not actually cause checking to be done; the
13589operating system must do that. The switch causes generation of code
13590to ensure that the operating system sees the stack being extended.
13591
13592@item -fstack-limit-register=@var{reg}
13593@itemx -fstack-limit-symbol=@var{sym}
13594@itemx -fno-stack-limit
13595@opindex fstack-limit-register
13596@opindex fstack-limit-symbol
13597@opindex fno-stack-limit
13598Generate code to ensure that the stack does not grow beyond a certain value,
13599either the value of a register or the address of a symbol. If the stack
13600would grow beyond the value, a signal is raised. For most targets,
13601the signal is raised before the stack overruns the boundary, so
13602it is possible to catch the signal without taking special precautions.
13603
13604For instance, if the stack starts at absolute address @samp{0x80000000}
13605and grows downwards, you can use the flags
13606@option{-fstack-limit-symbol=__stack_limit} and
13607@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
13608of 128KB@. Note that this may only work with the GNU linker.
13609
13610@cindex aliasing of parameters
13611@cindex parameters, aliased
13612@item -fargument-alias
13613@itemx -fargument-noalias
13614@itemx -fargument-noalias-global
13615@itemx -fargument-noalias-anything
13616@opindex fargument-alias
13617@opindex fargument-noalias
13618@opindex fargument-noalias-global
13619@opindex fargument-noalias-anything
13620Specify the possible relationships among parameters and between
13621parameters and global data.
13622
13623@option{-fargument-alias} specifies that arguments (parameters) may
13624alias each other and may alias global storage.@*
13625@option{-fargument-noalias} specifies that arguments do not alias
13626each other, but may alias global storage.@*
13627@option{-fargument-noalias-global} specifies that arguments do not
13628alias each other and do not alias global storage.
13629@option{-fargument-noalias-anything} specifies that arguments do not
13630alias any other storage.
13631
13632Each language will automatically use whatever option is required by
13633the language standard. You should not need to use these options yourself.
13634
13635@item -fleading-underscore
13636@opindex fleading-underscore
13637This option and its counterpart, @option{-fno-leading-underscore}, forcibly
13638change the way C symbols are represented in the object file. One use
13639is to help link with legacy assembly code.
13640
13641@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
13642generate code that is not binary compatible with code generated without that
13643switch. Use it to conform to a non-default application binary interface.
13644Not all targets provide complete support for this switch.
13645
13646@item -ftls-model=@var{model}
13647Alter the thread-local storage model to be used (@pxref{Thread-Local}).
13648The @var{model} argument should be one of @code{global-dynamic},
13649@code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
13650
13651The default without @option{-fpic} is @code{initial-exec}; with
13652@option{-fpic} the default is @code{global-dynamic}.
13653
13654@item -fvisibility=@var{default|internal|hidden|protected}
13655@opindex fvisibility
13656Set the default ELF image symbol visibility to the specified option---all
13657symbols will be marked with this unless overridden within the code.
13658Using this feature can very substantially improve linking and
13659load times of shared object libraries, produce more optimized
13660code, provide near-perfect API export and prevent symbol clashes.
13661It is @strong{strongly} recommended that you use this in any shared objects
13662you distribute.
13663
13664Despite the nomenclature, @code{default} always means public ie;
13665available to be linked against from outside the shared object.
13666@code{protected} and @code{internal} are pretty useless in real-world
13667usage so the only other commonly used option will be @code{hidden}.
13668The default if @option{-fvisibility} isn't specified is
13669@code{default}, i.e., make every
13670symbol public---this causes the same behavior as previous versions of
13671GCC@.
13672
13673A good explanation of the benefits offered by ensuring ELF
13674symbols have the correct visibility is given by ``How To Write
13675Shared Libraries'' by Ulrich Drepper (which can be found at
13676@w{@uref{http://people.redhat.com/~drepper/}})---however a superior
13677solution made possible by this option to marking things hidden when
13678the default is public is to make the default hidden and mark things
13679public. This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
13680and @code{__attribute__ ((visibility("default")))} instead of
13681@code{__declspec(dllexport)} you get almost identical semantics with
13682identical syntax. This is a great boon to those working with
13683cross-platform projects.
13684
13685For those adding visibility support to existing code, you may find
13686@samp{#pragma GCC visibility} of use. This works by you enclosing
13687the declarations you wish to set visibility for with (for example)
13688@samp{#pragma GCC visibility push(hidden)} and
13689@samp{#pragma GCC visibility pop}.
13690Bear in mind that symbol visibility should be viewed @strong{as
13691part of the API interface contract} and thus all new code should
13692always specify visibility when it is not the default ie; declarations
13693only for use within the local DSO should @strong{always} be marked explicitly
13694as hidden as so to avoid PLT indirection overheads---making this
13695abundantly clear also aids readability and self-documentation of the code.
13696Note that due to ISO C++ specification requirements, operator new and
13697operator delete must always be of default visibility.
13698
13699Be aware that headers from outside your project, in particular system
13700headers and headers from any other library you use, may not be
13701expecting to be compiled with visibility other than the default. You
13702may need to explicitly say @samp{#pragma GCC visibility push(default)}
13703before including any such headers.
13704
13705@samp{extern} declarations are not affected by @samp{-fvisibility}, so
13706a lot of code can be recompiled with @samp{-fvisibility=hidden} with
13707no modifications. However, this means that calls to @samp{extern}
13708functions with no explicit visibility will use the PLT, so it is more
13709effective to use @samp{__attribute ((visibility))} and/or
13710@samp{#pragma GCC visibility} to tell the compiler which @samp{extern}
13711declarations should be treated as hidden.
13712
13713Note that @samp{-fvisibility} does affect C++ vague linkage
13714entities. This means that, for instance, an exception class that will
13715be thrown between DSOs must be explicitly marked with default
13716visibility so that the @samp{type_info} nodes will be unified between
13717the DSOs.
13718
13719An overview of these techniques, their benefits and how to use them
13720is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
13721
13722@end table
13723
13724@c man end
13725
13726@node Environment Variables
13727@section Environment Variables Affecting GCC
13728@cindex environment variables
13729
13730@c man begin ENVIRONMENT
13731This section describes several environment variables that affect how GCC
13732operates. Some of them work by specifying directories or prefixes to use
13733when searching for various kinds of files. Some are used to specify other
13734aspects of the compilation environment.
13735
13736Note that you can also specify places to search using options such as
13737@option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
13738take precedence over places specified using environment variables, which
13739in turn take precedence over those specified by the configuration of GCC@.
13740@xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
13741GNU Compiler Collection (GCC) Internals}.
13742
13743@table @env
13744@item LANG
13745@itemx LC_CTYPE
13746@c @itemx LC_COLLATE
13747@itemx LC_MESSAGES
13748@c @itemx LC_MONETARY
13749@c @itemx LC_NUMERIC
13750@c @itemx LC_TIME
13751@itemx LC_ALL
13752@findex LANG
13753@findex LC_CTYPE
13754@c @findex LC_COLLATE
13755@findex LC_MESSAGES
13756@c @findex LC_MONETARY
13757@c @findex LC_NUMERIC
13758@c @findex LC_TIME
13759@findex LC_ALL
13760@cindex locale
13761These environment variables control the way that GCC uses
13762localization information that allow GCC to work with different
13763national conventions. GCC inspects the locale categories
13764@env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
13765so. These locale categories can be set to any value supported by your
13766installation. A typical value is @samp{en_GB.UTF-8} for English in the United
13767Kingdom encoded in UTF-8.
13768
13769The @env{LC_CTYPE} environment variable specifies character
13770classification. GCC uses it to determine the character boundaries in
13771a string; this is needed for some multibyte encodings that contain quote
13772and escape characters that would otherwise be interpreted as a string
13773end or escape.
13774
13775The @env{LC_MESSAGES} environment variable specifies the language to
13776use in diagnostic messages.
13777
13778If the @env{LC_ALL} environment variable is set, it overrides the value
13779of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
13780and @env{LC_MESSAGES} default to the value of the @env{LANG}
13781environment variable. If none of these variables are set, GCC
13782defaults to traditional C English behavior.
13783
13784@item TMPDIR
13785@findex TMPDIR
13786If @env{TMPDIR} is set, it specifies the directory to use for temporary
13787files. GCC uses temporary files to hold the output of one stage of
13788compilation which is to be used as input to the next stage: for example,
13789the output of the preprocessor, which is the input to the compiler
13790proper.
13791
13792@item GCC_EXEC_PREFIX
13793@findex GCC_EXEC_PREFIX
13794If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
13795names of the subprograms executed by the compiler. No slash is added
13796when this prefix is combined with the name of a subprogram, but you can
13797specify a prefix that ends with a slash if you wish.
13798
13799If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
13800an appropriate prefix to use based on the pathname it was invoked with.
13801
13802If GCC cannot find the subprogram using the specified prefix, it
13803tries looking in the usual places for the subprogram.
13804
13805The default value of @env{GCC_EXEC_PREFIX} is
13806@file{@var{prefix}/lib/gcc/} where @var{prefix} is the value
13807of @code{prefix} when you ran the @file{configure} script.
13808
13809Other prefixes specified with @option{-B} take precedence over this prefix.
13810
13811This prefix is also used for finding files such as @file{crt0.o} that are
13812used for linking.
13813
13814In addition, the prefix is used in an unusual way in finding the
13815directories to search for header files. For each of the standard
13816directories whose name normally begins with @samp{/usr/local/lib/gcc}
13817(more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
13818replacing that beginning with the specified prefix to produce an
13819alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
13820@file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
13821These alternate directories are searched first; the standard directories
13822come next.
13823
13824@item COMPILER_PATH
13825@findex COMPILER_PATH
13826The value of @env{COMPILER_PATH} is a colon-separated list of
13827directories, much like @env{PATH}. GCC tries the directories thus
13828specified when searching for subprograms, if it can't find the
13829subprograms using @env{GCC_EXEC_PREFIX}.
13830
13831@item LIBRARY_PATH
13832@findex LIBRARY_PATH
13833The value of @env{LIBRARY_PATH} is a colon-separated list of
13834directories, much like @env{PATH}. When configured as a native compiler,
13835GCC tries the directories thus specified when searching for special
13836linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking
13837using GCC also uses these directories when searching for ordinary
13838libraries for the @option{-l} option (but directories specified with
13839@option{-L} come first).
13840
13841@item LANG
13842@findex LANG
13843@cindex locale definition
13844This variable is used to pass locale information to the compiler. One way in
13845which this information is used is to determine the character set to be used
13846when character literals, string literals and comments are parsed in C and C++.
13847When the compiler is configured to allow multibyte characters,
13848the following values for @env{LANG} are recognized:
13849
13850@table @samp
13851@item C-JIS
13852Recognize JIS characters.
13853@item C-SJIS
13854Recognize SJIS characters.
13855@item C-EUCJP
13856Recognize EUCJP characters.
13857@end table
13858
13859If @env{LANG} is not defined, or if it has some other value, then the
13860compiler will use mblen and mbtowc as defined by the default locale to
13861recognize and translate multibyte characters.
13862@end table
13863
13864@noindent
13865Some additional environments variables affect the behavior of the
13866preprocessor.
13867
13868@include cppenv.texi
13869
13870@c man end
13871
13872@node Precompiled Headers
13873@section Using Precompiled Headers
13874@cindex precompiled headers
13875@cindex speed of compilation
13876
13877Often large projects have many header files that are included in every
13878source file. The time the compiler takes to process these header files
13879over and over again can account for nearly all of the time required to
13880build the project. To make builds faster, GCC allows users to
13881`precompile' a header file; then, if builds can use the precompiled
13882header file they will be much faster.
13883
13884To create a precompiled header file, simply compile it as you would any
13885other file, if necessary using the @option{-x} option to make the driver
13886treat it as a C or C++ header file. You will probably want to use a
13887tool like @command{make} to keep the precompiled header up-to-date when
13888the headers it contains change.
13889
13890A precompiled header file will be searched for when @code{#include} is
13891seen in the compilation. As it searches for the included file
13892(@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
13893compiler looks for a precompiled header in each directory just before it
13894looks for the include file in that directory. The name searched for is
13895the name specified in the @code{#include} with @samp{.gch} appended. If
13896the precompiled header file can't be used, it is ignored.
13897
13898For instance, if you have @code{#include "all.h"}, and you have
13899@file{all.h.gch} in the same directory as @file{all.h}, then the
13900precompiled header file will be used if possible, and the original
13901header will be used otherwise.
13902
13903Alternatively, you might decide to put the precompiled header file in a
13904directory and use @option{-I} to ensure that directory is searched
13905before (or instead of) the directory containing the original header.
13906Then, if you want to check that the precompiled header file is always
13907used, you can put a file of the same name as the original header in this
13908directory containing an @code{#error} command.
13909
13910This also works with @option{-include}. So yet another way to use
13911precompiled headers, good for projects not designed with precompiled
13912header files in mind, is to simply take most of the header files used by
13913a project, include them from another header file, precompile that header
13914file, and @option{-include} the precompiled header. If the header files
13915have guards against multiple inclusion, they will be skipped because
13916they've already been included (in the precompiled header).
13917
13918If you need to precompile the same header file for different
13919languages, targets, or compiler options, you can instead make a
13920@emph{directory} named like @file{all.h.gch}, and put each precompiled
13921header in the directory, perhaps using @option{-o}. It doesn't matter
13922what you call the files in the directory, every precompiled header in
13923the directory will be considered. The first precompiled header
13924encountered in the directory that is valid for this compilation will
13925be used; they're searched in no particular order.
13926
13927There are many other possibilities, limited only by your imagination,
13928good sense, and the constraints of your build system.
13929
13930A precompiled header file can be used only when these conditions apply:
13931
13932@itemize
13933@item
13934Only one precompiled header can be used in a particular compilation.
13935
13936@item
13937A precompiled header can't be used once the first C token is seen. You
13938can have preprocessor directives before a precompiled header; you can
13939even include a precompiled header from inside another header, so long as
13940there are no C tokens before the @code{#include}.
13941
13942@item
13943The precompiled header file must be produced for the same language as
13944the current compilation. You can't use a C precompiled header for a C++
13945compilation.
13946
13947@item
13948The precompiled header file must have been produced by the same compiler
13949binary as the current compilation is using.
13950
13951@item
13952Any macros defined before the precompiled header is included must
13953either be defined in the same way as when the precompiled header was
13954generated, or must not affect the precompiled header, which usually
13955means that they don't appear in the precompiled header at all.
13956
13957The @option{-D} option is one way to define a macro before a
13958precompiled header is included; using a @code{#define} can also do it.
13959There are also some options that define macros implicitly, like
13960@option{-O} and @option{-Wdeprecated}; the same rule applies to macros
13961defined this way.
13962
13963@item If debugging information is output when using the precompiled
13964header, using @option{-g} or similar, the same kind of debugging information
13965must have been output when building the precompiled header. However,
13966a precompiled header built using @option{-g} can be used in a compilation
13967when no debugging information is being output.
13968
13969@item The same @option{-m} options must generally be used when building
13970and using the precompiled header. @xref{Submodel Options},
13971for any cases where this rule is relaxed.
13972
13973@item Each of the following options must be the same when building and using
13974the precompiled header:
13975
13976@gccoptlist{-fexceptions -funit-at-a-time}
13977
13978@item
13979Some other command-line options starting with @option{-f},
13980@option{-p}, or @option{-O} must be defined in the same way as when
13981the precompiled header was generated. At present, it's not clear
13982which options are safe to change and which are not; the safest choice
13983is to use exactly the same options when generating and using the
13984precompiled header. The following are known to be safe:
13985
13986@gccoptlist{-fmessage-length= -fpreprocessed
13987-fsched-interblock -fsched-spec -fsched-spec-load -fsched-spec-load-dangerous
13988-fsched-verbose=<number> -fschedule-insns -fvisibility=
13989-pedantic-errors}
13990
13991@end itemize
13992
13993For all of these except the last, the compiler will automatically
13994ignore the precompiled header if the conditions aren't met. If you
13995find an option combination that doesn't work and doesn't cause the
13996precompiled header to be ignored, please consider filing a bug report,
13997see @ref{Bugs}.
13998
13999If you do use differing options when generating and using the
14000precompiled header, the actual behavior will be a mixture of the
14001behavior for the options. For instance, if you use @option{-g} to
14002generate the precompiled header but not when using it, you may or may
14003not get debugging information for routines in the precompiled header.
14004
14005@node Running Protoize
14006@section Running Protoize
14007
14008The program @code{protoize} is an optional part of GCC@. You can use
14009it to add prototypes to a program, thus converting the program to ISO
14010C in one respect. The companion program @code{unprotoize} does the
14011reverse: it removes argument types from any prototypes that are found.
14012
14013When you run these programs, you must specify a set of source files as
14014command line arguments. The conversion programs start out by compiling
14015these files to see what functions they define. The information gathered
14016about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
14017
14018After scanning comes actual conversion. The specified files are all
14019eligible to be converted; any files they include (whether sources or
14020just headers) are eligible as well.
14021
14022But not all the eligible files are converted. By default,
14023@code{protoize} and @code{unprotoize} convert only source and header
14024files in the current directory. You can specify additional directories
14025whose files should be converted with the @option{-d @var{directory}}
14026option. You can also specify particular files to exclude with the
14027@option{-x @var{file}} option. A file is converted if it is eligible, its
14028directory name matches one of the specified directory names, and its
14029name within the directory has not been excluded.
14030
14031Basic conversion with @code{protoize} consists of rewriting most
14032function definitions and function declarations to specify the types of
14033the arguments. The only ones not rewritten are those for varargs
14034functions.
14035
14036@code{protoize} optionally inserts prototype declarations at the
14037beginning of the source file, to make them available for any calls that
14038precede the function's definition. Or it can insert prototype
14039declarations with block scope in the blocks where undeclared functions
14040are called.
14041
14042Basic conversion with @code{unprotoize} consists of rewriting most
14043function declarations to remove any argument types, and rewriting
14044function definitions to the old-style pre-ISO form.
14045
14046Both conversion programs print a warning for any function declaration or
14047definition that they can't convert. You can suppress these warnings
14048with @option{-q}.
14049
14050The output from @code{protoize} or @code{unprotoize} replaces the
14051original source file. The original file is renamed to a name ending
14052with @samp{.save} (for DOS, the saved filename ends in @samp{.sav}
14053without the original @samp{.c} suffix). If the @samp{.save} (@samp{.sav}
14054for DOS) file already exists, then the source file is simply discarded.
14055
14056@code{protoize} and @code{unprotoize} both depend on GCC itself to
14057scan the program and collect information about the functions it uses.
14058So neither of these programs will work until GCC is installed.
14059
14060Here is a table of the options you can use with @code{protoize} and
14061@code{unprotoize}. Each option works with both programs unless
14062otherwise stated.
14063
14064@table @code
14065@item -B @var{directory}
14066Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
14067usual directory (normally @file{/usr/local/lib}). This file contains
14068prototype information about standard system functions. This option
14069applies only to @code{protoize}.
14070
14071@item -c @var{compilation-options}
14072Use @var{compilation-options} as the options when running @command{gcc} to
14073produce the @samp{.X} files. The special option @option{-aux-info} is
14074always passed in addition, to tell @command{gcc} to write a @samp{.X} file.
14075
14076Note that the compilation options must be given as a single argument to
14077@code{protoize} or @code{unprotoize}. If you want to specify several
14078@command{gcc} options, you must quote the entire set of compilation options
14079to make them a single word in the shell.
14080
14081There are certain @command{gcc} arguments that you cannot use, because they
14082would produce the wrong kind of output. These include @option{-g},
14083@option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in
14084the @var{compilation-options}, they are ignored.
14085
14086@item -C
14087Rename files to end in @samp{.C} (@samp{.cc} for DOS-based file
14088systems) instead of @samp{.c}. This is convenient if you are converting
14089a C program to C++. This option applies only to @code{protoize}.
14090
14091@item -g
14092Add explicit global declarations. This means inserting explicit
14093declarations at the beginning of each source file for each function
14094that is called in the file and was not declared. These declarations
14095precede the first function definition that contains a call to an
14096undeclared function. This option applies only to @code{protoize}.
14097
14098@item -i @var{string}
14099Indent old-style parameter declarations with the string @var{string}.
14100This option applies only to @code{protoize}.
14101
14102@code{unprotoize} converts prototyped function definitions to old-style
14103function definitions, where the arguments are declared between the
14104argument list and the initial @samp{@{}. By default, @code{unprotoize}
14105uses five spaces as the indentation. If you want to indent with just
14106one space instead, use @option{-i " "}.
14107
14108@item -k
14109Keep the @samp{.X} files. Normally, they are deleted after conversion
14110is finished.
14111
14112@item -l
14113Add explicit local declarations. @code{protoize} with @option{-l} inserts
14114a prototype declaration for each function in each block which calls the
14115function without any declaration. This option applies only to
14116@code{protoize}.
14117
14118@item -n
14119Make no real changes. This mode just prints information about the conversions
14120that would have been done without @option{-n}.
14121
14122@item -N
14123Make no @samp{.save} files. The original files are simply deleted.
14124Use this option with caution.
14125
14126@item -p @var{program}
14127Use the program @var{program} as the compiler. Normally, the name
14128@file{gcc} is used.
14129
14130@item -q
14131Work quietly. Most warnings are suppressed.
14132
14133@item -v
14134Print the version number, just like @option{-v} for @command{gcc}.
14135@end table
14136
14137If you need special compiler options to compile one of your program's
14138source files, then you should generate that file's @samp{.X} file
14139specially, by running @command{gcc} on that source file with the
14140appropriate options and the option @option{-aux-info}. Then run
14141@code{protoize} on the entire set of files. @code{protoize} will use
14142the existing @samp{.X} file because it is newer than the source file.
14143For example:
14144
14145@smallexample
14146gcc -Dfoo=bar file1.c -aux-info file1.X
14147protoize *.c
14148@end smallexample
14149
14150@noindent
14151You need to include the special files along with the rest in the
14152@code{protoize} command, even though their @samp{.X} files already
14153exist, because otherwise they won't get converted.
14154
14155@xref{Protoize Caveats}, for more information on how to use
14156@code{protoize} successfully.
| 9512OpenBSD and NetBSD@. This option is overridden when @option{-march}
9513indicates that the target cpu will always have an FPU and so the
9514instruction will not need emulation. As of revision 2.6.1, these
9515instructions are not generated unless you also use the
9516@option{-funsafe-math-optimizations} switch.
9517
9518@item -malign-double
9519@itemx -mno-align-double
9520@opindex malign-double
9521@opindex mno-align-double
9522Control whether GCC aligns @code{double}, @code{long double}, and
9523@code{long long} variables on a two word boundary or a one word
9524boundary. Aligning @code{double} variables on a two word boundary will
9525produce code that runs somewhat faster on a @samp{Pentium} at the
9526expense of more memory.
9527
9528On x86-64, @option{-malign-double} is enabled by default.
9529
9530@strong{Warning:} if you use the @option{-malign-double} switch,
9531structures containing the above types will be aligned differently than
9532the published application binary interface specifications for the 386
9533and will not be binary compatible with structures in code compiled
9534without that switch.
9535
9536@item -m96bit-long-double
9537@itemx -m128bit-long-double
9538@opindex m96bit-long-double
9539@opindex m128bit-long-double
9540These switches control the size of @code{long double} type. The i386
9541application binary interface specifies the size to be 96 bits,
9542so @option{-m96bit-long-double} is the default in 32 bit mode.
9543
9544Modern architectures (Pentium and newer) would prefer @code{long double}
9545to be aligned to an 8 or 16 byte boundary. In arrays or structures
9546conforming to the ABI, this would not be possible. So specifying a
9547@option{-m128bit-long-double} will align @code{long double}
9548to a 16 byte boundary by padding the @code{long double} with an additional
954932 bit zero.
9550
9551In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
9552its ABI specifies that @code{long double} is to be aligned on 16 byte boundary.
9553
9554Notice that neither of these options enable any extra precision over the x87
9555standard of 80 bits for a @code{long double}.
9556
9557@strong{Warning:} if you override the default value for your target ABI, the
9558structures and arrays containing @code{long double} variables will change
9559their size as well as function calling convention for function taking
9560@code{long double} will be modified. Hence they will not be binary
9561compatible with arrays or structures in code compiled without that switch.
9562
9563@item -mmlarge-data-threshold=@var{number}
9564@opindex mlarge-data-threshold=@var{number}
9565When @option{-mcmodel=medium} is specified, the data greater than
9566@var{threshold} are placed in large data section. This value must be the
9567same across all object linked into the binary and defaults to 65535.
9568
9569@item -msvr3-shlib
9570@itemx -mno-svr3-shlib
9571@opindex msvr3-shlib
9572@opindex mno-svr3-shlib
9573Control whether GCC places uninitialized local variables into the
9574@code{bss} or @code{data} segments. @option{-msvr3-shlib} places them
9575into @code{bss}. These options are meaningful only on System V Release 3.
9576
9577@item -mrtd
9578@opindex mrtd
9579Use a different function-calling convention, in which functions that
9580take a fixed number of arguments return with the @code{ret} @var{num}
9581instruction, which pops their arguments while returning. This saves one
9582instruction in the caller since there is no need to pop the arguments
9583there.
9584
9585You can specify that an individual function is called with this calling
9586sequence with the function attribute @samp{stdcall}. You can also
9587override the @option{-mrtd} option by using the function attribute
9588@samp{cdecl}. @xref{Function Attributes}.
9589
9590@strong{Warning:} this calling convention is incompatible with the one
9591normally used on Unix, so you cannot use it if you need to call
9592libraries compiled with the Unix compiler.
9593
9594Also, you must provide function prototypes for all functions that
9595take variable numbers of arguments (including @code{printf});
9596otherwise incorrect code will be generated for calls to those
9597functions.
9598
9599In addition, seriously incorrect code will result if you call a
9600function with too many arguments. (Normally, extra arguments are
9601harmlessly ignored.)
9602
9603@item -mregparm=@var{num}
9604@opindex mregparm
9605Control how many registers are used to pass integer arguments. By
9606default, no registers are used to pass arguments, and at most 3
9607registers can be used. You can control this behavior for a specific
9608function by using the function attribute @samp{regparm}.
9609@xref{Function Attributes}.
9610
9611@strong{Warning:} if you use this switch, and
9612@var{num} is nonzero, then you must build all modules with the same
9613value, including any libraries. This includes the system libraries and
9614startup modules.
9615
9616@item -msseregparm
9617@opindex msseregparm
9618Use SSE register passing conventions for float and double arguments
9619and return values. You can control this behavior for a specific
9620function by using the function attribute @samp{sseregparm}.
9621@xref{Function Attributes}.
9622
9623@strong{Warning:} if you use this switch then you must build all
9624modules with the same value, including any libraries. This includes
9625the system libraries and startup modules.
9626
9627@item -mstackrealign
9628@opindex mstackrealign
9629Realign the stack at entry. On the Intel x86, the
9630@option{-mstackrealign} option will generate an alternate prologue and
9631epilogue that realigns the runtime stack. This supports mixing legacy
9632codes that keep a 4-byte aligned stack with modern codes that keep a
963316-byte stack for SSE compatibility. The alternate prologue and
9634epilogue are slower and bigger than the regular ones, and the
9635alternate prologue requires an extra scratch register; this lowers the
9636number of registers available if used in conjunction with the
9637@code{regparm} attribute. The @option{-mstackrealign} option is
9638incompatible with the nested function prologue; this is considered a
9639hard error. See also the attribute @code{force_align_arg_pointer},
9640applicable to individual functions.
9641
9642@item -mpreferred-stack-boundary=@var{num}
9643@opindex mpreferred-stack-boundary
9644Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
9645byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
9646the default is 4 (16 bytes or 128 bits).
9647
9648On Pentium and PentiumPro, @code{double} and @code{long double} values
9649should be aligned to an 8 byte boundary (see @option{-malign-double}) or
9650suffer significant run time performance penalties. On Pentium III, the
9651Streaming SIMD Extension (SSE) data type @code{__m128} may not work
9652properly if it is not 16 byte aligned.
9653
9654To ensure proper alignment of this values on the stack, the stack boundary
9655must be as aligned as that required by any value stored on the stack.
9656Further, every function must be generated such that it keeps the stack
9657aligned. Thus calling a function compiled with a higher preferred
9658stack boundary from a function compiled with a lower preferred stack
9659boundary will most likely misalign the stack. It is recommended that
9660libraries that use callbacks always use the default setting.
9661
9662This extra alignment does consume extra stack space, and generally
9663increases code size. Code that is sensitive to stack space usage, such
9664as embedded systems and operating system kernels, may want to reduce the
9665preferred alignment to @option{-mpreferred-stack-boundary=2}.
9666
9667@item -mmmx
9668@itemx -mno-mmx
9669@item -msse
9670@itemx -mno-sse
9671@item -msse2
9672@itemx -mno-sse2
9673@item -msse3
9674@itemx -mno-sse3
9675@item -m3dnow
9676@itemx -mno-3dnow
9677@opindex mmmx
9678@opindex mno-mmx
9679@opindex msse
9680@opindex mno-sse
9681@opindex m3dnow
9682@opindex mno-3dnow
9683These switches enable or disable the use of instructions in the MMX,
9684SSE, SSE2 or 3DNow! extended instruction sets. These extensions are
9685also available as built-in functions: see @ref{X86 Built-in Functions},
9686for details of the functions enabled and disabled by these switches.
9687
9688To have SSE/SSE2 instructions generated automatically from floating-point
9689code (as opposed to 387 instructions), see @option{-mfpmath=sse}.
9690
9691These options will enable GCC to use these extended instructions in
9692generated code, even without @option{-mfpmath=sse}. Applications which
9693perform runtime CPU detection must compile separate files for each
9694supported architecture, using the appropriate flags. In particular,
9695the file containing the CPU detection code should be compiled without
9696these options.
9697
9698@item -mpush-args
9699@itemx -mno-push-args
9700@opindex mpush-args
9701@opindex mno-push-args
9702Use PUSH operations to store outgoing parameters. This method is shorter
9703and usually equally fast as method using SUB/MOV operations and is enabled
9704by default. In some cases disabling it may improve performance because of
9705improved scheduling and reduced dependencies.
9706
9707@item -maccumulate-outgoing-args
9708@opindex maccumulate-outgoing-args
9709If enabled, the maximum amount of space required for outgoing arguments will be
9710computed in the function prologue. This is faster on most modern CPUs
9711because of reduced dependencies, improved scheduling and reduced stack usage
9712when preferred stack boundary is not equal to 2. The drawback is a notable
9713increase in code size. This switch implies @option{-mno-push-args}.
9714
9715@item -mthreads
9716@opindex mthreads
9717Support thread-safe exception handling on @samp{Mingw32}. Code that relies
9718on thread-safe exception handling must compile and link all code with the
9719@option{-mthreads} option. When compiling, @option{-mthreads} defines
9720@option{-D_MT}; when linking, it links in a special thread helper library
9721@option{-lmingwthrd} which cleans up per thread exception handling data.
9722
9723@item -mno-align-stringops
9724@opindex mno-align-stringops
9725Do not align destination of inlined string operations. This switch reduces
9726code size and improves performance in case the destination is already aligned,
9727but GCC doesn't know about it.
9728
9729@item -minline-all-stringops
9730@opindex minline-all-stringops
9731By default GCC inlines string operations only when destination is known to be
9732aligned at least to 4 byte boundary. This enables more inlining, increase code
9733size, but may improve performance of code that depends on fast memcpy, strlen
9734and memset for short lengths.
9735
9736@item -momit-leaf-frame-pointer
9737@opindex momit-leaf-frame-pointer
9738Don't keep the frame pointer in a register for leaf functions. This
9739avoids the instructions to save, set up and restore frame pointers and
9740makes an extra register available in leaf functions. The option
9741@option{-fomit-frame-pointer} removes the frame pointer for all functions
9742which might make debugging harder.
9743
9744@item -mtls-direct-seg-refs
9745@itemx -mno-tls-direct-seg-refs
9746@opindex mtls-direct-seg-refs
9747Controls whether TLS variables may be accessed with offsets from the
9748TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
9749or whether the thread base pointer must be added. Whether or not this
9750is legal depends on the operating system, and whether it maps the
9751segment to cover the entire TLS area.
9752
9753For systems that use GNU libc, the default is on.
9754@end table
9755
9756These @samp{-m} switches are supported in addition to the above
9757on AMD x86-64 processors in 64-bit environments.
9758
9759@table @gcctabopt
9760@item -m32
9761@itemx -m64
9762@opindex m32
9763@opindex m64
9764Generate code for a 32-bit or 64-bit environment.
9765The 32-bit environment sets int, long and pointer to 32 bits and
9766generates code that runs on any i386 system.
9767The 64-bit environment sets int to 32 bits and long and pointer
9768to 64 bits and generates code for AMD's x86-64 architecture. For
9769darwin only the -m64 option turns off the @option{-fno-pic} and
9770@option{-mdynamic-no-pic} options.
9771
9772@item -mno-red-zone
9773@opindex no-red-zone
9774Do not use a so called red zone for x86-64 code. The red zone is mandated
9775by the x86-64 ABI, it is a 128-byte area beyond the location of the
9776stack pointer that will not be modified by signal or interrupt handlers
9777and therefore can be used for temporary data without adjusting the stack
9778pointer. The flag @option{-mno-red-zone} disables this red zone.
9779
9780@item -mcmodel=small
9781@opindex mcmodel=small
9782Generate code for the small code model: the program and its symbols must
9783be linked in the lower 2 GB of the address space. Pointers are 64 bits.
9784Programs can be statically or dynamically linked. This is the default
9785code model.
9786
9787@item -mcmodel=kernel
9788@opindex mcmodel=kernel
9789Generate code for the kernel code model. The kernel runs in the
9790negative 2 GB of the address space.
9791This model has to be used for Linux kernel code.
9792
9793@item -mcmodel=medium
9794@opindex mcmodel=medium
9795Generate code for the medium model: The program is linked in the lower 2
9796GB of the address space but symbols can be located anywhere in the
9797address space. Programs can be statically or dynamically linked, but
9798building of shared libraries are not supported with the medium model.
9799
9800@item -mcmodel=large
9801@opindex mcmodel=large
9802Generate code for the large model: This model makes no assumptions
9803about addresses and sizes of sections. Currently GCC does not implement
9804this model.
9805@end table
9806
9807@node IA-64 Options
9808@subsection IA-64 Options
9809@cindex IA-64 Options
9810
9811These are the @samp{-m} options defined for the Intel IA-64 architecture.
9812
9813@table @gcctabopt
9814@item -mbig-endian
9815@opindex mbig-endian
9816Generate code for a big endian target. This is the default for HP-UX@.
9817
9818@item -mlittle-endian
9819@opindex mlittle-endian
9820Generate code for a little endian target. This is the default for AIX5
9821and GNU/Linux.
9822
9823@item -mgnu-as
9824@itemx -mno-gnu-as
9825@opindex mgnu-as
9826@opindex mno-gnu-as
9827Generate (or don't) code for the GNU assembler. This is the default.
9828@c Also, this is the default if the configure option @option{--with-gnu-as}
9829@c is used.
9830
9831@item -mgnu-ld
9832@itemx -mno-gnu-ld
9833@opindex mgnu-ld
9834@opindex mno-gnu-ld
9835Generate (or don't) code for the GNU linker. This is the default.
9836@c Also, this is the default if the configure option @option{--with-gnu-ld}
9837@c is used.
9838
9839@item -mno-pic
9840@opindex mno-pic
9841Generate code that does not use a global pointer register. The result
9842is not position independent code, and violates the IA-64 ABI@.
9843
9844@item -mvolatile-asm-stop
9845@itemx -mno-volatile-asm-stop
9846@opindex mvolatile-asm-stop
9847@opindex mno-volatile-asm-stop
9848Generate (or don't) a stop bit immediately before and after volatile asm
9849statements.
9850
9851@item -mregister-names
9852@itemx -mno-register-names
9853@opindex mregister-names
9854@opindex mno-register-names
9855Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
9856the stacked registers. This may make assembler output more readable.
9857
9858@item -mno-sdata
9859@itemx -msdata
9860@opindex mno-sdata
9861@opindex msdata
9862Disable (or enable) optimizations that use the small data section. This may
9863be useful for working around optimizer bugs.
9864
9865@item -mconstant-gp
9866@opindex mconstant-gp
9867Generate code that uses a single constant global pointer value. This is
9868useful when compiling kernel code.
9869
9870@item -mauto-pic
9871@opindex mauto-pic
9872Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
9873This is useful when compiling firmware code.
9874
9875@item -minline-float-divide-min-latency
9876@opindex minline-float-divide-min-latency
9877Generate code for inline divides of floating point values
9878using the minimum latency algorithm.
9879
9880@item -minline-float-divide-max-throughput
9881@opindex minline-float-divide-max-throughput
9882Generate code for inline divides of floating point values
9883using the maximum throughput algorithm.
9884
9885@item -minline-int-divide-min-latency
9886@opindex minline-int-divide-min-latency
9887Generate code for inline divides of integer values
9888using the minimum latency algorithm.
9889
9890@item -minline-int-divide-max-throughput
9891@opindex minline-int-divide-max-throughput
9892Generate code for inline divides of integer values
9893using the maximum throughput algorithm.
9894
9895@item -minline-sqrt-min-latency
9896@opindex minline-sqrt-min-latency
9897Generate code for inline square roots
9898using the minimum latency algorithm.
9899
9900@item -minline-sqrt-max-throughput
9901@opindex minline-sqrt-max-throughput
9902Generate code for inline square roots
9903using the maximum throughput algorithm.
9904
9905@item -mno-dwarf2-asm
9906@itemx -mdwarf2-asm
9907@opindex mno-dwarf2-asm
9908@opindex mdwarf2-asm
9909Don't (or do) generate assembler code for the DWARF2 line number debugging
9910info. This may be useful when not using the GNU assembler.
9911
9912@item -mearly-stop-bits
9913@itemx -mno-early-stop-bits
9914@opindex mearly-stop-bits
9915@opindex mno-early-stop-bits
9916Allow stop bits to be placed earlier than immediately preceding the
9917instruction that triggered the stop bit. This can improve instruction
9918scheduling, but does not always do so.
9919
9920@item -mfixed-range=@var{register-range}
9921@opindex mfixed-range
9922Generate code treating the given register range as fixed registers.
9923A fixed register is one that the register allocator can not use. This is
9924useful when compiling kernel code. A register range is specified as
9925two registers separated by a dash. Multiple register ranges can be
9926specified separated by a comma.
9927
9928@item -mtls-size=@var{tls-size}
9929@opindex mtls-size
9930Specify bit size of immediate TLS offsets. Valid values are 14, 22, and
993164.
9932
9933@item -mtune=@var{cpu-type}
9934@opindex mtune
9935Tune the instruction scheduling for a particular CPU, Valid values are
9936itanium, itanium1, merced, itanium2, and mckinley.
9937
9938@item -mt
9939@itemx -pthread
9940@opindex mt
9941@opindex pthread
9942Add support for multithreading using the POSIX threads library. This
9943option sets flags for both the preprocessor and linker. It does
9944not affect the thread safety of object code produced by the compiler or
9945that of libraries supplied with it. These are HP-UX specific flags.
9946
9947@item -milp32
9948@itemx -mlp64
9949@opindex milp32
9950@opindex mlp64
9951Generate code for a 32-bit or 64-bit environment.
9952The 32-bit environment sets int, long and pointer to 32 bits.
9953The 64-bit environment sets int to 32 bits and long and pointer
9954to 64 bits. These are HP-UX specific flags.
9955
9956@item -mno-sched-br-data-spec
9957@itemx -msched-br-data-spec
9958@opindex mno-sched-br-data-spec
9959@opindex msched-br-data-spec
9960(Dis/En)able data speculative scheduling before reload.
9961This will result in generation of the ld.a instructions and
9962the corresponding check instructions (ld.c / chk.a).
9963The default is 'disable'.
9964
9965@item -msched-ar-data-spec
9966@itemx -mno-sched-ar-data-spec
9967@opindex msched-ar-data-spec
9968@opindex mno-sched-ar-data-spec
9969(En/Dis)able data speculative scheduling after reload.
9970This will result in generation of the ld.a instructions and
9971the corresponding check instructions (ld.c / chk.a).
9972The default is 'enable'.
9973
9974@item -mno-sched-control-spec
9975@itemx -msched-control-spec
9976@opindex mno-sched-control-spec
9977@opindex msched-control-spec
9978(Dis/En)able control speculative scheduling. This feature is
9979available only during region scheduling (i.e. before reload).
9980This will result in generation of the ld.s instructions and
9981the corresponding check instructions chk.s .
9982The default is 'disable'.
9983
9984@item -msched-br-in-data-spec
9985@itemx -mno-sched-br-in-data-spec
9986@opindex msched-br-in-data-spec
9987@opindex mno-sched-br-in-data-spec
9988(En/Dis)able speculative scheduling of the instructions that
9989are dependent on the data speculative loads before reload.
9990This is effective only with @option{-msched-br-data-spec} enabled.
9991The default is 'enable'.
9992
9993@item -msched-ar-in-data-spec
9994@itemx -mno-sched-ar-in-data-spec
9995@opindex msched-ar-in-data-spec
9996@opindex mno-sched-ar-in-data-spec
9997(En/Dis)able speculative scheduling of the instructions that
9998are dependent on the data speculative loads after reload.
9999This is effective only with @option{-msched-ar-data-spec} enabled.
10000The default is 'enable'.
10001
10002@item -msched-in-control-spec
10003@itemx -mno-sched-in-control-spec
10004@opindex msched-in-control-spec
10005@opindex mno-sched-in-control-spec
10006(En/Dis)able speculative scheduling of the instructions that
10007are dependent on the control speculative loads.
10008This is effective only with @option{-msched-control-spec} enabled.
10009The default is 'enable'.
10010
10011@item -msched-ldc
10012@itemx -mno-sched-ldc
10013@opindex msched-ldc
10014@opindex mno-sched-ldc
10015(En/Dis)able use of simple data speculation checks ld.c .
10016If disabled, only chk.a instructions will be emitted to check
10017data speculative loads.
10018The default is 'enable'.
10019
10020@item -mno-sched-control-ldc
10021@itemx -msched-control-ldc
10022@opindex mno-sched-control-ldc
10023@opindex msched-control-ldc
10024(Dis/En)able use of ld.c instructions to check control speculative loads.
10025If enabled, in case of control speculative load with no speculatively
10026scheduled dependent instructions this load will be emitted as ld.sa and
10027ld.c will be used to check it.
10028The default is 'disable'.
10029
10030@item -mno-sched-spec-verbose
10031@itemx -msched-spec-verbose
10032@opindex mno-sched-spec-verbose
10033@opindex msched-spec-verbose
10034(Dis/En)able printing of the information about speculative motions.
10035
10036@item -mno-sched-prefer-non-data-spec-insns
10037@itemx -msched-prefer-non-data-spec-insns
10038@opindex mno-sched-prefer-non-data-spec-insns
10039@opindex msched-prefer-non-data-spec-insns
10040If enabled, data speculative instructions will be chosen for schedule
10041only if there are no other choices at the moment. This will make
10042the use of the data speculation much more conservative.
10043The default is 'disable'.
10044
10045@item -mno-sched-prefer-non-control-spec-insns
10046@itemx -msched-prefer-non-control-spec-insns
10047@opindex mno-sched-prefer-non-control-spec-insns
10048@opindex msched-prefer-non-control-spec-insns
10049If enabled, control speculative instructions will be chosen for schedule
10050only if there are no other choices at the moment. This will make
10051the use of the control speculation much more conservative.
10052The default is 'disable'.
10053
10054@item -mno-sched-count-spec-in-critical-path
10055@itemx -msched-count-spec-in-critical-path
10056@opindex mno-sched-count-spec-in-critical-path
10057@opindex msched-count-spec-in-critical-path
10058If enabled, speculative dependencies will be considered during
10059computation of the instructions priorities. This will make the use of the
10060speculation a bit more conservative.
10061The default is 'disable'.
10062
10063@end table
10064
10065@node M32C Options
10066@subsection M32C Options
10067@cindex M32C options
10068
10069@table @gcctabopt
10070@item -mcpu=@var{name}
10071@opindex mcpu=
10072Select the CPU for which code is generated. @var{name} may be one of
10073@samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to
10074/60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for
10075the M32C/80 series.
10076
10077@item -msim
10078@opindex msim
10079Specifies that the program will be run on the simulator. This causes
10080an alternate runtime library to be linked in which supports, for
10081example, file I/O. You must not use this option when generating
10082programs that will run on real hardware; you must provide your own
10083runtime library for whatever I/O functions are needed.
10084
10085@item -memregs=@var{number}
10086@opindex memregs=
10087Specifies the number of memory-based pseudo-registers GCC will use
10088during code generation. These pseudo-registers will be used like real
10089registers, so there is a tradeoff between GCC's ability to fit the
10090code into available registers, and the performance penalty of using
10091memory instead of registers. Note that all modules in a program must
10092be compiled with the same value for this option. Because of that, you
10093must not use this option with the default runtime libraries gcc
10094builds.
10095
10096@end table
10097
10098@node M32R/D Options
10099@subsection M32R/D Options
10100@cindex M32R/D options
10101
10102These @option{-m} options are defined for Renesas M32R/D architectures:
10103
10104@table @gcctabopt
10105@item -m32r2
10106@opindex m32r2
10107Generate code for the M32R/2@.
10108
10109@item -m32rx
10110@opindex m32rx
10111Generate code for the M32R/X@.
10112
10113@item -m32r
10114@opindex m32r
10115Generate code for the M32R@. This is the default.
10116
10117@item -mmodel=small
10118@opindex mmodel=small
10119Assume all objects live in the lower 16MB of memory (so that their addresses
10120can be loaded with the @code{ld24} instruction), and assume all subroutines
10121are reachable with the @code{bl} instruction.
10122This is the default.
10123
10124The addressability of a particular object can be set with the
10125@code{model} attribute.
10126
10127@item -mmodel=medium
10128@opindex mmodel=medium
10129Assume objects may be anywhere in the 32-bit address space (the compiler
10130will generate @code{seth/add3} instructions to load their addresses), and
10131assume all subroutines are reachable with the @code{bl} instruction.
10132
10133@item -mmodel=large
10134@opindex mmodel=large
10135Assume objects may be anywhere in the 32-bit address space (the compiler
10136will generate @code{seth/add3} instructions to load their addresses), and
10137assume subroutines may not be reachable with the @code{bl} instruction
10138(the compiler will generate the much slower @code{seth/add3/jl}
10139instruction sequence).
10140
10141@item -msdata=none
10142@opindex msdata=none
10143Disable use of the small data area. Variables will be put into
10144one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
10145@code{section} attribute has been specified).
10146This is the default.
10147
10148The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
10149Objects may be explicitly put in the small data area with the
10150@code{section} attribute using one of these sections.
10151
10152@item -msdata=sdata
10153@opindex msdata=sdata
10154Put small global and static data in the small data area, but do not
10155generate special code to reference them.
10156
10157@item -msdata=use
10158@opindex msdata=use
10159Put small global and static data in the small data area, and generate
10160special instructions to reference them.
10161
10162@item -G @var{num}
10163@opindex G
10164@cindex smaller data references
10165Put global and static objects less than or equal to @var{num} bytes
10166into the small data or bss sections instead of the normal data or bss
10167sections. The default value of @var{num} is 8.
10168The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
10169for this option to have any effect.
10170
10171All modules should be compiled with the same @option{-G @var{num}} value.
10172Compiling with different values of @var{num} may or may not work; if it
10173doesn't the linker will give an error message---incorrect code will not be
10174generated.
10175
10176@item -mdebug
10177@opindex mdebug
10178Makes the M32R specific code in the compiler display some statistics
10179that might help in debugging programs.
10180
10181@item -malign-loops
10182@opindex malign-loops
10183Align all loops to a 32-byte boundary.
10184
10185@item -mno-align-loops
10186@opindex mno-align-loops
10187Do not enforce a 32-byte alignment for loops. This is the default.
10188
10189@item -missue-rate=@var{number}
10190@opindex missue-rate=@var{number}
10191Issue @var{number} instructions per cycle. @var{number} can only be 1
10192or 2.
10193
10194@item -mbranch-cost=@var{number}
10195@opindex mbranch-cost=@var{number}
10196@var{number} can only be 1 or 2. If it is 1 then branches will be
10197preferred over conditional code, if it is 2, then the opposite will
10198apply.
10199
10200@item -mflush-trap=@var{number}
10201@opindex mflush-trap=@var{number}
10202Specifies the trap number to use to flush the cache. The default is
1020312. Valid numbers are between 0 and 15 inclusive.
10204
10205@item -mno-flush-trap
10206@opindex mno-flush-trap
10207Specifies that the cache cannot be flushed by using a trap.
10208
10209@item -mflush-func=@var{name}
10210@opindex mflush-func=@var{name}
10211Specifies the name of the operating system function to call to flush
10212the cache. The default is @emph{_flush_cache}, but a function call
10213will only be used if a trap is not available.
10214
10215@item -mno-flush-func
10216@opindex mno-flush-func
10217Indicates that there is no OS function for flushing the cache.
10218
10219@end table
10220
10221@node M680x0 Options
10222@subsection M680x0 Options
10223@cindex M680x0 options
10224
10225These are the @samp{-m} options defined for the 68000 series. The default
10226values for these options depends on which style of 68000 was selected when
10227the compiler was configured; the defaults for the most common choices are
10228given below.
10229
10230@table @gcctabopt
10231@item -m68000
10232@itemx -mc68000
10233@opindex m68000
10234@opindex mc68000
10235Generate output for a 68000. This is the default
10236when the compiler is configured for 68000-based systems.
10237
10238Use this option for microcontrollers with a 68000 or EC000 core,
10239including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
10240
10241@item -m68020
10242@itemx -mc68020
10243@opindex m68020
10244@opindex mc68020
10245Generate output for a 68020. This is the default
10246when the compiler is configured for 68020-based systems.
10247
10248@item -m68881
10249@opindex m68881
10250Generate output containing 68881 instructions for floating point.
10251This is the default for most 68020 systems unless @option{--nfp} was
10252specified when the compiler was configured.
10253
10254@item -m68030
10255@opindex m68030
10256Generate output for a 68030. This is the default when the compiler is
10257configured for 68030-based systems.
10258
10259@item -m68040
10260@opindex m68040
10261Generate output for a 68040. This is the default when the compiler is
10262configured for 68040-based systems.
10263
10264This option inhibits the use of 68881/68882 instructions that have to be
10265emulated by software on the 68040. Use this option if your 68040 does not
10266have code to emulate those instructions.
10267
10268@item -m68060
10269@opindex m68060
10270Generate output for a 68060. This is the default when the compiler is
10271configured for 68060-based systems.
10272
10273This option inhibits the use of 68020 and 68881/68882 instructions that
10274have to be emulated by software on the 68060. Use this option if your 68060
10275does not have code to emulate those instructions.
10276
10277@item -mcpu32
10278@opindex mcpu32
10279Generate output for a CPU32. This is the default
10280when the compiler is configured for CPU32-based systems.
10281
10282Use this option for microcontrollers with a
10283CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
1028468336, 68340, 68341, 68349 and 68360.
10285
10286@item -m5200
10287@opindex m5200
10288Generate output for a 520X ``coldfire'' family cpu. This is the default
10289when the compiler is configured for 520X-based systems.
10290
10291Use this option for microcontroller with a 5200 core, including
10292the MCF5202, MCF5203, MCF5204 and MCF5202.
10293
10294@item -mcfv4e
10295@opindex mcfv4e
10296Generate output for a ColdFire V4e family cpu (e.g.@: 547x/548x).
10297This includes use of hardware floating point instructions.
10298
10299@item -m68020-40
10300@opindex m68020-40
10301Generate output for a 68040, without using any of the new instructions.
10302This results in code which can run relatively efficiently on either a
1030368020/68881 or a 68030 or a 68040. The generated code does use the
1030468881 instructions that are emulated on the 68040.
10305
10306@item -m68020-60
10307@opindex m68020-60
10308Generate output for a 68060, without using any of the new instructions.
10309This results in code which can run relatively efficiently on either a
1031068020/68881 or a 68030 or a 68040. The generated code does use the
1031168881 instructions that are emulated on the 68060.
10312
10313@item -msoft-float
10314@opindex msoft-float
10315Generate output containing library calls for floating point.
10316@strong{Warning:} the requisite libraries are not available for all m68k
10317targets. Normally the facilities of the machine's usual C compiler are
10318used, but this can't be done directly in cross-compilation. You must
10319make your own arrangements to provide suitable library functions for
10320cross-compilation. The embedded targets @samp{m68k-*-aout} and
10321@samp{m68k-*-coff} do provide software floating point support.
10322
10323@item -mshort
10324@opindex mshort
10325Consider type @code{int} to be 16 bits wide, like @code{short int}.
10326Additionally, parameters passed on the stack are also aligned to a
1032716-bit boundary even on targets whose API mandates promotion to 32-bit.
10328
10329@item -mnobitfield
10330@opindex mnobitfield
10331Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
10332and @option{-m5200} options imply @w{@option{-mnobitfield}}.
10333
10334@item -mbitfield
10335@opindex mbitfield
10336Do use the bit-field instructions. The @option{-m68020} option implies
10337@option{-mbitfield}. This is the default if you use a configuration
10338designed for a 68020.
10339
10340@item -mrtd
10341@opindex mrtd
10342Use a different function-calling convention, in which functions
10343that take a fixed number of arguments return with the @code{rtd}
10344instruction, which pops their arguments while returning. This
10345saves one instruction in the caller since there is no need to pop
10346the arguments there.
10347
10348This calling convention is incompatible with the one normally
10349used on Unix, so you cannot use it if you need to call libraries
10350compiled with the Unix compiler.
10351
10352Also, you must provide function prototypes for all functions that
10353take variable numbers of arguments (including @code{printf});
10354otherwise incorrect code will be generated for calls to those
10355functions.
10356
10357In addition, seriously incorrect code will result if you call a
10358function with too many arguments. (Normally, extra arguments are
10359harmlessly ignored.)
10360
10361The @code{rtd} instruction is supported by the 68010, 68020, 68030,
1036268040, 68060 and CPU32 processors, but not by the 68000 or 5200.
10363
10364@item -malign-int
10365@itemx -mno-align-int
10366@opindex malign-int
10367@opindex mno-align-int
10368Control whether GCC aligns @code{int}, @code{long}, @code{long long},
10369@code{float}, @code{double}, and @code{long double} variables on a 32-bit
10370boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
10371Aligning variables on 32-bit boundaries produces code that runs somewhat
10372faster on processors with 32-bit busses at the expense of more memory.
10373
10374@strong{Warning:} if you use the @option{-malign-int} switch, GCC will
10375align structures containing the above types differently than
10376most published application binary interface specifications for the m68k.
10377
10378@item -mpcrel
10379@opindex mpcrel
10380Use the pc-relative addressing mode of the 68000 directly, instead of
10381using a global offset table. At present, this option implies @option{-fpic},
10382allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
10383not presently supported with @option{-mpcrel}, though this could be supported for
1038468020 and higher processors.
10385
10386@item -mno-strict-align
10387@itemx -mstrict-align
10388@opindex mno-strict-align
10389@opindex mstrict-align
10390Do not (do) assume that unaligned memory references will be handled by
10391the system.
10392
10393@item -msep-data
10394Generate code that allows the data segment to be located in a different
10395area of memory from the text segment. This allows for execute in place in
10396an environment without virtual memory management. This option implies
10397@option{-fPIC}.
10398
10399@item -mno-sep-data
10400Generate code that assumes that the data segment follows the text segment.
10401This is the default.
10402
10403@item -mid-shared-library
10404Generate code that supports shared libraries via the library ID method.
10405This allows for execute in place and shared libraries in an environment
10406without virtual memory management. This option implies @option{-fPIC}.
10407
10408@item -mno-id-shared-library
10409Generate code that doesn't assume ID based shared libraries are being used.
10410This is the default.
10411
10412@item -mshared-library-id=n
10413Specified the identification number of the ID based shared library being
10414compiled. Specifying a value of 0 will generate more compact code, specifying
10415other values will force the allocation of that number to the current
10416library but is no more space or time efficient than omitting this option.
10417
10418@end table
10419
10420@node M68hc1x Options
10421@subsection M68hc1x Options
10422@cindex M68hc1x options
10423
10424These are the @samp{-m} options defined for the 68hc11 and 68hc12
10425microcontrollers. The default values for these options depends on
10426which style of microcontroller was selected when the compiler was configured;
10427the defaults for the most common choices are given below.
10428
10429@table @gcctabopt
10430@item -m6811
10431@itemx -m68hc11
10432@opindex m6811
10433@opindex m68hc11
10434Generate output for a 68HC11. This is the default
10435when the compiler is configured for 68HC11-based systems.
10436
10437@item -m6812
10438@itemx -m68hc12
10439@opindex m6812
10440@opindex m68hc12
10441Generate output for a 68HC12. This is the default
10442when the compiler is configured for 68HC12-based systems.
10443
10444@item -m68S12
10445@itemx -m68hcs12
10446@opindex m68S12
10447@opindex m68hcs12
10448Generate output for a 68HCS12.
10449
10450@item -mauto-incdec
10451@opindex mauto-incdec
10452Enable the use of 68HC12 pre and post auto-increment and auto-decrement
10453addressing modes.
10454
10455@item -minmax
10456@itemx -nominmax
10457@opindex minmax
10458@opindex mnominmax
10459Enable the use of 68HC12 min and max instructions.
10460
10461@item -mlong-calls
10462@itemx -mno-long-calls
10463@opindex mlong-calls
10464@opindex mno-long-calls
10465Treat all calls as being far away (near). If calls are assumed to be
10466far away, the compiler will use the @code{call} instruction to
10467call a function and the @code{rtc} instruction for returning.
10468
10469@item -mshort
10470@opindex mshort
10471Consider type @code{int} to be 16 bits wide, like @code{short int}.
10472
10473@item -msoft-reg-count=@var{count}
10474@opindex msoft-reg-count
10475Specify the number of pseudo-soft registers which are used for the
10476code generation. The maximum number is 32. Using more pseudo-soft
10477register may or may not result in better code depending on the program.
10478The default is 4 for 68HC11 and 2 for 68HC12.
10479
10480@end table
10481
10482@node MCore Options
10483@subsection MCore Options
10484@cindex MCore options
10485
10486These are the @samp{-m} options defined for the Motorola M*Core
10487processors.
10488
10489@table @gcctabopt
10490
10491@item -mhardlit
10492@itemx -mno-hardlit
10493@opindex mhardlit
10494@opindex mno-hardlit
10495Inline constants into the code stream if it can be done in two
10496instructions or less.
10497
10498@item -mdiv
10499@itemx -mno-div
10500@opindex mdiv
10501@opindex mno-div
10502Use the divide instruction. (Enabled by default).
10503
10504@item -mrelax-immediate
10505@itemx -mno-relax-immediate
10506@opindex mrelax-immediate
10507@opindex mno-relax-immediate
10508Allow arbitrary sized immediates in bit operations.
10509
10510@item -mwide-bitfields
10511@itemx -mno-wide-bitfields
10512@opindex mwide-bitfields
10513@opindex mno-wide-bitfields
10514Always treat bit-fields as int-sized.
10515
10516@item -m4byte-functions
10517@itemx -mno-4byte-functions
10518@opindex m4byte-functions
10519@opindex mno-4byte-functions
10520Force all functions to be aligned to a four byte boundary.
10521
10522@item -mcallgraph-data
10523@itemx -mno-callgraph-data
10524@opindex mcallgraph-data
10525@opindex mno-callgraph-data
10526Emit callgraph information.
10527
10528@item -mslow-bytes
10529@itemx -mno-slow-bytes
10530@opindex mslow-bytes
10531@opindex mno-slow-bytes
10532Prefer word access when reading byte quantities.
10533
10534@item -mlittle-endian
10535@itemx -mbig-endian
10536@opindex mlittle-endian
10537@opindex mbig-endian
10538Generate code for a little endian target.
10539
10540@item -m210
10541@itemx -m340
10542@opindex m210
10543@opindex m340
10544Generate code for the 210 processor.
10545@end table
10546
10547@node MIPS Options
10548@subsection MIPS Options
10549@cindex MIPS options
10550
10551@table @gcctabopt
10552
10553@item -EB
10554@opindex EB
10555Generate big-endian code.
10556
10557@item -EL
10558@opindex EL
10559Generate little-endian code. This is the default for @samp{mips*el-*-*}
10560configurations.
10561
10562@item -march=@var{arch}
10563@opindex march
10564Generate code that will run on @var{arch}, which can be the name of a
10565generic MIPS ISA, or the name of a particular processor.
10566The ISA names are:
10567@samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
10568@samp{mips32}, @samp{mips32r2}, and @samp{mips64}.
10569The processor names are:
10570@samp{4kc}, @samp{4km}, @samp{4kp},
10571@samp{5kc}, @samp{5kf},
10572@samp{20kc},
10573@samp{24k}, @samp{24kc}, @samp{24kf}, @samp{24kx},
10574@samp{m4k},
10575@samp{orion},
10576@samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
10577@samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000},
10578@samp{rm7000}, @samp{rm9000},
10579@samp{sb1},
10580@samp{sr71000},
10581@samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
10582@samp{vr5000}, @samp{vr5400} and @samp{vr5500}.
10583The special value @samp{from-abi} selects the
10584most compatible architecture for the selected ABI (that is,
10585@samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
10586
10587In processor names, a final @samp{000} can be abbreviated as @samp{k}
10588(for example, @samp{-march=r2k}). Prefixes are optional, and
10589@samp{vr} may be written @samp{r}.
10590
10591GCC defines two macros based on the value of this option. The first
10592is @samp{_MIPS_ARCH}, which gives the name of target architecture, as
10593a string. The second has the form @samp{_MIPS_ARCH_@var{foo}},
10594where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@.
10595For example, @samp{-march=r2000} will set @samp{_MIPS_ARCH}
10596to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}.
10597
10598Note that the @samp{_MIPS_ARCH} macro uses the processor names given
10599above. In other words, it will have the full prefix and will not
10600abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},
10601the macro names the resolved architecture (either @samp{"mips1"} or
10602@samp{"mips3"}). It names the default architecture when no
10603@option{-march} option is given.
10604
10605@item -mtune=@var{arch}
10606@opindex mtune
10607Optimize for @var{arch}. Among other things, this option controls
10608the way instructions are scheduled, and the perceived cost of arithmetic
10609operations. The list of @var{arch} values is the same as for
10610@option{-march}.
10611
10612When this option is not used, GCC will optimize for the processor
10613specified by @option{-march}. By using @option{-march} and
10614@option{-mtune} together, it is possible to generate code that will
10615run on a family of processors, but optimize the code for one
10616particular member of that family.
10617
10618@samp{-mtune} defines the macros @samp{_MIPS_TUNE} and
10619@samp{_MIPS_TUNE_@var{foo}}, which work in the same way as the
10620@samp{-march} ones described above.
10621
10622@item -mips1
10623@opindex mips1
10624Equivalent to @samp{-march=mips1}.
10625
10626@item -mips2
10627@opindex mips2
10628Equivalent to @samp{-march=mips2}.
10629
10630@item -mips3
10631@opindex mips3
10632Equivalent to @samp{-march=mips3}.
10633
10634@item -mips4
10635@opindex mips4
10636Equivalent to @samp{-march=mips4}.
10637
10638@item -mips32
10639@opindex mips32
10640Equivalent to @samp{-march=mips32}.
10641
10642@item -mips32r2
10643@opindex mips32r2
10644Equivalent to @samp{-march=mips32r2}.
10645
10646@item -mips64
10647@opindex mips64
10648Equivalent to @samp{-march=mips64}.
10649
10650@item -mips16
10651@itemx -mno-mips16
10652@opindex mips16
10653@opindex mno-mips16
10654Generate (do not generate) MIPS16 code. If GCC is targetting a
10655MIPS32 or MIPS64 architecture, it will make use of the MIPS16e ASE@.
10656
10657@item -mabi=32
10658@itemx -mabi=o64
10659@itemx -mabi=n32
10660@itemx -mabi=64
10661@itemx -mabi=eabi
10662@opindex mabi=32
10663@opindex mabi=o64
10664@opindex mabi=n32
10665@opindex mabi=64
10666@opindex mabi=eabi
10667Generate code for the given ABI@.
10668
10669Note that the EABI has a 32-bit and a 64-bit variant. GCC normally
10670generates 64-bit code when you select a 64-bit architecture, but you
10671can use @option{-mgp32} to get 32-bit code instead.
10672
10673For information about the O64 ABI, see
10674@w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
10675
10676@item -mabicalls
10677@itemx -mno-abicalls
10678@opindex mabicalls
10679@opindex mno-abicalls
10680Generate (do not generate) code that is suitable for SVR4-style
10681dynamic objects. @option{-mabicalls} is the default for SVR4-based
10682systems.
10683
10684@item -mshared
10685@itemx -mno-shared
10686Generate (do not generate) code that is fully position-independent,
10687and that can therefore be linked into shared libraries. This option
10688only affects @option{-mabicalls}.
10689
10690All @option{-mabicalls} code has traditionally been position-independent,
10691regardless of options like @option{-fPIC} and @option{-fpic}. However,
10692as an extension, the GNU toolchain allows executables to use absolute
10693accesses for locally-binding symbols. It can also use shorter GP
10694initialization sequences and generate direct calls to locally-defined
10695functions. This mode is selected by @option{-mno-shared}.
10696
10697@option{-mno-shared} depends on binutils 2.16 or higher and generates
10698objects that can only be linked by the GNU linker. However, the option
10699does not affect the ABI of the final executable; it only affects the ABI
10700of relocatable objects. Using @option{-mno-shared} will generally make
10701executables both smaller and quicker.
10702
10703@option{-mshared} is the default.
10704
10705@item -mxgot
10706@itemx -mno-xgot
10707@opindex mxgot
10708@opindex mno-xgot
10709Lift (do not lift) the usual restrictions on the size of the global
10710offset table.
10711
10712GCC normally uses a single instruction to load values from the GOT@.
10713While this is relatively efficient, it will only work if the GOT
10714is smaller than about 64k. Anything larger will cause the linker
10715to report an error such as:
10716
10717@cindex relocation truncated to fit (MIPS)
10718@smallexample
10719relocation truncated to fit: R_MIPS_GOT16 foobar
10720@end smallexample
10721
10722If this happens, you should recompile your code with @option{-mxgot}.
10723It should then work with very large GOTs, although it will also be
10724less efficient, since it will take three instructions to fetch the
10725value of a global symbol.
10726
10727Note that some linkers can create multiple GOTs. If you have such a
10728linker, you should only need to use @option{-mxgot} when a single object
10729file accesses more than 64k's worth of GOT entries. Very few do.
10730
10731These options have no effect unless GCC is generating position
10732independent code.
10733
10734@item -mgp32
10735@opindex mgp32
10736Assume that general-purpose registers are 32 bits wide.
10737
10738@item -mgp64
10739@opindex mgp64
10740Assume that general-purpose registers are 64 bits wide.
10741
10742@item -mfp32
10743@opindex mfp32
10744Assume that floating-point registers are 32 bits wide.
10745
10746@item -mfp64
10747@opindex mfp64
10748Assume that floating-point registers are 64 bits wide.
10749
10750@item -mhard-float
10751@opindex mhard-float
10752Use floating-point coprocessor instructions.
10753
10754@item -msoft-float
10755@opindex msoft-float
10756Do not use floating-point coprocessor instructions. Implement
10757floating-point calculations using library calls instead.
10758
10759@item -msingle-float
10760@opindex msingle-float
10761Assume that the floating-point coprocessor only supports single-precision
10762operations.
10763
10764@itemx -mdouble-float
10765@opindex mdouble-float
10766Assume that the floating-point coprocessor supports double-precision
10767operations. This is the default.
10768
10769@itemx -mdsp
10770@itemx -mno-dsp
10771@opindex mdsp
10772@opindex mno-dsp
10773Use (do not use) the MIPS DSP ASE. @xref{MIPS DSP Built-in Functions}.
10774
10775@itemx -mpaired-single
10776@itemx -mno-paired-single
10777@opindex mpaired-single
10778@opindex mno-paired-single
10779Use (do not use) paired-single floating-point instructions.
10780@xref{MIPS Paired-Single Support}. This option can only be used
10781when generating 64-bit code and requires hardware floating-point
10782support to be enabled.
10783
10784@itemx -mips3d
10785@itemx -mno-mips3d
10786@opindex mips3d
10787@opindex mno-mips3d
10788Use (do not use) the MIPS-3D ASE@. @xref{MIPS-3D Built-in Functions}.
10789The option @option{-mips3d} implies @option{-mpaired-single}.
10790
10791@item -mlong64
10792@opindex mlong64
10793Force @code{long} types to be 64 bits wide. See @option{-mlong32} for
10794an explanation of the default and the way that the pointer size is
10795determined.
10796
10797@item -mlong32
10798@opindex mlong32
10799Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
10800
10801The default size of @code{int}s, @code{long}s and pointers depends on
10802the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI
10803uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
1080432-bit @code{long}s. Pointers are the same size as @code{long}s,
10805or the same size as integer registers, whichever is smaller.
10806
10807@item -msym32
10808@itemx -mno-sym32
10809@opindex msym32
10810@opindex mno-sym32
10811Assume (do not assume) that all symbols have 32-bit values, regardless
10812of the selected ABI@. This option is useful in combination with
10813@option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
10814to generate shorter and faster references to symbolic addresses.
10815
10816@item -G @var{num}
10817@opindex G
10818@cindex smaller data references (MIPS)
10819@cindex gp-relative references (MIPS)
10820Put global and static items less than or equal to @var{num} bytes into
10821the small data or bss section instead of the normal data or bss section.
10822This allows the data to be accessed using a single instruction.
10823
10824All modules should be compiled with the same @option{-G @var{num}}
10825value.
10826
10827@item -membedded-data
10828@itemx -mno-embedded-data
10829@opindex membedded-data
10830@opindex mno-embedded-data
10831Allocate variables to the read-only data section first if possible, then
10832next in the small data section if possible, otherwise in data. This gives
10833slightly slower code than the default, but reduces the amount of RAM required
10834when executing, and thus may be preferred for some embedded systems.
10835
10836@item -muninit-const-in-rodata
10837@itemx -mno-uninit-const-in-rodata
10838@opindex muninit-const-in-rodata
10839@opindex mno-uninit-const-in-rodata
10840Put uninitialized @code{const} variables in the read-only data section.
10841This option is only meaningful in conjunction with @option{-membedded-data}.
10842
10843@item -msplit-addresses
10844@itemx -mno-split-addresses
10845@opindex msplit-addresses
10846@opindex mno-split-addresses
10847Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
10848relocation operators. This option has been superseded by
10849@option{-mexplicit-relocs} but is retained for backwards compatibility.
10850
10851@item -mexplicit-relocs
10852@itemx -mno-explicit-relocs
10853@opindex mexplicit-relocs
10854@opindex mno-explicit-relocs
10855Use (do not use) assembler relocation operators when dealing with symbolic
10856addresses. The alternative, selected by @option{-mno-explicit-relocs},
10857is to use assembler macros instead.
10858
10859@option{-mexplicit-relocs} is the default if GCC was configured
10860to use an assembler that supports relocation operators.
10861
10862@item -mcheck-zero-division
10863@itemx -mno-check-zero-division
10864@opindex mcheck-zero-division
10865@opindex mno-check-zero-division
10866Trap (do not trap) on integer division by zero. The default is
10867@option{-mcheck-zero-division}.
10868
10869@item -mdivide-traps
10870@itemx -mdivide-breaks
10871@opindex mdivide-traps
10872@opindex mdivide-breaks
10873MIPS systems check for division by zero by generating either a
10874conditional trap or a break instruction. Using traps results in
10875smaller code, but is only supported on MIPS II and later. Also, some
10876versions of the Linux kernel have a bug that prevents trap from
10877generating the proper signal (@code{SIGFPE}). Use @option{-mdivide-traps} to
10878allow conditional traps on architectures that support them and
10879@option{-mdivide-breaks} to force the use of breaks.
10880
10881The default is usually @option{-mdivide-traps}, but this can be
10882overridden at configure time using @option{--with-divide=breaks}.
10883Divide-by-zero checks can be completely disabled using
10884@option{-mno-check-zero-division}.
10885
10886@item -mmemcpy
10887@itemx -mno-memcpy
10888@opindex mmemcpy
10889@opindex mno-memcpy
10890Force (do not force) the use of @code{memcpy()} for non-trivial block
10891moves. The default is @option{-mno-memcpy}, which allows GCC to inline
10892most constant-sized copies.
10893
10894@item -mlong-calls
10895@itemx -mno-long-calls
10896@opindex mlong-calls
10897@opindex mno-long-calls
10898Disable (do not disable) use of the @code{jal} instruction. Calling
10899functions using @code{jal} is more efficient but requires the caller
10900and callee to be in the same 256 megabyte segment.
10901
10902This option has no effect on abicalls code. The default is
10903@option{-mno-long-calls}.
10904
10905@item -mmad
10906@itemx -mno-mad
10907@opindex mmad
10908@opindex mno-mad
10909Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
10910instructions, as provided by the R4650 ISA@.
10911
10912@item -mfused-madd
10913@itemx -mno-fused-madd
10914@opindex mfused-madd
10915@opindex mno-fused-madd
10916Enable (disable) use of the floating point multiply-accumulate
10917instructions, when they are available. The default is
10918@option{-mfused-madd}.
10919
10920When multiply-accumulate instructions are used, the intermediate
10921product is calculated to infinite precision and is not subject to
10922the FCSR Flush to Zero bit. This may be undesirable in some
10923circumstances.
10924
10925@item -nocpp
10926@opindex nocpp
10927Tell the MIPS assembler to not run its preprocessor over user
10928assembler files (with a @samp{.s} suffix) when assembling them.
10929
10930@item -mfix-r4000
10931@itemx -mno-fix-r4000
10932@opindex mfix-r4000
10933@opindex mno-fix-r4000
10934Work around certain R4000 CPU errata:
10935@itemize @minus
10936@item
10937A double-word or a variable shift may give an incorrect result if executed
10938immediately after starting an integer division.
10939@item
10940A double-word or a variable shift may give an incorrect result if executed
10941while an integer multiplication is in progress.
10942@item
10943An integer division may give an incorrect result if started in a delay slot
10944of a taken branch or a jump.
10945@end itemize
10946
10947@item -mfix-r4400
10948@itemx -mno-fix-r4400
10949@opindex mfix-r4400
10950@opindex mno-fix-r4400
10951Work around certain R4400 CPU errata:
10952@itemize @minus
10953@item
10954A double-word or a variable shift may give an incorrect result if executed
10955immediately after starting an integer division.
10956@end itemize
10957
10958@item -mfix-vr4120
10959@itemx -mno-fix-vr4120
10960@opindex mfix-vr4120
10961Work around certain VR4120 errata:
10962@itemize @minus
10963@item
10964@code{dmultu} does not always produce the correct result.
10965@item
10966@code{div} and @code{ddiv} do not always produce the correct result if one
10967of the operands is negative.
10968@end itemize
10969The workarounds for the division errata rely on special functions in
10970@file{libgcc.a}. At present, these functions are only provided by
10971the @code{mips64vr*-elf} configurations.
10972
10973Other VR4120 errata require a nop to be inserted between certain pairs of
10974instructions. These errata are handled by the assembler, not by GCC itself.
10975
10976@item -mfix-vr4130
10977@opindex mfix-vr4130
10978Work around the VR4130 @code{mflo}/@code{mfhi} errata. The
10979workarounds are implemented by the assembler rather than by GCC,
10980although GCC will avoid using @code{mflo} and @code{mfhi} if the
10981VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
10982instructions are available instead.
10983
10984@item -mfix-sb1
10985@itemx -mno-fix-sb1
10986@opindex mfix-sb1
10987Work around certain SB-1 CPU core errata.
10988(This flag currently works around the SB-1 revision 2
10989``F1'' and ``F2'' floating point errata.)
10990
10991@item -mflush-func=@var{func}
10992@itemx -mno-flush-func
10993@opindex mflush-func
10994Specifies the function to call to flush the I and D caches, or to not
10995call any such function. If called, the function must take the same
10996arguments as the common @code{_flush_func()}, that is, the address of the
10997memory range for which the cache is being flushed, the size of the
10998memory range, and the number 3 (to flush both caches). The default
10999depends on the target GCC was configured for, but commonly is either
11000@samp{_flush_func} or @samp{__cpu_flush}.
11001
11002@item -mbranch-likely
11003@itemx -mno-branch-likely
11004@opindex mbranch-likely
11005@opindex mno-branch-likely
11006Enable or disable use of Branch Likely instructions, regardless of the
11007default for the selected architecture. By default, Branch Likely
11008instructions may be generated if they are supported by the selected
11009architecture. An exception is for the MIPS32 and MIPS64 architectures
11010and processors which implement those architectures; for those, Branch
11011Likely instructions will not be generated by default because the MIPS32
11012and MIPS64 architectures specifically deprecate their use.
11013
11014@item -mfp-exceptions
11015@itemx -mno-fp-exceptions
11016@opindex mfp-exceptions
11017Specifies whether FP exceptions are enabled. This affects how we schedule
11018FP instructions for some processors. The default is that FP exceptions are
11019enabled.
11020
11021For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
1102264-bit code, then we can use both FP pipes. Otherwise, we can only use one
11023FP pipe.
11024
11025@item -mvr4130-align
11026@itemx -mno-vr4130-align
11027@opindex mvr4130-align
11028The VR4130 pipeline is two-way superscalar, but can only issue two
11029instructions together if the first one is 8-byte aligned. When this
11030option is enabled, GCC will align pairs of instructions that it
11031thinks should execute in parallel.
11032
11033This option only has an effect when optimizing for the VR4130.
11034It normally makes code faster, but at the expense of making it bigger.
11035It is enabled by default at optimization level @option{-O3}.
11036@end table
11037
11038@node MMIX Options
11039@subsection MMIX Options
11040@cindex MMIX Options
11041
11042These options are defined for the MMIX:
11043
11044@table @gcctabopt
11045@item -mlibfuncs
11046@itemx -mno-libfuncs
11047@opindex mlibfuncs
11048@opindex mno-libfuncs
11049Specify that intrinsic library functions are being compiled, passing all
11050values in registers, no matter the size.
11051
11052@item -mepsilon
11053@itemx -mno-epsilon
11054@opindex mepsilon
11055@opindex mno-epsilon
11056Generate floating-point comparison instructions that compare with respect
11057to the @code{rE} epsilon register.
11058
11059@item -mabi=mmixware
11060@itemx -mabi=gnu
11061@opindex mabi-mmixware
11062@opindex mabi=gnu
11063Generate code that passes function parameters and return values that (in
11064the called function) are seen as registers @code{$0} and up, as opposed to
11065the GNU ABI which uses global registers @code{$231} and up.
11066
11067@item -mzero-extend
11068@itemx -mno-zero-extend
11069@opindex mzero-extend
11070@opindex mno-zero-extend
11071When reading data from memory in sizes shorter than 64 bits, use (do not
11072use) zero-extending load instructions by default, rather than
11073sign-extending ones.
11074
11075@item -mknuthdiv
11076@itemx -mno-knuthdiv
11077@opindex mknuthdiv
11078@opindex mno-knuthdiv
11079Make the result of a division yielding a remainder have the same sign as
11080the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
11081remainder follows the sign of the dividend. Both methods are
11082arithmetically valid, the latter being almost exclusively used.
11083
11084@item -mtoplevel-symbols
11085@itemx -mno-toplevel-symbols
11086@opindex mtoplevel-symbols
11087@opindex mno-toplevel-symbols
11088Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
11089code can be used with the @code{PREFIX} assembly directive.
11090
11091@item -melf
11092@opindex melf
11093Generate an executable in the ELF format, rather than the default
11094@samp{mmo} format used by the @command{mmix} simulator.
11095
11096@item -mbranch-predict
11097@itemx -mno-branch-predict
11098@opindex mbranch-predict
11099@opindex mno-branch-predict
11100Use (do not use) the probable-branch instructions, when static branch
11101prediction indicates a probable branch.
11102
11103@item -mbase-addresses
11104@itemx -mno-base-addresses
11105@opindex mbase-addresses
11106@opindex mno-base-addresses
11107Generate (do not generate) code that uses @emph{base addresses}. Using a
11108base address automatically generates a request (handled by the assembler
11109and the linker) for a constant to be set up in a global register. The
11110register is used for one or more base address requests within the range 0
11111to 255 from the value held in the register. The generally leads to short
11112and fast code, but the number of different data items that can be
11113addressed is limited. This means that a program that uses lots of static
11114data may require @option{-mno-base-addresses}.
11115
11116@item -msingle-exit
11117@itemx -mno-single-exit
11118@opindex msingle-exit
11119@opindex mno-single-exit
11120Force (do not force) generated code to have a single exit point in each
11121function.
11122@end table
11123
11124@node MN10300 Options
11125@subsection MN10300 Options
11126@cindex MN10300 options
11127
11128These @option{-m} options are defined for Matsushita MN10300 architectures:
11129
11130@table @gcctabopt
11131@item -mmult-bug
11132@opindex mmult-bug
11133Generate code to avoid bugs in the multiply instructions for the MN10300
11134processors. This is the default.
11135
11136@item -mno-mult-bug
11137@opindex mno-mult-bug
11138Do not generate code to avoid bugs in the multiply instructions for the
11139MN10300 processors.
11140
11141@item -mam33
11142@opindex mam33
11143Generate code which uses features specific to the AM33 processor.
11144
11145@item -mno-am33
11146@opindex mno-am33
11147Do not generate code which uses features specific to the AM33 processor. This
11148is the default.
11149
11150@item -mreturn-pointer-on-d0
11151@opindex mreturn-pointer-on-d0
11152When generating a function which returns a pointer, return the pointer
11153in both @code{a0} and @code{d0}. Otherwise, the pointer is returned
11154only in a0, and attempts to call such functions without a prototype
11155would result in errors. Note that this option is on by default; use
11156@option{-mno-return-pointer-on-d0} to disable it.
11157
11158@item -mno-crt0
11159@opindex mno-crt0
11160Do not link in the C run-time initialization object file.
11161
11162@item -mrelax
11163@opindex mrelax
11164Indicate to the linker that it should perform a relaxation optimization pass
11165to shorten branches, calls and absolute memory addresses. This option only
11166has an effect when used on the command line for the final link step.
11167
11168This option makes symbolic debugging impossible.
11169@end table
11170
11171@node MT Options
11172@subsection MT Options
11173@cindex MT options
11174
11175These @option{-m} options are defined for Morpho MT architectures:
11176
11177@table @gcctabopt
11178
11179@item -march=@var{cpu-type}
11180@opindex march
11181Generate code that will run on @var{cpu-type}, which is the name of a system
11182representing a certain processor type. Possible values for
11183@var{cpu-type} are @samp{ms1-64-001}, @samp{ms1-16-002},
11184@samp{ms1-16-003} and @samp{ms2}.
11185
11186When this option is not used, the default is @option{-march=ms1-16-002}.
11187
11188@item -mbacc
11189@opindex mbacc
11190Use byte loads and stores when generating code.
11191
11192@item -mno-bacc
11193@opindex mno-bacc
11194Do not use byte loads and stores when generating code.
11195
11196@item -msim
11197@opindex msim
11198Use simulator runtime
11199
11200@item -mno-crt0
11201@opindex mno-crt0
11202Do not link in the C run-time initialization object file
11203@file{crti.o}. Other run-time initialization and termination files
11204such as @file{startup.o} and @file{exit.o} are still included on the
11205linker command line.
11206
11207@end table
11208
11209@node PDP-11 Options
11210@subsection PDP-11 Options
11211@cindex PDP-11 Options
11212
11213These options are defined for the PDP-11:
11214
11215@table @gcctabopt
11216@item -mfpu
11217@opindex mfpu
11218Use hardware FPP floating point. This is the default. (FIS floating
11219point on the PDP-11/40 is not supported.)
11220
11221@item -msoft-float
11222@opindex msoft-float
11223Do not use hardware floating point.
11224
11225@item -mac0
11226@opindex mac0
11227Return floating-point results in ac0 (fr0 in Unix assembler syntax).
11228
11229@item -mno-ac0
11230@opindex mno-ac0
11231Return floating-point results in memory. This is the default.
11232
11233@item -m40
11234@opindex m40
11235Generate code for a PDP-11/40.
11236
11237@item -m45
11238@opindex m45
11239Generate code for a PDP-11/45. This is the default.
11240
11241@item -m10
11242@opindex m10
11243Generate code for a PDP-11/10.
11244
11245@item -mbcopy-builtin
11246@opindex bcopy-builtin
11247Use inline @code{movmemhi} patterns for copying memory. This is the
11248default.
11249
11250@item -mbcopy
11251@opindex mbcopy
11252Do not use inline @code{movmemhi} patterns for copying memory.
11253
11254@item -mint16
11255@itemx -mno-int32
11256@opindex mint16
11257@opindex mno-int32
11258Use 16-bit @code{int}. This is the default.
11259
11260@item -mint32
11261@itemx -mno-int16
11262@opindex mint32
11263@opindex mno-int16
11264Use 32-bit @code{int}.
11265
11266@item -mfloat64
11267@itemx -mno-float32
11268@opindex mfloat64
11269@opindex mno-float32
11270Use 64-bit @code{float}. This is the default.
11271
11272@item -mfloat32
11273@itemx -mno-float64
11274@opindex mfloat32
11275@opindex mno-float64
11276Use 32-bit @code{float}.
11277
11278@item -mabshi
11279@opindex mabshi
11280Use @code{abshi2} pattern. This is the default.
11281
11282@item -mno-abshi
11283@opindex mno-abshi
11284Do not use @code{abshi2} pattern.
11285
11286@item -mbranch-expensive
11287@opindex mbranch-expensive
11288Pretend that branches are expensive. This is for experimenting with
11289code generation only.
11290
11291@item -mbranch-cheap
11292@opindex mbranch-cheap
11293Do not pretend that branches are expensive. This is the default.
11294
11295@item -msplit
11296@opindex msplit
11297Generate code for a system with split I&D@.
11298
11299@item -mno-split
11300@opindex mno-split
11301Generate code for a system without split I&D@. This is the default.
11302
11303@item -munix-asm
11304@opindex munix-asm
11305Use Unix assembler syntax. This is the default when configured for
11306@samp{pdp11-*-bsd}.
11307
11308@item -mdec-asm
11309@opindex mdec-asm
11310Use DEC assembler syntax. This is the default when configured for any
11311PDP-11 target other than @samp{pdp11-*-bsd}.
11312@end table
11313
11314@node PowerPC Options
11315@subsection PowerPC Options
11316@cindex PowerPC options
11317
11318These are listed under @xref{RS/6000 and PowerPC Options}.
11319
11320@node RS/6000 and PowerPC Options
11321@subsection IBM RS/6000 and PowerPC Options
11322@cindex RS/6000 and PowerPC Options
11323@cindex IBM RS/6000 and PowerPC Options
11324
11325These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
11326@table @gcctabopt
11327@item -mpower
11328@itemx -mno-power
11329@itemx -mpower2
11330@itemx -mno-power2
11331@itemx -mpowerpc
11332@itemx -mno-powerpc
11333@itemx -mpowerpc-gpopt
11334@itemx -mno-powerpc-gpopt
11335@itemx -mpowerpc-gfxopt
11336@itemx -mno-powerpc-gfxopt
11337@itemx -mpowerpc64
11338@itemx -mno-powerpc64
11339@itemx -mmfcrf
11340@itemx -mno-mfcrf
11341@itemx -mpopcntb
11342@itemx -mno-popcntb
11343@itemx -mfprnd
11344@itemx -mno-fprnd
11345@opindex mpower
11346@opindex mno-power
11347@opindex mpower2
11348@opindex mno-power2
11349@opindex mpowerpc
11350@opindex mno-powerpc
11351@opindex mpowerpc-gpopt
11352@opindex mno-powerpc-gpopt
11353@opindex mpowerpc-gfxopt
11354@opindex mno-powerpc-gfxopt
11355@opindex mpowerpc64
11356@opindex mno-powerpc64
11357@opindex mmfcrf
11358@opindex mno-mfcrf
11359@opindex mpopcntb
11360@opindex mno-popcntb
11361@opindex mfprnd
11362@opindex mno-fprnd
11363GCC supports two related instruction set architectures for the
11364RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those
11365instructions supported by the @samp{rios} chip set used in the original
11366RS/6000 systems and the @dfn{PowerPC} instruction set is the
11367architecture of the Freescale MPC5xx, MPC6xx, MPC8xx microprocessors, and
11368the IBM 4xx, 6xx, and follow-on microprocessors.
11369
11370Neither architecture is a subset of the other. However there is a
11371large common subset of instructions supported by both. An MQ
11372register is included in processors supporting the POWER architecture.
11373
11374You use these options to specify which instructions are available on the
11375processor you are using. The default value of these options is
11376determined when configuring GCC@. Specifying the
11377@option{-mcpu=@var{cpu_type}} overrides the specification of these
11378options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
11379rather than the options listed above.
11380
11381The @option{-mpower} option allows GCC to generate instructions that
11382are found only in the POWER architecture and to use the MQ register.
11383Specifying @option{-mpower2} implies @option{-power} and also allows GCC
11384to generate instructions that are present in the POWER2 architecture but
11385not the original POWER architecture.
11386
11387The @option{-mpowerpc} option allows GCC to generate instructions that
11388are found only in the 32-bit subset of the PowerPC architecture.
11389Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
11390GCC to use the optional PowerPC architecture instructions in the
11391General Purpose group, including floating-point square root. Specifying
11392@option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
11393use the optional PowerPC architecture instructions in the Graphics
11394group, including floating-point select.
11395
11396The @option{-mmfcrf} option allows GCC to generate the move from
11397condition register field instruction implemented on the POWER4
11398processor and other processors that support the PowerPC V2.01
11399architecture.
11400The @option{-mpopcntb} option allows GCC to generate the popcount and
11401double precision FP reciprocal estimate instruction implemented on the
11402POWER5 processor and other processors that support the PowerPC V2.02
11403architecture.
11404The @option{-mfprnd} option allows GCC to generate the FP round to
11405integer instructions implemented on the POWER5+ processor and other
11406processors that support the PowerPC V2.03 architecture.
11407
11408The @option{-mpowerpc64} option allows GCC to generate the additional
1140964-bit instructions that are found in the full PowerPC64 architecture
11410and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
11411@option{-mno-powerpc64}.
11412
11413If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
11414will use only the instructions in the common subset of both
11415architectures plus some special AIX common-mode calls, and will not use
11416the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
11417permits GCC to use any instruction from either architecture and to
11418allow use of the MQ register; specify this for the Motorola MPC601.
11419
11420@item -mnew-mnemonics
11421@itemx -mold-mnemonics
11422@opindex mnew-mnemonics
11423@opindex mold-mnemonics
11424Select which mnemonics to use in the generated assembler code. With
11425@option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
11426the PowerPC architecture. With @option{-mold-mnemonics} it uses the
11427assembler mnemonics defined for the POWER architecture. Instructions
11428defined in only one architecture have only one mnemonic; GCC uses that
11429mnemonic irrespective of which of these options is specified.
11430
11431GCC defaults to the mnemonics appropriate for the architecture in
11432use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
11433value of these option. Unless you are building a cross-compiler, you
11434should normally not specify either @option{-mnew-mnemonics} or
11435@option{-mold-mnemonics}, but should instead accept the default.
11436
11437@item -mcpu=@var{cpu_type}
11438@opindex mcpu
11439Set architecture type, register usage, choice of mnemonics, and
11440instruction scheduling parameters for machine type @var{cpu_type}.
11441Supported values for @var{cpu_type} are @samp{401}, @samp{403},
11442@samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{505},
11443@samp{601}, @samp{602}, @samp{603}, @samp{603e}, @samp{604},
11444@samp{604e}, @samp{620}, @samp{630}, @samp{740}, @samp{7400},
11445@samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
11446@samp{860}, @samp{970}, @samp{8540}, @samp{ec603e}, @samp{G3},
11447@samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3},
11448@samp{power4}, @samp{power5}, @samp{power5+}, @samp{power6},
11449@samp{common}, @samp{powerpc}, @samp{powerpc64},
11450@samp{rios}, @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64}.
11451
11452@option{-mcpu=common} selects a completely generic processor. Code
11453generated under this option will run on any POWER or PowerPC processor.
11454GCC will use only the instructions in the common subset of both
11455architectures, and will not use the MQ register. GCC assumes a generic
11456processor model for scheduling purposes.
11457
11458@option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
11459@option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
11460PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
11461types, with an appropriate, generic processor model assumed for
11462scheduling purposes.
11463
11464The other options specify a specific processor. Code generated under
11465those options will run best on that processor, and may not run at all on
11466others.
11467
11468The @option{-mcpu} options automatically enable or disable the
11469following options: @option{-maltivec}, @option{-mfprnd},
11470@option{-mhard-float}, @option{-mmfcrf}, @option{-mmultiple},
11471@option{-mnew-mnemonics}, @option{-mpopcntb}, @option{-mpower},
11472@option{-mpower2}, @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
11473@option{-mpowerpc-gfxopt}, @option{-mstring}, @option{-mmulhw}, @option{-mdlmzb}.
11474The particular options
11475set for any particular CPU will vary between compiler versions,
11476depending on what setting seems to produce optimal code for that CPU;
11477it doesn't necessarily reflect the actual hardware's capabilities. If
11478you wish to set an individual option to a particular value, you may
11479specify it after the @option{-mcpu} option, like @samp{-mcpu=970
11480-mno-altivec}.
11481
11482On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
11483not enabled or disabled by the @option{-mcpu} option at present because
11484AIX does not have full support for these options. You may still
11485enable or disable them individually if you're sure it'll work in your
11486environment.
11487
11488@item -mtune=@var{cpu_type}
11489@opindex mtune
11490Set the instruction scheduling parameters for machine type
11491@var{cpu_type}, but do not set the architecture type, register usage, or
11492choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
11493values for @var{cpu_type} are used for @option{-mtune} as for
11494@option{-mcpu}. If both are specified, the code generated will use the
11495architecture, registers, and mnemonics set by @option{-mcpu}, but the
11496scheduling parameters set by @option{-mtune}.
11497
11498@item -mswdiv
11499@itemx -mno-swdiv
11500@opindex mswdiv
11501@opindex mno-swdiv
11502Generate code to compute division as reciprocal estimate and iterative
11503refinement, creating opportunities for increased throughput. This
11504feature requires: optional PowerPC Graphics instruction set for single
11505precision and FRE instruction for double precision, assuming divides
11506cannot generate user-visible traps, and the domain values not include
11507Infinities, denormals or zero denominator.
11508
11509@item -maltivec
11510@itemx -mno-altivec
11511@opindex maltivec
11512@opindex mno-altivec
11513Generate code that uses (does not use) AltiVec instructions, and also
11514enable the use of built-in functions that allow more direct access to
11515the AltiVec instruction set. You may also need to set
11516@option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
11517enhancements.
11518
11519@item -mvrsave
11520@item -mno-vrsave
11521@opindex mvrsave
11522@opindex mno-vrsave
11523Generate VRSAVE instructions when generating AltiVec code.
11524
11525@item -msecure-plt
11526@opindex msecure-plt
11527Generate code that allows ld and ld.so to build executables and shared
11528libraries with non-exec .plt and .got sections. This is a PowerPC
1152932-bit SYSV ABI option.
11530
11531@item -mbss-plt
11532@opindex mbss-plt
11533Generate code that uses a BSS .plt section that ld.so fills in, and
11534requires .plt and .got sections that are both writable and executable.
11535This is a PowerPC 32-bit SYSV ABI option.
11536
11537@item -misel
11538@itemx -mno-isel
11539@opindex misel
11540@opindex mno-isel
11541This switch enables or disables the generation of ISEL instructions.
11542
11543@item -misel=@var{yes/no}
11544This switch has been deprecated. Use @option{-misel} and
11545@option{-mno-isel} instead.
11546
11547@item -mspe
11548@itemx -mno-spe
11549@opindex mspe
11550@opindex mno-spe
11551This switch enables or disables the generation of SPE simd
11552instructions.
11553
11554@item -mspe=@var{yes/no}
11555This option has been deprecated. Use @option{-mspe} and
11556@option{-mno-spe} instead.
11557
11558@item -mfloat-gprs=@var{yes/single/double/no}
11559@itemx -mfloat-gprs
11560@opindex mfloat-gprs
11561This switch enables or disables the generation of floating point
11562operations on the general purpose registers for architectures that
11563support it.
11564
11565The argument @var{yes} or @var{single} enables the use of
11566single-precision floating point operations.
11567
11568The argument @var{double} enables the use of single and
11569double-precision floating point operations.
11570
11571The argument @var{no} disables floating point operations on the
11572general purpose registers.
11573
11574This option is currently only available on the MPC854x.
11575
11576@item -m32
11577@itemx -m64
11578@opindex m32
11579@opindex m64
11580Generate code for 32-bit or 64-bit environments of Darwin and SVR4
11581targets (including GNU/Linux). The 32-bit environment sets int, long
11582and pointer to 32 bits and generates code that runs on any PowerPC
11583variant. The 64-bit environment sets int to 32 bits and long and
11584pointer to 64 bits, and generates code for PowerPC64, as for
11585@option{-mpowerpc64}.
11586
11587@item -mfull-toc
11588@itemx -mno-fp-in-toc
11589@itemx -mno-sum-in-toc
11590@itemx -mminimal-toc
11591@opindex mfull-toc
11592@opindex mno-fp-in-toc
11593@opindex mno-sum-in-toc
11594@opindex mminimal-toc
11595Modify generation of the TOC (Table Of Contents), which is created for
11596every executable file. The @option{-mfull-toc} option is selected by
11597default. In that case, GCC will allocate at least one TOC entry for
11598each unique non-automatic variable reference in your program. GCC
11599will also place floating-point constants in the TOC@. However, only
1160016,384 entries are available in the TOC@.
11601
11602If you receive a linker error message that saying you have overflowed
11603the available TOC space, you can reduce the amount of TOC space used
11604with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
11605@option{-mno-fp-in-toc} prevents GCC from putting floating-point
11606constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
11607generate code to calculate the sum of an address and a constant at
11608run-time instead of putting that sum into the TOC@. You may specify one
11609or both of these options. Each causes GCC to produce very slightly
11610slower and larger code at the expense of conserving TOC space.
11611
11612If you still run out of space in the TOC even when you specify both of
11613these options, specify @option{-mminimal-toc} instead. This option causes
11614GCC to make only one TOC entry for every file. When you specify this
11615option, GCC will produce code that is slower and larger but which
11616uses extremely little TOC space. You may wish to use this option
11617only on files that contain less frequently executed code.
11618
11619@item -maix64
11620@itemx -maix32
11621@opindex maix64
11622@opindex maix32
11623Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
11624@code{long} type, and the infrastructure needed to support them.
11625Specifying @option{-maix64} implies @option{-mpowerpc64} and
11626@option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
11627implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
11628
11629@item -mxl-compat
11630@itemx -mno-xl-compat
11631@opindex mxl-compat
11632@opindex mno-xl-compat
11633Produce code that conforms more closely to IBM XL compiler semantics
11634when using AIX-compatible ABI. Pass floating-point arguments to
11635prototyped functions beyond the register save area (RSA) on the stack
11636in addition to argument FPRs. Do not assume that most significant
11637double in 128-bit long double value is properly rounded when comparing
11638values and converting to double. Use XL symbol names for long double
11639support routines.
11640
11641The AIX calling convention was extended but not initially documented to
11642handle an obscure K&R C case of calling a function that takes the
11643address of its arguments with fewer arguments than declared. IBM XL
11644compilers access floating point arguments which do not fit in the
11645RSA from the stack when a subroutine is compiled without
11646optimization. Because always storing floating-point arguments on the
11647stack is inefficient and rarely needed, this option is not enabled by
11648default and only is necessary when calling subroutines compiled by IBM
11649XL compilers without optimization.
11650
11651@item -mpe
11652@opindex mpe
11653Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
11654application written to use message passing with special startup code to
11655enable the application to run. The system must have PE installed in the
11656standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
11657must be overridden with the @option{-specs=} option to specify the
11658appropriate directory location. The Parallel Environment does not
11659support threads, so the @option{-mpe} option and the @option{-pthread}
11660option are incompatible.
11661
11662@item -malign-natural
11663@itemx -malign-power
11664@opindex malign-natural
11665@opindex malign-power
11666On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
11667@option{-malign-natural} overrides the ABI-defined alignment of larger
11668types, such as floating-point doubles, on their natural size-based boundary.
11669The option @option{-malign-power} instructs GCC to follow the ABI-specified
11670alignment rules. GCC defaults to the standard alignment defined in the ABI@.
11671
11672On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
11673is not supported.
11674
11675@item -msoft-float
11676@itemx -mhard-float
11677@opindex msoft-float
11678@opindex mhard-float
11679Generate code that does not use (uses) the floating-point register set.
11680Software floating point emulation is provided if you use the
11681@option{-msoft-float} option, and pass the option to GCC when linking.
11682
11683@item -mmultiple
11684@itemx -mno-multiple
11685@opindex mmultiple
11686@opindex mno-multiple
11687Generate code that uses (does not use) the load multiple word
11688instructions and the store multiple word instructions. These
11689instructions are generated by default on POWER systems, and not
11690generated on PowerPC systems. Do not use @option{-mmultiple} on little
11691endian PowerPC systems, since those instructions do not work when the
11692processor is in little endian mode. The exceptions are PPC740 and
11693PPC750 which permit the instructions usage in little endian mode.
11694
11695@item -mstring
11696@itemx -mno-string
11697@opindex mstring
11698@opindex mno-string
11699Generate code that uses (does not use) the load string instructions
11700and the store string word instructions to save multiple registers and
11701do small block moves. These instructions are generated by default on
11702POWER systems, and not generated on PowerPC systems. Do not use
11703@option{-mstring} on little endian PowerPC systems, since those
11704instructions do not work when the processor is in little endian mode.
11705The exceptions are PPC740 and PPC750 which permit the instructions
11706usage in little endian mode.
11707
11708@item -mupdate
11709@itemx -mno-update
11710@opindex mupdate
11711@opindex mno-update
11712Generate code that uses (does not use) the load or store instructions
11713that update the base register to the address of the calculated memory
11714location. These instructions are generated by default. If you use
11715@option{-mno-update}, there is a small window between the time that the
11716stack pointer is updated and the address of the previous frame is
11717stored, which means code that walks the stack frame across interrupts or
11718signals may get corrupted data.
11719
11720@item -mfused-madd
11721@itemx -mno-fused-madd
11722@opindex mfused-madd
11723@opindex mno-fused-madd
11724Generate code that uses (does not use) the floating point multiply and
11725accumulate instructions. These instructions are generated by default if
11726hardware floating is used.
11727
11728@item -mmulhw
11729@itemx -mno-mulhw
11730@opindex mmulhw
11731@opindex mno-mulhw
11732Generate code that uses (does not use) the half-word multiply and
11733multiply-accumulate instructions on the IBM 405 and 440 processors.
11734These instructions are generated by default when targetting those
11735processors.
11736
11737@item -mdlmzb
11738@itemx -mno-dlmzb
11739@opindex mdlmzb
11740@opindex mno-dlmzb
11741Generate code that uses (does not use) the string-search @samp{dlmzb}
11742instruction on the IBM 405 and 440 processors. This instruction is
11743generated by default when targetting those processors.
11744
11745@item -mno-bit-align
11746@itemx -mbit-align
11747@opindex mno-bit-align
11748@opindex mbit-align
11749On System V.4 and embedded PowerPC systems do not (do) force structures
11750and unions that contain bit-fields to be aligned to the base type of the
11751bit-field.
11752
11753For example, by default a structure containing nothing but 8
11754@code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
11755boundary and have a size of 4 bytes. By using @option{-mno-bit-align},
11756the structure would be aligned to a 1 byte boundary and be one byte in
11757size.
11758
11759@item -mno-strict-align
11760@itemx -mstrict-align
11761@opindex mno-strict-align
11762@opindex mstrict-align
11763On System V.4 and embedded PowerPC systems do not (do) assume that
11764unaligned memory references will be handled by the system.
11765
11766@item -mrelocatable
11767@itemx -mno-relocatable
11768@opindex mrelocatable
11769@opindex mno-relocatable
11770On embedded PowerPC systems generate code that allows (does not allow)
11771the program to be relocated to a different address at runtime. If you
11772use @option{-mrelocatable} on any module, all objects linked together must
11773be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
11774
11775@item -mrelocatable-lib
11776@itemx -mno-relocatable-lib
11777@opindex mrelocatable-lib
11778@opindex mno-relocatable-lib
11779On embedded PowerPC systems generate code that allows (does not allow)
11780the program to be relocated to a different address at runtime. Modules
11781compiled with @option{-mrelocatable-lib} can be linked with either modules
11782compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
11783with modules compiled with the @option{-mrelocatable} options.
11784
11785@item -mno-toc
11786@itemx -mtoc
11787@opindex mno-toc
11788@opindex mtoc
11789On System V.4 and embedded PowerPC systems do not (do) assume that
11790register 2 contains a pointer to a global area pointing to the addresses
11791used in the program.
11792
11793@item -mlittle
11794@itemx -mlittle-endian
11795@opindex mlittle
11796@opindex mlittle-endian
11797On System V.4 and embedded PowerPC systems compile code for the
11798processor in little endian mode. The @option{-mlittle-endian} option is
11799the same as @option{-mlittle}.
11800
11801@item -mbig
11802@itemx -mbig-endian
11803@opindex mbig
11804@opindex mbig-endian
11805On System V.4 and embedded PowerPC systems compile code for the
11806processor in big endian mode. The @option{-mbig-endian} option is
11807the same as @option{-mbig}.
11808
11809@item -mdynamic-no-pic
11810@opindex mdynamic-no-pic
11811On Darwin and Mac OS X systems, compile code so that it is not
11812relocatable, but that its external references are relocatable. The
11813resulting code is suitable for applications, but not shared
11814libraries.
11815
11816@item -mprioritize-restricted-insns=@var{priority}
11817@opindex mprioritize-restricted-insns
11818This option controls the priority that is assigned to
11819dispatch-slot restricted instructions during the second scheduling
11820pass. The argument @var{priority} takes the value @var{0/1/2} to assign
11821@var{no/highest/second-highest} priority to dispatch slot restricted
11822instructions.
11823
11824@item -msched-costly-dep=@var{dependence_type}
11825@opindex msched-costly-dep
11826This option controls which dependences are considered costly
11827by the target during instruction scheduling. The argument
11828@var{dependence_type} takes one of the following values:
11829@var{no}: no dependence is costly,
11830@var{all}: all dependences are costly,
11831@var{true_store_to_load}: a true dependence from store to load is costly,
11832@var{store_to_load}: any dependence from store to load is costly,
11833@var{number}: any dependence which latency >= @var{number} is costly.
11834
11835@item -minsert-sched-nops=@var{scheme}
11836@opindex minsert-sched-nops
11837This option controls which nop insertion scheme will be used during
11838the second scheduling pass. The argument @var{scheme} takes one of the
11839following values:
11840@var{no}: Don't insert nops.
11841@var{pad}: Pad with nops any dispatch group which has vacant issue slots,
11842according to the scheduler's grouping.
11843@var{regroup_exact}: Insert nops to force costly dependent insns into
11844separate groups. Insert exactly as many nops as needed to force an insn
11845to a new group, according to the estimated processor grouping.
11846@var{number}: Insert nops to force costly dependent insns into
11847separate groups. Insert @var{number} nops to force an insn to a new group.
11848
11849@item -mcall-sysv
11850@opindex mcall-sysv
11851On System V.4 and embedded PowerPC systems compile code using calling
11852conventions that adheres to the March 1995 draft of the System V
11853Application Binary Interface, PowerPC processor supplement. This is the
11854default unless you configured GCC using @samp{powerpc-*-eabiaix}.
11855
11856@item -mcall-sysv-eabi
11857@opindex mcall-sysv-eabi
11858Specify both @option{-mcall-sysv} and @option{-meabi} options.
11859
11860@item -mcall-sysv-noeabi
11861@opindex mcall-sysv-noeabi
11862Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
11863
11864@item -mcall-solaris
11865@opindex mcall-solaris
11866On System V.4 and embedded PowerPC systems compile code for the Solaris
11867operating system.
11868
11869@item -mcall-linux
11870@opindex mcall-linux
11871On System V.4 and embedded PowerPC systems compile code for the
11872Linux-based GNU system.
11873
11874@item -mcall-gnu
11875@opindex mcall-gnu
11876On System V.4 and embedded PowerPC systems compile code for the
11877Hurd-based GNU system.
11878
11879@item -mcall-netbsd
11880@opindex mcall-netbsd
11881On System V.4 and embedded PowerPC systems compile code for the
11882NetBSD operating system.
11883
11884@item -maix-struct-return
11885@opindex maix-struct-return
11886Return all structures in memory (as specified by the AIX ABI)@.
11887
11888@item -msvr4-struct-return
11889@opindex msvr4-struct-return
11890Return structures smaller than 8 bytes in registers (as specified by the
11891SVR4 ABI)@.
11892
11893@item -mabi=@var{abi-type}
11894@opindex mabi
11895Extend the current ABI with a particular extension, or remove such extension.
11896Valid values are @var{altivec}, @var{no-altivec}, @var{spe},
11897@var{no-spe}, @var{ibmlongdouble}, @var{ieeelongdouble}@.
11898
11899@item -mabi=spe
11900@opindex mabi=spe
11901Extend the current ABI with SPE ABI extensions. This does not change
11902the default ABI, instead it adds the SPE ABI extensions to the current
11903ABI@.
11904
11905@item -mabi=no-spe
11906@opindex mabi=no-spe
11907Disable Booke SPE ABI extensions for the current ABI@.
11908
11909@item -mabi=ibmlongdouble
11910@opindex mabi=ibmlongdouble
11911Change the current ABI to use IBM extended precision long double.
11912This is a PowerPC 32-bit SYSV ABI option.
11913
11914@item -mabi=ieeelongdouble
11915@opindex mabi=ieeelongdouble
11916Change the current ABI to use IEEE extended precision long double.
11917This is a PowerPC 32-bit Linux ABI option.
11918
11919@item -mprototype
11920@itemx -mno-prototype
11921@opindex mprototype
11922@opindex mno-prototype
11923On System V.4 and embedded PowerPC systems assume that all calls to
11924variable argument functions are properly prototyped. Otherwise, the
11925compiler must insert an instruction before every non prototyped call to
11926set or clear bit 6 of the condition code register (@var{CR}) to
11927indicate whether floating point values were passed in the floating point
11928registers in case the function takes a variable arguments. With
11929@option{-mprototype}, only calls to prototyped variable argument functions
11930will set or clear the bit.
11931
11932@item -msim
11933@opindex msim
11934On embedded PowerPC systems, assume that the startup module is called
11935@file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
11936@file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
11937configurations.
11938
11939@item -mmvme
11940@opindex mmvme
11941On embedded PowerPC systems, assume that the startup module is called
11942@file{crt0.o} and the standard C libraries are @file{libmvme.a} and
11943@file{libc.a}.
11944
11945@item -mads
11946@opindex mads
11947On embedded PowerPC systems, assume that the startup module is called
11948@file{crt0.o} and the standard C libraries are @file{libads.a} and
11949@file{libc.a}.
11950
11951@item -myellowknife
11952@opindex myellowknife
11953On embedded PowerPC systems, assume that the startup module is called
11954@file{crt0.o} and the standard C libraries are @file{libyk.a} and
11955@file{libc.a}.
11956
11957@item -mvxworks
11958@opindex mvxworks
11959On System V.4 and embedded PowerPC systems, specify that you are
11960compiling for a VxWorks system.
11961
11962@item -mwindiss
11963@opindex mwindiss
11964Specify that you are compiling for the WindISS simulation environment.
11965
11966@item -memb
11967@opindex memb
11968On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
11969header to indicate that @samp{eabi} extended relocations are used.
11970
11971@item -meabi
11972@itemx -mno-eabi
11973@opindex meabi
11974@opindex mno-eabi
11975On System V.4 and embedded PowerPC systems do (do not) adhere to the
11976Embedded Applications Binary Interface (eabi) which is a set of
11977modifications to the System V.4 specifications. Selecting @option{-meabi}
11978means that the stack is aligned to an 8 byte boundary, a function
11979@code{__eabi} is called to from @code{main} to set up the eabi
11980environment, and the @option{-msdata} option can use both @code{r2} and
11981@code{r13} to point to two separate small data areas. Selecting
11982@option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
11983do not call an initialization function from @code{main}, and the
11984@option{-msdata} option will only use @code{r13} to point to a single
11985small data area. The @option{-meabi} option is on by default if you
11986configured GCC using one of the @samp{powerpc*-*-eabi*} options.
11987
11988@item -msdata=eabi
11989@opindex msdata=eabi
11990On System V.4 and embedded PowerPC systems, put small initialized
11991@code{const} global and static data in the @samp{.sdata2} section, which
11992is pointed to by register @code{r2}. Put small initialized
11993non-@code{const} global and static data in the @samp{.sdata} section,
11994which is pointed to by register @code{r13}. Put small uninitialized
11995global and static data in the @samp{.sbss} section, which is adjacent to
11996the @samp{.sdata} section. The @option{-msdata=eabi} option is
11997incompatible with the @option{-mrelocatable} option. The
11998@option{-msdata=eabi} option also sets the @option{-memb} option.
11999
12000@item -msdata=sysv
12001@opindex msdata=sysv
12002On System V.4 and embedded PowerPC systems, put small global and static
12003data in the @samp{.sdata} section, which is pointed to by register
12004@code{r13}. Put small uninitialized global and static data in the
12005@samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
12006The @option{-msdata=sysv} option is incompatible with the
12007@option{-mrelocatable} option.
12008
12009@item -msdata=default
12010@itemx -msdata
12011@opindex msdata=default
12012@opindex msdata
12013On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
12014compile code the same as @option{-msdata=eabi}, otherwise compile code the
12015same as @option{-msdata=sysv}.
12016
12017@item -msdata-data
12018@opindex msdata-data
12019On System V.4 and embedded PowerPC systems, put small global
12020data in the @samp{.sdata} section. Put small uninitialized global
12021data in the @samp{.sbss} section. Do not use register @code{r13}
12022to address small data however. This is the default behavior unless
12023other @option{-msdata} options are used.
12024
12025@item -msdata=none
12026@itemx -mno-sdata
12027@opindex msdata=none
12028@opindex mno-sdata
12029On embedded PowerPC systems, put all initialized global and static data
12030in the @samp{.data} section, and all uninitialized data in the
12031@samp{.bss} section.
12032
12033@item -G @var{num}
12034@opindex G
12035@cindex smaller data references (PowerPC)
12036@cindex .sdata/.sdata2 references (PowerPC)
12037On embedded PowerPC systems, put global and static items less than or
12038equal to @var{num} bytes into the small data or bss sections instead of
12039the normal data or bss section. By default, @var{num} is 8. The
12040@option{-G @var{num}} switch is also passed to the linker.
12041All modules should be compiled with the same @option{-G @var{num}} value.
12042
12043@item -mregnames
12044@itemx -mno-regnames
12045@opindex mregnames
12046@opindex mno-regnames
12047On System V.4 and embedded PowerPC systems do (do not) emit register
12048names in the assembly language output using symbolic forms.
12049
12050@item -mlongcall
12051@itemx -mno-longcall
12052@opindex mlongcall
12053@opindex mno-longcall
12054By default assume that all calls are far away so that a longer more
12055expensive calling sequence is required. This is required for calls
12056further than 32 megabytes (33,554,432 bytes) from the current location.
12057A short call will be generated if the compiler knows
12058the call cannot be that far away. This setting can be overridden by
12059the @code{shortcall} function attribute, or by @code{#pragma
12060longcall(0)}.
12061
12062Some linkers are capable of detecting out-of-range calls and generating
12063glue code on the fly. On these systems, long calls are unnecessary and
12064generate slower code. As of this writing, the AIX linker can do this,
12065as can the GNU linker for PowerPC/64. It is planned to add this feature
12066to the GNU linker for 32-bit PowerPC systems as well.
12067
12068On Darwin/PPC systems, @code{#pragma longcall} will generate ``jbsr
12069callee, L42'', plus a ``branch island'' (glue code). The two target
12070addresses represent the callee and the ``branch island''. The
12071Darwin/PPC linker will prefer the first address and generate a ``bl
12072callee'' if the PPC ``bl'' instruction will reach the callee directly;
12073otherwise, the linker will generate ``bl L42'' to call the ``branch
12074island''. The ``branch island'' is appended to the body of the
12075calling function; it computes the full 32-bit address of the callee
12076and jumps to it.
12077
12078On Mach-O (Darwin) systems, this option directs the compiler emit to
12079the glue for every direct call, and the Darwin linker decides whether
12080to use or discard it.
12081
12082In the future, we may cause GCC to ignore all longcall specifications
12083when the linker is known to generate glue.
12084
12085@item -pthread
12086@opindex pthread
12087Adds support for multithreading with the @dfn{pthreads} library.
12088This option sets flags for both the preprocessor and linker.
12089
12090@end table
12091
12092@node S/390 and zSeries Options
12093@subsection S/390 and zSeries Options
12094@cindex S/390 and zSeries Options
12095
12096These are the @samp{-m} options defined for the S/390 and zSeries architecture.
12097
12098@table @gcctabopt
12099@item -mhard-float
12100@itemx -msoft-float
12101@opindex mhard-float
12102@opindex msoft-float
12103Use (do not use) the hardware floating-point instructions and registers
12104for floating-point operations. When @option{-msoft-float} is specified,
12105functions in @file{libgcc.a} will be used to perform floating-point
12106operations. When @option{-mhard-float} is specified, the compiler
12107generates IEEE floating-point instructions. This is the default.
12108
12109@item -mlong-double-64
12110@itemx -mlong-double-128
12111@opindex mlong-double-64
12112@opindex mlong-double-128
12113These switches control the size of @code{long double} type. A size
12114of 64bit makes the @code{long double} type equivalent to the @code{double}
12115type. This is the default.
12116
12117@item -mbackchain
12118@itemx -mno-backchain
12119@opindex mbackchain
12120@opindex mno-backchain
12121Store (do not store) the address of the caller's frame as backchain pointer
12122into the callee's stack frame.
12123A backchain may be needed to allow debugging using tools that do not understand
12124DWARF-2 call frame information.
12125When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
12126at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
12127the backchain is placed into the topmost word of the 96/160 byte register
12128save area.
12129
12130In general, code compiled with @option{-mbackchain} is call-compatible with
12131code compiled with @option{-mmo-backchain}; however, use of the backchain
12132for debugging purposes usually requires that the whole binary is built with
12133@option{-mbackchain}. Note that the combination of @option{-mbackchain},
12134@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
12135to build a linux kernel use @option{-msoft-float}.
12136
12137The default is to not maintain the backchain.
12138
12139@item -mpacked-stack
12140@item -mno-packed-stack
12141@opindex mpacked-stack
12142@opindex mno-packed-stack
12143Use (do not use) the packed stack layout. When @option{-mno-packed-stack} is
12144specified, the compiler uses the all fields of the 96/160 byte register save
12145area only for their default purpose; unused fields still take up stack space.
12146When @option{-mpacked-stack} is specified, register save slots are densely
12147packed at the top of the register save area; unused space is reused for other
12148purposes, allowing for more efficient use of the available stack space.
12149However, when @option{-mbackchain} is also in effect, the topmost word of
12150the save area is always used to store the backchain, and the return address
12151register is always saved two words below the backchain.
12152
12153As long as the stack frame backchain is not used, code generated with
12154@option{-mpacked-stack} is call-compatible with code generated with
12155@option{-mno-packed-stack}. Note that some non-FSF releases of GCC 2.95 for
12156S/390 or zSeries generated code that uses the stack frame backchain at run
12157time, not just for debugging purposes. Such code is not call-compatible
12158with code compiled with @option{-mpacked-stack}. Also, note that the
12159combination of @option{-mbackchain},
12160@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
12161to build a linux kernel use @option{-msoft-float}.
12162
12163The default is to not use the packed stack layout.
12164
12165@item -msmall-exec
12166@itemx -mno-small-exec
12167@opindex msmall-exec
12168@opindex mno-small-exec
12169Generate (or do not generate) code using the @code{bras} instruction
12170to do subroutine calls.
12171This only works reliably if the total executable size does not
12172exceed 64k. The default is to use the @code{basr} instruction instead,
12173which does not have this limitation.
12174
12175@item -m64
12176@itemx -m31
12177@opindex m64
12178@opindex m31
12179When @option{-m31} is specified, generate code compliant to the
12180GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate
12181code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in
12182particular to generate 64-bit instructions. For the @samp{s390}
12183targets, the default is @option{-m31}, while the @samp{s390x}
12184targets default to @option{-m64}.
12185
12186@item -mzarch
12187@itemx -mesa
12188@opindex mzarch
12189@opindex mesa
12190When @option{-mzarch} is specified, generate code using the
12191instructions available on z/Architecture.
12192When @option{-mesa} is specified, generate code using the
12193instructions available on ESA/390. Note that @option{-mesa} is
12194not possible with @option{-m64}.
12195When generating code compliant to the GNU/Linux for S/390 ABI,
12196the default is @option{-mesa}. When generating code compliant
12197to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
12198
12199@item -mmvcle
12200@itemx -mno-mvcle
12201@opindex mmvcle
12202@opindex mno-mvcle
12203Generate (or do not generate) code using the @code{mvcle} instruction
12204to perform block moves. When @option{-mno-mvcle} is specified,
12205use a @code{mvc} loop instead. This is the default unless optimizing for
12206size.
12207
12208@item -mdebug
12209@itemx -mno-debug
12210@opindex mdebug
12211@opindex mno-debug
12212Print (or do not print) additional debug information when compiling.
12213The default is to not print debug information.
12214
12215@item -march=@var{cpu-type}
12216@opindex march
12217Generate code that will run on @var{cpu-type}, which is the name of a system
12218representing a certain processor type. Possible values for
12219@var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, and @samp{z990}.
12220When generating code using the instructions available on z/Architecture,
12221the default is @option{-march=z900}. Otherwise, the default is
12222@option{-march=g5}.
12223
12224@item -mtune=@var{cpu-type}
12225@opindex mtune
12226Tune to @var{cpu-type} everything applicable about the generated code,
12227except for the ABI and the set of available instructions.
12228The list of @var{cpu-type} values is the same as for @option{-march}.
12229The default is the value used for @option{-march}.
12230
12231@item -mtpf-trace
12232@itemx -mno-tpf-trace
12233@opindex mtpf-trace
12234@opindex mno-tpf-trace
12235Generate code that adds (does not add) in TPF OS specific branches to trace
12236routines in the operating system. This option is off by default, even
12237when compiling for the TPF OS@.
12238
12239@item -mfused-madd
12240@itemx -mno-fused-madd
12241@opindex mfused-madd
12242@opindex mno-fused-madd
12243Generate code that uses (does not use) the floating point multiply and
12244accumulate instructions. These instructions are generated by default if
12245hardware floating point is used.
12246
12247@item -mwarn-framesize=@var{framesize}
12248@opindex mwarn-framesize
12249Emit a warning if the current function exceeds the given frame size. Because
12250this is a compile time check it doesn't need to be a real problem when the program
12251runs. It is intended to identify functions which most probably cause
12252a stack overflow. It is useful to be used in an environment with limited stack
12253size e.g.@: the linux kernel.
12254
12255@item -mwarn-dynamicstack
12256@opindex mwarn-dynamicstack
12257Emit a warning if the function calls alloca or uses dynamically
12258sized arrays. This is generally a bad idea with a limited stack size.
12259
12260@item -mstack-guard=@var{stack-guard}
12261@item -mstack-size=@var{stack-size}
12262@opindex mstack-guard
12263@opindex mstack-size
12264These arguments always have to be used in conjunction. If they are present the s390
12265back end emits additional instructions in the function prologue which trigger a trap
12266if the stack size is @var{stack-guard} bytes above the @var{stack-size}
12267(remember that the stack on s390 grows downward). These options are intended to
12268be used to help debugging stack overflow problems. The additionally emitted code
12269causes only little overhead and hence can also be used in production like systems
12270without greater performance degradation. The given values have to be exact
12271powers of 2 and @var{stack-size} has to be greater than @var{stack-guard} without
12272exceeding 64k.
12273In order to be efficient the extra code makes the assumption that the stack starts
12274at an address aligned to the value given by @var{stack-size}.
12275@end table
12276
12277@node Score Options
12278@subsection Score Options
12279@cindex Score Options
12280
12281These options are defined for Score implementations:
12282
12283@table @gcctabopt
12284@item -meb
12285@opindex meb
12286Compile code for big endian mode. This is the default.
12287
12288@item -mel
12289@opindex mel
12290Compile code for little endian mode.
12291
12292@item -mnhwloop
12293@opindex mnhwloop
12294Disable generate bcnz instruction.
12295
12296@item -muls
12297@opindex muls
12298Enable generate unaligned load and store instruction.
12299
12300@item -mmac
12301@opindex mmac
12302Enable the use of multiply-accumulate instructions. Disabled by default.
12303
12304@item -mscore5
12305@opindex mscore5
12306Specify the SCORE5 as the target architecture.
12307
12308@item -mscore5u
12309@opindex mscore5u
12310Specify the SCORE5U of the target architecture.
12311
12312@item -mscore7
12313@opindex mscore7
12314Specify the SCORE7 as the target architecture. This is the default.
12315
12316@item -mscore7d
12317@opindex mscore7d
12318Specify the SCORE7D as the target architecture.
12319@end table
12320
12321@node SH Options
12322@subsection SH Options
12323
12324These @samp{-m} options are defined for the SH implementations:
12325
12326@table @gcctabopt
12327@item -m1
12328@opindex m1
12329Generate code for the SH1.
12330
12331@item -m2
12332@opindex m2
12333Generate code for the SH2.
12334
12335@item -m2e
12336Generate code for the SH2e.
12337
12338@item -m3
12339@opindex m3
12340Generate code for the SH3.
12341
12342@item -m3e
12343@opindex m3e
12344Generate code for the SH3e.
12345
12346@item -m4-nofpu
12347@opindex m4-nofpu
12348Generate code for the SH4 without a floating-point unit.
12349
12350@item -m4-single-only
12351@opindex m4-single-only
12352Generate code for the SH4 with a floating-point unit that only
12353supports single-precision arithmetic.
12354
12355@item -m4-single
12356@opindex m4-single
12357Generate code for the SH4 assuming the floating-point unit is in
12358single-precision mode by default.
12359
12360@item -m4
12361@opindex m4
12362Generate code for the SH4.
12363
12364@item -m4a-nofpu
12365@opindex m4a-nofpu
12366Generate code for the SH4al-dsp, or for a SH4a in such a way that the
12367floating-point unit is not used.
12368
12369@item -m4a-single-only
12370@opindex m4a-single-only
12371Generate code for the SH4a, in such a way that no double-precision
12372floating point operations are used.
12373
12374@item -m4a-single
12375@opindex m4a-single
12376Generate code for the SH4a assuming the floating-point unit is in
12377single-precision mode by default.
12378
12379@item -m4a
12380@opindex m4a
12381Generate code for the SH4a.
12382
12383@item -m4al
12384@opindex m4al
12385Same as @option{-m4a-nofpu}, except that it implicitly passes
12386@option{-dsp} to the assembler. GCC doesn't generate any DSP
12387instructions at the moment.
12388
12389@item -mb
12390@opindex mb
12391Compile code for the processor in big endian mode.
12392
12393@item -ml
12394@opindex ml
12395Compile code for the processor in little endian mode.
12396
12397@item -mdalign
12398@opindex mdalign
12399Align doubles at 64-bit boundaries. Note that this changes the calling
12400conventions, and thus some functions from the standard C library will
12401not work unless you recompile it first with @option{-mdalign}.
12402
12403@item -mrelax
12404@opindex mrelax
12405Shorten some address references at link time, when possible; uses the
12406linker option @option{-relax}.
12407
12408@item -mbigtable
12409@opindex mbigtable
12410Use 32-bit offsets in @code{switch} tables. The default is to use
1241116-bit offsets.
12412
12413@item -mfmovd
12414@opindex mfmovd
12415Enable the use of the instruction @code{fmovd}.
12416
12417@item -mhitachi
12418@opindex mhitachi
12419Comply with the calling conventions defined by Renesas.
12420
12421@item -mrenesas
12422@opindex mhitachi
12423Comply with the calling conventions defined by Renesas.
12424
12425@item -mno-renesas
12426@opindex mhitachi
12427Comply with the calling conventions defined for GCC before the Renesas
12428conventions were available. This option is the default for all
12429targets of the SH toolchain except for @samp{sh-symbianelf}.
12430
12431@item -mnomacsave
12432@opindex mnomacsave
12433Mark the @code{MAC} register as call-clobbered, even if
12434@option{-mhitachi} is given.
12435
12436@item -mieee
12437@opindex mieee
12438Increase IEEE-compliance of floating-point code.
12439At the moment, this is equivalent to @option{-fno-finite-math-only}.
12440When generating 16 bit SH opcodes, getting IEEE-conforming results for
12441comparisons of NANs / infinities incurs extra overhead in every
12442floating point comparison, therefore the default is set to
12443@option{-ffinite-math-only}.
12444
12445@item -misize
12446@opindex misize
12447Dump instruction size and location in the assembly code.
12448
12449@item -mpadstruct
12450@opindex mpadstruct
12451This option is deprecated. It pads structures to multiple of 4 bytes,
12452which is incompatible with the SH ABI@.
12453
12454@item -mspace
12455@opindex mspace
12456Optimize for space instead of speed. Implied by @option{-Os}.
12457
12458@item -mprefergot
12459@opindex mprefergot
12460When generating position-independent code, emit function calls using
12461the Global Offset Table instead of the Procedure Linkage Table.
12462
12463@item -musermode
12464@opindex musermode
12465Generate a library function call to invalidate instruction cache
12466entries, after fixing up a trampoline. This library function call
12467doesn't assume it can write to the whole memory address space. This
12468is the default when the target is @code{sh-*-linux*}.
12469
12470@item -multcost=@var{number}
12471@opindex multcost=@var{number}
12472Set the cost to assume for a multiply insn.
12473
12474@item -mdiv=@var{strategy}
12475@opindex mdiv=@var{strategy}
12476Set the division strategy to use for SHmedia code. @var{strategy} must be
12477one of: call, call2, fp, inv, inv:minlat, inv20u, inv20l, inv:call,
12478inv:call2, inv:fp .
12479"fp" performs the operation in floating point. This has a very high latency,
12480but needs only a few instructions, so it might be a good choice if
12481your code has enough easily exploitable ILP to allow the compiler to
12482schedule the floating point instructions together with other instructions.
12483Division by zero causes a floating point exception.
12484"inv" uses integer operations to calculate the inverse of the divisor,
12485and then multiplies the dividend with the inverse. This strategy allows
12486cse and hoisting of the inverse calculation. Division by zero calculates
12487an unspecified result, but does not trap.
12488"inv:minlat" is a variant of "inv" where if no cse / hoisting opportunities
12489have been found, or if the entire operation has been hoisted to the same
12490place, the last stages of the inverse calculation are intertwined with the
12491final multiply to reduce the overall latency, at the expense of using a few
12492more instructions, and thus offering fewer scheduling opportunities with
12493other code.
12494"call" calls a library function that usually implements the inv:minlat
12495strategy.
12496This gives high code density for m5-*media-nofpu compilations.
12497"call2" uses a different entry point of the same library function, where it
12498assumes that a pointer to a lookup table has already been set up, which
12499exposes the pointer load to cse / code hoisting optimizations.
12500"inv:call", "inv:call2" and "inv:fp" all use the "inv" algorithm for initial
12501code generation, but if the code stays unoptimized, revert to the "call",
12502"call2", or "fp" strategies, respectively. Note that the
12503potentially-trapping side effect of division by zero is carried by a
12504separate instruction, so it is possible that all the integer instructions
12505are hoisted out, but the marker for the side effect stays where it is.
12506A recombination to fp operations or a call is not possible in that case.
12507"inv20u" and "inv20l" are variants of the "inv:minlat" strategy. In the case
12508that the inverse calculation was nor separated from the multiply, they speed
12509up division where the dividend fits into 20 bits (plus sign where applicable),
12510by inserting a test to skip a number of operations in this case; this test
12511slows down the case of larger dividends. inv20u assumes the case of a such
12512a small dividend to be unlikely, and inv20l assumes it to be likely.
12513
12514@item -mdivsi3_libfunc=@var{name}
12515@opindex mdivsi3_libfunc=@var{name}
12516Set the name of the library function used for 32 bit signed division to
12517@var{name}. This only affect the name used in the call and inv:call
12518division strategies, and the compiler will still expect the same
12519sets of input/output/clobbered registers as if this option was not present.
12520
12521@item -madjust-unroll
12522@opindex madjust-unroll
12523Throttle unrolling to avoid thrashing target registers.
12524This option only has an effect if the gcc code base supports the
12525TARGET_ADJUST_UNROLL_MAX target hook.
12526
12527@item -mindexed-addressing
12528@opindex mindexed-addressing
12529Enable the use of the indexed addressing mode for SHmedia32/SHcompact.
12530This is only safe if the hardware and/or OS implement 32 bit wrap-around
12531semantics for the indexed addressing mode. The architecture allows the
12532implementation of processors with 64 bit MMU, which the OS could use to
12533get 32 bit addressing, but since no current hardware implementation supports
12534this or any other way to make the indexed addressing mode safe to use in
12535the 32 bit ABI, the default is -mno-indexed-addressing.
12536
12537@item -mgettrcost=@var{number}
12538@opindex mgettrcost=@var{number}
12539Set the cost assumed for the gettr instruction to @var{number}.
12540The default is 2 if @option{-mpt-fixed} is in effect, 100 otherwise.
12541
12542@item -mpt-fixed
12543@opindex mpt-fixed
12544Assume pt* instructions won't trap. This will generally generate better
12545scheduled code, but is unsafe on current hardware. The current architecture
12546definition says that ptabs and ptrel trap when the target anded with 3 is 3.
12547This has the unintentional effect of making it unsafe to schedule ptabs /
12548ptrel before a branch, or hoist it out of a loop. For example,
12549__do_global_ctors, a part of libgcc that runs constructors at program
12550startup, calls functions in a list which is delimited by -1. With the
12551-mpt-fixed option, the ptabs will be done before testing against -1.
12552That means that all the constructors will be run a bit quicker, but when
12553the loop comes to the end of the list, the program crashes because ptabs
12554loads -1 into a target register. Since this option is unsafe for any
12555hardware implementing the current architecture specification, the default
12556is -mno-pt-fixed. Unless the user specifies a specific cost with
12557@option{-mgettrcost}, -mno-pt-fixed also implies @option{-mgettrcost=100};
12558this deters register allocation using target registers for storing
12559ordinary integers.
12560
12561@item -minvalid-symbols
12562@opindex minvalid-symbols
12563Assume symbols might be invalid. Ordinary function symbols generated by
12564the compiler will always be valid to load with movi/shori/ptabs or
12565movi/shori/ptrel, but with assembler and/or linker tricks it is possible
12566to generate symbols that will cause ptabs / ptrel to trap.
12567This option is only meaningful when @option{-mno-pt-fixed} is in effect.
12568It will then prevent cross-basic-block cse, hoisting and most scheduling
12569of symbol loads. The default is @option{-mno-invalid-symbols}.
12570@end table
12571
12572@node SPARC Options
12573@subsection SPARC Options
12574@cindex SPARC options
12575
12576These @samp{-m} options are supported on the SPARC:
12577
12578@table @gcctabopt
12579@item -mno-app-regs
12580@itemx -mapp-regs
12581@opindex mno-app-regs
12582@opindex mapp-regs
12583Specify @option{-mapp-regs} to generate output using the global registers
125842 through 4, which the SPARC SVR4 ABI reserves for applications. This
12585is the default.
12586
12587To be fully SVR4 ABI compliant at the cost of some performance loss,
12588specify @option{-mno-app-regs}. You should compile libraries and system
12589software with this option.
12590
12591@item -mfpu
12592@itemx -mhard-float
12593@opindex mfpu
12594@opindex mhard-float
12595Generate output containing floating point instructions. This is the
12596default.
12597
12598@item -mno-fpu
12599@itemx -msoft-float
12600@opindex mno-fpu
12601@opindex msoft-float
12602Generate output containing library calls for floating point.
12603@strong{Warning:} the requisite libraries are not available for all SPARC
12604targets. Normally the facilities of the machine's usual C compiler are
12605used, but this cannot be done directly in cross-compilation. You must make
12606your own arrangements to provide suitable library functions for
12607cross-compilation. The embedded targets @samp{sparc-*-aout} and
12608@samp{sparclite-*-*} do provide software floating point support.
12609
12610@option{-msoft-float} changes the calling convention in the output file;
12611therefore, it is only useful if you compile @emph{all} of a program with
12612this option. In particular, you need to compile @file{libgcc.a}, the
12613library that comes with GCC, with @option{-msoft-float} in order for
12614this to work.
12615
12616@item -mhard-quad-float
12617@opindex mhard-quad-float
12618Generate output containing quad-word (long double) floating point
12619instructions.
12620
12621@item -msoft-quad-float
12622@opindex msoft-quad-float
12623Generate output containing library calls for quad-word (long double)
12624floating point instructions. The functions called are those specified
12625in the SPARC ABI@. This is the default.
12626
12627As of this writing, there are no SPARC implementations that have hardware
12628support for the quad-word floating point instructions. They all invoke
12629a trap handler for one of these instructions, and then the trap handler
12630emulates the effect of the instruction. Because of the trap handler overhead,
12631this is much slower than calling the ABI library routines. Thus the
12632@option{-msoft-quad-float} option is the default.
12633
12634@item -mno-unaligned-doubles
12635@itemx -munaligned-doubles
12636@opindex mno-unaligned-doubles
12637@opindex munaligned-doubles
12638Assume that doubles have 8 byte alignment. This is the default.
12639
12640With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
12641alignment only if they are contained in another type, or if they have an
12642absolute address. Otherwise, it assumes they have 4 byte alignment.
12643Specifying this option avoids some rare compatibility problems with code
12644generated by other compilers. It is not the default because it results
12645in a performance loss, especially for floating point code.
12646
12647@item -mno-faster-structs
12648@itemx -mfaster-structs
12649@opindex mno-faster-structs
12650@opindex mfaster-structs
12651With @option{-mfaster-structs}, the compiler assumes that structures
12652should have 8 byte alignment. This enables the use of pairs of
12653@code{ldd} and @code{std} instructions for copies in structure
12654assignment, in place of twice as many @code{ld} and @code{st} pairs.
12655However, the use of this changed alignment directly violates the SPARC
12656ABI@. Thus, it's intended only for use on targets where the developer
12657acknowledges that their resulting code will not be directly in line with
12658the rules of the ABI@.
12659
12660@item -mimpure-text
12661@opindex mimpure-text
12662@option{-mimpure-text}, used in addition to @option{-shared}, tells
12663the compiler to not pass @option{-z text} to the linker when linking a
12664shared object. Using this option, you can link position-dependent
12665code into a shared object.
12666
12667@option{-mimpure-text} suppresses the ``relocations remain against
12668allocatable but non-writable sections'' linker error message.
12669However, the necessary relocations will trigger copy-on-write, and the
12670shared object is not actually shared across processes. Instead of
12671using @option{-mimpure-text}, you should compile all source code with
12672@option{-fpic} or @option{-fPIC}.
12673
12674This option is only available on SunOS and Solaris.
12675
12676@item -mcpu=@var{cpu_type}
12677@opindex mcpu
12678Set the instruction set, register set, and instruction scheduling parameters
12679for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
12680@samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
12681@samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x},
12682@samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc},
12683@samp{ultrasparc3}, and @samp{niagara}.
12684
12685Default instruction scheduling parameters are used for values that select
12686an architecture and not an implementation. These are @samp{v7}, @samp{v8},
12687@samp{sparclite}, @samp{sparclet}, @samp{v9}.
12688
12689Here is a list of each supported architecture and their supported
12690implementations.
12691
12692@smallexample
12693 v7: cypress
12694 v8: supersparc, hypersparc
12695 sparclite: f930, f934, sparclite86x
12696 sparclet: tsc701
12697 v9: ultrasparc, ultrasparc3, niagara
12698@end smallexample
12699
12700By default (unless configured otherwise), GCC generates code for the V7
12701variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler
12702additionally optimizes it for the Cypress CY7C602 chip, as used in the
12703SPARCStation/SPARCServer 3xx series. This is also appropriate for the older
12704SPARCStation 1, 2, IPX etc.
12705
12706With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
12707architecture. The only difference from V7 code is that the compiler emits
12708the integer multiply and integer divide instructions which exist in SPARC-V8
12709but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally
12710optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
127112000 series.
12712
12713With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
12714the SPARC architecture. This adds the integer multiply, integer divide step
12715and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
12716With @option{-mcpu=f930}, the compiler additionally optimizes it for the
12717Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@. With
12718@option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
12719MB86934 chip, which is the more recent SPARClite with FPU@.
12720
12721With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
12722the SPARC architecture. This adds the integer multiply, multiply/accumulate,
12723integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
12724but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally
12725optimizes it for the TEMIC SPARClet chip.
12726
12727With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
12728architecture. This adds 64-bit integer and floating-point move instructions,
127293 additional floating-point condition code registers and conditional move
12730instructions. With @option{-mcpu=ultrasparc}, the compiler additionally
12731optimizes it for the Sun UltraSPARC I/II/IIi chips. With
12732@option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
12733Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips. With
12734@option{-mcpu=niagara}, the compiler additionally optimizes it for
12735Sun UltraSPARC T1 chips.
12736
12737@item -mtune=@var{cpu_type}
12738@opindex mtune
12739Set the instruction scheduling parameters for machine type
12740@var{cpu_type}, but do not set the instruction set or register set that the
12741option @option{-mcpu=@var{cpu_type}} would.
12742
12743The same values for @option{-mcpu=@var{cpu_type}} can be used for
12744@option{-mtune=@var{cpu_type}}, but the only useful values are those
12745that select a particular cpu implementation. Those are @samp{cypress},
12746@samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
12747@samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc},
12748@samp{ultrasparc3}, and @samp{niagara}.
12749
12750@item -mv8plus
12751@itemx -mno-v8plus
12752@opindex mv8plus
12753@opindex mno-v8plus
12754With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@. The
12755difference from the V8 ABI is that the global and out registers are
12756considered 64-bit wide. This is enabled by default on Solaris in 32-bit
12757mode for all SPARC-V9 processors.
12758
12759@item -mvis
12760@itemx -mno-vis
12761@opindex mvis
12762@opindex mno-vis
12763With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
12764Visual Instruction Set extensions. The default is @option{-mno-vis}.
12765@end table
12766
12767These @samp{-m} options are supported in addition to the above
12768on SPARC-V9 processors in 64-bit environments:
12769
12770@table @gcctabopt
12771@item -mlittle-endian
12772@opindex mlittle-endian
12773Generate code for a processor running in little-endian mode. It is only
12774available for a few configurations and most notably not on Solaris and Linux.
12775
12776@item -m32
12777@itemx -m64
12778@opindex m32
12779@opindex m64
12780Generate code for a 32-bit or 64-bit environment.
12781The 32-bit environment sets int, long and pointer to 32 bits.
12782The 64-bit environment sets int to 32 bits and long and pointer
12783to 64 bits.
12784
12785@item -mcmodel=medlow
12786@opindex mcmodel=medlow
12787Generate code for the Medium/Low code model: 64-bit addresses, programs
12788must be linked in the low 32 bits of memory. Programs can be statically
12789or dynamically linked.
12790
12791@item -mcmodel=medmid
12792@opindex mcmodel=medmid
12793Generate code for the Medium/Middle code model: 64-bit addresses, programs
12794must be linked in the low 44 bits of memory, the text and data segments must
12795be less than 2GB in size and the data segment must be located within 2GB of
12796the text segment.
12797
12798@item -mcmodel=medany
12799@opindex mcmodel=medany
12800Generate code for the Medium/Anywhere code model: 64-bit addresses, programs
12801may be linked anywhere in memory, the text and data segments must be less
12802than 2GB in size and the data segment must be located within 2GB of the
12803text segment.
12804
12805@item -mcmodel=embmedany
12806@opindex mcmodel=embmedany
12807Generate code for the Medium/Anywhere code model for embedded systems:
1280864-bit addresses, the text and data segments must be less than 2GB in
12809size, both starting anywhere in memory (determined at link time). The
12810global register %g4 points to the base of the data segment. Programs
12811are statically linked and PIC is not supported.
12812
12813@item -mstack-bias
12814@itemx -mno-stack-bias
12815@opindex mstack-bias
12816@opindex mno-stack-bias
12817With @option{-mstack-bias}, GCC assumes that the stack pointer, and
12818frame pointer if present, are offset by @minus{}2047 which must be added back
12819when making stack frame references. This is the default in 64-bit mode.
12820Otherwise, assume no such offset is present.
12821@end table
12822
12823These switches are supported in addition to the above on Solaris:
12824
12825@table @gcctabopt
12826@item -threads
12827@opindex threads
12828Add support for multithreading using the Solaris threads library. This
12829option sets flags for both the preprocessor and linker. This option does
12830not affect the thread safety of object code produced by the compiler or
12831that of libraries supplied with it.
12832
12833@item -pthreads
12834@opindex pthreads
12835Add support for multithreading using the POSIX threads library. This
12836option sets flags for both the preprocessor and linker. This option does
12837not affect the thread safety of object code produced by the compiler or
12838that of libraries supplied with it.
12839
12840@item -pthread
12841@opindex pthread
12842This is a synonym for @option{-pthreads}.
12843@end table
12844
12845@node System V Options
12846@subsection Options for System V
12847
12848These additional options are available on System V Release 4 for
12849compatibility with other compilers on those systems:
12850
12851@table @gcctabopt
12852@item -G
12853@opindex G
12854Create a shared object.
12855It is recommended that @option{-symbolic} or @option{-shared} be used instead.
12856
12857@item -Qy
12858@opindex Qy
12859Identify the versions of each tool used by the compiler, in a
12860@code{.ident} assembler directive in the output.
12861
12862@item -Qn
12863@opindex Qn
12864Refrain from adding @code{.ident} directives to the output file (this is
12865the default).
12866
12867@item -YP,@var{dirs}
12868@opindex YP
12869Search the directories @var{dirs}, and no others, for libraries
12870specified with @option{-l}.
12871
12872@item -Ym,@var{dir}
12873@opindex Ym
12874Look in the directory @var{dir} to find the M4 preprocessor.
12875The assembler uses this option.
12876@c This is supposed to go with a -Yd for predefined M4 macro files, but
12877@c the generic assembler that comes with Solaris takes just -Ym.
12878@end table
12879
12880@node TMS320C3x/C4x Options
12881@subsection TMS320C3x/C4x Options
12882@cindex TMS320C3x/C4x Options
12883
12884These @samp{-m} options are defined for TMS320C3x/C4x implementations:
12885
12886@table @gcctabopt
12887
12888@item -mcpu=@var{cpu_type}
12889@opindex mcpu
12890Set the instruction set, register set, and instruction scheduling
12891parameters for machine type @var{cpu_type}. Supported values for
12892@var{cpu_type} are @samp{c30}, @samp{c31}, @samp{c32}, @samp{c40}, and
12893@samp{c44}. The default is @samp{c40} to generate code for the
12894TMS320C40.
12895
12896@item -mbig-memory
12897@itemx -mbig
12898@itemx -msmall-memory
12899@itemx -msmall
12900@opindex mbig-memory
12901@opindex mbig
12902@opindex msmall-memory
12903@opindex msmall
12904Generates code for the big or small memory model. The small memory
12905model assumed that all data fits into one 64K word page. At run-time
12906the data page (DP) register must be set to point to the 64K page
12907containing the .bss and .data program sections. The big memory model is
12908the default and requires reloading of the DP register for every direct
12909memory access.
12910
12911@item -mbk
12912@itemx -mno-bk
12913@opindex mbk
12914@opindex mno-bk
12915Allow (disallow) allocation of general integer operands into the block
12916count register BK@.
12917
12918@item -mdb
12919@itemx -mno-db
12920@opindex mdb
12921@opindex mno-db
12922Enable (disable) generation of code using decrement and branch,
12923DBcond(D), instructions. This is enabled by default for the C4x. To be
12924on the safe side, this is disabled for the C3x, since the maximum
12925iteration count on the C3x is @math{2^{23} + 1} (but who iterates loops more than
12926@math{2^{23}} times on the C3x?). Note that GCC will try to reverse a loop so
12927that it can utilize the decrement and branch instruction, but will give
12928up if there is more than one memory reference in the loop. Thus a loop
12929where the loop counter is decremented can generate slightly more
12930efficient code, in cases where the RPTB instruction cannot be utilized.
12931
12932@item -mdp-isr-reload
12933@itemx -mparanoid
12934@opindex mdp-isr-reload
12935@opindex mparanoid
12936Force the DP register to be saved on entry to an interrupt service
12937routine (ISR), reloaded to point to the data section, and restored on
12938exit from the ISR@. This should not be required unless someone has
12939violated the small memory model by modifying the DP register, say within
12940an object library.
12941
12942@item -mmpyi
12943@itemx -mno-mpyi
12944@opindex mmpyi
12945@opindex mno-mpyi
12946For the C3x use the 24-bit MPYI instruction for integer multiplies
12947instead of a library call to guarantee 32-bit results. Note that if one
12948of the operands is a constant, then the multiplication will be performed
12949using shifts and adds. If the @option{-mmpyi} option is not specified for the C3x,
12950then squaring operations are performed inline instead of a library call.
12951
12952@item -mfast-fix
12953@itemx -mno-fast-fix
12954@opindex mfast-fix
12955@opindex mno-fast-fix
12956The C3x/C4x FIX instruction to convert a floating point value to an
12957integer value chooses the nearest integer less than or equal to the
12958floating point value rather than to the nearest integer. Thus if the
12959floating point number is negative, the result will be incorrectly
12960truncated an additional code is necessary to detect and correct this
12961case. This option can be used to disable generation of the additional
12962code required to correct the result.
12963
12964@item -mrptb
12965@itemx -mno-rptb
12966@opindex mrptb
12967@opindex mno-rptb
12968Enable (disable) generation of repeat block sequences using the RPTB
12969instruction for zero overhead looping. The RPTB construct is only used
12970for innermost loops that do not call functions or jump across the loop
12971boundaries. There is no advantage having nested RPTB loops due to the
12972overhead required to save and restore the RC, RS, and RE registers.
12973This is enabled by default with @option{-O2}.
12974
12975@item -mrpts=@var{count}
12976@itemx -mno-rpts
12977@opindex mrpts
12978@opindex mno-rpts
12979Enable (disable) the use of the single instruction repeat instruction
12980RPTS@. If a repeat block contains a single instruction, and the loop
12981count can be guaranteed to be less than the value @var{count}, GCC will
12982emit a RPTS instruction instead of a RPTB@. If no value is specified,
12983then a RPTS will be emitted even if the loop count cannot be determined
12984at compile time. Note that the repeated instruction following RPTS does
12985not have to be reloaded from memory each iteration, thus freeing up the
12986CPU buses for operands. However, since interrupts are blocked by this
12987instruction, it is disabled by default.
12988
12989@item -mloop-unsigned
12990@itemx -mno-loop-unsigned
12991@opindex mloop-unsigned
12992@opindex mno-loop-unsigned
12993The maximum iteration count when using RPTS and RPTB (and DB on the C40)
12994is @math{2^{31} + 1} since these instructions test if the iteration count is
12995negative to terminate the loop. If the iteration count is unsigned
12996there is a possibility than the @math{2^{31} + 1} maximum iteration count may be
12997exceeded. This switch allows an unsigned iteration count.
12998
12999@item -mti
13000@opindex mti
13001Try to emit an assembler syntax that the TI assembler (asm30) is happy
13002with. This also enforces compatibility with the API employed by the TI
13003C3x C compiler. For example, long doubles are passed as structures
13004rather than in floating point registers.
13005
13006@item -mregparm
13007@itemx -mmemparm
13008@opindex mregparm
13009@opindex mmemparm
13010Generate code that uses registers (stack) for passing arguments to functions.
13011By default, arguments are passed in registers where possible rather
13012than by pushing arguments on to the stack.
13013
13014@item -mparallel-insns
13015@itemx -mno-parallel-insns
13016@opindex mparallel-insns
13017@opindex mno-parallel-insns
13018Allow the generation of parallel instructions. This is enabled by
13019default with @option{-O2}.
13020
13021@item -mparallel-mpy
13022@itemx -mno-parallel-mpy
13023@opindex mparallel-mpy
13024@opindex mno-parallel-mpy
13025Allow the generation of MPY||ADD and MPY||SUB parallel instructions,
13026provided @option{-mparallel-insns} is also specified. These instructions have
13027tight register constraints which can pessimize the code generation
13028of large functions.
13029
13030@end table
13031
13032@node V850 Options
13033@subsection V850 Options
13034@cindex V850 Options
13035
13036These @samp{-m} options are defined for V850 implementations:
13037
13038@table @gcctabopt
13039@item -mlong-calls
13040@itemx -mno-long-calls
13041@opindex mlong-calls
13042@opindex mno-long-calls
13043Treat all calls as being far away (near). If calls are assumed to be
13044far away, the compiler will always load the functions address up into a
13045register, and call indirect through the pointer.
13046
13047@item -mno-ep
13048@itemx -mep
13049@opindex mno-ep
13050@opindex mep
13051Do not optimize (do optimize) basic blocks that use the same index
13052pointer 4 or more times to copy pointer into the @code{ep} register, and
13053use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
13054option is on by default if you optimize.
13055
13056@item -mno-prolog-function
13057@itemx -mprolog-function
13058@opindex mno-prolog-function
13059@opindex mprolog-function
13060Do not use (do use) external functions to save and restore registers
13061at the prologue and epilogue of a function. The external functions
13062are slower, but use less code space if more than one function saves
13063the same number of registers. The @option{-mprolog-function} option
13064is on by default if you optimize.
13065
13066@item -mspace
13067@opindex mspace
13068Try to make the code as small as possible. At present, this just turns
13069on the @option{-mep} and @option{-mprolog-function} options.
13070
13071@item -mtda=@var{n}
13072@opindex mtda
13073Put static or global variables whose size is @var{n} bytes or less into
13074the tiny data area that register @code{ep} points to. The tiny data
13075area can hold up to 256 bytes in total (128 bytes for byte references).
13076
13077@item -msda=@var{n}
13078@opindex msda
13079Put static or global variables whose size is @var{n} bytes or less into
13080the small data area that register @code{gp} points to. The small data
13081area can hold up to 64 kilobytes.
13082
13083@item -mzda=@var{n}
13084@opindex mzda
13085Put static or global variables whose size is @var{n} bytes or less into
13086the first 32 kilobytes of memory.
13087
13088@item -mv850
13089@opindex mv850
13090Specify that the target processor is the V850.
13091
13092@item -mbig-switch
13093@opindex mbig-switch
13094Generate code suitable for big switch tables. Use this option only if
13095the assembler/linker complain about out of range branches within a switch
13096table.
13097
13098@item -mapp-regs
13099@opindex mapp-regs
13100This option will cause r2 and r5 to be used in the code generated by
13101the compiler. This setting is the default.
13102
13103@item -mno-app-regs
13104@opindex mno-app-regs
13105This option will cause r2 and r5 to be treated as fixed registers.
13106
13107@item -mv850e1
13108@opindex mv850e1
13109Specify that the target processor is the V850E1. The preprocessor
13110constants @samp{__v850e1__} and @samp{__v850e__} will be defined if
13111this option is used.
13112
13113@item -mv850e
13114@opindex mv850e
13115Specify that the target processor is the V850E@. The preprocessor
13116constant @samp{__v850e__} will be defined if this option is used.
13117
13118If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
13119are defined then a default target processor will be chosen and the
13120relevant @samp{__v850*__} preprocessor constant will be defined.
13121
13122The preprocessor constants @samp{__v850} and @samp{__v851__} are always
13123defined, regardless of which processor variant is the target.
13124
13125@item -mdisable-callt
13126@opindex mdisable-callt
13127This option will suppress generation of the CALLT instruction for the
13128v850e and v850e1 flavors of the v850 architecture. The default is
13129@option{-mno-disable-callt} which allows the CALLT instruction to be used.
13130
13131@end table
13132
13133@node VAX Options
13134@subsection VAX Options
13135@cindex VAX options
13136
13137These @samp{-m} options are defined for the VAX:
13138
13139@table @gcctabopt
13140@item -munix
13141@opindex munix
13142Do not output certain jump instructions (@code{aobleq} and so on)
13143that the Unix assembler for the VAX cannot handle across long
13144ranges.
13145
13146@item -mgnu
13147@opindex mgnu
13148Do output those jump instructions, on the assumption that you
13149will assemble with the GNU assembler.
13150
13151@item -mg
13152@opindex mg
13153Output code for g-format floating point numbers instead of d-format.
13154@end table
13155
13156@node x86-64 Options
13157@subsection x86-64 Options
13158@cindex x86-64 options
13159
13160These are listed under @xref{i386 and x86-64 Options}.
13161
13162@node Xstormy16 Options
13163@subsection Xstormy16 Options
13164@cindex Xstormy16 Options
13165
13166These options are defined for Xstormy16:
13167
13168@table @gcctabopt
13169@item -msim
13170@opindex msim
13171Choose startup files and linker script suitable for the simulator.
13172@end table
13173
13174@node Xtensa Options
13175@subsection Xtensa Options
13176@cindex Xtensa Options
13177
13178These options are supported for Xtensa targets:
13179
13180@table @gcctabopt
13181@item -mconst16
13182@itemx -mno-const16
13183@opindex mconst16
13184@opindex mno-const16
13185Enable or disable use of @code{CONST16} instructions for loading
13186constant values. The @code{CONST16} instruction is currently not a
13187standard option from Tensilica. When enabled, @code{CONST16}
13188instructions are always used in place of the standard @code{L32R}
13189instructions. The use of @code{CONST16} is enabled by default only if
13190the @code{L32R} instruction is not available.
13191
13192@item -mfused-madd
13193@itemx -mno-fused-madd
13194@opindex mfused-madd
13195@opindex mno-fused-madd
13196Enable or disable use of fused multiply/add and multiply/subtract
13197instructions in the floating-point option. This has no effect if the
13198floating-point option is not also enabled. Disabling fused multiply/add
13199and multiply/subtract instructions forces the compiler to use separate
13200instructions for the multiply and add/subtract operations. This may be
13201desirable in some cases where strict IEEE 754-compliant results are
13202required: the fused multiply add/subtract instructions do not round the
13203intermediate result, thereby producing results with @emph{more} bits of
13204precision than specified by the IEEE standard. Disabling fused multiply
13205add/subtract instructions also ensures that the program output is not
13206sensitive to the compiler's ability to combine multiply and add/subtract
13207operations.
13208
13209@item -mtext-section-literals
13210@itemx -mno-text-section-literals
13211@opindex mtext-section-literals
13212@opindex mno-text-section-literals
13213Control the treatment of literal pools. The default is
13214@option{-mno-text-section-literals}, which places literals in a separate
13215section in the output file. This allows the literal pool to be placed
13216in a data RAM/ROM, and it also allows the linker to combine literal
13217pools from separate object files to remove redundant literals and
13218improve code size. With @option{-mtext-section-literals}, the literals
13219are interspersed in the text section in order to keep them as close as
13220possible to their references. This may be necessary for large assembly
13221files.
13222
13223@item -mtarget-align
13224@itemx -mno-target-align
13225@opindex mtarget-align
13226@opindex mno-target-align
13227When this option is enabled, GCC instructs the assembler to
13228automatically align instructions to reduce branch penalties at the
13229expense of some code density. The assembler attempts to widen density
13230instructions to align branch targets and the instructions following call
13231instructions. If there are not enough preceding safe density
13232instructions to align a target, no widening will be performed. The
13233default is @option{-mtarget-align}. These options do not affect the
13234treatment of auto-aligned instructions like @code{LOOP}, which the
13235assembler will always align, either by widening density instructions or
13236by inserting no-op instructions.
13237
13238@item -mlongcalls
13239@itemx -mno-longcalls
13240@opindex mlongcalls
13241@opindex mno-longcalls
13242When this option is enabled, GCC instructs the assembler to translate
13243direct calls to indirect calls unless it can determine that the target
13244of a direct call is in the range allowed by the call instruction. This
13245translation typically occurs for calls to functions in other source
13246files. Specifically, the assembler translates a direct @code{CALL}
13247instruction into an @code{L32R} followed by a @code{CALLX} instruction.
13248The default is @option{-mno-longcalls}. This option should be used in
13249programs where the call target can potentially be out of range. This
13250option is implemented in the assembler, not the compiler, so the
13251assembly code generated by GCC will still show direct call
13252instructions---look at the disassembled object code to see the actual
13253instructions. Note that the assembler will use an indirect call for
13254every cross-file call, not just those that really will be out of range.
13255@end table
13256
13257@node zSeries Options
13258@subsection zSeries Options
13259@cindex zSeries options
13260
13261These are listed under @xref{S/390 and zSeries Options}.
13262
13263@node Code Gen Options
13264@section Options for Code Generation Conventions
13265@cindex code generation conventions
13266@cindex options, code generation
13267@cindex run-time options
13268
13269These machine-independent options control the interface conventions
13270used in code generation.
13271
13272Most of them have both positive and negative forms; the negative form
13273of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
13274one of the forms is listed---the one which is not the default. You
13275can figure out the other form by either removing @samp{no-} or adding
13276it.
13277
13278@table @gcctabopt
13279@item -fbounds-check
13280@opindex fbounds-check
13281For front-ends that support it, generate additional code to check that
13282indices used to access arrays are within the declared range. This is
13283currently only supported by the Java and Fortran front-ends, where
13284this option defaults to true and false respectively.
13285
13286@item -ftrapv
13287@opindex ftrapv
13288This option generates traps for signed overflow on addition, subtraction,
13289multiplication operations.
13290
13291@item -fwrapv
13292@opindex fwrapv
13293This option instructs the compiler to assume that signed arithmetic
13294overflow of addition, subtraction and multiplication wraps around
13295using twos-complement representation. This flag enables some optimizations
13296and disables others. This option is enabled by default for the Java
13297front-end, as required by the Java language specification.
13298
13299@item -fexceptions
13300@opindex fexceptions
13301Enable exception handling. Generates extra code needed to propagate
13302exceptions. For some targets, this implies GCC will generate frame
13303unwind information for all functions, which can produce significant data
13304size overhead, although it does not affect execution. If you do not
13305specify this option, GCC will enable it by default for languages like
13306C++ which normally require exception handling, and disable it for
13307languages like C that do not normally require it. However, you may need
13308to enable this option when compiling C code that needs to interoperate
13309properly with exception handlers written in C++. You may also wish to
13310disable this option if you are compiling older C++ programs that don't
13311use exception handling.
13312
13313@item -fnon-call-exceptions
13314@opindex fnon-call-exceptions
13315Generate code that allows trapping instructions to throw exceptions.
13316Note that this requires platform-specific runtime support that does
13317not exist everywhere. Moreover, it only allows @emph{trapping}
13318instructions to throw exceptions, i.e.@: memory references or floating
13319point instructions. It does not allow exceptions to be thrown from
13320arbitrary signal handlers such as @code{SIGALRM}.
13321
13322@item -funwind-tables
13323@opindex funwind-tables
13324Similar to @option{-fexceptions}, except that it will just generate any needed
13325static data, but will not affect the generated code in any other way.
13326You will normally not enable this option; instead, a language processor
13327that needs this handling would enable it on your behalf.
13328
13329@item -fasynchronous-unwind-tables
13330@opindex fasynchronous-unwind-tables
13331Generate unwind table in dwarf2 format, if supported by target machine. The
13332table is exact at each instruction boundary, so it can be used for stack
13333unwinding from asynchronous events (such as debugger or garbage collector).
13334
13335@item -fpcc-struct-return
13336@opindex fpcc-struct-return
13337Return ``short'' @code{struct} and @code{union} values in memory like
13338longer ones, rather than in registers. This convention is less
13339efficient, but it has the advantage of allowing intercallability between
13340GCC-compiled files and files compiled with other compilers, particularly
13341the Portable C Compiler (pcc).
13342
13343The precise convention for returning structures in memory depends
13344on the target configuration macros.
13345
13346Short structures and unions are those whose size and alignment match
13347that of some integer type.
13348
13349@strong{Warning:} code compiled with the @option{-fpcc-struct-return}
13350switch is not binary compatible with code compiled with the
13351@option{-freg-struct-return} switch.
13352Use it to conform to a non-default application binary interface.
13353
13354@item -freg-struct-return
13355@opindex freg-struct-return
13356Return @code{struct} and @code{union} values in registers when possible.
13357This is more efficient for small structures than
13358@option{-fpcc-struct-return}.
13359
13360If you specify neither @option{-fpcc-struct-return} nor
13361@option{-freg-struct-return}, GCC defaults to whichever convention is
13362standard for the target. If there is no standard convention, GCC
13363defaults to @option{-fpcc-struct-return}, except on targets where GCC is
13364the principal compiler. In those cases, we can choose the standard, and
13365we chose the more efficient register return alternative.
13366
13367@strong{Warning:} code compiled with the @option{-freg-struct-return}
13368switch is not binary compatible with code compiled with the
13369@option{-fpcc-struct-return} switch.
13370Use it to conform to a non-default application binary interface.
13371
13372@item -fshort-enums
13373@opindex fshort-enums
13374Allocate to an @code{enum} type only as many bytes as it needs for the
13375declared range of possible values. Specifically, the @code{enum} type
13376will be equivalent to the smallest integer type which has enough room.
13377
13378@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
13379code that is not binary compatible with code generated without that switch.
13380Use it to conform to a non-default application binary interface.
13381
13382@item -fshort-double
13383@opindex fshort-double
13384Use the same size for @code{double} as for @code{float}.
13385
13386@strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
13387code that is not binary compatible with code generated without that switch.
13388Use it to conform to a non-default application binary interface.
13389
13390@item -fshort-wchar
13391@opindex fshort-wchar
13392Override the underlying type for @samp{wchar_t} to be @samp{short
13393unsigned int} instead of the default for the target. This option is
13394useful for building programs to run under WINE@.
13395
13396@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
13397code that is not binary compatible with code generated without that switch.
13398Use it to conform to a non-default application binary interface.
13399
13400@item -fno-common
13401@opindex fno-common
13402In C, allocate even uninitialized global variables in the data section of the
13403object file, rather than generating them as common blocks. This has the
13404effect that if the same variable is declared (without @code{extern}) in
13405two different compilations, you will get an error when you link them.
13406The only reason this might be useful is if you wish to verify that the
13407program will work on other systems which always work this way.
13408
13409@item -fno-ident
13410@opindex fno-ident
13411Ignore the @samp{#ident} directive.
13412
13413@item -finhibit-size-directive
13414@opindex finhibit-size-directive
13415Don't output a @code{.size} assembler directive, or anything else that
13416would cause trouble if the function is split in the middle, and the
13417two halves are placed at locations far apart in memory. This option is
13418used when compiling @file{crtstuff.c}; you should not need to use it
13419for anything else.
13420
13421@item -fverbose-asm
13422@opindex fverbose-asm
13423Put extra commentary information in the generated assembly code to
13424make it more readable. This option is generally only of use to those
13425who actually need to read the generated assembly code (perhaps while
13426debugging the compiler itself).
13427
13428@option{-fno-verbose-asm}, the default, causes the
13429extra information to be omitted and is useful when comparing two assembler
13430files.
13431
13432@item -fpic
13433@opindex fpic
13434@cindex global offset table
13435@cindex PIC
13436Generate position-independent code (PIC) suitable for use in a shared
13437library, if supported for the target machine. Such code accesses all
13438constant addresses through a global offset table (GOT)@. The dynamic
13439loader resolves the GOT entries when the program starts (the dynamic
13440loader is not part of GCC; it is part of the operating system). If
13441the GOT size for the linked executable exceeds a machine-specific
13442maximum size, you get an error message from the linker indicating that
13443@option{-fpic} does not work; in that case, recompile with @option{-fPIC}
13444instead. (These maximums are 8k on the SPARC and 32k
13445on the m68k and RS/6000. The 386 has no such limit.)
13446
13447Position-independent code requires special support, and therefore works
13448only on certain machines. For the 386, GCC supports PIC for System V
13449but not for the Sun 386i. Code generated for the IBM RS/6000 is always
13450position-independent.
13451
13452When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13453are defined to 1.
13454
13455@item -fPIC
13456@opindex fPIC
13457If supported for the target machine, emit position-independent code,
13458suitable for dynamic linking and avoiding any limit on the size of the
13459global offset table. This option makes a difference on the m68k,
13460PowerPC and SPARC@.
13461
13462Position-independent code requires special support, and therefore works
13463only on certain machines.
13464
13465When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13466are defined to 2.
13467
13468@item -fpie
13469@itemx -fPIE
13470@opindex fpie
13471@opindex fPIE
13472These options are similar to @option{-fpic} and @option{-fPIC}, but
13473generated position independent code can be only linked into executables.
13474Usually these options are used when @option{-pie} GCC option will be
13475used during linking.
13476
13477@item -fno-jump-tables
13478@opindex fno-jump-tables
13479Do not use jump tables for switch statements even where it would be
13480more efficient than other code generation strategies. This option is
13481of use in conjunction with @option{-fpic} or @option{-fPIC} for
13482building code which forms part of a dynamic linker and cannot
13483reference the address of a jump table. On some targets, jump tables
13484do not require a GOT and this option is not needed.
13485
13486@item -ffixed-@var{reg}
13487@opindex ffixed
13488Treat the register named @var{reg} as a fixed register; generated code
13489should never refer to it (except perhaps as a stack pointer, frame
13490pointer or in some other fixed role).
13491
13492@var{reg} must be the name of a register. The register names accepted
13493are machine-specific and are defined in the @code{REGISTER_NAMES}
13494macro in the machine description macro file.
13495
13496This flag does not have a negative form, because it specifies a
13497three-way choice.
13498
13499@item -fcall-used-@var{reg}
13500@opindex fcall-used
13501Treat the register named @var{reg} as an allocable register that is
13502clobbered by function calls. It may be allocated for temporaries or
13503variables that do not live across a call. Functions compiled this way
13504will not save and restore the register @var{reg}.
13505
13506It is an error to used this flag with the frame pointer or stack pointer.
13507Use of this flag for other registers that have fixed pervasive roles in
13508the machine's execution model will produce disastrous results.
13509
13510This flag does not have a negative form, because it specifies a
13511three-way choice.
13512
13513@item -fcall-saved-@var{reg}
13514@opindex fcall-saved
13515Treat the register named @var{reg} as an allocable register saved by
13516functions. It may be allocated even for temporaries or variables that
13517live across a call. Functions compiled this way will save and restore
13518the register @var{reg} if they use it.
13519
13520It is an error to used this flag with the frame pointer or stack pointer.
13521Use of this flag for other registers that have fixed pervasive roles in
13522the machine's execution model will produce disastrous results.
13523
13524A different sort of disaster will result from the use of this flag for
13525a register in which function values may be returned.
13526
13527This flag does not have a negative form, because it specifies a
13528three-way choice.
13529
13530@item -fpack-struct[=@var{n}]
13531@opindex fpack-struct
13532Without a value specified, pack all structure members together without
13533holes. When a value is specified (which must be a small power of two), pack
13534structure members according to this value, representing the maximum
13535alignment (that is, objects with default alignment requirements larger than
13536this will be output potentially unaligned at the next fitting location.
13537
13538@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
13539code that is not binary compatible with code generated without that switch.
13540Additionally, it makes the code suboptimal.
13541Use it to conform to a non-default application binary interface.
13542
13543@item -finstrument-functions
13544@opindex finstrument-functions
13545Generate instrumentation calls for entry and exit to functions. Just
13546after function entry and just before function exit, the following
13547profiling functions will be called with the address of the current
13548function and its call site. (On some platforms,
13549@code{__builtin_return_address} does not work beyond the current
13550function, so the call site information may not be available to the
13551profiling functions otherwise.)
13552
13553@smallexample
13554void __cyg_profile_func_enter (void *this_fn,
13555 void *call_site);
13556void __cyg_profile_func_exit (void *this_fn,
13557 void *call_site);
13558@end smallexample
13559
13560The first argument is the address of the start of the current function,
13561which may be looked up exactly in the symbol table.
13562
13563This instrumentation is also done for functions expanded inline in other
13564functions. The profiling calls will indicate where, conceptually, the
13565inline function is entered and exited. This means that addressable
13566versions of such functions must be available. If all your uses of a
13567function are expanded inline, this may mean an additional expansion of
13568code size. If you use @samp{extern inline} in your C code, an
13569addressable version of such functions must be provided. (This is
13570normally the case anyways, but if you get lucky and the optimizer always
13571expands the functions inline, you might have gotten away without
13572providing static copies.)
13573
13574A function may be given the attribute @code{no_instrument_function}, in
13575which case this instrumentation will not be done. This can be used, for
13576example, for the profiling functions listed above, high-priority
13577interrupt routines, and any functions from which the profiling functions
13578cannot safely be called (perhaps signal handlers, if the profiling
13579routines generate output or allocate memory).
13580
13581@item -fstack-check
13582@opindex fstack-check
13583Generate code to verify that you do not go beyond the boundary of the
13584stack. You should specify this flag if you are running in an
13585environment with multiple threads, but only rarely need to specify it in
13586a single-threaded environment since stack overflow is automatically
13587detected on nearly all systems if there is only one stack.
13588
13589Note that this switch does not actually cause checking to be done; the
13590operating system must do that. The switch causes generation of code
13591to ensure that the operating system sees the stack being extended.
13592
13593@item -fstack-limit-register=@var{reg}
13594@itemx -fstack-limit-symbol=@var{sym}
13595@itemx -fno-stack-limit
13596@opindex fstack-limit-register
13597@opindex fstack-limit-symbol
13598@opindex fno-stack-limit
13599Generate code to ensure that the stack does not grow beyond a certain value,
13600either the value of a register or the address of a symbol. If the stack
13601would grow beyond the value, a signal is raised. For most targets,
13602the signal is raised before the stack overruns the boundary, so
13603it is possible to catch the signal without taking special precautions.
13604
13605For instance, if the stack starts at absolute address @samp{0x80000000}
13606and grows downwards, you can use the flags
13607@option{-fstack-limit-symbol=__stack_limit} and
13608@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
13609of 128KB@. Note that this may only work with the GNU linker.
13610
13611@cindex aliasing of parameters
13612@cindex parameters, aliased
13613@item -fargument-alias
13614@itemx -fargument-noalias
13615@itemx -fargument-noalias-global
13616@itemx -fargument-noalias-anything
13617@opindex fargument-alias
13618@opindex fargument-noalias
13619@opindex fargument-noalias-global
13620@opindex fargument-noalias-anything
13621Specify the possible relationships among parameters and between
13622parameters and global data.
13623
13624@option{-fargument-alias} specifies that arguments (parameters) may
13625alias each other and may alias global storage.@*
13626@option{-fargument-noalias} specifies that arguments do not alias
13627each other, but may alias global storage.@*
13628@option{-fargument-noalias-global} specifies that arguments do not
13629alias each other and do not alias global storage.
13630@option{-fargument-noalias-anything} specifies that arguments do not
13631alias any other storage.
13632
13633Each language will automatically use whatever option is required by
13634the language standard. You should not need to use these options yourself.
13635
13636@item -fleading-underscore
13637@opindex fleading-underscore
13638This option and its counterpart, @option{-fno-leading-underscore}, forcibly
13639change the way C symbols are represented in the object file. One use
13640is to help link with legacy assembly code.
13641
13642@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
13643generate code that is not binary compatible with code generated without that
13644switch. Use it to conform to a non-default application binary interface.
13645Not all targets provide complete support for this switch.
13646
13647@item -ftls-model=@var{model}
13648Alter the thread-local storage model to be used (@pxref{Thread-Local}).
13649The @var{model} argument should be one of @code{global-dynamic},
13650@code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
13651
13652The default without @option{-fpic} is @code{initial-exec}; with
13653@option{-fpic} the default is @code{global-dynamic}.
13654
13655@item -fvisibility=@var{default|internal|hidden|protected}
13656@opindex fvisibility
13657Set the default ELF image symbol visibility to the specified option---all
13658symbols will be marked with this unless overridden within the code.
13659Using this feature can very substantially improve linking and
13660load times of shared object libraries, produce more optimized
13661code, provide near-perfect API export and prevent symbol clashes.
13662It is @strong{strongly} recommended that you use this in any shared objects
13663you distribute.
13664
13665Despite the nomenclature, @code{default} always means public ie;
13666available to be linked against from outside the shared object.
13667@code{protected} and @code{internal} are pretty useless in real-world
13668usage so the only other commonly used option will be @code{hidden}.
13669The default if @option{-fvisibility} isn't specified is
13670@code{default}, i.e., make every
13671symbol public---this causes the same behavior as previous versions of
13672GCC@.
13673
13674A good explanation of the benefits offered by ensuring ELF
13675symbols have the correct visibility is given by ``How To Write
13676Shared Libraries'' by Ulrich Drepper (which can be found at
13677@w{@uref{http://people.redhat.com/~drepper/}})---however a superior
13678solution made possible by this option to marking things hidden when
13679the default is public is to make the default hidden and mark things
13680public. This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
13681and @code{__attribute__ ((visibility("default")))} instead of
13682@code{__declspec(dllexport)} you get almost identical semantics with
13683identical syntax. This is a great boon to those working with
13684cross-platform projects.
13685
13686For those adding visibility support to existing code, you may find
13687@samp{#pragma GCC visibility} of use. This works by you enclosing
13688the declarations you wish to set visibility for with (for example)
13689@samp{#pragma GCC visibility push(hidden)} and
13690@samp{#pragma GCC visibility pop}.
13691Bear in mind that symbol visibility should be viewed @strong{as
13692part of the API interface contract} and thus all new code should
13693always specify visibility when it is not the default ie; declarations
13694only for use within the local DSO should @strong{always} be marked explicitly
13695as hidden as so to avoid PLT indirection overheads---making this
13696abundantly clear also aids readability and self-documentation of the code.
13697Note that due to ISO C++ specification requirements, operator new and
13698operator delete must always be of default visibility.
13699
13700Be aware that headers from outside your project, in particular system
13701headers and headers from any other library you use, may not be
13702expecting to be compiled with visibility other than the default. You
13703may need to explicitly say @samp{#pragma GCC visibility push(default)}
13704before including any such headers.
13705
13706@samp{extern} declarations are not affected by @samp{-fvisibility}, so
13707a lot of code can be recompiled with @samp{-fvisibility=hidden} with
13708no modifications. However, this means that calls to @samp{extern}
13709functions with no explicit visibility will use the PLT, so it is more
13710effective to use @samp{__attribute ((visibility))} and/or
13711@samp{#pragma GCC visibility} to tell the compiler which @samp{extern}
13712declarations should be treated as hidden.
13713
13714Note that @samp{-fvisibility} does affect C++ vague linkage
13715entities. This means that, for instance, an exception class that will
13716be thrown between DSOs must be explicitly marked with default
13717visibility so that the @samp{type_info} nodes will be unified between
13718the DSOs.
13719
13720An overview of these techniques, their benefits and how to use them
13721is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
13722
13723@end table
13724
13725@c man end
13726
13727@node Environment Variables
13728@section Environment Variables Affecting GCC
13729@cindex environment variables
13730
13731@c man begin ENVIRONMENT
13732This section describes several environment variables that affect how GCC
13733operates. Some of them work by specifying directories or prefixes to use
13734when searching for various kinds of files. Some are used to specify other
13735aspects of the compilation environment.
13736
13737Note that you can also specify places to search using options such as
13738@option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
13739take precedence over places specified using environment variables, which
13740in turn take precedence over those specified by the configuration of GCC@.
13741@xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
13742GNU Compiler Collection (GCC) Internals}.
13743
13744@table @env
13745@item LANG
13746@itemx LC_CTYPE
13747@c @itemx LC_COLLATE
13748@itemx LC_MESSAGES
13749@c @itemx LC_MONETARY
13750@c @itemx LC_NUMERIC
13751@c @itemx LC_TIME
13752@itemx LC_ALL
13753@findex LANG
13754@findex LC_CTYPE
13755@c @findex LC_COLLATE
13756@findex LC_MESSAGES
13757@c @findex LC_MONETARY
13758@c @findex LC_NUMERIC
13759@c @findex LC_TIME
13760@findex LC_ALL
13761@cindex locale
13762These environment variables control the way that GCC uses
13763localization information that allow GCC to work with different
13764national conventions. GCC inspects the locale categories
13765@env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
13766so. These locale categories can be set to any value supported by your
13767installation. A typical value is @samp{en_GB.UTF-8} for English in the United
13768Kingdom encoded in UTF-8.
13769
13770The @env{LC_CTYPE} environment variable specifies character
13771classification. GCC uses it to determine the character boundaries in
13772a string; this is needed for some multibyte encodings that contain quote
13773and escape characters that would otherwise be interpreted as a string
13774end or escape.
13775
13776The @env{LC_MESSAGES} environment variable specifies the language to
13777use in diagnostic messages.
13778
13779If the @env{LC_ALL} environment variable is set, it overrides the value
13780of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
13781and @env{LC_MESSAGES} default to the value of the @env{LANG}
13782environment variable. If none of these variables are set, GCC
13783defaults to traditional C English behavior.
13784
13785@item TMPDIR
13786@findex TMPDIR
13787If @env{TMPDIR} is set, it specifies the directory to use for temporary
13788files. GCC uses temporary files to hold the output of one stage of
13789compilation which is to be used as input to the next stage: for example,
13790the output of the preprocessor, which is the input to the compiler
13791proper.
13792
13793@item GCC_EXEC_PREFIX
13794@findex GCC_EXEC_PREFIX
13795If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
13796names of the subprograms executed by the compiler. No slash is added
13797when this prefix is combined with the name of a subprogram, but you can
13798specify a prefix that ends with a slash if you wish.
13799
13800If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
13801an appropriate prefix to use based on the pathname it was invoked with.
13802
13803If GCC cannot find the subprogram using the specified prefix, it
13804tries looking in the usual places for the subprogram.
13805
13806The default value of @env{GCC_EXEC_PREFIX} is
13807@file{@var{prefix}/lib/gcc/} where @var{prefix} is the value
13808of @code{prefix} when you ran the @file{configure} script.
13809
13810Other prefixes specified with @option{-B} take precedence over this prefix.
13811
13812This prefix is also used for finding files such as @file{crt0.o} that are
13813used for linking.
13814
13815In addition, the prefix is used in an unusual way in finding the
13816directories to search for header files. For each of the standard
13817directories whose name normally begins with @samp{/usr/local/lib/gcc}
13818(more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
13819replacing that beginning with the specified prefix to produce an
13820alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
13821@file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
13822These alternate directories are searched first; the standard directories
13823come next.
13824
13825@item COMPILER_PATH
13826@findex COMPILER_PATH
13827The value of @env{COMPILER_PATH} is a colon-separated list of
13828directories, much like @env{PATH}. GCC tries the directories thus
13829specified when searching for subprograms, if it can't find the
13830subprograms using @env{GCC_EXEC_PREFIX}.
13831
13832@item LIBRARY_PATH
13833@findex LIBRARY_PATH
13834The value of @env{LIBRARY_PATH} is a colon-separated list of
13835directories, much like @env{PATH}. When configured as a native compiler,
13836GCC tries the directories thus specified when searching for special
13837linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking
13838using GCC also uses these directories when searching for ordinary
13839libraries for the @option{-l} option (but directories specified with
13840@option{-L} come first).
13841
13842@item LANG
13843@findex LANG
13844@cindex locale definition
13845This variable is used to pass locale information to the compiler. One way in
13846which this information is used is to determine the character set to be used
13847when character literals, string literals and comments are parsed in C and C++.
13848When the compiler is configured to allow multibyte characters,
13849the following values for @env{LANG} are recognized:
13850
13851@table @samp
13852@item C-JIS
13853Recognize JIS characters.
13854@item C-SJIS
13855Recognize SJIS characters.
13856@item C-EUCJP
13857Recognize EUCJP characters.
13858@end table
13859
13860If @env{LANG} is not defined, or if it has some other value, then the
13861compiler will use mblen and mbtowc as defined by the default locale to
13862recognize and translate multibyte characters.
13863@end table
13864
13865@noindent
13866Some additional environments variables affect the behavior of the
13867preprocessor.
13868
13869@include cppenv.texi
13870
13871@c man end
13872
13873@node Precompiled Headers
13874@section Using Precompiled Headers
13875@cindex precompiled headers
13876@cindex speed of compilation
13877
13878Often large projects have many header files that are included in every
13879source file. The time the compiler takes to process these header files
13880over and over again can account for nearly all of the time required to
13881build the project. To make builds faster, GCC allows users to
13882`precompile' a header file; then, if builds can use the precompiled
13883header file they will be much faster.
13884
13885To create a precompiled header file, simply compile it as you would any
13886other file, if necessary using the @option{-x} option to make the driver
13887treat it as a C or C++ header file. You will probably want to use a
13888tool like @command{make} to keep the precompiled header up-to-date when
13889the headers it contains change.
13890
13891A precompiled header file will be searched for when @code{#include} is
13892seen in the compilation. As it searches for the included file
13893(@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
13894compiler looks for a precompiled header in each directory just before it
13895looks for the include file in that directory. The name searched for is
13896the name specified in the @code{#include} with @samp{.gch} appended. If
13897the precompiled header file can't be used, it is ignored.
13898
13899For instance, if you have @code{#include "all.h"}, and you have
13900@file{all.h.gch} in the same directory as @file{all.h}, then the
13901precompiled header file will be used if possible, and the original
13902header will be used otherwise.
13903
13904Alternatively, you might decide to put the precompiled header file in a
13905directory and use @option{-I} to ensure that directory is searched
13906before (or instead of) the directory containing the original header.
13907Then, if you want to check that the precompiled header file is always
13908used, you can put a file of the same name as the original header in this
13909directory containing an @code{#error} command.
13910
13911This also works with @option{-include}. So yet another way to use
13912precompiled headers, good for projects not designed with precompiled
13913header files in mind, is to simply take most of the header files used by
13914a project, include them from another header file, precompile that header
13915file, and @option{-include} the precompiled header. If the header files
13916have guards against multiple inclusion, they will be skipped because
13917they've already been included (in the precompiled header).
13918
13919If you need to precompile the same header file for different
13920languages, targets, or compiler options, you can instead make a
13921@emph{directory} named like @file{all.h.gch}, and put each precompiled
13922header in the directory, perhaps using @option{-o}. It doesn't matter
13923what you call the files in the directory, every precompiled header in
13924the directory will be considered. The first precompiled header
13925encountered in the directory that is valid for this compilation will
13926be used; they're searched in no particular order.
13927
13928There are many other possibilities, limited only by your imagination,
13929good sense, and the constraints of your build system.
13930
13931A precompiled header file can be used only when these conditions apply:
13932
13933@itemize
13934@item
13935Only one precompiled header can be used in a particular compilation.
13936
13937@item
13938A precompiled header can't be used once the first C token is seen. You
13939can have preprocessor directives before a precompiled header; you can
13940even include a precompiled header from inside another header, so long as
13941there are no C tokens before the @code{#include}.
13942
13943@item
13944The precompiled header file must be produced for the same language as
13945the current compilation. You can't use a C precompiled header for a C++
13946compilation.
13947
13948@item
13949The precompiled header file must have been produced by the same compiler
13950binary as the current compilation is using.
13951
13952@item
13953Any macros defined before the precompiled header is included must
13954either be defined in the same way as when the precompiled header was
13955generated, or must not affect the precompiled header, which usually
13956means that they don't appear in the precompiled header at all.
13957
13958The @option{-D} option is one way to define a macro before a
13959precompiled header is included; using a @code{#define} can also do it.
13960There are also some options that define macros implicitly, like
13961@option{-O} and @option{-Wdeprecated}; the same rule applies to macros
13962defined this way.
13963
13964@item If debugging information is output when using the precompiled
13965header, using @option{-g} or similar, the same kind of debugging information
13966must have been output when building the precompiled header. However,
13967a precompiled header built using @option{-g} can be used in a compilation
13968when no debugging information is being output.
13969
13970@item The same @option{-m} options must generally be used when building
13971and using the precompiled header. @xref{Submodel Options},
13972for any cases where this rule is relaxed.
13973
13974@item Each of the following options must be the same when building and using
13975the precompiled header:
13976
13977@gccoptlist{-fexceptions -funit-at-a-time}
13978
13979@item
13980Some other command-line options starting with @option{-f},
13981@option{-p}, or @option{-O} must be defined in the same way as when
13982the precompiled header was generated. At present, it's not clear
13983which options are safe to change and which are not; the safest choice
13984is to use exactly the same options when generating and using the
13985precompiled header. The following are known to be safe:
13986
13987@gccoptlist{-fmessage-length= -fpreprocessed
13988-fsched-interblock -fsched-spec -fsched-spec-load -fsched-spec-load-dangerous
13989-fsched-verbose=<number> -fschedule-insns -fvisibility=
13990-pedantic-errors}
13991
13992@end itemize
13993
13994For all of these except the last, the compiler will automatically
13995ignore the precompiled header if the conditions aren't met. If you
13996find an option combination that doesn't work and doesn't cause the
13997precompiled header to be ignored, please consider filing a bug report,
13998see @ref{Bugs}.
13999
14000If you do use differing options when generating and using the
14001precompiled header, the actual behavior will be a mixture of the
14002behavior for the options. For instance, if you use @option{-g} to
14003generate the precompiled header but not when using it, you may or may
14004not get debugging information for routines in the precompiled header.
14005
14006@node Running Protoize
14007@section Running Protoize
14008
14009The program @code{protoize} is an optional part of GCC@. You can use
14010it to add prototypes to a program, thus converting the program to ISO
14011C in one respect. The companion program @code{unprotoize} does the
14012reverse: it removes argument types from any prototypes that are found.
14013
14014When you run these programs, you must specify a set of source files as
14015command line arguments. The conversion programs start out by compiling
14016these files to see what functions they define. The information gathered
14017about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
14018
14019After scanning comes actual conversion. The specified files are all
14020eligible to be converted; any files they include (whether sources or
14021just headers) are eligible as well.
14022
14023But not all the eligible files are converted. By default,
14024@code{protoize} and @code{unprotoize} convert only source and header
14025files in the current directory. You can specify additional directories
14026whose files should be converted with the @option{-d @var{directory}}
14027option. You can also specify particular files to exclude with the
14028@option{-x @var{file}} option. A file is converted if it is eligible, its
14029directory name matches one of the specified directory names, and its
14030name within the directory has not been excluded.
14031
14032Basic conversion with @code{protoize} consists of rewriting most
14033function definitions and function declarations to specify the types of
14034the arguments. The only ones not rewritten are those for varargs
14035functions.
14036
14037@code{protoize} optionally inserts prototype declarations at the
14038beginning of the source file, to make them available for any calls that
14039precede the function's definition. Or it can insert prototype
14040declarations with block scope in the blocks where undeclared functions
14041are called.
14042
14043Basic conversion with @code{unprotoize} consists of rewriting most
14044function declarations to remove any argument types, and rewriting
14045function definitions to the old-style pre-ISO form.
14046
14047Both conversion programs print a warning for any function declaration or
14048definition that they can't convert. You can suppress these warnings
14049with @option{-q}.
14050
14051The output from @code{protoize} or @code{unprotoize} replaces the
14052original source file. The original file is renamed to a name ending
14053with @samp{.save} (for DOS, the saved filename ends in @samp{.sav}
14054without the original @samp{.c} suffix). If the @samp{.save} (@samp{.sav}
14055for DOS) file already exists, then the source file is simply discarded.
14056
14057@code{protoize} and @code{unprotoize} both depend on GCC itself to
14058scan the program and collect information about the functions it uses.
14059So neither of these programs will work until GCC is installed.
14060
14061Here is a table of the options you can use with @code{protoize} and
14062@code{unprotoize}. Each option works with both programs unless
14063otherwise stated.
14064
14065@table @code
14066@item -B @var{directory}
14067Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
14068usual directory (normally @file{/usr/local/lib}). This file contains
14069prototype information about standard system functions. This option
14070applies only to @code{protoize}.
14071
14072@item -c @var{compilation-options}
14073Use @var{compilation-options} as the options when running @command{gcc} to
14074produce the @samp{.X} files. The special option @option{-aux-info} is
14075always passed in addition, to tell @command{gcc} to write a @samp{.X} file.
14076
14077Note that the compilation options must be given as a single argument to
14078@code{protoize} or @code{unprotoize}. If you want to specify several
14079@command{gcc} options, you must quote the entire set of compilation options
14080to make them a single word in the shell.
14081
14082There are certain @command{gcc} arguments that you cannot use, because they
14083would produce the wrong kind of output. These include @option{-g},
14084@option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in
14085the @var{compilation-options}, they are ignored.
14086
14087@item -C
14088Rename files to end in @samp{.C} (@samp{.cc} for DOS-based file
14089systems) instead of @samp{.c}. This is convenient if you are converting
14090a C program to C++. This option applies only to @code{protoize}.
14091
14092@item -g
14093Add explicit global declarations. This means inserting explicit
14094declarations at the beginning of each source file for each function
14095that is called in the file and was not declared. These declarations
14096precede the first function definition that contains a call to an
14097undeclared function. This option applies only to @code{protoize}.
14098
14099@item -i @var{string}
14100Indent old-style parameter declarations with the string @var{string}.
14101This option applies only to @code{protoize}.
14102
14103@code{unprotoize} converts prototyped function definitions to old-style
14104function definitions, where the arguments are declared between the
14105argument list and the initial @samp{@{}. By default, @code{unprotoize}
14106uses five spaces as the indentation. If you want to indent with just
14107one space instead, use @option{-i " "}.
14108
14109@item -k
14110Keep the @samp{.X} files. Normally, they are deleted after conversion
14111is finished.
14112
14113@item -l
14114Add explicit local declarations. @code{protoize} with @option{-l} inserts
14115a prototype declaration for each function in each block which calls the
14116function without any declaration. This option applies only to
14117@code{protoize}.
14118
14119@item -n
14120Make no real changes. This mode just prints information about the conversions
14121that would have been done without @option{-n}.
14122
14123@item -N
14124Make no @samp{.save} files. The original files are simply deleted.
14125Use this option with caution.
14126
14127@item -p @var{program}
14128Use the program @var{program} as the compiler. Normally, the name
14129@file{gcc} is used.
14130
14131@item -q
14132Work quietly. Most warnings are suppressed.
14133
14134@item -v
14135Print the version number, just like @option{-v} for @command{gcc}.
14136@end table
14137
14138If you need special compiler options to compile one of your program's
14139source files, then you should generate that file's @samp{.X} file
14140specially, by running @command{gcc} on that source file with the
14141appropriate options and the option @option{-aux-info}. Then run
14142@code{protoize} on the entire set of files. @code{protoize} will use
14143the existing @samp{.X} file because it is newer than the source file.
14144For example:
14145
14146@smallexample
14147gcc -Dfoo=bar file1.c -aux-info file1.X
14148protoize *.c
14149@end smallexample
14150
14151@noindent
14152You need to include the special files along with the rest in the
14153@code{protoize} command, even though their @samp{.X} files already
14154exist, because otherwise they won't get converted.
14155
14156@xref{Protoize Caveats}, for more information on how to use
14157@code{protoize} successfully.
|