1@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2@c 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
3@c This is part of the GCC manual.
4@c For copying conditions, see the file gcc.texi.
5
6@ignore
7@c man begin INCLUDE
8@include gcc-vers.texi
9@c man end
10
11@c man begin COPYRIGHT
12Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
131999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
14
15Permission is granted to copy, distribute and/or modify this document
16under the terms of the GNU Free Documentation License, Version 1.2 or
17any later version published by the Free Software Foundation; with the
18Invariant Sections being ``GNU General Public License'' and ``Funding
19Free Software'', the Front-Cover texts being (a) (see below), and with
20the Back-Cover Texts being (b) (see below). A copy of the license is
21included in the gfdl(7) man page.
22
23(a) The FSF's Front-Cover Text is:
24
25 A GNU Manual
26
27(b) The FSF's Back-Cover Text is:
28
29 You have freedom to copy and modify this GNU Manual, like GNU
30 software. Copies published by the Free Software Foundation raise
31 funds for GNU development.
32@c man end
33@c Set file name and title for the man page.
34@setfilename gcc
35@settitle GNU project C and C++ compiler
36@c man begin SYNOPSIS
37gcc [@option{-c}|@option{-S}|@option{-E}] [@option{-std=}@var{standard}]
38 [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
39 [@option{-W}@var{warn}@dots{}] [@option{-pedantic}]
40 [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
41 [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
42 [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
43 [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}
44
45Only the most useful options are listed here; see below for the
46remainder. @samp{g++} accepts mostly the same options as @samp{gcc}.
47@c man end
48@c man begin SEEALSO
49gpl(7), gfdl(7), fsf-funding(7),
50cpp(1), gcov(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1)
51and the Info entries for @file{gcc}, @file{cpp}, @file{as},
52@file{ld}, @file{binutils} and @file{gdb}.
53@c man end
54@c man begin BUGS
55For instructions on reporting bugs, see
56@w{@uref{http://gcc.gnu.org/bugs.html}}.
57@c man end
58@c man begin AUTHOR
59See the Info entry for @command{gcc}, or
60@w{@uref{http://gcc.gnu.org/onlinedocs/gcc/Contributors.html}},
61for contributors to GCC@.
62@c man end
63@end ignore
64
65@node Invoking GCC
66@chapter GCC Command Options
67@cindex GCC command options
68@cindex command options
69@cindex options, GCC command
70
71@c man begin DESCRIPTION
72When you invoke GCC, it normally does preprocessing, compilation,
73assembly and linking. The ``overall options'' allow you to stop this
74process at an intermediate stage. For example, the @option{-c} option
75says not to run the linker. Then the output consists of object files
76output by the assembler.
77
78Other options are passed on to one stage of processing. Some options
79control the preprocessor and others the compiler itself. Yet other
80options control the assembler and linker; most of these are not
81documented here, since you rarely need to use any of them.
82
83@cindex C compilation options
84Most of the command line options that you can use with GCC are useful
85for C programs; when an option is only useful with another language
86(usually C++), the explanation says so explicitly. If the description
87for a particular option does not mention a source language, you can use
88that option with all supported languages.
89
90@cindex C++ compilation options
91@xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
92options for compiling C++ programs.
93
94@cindex grouping options
95@cindex options, grouping
96The @command{gcc} program accepts options and file names as operands. Many
97options have multi-letter names; therefore multiple single-letter options
98may @emph{not} be grouped: @option{-dr} is very different from @w{@samp{-d
99-r}}.
100
101@cindex order of options
102@cindex options, order
103You can mix options and other arguments. For the most part, the order
104you use doesn't matter. Order does matter when you use several options
105of the same kind; for example, if you specify @option{-L} more than once,
106the directories are searched in the order specified.
107
108Many options have long names starting with @samp{-f} or with
109@samp{-W}---for example,
110@option{-fmove-loop-invariants}, @option{-Wformat} and so on. Most of
111these have both positive and negative forms; the negative form of
112@option{-ffoo} would be @option{-fno-foo}. This manual documents
113only one of these two forms, whichever one is not the default.
114
115@c man end
116
117@xref{Option Index}, for an index to GCC's options.
118
119@menu
120* Option Summary:: Brief list of all options, without explanations.
121* Overall Options:: Controlling the kind of output:
122 an executable, object files, assembler files,
123 or preprocessed source.
124* Invoking G++:: Compiling C++ programs.
125* C Dialect Options:: Controlling the variant of C language compiled.
126* C++ Dialect Options:: Variations on C++.
127* Language Independent Options:: Controlling how diagnostics should be
128 formatted.
129* Warning Options:: How picky should the compiler be?
130* Debugging Options:: Symbol tables, measurements, and debugging dumps.
131* Optimize Options:: How much optimization?
132* Preprocessor Options:: Controlling header files and macro definitions.
133 Also, getting dependency information for Make.
134* Assembler Options:: Passing options to the assembler.
135* Link Options:: Specifying libraries and so on.
136* Directory Options:: Where to find header files and libraries.
137 Where to find the compiler executable files.
138* Spec Files:: How to pass switches to sub-processes.
139* Target Options:: Running a cross-compiler, or an old version of GCC.
140* Submodel Options:: Specifying minor hardware or convention variations,
141 such as 68010 vs 68020.
142* Code Gen Options:: Specifying conventions for function calls, data layout
143 and register usage.
144* Environment Variables:: Env vars that affect GCC.
145* Precompiled Headers:: Compiling a header once, and using it many times.
146* Running Protoize:: Automatically adding or removing function prototypes.
147@end menu
148
149@c man begin OPTIONS
150
151@node Option Summary
152@section Option Summary
153
154Here is a summary of all the options, grouped by type. Explanations are
155in the following sections.
156
157@table @emph
158@item Overall Options
159@xref{Overall Options,,Options Controlling the Kind of Output}.
160@gccoptlist{-c -S -E -o @var{file} -combine -pipe -pass-exit-codes @gol
161-x @var{language} -v -### --help --target-help --version @@@var{file}}
162
163@item C Language Options
164@xref{C Dialect Options,,Options Controlling C Dialect}.
165@gccoptlist{-ansi -std=@var{standard} -fgnu89-inline @gol
166-aux-info @var{filename} @gol
167-fno-asm -fno-builtin -fno-builtin-@var{function} @gol
168-fhosted -ffreestanding -fopenmp -fms-extensions @gol
169-trigraphs -no-integrated-cpp -traditional -traditional-cpp @gol
170-fallow-single-precision -fcond-mismatch @gol
171-fsigned-bitfields -fsigned-char @gol
172@c APPLE LOCAL -Wnewline-eof 2001-08-23 --sts **
173-Wnewline-eof (Apple compatible) @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 Language Independent Options
199@xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}.
200@gccoptlist{-fmessage-length=@var{n} @gol
201-fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]} @gol
202-fdiagnostics-show-option}
203
204@item Warning Options
205@xref{Warning Options,,Options to Request or Suppress Warnings}.
206@gccoptlist{-fsyntax-only -pedantic -pedantic-errors @gol
207-w -Wextra -Wall -Waddress -Waggregate-return -Wno-attributes @gol
208-Wc++-compat -Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment @gol
209-Wconversion -Wno-deprecated-declarations @gol
210-Wdisabled-optimization -Wno-div-by-zero -Wno-endif-labels @gol
211-Werror -Werror=* -Werror-implicit-function-declaration @gol
212-Wfatal-errors -Wfloat-equal -Wformat -Wformat=2 @gol
213-Wno-format-extra-args -Wformat-nonliteral @gol
214-Wformat-security -Wformat-y2k @gol
215-Wimplicit -Wimplicit-function-declaration -Wimplicit-int @gol
216-Wimport -Wno-import -Winit-self -Winline @gol
217-Wno-int-to-pointer-cast @gol
218-Wno-invalid-offsetof -Winvalid-pch @gol
219-Wlarger-than-@var{len} -Wframe-larger-than-@var{len} @gol
220-Wunsafe-loop-optimizations -Wlong-long @gol
221-Wmain -Wmissing-braces -Wmissing-field-initializers @gol
222-Wmissing-format-attribute -Wmissing-include-dirs @gol
223-Wmissing-noreturn @gol
224-Wno-multichar -Wnonnull -Wno-overflow @gol
225-Woverlength-strings -Wpacked -Wpadded @gol
226-Wparentheses -Wpointer-arith -Wno-pointer-to-int-cast @gol
227-Wredundant-decls @gol
228-Wreturn-type -Wsequence-point -Wshadow @gol
229-Wsign-compare -Wstack-protector @gol
230-Wstrict-aliasing -Wstrict-aliasing=2 @gol
231-Wstrict-overflow -Wstrict-overflow=@var{n} @gol
232-Wswitch -Wswitch-default -Wswitch-enum @gol
233-Wsystem-headers -Wtrigraphs -Wundef -Wuninitialized @gol
234-Wunknown-pragmas -Wno-pragmas -Wunreachable-code @gol
235-Wunused -Wunused-function -Wunused-label -Wunused-parameter @gol
236-Wunused-value -Wunused-variable @gol
237-Wvariadic-macros -Wvla @gol
238-Wvolatile-register-var -Wwrite-strings}
239
240@item C-only Warning Options
241@gccoptlist{-Wbad-function-cast -Wmissing-declarations @gol
242-Wmissing-prototypes -Wnested-externs -Wold-style-definition @gol
243-Wstrict-prototypes -Wtraditional @gol
244-Wdeclaration-after-statement -Wpointer-sign}
245
246@item Debugging Options
247@xref{Debugging Options,,Options for Debugging Your Program or GCC}.
248@gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
249-fdump-noaddr -fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} @gol
250-fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
251-fdump-ipa-all -fdump-ipa-cgraph @gol
252-fdump-tree-all @gol
253-fdump-tree-original@r{[}-@var{n}@r{]} @gol
254-fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
255-fdump-tree-inlined@r{[}-@var{n}@r{]} @gol
256-fdump-tree-cfg -fdump-tree-vcg -fdump-tree-alias @gol
257-fdump-tree-ch @gol
258-fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol
259-fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol
260-fdump-tree-gimple@r{[}-raw@r{]} -fdump-tree-mudflap@r{[}-@var{n}@r{]} @gol
261-fdump-tree-dom@r{[}-@var{n}@r{]} @gol
262-fdump-tree-dse@r{[}-@var{n}@r{]} @gol
263-fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol
264-fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
265-fdump-tree-copyrename@r{[}-@var{n}@r{]} @gol
266-fdump-tree-nrv -fdump-tree-vect @gol
267-fdump-tree-sink @gol
268-fdump-tree-sra@r{[}-@var{n}@r{]} @gol
269-fdump-tree-salias @gol
270-fdump-tree-fre@r{[}-@var{n}@r{]} @gol
271-fdump-tree-vrp@r{[}-@var{n}@r{]} @gol
272-ftree-vectorizer-verbose=@var{n} @gol
273-fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol
274-feliminate-dwarf2-dups -feliminate-unused-debug-types @gol
275-feliminate-unused-debug-symbols -femit-class-debug-always @gol
276-fmem-report -fprofile-arcs @gol
277-frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
278-ftest-coverage -ftime-report -fvar-tracking @gol
279-g -g@var{level} -gcoff -gdwarf-2 @gol
280-ggdb -gstabs -gstabs+ -gvms -gxcoff -gxcoff+ @gol
281-femit-struct-debug-baseonly -femit-struct-debug-reduced @gol
282-femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} @gol
283-p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol
284-print-multi-directory -print-multi-lib @gol
285-print-prog-name=@var{program} -print-search-dirs -Q @gol
286-save-temps -time}
287
288@item Optimization Options
289@xref{Optimize Options,,Options that Control Optimization}.
290@gccoptlist{-falign-functions=@var{n} -falign-jumps=@var{n} @gol
291-falign-labels=@var{n} -falign-loops=@var{n} @gol
292-fbounds-check -fmudflap -fmudflapth -fmudflapir @gol
293-fbranch-probabilities -fprofile-values -fvpt -fbranch-target-load-optimize @gol
294-fbranch-target-load-optimize2 -fbtr-bb-exclusive @gol
295-fcaller-saves -fcprop-registers -fcse-follow-jumps @gol
296-fcse-skip-blocks -fcx-limited-range -fdata-sections @gol
297-fdelayed-branch -fdelete-null-pointer-checks -fearly-inlining @gol
298-fexpensive-optimizations -ffast-math -ffloat-store @gol
299-fforce-addr -ffunction-sections @gol
300-fgcse -fgcse-lm -fgcse-sm -fgcse-las -fgcse-after-reload @gol
301-fcrossjumping -fif-conversion -fif-conversion2 @gol
302-finline-functions -finline-functions-called-once @gol
303-finline-limit=@var{n} -fkeep-inline-functions @gol
304-fkeep-static-consts -fmerge-constants -fmerge-all-constants @gol
305-fmodulo-sched -fno-branch-count-reg @gol
306-fno-default-inline -fno-defer-pop -fmove-loop-invariants @gol
307-fno-function-cse -fno-guess-branch-probability @gol
308-fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol
309-funsafe-math-optimizations -funsafe-loop-optimizations -ffinite-math-only @gol
310-fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol
311-fomit-frame-pointer -foptimize-register-move @gol
312-foptimize-sibling-calls -fprefetch-loop-arrays @gol
313-fprofile-generate -fprofile-use @gol
314-fregmove -frename-registers @gol
315-freorder-blocks -freorder-blocks-and-partition -freorder-functions @gol
316-frerun-cse-after-loop @gol
317-frounding-math -frtl-abstract-sequences @gol
318-fschedule-insns -fschedule-insns2 @gol
319-fno-sched-interblock -fno-sched-spec -fsched-spec-load @gol
320-fsched-spec-load-dangerous @gol
321-fsched-stalled-insns=@var{n} -fsched-stalled-insns-dep=@var{n} @gol
322-fsched2-use-superblocks @gol
323-fsched2-use-traces -fsee -freschedule-modulo-scheduled-loops @gol
324-fsection-anchors -fsignaling-nans -fsingle-precision-constant @gol
325-fstack-protector -fstack-protector-all @gol
326-fstrict-aliasing -fstrict-overflow -ftracer -fthread-jumps @gol
327-funroll-all-loops -funroll-loops -fpeel-loops @gol
328-fsplit-ivs-in-unroller -funswitch-loops @gol
329-fvariable-expansion-in-unroller @gol
330-ftree-pre -ftree-ccp -ftree-dce -ftree-loop-optimize @gol
331-ftree-loop-linear -ftree-loop-im -ftree-loop-ivcanon -fivopts @gol
332-ftree-dominator-opts -ftree-dse -ftree-copyrename -ftree-sink @gol
333-ftree-ch -ftree-sra -ftree-ter -ftree-lrs -ftree-fre -ftree-vectorize @gol
334-ftree-vect-loop-version -ftree-salias -fipa-pta -fweb @gol
335-ftree-copy-prop -ftree-store-ccp -ftree-store-copy-prop -fwhole-program @gol
336--param @var{name}=@var{value}
337-O -O0 -O1 -O2 -O3 -Os}
338
339@item Preprocessor Options
340@xref{Preprocessor Options,,Options Controlling the Preprocessor}.
341@gccoptlist{-A@var{question}=@var{answer} @gol
342-A-@var{question}@r{[}=@var{answer}@r{]} @gol
343-C -dD -dI -dM -dN @gol
344-D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol
345-idirafter @var{dir} @gol
346-include @var{file} -imacros @var{file} @gol
347-iprefix @var{file} -iwithprefix @var{dir} @gol
348-iwithprefixbefore @var{dir} -isystem @var{dir} @gol
349-imultilib @var{dir} -isysroot @var{dir} @gol
350-M -MM -MF -MG -MP -MQ -MT -nostdinc @gol
351-P -fworking-directory -remap @gol
352-trigraphs -undef -U@var{macro} -Wp,@var{option} @gol
353-Xpreprocessor @var{option}}
354
355@item Assembler Option
356@xref{Assembler Options,,Passing Options to the Assembler}.
357@gccoptlist{-Wa,@var{option} -Xassembler @var{option}}
358
359@item Linker Options
360@xref{Link Options,,Options for Linking}.
361@gccoptlist{@var{object-file-name} -l@var{library} @gol
362-nostartfiles -nodefaultlibs -nostdlib -pie -rdynamic @gol
363-s -static -static-libgcc -shared -shared-libgcc -symbolic @gol
364-Wl,@var{option} -Xlinker @var{option} @gol
365-u @var{symbol}}
366
367@item Directory Options
368@xref{Directory Options,,Options for Directory Search}.
369@gccoptlist{-B@var{prefix} -I@var{dir} -iquote@var{dir} -L@var{dir}
370-specs=@var{file} -I- --sysroot=@var{dir}}
371
372@item Target Options
373@c I wrote this xref this way to avoid overfull hbox. -- rms
374@xref{Target Options}.
375@gccoptlist{-V @var{version} -b @var{machine}}
376
377@item Machine Dependent Options
378@xref{Submodel Options,,Hardware Models and Configurations}.
379@c This list is ordered alphanumerically by subsection name.
380@c Try and put the significant identifier (CPU or system) first,
381@c so users have a clue at guessing where the ones they want will be.
382
383@emph{ARC Options}
384@gccoptlist{-EB -EL @gol
385-mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text-section} @gol
386-mdata=@var{data-section} -mrodata=@var{readonly-data-section}}
387
388@emph{ARM Options}
389@gccoptlist{-mapcs-frame -mno-apcs-frame @gol
390-mabi=@var{name} @gol
391-mapcs-stack-check -mno-apcs-stack-check @gol
392-mapcs-float -mno-apcs-float @gol
393-mapcs-reentrant -mno-apcs-reentrant @gol
394-msched-prolog -mno-sched-prolog @gol
395-mlittle-endian -mbig-endian -mwords-little-endian @gol
396-mfloat-abi=@var{name} -msoft-float -mhard-float -mfpe @gol
397-mthumb-interwork -mno-thumb-interwork @gol
398-mcpu=@var{name} -march=@var{name} -mfpu=@var{name} @gol
399-mstructure-size-boundary=@var{n} @gol
400-mabort-on-noreturn @gol
401-mlong-calls -mno-long-calls @gol
402-msingle-pic-base -mno-single-pic-base @gol
403-mpic-register=@var{reg} @gol
404-mnop-fun-dllimport @gol
405-mcirrus-fix-invalid-insns -mno-cirrus-fix-invalid-insns @gol
406-mpoke-function-name @gol
407-mthumb -marm @gol
408-mtpcs-frame -mtpcs-leaf-frame @gol
409-mcaller-super-interworking -mcallee-super-interworking @gol
410-mtp=@var{name}}
411
412@emph{AVR Options}
413@gccoptlist{-mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts @gol
414-mcall-prologues -mno-tablejump -mtiny-stack -mint8}
415
416@emph{Blackfin Options}
417@gccoptlist{-momit-leaf-frame-pointer -mno-omit-leaf-frame-pointer @gol
418-mspecld-anomaly -mno-specld-anomaly -mcsync-anomaly -mno-csync-anomaly @gol
419-mlow-64k -mno-low64k -mid-shared-library @gol
420-mno-id-shared-library -mshared-library-id=@var{n} @gol
421-mlong-calls -mno-long-calls}
422
423@emph{CRIS Options}
424@gccoptlist{-mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol
425-mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol
426-metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol
427-mstack-align -mdata-align -mconst-align @gol
428-m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol
429-melf -maout -melinux -mlinux -sim -sim2 @gol
430-mmul-bug-workaround -mno-mul-bug-workaround}
431
432@emph{CRX Options}
433@gccoptlist{-mmac -mpush-args}
434
435@emph{Darwin Options}
436@gccoptlist{-all_load -allowable_client -arch -arch_errors_fatal @gol
437-arch_only -bind_at_load -bundle -bundle_loader @gol
438-client_name -compatibility_version -current_version @gol
439-dead_strip @gol
440-dependency-file -dylib_file -dylinker_install_name @gol
441-dynamic -dynamiclib -exported_symbols_list @gol
442-filelist -flat_namespace -force_cpusubtype_ALL @gol
443-force_flat_namespace -headerpad_max_install_names @gol
444-image_base -init -install_name -keep_private_externs @gol
445-multi_module -multiply_defined -multiply_defined_unused @gol
446-noall_load -no_dead_strip_inits_and_terms @gol
447-nofixprebinding -nomultidefs -noprebind -noseglinkedit @gol
448-pagezero_size -prebind -prebind_all_twolevel_modules @gol
449-private_bundle -read_only_relocs -sectalign @gol
450-sectobjectsymbols -whyload -seg1addr @gol
451-sectcreate -sectobjectsymbols -sectorder @gol
452-segaddr -segs_read_only_addr -segs_read_write_addr @gol
453-seg_addr_table -seg_addr_table_filename -seglinkedit @gol
454-segprot -segs_read_only_addr -segs_read_write_addr @gol
455-single_module -static -sub_library -sub_umbrella @gol
456-twolevel_namespace -umbrella -undefined @gol
457-unexported_symbols_list -weak_reference_mismatches @gol
458-whatsloaded -F -gused -gfull -mmacosx-version-min=@var{version} @gol
459-mkernel -mone-byte-bool}
460
461@emph{DEC Alpha Options}
462@gccoptlist{-mno-fp-regs -msoft-float -malpha-as -mgas @gol
463-mieee -mieee-with-inexact -mieee-conformant @gol
464-mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} @gol
465-mtrap-precision=@var{mode} -mbuild-constants @gol
466-mcpu=@var{cpu-type} -mtune=@var{cpu-type} @gol
467-mbwx -mmax -mfix -mcix @gol
468-mfloat-vax -mfloat-ieee @gol
469-mexplicit-relocs -msmall-data -mlarge-data @gol
470-msmall-text -mlarge-text @gol
471-mmemory-latency=@var{time}}
472
473@emph{DEC Alpha/VMS Options}
474@gccoptlist{-mvms-return-codes}
475
476@emph{FRV Options}
477@gccoptlist{-mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 @gol
478-mhard-float -msoft-float @gol
479-malloc-cc -mfixed-cc -mdword -mno-dword @gol
480-mdouble -mno-double @gol
481-mmedia -mno-media -mmuladd -mno-muladd @gol
482-mfdpic -minline-plt -mgprel-ro -multilib-library-pic @gol
483-mlinked-fp -mlong-calls -malign-labels @gol
484-mlibrary-pic -macc-4 -macc-8 @gol
485-mpack -mno-pack -mno-eflags -mcond-move -mno-cond-move @gol
486-moptimize-membar -mno-optimize-membar @gol
487-mscc -mno-scc -mcond-exec -mno-cond-exec @gol
488-mvliw-branch -mno-vliw-branch @gol
489-mmulti-cond-exec -mno-multi-cond-exec -mnested-cond-exec @gol
490-mno-nested-cond-exec -mtomcat-stats @gol
491-mTLS -mtls @gol
492-mcpu=@var{cpu}}
493
494@emph{GNU/Linux Options}
495@gccoptlist{-muclibc}
496
497@emph{H8/300 Options}
498@gccoptlist{-mrelax -mh -ms -mn -mint32 -malign-300}
499
500@emph{HPPA Options}
501@gccoptlist{-march=@var{architecture-type} @gol
502-mbig-switch -mdisable-fpregs -mdisable-indexing @gol
503-mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol
504-mfixed-range=@var{register-range} @gol
505-mjump-in-delay -mlinker-opt -mlong-calls @gol
506-mlong-load-store -mno-big-switch -mno-disable-fpregs @gol
507-mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol
508-mno-jump-in-delay -mno-long-load-store @gol
509-mno-portable-runtime -mno-soft-float @gol
510-mno-space-regs -msoft-float -mpa-risc-1-0 @gol
511-mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime @gol
512-mschedule=@var{cpu-type} -mspace-regs -msio -mwsio @gol
513-munix=@var{unix-std} -nolibdld -static -threads}
514
515@emph{i386 and x86-64 Options}
516@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
517-mfpmath=@var{unit} @gol
518-masm=@var{dialect} -mno-fancy-math-387 @gol
519-mno-fp-ret-in-387 -msoft-float -msvr3-shlib @gol
520-mno-wide-multiply -mrtd -malign-double @gol
521-mpreferred-stack-boundary=@var{num} @gol
522-mmmx -msse -msse2 -msse3 -mssse3 -msse4a -m3dnow -mpopcnt -mabm -maes @gol
523-mthreads -mno-align-stringops -minline-all-stringops @gol
524-mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol
525-m96bit-long-double -mregparm=@var{num} -msseregparm @gol
526-mstackrealign @gol
527-momit-leaf-frame-pointer -mno-red-zone -mno-tls-direct-seg-refs @gol
528-mcmodel=@var{code-model} @gol
529-m32 -m64 -mlarge-data-threshold=@var{num}}
530
531@emph{IA-64 Options}
532@gccoptlist{-mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol
533-mvolatile-asm-stop -mregister-names -mno-sdata @gol
534-mconstant-gp -mauto-pic -minline-float-divide-min-latency @gol
535-minline-float-divide-max-throughput @gol
536-minline-int-divide-min-latency @gol
537-minline-int-divide-max-throughput @gol
538-minline-sqrt-min-latency -minline-sqrt-max-throughput @gol
539-mno-dwarf2-asm -mearly-stop-bits @gol
540-mfixed-range=@var{register-range} -mtls-size=@var{tls-size} @gol
541-mtune=@var{cpu-type} -mt -pthread -milp32 -mlp64 @gol
542-mno-sched-br-data-spec -msched-ar-data-spec -mno-sched-control-spec @gol
543-msched-br-in-data-spec -msched-ar-in-data-spec -msched-in-control-spec @gol
544-msched-ldc -mno-sched-control-ldc -mno-sched-spec-verbose @gol
545-mno-sched-prefer-non-data-spec-insns @gol
546-mno-sched-prefer-non-control-spec-insns @gol
547-mno-sched-count-spec-in-critical-path}
548
549@emph{M32R/D Options}
550@gccoptlist{-m32r2 -m32rx -m32r @gol
551-mdebug @gol
552-malign-loops -mno-align-loops @gol
553-missue-rate=@var{number} @gol
554-mbranch-cost=@var{number} @gol
555-mmodel=@var{code-size-model-type} @gol
556-msdata=@var{sdata-type} @gol
557-mno-flush-func -mflush-func=@var{name} @gol
558-mno-flush-trap -mflush-trap=@var{number} @gol
559-G @var{num}}
560
561@emph{M32C Options}
562@gccoptlist{-mcpu=@var{cpu} -msim -memregs=@var{number}}
563
564@emph{M680x0 Options}
565@gccoptlist{-m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol
566-m68060 -mcpu32 -m5200 -mcfv4e -m68881 -mbitfield @gol
567-mc68000 -mc68020 @gol
568-mnobitfield -mrtd -mshort -msoft-float -mpcrel @gol
569-malign-int -mstrict-align -msep-data -mno-sep-data @gol
570-mshared-library-id=n -mid-shared-library -mno-id-shared-library}
571
572@emph{M68hc1x Options}
573@gccoptlist{-m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 @gol
574-mauto-incdec -minmax -mlong-calls -mshort @gol
575-msoft-reg-count=@var{count}}
576
577@emph{MCore Options}
578@gccoptlist{-mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol
579-mno-relax-immediates -mwide-bitfields -mno-wide-bitfields @gol
580-m4byte-functions -mno-4byte-functions -mcallgraph-data @gol
581-mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim @gol
582-mlittle-endian -mbig-endian -m210 -m340 -mstack-increment}
583
584@emph{MIPS Options}
585@gccoptlist{-EL -EB -march=@var{arch} -mtune=@var{arch} @gol
586-mips1 -mips2 -mips3 -mips4 -mips32 -mips32r2 -mips64 @gol
587-mips16 -mno-mips16 -mabi=@var{abi} -mabicalls -mno-abicalls @gol
588-mshared -mno-shared -mxgot -mno-xgot -mgp32 -mgp64 @gol
589-mfp32 -mfp64 -mhard-float -msoft-float @gol
590-msingle-float -mdouble-float -mdsp -mpaired-single -mips3d @gol
591-mlong64 -mlong32 -msym32 -mno-sym32 @gol
592-G@var{num} -membedded-data -mno-embedded-data @gol
593-muninit-const-in-rodata -mno-uninit-const-in-rodata @gol
594-msplit-addresses -mno-split-addresses @gol
595-mexplicit-relocs -mno-explicit-relocs @gol
596-mcheck-zero-division -mno-check-zero-division @gol
597-mdivide-traps -mdivide-breaks @gol
598-mmemcpy -mno-memcpy -mlong-calls -mno-long-calls @gol
599-mmad -mno-mad -mfused-madd -mno-fused-madd -nocpp @gol
600-mfix-r4000 -mno-fix-r4000 -mfix-r4400 -mno-fix-r4400 @gol
601-mfix-vr4120 -mno-fix-vr4120 -mfix-vr4130 @gol
602-mfix-sb1 -mno-fix-sb1 @gol
603-mflush-func=@var{func} -mno-flush-func @gol
604-mbranch-likely -mno-branch-likely @gol
605-mfp-exceptions -mno-fp-exceptions @gol
606-mvr4130-align -mno-vr4130-align}
607
608@emph{MMIX Options}
609@gccoptlist{-mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol
610-mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol
611-melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol
612-mno-base-addresses -msingle-exit -mno-single-exit}
613
614@emph{MN10300 Options}
615@gccoptlist{-mmult-bug -mno-mult-bug @gol
616-mam33 -mno-am33 @gol
617-mam33-2 -mno-am33-2 @gol
618-mreturn-pointer-on-d0 @gol
619-mno-crt0 -mrelax}
620
621@emph{MT Options}
622@gccoptlist{-mno-crt0 -mbacc -msim @gol
623-march=@var{cpu-type} }
624
625@emph{PDP-11 Options}
626@gccoptlist{-mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol
627-mbcopy -mbcopy-builtin -mint32 -mno-int16 @gol
628-mint16 -mno-int32 -mfloat32 -mno-float64 @gol
629-mfloat64 -mno-float32 -mabshi -mno-abshi @gol
630-mbranch-expensive -mbranch-cheap @gol
631-msplit -mno-split -munix-asm -mdec-asm}
632
633@emph{PowerPC Options}
634See RS/6000 and PowerPC Options.
635
636@emph{RS/6000 and PowerPC Options}
637@gccoptlist{-mcpu=@var{cpu-type} @gol
638-mtune=@var{cpu-type} @gol
639-mpower -mno-power -mpower2 -mno-power2 @gol
640-mpowerpc -mpowerpc64 -mno-powerpc @gol
641-maltivec -mno-altivec @gol
642-mpowerpc-gpopt -mno-powerpc-gpopt @gol
643-mpowerpc-gfxopt -mno-powerpc-gfxopt @gol
644-mmfcrf -mno-mfcrf -mpopcntb -mno-popcntb -mfprnd -mno-fprnd @gol
645-mnew-mnemonics -mold-mnemonics @gol
646-mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc @gol
647-m64 -m32 -mxl-compat -mno-xl-compat -mpe @gol
648-malign-power -malign-natural @gol
649-msoft-float -mhard-float -mmultiple -mno-multiple @gol
650-mstring -mno-string -mupdate -mno-update @gol
651-mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol
652-mstrict-align -mno-strict-align -mrelocatable @gol
653-mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol
654-mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol
655-mdynamic-no-pic -maltivec -mswdiv @gol
656-mprioritize-restricted-insns=@var{priority} @gol
657-msched-costly-dep=@var{dependence_type} @gol
658-minsert-sched-nops=@var{scheme} @gol
659-mcall-sysv -mcall-netbsd @gol
660-maix-struct-return -msvr4-struct-return @gol
661-mabi=@var{abi-type} -msecure-plt -mbss-plt @gol
662-misel -mno-isel @gol
663-misel=yes -misel=no @gol
664-mspe -mno-spe @gol
665-mspe=yes -mspe=no @gol
666-mvrsave -mno-vrsave @gol
667-mmulhw -mno-mulhw @gol
668-mdlmzb -mno-dlmzb @gol
669-mfloat-gprs=yes -mfloat-gprs=no -mfloat-gprs=single -mfloat-gprs=double @gol
670-mprototype -mno-prototype @gol
671-msim -mmvme -mads -myellowknife -memb -msdata @gol
672-msdata=@var{opt} -mvxworks -mwindiss -G @var{num} -pthread}
673
674@emph{S/390 and zSeries Options}
675@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
676-mhard-float -msoft-float -mlong-double-64 -mlong-double-128 @gol
677-mbackchain -mno-backchain -mpacked-stack -mno-packed-stack @gol
678-msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol
679-m64 -m31 -mdebug -mno-debug -mesa -mzarch @gol
680-mtpf-trace -mno-tpf-trace -mfused-madd -mno-fused-madd @gol
681-mwarn-framesize -mwarn-dynamicstack -mstack-size -mstack-guard}
682
683@emph{Score Options}
684@gccoptlist{-meb -mel @gol
685-mnhwloop @gol
686-muls @gol
687-mmac @gol
688-mscore5 -mscore5u -mscore7 -mscore7d}
689
690@emph{SH Options}
691@gccoptlist{-m1 -m2 -m2e -m3 -m3e @gol
692-m4-nofpu -m4-single-only -m4-single -m4 @gol
693-m4a-nofpu -m4a-single-only -m4a-single -m4a -m4al @gol
694-m5-64media -m5-64media-nofpu @gol
695-m5-32media -m5-32media-nofpu @gol
696-m5-compact -m5-compact-nofpu @gol
697-mb -ml -mdalign -mrelax @gol
698-mbigtable -mfmovd -mhitachi -mrenesas -mno-renesas -mnomacsave @gol
699-mieee -misize -mpadstruct -mspace @gol
700-mprefergot -musermode -multcost=@var{number} -mdiv=@var{strategy} @gol
701-mdivsi3_libfunc=@var{name} @gol
702-madjust-unroll -mindexed-addressing -mgettrcost=@var{number} -mpt-fixed @gol
703 -minvalid-symbols}
704
705@emph{SPARC Options}
706@gccoptlist{-mcpu=@var{cpu-type} @gol
707-mtune=@var{cpu-type} @gol
708-mcmodel=@var{code-model} @gol
709-m32 -m64 -mapp-regs -mno-app-regs @gol
710-mfaster-structs -mno-faster-structs @gol
711-mfpu -mno-fpu -mhard-float -msoft-float @gol
712-mhard-quad-float -msoft-quad-float @gol
713-mimpure-text -mno-impure-text -mlittle-endian @gol
714-mstack-bias -mno-stack-bias @gol
715-munaligned-doubles -mno-unaligned-doubles @gol
716-mv8plus -mno-v8plus -mvis -mno-vis
717-threads -pthreads -pthread}
718
719@emph{System V Options}
720@gccoptlist{-Qy -Qn -YP,@var{paths} -Ym,@var{dir}}
721
722@emph{TMS320C3x/C4x Options}
723@gccoptlist{-mcpu=@var{cpu} -mbig -msmall -mregparm -mmemparm @gol
724-mfast-fix -mmpyi -mbk -mti -mdp-isr-reload @gol
725-mrpts=@var{count} -mrptb -mdb -mloop-unsigned @gol
726-mparallel-insns -mparallel-mpy -mpreserve-float}
727
728@emph{V850 Options}
729@gccoptlist{-mlong-calls -mno-long-calls -mep -mno-ep @gol
730-mprolog-function -mno-prolog-function -mspace @gol
731-mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol
732-mapp-regs -mno-app-regs @gol
733-mdisable-callt -mno-disable-callt @gol
734-mv850e1 @gol
735-mv850e @gol
736-mv850 -mbig-switch}
737
738@emph{VAX Options}
739@gccoptlist{-mg -mgnu -munix}
740
741@emph{x86-64 Options}
742See i386 and x86-64 Options.
743
744@emph{Xstormy16 Options}
745@gccoptlist{-msim}
746
747@emph{Xtensa Options}
748@gccoptlist{-mconst16 -mno-const16 @gol
749-mfused-madd -mno-fused-madd @gol
750-mtext-section-literals -mno-text-section-literals @gol
751-mtarget-align -mno-target-align @gol
752-mlongcalls -mno-longcalls}
753
754@emph{zSeries Options}
755See S/390 and zSeries Options.
756
757@item Code Generation Options
758@xref{Code Gen Options,,Options for Code Generation Conventions}.
759@gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol
760-ffixed-@var{reg} -fexceptions @gol
761-fnon-call-exceptions -funwind-tables @gol
762-fasynchronous-unwind-tables @gol
763-finhibit-size-directive -finstrument-functions @gol
764-finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} @gol
765-finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{} @gol
766-fno-common -fno-ident @gol
767-fpcc-struct-return -fpic -fPIC -fpie -fPIE @gol
768-fno-jump-tables @gol
769-freg-struct-return -fshort-enums @gol
770-fshort-double -fshort-wchar @gol
771-fverbose-asm -fpack-struct[=@var{n}] -fstack-check @gol
772-fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
773-fargument-alias -fargument-noalias @gol
774-fargument-noalias-global -fargument-noalias-anything
775-fleading-underscore -ftls-model=@var{model} @gol
776-ftrapv -fwrapv -fbounds-check @gol
777-fvisibility}
778@end table
779
780@menu
781* Overall Options:: Controlling the kind of output:
782 an executable, object files, assembler files,
783 or preprocessed source.
784* C Dialect Options:: Controlling the variant of C language compiled.
785* C++ Dialect Options:: Variations on C++.
786* Language Independent Options:: Controlling how diagnostics should be
787 formatted.
788* Warning Options:: How picky should the compiler be?
789* Debugging Options:: Symbol tables, measurements, and debugging dumps.
790* Optimize Options:: How much optimization?
791* Preprocessor Options:: Controlling header files and macro definitions.
792 Also, getting dependency information for Make.
793* Assembler Options:: Passing options to the assembler.
794* Link Options:: Specifying libraries and so on.
795* Directory Options:: Where to find header files and libraries.
796 Where to find the compiler executable files.
797* Spec Files:: How to pass switches to sub-processes.
798* Target Options:: Running a cross-compiler, or an old version of GCC.
799@end menu
800
801@node Overall Options
802@section Options Controlling the Kind of Output
803
804Compilation can involve up to four stages: preprocessing, compilation
805proper, assembly and linking, always in that order. GCC is capable of
806preprocessing and compiling several files either into several
807assembler input files, or into one assembler input file; then each
808assembler input file produces an object file, and linking combines all
809the object files (those newly compiled, and those specified as input)
810into an executable file.
811
812@cindex file name suffix
813For any given input file, the file name suffix determines what kind of
814compilation is done:
815
816@table @gcctabopt
817@item @var{file}.c
818C source code which must be preprocessed.
819
820@item @var{file}.i
821C source code which should not be preprocessed.
822
823@item @var{file}.ii
824C++ source code which should not be preprocessed.
825
826@item @var{file}.h
827C, or C++ header file to be turned into a precompiled header.
828
829@item @var{file}.cc
830@itemx @var{file}.cp
831@itemx @var{file}.cxx
832@itemx @var{file}.cpp
833@itemx @var{file}.CPP
834@itemx @var{file}.c++
835@itemx @var{file}.C
836C++ source code which must be preprocessed. Note that in @samp{.cxx},
837the last two letters must both be literally @samp{x}. Likewise,
838@samp{.C} refers to a literal capital C@.
839
840@item @var{file}.hh
841@itemx @var{file}.H
842C++ header file to be turned into a precompiled header.
843
844@item @var{file}.f
845@itemx @var{file}.for
846@itemx @var{file}.FOR
847Fixed form Fortran source code which should not be preprocessed.
848
849@item @var{file}.F
850@itemx @var{file}.fpp
851@itemx @var{file}.FPP
852Fixed form Fortran source code which must be preprocessed (with the traditional
853preprocessor).
854
855@item @var{file}.f90
856@itemx @var{file}.f95
857Free form Fortran source code which should not be preprocessed.
858
859@item @var{file}.F90
860@itemx @var{file}.F95
861Free form Fortran source code which must be preprocessed (with the
862traditional preprocessor).
863
864@c FIXME: Descriptions of Java file types.
865@c @var{file}.java
866@c @var{file}.class
867@c @var{file}.zip
868@c @var{file}.jar
869
870@item @var{file}.ads
871Ada source code file which contains a library unit declaration (a
872declaration of a package, subprogram, or generic, or a generic
873instantiation), or a library unit renaming declaration (a package,
874generic, or subprogram renaming declaration). Such files are also
875called @dfn{specs}.
876
877@itemx @var{file}.adb
878Ada source code file containing a library unit body (a subprogram or
879package body). Such files are also called @dfn{bodies}.
880
881@c GCC also knows about some suffixes for languages not yet included:
882@c Pascal:
883@c @var{file}.p
884@c @var{file}.pas
885@c Ratfor:
886@c @var{file}.r
887
888@item @var{file}.s
889Assembler code.
890
891@item @var{file}.S
892Assembler code which must be preprocessed.
893
894@item @var{other}
895An object file to be fed straight into linking.
896Any file name with no recognized suffix is treated this way.
897@end table
898
899@opindex x
900You can specify the input language explicitly with the @option{-x} option:
901
902@table @gcctabopt
903@item -x @var{language}
904Specify explicitly the @var{language} for the following input files
905(rather than letting the compiler choose a default based on the file
906name suffix). This option applies to all following input files until
907the next @option{-x} option. Possible values for @var{language} are:
908@smallexample
909c c-header c-cpp-output
910c++ c++-header c++-cpp-output
911assembler assembler-with-cpp
912ada
913f95 f95-cpp-input
914java
915treelang
916@end smallexample
917
918@item -x none
919Turn off any specification of a language, so that subsequent files are
920handled according to their file name suffixes (as they are if @option{-x}
921has not been used at all).
922
923@item -pass-exit-codes
924@opindex pass-exit-codes
925Normally the @command{gcc} program will exit with the code of 1 if any
926phase of the compiler returns a non-success return code. If you specify
927@option{-pass-exit-codes}, the @command{gcc} program will instead return with
928numerically highest error produced by any phase that returned an error
929indication. The C, C++, and Fortran frontends return 4, if an internal
930compiler error is encountered.
931@end table
932
933If you only want some of the stages of compilation, you can use
934@option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
935one of the options @option{-c}, @option{-S}, or @option{-E} to say where
936@command{gcc} is to stop. Note that some combinations (for example,
937@samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
938
939@table @gcctabopt
940@item -c
941@opindex c
942Compile or assemble the source files, but do not link. The linking
943stage simply is not done. The ultimate output is in the form of an
944object file for each source file.
945
946By default, the object file name for a source file is made by replacing
947the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
948
949Unrecognized input files, not requiring compilation or assembly, are
950ignored.
951
952@item -S
953@opindex S
954Stop after the stage of compilation proper; do not assemble. The output
955is in the form of an assembler code file for each non-assembler input
956file specified.
957
958By default, the assembler file name for a source file is made by
959replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
960
961Input files that don't require compilation are ignored.
962
963@item -E
964@opindex E
965Stop after the preprocessing stage; do not run the compiler proper. The
966output is in the form of preprocessed source code, which is sent to the
967standard output.
968
969Input files which don't require preprocessing are ignored.
970
971@cindex output file option
972@item -o @var{file}
973@opindex o
974Place output in file @var{file}. This applies regardless to whatever
975sort of output is being produced, whether it be an executable file,
976an object file, an assembler file or preprocessed C code.
977
978If @option{-o} is not specified, the default is to put an executable
979file in @file{a.out}, the object file for
980@file{@var{source}.@var{suffix}} in @file{@var{source}.o}, its
981assembler file in @file{@var{source}.s}, a precompiled header file in
982@file{@var{source}.@var{suffix}.gch}, and all preprocessed C source on
983standard output.
984
985@item -v
986@opindex v
987Print (on standard error output) the commands executed to run the stages
988of compilation. Also print the version number of the compiler driver
989program and of the preprocessor and the compiler proper.
990
991@item -###
992@opindex ###
993Like @option{-v} except the commands are not executed and all command
994arguments are quoted. This is useful for shell scripts to capture the
995driver-generated command lines.
996
997@item -pipe
998@opindex pipe
999Use pipes rather than temporary files for communication between the
1000various stages of compilation. This fails to work on some systems where
1001the assembler is unable to read from a pipe; but the GNU assembler has
1002no trouble.
1003
1004@item -combine
1005@opindex combine
1006If you are compiling multiple source files, this option tells the driver
1007to pass all the source files to the compiler at once (for those
1008languages for which the compiler can handle this). This will allow
1009intermodule analysis (IMA) to be performed by the compiler. Currently the only
1010language for which this is supported is C@. If you pass source files for
1011multiple languages to the driver, using this option, the driver will invoke
1012the compiler(s) that support IMA once each, passing each compiler all the
1013source files appropriate for it. For those languages that do not support
1014IMA this option will be ignored, and the compiler will be invoked once for
1015each source file in that language. If you use this option in conjunction
1016with @option{-save-temps}, the compiler will generate multiple
1017pre-processed files
1018(one for each source file), but only one (combined) @file{.o} or
1019@file{.s} file.
1020
1021@item --help
1022@opindex help
1023Print (on the standard output) a description of the command line options
1024understood by @command{gcc}. If the @option{-v} option is also specified
1025then @option{--help} will also be passed on to the various processes
1026invoked by @command{gcc}, so that they can display the command line options
1027they accept. If the @option{-Wextra} option is also specified then command
1028line options which have no documentation associated with them will also
1029be displayed.
1030
1031@item --target-help
1032@opindex target-help
1033Print (on the standard output) a description of target specific command
1034line options for each tool.
1035
1036@item --version
1037@opindex version
1038Display the version number and copyrights of the invoked GCC@.
1039
1040@include @value{srcdir}/../libiberty/at-file.texi
1041@end table
1042
1043@node Invoking G++
1044@section Compiling C++ Programs
1045
1046@cindex suffixes for C++ source
1047@cindex C++ source file suffixes
1048C++ source files conventionally use one of the suffixes @samp{.C},
1049@samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or
1050@samp{.cxx}; C++ header files often use @samp{.hh} or @samp{.H}; and
1051preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes
1052files with these names and compiles them as C++ programs even if you
1053call the compiler the same way as for compiling C programs (usually
1054with the name @command{gcc}).
1055
1056@findex g++
1057@findex c++
1058However, the use of @command{gcc} does not add the C++ library.
1059@command{g++} is a program that calls GCC and treats @samp{.c},
1060@samp{.h} and @samp{.i} files as C++ source files instead of C source
1061files unless @option{-x} is used, and automatically specifies linking
1062against the C++ library. This program is also useful when
1063precompiling a C header file with a @samp{.h} extension for use in C++
1064compilations. On many systems, @command{g++} is also installed with
1065the name @command{c++}.
1066
1067@cindex invoking @command{g++}
1068When you compile C++ programs, you may specify many of the same
1069command-line options that you use for compiling programs in any
1070language; or command-line options meaningful for C and related
1071languages; or options that are meaningful only for C++ programs.
1072@xref{C Dialect Options,,Options Controlling C Dialect}, for
1073explanations of options for languages related to C@.
1074@xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
1075explanations of options that are meaningful only for C++ programs.
1076
1077@node C Dialect Options
1078@section Options Controlling C Dialect
1079@cindex dialect options
1080@cindex language dialect options
1081@cindex options, dialect
1082
1083The following options control the dialect of C (or languages derived
1084from C, such as C++) that the compiler accepts:
1085
1086@table @gcctabopt
1087@cindex ANSI support
1088@cindex ISO support
1089@item -ansi
1090@opindex ansi
1091In C mode, support all ISO C90 programs. In C++ mode,
1092remove GNU extensions that conflict with ISO C++.
1093
1094This turns off certain features of GCC that are incompatible with ISO
1095C90 (when compiling C code), or of standard C++ (when compiling C++ code),
1096such as the @code{asm} and @code{typeof} keywords, and
1097predefined macros such as @code{unix} and @code{vax} that identify the
1098type of system you are using. It also enables the undesirable and
1099rarely used ISO trigraph feature. For the C compiler,
1100it disables recognition of C++ style @samp{//} comments as well as
1101the @code{inline} keyword.
1102
1103The alternate keywords @code{__asm__}, @code{__extension__},
1104@code{__inline__} and @code{__typeof__} continue to work despite
1105@option{-ansi}. You would not want to use them in an ISO C program, of
1106course, but it is useful to put them in header files that might be included
1107in compilations done with @option{-ansi}. Alternate predefined macros
1108such as @code{__unix__} and @code{__vax__} are also available, with or
1109without @option{-ansi}.
1110
1111The @option{-ansi} option does not cause non-ISO programs to be
1112rejected gratuitously. For that, @option{-pedantic} is required in
1113addition to @option{-ansi}. @xref{Warning Options}.
1114
1115The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
1116option is used. Some header files may notice this macro and refrain
1117from declaring certain functions or defining certain macros that the
1118ISO standard doesn't call for; this is to avoid interfering with any
1119programs that might use these names for other things.
1120
1121Functions which would normally be built in but do not have semantics
1122defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
1123functions with @option{-ansi} is used. @xref{Other Builtins,,Other
1124built-in functions provided by GCC}, for details of the functions
1125affected.
1126
1127@item -std=
1128@opindex std
1129Determine the language standard. This option is currently only
1130supported when compiling C or C++. A value for this option must be
1131provided; possible values are
1132
1133@table @samp
1134@item c89
1135@itemx iso9899:1990
1136ISO C90 (same as @option{-ansi}).
1137
1138@item iso9899:199409
1139ISO C90 as modified in amendment 1.
1140
1141@item c99
1142@itemx c9x
1143@itemx iso9899:1999
1144@itemx iso9899:199x
1145ISO C99. Note that this standard is not yet fully supported; see
1146@w{@uref{http://gcc.gnu.org/gcc-4.2/c99status.html}} for more information. The
1147names @samp{c9x} and @samp{iso9899:199x} are deprecated.
1148
1149@item gnu89
1150Default, ISO C90 plus GNU extensions (including some C99 features).
1151
1152@item gnu99
1153@itemx gnu9x
1154ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC,
1155this will become the default. The name @samp{gnu9x} is deprecated.
1156
1157@item c++98
1158The 1998 ISO C++ standard plus amendments.
1159
1160@item gnu++98
1161The same as @option{-std=c++98} plus GNU extensions. This is the
1162default for C++ code.
1163@end table
1164
1165Even when this option is not specified, you can still use some of the
1166features of newer standards in so far as they do not conflict with
1167previous C standards. For example, you may use @code{__restrict__} even
1168when @option{-std=c99} is not specified.
1169
1170The @option{-std} options specifying some version of ISO C have the same
1171effects as @option{-ansi}, except that features that were not in ISO C90
1172but are in the specified version (for example, @samp{//} comments and
1173the @code{inline} keyword in ISO C99) are not disabled.
1174
1175@xref{Standards,,Language Standards Supported by GCC}, for details of
1176these standard versions.
1177
1178@item -fgnu89-inline
1179@opindex fgnu89-inline
1180The option @option{-fgnu89-inline} tells GCC to use the traditional
1181GNU semantics for @code{inline} functions when in C99 mode.
1182@xref{Inline,,An Inline Function is As Fast As a Macro}. Using this
1183option is roughly equivalent to adding the @code{gnu_inline} function
1184attribute to all inline functions (@pxref{Function Attributes}).
1185
1186This option is accepted by GCC versions 4.1.3 and up. In GCC versions
1187prior to 4.3, C99 inline semantics are not supported, and thus this
1188option is effectively assumed to be present regardless of whether or not
1189it is specified; the only effect of specifying it explicitly is to
1190disable warnings about using inline functions in C99 mode. Likewise,
1191the option @option{-fno-gnu89-inline} is not supported in versions of
1192GCC before 4.3. It will be supported only in C99 or gnu99 mode, not in
1193C89 or gnu89 mode.
1194
1195The preprocesor macros @code{__GNUC_GNU_INLINE__} and
1196@code{__GNUC_STDC_INLINE__} may be used to check which semantics are
1197in effect for @code{inline} functions. @xref{Common Predefined
1198Macros,,,cpp,The C Preprocessor}.
1199
1200@item -aux-info @var{filename}
1201@opindex aux-info
1202Output to the given filename prototyped declarations for all functions
1203declared and/or defined in a translation unit, including those in header
1204files. This option is silently ignored in any language other than C@.
1205
1206Besides declarations, the file indicates, in comments, the origin of
1207each declaration (source file and line), whether the declaration was
1208implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
1209@samp{O} for old, respectively, in the first character after the line
1210number and the colon), and whether it came from a declaration or a
1211definition (@samp{C} or @samp{F}, respectively, in the following
1212character). In the case of function definitions, a K&R-style list of
1213arguments followed by their declarations is also provided, inside
1214comments, after the declaration.
1215
1216@item -fno-asm
1217@opindex fno-asm
1218Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1219keyword, so that code can use these words as identifiers. You can use
1220the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
1221instead. @option{-ansi} implies @option{-fno-asm}.
1222
1223In C++, this switch only affects the @code{typeof} keyword, since
1224@code{asm} and @code{inline} are standard keywords. You may want to
1225use the @option{-fno-gnu-keywords} flag instead, which has the same
1226effect. In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
1227switch only affects the @code{asm} and @code{typeof} keywords, since
1228@code{inline} is a standard keyword in ISO C99.
1229
1230@item -fno-builtin
1231@itemx -fno-builtin-@var{function}
1232@opindex fno-builtin
1233@cindex built-in functions
1234Don't recognize built-in functions that do not begin with
1235@samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in
1236functions provided by GCC}, for details of the functions affected,
1237including those which are not built-in functions when @option{-ansi} or
1238@option{-std} options for strict ISO C conformance are used because they
1239do not have an ISO standard meaning.
1240
1241GCC normally generates special code to handle certain built-in functions
1242more efficiently; for instance, calls to @code{alloca} may become single
1243instructions that adjust the stack directly, and calls to @code{memcpy}
1244may become inline copy loops. The resulting code is often both smaller
1245and faster, but since the function calls no longer appear as such, you
1246cannot set a breakpoint on those calls, nor can you change the behavior
1247of the functions by linking with a different library. In addition,
1248when a function is recognized as a built-in function, GCC may use
1249information about that function to warn about problems with calls to
1250that function, or to generate more efficient code, even if the
1251resulting code still contains calls to that function. For example,
1252warnings are given with @option{-Wformat} for bad calls to
1253@code{printf}, when @code{printf} is built in, and @code{strlen} is
1254known not to modify global memory.
1255
1256With the @option{-fno-builtin-@var{function}} option
1257only the built-in function @var{function} is
1258disabled. @var{function} must not begin with @samp{__builtin_}. If a
1259function is named this is not built-in in this version of GCC, this
1260option is ignored. There is no corresponding
1261@option{-fbuiltin-@var{function}} option; if you wish to enable
1262built-in functions selectively when using @option{-fno-builtin} or
1263@option{-ffreestanding}, you may define macros such as:
1264
1265@smallexample
1266#define abs(n) __builtin_abs ((n))
1267#define strcpy(d, s) __builtin_strcpy ((d), (s))
1268@end smallexample
1269
1270@item -fhosted
1271@opindex fhosted
1272@cindex hosted environment
1273
1274Assert that compilation takes place in a hosted environment. This implies
1275@option{-fbuiltin}. A hosted environment is one in which the
1276entire standard library is available, and in which @code{main} has a return
1277type of @code{int}. Examples are nearly everything except a kernel.
1278This is equivalent to @option{-fno-freestanding}.
1279
1280@item -ffreestanding
1281@opindex ffreestanding
1282@cindex hosted environment
1283
1284Assert that compilation takes place in a freestanding environment. This
1285implies @option{-fno-builtin}. A freestanding environment
1286is one in which the standard library may not exist, and program startup may
1287not necessarily be at @code{main}. The most obvious example is an OS kernel.
1288This is equivalent to @option{-fno-hosted}.
1289
1290@xref{Standards,,Language Standards Supported by GCC}, for details of
1291freestanding and hosted environments.
1292
1293@item -fopenmp
1294@opindex fopenmp
1295@cindex openmp parallel
1296Enable handling of OpenMP directives @code{#pragma omp} in C/C++ and
1297@code{!$omp} in Fortran. When @option{-fopenmp} is specified, the
1298compiler generates parallel code according to the OpenMP Application
1299Program Interface v2.5 @w{@uref{http://www.openmp.org/}}.
1300
1301@item -fms-extensions
1302@opindex fms-extensions
1303Accept some non-standard constructs used in Microsoft header files.
1304
1305Some cases of unnamed fields in structures and unions are only
1306accepted with this option. @xref{Unnamed Fields,,Unnamed struct/union
1307fields within structs/unions}, for details.
1308
1309@item -trigraphs
1310@opindex trigraphs
1311Support ISO C trigraphs. The @option{-ansi} option (and @option{-std}
1312options for strict ISO C conformance) implies @option{-trigraphs}.
1313
1314@item -no-integrated-cpp
1315@opindex no-integrated-cpp
1316Performs a compilation in two passes: preprocessing and compiling. This
1317option allows a user supplied "cc1", "cc1plus", or "cc1obj" via the
1318@option{-B} option. The user supplied compilation step can then add in
1319an additional preprocessing step after normal preprocessing but before
1320compiling. The default is to use the integrated cpp (internal cpp)
1321
1322The semantics of this option will change if "cc1", "cc1plus", and
1323"cc1obj" are merged.
1324
1325@cindex traditional C language
1326@cindex C language, traditional
1327@item -traditional
1328@itemx -traditional-cpp
1329@opindex traditional-cpp
1330@opindex traditional
1331Formerly, these options caused GCC to attempt to emulate a pre-standard
1332C compiler. They are now only supported with the @option{-E} switch.
1333The preprocessor continues to support a pre-standard mode. See the GNU
1334CPP manual for details.
1335
1336@item -fcond-mismatch
1337@opindex fcond-mismatch
1338Allow conditional expressions with mismatched types in the second and
1339third arguments. The value of such an expression is void. This option
1340is not supported for C++.
1341
1342@item -funsigned-char
1343@opindex funsigned-char
1344Let the type @code{char} be unsigned, like @code{unsigned char}.
1345
1346Each kind of machine has a default for what @code{char} should
1347be. It is either like @code{unsigned char} by default or like
1348@code{signed char} by default.
1349
1350Ideally, a portable program should always use @code{signed char} or
1351@code{unsigned char} when it depends on the signedness of an object.
1352But many programs have been written to use plain @code{char} and
1353expect it to be signed, or expect it to be unsigned, depending on the
1354machines they were written for. This option, and its inverse, let you
1355make such a program work with the opposite default.
1356
1357The type @code{char} is always a distinct type from each of
1358@code{signed char} or @code{unsigned char}, even though its behavior
1359is always just like one of those two.
1360
1361@item -fsigned-char
1362@opindex fsigned-char
1363Let the type @code{char} be signed, like @code{signed char}.
1364
1365Note that this is equivalent to @option{-fno-unsigned-char}, which is
1366the negative form of @option{-funsigned-char}. Likewise, the option
1367@option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
1368
1369@item -fsigned-bitfields
1370@itemx -funsigned-bitfields
1371@itemx -fno-signed-bitfields
1372@itemx -fno-unsigned-bitfields
1373@opindex fsigned-bitfields
1374@opindex funsigned-bitfields
1375@opindex fno-signed-bitfields
1376@opindex fno-unsigned-bitfields
1377These options control whether a bit-field is signed or unsigned, when the
1378declaration does not use either @code{signed} or @code{unsigned}. By
1379default, such a bit-field is signed, because this is consistent: the
1380basic integer types such as @code{int} are signed types.
1381@end table
1382
1383@node C++ Dialect Options
1384@section Options Controlling C++ Dialect
1385
1386@cindex compiler options, C++
1387@cindex C++ options, command line
1388@cindex options, C++
1389This section describes the command-line options that are only meaningful
1390for C++ programs; but you can also use most of the GNU compiler options
1391regardless of what language your program is in. For example, you
1392might compile a file @code{firstClass.C} like this:
1393
1394@smallexample
1395g++ -g -frepo -O -c firstClass.C
1396@end smallexample
1397
1398@noindent
1399In this example, only @option{-frepo} is an option meant
1400only for C++ programs; you can use the other options with any
1401language supported by GCC@.
1402
1403Here is a list of options that are @emph{only} for compiling C++ programs:
1404
1405@table @gcctabopt
1406
1407@item -fabi-version=@var{n}
1408@opindex fabi-version
1409Use version @var{n} of the C++ ABI@. Version 2 is the version of the
1410C++ ABI that first appeared in G++ 3.4. Version 1 is the version of
1411the C++ ABI that first appeared in G++ 3.2. Version 0 will always be
1412the version that conforms most closely to the C++ ABI specification.
1413Therefore, the ABI obtained using version 0 will change as ABI bugs
1414are fixed.
1415
1416The default is version 2.
1417
1418@item -fno-access-control
1419@opindex fno-access-control
1420Turn off all access checking. This switch is mainly useful for working
1421around bugs in the access control code.
1422
1423@item -fcheck-new
1424@opindex fcheck-new
1425Check that the pointer returned by @code{operator new} is non-null
1426before attempting to modify the storage allocated. This check is
1427normally unnecessary because the C++ standard specifies that
1428@code{operator new} will only return @code{0} if it is declared
1429@samp{throw()}, in which case the compiler will always check the
1430return value even without this option. In all other cases, when
1431@code{operator new} has a non-empty exception specification, memory
1432exhaustion is signalled by throwing @code{std::bad_alloc}. See also
1433@samp{new (nothrow)}.
1434
1435@item -fconserve-space
1436@opindex fconserve-space
1437Put uninitialized or runtime-initialized global variables into the
1438common segment, as C does. This saves space in the executable at the
1439cost of not diagnosing duplicate definitions. If you compile with this
1440flag and your program mysteriously crashes after @code{main()} has
1441completed, you may have an object that is being destroyed twice because
1442two definitions were merged.
1443
1444This option is no longer useful on most targets, now that support has
1445been added for putting variables into BSS without making them common.
1446
1447@item -ffriend-injection
1448@opindex ffriend-injection
1449Inject friend functions into the enclosing namespace, so that they are
1450visible outside the scope of the class in which they are declared.
1451Friend functions were documented to work this way in the old Annotated
1452C++ Reference Manual, and versions of G++ before 4.1 always worked
1453that way. However, in ISO C++ a friend function which is not declared
1454in an enclosing scope can only be found using argument dependent
1455lookup. This option causes friends to be injected as they were in
1456earlier releases.
1457
1458This option is for compatibility, and may be removed in a future
1459release of G++.
1460
1461@item -fno-elide-constructors
1462@opindex fno-elide-constructors
1463The C++ standard allows an implementation to omit creating a temporary
1464which is only used to initialize another object of the same type.
1465Specifying this option disables that optimization, and forces G++ to
1466call the copy constructor in all cases.
1467
1468@item -fno-enforce-eh-specs
1469@opindex fno-enforce-eh-specs
1470Don't generate code to check for violation of exception specifications
1471at runtime. This option violates the C++ standard, but may be useful
1472for reducing code size in production builds, much like defining
1473@samp{NDEBUG}. This does not give user code permission to throw
1474exceptions in violation of the exception specifications; the compiler
1475will still optimize based on the specifications, so throwing an
1476unexpected exception will result in undefined behavior.
1477
1478@item -ffor-scope
1479@itemx -fno-for-scope
1480@opindex ffor-scope
1481@opindex fno-for-scope
1482If @option{-ffor-scope} is specified, the scope of variables declared in
1483a @i{for-init-statement} is limited to the @samp{for} loop itself,
1484as specified by the C++ standard.
1485If @option{-fno-for-scope} is specified, the scope of variables declared in
1486a @i{for-init-statement} extends to the end of the enclosing scope,
1487as was the case in old versions of G++, and other (traditional)
1488implementations of C++.
1489
1490The default if neither flag is given to follow the standard,
1491but to allow and give a warning for old-style code that would
1492otherwise be invalid, or have different behavior.
1493
1494@item -fno-gnu-keywords
1495@opindex fno-gnu-keywords
1496Do not recognize @code{typeof} as a keyword, so that code can use this
1497word as an identifier. You can use the keyword @code{__typeof__} instead.
1498@option{-ansi} implies @option{-fno-gnu-keywords}.
1499
1500@item -fno-implicit-templates
1501@opindex fno-implicit-templates
1502Never emit code for non-inline templates which are instantiated
1503implicitly (i.e.@: by use); only emit code for explicit instantiations.
1504@xref{Template Instantiation}, for more information.
1505
1506@item -fno-implicit-inline-templates
1507@opindex fno-implicit-inline-templates
1508Don't emit code for implicit instantiations of inline templates, either.
1509The default is to handle inlines differently so that compiles with and
1510without optimization will need the same set of explicit instantiations.
1511
1512@item -fno-implement-inlines
1513@opindex fno-implement-inlines
1514To save space, do not emit out-of-line copies of inline functions
1515controlled by @samp{#pragma implementation}. This will cause linker
1516errors if these functions are not inlined everywhere they are called.
1517
1518@item -fms-extensions
1519@opindex fms-extensions
1520Disable pedantic warnings about constructs used in MFC, such as implicit
1521int and getting a pointer to member function via non-standard syntax.
1522
1523@item -fno-nonansi-builtins
1524@opindex fno-nonansi-builtins
1525Disable built-in declarations of functions that are not mandated by
1526ANSI/ISO C@. These include @code{ffs}, @code{alloca}, @code{_exit},
1527@code{index}, @code{bzero}, @code{conjf}, and other related functions.
1528
1529@item -fno-operator-names
1530@opindex fno-operator-names
1531Do not treat the operator name keywords @code{and}, @code{bitand},
1532@code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1533synonyms as keywords.
1534
1535@item -fno-optional-diags
1536@opindex fno-optional-diags
1537Disable diagnostics that the standard says a compiler does not need to
1538issue. Currently, the only such diagnostic issued by G++ is the one for
1539a name having multiple meanings within a class.
1540
1541@item -fpermissive
1542@opindex fpermissive
1543Downgrade some diagnostics about nonconformant code from errors to
1544warnings. Thus, using @option{-fpermissive} will allow some
1545nonconforming code to compile.
1546
1547@item -frepo
1548@opindex frepo
1549Enable automatic template instantiation at link time. This option also
1550implies @option{-fno-implicit-templates}. @xref{Template
1551Instantiation}, for more information.
1552
1553@item -fno-rtti
1554@opindex fno-rtti
1555Disable generation of information about every class with virtual
1556functions for use by the C++ runtime type identification features
1557(@samp{dynamic_cast} and @samp{typeid}). If you don't use those parts
1558of the language, you can save some space by using this flag. Note that
1559exception handling uses the same information, but it will generate it as
1560needed. The @samp{dynamic_cast} operator can still be used for casts that
1561do not require runtime type information, i.e. casts to @code{void *} or to
1562unambiguous base classes.
1563
1564@item -fstats
1565@opindex fstats
1566Emit statistics about front-end processing at the end of the compilation.
1567This information is generally only useful to the G++ development team.
1568
1569@item -ftemplate-depth-@var{n}
1570@opindex ftemplate-depth
1571Set the maximum instantiation depth for template classes to @var{n}.
1572A limit on the template instantiation depth is needed to detect
1573endless recursions during template class instantiation. ANSI/ISO C++
1574conforming programs must not rely on a maximum depth greater than 17.
1575
1576@item -fno-threadsafe-statics
1577@opindex fno-threadsafe-statics
1578Do not emit the extra code to use the routines specified in the C++
1579ABI for thread-safe initialization of local statics. You can use this
1580option to reduce code size slightly in code that doesn't need to be
1581thread-safe.
1582
1583@item -fuse-cxa-atexit
1584@opindex fuse-cxa-atexit
1585Register destructors for objects with static storage duration with the
1586@code{__cxa_atexit} function rather than the @code{atexit} function.
1587This option is required for fully standards-compliant handling of static
1588destructors, but will only work if your C library supports
1589@code{__cxa_atexit}.
1590
1591@item -fno-use-cxa-get-exception-ptr
1592@opindex fno-use-cxa-get-exception-ptr
1593Don't use the @code{__cxa_get_exception_ptr} runtime routine. This
1594will cause @code{std::uncaught_exception} to be incorrect, but is necessary
1595if the runtime routine is not available.
1596
1597@item -fvisibility-inlines-hidden
1598@opindex fvisibility-inlines-hidden
1599This switch declares that the user does not attempt to compare
1600pointers to inline methods where the addresses of the two functions
1601were taken in different shared objects.
1602
1603The effect of this is that GCC may, effectively, mark inline methods with
1604@code{__attribute__ ((visibility ("hidden")))} so that they do not
1605appear in the export table of a DSO and do not require a PLT indirection
1606when used within the DSO@. Enabling this option can have a dramatic effect
1607on load and link times of a DSO as it massively reduces the size of the
1608dynamic export table when the library makes heavy use of templates.
1609
1610The behaviour of this switch is not quite the same as marking the
1611methods as hidden directly, because it does not affect static variables
1612local to the function or cause the compiler to deduce that
1613the function is defined in only one shared object.
1614
1615You may mark a method as having a visibility explicitly to negate the
1616effect of the switch for that method. For example, if you do want to
1617compare pointers to a particular inline method, you might mark it as
1618having default visibility. Marking the enclosing class with explicit
1619visibility will have no effect.
1620
1621Explicitly instantiated inline methods are unaffected by this option
1622as their linkage might otherwise cross a shared library boundary.
1623@xref{Template Instantiation}.
1624
1625@item -fno-weak
1626@opindex fno-weak
1627Do not use weak symbol support, even if it is provided by the linker.
1628By default, G++ will use weak symbols if they are available. This
1629option exists only for testing, and should not be used by end-users;
1630it will result in inferior code and has no benefits. This option may
1631be removed in a future release of G++.
1632
1633@item -nostdinc++
1634@opindex nostdinc++
1635Do not search for header files in the standard directories specific to
1636C++, but do still search the other standard directories. (This option
1637is used when building the C++ library.)
1638@end table
1639
1640In addition, these optimization, warning, and code generation options
1641have meanings only for C++ programs:
1642
1643@table @gcctabopt
1644@item -fno-default-inline
1645@opindex fno-default-inline
1646Do not assume @samp{inline} for functions defined inside a class scope.
1647@xref{Optimize Options,,Options That Control Optimization}. Note that these
1648functions will have linkage like inline functions; they just won't be
1649inlined by default.
1650
1651@item -Wabi @r{(C++ only)}
1652@opindex Wabi
1653Warn when G++ generates code that is probably not compatible with the
1654vendor-neutral C++ ABI@. Although an effort has been made to warn about
1655all such cases, there are probably some cases that are not warned about,
1656even though G++ is generating incompatible code. There may also be
1657cases where warnings are emitted even though the code that is generated
1658will be compatible.
1659
1660You should rewrite your code to avoid these warnings if you are
1661concerned about the fact that code generated by G++ may not be binary
1662compatible with code generated by other compilers.
1663
1664The known incompatibilities at this point include:
1665
1666@itemize @bullet
1667
1668@item
1669Incorrect handling of tail-padding for bit-fields. G++ may attempt to
1670pack data into the same byte as a base class. For example:
1671
1672@smallexample
1673struct A @{ virtual void f(); int f1 : 1; @};
1674struct B : public A @{ int f2 : 1; @};
1675@end smallexample
1676
1677@noindent
1678In this case, G++ will place @code{B::f2} into the same byte
1679as@code{A::f1}; other compilers will not. You can avoid this problem
1680by explicitly padding @code{A} so that its size is a multiple of the
1681byte size on your platform; that will cause G++ and other compilers to
1682layout @code{B} identically.
1683
1684@item
1685Incorrect handling of tail-padding for virtual bases. G++ does not use
1686tail padding when laying out virtual bases. For example:
1687
1688@smallexample
1689struct A @{ virtual void f(); char c1; @};
1690struct B @{ B(); char c2; @};
1691struct C : public A, public virtual B @{@};
1692@end smallexample
1693
1694@noindent
1695In this case, G++ will not place @code{B} into the tail-padding for
1696@code{A}; other compilers will. You can avoid this problem by
1697explicitly padding @code{A} so that its size is a multiple of its
1698alignment (ignoring virtual base classes); that will cause G++ and other
1699compilers to layout @code{C} identically.
1700
1701@item
1702Incorrect handling of bit-fields with declared widths greater than that
1703of their underlying types, when the bit-fields appear in a union. For
1704example:
1705
1706@smallexample
1707union U @{ int i : 4096; @};
1708@end smallexample
1709
1710@noindent
1711Assuming that an @code{int} does not have 4096 bits, G++ will make the
1712union too small by the number of bits in an @code{int}.
1713
1714@item
1715Empty classes can be placed at incorrect offsets. For example:
1716
1717@smallexample
1718struct A @{@};
1719
1720struct B @{
1721 A a;
1722 virtual void f ();
1723@};
1724
1725struct C : public B, public A @{@};
1726@end smallexample
1727
1728@noindent
1729G++ will place the @code{A} base class of @code{C} at a nonzero offset;
1730it should be placed at offset zero. G++ mistakenly believes that the
1731@code{A} data member of @code{B} is already at offset zero.
1732
1733@item
1734Names of template functions whose types involve @code{typename} or
1735template template parameters can be mangled incorrectly.
1736
1737@smallexample
1738template <typename Q>
1739void f(typename Q::X) @{@}
1740
1741template <template <typename> class Q>
1742void f(typename Q<int>::X) @{@}
1743@end smallexample
1744
1745@noindent
1746Instantiations of these templates may be mangled incorrectly.
1747
1748@end itemize
1749
1750@item -Wctor-dtor-privacy @r{(C++ only)}
1751@opindex Wctor-dtor-privacy
1752Warn when a class seems unusable because all the constructors or
1753destructors in that class are private, and it has neither friends nor
1754public static member functions.
1755
1756@item -Wnon-virtual-dtor @r{(C++ only)}
1757@opindex Wnon-virtual-dtor
1758Warn when a class appears to be polymorphic, thereby requiring a virtual
1759destructor, yet it declares a non-virtual one. This warning is also
1760enabled if -Weffc++ is specified.
1761
1762@item -Wreorder @r{(C++ only)}
1763@opindex Wreorder
1764@cindex reordering, warning
1765@cindex warning for reordering of member initializers
1766Warn when the order of member initializers given in the code does not
1767match the order in which they must be executed. For instance:
1768
1769@smallexample
1770struct A @{
1771 int i;
1772 int j;
1773 A(): j (0), i (1) @{ @}
1774@};
1775@end smallexample
1776
1777The compiler will rearrange the member initializers for @samp{i}
1778and @samp{j} to match the declaration order of the members, emitting
1779a warning to that effect. This warning is enabled by @option{-Wall}.
1780@end table
1781
1782The following @option{-W@dots{}} options are not affected by @option{-Wall}.
1783
1784@table @gcctabopt
1785@item -Weffc++ @r{(C++ only)}
1786@opindex Weffc++
1787Warn about violations of the following style guidelines from Scott Meyers'
1788@cite{Effective C++} book:
1789
1790@itemize @bullet
1791@item
1792Item 11: Define a copy constructor and an assignment operator for classes
1793with dynamically allocated memory.
1794
1795@item
1796Item 12: Prefer initialization to assignment in constructors.
1797
1798@item
1799Item 14: Make destructors virtual in base classes.
1800
1801@item
1802Item 15: Have @code{operator=} return a reference to @code{*this}.
1803
1804@item
1805Item 23: Don't try to return a reference when you must return an object.
1806
1807@end itemize
1808
1809Also warn about violations of the following style guidelines from
1810Scott Meyers' @cite{More Effective C++} book:
1811
1812@itemize @bullet
1813@item
1814Item 6: Distinguish between prefix and postfix forms of increment and
1815decrement operators.
1816
1817@item
1818Item 7: Never overload @code{&&}, @code{||}, or @code{,}.
1819
1820@end itemize
1821
1822When selecting this option, be aware that the standard library
1823headers do not obey all of these guidelines; use @samp{grep -v}
1824to filter out those warnings.
1825
1826@item -Wno-deprecated @r{(C++ only)}
1827@opindex Wno-deprecated
1828Do not warn about usage of deprecated features. @xref{Deprecated Features}.
1829
1830@item -Wstrict-null-sentinel @r{(C++ only)}
1831@opindex Wstrict-null-sentinel
1832Warn also about the use of an uncasted @code{NULL} as sentinel. When
1833compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
1834to @code{__null}. Although it is a null pointer constant not a null pointer,
1835it is guaranteed to of the same size as a pointer. But this use is
1836not portable across different compilers.
1837
1838@item -Wno-non-template-friend @r{(C++ only)}
1839@opindex Wno-non-template-friend
1840Disable warnings when non-templatized friend functions are declared
1841within a template. Since the advent of explicit template specification
1842support in G++, if the name of the friend is an unqualified-id (i.e.,
1843@samp{friend foo(int)}), the C++ language specification demands that the
1844friend declare or define an ordinary, nontemplate function. (Section
184514.5.3). Before G++ implemented explicit specification, unqualified-ids
1846could be interpreted as a particular specialization of a templatized
1847function. Because this non-conforming behavior is no longer the default
1848behavior for G++, @option{-Wnon-template-friend} allows the compiler to
1849check existing code for potential trouble spots and is on by default.
1850This new compiler behavior can be turned off with
1851@option{-Wno-non-template-friend} which keeps the conformant compiler code
1852but disables the helpful warning.
1853
1854@item -Wold-style-cast @r{(C++ only)}
1855@opindex Wold-style-cast
1856Warn if an old-style (C-style) cast to a non-void type is used within
1857a C++ program. The new-style casts (@samp{dynamic_cast},
1858@samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are
1859less vulnerable to unintended effects and much easier to search for.
1860
1861@item -Woverloaded-virtual @r{(C++ only)}
1862@opindex Woverloaded-virtual
1863@cindex overloaded virtual fn, warning
1864@cindex warning for overloaded virtual fn
1865Warn when a function declaration hides virtual functions from a
1866base class. For example, in:
1867
1868@smallexample
1869struct A @{
1870 virtual void f();
1871@};
1872
1873struct B: public A @{
1874 void f(int);
1875@};
1876@end smallexample
1877
1878the @code{A} class version of @code{f} is hidden in @code{B}, and code
1879like:
1880
1881@smallexample
1882B* b;
1883b->f();
1884@end smallexample
1885
1886will fail to compile.
1887
1888@item -Wno-pmf-conversions @r{(C++ only)}
1889@opindex Wno-pmf-conversions
1890Disable the diagnostic for converting a bound pointer to member function
1891to a plain pointer.
1892
1893@item -Wsign-promo @r{(C++ only)}
1894@opindex Wsign-promo
1895Warn when overload resolution chooses a promotion from unsigned or
1896enumerated type to a signed type, over a conversion to an unsigned type of
1897the same size. Previous versions of G++ would try to preserve
1898unsignedness, but the standard mandates the current behavior.
1899
1900@smallexample
1901struct A @{
1902 operator int ();
1903 A& operator = (int);
1904@};
1905
1906main ()
1907@{
1908 A a,b;
1909 a = b;
1910@}
1911@end smallexample
1912
1913In this example, G++ will synthesize a default @samp{A& operator =
1914(const A&);}, while cfront will use the user-defined @samp{operator =}.
1915@end table
1916
1917@node Language Independent Options
1918@section Options to Control Diagnostic Messages Formatting
1919@cindex options to control diagnostics formatting
1920@cindex diagnostic messages
1921@cindex message formatting
1922
1923Traditionally, diagnostic messages have been formatted irrespective of
1924the output device's aspect (e.g.@: its width, @dots{}). The options described
1925below can be used to control the diagnostic messages formatting
1926algorithm, e.g.@: how many characters per line, how often source location
1927information should be reported. Right now, only the C++ front end can
1928honor these options. However it is expected, in the near future, that
1929the remaining front ends would be able to digest them correctly.
1930
1931@table @gcctabopt
1932@item -fmessage-length=@var{n}
1933@opindex fmessage-length
1934Try to format error messages so that they fit on lines of about @var{n}
1935characters. The default is 72 characters for @command{g++} and 0 for the rest of
1936the front ends supported by GCC@. If @var{n} is zero, then no
1937line-wrapping will be done; each error message will appear on a single
1938line.
1939
1940@opindex fdiagnostics-show-location
1941@item -fdiagnostics-show-location=once
1942Only meaningful in line-wrapping mode. Instructs the diagnostic messages
1943reporter to emit @emph{once} source location information; that is, in
1944case the message is too long to fit on a single physical line and has to
1945be wrapped, the source location won't be emitted (as prefix) again,
1946over and over, in subsequent continuation lines. This is the default
1947behavior.
1948
1949@item -fdiagnostics-show-location=every-line
1950Only meaningful in line-wrapping mode. Instructs the diagnostic
1951messages reporter to emit the same source location information (as
1952prefix) for physical lines that result from the process of breaking
1953a message which is too long to fit on a single line.
1954
1955@item -fdiagnostics-show-option
1956@opindex fdiagnostics-show-option
1957This option instructs the diagnostic machinery to add text to each
1958diagnostic emitted, which indicates which command line option directly
1959controls that diagnostic, when such an option is known to the
1960diagnostic machinery.
1961
1962@end table
1963
1964@node Warning Options
1965@section Options to Request or Suppress Warnings
1966@cindex options to control warnings
1967@cindex warning messages
1968@cindex messages, warning
1969@cindex suppressing warnings
1970
1971Warnings are diagnostic messages that report constructions which
1972are not inherently erroneous but which are risky or suggest there
1973may have been an error.
1974
1975You can request many specific warnings with options beginning @samp{-W},
1976for example @option{-Wimplicit} to request warnings on implicit
1977declarations. Each of these specific warning options also has a
1978negative form beginning @samp{-Wno-} to turn off warnings;
1979for example, @option{-Wno-implicit}. This manual lists only one of the
1980two forms, whichever is not the default.
1981
1982The following options control the amount and kinds of warnings produced
1983by GCC; for further, language-specific options also refer to
1984@ref{C++ Dialect Options}.
1985
1986@table @gcctabopt
1987@cindex syntax checking
1988@item -fsyntax-only
1989@opindex fsyntax-only
1990Check the code for syntax errors, but don't do anything beyond that.
1991
1992@item -pedantic
1993@opindex pedantic
1994Issue all the warnings demanded by strict ISO C and ISO C++;
1995reject all programs that use forbidden extensions, and some other
1996programs that do not follow ISO C and ISO C++. For ISO C, follows the
1997version of the ISO C standard specified by any @option{-std} option used.
1998
1999Valid ISO C and ISO C++ programs should compile properly with or without
2000this option (though a rare few will require @option{-ansi} or a
2001@option{-std} option specifying the required version of ISO C)@. However,
2002without this option, certain GNU extensions and traditional C and C++
2003features are supported as well. With this option, they are rejected.
2004
2005@option{-pedantic} does not cause warning messages for use of the
2006alternate keywords whose names begin and end with @samp{__}. Pedantic
2007warnings are also disabled in the expression that follows
2008@code{__extension__}. However, only system header files should use
2009these escape routes; application programs should avoid them.
2010@xref{Alternate Keywords}.
2011
2012Some users try to use @option{-pedantic} to check programs for strict ISO
2013C conformance. They soon find that it does not do quite what they want:
2014it finds some non-ISO practices, but not all---only those for which
2015ISO C @emph{requires} a diagnostic, and some others for which
2016diagnostics have been added.
2017
2018A feature to report any failure to conform to ISO C might be useful in
2019some instances, but would require considerable additional work and would
2020be quite different from @option{-pedantic}. We don't have plans to
2021support such a feature in the near future.
2022
2023Where the standard specified with @option{-std} represents a GNU
2024extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
2025corresponding @dfn{base standard}, the version of ISO C on which the GNU
2026extended dialect is based. Warnings from @option{-pedantic} are given
2027where they are required by the base standard. (It would not make sense
2028for such warnings to be given only for features not in the specified GNU
2029C dialect, since by definition the GNU dialects of C include all
2030features the compiler supports with the given option, and there would be
2031nothing to warn about.)
2032
2033@item -pedantic-errors
2034@opindex pedantic-errors
2035Like @option{-pedantic}, except that errors are produced rather than
2036warnings.
2037
2038@item -w
2039@opindex w
2040Inhibit all warning messages.
2041
2042@item -Wno-import
2043@opindex Wno-import
2044Inhibit warning messages about the use of @samp{#import}.
2045
2046@c APPLE LOCAL begin -Wnewline-eof 2001-08-23 --sts **
2047@item -Wnewline-eof
2048@opindex Wnewline-eof
2049Warn about files missing a newline at the end of the file. (Apple compatible)
2050@c APPLE LOCAL end -Wnewline-eof 2001-08-23 --sts **
2051
2052@item -Wchar-subscripts
2053@opindex Wchar-subscripts
2054Warn if an array subscript has type @code{char}. This is a common cause
2055of error, as programmers often forget that this type is signed on some
2056machines.
2057This warning is enabled by @option{-Wall}.
2058
2059@item -Wcomment
2060@opindex Wcomment
2061Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
2062comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
2063This warning is enabled by @option{-Wall}.
2064
2065@item -Wfatal-errors
2066@opindex Wfatal-errors
2067This option causes the compiler to abort compilation on the first error
2068occurred rather than trying to keep going and printing further error
2069messages.
2070
2071@item -Wformat
2072@opindex Wformat
2073@opindex ffreestanding
2074@opindex fno-builtin
2075Check calls to @code{printf} and @code{scanf}, etc., to make sure that
2076the arguments supplied have types appropriate to the format string
2077specified, and that the conversions specified in the format string make
2078sense. This includes standard functions, and others specified by format
2079attributes (@pxref{Function Attributes}), in the @code{printf},
2080@code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
2081not in the C standard) families (or other target-specific families).
2082Which functions are checked without format attributes having been
2083specified depends on the standard version selected, and such checks of
2084functions without the attribute specified are disabled by
2085@option{-ffreestanding} or @option{-fno-builtin}.
2086
2087The formats are checked against the format features supported by GNU
2088libc version 2.2. These include all ISO C90 and C99 features, as well
2089as features from the Single Unix Specification and some BSD and GNU
2090extensions. Other library implementations may not support all these
2091features; GCC does not support warning about features that go beyond a
2092particular library's limitations. However, if @option{-pedantic} is used
2093with @option{-Wformat}, warnings will be given about format features not
2094in the selected standard version (but not for @code{strfmon} formats,
2095since those are not in any version of the C standard). @xref{C Dialect
2096Options,,Options Controlling C Dialect}.
2097
2098Since @option{-Wformat} also checks for null format arguments for
2099several functions, @option{-Wformat} also implies @option{-Wnonnull}.
2100
2101@option{-Wformat} is included in @option{-Wall}. For more control over some
2102aspects of format checking, the options @option{-Wformat-y2k},
2103@option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
2104@option{-Wformat-nonliteral}, @option{-Wformat-security}, and
2105@option{-Wformat=2} are available, but are not included in @option{-Wall}.
2106
2107@item -Wformat-y2k
2108@opindex Wformat-y2k
2109If @option{-Wformat} is specified, also warn about @code{strftime}
2110formats which may yield only a two-digit year.
2111
2112@item -Wno-format-extra-args
2113@opindex Wno-format-extra-args
2114If @option{-Wformat} is specified, do not warn about excess arguments to a
2115@code{printf} or @code{scanf} format function. The C standard specifies
2116that such arguments are ignored.
2117
2118Where the unused arguments lie between used arguments that are
2119specified with @samp{$} operand number specifications, normally
2120warnings are still given, since the implementation could not know what
2121type to pass to @code{va_arg} to skip the unused arguments. However,
2122in the case of @code{scanf} formats, this option will suppress the
2123warning if the unused arguments are all pointers, since the Single
2124Unix Specification says that such unused arguments are allowed.
2125
2126@item -Wno-format-zero-length
2127@opindex Wno-format-zero-length
2128If @option{-Wformat} is specified, do not warn about zero-length formats.
2129The C standard specifies that zero-length formats are allowed.
2130
2131@item -Wformat-nonliteral
2132@opindex Wformat-nonliteral
2133If @option{-Wformat} is specified, also warn if the format string is not a
2134string literal and so cannot be checked, unless the format function
2135takes its format arguments as a @code{va_list}.
2136
2137@item -Wformat-security
2138@opindex Wformat-security
2139If @option{-Wformat} is specified, also warn about uses of format
2140functions that represent possible security problems. At present, this
2141warns about calls to @code{printf} and @code{scanf} functions where the
2142format string is not a string literal and there are no format arguments,
2143as in @code{printf (foo);}. This may be a security hole if the format
2144string came from untrusted input and contains @samp{%n}. (This is
2145currently a subset of what @option{-Wformat-nonliteral} warns about, but
2146in future warnings may be added to @option{-Wformat-security} that are not
2147included in @option{-Wformat-nonliteral}.)
2148
2149@item -Wformat=2
2150@opindex Wformat=2
2151Enable @option{-Wformat} plus format checks not included in
2152@option{-Wformat}. Currently equivalent to @samp{-Wformat
2153-Wformat-nonliteral -Wformat-security -Wformat-y2k}.
2154
2155@item -Wnonnull
2156@opindex Wnonnull
2157Warn about passing a null pointer for arguments marked as
2158requiring a non-null value by the @code{nonnull} function attribute.
2159
2160@option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It
2161can be disabled with the @option{-Wno-nonnull} option.
2162
2163@item -Winit-self @r{(C and C++ only)}
2164@opindex Winit-self
2165Warn about uninitialized variables which are initialized with themselves.
2166Note this option can only be used with the @option{-Wuninitialized} option,
2167which in turn only works with @option{-O1} and above.
2168
2169For example, GCC will warn about @code{i} being uninitialized in the
2170following snippet only when @option{-Winit-self} has been specified:
2171@smallexample
2172@group
2173int f()
2174@{
2175 int i = i;
2176 return i;
2177@}
2178@end group
2179@end smallexample
2180
2181@item -Wimplicit-int
2182@opindex Wimplicit-int
2183Warn when a declaration does not specify a type.
2184This warning is enabled by @option{-Wall}.
2185
2186@item -Wimplicit-function-declaration
2187@itemx -Werror-implicit-function-declaration
2188@opindex Wimplicit-function-declaration
2189@opindex Werror-implicit-function-declaration
2190Give a warning (or error) whenever a function is used before being
2191declared. The form @option{-Wno-error-implicit-function-declaration}
2192is not supported.
2193This warning is enabled by @option{-Wall} (as a warning, not an error).
2194
2195@item -Wimplicit
2196@opindex Wimplicit
2197Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
2198This warning is enabled by @option{-Wall}.
2199
2200@item -Wmain
2201@opindex Wmain
2202Warn if the type of @samp{main} is suspicious. @samp{main} should be a
2203function with external linkage, returning int, taking either zero
2204arguments, two, or three arguments of appropriate types.
2205This warning is enabled by @option{-Wall}.
2206
2207@item -Wmissing-braces
2208@opindex Wmissing-braces
2209Warn if an aggregate or union initializer is not fully bracketed. In
2210the following example, the initializer for @samp{a} is not fully
2211bracketed, but that for @samp{b} is fully bracketed.
2212
2213@smallexample
2214int a[2][2] = @{ 0, 1, 2, 3 @};
2215int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
2216@end smallexample
2217
2218This warning is enabled by @option{-Wall}.
2219
2220@item -Wmissing-include-dirs @r{(C and C++ only)}
2221@opindex Wmissing-include-dirs
2222Warn if a user-supplied include directory does not exist.
2223
2224@item -Wparentheses
2225@opindex Wparentheses
2226Warn if parentheses are omitted in certain contexts, such
2227as when there is an assignment in a context where a truth value
2228is expected, or when operators are nested whose precedence people
2229often get confused about.
2230
2231Also warn if a comparison like @samp{x<=y<=z} appears; this is
2232equivalent to @samp{(x<=y ? 1 : 0) <= z}, which is a different
2233interpretation from that of ordinary mathematical notation.
2234
2235Also warn about constructions where there may be confusion to which
2236@code{if} statement an @code{else} branch belongs. Here is an example of
2237such a case:
2238
2239@smallexample
2240@group
2241@{
2242 if (a)
2243 if (b)
2244 foo ();
2245 else
2246 bar ();
2247@}
2248@end group
2249@end smallexample
2250
2251In C/C++, every @code{else} branch belongs to the innermost possible
2252@code{if} statement, which in this example is @code{if (b)}. This is
2253often not what the programmer expected, as illustrated in the above
2254example by indentation the programmer chose. When there is the
2255potential for this confusion, GCC will issue a warning when this flag
2256is specified. To eliminate the warning, add explicit braces around
2257the innermost @code{if} statement so there is no way the @code{else}
2258could belong to the enclosing @code{if}. The resulting code would
2259look like this:
2260
2261@smallexample
2262@group
2263@{
2264 if (a)
2265 @{
2266 if (b)
2267 foo ();
2268 else
2269 bar ();
2270 @}
2271@}
2272@end group
2273@end smallexample
2274
2275This warning is enabled by @option{-Wall}.
2276
2277@item -Wsequence-point
2278@opindex Wsequence-point
2279Warn about code that may have undefined semantics because of violations
2280of sequence point rules in the C and C++ standards.
2281
2282The C and C++ standards defines the order in which expressions in a C/C++
2283program are evaluated in terms of @dfn{sequence points}, which represent
2284a partial ordering between the execution of parts of the program: those
2285executed before the sequence point, and those executed after it. These
2286occur after the evaluation of a full expression (one which is not part
2287of a larger expression), after the evaluation of the first operand of a
2288@code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
2289function is called (but after the evaluation of its arguments and the
2290expression denoting the called function), and in certain other places.
2291Other than as expressed by the sequence point rules, the order of
2292evaluation of subexpressions of an expression is not specified. All
2293these rules describe only a partial order rather than a total order,
2294since, for example, if two functions are called within one expression
2295with no sequence point between them, the order in which the functions
2296are called is not specified. However, the standards committee have
2297ruled that function calls do not overlap.
2298
2299It is not specified when between sequence points modifications to the
2300values of objects take effect. Programs whose behavior depends on this
2301have undefined behavior; the C and C++ standards specify that ``Between
2302the previous and next sequence point an object shall have its stored
2303value modified at most once by the evaluation of an expression.
2304Furthermore, the prior value shall be read only to determine the value
2305to be stored.''. If a program breaks these rules, the results on any
2306particular implementation are entirely unpredictable.
2307
2308Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
2309= b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
2310diagnosed by this option, and it may give an occasional false positive
2311result, but in general it has been found fairly effective at detecting
2312this sort of problem in programs.
2313
2314The standard is worded confusingly, therefore there is some debate
2315over the precise meaning of the sequence point rules in subtle cases.
2316Links to discussions of the problem, including proposed formal
2317definitions, may be found on the GCC readings page, at
2318@w{@uref{http://gcc.gnu.org/readings.html}}.
2319
2320This warning is enabled by @option{-Wall} for C and C++.
2321
2322@item -Wreturn-type
2323@opindex Wreturn-type
2324Warn whenever a function is defined with a return-type that defaults to
2325@code{int}. Also warn about any @code{return} statement with no
2326return-value in a function whose return-type is not @code{void}.
2327
2328For C, also warn if the return type of a function has a type qualifier
2329such as @code{const}. Such a type qualifier has no effect, since the
2330value returned by a function is not an lvalue. ISO C prohibits
2331qualified @code{void} return types on function definitions, so such
2332return types always receive a warning even without this option.
2333
2334For C++, a function without return type always produces a diagnostic
2335message, even when @option{-Wno-return-type} is specified. The only
2336exceptions are @samp{main} and functions defined in system headers.
2337
2338This warning is enabled by @option{-Wall}.
2339
2340@item -Wswitch
2341@opindex Wswitch
2342Warn whenever a @code{switch} statement has an index of enumerated type
2343and lacks a @code{case} for one or more of the named codes of that
2344enumeration. (The presence of a @code{default} label prevents this
2345warning.) @code{case} labels outside the enumeration range also
2346provoke warnings when this option is used.
2347This warning is enabled by @option{-Wall}.
2348
2349@item -Wswitch-default
2350@opindex Wswitch-switch
2351Warn whenever a @code{switch} statement does not have a @code{default}
2352case.
2353
2354@item -Wswitch-enum
2355@opindex Wswitch-enum
2356Warn whenever a @code{switch} statement has an index of enumerated type
2357and lacks a @code{case} for one or more of the named codes of that
2358enumeration. @code{case} labels outside the enumeration range also
2359provoke warnings when this option is used.
2360
2361@item -Wtrigraphs
2362@opindex Wtrigraphs
2363Warn if any trigraphs are encountered that might change the meaning of
2364the program (trigraphs within comments are not warned about).
2365This warning is enabled by @option{-Wall}.
2366
2367@item -Wunused-function
2368@opindex Wunused-function
2369Warn whenever a static function is declared but not defined or a
2370non-inline static function is unused.
2371This warning is enabled by @option{-Wall}.
2372
2373@item -Wunused-label
2374@opindex Wunused-label
2375Warn whenever a label is declared but not used.
2376This warning is enabled by @option{-Wall}.
2377
2378To suppress this warning use the @samp{unused} attribute
2379(@pxref{Variable Attributes}).
2380
2381@item -Wunused-parameter
2382@opindex Wunused-parameter
2383Warn whenever a function parameter is unused aside from its declaration.
2384
2385To suppress this warning use the @samp{unused} attribute
2386(@pxref{Variable Attributes}).
2387
2388@item -Wunused-variable
2389@opindex Wunused-variable
2390Warn whenever a local variable or non-constant static variable is unused
2391aside from its declaration.
2392This warning is enabled by @option{-Wall}.
2393
2394To suppress this warning use the @samp{unused} attribute
2395(@pxref{Variable Attributes}).
2396
2397@item -Wunused-value
2398@opindex Wunused-value
2399Warn whenever a statement computes a result that is explicitly not used.
2400This warning is enabled by @option{-Wall}.
2401
2402To suppress this warning cast the expression to @samp{void}.
2403
2404@item -Wunused
2405@opindex Wunused
2406All the above @option{-Wunused} options combined.
2407
2408In order to get a warning about an unused function parameter, you must
2409either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
2410@samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
2411
2412@item -Wuninitialized
2413@opindex Wuninitialized
2414Warn if an automatic variable is used without first being initialized or
2415if a variable may be clobbered by a @code{setjmp} call.
2416
2417These warnings are possible only in optimizing compilation,
2418because they require data flow information that is computed only
2419when optimizing. If you do not specify @option{-O}, you will not get
2420these warnings. Instead, GCC will issue a warning about @option{-Wuninitialized}
2421requiring @option{-O}.
2422
2423If you want to warn about code which uses the uninitialized value of the
2424variable in its own initializer, use the @option{-Winit-self} option.
2425
2426These warnings occur for individual uninitialized or clobbered
2427elements of structure, union or array variables as well as for
2428variables which are uninitialized or clobbered as a whole. They do
2429not occur for variables or elements declared @code{volatile}. Because
2430these warnings depend on optimization, the exact variables or elements
2431for which there are warnings will depend on the precise optimization
2432options and version of GCC used.
2433
2434Note that there may be no warning about a variable that is used only
2435to compute a value that itself is never used, because such
2436computations may be deleted by data flow analysis before the warnings
2437are printed.
2438
2439These warnings are made optional because GCC is not smart
2440enough to see all the reasons why the code might be correct
2441despite appearing to have an error. Here is one example of how
2442this can happen:
2443
2444@smallexample
2445@group
2446@{
2447 int x;
2448 switch (y)
2449 @{
2450 case 1: x = 1;
2451 break;
2452 case 2: x = 4;
2453 break;
2454 case 3: x = 5;
2455 @}
2456 foo (x);
2457@}
2458@end group
2459@end smallexample
2460
2461@noindent
2462If the value of @code{y} is always 1, 2 or 3, then @code{x} is
2463always initialized, but GCC doesn't know this. Here is
2464another common case:
2465
2466@smallexample
2467@{
2468 int save_y;
2469 if (change_y) save_y = y, y = new_y;
2470 @dots{}
2471 if (change_y) y = save_y;
2472@}
2473@end smallexample
2474
2475@noindent
2476This has no bug because @code{save_y} is used only if it is set.
2477
2478@cindex @code{longjmp} warnings
2479This option also warns when a non-volatile automatic variable might be
2480changed by a call to @code{longjmp}. These warnings as well are possible
2481only in optimizing compilation.
2482
2483The compiler sees only the calls to @code{setjmp}. It cannot know
2484where @code{longjmp} will be called; in fact, a signal handler could
2485call it at any point in the code. As a result, you may get a warning
2486even when there is in fact no problem because @code{longjmp} cannot
2487in fact be called at the place which would cause a problem.
2488
2489Some spurious warnings can be avoided if you declare all the functions
2490you use that never return as @code{noreturn}. @xref{Function
2491Attributes}.
2492
2493This warning is enabled by @option{-Wall}.
2494
2495@item -Wunknown-pragmas
2496@opindex Wunknown-pragmas
2497@cindex warning for unknown pragmas
2498@cindex unknown pragmas, warning
2499@cindex pragmas, warning of unknown
2500Warn when a #pragma directive is encountered which is not understood by
2501GCC@. If this command line option is used, warnings will even be issued
2502for unknown pragmas in system header files. This is not the case if
2503the warnings were only enabled by the @option{-Wall} command line option.
2504
2505@item -Wno-pragmas
2506@opindex Wno-pragmas
2507@opindex Wpragmas
2508Do not warn about misuses of pragmas, such as incorrect parameters,
2509invalid syntax, or conflicts between pragmas. See also
2510@samp{-Wunknown-pragmas}.
2511
2512@item -Wstrict-aliasing
2513@opindex Wstrict-aliasing
2514This option is only active when @option{-fstrict-aliasing} is active.
2515It warns about code which might break the strict aliasing rules that the
2516compiler is using for optimization. The warning does not catch all
2517cases, but does attempt to catch the more common pitfalls. It is
2518included in @option{-Wall}.
2519It is equivalent to -Wstrict-aliasing=3
2520
2521@item -Wstrict-aliasing=n
2522@opindex Wstrict-aliasing=n
2523This option is only active when @option{-fstrict-aliasing} is active.
2524It warns about code which might break the strict aliasing rules that the
2525compiler is using for optimization.
2526Higher levels correspond to higher accuracy (fewer false positives).
2527Higher levels also correspond to more effort, similar to the way -O works.
2528@option{-Wstrict-aliasing} is equivalent to @option{-Wstrict-aliasing=n},
2529with n=3.
2530
2531Level 1: Most aggressive, quick, least accurate.
2532Possibly useful when higher levels
2533do not warn but -fstrict-aliasing still breaks the code, as it has very few
2534false negatives. However, it has many false positives.
2535Warns for all pointer conversions between possibly incompatible types,
2536even if never dereferenced. Runs in the frontend only.
2537
2538Level 2: Aggressive, quick, not too precise.
2539May still have many false positives (not as many as level 1 though),
2540and few false negatives (but possibly more than level 1).
2541Unlike level 1, it only warns when an address is taken. Warns about
2542incomplete types. Runs in the frontend only.
2543
2544Level 3 (default for @option{-Wstrict-aliasing}):
2545Should have very few false positives and few false
2546negatives. Slightly slower than levels 1 or 2 when optimization is enabled.
2547Takes care of the common punn+dereference pattern in the frontend:
2548@code{*(int*)&some_float}.
2549If optimization is enabled, it also runs in the backend, where it deals
2550with multiple statement cases using flow-sensitive points-to information.
2551Only warns when the converted pointer is dereferenced.
2552Does not warn about incomplete types.
2553
2554@item -Wstrict-overflow
2555@item -Wstrict-overflow=@var{n}
2556@opindex Wstrict-overflow
2557This option is only active when @option{-fstrict-overflow} is active.
2558It warns about cases where the compiler optimizes based on the
2559assumption that signed overflow does not occur. Note that it does not
2560warn about all cases where the code might overflow: it only warns
2561about cases where the compiler implements some optimization. Thus
2562this warning depends on the optimization level.
2563
2564An optimization which assumes that signed overflow does not occur is
2565perfectly safe if the values of the variables involved are such that
2566overflow never does, in fact, occur. Therefore this warning can
2567easily give a false positive: a warning about code which is not
2568actually a problem. To help focus on important issues, several
2569warning levels are defined. No warnings are issued for the use of
2570undefined signed overflow when estimating how many iterations a loop
2571will require, in particular when determining whether a loop will be
2572executed at all.
2573
2574@table @option
2575@item -Wstrict-overflow=1
2576Warn about cases which are both questionable and easy to avoid. For
2577example: @code{x + 1 > x}; with @option{-fstrict-overflow}, the
2578compiler will simplify this to @code{1}. This level of
2579@option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
2580are not, and must be explicitly requested.
2581
2582@item -Wstrict-overflow=2
2583Also warn about other cases where a comparison is simplified to a
2584constant. For example: @code{abs (x) >= 0}. This can only be
2585simplified when @option{-fstrict-overflow} is in effect, because
2586@code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
2587zero. @option{-Wstrict-overflow} (with no level) is the same as
2588@option{-Wstrict-overflow=2}.
2589
2590@item -Wstrict-overflow=3
2591Also warn about other cases where a comparison is simplified. For
2592example: @code{x + 1 > 1} will be simplified to @code{x > 0}.
2593
2594@item -Wstrict-overflow=4
2595Also warn about other simplifications not covered by the above cases.
2596For example: @code{(x * 10) / 5} will be simplified to @code{x * 2}.
2597
2598@item -Wstrict-overflow=5
2599Also warn about cases where the compiler reduces the magnitude of a
2600constant involved in a comparison. For example: @code{x + 2 > y} will
2601be simplified to @code{x + 1 >= y}. This is reported only at the
2602highest warning level because this simplification applies to many
2603comparisons, so this warning level will give a very large number of
2604false positives.
2605@end table
2606
2607@item -Wall
2608@opindex Wall
2609All of the above @samp{-W} options combined. This enables all the
2610warnings about constructions that some users consider questionable, and
2611that are easy to avoid (or modify to prevent the warning), even in
2612conjunction with macros. This also enables some language-specific
2613warnings described in @ref{C++ Dialect Options}.
2614@end table
2615
2616The following @option{-W@dots{}} options are not implied by @option{-Wall}.
2617Some of them warn about constructions that users generally do not
2618consider questionable, but which occasionally you might wish to check
2619for; others warn about constructions that are necessary or hard to avoid
2620in some cases, and there is no simple way to modify the code to suppress
2621the warning.
2622
2623@table @gcctabopt
2624@item -Wextra
2625@opindex W
2626@opindex Wextra
2627(This option used to be called @option{-W}. The older name is still
2628supported, but the newer name is more descriptive.) Print extra warning
2629messages for these events:
2630
2631@itemize @bullet
2632@item
2633A function can return either with or without a value. (Falling
2634off the end of the function body is considered returning without
2635a value.) For example, this function would evoke such a
2636warning:
2637
2638@smallexample
2639@group
2640foo (a)
2641@{
2642 if (a > 0)
2643 return a;
2644@}
2645@end group
2646@end smallexample
2647
2648@item
2649An expression-statement or the left-hand side of a comma expression
2650contains no side effects.
2651To suppress the warning, cast the unused expression to void.
2652For example, an expression such as @samp{x[i,j]} will cause a warning,
2653but @samp{x[(void)i,j]} will not.
2654
2655@item
2656An unsigned value is compared against zero with @samp{<} or @samp{>=}.
2657
2658@item
2659Storage-class specifiers like @code{static} are not the first things in
2660a declaration. According to the C Standard, this usage is obsolescent.
2661
2662@item
2663If @option{-Wall} or @option{-Wunused} is also specified, warn about unused
2664arguments.
2665
2666@item
2667A comparison between signed and unsigned values could produce an
2668incorrect result when the signed value is converted to unsigned.
2669(But don't warn if @option{-Wno-sign-compare} is also specified.)
2670
2671@item
2672An aggregate has an initializer which does not initialize all members.
2673This warning can be independently controlled by
2674@option{-Wmissing-field-initializers}.
2675
2676@item
2677An initialized field without side effects is overridden when using
2678designated initializers (@pxref{Designated Inits, , Designated
2679Initializers}). This warning can be independently controlled by
2680@option{-Woverride-init}.
2681
2682@item
2683A function parameter is declared without a type specifier in K&R-style
2684functions:
2685
2686@smallexample
2687void foo(bar) @{ @}
2688@end smallexample
2689
2690@item
2691An empty body occurs in an @samp{if} or @samp{else} statement.
2692
2693@item
2694A pointer is compared against integer zero with @samp{<}, @samp{<=},
2695@samp{>}, or @samp{>=}.
2696
2697@item
2698A variable might be changed by @samp{longjmp} or @samp{vfork}.
2699
2700@item @r{(C++ only)}
2701An enumerator and a non-enumerator both appear in a conditional expression.
2702
2703@item @r{(C++ only)}
2704A non-static reference or non-static @samp{const} member appears in a
2705class without constructors.
2706
2707@item @r{(C++ only)}
2708Ambiguous virtual bases.
2709
2710@item @r{(C++ only)}
2711Subscripting an array which has been declared @samp{register}.
2712
2713@item @r{(C++ only)}
2714Taking the address of a variable which has been declared @samp{register}.
2715
2716@item @r{(C++ only)}
2717A base class is not initialized in a derived class' copy constructor.
2718@end itemize
2719
2720@item -Wno-div-by-zero
2721@opindex Wno-div-by-zero
2722@opindex Wdiv-by-zero
2723Do not warn about compile-time integer division by zero. Floating point
2724division by zero is not warned about, as it can be a legitimate way of
2725obtaining infinities and NaNs.
2726
2727@item -Wsystem-headers
2728@opindex Wsystem-headers
2729@cindex warnings from system headers
2730@cindex system headers, warnings from
2731Print warning messages for constructs found in system header files.
2732Warnings from system headers are normally suppressed, on the assumption
2733that they usually do not indicate real problems and would only make the
2734compiler output harder to read. Using this command line option tells
2735GCC to emit warnings from system headers as if they occurred in user
2736code. However, note that using @option{-Wall} in conjunction with this
2737option will @emph{not} warn about unknown pragmas in system
2738headers---for that, @option{-Wunknown-pragmas} must also be used.
2739
2740@item -Wfloat-equal
2741@opindex Wfloat-equal
2742Warn if floating point values are used in equality comparisons.
2743
2744The idea behind this is that sometimes it is convenient (for the
2745programmer) to consider floating-point values as approximations to
2746infinitely precise real numbers. If you are doing this, then you need
2747to compute (by analyzing the code, or in some other way) the maximum or
2748likely maximum error that the computation introduces, and allow for it
2749when performing comparisons (and when producing output, but that's a
2750different problem). In particular, instead of testing for equality, you
2751would check to see whether the two values have ranges that overlap; and
2752this is done with the relational operators, so equality comparisons are
2753probably mistaken.
2754
2755@item -Wtraditional @r{(C only)}
2756@opindex Wtraditional
2757Warn about certain constructs that behave differently in traditional and
2758ISO C@. Also warn about ISO C constructs that have no traditional C
2759equivalent, and/or problematic constructs which should be avoided.
2760
2761@itemize @bullet
2762@item
2763Macro parameters that appear within string literals in the macro body.
2764In traditional C macro replacement takes place within string literals,
2765but does not in ISO C@.
2766
2767@item
2768In traditional C, some preprocessor directives did not exist.
2769Traditional preprocessors would only consider a line to be a directive
2770if the @samp{#} appeared in column 1 on the line. Therefore
2771@option{-Wtraditional} warns about directives that traditional C
2772understands but would ignore because the @samp{#} does not appear as the
2773first character on the line. It also suggests you hide directives like
2774@samp{#pragma} not understood by traditional C by indenting them. Some
2775traditional implementations would not recognize @samp{#elif}, so it
2776suggests avoiding it altogether.
2777
2778@item
2779A function-like macro that appears without arguments.
2780
2781@item
2782The unary plus operator.
2783
2784@item
2785The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
2786constant suffixes. (Traditional C does support the @samp{L} suffix on integer
2787constants.) Note, these suffixes appear in macros defined in the system
2788headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
2789Use of these macros in user code might normally lead to spurious
2790warnings, however GCC's integrated preprocessor has enough context to
2791avoid warning in these cases.
2792
2793@item
2794A function declared external in one block and then used after the end of
2795the block.
2796
2797@item
2798A @code{switch} statement has an operand of type @code{long}.
2799
2800@item
2801A non-@code{static} function declaration follows a @code{static} one.
2802This construct is not accepted by some traditional C compilers.
2803
2804@item
2805The ISO type of an integer constant has a different width or
2806signedness from its traditional type. This warning is only issued if
2807the base of the constant is ten. I.e.@: hexadecimal or octal values, which
2808typically represent bit patterns, are not warned about.
2809
2810@item
2811Usage of ISO string concatenation is detected.
2812
2813@item
2814Initialization of automatic aggregates.
2815
2816@item
2817Identifier conflicts with labels. Traditional C lacks a separate
2818namespace for labels.
2819
2820@item
2821Initialization of unions. If the initializer is zero, the warning is
2822omitted. This is done under the assumption that the zero initializer in
2823user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
2824initializer warnings and relies on default initialization to zero in the
2825traditional C case.
2826
2827@item
2828Conversions by prototypes between fixed/floating point values and vice
2829versa. The absence of these prototypes when compiling with traditional
2830C would cause serious problems. This is a subset of the possible
2831conversion warnings, for the full set use @option{-Wconversion}.
2832
2833@item
2834Use of ISO C style function definitions. This warning intentionally is
2835@emph{not} issued for prototype declarations or variadic functions
2836because these ISO C features will appear in your code when using
2837libiberty's traditional C compatibility macros, @code{PARAMS} and
2838@code{VPARAMS}. This warning is also bypassed for nested functions
2839because that feature is already a GCC extension and thus not relevant to
2840traditional C compatibility.
2841@end itemize
2842
2843@item -Wdeclaration-after-statement @r{(C only)}
2844@opindex Wdeclaration-after-statement
2845Warn when a declaration is found after a statement in a block. This
2846construct, known from C++, was introduced with ISO C99 and is by default
2847allowed in GCC@. It is not supported by ISO C90 and was not supported by
2848GCC versions before GCC 3.0. @xref{Mixed Declarations}.
2849
2850@item -Wundef
2851@opindex Wundef
2852Warn if an undefined identifier is evaluated in an @samp{#if} directive.
2853
2854@item -Wno-endif-labels
2855@opindex Wno-endif-labels
2856@opindex Wendif-labels
2857Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
2858
2859@item -Wshadow
2860@opindex Wshadow
2861Warn whenever a local variable shadows another local variable, parameter or
2862global variable or whenever a built-in function is shadowed.
2863
2864@item -Wlarger-than-@var{len}
2865@opindex Wlarger-than
2866Warn whenever an object of larger than @var{len} bytes is defined.
2867
2868@item -Wframe-larger-than-@var{len}
2869@opindex Wframe-larger-than
2870Warn whenever the frame size of a function is larger than @var{len} bytes.
2871
2872@item -Wunsafe-loop-optimizations
2873@opindex Wunsafe-loop-optimizations
2874Warn if the loop cannot be optimized because the compiler could not
2875assume anything on the bounds of the loop indices. With
2876@option{-funsafe-loop-optimizations} warn if the compiler made
2877such assumptions.
2878
2879@item -Wpointer-arith
2880@opindex Wpointer-arith
2881Warn about anything that depends on the ``size of'' a function type or
2882of @code{void}. GNU C assigns these types a size of 1, for
2883convenience in calculations with @code{void *} pointers and pointers
2884to functions.
2885
2886@item -Wbad-function-cast @r{(C only)}
2887@opindex Wbad-function-cast
2888Warn whenever a function call is cast to a non-matching type.
2889For example, warn if @code{int malloc()} is cast to @code{anything *}.
2890
2891@item -Wc++-compat
2892Warn about ISO C constructs that are outside of the common subset of
2893ISO C and ISO C++, e.g.@: request for implicit conversion from
2894@code{void *} to a pointer to non-@code{void} type.
2895
2896@item -Wcast-qual
2897@opindex Wcast-qual
2898Warn whenever a pointer is cast so as to remove a type qualifier from
2899the target type. For example, warn if a @code{const char *} is cast
2900to an ordinary @code{char *}.
2901
2902@item -Wcast-align
2903@opindex Wcast-align
2904Warn whenever a pointer is cast such that the required alignment of the
2905target is increased. For example, warn if a @code{char *} is cast to
2906an @code{int *} on machines where integers can only be accessed at
2907two- or four-byte boundaries.
2908
2909@item -Wwrite-strings
2910@opindex Wwrite-strings
2911When compiling C, give string constants the type @code{const
2912char[@var{length}]} so that
2913copying the address of one into a non-@code{const} @code{char *}
2914pointer will get a warning; when compiling C++, warn about the
2915deprecated conversion from string literals to @code{char *}. This
2916warning, by default, is enabled for C++ programs.
2917These warnings will help you find at
2918compile time code that can try to write into a string constant, but
2919only if you have been very careful about using @code{const} in
2920declarations and prototypes. Otherwise, it will just be a nuisance;
2921this is why we did not make @option{-Wall} request these warnings.
2922
2923@item -Wconversion
2924@opindex Wconversion
2925Warn if a prototype causes a type conversion that is different from what
2926would happen to the same argument in the absence of a prototype. This
2927includes conversions of fixed point to floating and vice versa, and
2928conversions changing the width or signedness of a fixed point argument
2929except when the same as the default promotion.
2930
2931Also, warn if a negative integer constant expression is implicitly
2932converted to an unsigned type. For example, warn about the assignment
2933@code{x = -1} if @code{x} is unsigned. But do not warn about explicit
2934casts like @code{(unsigned) -1}.
2935
2936@item -Wsign-compare
2937@opindex Wsign-compare
2938@cindex warning for comparison of signed and unsigned values
2939@cindex comparison of signed and unsigned values, warning
2940@cindex signed and unsigned values, comparison warning
2941Warn when a comparison between signed and unsigned values could produce
2942an incorrect result when the signed value is converted to unsigned.
2943This warning is also enabled by @option{-Wextra}; to get the other warnings
2944of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
2945
2946@item -Waddress
2947@opindex Waddress
2948@opindex Wno-address
2949Warn about suspicious uses of memory addresses. These include using
2950the address of a function in a conditional expression, such as
2951@code{void func(void); if (func)}, and comparisons against the memory
2952address of a string literal, such as @code{if (x == "abc")}. Such
2953uses typically indicate a programmer error: the address of a function
2954always evaluates to true, so their use in a conditional usually
2955indicate that the programmer forgot the parentheses in a function
2956call; and comparisons against string literals result in unspecified
2957behavior and are not portable in C, so they usually indicate that the
2958programmer intended to use @code{strcmp}. This warning is enabled by
2959@option{-Wall}.
2960
2961@item -Waggregate-return
2962@opindex Waggregate-return
2963Warn if any functions that return structures or unions are defined or
2964called. (In languages where you can return an array, this also elicits
2965a warning.)
2966
2967@item -Wno-attributes
2968@opindex Wno-attributes
2969@opindex Wattributes
2970Do not warn if an unexpected @code{__attribute__} is used, such as
2971unrecognized attributes, function attributes applied to variables,
2972etc. This will not stop errors for incorrect use of supported
2973attributes.
2974
2975@item -Wstrict-prototypes @r{(C only)}
2976@opindex Wstrict-prototypes
2977Warn if a function is declared or defined without specifying the
2978argument types. (An old-style function definition is permitted without
2979a warning if preceded by a declaration which specifies the argument
2980types.)
2981
2982@item -Wold-style-definition @r{(C only)}
2983@opindex Wold-style-definition
2984Warn if an old-style function definition is used. A warning is given
2985even if there is a previous prototype.
2986
2987@item -Wmissing-prototypes @r{(C only)}
2988@opindex Wmissing-prototypes
2989Warn if a global function is defined without a previous prototype
2990declaration. This warning is issued even if the definition itself
2991provides a prototype. The aim is to detect global functions that fail
2992to be declared in header files.
2993
2994@item -Wmissing-declarations @r{(C only)}
2995@opindex Wmissing-declarations
2996Warn if a global function is defined without a previous declaration.
2997Do so even if the definition itself provides a prototype.
2998Use this option to detect global functions that are not declared in
2999header files.
3000
3001@item -Wmissing-field-initializers
3002@opindex Wmissing-field-initializers
3003@opindex W
3004@opindex Wextra
3005Warn if a structure's initializer has some fields missing. For
3006example, the following code would cause such a warning, because
3007@code{x.h} is implicitly zero:
3008
3009@smallexample
3010struct s @{ int f, g, h; @};
3011struct s x = @{ 3, 4 @};
3012@end smallexample
3013
3014This option does not warn about designated initializers, so the following
3015modification would not trigger a warning:
3016
3017@smallexample
3018struct s @{ int f, g, h; @};
3019struct s x = @{ .f = 3, .g = 4 @};
3020@end smallexample
3021
3022This warning is included in @option{-Wextra}. To get other @option{-Wextra}
3023warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
3024
3025@item -Wmissing-noreturn
3026@opindex Wmissing-noreturn
3027Warn about functions which might be candidates for attribute @code{noreturn}.
3028Note these are only possible candidates, not absolute ones. Care should
3029be taken to manually verify functions actually do not ever return before
3030adding the @code{noreturn} attribute, otherwise subtle code generation
3031bugs could be introduced. You will not get a warning for @code{main} in
3032hosted C environments.
3033
3034@item -Wmissing-format-attribute
3035@opindex Wmissing-format-attribute
3036@opindex Wformat
3037Warn about function pointers which might be candidates for @code{format}
3038attributes. Note these are only possible candidates, not absolute ones.
3039GCC will guess that function pointers with @code{format} attributes that
3040are used in assignment, initialization, parameter passing or return
3041statements should have a corresponding @code{format} attribute in the
3042resulting type. I.e.@: the left-hand side of the assignment or
3043initialization, the type of the parameter variable, or the return type
3044of the containing function respectively should also have a @code{format}
3045attribute to avoid the warning.
3046
3047GCC will also warn about function definitions which might be
3048candidates for @code{format} attributes. Again, these are only
3049possible candidates. GCC will guess that @code{format} attributes
3050might be appropriate for any function that calls a function like
3051@code{vprintf} or @code{vscanf}, but this might not always be the
3052case, and some functions for which @code{format} attributes are
3053appropriate may not be detected.
3054
3055@item -Wno-multichar
3056@opindex Wno-multichar
3057@opindex Wmultichar
3058Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
3059Usually they indicate a typo in the user's code, as they have
3060implementation-defined values, and should not be used in portable code.
3061
3062@item -Wnormalized=<none|id|nfc|nfkc>
3063@opindex Wnormalized
3064@cindex NFC
3065@cindex NFKC
3066@cindex character set, input normalization
3067In ISO C and ISO C++, two identifiers are different if they are
3068different sequences of characters. However, sometimes when characters
3069outside the basic ASCII character set are used, you can have two
3070different character sequences that look the same. To avoid confusion,
3071the ISO 10646 standard sets out some @dfn{normalization rules} which
3072when applied ensure that two sequences that look the same are turned into
3073the same sequence. GCC can warn you if you are using identifiers which
3074have not been normalized; this option controls that warning.
3075
3076There are four levels of warning that GCC supports. The default is
3077@option{-Wnormalized=nfc}, which warns about any identifier which is
3078not in the ISO 10646 ``C'' normalized form, @dfn{NFC}. NFC is the
3079recommended form for most uses.
3080
3081Unfortunately, there are some characters which ISO C and ISO C++ allow
3082in identifiers that when turned into NFC aren't allowable as
3083identifiers. That is, there's no way to use these symbols in portable
3084ISO C or C++ and have all your identifiers in NFC.
3085@option{-Wnormalized=id} suppresses the warning for these characters.
3086It is hoped that future versions of the standards involved will correct
3087this, which is why this option is not the default.
3088
3089You can switch the warning off for all characters by writing
3090@option{-Wnormalized=none}. You would only want to do this if you
3091were using some other normalization scheme (like ``D''), because
3092otherwise you can easily create bugs that are literally impossible to see.
3093
3094Some characters in ISO 10646 have distinct meanings but look identical
3095in some fonts or display methodologies, especially once formatting has
3096been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
3097LETTER N'', will display just like a regular @code{n} which has been
3098placed in a superscript. ISO 10646 defines the @dfn{NFKC}
3099normalization scheme to convert all these into a standard form as
3100well, and GCC will warn if your code is not in NFKC if you use
3101@option{-Wnormalized=nfkc}. This warning is comparable to warning
3102about every identifier that contains the letter O because it might be
3103confused with the digit 0, and so is not the default, but may be
3104useful as a local coding convention if the programming environment is
3105unable to be fixed to display these characters distinctly.
3106
3107@item -Wno-deprecated-declarations
3108@opindex Wno-deprecated-declarations
3109Do not warn about uses of functions (@pxref{Function Attributes}),
3110variables (@pxref{Variable Attributes}), and types (@pxref{Type
3111Attributes}) marked as deprecated by using the @code{deprecated}
3112attribute.
3113
3114@item -Wno-overflow
3115@opindex Wno-overflow
3116Do not warn about compile-time overflow in constant expressions.
3117
3118@item -Woverride-init
3119@opindex Woverride-init
3120@opindex W
3121@opindex Wextra
3122Warn if an initialized field without side effects is overridden when
3123using designated initializers (@pxref{Designated Inits, , Designated
3124Initializers}).
3125
3126This warning is included in @option{-Wextra}. To get other
3127@option{-Wextra} warnings without this one, use @samp{-Wextra
3128-Wno-override-init}.
3129
3130@item -Wpacked
3131@opindex Wpacked
3132Warn if a structure is given the packed attribute, but the packed
3133attribute has no effect on the layout or size of the structure.
3134Such structures may be mis-aligned for little benefit. For
3135instance, in this code, the variable @code{f.x} in @code{struct bar}
3136will be misaligned even though @code{struct bar} does not itself
3137have the packed attribute:
3138
3139@smallexample
3140@group
3141struct foo @{
3142 int x;
3143 char a, b, c, d;
3144@} __attribute__((packed));
3145struct bar @{
3146 char z;
3147 struct foo f;
3148@};
3149@end group
3150@end smallexample
3151
3152@item -Wpadded
3153@opindex Wpadded
3154Warn if padding is included in a structure, either to align an element
3155of the structure or to align the whole structure. Sometimes when this
3156happens it is possible to rearrange the fields of the structure to
3157reduce the padding and so make the structure smaller.
3158
3159@item -Wredundant-decls
3160@opindex Wredundant-decls
3161Warn if anything is declared more than once in the same scope, even in
3162cases where multiple declaration is valid and changes nothing.
3163
3164@item -Wnested-externs @r{(C only)}
3165@opindex Wnested-externs
3166Warn if an @code{extern} declaration is encountered within a function.
3167
3168@item -Wunreachable-code
3169@opindex Wunreachable-code
3170Warn if the compiler detects that code will never be executed.
3171
3172This option is intended to warn when the compiler detects that at
3173least a whole line of source code will never be executed, because
3174some condition is never satisfied or because it is after a
3175procedure that never returns.
3176
3177It is possible for this option to produce a warning even though there
3178are circumstances under which part of the affected line can be executed,
3179so care should be taken when removing apparently-unreachable code.
3180
3181For instance, when a function is inlined, a warning may mean that the
3182line is unreachable in only one inlined copy of the function.
3183
3184This option is not made part of @option{-Wall} because in a debugging
3185version of a program there is often substantial code which checks
3186correct functioning of the program and is, hopefully, unreachable
3187because the program does work. Another common use of unreachable
3188code is to provide behavior which is selectable at compile-time.
3189
3190@item -Winline
3191@opindex Winline
3192Warn if a function can not be inlined and it was declared as inline.
3193Even with this option, the compiler will not warn about failures to
3194inline functions declared in system headers.
3195
3196The compiler uses a variety of heuristics to determine whether or not
3197to inline a function. For example, the compiler takes into account
3198the size of the function being inlined and the amount of inlining
3199that has already been done in the current function. Therefore,
3200seemingly insignificant changes in the source program can cause the
3201warnings produced by @option{-Winline} to appear or disappear.
3202
3203@item -Wno-invalid-offsetof @r{(C++ only)}
3204@opindex Wno-invalid-offsetof
3205Suppress warnings from applying the @samp{offsetof} macro to a non-POD
3206type. According to the 1998 ISO C++ standard, applying @samp{offsetof}
3207to a non-POD type is undefined. In existing C++ implementations,
3208however, @samp{offsetof} typically gives meaningful results even when
3209applied to certain kinds of non-POD types. (Such as a simple
3210@samp{struct} that fails to be a POD type only by virtue of having a
3211constructor.) This flag is for users who are aware that they are
3212writing nonportable code and who have deliberately chosen to ignore the
3213warning about it.
3214
3215The restrictions on @samp{offsetof} may be relaxed in a future version
3216of the C++ standard.
3217
3218@item -Wno-int-to-pointer-cast @r{(C only)}
3219@opindex Wno-int-to-pointer-cast
3220Suppress warnings from casts to pointer type of an integer of a
3221different size.
3222
3223@item -Wno-pointer-to-int-cast @r{(C only)}
3224@opindex Wno-pointer-to-int-cast
3225Suppress warnings from casts from a pointer to an integer type of a
3226different size.
3227
3228@item -Winvalid-pch
3229@opindex Winvalid-pch
3230Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
3231the search path but can't be used.
3232
3233@item -Wlong-long
3234@opindex Wlong-long
3235@opindex Wno-long-long
3236Warn if @samp{long long} type is used. This is default. To inhibit
3237the warning messages, use @option{-Wno-long-long}. Flags
3238@option{-Wlong-long} and @option{-Wno-long-long} are taken into account
3239only when @option{-pedantic} flag is used.
3240
3241@item -Wvariadic-macros
3242@opindex Wvariadic-macros
3243@opindex Wno-variadic-macros
3244Warn if variadic macros are used in pedantic ISO C90 mode, or the GNU
3245alternate syntax when in pedantic ISO C99 mode. This is default.
3246To inhibit the warning messages, use @option{-Wno-variadic-macros}.
3247
3248@item -Wvla
3249@opindex Wvla
3250@opindex Wno-vla
3251Warn if variable length array is used in the code.
3252@option{-Wno-vla} will prevent the @option{-pedantic} warning of
3253the variable length array.
3254
3255@item -Wvolatile-register-var
3256@opindex Wvolatile-register-var
3257@opindex Wno-volatile-register-var
3258Warn if a register variable is declared volatile. The volatile
3259modifier does not inhibit all optimizations that may eliminate reads
3260and/or writes to register variables.
3261
3262@item -Wdisabled-optimization
3263@opindex Wdisabled-optimization
3264Warn if a requested optimization pass is disabled. This warning does
3265not generally indicate that there is anything wrong with your code; it
3266merely indicates that GCC's optimizers were unable to handle the code
3267effectively. Often, the problem is that your code is too big or too
3268complex; GCC will refuse to optimize programs when the optimization
3269itself is likely to take inordinate amounts of time.
3270
3271@item -Wpointer-sign
3272@opindex Wpointer-sign
3273@opindex Wno-pointer-sign
3274Warn for pointer argument passing or assignment with different signedness.
3275This option is only supported for C. It is implied by @option{-Wall}
3276and by @option{-pedantic}, which can be disabled with
3277@option{-Wno-pointer-sign}.
3278
3279@item -Werror
3280@opindex Werror
3281Make all warnings into errors.
3282
3283@item -Werror=
3284@opindex Werror=
3285Make the specified warning into an errors. The specifier for a
3286warning is appended, for example @option{-Werror=switch} turns the
3287warnings controlled by @option{-Wswitch} into errors. This switch
3288takes a negative form, to be used to negate @option{-Werror} for
3289specific warnings, for example @option{-Wno-error=switch} makes
3290@option{-Wswitch} warnings not be errors, even when @option{-Werror}
3291is in effect. You can use the @option{-fdiagnostics-show-option}
3292option to have each controllable warning amended with the option which
3293controls it, to determine what to use with this option.
3294
3295Note that specifying @option{-Werror=}@var{foo} automatically implies
3296@option{-W}@var{foo}. However, @option{-Wno-error=}@var{foo} does not
3297imply anything.
3298
3299@item -Wstack-protector
3300@opindex Wstack-protector
3301This option is only active when @option{-fstack-protector} is active. It
3302warns about functions that will not be protected against stack smashing.
3303
3304@item -Woverlength-strings
3305@opindex Woverlength-strings
3306Warn about string constants which are longer than the ``minimum
3307maximum'' length specified in the C standard. Modern compilers
3308generally allow string constants which are much longer than the
3309standard's minimum limit, but very portable programs should avoid
3310using longer strings.
3311
3312The limit applies @emph{after} string constant concatenation, and does
3313not count the trailing NUL@. In C89, the limit was 509 characters; in
3314C99, it was raised to 4095. C++98 does not specify a normative
3315minimum maximum, so we do not diagnose overlength strings in C++@.
3316
3317This option is implied by @option{-pedantic}, and can be disabled with
3318@option{-Wno-overlength-strings}.
3319@end table
3320
3321@node Debugging Options
3322@section Options for Debugging Your Program or GCC
3323@cindex options, debugging
3324@cindex debugging information options
3325
3326GCC has various special options that are used for debugging
3327either your program or GCC:
3328
3329@table @gcctabopt
3330@item -g
3331@opindex g
3332Produce debugging information in the operating system's native format
3333(stabs, COFF, XCOFF, or DWARF 2)@. GDB can work with this debugging
3334information.
3335
3336On most systems that use stabs format, @option{-g} enables use of extra
3337debugging information that only GDB can use; this extra information
3338makes debugging work better in GDB but will probably make other debuggers
3339crash or
3340refuse to read the program. If you want to control for certain whether
3341to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
3342@option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
3343
3344GCC allows you to use @option{-g} with
3345@option{-O}. The shortcuts taken by optimized code may occasionally
3346produce surprising results: some variables you declared may not exist
3347at all; flow of control may briefly move where you did not expect it;
3348some statements may not be executed because they compute constant
3349results or their values were already at hand; some statements may
3350execute in different places because they were moved out of loops.
3351
3352Nevertheless it proves possible to debug optimized output. This makes
3353it reasonable to use the optimizer for programs that might have bugs.
3354
3355The following options are useful when GCC is generated with the
3356capability for more than one debugging format.
3357
3358@item -ggdb
3359@opindex ggdb
3360Produce debugging information for use by GDB@. This means to use the
3361most expressive format available (DWARF 2, stabs, or the native format
3362if neither of those are supported), including GDB extensions if at all
3363possible.
3364
3365@item -gstabs
3366@opindex gstabs
3367Produce debugging information in stabs format (if that is supported),
3368without GDB extensions. This is the format used by DBX on most BSD
3369systems. On MIPS, Alpha and System V Release 4 systems this option
3370produces stabs debugging output which is not understood by DBX or SDB@.
3371On System V Release 4 systems this option requires the GNU assembler.
3372
3373@item -feliminate-unused-debug-symbols
3374@opindex feliminate-unused-debug-symbols
3375Produce debugging information in stabs format (if that is supported),
3376for only symbols that are actually used.
3377
3378@item -femit-class-debug-always
3379Instead of emitting debugging information for a C++ class in only one
3380object file, emit it in all object files using the class. This option
3381should be used only with debuggers that are unable to handle the way GCC
3382normally emits debugging information for classes because using this
3383option will increase the size of debugging information by as much as a
3384factor of two.
3385
3386@item -gstabs+
3387@opindex gstabs+
3388Produce debugging information in stabs format (if that is supported),
3389using GNU extensions understood only by the GNU debugger (GDB)@. The
3390use of these extensions is likely to make other debuggers crash or
3391refuse to read the program.
3392
3393@item -gcoff
3394@opindex gcoff
3395Produce debugging information in COFF format (if that is supported).
3396This is the format used by SDB on most System V systems prior to
3397System V Release 4.
3398
3399@item -gxcoff
3400@opindex gxcoff
3401Produce debugging information in XCOFF format (if that is supported).
3402This is the format used by the DBX debugger on IBM RS/6000 systems.
3403
3404@item -gxcoff+
3405@opindex gxcoff+
3406Produce debugging information in XCOFF format (if that is supported),
3407using GNU extensions understood only by the GNU debugger (GDB)@. The
3408use of these extensions is likely to make other debuggers crash or
3409refuse to read the program, and may cause assemblers other than the GNU
3410assembler (GAS) to fail with an error.
3411
3412@item -gdwarf-2
3413@opindex gdwarf-2
3414Produce debugging information in DWARF version 2 format (if that is
3415supported). This is the format used by DBX on IRIX 6. With this
3416option, GCC uses features of DWARF version 3 when they are useful;
3417version 3 is upward compatible with version 2, but may still cause
3418problems for older debuggers.
3419
3420@item -gvms
3421@opindex gvms
3422Produce debugging information in VMS debug format (if that is
3423supported). This is the format used by DEBUG on VMS systems.
3424
3425@item -g@var{level}
3426@itemx -ggdb@var{level}
3427@itemx -gstabs@var{level}
3428@itemx -gcoff@var{level}
3429@itemx -gxcoff@var{level}
3430@itemx -gvms@var{level}
3431Request debugging information and also use @var{level} to specify how
3432much information. The default level is 2.
3433
3434Level 1 produces minimal information, enough for making backtraces in
3435parts of the program that you don't plan to debug. This includes
3436descriptions of functions and external variables, but no information
3437about local variables and no line numbers.
3438
3439Level 3 includes extra information, such as all the macro definitions
3440present in the program. Some debuggers support macro expansion when
3441you use @option{-g3}.
3442
3443@option{-gdwarf-2} does not accept a concatenated debug level, because
3444GCC used to support an option @option{-gdwarf} that meant to generate
3445debug information in version 1 of the DWARF format (which is very
3446different from version 2), and it would have been too confusing. That
3447debug format is long obsolete, but the option cannot be changed now.
3448Instead use an additional @option{-g@var{level}} option to change the
3449debug level for DWARF2.
3450
3451@item -feliminate-dwarf2-dups
3452@opindex feliminate-dwarf2-dups
3453Compress DWARF2 debugging information by eliminating duplicated
3454information about each symbol. This option only makes sense when
3455generating DWARF2 debugging information with @option{-gdwarf-2}.
3456
3457@item -femit-struct-debug-baseonly
3458Emit debug information for struct-like types
3459only when the base name of the compilation source file
3460matches the base name of file in which the struct was defined.
3461
3462This option substantially reduces the size of debugging information,
3463but at significant potential loss in type information to the debugger.
3464See @option{-femit-struct-debug-reduced} for a less aggressive option.
3465See @option{-femit-struct-debug-detailed} for more detailed control.
3466
3467This option works only with DWARF 2.
3468
3469@item -femit-struct-debug-reduced
3470Emit debug information for struct-like types
3471only when the base name of the compilation source file
3472matches the base name of file in which the type was defined,
3473unless the struct is a template or defined in a system header.
3474
3475This option significantly reduces the size of debugging information,
3476with some potential loss in type information to the debugger.
3477See @option{-femit-struct-debug-baseonly} for a more aggressive option.
3478See @option{-femit-struct-debug-detailed} for more detailed control.
3479
3480This option works only with DWARF 2.
3481
3482@item -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]}
3483Specify the struct-like types
3484for which the compiler will generate debug information.
3485The intent is to reduce duplicate struct debug information
3486between different object files within the same program.
3487
3488This option is a detailed version of
3489@option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly},
3490which will serve for most needs.
3491
3492A specification has the syntax
3493[@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none})
3494
3495The optional first word limits the specification to
3496structs that are used directly (@samp{dir:}) or used indirectly (@samp{ind:}).
3497A struct type is used directly when it is the type of a variable, member.
3498Indirect uses arise through pointers to structs.
3499That is, when use of an incomplete struct would be legal, the use is indirect.
3500An example is
3501@samp{struct one direct; struct two * indirect;}.
3502
3503The optional second word limits the specification to
3504ordinary structs (@samp{ord:}) or generic structs (@samp{gen:}).
3505Generic structs are a bit complicated to explain.
3506For C++, these are non-explicit specializations of template classes,
3507or non-template classes within the above.
3508Other programming languages have generics,
3509but @samp{-femit-struct-debug-detailed} does not yet implement them.
3510
3511The third word specifies the source files for those
3512structs for which the compiler will emit debug information.
3513The values @samp{none} and @samp{any} have the normal meaning.
3514The value @samp{base} means that
3515the base of name of the file in which the type declaration appears
3516must match the base of the name of the main compilation file.
3517In practice, this means that
3518types declared in @file{foo.c} and @file{foo.h} will have debug information,
3519but types declared in other header will not.
3520The value @samp{sys} means those types satisfying @samp{base}
3521or declared in system or compiler headers.
3522
3523You may need to experiment to determine the best settings for your application.
3524
3525The default is @samp{-femit-struct-debug-detailed=all}.
3526
3527This option works only with DWARF 2.
3528
3529@cindex @command{prof}
3530@item -p
3531@opindex p
3532Generate extra code to write profile information suitable for the
3533analysis program @command{prof}. You must use this option when compiling
3534the source files you want data about, and you must also use it when
3535linking.
3536
3537@cindex @command{gprof}
3538@item -pg
3539@opindex pg
3540Generate extra code to write profile information suitable for the
3541analysis program @command{gprof}. You must use this option when compiling
3542the source files you want data about, and you must also use it when
3543linking.
3544
3545@item -Q
3546@opindex Q
3547Makes the compiler print out each function name as it is compiled, and
3548print some statistics about each pass when it finishes.
3549
3550@item -ftime-report
3551@opindex ftime-report
3552Makes the compiler print some statistics about the time consumed by each
3553pass when it finishes.
3554
3555@item -fmem-report
3556@opindex fmem-report
3557Makes the compiler print some statistics about permanent memory
3558allocation when it finishes.
3559
3560@item -fprofile-arcs
3561@opindex fprofile-arcs
3562Add code so that program flow @dfn{arcs} are instrumented. During
3563execution the program records how many times each branch and call is
3564executed and how many times it is taken or returns. When the compiled
3565program exits it saves this data to a file called
3566@file{@var{auxname}.gcda} for each source file. The data may be used for
3567profile-directed optimizations (@option{-fbranch-probabilities}), or for
3568test coverage analysis (@option{-ftest-coverage}). Each object file's
3569@var{auxname} is generated from the name of the output file, if
3570explicitly specified and it is not the final executable, otherwise it is
3571the basename of the source file. In both cases any suffix is removed
3572(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
3573@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
3574@xref{Cross-profiling}.
3575
3576@cindex @command{gcov}
3577@item --coverage
3578@opindex coverage
3579
3580This option is used to compile and link code instrumented for coverage
3581analysis. The option is a synonym for @option{-fprofile-arcs}
3582@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
3583linking). See the documentation for those options for more details.
3584
3585@itemize
3586
3587@item
3588Compile the source files with @option{-fprofile-arcs} plus optimization
3589and code generation options. For test coverage analysis, use the
3590additional @option{-ftest-coverage} option. You do not need to profile
3591every source file in a program.
3592
3593@item
3594Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
3595(the latter implies the former).
3596
3597@item
3598Run the program on a representative workload to generate the arc profile
3599information. This may be repeated any number of times. You can run
3600concurrent instances of your program, and provided that the file system
3601supports locking, the data files will be correctly updated. Also
3602@code{fork} calls are detected and correctly handled (double counting
3603will not happen).
3604
3605@item
3606For profile-directed optimizations, compile the source files again with
3607the same optimization and code generation options plus
3608@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
3609Control Optimization}).
3610
3611@item
3612For test coverage analysis, use @command{gcov} to produce human readable
3613information from the @file{.gcno} and @file{.gcda} files. Refer to the
3614@command{gcov} documentation for further information.
3615
3616@end itemize
3617
3618With @option{-fprofile-arcs}, for each function of your program GCC
3619creates a program flow graph, then finds a spanning tree for the graph.
3620Only arcs that are not on the spanning tree have to be instrumented: the
3621compiler adds code to count the number of times that these arcs are
3622executed. When an arc is the only exit or only entrance to a block, the
3623instrumentation code can be added to the block; otherwise, a new basic
3624block must be created to hold the instrumentation code.
3625
3626@need 2000
3627@item -ftest-coverage
3628@opindex ftest-coverage
3629Produce a notes file that the @command{gcov} code-coverage utility
3630(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
3631show program coverage. Each source file's note file is called
3632@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
3633above for a description of @var{auxname} and instructions on how to
3634generate test coverage data. Coverage data will match the source files
3635more closely, if you do not optimize.
3636
3637@item -d@var{letters}
3638@item -fdump-rtl-@var{pass}
3639@opindex d
3640Says to make debugging dumps during compilation at times specified by
3641@var{letters}. This is used for debugging the RTL-based passes of the
3642compiler. The file names for most of the dumps are made by appending a
3643pass number and a word to the @var{dumpname}. @var{dumpname} is generated
3644from the name of the output file, if explicitly specified and it is not
3645an executable, otherwise it is the basename of the source file.
3646
3647Most debug dumps can be enabled either passing a letter to the @option{-d}
3648option, or with a long @option{-fdump-rtl} switch; here are the possible
3649letters for use in @var{letters} and @var{pass}, and their meanings:
3650
3651@table @gcctabopt
3652@item -dA
3653@opindex dA
3654Annotate the assembler output with miscellaneous debugging information.
3655
3656@item -dB
3657@itemx -fdump-rtl-bbro
3658@opindex dB
3659@opindex fdump-rtl-bbro
3660Dump after block reordering, to @file{@var{file}.148r.bbro}.
3661
3662@item -dc
3663@itemx -fdump-rtl-combine
3664@opindex dc
3665@opindex fdump-rtl-combine
3666Dump after instruction combination, to the file @file{@var{file}.129r.combine}.
3667
3668@item -dC
3669@itemx -fdump-rtl-ce1
3670@itemx -fdump-rtl-ce2
3671@opindex dC
3672@opindex fdump-rtl-ce1
3673@opindex fdump-rtl-ce2
3674@option{-dC} and @option{-fdump-rtl-ce1} enable dumping after the
3675first if conversion, to the file @file{@var{file}.117r.ce1}. @option{-dC}
3676and @option{-fdump-rtl-ce2} enable dumping after the second if
3677conversion, to the file @file{@var{file}.130r.ce2}.
3678
3679@item -dd
3680@itemx -fdump-rtl-btl
3681@itemx -fdump-rtl-dbr
3682@opindex dd
3683@opindex fdump-rtl-btl
3684@opindex fdump-rtl-dbr
3685@option{-dd} and @option{-fdump-rtl-btl} enable dumping after branch
3686target load optimization, to @file{@var{file}.31.btl}. @option{-dd}
3687and @option{-fdump-rtl-dbr} enable dumping after delayed branch
3688scheduling, to @file{@var{file}.36.dbr}.
3689
3690@item -dD
3691@opindex dD
3692Dump all macro definitions, at the end of preprocessing, in addition to
3693normal output.
3694
3695@item -dE
3696@itemx -fdump-rtl-ce3
3697@opindex dE
3698@opindex fdump-rtl-ce3
3699Dump after the third if conversion, to @file{@var{file}.146r.ce3}.
3700
3701@item -df
3702@itemx -fdump-rtl-cfg
3703@itemx -fdump-rtl-life
3704@opindex df
3705@opindex fdump-rtl-cfg
3706@opindex fdump-rtl-life
3707@option{-df} and @option{-fdump-rtl-cfg} enable dumping after control
3708and data flow analysis, to @file{@var{file}.116r.cfg}. @option{-df}
3709and @option{-fdump-rtl-cfg} enable dumping dump after life analysis,
3710to @file{@var{file}.128r.life1} and @file{@var{file}.135r.life2}.
3711
3712@item -dg
3713@itemx -fdump-rtl-greg
3714@opindex dg
3715@opindex fdump-rtl-greg
3716Dump after global register allocation, to @file{@var{file}.139r.greg}.
3717
3718@item -dG
3719@itemx -fdump-rtl-gcse
3720@itemx -fdump-rtl-bypass
3721@opindex dG
3722@opindex fdump-rtl-gcse
3723@opindex fdump-rtl-bypass
3724@option{-dG} and @option{-fdump-rtl-gcse} enable dumping after GCSE, to
3725@file{@var{file}.114r.gcse}. @option{-dG} and @option{-fdump-rtl-bypass}
3726enable dumping after jump bypassing and control flow optimizations, to
3727@file{@var{file}.115r.bypass}.
3728
3729@item -dh
3730@itemx -fdump-rtl-eh
3731@opindex dh
3732@opindex fdump-rtl-eh
3733Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
3734
3735@item -di
3736@itemx -fdump-rtl-sibling
3737@opindex di
3738@opindex fdump-rtl-sibling
3739Dump after sibling call optimizations, to @file{@var{file}.106r.sibling}.
3740
3741@item -dj
3742@itemx -fdump-rtl-jump
3743@opindex dj
3744@opindex fdump-rtl-jump
3745Dump after the first jump optimization, to @file{@var{file}.112r.jump}.
3746
3747@item -dk
3748@itemx -fdump-rtl-stack
3749@opindex dk
3750@opindex fdump-rtl-stack
3751Dump after conversion from registers to stack, to @file{@var{file}.152r.stack}.
3752
3753@item -dl
3754@itemx -fdump-rtl-lreg
3755@opindex dl
3756@opindex fdump-rtl-lreg
3757Dump after local register allocation, to @file{@var{file}.138r.lreg}.
3758
3759@item -dL
3760@itemx -fdump-rtl-loop2
3761@opindex dL
3762@opindex fdump-rtl-loop2
3763@option{-dL} and @option{-fdump-rtl-loop2} enable dumping after the
3764loop optimization pass, to @file{@var{file}.119r.loop2},
3765@file{@var{file}.120r.loop2_init},
3766@file{@var{file}.121r.loop2_invariant}, and
3767@file{@var{file}.125r.loop2_done}.
3768
3769@item -dm
3770@itemx -fdump-rtl-sms
3771@opindex dm
3772@opindex fdump-rtl-sms
3773Dump after modulo scheduling, to @file{@var{file}.136r.sms}.
3774
3775@item -dM
3776@itemx -fdump-rtl-mach
3777@opindex dM
3778@opindex fdump-rtl-mach
3779Dump after performing the machine dependent reorganization pass, to
3780@file{@var{file}.155r.mach}.
3781
3782@item -dn
3783@itemx -fdump-rtl-rnreg
3784@opindex dn
3785@opindex fdump-rtl-rnreg
3786Dump after register renumbering, to @file{@var{file}.147r.rnreg}.
3787
3788@item -dN
3789@itemx -fdump-rtl-regmove
3790@opindex dN
3791@opindex fdump-rtl-regmove
3792Dump after the register move pass, to @file{@var{file}.132r.regmove}.
3793
3794@item -do
3795@itemx -fdump-rtl-postreload
3796@opindex do
3797@opindex fdump-rtl-postreload
3798Dump after post-reload optimizations, to @file{@var{file}.24.postreload}.
3799
3800@item -dr
3801@itemx -fdump-rtl-expand
3802@opindex dr
3803@opindex fdump-rtl-expand
3804Dump after RTL generation, to @file{@var{file}.104r.expand}.
3805
3806@item -dR
3807@itemx -fdump-rtl-sched2
3808@opindex dR
3809@opindex fdump-rtl-sched2
3810Dump after the second scheduling pass, to @file{@var{file}.150r.sched2}.
3811
3812@item -ds
3813@itemx -fdump-rtl-cse
3814@opindex ds
3815@opindex fdump-rtl-cse
3816Dump after CSE (including the jump optimization that sometimes follows
3817CSE), to @file{@var{file}.113r.cse}.
3818
3819@item -dS
3820@itemx -fdump-rtl-sched
3821@opindex dS
3822@opindex fdump-rtl-sched
3823Dump after the first scheduling pass, to @file{@var{file}.21.sched}.
3824
3825@item -dt
3826@itemx -fdump-rtl-cse2
3827@opindex dt
3828@opindex fdump-rtl-cse2
3829Dump after the second CSE pass (including the jump optimization that
3830sometimes follows CSE), to @file{@var{file}.127r.cse2}.
3831
3832@item -dT
3833@itemx -fdump-rtl-tracer
3834@opindex dT
3835@opindex fdump-rtl-tracer
3836Dump after running tracer, to @file{@var{file}.118r.tracer}.
3837
3838@item -dV
3839@itemx -fdump-rtl-vpt
3840@itemx -fdump-rtl-vartrack
3841@opindex dV
3842@opindex fdump-rtl-vpt
3843@opindex fdump-rtl-vartrack
3844@option{-dV} and @option{-fdump-rtl-vpt} enable dumping after the value
3845profile transformations, to @file{@var{file}.10.vpt}. @option{-dV}
3846and @option{-fdump-rtl-vartrack} enable dumping after variable tracking,
3847to @file{@var{file}.154r.vartrack}.
3848
3849@item -dw
3850@itemx -fdump-rtl-flow2
3851@opindex dw
3852@opindex fdump-rtl-flow2
3853Dump after the second flow pass, to @file{@var{file}.142r.flow2}.
3854
3855@item -dz
3856@itemx -fdump-rtl-peephole2
3857@opindex dz
3858@opindex fdump-rtl-peephole2
3859Dump after the peephole pass, to @file{@var{file}.145r.peephole2}.
3860
3861@item -dZ
3862@itemx -fdump-rtl-web
3863@opindex dZ
3864@opindex fdump-rtl-web
3865Dump after live range splitting, to @file{@var{file}.126r.web}.
3866
3867@item -da
3868@itemx -fdump-rtl-all
3869@opindex da
3870@opindex fdump-rtl-all
3871Produce all the dumps listed above.
3872
3873@item -dH
3874@opindex dH
3875Produce a core dump whenever an error occurs.
3876
3877@item -dm
3878@opindex dm
3879Print statistics on memory usage, at the end of the run, to
3880standard error.
3881
3882@item -dp
3883@opindex dp
3884Annotate the assembler output with a comment indicating which
3885pattern and alternative was used. The length of each instruction is
3886also printed.
3887
3888@item -dP
3889@opindex dP
3890Dump the RTL in the assembler output as a comment before each instruction.
3891Also turns on @option{-dp} annotation.
3892
3893@item -dv
3894@opindex dv
3895For each of the other indicated dump files (either with @option{-d} or
3896@option{-fdump-rtl-@var{pass}}), dump a representation of the control flow
3897graph suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
3898
3899@item -dx
3900@opindex dx
3901Just generate RTL for a function instead of compiling it. Usually used
3902with @samp{r} (@option{-fdump-rtl-expand}).
3903
3904@item -dy
3905@opindex dy
3906Dump debugging information during parsing, to standard error.
3907@end table
3908
3909@item -fdump-noaddr
3910@opindex fdump-noaddr
3911When doing debugging dumps (see @option{-d} option above), suppress
3912address output. This makes it more feasible to use diff on debugging
3913dumps for compiler invocations with different compiler binaries and/or
3914different text / bss / data / heap / stack / dso start locations.
3915
3916@item -fdump-unnumbered
3917@opindex fdump-unnumbered
3918When doing debugging dumps (see @option{-d} option above), suppress instruction
3919numbers, line number note and address output. This makes it more feasible to
3920use diff on debugging dumps for compiler invocations with different
3921options, in particular with and without @option{-g}.
3922
3923@item -fdump-translation-unit @r{(C++ only)}
3924@itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
3925@opindex fdump-translation-unit
3926Dump a representation of the tree structure for the entire translation
3927unit to a file. The file name is made by appending @file{.tu} to the
3928source file name. If the @samp{-@var{options}} form is used, @var{options}
3929controls the details of the dump as described for the
3930@option{-fdump-tree} options.
3931
3932@item -fdump-class-hierarchy @r{(C++ only)}
3933@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
3934@opindex fdump-class-hierarchy
3935Dump a representation of each class's hierarchy and virtual function
3936table layout to a file. The file name is made by appending @file{.class}
3937to the source file name. If the @samp{-@var{options}} form is used,
3938@var{options} controls the details of the dump as described for the
3939@option{-fdump-tree} options.
3940
3941@item -fdump-ipa-@var{switch}
3942@opindex fdump-ipa
3943Control the dumping at various stages of inter-procedural analysis
3944language tree to a file. The file name is generated by appending a switch
3945specific suffix to the source file name. The following dumps are possible:
3946
3947@table @samp
3948@item all
3949Enables all inter-procedural analysis dumps; currently the only produced
3950dump is the @samp{cgraph} dump.
3951
3952@item cgraph
3953Dumps information about call-graph optimization, unused function removal,
3954and inlining decisions.
3955@end table
3956
3957@item -fdump-tree-@var{switch}
3958@itemx -fdump-tree-@var{switch}-@var{options}
3959@opindex fdump-tree
3960Control the dumping at various stages of processing the intermediate
3961language tree to a file. The file name is generated by appending a switch
3962specific suffix to the source file name. If the @samp{-@var{options}}
3963form is used, @var{options} is a list of @samp{-} separated options that
3964control the details of the dump. Not all options are applicable to all
3965dumps, those which are not meaningful will be ignored. The following
3966options are available
3967
3968@table @samp
3969@item address
3970Print the address of each node. Usually this is not meaningful as it
3971changes according to the environment and source file. Its primary use
3972is for tying up a dump file with a debug environment.
3973@item slim
3974Inhibit dumping of members of a scope or body of a function merely
3975because that scope has been reached. Only dump such items when they
3976are directly reachable by some other path. When dumping pretty-printed
3977trees, this option inhibits dumping the bodies of control structures.
3978@item raw
3979Print a raw representation of the tree. By default, trees are
3980pretty-printed into a C-like representation.
3981@item details
3982Enable more detailed dumps (not honored by every dump option).
3983@item stats
3984Enable dumping various statistics about the pass (not honored by every dump
3985option).
3986@item blocks
3987Enable showing basic block boundaries (disabled in raw dumps).
3988@item vops
3989Enable showing virtual operands for every statement.
3990@item lineno
3991Enable showing line numbers for statements.
3992@item uid
3993Enable showing the unique ID (@code{DECL_UID}) for each variable.
3994@item all
3995Turn on all options, except @option{raw}, @option{slim} and @option{lineno}.
3996@end table
3997
3998The following tree dumps are possible:
3999@table @samp
4000
4001@item original
4002Dump before any tree based optimization, to @file{@var{file}.original}.
4003
4004@item optimized
4005Dump after all tree based optimization, to @file{@var{file}.optimized}.
4006
4007@item inlined
4008Dump after function inlining, to @file{@var{file}.inlined}.
4009
4010@item gimple
4011@opindex fdump-tree-gimple
4012Dump each function before and after the gimplification pass to a file. The
4013file name is made by appending @file{.gimple} to the source file name.
4014
4015@item cfg
4016@opindex fdump-tree-cfg
4017Dump the control flow graph of each function to a file. The file name is
4018made by appending @file{.cfg} to the source file name.
4019
4020@item vcg
4021@opindex fdump-tree-vcg
4022Dump the control flow graph of each function to a file in VCG format. The
4023file name is made by appending @file{.vcg} to the source file name. Note
4024that if the file contains more than one function, the generated file cannot
4025be used directly by VCG@. You will need to cut and paste each function's
4026graph into its own separate file first.
4027
4028@item ch
4029@opindex fdump-tree-ch
4030Dump each function after copying loop headers. The file name is made by
4031appending @file{.ch} to the source file name.
4032
4033@item ssa
4034@opindex fdump-tree-ssa
4035Dump SSA related information to a file. The file name is made by appending
4036@file{.ssa} to the source file name.
4037
4038@item salias
4039@opindex fdump-tree-salias
4040Dump structure aliasing variable information to a file. This file name
4041is made by appending @file{.salias} to the source file name.
4042
4043@item alias
4044@opindex fdump-tree-alias
4045Dump aliasing information for each function. The file name is made by
4046appending @file{.alias} to the source file name.
4047
4048@item ccp
4049@opindex fdump-tree-ccp
4050Dump each function after CCP@. The file name is made by appending
4051@file{.ccp} to the source file name.
4052
4053@item storeccp
4054@opindex fdump-tree-storeccp
4055Dump each function after STORE-CCP. The file name is made by appending
4056@file{.storeccp} to the source file name.
4057
4058@item pre
4059@opindex fdump-tree-pre
4060Dump trees after partial redundancy elimination. The file name is made
4061by appending @file{.pre} to the source file name.
4062
4063@item fre
4064@opindex fdump-tree-fre
4065Dump trees after full redundancy elimination. The file name is made
4066by appending @file{.fre} to the source file name.
4067
4068@item copyprop
4069@opindex fdump-tree-copyprop
4070Dump trees after copy propagation. The file name is made
4071by appending @file{.copyprop} to the source file name.
4072
4073@item store_copyprop
4074@opindex fdump-tree-store_copyprop
4075Dump trees after store copy-propagation. The file name is made
4076by appending @file{.store_copyprop} to the source file name.
4077
4078@item dce
4079@opindex fdump-tree-dce
4080Dump each function after dead code elimination. The file name is made by
4081appending @file{.dce} to the source file name.
4082
4083@item mudflap
4084@opindex fdump-tree-mudflap
4085Dump each function after adding mudflap instrumentation. The file name is
4086made by appending @file{.mudflap} to the source file name.
4087
4088@item sra
4089@opindex fdump-tree-sra
4090Dump each function after performing scalar replacement of aggregates. The
4091file name is made by appending @file{.sra} to the source file name.
4092
4093@item sink
4094@opindex fdump-tree-sink
4095Dump each function after performing code sinking. The file name is made
4096by appending @file{.sink} to the source file name.
4097
4098@item dom
4099@opindex fdump-tree-dom
4100Dump each function after applying dominator tree optimizations. The file
4101name is made by appending @file{.dom} to the source file name.
4102
4103@item dse
4104@opindex fdump-tree-dse
4105Dump each function after applying dead store elimination. The file
4106name is made by appending @file{.dse} to the source file name.
4107
4108@item phiopt
4109@opindex fdump-tree-phiopt
4110Dump each function after optimizing PHI nodes into straightline code. The file
4111name is made by appending @file{.phiopt} to the source file name.
4112
4113@item forwprop
4114@opindex fdump-tree-forwprop
4115Dump each function after forward propagating single use variables. The file
4116name is made by appending @file{.forwprop} to the source file name.
4117
4118@item copyrename
4119@opindex fdump-tree-copyrename
4120Dump each function after applying the copy rename optimization. The file
4121name is made by appending @file{.copyrename} to the source file name.
4122
4123@item nrv
4124@opindex fdump-tree-nrv
4125Dump each function after applying the named return value optimization on
4126generic trees. The file name is made by appending @file{.nrv} to the source
4127file name.
4128
4129@item vect
4130@opindex fdump-tree-vect
4131Dump each function after applying vectorization of loops. The file name is
4132made by appending @file{.vect} to the source file name.
4133
4134@item vrp
4135@opindex fdump-tree-vrp
4136Dump each function after Value Range Propagation (VRP). The file name
4137is made by appending @file{.vrp} to the source file name.
4138
4139@item all
4140@opindex fdump-tree-all
4141Enable all the available tree dumps with the flags provided in this option.
4142@end table
4143
4144@item -ftree-vectorizer-verbose=@var{n}
4145@opindex ftree-vectorizer-verbose
4146This option controls the amount of debugging output the vectorizer prints.
4147This information is written to standard error, unless
4148@option{-fdump-tree-all} or @option{-fdump-tree-vect} is specified,
4149in which case it is output to the usual dump listing file, @file{.vect}.
4150For @var{n}=0 no diagnostic information is reported.
4151If @var{n}=1 the vectorizer reports each loop that got vectorized,
4152and the total number of loops that got vectorized.
4153If @var{n}=2 the vectorizer also reports non-vectorized loops that passed
4154the first analysis phase (vect_analyze_loop_form) - i.e. countable,
4155inner-most, single-bb, single-entry/exit loops. This is the same verbosity
4156level that @option{-fdump-tree-vect-stats} uses.
4157Higher verbosity levels mean either more information dumped for each
4158reported loop, or same amount of information reported for more loops:
4159If @var{n}=3, alignment related information is added to the reports.
4160If @var{n}=4, data-references related information (e.g. memory dependences,
4161memory access-patterns) is added to the reports.
4162If @var{n}=5, the vectorizer reports also non-vectorized inner-most loops
4163that did not pass the first analysis phase (i.e. may not be countable, or
4164may have complicated control-flow).
4165If @var{n}=6, the vectorizer reports also non-vectorized nested loops.
4166For @var{n}=7, all the information the vectorizer generates during its
4167analysis and transformation is reported. This is the same verbosity level
4168that @option{-fdump-tree-vect-details} uses.
4169
4170@item -frandom-seed=@var{string}
4171@opindex frandom-string
4172This option provides a seed that GCC uses when it would otherwise use
4173random numbers. It is used to generate certain symbol names
4174that have to be different in every compiled file. It is also used to
4175place unique stamps in coverage data files and the object files that
4176produce them. You can use the @option{-frandom-seed} option to produce
4177reproducibly identical object files.
4178
4179The @var{string} should be different for every file you compile.
4180
4181@item -fsched-verbose=@var{n}
4182@opindex fsched-verbose
4183On targets that use instruction scheduling, this option controls the
4184amount of debugging output the scheduler prints. This information is
4185written to standard error, unless @option{-dS} or @option{-dR} is
4186specified, in which case it is output to the usual dump
4187listing file, @file{.sched} or @file{.sched2} respectively. However
4188for @var{n} greater than nine, the output is always printed to standard
4189error.
4190
4191For @var{n} greater than zero, @option{-fsched-verbose} outputs the
4192same information as @option{-dRS}. For @var{n} greater than one, it
4193also output basic block probabilities, detailed ready list information
4194and unit/insn info. For @var{n} greater than two, it includes RTL
4195at abort point, control-flow and regions info. And for @var{n} over
4196four, @option{-fsched-verbose} also includes dependence info.
4197
4198@item -save-temps
4199@opindex save-temps
4200Store the usual ``temporary'' intermediate files permanently; place them
4201in the current directory and name them based on the source file. Thus,
4202compiling @file{foo.c} with @samp{-c -save-temps} would produce files
4203@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
4204preprocessed @file{foo.i} output file even though the compiler now
4205normally uses an integrated preprocessor.
4206
4207When used in combination with the @option{-x} command line option,
4208@option{-save-temps} is sensible enough to avoid over writing an
4209input source file with the same extension as an intermediate file.
4210The corresponding intermediate file may be obtained by renaming the
4211source file before using @option{-save-temps}.
4212
4213@item -time
4214@opindex time
4215Report the CPU time taken by each subprocess in the compilation
4216sequence. For C source files, this is the compiler proper and assembler
4217(plus the linker if linking is done). The output looks like this:
4218
4219@smallexample
4220# cc1 0.12 0.01
4221# as 0.00 0.01
4222@end smallexample
4223
4224The first number on each line is the ``user time'', that is time spent
4225executing the program itself. The second number is ``system time'',
4226time spent executing operating system routines on behalf of the program.
4227Both numbers are in seconds.
4228
4229@item -fvar-tracking
4230@opindex fvar-tracking
4231Run variable tracking pass. It computes where variables are stored at each
4232position in code. Better debugging information is then generated
4233(if the debugging information format supports this information).
4234
4235It is enabled by default when compiling with optimization (@option{-Os},
4236@option{-O}, @option{-O2}, ...), debugging information (@option{-g}) and
4237the debug info format supports it.
4238
4239@item -print-file-name=@var{library}
4240@opindex print-file-name
4241Print the full absolute name of the library file @var{library} that
4242would be used when linking---and don't do anything else. With this
4243option, GCC does not compile or link anything; it just prints the
4244file name.
4245
4246@item -print-multi-directory
4247@opindex print-multi-directory
4248Print the directory name corresponding to the multilib selected by any
4249other switches present in the command line. This directory is supposed
4250to exist in @env{GCC_EXEC_PREFIX}.
4251
4252@item -print-multi-lib
4253@opindex print-multi-lib
4254Print the mapping from multilib directory names to compiler switches
4255that enable them. The directory name is separated from the switches by
4256@samp{;}, and each switch starts with an @samp{@@} instead of the
4257@samp{-}, without spaces between multiple switches. This is supposed to
4258ease shell-processing.
4259
4260@item -print-prog-name=@var{program}
4261@opindex print-prog-name
4262Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
4263
4264@item -print-libgcc-file-name
4265@opindex print-libgcc-file-name
4266Same as @option{-print-file-name=libgcc.a}.
4267
4268This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
4269but you do want to link with @file{libgcc.a}. You can do
4270
4271@smallexample
4272gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
4273@end smallexample
4274
4275@item -print-search-dirs
4276@opindex print-search-dirs
4277Print the name of the configured installation directory and a list of
4278program and library directories @command{gcc} will search---and don't do anything else.
4279
4280This is useful when @command{gcc} prints the error message
4281@samp{installation problem, cannot exec cpp0: No such file or directory}.
4282To resolve this you either need to put @file{cpp0} and the other compiler
4283components where @command{gcc} expects to find them, or you can set the environment
4284variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
4285Don't forget the trailing @samp{/}.
4286@xref{Environment Variables}.
4287
4288@item -dumpmachine
4289@opindex dumpmachine
4290Print the compiler's target machine (for example,
4291@samp{i686-pc-linux-gnu})---and don't do anything else.
4292
4293@item -dumpversion
4294@opindex dumpversion
4295Print the compiler version (for example, @samp{3.0})---and don't do
4296anything else.
4297
4298@item -dumpspecs
4299@opindex dumpspecs
4300Print the compiler's built-in specs---and don't do anything else. (This
4301is used when GCC itself is being built.) @xref{Spec Files}.
4302
4303@item -feliminate-unused-debug-types
4304@opindex feliminate-unused-debug-types
4305Normally, when producing DWARF2 output, GCC will emit debugging
4306information for all types declared in a compilation
4307unit, regardless of whether or not they are actually used
4308in that compilation unit. Sometimes this is useful, such as
4309if, in the debugger, you want to cast a value to a type that is
4310not actually used in your program (but is declared). More often,
4311however, this results in a significant amount of wasted space.
4312With this option, GCC will avoid producing debug symbol output
4313for types that are nowhere used in the source file being compiled.
4314@end table
4315
4316@node Optimize Options
4317@section Options That Control Optimization
4318@cindex optimize options
4319@cindex options, optimization
4320
4321These options control various sorts of optimizations.
4322
4323Without any optimization option, the compiler's goal is to reduce the
4324cost of compilation and to make debugging produce the expected
4325results. Statements are independent: if you stop the program with a
4326breakpoint between statements, you can then assign a new value to any
4327variable or change the program counter to any other statement in the
4328function and get exactly the results you would expect from the source
4329code.
4330
4331Turning on optimization flags makes the compiler attempt to improve
4332the performance and/or code size at the expense of compilation time
4333and possibly the ability to debug the program.
4334
4335The compiler performs optimization based on the knowledge it has of
4336the program. Optimization levels @option{-O} and above, in
4337particular, enable @emph{unit-at-a-time} mode, which allows the
4338compiler to consider information gained from later functions in
4339the file when compiling a function. Compiling multiple files at
4340once to a single output file in @emph{unit-at-a-time} mode allows
4341the compiler to use information gained from all of the files when
4342compiling each of them.
4343
4344Not all optimizations are controlled directly by a flag. Only
4345optimizations that have a flag are listed.
4346
4347@table @gcctabopt
4348@item -O
4349@itemx -O1
4350@opindex O
4351@opindex O1
4352Optimize. Optimizing compilation takes somewhat more time, and a lot
4353more memory for a large function.
4354
4355With @option{-O}, the compiler tries to reduce code size and execution
4356time, without performing any optimizations that take a great deal of
4357compilation time.
4358
4359@option{-O} turns on the following optimization flags:
4360@gccoptlist{-fdefer-pop @gol
4361-fdelayed-branch @gol
4362-fguess-branch-probability @gol
4363-fcprop-registers @gol
4364-fif-conversion @gol
4365-fif-conversion2 @gol
4366-ftree-ccp @gol
4367-ftree-dce @gol
4368-ftree-dominator-opts @gol
4369-ftree-dse @gol
4370-ftree-ter @gol
4371-ftree-lrs @gol
4372-ftree-sra @gol
4373-ftree-copyrename @gol
4374-ftree-fre @gol
4375-ftree-ch @gol
4376-funit-at-a-time @gol
4377-fmerge-constants}
4378
4379@option{-O} also turns on @option{-fomit-frame-pointer} on machines
4380where doing so does not interfere with debugging.
4381
4382@item -O2
4383@opindex O2
4384Optimize even more. GCC performs nearly all supported optimizations
4385that do not involve a space-speed tradeoff. The compiler does not
4386perform loop unrolling or function inlining when you specify @option{-O2}.
4387As compared to @option{-O}, this option increases both compilation time
4388and the performance of the generated code.
4389
4390@option{-O2} turns on all optimization flags specified by @option{-O}. It
4391also turns on the following optimization flags:
4392@gccoptlist{-fthread-jumps @gol
4393-fcrossjumping @gol
4394-foptimize-sibling-calls @gol
4395-fcse-follow-jumps -fcse-skip-blocks @gol
4396-fgcse -fgcse-lm @gol
4397-fexpensive-optimizations @gol
4398-frerun-cse-after-loop @gol
4399-fcaller-saves @gol
4400-fpeephole2 @gol
4401-fschedule-insns -fschedule-insns2 @gol
4402-fsched-interblock -fsched-spec @gol
4403-fregmove @gol
4404-fstrict-aliasing -fstrict-overflow @gol
4405-fdelete-null-pointer-checks @gol
4406-freorder-blocks -freorder-functions @gol
4407-falign-functions -falign-jumps @gol
4408-falign-loops -falign-labels @gol
4409-ftree-vrp @gol
4410-ftree-pre}
4411
4412Please note the warning under @option{-fgcse} about
4413invoking @option{-O2} on programs that use computed gotos.
4414
4415@option{-O2} doesn't turn on @option{-ftree-vrp} for the Ada compiler.
4416This option must be explicitly specified on the command line to be
4417enabled for the Ada compiler.
4418
4419@item -O3
4420@opindex O3
4421Optimize yet more. @option{-O3} turns on all optimizations specified by
4422@option{-O2} and also turns on the @option{-finline-functions},
4423@option{-funswitch-loops} and @option{-fgcse-after-reload} options.
4424
4425@item -O0
4426@opindex O0
4427Do not optimize. This is the default.
4428
4429@item -Os
4430@opindex Os
4431Optimize for size. @option{-Os} enables all @option{-O2} optimizations that
4432do not typically increase code size. It also performs further
4433optimizations designed to reduce code size.
4434
4435@option{-Os} disables the following optimization flags:
4436@gccoptlist{-falign-functions -falign-jumps -falign-loops @gol
4437-falign-labels -freorder-blocks -freorder-blocks-and-partition @gol
4438-fprefetch-loop-arrays -ftree-vect-loop-version}
4439
4440If you use multiple @option{-O} options, with or without level numbers,
4441the last such option is the one that is effective.
4442@end table
4443
4444Options of the form @option{-f@var{flag}} specify machine-independent
4445flags. Most flags have both positive and negative forms; the negative
4446form of @option{-ffoo} would be @option{-fno-foo}. In the table
4447below, only one of the forms is listed---the one you typically will
4448use. You can figure out the other form by either removing @samp{no-}
4449or adding it.
4450
4451The following options control specific optimizations. They are either
4452activated by @option{-O} options or are related to ones that are. You
4453can use the following flags in the rare cases when ``fine-tuning'' of
4454optimizations to be performed is desired.
4455
4456@table @gcctabopt
4457@item -fno-default-inline
4458@opindex fno-default-inline
4459Do not make member functions inline by default merely because they are
4460defined inside the class scope (C++ only). Otherwise, when you specify
4461@w{@option{-O}}, member functions defined inside class scope are compiled
4462inline by default; i.e., you don't need to add @samp{inline} in front of
4463the member function name.
4464
4465@item -fno-defer-pop
4466@opindex fno-defer-pop
4467Always pop the arguments to each function call as soon as that function
4468returns. For machines which must pop arguments after a function call,
4469the compiler normally lets arguments accumulate on the stack for several
4470function calls and pops them all at once.
4471
4472Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4473
4474@item -fforce-mem
4475@opindex fforce-mem
4476Force memory operands to be copied into registers before doing
4477arithmetic on them. This produces better code by making all memory
4478references potential common subexpressions. When they are not common
4479subexpressions, instruction combination should eliminate the separate
4480register-load. This option is now a nop and will be removed in 4.3.
4481
4482@item -fforce-addr
4483@opindex fforce-addr
4484Force memory address constants to be copied into registers before
4485doing arithmetic on them.
4486
4487@item -fomit-frame-pointer
4488@opindex fomit-frame-pointer
4489Don't keep the frame pointer in a register for functions that
4490don't need one. This avoids the instructions to save, set up and
4491restore frame pointers; it also makes an extra register available
4492in many functions. @strong{It also makes debugging impossible on
4493some machines.}
4494
4495On some machines, such as the VAX, this flag has no effect, because
4496the standard calling sequence automatically handles the frame pointer
4497and nothing is saved by pretending it doesn't exist. The
4498machine-description macro @code{FRAME_POINTER_REQUIRED} controls
4499whether a target machine supports this flag. @xref{Registers,,Register
4500Usage, gccint, GNU Compiler Collection (GCC) Internals}.
4501
4502Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4503
4504@item -foptimize-sibling-calls
4505@opindex foptimize-sibling-calls
4506Optimize sibling and tail recursive calls.
4507
4508Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4509
4510@item -fno-inline
4511@opindex fno-inline
4512Don't pay attention to the @code{inline} keyword. Normally this option
4513is used to keep the compiler from expanding any functions inline.
4514Note that if you are not optimizing, no functions can be expanded inline.
4515
4516@item -finline-functions
4517@opindex finline-functions
4518Integrate all simple functions into their callers. The compiler
4519heuristically decides which functions are simple enough to be worth
4520integrating in this way.
4521
4522If all calls to a given function are integrated, and the function is
4523declared @code{static}, then the function is normally not output as
4524assembler code in its own right.
4525
4526Enabled at level @option{-O3}.
4527
4528@item -finline-functions-called-once
4529@opindex finline-functions-called-once
4530Consider all @code{static} functions called once for inlining into their
4531caller even if they are not marked @code{inline}. If a call to a given
4532function is integrated, then the function is not output as assembler code
4533in its own right.
4534
4535Enabled if @option{-funit-at-a-time} is enabled.
4536
4537@item -fearly-inlining
4538@opindex fearly-inlining
4539Inline functions marked by @code{always_inline} and functions whose body seems
4540smaller than the function call overhead early before doing
4541@option{-fprofile-generate} instrumentation and real inlining pass. Doing so
4542makes profiling significantly cheaper and usually inlining faster on programs
4543having large chains of nested wrapper functions.
4544
4545Enabled by default.
4546
4547@item -finline-limit=@var{n}
4548@opindex finline-limit
4549By default, GCC limits the size of functions that can be inlined. This flag
4550allows the control of this limit for functions that are explicitly marked as
4551inline (i.e., marked with the inline keyword or defined within the class
4552definition in c++). @var{n} is the size of functions that can be inlined in
4553number of pseudo instructions (not counting parameter handling). The default
4554value of @var{n} is 600.
4555Increasing this value can result in more inlined code at
4556the cost of compilation time and memory consumption. Decreasing usually makes
4557the compilation faster and less code will be inlined (which presumably
4558means slower programs). This option is particularly useful for programs that
4559use inlining heavily such as those based on recursive templates with C++.
4560
4561Inlining is actually controlled by a number of parameters, which may be
4562specified individually by using @option{--param @var{name}=@var{value}}.
4563The @option{-finline-limit=@var{n}} option sets some of these parameters
4564as follows:
4565
4566@table @gcctabopt
4567@item max-inline-insns-single
4568 is set to @var{n}/2.
4569@item max-inline-insns-auto
4570 is set to @var{n}/2.
4571@item min-inline-insns
4572 is set to 130 or @var{n}/4, whichever is smaller.
4573@item max-inline-insns-rtl
4574 is set to @var{n}.
4575@end table
4576
4577See below for a documentation of the individual
4578parameters controlling inlining.
4579
4580@emph{Note:} pseudo instruction represents, in this particular context, an
4581abstract measurement of function's size. In no way does it represent a count
4582of assembly instructions and as such its exact meaning might change from one
4583release to an another.
4584
4585@item -fkeep-inline-functions
4586@opindex fkeep-inline-functions
4587In C, emit @code{static} functions that are declared @code{inline}
4588into the object file, even if the function has been inlined into all
4589of its callers. This switch does not affect functions using the
4590@code{extern inline} extension in GNU C@. In C++, emit any and all
4591inline functions into the object file.
4592
4593@item -fkeep-static-consts
4594@opindex fkeep-static-consts
4595Emit variables declared @code{static const} when optimization isn't turned
4596on, even if the variables aren't referenced.
4597
4598GCC enables this option by default. If you want to force the compiler to
4599check if the variable was referenced, regardless of whether or not
4600optimization is turned on, use the @option{-fno-keep-static-consts} option.
4601
4602@item -fmerge-constants
4603Attempt to merge identical constants (string constants and floating point
4604constants) across compilation units.
4605
4606This option is the default for optimized compilation if the assembler and
4607linker support it. Use @option{-fno-merge-constants} to inhibit this
4608behavior.
4609
4610Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4611
4612@item -fmerge-all-constants
4613Attempt to merge identical constants and identical variables.
4614
4615This option implies @option{-fmerge-constants}. In addition to
4616@option{-fmerge-constants} this considers e.g.@: even constant initialized
4617arrays or initialized constant variables with integral or floating point
4618types. Languages like C or C++ require each non-automatic variable to
4619have distinct location, so using this option will result in non-conforming
4620behavior.
4621
4622@item -fmodulo-sched
4623@opindex fmodulo-sched
4624Perform swing modulo scheduling immediately before the first scheduling
4625pass. This pass looks at innermost loops and reorders their
4626instructions by overlapping different iterations.
4627
4628@item -fno-branch-count-reg
4629@opindex fno-branch-count-reg
4630Do not use ``decrement and branch'' instructions on a count register,
4631but instead generate a sequence of instructions that decrement a
4632register, compare it against zero, then branch based upon the result.
4633This option is only meaningful on architectures that support such
4634instructions, which include x86, PowerPC, IA-64 and S/390.
4635
4636The default is @option{-fbranch-count-reg}.
4637
4638@item -fno-function-cse
4639@opindex fno-function-cse
4640Do not put function addresses in registers; make each instruction that
4641calls a constant function contain the function's address explicitly.
4642
4643This option results in less efficient code, but some strange hacks
4644that alter the assembler output may be confused by the optimizations
4645performed when this option is not used.
4646
4647The default is @option{-ffunction-cse}
4648
4649@item -fno-zero-initialized-in-bss
4650@opindex fno-zero-initialized-in-bss
4651If the target supports a BSS section, GCC by default puts variables that
4652are initialized to zero into BSS@. This can save space in the resulting
4653code.
4654
4655This option turns off this behavior because some programs explicitly
4656rely on variables going to the data section. E.g., so that the
4657resulting executable can find the beginning of that section and/or make
4658assumptions based on that.
4659
4660The default is @option{-fzero-initialized-in-bss}.
4661
4662@item -fbounds-check
4663@opindex fbounds-check
4664For front-ends that support it, generate additional code to check that
4665indices used to access arrays are within the declared range. This is
4666currently only supported by the Java and Fortran front-ends, where
4667this option defaults to true and false respectively.
4668
4669@item -fmudflap -fmudflapth -fmudflapir
4670@opindex fmudflap
4671@opindex fmudflapth
4672@opindex fmudflapir
4673@cindex bounds checking
4674@cindex mudflap
4675For front-ends that support it (C and C++), instrument all risky
4676pointer/array dereferencing operations, some standard library
4677string/heap functions, and some other associated constructs with
4678range/validity tests. Modules so instrumented should be immune to
4679buffer overflows, invalid heap use, and some other classes of C/C++
4680programming errors. The instrumentation relies on a separate runtime
4681library (@file{libmudflap}), which will be linked into a program if
4682@option{-fmudflap} is given at link time. Run-time behavior of the
4683instrumented program is controlled by the @env{MUDFLAP_OPTIONS}
4684environment variable. See @code{env MUDFLAP_OPTIONS=-help a.out}
4685for its options.
4686
4687Use @option{-fmudflapth} instead of @option{-fmudflap} to compile and to
4688link if your program is multi-threaded. Use @option{-fmudflapir}, in
4689addition to @option{-fmudflap} or @option{-fmudflapth}, if
4690instrumentation should ignore pointer reads. This produces less
4691instrumentation (and therefore faster execution) and still provides
4692some protection against outright memory corrupting writes, but allows
4693erroneously read data to propagate within a program.
4694
4695@item -fthread-jumps
4696@opindex fthread-jumps
4697Perform optimizations where we check to see if a jump branches to a
4698location where another comparison subsumed by the first is found. If
4699so, the first branch is redirected to either the destination of the
4700second branch or a point immediately following it, depending on whether
4701the condition is known to be true or false.
4702
4703Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4704
4705@item -fcse-follow-jumps
4706@opindex fcse-follow-jumps
4707In common subexpression elimination, scan through jump instructions
4708when the target of the jump is not reached by any other path. For
4709example, when CSE encounters an @code{if} statement with an
4710@code{else} clause, CSE will follow the jump when the condition
4711tested is false.
4712
4713Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4714
4715@item -fcse-skip-blocks
4716@opindex fcse-skip-blocks
4717This is similar to @option{-fcse-follow-jumps}, but causes CSE to
4718follow jumps which conditionally skip over blocks. When CSE
4719encounters a simple @code{if} statement with no else clause,
4720@option{-fcse-skip-blocks} causes CSE to follow the jump around the
4721body of the @code{if}.
4722
4723Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4724
4725@item -frerun-cse-after-loop
4726@opindex frerun-cse-after-loop
4727Re-run common subexpression elimination after loop optimizations has been
4728performed.
4729
4730Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4731
4732@item -fgcse
4733@opindex fgcse
4734Perform a global common subexpression elimination pass.
4735This pass also performs global constant and copy propagation.
4736
4737@emph{Note:} When compiling a program using computed gotos, a GCC
4738extension, you may get better runtime performance if you disable
4739the global common subexpression elimination pass by adding
4740@option{-fno-gcse} to the command line.
4741
4742Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4743
4744@item -fgcse-lm
4745@opindex fgcse-lm
4746When @option{-fgcse-lm} is enabled, global common subexpression elimination will
4747attempt to move loads which are only killed by stores into themselves. This
4748allows a loop containing a load/store sequence to be changed to a load outside
4749the loop, and a copy/store within the loop.
4750
4751Enabled by default when gcse is enabled.
4752
4753@item -fgcse-sm
4754@opindex fgcse-sm
4755When @option{-fgcse-sm} is enabled, a store motion pass is run after
4756global common subexpression elimination. This pass will attempt to move
4757stores out of loops. When used in conjunction with @option{-fgcse-lm},
4758loops containing a load/store sequence can be changed to a load before
4759the loop and a store after the loop.
4760
4761Not enabled at any optimization level.
4762
4763@item -fgcse-las
4764@opindex fgcse-las
4765When @option{-fgcse-las} is enabled, the global common subexpression
4766elimination pass eliminates redundant loads that come after stores to the
4767same memory location (both partial and full redundancies).
4768
4769Not enabled at any optimization level.
4770
4771@item -fgcse-after-reload
4772@opindex fgcse-after-reload
4773When @option{-fgcse-after-reload} is enabled, a redundant load elimination
4774pass is performed after reload. The purpose of this pass is to cleanup
4775redundant spilling.
4776
4777@item -funsafe-loop-optimizations
4778@opindex funsafe-loop-optimizations
4779If given, the loop optimizer will assume that loop indices do not
4780overflow, and that the loops with nontrivial exit condition are not
4781infinite. This enables a wider range of loop optimizations even if
4782the loop optimizer itself cannot prove that these assumptions are valid.
4783Using @option{-Wunsafe-loop-optimizations}, the compiler will warn you
4784if it finds this kind of loop.
4785
4786@item -fcrossjumping
4787@opindex crossjumping
4788Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
4789resulting code may or may not perform better than without cross-jumping.
4790
4791Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4792
4793@item -fif-conversion
4794@opindex if-conversion
4795Attempt to transform conditional jumps into branch-less equivalents. This
4796include use of conditional moves, min, max, set flags and abs instructions, and
4797some tricks doable by standard arithmetics. The use of conditional execution
4798on chips where it is available is controlled by @code{if-conversion2}.
4799
4800Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4801
4802@item -fif-conversion2
4803@opindex if-conversion2
4804Use conditional execution (where available) to transform conditional jumps into
4805branch-less equivalents.
4806
4807Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4808
4809@item -fdelete-null-pointer-checks
4810@opindex fdelete-null-pointer-checks
4811Use global dataflow analysis to identify and eliminate useless checks
4812for null pointers. The compiler assumes that dereferencing a null
4813pointer would have halted the program. If a pointer is checked after
4814it has already been dereferenced, it cannot be null.
4815
4816In some environments, this assumption is not true, and programs can
4817safely dereference null pointers. Use
4818@option{-fno-delete-null-pointer-checks} to disable this optimization
4819for programs which depend on that behavior.
4820
4821Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4822
4823@item -fexpensive-optimizations
4824@opindex fexpensive-optimizations
4825Perform a number of minor optimizations that are relatively expensive.
4826
4827Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4828
4829@item -foptimize-register-move
4830@itemx -fregmove
4831@opindex foptimize-register-move
4832@opindex fregmove
4833Attempt to reassign register numbers in move instructions and as
4834operands of other simple instructions in order to maximize the amount of
4835register tying. This is especially helpful on machines with two-operand
4836instructions.
4837
4838Note @option{-fregmove} and @option{-foptimize-register-move} are the same
4839optimization.
4840
4841Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4842
4843@item -fdelayed-branch
4844@opindex fdelayed-branch
4845If supported for the target machine, attempt to reorder instructions
4846to exploit instruction slots available after delayed branch
4847instructions.
4848
4849Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4850
4851@item -fschedule-insns
4852@opindex fschedule-insns
4853If supported for the target machine, attempt to reorder instructions to
4854eliminate execution stalls due to required data being unavailable. This
4855helps machines that have slow floating point or memory load instructions
4856by allowing other instructions to be issued until the result of the load
4857or floating point instruction is required.
4858
4859Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4860
4861@item -fschedule-insns2
4862@opindex fschedule-insns2
4863Similar to @option{-fschedule-insns}, but requests an additional pass of
4864instruction scheduling after register allocation has been done. This is
4865especially useful on machines with a relatively small number of
4866registers and where memory load instructions take more than one cycle.
4867
4868Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4869
4870@item -fno-sched-interblock
4871@opindex fno-sched-interblock
4872Don't schedule instructions across basic blocks. This is normally
4873enabled by default when scheduling before register allocation, i.e.@:
4874with @option{-fschedule-insns} or at @option{-O2} or higher.
4875
4876@item -fno-sched-spec
4877@opindex fno-sched-spec
4878Don't allow speculative motion of non-load instructions. This is normally
4879enabled by default when scheduling before register allocation, i.e.@:
4880with @option{-fschedule-insns} or at @option{-O2} or higher.
4881
4882@item -fsched-spec-load
4883@opindex fsched-spec-load
4884Allow speculative motion of some load instructions. This only makes
4885sense when scheduling before register allocation, i.e.@: with
4886@option{-fschedule-insns} or at @option{-O2} or higher.
4887
4888@item -fsched-spec-load-dangerous
4889@opindex fsched-spec-load-dangerous
4890Allow speculative motion of more load instructions. This only makes
4891sense when scheduling before register allocation, i.e.@: with
4892@option{-fschedule-insns} or at @option{-O2} or higher.
4893
4894@item -fsched-stalled-insns=@var{n}
4895@opindex fsched-stalled-insns
4896Define how many insns (if any) can be moved prematurely from the queue
4897of stalled insns into the ready list, during the second scheduling pass.
4898
4899@item -fsched-stalled-insns-dep=@var{n}
4900@opindex fsched-stalled-insns-dep
4901Define how many insn groups (cycles) will be examined for a dependency
4902on a stalled insn that is candidate for premature removal from the queue
4903of stalled insns. Has an effect only during the second scheduling pass,
4904and only if @option{-fsched-stalled-insns} is used and its value is not zero.
4905
4906@item -fsched2-use-superblocks
4907@opindex fsched2-use-superblocks
4908When scheduling after register allocation, do use superblock scheduling
4909algorithm. Superblock scheduling allows motion across basic block boundaries
4910resulting on faster schedules. This option is experimental, as not all machine
4911descriptions used by GCC model the CPU closely enough to avoid unreliable
4912results from the algorithm.
4913
4914This only makes sense when scheduling after register allocation, i.e.@: with
4915@option{-fschedule-insns2} or at @option{-O2} or higher.
4916
4917@item -fsched2-use-traces
4918@opindex fsched2-use-traces
4919Use @option{-fsched2-use-superblocks} algorithm when scheduling after register
4920allocation and additionally perform code duplication in order to increase the
4921size of superblocks using tracer pass. See @option{-ftracer} for details on
4922trace formation.
4923
4924This mode should produce faster but significantly longer programs. Also
4925without @option{-fbranch-probabilities} the traces constructed may not
4926match the reality and hurt the performance. This only makes
4927sense when scheduling after register allocation, i.e.@: with
4928@option{-fschedule-insns2} or at @option{-O2} or higher.
4929
4930@item -fsee
4931@opindex fsee
4932Eliminates redundant extension instructions and move the non redundant
4933ones to optimal placement using LCM.
4934
4935@item -freschedule-modulo-scheduled-loops
4936@opindex fscheduling-in-modulo-scheduled-loops
4937The modulo scheduling comes before the traditional scheduling, if a loop was modulo scheduled
4938we may want to prevent the later scheduling passes from changing its schedule, we use this
4939option to control that.
4940
4941@item -fcaller-saves
4942@opindex fcaller-saves
4943Enable values to be allocated in registers that will be clobbered by
4944function calls, by emitting extra instructions to save and restore the
4945registers around such calls. Such allocation is done only when it
4946seems to result in better code than would otherwise be produced.
4947
4948This option is always enabled by default on certain machines, usually
4949those which have no call-preserved registers to use instead.
4950
4951Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4952
4953@item -ftree-pre
4954Perform Partial Redundancy Elimination (PRE) on trees. This flag is
4955enabled by default at @option{-O2} and @option{-O3}.
4956
4957@item -ftree-fre
4958Perform Full Redundancy Elimination (FRE) on trees. The difference
4959between FRE and PRE is that FRE only considers expressions
4960that are computed on all paths leading to the redundant computation.
4961This analysis faster than PRE, though it exposes fewer redundancies.
4962This flag is enabled by default at @option{-O} and higher.
4963
4964@item -ftree-copy-prop
4965Perform copy propagation on trees. This pass eliminates unnecessary
4966copy operations. This flag is enabled by default at @option{-O} and
4967higher.
4968
4969@item -ftree-store-copy-prop
4970Perform copy propagation of memory loads and stores. This pass
4971eliminates unnecessary copy operations in memory references
4972(structures, global variables, arrays, etc). This flag is enabled by
4973default at @option{-O2} and higher.
4974
4975@item -ftree-salias
4976Perform structural alias analysis on trees. This flag
4977is enabled by default at @option{-O} and higher.
4978
4979@item -fipa-pta
4980Perform interprocedural pointer analysis.
4981
4982@item -ftree-sink
4983Perform forward store motion on trees. This flag is
4984enabled by default at @option{-O} and higher.
4985
4986@item -ftree-ccp
4987Perform sparse conditional constant propagation (CCP) on trees. This
4988pass only operates on local scalar variables and is enabled by default
4989at @option{-O} and higher.
4990
4991@item -ftree-store-ccp
4992Perform sparse conditional constant propagation (CCP) on trees. This
4993pass operates on both local scalar variables and memory stores and
4994loads (global variables, structures, arrays, etc). This flag is
4995enabled by default at @option{-O2} and higher.
4996
4997@item -ftree-dce
4998Perform dead code elimination (DCE) on trees. This flag is enabled by
4999default at @option{-O} and higher.
5000
5001@item -ftree-dominator-opts
5002Perform a variety of simple scalar cleanups (constant/copy
5003propagation, redundancy elimination, range propagation and expression
5004simplification) based on a dominator tree traversal. This also
5005performs jump threading (to reduce jumps to jumps). This flag is
5006enabled by default at @option{-O} and higher.
5007
5008@item -ftree-ch
5009Perform loop header copying on trees. This is beneficial since it increases
5010effectiveness of code motion optimizations. It also saves one jump. This flag
5011is enabled by default at @option{-O} and higher. It is not enabled
5012for @option{-Os}, since it usually increases code size.
5013
5014@item -ftree-loop-optimize
5015Perform loop optimizations on trees. This flag is enabled by default
5016at @option{-O} and higher.
5017
5018@item -ftree-loop-linear
5019Perform linear loop transformations on tree. This flag can improve cache
5020performance and allow further loop optimizations to take place.
5021
5022@item -ftree-loop-im
5023Perform loop invariant motion on trees. This pass moves only invariants that
5024would be hard to handle at RTL level (function calls, operations that expand to
5025nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
5026operands of conditions that are invariant out of the loop, so that we can use
5027just trivial invariantness analysis in loop unswitching. The pass also includes
5028store motion.
5029
5030@item -ftree-loop-ivcanon
5031Create a canonical counter for number of iterations in the loop for that
5032determining number of iterations requires complicated analysis. Later
5033optimizations then may determine the number easily. Useful especially
5034in connection with unrolling.
5035
5036@item -fivopts
5037Perform induction variable optimizations (strength reduction, induction
5038variable merging and induction variable elimination) on trees.
5039
5040@item -ftree-sra
5041Perform scalar replacement of aggregates. This pass replaces structure
5042references with scalars to prevent committing structures to memory too
5043early. This flag is enabled by default at @option{-O} and higher.
5044
5045@item -ftree-copyrename
5046Perform copy renaming on trees. This pass attempts to rename compiler
5047temporaries to other variables at copy locations, usually resulting in
5048variable names which more closely resemble the original variables. This flag
5049is enabled by default at @option{-O} and higher.
5050
5051@item -ftree-ter
5052Perform temporary expression replacement during the SSA->normal phase. Single
5053use/single def temporaries are replaced at their use location with their
5054defining expression. This results in non-GIMPLE code, but gives the expanders
5055much more complex trees to work on resulting in better RTL generation. This is
5056enabled by default at @option{-O} and higher.
5057
5058@item -ftree-lrs
5059Perform live range splitting during the SSA->normal phase. Distinct live
5060ranges of a variable are split into unique variables, allowing for better
5061optimization later. This is enabled by default at @option{-O} and higher.
5062
5063@item -ftree-vectorize
5064Perform loop vectorization on trees.
5065
5066@item -ftree-vect-loop-version
5067@opindex ftree-vect-loop-version
5068Perform loop versioning when doing loop vectorization on trees. When a loop
5069appears to be vectorizable except that data alignment or data dependence cannot
5070be determined at compile time then vectorized and non-vectorized versions of
5071the loop are generated along with runtime checks for alignment or dependence
5072to control which version is executed. This option is enabled by default
5073except at level @option{-Os} where it is disabled.
5074
5075@item -ftree-vrp
5076Perform Value Range Propagation on trees. This is similar to the
5077constant propagation pass, but instead of values, ranges of values are
5078propagated. This allows the optimizers to remove unnecessary range
5079checks like array bound checks and null pointer checks. This is
5080enabled by default at @option{-O2} and higher. Null pointer check
5081elimination is only done if @option{-fdelete-null-pointer-checks} is
5082enabled.
5083
5084@item -ftracer
5085@opindex ftracer
5086Perform tail duplication to enlarge superblock size. This transformation
5087simplifies the control flow of the function allowing other optimizations to do
5088better job.
5089
5090@item -funroll-loops
5091@opindex funroll-loops
5092Unroll loops whose number of iterations can be determined at compile
5093time or upon entry to the loop. @option{-funroll-loops} implies
5094@option{-frerun-cse-after-loop}. This option makes code larger,
5095and may or may not make it run faster.
5096
5097@item -funroll-all-loops
5098@opindex funroll-all-loops
5099Unroll all loops, even if their number of iterations is uncertain when
5100the loop is entered. This usually makes programs run more slowly.
5101@option{-funroll-all-loops} implies the same options as
5102@option{-funroll-loops},
5103
5104@item -fsplit-ivs-in-unroller
5105@opindex fsplit-ivs-in-unroller
5106Enables expressing of values of induction variables in later iterations
5107of the unrolled loop using the value in the first iteration. This breaks
5108long dependency chains, thus improving efficiency of the scheduling passes.
5109
5110Combination of @option{-fweb} and CSE is often sufficient to obtain the
5111same effect. However in cases the loop body is more complicated than
5112a single basic block, this is not reliable. It also does not work at all
5113on some of the architectures due to restrictions in the CSE pass.
5114
5115This optimization is enabled by default.
5116
5117@item -fvariable-expansion-in-unroller
5118@opindex fvariable-expansion-in-unroller
5119With this option, the compiler will create multiple copies of some
5120local variables when unrolling a loop which can result in superior code.
5121
5122@item -fprefetch-loop-arrays
5123@opindex fprefetch-loop-arrays
5124If supported by the target machine, generate instructions to prefetch
5125memory to improve the performance of loops that access large arrays.
5126
5127This option may generate better or worse code; results are highly
5128dependent on the structure of loops within the source code.
5129
5130Disabled at level @option{-Os}.
5131
5132@item -fno-peephole
5133@itemx -fno-peephole2
5134@opindex fno-peephole
5135@opindex fno-peephole2
5136Disable any machine-specific peephole optimizations. The difference
5137between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
5138are implemented in the compiler; some targets use one, some use the
5139other, a few use both.
5140
5141@option{-fpeephole} is enabled by default.
5142@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5143
5144@item -fno-guess-branch-probability
5145@opindex fno-guess-branch-probability
5146Do not guess branch probabilities using heuristics.
5147
5148GCC will use heuristics to guess branch probabilities if they are
5149not provided by profiling feedback (@option{-fprofile-arcs}). These
5150heuristics are based on the control flow graph. If some branch probabilities
5151are specified by @samp{__builtin_expect}, then the heuristics will be
5152used to guess branch probabilities for the rest of the control flow graph,
5153taking the @samp{__builtin_expect} info into account. The interactions
5154between the heuristics and @samp{__builtin_expect} can be complex, and in
5155some cases, it may be useful to disable the heuristics so that the effects
5156of @samp{__builtin_expect} are easier to understand.
5157
5158The default is @option{-fguess-branch-probability} at levels
5159@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5160
5161@item -freorder-blocks
5162@opindex freorder-blocks
5163Reorder basic blocks in the compiled function in order to reduce number of
5164taken branches and improve code locality.
5165
5166Enabled at levels @option{-O2}, @option{-O3}.
5167
5168@item -freorder-blocks-and-partition
5169@opindex freorder-blocks-and-partition
5170In addition to reordering basic blocks in the compiled function, in order
5171to reduce number of taken branches, partitions hot and cold basic blocks
5172into separate sections of the assembly and .o files, to improve
5173paging and cache locality performance.
5174
5175This optimization is automatically turned off in the presence of
5176exception handling, for linkonce sections, for functions with a user-defined
5177section attribute and on any architecture that does not support named
5178sections.
5179
5180@item -freorder-functions
5181@opindex freorder-functions
5182Reorder functions in the object file in order to
5183improve code locality. This is implemented by using special
5184subsections @code{.text.hot} for most frequently executed functions and
5185@code{.text.unlikely} for unlikely executed functions. Reordering is done by
5186the linker so object file format must support named sections and linker must
5187place them in a reasonable way.
5188
5189Also profile feedback must be available in to make this option effective. See
5190@option{-fprofile-arcs} for details.
5191
5192Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5193
5194@item -fstrict-aliasing
5195@opindex fstrict-aliasing
5196Allows the compiler to assume the strictest aliasing rules applicable to
5197the language being compiled. For C (and C++), this activates
5198optimizations based on the type of expressions. In particular, an
5199object of one type is assumed never to reside at the same address as an
5200object of a different type, unless the types are almost the same. For
5201example, an @code{unsigned int} can alias an @code{int}, but not a
5202@code{void*} or a @code{double}. A character type may alias any other
5203type.
5204
5205Pay special attention to code like this:
5206@smallexample
5207union a_union @{
5208 int i;
5209 double d;
5210@};
5211
5212int f() @{
5213 a_union t;
5214 t.d = 3.0;
5215 return t.i;
5216@}
5217@end smallexample
5218The practice of reading from a different union member than the one most
5219recently written to (called ``type-punning'') is common. Even with
5220@option{-fstrict-aliasing}, type-punning is allowed, provided the memory
5221is accessed through the union type. So, the code above will work as
5222expected. However, this code might not:
5223@smallexample
5224int f() @{
5225 a_union t;
5226 int* ip;
5227 t.d = 3.0;
5228 ip = &t.i;
5229 return *ip;
5230@}
5231@end smallexample
5232
5233Every language that wishes to perform language-specific alias analysis
5234should define a function that computes, given an @code{tree}
5235node, an alias set for the node. Nodes in different alias sets are not
5236allowed to alias. For an example, see the C front-end function
5237@code{c_get_alias_set}.
5238
5239Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5240
5241@item -fstrict-overflow
5242@opindex fstrict-overflow
5243Allow the compiler to assume strict signed overflow rules, depending
5244on the language being compiled. For C (and C++) this means that
5245overflow when doing arithmetic with signed numbers is undefined, which
5246means that the compiler may assume that it will not happen. This
5247permits various optimizations. For example, the compiler will assume
5248that an expression like @code{i + 10 > i} will always be true for
5249signed @code{i}. This assumption is only valid if signed overflow is
5250undefined, as the expression is false if @code{i + 10} overflows when
5251using twos complement arithmetic. When this option is in effect any
5252attempt to determine whether an operation on signed numbers will
5253overflow must be written carefully to not actually involve overflow.
5254
5255See also the @option{-fwrapv} option. Using @option{-fwrapv} means
5256that signed overflow is fully defined: it wraps. When
5257@option{-fwrapv} is used, there is no difference between
5258@option{-fstrict-overflow} and @option{-fno-strict-overflow}. With
5259@option{-fwrapv} certain types of overflow are permitted. For
5260example, if the compiler gets an overflow when doing arithmetic on
5261constants, the overflowed value can still be used with
5262@option{-fwrapv}, but not otherwise.
5263
5264The @option{-fstrict-overflow} option is enabled at levels
5265@option{-O2}, @option{-O3}, @option{-Os}.
5266
5267@item -falign-functions
5268@itemx -falign-functions=@var{n}
5269@opindex falign-functions
5270Align the start of functions to the next power-of-two greater than
5271@var{n}, skipping up to @var{n} bytes. For instance,
5272@option{-falign-functions=32} aligns functions to the next 32-byte
5273boundary, but @option{-falign-functions=24} would align to the next
527432-byte boundary only if this can be done by skipping 23 bytes or less.
5275
5276@option{-fno-align-functions} and @option{-falign-functions=1} are
5277equivalent and mean that functions will not be aligned.
5278
5279Some assemblers only support this flag when @var{n} is a power of two;
5280in that case, it is rounded up.
5281
5282If @var{n} is not specified or is zero, use a machine-dependent default.
5283
5284Enabled at levels @option{-O2}, @option{-O3}.
5285
5286@item -falign-labels
5287@itemx -falign-labels=@var{n}
5288@opindex falign-labels
5289Align all branch targets to a power-of-two boundary, skipping up to
5290@var{n} bytes like @option{-falign-functions}. This option can easily
5291make code slower, because it must insert dummy operations for when the
5292branch target is reached in the usual flow of the code.
5293
5294@option{-fno-align-labels} and @option{-falign-labels=1} are
5295equivalent and mean that labels will not be aligned.
5296
5297If @option{-falign-loops} or @option{-falign-jumps} are applicable and
5298are greater than this value, then their values are used instead.
5299
5300If @var{n} is not specified or is zero, use a machine-dependent default
5301which is very likely to be @samp{1}, meaning no alignment.
5302
5303Enabled at levels @option{-O2}, @option{-O3}.
5304
5305@item -falign-loops
5306@itemx -falign-loops=@var{n}
5307@opindex falign-loops
5308Align loops to a power-of-two boundary, skipping up to @var{n} bytes
5309like @option{-falign-functions}. The hope is that the loop will be
5310executed many times, which will make up for any execution of the dummy
5311operations.
5312
5313@option{-fno-align-loops} and @option{-falign-loops=1} are
5314equivalent and mean that loops will not be aligned.
5315
5316If @var{n} is not specified or is zero, use a machine-dependent default.
5317
5318Enabled at levels @option{-O2}, @option{-O3}.
5319
5320@item -falign-jumps
5321@itemx -falign-jumps=@var{n}
5322@opindex falign-jumps
5323Align branch targets to a power-of-two boundary, for branch targets
5324where the targets can only be reached by jumping, skipping up to @var{n}
5325bytes like @option{-falign-functions}. In this case, no dummy operations
5326need be executed.
5327
5328@option{-fno-align-jumps} and @option{-falign-jumps=1} are
5329equivalent and mean that loops will not be aligned.
5330
5331If @var{n} is not specified or is zero, use a machine-dependent default.
5332
5333Enabled at levels @option{-O2}, @option{-O3}.
5334
5335@item -funit-at-a-time
5336@opindex funit-at-a-time
5337Parse the whole compilation unit before starting to produce code.
5338This allows some extra optimizations to take place but consumes
5339more memory (in general). There are some compatibility issues
5340with @emph{unit-at-a-time} mode:
5341@itemize @bullet
5342@item
5343enabling @emph{unit-at-a-time} mode may change the order
5344in which functions, variables, and top-level @code{asm} statements
5345are emitted, and will likely break code relying on some particular
5346ordering. The majority of such top-level @code{asm} statements,
5347though, can be replaced by @code{section} attributes. The
5348@option{fno-toplevel-reorder} option may be used to keep the ordering
5349used in the input file, at the cost of some optimizations.
5350
5351@item
5352@emph{unit-at-a-time} mode removes unreferenced static variables
5353and functions. This may result in undefined references
5354when an @code{asm} statement refers directly to variables or functions
5355that are otherwise unused. In that case either the variable/function
5356shall be listed as an operand of the @code{asm} statement operand or,
5357in the case of top-level @code{asm} statements the attribute @code{used}
5358shall be used on the declaration.
5359
5360@item
5361Static functions now can use non-standard passing conventions that
5362may break @code{asm} statements calling functions directly. Again,
5363attribute @code{used} will prevent this behavior.
5364@end itemize
5365
5366As a temporary workaround, @option{-fno-unit-at-a-time} can be used,
5367but this scheme may not be supported by future releases of GCC@.
5368
5369Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5370
5371@item -fno-toplevel-reorder
5372Do not reorder top-level functions, variables, and @code{asm}
5373statements. Output them in the same order that they appear in the
5374input file. When this option is used, unreferenced static variables
5375will not be removed. This option is intended to support existing code
5376which relies on a particular ordering. For new code, it is better to
5377use attributes.
5378
5379@item -fweb
5380@opindex fweb
5381Constructs webs as commonly used for register allocation purposes and assign
5382each web individual pseudo register. This allows the register allocation pass
5383to operate on pseudos directly, but also strengthens several other optimization
5384passes, such as CSE, loop optimizer and trivial dead code remover. It can,
5385however, make debugging impossible, since variables will no longer stay in a
5386``home register''.
5387
5388Enabled by default with @option{-funroll-loops}.
5389
5390@item -fwhole-program
5391@opindex fwhole-program
5392Assume that the current compilation unit represents whole program being
5393compiled. All public functions and variables with the exception of @code{main}
5394and those merged by attribute @code{externally_visible} become static functions
5395and in a affect gets more aggressively optimized by interprocedural optimizers.
5396While this option is equivalent to proper use of @code{static} keyword for
5397programs consisting of single file, in combination with option
5398@option{--combine} this flag can be used to compile most of smaller scale C
5399programs since the functions and variables become local for the whole combined
5400compilation unit, not for the single source file itself.
5401
5402
5403@item -fno-cprop-registers
5404@opindex fno-cprop-registers
5405After register allocation and post-register allocation instruction splitting,
5406we perform a copy-propagation pass to try to reduce scheduling dependencies
5407and occasionally eliminate the copy.
5408
5409Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5410
5411@item -fprofile-generate
5412@opindex fprofile-generate
5413
5414Enable options usually used for instrumenting application to produce
5415profile useful for later recompilation with profile feedback based
5416optimization. You must use @option{-fprofile-generate} both when
5417compiling and when linking your program.
5418
5419The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
5420
5421@item -fprofile-use
5422@opindex fprofile-use
5423Enable profile feedback directed optimizations, and optimizations
5424generally profitable only with profile feedback available.
5425
5426The following options are enabled: @code{-fbranch-probabilities}, @code{-fvpt},
5427@code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}
5428
5429@end table
5430
5431The following options control compiler behavior regarding floating
5432point arithmetic. These options trade off between speed and
5433correctness. All must be specifically enabled.
5434
5435@table @gcctabopt
5436@item -ffloat-store
5437@opindex ffloat-store
5438Do not store floating point variables in registers, and inhibit other
5439options that might change whether a floating point value is taken from a
5440register or memory.
5441
5442@cindex floating point precision
5443This option prevents undesirable excess precision on machines such as
5444the 68000 where the floating registers (of the 68881) keep more
5445precision than a @code{double} is supposed to have. Similarly for the
5446x86 architecture. For most programs, the excess precision does only
5447good, but a few programs rely on the precise definition of IEEE floating
5448point. Use @option{-ffloat-store} for such programs, after modifying
5449them to store all pertinent intermediate computations into variables.
5450
5451@item -ffast-math
5452@opindex ffast-math
5453Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
5454@option{-fno-trapping-math}, @option{-ffinite-math-only},
5455@option{-fno-rounding-math}, @option{-fno-signaling-nans}
5456and @option{fcx-limited-range}.
5457
5458This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
5459
5460This option should never be turned on by any @option{-O} option since
5461it can result in incorrect output for programs which depend on
5462an exact implementation of IEEE or ISO rules/specifications for
5463math functions.
5464
5465@item -fno-math-errno
5466@opindex fno-math-errno
5467Do not set ERRNO after calling math functions that are executed
5468with a single instruction, e.g., sqrt. A program that relies on
5469IEEE exceptions for math error handling may want to use this flag
5470for speed while maintaining IEEE arithmetic compatibility.
5471
5472This option should never be turned on by any @option{-O} option since
5473it can result in incorrect output for programs which depend on
5474an exact implementation of IEEE or ISO rules/specifications for
5475math functions.
5476
5477The default is @option{-fmath-errno}.
5478
5479On Darwin and FreeBSD systems, the math library never sets @code{errno}.
5480There is therefore
5481no reason for the compiler to consider the possibility that it might,
5482and @option{-fno-math-errno} is the default.
5483
5484@item -funsafe-math-optimizations
5485@opindex funsafe-math-optimizations
5486Allow optimizations for floating-point arithmetic that (a) assume
5487that arguments and results are valid and (b) may violate IEEE or
5488ANSI standards. When used at link-time, it may include libraries
5489or startup files that change the default FPU control word or other
5490similar optimizations.
5491
5492This option should never be turned on by any @option{-O} option since
5493it can result in incorrect output for programs which depend on
5494an exact implementation of IEEE or ISO rules/specifications for
5495math functions.
5496
5497The default is @option{-fno-unsafe-math-optimizations}.
5498
5499@item -ffinite-math-only
5500@opindex ffinite-math-only
5501Allow optimizations for floating-point arithmetic that assume
5502that arguments and results are not NaNs or +-Infs.
5503
5504This option should never be turned on by any @option{-O} option since
5505it can result in incorrect output for programs which depend on
5506an exact implementation of IEEE or ISO rules/specifications.
5507
5508The default is @option{-fno-finite-math-only}.
5509
5510@item -fno-trapping-math
5511@opindex fno-trapping-math
5512Compile code assuming that floating-point operations cannot generate
5513user-visible traps. These traps include division by zero, overflow,
5514underflow, inexact result and invalid operation. This option implies
5515@option{-fno-signaling-nans}. Setting this option may allow faster
5516code if one relies on ``non-stop'' IEEE arithmetic, for example.
5517
5518This option should never be turned on by any @option{-O} option since
5519it can result in incorrect output for programs which depend on
5520an exact implementation of IEEE or ISO rules/specifications for
5521math functions.
5522
5523The default is @option{-ftrapping-math}.
5524
5525@item -frounding-math
5526@opindex frounding-math
5527Disable transformations and optimizations that assume default floating
5528point rounding behavior. This is round-to-zero for all floating point
5529to integer conversions, and round-to-nearest for all other arithmetic
5530truncations. This option should be specified for programs that change
5531the FP rounding mode dynamically, or that may be executed with a
5532non-default rounding mode. This option disables constant folding of
5533floating point expressions at compile-time (which may be affected by
5534rounding mode) and arithmetic transformations that are unsafe in the
5535presence of sign-dependent rounding modes.
5536
5537The default is @option{-fno-rounding-math}.
5538
5539This option is experimental and does not currently guarantee to
5540disable all GCC optimizations that are affected by rounding mode.
5541Future versions of GCC may provide finer control of this setting
5542using C99's @code{FENV_ACCESS} pragma. This command line option
5543will be used to specify the default state for @code{FENV_ACCESS}.
5544
5545@item -frtl-abstract-sequences
5546@opindex frtl-abstract-sequences
5547It is a size optimization method. This option is to find identical
5548sequences of code, which can be turned into pseudo-procedures and
5549then replace all occurrences with calls to the newly created
5550subroutine. It is kind of an opposite of @option{-finline-functions}.
5551This optimization runs at RTL level.
5552
5553@item -fsignaling-nans
5554@opindex fsignaling-nans
5555Compile code assuming that IEEE signaling NaNs may generate user-visible
5556traps during floating-point operations. Setting this option disables
5557optimizations that may change the number of exceptions visible with
5558signaling NaNs. This option implies @option{-ftrapping-math}.
5559
5560This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
5561be defined.
5562
5563The default is @option{-fno-signaling-nans}.
5564
5565This option is experimental and does not currently guarantee to
5566disable all GCC optimizations that affect signaling NaN behavior.
5567
5568@item -fsingle-precision-constant
5569@opindex fsingle-precision-constant
5570Treat floating point constant as single precision constant instead of
5571implicitly converting it to double precision constant.
5572
5573@item -fcx-limited-range
5574@itemx -fno-cx-limited-range
5575@opindex fcx-limited-range
5576@opindex fno-cx-limited-range
5577When enabled, this option states that a range reduction step is not
5578needed when performing complex division. The default is
5579@option{-fno-cx-limited-range}, but is enabled by @option{-ffast-math}.
5580
5581This option controls the default setting of the ISO C99
5582@code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to
5583all languages.
5584
5585@end table
5586
5587The following options control optimizations that may improve
5588performance, but are not enabled by any @option{-O} options. This
5589section includes experimental options that may produce broken code.
5590
5591@table @gcctabopt
5592@item -fbranch-probabilities
5593@opindex fbranch-probabilities
5594After running a program compiled with @option{-fprofile-arcs}
5595(@pxref{Debugging Options,, Options for Debugging Your Program or
5596@command{gcc}}), you can compile it a second time using
5597@option{-fbranch-probabilities}, to improve optimizations based on
5598the number of times each branch was taken. When the program
5599compiled with @option{-fprofile-arcs} exits it saves arc execution
5600counts to a file called @file{@var{sourcename}.gcda} for each source
5601file The information in this data file is very dependent on the
5602structure of the generated code, so you must use the same source code
5603and the same optimization options for both compilations.
5604
5605With @option{-fbranch-probabilities}, GCC puts a
5606@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
5607These can be used to improve optimization. Currently, they are only
5608used in one place: in @file{reorg.c}, instead of guessing which path a
5609branch is mostly to take, the @samp{REG_BR_PROB} values are used to
5610exactly determine which path is taken more often.
5611
5612@item -fprofile-values
5613@opindex fprofile-values
5614If combined with @option{-fprofile-arcs}, it adds code so that some
5615data about values of expressions in the program is gathered.
5616
5617With @option{-fbranch-probabilities}, it reads back the data gathered
5618from profiling values of expressions and adds @samp{REG_VALUE_PROFILE}
5619notes to instructions for their later usage in optimizations.
5620
5621Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
5622
5623@item -fvpt
5624@opindex fvpt
5625If combined with @option{-fprofile-arcs}, it instructs the compiler to add
5626a code to gather information about values of expressions.
5627
5628With @option{-fbranch-probabilities}, it reads back the data gathered
5629and actually performs the optimizations based on them.
5630Currently the optimizations include specialization of division operation
5631using the knowledge about the value of the denominator.
5632
5633@item -frename-registers
5634@opindex frename-registers
5635Attempt to avoid false dependencies in scheduled code by making use
5636of registers left over after register allocation. This optimization
5637will most benefit processors with lots of registers. Depending on the
5638debug information format adopted by the target, however, it can
5639make debugging impossible, since variables will no longer stay in
5640a ``home register''.
5641
5642Enabled by default with @option{-funroll-loops}.
5643
5644@item -ftracer
5645@opindex ftracer
5646Perform tail duplication to enlarge superblock size. This transformation
5647simplifies the control flow of the function allowing other optimizations to do
5648better job.
5649
5650Enabled with @option{-fprofile-use}.
5651
5652@item -funroll-loops
5653@opindex funroll-loops
5654Unroll loops whose number of iterations can be determined at compile time or
5655upon entry to the loop. @option{-funroll-loops} implies
5656@option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.
5657It also turns on complete loop peeling (i.e.@: complete removal of loops with
5658small constant number of iterations). This option makes code larger, and may
5659or may not make it run faster.
5660
5661Enabled with @option{-fprofile-use}.
5662
5663@item -funroll-all-loops
5664@opindex funroll-all-loops
5665Unroll all loops, even if their number of iterations is uncertain when
5666the loop is entered. This usually makes programs run more slowly.
5667@option{-funroll-all-loops} implies the same options as
5668@option{-funroll-loops}.
5669
5670@item -fpeel-loops
5671@opindex fpeel-loops
5672Peels the loops for that there is enough information that they do not
5673roll much (from profile feedback). It also turns on complete loop peeling
5674(i.e.@: complete removal of loops with small constant number of iterations).
5675
5676Enabled with @option{-fprofile-use}.
5677
5678@item -fmove-loop-invariants
5679@opindex fmove-loop-invariants
5680Enables the loop invariant motion pass in the RTL loop optimizer. Enabled
5681at level @option{-O1}
5682
5683@item -funswitch-loops
5684@opindex funswitch-loops
5685Move branches with loop invariant conditions out of the loop, with duplicates
5686of the loop on both branches (modified according to result of the condition).
5687
5688@item -ffunction-sections
5689@itemx -fdata-sections
5690@opindex ffunction-sections
5691@opindex fdata-sections
5692Place each function or data item into its own section in the output
5693file if the target supports arbitrary sections. The name of the
5694function or the name of the data item determines the section's name
5695in the output file.
5696
5697Use these options on systems where the linker can perform optimizations
5698to improve locality of reference in the instruction space. Most systems
5699using the ELF object format and SPARC processors running Solaris 2 have
5700linkers with such optimizations. AIX may have these optimizations in
5701the future.
5702
5703Only use these options when there are significant benefits from doing
5704so. When you specify these options, the assembler and linker will
5705create larger object and executable files and will also be slower.
5706You will not be able to use @code{gprof} on all systems if you
5707specify this option and you may have problems with debugging if
5708you specify both this option and @option{-g}.
5709
5710@item -fbranch-target-load-optimize
5711@opindex fbranch-target-load-optimize
5712Perform branch target register load optimization before prologue / epilogue
5713threading.
5714The use of target registers can typically be exposed only during reload,
5715thus hoisting loads out of loops and doing inter-block scheduling needs
5716a separate optimization pass.
5717
5718@item -fbranch-target-load-optimize2
5719@opindex fbranch-target-load-optimize2
5720Perform branch target register load optimization after prologue / epilogue
5721threading.
5722
5723@item -fbtr-bb-exclusive
5724@opindex fbtr-bb-exclusive
5725When performing branch target register load optimization, don't reuse
5726branch target registers in within any basic block.
5727
5728@item -fstack-protector
5729Emit extra code to check for buffer overflows, such as stack smashing
5730attacks. This is done by adding a guard variable to functions with
5731vulnerable objects. This includes functions that call alloca, and
5732functions with buffers larger than 8 bytes. The guards are initialized
5733when a function is entered and then checked when the function exits.
5734If a guard check fails, an error message is printed and the program exits.
5735
5736@item -fstack-protector-all
5737Like @option{-fstack-protector} except that all functions are protected.
5738
5739@item -fsection-anchors
5740@opindex fsection-anchors
5741Try to reduce the number of symbolic address calculations by using
5742shared ``anchor'' symbols to address nearby objects. This transformation
5743can help to reduce the number of GOT entries and GOT accesses on some
5744targets.
5745
5746For example, the implementation of the following function @code{foo}:
5747
5748@smallexample
5749static int a, b, c;
5750int foo (void) @{ return a + b + c; @}
5751@end smallexample
5752
5753would usually calculate the addresses of all three variables, but if you
5754compile it with @option{-fsection-anchors}, it will access the variables
5755from a common anchor point instead. The effect is similar to the
5756following pseudocode (which isn't valid C):
5757
5758@smallexample
5759int foo (void)
5760@{
5761 register int *xr = &x;
5762 return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
5763@}
5764@end smallexample
5765
5766Not all targets support this option.
5767
5768@item --param @var{name}=@var{value}
5769@opindex param
5770In some places, GCC uses various constants to control the amount of
5771optimization that is done. For example, GCC will not inline functions
5772that contain more that a certain number of instructions. You can
5773control some of these constants on the command-line using the
5774@option{--param} option.
5775
5776The names of specific parameters, and the meaning of the values, are
5777tied to the internals of the compiler, and are subject to change
5778without notice in future releases.
5779
5780In each case, the @var{value} is an integer. The allowable choices for
5781@var{name} are given in the following table:
5782
5783@table @gcctabopt
5784@item salias-max-implicit-fields
5785The maximum number of fields in a variable without direct
5786structure accesses for which structure aliasing will consider trying
5787to track each field. The default is 5
5788
5789@item salias-max-array-elements
5790The maximum number of elements an array can have and its elements
5791still be tracked individually by structure aliasing. The default is 4
5792
5793@item sra-max-structure-size
5794The maximum structure size, in bytes, at which the scalar replacement
5795of aggregates (SRA) optimization will perform block copies. The
5796default value, 0, implies that GCC will select the most appropriate
5797size itself.
5798
5799@item sra-field-structure-ratio
5800The threshold ratio (as a percentage) between instantiated fields and
5801the complete structure size. We say that if the ratio of the number
5802of bytes in instantiated fields to the number of bytes in the complete
5803structure exceeds this parameter, then block copies are not used. The
5804default is 75.
5805
5806@item max-crossjump-edges
5807The maximum number of incoming edges to consider for crossjumping.
5808The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
5809the number of edges incoming to each block. Increasing values mean
5810more aggressive optimization, making the compile time increase with
5811probably small improvement in executable size.
5812
5813@item min-crossjump-insns
5814The minimum number of instructions which must be matched at the end
5815of two blocks before crossjumping will be performed on them. This
5816value is ignored in the case where all instructions in the block being
5817crossjumped from are matched. The default value is 5.
5818
5819@item max-grow-copy-bb-insns
5820The maximum code size expansion factor when copying basic blocks
5821instead of jumping. The expansion is relative to a jump instruction.
5822The default value is 8.
5823
5824@item max-goto-duplication-insns
5825The maximum number of instructions to duplicate to a block that jumps
5826to a computed goto. To avoid @math{O(N^2)} behavior in a number of
5827passes, GCC factors computed gotos early in the compilation process,
5828and unfactors them as late as possible. Only computed jumps at the
5829end of a basic blocks with no more than max-goto-duplication-insns are
5830unfactored. The default value is 8.
5831
5832@item max-delay-slot-insn-search
5833The maximum number of instructions to consider when looking for an
5834instruction to fill a delay slot. If more than this arbitrary number of
5835instructions is searched, the time savings from filling the delay slot
5836will be minimal so stop searching. Increasing values mean more
5837aggressive optimization, making the compile time increase with probably
5838small improvement in executable run time.
5839
5840@item max-delay-slot-live-search
5841When trying to fill delay slots, the maximum number of instructions to
5842consider when searching for a block with valid live register
5843information. Increasing this arbitrarily chosen value means more
5844aggressive optimization, increasing the compile time. This parameter
5845should be removed when the delay slot code is rewritten to maintain the
5846control-flow graph.
5847
5848@item max-gcse-memory
5849The approximate maximum amount of memory that will be allocated in
5850order to perform the global common subexpression elimination
5851optimization. If more memory than specified is required, the
5852optimization will not be done.
5853
5854@item max-gcse-passes
5855The maximum number of passes of GCSE to run. The default is 1.
5856
5857@item max-pending-list-length
5858The maximum number of pending dependencies scheduling will allow
5859before flushing the current state and starting over. Large functions
5860with few branches or calls can create excessively large lists which
5861needlessly consume memory and resources.
5862
5863@item max-inline-insns-single
5864Several parameters control the tree inliner used in gcc.
5865This number sets the maximum number of instructions (counted in GCC's
5866internal representation) in a single function that the tree inliner
5867will consider for inlining. This only affects functions declared
5868inline and methods implemented in a class declaration (C++).
5869The default value is 450.
5870
5871@item max-inline-insns-auto
5872When you use @option{-finline-functions} (included in @option{-O3}),
5873a lot of functions that would otherwise not be considered for inlining
5874by the compiler will be investigated. To those functions, a different
5875(more restrictive) limit compared to functions declared inline can
5876be applied.
5877The default value is 90.
5878
5879@item large-function-insns
5880The limit specifying really large functions. For functions larger than this
5881limit after inlining inlining is constrained by
5882@option{--param large-function-growth}. This parameter is useful primarily
5883to avoid extreme compilation time caused by non-linear algorithms used by the
5884backend.
5885This parameter is ignored when @option{-funit-at-a-time} is not used.
5886The default value is 2700.
5887
5888@item large-function-growth
5889Specifies maximal growth of large function caused by inlining in percents.
5890This parameter is ignored when @option{-funit-at-a-time} is not used.
5891The default value is 100 which limits large function growth to 2.0 times
5892the original size.
5893
5894@item large-unit-insns
5895The limit specifying large translation unit. Growth caused by inlining of
5896units larger than this limit is limited by @option{--param inline-unit-growth}.
5897For small units this might be too tight (consider unit consisting of function A
5898that is inline and B that just calls A three time. If B is small relative to
5899A, the growth of unit is 300\% and yet such inlining is very sane. For very
5900large units consisting of small inlininable functions however the overall unit
5901growth limit is needed to avoid exponential explosion of code size. Thus for
5902smaller units, the size is increased to @option{--param large-unit-insns}
5903before applying @option{--param inline-unit-growth}. The default is 10000
5904
5905@item inline-unit-growth
5906Specifies maximal overall growth of the compilation unit caused by inlining.
5907This parameter is ignored when @option{-funit-at-a-time} is not used.
5908The default value is 50 which limits unit growth to 1.5 times the original
5909size.
5910
5911@item max-inline-insns-recursive
5912@itemx max-inline-insns-recursive-auto
5913Specifies maximum number of instructions out-of-line copy of self recursive inline
5914function can grow into by performing recursive inlining.
5915
5916For functions declared inline @option{--param max-inline-insns-recursive} is
5917taken into account. For function not declared inline, recursive inlining
5918happens only when @option{-finline-functions} (included in @option{-O3}) is
5919enabled and @option{--param max-inline-insns-recursive-auto} is used. The
5920default value is 450.
5921
5922@item max-inline-recursive-depth
5923@itemx max-inline-recursive-depth-auto
5924Specifies maximum recursion depth used by the recursive inlining.
5925
5926For functions declared inline @option{--param max-inline-recursive-depth} is
5927taken into account. For function not declared inline, recursive inlining
5928happens only when @option{-finline-functions} (included in @option{-O3}) is
5929enabled and @option{--param max-inline-recursive-depth-auto} is used. The
5930default value is 450.
5931
5932@item min-inline-recursive-probability
5933Recursive inlining is profitable only for function having deep recursion
5934in average and can hurt for function having little recursion depth by
5935increasing the prologue size or complexity of function body to other
5936optimizers.
5937
5938When profile feedback is available (see @option{-fprofile-generate}) the actual
5939recursion depth can be guessed from probability that function will recurse via
5940given call expression. This parameter limits inlining only to call expression
5941whose probability exceeds given threshold (in percents). The default value is
594210.
5943
5944@item inline-call-cost
5945Specify cost of call instruction relative to simple arithmetics operations
5946(having cost of 1). Increasing this cost disqualifies inlining of non-leaf
5947functions and at the same time increases size of leaf function that is believed to
5948reduce function size by being inlined. In effect it increases amount of
5949inlining for code having large abstraction penalty (many functions that just
5950pass the arguments to other functions) and decrease inlining for code with low
5951abstraction penalty. The default value is 16.
5952
5953@item max-unrolled-insns
5954The maximum number of instructions that a loop should have if that loop
5955is unrolled, and if the loop is unrolled, it determines how many times
5956the loop code is unrolled.
5957
5958@item max-average-unrolled-insns
5959The maximum number of instructions biased by probabilities of their execution
5960that a loop should have if that loop is unrolled, and if the loop is unrolled,
5961it determines how many times the loop code is unrolled.
5962
5963@item max-unroll-times
5964The maximum number of unrollings of a single loop.
5965
5966@item max-peeled-insns
5967The maximum number of instructions that a loop should have if that loop
5968is peeled, and if the loop is peeled, it determines how many times
5969the loop code is peeled.
5970
5971@item max-peel-times
5972The maximum number of peelings of a single loop.
5973
5974@item max-completely-peeled-insns
5975The maximum number of insns of a completely peeled loop.
5976
5977@item max-completely-peel-times
5978The maximum number of iterations of a loop to be suitable for complete peeling.
5979
5980@item max-unswitch-insns
5981The maximum number of insns of an unswitched loop.
5982
5983@item max-unswitch-level
5984The maximum number of branches unswitched in a single loop.
5985
5986@item lim-expensive
5987The minimum cost of an expensive expression in the loop invariant motion.
5988
5989@item iv-consider-all-candidates-bound
5990Bound on number of candidates for induction variables below that
5991all candidates are considered for each use in induction variable
5992optimizations. Only the most relevant candidates are considered
5993if there are more candidates, to avoid quadratic time complexity.
5994
5995@item iv-max-considered-uses
5996The induction variable optimizations give up on loops that contain more
5997induction variable uses.
5998
5999@item iv-always-prune-cand-set-bound
6000If number of candidates in the set is smaller than this value,
6001we always try to remove unnecessary ivs from the set during its
6002optimization when a new iv is added to the set.
6003
6004@item scev-max-expr-size
6005Bound on size of expressions used in the scalar evolutions analyzer.
6006Large expressions slow the analyzer.
6007
6008@item vect-max-version-checks
6009The maximum number of runtime checks that can be performed when doing
6010loop versioning in the vectorizer. See option ftree-vect-loop-version
6011for more information.
6012
6013@item max-iterations-to-track
6014
6015The maximum number of iterations of a loop the brute force algorithm
6016for analysis of # of iterations of the loop tries to evaluate.
6017
6018@item hot-bb-count-fraction
6019Select fraction of the maximal count of repetitions of basic block in program
6020given basic block needs to have to be considered hot.
6021
6022@item hot-bb-frequency-fraction
6023Select fraction of the maximal frequency of executions of basic block in
6024function given basic block needs to have to be considered hot
6025
6026@item max-predicted-iterations
6027The maximum number of loop iterations we predict statically. This is useful
6028in cases where function contain single loop with known bound and other loop
6029with unknown. We predict the known number of iterations correctly, while
6030the unknown number of iterations average to roughly 10. This means that the
6031loop without bounds would appear artificially cold relative to the other one.
6032
6033@item tracer-dynamic-coverage
6034@itemx tracer-dynamic-coverage-feedback
6035
6036This value is used to limit superblock formation once the given percentage of
6037executed instructions is covered. This limits unnecessary code size
6038expansion.
6039
6040The @option{tracer-dynamic-coverage-feedback} is used only when profile
6041feedback is available. The real profiles (as opposed to statically estimated
6042ones) are much less balanced allowing the threshold to be larger value.
6043
6044@item tracer-max-code-growth
6045Stop tail duplication once code growth has reached given percentage. This is
6046rather hokey argument, as most of the duplicates will be eliminated later in
6047cross jumping, so it may be set to much higher values than is the desired code
6048growth.
6049
6050@item tracer-min-branch-ratio
6051
6052Stop reverse growth when the reverse probability of best edge is less than this
6053threshold (in percent).
6054
6055@item tracer-min-branch-ratio
6056@itemx tracer-min-branch-ratio-feedback
6057
6058Stop forward growth if the best edge do have probability lower than this
6059threshold.
6060
6061Similarly to @option{tracer-dynamic-coverage} two values are present, one for
6062compilation for profile feedback and one for compilation without. The value
6063for compilation with profile feedback needs to be more conservative (higher) in
6064order to make tracer effective.
6065
6066@item max-cse-path-length
6067
6068Maximum number of basic blocks on path that cse considers. The default is 10.
6069
6070@item max-cse-insns
6071The maximum instructions CSE process before flushing. The default is 1000.
6072
6073@item global-var-threshold
6074
6075Counts the number of function calls (@var{n}) and the number of
6076call-clobbered variables (@var{v}). If @var{n}x@var{v} is larger than this limit, a
6077single artificial variable will be created to represent all the
6078call-clobbered variables at function call sites. This artificial
6079variable will then be made to alias every call-clobbered variable.
6080(done as @code{int * size_t} on the host machine; beware overflow).
6081
6082@item max-aliased-vops
6083
6084Maximum number of virtual operands allowed to represent aliases
6085before triggering the alias grouping heuristic. Alias grouping
6086reduces compile times and memory consumption needed for aliasing at
6087the expense of precision loss in alias information.
6088
6089@item ggc-min-expand
6090
6091GCC uses a garbage collector to manage its own memory allocation. This
6092parameter specifies the minimum percentage by which the garbage
6093collector's heap should be allowed to expand between collections.
6094Tuning this may improve compilation speed; it has no effect on code
6095generation.
6096
6097The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
6098RAM >= 1GB@. If @code{getrlimit} is available, the notion of "RAM" is
6099the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If
6100GCC is not able to calculate RAM on a particular platform, the lower
6101bound of 30% is used. Setting this parameter and
6102@option{ggc-min-heapsize} to zero causes a full collection to occur at
6103every opportunity. This is extremely slow, but can be useful for
6104debugging.
6105
6106@item ggc-min-heapsize
6107
6108Minimum size of the garbage collector's heap before it begins bothering
6109to collect garbage. The first collection occurs after the heap expands
6110by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again,
6111tuning this may improve compilation speed, and has no effect on code
6112generation.
6113
6114The default is the smaller of RAM/8, RLIMIT_RSS, or a limit which
6115tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
6116with a lower bound of 4096 (four megabytes) and an upper bound of
6117131072 (128 megabytes). If GCC is not able to calculate RAM on a
6118particular platform, the lower bound is used. Setting this parameter
6119very large effectively disables garbage collection. Setting this
6120parameter and @option{ggc-min-expand} to zero causes a full collection
6121to occur at every opportunity.
6122
6123@item max-reload-search-insns
6124The maximum number of instruction reload should look backward for equivalent
6125register. Increasing values mean more aggressive optimization, making the
6126compile time increase with probably slightly better performance. The default
6127value is 100.
6128
6129@item max-cselib-memory-locations
6130The maximum number of memory locations cselib should take into account.
6131Increasing values mean more aggressive optimization, making the compile time
6132increase with probably slightly better performance. The default value is 500.
6133
6134@item max-flow-memory-locations
6135Similar as @option{max-cselib-memory-locations} but for dataflow liveness.
6136The default value is 100.
6137
6138@item reorder-blocks-duplicate
6139@itemx reorder-blocks-duplicate-feedback
6140
6141Used by basic block reordering pass to decide whether to use unconditional
6142branch or duplicate the code on its destination. Code is duplicated when its
6143estimated size is smaller than this value multiplied by the estimated size of
6144unconditional jump in the hot spots of the program.
6145
6146The @option{reorder-block-duplicate-feedback} is used only when profile
6147feedback is available and may be set to higher values than
6148@option{reorder-block-duplicate} since information about the hot spots is more
6149accurate.
6150
6151@item max-sched-ready-insns
6152The maximum number of instructions ready to be issued the scheduler should
6153consider at any given time during the first scheduling pass. Increasing
6154values mean more thorough searches, making the compilation time increase
6155with probably little benefit. The default value is 100.
6156
6157@item max-sched-region-blocks
6158The maximum number of blocks in a region to be considered for
6159interblock scheduling. The default value is 10.
6160
6161@item max-sched-region-insns
6162The maximum number of insns in a region to be considered for
6163interblock scheduling. The default value is 100.
6164
6165@item min-spec-prob
6166The minimum probability (in percents) of reaching a source block
6167for interblock speculative scheduling. The default value is 40.
6168
6169@item max-sched-extend-regions-iters
6170The maximum number of iterations through CFG to extend regions.
61710 - disable region extension,
6172N - do at most N iterations.
6173The default value is 0.
6174
6175@item max-sched-insn-conflict-delay
6176The maximum conflict delay for an insn to be considered for speculative motion.
6177The default value is 3.
6178
6179@item sched-spec-prob-cutoff
6180The minimal probability of speculation success (in percents), so that
6181speculative insn will be scheduled.
6182The default value is 40.
6183
6184@item max-last-value-rtl
6185
6186The maximum size measured as number of RTLs that can be recorded in an expression
6187in combiner for a pseudo register as last known value of that register. The default
6188is 10000.
6189
6190@item integer-share-limit
6191Small integer constants can use a shared data structure, reducing the
6192compiler's memory usage and increasing its speed. This sets the maximum
6193value of a shared integer constant's. The default value is 256.
6194
6195@item min-virtual-mappings
6196Specifies the minimum number of virtual mappings in the incremental
6197SSA updater that should be registered to trigger the virtual mappings
6198heuristic defined by virtual-mappings-ratio. The default value is
6199100.
6200
6201@item virtual-mappings-ratio
6202If the number of virtual mappings is virtual-mappings-ratio bigger
6203than the number of virtual symbols to be updated, then the incremental
6204SSA updater switches to a full update for those symbols. The default
6205ratio is 3.
6206
6207@item ssp-buffer-size
6208The minimum size of buffers (i.e. arrays) that will receive stack smashing
6209protection when @option{-fstack-protection} is used.
6210
6211@item max-jump-thread-duplication-stmts
6212Maximum number of statements allowed in a block that needs to be
6213duplicated when threading jumps.
6214
6215@item max-fields-for-field-sensitive
6216Maximum number of fields in a structure we will treat in
6217a field sensitive manner during pointer analysis.
6218
6219@end table
6220@end table
6221
6222@node Preprocessor Options
6223@section Options Controlling the Preprocessor
6224@cindex preprocessor options
6225@cindex options, preprocessor
6226
6227These options control the C preprocessor, which is run on each C source
6228file before actual compilation.
6229
6230If you use the @option{-E} option, nothing is done except preprocessing.
6231Some of these options make sense only together with @option{-E} because
6232they cause the preprocessor output to be unsuitable for actual
6233compilation.
6234
6235@table @gcctabopt
6236@opindex Wp
6237You can use @option{-Wp,@var{option}} to bypass the compiler driver
6238and pass @var{option} directly through to the preprocessor. If
6239@var{option} contains commas, it is split into multiple options at the
6240commas. However, many options are modified, translated or interpreted
6241by the compiler driver before being passed to the preprocessor, and
6242@option{-Wp} forcibly bypasses this phase. The preprocessor's direct
6243interface is undocumented and subject to change, so whenever possible
6244you should avoid using @option{-Wp} and let the driver handle the
6245options instead.
6246
6247@item -Xpreprocessor @var{option}
6248@opindex preprocessor
6249Pass @var{option} as an option to the preprocessor. You can use this to
6250supply system-specific preprocessor options which GCC does not know how to
6251recognize.
6252
6253If you want to pass an option that takes an argument, you must use
6254@option{-Xpreprocessor} twice, once for the option and once for the argument.
6255@end table
6256
6257@include cppopts.texi
6258
6259@node Assembler Options
6260@section Passing Options to the Assembler
6261
6262@c prevent bad page break with this line
6263You can pass options to the assembler.
6264
6265@table @gcctabopt
6266@item -Wa,@var{option}
6267@opindex Wa
6268Pass @var{option} as an option to the assembler. If @var{option}
6269contains commas, it is split into multiple options at the commas.
6270
6271@item -Xassembler @var{option}
6272@opindex Xassembler
6273Pass @var{option} as an option to the assembler. You can use this to
6274supply system-specific assembler options which GCC does not know how to
6275recognize.
6276
6277If you want to pass an option that takes an argument, you must use
6278@option{-Xassembler} twice, once for the option and once for the argument.
6279
6280@end table
6281
6282@node Link Options
6283@section Options for Linking
6284@cindex link options
6285@cindex options, linking
6286
6287These options come into play when the compiler links object files into
6288an executable output file. They are meaningless if the compiler is
6289not doing a link step.
6290
6291@table @gcctabopt
6292@cindex file names
6293@item @var{object-file-name}
6294A file name that does not end in a special recognized suffix is
6295considered to name an object file or library. (Object files are
6296distinguished from libraries by the linker according to the file
6297contents.) If linking is done, these object files are used as input
6298to the linker.
6299
6300@item -c
6301@itemx -S
6302@itemx -E
6303@opindex c
6304@opindex S
6305@opindex E
6306If any of these options is used, then the linker is not run, and
6307object file names should not be used as arguments. @xref{Overall
6308Options}.
6309
6310@cindex Libraries
6311@item -l@var{library}
6312@itemx -l @var{library}
6313@opindex l
6314Search the library named @var{library} when linking. (The second
6315alternative with the library as a separate argument is only for
6316POSIX compliance and is not recommended.)
6317
6318It makes a difference where in the command you write this option; the
6319linker searches and processes libraries and object files in the order they
6320are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
6321after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
6322to functions in @samp{z}, those functions may not be loaded.
6323
6324The linker searches a standard list of directories for the library,
6325which is actually a file named @file{lib@var{library}.a}. The linker
6326then uses this file as if it had been specified precisely by name.
6327
6328The directories searched include several standard system directories
6329plus any that you specify with @option{-L}.
6330
6331Normally the files found this way are library files---archive files
6332whose members are object files. The linker handles an archive file by
6333scanning through it for members which define symbols that have so far
6334been referenced but not defined. But if the file that is found is an
6335ordinary object file, it is linked in the usual fashion. The only
6336difference between using an @option{-l} option and specifying a file name
6337is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
6338and searches several directories.
6339
6340@item -nostartfiles
6341@opindex nostartfiles
6342Do not use the standard system startup files when linking.
6343The standard system libraries are used normally, unless @option{-nostdlib}
6344or @option{-nodefaultlibs} is used.
6345
6346@item -nodefaultlibs
6347@opindex nodefaultlibs
6348Do not use the standard system libraries when linking.
6349Only the libraries you specify will be passed to the linker.
6350The standard startup files are used normally, unless @option{-nostartfiles}
6351is used. The compiler may generate calls to @code{memcmp},
6352@code{memset}, @code{memcpy} and @code{memmove}.
6353These entries are usually resolved by entries in
6354libc. These entry points should be supplied through some other
6355mechanism when this option is specified.
6356
6357@item -nostdlib
6358@opindex nostdlib
6359Do not use the standard system startup files or libraries when linking.
6360No startup files and only the libraries you specify will be passed to
6361the linker. The compiler may generate calls to @code{memcmp}, @code{memset},
6362@code{memcpy} and @code{memmove}.
6363These entries are usually resolved by entries in
6364libc. These entry points should be supplied through some other
6365mechanism when this option is specified.
6366
6367@cindex @option{-lgcc}, use with @option{-nostdlib}
6368@cindex @option{-nostdlib} and unresolved references
6369@cindex unresolved references and @option{-nostdlib}
6370@cindex @option{-lgcc}, use with @option{-nodefaultlibs}
6371@cindex @option{-nodefaultlibs} and unresolved references
6372@cindex unresolved references and @option{-nodefaultlibs}
6373One of the standard libraries bypassed by @option{-nostdlib} and
6374@option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
6375that GCC uses to overcome shortcomings of particular machines, or special
6376needs for some languages.
6377(@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
6378Collection (GCC) Internals},
6379for more discussion of @file{libgcc.a}.)
6380In most cases, you need @file{libgcc.a} even when you want to avoid
6381other standard libraries. In other words, when you specify @option{-nostdlib}
6382or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
6383This ensures that you have no unresolved references to internal GCC
6384library subroutines. (For example, @samp{__main}, used to ensure C++
6385constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
6386GNU Compiler Collection (GCC) Internals}.)
6387
6388@item -pie
6389@opindex pie
6390Produce a position independent executable on targets which support it.
6391For predictable results, you must also specify the same set of options
6392that were used to generate code (@option{-fpie}, @option{-fPIE},
6393or model suboptions) when you specify this option.
6394
6395@item -rdynamic
6396@opindex rdynamic
6397Pass the flag @option{-export-dynamic} to the ELF linker, on targets
6398that support it. This instructs the linker to add all symbols, not
6399only used ones, to the dynamic symbol table. This option is needed
6400for some uses of @code{dlopen} or to allow obtaining backtraces
6401from within a program.
6402
6403@item -s
6404@opindex s
6405Remove all symbol table and relocation information from the executable.
6406
6407@item -static
6408@opindex static
6409On systems that support dynamic linking, this prevents linking with the shared
6410libraries. On other systems, this option has no effect.
6411
6412@item -shared
6413@opindex shared
6414Produce a shared object which can then be linked with other objects to
6415form an executable. Not all systems support this option. For predictable
6416results, you must also specify the same set of options that were used to
6417generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
6418when you specify this option.@footnote{On some systems, @samp{gcc -shared}
6419needs to build supplementary stub code for constructors to work. On
6420multi-libbed systems, @samp{gcc -shared} must select the correct support
6421libraries to link against. Failing to supply the correct flags may lead
6422to subtle defects. Supplying them in cases where they are not necessary
6423is innocuous.}
6424
6425@item -shared-libgcc
6426@itemx -static-libgcc
6427@opindex shared-libgcc
6428@opindex static-libgcc
6429On systems that provide @file{libgcc} as a shared library, these options
6430force the use of either the shared or static version respectively.
6431If no shared version of @file{libgcc} was built when the compiler was
6432configured, these options have no effect.
6433
6434There are several situations in which an application should use the
6435shared @file{libgcc} instead of the static version. The most common
6436of these is when the application wishes to throw and catch exceptions
6437across different shared libraries. In that case, each of the libraries
6438as well as the application itself should use the shared @file{libgcc}.
6439
6440Therefore, the G++ and GCJ drivers automatically add
6441@option{-shared-libgcc} whenever you build a shared library or a main
6442executable, because C++ and Java programs typically use exceptions, so
6443this is the right thing to do.
6444
6445If, instead, you use the GCC driver to create shared libraries, you may
6446find that they will not always be linked with the shared @file{libgcc}.
6447If GCC finds, at its configuration time, that you have a non-GNU linker
6448or a GNU linker that does not support option @option{--eh-frame-hdr},
6449it will link the shared version of @file{libgcc} into shared libraries
6450by default. Otherwise, it will take advantage of the linker and optimize
6451away the linking with the shared version of @file{libgcc}, linking with
6452the static version of libgcc by default. This allows exceptions to
6453propagate through such shared libraries, without incurring relocation
6454costs at library load time.
6455
6456However, if a library or main executable is supposed to throw or catch
6457exceptions, you must link it using the G++ or GCJ driver, as appropriate
6458for the languages used in the program, or using the option
6459@option{-shared-libgcc}, such that it is linked with the shared
6460@file{libgcc}.
6461
6462@item -symbolic
6463@opindex symbolic
6464Bind references to global symbols when building a shared object. Warn
6465about any unresolved references (unless overridden by the link editor
6466option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
6467this option.
6468
6469@item -Xlinker @var{option}
6470@opindex Xlinker
6471Pass @var{option} as an option to the linker. You can use this to
6472supply system-specific linker options which GCC does not know how to
6473recognize.
6474
6475If you want to pass an option that takes an argument, you must use
6476@option{-Xlinker} twice, once for the option and once for the argument.
6477For example, to pass @option{-assert definitions}, you must write
6478@samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
6479@option{-Xlinker "-assert definitions"}, because this passes the entire
6480string as a single argument, which is not what the linker expects.
6481
6482@item -Wl,@var{option}
6483@opindex Wl
6484Pass @var{option} as an option to the linker. If @var{option} contains
6485commas, it is split into multiple options at the commas.
6486
6487@item -u @var{symbol}
6488@opindex u
6489Pretend the symbol @var{symbol} is undefined, to force linking of
6490library modules to define it. You can use @option{-u} multiple times with
6491different symbols to force loading of additional library modules.
6492@end table
6493
6494@node Directory Options
6495@section Options for Directory Search
6496@cindex directory options
6497@cindex options, directory search
6498@cindex search path
6499
6500These options specify directories to search for header files, for
6501libraries and for parts of the compiler:
6502
6503@table @gcctabopt
6504@item -I@var{dir}
6505@opindex I
6506Add the directory @var{dir} to the head of the list of directories to be
6507searched for header files. This can be used to override a system header
6508file, substituting your own version, since these directories are
6509searched before the system header file directories. However, you should
6510not use this option to add directories that contain vendor-supplied
6511system header files (use @option{-isystem} for that). If you use more than
6512one @option{-I} option, the directories are scanned in left-to-right
6513order; the standard system directories come after.
6514
6515If a standard system include directory, or a directory specified with
6516@option{-isystem}, is also specified with @option{-I}, the @option{-I}
6517option will be ignored. The directory will still be searched but as a
6518system directory at its normal position in the system include chain.
6519This is to ensure that GCC's procedure to fix buggy system headers and
6520the ordering for the include_next directive are not inadvertently changed.
6521If you really need to change the search order for system directories,
6522use the @option{-nostdinc} and/or @option{-isystem} options.
6523
6524@item -iquote@var{dir}
6525@opindex iquote
6526Add the directory @var{dir} to the head of the list of directories to
6527be searched for header files only for the case of @samp{#include
6528"@var{file}"}; they are not searched for @samp{#include <@var{file}>},
6529otherwise just like @option{-I}.
6530
6531@item -L@var{dir}
6532@opindex L
6533Add directory @var{dir} to the list of directories to be searched
6534for @option{-l}.
6535
6536@item -B@var{prefix}
6537@opindex B
6538This option specifies where to find the executables, libraries,
6539include files, and data files of the compiler itself.
6540
6541The compiler driver program runs one or more of the subprograms
6542@file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
6543@var{prefix} as a prefix for each program it tries to run, both with and
6544without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
6545
6546For each subprogram to be run, the compiler driver first tries the
6547@option{-B} prefix, if any. If that name is not found, or if @option{-B}
6548was not specified, the driver tries two standard prefixes, which are
6549@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of
6550those results in a file name that is found, the unmodified program
6551name is searched for using the directories specified in your
6552@env{PATH} environment variable.
6553
6554The compiler will check to see if the path provided by the @option{-B}
6555refers to a directory, and if necessary it will add a directory
6556separator character at the end of the path.
6557
6558@option{-B} prefixes that effectively specify directory names also apply
6559to libraries in the linker, because the compiler translates these
6560options into @option{-L} options for the linker. They also apply to
6561includes files in the preprocessor, because the compiler translates these
6562options into @option{-isystem} options for the preprocessor. In this case,
6563the compiler appends @samp{include} to the prefix.
6564
6565The run-time support file @file{libgcc.a} can also be searched for using
6566the @option{-B} prefix, if needed. If it is not found there, the two
6567standard prefixes above are tried, and that is all. The file is left
6568out of the link if it is not found by those means.
6569
6570Another way to specify a prefix much like the @option{-B} prefix is to use
6571the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
6572Variables}.
6573
6574As a special kludge, if the path provided by @option{-B} is
6575@file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
65769, then it will be replaced by @file{[dir/]include}. This is to help
6577with boot-strapping the compiler.
6578
6579@item -specs=@var{file}
6580@opindex specs
6581Process @var{file} after the compiler reads in the standard @file{specs}
6582file, in order to override the defaults that the @file{gcc} driver
6583program uses when determining what switches to pass to @file{cc1},
6584@file{cc1plus}, @file{as}, @file{ld}, etc. More than one
6585@option{-specs=@var{file}} can be specified on the command line, and they
6586are processed in order, from left to right.
6587
6588@item --sysroot=@var{dir}
6589@opindex sysroot
6590Use @var{dir} as the logical root directory for headers and libraries.
6591For example, if the compiler would normally search for headers in
6592@file{/usr/include} and libraries in @file{/usr/lib}, it will instead
6593search @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
6594
6595If you use both this option and the @option{-isysroot} option, then
6596the @option{--sysroot} option will apply to libraries, but the
6597@option{-isysroot} option will apply to header files.
6598
6599The GNU linker (beginning with version 2.16) has the necessary support
6600for this option. If your linker does not support this option, the
6601header file aspect of @option{--sysroot} will still work, but the
6602library aspect will not.
6603
6604@item -I-
6605@opindex I-
6606This option has been deprecated. Please use @option{-iquote} instead for
6607@option{-I} directories before the @option{-I-} and remove the @option{-I-}.
6608Any directories you specify with @option{-I} options before the @option{-I-}
6609option are searched only for the case of @samp{#include "@var{file}"};
6610they are not searched for @samp{#include <@var{file}>}.
6611
6612If additional directories are specified with @option{-I} options after
6613the @option{-I-}, these directories are searched for all @samp{#include}
6614directives. (Ordinarily @emph{all} @option{-I} directories are used
6615this way.)
6616
6617In addition, the @option{-I-} option inhibits the use of the current
6618directory (where the current input file came from) as the first search
6619directory for @samp{#include "@var{file}"}. There is no way to
6620override this effect of @option{-I-}. With @option{-I.} you can specify
6621searching the directory which was current when the compiler was
6622invoked. That is not exactly the same as what the preprocessor does
6623by default, but it is often satisfactory.
6624
6625@option{-I-} does not inhibit the use of the standard system directories
6626for header files. Thus, @option{-I-} and @option{-nostdinc} are
6627independent.
6628@end table
6629
6630@c man end
6631
6632@node Spec Files
6633@section Specifying subprocesses and the switches to pass to them
6634@cindex Spec Files
6635
6636@command{gcc} is a driver program. It performs its job by invoking a
6637sequence of other programs to do the work of compiling, assembling and
6638linking. GCC interprets its command-line parameters and uses these to
6639deduce which programs it should invoke, and which command-line options
6640it ought to place on their command lines. This behavior is controlled
6641by @dfn{spec strings}. In most cases there is one spec string for each
6642program that GCC can invoke, but a few programs have multiple spec
6643strings to control their behavior. The spec strings built into GCC can
6644be overridden by using the @option{-specs=} command-line switch to specify
6645a spec file.
6646
6647@dfn{Spec files} are plaintext files that are used to construct spec
6648strings. They consist of a sequence of directives separated by blank
6649lines. The type of directive is determined by the first non-whitespace
6650character on the line and it can be one of the following:
6651
6652@table @code
6653@item %@var{command}
6654Issues a @var{command} to the spec file processor. The commands that can
6655appear here are:
6656
6657@table @code
6658@item %include <@var{file}>
6659@cindex %include
6660Search for @var{file} and insert its text at the current point in the
6661specs file.
6662
6663@item %include_noerr <@var{file}>
6664@cindex %include_noerr
6665Just like @samp{%include}, but do not generate an error message if the include
6666file cannot be found.
6667
6668@item %rename @var{old_name} @var{new_name}
6669@cindex %rename
6670Rename the spec string @var{old_name} to @var{new_name}.
6671
6672@end table
6673
6674@item *[@var{spec_name}]:
6675This tells the compiler to create, override or delete the named spec
6676string. All lines after this directive up to the next directive or
6677blank line are considered to be the text for the spec string. If this
6678results in an empty string then the spec will be deleted. (Or, if the
6679spec did not exist, then nothing will happened.) Otherwise, if the spec
6680does not currently exist a new spec will be created. If the spec does
6681exist then its contents will be overridden by the text of this
6682directive, unless the first character of that text is the @samp{+}
6683character, in which case the text will be appended to the spec.
6684
6685@item [@var{suffix}]:
6686Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
6687and up to the next directive or blank line are considered to make up the
6688spec string for the indicated suffix. When the compiler encounters an
6689input file with the named suffix, it will processes the spec string in
6690order to work out how to compile that file. For example:
6691
6692@smallexample
6693.ZZ:
6694z-compile -input %i
6695@end smallexample
6696
6697This says that any input file whose name ends in @samp{.ZZ} should be
6698passed to the program @samp{z-compile}, which should be invoked with the
6699command-line switch @option{-input} and with the result of performing the
6700@samp{%i} substitution. (See below.)
6701
6702As an alternative to providing a spec string, the text that follows a
6703suffix directive can be one of the following:
6704
6705@table @code
6706@item @@@var{language}
6707This says that the suffix is an alias for a known @var{language}. This is
6708similar to using the @option{-x} command-line switch to GCC to specify a
6709language explicitly. For example:
6710
6711@smallexample
6712.ZZ:
6713@@c++
6714@end smallexample
6715
6716Says that .ZZ files are, in fact, C++ source files.
6717
6718@item #@var{name}
6719This causes an error messages saying:
6720
6721@smallexample
6722@var{name} compiler not installed on this system.
6723@end smallexample
6724@end table
6725
6726GCC already has an extensive list of suffixes built into it.
6727This directive will add an entry to the end of the list of suffixes, but
6728since the list is searched from the end backwards, it is effectively
6729possible to override earlier entries using this technique.
6730
6731@end table
6732
6733GCC has the following spec strings built into it. Spec files can
6734override these strings or create their own. Note that individual
6735targets can also add their own spec strings to this list.
6736
6737@smallexample
6738asm Options to pass to the assembler
6739asm_final Options to pass to the assembler post-processor
6740cpp Options to pass to the C preprocessor
6741cc1 Options to pass to the C compiler
6742cc1plus Options to pass to the C++ compiler
6743endfile Object files to include at the end of the link
6744link Options to pass to the linker
6745lib Libraries to include on the command line to the linker
6746libgcc Decides which GCC support library to pass to the linker
6747linker Sets the name of the linker
6748predefines Defines to be passed to the C preprocessor
6749signed_char Defines to pass to CPP to say whether @code{char} is signed
6750 by default
6751startfile Object files to include at the start of the link
6752@end smallexample
6753
6754Here is a small example of a spec file:
6755
6756@smallexample
6757%rename lib old_lib
6758
6759*lib:
6760--start-group -lgcc -lc -leval1 --end-group %(old_lib)
6761@end smallexample
6762
6763This example renames the spec called @samp{lib} to @samp{old_lib} and
6764then overrides the previous definition of @samp{lib} with a new one.
6765The new definition adds in some extra command-line options before
6766including the text of the old definition.
6767
6768@dfn{Spec strings} are a list of command-line options to be passed to their
6769corresponding program. In addition, the spec strings can contain
6770@samp{%}-prefixed sequences to substitute variable text or to
6771conditionally insert text into the command line. Using these constructs
6772it is possible to generate quite complex command lines.
6773
6774Here is a table of all defined @samp{%}-sequences for spec
6775strings. Note that spaces are not generated automatically around the
6776results of expanding these sequences. Therefore you can concatenate them
6777together or combine them with constant text in a single argument.
6778
6779@table @code
6780@item %%
6781Substitute one @samp{%} into the program name or argument.
6782
6783@item %i
6784Substitute the name of the input file being processed.
6785
6786@item %b
6787Substitute the basename of the input file being processed.
6788This is the substring up to (and not including) the last period
6789and not including the directory.
6790
6791@item %B
6792This is the same as @samp{%b}, but include the file suffix (text after
6793the last period).
6794
6795@item %d
6796Marks the argument containing or following the @samp{%d} as a
6797temporary file name, so that that file will be deleted if GCC exits
6798successfully. Unlike @samp{%g}, this contributes no text to the
6799argument.
6800
6801@item %g@var{suffix}
6802Substitute a file name that has suffix @var{suffix} and is chosen
6803once per compilation, and mark the argument in the same way as
6804@samp{%d}. To reduce exposure to denial-of-service attacks, the file
6805name is now chosen in a way that is hard to predict even when previously
6806chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
6807might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
6808the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
6809treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
6810was simply substituted with a file name chosen once per compilation,
6811without regard to any appended suffix (which was therefore treated
6812just like ordinary text), making such attacks more likely to succeed.
6813
6814@item %u@var{suffix}
6815Like @samp{%g}, but generates a new temporary file name even if
6816@samp{%u@var{suffix}} was already seen.
6817
6818@item %U@var{suffix}
6819Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
6820new one if there is no such last file name. In the absence of any
6821@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
6822the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
6823would involve the generation of two distinct file names, one
6824for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
6825simply substituted with a file name chosen for the previous @samp{%u},
6826without regard to any appended suffix.
6827
6828@item %j@var{suffix}
6829Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
6830writable, and if save-temps is off; otherwise, substitute the name
6831of a temporary file, just like @samp{%u}. This temporary file is not
6832meant for communication between processes, but rather as a junk
6833disposal mechanism.
6834
6835@item %|@var{suffix}
6836@itemx %m@var{suffix}
6837Like @samp{%g}, except if @option{-pipe} is in effect. In that case
6838@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
6839all. These are the two most common ways to instruct a program that it
6840should read from standard input or write to standard output. If you
6841need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
6842construct: see for example @file{f/lang-specs.h}.
6843
6844@item %.@var{SUFFIX}
6845Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
6846when it is subsequently output with @samp{%*}. @var{SUFFIX} is
6847terminated by the next space or %.
6848
6849@item %w
6850Marks the argument containing or following the @samp{%w} as the
6851designated output file of this compilation. This puts the argument
6852into the sequence of arguments that @samp{%o} will substitute later.
6853
6854@item %o
6855Substitutes the names of all the output files, with spaces
6856automatically placed around them. You should write spaces
6857around the @samp{%o} as well or the results are undefined.
6858@samp{%o} is for use in the specs for running the linker.
6859Input files whose names have no recognized suffix are not compiled
6860at all, but they are included among the output files, so they will
6861be linked.
6862
6863@item %O
6864Substitutes the suffix for object files. Note that this is
6865handled specially when it immediately follows @samp{%g, %u, or %U},
6866because of the need for those to form complete file names. The
6867handling is such that @samp{%O} is treated exactly as if it had already
6868been substituted, except that @samp{%g, %u, and %U} do not currently
6869support additional @var{suffix} characters following @samp{%O} as they would
6870following, for example, @samp{.o}.
6871
6872@item %p
6873Substitutes the standard macro predefinitions for the
6874current target machine. Use this when running @code{cpp}.
6875
6876@item %P
6877Like @samp{%p}, but puts @samp{__} before and after the name of each
6878predefined macro, except for macros that start with @samp{__} or with
6879@samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
6880C@.
6881
6882@item %I
6883Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
6884@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
6885@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
6886and @option{-imultilib} as necessary.
6887
6888@item %s
6889Current argument is the name of a library or startup file of some sort.
6890Search for that file in a standard list of directories and substitute
6891the full name found.
6892
6893@item %e@var{str}
6894Print @var{str} as an error message. @var{str} is terminated by a newline.
6895Use this when inconsistent options are detected.
6896
6897@item %(@var{name})
6898Substitute the contents of spec string @var{name} at this point.
6899
6900@item %[@var{name}]
6901Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
6902
6903@item %x@{@var{option}@}
6904Accumulate an option for @samp{%X}.
6905
6906@item %X
6907Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
6908spec string.
6909
6910@item %Y
6911Output the accumulated assembler options specified by @option{-Wa}.
6912
6913@item %Z
6914Output the accumulated preprocessor options specified by @option{-Wp}.
6915
6916@item %a
6917Process the @code{asm} spec. This is used to compute the
6918switches to be passed to the assembler.
6919
6920@item %A
6921Process the @code{asm_final} spec. This is a spec string for
6922passing switches to an assembler post-processor, if such a program is
6923needed.
6924
6925@item %l
6926Process the @code{link} spec. This is the spec for computing the
6927command line passed to the linker. Typically it will make use of the
6928@samp{%L %G %S %D and %E} sequences.
6929
6930@item %D
6931Dump out a @option{-L} option for each directory that GCC believes might
6932contain startup files. If the target supports multilibs then the
6933current multilib directory will be prepended to each of these paths.
6934
6935@item %L
6936Process the @code{lib} spec. This is a spec string for deciding which
6937libraries should be included on the command line to the linker.
6938
6939@item %G
6940Process the @code{libgcc} spec. This is a spec string for deciding
6941which GCC support library should be included on the command line to the linker.
6942
6943@item %S
6944Process the @code{startfile} spec. This is a spec for deciding which
6945object files should be the first ones passed to the linker. Typically
6946this might be a file named @file{crt0.o}.
6947
6948@item %E
6949Process the @code{endfile} spec. This is a spec string that specifies
6950the last object files that will be passed to the linker.
6951
6952@item %C
6953Process the @code{cpp} spec. This is used to construct the arguments
6954to be passed to the C preprocessor.
6955
6956@item %1
6957Process the @code{cc1} spec. This is used to construct the options to be
6958passed to the actual C compiler (@samp{cc1}).
6959
6960@item %2
6961Process the @code{cc1plus} spec. This is used to construct the options to be
6962passed to the actual C++ compiler (@samp{cc1plus}).
6963
6964@item %*
6965Substitute the variable part of a matched option. See below.
6966Note that each comma in the substituted string is replaced by
6967a single space.
6968
6969@item %<@code{S}
6970Remove all occurrences of @code{-S} from the command line. Note---this
6971command is position dependent. @samp{%} commands in the spec string
6972before this one will see @code{-S}, @samp{%} commands in the spec string
6973after this one will not.
6974
6975@item %:@var{function}(@var{args})
6976Call the named function @var{function}, passing it @var{args}.
6977@var{args} is first processed as a nested spec string, then split
6978into an argument vector in the usual fashion. The function returns
6979a string which is processed as if it had appeared literally as part
6980of the current spec.
6981
6982The following built-in spec functions are provided:
6983
6984@table @code
6985@item @code{if-exists}
6986The @code{if-exists} spec function takes one argument, an absolute
6987pathname to a file. If the file exists, @code{if-exists} returns the
6988pathname. Here is a small example of its usage:
6989
6990@smallexample
6991*startfile:
6992crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
6993@end smallexample
6994
6995@item @code{if-exists-else}
6996The @code{if-exists-else} spec function is similar to the @code{if-exists}
6997spec function, except that it takes two arguments. The first argument is
6998an absolute pathname to a file. If the file exists, @code{if-exists-else}
6999returns the pathname. If it does not exist, it returns the second argument.
7000This way, @code{if-exists-else} can be used to select one file or another,
7001based on the existence of the first. Here is a small example of its usage:
7002
7003@smallexample
7004*startfile:
7005crt0%O%s %:if-exists(crti%O%s) \
7006%:if-exists-else(crtbeginT%O%s crtbegin%O%s)
7007@end smallexample
7008
7009@item @code{replace-outfile}
7010The @code{replace-outfile} spec function takes two arguments. It looks for the
7011first argument in the outfiles array and replaces it with the second argument. Here
7012is a small example of its usage:
7013
7014@smallexample
7015%@{static|static-libgcc|static-libstdc++:%:replace-outfile(-lstdc++ \
7016libstdc++.a%s)@}
7017
7018@end smallexample
7019
7020@end table
7021
7022@item %@{@code{S}@}
7023Substitutes the @code{-S} switch, if that switch was given to GCC@.
7024If that switch was not specified, this substitutes nothing. Note that
7025the leading dash is omitted when specifying this option, and it is
7026automatically inserted if the substitution is performed. Thus the spec
7027string @samp{%@{foo@}} would match the command-line option @option{-foo}
7028and would output the command line option @option{-foo}.
7029
7030@item %W@{@code{S}@}
7031Like %@{@code{S}@} but mark last argument supplied within as a file to be
7032deleted on failure.
7033
7034@item %@{@code{S}*@}
7035Substitutes all the switches specified to GCC whose names start
7036with @code{-S}, but which also take an argument. This is used for
7037switches like @option{-o}, @option{-D}, @option{-I}, etc.
7038GCC considers @option{-o foo} as being
7039one switch whose names starts with @samp{o}. %@{o*@} would substitute this
7040text, including the space. Thus two arguments would be generated.
7041
7042@item %@{@code{S}*&@code{T}*@}
7043Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
7044(the order of @code{S} and @code{T} in the spec is not significant).
7045There can be any number of ampersand-separated variables; for each the
7046wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
7047
7048@item %@{@code{S}:@code{X}@}
7049Substitutes @code{X}, if the @samp{-S} switch was given to GCC@.
7050
7051@item %@{!@code{S}:@code{X}@}
7052Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@.
7053
7054@item %@{@code{S}*:@code{X}@}
7055Substitutes @code{X} if one or more switches whose names start with
7056@code{-S} are specified to GCC@. Normally @code{X} is substituted only
7057once, no matter how many such switches appeared. However, if @code{%*}
7058appears somewhere in @code{X}, then @code{X} will be substituted once
7059for each matching switch, with the @code{%*} replaced by the part of
7060that switch that matched the @code{*}.
7061
7062@item %@{.@code{S}:@code{X}@}
7063Substitutes @code{X}, if processing a file with suffix @code{S}.
7064
7065@item %@{!.@code{S}:@code{X}@}
7066Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
7067
7068@item %@{@code{S}|@code{P}:@code{X}@}
7069Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@.
7070This may be combined with @samp{!}, @samp{.}, and @code{*} sequences as well,
7071although they have a stronger binding than the @samp{|}. If @code{%*}
7072appears in @code{X}, all of the alternatives must be starred, and only
7073the first matching alternative is substituted.
7074
7075For example, a spec string like this:
7076
7077@smallexample
7078%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
7079@end smallexample
7080
7081will output the following command-line options from the following input
7082command-line options:
7083
7084@smallexample
7085fred.c -foo -baz
7086jim.d -bar -boggle
7087-d fred.c -foo -baz -boggle
7088-d jim.d -bar -baz -boggle
7089@end smallexample
7090
7091@item %@{S:X; T:Y; :D@}
7092
7093If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was
7094given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
7095be as many clauses as you need. This may be combined with @code{.},
7096@code{!}, @code{|}, and @code{*} as needed.
7097
7098
7099@end table
7100
7101The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
7102construct may contain other nested @samp{%} constructs or spaces, or
7103even newlines. They are processed as usual, as described above.
7104Trailing white space in @code{X} is ignored. White space may also
7105appear anywhere on the left side of the colon in these constructs,
7106except between @code{.} or @code{*} and the corresponding word.
7107
7108The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
7109handled specifically in these constructs. If another value of
7110@option{-O} or the negated form of a @option{-f}, @option{-m}, or
7111@option{-W} switch is found later in the command line, the earlier
7112switch value is ignored, except with @{@code{S}*@} where @code{S} is
7113just one letter, which passes all matching options.
7114
7115The character @samp{|} at the beginning of the predicate text is used to
7116indicate that a command should be piped to the following command, but
7117only if @option{-pipe} is specified.
7118
7119It is built into GCC which switches take arguments and which do not.
7120(You might think it would be useful to generalize this to allow each
7121compiler's spec to say which switches take arguments. But this cannot
7122be done in a consistent fashion. GCC cannot even decide which input
7123files have been specified without knowing which switches take arguments,
7124and it must know which input files to compile in order to tell which
7125compilers to run).
7126
7127GCC also knows implicitly that arguments starting in @option{-l} are to be
7128treated as compiler output files, and passed to the linker in their
7129proper position among the other output files.
7130
7131@c man begin OPTIONS
7132
7133@node Target Options
7134@section Specifying Target Machine and Compiler Version
7135@cindex target options
7136@cindex cross compiling
7137@cindex specifying machine version
7138@cindex specifying compiler version and target machine
7139@cindex compiler version, specifying
7140@cindex target machine, specifying
7141
7142The usual way to run GCC is to run the executable called @file{gcc}, or
7143@file{<machine>-gcc} when cross-compiling, or
7144@file{<machine>-gcc-<version>} to run a version other than the one that
7145was installed last. Sometimes this is inconvenient, so GCC provides
7146options that will switch to another cross-compiler or version.
7147
7148@table @gcctabopt
7149@item -b @var{machine}
7150@opindex b
7151The argument @var{machine} specifies the target machine for compilation.
7152
7153The value to use for @var{machine} is the same as was specified as the
7154machine type when configuring GCC as a cross-compiler. For
7155example, if a cross-compiler was configured with @samp{configure
7156arm-elf}, meaning to compile for an arm processor with elf binaries,
7157then you would specify @option{-b arm-elf} to run that cross compiler.
7158Because there are other options beginning with @option{-b}, the
7159configuration must contain a hyphen.
7160
7161@item -V @var{version}
7162@opindex V
7163The argument @var{version} specifies which version of GCC to run.
7164This is useful when multiple versions are installed. For example,
7165@var{version} might be @samp{4.0}, meaning to run GCC version 4.0.
7166@end table
7167
7168The @option{-V} and @option{-b} options work by running the
7169@file{<machine>-gcc-<version>} executable, so there's no real reason to
7170use them if you can just run that directly.
7171
7172@node Submodel Options
7173@section Hardware Models and Configurations
7174@cindex submodel options
7175@cindex specifying hardware config
7176@cindex hardware models and configurations, specifying
7177@cindex machine dependent options
7178
7179Earlier we discussed the standard option @option{-b} which chooses among
7180different installed compilers for completely different target
7181machines, such as VAX vs.@: 68000 vs.@: 80386.
7182
7183In addition, each of these target machine types can have its own
7184special options, starting with @samp{-m}, to choose among various
7185hardware models or configurations---for example, 68010 vs 68020,
7186floating coprocessor or none. A single installed version of the
7187compiler can compile for any model or configuration, according to the
7188options specified.
7189
7190Some configurations of the compiler also support additional special
7191options, usually for compatibility with other compilers on the same
7192platform.
7193
7194@c This list is ordered alphanumerically by subsection name.
7195@c It should be the same order and spelling as these options are listed
7196@c in Machine Dependent Options
7197
7198@menu
7199* ARC Options::
7200* ARM Options::
7201* AVR Options::
7202* Blackfin Options::
7203* CRIS Options::
7204* CRX Options::
7205* Darwin Options::
7206* DEC Alpha Options::
7207* DEC Alpha/VMS Options::
7208* FRV Options::
7209* GNU/Linux Options::
7210* H8/300 Options::
7211* HPPA Options::
7212* i386 and x86-64 Options::
7213* IA-64 Options::
7214* M32C Options::
7215* M32R/D Options::
7216* M680x0 Options::
7217* M68hc1x Options::
7218* MCore Options::
7219* MIPS Options::
7220* MMIX Options::
7221* MN10300 Options::
7222* MT Options::
7223* PDP-11 Options::
7224* PowerPC Options::
7225* RS/6000 and PowerPC Options::
7226* S/390 and zSeries Options::
7227* Score Options::
7228* SH Options::
7229* SPARC Options::
7230* System V Options::
7231* TMS320C3x/C4x Options::
7232* V850 Options::
7233* VAX Options::
7234* x86-64 Options::
7235* Xstormy16 Options::
7236* Xtensa Options::
7237* zSeries Options::
7238@end menu
7239
7240@node ARC Options
7241@subsection ARC Options
7242@cindex ARC Options
7243
7244These options are defined for ARC implementations:
7245
7246@table @gcctabopt
7247@item -EL
7248@opindex EL
7249Compile code for little endian mode. This is the default.
7250
7251@item -EB
7252@opindex EB
7253Compile code for big endian mode.
7254
7255@item -mmangle-cpu
7256@opindex mmangle-cpu
7257Prepend the name of the cpu to all public symbol names.
7258In multiple-processor systems, there are many ARC variants with different
7259instruction and register set characteristics. This flag prevents code
7260compiled for one cpu to be linked with code compiled for another.
7261No facility exists for handling variants that are ``almost identical''.
7262This is an all or nothing option.
7263
7264@item -mcpu=@var{cpu}
7265@opindex mcpu
7266Compile code for ARC variant @var{cpu}.
7267Which variants are supported depend on the configuration.
7268All variants support @option{-mcpu=base}, this is the default.
7269
7270@item -mtext=@var{text-section}
7271@itemx -mdata=@var{data-section}
7272@itemx -mrodata=@var{readonly-data-section}
7273@opindex mtext
7274@opindex mdata
7275@opindex mrodata
7276Put functions, data, and readonly data in @var{text-section},
7277@var{data-section}, and @var{readonly-data-section} respectively
7278by default. This can be overridden with the @code{section} attribute.
7279@xref{Variable Attributes}.
7280
7281@end table
7282
7283@node ARM Options
7284@subsection ARM Options
7285@cindex ARM options
7286
7287These @samp{-m} options are defined for Advanced RISC Machines (ARM)
7288architectures:
7289
7290@table @gcctabopt
7291@item -mabi=@var{name}
7292@opindex mabi
7293Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu},
7294@samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.
7295
7296@item -mapcs-frame
7297@opindex mapcs-frame
7298Generate a stack frame that is compliant with the ARM Procedure Call
7299Standard for all functions, even if this is not strictly necessary for
7300correct execution of the code. Specifying @option{-fomit-frame-pointer}
7301with this option will cause the stack frames not to be generated for
7302leaf functions. The default is @option{-mno-apcs-frame}.
7303
7304@item -mapcs
7305@opindex mapcs
7306This is a synonym for @option{-mapcs-frame}.
7307
7308@ignore
7309@c not currently implemented
7310@item -mapcs-stack-check
7311@opindex mapcs-stack-check
7312Generate code to check the amount of stack space available upon entry to
7313every function (that actually uses some stack space). If there is
7314insufficient space available then either the function
7315@samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
7316called, depending upon the amount of stack space required. The run time
7317system is required to provide these functions. The default is
7318@option{-mno-apcs-stack-check}, since this produces smaller code.
7319
7320@c not currently implemented
7321@item -mapcs-float
7322@opindex mapcs-float
7323Pass floating point arguments using the float point registers. This is
7324one of the variants of the APCS@. This option is recommended if the
7325target hardware has a floating point unit or if a lot of floating point
7326arithmetic is going to be performed by the code. The default is
7327@option{-mno-apcs-float}, since integer only code is slightly increased in
7328size if @option{-mapcs-float} is used.
7329
7330@c not currently implemented
7331@item -mapcs-reentrant
7332@opindex mapcs-reentrant
7333Generate reentrant, position independent code. The default is
7334@option{-mno-apcs-reentrant}.
7335@end ignore
7336
7337@item -mthumb-interwork
7338@opindex mthumb-interwork
7339Generate code which supports calling between the ARM and Thumb
7340instruction sets. Without this option the two instruction sets cannot
7341be reliably used inside one program. The default is
7342@option{-mno-thumb-interwork}, since slightly larger code is generated
7343when @option{-mthumb-interwork} is specified.
7344
7345@item -mno-sched-prolog
7346@opindex mno-sched-prolog
7347Prevent the reordering of instructions in the function prolog, or the
7348merging of those instruction with the instructions in the function's
7349body. This means that all functions will start with a recognizable set
7350of instructions (or in fact one of a choice from a small set of
7351different function prologues), and this information can be used to
7352locate the start if functions inside an executable piece of code. The
7353default is @option{-msched-prolog}.
7354
7355@item -mhard-float
7356@opindex mhard-float
7357Generate output containing floating point instructions. This is the
7358default.
7359
7360@item -msoft-float
7361@opindex msoft-float
7362Generate output containing library calls for floating point.
7363@strong{Warning:} the requisite libraries are not available for all ARM
7364targets. Normally the facilities of the machine's usual C compiler are
7365used, but this cannot be done directly in cross-compilation. You must make
7366your own arrangements to provide suitable library functions for
7367cross-compilation.
7368
7369@option{-msoft-float} changes the calling convention in the output file;
7370therefore, it is only useful if you compile @emph{all} of a program with
7371this option. In particular, you need to compile @file{libgcc.a}, the
7372library that comes with GCC, with @option{-msoft-float} in order for
7373this to work.
7374
7375@item -mfloat-abi=@var{name}
7376@opindex mfloat-abi
7377Specifies which ABI to use for floating point values. Permissible values
7378are: @samp{soft}, @samp{softfp} and @samp{hard}.
7379
7380@samp{soft} and @samp{hard} are equivalent to @option{-msoft-float}
7381and @option{-mhard-float} respectively. @samp{softfp} allows the generation
7382of floating point instructions, but still uses the soft-float calling
7383conventions.
7384
7385@item -mlittle-endian
7386@opindex mlittle-endian
7387Generate code for a processor running in little-endian mode. This is
7388the default for all standard configurations.
7389
7390@item -mbig-endian
7391@opindex mbig-endian
7392Generate code for a processor running in big-endian mode; the default is
7393to compile code for a little-endian processor.
7394
7395@item -mwords-little-endian
7396@opindex mwords-little-endian
7397This option only applies when generating code for big-endian processors.
7398Generate code for a little-endian word order but a big-endian byte
7399order. That is, a byte order of the form @samp{32107654}. Note: this
7400option should only be used if you require compatibility with code for
7401big-endian ARM processors generated by versions of the compiler prior to
74022.8.
7403
7404@item -mcpu=@var{name}
7405@opindex mcpu
7406This specifies the name of the target ARM processor. GCC uses this name
7407to determine what kind of instructions it can emit when generating
7408assembly code. Permissible names are: @samp{arm2}, @samp{arm250},
7409@samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
7410@samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
7411@samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
7412@samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
7413@samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},
7414@samp{arm8}, @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
7415@samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
7416@samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},
7417@samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},
7418@samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},
7419@samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
7420@samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
7421@samp{arm1176jz-s}, @samp{arm1176jzf-s}, @samp{xscale}, @samp{iwmmxt},
7422@samp{ep9312}.
7423
7424@itemx -mtune=@var{name}
7425@opindex mtune
7426This option is very similar to the @option{-mcpu=} option, except that
7427instead of specifying the actual target processor type, and hence
7428restricting which instructions can be used, it specifies that GCC should
7429tune the performance of the code as if the target were of the type
7430specified in this option, but still choosing the instructions that it
7431will generate based on the cpu specified by a @option{-mcpu=} option.
7432For some ARM implementations better performance can be obtained by using
7433this option.
7434
7435@item -march=@var{name}
7436@opindex march
7437This specifies the name of the target ARM architecture. GCC uses this
7438name to determine what kind of instructions it can emit when generating
7439assembly code. This option can be used in conjunction with or instead
7440of the @option{-mcpu=} option. Permissible names are: @samp{armv2},
7441@samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
7442@samp{armv5}, @samp{armv5t}, @samp{armv5te}, @samp{armv6}, @samp{armv6j},
7443@samp{iwmmxt}, @samp{ep9312}.
7444
7445@item -mfpu=@var{name}
7446@itemx -mfpe=@var{number}
7447@itemx -mfp=@var{number}
7448@opindex mfpu
7449@opindex mfpe
7450@opindex mfp
7451This specifies what floating point hardware (or hardware emulation) is
7452available on the target. Permissible names are: @samp{fpa}, @samp{fpe2},
7453@samp{fpe3}, @samp{maverick}, @samp{vfp}. @option{-mfp} and @option{-mfpe}
7454are synonyms for @option{-mfpu}=@samp{fpe}@var{number}, for compatibility
7455with older versions of GCC@.
7456
7457If @option{-msoft-float} is specified this specifies the format of
7458floating point values.
7459
7460@item -mstructure-size-boundary=@var{n}
7461@opindex mstructure-size-boundary
7462The size of all structures and unions will be rounded up to a multiple
7463of the number of bits set by this option. Permissible values are 8, 32
7464and 64. The default value varies for different toolchains. For the COFF
7465targeted toolchain the default value is 8. A value of 64 is only allowed
7466if the underlying ABI supports it.
7467
7468Specifying the larger number can produce faster, more efficient code, but
7469can also increase the size of the program. Different values are potentially
7470incompatible. Code compiled with one value cannot necessarily expect to
7471work with code or libraries compiled with another value, if they exchange
7472information using structures or unions.
7473
7474@item -mabort-on-noreturn
7475@opindex mabort-on-noreturn
7476Generate a call to the function @code{abort} at the end of a
7477@code{noreturn} function. It will be executed if the function tries to
7478return.
7479
7480@item -mlong-calls
7481@itemx -mno-long-calls
7482@opindex mlong-calls
7483@opindex mno-long-calls
7484Tells the compiler to perform function calls by first loading the
7485address of the function into a register and then performing a subroutine
7486call on this register. This switch is needed if the target function
7487will lie outside of the 64 megabyte addressing range of the offset based
7488version of subroutine call instruction.
7489
7490Even if this switch is enabled, not all function calls will be turned
7491into long calls. The heuristic is that static functions, functions
7492which have the @samp{short-call} attribute, functions that are inside
7493the scope of a @samp{#pragma no_long_calls} directive and functions whose
7494definitions have already been compiled within the current compilation
7495unit, will not be turned into long calls. The exception to this rule is
7496that weak function definitions, functions with the @samp{long-call}
7497attribute or the @samp{section} attribute, and functions that are within
7498the scope of a @samp{#pragma long_calls} directive, will always be
7499turned into long calls.
7500
7501This feature is not enabled by default. Specifying
7502@option{-mno-long-calls} will restore the default behavior, as will
7503placing the function calls within the scope of a @samp{#pragma
7504long_calls_off} directive. Note these switches have no effect on how
7505the compiler generates code to handle function calls via function
7506pointers.
7507
7508@item -mnop-fun-dllimport
7509@opindex mnop-fun-dllimport
7510Disable support for the @code{dllimport} attribute.
7511
7512@item -msingle-pic-base
7513@opindex msingle-pic-base
7514Treat the register used for PIC addressing as read-only, rather than
7515loading it in the prologue for each function. The run-time system is
7516responsible for initializing this register with an appropriate value
7517before execution begins.
7518
7519@item -mpic-register=@var{reg}
7520@opindex mpic-register
7521Specify the register to be used for PIC addressing. The default is R10
7522unless stack-checking is enabled, when R9 is used.
7523
7524@item -mcirrus-fix-invalid-insns
7525@opindex mcirrus-fix-invalid-insns
7526@opindex mno-cirrus-fix-invalid-insns
7527Insert NOPs into the instruction stream to in order to work around
7528problems with invalid Maverick instruction combinations. This option
7529is only valid if the @option{-mcpu=ep9312} option has been used to
7530enable generation of instructions for the Cirrus Maverick floating
7531point co-processor. This option is not enabled by default, since the
7532problem is only present in older Maverick implementations. The default
7533can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns}
7534switch.
7535
7536@item -mpoke-function-name
7537@opindex mpoke-function-name
7538Write the name of each function into the text section, directly
7539preceding the function prologue. The generated code is similar to this:
7540
7541@smallexample
7542 t0
7543 .ascii "arm_poke_function_name", 0
7544 .align
7545 t1
7546 .word 0xff000000 + (t1 - t0)
7547 arm_poke_function_name
7548 mov ip, sp
7549 stmfd sp!, @{fp, ip, lr, pc@}
7550 sub fp, ip, #4
7551@end smallexample
7552
7553When performing a stack backtrace, code can inspect the value of
7554@code{pc} stored at @code{fp + 0}. If the trace function then looks at
7555location @code{pc - 12} and the top 8 bits are set, then we know that
7556there is a function name embedded immediately preceding this location
7557and has length @code{((pc[-3]) & 0xff000000)}.
7558
7559@item -mthumb
7560@opindex mthumb
7561Generate code for the 16-bit Thumb instruction set. The default is to
7562use the 32-bit ARM instruction set.
7563
7564@item -mtpcs-frame
7565@opindex mtpcs-frame
7566Generate a stack frame that is compliant with the Thumb Procedure Call
7567Standard for all non-leaf functions. (A leaf function is one that does
7568not call any other functions.) The default is @option{-mno-tpcs-frame}.
7569
7570@item -mtpcs-leaf-frame
7571@opindex mtpcs-leaf-frame
7572Generate a stack frame that is compliant with the Thumb Procedure Call
7573Standard for all leaf functions. (A leaf function is one that does
7574not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
7575
7576@item -mcallee-super-interworking
7577@opindex mcallee-super-interworking
7578Gives all externally visible functions in the file being compiled an ARM
7579instruction set header which switches to Thumb mode before executing the
7580rest of the function. This allows these functions to be called from
7581non-interworking code.
7582
7583@item -mcaller-super-interworking
7584@opindex mcaller-super-interworking
7585Allows calls via function pointers (including virtual functions) to
7586execute correctly regardless of whether the target code has been
7587compiled for interworking or not. There is a small overhead in the cost
7588of executing a function pointer if this option is enabled.
7589
7590@item -mtp=@var{name}
7591@opindex mtp
7592Specify the access model for the thread local storage pointer. The valid
7593models are @option{soft}, which generates calls to @code{__aeabi_read_tp},
7594@option{cp15}, which fetches the thread pointer from @code{cp15} directly
7595(supported in the arm6k architecture), and @option{auto}, which uses the
7596best available method for the selected processor. The default setting is
7597@option{auto}.
7598
7599@end table
7600
7601@node AVR Options
7602@subsection AVR Options
7603@cindex AVR Options
7604
7605These options are defined for AVR implementations:
7606
7607@table @gcctabopt
7608@item -mmcu=@var{mcu}
7609@opindex mmcu
7610Specify ATMEL AVR instruction set or MCU type.
7611
7612Instruction set avr1 is for the minimal AVR core, not supported by the C
7613compiler, only for assembler programs (MCU types: at90s1200, attiny10,
7614attiny11, attiny12, attiny15, attiny28).
7615
7616Instruction set avr2 (default) is for the classic AVR core with up to
76178K program memory space (MCU types: at90s2313, at90s2323, attiny22,
7618at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
7619at90c8534, at90s8535).
7620
7621Instruction set avr3 is for the classic AVR core with up to 128K program
7622memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
7623
7624Instruction set avr4 is for the enhanced AVR core with up to 8K program
7625memory space (MCU types: atmega8, atmega83, atmega85).
7626
7627Instruction set avr5 is for the enhanced AVR core with up to 128K program
7628memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
7629atmega64, atmega128, at43usb355, at94k).
7630
7631@item -msize
7632@opindex msize
7633Output instruction sizes to the asm file.
7634
7635@item -minit-stack=@var{N}
7636@opindex minit-stack
7637Specify the initial stack address, which may be a symbol or numeric value,
7638@samp{__stack} is the default.
7639
7640@item -mno-interrupts
7641@opindex mno-interrupts
7642Generated code is not compatible with hardware interrupts.
7643Code size will be smaller.
7644
7645@item -mcall-prologues
7646@opindex mcall-prologues
7647Functions prologues/epilogues expanded as call to appropriate
7648subroutines. Code size will be smaller.
7649
7650@item -mno-tablejump
7651@opindex mno-tablejump
7652Do not generate tablejump insns which sometimes increase code size.
7653
7654@item -mtiny-stack
7655@opindex mtiny-stack
7656Change only the low 8 bits of the stack pointer.
7657
7658@item -mint8
7659@opindex mint8
7660Assume int to be 8 bit integer. This affects the sizes of all types: A
7661char will be 1 byte, an int will be 1 byte, an long will be 2 bytes
7662and long long will be 4 bytes. Please note that this option does not
7663comply to the C standards, but it will provide you with smaller code
7664size.
7665@end table
7666
7667@node Blackfin Options
7668@subsection Blackfin Options
7669@cindex Blackfin Options
7670
7671@table @gcctabopt
7672@item -momit-leaf-frame-pointer
7673@opindex momit-leaf-frame-pointer
7674Don't keep the frame pointer in a register for leaf functions. This
7675avoids the instructions to save, set up and restore frame pointers and
7676makes an extra register available in leaf functions. The option
7677@option{-fomit-frame-pointer} removes the frame pointer for all functions
7678which might make debugging harder.
7679
7680@item -mspecld-anomaly
7681@opindex mspecld-anomaly
7682When enabled, the compiler will ensure that the generated code does not
7683contain speculative loads after jump instructions. This option is enabled
7684by default.
7685
7686@item -mno-specld-anomaly
7687@opindex mno-specld-anomaly
7688Don't generate extra code to prevent speculative loads from occurring.
7689
7690@item -mcsync-anomaly
7691@opindex mcsync-anomaly
7692When enabled, the compiler will ensure that the generated code does not
7693contain CSYNC or SSYNC instructions too soon after conditional branches.
7694This option is enabled by default.
7695
7696@item -mno-csync-anomaly
7697@opindex mno-csync-anomaly
7698Don't generate extra code to prevent CSYNC or SSYNC instructions from
7699occurring too soon after a conditional branch.
7700
7701@item -mlow-64k
7702@opindex mlow-64k
7703When enabled, the compiler is free to take advantage of the knowledge that
7704the entire program fits into the low 64k of memory.
7705
7706@item -mno-low-64k
7707@opindex mno-low-64k
7708Assume that the program is arbitrarily large. This is the default.
7709
7710@item -mid-shared-library
7711@opindex mid-shared-library
7712Generate code that supports shared libraries via the library ID method.
7713This allows for execute in place and shared libraries in an environment
7714without virtual memory management. This option implies @option{-fPIC}.
7715
7716@item -mno-id-shared-library
7717@opindex mno-id-shared-library
7718Generate code that doesn't assume ID based shared libraries are being used.
7719This is the default.
7720
7721@item -mshared-library-id=n
7722@opindex mshared-library-id
7723Specified the identification number of the ID based shared library being
7724compiled. Specifying a value of 0 will generate more compact code, specifying
7725other values will force the allocation of that number to the current
7726library but is no more space or time efficient than omitting this option.
7727
7728@item -mlong-calls
7729@itemx -mno-long-calls
7730@opindex mlong-calls
7731@opindex mno-long-calls
7732Tells the compiler to perform function calls by first loading the
7733address of the function into a register and then performing a subroutine
7734call on this register. This switch is needed if the target function
7735will lie outside of the 24 bit addressing range of the offset based
7736version of subroutine call instruction.
7737
7738This feature is not enabled by default. Specifying
7739@option{-mno-long-calls} will restore the default behavior. Note these
7740switches have no effect on how the compiler generates code to handle
7741function calls via function pointers.
7742@end table
7743
7744@node CRIS Options
7745@subsection CRIS Options
7746@cindex CRIS Options
7747
7748These options are defined specifically for the CRIS ports.
7749
7750@table @gcctabopt
7751@item -march=@var{architecture-type}
7752@itemx -mcpu=@var{architecture-type}
7753@opindex march
7754@opindex mcpu
7755Generate code for the specified architecture. The choices for
7756@var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
7757respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
7758Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
7759@samp{v10}.
7760
7761@item -mtune=@var{architecture-type}
7762@opindex mtune
7763Tune to @var{architecture-type} everything applicable about the generated
7764code, except for the ABI and the set of available instructions. The
7765choices for @var{architecture-type} are the same as for
7766@option{-march=@var{architecture-type}}.
7767
7768@item -mmax-stack-frame=@var{n}
7769@opindex mmax-stack-frame
7770Warn when the stack frame of a function exceeds @var{n} bytes.
7771
7772@item -melinux-stacksize=@var{n}
7773@opindex melinux-stacksize
7774Only available with the @samp{cris-axis-aout} target. Arranges for
7775indications in the program to the kernel loader that the stack of the
7776program should be set to @var{n} bytes.
7777
7778@item -metrax4
7779@itemx -metrax100
7780@opindex metrax4
7781@opindex metrax100
7782The options @option{-metrax4} and @option{-metrax100} are synonyms for
7783@option{-march=v3} and @option{-march=v8} respectively.
7784
7785@item -mmul-bug-workaround
7786@itemx -mno-mul-bug-workaround
7787@opindex mmul-bug-workaround
7788@opindex mno-mul-bug-workaround
7789Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
7790models where it applies. This option is active by default.
7791
7792@item -mpdebug
7793@opindex mpdebug
7794Enable CRIS-specific verbose debug-related information in the assembly
7795code. This option also has the effect to turn off the @samp{#NO_APP}
7796formatted-code indicator to the assembler at the beginning of the
7797assembly file.
7798
7799@item -mcc-init
7800@opindex mcc-init
7801Do not use condition-code results from previous instruction; always emit
7802compare and test instructions before use of condition codes.
7803
7804@item -mno-side-effects
7805@opindex mno-side-effects
7806Do not emit instructions with side-effects in addressing modes other than
7807post-increment.
7808
7809@item -mstack-align
7810@itemx -mno-stack-align
7811@itemx -mdata-align
7812@itemx -mno-data-align
7813@itemx -mconst-align
7814@itemx -mno-const-align
7815@opindex mstack-align
7816@opindex mno-stack-align
7817@opindex mdata-align
7818@opindex mno-data-align
7819@opindex mconst-align
7820@opindex mno-const-align
7821These options (no-options) arranges (eliminate arrangements) for the
7822stack-frame, individual data and constants to be aligned for the maximum
7823single data access size for the chosen CPU model. The default is to
7824arrange for 32-bit alignment. ABI details such as structure layout are
7825not affected by these options.
7826
7827@item -m32-bit
7828@itemx -m16-bit
7829@itemx -m8-bit
7830@opindex m32-bit
7831@opindex m16-bit
7832@opindex m8-bit
7833Similar to the stack- data- and const-align options above, these options
7834arrange for stack-frame, writable data and constants to all be 32-bit,
783516-bit or 8-bit aligned. The default is 32-bit alignment.
7836
7837@item -mno-prologue-epilogue
7838@itemx -mprologue-epilogue
7839@opindex mno-prologue-epilogue
7840@opindex mprologue-epilogue
7841With @option{-mno-prologue-epilogue}, the normal function prologue and
7842epilogue that sets up the stack-frame are omitted and no return
7843instructions or return sequences are generated in the code. Use this
7844option only together with visual inspection of the compiled code: no
7845warnings or errors are generated when call-saved registers must be saved,
7846or storage for local variable needs to be allocated.
7847
7848@item -mno-gotplt
7849@itemx -mgotplt
7850@opindex mno-gotplt
7851@opindex mgotplt
7852With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
7853instruction sequences that load addresses for functions from the PLT part
7854of the GOT rather than (traditional on other architectures) calls to the
7855PLT@. The default is @option{-mgotplt}.
7856
7857@item -maout
7858@opindex maout
7859Legacy no-op option only recognized with the cris-axis-aout target.
7860
7861@item -melf
7862@opindex melf
7863Legacy no-op option only recognized with the cris-axis-elf and
7864cris-axis-linux-gnu targets.
7865
7866@item -melinux
7867@opindex melinux
7868Only recognized with the cris-axis-aout target, where it selects a
7869GNU/linux-like multilib, include files and instruction set for
7870@option{-march=v8}.
7871
7872@item -mlinux
7873@opindex mlinux
7874Legacy no-op option only recognized with the cris-axis-linux-gnu target.
7875
7876@item -sim
7877@opindex sim
7878This option, recognized for the cris-axis-aout and cris-axis-elf arranges
7879to link with input-output functions from a simulator library. Code,
7880initialized data and zero-initialized data are allocated consecutively.
7881
7882@item -sim2
7883@opindex sim2
7884Like @option{-sim}, but pass linker options to locate initialized data at
78850x40000000 and zero-initialized data at 0x80000000.
7886@end table
7887
7888@node CRX Options
7889@subsection CRX Options
7890@cindex CRX Options
7891
7892These options are defined specifically for the CRX ports.
7893
7894@table @gcctabopt
7895
7896@item -mmac
7897@opindex mmac
7898Enable the use of multiply-accumulate instructions. Disabled by default.
7899
7900@item -mpush-args
7901@opindex mpush-args
7902Push instructions will be used to pass outgoing arguments when functions
7903are called. Enabled by default.
7904@end table
7905
7906@node Darwin Options
7907@subsection Darwin Options
7908@cindex Darwin options
7909
7910These options are defined for all architectures running the Darwin operating
7911system.
7912
7913FSF GCC on Darwin does not create ``fat'' object files; it will create
7914an object file for the single architecture that it was built to
7915target. Apple's GCC on Darwin does create ``fat'' files if multiple
7916@option{-arch} options are used; it does so by running the compiler or
7917linker multiple times and joining the results together with
7918@file{lipo}.
7919
7920The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
7921@samp{i686}) is determined by the flags that specify the ISA
7922that GCC is targetting, like @option{-mcpu} or @option{-march}. The
7923@option{-force_cpusubtype_ALL} option can be used to override this.
7924
7925The Darwin tools vary in their behavior when presented with an ISA
7926mismatch. The assembler, @file{as}, will only permit instructions to
7927be used that are valid for the subtype of the file it is generating,
7928so you cannot put 64-bit instructions in an @samp{ppc750} object file.
7929The linker for shared libraries, @file{/usr/bin/libtool}, will fail
7930and print an error if asked to create a shared library with a less
7931restrictive subtype than its input files (for instance, trying to put
7932a @samp{ppc970} object file in a @samp{ppc7400} library). The linker
7933for executables, @file{ld}, will quietly give the executable the most
7934restrictive subtype of any of its input files.
7935
7936@table @gcctabopt
7937@item -F@var{dir}
7938@opindex F
7939Add the framework directory @var{dir} to the head of the list of
7940directories to be searched for header files. These directories are
7941interleaved with those specified by @option{-I} options and are
7942scanned in a left-to-right order.
7943
7944A framework directory is a directory with frameworks in it. A
7945framework is a directory with a @samp{"Headers"} and/or
7946@samp{"PrivateHeaders"} directory contained directly in it that ends
7947in @samp{".framework"}. The name of a framework is the name of this
7948directory excluding the @samp{".framework"}. Headers associated with
7949the framework are found in one of those two directories, with
7950@samp{"Headers"} being searched first. A subframework is a framework
7951directory that is in a framework's @samp{"Frameworks"} directory.
7952Includes of subframework headers can only appear in a header of a
7953framework that contains the subframework, or in a sibling subframework
7954header. Two subframeworks are siblings if they occur in the same
7955framework. A subframework should not have the same name as a
7956framework, a warning will be issued if this is violated. Currently a
7957subframework cannot have subframeworks, in the future, the mechanism
7958may be extended to support this. The standard frameworks can be found
7959in @samp{"/System/Library/Frameworks"} and
7960@samp{"/Library/Frameworks"}. An example include looks like
7961@code{#include <Framework/header.h>}, where @samp{Framework} denotes
7962the name of the framework and header.h is found in the
7963@samp{"PrivateHeaders"} or @samp{"Headers"} directory.
7964
7965@item -gused
7966@opindex gused
7967Emit debugging information for symbols that are used. For STABS
7968debugging format, this enables @option{-feliminate-unused-debug-symbols}.
7969This is by default ON@.
7970
7971@item -gfull
7972@opindex gfull
7973Emit debugging information for all symbols and types.
7974
7975@item -mmacosx-version-min=@var{version}
7976The earliest version of MacOS X that this executable will run on
7977is @var{version}. Typical values of @var{version} include @code{10.1},
7978@code{10.2}, and @code{10.3.9}.
7979
7980The default for this option is to make choices that seem to be most
7981useful.
7982
7983@item -mkernel
7984@opindex mkernel
7985Enable kernel development mode. The @option{-mkernel} option sets
7986@option{-static}, @option{-fno-common}, @option{-fno-cxa-atexit},
7987@option{-fno-exceptions}, @option{-fno-non-call-exceptions},
7988@option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where
7989applicable. This mode also sets @option{-mno-altivec},
7990@option{-msoft-float}, @option{-fno-builtin} and
7991@option{-mlong-branch} for PowerPC targets.
7992
7993@item -mone-byte-bool
7994@opindex mone-byte-bool
7995Override the defaults for @samp{bool} so that @samp{sizeof(bool)==1}.
7996By default @samp{sizeof(bool)} is @samp{4} when compiling for
7997Darwin/PowerPC and @samp{1} when compiling for Darwin/x86, so this
7998option has no effect on x86.
7999
8000@strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
8001to generate code that is not binary compatible with code generated
8002without that switch. Using this switch may require recompiling all
8003other modules in a program, including system libraries. Use this
8004switch to conform to a non-default data model.
8005
8006@item -mfix-and-continue
8007@itemx -ffix-and-continue
8008@itemx -findirect-data
8009@opindex mfix-and-continue
8010@opindex ffix-and-continue
8011@opindex findirect-data
8012Generate code suitable for fast turn around development. Needed to
8013enable gdb to dynamically load @code{.o} files into already running
8014programs. @option{-findirect-data} and @option{-ffix-and-continue}
8015are provided for backwards compatibility.
8016
8017@item -all_load
8018@opindex all_load
8019Loads all members of static archive libraries.
8020See man ld(1) for more information.
8021
8022@item -arch_errors_fatal
8023@opindex arch_errors_fatal
8024Cause the errors having to do with files that have the wrong architecture
8025to be fatal.
8026
8027@item -bind_at_load
8028@opindex bind_at_load
8029Causes the output file to be marked such that the dynamic linker will
8030bind all undefined references when the file is loaded or launched.
8031
8032@item -bundle
8033@opindex bundle
8034Produce a Mach-o bundle format file.
8035See man ld(1) for more information.
8036
8037@item -bundle_loader @var{executable}
8038@opindex bundle_loader
8039This option specifies the @var{executable} that will be loading the build
8040output file being linked. See man ld(1) for more information.
8041
8042@item -dynamiclib
8043@opindex dynamiclib
8044When passed this option, GCC will produce a dynamic library instead of
8045an executable when linking, using the Darwin @file{libtool} command.
8046
8047@item -force_cpusubtype_ALL
8048@opindex force_cpusubtype_ALL
8049This causes GCC's output file to have the @var{ALL} subtype, instead of
8050one controlled by the @option{-mcpu} or @option{-march} option.
8051
8052@item -allowable_client @var{client_name}
8053@itemx -client_name
8054@itemx -compatibility_version
8055@itemx -current_version
8056@itemx -dead_strip
8057@itemx -dependency-file
8058@itemx -dylib_file
8059@itemx -dylinker_install_name
8060@itemx -dynamic
8061@itemx -exported_symbols_list
8062@itemx -filelist
8063@itemx -flat_namespace
8064@itemx -force_flat_namespace
8065@itemx -headerpad_max_install_names
8066@itemx -image_base
8067@itemx -init
8068@itemx -install_name
8069@itemx -keep_private_externs
8070@itemx -multi_module
8071@itemx -multiply_defined
8072@itemx -multiply_defined_unused
8073@itemx -noall_load
8074@itemx -no_dead_strip_inits_and_terms
8075@itemx -nofixprebinding
8076@itemx -nomultidefs
8077@itemx -noprebind
8078@itemx -noseglinkedit
8079@itemx -pagezero_size
8080@itemx -prebind
8081@itemx -prebind_all_twolevel_modules
8082@itemx -private_bundle
8083@itemx -read_only_relocs
8084@itemx -sectalign
8085@itemx -sectobjectsymbols
8086@itemx -whyload
8087@itemx -seg1addr
8088@itemx -sectcreate
8089@itemx -sectobjectsymbols
8090@itemx -sectorder
8091@itemx -segaddr
8092@itemx -segs_read_only_addr
8093@itemx -segs_read_write_addr
8094@itemx -seg_addr_table
8095@itemx -seg_addr_table_filename
8096@itemx -seglinkedit
8097@itemx -segprot
8098@itemx -segs_read_only_addr
8099@itemx -segs_read_write_addr
8100@itemx -single_module
8101@itemx -static
8102@itemx -sub_library
8103@itemx -sub_umbrella
8104@itemx -twolevel_namespace
8105@itemx -umbrella
8106@itemx -undefined
8107@itemx -unexported_symbols_list
8108@itemx -weak_reference_mismatches
8109@itemx -whatsloaded
8110
8111@opindex allowable_client
8112@opindex client_name
8113@opindex compatibility_version
8114@opindex current_version
8115@opindex dead_strip
8116@opindex dependency-file
8117@opindex dylib_file
8118@opindex dylinker_install_name
8119@opindex dynamic
8120@opindex exported_symbols_list
8121@opindex filelist
8122@opindex flat_namespace
8123@opindex force_flat_namespace
8124@opindex headerpad_max_install_names
8125@opindex image_base
8126@opindex init
8127@opindex install_name
8128@opindex keep_private_externs
8129@opindex multi_module
8130@opindex multiply_defined
8131@opindex multiply_defined_unused
8132@opindex noall_load
8133@opindex no_dead_strip_inits_and_terms
8134@opindex nofixprebinding
8135@opindex nomultidefs
8136@opindex noprebind
8137@opindex noseglinkedit
8138@opindex pagezero_size
8139@opindex prebind
8140@opindex prebind_all_twolevel_modules
8141@opindex private_bundle
8142@opindex read_only_relocs
8143@opindex sectalign
8144@opindex sectobjectsymbols
8145@opindex whyload
8146@opindex seg1addr
8147@opindex sectcreate
8148@opindex sectobjectsymbols
8149@opindex sectorder
8150@opindex segaddr
8151@opindex segs_read_only_addr
8152@opindex segs_read_write_addr
8153@opindex seg_addr_table
8154@opindex seg_addr_table_filename
8155@opindex seglinkedit
8156@opindex segprot
8157@opindex segs_read_only_addr
8158@opindex segs_read_write_addr
8159@opindex single_module
8160@opindex static
8161@opindex sub_library
8162@opindex sub_umbrella
8163@opindex twolevel_namespace
8164@opindex umbrella
8165@opindex undefined
8166@opindex unexported_symbols_list
8167@opindex weak_reference_mismatches
8168@opindex whatsloaded
8169
8170These options are passed to the Darwin linker. The Darwin linker man page
8171describes them in detail.
8172@end table
8173
8174@node DEC Alpha Options
8175@subsection DEC Alpha Options
8176
8177These @samp{-m} options are defined for the DEC Alpha implementations:
8178
8179@table @gcctabopt
8180@item -mno-soft-float
8181@itemx -msoft-float
8182@opindex mno-soft-float
8183@opindex msoft-float
8184Use (do not use) the hardware floating-point instructions for
8185floating-point operations. When @option{-msoft-float} is specified,
8186functions in @file{libgcc.a} will be used to perform floating-point
8187operations. Unless they are replaced by routines that emulate the
8188floating-point operations, or compiled in such a way as to call such
8189emulations routines, these routines will issue floating-point
8190operations. If you are compiling for an Alpha without floating-point
8191operations, you must ensure that the library is built so as not to call
8192them.
8193
8194Note that Alpha implementations without floating-point operations are
8195required to have floating-point registers.
8196
8197@item -mfp-reg
8198@itemx -mno-fp-regs
8199@opindex mfp-reg
8200@opindex mno-fp-regs
8201Generate code that uses (does not use) the floating-point register set.
8202@option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
8203register set is not used, floating point operands are passed in integer
8204registers as if they were integers and floating-point results are passed
8205in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
8206so any function with a floating-point argument or return value called by code
8207compiled with @option{-mno-fp-regs} must also be compiled with that
8208option.
8209
8210A typical use of this option is building a kernel that does not use,
8211and hence need not save and restore, any floating-point registers.
8212
8213@item -mieee
8214@opindex mieee
8215The Alpha architecture implements floating-point hardware optimized for
8216maximum performance. It is mostly compliant with the IEEE floating
8217point standard. However, for full compliance, software assistance is
8218required. This option generates code fully IEEE compliant code
8219@emph{except} that the @var{inexact-flag} is not maintained (see below).
8220If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
8221defined during compilation. The resulting code is less efficient but is
8222able to correctly support denormalized numbers and exceptional IEEE
8223values such as not-a-number and plus/minus infinity. Other Alpha
8224compilers call this option @option{-ieee_with_no_inexact}.
8225
8226@item -mieee-with-inexact
8227@opindex mieee-with-inexact
8228This is like @option{-mieee} except the generated code also maintains
8229the IEEE @var{inexact-flag}. Turning on this option causes the
8230generated code to implement fully-compliant IEEE math. In addition to
8231@code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
8232macro. On some Alpha implementations the resulting code may execute
8233significantly slower than the code generated by default. Since there is
8234very little code that depends on the @var{inexact-flag}, you should
8235normally not specify this option. Other Alpha compilers call this
8236option @option{-ieee_with_inexact}.
8237
8238@item -mfp-trap-mode=@var{trap-mode}
8239@opindex mfp-trap-mode
8240This option controls what floating-point related traps are enabled.
8241Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
8242The trap mode can be set to one of four values:
8243
8244@table @samp
8245@item n
8246This is the default (normal) setting. The only traps that are enabled
8247are the ones that cannot be disabled in software (e.g., division by zero
8248trap).
8249
8250@item u
8251In addition to the traps enabled by @samp{n}, underflow traps are enabled
8252as well.
8253
8254@item su
8255Like @samp{u}, but the instructions are marked to be safe for software
8256completion (see Alpha architecture manual for details).
8257
8258@item sui
8259Like @samp{su}, but inexact traps are enabled as well.
8260@end table
8261
8262@item -mfp-rounding-mode=@var{rounding-mode}
8263@opindex mfp-rounding-mode
8264Selects the IEEE rounding mode. Other Alpha compilers call this option
8265@option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
8266of:
8267
8268@table @samp
8269@item n
8270Normal IEEE rounding mode. Floating point numbers are rounded towards
8271the nearest machine number or towards the even machine number in case
8272of a tie.
8273
8274@item m
8275Round towards minus infinity.
8276
8277@item c
8278Chopped rounding mode. Floating point numbers are rounded towards zero.
8279
8280@item d
8281Dynamic rounding mode. A field in the floating point control register
8282(@var{fpcr}, see Alpha architecture reference manual) controls the
8283rounding mode in effect. The C library initializes this register for
8284rounding towards plus infinity. Thus, unless your program modifies the
8285@var{fpcr}, @samp{d} corresponds to round towards plus infinity.
8286@end table
8287
8288@item -mtrap-precision=@var{trap-precision}
8289@opindex mtrap-precision
8290In the Alpha architecture, floating point traps are imprecise. This
8291means without software assistance it is impossible to recover from a
8292floating trap and program execution normally needs to be terminated.
8293GCC can generate code that can assist operating system trap handlers
8294in determining the exact location that caused a floating point trap.
8295Depending on the requirements of an application, different levels of
8296precisions can be selected:
8297
8298@table @samp
8299@item p
8300Program precision. This option is the default and means a trap handler
8301can only identify which program caused a floating point exception.
8302
8303@item f
8304Function precision. The trap handler can determine the function that
8305caused a floating point exception.
8306
8307@item i
8308Instruction precision. The trap handler can determine the exact
8309instruction that caused a floating point exception.
8310@end table
8311
8312Other Alpha compilers provide the equivalent options called
8313@option{-scope_safe} and @option{-resumption_safe}.
8314
8315@item -mieee-conformant
8316@opindex mieee-conformant
8317This option marks the generated code as IEEE conformant. You must not
8318use this option unless you also specify @option{-mtrap-precision=i} and either
8319@option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
8320is to emit the line @samp{.eflag 48} in the function prologue of the
8321generated assembly file. Under DEC Unix, this has the effect that
8322IEEE-conformant math library routines will be linked in.
8323
8324@item -mbuild-constants
8325@opindex mbuild-constants
8326Normally GCC examines a 32- or 64-bit integer constant to
8327see if it can construct it from smaller constants in two or three
8328instructions. If it cannot, it will output the constant as a literal and
8329generate code to load it from the data segment at runtime.
8330
8331Use this option to require GCC to construct @emph{all} integer constants
8332using code, even if it takes more instructions (the maximum is six).
8333
8334You would typically use this option to build a shared library dynamic
8335loader. Itself a shared library, it must relocate itself in memory
8336before it can find the variables and constants in its own data segment.
8337
8338@item -malpha-as
8339@itemx -mgas
8340@opindex malpha-as
8341@opindex mgas
8342Select whether to generate code to be assembled by the vendor-supplied
8343assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
8344
8345@item -mbwx
8346@itemx -mno-bwx
8347@itemx -mcix
8348@itemx -mno-cix
8349@itemx -mfix
8350@itemx -mno-fix
8351@itemx -mmax
8352@itemx -mno-max
8353@opindex mbwx
8354@opindex mno-bwx
8355@opindex mcix
8356@opindex mno-cix
8357@opindex mfix
8358@opindex mno-fix
8359@opindex mmax
8360@opindex mno-max
8361Indicate whether GCC should generate code to use the optional BWX,
8362CIX, FIX and MAX instruction sets. The default is to use the instruction
8363sets supported by the CPU type specified via @option{-mcpu=} option or that
8364of the CPU on which GCC was built if none was specified.
8365
8366@item -mfloat-vax
8367@itemx -mfloat-ieee
8368@opindex mfloat-vax
8369@opindex mfloat-ieee
8370Generate code that uses (does not use) VAX F and G floating point
8371arithmetic instead of IEEE single and double precision.
8372
8373@item -mexplicit-relocs
8374@itemx -mno-explicit-relocs
8375@opindex mexplicit-relocs
8376@opindex mno-explicit-relocs
8377Older Alpha assemblers provided no way to generate symbol relocations
8378except via assembler macros. Use of these macros does not allow
8379optimal instruction scheduling. GNU binutils as of version 2.12
8380supports a new syntax that allows the compiler to explicitly mark
8381which relocations should apply to which instructions. This option
8382is mostly useful for debugging, as GCC detects the capabilities of
8383the assembler when it is built and sets the default accordingly.
8384
8385@item -msmall-data
8386@itemx -mlarge-data
8387@opindex msmall-data
8388@opindex mlarge-data
8389When @option{-mexplicit-relocs} is in effect, static data is
8390accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
8391is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
8392(the @code{.sdata} and @code{.sbss} sections) and are accessed via
839316-bit relocations off of the @code{$gp} register. This limits the
8394size of the small data area to 64KB, but allows the variables to be
8395directly accessed via a single instruction.
8396
8397The default is @option{-mlarge-data}. With this option the data area
8398is limited to just below 2GB@. Programs that require more than 2GB of
8399data must use @code{malloc} or @code{mmap} to allocate the data in the
8400heap instead of in the program's data segment.
8401
8402When generating code for shared libraries, @option{-fpic} implies
8403@option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
8404
8405@item -msmall-text
8406@itemx -mlarge-text
8407@opindex msmall-text
8408@opindex mlarge-text
8409When @option{-msmall-text} is used, the compiler assumes that the
8410code of the entire program (or shared library) fits in 4MB, and is
8411thus reachable with a branch instruction. When @option{-msmall-data}
8412is used, the compiler can assume that all local symbols share the
8413same @code{$gp} value, and thus reduce the number of instructions
8414required for a function call from 4 to 1.
8415
8416The default is @option{-mlarge-text}.
8417
8418@item -mcpu=@var{cpu_type}
8419@opindex mcpu
8420Set the instruction set and instruction scheduling parameters for
8421machine type @var{cpu_type}. You can specify either the @samp{EV}
8422style name or the corresponding chip number. GCC supports scheduling
8423parameters for the EV4, EV5 and EV6 family of processors and will
8424choose the default values for the instruction set from the processor
8425you specify. If you do not specify a processor type, GCC will default
8426to the processor on which the compiler was built.
8427
8428Supported values for @var{cpu_type} are
8429
8430@table @samp
8431@item ev4
8432@itemx ev45
8433@itemx 21064
8434Schedules as an EV4 and has no instruction set extensions.
8435
8436@item ev5
8437@itemx 21164
8438Schedules as an EV5 and has no instruction set extensions.
8439
8440@item ev56
8441@itemx 21164a
8442Schedules as an EV5 and supports the BWX extension.
8443
8444@item pca56
8445@itemx 21164pc
8446@itemx 21164PC
8447Schedules as an EV5 and supports the BWX and MAX extensions.
8448
8449@item ev6
8450@itemx 21264
8451Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
8452
8453@item ev67
8454@itemx 21264a
8455Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
8456@end table
8457
8458@item -mtune=@var{cpu_type}
8459@opindex mtune
8460Set only the instruction scheduling parameters for machine type
8461@var{cpu_type}. The instruction set is not changed.
8462
8463@item -mmemory-latency=@var{time}
8464@opindex mmemory-latency
8465Sets the latency the scheduler should assume for typical memory
8466references as seen by the application. This number is highly
8467dependent on the memory access patterns used by the application
8468and the size of the external cache on the machine.
8469
8470Valid options for @var{time} are
8471
8472@table @samp
8473@item @var{number}
8474A decimal number representing clock cycles.
8475
8476@item L1
8477@itemx L2
8478@itemx L3
8479@itemx main
8480The compiler contains estimates of the number of clock cycles for
8481``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
8482(also called Dcache, Scache, and Bcache), as well as to main memory.
8483Note that L3 is only valid for EV5.
8484
8485@end table
8486@end table
8487
8488@node DEC Alpha/VMS Options
8489@subsection DEC Alpha/VMS Options
8490
8491These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
8492
8493@table @gcctabopt
8494@item -mvms-return-codes
8495@opindex mvms-return-codes
8496Return VMS condition codes from main. The default is to return POSIX
8497style condition (e.g.@ error) codes.
8498@end table
8499
8500@node FRV Options
8501@subsection FRV Options
8502@cindex FRV Options
8503
8504@table @gcctabopt
8505@item -mgpr-32
8506@opindex mgpr-32
8507
8508Only use the first 32 general purpose registers.
8509
8510@item -mgpr-64
8511@opindex mgpr-64
8512
8513Use all 64 general purpose registers.
8514
8515@item -mfpr-32
8516@opindex mfpr-32
8517
8518Use only the first 32 floating point registers.
8519
8520@item -mfpr-64
8521@opindex mfpr-64
8522
8523Use all 64 floating point registers
8524
8525@item -mhard-float
8526@opindex mhard-float
8527
8528Use hardware instructions for floating point operations.
8529
8530@item -msoft-float
8531@opindex msoft-float
8532
8533Use library routines for floating point operations.
8534
8535@item -malloc-cc
8536@opindex malloc-cc
8537
8538Dynamically allocate condition code registers.
8539
8540@item -mfixed-cc
8541@opindex mfixed-cc
8542
8543Do not try to dynamically allocate condition code registers, only
8544use @code{icc0} and @code{fcc0}.
8545
8546@item -mdword
8547@opindex mdword
8548
8549Change ABI to use double word insns.
8550
8551@item -mno-dword
8552@opindex mno-dword
8553
8554Do not use double word instructions.
8555
8556@item -mdouble
8557@opindex mdouble
8558
8559Use floating point double instructions.
8560
8561@item -mno-double
8562@opindex mno-double
8563
8564Do not use floating point double instructions.
8565
8566@item -mmedia
8567@opindex mmedia
8568
8569Use media instructions.
8570
8571@item -mno-media
8572@opindex mno-media
8573
8574Do not use media instructions.
8575
8576@item -mmuladd
8577@opindex mmuladd
8578
8579Use multiply and add/subtract instructions.
8580
8581@item -mno-muladd
8582@opindex mno-muladd
8583
8584Do not use multiply and add/subtract instructions.
8585
8586@item -mfdpic
8587@opindex mfdpic
8588
8589Select the FDPIC ABI, that uses function descriptors to represent
8590pointers to functions. Without any PIC/PIE-related options, it
8591implies @option{-fPIE}. With @option{-fpic} or @option{-fpie}, it
8592assumes GOT entries and small data are within a 12-bit range from the
8593GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
8594are computed with 32 bits.
8595
8596@item -minline-plt
8597@opindex minline-plt
8598
8599Enable inlining of PLT entries in function calls to functions that are
8600not known to bind locally. It has no effect without @option{-mfdpic}.
8601It's enabled by default if optimizing for speed and compiling for
8602shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
8603optimization option such as @option{-O3} or above is present in the
8604command line.
8605
8606@item -mTLS
8607@opindex TLS
8608
8609Assume a large TLS segment when generating thread-local code.
8610
8611@item -mtls
8612@opindex tls
8613
8614Do not assume a large TLS segment when generating thread-local code.
8615
8616@item -mgprel-ro
8617@opindex mgprel-ro
8618
8619Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
8620that is known to be in read-only sections. It's enabled by default,
8621except for @option{-fpic} or @option{-fpie}: even though it may help
8622make the global offset table smaller, it trades 1 instruction for 4.
8623With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
8624one of which may be shared by multiple symbols, and it avoids the need
8625for a GOT entry for the referenced symbol, so it's more likely to be a
8626win. If it is not, @option{-mno-gprel-ro} can be used to disable it.
8627
8628@item -multilib-library-pic
8629@opindex multilib-library-pic
8630
8631Link with the (library, not FD) pic libraries. It's implied by
8632@option{-mlibrary-pic}, as well as by @option{-fPIC} and
8633@option{-fpic} without @option{-mfdpic}. You should never have to use
8634it explicitly.
8635
8636@item -mlinked-fp
8637@opindex mlinked-fp
8638
8639Follow the EABI requirement of always creating a frame pointer whenever
8640a stack frame is allocated. This option is enabled by default and can
8641be disabled with @option{-mno-linked-fp}.
8642
8643@item -mlong-calls
8644@opindex mlong-calls
8645
8646Use indirect addressing to call functions outside the current
8647compilation unit. This allows the functions to be placed anywhere
8648within the 32-bit address space.
8649
8650@item -malign-labels
8651@opindex malign-labels
8652
8653Try to align labels to an 8-byte boundary by inserting nops into the
8654previous packet. This option only has an effect when VLIW packing
8655is enabled. It doesn't create new packets; it merely adds nops to
8656existing ones.
8657
8658@item -mlibrary-pic
8659@opindex mlibrary-pic
8660
8661Generate position-independent EABI code.
8662
8663@item -macc-4
8664@opindex macc-4
8665
8666Use only the first four media accumulator registers.
8667
8668@item -macc-8
8669@opindex macc-8
8670
8671Use all eight media accumulator registers.
8672
8673@item -mpack
8674@opindex mpack
8675
8676Pack VLIW instructions.
8677
8678@item -mno-pack
8679@opindex mno-pack
8680
8681Do not pack VLIW instructions.
8682
8683@item -mno-eflags
8684@opindex mno-eflags
8685
8686Do not mark ABI switches in e_flags.
8687
8688@item -mcond-move
8689@opindex mcond-move
8690
8691Enable the use of conditional-move instructions (default).
8692
8693This switch is mainly for debugging the compiler and will likely be removed
8694in a future version.
8695
8696@item -mno-cond-move
8697@opindex mno-cond-move
8698
8699Disable the use of conditional-move instructions.
8700
8701This switch is mainly for debugging the compiler and will likely be removed
8702in a future version.
8703
8704@item -mscc
8705@opindex mscc
8706
8707Enable the use of conditional set instructions (default).
8708
8709This switch is mainly for debugging the compiler and will likely be removed
8710in a future version.
8711
8712@item -mno-scc
8713@opindex mno-scc
8714
8715Disable the use of conditional set instructions.
8716
8717This switch is mainly for debugging the compiler and will likely be removed
8718in a future version.
8719
8720@item -mcond-exec
8721@opindex mcond-exec
8722
8723Enable the use of conditional execution (default).
8724
8725This switch is mainly for debugging the compiler and will likely be removed
8726in a future version.
8727
8728@item -mno-cond-exec
8729@opindex mno-cond-exec
8730
8731Disable the use of conditional execution.
8732
8733This switch is mainly for debugging the compiler and will likely be removed
8734in a future version.
8735
8736@item -mvliw-branch
8737@opindex mvliw-branch
8738
8739Run a pass to pack branches into VLIW instructions (default).
8740
8741This switch is mainly for debugging the compiler and will likely be removed
8742in a future version.
8743
8744@item -mno-vliw-branch
8745@opindex mno-vliw-branch
8746
8747Do not run a pass to pack branches into VLIW instructions.
8748
8749This switch is mainly for debugging the compiler and will likely be removed
8750in a future version.
8751
8752@item -mmulti-cond-exec
8753@opindex mmulti-cond-exec
8754
8755Enable optimization of @code{&&} and @code{||} in conditional execution
8756(default).
8757
8758This switch is mainly for debugging the compiler and will likely be removed
8759in a future version.
8760
8761@item -mno-multi-cond-exec
8762@opindex mno-multi-cond-exec
8763
8764Disable optimization of @code{&&} and @code{||} in conditional execution.
8765
8766This switch is mainly for debugging the compiler and will likely be removed
8767in a future version.
8768
8769@item -mnested-cond-exec
8770@opindex mnested-cond-exec
8771
8772Enable nested conditional execution optimizations (default).
8773
8774This switch is mainly for debugging the compiler and will likely be removed
8775in a future version.
8776
8777@item -mno-nested-cond-exec
8778@opindex mno-nested-cond-exec
8779
8780Disable nested conditional execution optimizations.
8781
8782This switch is mainly for debugging the compiler and will likely be removed
8783in a future version.
8784
8785@item -moptimize-membar
8786@opindex moptimize-membar
8787
8788This switch removes redundant @code{membar} instructions from the
8789compiler generated code. It is enabled by default.
8790
8791@item -mno-optimize-membar
8792@opindex mno-optimize-membar
8793
8794This switch disables the automatic removal of redundant @code{membar}
8795instructions from the generated code.
8796
8797@item -mtomcat-stats
8798@opindex mtomcat-stats
8799
8800Cause gas to print out tomcat statistics.
8801
8802@item -mcpu=@var{cpu}
8803@opindex mcpu
8804
8805Select the processor type for which to generate code. Possible values are
8806@samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
8807@samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
8808
8809@end table
8810
8811@node GNU/Linux Options
8812@subsection GNU/Linux Options
8813
8814These @samp{-m} options are defined for GNU/Linux targets:
8815
8816@table @gcctabopt
8817@item -mglibc
8818@opindex mglibc
8819Use the GNU C library instead of uClibc. This is the default except
8820on @samp{*-*-linux-*uclibc*} targets.
8821
8822@item -muclibc
8823@opindex muclibc
8824Use uClibc instead of the GNU C library. This is the default on
8825@samp{*-*-linux-*uclibc*} targets.
8826@end table
8827
8828@node H8/300 Options
8829@subsection H8/300 Options
8830
8831These @samp{-m} options are defined for the H8/300 implementations:
8832
8833@table @gcctabopt
8834@item -mrelax
8835@opindex mrelax
8836Shorten some address references at link time, when possible; uses the
8837linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
8838ld, Using ld}, for a fuller description.
8839
8840@item -mh
8841@opindex mh
8842Generate code for the H8/300H@.
8843
8844@item -ms
8845@opindex ms
8846Generate code for the H8S@.
8847
8848@item -mn
8849@opindex mn
8850Generate code for the H8S and H8/300H in the normal mode. This switch
8851must be used either with @option{-mh} or @option{-ms}.
8852
8853@item -ms2600
8854@opindex ms2600
8855Generate code for the H8S/2600. This switch must be used with @option{-ms}.
8856
8857@item -mint32
8858@opindex mint32
8859Make @code{int} data 32 bits by default.
8860
8861@item -malign-300
8862@opindex malign-300
8863On the H8/300H and H8S, use the same alignment rules as for the H8/300.
8864The default for the H8/300H and H8S is to align longs and floats on 4
8865byte boundaries.
8866@option{-malign-300} causes them to be aligned on 2 byte boundaries.
8867This option has no effect on the H8/300.
8868@end table
8869
8870@node HPPA Options
8871@subsection HPPA Options
8872@cindex HPPA Options
8873
8874These @samp{-m} options are defined for the HPPA family of computers:
8875
8876@table @gcctabopt
8877@item -march=@var{architecture-type}
8878@opindex march
8879Generate code for the specified architecture. The choices for
8880@var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
88811.1, and @samp{2.0} for PA 2.0 processors. Refer to
8882@file{/usr/lib/sched.models} on an HP-UX system to determine the proper
8883architecture option for your machine. Code compiled for lower numbered
8884architectures will run on higher numbered architectures, but not the
8885other way around.
8886
8887@item -mpa-risc-1-0
8888@itemx -mpa-risc-1-1
8889@itemx -mpa-risc-2-0
8890@opindex mpa-risc-1-0
8891@opindex mpa-risc-1-1
8892@opindex mpa-risc-2-0
8893Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
8894
8895@item -mbig-switch
8896@opindex mbig-switch
8897Generate code suitable for big switch tables. Use this option only if
8898the assembler/linker complain about out of range branches within a switch
8899table.
8900
8901@item -mjump-in-delay
8902@opindex mjump-in-delay
8903Fill delay slots of function calls with unconditional jump instructions
8904by modifying the return pointer for the function call to be the target
8905of the conditional jump.
8906
8907@item -mdisable-fpregs
8908@opindex mdisable-fpregs
8909Prevent floating point registers from being used in any manner. This is
8910necessary for compiling kernels which perform lazy context switching of
8911floating point registers. If you use this option and attempt to perform
8912floating point operations, the compiler will abort.
8913
8914@item -mdisable-indexing
8915@opindex mdisable-indexing
8916Prevent the compiler from using indexing address modes. This avoids some
8917rather obscure problems when compiling MIG generated code under MACH@.
8918
8919@item -mno-space-regs
8920@opindex mno-space-regs
8921Generate code that assumes the target has no space registers. This allows
8922GCC to generate faster indirect calls and use unscaled index address modes.
8923
8924Such code is suitable for level 0 PA systems and kernels.
8925
8926@item -mfast-indirect-calls
8927@opindex mfast-indirect-calls
8928Generate code that assumes calls never cross space boundaries. This
8929allows GCC to emit code which performs faster indirect calls.
8930
8931This option will not work in the presence of shared libraries or nested
8932functions.
8933
8934@item -mfixed-range=@var{register-range}
8935@opindex mfixed-range
8936Generate code treating the given register range as fixed registers.
8937A fixed register is one that the register allocator can not use. This is
8938useful when compiling kernel code. A register range is specified as
8939two registers separated by a dash. Multiple register ranges can be
8940specified separated by a comma.
8941
8942@item -mlong-load-store
8943@opindex mlong-load-store
8944Generate 3-instruction load and store sequences as sometimes required by
8945the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
8946the HP compilers.
8947
8948@item -mportable-runtime
8949@opindex mportable-runtime
8950Use the portable calling conventions proposed by HP for ELF systems.
8951
8952@item -mgas
8953@opindex mgas
8954Enable the use of assembler directives only GAS understands.
8955
8956@item -mschedule=@var{cpu-type}
8957@opindex mschedule
8958Schedule code according to the constraints for the machine type
8959@var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
8960@samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer
8961to @file{/usr/lib/sched.models} on an HP-UX system to determine the
8962proper scheduling option for your machine. The default scheduling is
8963@samp{8000}.
8964
8965@item -mlinker-opt
8966@opindex mlinker-opt
8967Enable the optimization pass in the HP-UX linker. Note this makes symbolic
8968debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9
8969linkers in which they give bogus error messages when linking some programs.
8970
8971@item -msoft-float
8972@opindex msoft-float
8973Generate output containing library calls for floating point.
8974@strong{Warning:} the requisite libraries are not available for all HPPA
8975targets. Normally the facilities of the machine's usual C compiler are
8976used, but this cannot be done directly in cross-compilation. You must make
8977your own arrangements to provide suitable library functions for
8978cross-compilation. The embedded target @samp{hppa1.1-*-pro}
8979does provide software floating point support.
8980
8981@option{-msoft-float} changes the calling convention in the output file;
8982therefore, it is only useful if you compile @emph{all} of a program with
8983this option. In particular, you need to compile @file{libgcc.a}, the
8984library that comes with GCC, with @option{-msoft-float} in order for
8985this to work.
8986
8987@item -msio
8988@opindex msio
8989Generate the predefine, @code{_SIO}, for server IO@. The default is
8990@option{-mwsio}. This generates the predefines, @code{__hp9000s700},
8991@code{__hp9000s700__} and @code{_WSIO}, for workstation IO@. These
8992options are available under HP-UX and HI-UX@.
8993
8994@item -mgnu-ld
8995@opindex gnu-ld
8996Use GNU ld specific options. This passes @option{-shared} to ld when
8997building a shared library. It is the default when GCC is configured,
8998explicitly or implicitly, with the GNU linker. This option does not
8999have any affect on which ld is called, it only changes what parameters
9000are passed to that ld. The ld that is called is determined by the
9001@option{--with-ld} configure option, GCC's program search path, and
9002finally by the user's @env{PATH}. The linker used by GCC can be printed
9003using @samp{which `gcc -print-prog-name=ld`}. This option is only available
9004on the 64 bit HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
9005
9006@item -mhp-ld
9007@opindex hp-ld
9008Use HP ld specific options. This passes @option{-b} to ld when building
9009a shared library and passes @option{+Accept TypeMismatch} to ld on all
9010links. It is the default when GCC is configured, explicitly or
9011implicitly, with the HP linker. This option does not have any affect on
9012which ld is called, it only changes what parameters are passed to that
9013ld. The ld that is called is determined by the @option{--with-ld}
9014configure option, GCC's program search path, and finally by the user's
9015@env{PATH}. The linker used by GCC can be printed using @samp{which
9016`gcc -print-prog-name=ld`}. This option is only available on the 64 bit
9017HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
9018
9019@item -mlong-calls
9020@opindex mno-long-calls
9021Generate code that uses long call sequences. This ensures that a call
9022is always able to reach linker generated stubs. The default is to generate
9023long calls only when the distance from the call site to the beginning
9024of the function or translation unit, as the case may be, exceeds a
9025predefined limit set by the branch type being used. The limits for
9026normal calls are 7,600,000 and 240,000 bytes, respectively for the
9027PA 2.0 and PA 1.X architectures. Sibcalls are always limited at
9028240,000 bytes.
9029
9030Distances are measured from the beginning of functions when using the
9031@option{-ffunction-sections} option, or when using the @option{-mgas}
9032and @option{-mno-portable-runtime} options together under HP-UX with
9033the SOM linker.
9034
9035It is normally not desirable to use this option as it will degrade
9036performance. However, it may be useful in large applications,
9037particularly when partial linking is used to build the application.
9038
9039The types of long calls used depends on the capabilities of the
9040assembler and linker, and the type of code being generated. The
9041impact on systems that support long absolute calls, and long pic
9042symbol-difference or pc-relative calls should be relatively small.
9043However, an indirect call is used on 32-bit ELF systems in pic code
9044and it is quite long.
9045
9046@item -munix=@var{unix-std}
9047@opindex march
9048Generate compiler predefines and select a startfile for the specified
9049UNIX standard. The choices for @var{unix-std} are @samp{93}, @samp{95}
9050and @samp{98}. @samp{93} is supported on all HP-UX versions. @samp{95}
9051is available on HP-UX 10.10 and later. @samp{98} is available on HP-UX
905211.11 and later. The default values are @samp{93} for HP-UX 10.00,
9053@samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
9054and later.
9055
9056@option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
9057@option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
9058and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
9059@option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
9060@code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
9061@code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
9062
9063It is @emph{important} to note that this option changes the interfaces
9064for various library routines. It also affects the operational behavior
9065of the C library. Thus, @emph{extreme} care is needed in using this
9066option.
9067
9068Library code that is intended to operate with more than one UNIX
9069standard must test, set and restore the variable @var{__xpg4_extended_mask}
9070as appropriate. Most GNU software doesn't provide this capability.
9071
9072@item -nolibdld
9073@opindex nolibdld
9074Suppress the generation of link options to search libdld.sl when the
9075@option{-static} option is specified on HP-UX 10 and later.
9076
9077@item -static
9078@opindex static
9079The HP-UX implementation of setlocale in libc has a dependency on
9080libdld.sl. There isn't an archive version of libdld.sl. Thus,
9081when the @option{-static} option is specified, special link options
9082are needed to resolve this dependency.
9083
9084On HP-UX 10 and later, the GCC driver adds the necessary options to
9085link with libdld.sl when the @option{-static} option is specified.
9086This causes the resulting binary to be dynamic. On the 64-bit port,
9087the linkers generate dynamic binaries by default in any case. The
9088@option{-nolibdld} option can be used to prevent the GCC driver from
9089adding these link options.
9090
9091@item -threads
9092@opindex threads
9093Add support for multithreading with the @dfn{dce thread} library
9094under HP-UX@. This option sets flags for both the preprocessor and
9095linker.
9096@end table
9097
9098@node i386 and x86-64 Options
9099@subsection Intel 386 and AMD x86-64 Options
9100@cindex i386 Options
9101@cindex x86-64 Options
9102@cindex Intel 386 Options
9103@cindex AMD x86-64 Options
9104
9105These @samp{-m} options are defined for the i386 and x86-64 family of
9106computers:
9107
9108@table @gcctabopt
9109@item -mtune=@var{cpu-type}
9110@opindex mtune
9111Tune to @var{cpu-type} everything applicable about the generated code, except
9112for the ABI and the set of available instructions. The choices for
9113@var{cpu-type} are:
9114@table @emph
9115@item generic
9116Produce code optimized for the most common IA32/AMD64/EM64T processors.
9117If you know the CPU on which your code will run, then you should use
9118the corresponding @option{-mtune} option instead of
9119@option{-mtune=generic}. But, if you do not know exactly what CPU users
9120of your application will have, then you should use this option.
9121
9122As new processors are deployed in the marketplace, the behavior of this
9123option will change. Therefore, if you upgrade to a newer version of
9124GCC, the code generated option will change to reflect the processors
9125that were most common when that version of GCC was released.
9126
9127There is no @option{-march=generic} option because @option{-march}
9128indicates the instruction set the compiler can use, and there is no
9129generic instruction set applicable to all processors. In contrast,
9130@option{-mtune} indicates the processor (or, in this case, collection of
9131processors) for which the code is optimized.
9132@item native
9133This selects the CPU to tune for at compilation time by determining
9134the processor type of the compiling machine. Using @option{-mtune=native}
9135will produce code optimized for the local machine under the constraints
9136of the selected instruction set. Using @option{-march=native} will
9137enable all instruction subsets supported by the local machine (hence
9138the result might not run on different machines).
9139@item i386
9140Original Intel's i386 CPU@.
9141@item i486
9142Intel's i486 CPU@. (No scheduling is implemented for this chip.)
9143@item i586, pentium
9144Intel Pentium CPU with no MMX support.
9145@item pentium-mmx
9146Intel PentiumMMX CPU based on Pentium core with MMX instruction set support.
9147@item pentiumpro
9148Intel PentiumPro CPU@.
9149@item i686
9150Same as @code{generic}, but when used as @code{march} option, PentiumPro
9151instruction set will be used, so the code will run on all i686 family chips.
9152@item pentium2
9153Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support.
9154@item pentium3, pentium3m
9155Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set
9156support.
9157@item pentium-m
9158Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set
9159support. Used by Centrino notebooks.
9160@item pentium4, pentium4m
9161Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support.
9162@item prescott
9163Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction
9164set support.
9165@item nocona
9166Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE,
9167SSE2 and SSE3 instruction set support.
9168@item core2
9169Intel Core2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3
9170instruction set support.
9171@item k6
9172AMD K6 CPU with MMX instruction set support.
9173@item k6-2, k6-3
9174Improved versions of AMD K6 CPU with MMX and 3dNOW! instruction set support.
9175@item athlon, athlon-tbird
9176AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and SSE prefetch instructions
9177support.
9178@item athlon-4, athlon-xp, athlon-mp
9179Improved AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and full SSE
9180instruction set support.
9181@item k8, opteron, athlon64, athlon-fx
9182AMD K8 core based CPUs with x86-64 instruction set support. (This supersets
9183MMX, SSE, SSE2, 3dNOW!, enhanced 3dNOW! and 64-bit instruction set extensions.)
9184@item k8-sse3, opteron-sse3, athlon64-sse3
9185Improved versions of k8, opteron and athlon64 with SSE3 instruction set support.
9186@item amdfam10, barcelona
9187AMD Family 10h core based CPUs with x86-64 instruction set support. (This
9188supersets MMX, SSE, SSE2, SSE3, SSE4A, 3dNOW!, enhanced 3dNOW!, ABM and 64-bit
9189instruction set extensions.)
9190@item winchip-c6
9191IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction
9192set support.
9193@item winchip2
9194IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3dNOW!
9195instruction set support.
9196@item c3
9197Via C3 CPU with MMX and 3dNOW! instruction set support. (No scheduling is
9198implemented for this chip.)
9199@item c3-2
9200Via C3-2 CPU with MMX and SSE instruction set support. (No scheduling is
9201implemented for this chip.)
9202@item geode
9203Embedded AMD CPU with MMX and 3dNOW! instruction set support.
9204@end table
9205
9206While picking a specific @var{cpu-type} will schedule things appropriately
9207for that particular chip, the compiler will not generate any code that
9208does not run on the i386 without the @option{-march=@var{cpu-type}} option
9209being used.
9210
9211@item -march=@var{cpu-type}
9212@opindex march
9213Generate instructions for the machine type @var{cpu-type}. The choices
9214for @var{cpu-type} are the same as for @option{-mtune}. Moreover,
9215specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}.
9216
9217@item -mcpu=@var{cpu-type}
9218@opindex mcpu
9219A deprecated synonym for @option{-mtune}.
9220
9221@item -m386
9222@itemx -m486
9223@itemx -mpentium
9224@itemx -mpentiumpro
9225@opindex m386
9226@opindex m486
9227@opindex mpentium
9228@opindex mpentiumpro
9229These options are synonyms for @option{-mtune=i386}, @option{-mtune=i486},
9230@option{-mtune=pentium}, and @option{-mtune=pentiumpro} respectively.
9231These synonyms are deprecated.
9232
9233@item -mfpmath=@var{unit}
9234@opindex march
9235Generate floating point arithmetics for selected unit @var{unit}. The choices
9236for @var{unit} are:
9237
9238@table @samp
9239@item 387
9240Use the standard 387 floating point coprocessor present majority of chips and
9241emulated otherwise. Code compiled with this option will run almost everywhere.
9242The temporary results are computed in 80bit precision instead of precision
9243specified by the type resulting in slightly different results compared to most
9244of other chips. See @option{-ffloat-store} for more detailed description.
9245
9246This is the default choice for i386 compiler.
9247
9248@item sse
9249Use scalar floating point instructions present in the SSE instruction set.
9250This instruction set is supported by Pentium3 and newer chips, in the AMD line
9251by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE
9252instruction set supports only single precision arithmetics, thus the double and
9253extended precision arithmetics is still done using 387. Later version, present
9254only in Pentium4 and the future AMD x86-64 chips supports double precision
9255arithmetics too.
9256
9257For the i386 compiler, you need to use @option{-march=@var{cpu-type}}, @option{-msse}
9258or @option{-msse2} switches to enable SSE extensions and make this option
9259effective. For the x86-64 compiler, these extensions are enabled by default.
9260
9261The resulting code should be considerably faster in the majority of cases and avoid
9262the numerical instability problems of 387 code, but may break some existing
9263code that expects temporaries to be 80bit.
9264
9265This is the default choice for the x86-64 compiler.
9266
9267@item sse,387
9268Attempt to utilize both instruction sets at once. This effectively double the
9269amount of available registers and on chips with separate execution units for
9270387 and SSE the execution resources too. Use this option with care, as it is
9271still experimental, because the GCC register allocator does not model separate
9272functional units well resulting in instable performance.
9273@end table
9274
9275@item -masm=@var{dialect}
9276@opindex masm=@var{dialect}
9277Output asm instructions using selected @var{dialect}. Supported
9278choices are @samp{intel} or @samp{att} (the default one). Darwin does
9279not support @samp{intel}.
9280
9281@item -mieee-fp
9282@itemx -mno-ieee-fp
9283@opindex mieee-fp
9284@opindex mno-ieee-fp
9285Control whether or not the compiler uses IEEE floating point
9286comparisons. These handle correctly the case where the result of a
9287comparison is unordered.
9288
9289@item -msoft-float
9290@opindex msoft-float
9291Generate output containing library calls for floating point.
9292@strong{Warning:} the requisite libraries are not part of GCC@.
9293Normally the facilities of the machine's usual C compiler are used, but
9294this can't be done directly in cross-compilation. You must make your
9295own arrangements to provide suitable library functions for
9296cross-compilation.
9297
9298On machines where a function returns floating point results in the 80387
9299register stack, some floating point opcodes may be emitted even if
9300@option{-msoft-float} is used.
9301
9302@item -mno-fp-ret-in-387
9303@opindex mno-fp-ret-in-387
9304Do not use the FPU registers for return values of functions.
9305
9306The usual calling convention has functions return values of types
9307@code{float} and @code{double} in an FPU register, even if there
9308is no FPU@. The idea is that the operating system should emulate
9309an FPU@.
9310
9311The option @option{-mno-fp-ret-in-387} causes such values to be returned
9312in ordinary CPU registers instead.
9313
9314@item -mno-fancy-math-387
9315@opindex mno-fancy-math-387
9316Some 387 emulators do not support the @code{sin}, @code{cos} and
9317@code{sqrt} instructions for the 387. Specify this option to avoid
9318generating those instructions. This option is the default on
9319OpenBSD and NetBSD@. This option is overridden when @option{-march}
9320indicates that the target cpu will always have an FPU and so the
9321instruction will not need emulation. As of revision 2.6.1, these
9322instructions are not generated unless you also use the
9323@option{-funsafe-math-optimizations} switch.
9324
9325@item -malign-double
9326@itemx -mno-align-double
9327@opindex malign-double
9328@opindex mno-align-double
9329Control whether GCC aligns @code{double}, @code{long double}, and
9330@code{long long} variables on a two word boundary or a one word
9331boundary. Aligning @code{double} variables on a two word boundary will
9332produce code that runs somewhat faster on a @samp{Pentium} at the
9333expense of more memory.
9334
9335On x86-64, @option{-malign-double} is enabled by default.
9336
9337@strong{Warning:} if you use the @option{-malign-double} switch,
9338structures containing the above types will be aligned differently than
9339the published application binary interface specifications for the 386
9340and will not be binary compatible with structures in code compiled
9341without that switch.
9342
9343@item -m96bit-long-double
9344@itemx -m128bit-long-double
9345@opindex m96bit-long-double
9346@opindex m128bit-long-double
9347These switches control the size of @code{long double} type. The i386
9348application binary interface specifies the size to be 96 bits,
9349so @option{-m96bit-long-double} is the default in 32 bit mode.
9350
9351Modern architectures (Pentium and newer) would prefer @code{long double}
9352to be aligned to an 8 or 16 byte boundary. In arrays or structures
9353conforming to the ABI, this would not be possible. So specifying a
9354@option{-m128bit-long-double} will align @code{long double}
9355to a 16 byte boundary by padding the @code{long double} with an additional
935632 bit zero.
9357
9358In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
9359its ABI specifies that @code{long double} is to be aligned on 16 byte boundary.
9360
9361Notice that neither of these options enable any extra precision over the x87
9362standard of 80 bits for a @code{long double}.
9363
9364@strong{Warning:} if you override the default value for your target ABI, the
9365structures and arrays containing @code{long double} variables will change
9366their size as well as function calling convention for function taking
9367@code{long double} will be modified. Hence they will not be binary
9368compatible with arrays or structures in code compiled without that switch.
9369
9370@item -mmlarge-data-threshold=@var{number}
9371@opindex mlarge-data-threshold=@var{number}
9372When @option{-mcmodel=medium} is specified, the data greater than
9373@var{threshold} are placed in large data section. This value must be the
9374same across all object linked into the binary and defaults to 65535.
9375
9376@item -msvr3-shlib
9377@itemx -mno-svr3-shlib
9378@opindex msvr3-shlib
9379@opindex mno-svr3-shlib
9380Control whether GCC places uninitialized local variables into the
9381@code{bss} or @code{data} segments. @option{-msvr3-shlib} places them
9382into @code{bss}. These options are meaningful only on System V Release 3.
9383
9384@item -mrtd
9385@opindex mrtd
9386Use a different function-calling convention, in which functions that
9387take a fixed number of arguments return with the @code{ret} @var{num}
9388instruction, which pops their arguments while returning. This saves one
9389instruction in the caller since there is no need to pop the arguments
9390there.
9391
9392You can specify that an individual function is called with this calling
9393sequence with the function attribute @samp{stdcall}. You can also
9394override the @option{-mrtd} option by using the function attribute
9395@samp{cdecl}. @xref{Function Attributes}.
9396
9397@strong{Warning:} this calling convention is incompatible with the one
9398normally used on Unix, so you cannot use it if you need to call
9399libraries compiled with the Unix compiler.
9400
9401Also, you must provide function prototypes for all functions that
9402take variable numbers of arguments (including @code{printf});
9403otherwise incorrect code will be generated for calls to those
9404functions.
9405
9406In addition, seriously incorrect code will result if you call a
9407function with too many arguments. (Normally, extra arguments are
9408harmlessly ignored.)
9409
9410@item -mregparm=@var{num}
9411@opindex mregparm
9412Control how many registers are used to pass integer arguments. By
9413default, no registers are used to pass arguments, and at most 3
9414registers can be used. You can control this behavior for a specific
9415function by using the function attribute @samp{regparm}.
9416@xref{Function Attributes}.
9417
9418@strong{Warning:} if you use this switch, and
9419@var{num} is nonzero, then you must build all modules with the same
9420value, including any libraries. This includes the system libraries and
9421startup modules.
9422
9423@item -msseregparm
9424@opindex msseregparm
9425Use SSE register passing conventions for float and double arguments
9426and return values. You can control this behavior for a specific
9427function by using the function attribute @samp{sseregparm}.
9428@xref{Function Attributes}.
9429
9430@strong{Warning:} if you use this switch then you must build all
9431modules with the same value, including any libraries. This includes
9432the system libraries and startup modules.
9433
9434@item -mstackrealign
9435@opindex mstackrealign
9436Realign the stack at entry. On the Intel x86, the
9437@option{-mstackrealign} option will generate an alternate prologue and
9438epilogue that realigns the runtime stack. This supports mixing legacy
9439codes that keep a 4-byte aligned stack with modern codes that keep a
944016-byte stack for SSE compatibility. The alternate prologue and
9441epilogue are slower and bigger than the regular ones, and the
9442alternate prologue requires an extra scratch register; this lowers the
9443number of registers available if used in conjunction with the
9444@code{regparm} attribute. The @option{-mstackrealign} option is
9445incompatible with the nested function prologue; this is considered a
9446hard error. See also the attribute @code{force_align_arg_pointer},
9447applicable to individual functions.
9448
9449@item -mpreferred-stack-boundary=@var{num}
9450@opindex mpreferred-stack-boundary
9451Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
9452byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
9453the default is 4 (16 bytes or 128 bits).
9454
9455On Pentium and PentiumPro, @code{double} and @code{long double} values
9456should be aligned to an 8 byte boundary (see @option{-malign-double}) or
9457suffer significant run time performance penalties. On Pentium III, the
9458Streaming SIMD Extension (SSE) data type @code{__m128} may not work
9459properly if it is not 16 byte aligned.
9460
9461To ensure proper alignment of this values on the stack, the stack boundary
9462must be as aligned as that required by any value stored on the stack.
9463Further, every function must be generated such that it keeps the stack
9464aligned. Thus calling a function compiled with a higher preferred
9465stack boundary from a function compiled with a lower preferred stack
9466boundary will most likely misalign the stack. It is recommended that
9467libraries that use callbacks always use the default setting.
9468
9469This extra alignment does consume extra stack space, and generally
9470increases code size. Code that is sensitive to stack space usage, such
9471as embedded systems and operating system kernels, may want to reduce the
9472preferred alignment to @option{-mpreferred-stack-boundary=2}.
9473
9474@item -mmmx
9475@itemx -mno-mmx
9476@item -msse
9477@itemx -mno-sse
9478@item -msse2
9479@itemx -mno-sse2
9480@item -msse3
9481@itemx -mno-sse3
9482@item -mssse3
9483@itemx -mno-ssse3
9484@item -msse4a
9485@item -mno-sse4a
9486@item -m3dnow
9487@itemx -mno-3dnow
9488@item -mpopcnt
9489@itemx -mno-popcnt
9490@item -mabm
9491@itemx -mno-abm
9492@item -maes
9493@itemx -mno-aes
9494@opindex mmmx
9495@opindex mno-mmx
9496@opindex msse
9497@opindex mno-sse
9498@opindex m3dnow
9499@opindex mno-3dnow
9500These switches enable or disable the use of instructions in the MMX,
9501SSE, SSE2, SSE3, SSSE3, SSE4A, ABM, AES or 3DNow! extended
9502instruction sets. These extensions are also available as built-in
9503functions: see @ref{X86 Built-in Functions}, for details of the functions
9504enabled and disabled by these switches.
9505
9506To have SSE/SSE2 instructions generated automatically from floating-point
9507code (as opposed to 387 instructions), see @option{-mfpmath=sse}.
9508
9509These options will enable GCC to use these extended instructions in
9510generated code, even without @option{-mfpmath=sse}. Applications which
9511perform runtime CPU detection must compile separate files for each
9512supported architecture, using the appropriate flags. In particular,
9513the file containing the CPU detection code should be compiled without
9514these options.
9515
9516@item -mpush-args
9517@itemx -mno-push-args
9518@opindex mpush-args
9519@opindex mno-push-args
9520Use PUSH operations to store outgoing parameters. This method is shorter
9521and usually equally fast as method using SUB/MOV operations and is enabled
9522by default. In some cases disabling it may improve performance because of
9523improved scheduling and reduced dependencies.
9524
9525@item -maccumulate-outgoing-args
9526@opindex maccumulate-outgoing-args
9527If enabled, the maximum amount of space required for outgoing arguments will be
9528computed in the function prologue. This is faster on most modern CPUs
9529because of reduced dependencies, improved scheduling and reduced stack usage
9530when preferred stack boundary is not equal to 2. The drawback is a notable
9531increase in code size. This switch implies @option{-mno-push-args}.
9532
9533@item -mthreads
9534@opindex mthreads
9535Support thread-safe exception handling on @samp{Mingw32}. Code that relies
9536on thread-safe exception handling must compile and link all code with the
9537@option{-mthreads} option. When compiling, @option{-mthreads} defines
9538@option{-D_MT}; when linking, it links in a special thread helper library
9539@option{-lmingwthrd} which cleans up per thread exception handling data.
9540
9541@item -mno-align-stringops
9542@opindex mno-align-stringops
9543Do not align destination of inlined string operations. This switch reduces
9544code size and improves performance in case the destination is already aligned,
9545but GCC doesn't know about it.
9546
9547@item -minline-all-stringops
9548@opindex minline-all-stringops
9549By default GCC inlines string operations only when destination is known to be
9550aligned at least to 4 byte boundary. This enables more inlining, increase code
9551size, but may improve performance of code that depends on fast memcpy, strlen
9552and memset for short lengths.
9553
9554@item -momit-leaf-frame-pointer
9555@opindex momit-leaf-frame-pointer
9556Don't keep the frame pointer in a register for leaf functions. This
9557avoids the instructions to save, set up and restore frame pointers and
9558makes an extra register available in leaf functions. The option
9559@option{-fomit-frame-pointer} removes the frame pointer for all functions
9560which might make debugging harder.
9561
9562@item -mtls-direct-seg-refs
9563@itemx -mno-tls-direct-seg-refs
9564@opindex mtls-direct-seg-refs
9565Controls whether TLS variables may be accessed with offsets from the
9566TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
9567or whether the thread base pointer must be added. Whether or not this
9568is legal depends on the operating system, and whether it maps the
9569segment to cover the entire TLS area.
9570
9571For systems that use GNU libc, the default is on.
9572@end table
9573
9574These @samp{-m} switches are supported in addition to the above
9575on AMD x86-64 processors in 64-bit environments.
9576
9577@table @gcctabopt
9578@item -m32
9579@itemx -m64
9580@opindex m32
9581@opindex m64
9582Generate code for a 32-bit or 64-bit environment.
9583The 32-bit environment sets int, long and pointer to 32 bits and
9584generates code that runs on any i386 system.
9585The 64-bit environment sets int to 32 bits and long and pointer
9586to 64 bits and generates code for AMD's x86-64 architecture. For
9587darwin only the -m64 option turns off the @option{-fno-pic} and
9588@option{-mdynamic-no-pic} options.
9589
9590@item -mno-red-zone
9591@opindex no-red-zone
9592Do not use a so called red zone for x86-64 code. The red zone is mandated
9593by the x86-64 ABI, it is a 128-byte area beyond the location of the
9594stack pointer that will not be modified by signal or interrupt handlers
9595and therefore can be used for temporary data without adjusting the stack
9596pointer. The flag @option{-mno-red-zone} disables this red zone.
9597
9598@item -mcmodel=small
9599@opindex mcmodel=small
9600Generate code for the small code model: the program and its symbols must
9601be linked in the lower 2 GB of the address space. Pointers are 64 bits.
9602Programs can be statically or dynamically linked. This is the default
9603code model.
9604
9605@item -mcmodel=kernel
9606@opindex mcmodel=kernel
9607Generate code for the kernel code model. The kernel runs in the
9608negative 2 GB of the address space.
9609This model has to be used for Linux kernel code.
9610
9611@item -mcmodel=medium
9612@opindex mcmodel=medium
9613Generate code for the medium model: The program is linked in the lower 2
9614GB of the address space but symbols can be located anywhere in the
9615address space. Programs can be statically or dynamically linked, but
9616building of shared libraries are not supported with the medium model.
9617
9618@item -mcmodel=large
9619@opindex mcmodel=large
9620Generate code for the large model: This model makes no assumptions
9621about addresses and sizes of sections. Currently GCC does not implement
9622this model.
9623@end table
9624
9625@node IA-64 Options
9626@subsection IA-64 Options
9627@cindex IA-64 Options
9628
9629These are the @samp{-m} options defined for the Intel IA-64 architecture.
9630
9631@table @gcctabopt
9632@item -mbig-endian
9633@opindex mbig-endian
9634Generate code for a big endian target. This is the default for HP-UX@.
9635
9636@item -mlittle-endian
9637@opindex mlittle-endian
9638Generate code for a little endian target. This is the default for AIX5
9639and GNU/Linux.
9640
9641@item -mgnu-as
9642@itemx -mno-gnu-as
9643@opindex mgnu-as
9644@opindex mno-gnu-as
9645Generate (or don't) code for the GNU assembler. This is the default.
9646@c Also, this is the default if the configure option @option{--with-gnu-as}
9647@c is used.
9648
9649@item -mgnu-ld
9650@itemx -mno-gnu-ld
9651@opindex mgnu-ld
9652@opindex mno-gnu-ld
9653Generate (or don't) code for the GNU linker. This is the default.
9654@c Also, this is the default if the configure option @option{--with-gnu-ld}
9655@c is used.
9656
9657@item -mno-pic
9658@opindex mno-pic
9659Generate code that does not use a global pointer register. The result
9660is not position independent code, and violates the IA-64 ABI@.
9661
9662@item -mvolatile-asm-stop
9663@itemx -mno-volatile-asm-stop
9664@opindex mvolatile-asm-stop
9665@opindex mno-volatile-asm-stop
9666Generate (or don't) a stop bit immediately before and after volatile asm
9667statements.
9668
9669@item -mregister-names
9670@itemx -mno-register-names
9671@opindex mregister-names
9672@opindex mno-register-names
9673Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
9674the stacked registers. This may make assembler output more readable.
9675
9676@item -mno-sdata
9677@itemx -msdata
9678@opindex mno-sdata
9679@opindex msdata
9680Disable (or enable) optimizations that use the small data section. This may
9681be useful for working around optimizer bugs.
9682
9683@item -mconstant-gp
9684@opindex mconstant-gp
9685Generate code that uses a single constant global pointer value. This is
9686useful when compiling kernel code.
9687
9688@item -mauto-pic
9689@opindex mauto-pic
9690Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
9691This is useful when compiling firmware code.
9692
9693@item -minline-float-divide-min-latency
9694@opindex minline-float-divide-min-latency
9695Generate code for inline divides of floating point values
9696using the minimum latency algorithm.
9697
9698@item -minline-float-divide-max-throughput
9699@opindex minline-float-divide-max-throughput
9700Generate code for inline divides of floating point values
9701using the maximum throughput algorithm.
9702
9703@item -minline-int-divide-min-latency
9704@opindex minline-int-divide-min-latency
9705Generate code for inline divides of integer values
9706using the minimum latency algorithm.
9707
9708@item -minline-int-divide-max-throughput
9709@opindex minline-int-divide-max-throughput
9710Generate code for inline divides of integer values
9711using the maximum throughput algorithm.
9712
9713@item -minline-sqrt-min-latency
9714@opindex minline-sqrt-min-latency
9715Generate code for inline square roots
9716using the minimum latency algorithm.
9717
9718@item -minline-sqrt-max-throughput
9719@opindex minline-sqrt-max-throughput
9720Generate code for inline square roots
9721using the maximum throughput algorithm.
9722
9723@item -mno-dwarf2-asm
9724@itemx -mdwarf2-asm
9725@opindex mno-dwarf2-asm
9726@opindex mdwarf2-asm
9727Don't (or do) generate assembler code for the DWARF2 line number debugging
9728info. This may be useful when not using the GNU assembler.
9729
9730@item -mearly-stop-bits
9731@itemx -mno-early-stop-bits
9732@opindex mearly-stop-bits
9733@opindex mno-early-stop-bits
9734Allow stop bits to be placed earlier than immediately preceding the
9735instruction that triggered the stop bit. This can improve instruction
9736scheduling, but does not always do so.
9737
9738@item -mfixed-range=@var{register-range}
9739@opindex mfixed-range
9740Generate code treating the given register range as fixed registers.
9741A fixed register is one that the register allocator can not use. This is
9742useful when compiling kernel code. A register range is specified as
9743two registers separated by a dash. Multiple register ranges can be
9744specified separated by a comma.
9745
9746@item -mtls-size=@var{tls-size}
9747@opindex mtls-size
9748Specify bit size of immediate TLS offsets. Valid values are 14, 22, and
974964.
9750
9751@item -mtune=@var{cpu-type}
9752@opindex mtune
9753Tune the instruction scheduling for a particular CPU, Valid values are
9754itanium, itanium1, merced, itanium2, and mckinley.
9755
9756@item -mt
9757@itemx -pthread
9758@opindex mt
9759@opindex pthread
9760Add support for multithreading using the POSIX threads library. This
9761option sets flags for both the preprocessor and linker. It does
9762not affect the thread safety of object code produced by the compiler or
9763that of libraries supplied with it. These are HP-UX specific flags.
9764
9765@item -milp32
9766@itemx -mlp64
9767@opindex milp32
9768@opindex mlp64
9769Generate code for a 32-bit or 64-bit environment.
9770The 32-bit environment sets int, long and pointer to 32 bits.
9771The 64-bit environment sets int to 32 bits and long and pointer
9772to 64 bits. These are HP-UX specific flags.
9773
9774@item -mno-sched-br-data-spec
9775@itemx -msched-br-data-spec
9776@opindex mno-sched-br-data-spec
9777@opindex msched-br-data-spec
9778(Dis/En)able data speculative scheduling before reload.
9779This will result in generation of the ld.a instructions and
9780the corresponding check instructions (ld.c / chk.a).
9781The default is 'disable'.
9782
9783@item -msched-ar-data-spec
9784@itemx -mno-sched-ar-data-spec
9785@opindex msched-ar-data-spec
9786@opindex mno-sched-ar-data-spec
9787(En/Dis)able data speculative scheduling after reload.
9788This will result in generation of the ld.a instructions and
9789the corresponding check instructions (ld.c / chk.a).
9790The default is 'enable'.
9791
9792@item -mno-sched-control-spec
9793@itemx -msched-control-spec
9794@opindex mno-sched-control-spec
9795@opindex msched-control-spec
9796(Dis/En)able control speculative scheduling. This feature is
9797available only during region scheduling (i.e. before reload).
9798This will result in generation of the ld.s instructions and
9799the corresponding check instructions chk.s .
9800The default is 'disable'.
9801
9802@item -msched-br-in-data-spec
9803@itemx -mno-sched-br-in-data-spec
9804@opindex msched-br-in-data-spec
9805@opindex mno-sched-br-in-data-spec
9806(En/Dis)able speculative scheduling of the instructions that
9807are dependent on the data speculative loads before reload.
9808This is effective only with @option{-msched-br-data-spec} enabled.
9809The default is 'enable'.
9810
9811@item -msched-ar-in-data-spec
9812@itemx -mno-sched-ar-in-data-spec
9813@opindex msched-ar-in-data-spec
9814@opindex mno-sched-ar-in-data-spec
9815(En/Dis)able speculative scheduling of the instructions that
9816are dependent on the data speculative loads after reload.
9817This is effective only with @option{-msched-ar-data-spec} enabled.
9818The default is 'enable'.
9819
9820@item -msched-in-control-spec
9821@itemx -mno-sched-in-control-spec
9822@opindex msched-in-control-spec
9823@opindex mno-sched-in-control-spec
9824(En/Dis)able speculative scheduling of the instructions that
9825are dependent on the control speculative loads.
9826This is effective only with @option{-msched-control-spec} enabled.
9827The default is 'enable'.
9828
9829@item -msched-ldc
9830@itemx -mno-sched-ldc
9831@opindex msched-ldc
9832@opindex mno-sched-ldc
9833(En/Dis)able use of simple data speculation checks ld.c .
9834If disabled, only chk.a instructions will be emitted to check
9835data speculative loads.
9836The default is 'enable'.
9837
9838@item -mno-sched-control-ldc
9839@itemx -msched-control-ldc
9840@opindex mno-sched-control-ldc
9841@opindex msched-control-ldc
9842(Dis/En)able use of ld.c instructions to check control speculative loads.
9843If enabled, in case of control speculative load with no speculatively
9844scheduled dependent instructions this load will be emitted as ld.sa and
9845ld.c will be used to check it.
9846The default is 'disable'.
9847
9848@item -mno-sched-spec-verbose
9849@itemx -msched-spec-verbose
9850@opindex mno-sched-spec-verbose
9851@opindex msched-spec-verbose
9852(Dis/En)able printing of the information about speculative motions.
9853
9854@item -mno-sched-prefer-non-data-spec-insns
9855@itemx -msched-prefer-non-data-spec-insns
9856@opindex mno-sched-prefer-non-data-spec-insns
9857@opindex msched-prefer-non-data-spec-insns
9858If enabled, data speculative instructions will be chosen for schedule
9859only if there are no other choices at the moment. This will make
9860the use of the data speculation much more conservative.
9861The default is 'disable'.
9862
9863@item -mno-sched-prefer-non-control-spec-insns
9864@itemx -msched-prefer-non-control-spec-insns
9865@opindex mno-sched-prefer-non-control-spec-insns
9866@opindex msched-prefer-non-control-spec-insns
9867If enabled, control speculative instructions will be chosen for schedule
9868only if there are no other choices at the moment. This will make
9869the use of the control speculation much more conservative.
9870The default is 'disable'.
9871
9872@item -mno-sched-count-spec-in-critical-path
9873@itemx -msched-count-spec-in-critical-path
9874@opindex mno-sched-count-spec-in-critical-path
9875@opindex msched-count-spec-in-critical-path
9876If enabled, speculative dependencies will be considered during
9877computation of the instructions priorities. This will make the use of the
9878speculation a bit more conservative.
9879The default is 'disable'.
9880
9881@end table
9882
9883@node M32C Options
9884@subsection M32C Options
9885@cindex M32C options
9886
9887@table @gcctabopt
9888@item -mcpu=@var{name}
9889@opindex mcpu=
9890Select the CPU for which code is generated. @var{name} may be one of
9891@samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to
9892/60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for
9893the M32C/80 series.
9894
9895@item -msim
9896@opindex msim
9897Specifies that the program will be run on the simulator. This causes
9898an alternate runtime library to be linked in which supports, for
9899example, file I/O. You must not use this option when generating
9900programs that will run on real hardware; you must provide your own
9901runtime library for whatever I/O functions are needed.
9902
9903@item -memregs=@var{number}
9904@opindex memregs=
9905Specifies the number of memory-based pseudo-registers GCC will use
9906during code generation. These pseudo-registers will be used like real
9907registers, so there is a tradeoff between GCC's ability to fit the
9908code into available registers, and the performance penalty of using
9909memory instead of registers. Note that all modules in a program must
9910be compiled with the same value for this option. Because of that, you
9911must not use this option with the default runtime libraries gcc
9912builds.
9913
9914@end table
9915
9916@node M32R/D Options
9917@subsection M32R/D Options
9918@cindex M32R/D options
9919
9920These @option{-m} options are defined for Renesas M32R/D architectures:
9921
9922@table @gcctabopt
9923@item -m32r2
9924@opindex m32r2
9925Generate code for the M32R/2@.
9926
9927@item -m32rx
9928@opindex m32rx
9929Generate code for the M32R/X@.
9930
9931@item -m32r
9932@opindex m32r
9933Generate code for the M32R@. This is the default.
9934
9935@item -mmodel=small
9936@opindex mmodel=small
9937Assume all objects live in the lower 16MB of memory (so that their addresses
9938can be loaded with the @code{ld24} instruction), and assume all subroutines
9939are reachable with the @code{bl} instruction.
9940This is the default.
9941
9942The addressability of a particular object can be set with the
9943@code{model} attribute.
9944
9945@item -mmodel=medium
9946@opindex mmodel=medium
9947Assume objects may be anywhere in the 32-bit address space (the compiler
9948will generate @code{seth/add3} instructions to load their addresses), and
9949assume all subroutines are reachable with the @code{bl} instruction.
9950
9951@item -mmodel=large
9952@opindex mmodel=large
9953Assume objects may be anywhere in the 32-bit address space (the compiler
9954will generate @code{seth/add3} instructions to load their addresses), and
9955assume subroutines may not be reachable with the @code{bl} instruction
9956(the compiler will generate the much slower @code{seth/add3/jl}
9957instruction sequence).
9958
9959@item -msdata=none
9960@opindex msdata=none
9961Disable use of the small data area. Variables will be put into
9962one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
9963@code{section} attribute has been specified).
9964This is the default.
9965
9966The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
9967Objects may be explicitly put in the small data area with the
9968@code{section} attribute using one of these sections.
9969
9970@item -msdata=sdata
9971@opindex msdata=sdata
9972Put small global and static data in the small data area, but do not
9973generate special code to reference them.
9974
9975@item -msdata=use
9976@opindex msdata=use
9977Put small global and static data in the small data area, and generate
9978special instructions to reference them.
9979
9980@item -G @var{num}
9981@opindex G
9982@cindex smaller data references
9983Put global and static objects less than or equal to @var{num} bytes
9984into the small data or bss sections instead of the normal data or bss
9985sections. The default value of @var{num} is 8.
9986The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
9987for this option to have any effect.
9988
9989All modules should be compiled with the same @option{-G @var{num}} value.
9990Compiling with different values of @var{num} may or may not work; if it
9991doesn't the linker will give an error message---incorrect code will not be
9992generated.
9993
9994@item -mdebug
9995@opindex mdebug
9996Makes the M32R specific code in the compiler display some statistics
9997that might help in debugging programs.
9998
9999@item -malign-loops
10000@opindex malign-loops
10001Align all loops to a 32-byte boundary.
10002
10003@item -mno-align-loops
10004@opindex mno-align-loops
10005Do not enforce a 32-byte alignment for loops. This is the default.
10006
10007@item -missue-rate=@var{number}
10008@opindex missue-rate=@var{number}
10009Issue @var{number} instructions per cycle. @var{number} can only be 1
10010or 2.
10011
10012@item -mbranch-cost=@var{number}
10013@opindex mbranch-cost=@var{number}
10014@var{number} can only be 1 or 2. If it is 1 then branches will be
10015preferred over conditional code, if it is 2, then the opposite will
10016apply.
10017
10018@item -mflush-trap=@var{number}
10019@opindex mflush-trap=@var{number}
10020Specifies the trap number to use to flush the cache. The default is
1002112. Valid numbers are between 0 and 15 inclusive.
10022
10023@item -mno-flush-trap
10024@opindex mno-flush-trap
10025Specifies that the cache cannot be flushed by using a trap.
10026
10027@item -mflush-func=@var{name}
10028@opindex mflush-func=@var{name}
10029Specifies the name of the operating system function to call to flush
10030the cache. The default is @emph{_flush_cache}, but a function call
10031will only be used if a trap is not available.
10032
10033@item -mno-flush-func
10034@opindex mno-flush-func
10035Indicates that there is no OS function for flushing the cache.
10036
10037@end table
10038
10039@node M680x0 Options
10040@subsection M680x0 Options
10041@cindex M680x0 options
10042
10043These are the @samp{-m} options defined for the 68000 series. The default
10044values for these options depends on which style of 68000 was selected when
10045the compiler was configured; the defaults for the most common choices are
10046given below.
10047
10048@table @gcctabopt
10049@item -m68000
10050@itemx -mc68000
10051@opindex m68000
10052@opindex mc68000
10053Generate output for a 68000. This is the default
10054when the compiler is configured for 68000-based systems.
10055
10056Use this option for microcontrollers with a 68000 or EC000 core,
10057including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
10058
10059@item -m68020
10060@itemx -mc68020
10061@opindex m68020
10062@opindex mc68020
10063Generate output for a 68020. This is the default
10064when the compiler is configured for 68020-based systems.
10065
10066@item -m68881
10067@opindex m68881
10068Generate output containing 68881 instructions for floating point.
10069This is the default for most 68020 systems unless @option{--nfp} was
10070specified when the compiler was configured.
10071
10072@item -m68030
10073@opindex m68030
10074Generate output for a 68030. This is the default when the compiler is
10075configured for 68030-based systems.
10076
10077@item -m68040
10078@opindex m68040
10079Generate output for a 68040. This is the default when the compiler is
10080configured for 68040-based systems.
10081
10082This option inhibits the use of 68881/68882 instructions that have to be
10083emulated by software on the 68040. Use this option if your 68040 does not
10084have code to emulate those instructions.
10085
10086@item -m68060
10087@opindex m68060
10088Generate output for a 68060. This is the default when the compiler is
10089configured for 68060-based systems.
10090
10091This option inhibits the use of 68020 and 68881/68882 instructions that
10092have to be emulated by software on the 68060. Use this option if your 68060
10093does not have code to emulate those instructions.
10094
10095@item -mcpu32
10096@opindex mcpu32
10097Generate output for a CPU32. This is the default
10098when the compiler is configured for CPU32-based systems.
10099
10100Use this option for microcontrollers with a
10101CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
1010268336, 68340, 68341, 68349 and 68360.
10103
10104@item -m5200
10105@opindex m5200
10106Generate output for a 520X ``coldfire'' family cpu. This is the default
10107when the compiler is configured for 520X-based systems.
10108
10109Use this option for microcontroller with a 5200 core, including
10110the MCF5202, MCF5203, MCF5204 and MCF5202.
10111
10112@item -mcfv4e
10113@opindex mcfv4e
10114Generate output for a ColdFire V4e family cpu (e.g.@: 547x/548x).
10115This includes use of hardware floating point instructions.
10116
10117@item -m68020-40
10118@opindex m68020-40
10119Generate output for a 68040, without using any of the new instructions.
10120This results in code which can run relatively efficiently on either a
1012168020/68881 or a 68030 or a 68040. The generated code does use the
1012268881 instructions that are emulated on the 68040.
10123
10124@item -m68020-60
10125@opindex m68020-60
10126Generate output for a 68060, without using any of the new instructions.
10127This results in code which can run relatively efficiently on either a
1012868020/68881 or a 68030 or a 68040. The generated code does use the
1012968881 instructions that are emulated on the 68060.
10130
10131@item -msoft-float
10132@opindex msoft-float
10133Generate output containing library calls for floating point.
10134@strong{Warning:} the requisite libraries are not available for all m68k
10135targets. Normally the facilities of the machine's usual C compiler are
10136used, but this can't be done directly in cross-compilation. You must
10137make your own arrangements to provide suitable library functions for
10138cross-compilation. The embedded targets @samp{m68k-*-aout} and
10139@samp{m68k-*-coff} do provide software floating point support.
10140
10141@item -mshort
10142@opindex mshort
10143Consider type @code{int} to be 16 bits wide, like @code{short int}.
10144Additionally, parameters passed on the stack are also aligned to a
1014516-bit boundary even on targets whose API mandates promotion to 32-bit.
10146
10147@item -mnobitfield
10148@opindex mnobitfield
10149Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
10150and @option{-m5200} options imply @w{@option{-mnobitfield}}.
10151
10152@item -mbitfield
10153@opindex mbitfield
10154Do use the bit-field instructions. The @option{-m68020} option implies
10155@option{-mbitfield}. This is the default if you use a configuration
10156designed for a 68020.
10157
10158@item -mrtd
10159@opindex mrtd
10160Use a different function-calling convention, in which functions
10161that take a fixed number of arguments return with the @code{rtd}
10162instruction, which pops their arguments while returning. This
10163saves one instruction in the caller since there is no need to pop
10164the arguments there.
10165
10166This calling convention is incompatible with the one normally
10167used on Unix, so you cannot use it if you need to call libraries
10168compiled with the Unix compiler.
10169
10170Also, you must provide function prototypes for all functions that
10171take variable numbers of arguments (including @code{printf});
10172otherwise incorrect code will be generated for calls to those
10173functions.
10174
10175In addition, seriously incorrect code will result if you call a
10176function with too many arguments. (Normally, extra arguments are
10177harmlessly ignored.)
10178
10179The @code{rtd} instruction is supported by the 68010, 68020, 68030,
1018068040, 68060 and CPU32 processors, but not by the 68000 or 5200.
10181
10182@item -malign-int
10183@itemx -mno-align-int
10184@opindex malign-int
10185@opindex mno-align-int
10186Control whether GCC aligns @code{int}, @code{long}, @code{long long},
10187@code{float}, @code{double}, and @code{long double} variables on a 32-bit
10188boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
10189Aligning variables on 32-bit boundaries produces code that runs somewhat
10190faster on processors with 32-bit busses at the expense of more memory.
10191
10192@strong{Warning:} if you use the @option{-malign-int} switch, GCC will
10193align structures containing the above types differently than
10194most published application binary interface specifications for the m68k.
10195
10196@item -mpcrel
10197@opindex mpcrel
10198Use the pc-relative addressing mode of the 68000 directly, instead of
10199using a global offset table. At present, this option implies @option{-fpic},
10200allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
10201not presently supported with @option{-mpcrel}, though this could be supported for
1020268020 and higher processors.
10203
10204@item -mno-strict-align
10205@itemx -mstrict-align
10206@opindex mno-strict-align
10207@opindex mstrict-align
10208Do not (do) assume that unaligned memory references will be handled by
10209the system.
10210
10211@item -msep-data
10212Generate code that allows the data segment to be located in a different
10213area of memory from the text segment. This allows for execute in place in
10214an environment without virtual memory management. This option implies
10215@option{-fPIC}.
10216
10217@item -mno-sep-data
10218Generate code that assumes that the data segment follows the text segment.
10219This is the default.
10220
10221@item -mid-shared-library
10222Generate code that supports shared libraries via the library ID method.
10223This allows for execute in place and shared libraries in an environment
10224without virtual memory management. This option implies @option{-fPIC}.
10225
10226@item -mno-id-shared-library
10227Generate code that doesn't assume ID based shared libraries are being used.
10228This is the default.
10229
10230@item -mshared-library-id=n
10231Specified the identification number of the ID based shared library being
10232compiled. Specifying a value of 0 will generate more compact code, specifying
10233other values will force the allocation of that number to the current
10234library but is no more space or time efficient than omitting this option.
10235
10236@end table
10237
10238@node M68hc1x Options
10239@subsection M68hc1x Options
10240@cindex M68hc1x options
10241
10242These are the @samp{-m} options defined for the 68hc11 and 68hc12
10243microcontrollers. The default values for these options depends on
10244which style of microcontroller was selected when the compiler was configured;
10245the defaults for the most common choices are given below.
10246
10247@table @gcctabopt
10248@item -m6811
10249@itemx -m68hc11
10250@opindex m6811
10251@opindex m68hc11
10252Generate output for a 68HC11. This is the default
10253when the compiler is configured for 68HC11-based systems.
10254
10255@item -m6812
10256@itemx -m68hc12
10257@opindex m6812
10258@opindex m68hc12
10259Generate output for a 68HC12. This is the default
10260when the compiler is configured for 68HC12-based systems.
10261
10262@item -m68S12
10263@itemx -m68hcs12
10264@opindex m68S12
10265@opindex m68hcs12
10266Generate output for a 68HCS12.
10267
10268@item -mauto-incdec
10269@opindex mauto-incdec
10270Enable the use of 68HC12 pre and post auto-increment and auto-decrement
10271addressing modes.
10272
10273@item -minmax
10274@itemx -nominmax
10275@opindex minmax
10276@opindex mnominmax
10277Enable the use of 68HC12 min and max instructions.
10278
10279@item -mlong-calls
10280@itemx -mno-long-calls
10281@opindex mlong-calls
10282@opindex mno-long-calls
10283Treat all calls as being far away (near). If calls are assumed to be
10284far away, the compiler will use the @code{call} instruction to
10285call a function and the @code{rtc} instruction for returning.
10286
10287@item -mshort
10288@opindex mshort
10289Consider type @code{int} to be 16 bits wide, like @code{short int}.
10290
10291@item -msoft-reg-count=@var{count}
10292@opindex msoft-reg-count
10293Specify the number of pseudo-soft registers which are used for the
10294code generation. The maximum number is 32. Using more pseudo-soft
10295register may or may not result in better code depending on the program.
10296The default is 4 for 68HC11 and 2 for 68HC12.
10297
10298@end table
10299
10300@node MCore Options
10301@subsection MCore Options
10302@cindex MCore options
10303
10304These are the @samp{-m} options defined for the Motorola M*Core
10305processors.
10306
10307@table @gcctabopt
10308
10309@item -mhardlit
10310@itemx -mno-hardlit
10311@opindex mhardlit
10312@opindex mno-hardlit
10313Inline constants into the code stream if it can be done in two
10314instructions or less.
10315
10316@item -mdiv
10317@itemx -mno-div
10318@opindex mdiv
10319@opindex mno-div
10320Use the divide instruction. (Enabled by default).
10321
10322@item -mrelax-immediate
10323@itemx -mno-relax-immediate
10324@opindex mrelax-immediate
10325@opindex mno-relax-immediate
10326Allow arbitrary sized immediates in bit operations.
10327
10328@item -mwide-bitfields
10329@itemx -mno-wide-bitfields
10330@opindex mwide-bitfields
10331@opindex mno-wide-bitfields
10332Always treat bit-fields as int-sized.
10333
10334@item -m4byte-functions
10335@itemx -mno-4byte-functions
10336@opindex m4byte-functions
10337@opindex mno-4byte-functions
10338Force all functions to be aligned to a four byte boundary.
10339
10340@item -mcallgraph-data
10341@itemx -mno-callgraph-data
10342@opindex mcallgraph-data
10343@opindex mno-callgraph-data
10344Emit callgraph information.
10345
10346@item -mslow-bytes
10347@itemx -mno-slow-bytes
10348@opindex mslow-bytes
10349@opindex mno-slow-bytes
10350Prefer word access when reading byte quantities.
10351
10352@item -mlittle-endian
10353@itemx -mbig-endian
10354@opindex mlittle-endian
10355@opindex mbig-endian
10356Generate code for a little endian target.
10357
10358@item -m210
10359@itemx -m340
10360@opindex m210
10361@opindex m340
10362Generate code for the 210 processor.
10363@end table
10364
10365@node MIPS Options
10366@subsection MIPS Options
10367@cindex MIPS options
10368
10369@table @gcctabopt
10370
10371@item -EB
10372@opindex EB
10373Generate big-endian code.
10374
10375@item -EL
10376@opindex EL
10377Generate little-endian code. This is the default for @samp{mips*el-*-*}
10378configurations.
10379
10380@item -march=@var{arch}
10381@opindex march
10382Generate code that will run on @var{arch}, which can be the name of a
10383generic MIPS ISA, or the name of a particular processor.
10384The ISA names are:
10385@samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
10386@samp{mips32}, @samp{mips32r2}, and @samp{mips64}.
10387The processor names are:
10388@samp{4kc}, @samp{4km}, @samp{4kp},
10389@samp{5kc}, @samp{5kf},
10390@samp{20kc},
10391@samp{24k}, @samp{24kc}, @samp{24kf}, @samp{24kx},
10392@samp{m4k},
10393@samp{orion},
10394@samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
10395@samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000},
10396@samp{rm7000}, @samp{rm9000},
10397@samp{sb1},
10398@samp{sr71000},
10399@samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
10400@samp{vr5000}, @samp{vr5400} and @samp{vr5500}.
10401The special value @samp{from-abi} selects the
10402most compatible architecture for the selected ABI (that is,
10403@samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
10404
10405In processor names, a final @samp{000} can be abbreviated as @samp{k}
10406(for example, @samp{-march=r2k}). Prefixes are optional, and
10407@samp{vr} may be written @samp{r}.
10408
10409GCC defines two macros based on the value of this option. The first
10410is @samp{_MIPS_ARCH}, which gives the name of target architecture, as
10411a string. The second has the form @samp{_MIPS_ARCH_@var{foo}},
10412where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@.
10413For example, @samp{-march=r2000} will set @samp{_MIPS_ARCH}
10414to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}.
10415
10416Note that the @samp{_MIPS_ARCH} macro uses the processor names given
10417above. In other words, it will have the full prefix and will not
10418abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},
10419the macro names the resolved architecture (either @samp{"mips1"} or
10420@samp{"mips3"}). It names the default architecture when no
10421@option{-march} option is given.
10422
10423@item -mtune=@var{arch}
10424@opindex mtune
10425Optimize for @var{arch}. Among other things, this option controls
10426the way instructions are scheduled, and the perceived cost of arithmetic
10427operations. The list of @var{arch} values is the same as for
10428@option{-march}.
10429
10430When this option is not used, GCC will optimize for the processor
10431specified by @option{-march}. By using @option{-march} and
10432@option{-mtune} together, it is possible to generate code that will
10433run on a family of processors, but optimize the code for one
10434particular member of that family.
10435
10436@samp{-mtune} defines the macros @samp{_MIPS_TUNE} and
10437@samp{_MIPS_TUNE_@var{foo}}, which work in the same way as the
10438@samp{-march} ones described above.
10439
10440@item -mips1
10441@opindex mips1
10442Equivalent to @samp{-march=mips1}.
10443
10444@item -mips2
10445@opindex mips2
10446Equivalent to @samp{-march=mips2}.
10447
10448@item -mips3
10449@opindex mips3
10450Equivalent to @samp{-march=mips3}.
10451
10452@item -mips4
10453@opindex mips4
10454Equivalent to @samp{-march=mips4}.
10455
10456@item -mips32
10457@opindex mips32
10458Equivalent to @samp{-march=mips32}.
10459
10460@item -mips32r2
10461@opindex mips32r2
10462Equivalent to @samp{-march=mips32r2}.
10463
10464@item -mips64
10465@opindex mips64
10466Equivalent to @samp{-march=mips64}.
10467
10468@item -mips16
10469@itemx -mno-mips16
10470@opindex mips16
10471@opindex mno-mips16
10472Generate (do not generate) MIPS16 code. If GCC is targetting a
10473MIPS32 or MIPS64 architecture, it will make use of the MIPS16e ASE@.
10474
10475@item -mabi=32
10476@itemx -mabi=o64
10477@itemx -mabi=n32
10478@itemx -mabi=64
10479@itemx -mabi=eabi
10480@opindex mabi=32
10481@opindex mabi=o64
10482@opindex mabi=n32
10483@opindex mabi=64
10484@opindex mabi=eabi
10485Generate code for the given ABI@.
10486
10487Note that the EABI has a 32-bit and a 64-bit variant. GCC normally
10488generates 64-bit code when you select a 64-bit architecture, but you
10489can use @option{-mgp32} to get 32-bit code instead.
10490
10491For information about the O64 ABI, see
10492@w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
10493
10494@item -mabicalls
10495@itemx -mno-abicalls
10496@opindex mabicalls
10497@opindex mno-abicalls
10498Generate (do not generate) code that is suitable for SVR4-style
10499dynamic objects. @option{-mabicalls} is the default for SVR4-based
10500systems.
10501
10502@item -mshared
10503@itemx -mno-shared
10504Generate (do not generate) code that is fully position-independent,
10505and that can therefore be linked into shared libraries. This option
10506only affects @option{-mabicalls}.
10507
10508All @option{-mabicalls} code has traditionally been position-independent,
10509regardless of options like @option{-fPIC} and @option{-fpic}. However,
10510as an extension, the GNU toolchain allows executables to use absolute
10511accesses for locally-binding symbols. It can also use shorter GP
10512initialization sequences and generate direct calls to locally-defined
10513functions. This mode is selected by @option{-mno-shared}.
10514
10515@option{-mno-shared} depends on binutils 2.16 or higher and generates
10516objects that can only be linked by the GNU linker. However, the option
10517does not affect the ABI of the final executable; it only affects the ABI
10518of relocatable objects. Using @option{-mno-shared} will generally make
10519executables both smaller and quicker.
10520
10521@option{-mshared} is the default.
10522
10523@item -mxgot
10524@itemx -mno-xgot
10525@opindex mxgot
10526@opindex mno-xgot
10527Lift (do not lift) the usual restrictions on the size of the global
10528offset table.
10529
10530GCC normally uses a single instruction to load values from the GOT@.
10531While this is relatively efficient, it will only work if the GOT
10532is smaller than about 64k. Anything larger will cause the linker
10533to report an error such as:
10534
10535@cindex relocation truncated to fit (MIPS)
10536@smallexample
10537relocation truncated to fit: R_MIPS_GOT16 foobar
10538@end smallexample
10539
10540If this happens, you should recompile your code with @option{-mxgot}.
10541It should then work with very large GOTs, although it will also be
10542less efficient, since it will take three instructions to fetch the
10543value of a global symbol.
10544
10545Note that some linkers can create multiple GOTs. If you have such a
10546linker, you should only need to use @option{-mxgot} when a single object
10547file accesses more than 64k's worth of GOT entries. Very few do.
10548
10549These options have no effect unless GCC is generating position
10550independent code.
10551
10552@item -mgp32
10553@opindex mgp32
10554Assume that general-purpose registers are 32 bits wide.
10555
10556@item -mgp64
10557@opindex mgp64
10558Assume that general-purpose registers are 64 bits wide.
10559
10560@item -mfp32
10561@opindex mfp32
10562Assume that floating-point registers are 32 bits wide.
10563
10564@item -mfp64
10565@opindex mfp64
10566Assume that floating-point registers are 64 bits wide.
10567
10568@item -mhard-float
10569@opindex mhard-float
10570Use floating-point coprocessor instructions.
10571
10572@item -msoft-float
10573@opindex msoft-float
10574Do not use floating-point coprocessor instructions. Implement
10575floating-point calculations using library calls instead.
10576
10577@item -msingle-float
10578@opindex msingle-float
10579Assume that the floating-point coprocessor only supports single-precision
10580operations.
10581
10582@itemx -mdouble-float
10583@opindex mdouble-float
10584Assume that the floating-point coprocessor supports double-precision
10585operations. This is the default.
10586
10587@itemx -mdsp
10588@itemx -mno-dsp
10589@opindex mdsp
10590@opindex mno-dsp
10591Use (do not use) the MIPS DSP ASE. @xref{MIPS DSP Built-in Functions}.
10592
10593@itemx -mpaired-single
10594@itemx -mno-paired-single
10595@opindex mpaired-single
10596@opindex mno-paired-single
10597Use (do not use) paired-single floating-point instructions.
10598@xref{MIPS Paired-Single Support}. This option can only be used
10599when generating 64-bit code and requires hardware floating-point
10600support to be enabled.
10601
10602@itemx -mips3d
10603@itemx -mno-mips3d
10604@opindex mips3d
10605@opindex mno-mips3d
10606Use (do not use) the MIPS-3D ASE@. @xref{MIPS-3D Built-in Functions}.
10607The option @option{-mips3d} implies @option{-mpaired-single}.
10608
10609@item -mlong64
10610@opindex mlong64
10611Force @code{long} types to be 64 bits wide. See @option{-mlong32} for
10612an explanation of the default and the way that the pointer size is
10613determined.
10614
10615@item -mlong32
10616@opindex mlong32
10617Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
10618
10619The default size of @code{int}s, @code{long}s and pointers depends on
10620the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI
10621uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
1062232-bit @code{long}s. Pointers are the same size as @code{long}s,
10623or the same size as integer registers, whichever is smaller.
10624
10625@item -msym32
10626@itemx -mno-sym32
10627@opindex msym32
10628@opindex mno-sym32
10629Assume (do not assume) that all symbols have 32-bit values, regardless
10630of the selected ABI@. This option is useful in combination with
10631@option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
10632to generate shorter and faster references to symbolic addresses.
10633
10634@item -G @var{num}
10635@opindex G
10636@cindex smaller data references (MIPS)
10637@cindex gp-relative references (MIPS)
10638Put global and static items less than or equal to @var{num} bytes into
10639the small data or bss section instead of the normal data or bss section.
10640This allows the data to be accessed using a single instruction.
10641
10642All modules should be compiled with the same @option{-G @var{num}}
10643value.
10644
10645@item -membedded-data
10646@itemx -mno-embedded-data
10647@opindex membedded-data
10648@opindex mno-embedded-data
10649Allocate variables to the read-only data section first if possible, then
10650next in the small data section if possible, otherwise in data. This gives
10651slightly slower code than the default, but reduces the amount of RAM required
10652when executing, and thus may be preferred for some embedded systems.
10653
10654@item -muninit-const-in-rodata
10655@itemx -mno-uninit-const-in-rodata
10656@opindex muninit-const-in-rodata
10657@opindex mno-uninit-const-in-rodata
10658Put uninitialized @code{const} variables in the read-only data section.
10659This option is only meaningful in conjunction with @option{-membedded-data}.
10660
10661@item -msplit-addresses
10662@itemx -mno-split-addresses
10663@opindex msplit-addresses
10664@opindex mno-split-addresses
10665Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
10666relocation operators. This option has been superseded by
10667@option{-mexplicit-relocs} but is retained for backwards compatibility.
10668
10669@item -mexplicit-relocs
10670@itemx -mno-explicit-relocs
10671@opindex mexplicit-relocs
10672@opindex mno-explicit-relocs
10673Use (do not use) assembler relocation operators when dealing with symbolic
10674addresses. The alternative, selected by @option{-mno-explicit-relocs},
10675is to use assembler macros instead.
10676
10677@option{-mexplicit-relocs} is the default if GCC was configured
10678to use an assembler that supports relocation operators.
10679
10680@item -mcheck-zero-division
10681@itemx -mno-check-zero-division
10682@opindex mcheck-zero-division
10683@opindex mno-check-zero-division
10684Trap (do not trap) on integer division by zero. The default is
10685@option{-mcheck-zero-division}.
10686
10687@item -mdivide-traps
10688@itemx -mdivide-breaks
10689@opindex mdivide-traps
10690@opindex mdivide-breaks
10691MIPS systems check for division by zero by generating either a
10692conditional trap or a break instruction. Using traps results in
10693smaller code, but is only supported on MIPS II and later. Also, some
10694versions of the Linux kernel have a bug that prevents trap from
10695generating the proper signal (@code{SIGFPE}). Use @option{-mdivide-traps} to
10696allow conditional traps on architectures that support them and
10697@option{-mdivide-breaks} to force the use of breaks.
10698
10699The default is usually @option{-mdivide-traps}, but this can be
10700overridden at configure time using @option{--with-divide=breaks}.
10701Divide-by-zero checks can be completely disabled using
10702@option{-mno-check-zero-division}.
10703
10704@item -mmemcpy
10705@itemx -mno-memcpy
10706@opindex mmemcpy
10707@opindex mno-memcpy
10708Force (do not force) the use of @code{memcpy()} for non-trivial block
10709moves. The default is @option{-mno-memcpy}, which allows GCC to inline
10710most constant-sized copies.
10711
10712@item -mlong-calls
10713@itemx -mno-long-calls
10714@opindex mlong-calls
10715@opindex mno-long-calls
10716Disable (do not disable) use of the @code{jal} instruction. Calling
10717functions using @code{jal} is more efficient but requires the caller
10718and callee to be in the same 256 megabyte segment.
10719
10720This option has no effect on abicalls code. The default is
10721@option{-mno-long-calls}.
10722
10723@item -mmad
10724@itemx -mno-mad
10725@opindex mmad
10726@opindex mno-mad
10727Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
10728instructions, as provided by the R4650 ISA@.
10729
10730@item -mfused-madd
10731@itemx -mno-fused-madd
10732@opindex mfused-madd
10733@opindex mno-fused-madd
10734Enable (disable) use of the floating point multiply-accumulate
10735instructions, when they are available. The default is
10736@option{-mfused-madd}.
10737
10738When multiply-accumulate instructions are used, the intermediate
10739product is calculated to infinite precision and is not subject to
10740the FCSR Flush to Zero bit. This may be undesirable in some
10741circumstances.
10742
10743@item -nocpp
10744@opindex nocpp
10745Tell the MIPS assembler to not run its preprocessor over user
10746assembler files (with a @samp{.s} suffix) when assembling them.
10747
10748@item -mfix-r4000
10749@itemx -mno-fix-r4000
10750@opindex mfix-r4000
10751@opindex mno-fix-r4000
10752Work around certain R4000 CPU errata:
10753@itemize @minus
10754@item
10755A double-word or a variable shift may give an incorrect result if executed
10756immediately after starting an integer division.
10757@item
10758A double-word or a variable shift may give an incorrect result if executed
10759while an integer multiplication is in progress.
10760@item
10761An integer division may give an incorrect result if started in a delay slot
10762of a taken branch or a jump.
10763@end itemize
10764
10765@item -mfix-r4400
10766@itemx -mno-fix-r4400
10767@opindex mfix-r4400
10768@opindex mno-fix-r4400
10769Work around certain R4400 CPU errata:
10770@itemize @minus
10771@item
10772A double-word or a variable shift may give an incorrect result if executed
10773immediately after starting an integer division.
10774@end itemize
10775
10776@item -mfix-vr4120
10777@itemx -mno-fix-vr4120
10778@opindex mfix-vr4120
10779Work around certain VR4120 errata:
10780@itemize @minus
10781@item
10782@code{dmultu} does not always produce the correct result.
10783@item
10784@code{div} and @code{ddiv} do not always produce the correct result if one
10785of the operands is negative.
10786@end itemize
10787The workarounds for the division errata rely on special functions in
10788@file{libgcc.a}. At present, these functions are only provided by
10789the @code{mips64vr*-elf} configurations.
10790
10791Other VR4120 errata require a nop to be inserted between certain pairs of
10792instructions. These errata are handled by the assembler, not by GCC itself.
10793
10794@item -mfix-vr4130
10795@opindex mfix-vr4130
10796Work around the VR4130 @code{mflo}/@code{mfhi} errata. The
10797workarounds are implemented by the assembler rather than by GCC,
10798although GCC will avoid using @code{mflo} and @code{mfhi} if the
10799VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
10800instructions are available instead.
10801
10802@item -mfix-sb1
10803@itemx -mno-fix-sb1
10804@opindex mfix-sb1
10805Work around certain SB-1 CPU core errata.
10806(This flag currently works around the SB-1 revision 2
10807``F1'' and ``F2'' floating point errata.)
10808
10809@item -mflush-func=@var{func}
10810@itemx -mno-flush-func
10811@opindex mflush-func
10812Specifies the function to call to flush the I and D caches, or to not
10813call any such function. If called, the function must take the same
10814arguments as the common @code{_flush_func()}, that is, the address of the
10815memory range for which the cache is being flushed, the size of the
10816memory range, and the number 3 (to flush both caches). The default
10817depends on the target GCC was configured for, but commonly is either
10818@samp{_flush_func} or @samp{__cpu_flush}.
10819
10820@item -mbranch-likely
10821@itemx -mno-branch-likely
10822@opindex mbranch-likely
10823@opindex mno-branch-likely
10824Enable or disable use of Branch Likely instructions, regardless of the
10825default for the selected architecture. By default, Branch Likely
10826instructions may be generated if they are supported by the selected
10827architecture. An exception is for the MIPS32 and MIPS64 architectures
10828and processors which implement those architectures; for those, Branch
10829Likely instructions will not be generated by default because the MIPS32
10830and MIPS64 architectures specifically deprecate their use.
10831
10832@item -mfp-exceptions
10833@itemx -mno-fp-exceptions
10834@opindex mfp-exceptions
10835Specifies whether FP exceptions are enabled. This affects how we schedule
10836FP instructions for some processors. The default is that FP exceptions are
10837enabled.
10838
10839For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
1084064-bit code, then we can use both FP pipes. Otherwise, we can only use one
10841FP pipe.
10842
10843@item -mvr4130-align
10844@itemx -mno-vr4130-align
10845@opindex mvr4130-align
10846The VR4130 pipeline is two-way superscalar, but can only issue two
10847instructions together if the first one is 8-byte aligned. When this
10848option is enabled, GCC will align pairs of instructions that it
10849thinks should execute in parallel.
10850
10851This option only has an effect when optimizing for the VR4130.
10852It normally makes code faster, but at the expense of making it bigger.
10853It is enabled by default at optimization level @option{-O3}.
10854@end table
10855
10856@node MMIX Options
10857@subsection MMIX Options
10858@cindex MMIX Options
10859
10860These options are defined for the MMIX:
10861
10862@table @gcctabopt
10863@item -mlibfuncs
10864@itemx -mno-libfuncs
10865@opindex mlibfuncs
10866@opindex mno-libfuncs
10867Specify that intrinsic library functions are being compiled, passing all
10868values in registers, no matter the size.
10869
10870@item -mepsilon
10871@itemx -mno-epsilon
10872@opindex mepsilon
10873@opindex mno-epsilon
10874Generate floating-point comparison instructions that compare with respect
10875to the @code{rE} epsilon register.
10876
10877@item -mabi=mmixware
10878@itemx -mabi=gnu
10879@opindex mabi-mmixware
10880@opindex mabi=gnu
10881Generate code that passes function parameters and return values that (in
10882the called function) are seen as registers @code{$0} and up, as opposed to
10883the GNU ABI which uses global registers @code{$231} and up.
10884
10885@item -mzero-extend
10886@itemx -mno-zero-extend
10887@opindex mzero-extend
10888@opindex mno-zero-extend
10889When reading data from memory in sizes shorter than 64 bits, use (do not
10890use) zero-extending load instructions by default, rather than
10891sign-extending ones.
10892
10893@item -mknuthdiv
10894@itemx -mno-knuthdiv
10895@opindex mknuthdiv
10896@opindex mno-knuthdiv
10897Make the result of a division yielding a remainder have the same sign as
10898the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
10899remainder follows the sign of the dividend. Both methods are
10900arithmetically valid, the latter being almost exclusively used.
10901
10902@item -mtoplevel-symbols
10903@itemx -mno-toplevel-symbols
10904@opindex mtoplevel-symbols
10905@opindex mno-toplevel-symbols
10906Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
10907code can be used with the @code{PREFIX} assembly directive.
10908
10909@item -melf
10910@opindex melf
10911Generate an executable in the ELF format, rather than the default
10912@samp{mmo} format used by the @command{mmix} simulator.
10913
10914@item -mbranch-predict
10915@itemx -mno-branch-predict
10916@opindex mbranch-predict
10917@opindex mno-branch-predict
10918Use (do not use) the probable-branch instructions, when static branch
10919prediction indicates a probable branch.
10920
10921@item -mbase-addresses
10922@itemx -mno-base-addresses
10923@opindex mbase-addresses
10924@opindex mno-base-addresses
10925Generate (do not generate) code that uses @emph{base addresses}. Using a
10926base address automatically generates a request (handled by the assembler
10927and the linker) for a constant to be set up in a global register. The
10928register is used for one or more base address requests within the range 0
10929to 255 from the value held in the register. The generally leads to short
10930and fast code, but the number of different data items that can be
10931addressed is limited. This means that a program that uses lots of static
10932data may require @option{-mno-base-addresses}.
10933
10934@item -msingle-exit
10935@itemx -mno-single-exit
10936@opindex msingle-exit
10937@opindex mno-single-exit
10938Force (do not force) generated code to have a single exit point in each
10939function.
10940@end table
10941
10942@node MN10300 Options
10943@subsection MN10300 Options
10944@cindex MN10300 options
10945
10946These @option{-m} options are defined for Matsushita MN10300 architectures:
10947
10948@table @gcctabopt
10949@item -mmult-bug
10950@opindex mmult-bug
10951Generate code to avoid bugs in the multiply instructions for the MN10300
10952processors. This is the default.
10953
10954@item -mno-mult-bug
10955@opindex mno-mult-bug
10956Do not generate code to avoid bugs in the multiply instructions for the
10957MN10300 processors.
10958
10959@item -mam33
10960@opindex mam33
10961Generate code which uses features specific to the AM33 processor.
10962
10963@item -mno-am33
10964@opindex mno-am33
10965Do not generate code which uses features specific to the AM33 processor. This
10966is the default.
10967
10968@item -mreturn-pointer-on-d0
10969@opindex mreturn-pointer-on-d0
10970When generating a function which returns a pointer, return the pointer
10971in both @code{a0} and @code{d0}. Otherwise, the pointer is returned
10972only in a0, and attempts to call such functions without a prototype
10973would result in errors. Note that this option is on by default; use
10974@option{-mno-return-pointer-on-d0} to disable it.
10975
10976@item -mno-crt0
10977@opindex mno-crt0
10978Do not link in the C run-time initialization object file.
10979
10980@item -mrelax
10981@opindex mrelax
10982Indicate to the linker that it should perform a relaxation optimization pass
10983to shorten branches, calls and absolute memory addresses. This option only
10984has an effect when used on the command line for the final link step.
10985
10986This option makes symbolic debugging impossible.
10987@end table
10988
10989@node MT Options
10990@subsection MT Options
10991@cindex MT options
10992
10993These @option{-m} options are defined for Morpho MT architectures:
10994
10995@table @gcctabopt
10996
10997@item -march=@var{cpu-type}
10998@opindex march
10999Generate code that will run on @var{cpu-type}, which is the name of a system
11000representing a certain processor type. Possible values for
11001@var{cpu-type} are @samp{ms1-64-001}, @samp{ms1-16-002},
11002@samp{ms1-16-003} and @samp{ms2}.
11003
11004When this option is not used, the default is @option{-march=ms1-16-002}.
11005
11006@item -mbacc
11007@opindex mbacc
11008Use byte loads and stores when generating code.
11009
11010@item -mno-bacc
11011@opindex mno-bacc
11012Do not use byte loads and stores when generating code.
11013
11014@item -msim
11015@opindex msim
11016Use simulator runtime
11017
11018@item -mno-crt0
11019@opindex mno-crt0
11020Do not link in the C run-time initialization object file
11021@file{crti.o}. Other run-time initialization and termination files
11022such as @file{startup.o} and @file{exit.o} are still included on the
11023linker command line.
11024
11025@end table
11026
11027@node PDP-11 Options
11028@subsection PDP-11 Options
11029@cindex PDP-11 Options
11030
11031These options are defined for the PDP-11:
11032
11033@table @gcctabopt
11034@item -mfpu
11035@opindex mfpu
11036Use hardware FPP floating point. This is the default. (FIS floating
11037point on the PDP-11/40 is not supported.)
11038
11039@item -msoft-float
11040@opindex msoft-float
11041Do not use hardware floating point.
11042
11043@item -mac0
11044@opindex mac0
11045Return floating-point results in ac0 (fr0 in Unix assembler syntax).
11046
11047@item -mno-ac0
11048@opindex mno-ac0
11049Return floating-point results in memory. This is the default.
11050
11051@item -m40
11052@opindex m40
11053Generate code for a PDP-11/40.
11054
11055@item -m45
11056@opindex m45
11057Generate code for a PDP-11/45. This is the default.
11058
11059@item -m10
11060@opindex m10
11061Generate code for a PDP-11/10.
11062
11063@item -mbcopy-builtin
11064@opindex bcopy-builtin
11065Use inline @code{movmemhi} patterns for copying memory. This is the
11066default.
11067
11068@item -mbcopy
11069@opindex mbcopy
11070Do not use inline @code{movmemhi} patterns for copying memory.
11071
11072@item -mint16
11073@itemx -mno-int32
11074@opindex mint16
11075@opindex mno-int32
11076Use 16-bit @code{int}. This is the default.
11077
11078@item -mint32
11079@itemx -mno-int16
11080@opindex mint32
11081@opindex mno-int16
11082Use 32-bit @code{int}.
11083
11084@item -mfloat64
11085@itemx -mno-float32
11086@opindex mfloat64
11087@opindex mno-float32
11088Use 64-bit @code{float}. This is the default.
11089
11090@item -mfloat32
11091@itemx -mno-float64
11092@opindex mfloat32
11093@opindex mno-float64
11094Use 32-bit @code{float}.
11095
11096@item -mabshi
11097@opindex mabshi
11098Use @code{abshi2} pattern. This is the default.
11099
11100@item -mno-abshi
11101@opindex mno-abshi
11102Do not use @code{abshi2} pattern.
11103
11104@item -mbranch-expensive
11105@opindex mbranch-expensive
11106Pretend that branches are expensive. This is for experimenting with
11107code generation only.
11108
11109@item -mbranch-cheap
11110@opindex mbranch-cheap
11111Do not pretend that branches are expensive. This is the default.
11112
11113@item -msplit
11114@opindex msplit
11115Generate code for a system with split I&D@.
11116
11117@item -mno-split
11118@opindex mno-split
11119Generate code for a system without split I&D@. This is the default.
11120
11121@item -munix-asm
11122@opindex munix-asm
11123Use Unix assembler syntax. This is the default when configured for
11124@samp{pdp11-*-bsd}.
11125
11126@item -mdec-asm
11127@opindex mdec-asm
11128Use DEC assembler syntax. This is the default when configured for any
11129PDP-11 target other than @samp{pdp11-*-bsd}.
11130@end table
11131
11132@node PowerPC Options
11133@subsection PowerPC Options
11134@cindex PowerPC options
11135
11136These are listed under @xref{RS/6000 and PowerPC Options}.
11137
11138@node RS/6000 and PowerPC Options
11139@subsection IBM RS/6000 and PowerPC Options
11140@cindex RS/6000 and PowerPC Options
11141@cindex IBM RS/6000 and PowerPC Options
11142
11143These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
11144@table @gcctabopt
11145@item -mpower
11146@itemx -mno-power
11147@itemx -mpower2
11148@itemx -mno-power2
11149@itemx -mpowerpc
11150@itemx -mno-powerpc
11151@itemx -mpowerpc-gpopt
11152@itemx -mno-powerpc-gpopt
11153@itemx -mpowerpc-gfxopt
11154@itemx -mno-powerpc-gfxopt
11155@itemx -mpowerpc64
11156@itemx -mno-powerpc64
11157@itemx -mmfcrf
11158@itemx -mno-mfcrf
11159@itemx -mpopcntb
11160@itemx -mno-popcntb
11161@itemx -mfprnd
11162@itemx -mno-fprnd
11163@opindex mpower
11164@opindex mno-power
11165@opindex mpower2
11166@opindex mno-power2
11167@opindex mpowerpc
11168@opindex mno-powerpc
11169@opindex mpowerpc-gpopt
11170@opindex mno-powerpc-gpopt
11171@opindex mpowerpc-gfxopt
11172@opindex mno-powerpc-gfxopt
11173@opindex mpowerpc64
11174@opindex mno-powerpc64
11175@opindex mmfcrf
11176@opindex mno-mfcrf
11177@opindex mpopcntb
11178@opindex mno-popcntb
11179@opindex mfprnd
11180@opindex mno-fprnd
11181GCC supports two related instruction set architectures for the
11182RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those
11183instructions supported by the @samp{rios} chip set used in the original
11184RS/6000 systems and the @dfn{PowerPC} instruction set is the
11185architecture of the Freescale MPC5xx, MPC6xx, MPC8xx microprocessors, and
11186the IBM 4xx, 6xx, and follow-on microprocessors.
11187
11188Neither architecture is a subset of the other. However there is a
11189large common subset of instructions supported by both. An MQ
11190register is included in processors supporting the POWER architecture.
11191
11192You use these options to specify which instructions are available on the
11193processor you are using. The default value of these options is
11194determined when configuring GCC@. Specifying the
11195@option{-mcpu=@var{cpu_type}} overrides the specification of these
11196options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
11197rather than the options listed above.
11198
11199The @option{-mpower} option allows GCC to generate instructions that
11200are found only in the POWER architecture and to use the MQ register.
11201Specifying @option{-mpower2} implies @option{-power} and also allows GCC
11202to generate instructions that are present in the POWER2 architecture but
11203not the original POWER architecture.
11204
11205The @option{-mpowerpc} option allows GCC to generate instructions that
11206are found only in the 32-bit subset of the PowerPC architecture.
11207Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
11208GCC to use the optional PowerPC architecture instructions in the
11209General Purpose group, including floating-point square root. Specifying
11210@option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
11211use the optional PowerPC architecture instructions in the Graphics
11212group, including floating-point select.
11213
11214The @option{-mmfcrf} option allows GCC to generate the move from
11215condition register field instruction implemented on the POWER4
11216processor and other processors that support the PowerPC V2.01
11217architecture.
11218The @option{-mpopcntb} option allows GCC to generate the popcount and
11219double precision FP reciprocal estimate instruction implemented on the
11220POWER5 processor and other processors that support the PowerPC V2.02
11221architecture.
11222The @option{-mfprnd} option allows GCC to generate the FP round to
11223integer instructions implemented on the POWER5+ processor and other
11224processors that support the PowerPC V2.03 architecture.
11225
11226The @option{-mpowerpc64} option allows GCC to generate the additional
1122764-bit instructions that are found in the full PowerPC64 architecture
11228and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
11229@option{-mno-powerpc64}.
11230
11231If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
11232will use only the instructions in the common subset of both
11233architectures plus some special AIX common-mode calls, and will not use
11234the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
11235permits GCC to use any instruction from either architecture and to
11236allow use of the MQ register; specify this for the Motorola MPC601.
11237
11238@item -mnew-mnemonics
11239@itemx -mold-mnemonics
11240@opindex mnew-mnemonics
11241@opindex mold-mnemonics
11242Select which mnemonics to use in the generated assembler code. With
11243@option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
11244the PowerPC architecture. With @option{-mold-mnemonics} it uses the
11245assembler mnemonics defined for the POWER architecture. Instructions
11246defined in only one architecture have only one mnemonic; GCC uses that
11247mnemonic irrespective of which of these options is specified.
11248
11249GCC defaults to the mnemonics appropriate for the architecture in
11250use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
11251value of these option. Unless you are building a cross-compiler, you
11252should normally not specify either @option{-mnew-mnemonics} or
11253@option{-mold-mnemonics}, but should instead accept the default.
11254
11255@item -mcpu=@var{cpu_type}
11256@opindex mcpu
11257Set architecture type, register usage, choice of mnemonics, and
11258instruction scheduling parameters for machine type @var{cpu_type}.
11259Supported values for @var{cpu_type} are @samp{401}, @samp{403},
11260@samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{505},
11261@samp{601}, @samp{602}, @samp{603}, @samp{603e}, @samp{604},
11262@samp{604e}, @samp{620}, @samp{630}, @samp{740}, @samp{7400},
11263@samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
11264@samp{860}, @samp{970}, @samp{8540}, @samp{ec603e}, @samp{G3},
11265@samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3},
11266@samp{power4}, @samp{power5}, @samp{power5+}, @samp{power6},
11267@samp{common}, @samp{powerpc}, @samp{powerpc64},
11268@samp{rios}, @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64}.
11269
11270@option{-mcpu=common} selects a completely generic processor. Code
11271generated under this option will run on any POWER or PowerPC processor.
11272GCC will use only the instructions in the common subset of both
11273architectures, and will not use the MQ register. GCC assumes a generic
11274processor model for scheduling purposes.
11275
11276@option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
11277@option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
11278PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
11279types, with an appropriate, generic processor model assumed for
11280scheduling purposes.
11281
11282The other options specify a specific processor. Code generated under
11283those options will run best on that processor, and may not run at all on
11284others.
11285
11286The @option{-mcpu} options automatically enable or disable the
11287following options: @option{-maltivec}, @option{-mfprnd},
11288@option{-mhard-float}, @option{-mmfcrf}, @option{-mmultiple},
11289@option{-mnew-mnemonics}, @option{-mpopcntb}, @option{-mpower},
11290@option{-mpower2}, @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
11291@option{-mpowerpc-gfxopt}, @option{-mstring}, @option{-mmulhw}, @option{-mdlmzb}.
11292The particular options
11293set for any particular CPU will vary between compiler versions,
11294depending on what setting seems to produce optimal code for that CPU;
11295it doesn't necessarily reflect the actual hardware's capabilities. If
11296you wish to set an individual option to a particular value, you may
11297specify it after the @option{-mcpu} option, like @samp{-mcpu=970
11298-mno-altivec}.
11299
11300On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
11301not enabled or disabled by the @option{-mcpu} option at present because
11302AIX does not have full support for these options. You may still
11303enable or disable them individually if you're sure it'll work in your
11304environment.
11305
11306@item -mtune=@var{cpu_type}
11307@opindex mtune
11308Set the instruction scheduling parameters for machine type
11309@var{cpu_type}, but do not set the architecture type, register usage, or
11310choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
11311values for @var{cpu_type} are used for @option{-mtune} as for
11312@option{-mcpu}. If both are specified, the code generated will use the
11313architecture, registers, and mnemonics set by @option{-mcpu}, but the
11314scheduling parameters set by @option{-mtune}.
11315
11316@item -mswdiv
11317@itemx -mno-swdiv
11318@opindex mswdiv
11319@opindex mno-swdiv
11320Generate code to compute division as reciprocal estimate and iterative
11321refinement, creating opportunities for increased throughput. This
11322feature requires: optional PowerPC Graphics instruction set for single
11323precision and FRE instruction for double precision, assuming divides
11324cannot generate user-visible traps, and the domain values not include
11325Infinities, denormals or zero denominator.
11326
11327@item -maltivec
11328@itemx -mno-altivec
11329@opindex maltivec
11330@opindex mno-altivec
11331Generate code that uses (does not use) AltiVec instructions, and also
11332enable the use of built-in functions that allow more direct access to
11333the AltiVec instruction set. You may also need to set
11334@option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
11335enhancements.
11336
11337@item -mvrsave
11338@item -mno-vrsave
11339@opindex mvrsave
11340@opindex mno-vrsave
11341Generate VRSAVE instructions when generating AltiVec code.
11342
11343@item -msecure-plt
11344@opindex msecure-plt
11345Generate code that allows ld and ld.so to build executables and shared
11346libraries with non-exec .plt and .got sections. This is a PowerPC
1134732-bit SYSV ABI option.
11348
11349@item -mbss-plt
11350@opindex mbss-plt
11351Generate code that uses a BSS .plt section that ld.so fills in, and
11352requires .plt and .got sections that are both writable and executable.
11353This is a PowerPC 32-bit SYSV ABI option.
11354
11355@item -misel
11356@itemx -mno-isel
11357@opindex misel
11358@opindex mno-isel
11359This switch enables or disables the generation of ISEL instructions.
11360
11361@item -misel=@var{yes/no}
11362This switch has been deprecated. Use @option{-misel} and
11363@option{-mno-isel} instead.
11364
11365@item -mspe
11366@itemx -mno-spe
11367@opindex mspe
11368@opindex mno-spe
11369This switch enables or disables the generation of SPE simd
11370instructions.
11371
11372@item -mspe=@var{yes/no}
11373This option has been deprecated. Use @option{-mspe} and
11374@option{-mno-spe} instead.
11375
11376@item -mfloat-gprs=@var{yes/single/double/no}
11377@itemx -mfloat-gprs
11378@opindex mfloat-gprs
11379This switch enables or disables the generation of floating point
11380operations on the general purpose registers for architectures that
11381support it.
11382
11383The argument @var{yes} or @var{single} enables the use of
11384single-precision floating point operations.
11385
11386The argument @var{double} enables the use of single and
11387double-precision floating point operations.
11388
11389The argument @var{no} disables floating point operations on the
11390general purpose registers.
11391
11392This option is currently only available on the MPC854x.
11393
11394@item -m32
11395@itemx -m64
11396@opindex m32
11397@opindex m64
11398Generate code for 32-bit or 64-bit environments of Darwin and SVR4
11399targets (including GNU/Linux). The 32-bit environment sets int, long
11400and pointer to 32 bits and generates code that runs on any PowerPC
11401variant. The 64-bit environment sets int to 32 bits and long and
11402pointer to 64 bits, and generates code for PowerPC64, as for
11403@option{-mpowerpc64}.
11404
11405@item -mfull-toc
11406@itemx -mno-fp-in-toc
11407@itemx -mno-sum-in-toc
11408@itemx -mminimal-toc
11409@opindex mfull-toc
11410@opindex mno-fp-in-toc
11411@opindex mno-sum-in-toc
11412@opindex mminimal-toc
11413Modify generation of the TOC (Table Of Contents), which is created for
11414every executable file. The @option{-mfull-toc} option is selected by
11415default. In that case, GCC will allocate at least one TOC entry for
11416each unique non-automatic variable reference in your program. GCC
11417will also place floating-point constants in the TOC@. However, only
1141816,384 entries are available in the TOC@.
11419
11420If you receive a linker error message that saying you have overflowed
11421the available TOC space, you can reduce the amount of TOC space used
11422with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
11423@option{-mno-fp-in-toc} prevents GCC from putting floating-point
11424constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
11425generate code to calculate the sum of an address and a constant at
11426run-time instead of putting that sum into the TOC@. You may specify one
11427or both of these options. Each causes GCC to produce very slightly
11428slower and larger code at the expense of conserving TOC space.
11429
11430If you still run out of space in the TOC even when you specify both of
11431these options, specify @option{-mminimal-toc} instead. This option causes
11432GCC to make only one TOC entry for every file. When you specify this
11433option, GCC will produce code that is slower and larger but which
11434uses extremely little TOC space. You may wish to use this option
11435only on files that contain less frequently executed code.
11436
11437@item -maix64
11438@itemx -maix32
11439@opindex maix64
11440@opindex maix32
11441Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
11442@code{long} type, and the infrastructure needed to support them.
11443Specifying @option{-maix64} implies @option{-mpowerpc64} and
11444@option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
11445implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
11446
11447@item -mxl-compat
11448@itemx -mno-xl-compat
11449@opindex mxl-compat
11450@opindex mno-xl-compat
11451Produce code that conforms more closely to IBM XL compiler semantics
11452when using AIX-compatible ABI. Pass floating-point arguments to
11453prototyped functions beyond the register save area (RSA) on the stack
11454in addition to argument FPRs. Do not assume that most significant
11455double in 128-bit long double value is properly rounded when comparing
11456values and converting to double. Use XL symbol names for long double
11457support routines.
11458
11459The AIX calling convention was extended but not initially documented to
11460handle an obscure K&R C case of calling a function that takes the
11461address of its arguments with fewer arguments than declared. IBM XL
11462compilers access floating point arguments which do not fit in the
11463RSA from the stack when a subroutine is compiled without
11464optimization. Because always storing floating-point arguments on the
11465stack is inefficient and rarely needed, this option is not enabled by
11466default and only is necessary when calling subroutines compiled by IBM
11467XL compilers without optimization.
11468
11469@item -mpe
11470@opindex mpe
11471Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
11472application written to use message passing with special startup code to
11473enable the application to run. The system must have PE installed in the
11474standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
11475must be overridden with the @option{-specs=} option to specify the
11476appropriate directory location. The Parallel Environment does not
11477support threads, so the @option{-mpe} option and the @option{-pthread}
11478option are incompatible.
11479
11480@item -malign-natural
11481@itemx -malign-power
11482@opindex malign-natural
11483@opindex malign-power
11484On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
11485@option{-malign-natural} overrides the ABI-defined alignment of larger
11486types, such as floating-point doubles, on their natural size-based boundary.
11487The option @option{-malign-power} instructs GCC to follow the ABI-specified
11488alignment rules. GCC defaults to the standard alignment defined in the ABI@.
11489
11490On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
11491is not supported.
11492
11493@item -msoft-float
11494@itemx -mhard-float
11495@opindex msoft-float
11496@opindex mhard-float
11497Generate code that does not use (uses) the floating-point register set.
11498Software floating point emulation is provided if you use the
11499@option{-msoft-float} option, and pass the option to GCC when linking.
11500
11501@item -mmultiple
11502@itemx -mno-multiple
11503@opindex mmultiple
11504@opindex mno-multiple
11505Generate code that uses (does not use) the load multiple word
11506instructions and the store multiple word instructions. These
11507instructions are generated by default on POWER systems, and not
11508generated on PowerPC systems. Do not use @option{-mmultiple} on little
11509endian PowerPC systems, since those instructions do not work when the
11510processor is in little endian mode. The exceptions are PPC740 and
11511PPC750 which permit the instructions usage in little endian mode.
11512
11513@item -mstring
11514@itemx -mno-string
11515@opindex mstring
11516@opindex mno-string
11517Generate code that uses (does not use) the load string instructions
11518and the store string word instructions to save multiple registers and
11519do small block moves. These instructions are generated by default on
11520POWER systems, and not generated on PowerPC systems. Do not use
11521@option{-mstring} on little endian PowerPC systems, since those
11522instructions do not work when the processor is in little endian mode.
11523The exceptions are PPC740 and PPC750 which permit the instructions
11524usage in little endian mode.
11525
11526@item -mupdate
11527@itemx -mno-update
11528@opindex mupdate
11529@opindex mno-update
11530Generate code that uses (does not use) the load or store instructions
11531that update the base register to the address of the calculated memory
11532location. These instructions are generated by default. If you use
11533@option{-mno-update}, there is a small window between the time that the
11534stack pointer is updated and the address of the previous frame is
11535stored, which means code that walks the stack frame across interrupts or
11536signals may get corrupted data.
11537
11538@item -mfused-madd
11539@itemx -mno-fused-madd
11540@opindex mfused-madd
11541@opindex mno-fused-madd
11542Generate code that uses (does not use) the floating point multiply and
11543accumulate instructions. These instructions are generated by default if
11544hardware floating is used.
11545
11546@item -mmulhw
11547@itemx -mno-mulhw
11548@opindex mmulhw
11549@opindex mno-mulhw
11550Generate code that uses (does not use) the half-word multiply and
11551multiply-accumulate instructions on the IBM 405 and 440 processors.
11552These instructions are generated by default when targetting those
11553processors.
11554
11555@item -mdlmzb
11556@itemx -mno-dlmzb
11557@opindex mdlmzb
11558@opindex mno-dlmzb
11559Generate code that uses (does not use) the string-search @samp{dlmzb}
11560instruction on the IBM 405 and 440 processors. This instruction is
11561generated by default when targetting those processors.
11562
11563@item -mno-bit-align
11564@itemx -mbit-align
11565@opindex mno-bit-align
11566@opindex mbit-align
11567On System V.4 and embedded PowerPC systems do not (do) force structures
11568and unions that contain bit-fields to be aligned to the base type of the
11569bit-field.
11570
11571For example, by default a structure containing nothing but 8
11572@code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
11573boundary and have a size of 4 bytes. By using @option{-mno-bit-align},
11574the structure would be aligned to a 1 byte boundary and be one byte in
11575size.
11576
11577@item -mno-strict-align
11578@itemx -mstrict-align
11579@opindex mno-strict-align
11580@opindex mstrict-align
11581On System V.4 and embedded PowerPC systems do not (do) assume that
11582unaligned memory references will be handled by the system.
11583
11584@item -mrelocatable
11585@itemx -mno-relocatable
11586@opindex mrelocatable
11587@opindex mno-relocatable
11588On embedded PowerPC systems generate code that allows (does not allow)
11589the program to be relocated to a different address at runtime. If you
11590use @option{-mrelocatable} on any module, all objects linked together must
11591be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
11592
11593@item -mrelocatable-lib
11594@itemx -mno-relocatable-lib
11595@opindex mrelocatable-lib
11596@opindex mno-relocatable-lib
11597On embedded PowerPC systems generate code that allows (does not allow)
11598the program to be relocated to a different address at runtime. Modules
11599compiled with @option{-mrelocatable-lib} can be linked with either modules
11600compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
11601with modules compiled with the @option{-mrelocatable} options.
11602
11603@item -mno-toc
11604@itemx -mtoc
11605@opindex mno-toc
11606@opindex mtoc
11607On System V.4 and embedded PowerPC systems do not (do) assume that
11608register 2 contains a pointer to a global area pointing to the addresses
11609used in the program.
11610
11611@item -mlittle
11612@itemx -mlittle-endian
11613@opindex mlittle
11614@opindex mlittle-endian
11615On System V.4 and embedded PowerPC systems compile code for the
11616processor in little endian mode. The @option{-mlittle-endian} option is
11617the same as @option{-mlittle}.
11618
11619@item -mbig
11620@itemx -mbig-endian
11621@opindex mbig
11622@opindex mbig-endian
11623On System V.4 and embedded PowerPC systems compile code for the
11624processor in big endian mode. The @option{-mbig-endian} option is
11625the same as @option{-mbig}.
11626
11627@item -mdynamic-no-pic
11628@opindex mdynamic-no-pic
11629On Darwin and Mac OS X systems, compile code so that it is not
11630relocatable, but that its external references are relocatable. The
11631resulting code is suitable for applications, but not shared
11632libraries.
11633
11634@item -mprioritize-restricted-insns=@var{priority}
11635@opindex mprioritize-restricted-insns
11636This option controls the priority that is assigned to
11637dispatch-slot restricted instructions during the second scheduling
11638pass. The argument @var{priority} takes the value @var{0/1/2} to assign
11639@var{no/highest/second-highest} priority to dispatch slot restricted
11640instructions.
11641
11642@item -msched-costly-dep=@var{dependence_type}
11643@opindex msched-costly-dep
11644This option controls which dependences are considered costly
11645by the target during instruction scheduling. The argument
11646@var{dependence_type} takes one of the following values:
11647@var{no}: no dependence is costly,
11648@var{all}: all dependences are costly,
11649@var{true_store_to_load}: a true dependence from store to load is costly,
11650@var{store_to_load}: any dependence from store to load is costly,
11651@var{number}: any dependence which latency >= @var{number} is costly.
11652
11653@item -minsert-sched-nops=@var{scheme}
11654@opindex minsert-sched-nops
11655This option controls which nop insertion scheme will be used during
11656the second scheduling pass. The argument @var{scheme} takes one of the
11657following values:
11658@var{no}: Don't insert nops.
11659@var{pad}: Pad with nops any dispatch group which has vacant issue slots,
11660according to the scheduler's grouping.
11661@var{regroup_exact}: Insert nops to force costly dependent insns into
11662separate groups. Insert exactly as many nops as needed to force an insn
11663to a new group, according to the estimated processor grouping.
11664@var{number}: Insert nops to force costly dependent insns into
11665separate groups. Insert @var{number} nops to force an insn to a new group.
11666
11667@item -mcall-sysv
11668@opindex mcall-sysv
11669On System V.4 and embedded PowerPC systems compile code using calling
11670conventions that adheres to the March 1995 draft of the System V
11671Application Binary Interface, PowerPC processor supplement. This is the
11672default unless you configured GCC using @samp{powerpc-*-eabiaix}.
11673
11674@item -mcall-sysv-eabi
11675@opindex mcall-sysv-eabi
11676Specify both @option{-mcall-sysv} and @option{-meabi} options.
11677
11678@item -mcall-sysv-noeabi
11679@opindex mcall-sysv-noeabi
11680Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
11681
11682@item -mcall-solaris
11683@opindex mcall-solaris
11684On System V.4 and embedded PowerPC systems compile code for the Solaris
11685operating system.
11686
11687@item -mcall-linux
11688@opindex mcall-linux
11689On System V.4 and embedded PowerPC systems compile code for the
11690Linux-based GNU system.
11691
11692@item -mcall-gnu
11693@opindex mcall-gnu
11694On System V.4 and embedded PowerPC systems compile code for the
11695Hurd-based GNU system.
11696
11697@item -mcall-netbsd
11698@opindex mcall-netbsd
11699On System V.4 and embedded PowerPC systems compile code for the
11700NetBSD operating system.
11701
11702@item -maix-struct-return
11703@opindex maix-struct-return
11704Return all structures in memory (as specified by the AIX ABI)@.
11705
11706@item -msvr4-struct-return
11707@opindex msvr4-struct-return
11708Return structures smaller than 8 bytes in registers (as specified by the
11709SVR4 ABI)@.
11710
11711@item -mabi=@var{abi-type}
11712@opindex mabi
11713Extend the current ABI with a particular extension, or remove such extension.
11714Valid values are @var{altivec}, @var{no-altivec}, @var{spe},
11715@var{no-spe}, @var{ibmlongdouble}, @var{ieeelongdouble}@.
11716
11717@item -mabi=spe
11718@opindex mabi=spe
11719Extend the current ABI with SPE ABI extensions. This does not change
11720the default ABI, instead it adds the SPE ABI extensions to the current
11721ABI@.
11722
11723@item -mabi=no-spe
11724@opindex mabi=no-spe
11725Disable Booke SPE ABI extensions for the current ABI@.
11726
11727@item -mabi=ibmlongdouble
11728@opindex mabi=ibmlongdouble
11729Change the current ABI to use IBM extended precision long double.
11730This is a PowerPC 32-bit SYSV ABI option.
11731
11732@item -mabi=ieeelongdouble
11733@opindex mabi=ieeelongdouble
11734Change the current ABI to use IEEE extended precision long double.
11735This is a PowerPC 32-bit Linux ABI option.
11736
11737@item -mprototype
11738@itemx -mno-prototype
11739@opindex mprototype
11740@opindex mno-prototype
11741On System V.4 and embedded PowerPC systems assume that all calls to
11742variable argument functions are properly prototyped. Otherwise, the
11743compiler must insert an instruction before every non prototyped call to
11744set or clear bit 6 of the condition code register (@var{CR}) to
11745indicate whether floating point values were passed in the floating point
11746registers in case the function takes a variable arguments. With
11747@option{-mprototype}, only calls to prototyped variable argument functions
11748will set or clear the bit.
11749
11750@item -msim
11751@opindex msim
11752On embedded PowerPC systems, assume that the startup module is called
11753@file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
11754@file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
11755configurations.
11756
11757@item -mmvme
11758@opindex mmvme
11759On embedded PowerPC systems, assume that the startup module is called
11760@file{crt0.o} and the standard C libraries are @file{libmvme.a} and
11761@file{libc.a}.
11762
11763@item -mads
11764@opindex mads
11765On embedded PowerPC systems, assume that the startup module is called
11766@file{crt0.o} and the standard C libraries are @file{libads.a} and
11767@file{libc.a}.
11768
11769@item -myellowknife
11770@opindex myellowknife
11771On embedded PowerPC systems, assume that the startup module is called
11772@file{crt0.o} and the standard C libraries are @file{libyk.a} and
11773@file{libc.a}.
11774
11775@item -mvxworks
11776@opindex mvxworks
11777On System V.4 and embedded PowerPC systems, specify that you are
11778compiling for a VxWorks system.
11779
11780@item -mwindiss
11781@opindex mwindiss
11782Specify that you are compiling for the WindISS simulation environment.
11783
11784@item -memb
11785@opindex memb
11786On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
11787header to indicate that @samp{eabi} extended relocations are used.
11788
11789@item -meabi
11790@itemx -mno-eabi
11791@opindex meabi
11792@opindex mno-eabi
11793On System V.4 and embedded PowerPC systems do (do not) adhere to the
11794Embedded Applications Binary Interface (eabi) which is a set of
11795modifications to the System V.4 specifications. Selecting @option{-meabi}
11796means that the stack is aligned to an 8 byte boundary, a function
11797@code{__eabi} is called to from @code{main} to set up the eabi
11798environment, and the @option{-msdata} option can use both @code{r2} and
11799@code{r13} to point to two separate small data areas. Selecting
11800@option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
11801do not call an initialization function from @code{main}, and the
11802@option{-msdata} option will only use @code{r13} to point to a single
11803small data area. The @option{-meabi} option is on by default if you
11804configured GCC using one of the @samp{powerpc*-*-eabi*} options.
11805
11806@item -msdata=eabi
11807@opindex msdata=eabi
11808On System V.4 and embedded PowerPC systems, put small initialized
11809@code{const} global and static data in the @samp{.sdata2} section, which
11810is pointed to by register @code{r2}. Put small initialized
11811non-@code{const} global and static data in the @samp{.sdata} section,
11812which is pointed to by register @code{r13}. Put small uninitialized
11813global and static data in the @samp{.sbss} section, which is adjacent to
11814the @samp{.sdata} section. The @option{-msdata=eabi} option is
11815incompatible with the @option{-mrelocatable} option. The
11816@option{-msdata=eabi} option also sets the @option{-memb} option.
11817
11818@item -msdata=sysv
11819@opindex msdata=sysv
11820On System V.4 and embedded PowerPC systems, put small global and static
11821data in the @samp{.sdata} section, which is pointed to by register
11822@code{r13}. Put small uninitialized global and static data in the
11823@samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
11824The @option{-msdata=sysv} option is incompatible with the
11825@option{-mrelocatable} option.
11826
11827@item -msdata=default
11828@itemx -msdata
11829@opindex msdata=default
11830@opindex msdata
11831On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
11832compile code the same as @option{-msdata=eabi}, otherwise compile code the
11833same as @option{-msdata=sysv}.
11834
11835@item -msdata-data
11836@opindex msdata-data
11837On System V.4 and embedded PowerPC systems, put small global
11838data in the @samp{.sdata} section. Put small uninitialized global
11839data in the @samp{.sbss} section. Do not use register @code{r13}
11840to address small data however. This is the default behavior unless
11841other @option{-msdata} options are used.
11842
11843@item -msdata=none
11844@itemx -mno-sdata
11845@opindex msdata=none
11846@opindex mno-sdata
11847On embedded PowerPC systems, put all initialized global and static data
11848in the @samp{.data} section, and all uninitialized data in the
11849@samp{.bss} section.
11850
11851@item -G @var{num}
11852@opindex G
11853@cindex smaller data references (PowerPC)
11854@cindex .sdata/.sdata2 references (PowerPC)
11855On embedded PowerPC systems, put global and static items less than or
11856equal to @var{num} bytes into the small data or bss sections instead of
11857the normal data or bss section. By default, @var{num} is 8. The
11858@option{-G @var{num}} switch is also passed to the linker.
11859All modules should be compiled with the same @option{-G @var{num}} value.
11860
11861@item -mregnames
11862@itemx -mno-regnames
11863@opindex mregnames
11864@opindex mno-regnames
11865On System V.4 and embedded PowerPC systems do (do not) emit register
11866names in the assembly language output using symbolic forms.
11867
11868@item -mlongcall
11869@itemx -mno-longcall
11870@opindex mlongcall
11871@opindex mno-longcall
11872By default assume that all calls are far away so that a longer more
11873expensive calling sequence is required. This is required for calls
11874further than 32 megabytes (33,554,432 bytes) from the current location.
11875A short call will be generated if the compiler knows
11876the call cannot be that far away. This setting can be overridden by
11877the @code{shortcall} function attribute, or by @code{#pragma
11878longcall(0)}.
11879
11880Some linkers are capable of detecting out-of-range calls and generating
11881glue code on the fly. On these systems, long calls are unnecessary and
11882generate slower code. As of this writing, the AIX linker can do this,
11883as can the GNU linker for PowerPC/64. It is planned to add this feature
11884to the GNU linker for 32-bit PowerPC systems as well.
11885
11886On Darwin/PPC systems, @code{#pragma longcall} will generate ``jbsr
11887callee, L42'', plus a ``branch island'' (glue code). The two target
11888addresses represent the callee and the ``branch island''. The
11889Darwin/PPC linker will prefer the first address and generate a ``bl
11890callee'' if the PPC ``bl'' instruction will reach the callee directly;
11891otherwise, the linker will generate ``bl L42'' to call the ``branch
11892island''. The ``branch island'' is appended to the body of the
11893calling function; it computes the full 32-bit address of the callee
11894and jumps to it.
11895
11896On Mach-O (Darwin) systems, this option directs the compiler emit to
11897the glue for every direct call, and the Darwin linker decides whether
11898to use or discard it.
11899
11900In the future, we may cause GCC to ignore all longcall specifications
11901when the linker is known to generate glue.
11902
11903@item -pthread
11904@opindex pthread
11905Adds support for multithreading with the @dfn{pthreads} library.
11906This option sets flags for both the preprocessor and linker.
11907
11908@end table
11909
11910@node S/390 and zSeries Options
11911@subsection S/390 and zSeries Options
11912@cindex S/390 and zSeries Options
11913
11914These are the @samp{-m} options defined for the S/390 and zSeries architecture.
11915
11916@table @gcctabopt
11917@item -mhard-float
11918@itemx -msoft-float
11919@opindex mhard-float
11920@opindex msoft-float
11921Use (do not use) the hardware floating-point instructions and registers
11922for floating-point operations. When @option{-msoft-float} is specified,
11923functions in @file{libgcc.a} will be used to perform floating-point
11924operations. When @option{-mhard-float} is specified, the compiler
11925generates IEEE floating-point instructions. This is the default.
11926
11927@item -mlong-double-64
11928@itemx -mlong-double-128
11929@opindex mlong-double-64
11930@opindex mlong-double-128
11931These switches control the size of @code{long double} type. A size
11932of 64bit makes the @code{long double} type equivalent to the @code{double}
11933type. This is the default.
11934
11935@item -mbackchain
11936@itemx -mno-backchain
11937@opindex mbackchain
11938@opindex mno-backchain
11939Store (do not store) the address of the caller's frame as backchain pointer
11940into the callee's stack frame.
11941A backchain may be needed to allow debugging using tools that do not understand
11942DWARF-2 call frame information.
11943When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
11944at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
11945the backchain is placed into the topmost word of the 96/160 byte register
11946save area.
11947
11948In general, code compiled with @option{-mbackchain} is call-compatible with
11949code compiled with @option{-mmo-backchain}; however, use of the backchain
11950for debugging purposes usually requires that the whole binary is built with
11951@option{-mbackchain}. Note that the combination of @option{-mbackchain},
11952@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
11953to build a linux kernel use @option{-msoft-float}.
11954
11955The default is to not maintain the backchain.
11956
11957@item -mpacked-stack
11958@item -mno-packed-stack
11959@opindex mpacked-stack
11960@opindex mno-packed-stack
11961Use (do not use) the packed stack layout. When @option{-mno-packed-stack} is
11962specified, the compiler uses the all fields of the 96/160 byte register save
11963area only for their default purpose; unused fields still take up stack space.
11964When @option{-mpacked-stack} is specified, register save slots are densely
11965packed at the top of the register save area; unused space is reused for other
11966purposes, allowing for more efficient use of the available stack space.
11967However, when @option{-mbackchain} is also in effect, the topmost word of
11968the save area is always used to store the backchain, and the return address
11969register is always saved two words below the backchain.
11970
11971As long as the stack frame backchain is not used, code generated with
11972@option{-mpacked-stack} is call-compatible with code generated with
11973@option{-mno-packed-stack}. Note that some non-FSF releases of GCC 2.95 for
11974S/390 or zSeries generated code that uses the stack frame backchain at run
11975time, not just for debugging purposes. Such code is not call-compatible
11976with code compiled with @option{-mpacked-stack}. Also, note that the
11977combination of @option{-mbackchain},
11978@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
11979to build a linux kernel use @option{-msoft-float}.
11980
11981The default is to not use the packed stack layout.
11982
11983@item -msmall-exec
11984@itemx -mno-small-exec
11985@opindex msmall-exec
11986@opindex mno-small-exec
11987Generate (or do not generate) code using the @code{bras} instruction
11988to do subroutine calls.
11989This only works reliably if the total executable size does not
11990exceed 64k. The default is to use the @code{basr} instruction instead,
11991which does not have this limitation.
11992
11993@item -m64
11994@itemx -m31
11995@opindex m64
11996@opindex m31
11997When @option{-m31} is specified, generate code compliant to the
11998GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate
11999code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in
12000particular to generate 64-bit instructions. For the @samp{s390}
12001targets, the default is @option{-m31}, while the @samp{s390x}
12002targets default to @option{-m64}.
12003
12004@item -mzarch
12005@itemx -mesa
12006@opindex mzarch
12007@opindex mesa
12008When @option{-mzarch} is specified, generate code using the
12009instructions available on z/Architecture.
12010When @option{-mesa} is specified, generate code using the
12011instructions available on ESA/390. Note that @option{-mesa} is
12012not possible with @option{-m64}.
12013When generating code compliant to the GNU/Linux for S/390 ABI,
12014the default is @option{-mesa}. When generating code compliant
12015to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
12016
12017@item -mmvcle
12018@itemx -mno-mvcle
12019@opindex mmvcle
12020@opindex mno-mvcle
12021Generate (or do not generate) code using the @code{mvcle} instruction
12022to perform block moves. When @option{-mno-mvcle} is specified,
12023use a @code{mvc} loop instead. This is the default unless optimizing for
12024size.
12025
12026@item -mdebug
12027@itemx -mno-debug
12028@opindex mdebug
12029@opindex mno-debug
12030Print (or do not print) additional debug information when compiling.
12031The default is to not print debug information.
12032
12033@item -march=@var{cpu-type}
12034@opindex march
12035Generate code that will run on @var{cpu-type}, which is the name of a system
12036representing a certain processor type. Possible values for
12037@var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, and @samp{z990}.
12038When generating code using the instructions available on z/Architecture,
12039the default is @option{-march=z900}. Otherwise, the default is
12040@option{-march=g5}.
12041
12042@item -mtune=@var{cpu-type}
12043@opindex mtune
12044Tune to @var{cpu-type} everything applicable about the generated code,
12045except for the ABI and the set of available instructions.
12046The list of @var{cpu-type} values is the same as for @option{-march}.
12047The default is the value used for @option{-march}.
12048
12049@item -mtpf-trace
12050@itemx -mno-tpf-trace
12051@opindex mtpf-trace
12052@opindex mno-tpf-trace
12053Generate code that adds (does not add) in TPF OS specific branches to trace
12054routines in the operating system. This option is off by default, even
12055when compiling for the TPF OS@.
12056
12057@item -mfused-madd
12058@itemx -mno-fused-madd
12059@opindex mfused-madd
12060@opindex mno-fused-madd
12061Generate code that uses (does not use) the floating point multiply and
12062accumulate instructions. These instructions are generated by default if
12063hardware floating point is used.
12064
12065@item -mwarn-framesize=@var{framesize}
12066@opindex mwarn-framesize
12067Emit a warning if the current function exceeds the given frame size. Because
12068this is a compile time check it doesn't need to be a real problem when the program
12069runs. It is intended to identify functions which most probably cause
12070a stack overflow. It is useful to be used in an environment with limited stack
12071size e.g.@: the linux kernel.
12072
12073@item -mwarn-dynamicstack
12074@opindex mwarn-dynamicstack
12075Emit a warning if the function calls alloca or uses dynamically
12076sized arrays. This is generally a bad idea with a limited stack size.
12077
12078@item -mstack-guard=@var{stack-guard}
12079@item -mstack-size=@var{stack-size}
12080@opindex mstack-guard
12081@opindex mstack-size
12082These arguments always have to be used in conjunction. If they are present the s390
12083back end emits additional instructions in the function prologue which trigger a trap
12084if the stack size is @var{stack-guard} bytes above the @var{stack-size}
12085(remember that the stack on s390 grows downward). These options are intended to
12086be used to help debugging stack overflow problems. The additionally emitted code
12087causes only little overhead and hence can also be used in production like systems
12088without greater performance degradation. The given values have to be exact
12089powers of 2 and @var{stack-size} has to be greater than @var{stack-guard} without
12090exceeding 64k.
12091In order to be efficient the extra code makes the assumption that the stack starts
12092at an address aligned to the value given by @var{stack-size}.
12093@end table
12094
12095@node Score Options
12096@subsection Score Options
12097@cindex Score Options
12098
12099These options are defined for Score implementations:
12100
12101@table @gcctabopt
12102@item -meb
12103@opindex meb
12104Compile code for big endian mode. This is the default.
12105
12106@item -mel
12107@opindex mel
12108Compile code for little endian mode.
12109
12110@item -mnhwloop
12111@opindex mnhwloop
12112Disable generate bcnz instruction.
12113
12114@item -muls
12115@opindex muls
12116Enable generate unaligned load and store instruction.
12117
12118@item -mmac
12119@opindex mmac
12120Enable the use of multiply-accumulate instructions. Disabled by default.
12121
12122@item -mscore5
12123@opindex mscore5
12124Specify the SCORE5 as the target architecture.
12125
12126@item -mscore5u
12127@opindex mscore5u
12128Specify the SCORE5U of the target architecture.
12129
12130@item -mscore7
12131@opindex mscore7
12132Specify the SCORE7 as the target architecture. This is the default.
12133
12134@item -mscore7d
12135@opindex mscore7d
12136Specify the SCORE7D as the target architecture.
12137@end table
12138
12139@node SH Options
12140@subsection SH Options
12141
12142These @samp{-m} options are defined for the SH implementations:
12143
12144@table @gcctabopt
12145@item -m1
12146@opindex m1
12147Generate code for the SH1.
12148
12149@item -m2
12150@opindex m2
12151Generate code for the SH2.
12152
12153@item -m2e
12154Generate code for the SH2e.
12155
12156@item -m3
12157@opindex m3
12158Generate code for the SH3.
12159
12160@item -m3e
12161@opindex m3e
12162Generate code for the SH3e.
12163
12164@item -m4-nofpu
12165@opindex m4-nofpu
12166Generate code for the SH4 without a floating-point unit.
12167
12168@item -m4-single-only
12169@opindex m4-single-only
12170Generate code for the SH4 with a floating-point unit that only
12171supports single-precision arithmetic.
12172
12173@item -m4-single
12174@opindex m4-single
12175Generate code for the SH4 assuming the floating-point unit is in
12176single-precision mode by default.
12177
12178@item -m4
12179@opindex m4
12180Generate code for the SH4.
12181
12182@item -m4a-nofpu
12183@opindex m4a-nofpu
12184Generate code for the SH4al-dsp, or for a SH4a in such a way that the
12185floating-point unit is not used.
12186
12187@item -m4a-single-only
12188@opindex m4a-single-only
12189Generate code for the SH4a, in such a way that no double-precision
12190floating point operations are used.
12191
12192@item -m4a-single
12193@opindex m4a-single
12194Generate code for the SH4a assuming the floating-point unit is in
12195single-precision mode by default.
12196
12197@item -m4a
12198@opindex m4a
12199Generate code for the SH4a.
12200
12201@item -m4al
12202@opindex m4al
12203Same as @option{-m4a-nofpu}, except that it implicitly passes
12204@option{-dsp} to the assembler. GCC doesn't generate any DSP
12205instructions at the moment.
12206
12207@item -mb
12208@opindex mb
12209Compile code for the processor in big endian mode.
12210
12211@item -ml
12212@opindex ml
12213Compile code for the processor in little endian mode.
12214
12215@item -mdalign
12216@opindex mdalign
12217Align doubles at 64-bit boundaries. Note that this changes the calling
12218conventions, and thus some functions from the standard C library will
12219not work unless you recompile it first with @option{-mdalign}.
12220
12221@item -mrelax
12222@opindex mrelax
12223Shorten some address references at link time, when possible; uses the
12224linker option @option{-relax}.
12225
12226@item -mbigtable
12227@opindex mbigtable
12228Use 32-bit offsets in @code{switch} tables. The default is to use
1222916-bit offsets.
12230
12231@item -mfmovd
12232@opindex mfmovd
12233Enable the use of the instruction @code{fmovd}.
12234
12235@item -mhitachi
12236@opindex mhitachi
12237Comply with the calling conventions defined by Renesas.
12238
12239@item -mrenesas
12240@opindex mhitachi
12241Comply with the calling conventions defined by Renesas.
12242
12243@item -mno-renesas
12244@opindex mhitachi
12245Comply with the calling conventions defined for GCC before the Renesas
12246conventions were available. This option is the default for all
12247targets of the SH toolchain except for @samp{sh-symbianelf}.
12248
12249@item -mnomacsave
12250@opindex mnomacsave
12251Mark the @code{MAC} register as call-clobbered, even if
12252@option{-mhitachi} is given.
12253
12254@item -mieee
12255@opindex mieee
12256Increase IEEE-compliance of floating-point code.
12257At the moment, this is equivalent to @option{-fno-finite-math-only}.
12258When generating 16 bit SH opcodes, getting IEEE-conforming results for
12259comparisons of NANs / infinities incurs extra overhead in every
12260floating point comparison, therefore the default is set to
12261@option{-ffinite-math-only}.
12262
12263@item -misize
12264@opindex misize
12265Dump instruction size and location in the assembly code.
12266
12267@item -mpadstruct
12268@opindex mpadstruct
12269This option is deprecated. It pads structures to multiple of 4 bytes,
12270which is incompatible with the SH ABI@.
12271
12272@item -mspace
12273@opindex mspace
12274Optimize for space instead of speed. Implied by @option{-Os}.
12275
12276@item -mprefergot
12277@opindex mprefergot
12278When generating position-independent code, emit function calls using
12279the Global Offset Table instead of the Procedure Linkage Table.
12280
12281@item -musermode
12282@opindex musermode
12283Generate a library function call to invalidate instruction cache
12284entries, after fixing up a trampoline. This library function call
12285doesn't assume it can write to the whole memory address space. This
12286is the default when the target is @code{sh-*-linux*}.
12287
12288@item -multcost=@var{number}
12289@opindex multcost=@var{number}
12290Set the cost to assume for a multiply insn.
12291
12292@item -mdiv=@var{strategy}
12293@opindex mdiv=@var{strategy}
12294Set the division strategy to use for SHmedia code. @var{strategy} must be
12295one of: call, call2, fp, inv, inv:minlat, inv20u, inv20l, inv:call,
12296inv:call2, inv:fp .
12297"fp" performs the operation in floating point. This has a very high latency,
12298but needs only a few instructions, so it might be a good choice if
12299your code has enough easily exploitable ILP to allow the compiler to
12300schedule the floating point instructions together with other instructions.
12301Division by zero causes a floating point exception.
12302"inv" uses integer operations to calculate the inverse of the divisor,
12303and then multiplies the dividend with the inverse. This strategy allows
12304cse and hoisting of the inverse calculation. Division by zero calculates
12305an unspecified result, but does not trap.
12306"inv:minlat" is a variant of "inv" where if no cse / hoisting opportunities
12307have been found, or if the entire operation has been hoisted to the same
12308place, the last stages of the inverse calculation are intertwined with the
12309final multiply to reduce the overall latency, at the expense of using a few
12310more instructions, and thus offering fewer scheduling opportunities with
12311other code.
12312"call" calls a library function that usually implements the inv:minlat
12313strategy.
12314This gives high code density for m5-*media-nofpu compilations.
12315"call2" uses a different entry point of the same library function, where it
12316assumes that a pointer to a lookup table has already been set up, which
12317exposes the pointer load to cse / code hoisting optimizations.
12318"inv:call", "inv:call2" and "inv:fp" all use the "inv" algorithm for initial
12319code generation, but if the code stays unoptimized, revert to the "call",
12320"call2", or "fp" strategies, respectively. Note that the
12321potentially-trapping side effect of division by zero is carried by a
12322separate instruction, so it is possible that all the integer instructions
12323are hoisted out, but the marker for the side effect stays where it is.
12324A recombination to fp operations or a call is not possible in that case.
12325"inv20u" and "inv20l" are variants of the "inv:minlat" strategy. In the case
12326that the inverse calculation was nor separated from the multiply, they speed
12327up division where the dividend fits into 20 bits (plus sign where applicable),
12328by inserting a test to skip a number of operations in this case; this test
12329slows down the case of larger dividends. inv20u assumes the case of a such
12330a small dividend to be unlikely, and inv20l assumes it to be likely.
12331
12332@item -mdivsi3_libfunc=@var{name}
12333@opindex mdivsi3_libfunc=@var{name}
12334Set the name of the library function used for 32 bit signed division to
12335@var{name}. This only affect the name used in the call and inv:call
12336division strategies, and the compiler will still expect the same
12337sets of input/output/clobbered registers as if this option was not present.
12338
12339@item -madjust-unroll
12340@opindex madjust-unroll
12341Throttle unrolling to avoid thrashing target registers.
12342This option only has an effect if the gcc code base supports the
12343TARGET_ADJUST_UNROLL_MAX target hook.
12344
12345@item -mindexed-addressing
12346@opindex mindexed-addressing
12347Enable the use of the indexed addressing mode for SHmedia32/SHcompact.
12348This is only safe if the hardware and/or OS implement 32 bit wrap-around
12349semantics for the indexed addressing mode. The architecture allows the
12350implementation of processors with 64 bit MMU, which the OS could use to
12351get 32 bit addressing, but since no current hardware implementation supports
12352this or any other way to make the indexed addressing mode safe to use in
12353the 32 bit ABI, the default is -mno-indexed-addressing.
12354
12355@item -mgettrcost=@var{number}
12356@opindex mgettrcost=@var{number}
12357Set the cost assumed for the gettr instruction to @var{number}.
12358The default is 2 if @option{-mpt-fixed} is in effect, 100 otherwise.
12359
12360@item -mpt-fixed
12361@opindex mpt-fixed
12362Assume pt* instructions won't trap. This will generally generate better
12363scheduled code, but is unsafe on current hardware. The current architecture
12364definition says that ptabs and ptrel trap when the target anded with 3 is 3.
12365This has the unintentional effect of making it unsafe to schedule ptabs /
12366ptrel before a branch, or hoist it out of a loop. For example,
12367__do_global_ctors, a part of libgcc that runs constructors at program
12368startup, calls functions in a list which is delimited by -1. With the
12369-mpt-fixed option, the ptabs will be done before testing against -1.
12370That means that all the constructors will be run a bit quicker, but when
12371the loop comes to the end of the list, the program crashes because ptabs
12372loads -1 into a target register. Since this option is unsafe for any
12373hardware implementing the current architecture specification, the default
12374is -mno-pt-fixed. Unless the user specifies a specific cost with
12375@option{-mgettrcost}, -mno-pt-fixed also implies @option{-mgettrcost=100};
12376this deters register allocation using target registers for storing
12377ordinary integers.
12378
12379@item -minvalid-symbols
12380@opindex minvalid-symbols
12381Assume symbols might be invalid. Ordinary function symbols generated by
12382the compiler will always be valid to load with movi/shori/ptabs or
12383movi/shori/ptrel, but with assembler and/or linker tricks it is possible
12384to generate symbols that will cause ptabs / ptrel to trap.
12385This option is only meaningful when @option{-mno-pt-fixed} is in effect.
12386It will then prevent cross-basic-block cse, hoisting and most scheduling
12387of symbol loads. The default is @option{-mno-invalid-symbols}.
12388@end table
12389
12390@node SPARC Options
12391@subsection SPARC Options
12392@cindex SPARC options
12393
12394These @samp{-m} options are supported on the SPARC:
12395
12396@table @gcctabopt
12397@item -mno-app-regs
12398@itemx -mapp-regs
12399@opindex mno-app-regs
12400@opindex mapp-regs
12401Specify @option{-mapp-regs} to generate output using the global registers
124022 through 4, which the SPARC SVR4 ABI reserves for applications. This
12403is the default.
12404
12405To be fully SVR4 ABI compliant at the cost of some performance loss,
12406specify @option{-mno-app-regs}. You should compile libraries and system
12407software with this option.
12408
12409@item -mfpu
12410@itemx -mhard-float
12411@opindex mfpu
12412@opindex mhard-float
12413Generate output containing floating point instructions. This is the
12414default.
12415
12416@item -mno-fpu
12417@itemx -msoft-float
12418@opindex mno-fpu
12419@opindex msoft-float
12420Generate output containing library calls for floating point.
12421@strong{Warning:} the requisite libraries are not available for all SPARC
12422targets. Normally the facilities of the machine's usual C compiler are
12423used, but this cannot be done directly in cross-compilation. You must make
12424your own arrangements to provide suitable library functions for
12425cross-compilation. The embedded targets @samp{sparc-*-aout} and
12426@samp{sparclite-*-*} do provide software floating point support.
12427
12428@option{-msoft-float} changes the calling convention in the output file;
12429therefore, it is only useful if you compile @emph{all} of a program with
12430this option. In particular, you need to compile @file{libgcc.a}, the
12431library that comes with GCC, with @option{-msoft-float} in order for
12432this to work.
12433
12434@item -mhard-quad-float
12435@opindex mhard-quad-float
12436Generate output containing quad-word (long double) floating point
12437instructions.
12438
12439@item -msoft-quad-float
12440@opindex msoft-quad-float
12441Generate output containing library calls for quad-word (long double)
12442floating point instructions. The functions called are those specified
12443in the SPARC ABI@. This is the default.
12444
12445As of this writing, there are no SPARC implementations that have hardware
12446support for the quad-word floating point instructions. They all invoke
12447a trap handler for one of these instructions, and then the trap handler
12448emulates the effect of the instruction. Because of the trap handler overhead,
12449this is much slower than calling the ABI library routines. Thus the
12450@option{-msoft-quad-float} option is the default.
12451
12452@item -mno-unaligned-doubles
12453@itemx -munaligned-doubles
12454@opindex mno-unaligned-doubles
12455@opindex munaligned-doubles
12456Assume that doubles have 8 byte alignment. This is the default.
12457
12458With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
12459alignment only if they are contained in another type, or if they have an
12460absolute address. Otherwise, it assumes they have 4 byte alignment.
12461Specifying this option avoids some rare compatibility problems with code
12462generated by other compilers. It is not the default because it results
12463in a performance loss, especially for floating point code.
12464
12465@item -mno-faster-structs
12466@itemx -mfaster-structs
12467@opindex mno-faster-structs
12468@opindex mfaster-structs
12469With @option{-mfaster-structs}, the compiler assumes that structures
12470should have 8 byte alignment. This enables the use of pairs of
12471@code{ldd} and @code{std} instructions for copies in structure
12472assignment, in place of twice as many @code{ld} and @code{st} pairs.
12473However, the use of this changed alignment directly violates the SPARC
12474ABI@. Thus, it's intended only for use on targets where the developer
12475acknowledges that their resulting code will not be directly in line with
12476the rules of the ABI@.
12477
12478@item -mimpure-text
12479@opindex mimpure-text
12480@option{-mimpure-text}, used in addition to @option{-shared}, tells
12481the compiler to not pass @option{-z text} to the linker when linking a
12482shared object. Using this option, you can link position-dependent
12483code into a shared object.
12484
12485@option{-mimpure-text} suppresses the ``relocations remain against
12486allocatable but non-writable sections'' linker error message.
12487However, the necessary relocations will trigger copy-on-write, and the
12488shared object is not actually shared across processes. Instead of
12489using @option{-mimpure-text}, you should compile all source code with
12490@option{-fpic} or @option{-fPIC}.
12491
12492This option is only available on SunOS and Solaris.
12493
12494@item -mcpu=@var{cpu_type}
12495@opindex mcpu
12496Set the instruction set, register set, and instruction scheduling parameters
12497for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
12498@samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
12499@samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x},
12500@samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc},
12501@samp{ultrasparc3}, and @samp{niagara}.
12502
12503Default instruction scheduling parameters are used for values that select
12504an architecture and not an implementation. These are @samp{v7}, @samp{v8},
12505@samp{sparclite}, @samp{sparclet}, @samp{v9}.
12506
12507Here is a list of each supported architecture and their supported
12508implementations.
12509
12510@smallexample
12511 v7: cypress
12512 v8: supersparc, hypersparc
12513 sparclite: f930, f934, sparclite86x
12514 sparclet: tsc701
12515 v9: ultrasparc, ultrasparc3, niagara
12516@end smallexample
12517
12518By default (unless configured otherwise), GCC generates code for the V7
12519variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler
12520additionally optimizes it for the Cypress CY7C602 chip, as used in the
12521SPARCStation/SPARCServer 3xx series. This is also appropriate for the older
12522SPARCStation 1, 2, IPX etc.
12523
12524With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
12525architecture. The only difference from V7 code is that the compiler emits
12526the integer multiply and integer divide instructions which exist in SPARC-V8
12527but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally
12528optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
125292000 series.
12530
12531With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
12532the SPARC architecture. This adds the integer multiply, integer divide step
12533and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
12534With @option{-mcpu=f930}, the compiler additionally optimizes it for the
12535Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@. With
12536@option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
12537MB86934 chip, which is the more recent SPARClite with FPU@.
12538
12539With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
12540the SPARC architecture. This adds the integer multiply, multiply/accumulate,
12541integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
12542but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally
12543optimizes it for the TEMIC SPARClet chip.
12544
12545With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
12546architecture. This adds 64-bit integer and floating-point move instructions,
125473 additional floating-point condition code registers and conditional move
12548instructions. With @option{-mcpu=ultrasparc}, the compiler additionally
12549optimizes it for the Sun UltraSPARC I/II/IIi chips. With
12550@option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
12551Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips. With
12552@option{-mcpu=niagara}, the compiler additionally optimizes it for
12553Sun UltraSPARC T1 chips.
12554
12555@item -mtune=@var{cpu_type}
12556@opindex mtune
12557Set the instruction scheduling parameters for machine type
12558@var{cpu_type}, but do not set the instruction set or register set that the
12559option @option{-mcpu=@var{cpu_type}} would.
12560
12561The same values for @option{-mcpu=@var{cpu_type}} can be used for
12562@option{-mtune=@var{cpu_type}}, but the only useful values are those
12563that select a particular cpu implementation. Those are @samp{cypress},
12564@samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
12565@samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc},
12566@samp{ultrasparc3}, and @samp{niagara}.
12567
12568@item -mv8plus
12569@itemx -mno-v8plus
12570@opindex mv8plus
12571@opindex mno-v8plus
12572With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@. The
12573difference from the V8 ABI is that the global and out registers are
12574considered 64-bit wide. This is enabled by default on Solaris in 32-bit
12575mode for all SPARC-V9 processors.
12576
12577@item -mvis
12578@itemx -mno-vis
12579@opindex mvis
12580@opindex mno-vis
12581With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
12582Visual Instruction Set extensions. The default is @option{-mno-vis}.
12583@end table
12584
12585These @samp{-m} options are supported in addition to the above
12586on SPARC-V9 processors in 64-bit environments:
12587
12588@table @gcctabopt
12589@item -mlittle-endian
12590@opindex mlittle-endian
12591Generate code for a processor running in little-endian mode. It is only
12592available for a few configurations and most notably not on Solaris and Linux.
12593
12594@item -m32
12595@itemx -m64
12596@opindex m32
12597@opindex m64
12598Generate code for a 32-bit or 64-bit environment.
12599The 32-bit environment sets int, long and pointer to 32 bits.
12600The 64-bit environment sets int to 32 bits and long and pointer
12601to 64 bits.
12602
12603@item -mcmodel=medlow
12604@opindex mcmodel=medlow
12605Generate code for the Medium/Low code model: 64-bit addresses, programs
12606must be linked in the low 32 bits of memory. Programs can be statically
12607or dynamically linked.
12608
12609@item -mcmodel=medmid
12610@opindex mcmodel=medmid
12611Generate code for the Medium/Middle code model: 64-bit addresses, programs
12612must be linked in the low 44 bits of memory, the text and data segments must
12613be less than 2GB in size and the data segment must be located within 2GB of
12614the text segment.
12615
12616@item -mcmodel=medany
12617@opindex mcmodel=medany
12618Generate code for the Medium/Anywhere code model: 64-bit addresses, programs
12619may be linked anywhere in memory, the text and data segments must be less
12620than 2GB in size and the data segment must be located within 2GB of the
12621text segment.
12622
12623@item -mcmodel=embmedany
12624@opindex mcmodel=embmedany
12625Generate code for the Medium/Anywhere code model for embedded systems:
1262664-bit addresses, the text and data segments must be less than 2GB in
12627size, both starting anywhere in memory (determined at link time). The
12628global register %g4 points to the base of the data segment. Programs
12629are statically linked and PIC is not supported.
12630
12631@item -mstack-bias
12632@itemx -mno-stack-bias
12633@opindex mstack-bias
12634@opindex mno-stack-bias
12635With @option{-mstack-bias}, GCC assumes that the stack pointer, and
12636frame pointer if present, are offset by @minus{}2047 which must be added back
12637when making stack frame references. This is the default in 64-bit mode.
12638Otherwise, assume no such offset is present.
12639@end table
12640
12641These switches are supported in addition to the above on Solaris:
12642
12643@table @gcctabopt
12644@item -threads
12645@opindex threads
12646Add support for multithreading using the Solaris threads library. This
12647option sets flags for both the preprocessor and linker. This option does
12648not affect the thread safety of object code produced by the compiler or
12649that of libraries supplied with it.
12650
12651@item -pthreads
12652@opindex pthreads
12653Add support for multithreading using the POSIX threads library. This
12654option sets flags for both the preprocessor and linker. This option does
12655not affect the thread safety of object code produced by the compiler or
12656that of libraries supplied with it.
12657
12658@item -pthread
12659@opindex pthread
12660This is a synonym for @option{-pthreads}.
12661@end table
12662
12663@node System V Options
12664@subsection Options for System V
12665
12666These additional options are available on System V Release 4 for
12667compatibility with other compilers on those systems:
12668
12669@table @gcctabopt
12670@item -G
12671@opindex G
12672Create a shared object.
12673It is recommended that @option{-symbolic} or @option{-shared} be used instead.
12674
12675@item -Qy
12676@opindex Qy
12677Identify the versions of each tool used by the compiler, in a
12678@code{.ident} assembler directive in the output.
12679
12680@item -Qn
12681@opindex Qn
12682Refrain from adding @code{.ident} directives to the output file (this is
12683the default).
12684
12685@item -YP,@var{dirs}
12686@opindex YP
12687Search the directories @var{dirs}, and no others, for libraries
12688specified with @option{-l}.
12689
12690@item -Ym,@var{dir}
12691@opindex Ym
12692Look in the directory @var{dir} to find the M4 preprocessor.
12693The assembler uses this option.
12694@c This is supposed to go with a -Yd for predefined M4 macro files, but
12695@c the generic assembler that comes with Solaris takes just -Ym.
12696@end table
12697
12698@node TMS320C3x/C4x Options
12699@subsection TMS320C3x/C4x Options
12700@cindex TMS320C3x/C4x Options
12701
12702These @samp{-m} options are defined for TMS320C3x/C4x implementations:
12703
12704@table @gcctabopt
12705
12706@item -mcpu=@var{cpu_type}
12707@opindex mcpu
12708Set the instruction set, register set, and instruction scheduling
12709parameters for machine type @var{cpu_type}. Supported values for
12710@var{cpu_type} are @samp{c30}, @samp{c31}, @samp{c32}, @samp{c40}, and
12711@samp{c44}. The default is @samp{c40} to generate code for the
12712TMS320C40.
12713
12714@item -mbig-memory
12715@itemx -mbig
12716@itemx -msmall-memory
12717@itemx -msmall
12718@opindex mbig-memory
12719@opindex mbig
12720@opindex msmall-memory
12721@opindex msmall
12722Generates code for the big or small memory model. The small memory
12723model assumed that all data fits into one 64K word page. At run-time
12724the data page (DP) register must be set to point to the 64K page
12725containing the .bss and .data program sections. The big memory model is
12726the default and requires reloading of the DP register for every direct
12727memory access.
12728
12729@item -mbk
12730@itemx -mno-bk
12731@opindex mbk
12732@opindex mno-bk
12733Allow (disallow) allocation of general integer operands into the block
12734count register BK@.
12735
12736@item -mdb
12737@itemx -mno-db
12738@opindex mdb
12739@opindex mno-db
12740Enable (disable) generation of code using decrement and branch,
12741DBcond(D), instructions. This is enabled by default for the C4x. To be
12742on the safe side, this is disabled for the C3x, since the maximum
12743iteration count on the C3x is @math{2^{23} + 1} (but who iterates loops more than
12744@math{2^{23}} times on the C3x?). Note that GCC will try to reverse a loop so
12745that it can utilize the decrement and branch instruction, but will give
12746up if there is more than one memory reference in the loop. Thus a loop
12747where the loop counter is decremented can generate slightly more
12748efficient code, in cases where the RPTB instruction cannot be utilized.
12749
12750@item -mdp-isr-reload
12751@itemx -mparanoid
12752@opindex mdp-isr-reload
12753@opindex mparanoid
12754Force the DP register to be saved on entry to an interrupt service
12755routine (ISR), reloaded to point to the data section, and restored on
12756exit from the ISR@. This should not be required unless someone has
12757violated the small memory model by modifying the DP register, say within
12758an object library.
12759
12760@item -mmpyi
12761@itemx -mno-mpyi
12762@opindex mmpyi
12763@opindex mno-mpyi
12764For the C3x use the 24-bit MPYI instruction for integer multiplies
12765instead of a library call to guarantee 32-bit results. Note that if one
12766of the operands is a constant, then the multiplication will be performed
12767using shifts and adds. If the @option{-mmpyi} option is not specified for the C3x,
12768then squaring operations are performed inline instead of a library call.
12769
12770@item -mfast-fix
12771@itemx -mno-fast-fix
12772@opindex mfast-fix
12773@opindex mno-fast-fix
12774The C3x/C4x FIX instruction to convert a floating point value to an
12775integer value chooses the nearest integer less than or equal to the
12776floating point value rather than to the nearest integer. Thus if the
12777floating point number is negative, the result will be incorrectly
12778truncated an additional code is necessary to detect and correct this
12779case. This option can be used to disable generation of the additional
12780code required to correct the result.
12781
12782@item -mrptb
12783@itemx -mno-rptb
12784@opindex mrptb
12785@opindex mno-rptb
12786Enable (disable) generation of repeat block sequences using the RPTB
12787instruction for zero overhead looping. The RPTB construct is only used
12788for innermost loops that do not call functions or jump across the loop
12789boundaries. There is no advantage having nested RPTB loops due to the
12790overhead required to save and restore the RC, RS, and RE registers.
12791This is enabled by default with @option{-O2}.
12792
12793@item -mrpts=@var{count}
12794@itemx -mno-rpts
12795@opindex mrpts
12796@opindex mno-rpts
12797Enable (disable) the use of the single instruction repeat instruction
12798RPTS@. If a repeat block contains a single instruction, and the loop
12799count can be guaranteed to be less than the value @var{count}, GCC will
12800emit a RPTS instruction instead of a RPTB@. If no value is specified,
12801then a RPTS will be emitted even if the loop count cannot be determined
12802at compile time. Note that the repeated instruction following RPTS does
12803not have to be reloaded from memory each iteration, thus freeing up the
12804CPU buses for operands. However, since interrupts are blocked by this
12805instruction, it is disabled by default.
12806
12807@item -mloop-unsigned
12808@itemx -mno-loop-unsigned
12809@opindex mloop-unsigned
12810@opindex mno-loop-unsigned
12811The maximum iteration count when using RPTS and RPTB (and DB on the C40)
12812is @math{2^{31} + 1} since these instructions test if the iteration count is
12813negative to terminate the loop. If the iteration count is unsigned
12814there is a possibility than the @math{2^{31} + 1} maximum iteration count may be
12815exceeded. This switch allows an unsigned iteration count.
12816
12817@item -mti
12818@opindex mti
12819Try to emit an assembler syntax that the TI assembler (asm30) is happy
12820with. This also enforces compatibility with the API employed by the TI
12821C3x C compiler. For example, long doubles are passed as structures
12822rather than in floating point registers.
12823
12824@item -mregparm
12825@itemx -mmemparm
12826@opindex mregparm
12827@opindex mmemparm
12828Generate code that uses registers (stack) for passing arguments to functions.
12829By default, arguments are passed in registers where possible rather
12830than by pushing arguments on to the stack.
12831
12832@item -mparallel-insns
12833@itemx -mno-parallel-insns
12834@opindex mparallel-insns
12835@opindex mno-parallel-insns
12836Allow the generation of parallel instructions. This is enabled by
12837default with @option{-O2}.
12838
12839@item -mparallel-mpy
12840@itemx -mno-parallel-mpy
12841@opindex mparallel-mpy
12842@opindex mno-parallel-mpy
12843Allow the generation of MPY||ADD and MPY||SUB parallel instructions,
12844provided @option{-mparallel-insns} is also specified. These instructions have
12845tight register constraints which can pessimize the code generation
12846of large functions.
12847
12848@end table
12849
12850@node V850 Options
12851@subsection V850 Options
12852@cindex V850 Options
12853
12854These @samp{-m} options are defined for V850 implementations:
12855
12856@table @gcctabopt
12857@item -mlong-calls
12858@itemx -mno-long-calls
12859@opindex mlong-calls
12860@opindex mno-long-calls
12861Treat all calls as being far away (near). If calls are assumed to be
12862far away, the compiler will always load the functions address up into a
12863register, and call indirect through the pointer.
12864
12865@item -mno-ep
12866@itemx -mep
12867@opindex mno-ep
12868@opindex mep
12869Do not optimize (do optimize) basic blocks that use the same index
12870pointer 4 or more times to copy pointer into the @code{ep} register, and
12871use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
12872option is on by default if you optimize.
12873
12874@item -mno-prolog-function
12875@itemx -mprolog-function
12876@opindex mno-prolog-function
12877@opindex mprolog-function
12878Do not use (do use) external functions to save and restore registers
12879at the prologue and epilogue of a function. The external functions
12880are slower, but use less code space if more than one function saves
12881the same number of registers. The @option{-mprolog-function} option
12882is on by default if you optimize.
12883
12884@item -mspace
12885@opindex mspace
12886Try to make the code as small as possible. At present, this just turns
12887on the @option{-mep} and @option{-mprolog-function} options.
12888
12889@item -mtda=@var{n}
12890@opindex mtda
12891Put static or global variables whose size is @var{n} bytes or less into
12892the tiny data area that register @code{ep} points to. The tiny data
12893area can hold up to 256 bytes in total (128 bytes for byte references).
12894
12895@item -msda=@var{n}
12896@opindex msda
12897Put static or global variables whose size is @var{n} bytes or less into
12898the small data area that register @code{gp} points to. The small data
12899area can hold up to 64 kilobytes.
12900
12901@item -mzda=@var{n}
12902@opindex mzda
12903Put static or global variables whose size is @var{n} bytes or less into
12904the first 32 kilobytes of memory.
12905
12906@item -mv850
12907@opindex mv850
12908Specify that the target processor is the V850.
12909
12910@item -mbig-switch
12911@opindex mbig-switch
12912Generate code suitable for big switch tables. Use this option only if
12913the assembler/linker complain about out of range branches within a switch
12914table.
12915
12916@item -mapp-regs
12917@opindex mapp-regs
12918This option will cause r2 and r5 to be used in the code generated by
12919the compiler. This setting is the default.
12920
12921@item -mno-app-regs
12922@opindex mno-app-regs
12923This option will cause r2 and r5 to be treated as fixed registers.
12924
12925@item -mv850e1
12926@opindex mv850e1
12927Specify that the target processor is the V850E1. The preprocessor
12928constants @samp{__v850e1__} and @samp{__v850e__} will be defined if
12929this option is used.
12930
12931@item -mv850e
12932@opindex mv850e
12933Specify that the target processor is the V850E@. The preprocessor
12934constant @samp{__v850e__} will be defined if this option is used.
12935
12936If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
12937are defined then a default target processor will be chosen and the
12938relevant @samp{__v850*__} preprocessor constant will be defined.
12939
12940The preprocessor constants @samp{__v850} and @samp{__v851__} are always
12941defined, regardless of which processor variant is the target.
12942
12943@item -mdisable-callt
12944@opindex mdisable-callt
12945This option will suppress generation of the CALLT instruction for the
12946v850e and v850e1 flavors of the v850 architecture. The default is
12947@option{-mno-disable-callt} which allows the CALLT instruction to be used.
12948
12949@end table
12950
12951@node VAX Options
12952@subsection VAX Options
12953@cindex VAX options
12954
12955These @samp{-m} options are defined for the VAX:
12956
12957@table @gcctabopt
12958@item -munix
12959@opindex munix
12960Do not output certain jump instructions (@code{aobleq} and so on)
12961that the Unix assembler for the VAX cannot handle across long
12962ranges.
12963
12964@item -mgnu
12965@opindex mgnu
12966Do output those jump instructions, on the assumption that you
12967will assemble with the GNU assembler.
12968
12969@item -mg
12970@opindex mg
12971Output code for g-format floating point numbers instead of d-format.
12972@end table
12973
12974@node x86-64 Options
12975@subsection x86-64 Options
12976@cindex x86-64 options
12977
12978These are listed under @xref{i386 and x86-64 Options}.
12979
12980@node Xstormy16 Options
12981@subsection Xstormy16 Options
12982@cindex Xstormy16 Options
12983
12984These options are defined for Xstormy16:
12985
12986@table @gcctabopt
12987@item -msim
12988@opindex msim
12989Choose startup files and linker script suitable for the simulator.
12990@end table
12991
12992@node Xtensa Options
12993@subsection Xtensa Options
12994@cindex Xtensa Options
12995
12996These options are supported for Xtensa targets:
12997
12998@table @gcctabopt
12999@item -mconst16
13000@itemx -mno-const16
13001@opindex mconst16
13002@opindex mno-const16
13003Enable or disable use of @code{CONST16} instructions for loading
13004constant values. The @code{CONST16} instruction is currently not a
13005standard option from Tensilica. When enabled, @code{CONST16}
13006instructions are always used in place of the standard @code{L32R}
13007instructions. The use of @code{CONST16} is enabled by default only if
13008the @code{L32R} instruction is not available.
13009
13010@item -mfused-madd
13011@itemx -mno-fused-madd
13012@opindex mfused-madd
13013@opindex mno-fused-madd
13014Enable or disable use of fused multiply/add and multiply/subtract
13015instructions in the floating-point option. This has no effect if the
13016floating-point option is not also enabled. Disabling fused multiply/add
13017and multiply/subtract instructions forces the compiler to use separate
13018instructions for the multiply and add/subtract operations. This may be
13019desirable in some cases where strict IEEE 754-compliant results are
13020required: the fused multiply add/subtract instructions do not round the
13021intermediate result, thereby producing results with @emph{more} bits of
13022precision than specified by the IEEE standard. Disabling fused multiply
13023add/subtract instructions also ensures that the program output is not
13024sensitive to the compiler's ability to combine multiply and add/subtract
13025operations.
13026
13027@item -mtext-section-literals
13028@itemx -mno-text-section-literals
13029@opindex mtext-section-literals
13030@opindex mno-text-section-literals
13031Control the treatment of literal pools. The default is
13032@option{-mno-text-section-literals}, which places literals in a separate
13033section in the output file. This allows the literal pool to be placed
13034in a data RAM/ROM, and it also allows the linker to combine literal
13035pools from separate object files to remove redundant literals and
13036improve code size. With @option{-mtext-section-literals}, the literals
13037are interspersed in the text section in order to keep them as close as
13038possible to their references. This may be necessary for large assembly
13039files.
13040
13041@item -mtarget-align
13042@itemx -mno-target-align
13043@opindex mtarget-align
13044@opindex mno-target-align
13045When this option is enabled, GCC instructs the assembler to
13046automatically align instructions to reduce branch penalties at the
13047expense of some code density. The assembler attempts to widen density
13048instructions to align branch targets and the instructions following call
13049instructions. If there are not enough preceding safe density
13050instructions to align a target, no widening will be performed. The
13051default is @option{-mtarget-align}. These options do not affect the
13052treatment of auto-aligned instructions like @code{LOOP}, which the
13053assembler will always align, either by widening density instructions or
13054by inserting no-op instructions.
13055
13056@item -mlongcalls
13057@itemx -mno-longcalls
13058@opindex mlongcalls
13059@opindex mno-longcalls
13060When this option is enabled, GCC instructs the assembler to translate
13061direct calls to indirect calls unless it can determine that the target
13062of a direct call is in the range allowed by the call instruction. This
13063translation typically occurs for calls to functions in other source
13064files. Specifically, the assembler translates a direct @code{CALL}
13065instruction into an @code{L32R} followed by a @code{CALLX} instruction.
13066The default is @option{-mno-longcalls}. This option should be used in
13067programs where the call target can potentially be out of range. This
13068option is implemented in the assembler, not the compiler, so the
13069assembly code generated by GCC will still show direct call
13070instructions---look at the disassembled object code to see the actual
13071instructions. Note that the assembler will use an indirect call for
13072every cross-file call, not just those that really will be out of range.
13073@end table
13074
13075@node zSeries Options
13076@subsection zSeries Options
13077@cindex zSeries options
13078
13079These are listed under @xref{S/390 and zSeries Options}.
13080
13081@node Code Gen Options
13082@section Options for Code Generation Conventions
13083@cindex code generation conventions
13084@cindex options, code generation
13085@cindex run-time options
13086
13087These machine-independent options control the interface conventions
13088used in code generation.
13089
13090Most of them have both positive and negative forms; the negative form
13091of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
13092one of the forms is listed---the one which is not the default. You
13093can figure out the other form by either removing @samp{no-} or adding
13094it.
13095
13096@table @gcctabopt
13097@item -fbounds-check
13098@opindex fbounds-check
13099For front-ends that support it, generate additional code to check that
13100indices used to access arrays are within the declared range. This is
13101currently only supported by the Java and Fortran front-ends, where
13102this option defaults to true and false respectively.
13103
13104@item -ftrapv
13105@opindex ftrapv
13106This option generates traps for signed overflow on addition, subtraction,
13107multiplication operations.
13108
13109@item -fwrapv
13110@opindex fwrapv
13111This option instructs the compiler to assume that signed arithmetic
13112overflow of addition, subtraction and multiplication wraps around
13113using twos-complement representation. This flag enables some optimizations
13114and disables others. This option is enabled by default for the Java
13115front-end, as required by the Java language specification.
13116
13117@item -fexceptions
13118@opindex fexceptions
13119Enable exception handling. Generates extra code needed to propagate
13120exceptions. For some targets, this implies GCC will generate frame
13121unwind information for all functions, which can produce significant data
13122size overhead, although it does not affect execution. If you do not
13123specify this option, GCC will enable it by default for languages like
13124C++ which normally require exception handling, and disable it for
13125languages like C that do not normally require it. However, you may need
13126to enable this option when compiling C code that needs to interoperate
13127properly with exception handlers written in C++. You may also wish to
13128disable this option if you are compiling older C++ programs that don't
13129use exception handling.
13130
13131@item -fnon-call-exceptions
13132@opindex fnon-call-exceptions
13133Generate code that allows trapping instructions to throw exceptions.
13134Note that this requires platform-specific runtime support that does
13135not exist everywhere. Moreover, it only allows @emph{trapping}
13136instructions to throw exceptions, i.e.@: memory references or floating
13137point instructions. It does not allow exceptions to be thrown from
13138arbitrary signal handlers such as @code{SIGALRM}.
13139
13140@item -funwind-tables
13141@opindex funwind-tables
13142Similar to @option{-fexceptions}, except that it will just generate any needed
13143static data, but will not affect the generated code in any other way.
13144You will normally not enable this option; instead, a language processor
13145that needs this handling would enable it on your behalf.
13146
13147@item -fasynchronous-unwind-tables
13148@opindex fasynchronous-unwind-tables
13149Generate unwind table in dwarf2 format, if supported by target machine. The
13150table is exact at each instruction boundary, so it can be used for stack
13151unwinding from asynchronous events (such as debugger or garbage collector).
13152
13153@item -fpcc-struct-return
13154@opindex fpcc-struct-return
13155Return ``short'' @code{struct} and @code{union} values in memory like
13156longer ones, rather than in registers. This convention is less
13157efficient, but it has the advantage of allowing intercallability between
13158GCC-compiled files and files compiled with other compilers, particularly
13159the Portable C Compiler (pcc).
13160
13161The precise convention for returning structures in memory depends
13162on the target configuration macros.
13163
13164Short structures and unions are those whose size and alignment match
13165that of some integer type.
13166
13167@strong{Warning:} code compiled with the @option{-fpcc-struct-return}
13168switch is not binary compatible with code compiled with the
13169@option{-freg-struct-return} switch.
13170Use it to conform to a non-default application binary interface.
13171
13172@item -freg-struct-return
13173@opindex freg-struct-return
13174Return @code{struct} and @code{union} values in registers when possible.
13175This is more efficient for small structures than
13176@option{-fpcc-struct-return}.
13177
13178If you specify neither @option{-fpcc-struct-return} nor
13179@option{-freg-struct-return}, GCC defaults to whichever convention is
13180standard for the target. If there is no standard convention, GCC
13181defaults to @option{-fpcc-struct-return}, except on targets where GCC is
13182the principal compiler. In those cases, we can choose the standard, and
13183we chose the more efficient register return alternative.
13184
13185@strong{Warning:} code compiled with the @option{-freg-struct-return}
13186switch is not binary compatible with code compiled with the
13187@option{-fpcc-struct-return} switch.
13188Use it to conform to a non-default application binary interface.
13189
13190@item -fshort-enums
13191@opindex fshort-enums
13192Allocate to an @code{enum} type only as many bytes as it needs for the
13193declared range of possible values. Specifically, the @code{enum} type
13194will be equivalent to the smallest integer type which has enough room.
13195
13196@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
13197code that is not binary compatible with code generated without that switch.
13198Use it to conform to a non-default application binary interface.
13199
13200@item -fshort-double
13201@opindex fshort-double
13202Use the same size for @code{double} as for @code{float}.
13203
13204@strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
13205code that is not binary compatible with code generated without that switch.
13206Use it to conform to a non-default application binary interface.
13207
13208@item -fshort-wchar
13209@opindex fshort-wchar
13210Override the underlying type for @samp{wchar_t} to be @samp{short
13211unsigned int} instead of the default for the target. This option is
13212useful for building programs to run under WINE@.
13213
13214@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
13215code that is not binary compatible with code generated without that switch.
13216Use it to conform to a non-default application binary interface.
13217
13218@item -fno-common
13219@opindex fno-common
13220In C, allocate even uninitialized global variables in the data section of the
13221object file, rather than generating them as common blocks. This has the
13222effect that if the same variable is declared (without @code{extern}) in
13223two different compilations, you will get an error when you link them.
13224The only reason this might be useful is if you wish to verify that the
13225program will work on other systems which always work this way.
13226
13227@item -fno-ident
13228@opindex fno-ident
13229Ignore the @samp{#ident} directive.
13230
13231@item -finhibit-size-directive
13232@opindex finhibit-size-directive
13233Don't output a @code{.size} assembler directive, or anything else that
13234would cause trouble if the function is split in the middle, and the
13235two halves are placed at locations far apart in memory. This option is
13236used when compiling @file{crtstuff.c}; you should not need to use it
13237for anything else.
13238
13239@item -fverbose-asm
13240@opindex fverbose-asm
13241Put extra commentary information in the generated assembly code to
13242make it more readable. This option is generally only of use to those
13243who actually need to read the generated assembly code (perhaps while
13244debugging the compiler itself).
13245
13246@option{-fno-verbose-asm}, the default, causes the
13247extra information to be omitted and is useful when comparing two assembler
13248files.
13249
13250@item -fpic
13251@opindex fpic
13252@cindex global offset table
13253@cindex PIC
13254Generate position-independent code (PIC) suitable for use in a shared
13255library, if supported for the target machine. Such code accesses all
13256constant addresses through a global offset table (GOT)@. The dynamic
13257loader resolves the GOT entries when the program starts (the dynamic
13258loader is not part of GCC; it is part of the operating system). If
13259the GOT size for the linked executable exceeds a machine-specific
13260maximum size, you get an error message from the linker indicating that
13261@option{-fpic} does not work; in that case, recompile with @option{-fPIC}
13262instead. (These maximums are 8k on the SPARC and 32k
13263on the m68k and RS/6000. The 386 has no such limit.)
13264
13265Position-independent code requires special support, and therefore works
13266only on certain machines. For the 386, GCC supports PIC for System V
13267but not for the Sun 386i. Code generated for the IBM RS/6000 is always
13268position-independent.
13269
13270When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13271are defined to 1.
13272
13273@item -fPIC
13274@opindex fPIC
13275If supported for the target machine, emit position-independent code,
13276suitable for dynamic linking and avoiding any limit on the size of the
13277global offset table. This option makes a difference on the m68k,
13278PowerPC and SPARC@.
13279
13280Position-independent code requires special support, and therefore works
13281only on certain machines.
13282
13283When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13284are defined to 2.
13285
13286@item -fpie
13287@itemx -fPIE
13288@opindex fpie
13289@opindex fPIE
13290These options are similar to @option{-fpic} and @option{-fPIC}, but
13291generated position independent code can be only linked into executables.
13292Usually these options are used when @option{-pie} GCC option will be
13293used during linking.
13294
13295@item -fno-jump-tables
13296@opindex fno-jump-tables
13297Do not use jump tables for switch statements even where it would be
13298more efficient than other code generation strategies. This option is
13299of use in conjunction with @option{-fpic} or @option{-fPIC} for
13300building code which forms part of a dynamic linker and cannot
13301reference the address of a jump table. On some targets, jump tables
13302do not require a GOT and this option is not needed.
13303
13304@item -ffixed-@var{reg}
13305@opindex ffixed
13306Treat the register named @var{reg} as a fixed register; generated code
13307should never refer to it (except perhaps as a stack pointer, frame
13308pointer or in some other fixed role).
13309
13310@var{reg} must be the name of a register. The register names accepted
13311are machine-specific and are defined in the @code{REGISTER_NAMES}
13312macro in the machine description macro file.
13313
13314This flag does not have a negative form, because it specifies a
13315three-way choice.
13316
13317@item -fcall-used-@var{reg}
13318@opindex fcall-used
13319Treat the register named @var{reg} as an allocable register that is
13320clobbered by function calls. It may be allocated for temporaries or
13321variables that do not live across a call. Functions compiled this way
13322will not save and restore the register @var{reg}.
13323
13324It is an error to used this flag with the frame pointer or stack pointer.
13325Use of this flag for other registers that have fixed pervasive roles in
13326the machine's execution model will produce disastrous results.
13327
13328This flag does not have a negative form, because it specifies a
13329three-way choice.
13330
13331@item -fcall-saved-@var{reg}
13332@opindex fcall-saved
13333Treat the register named @var{reg} as an allocable register saved by
13334functions. It may be allocated even for temporaries or variables that
13335live across a call. Functions compiled this way will save and restore
13336the register @var{reg} if they use it.
13337
13338It is an error to used this flag with the frame pointer or stack pointer.
13339Use of this flag for other registers that have fixed pervasive roles in
13340the machine's execution model will produce disastrous results.
13341
13342A different sort of disaster will result from the use of this flag for
13343a register in which function values may be returned.
13344
13345This flag does not have a negative form, because it specifies a
13346three-way choice.
13347
13348@item -fpack-struct[=@var{n}]
13349@opindex fpack-struct
13350Without a value specified, pack all structure members together without
13351holes. When a value is specified (which must be a small power of two), pack
13352structure members according to this value, representing the maximum
13353alignment (that is, objects with default alignment requirements larger than
13354this will be output potentially unaligned at the next fitting location.
13355
13356@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
13357code that is not binary compatible with code generated without that switch.
13358Additionally, it makes the code suboptimal.
13359Use it to conform to a non-default application binary interface.
13360
13361@item -finstrument-functions
13362@opindex finstrument-functions
13363Generate instrumentation calls for entry and exit to functions. Just
13364after function entry and just before function exit, the following
13365profiling functions will be called with the address of the current
13366function and its call site. (On some platforms,
13367@code{__builtin_return_address} does not work beyond the current
13368function, so the call site information may not be available to the
13369profiling functions otherwise.)
13370
13371@smallexample
13372void __cyg_profile_func_enter (void *this_fn,
13373 void *call_site);
13374void __cyg_profile_func_exit (void *this_fn,
13375 void *call_site);
13376@end smallexample
13377
13378The first argument is the address of the start of the current function,
13379which may be looked up exactly in the symbol table.
13380
13381This instrumentation is also done for functions expanded inline in other
13382functions. The profiling calls will indicate where, conceptually, the
13383inline function is entered and exited. This means that addressable
13384versions of such functions must be available. If all your uses of a
13385function are expanded inline, this may mean an additional expansion of
13386code size. If you use @samp{extern inline} in your C code, an
13387addressable version of such functions must be provided. (This is
13388normally the case anyways, but if you get lucky and the optimizer always
13389expands the functions inline, you might have gotten away without
13390providing static copies.)
13391
13392A function may be given the attribute @code{no_instrument_function}, in
13393which case this instrumentation will not be done. This can be used, for
13394example, for the profiling functions listed above, high-priority
13395interrupt routines, and any functions from which the profiling functions
13396cannot safely be called (perhaps signal handlers, if the profiling
13397routines generate output or allocate memory).
13398
13399@item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}
13400@opindex finstrument-functions-exclude-file-list
13401
13402Set the list of functions that are excluded from instrumentation (see
13403the description of @code{-finstrument-functions}). If the file that
13404contains a function definition matches with one of @var{file}, then
13405that function is not instrumented. The match is done on substrings:
13406if the @var{file} parameter is a substring of the file name, it is
13407considered to be a match.
13408
13409For example,
13410@code{-finstrument-functions-exclude-file-list=/bits/stl,include/sys}
13411will exclude any inline function defined in files whose pathnames
13412contain @code{/bits/stl} or @code{include/sys}.
13413
13414If, for some reason, you want to include letter @code{','} in one of
13415@var{sym}, write @code{'\,'}. For example,
13416@code{-finstrument-functions-exclude-file-list='\,\,tmp'}
13417(note the single quote surrounding the option).
13418
13419@item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{}
13420@opindex finstrument-functions-exclude-function-list
13421
13422This is similar to @code{-finstrument-functions-exclude-file-list},
13423but this option sets the list of function names to be excluded from
13424instrumentation. The function name to be matched is its user-visible
13425name, such as @code{vector<int> blah(const vector<int> &)}, not the
13426internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The
13427match is done on substrings: if the @var{sym} parameter is a substring
13428of the function name, it is considered to be a match.
13429
13430@item -fstack-check
13431@opindex fstack-check
13432Generate code to verify that you do not go beyond the boundary of the
13433stack. You should specify this flag if you are running in an
13434environment with multiple threads, but only rarely need to specify it in
13435a single-threaded environment since stack overflow is automatically
13436detected on nearly all systems if there is only one stack.
13437
13438Note that this switch does not actually cause checking to be done; the
13439operating system must do that. The switch causes generation of code
13440to ensure that the operating system sees the stack being extended.
13441
13442@item -fstack-limit-register=@var{reg}
13443@itemx -fstack-limit-symbol=@var{sym}
13444@itemx -fno-stack-limit
13445@opindex fstack-limit-register
13446@opindex fstack-limit-symbol
13447@opindex fno-stack-limit
13448Generate code to ensure that the stack does not grow beyond a certain value,
13449either the value of a register or the address of a symbol. If the stack
13450would grow beyond the value, a signal is raised. For most targets,
13451the signal is raised before the stack overruns the boundary, so
13452it is possible to catch the signal without taking special precautions.
13453
13454For instance, if the stack starts at absolute address @samp{0x80000000}
13455and grows downwards, you can use the flags
13456@option{-fstack-limit-symbol=__stack_limit} and
13457@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
13458of 128KB@. Note that this may only work with the GNU linker.
13459
13460@cindex aliasing of parameters
13461@cindex parameters, aliased
13462@item -fargument-alias
13463@itemx -fargument-noalias
13464@itemx -fargument-noalias-global
13465@itemx -fargument-noalias-anything
13466@opindex fargument-alias
13467@opindex fargument-noalias
13468@opindex fargument-noalias-global
13469@opindex fargument-noalias-anything
13470Specify the possible relationships among parameters and between
13471parameters and global data.
13472
13473@option{-fargument-alias} specifies that arguments (parameters) may
13474alias each other and may alias global storage.@*
13475@option{-fargument-noalias} specifies that arguments do not alias
13476each other, but may alias global storage.@*
13477@option{-fargument-noalias-global} specifies that arguments do not
13478alias each other and do not alias global storage.
13479@option{-fargument-noalias-anything} specifies that arguments do not
13480alias any other storage.
13481
13482Each language will automatically use whatever option is required by
13483the language standard. You should not need to use these options yourself.
13484
13485@item -fleading-underscore
13486@opindex fleading-underscore
13487This option and its counterpart, @option{-fno-leading-underscore}, forcibly
13488change the way C symbols are represented in the object file. One use
13489is to help link with legacy assembly code.
13490
13491@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
13492generate code that is not binary compatible with code generated without that
13493switch. Use it to conform to a non-default application binary interface.
13494Not all targets provide complete support for this switch.
13495
13496@item -ftls-model=@var{model}
13497Alter the thread-local storage model to be used (@pxref{Thread-Local}).
13498The @var{model} argument should be one of @code{global-dynamic},
13499@code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
13500
13501The default without @option{-fpic} is @code{initial-exec}; with
13502@option{-fpic} the default is @code{global-dynamic}.
13503
13504@item -fvisibility=@var{default|internal|hidden|protected}
13505@opindex fvisibility
13506Set the default ELF image symbol visibility to the specified option---all
13507symbols will be marked with this unless overridden within the code.
13508Using this feature can very substantially improve linking and
13509load times of shared object libraries, produce more optimized
13510code, provide near-perfect API export and prevent symbol clashes.
13511It is @strong{strongly} recommended that you use this in any shared objects
13512you distribute.
13513
13514Despite the nomenclature, @code{default} always means public ie;
13515available to be linked against from outside the shared object.
13516@code{protected} and @code{internal} are pretty useless in real-world
13517usage so the only other commonly used option will be @code{hidden}.
13518The default if @option{-fvisibility} isn't specified is
13519@code{default}, i.e., make every
13520symbol public---this causes the same behavior as previous versions of
13521GCC@.
13522
13523A good explanation of the benefits offered by ensuring ELF
13524symbols have the correct visibility is given by ``How To Write
13525Shared Libraries'' by Ulrich Drepper (which can be found at
13526@w{@uref{http://people.redhat.com/~drepper/}})---however a superior
13527solution made possible by this option to marking things hidden when
13528the default is public is to make the default hidden and mark things
13529public. This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
13530and @code{__attribute__ ((visibility("default")))} instead of
13531@code{__declspec(dllexport)} you get almost identical semantics with
13532identical syntax. This is a great boon to those working with
13533cross-platform projects.
13534
13535For those adding visibility support to existing code, you may find
13536@samp{#pragma GCC visibility} of use. This works by you enclosing
13537the declarations you wish to set visibility for with (for example)
13538@samp{#pragma GCC visibility push(hidden)} and
13539@samp{#pragma GCC visibility pop}.
13540Bear in mind that symbol visibility should be viewed @strong{as
13541part of the API interface contract} and thus all new code should
13542always specify visibility when it is not the default ie; declarations
13543only for use within the local DSO should @strong{always} be marked explicitly
13544as hidden as so to avoid PLT indirection overheads---making this
13545abundantly clear also aids readability and self-documentation of the code.
13546Note that due to ISO C++ specification requirements, operator new and
13547operator delete must always be of default visibility.
13548
13549Be aware that headers from outside your project, in particular system
13550headers and headers from any other library you use, may not be
13551expecting to be compiled with visibility other than the default. You
13552may need to explicitly say @samp{#pragma GCC visibility push(default)}
13553before including any such headers.
13554
13555@samp{extern} declarations are not affected by @samp{-fvisibility}, so
13556a lot of code can be recompiled with @samp{-fvisibility=hidden} with
13557no modifications. However, this means that calls to @samp{extern}
13558functions with no explicit visibility will use the PLT, so it is more
13559effective to use @samp{__attribute ((visibility))} and/or
13560@samp{#pragma GCC visibility} to tell the compiler which @samp{extern}
13561declarations should be treated as hidden.
13562
13563Note that @samp{-fvisibility} does affect C++ vague linkage
13564entities. This means that, for instance, an exception class that will
13565be thrown between DSOs must be explicitly marked with default
13566visibility so that the @samp{type_info} nodes will be unified between
13567the DSOs.
13568
13569An overview of these techniques, their benefits and how to use them
13570is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
13571
13572@end table
13573
13574@c man end
13575
13576@node Environment Variables
13577@section Environment Variables Affecting GCC
13578@cindex environment variables
13579
13580@c man begin ENVIRONMENT
13581This section describes several environment variables that affect how GCC
13582operates. Some of them work by specifying directories or prefixes to use
13583when searching for various kinds of files. Some are used to specify other
13584aspects of the compilation environment.
13585
13586Note that you can also specify places to search using options such as
13587@option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
13588take precedence over places specified using environment variables, which
13589in turn take precedence over those specified by the configuration of GCC@.
13590@xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
13591GNU Compiler Collection (GCC) Internals}.
13592
13593@table @env
13594@item LANG
13595@itemx LC_CTYPE
13596@c @itemx LC_COLLATE
13597@itemx LC_MESSAGES
13598@c @itemx LC_MONETARY
13599@c @itemx LC_NUMERIC
13600@c @itemx LC_TIME
13601@itemx LC_ALL
13602@findex LANG
13603@findex LC_CTYPE
13604@c @findex LC_COLLATE
13605@findex LC_MESSAGES
13606@c @findex LC_MONETARY
13607@c @findex LC_NUMERIC
13608@c @findex LC_TIME
13609@findex LC_ALL
13610@cindex locale
13611These environment variables control the way that GCC uses
13612localization information that allow GCC to work with different
13613national conventions. GCC inspects the locale categories
13614@env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
13615so. These locale categories can be set to any value supported by your
13616installation. A typical value is @samp{en_GB.UTF-8} for English in the United
13617Kingdom encoded in UTF-8.
13618
13619The @env{LC_CTYPE} environment variable specifies character
13620classification. GCC uses it to determine the character boundaries in
13621a string; this is needed for some multibyte encodings that contain quote
13622and escape characters that would otherwise be interpreted as a string
13623end or escape.
13624
13625The @env{LC_MESSAGES} environment variable specifies the language to
13626use in diagnostic messages.
13627
13628If the @env{LC_ALL} environment variable is set, it overrides the value
13629of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
13630and @env{LC_MESSAGES} default to the value of the @env{LANG}
13631environment variable. If none of these variables are set, GCC
13632defaults to traditional C English behavior.
13633
13634@item TMPDIR
13635@findex TMPDIR
13636If @env{TMPDIR} is set, it specifies the directory to use for temporary
13637files. GCC uses temporary files to hold the output of one stage of
13638compilation which is to be used as input to the next stage: for example,
13639the output of the preprocessor, which is the input to the compiler
13640proper.
13641
13642@item GCC_EXEC_PREFIX
13643@findex GCC_EXEC_PREFIX
13644If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
13645names of the subprograms executed by the compiler. No slash is added
13646when this prefix is combined with the name of a subprogram, but you can
13647specify a prefix that ends with a slash if you wish.
13648
13649If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
13650an appropriate prefix to use based on the pathname it was invoked with.
13651
13652If GCC cannot find the subprogram using the specified prefix, it
13653tries looking in the usual places for the subprogram.
13654
13655The default value of @env{GCC_EXEC_PREFIX} is
13656@file{@var{prefix}/lib/gcc/} where @var{prefix} is the value
13657of @code{prefix} when you ran the @file{configure} script.
13658
13659Other prefixes specified with @option{-B} take precedence over this prefix.
13660
13661This prefix is also used for finding files such as @file{crt0.o} that are
13662used for linking.
13663
13664In addition, the prefix is used in an unusual way in finding the
13665directories to search for header files. For each of the standard
13666directories whose name normally begins with @samp{/usr/local/lib/gcc}
13667(more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
13668replacing that beginning with the specified prefix to produce an
13669alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
13670@file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
13671These alternate directories are searched first; the standard directories
13672come next.
13673
13674@item COMPILER_PATH
13675@findex COMPILER_PATH
13676The value of @env{COMPILER_PATH} is a colon-separated list of
13677directories, much like @env{PATH}. GCC tries the directories thus
13678specified when searching for subprograms, if it can't find the
13679subprograms using @env{GCC_EXEC_PREFIX}.
13680
13681@item LIBRARY_PATH
13682@findex LIBRARY_PATH
13683The value of @env{LIBRARY_PATH} is a colon-separated list of
13684directories, much like @env{PATH}. When configured as a native compiler,
13685GCC tries the directories thus specified when searching for special
13686linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking
13687using GCC also uses these directories when searching for ordinary
13688libraries for the @option{-l} option (but directories specified with
13689@option{-L} come first).
13690
13691@item LANG
13692@findex LANG
13693@cindex locale definition
13694This variable is used to pass locale information to the compiler. One way in
13695which this information is used is to determine the character set to be used
13696when character literals, string literals and comments are parsed in C and C++.
13697When the compiler is configured to allow multibyte characters,
13698the following values for @env{LANG} are recognized:
13699
13700@table @samp
13701@item C-JIS
13702Recognize JIS characters.
13703@item C-SJIS
13704Recognize SJIS characters.
13705@item C-EUCJP
13706Recognize EUCJP characters.
13707@end table
13708
13709If @env{LANG} is not defined, or if it has some other value, then the
13710compiler will use mblen and mbtowc as defined by the default locale to
13711recognize and translate multibyte characters.
13712@end table
13713
13714@noindent
13715Some additional environments variables affect the behavior of the
13716preprocessor.
13717
13718@include cppenv.texi
13719
13720@c man end
13721
13722@node Precompiled Headers
13723@section Using Precompiled Headers
13724@cindex precompiled headers
13725@cindex speed of compilation
13726
13727Often large projects have many header files that are included in every
13728source file. The time the compiler takes to process these header files
13729over and over again can account for nearly all of the time required to
13730build the project. To make builds faster, GCC allows users to
13731`precompile' a header file; then, if builds can use the precompiled
13732header file they will be much faster.
13733
13734To create a precompiled header file, simply compile it as you would any
13735other file, if necessary using the @option{-x} option to make the driver
13736treat it as a C or C++ header file. You will probably want to use a
13737tool like @command{make} to keep the precompiled header up-to-date when
13738the headers it contains change.
13739
13740A precompiled header file will be searched for when @code{#include} is
13741seen in the compilation. As it searches for the included file
13742(@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
13743compiler looks for a precompiled header in each directory just before it
13744looks for the include file in that directory. The name searched for is
13745the name specified in the @code{#include} with @samp{.gch} appended. If
13746the precompiled header file can't be used, it is ignored.
13747
13748For instance, if you have @code{#include "all.h"}, and you have
13749@file{all.h.gch} in the same directory as @file{all.h}, then the
13750precompiled header file will be used if possible, and the original
13751header will be used otherwise.
13752
13753Alternatively, you might decide to put the precompiled header file in a
13754directory and use @option{-I} to ensure that directory is searched
13755before (or instead of) the directory containing the original header.
13756Then, if you want to check that the precompiled header file is always
13757used, you can put a file of the same name as the original header in this
13758directory containing an @code{#error} command.
13759
13760This also works with @option{-include}. So yet another way to use
13761precompiled headers, good for projects not designed with precompiled
13762header files in mind, is to simply take most of the header files used by
13763a project, include them from another header file, precompile that header
13764file, and @option{-include} the precompiled header. If the header files
13765have guards against multiple inclusion, they will be skipped because
13766they've already been included (in the precompiled header).
13767
13768If you need to precompile the same header file for different
13769languages, targets, or compiler options, you can instead make a
13770@emph{directory} named like @file{all.h.gch}, and put each precompiled
13771header in the directory, perhaps using @option{-o}. It doesn't matter
13772what you call the files in the directory, every precompiled header in
13773the directory will be considered. The first precompiled header
13774encountered in the directory that is valid for this compilation will
13775be used; they're searched in no particular order.
13776
13777There are many other possibilities, limited only by your imagination,
13778good sense, and the constraints of your build system.
13779
13780A precompiled header file can be used only when these conditions apply:
13781
13782@itemize
13783@item
13784Only one precompiled header can be used in a particular compilation.
13785
13786@item
13787A precompiled header can't be used once the first C token is seen. You
13788can have preprocessor directives before a precompiled header; you can
13789even include a precompiled header from inside another header, so long as
13790there are no C tokens before the @code{#include}.
13791
13792@item
13793The precompiled header file must be produced for the same language as
13794the current compilation. You can't use a C precompiled header for a C++
13795compilation.
13796
13797@item
13798The precompiled header file must have been produced by the same compiler
13799binary as the current compilation is using.
13800
13801@item
13802Any macros defined before the precompiled header is included must
13803either be defined in the same way as when the precompiled header was
13804generated, or must not affect the precompiled header, which usually
13805means that they don't appear in the precompiled header at all.
13806
13807The @option{-D} option is one way to define a macro before a
13808precompiled header is included; using a @code{#define} can also do it.
13809There are also some options that define macros implicitly, like
13810@option{-O} and @option{-Wdeprecated}; the same rule applies to macros
13811defined this way.
13812
13813@item If debugging information is output when using the precompiled
13814header, using @option{-g} or similar, the same kind of debugging information
13815must have been output when building the precompiled header. However,
13816a precompiled header built using @option{-g} can be used in a compilation
13817when no debugging information is being output.
13818
13819@item The same @option{-m} options must generally be used when building
13820and using the precompiled header. @xref{Submodel Options},
13821for any cases where this rule is relaxed.
13822
13823@item Each of the following options must be the same when building and using
13824the precompiled header:
13825
13826@gccoptlist{-fexceptions -funit-at-a-time}
13827
13828@item
13829Some other command-line options starting with @option{-f},
13830@option{-p}, or @option{-O} must be defined in the same way as when
13831the precompiled header was generated. At present, it's not clear
13832which options are safe to change and which are not; the safest choice
13833is to use exactly the same options when generating and using the
13834precompiled header. The following are known to be safe:
13835
13836@gccoptlist{-fmessage-length= -fpreprocessed
13837-fsched-interblock -fsched-spec -fsched-spec-load -fsched-spec-load-dangerous
13838-fsched-verbose=<number> -fschedule-insns -fvisibility=
13839-pedantic-errors}
13840
13841@end itemize
13842
13843For all of these except the last, the compiler will automatically
13844ignore the precompiled header if the conditions aren't met. If you
13845find an option combination that doesn't work and doesn't cause the
13846precompiled header to be ignored, please consider filing a bug report,
13847see @ref{Bugs}.
13848
13849If you do use differing options when generating and using the
13850precompiled header, the actual behavior will be a mixture of the
13851behavior for the options. For instance, if you use @option{-g} to
13852generate the precompiled header but not when using it, you may or may
13853not get debugging information for routines in the precompiled header.
13854
13855@node Running Protoize
13856@section Running Protoize
13857
13858The program @code{protoize} is an optional part of GCC@. You can use
13859it to add prototypes to a program, thus converting the program to ISO
13860C in one respect. The companion program @code{unprotoize} does the
13861reverse: it removes argument types from any prototypes that are found.
13862
13863When you run these programs, you must specify a set of source files as
13864command line arguments. The conversion programs start out by compiling
13865these files to see what functions they define. The information gathered
13866about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
13867
13868After scanning comes actual conversion. The specified files are all
13869eligible to be converted; any files they include (whether sources or
13870just headers) are eligible as well.
13871
13872But not all the eligible files are converted. By default,
13873@code{protoize} and @code{unprotoize} convert only source and header
13874files in the current directory. You can specify additional directories
13875whose files should be converted with the @option{-d @var{directory}}
13876option. You can also specify particular files to exclude with the
13877@option{-x @var{file}} option. A file is converted if it is eligible, its
13878directory name matches one of the specified directory names, and its
13879name within the directory has not been excluded.
13880
13881Basic conversion with @code{protoize} consists of rewriting most
13882function definitions and function declarations to specify the types of
13883the arguments. The only ones not rewritten are those for varargs
13884functions.
13885
13886@code{protoize} optionally inserts prototype declarations at the
13887beginning of the source file, to make them available for any calls that
13888precede the function's definition. Or it can insert prototype
13889declarations with block scope in the blocks where undeclared functions
13890are called.
13891
13892Basic conversion with @code{unprotoize} consists of rewriting most
13893function declarations to remove any argument types, and rewriting
13894function definitions to the old-style pre-ISO form.
13895
13896Both conversion programs print a warning for any function declaration or
13897definition that they can't convert. You can suppress these warnings
13898with @option{-q}.
13899
13900The output from @code{protoize} or @code{unprotoize} replaces the
13901original source file. The original file is renamed to a name ending
13902with @samp{.save} (for DOS, the saved filename ends in @samp{.sav}
13903without the original @samp{.c} suffix). If the @samp{.save} (@samp{.sav}
13904for DOS) file already exists, then the source file is simply discarded.
13905
13906@code{protoize} and @code{unprotoize} both depend on GCC itself to
13907scan the program and collect information about the functions it uses.
13908So neither of these programs will work until GCC is installed.
13909
13910Here is a table of the options you can use with @code{protoize} and
13911@code{unprotoize}. Each option works with both programs unless
13912otherwise stated.
13913
13914@table @code
13915@item -B @var{directory}
13916Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
13917usual directory (normally @file{/usr/local/lib}). This file contains
13918prototype information about standard system functions. This option
13919applies only to @code{protoize}.
13920
13921@item -c @var{compilation-options}
13922Use @var{compilation-options} as the options when running @command{gcc} to
13923produce the @samp{.X} files. The special option @option{-aux-info} is
13924always passed in addition, to tell @command{gcc} to write a @samp{.X} file.
13925
13926Note that the compilation options must be given as a single argument to
13927@code{protoize} or @code{unprotoize}. If you want to specify several
13928@command{gcc} options, you must quote the entire set of compilation options
13929to make them a single word in the shell.
13930
13931There are certain @command{gcc} arguments that you cannot use, because they
13932would produce the wrong kind of output. These include @option{-g},
13933@option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in
13934the @var{compilation-options}, they are ignored.
13935
13936@item -C
13937Rename files to end in @samp{.C} (@samp{.cc} for DOS-based file
13938systems) instead of @samp{.c}. This is convenient if you are converting
13939a C program to C++. This option applies only to @code{protoize}.
13940
13941@item -g
13942Add explicit global declarations. This means inserting explicit
13943declarations at the beginning of each source file for each function
13944that is called in the file and was not declared. These declarations
13945precede the first function definition that contains a call to an
13946undeclared function. This option applies only to @code{protoize}.
13947
13948@item -i @var{string}
13949Indent old-style parameter declarations with the string @var{string}.
13950This option applies only to @code{protoize}.
13951
13952@code{unprotoize} converts prototyped function definitions to old-style
13953function definitions, where the arguments are declared between the
13954argument list and the initial @samp{@{}. By default, @code{unprotoize}
13955uses five spaces as the indentation. If you want to indent with just
13956one space instead, use @option{-i " "}.
13957
13958@item -k
13959Keep the @samp{.X} files. Normally, they are deleted after conversion
13960is finished.
13961
13962@item -l
13963Add explicit local declarations. @code{protoize} with @option{-l} inserts
13964a prototype declaration for each function in each block which calls the
13965function without any declaration. This option applies only to
13966@code{protoize}.
13967
13968@item -n
13969Make no real changes. This mode just prints information about the conversions
13970that would have been done without @option{-n}.
13971
13972@item -N
13973Make no @samp{.save} files. The original files are simply deleted.
13974Use this option with caution.
13975
13976@item -p @var{program}
13977Use the program @var{program} as the compiler. Normally, the name
13978@file{gcc} is used.
13979
13980@item -q
13981Work quietly. Most warnings are suppressed.
13982
13983@item -v
13984Print the version number, just like @option{-v} for @command{gcc}.
13985@end table
13986
13987If you need special compiler options to compile one of your program's
13988source files, then you should generate that file's @samp{.X} file
13989specially, by running @command{gcc} on that source file with the
13990appropriate options and the option @option{-aux-info}. Then run
13991@code{protoize} on the entire set of files. @code{protoize} will use
13992the existing @samp{.X} file because it is newer than the source file.
13993For example:
13994
13995@smallexample
13996gcc -Dfoo=bar file1.c -aux-info file1.X
13997protoize *.c
13998@end smallexample
13999
14000@noindent
14001You need to include the special files along with the rest in the
14002@code{protoize} command, even though their @samp{.X} files already
14003exist, because otherwise they won't get converted.
14004
14005@xref{Protoize Caveats}, for more information on how to use
14006@code{protoize} successfully.
14007