1@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2@c 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
3@c This is part of the GCC manual.
4@c For copying conditions, see the file gcc.texi.
5
6@ignore
7@c man begin INCLUDE
8@include gcc-vers.texi
9@c man end
10
11@c man begin COPYRIGHT
12Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
131999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
14
15Permission is granted to copy, distribute and/or modify this document
16under the terms of the GNU Free Documentation License, Version 1.2 or
17any later version published by the Free Software Foundation; with the
18Invariant Sections being ``GNU General Public License'' and ``Funding
19Free Software'', the Front-Cover texts being (a) (see below), and with
20the Back-Cover Texts being (b) (see below). A copy of the license is
21included in the gfdl(7) man page.
22
23(a) The FSF's Front-Cover Text is:
24
25 A GNU Manual
26
27(b) The FSF's Back-Cover Text is:
28
29 You have freedom to copy and modify this GNU Manual, like GNU
30 software. Copies published by the Free Software Foundation raise
31 funds for GNU development.
32@c man end
33@c Set file name and title for the man page.
34@setfilename gcc
35@settitle GNU project C and C++ compiler
36@c man begin SYNOPSIS
37gcc [@option{-c}|@option{-S}|@option{-E}] [@option{-std=}@var{standard}]
38 [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
39 [@option{-W}@var{warn}@dots{}] [@option{-pedantic}]
40 [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
41 [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
42 [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
43 [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}
44
45Only the most useful options are listed here; see below for the
46remainder. @samp{g++} accepts mostly the same options as @samp{gcc}.
47@c man end
48@c man begin SEEALSO
49gpl(7), gfdl(7), fsf-funding(7),
50cpp(1), gcov(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1)
51and the Info entries for @file{gcc}, @file{cpp}, @file{as},
52@file{ld}, @file{binutils} and @file{gdb}.
53@c man end
54@c man begin BUGS
55For instructions on reporting bugs, see
56@w{@uref{http://gcc.gnu.org/bugs.html}}.
57@c man end
58@c man begin AUTHOR
59See the Info entry for @command{gcc}, or
60@w{@uref{http://gcc.gnu.org/onlinedocs/gcc/Contributors.html}},
61for contributors to GCC@.
62@c man end
63@end ignore
64
65@node Invoking GCC
66@chapter GCC Command Options
67@cindex GCC command options
68@cindex command options
69@cindex options, GCC command
70
71@c man begin DESCRIPTION
72When you invoke GCC, it normally does preprocessing, compilation,
73assembly and linking. The ``overall options'' allow you to stop this
74process at an intermediate stage. For example, the @option{-c} option
75says not to run the linker. Then the output consists of object files
76output by the assembler.
77
78Other options are passed on to one stage of processing. Some options
79control the preprocessor and others the compiler itself. Yet other
80options control the assembler and linker; most of these are not
81documented here, since you rarely need to use any of them.
82
83@cindex C compilation options
84Most of the command line options that you can use with GCC are useful
85for C programs; when an option is only useful with another language
86(usually C++), the explanation says so explicitly. If the description
87for a particular option does not mention a source language, you can use
88that option with all supported languages.
89
90@cindex C++ compilation options
91@xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
92options for compiling C++ programs.
93
94@cindex grouping options
95@cindex options, grouping
96The @command{gcc} program accepts options and file names as operands. Many
97options have multi-letter names; therefore multiple single-letter options
98may @emph{not} be grouped: @option{-dr} is very different from @w{@samp{-d
99-r}}.
100
101@cindex order of options
102@cindex options, order
103You can mix options and other arguments. For the most part, the order
104you use doesn't matter. Order does matter when you use several options
105of the same kind; for example, if you specify @option{-L} more than once,
106the directories are searched in the order specified.
107
108Many options have long names starting with @samp{-f} or with
109@samp{-W}---for example,
110@option{-fmove-loop-invariants}, @option{-Wformat} and so on. Most of
111these have both positive and negative forms; the negative form of
112@option{-ffoo} would be @option{-fno-foo}. This manual documents
113only one of these two forms, whichever one is not the default.
114
115@c man end
116
117@xref{Option Index}, for an index to GCC's options.
118
119@menu
120* Option Summary:: Brief list of all options, without explanations.
121* Overall Options:: Controlling the kind of output:
122 an executable, object files, assembler files,
123 or preprocessed source.
124* Invoking G++:: Compiling C++ programs.
125* C Dialect Options:: Controlling the variant of C language compiled.
126* C++ Dialect Options:: Variations on C++.
127* Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
128 and Objective-C++.
129* Language Independent Options:: Controlling how diagnostics should be
130 formatted.
131* Warning Options:: How picky should the compiler be?
132* Debugging Options:: Symbol tables, measurements, and debugging dumps.
133* Optimize Options:: How much optimization?
134* Preprocessor Options:: Controlling header files and macro definitions.
135 Also, getting dependency information for Make.
136* Assembler Options:: Passing options to the assembler.
137* Link Options:: Specifying libraries and so on.
138* Directory Options:: Where to find header files and libraries.
139 Where to find the compiler executable files.
140* Spec Files:: How to pass switches to sub-processes.
141* Target Options:: Running a cross-compiler, or an old version of GCC.
142* Submodel Options:: Specifying minor hardware or convention variations,
143 such as 68010 vs 68020.
144* Code Gen Options:: Specifying conventions for function calls, data layout
145 and register usage.
146* Environment Variables:: Env vars that affect GCC.
147* Precompiled Headers:: Compiling a header once, and using it many times.
148* Running Protoize:: Automatically adding or removing function prototypes.
149@end menu
150
151@c man begin OPTIONS
152
153@node Option Summary
154@section Option Summary
155
156Here is a summary of all the options, grouped by type. Explanations are
157in the following sections.
158
159@table @emph
160@item Overall Options
161@xref{Overall Options,,Options Controlling the Kind of Output}.
162@gccoptlist{-c -S -E -o @var{file} -combine -pipe -pass-exit-codes @gol
163-x @var{language} -v -### --help --target-help --version @@@var{file}}
164
165@item C Language Options
166@xref{C Dialect Options,,Options Controlling C Dialect}.
167@gccoptlist{-ansi -std=@var{standard} -fgnu89-inline @gol
168-aux-info @var{filename} @gol
169-fno-asm -fno-builtin -fno-builtin-@var{function} @gol
170-fhosted -ffreestanding -fopenmp -fms-extensions @gol
171-trigraphs -no-integrated-cpp -traditional -traditional-cpp @gol
172-fallow-single-precision -fcond-mismatch @gol
173-fsigned-bitfields -fsigned-char @gol
174-funsigned-bitfields -funsigned-char}
175
176@item C++ Language Options
177@xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
178@gccoptlist{-fabi-version=@var{n} -fno-access-control -fcheck-new @gol
179-fconserve-space -ffriend-injection @gol
180-fno-elide-constructors @gol
181-fno-enforce-eh-specs @gol
182-ffor-scope -fno-for-scope -fno-gnu-keywords @gol
183-fno-implicit-templates @gol
184-fno-implicit-inline-templates @gol
185-fno-implement-inlines -fms-extensions @gol
186-fno-nonansi-builtins -fno-operator-names @gol
187-fno-optional-diags -fpermissive @gol
188-frepo -fno-rtti -fstats -ftemplate-depth-@var{n} @gol
189-fno-threadsafe-statics -fuse-cxa-atexit -fno-weak -nostdinc++ @gol
190-fno-default-inline -fvisibility-inlines-hidden @gol
191-Wabi -Wctor-dtor-privacy @gol
192-Wnon-virtual-dtor -Wreorder @gol
193-Weffc++ -Wno-deprecated -Wstrict-null-sentinel @gol
194-Wno-non-template-friend -Wold-style-cast @gol
195-Woverloaded-virtual -Wno-pmf-conversions @gol
196-Wsign-promo}
197
198@item Objective-C and Objective-C++ Language Options
199@xref{Objective-C and Objective-C++ Dialect Options,,Options Controlling
200Objective-C and Objective-C++ Dialects}.
201@gccoptlist{-fconstant-string-class=@var{class-name} @gol
202-fgnu-runtime -fnext-runtime @gol
203-fno-nil-receivers @gol
204-fobjc-call-cxx-cdtors @gol
205-fobjc-direct-dispatch @gol
206-fobjc-exceptions @gol
207-fobjc-gc @gol
208-freplace-objc-classes @gol
209-fzero-link @gol
210-gen-decls @gol
211-Wassign-intercept @gol
212-Wno-protocol -Wselector @gol
213-Wstrict-selector-match @gol
214-Wundeclared-selector}
215
216@item Language Independent Options
217@xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}.
218@gccoptlist{-fmessage-length=@var{n} @gol
219-fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]} @gol
220-fdiagnostics-show-option}
221
222@item Warning Options
223@xref{Warning Options,,Options to Request or Suppress Warnings}.
224@gccoptlist{-fsyntax-only -pedantic -pedantic-errors @gol
225-w -Wextra -Wall -Waddress -Waggregate-return -Wno-attributes @gol
226-Wc++-compat -Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment @gol
227-Wconversion -Wno-deprecated-declarations @gol
228-Wdisabled-optimization -Wno-div-by-zero -Wno-endif-labels @gol
229-Werror -Werror=* -Werror-implicit-function-declaration @gol
230-Wfatal-errors -Wfloat-equal -Wformat -Wformat=2 @gol
231-Wno-format-extra-args -Wformat-nonliteral @gol
232-Wformat-security -Wformat-y2k @gol
233-Wimplicit -Wimplicit-function-declaration -Wimplicit-int @gol
234-Wimport -Wno-import -Winit-self -Winline @gol
235-Wno-int-to-pointer-cast @gol
236-Wno-invalid-offsetof -Winvalid-pch @gol
237-Wlarger-than-@var{len} -Wunsafe-loop-optimizations -Wlong-long @gol
238-Wmain -Wmissing-braces -Wmissing-field-initializers @gol
239-Wmissing-format-attribute -Wmissing-include-dirs @gol
240-Wmissing-noreturn @gol
241-Wno-multichar -Wnonnull -Wno-overflow @gol
242-Woverlength-strings -Wpacked -Wpadded @gol
243-Wparentheses -Wpointer-arith -Wno-pointer-to-int-cast @gol
244-Wredundant-decls @gol
245-Wreturn-type -Wsequence-point -Wshadow @gol
246-Wsign-compare -Wstack-protector @gol
247-Wstrict-aliasing -Wstrict-aliasing=2 @gol
248-Wstrict-overflow -Wstrict-overflow=@var{n} @gol
249-Wswitch -Wswitch-default -Wswitch-enum @gol
250-Wsystem-headers -Wtrigraphs -Wundef -Wuninitialized @gol
251-Wunknown-pragmas -Wno-pragmas -Wunreachable-code @gol
252-Wunused -Wunused-function -Wunused-label -Wunused-parameter @gol
253-Wunused-value -Wunused-variable -Wvariadic-macros @gol
254-Wvolatile-register-var -Wwrite-strings}
255
256@item C-only Warning Options
257@gccoptlist{-Wbad-function-cast -Wmissing-declarations @gol
258-Wmissing-prototypes -Wnested-externs -Wold-style-definition @gol
259-Wstrict-prototypes -Wtraditional @gol
260-Wdeclaration-after-statement -Wpointer-sign}
261
262@item Debugging Options
263@xref{Debugging Options,,Options for Debugging Your Program or GCC}.
264@gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
265-fdump-noaddr -fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} @gol
266-fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
267-fdump-ipa-all -fdump-ipa-cgraph @gol
268-fdump-tree-all @gol
269-fdump-tree-original@r{[}-@var{n}@r{]} @gol
270-fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
271-fdump-tree-inlined@r{[}-@var{n}@r{]} @gol
272-fdump-tree-cfg -fdump-tree-vcg -fdump-tree-alias @gol
273-fdump-tree-ch @gol
274-fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol
275-fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol
276-fdump-tree-gimple@r{[}-raw@r{]} -fdump-tree-mudflap@r{[}-@var{n}@r{]} @gol
277-fdump-tree-dom@r{[}-@var{n}@r{]} @gol
278-fdump-tree-dse@r{[}-@var{n}@r{]} @gol
279-fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol
280-fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
281-fdump-tree-copyrename@r{[}-@var{n}@r{]} @gol
282-fdump-tree-nrv -fdump-tree-vect @gol
283-fdump-tree-sink @gol
284-fdump-tree-sra@r{[}-@var{n}@r{]} @gol
285-fdump-tree-salias @gol
286-fdump-tree-fre@r{[}-@var{n}@r{]} @gol
287-fdump-tree-vrp@r{[}-@var{n}@r{]} @gol
288-ftree-vectorizer-verbose=@var{n} @gol
289-fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol
290-feliminate-dwarf2-dups -feliminate-unused-debug-types @gol
291-feliminate-unused-debug-symbols -femit-class-debug-always @gol
292-fmem-report -fprofile-arcs @gol
293-frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
294-ftest-coverage -ftime-report -fvar-tracking @gol
295-g -g@var{level} -gcoff -gdwarf-2 @gol
296-ggdb -gstabs -gstabs+ -gvms -gxcoff -gxcoff+ @gol
297-p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol
298-print-multi-directory -print-multi-lib @gol
299-print-prog-name=@var{program} -print-search-dirs -Q @gol
300-save-temps -time}
301
302@item Optimization Options
303@xref{Optimize Options,,Options that Control Optimization}.
304@gccoptlist{-falign-functions=@var{n} -falign-jumps=@var{n} @gol
305-falign-labels=@var{n} -falign-loops=@var{n} @gol
306-fbounds-check -fmudflap -fmudflapth -fmudflapir @gol
307-fbranch-probabilities -fprofile-values -fvpt -fbranch-target-load-optimize @gol
308-fbranch-target-load-optimize2 -fbtr-bb-exclusive @gol
309-fcaller-saves -fcprop-registers -fcse-follow-jumps @gol
310-fcse-skip-blocks -fcx-limited-range -fdata-sections @gol
311-fdelayed-branch -fdelete-null-pointer-checks -fearly-inlining @gol
312-fexpensive-optimizations -ffast-math -ffloat-store @gol
313-fforce-addr -ffunction-sections @gol
314-fgcse -fgcse-lm -fgcse-sm -fgcse-las -fgcse-after-reload @gol
315-fcrossjumping -fif-conversion -fif-conversion2 @gol
316-finline-functions -finline-functions-called-once @gol
317-finline-limit=@var{n} -fkeep-inline-functions @gol
318-fkeep-static-consts -fmerge-constants -fmerge-all-constants @gol
319-fmodulo-sched -fno-branch-count-reg @gol
320-fno-default-inline -fno-defer-pop -fmove-loop-invariants @gol
321-fno-function-cse -fno-guess-branch-probability @gol
322-fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol
323-funsafe-math-optimizations -funsafe-loop-optimizations -ffinite-math-only @gol
324-fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol
325-fomit-frame-pointer -foptimize-register-move @gol
326-foptimize-sibling-calls -fprefetch-loop-arrays @gol
327-fprofile-generate -fprofile-use @gol
328-fregmove -frename-registers @gol
329-freorder-blocks -freorder-blocks-and-partition -freorder-functions @gol
330-frerun-cse-after-loop @gol
331-frounding-math -frtl-abstract-sequences @gol
332-fschedule-insns -fschedule-insns2 @gol
333-fno-sched-interblock -fno-sched-spec -fsched-spec-load @gol
334-fsched-spec-load-dangerous @gol
335-fsched-stalled-insns=@var{n} -fsched-stalled-insns-dep=@var{n} @gol
336-fsched2-use-superblocks @gol
337-fsched2-use-traces -fsee -freschedule-modulo-scheduled-loops @gol
338-fsection-anchors -fsignaling-nans -fsingle-precision-constant @gol
339-fstack-protector -fstack-protector-all @gol
340-fstrict-aliasing -fstrict-overflow -ftracer -fthread-jumps @gol
341-funroll-all-loops -funroll-loops -fpeel-loops @gol
342-fsplit-ivs-in-unroller -funswitch-loops @gol
343-fvariable-expansion-in-unroller @gol
344-ftree-pre -ftree-ccp -ftree-dce -ftree-loop-optimize @gol
345-ftree-loop-linear -ftree-loop-im -ftree-loop-ivcanon -fivopts @gol
346-ftree-dominator-opts -ftree-dse -ftree-copyrename -ftree-sink @gol
347-ftree-ch -ftree-sra -ftree-ter -ftree-lrs -ftree-fre -ftree-vectorize @gol
348-ftree-vect-loop-version -ftree-salias -fipa-pta -fweb @gol
349-ftree-copy-prop -ftree-store-ccp -ftree-store-copy-prop -fwhole-program @gol
350--param @var{name}=@var{value}
351-O -O0 -O1 -O2 -O3 -Os}
352
353@item Preprocessor Options
354@xref{Preprocessor Options,,Options Controlling the Preprocessor}.
355@gccoptlist{-A@var{question}=@var{answer} @gol
356-A-@var{question}@r{[}=@var{answer}@r{]} @gol
357-C -dD -dI -dM -dN @gol
358-D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol
359-idirafter @var{dir} @gol
360-include @var{file} -imacros @var{file} @gol
361-iprefix @var{file} -iwithprefix @var{dir} @gol
362-iwithprefixbefore @var{dir} -isystem @var{dir} @gol
363-imultilib @var{dir} -isysroot @var{dir} @gol
364-M -MM -MF -MG -MP -MQ -MT -nostdinc @gol
365-P -fworking-directory -remap @gol
366-trigraphs -undef -U@var{macro} -Wp,@var{option} @gol
367-Xpreprocessor @var{option}}
368
369@item Assembler Option
370@xref{Assembler Options,,Passing Options to the Assembler}.
371@gccoptlist{-Wa,@var{option} -Xassembler @var{option}}
372
373@item Linker Options
374@xref{Link Options,,Options for Linking}.
375@gccoptlist{@var{object-file-name} -l@var{library} @gol
376-nostartfiles -nodefaultlibs -nostdlib -pie -rdynamic @gol
377-s -static -static-libgcc -shared -shared-libgcc -symbolic @gol
378-Wl,@var{option} -Xlinker @var{option} @gol
379-u @var{symbol}}
380
381@item Directory Options
382@xref{Directory Options,,Options for Directory Search}.
383@gccoptlist{-B@var{prefix} -I@var{dir} -iquote@var{dir} -L@var{dir}
384-specs=@var{file} -I- --sysroot=@var{dir}}
385
386@item Target Options
387@c I wrote this xref this way to avoid overfull hbox. -- rms
388@xref{Target Options}.
389@gccoptlist{-V @var{version} -b @var{machine}}
390
391@item Machine Dependent Options
392@xref{Submodel Options,,Hardware Models and Configurations}.
393@c This list is ordered alphanumerically by subsection name.
394@c Try and put the significant identifier (CPU or system) first,
395@c so users have a clue at guessing where the ones they want will be.
396
397@emph{ARC Options}
398@gccoptlist{-EB -EL @gol
399-mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text-section} @gol
400-mdata=@var{data-section} -mrodata=@var{readonly-data-section}}
401
402@emph{ARM Options}
403@gccoptlist{-mapcs-frame -mno-apcs-frame @gol
404-mabi=@var{name} @gol
405-mapcs-stack-check -mno-apcs-stack-check @gol
406-mapcs-float -mno-apcs-float @gol
407-mapcs-reentrant -mno-apcs-reentrant @gol
408-msched-prolog -mno-sched-prolog @gol
409-mlittle-endian -mbig-endian -mwords-little-endian @gol
410-mfloat-abi=@var{name} -msoft-float -mhard-float -mfpe @gol
411-mthumb-interwork -mno-thumb-interwork @gol
412-mcpu=@var{name} -march=@var{name} -mfpu=@var{name} @gol
413-mstructure-size-boundary=@var{n} @gol
414-mabort-on-noreturn @gol
415-mlong-calls -mno-long-calls @gol
416-msingle-pic-base -mno-single-pic-base @gol
417-mpic-register=@var{reg} @gol
418-mnop-fun-dllimport @gol
419-mcirrus-fix-invalid-insns -mno-cirrus-fix-invalid-insns @gol
420-mpoke-function-name @gol
421-mthumb -marm @gol
422-mtpcs-frame -mtpcs-leaf-frame @gol
423-mcaller-super-interworking -mcallee-super-interworking @gol
424-mtp=@var{name}}
425
426@emph{AVR Options}
427@gccoptlist{-mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts @gol
428-mcall-prologues -mno-tablejump -mtiny-stack -mint8}
429
430@emph{Blackfin Options}
431@gccoptlist{-momit-leaf-frame-pointer -mno-omit-leaf-frame-pointer @gol
432-mspecld-anomaly -mno-specld-anomaly -mcsync-anomaly -mno-csync-anomaly @gol
433-mlow-64k -mno-low64k -mid-shared-library @gol
434-mno-id-shared-library -mshared-library-id=@var{n} @gol
435-mlong-calls -mno-long-calls}
436
437@emph{CRIS Options}
438@gccoptlist{-mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol
439-mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol
440-metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol
441-mstack-align -mdata-align -mconst-align @gol
442-m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol
443-melf -maout -melinux -mlinux -sim -sim2 @gol
444-mmul-bug-workaround -mno-mul-bug-workaround}
445
446@emph{CRX Options}
447@gccoptlist{-mmac -mpush-args}
448
449@emph{Darwin Options}
450@gccoptlist{-all_load -allowable_client -arch -arch_errors_fatal @gol
451-arch_only -bind_at_load -bundle -bundle_loader @gol
452-client_name -compatibility_version -current_version @gol
453-dead_strip @gol
454-dependency-file -dylib_file -dylinker_install_name @gol
455-dynamic -dynamiclib -exported_symbols_list @gol
456-filelist -flat_namespace -force_cpusubtype_ALL @gol
457-force_flat_namespace -headerpad_max_install_names @gol
458-image_base -init -install_name -keep_private_externs @gol
459-multi_module -multiply_defined -multiply_defined_unused @gol
460-noall_load -no_dead_strip_inits_and_terms @gol
461-nofixprebinding -nomultidefs -noprebind -noseglinkedit @gol
462-pagezero_size -prebind -prebind_all_twolevel_modules @gol
463-private_bundle -read_only_relocs -sectalign @gol
464-sectobjectsymbols -whyload -seg1addr @gol
465-sectcreate -sectobjectsymbols -sectorder @gol
466-segaddr -segs_read_only_addr -segs_read_write_addr @gol
467-seg_addr_table -seg_addr_table_filename -seglinkedit @gol
468-segprot -segs_read_only_addr -segs_read_write_addr @gol
469-single_module -static -sub_library -sub_umbrella @gol
470-twolevel_namespace -umbrella -undefined @gol
471-unexported_symbols_list -weak_reference_mismatches @gol
472-whatsloaded -F -gused -gfull -mmacosx-version-min=@var{version} @gol
473-mkernel -mone-byte-bool}
474
475@emph{DEC Alpha Options}
476@gccoptlist{-mno-fp-regs -msoft-float -malpha-as -mgas @gol
477-mieee -mieee-with-inexact -mieee-conformant @gol
478-mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} @gol
479-mtrap-precision=@var{mode} -mbuild-constants @gol
480-mcpu=@var{cpu-type} -mtune=@var{cpu-type} @gol
481-mbwx -mmax -mfix -mcix @gol
482-mfloat-vax -mfloat-ieee @gol
483-mexplicit-relocs -msmall-data -mlarge-data @gol
484-msmall-text -mlarge-text @gol
485-mmemory-latency=@var{time}}
486
487@emph{DEC Alpha/VMS Options}
488@gccoptlist{-mvms-return-codes}
489
490@emph{FRV Options}
491@gccoptlist{-mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 @gol
492-mhard-float -msoft-float @gol
493-malloc-cc -mfixed-cc -mdword -mno-dword @gol
494-mdouble -mno-double @gol
495-mmedia -mno-media -mmuladd -mno-muladd @gol
496-mfdpic -minline-plt -mgprel-ro -multilib-library-pic @gol
497-mlinked-fp -mlong-calls -malign-labels @gol
498-mlibrary-pic -macc-4 -macc-8 @gol
499-mpack -mno-pack -mno-eflags -mcond-move -mno-cond-move @gol
500-moptimize-membar -mno-optimize-membar @gol
501-mscc -mno-scc -mcond-exec -mno-cond-exec @gol
502-mvliw-branch -mno-vliw-branch @gol
503-mmulti-cond-exec -mno-multi-cond-exec -mnested-cond-exec @gol
504-mno-nested-cond-exec -mtomcat-stats @gol
505-mTLS -mtls @gol
506-mcpu=@var{cpu}}
507
508@emph{GNU/Linux Options}
509@gccoptlist{-muclibc}
510
511@emph{H8/300 Options}
512@gccoptlist{-mrelax -mh -ms -mn -mint32 -malign-300}
513
514@emph{HPPA Options}
515@gccoptlist{-march=@var{architecture-type} @gol
516-mbig-switch -mdisable-fpregs -mdisable-indexing @gol
517-mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol
518-mfixed-range=@var{register-range} @gol
519-mjump-in-delay -mlinker-opt -mlong-calls @gol
520-mlong-load-store -mno-big-switch -mno-disable-fpregs @gol
521-mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol
522-mno-jump-in-delay -mno-long-load-store @gol
523-mno-portable-runtime -mno-soft-float @gol
524-mno-space-regs -msoft-float -mpa-risc-1-0 @gol
525-mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime @gol
526-mschedule=@var{cpu-type} -mspace-regs -msio -mwsio @gol
527-munix=@var{unix-std} -nolibdld -static -threads}
528
529@emph{i386 and x86-64 Options}
530@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
531-mfpmath=@var{unit} @gol
532-masm=@var{dialect} -mno-fancy-math-387 @gol
533-mno-fp-ret-in-387 -msoft-float -msvr3-shlib @gol
534-mno-wide-multiply -mrtd -malign-double @gol
535-mpreferred-stack-boundary=@var{num} @gol
536-mmmx -msse -msse2 -msse3 -m3dnow @gol
537-mthreads -mno-align-stringops -minline-all-stringops @gol
538-mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol
539-m96bit-long-double -mregparm=@var{num} -msseregparm @gol
540-mstackrealign @gol
541-momit-leaf-frame-pointer -mno-red-zone -mno-tls-direct-seg-refs @gol
542-mcmodel=@var{code-model} @gol
543-m32 -m64 -mlarge-data-threshold=@var{num}}
544
545@emph{IA-64 Options}
546@gccoptlist{-mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol
547-mvolatile-asm-stop -mregister-names -mno-sdata @gol
548-mconstant-gp -mauto-pic -minline-float-divide-min-latency @gol
549-minline-float-divide-max-throughput @gol
550-minline-int-divide-min-latency @gol
551-minline-int-divide-max-throughput @gol
552-minline-sqrt-min-latency -minline-sqrt-max-throughput @gol
553-mno-dwarf2-asm -mearly-stop-bits @gol
554-mfixed-range=@var{register-range} -mtls-size=@var{tls-size} @gol
555-mtune=@var{cpu-type} -mt -pthread -milp32 -mlp64 @gol
556-mno-sched-br-data-spec -msched-ar-data-spec -mno-sched-control-spec @gol
557-msched-br-in-data-spec -msched-ar-in-data-spec -msched-in-control-spec @gol
558-msched-ldc -mno-sched-control-ldc -mno-sched-spec-verbose @gol
559-mno-sched-prefer-non-data-spec-insns @gol
560-mno-sched-prefer-non-control-spec-insns @gol
561-mno-sched-count-spec-in-critical-path}
562
563@emph{M32R/D Options}
564@gccoptlist{-m32r2 -m32rx -m32r @gol
565-mdebug @gol
566-malign-loops -mno-align-loops @gol
567-missue-rate=@var{number} @gol
568-mbranch-cost=@var{number} @gol
569-mmodel=@var{code-size-model-type} @gol
570-msdata=@var{sdata-type} @gol
571-mno-flush-func -mflush-func=@var{name} @gol
572-mno-flush-trap -mflush-trap=@var{number} @gol
573-G @var{num}}
574
575@emph{M32C Options}
576@gccoptlist{-mcpu=@var{cpu} -msim -memregs=@var{number}}
577
578@emph{M680x0 Options}
579@gccoptlist{-m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol
580-m68060 -mcpu32 -m5200 -mcfv4e -m68881 -mbitfield @gol
581-mc68000 -mc68020 @gol
582-mnobitfield -mrtd -mshort -msoft-float -mpcrel @gol
583-malign-int -mstrict-align -msep-data -mno-sep-data @gol
584-mshared-library-id=n -mid-shared-library -mno-id-shared-library}
585
586@emph{M68hc1x Options}
587@gccoptlist{-m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 @gol
588-mauto-incdec -minmax -mlong-calls -mshort @gol
589-msoft-reg-count=@var{count}}
590
591@emph{MCore Options}
592@gccoptlist{-mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol
593-mno-relax-immediates -mwide-bitfields -mno-wide-bitfields @gol
594-m4byte-functions -mno-4byte-functions -mcallgraph-data @gol
595-mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim @gol
596-mlittle-endian -mbig-endian -m210 -m340 -mstack-increment}
597
598@emph{MIPS Options}
599@gccoptlist{-EL -EB -march=@var{arch} -mtune=@var{arch} @gol
600-mips1 -mips2 -mips3 -mips4 -mips32 -mips32r2 -mips64 @gol
601-mips16 -mno-mips16 -mabi=@var{abi} -mabicalls -mno-abicalls @gol
602-mshared -mno-shared -mxgot -mno-xgot -mgp32 -mgp64 @gol
603-mfp32 -mfp64 -mhard-float -msoft-float @gol
604-msingle-float -mdouble-float -mdsp -mpaired-single -mips3d @gol
605-mlong64 -mlong32 -msym32 -mno-sym32 @gol
606-G@var{num} -membedded-data -mno-embedded-data @gol
607-muninit-const-in-rodata -mno-uninit-const-in-rodata @gol
608-msplit-addresses -mno-split-addresses @gol
609-mexplicit-relocs -mno-explicit-relocs @gol
610-mcheck-zero-division -mno-check-zero-division @gol
611-mdivide-traps -mdivide-breaks @gol
612-mmemcpy -mno-memcpy -mlong-calls -mno-long-calls @gol
613-mmad -mno-mad -mfused-madd -mno-fused-madd -nocpp @gol
614-mfix-r4000 -mno-fix-r4000 -mfix-r4400 -mno-fix-r4400 @gol
615-mfix-vr4120 -mno-fix-vr4120 -mfix-vr4130 @gol
616-mfix-sb1 -mno-fix-sb1 @gol
617-mflush-func=@var{func} -mno-flush-func @gol
618-mbranch-likely -mno-branch-likely @gol
619-mfp-exceptions -mno-fp-exceptions @gol
620-mvr4130-align -mno-vr4130-align}
621
622@emph{MMIX Options}
623@gccoptlist{-mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol
624-mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol
625-melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol
626-mno-base-addresses -msingle-exit -mno-single-exit}
627
628@emph{MN10300 Options}
629@gccoptlist{-mmult-bug -mno-mult-bug @gol
630-mam33 -mno-am33 @gol
631-mam33-2 -mno-am33-2 @gol
632-mreturn-pointer-on-d0 @gol
633-mno-crt0 -mrelax}
634
635@emph{MT Options}
636@gccoptlist{-mno-crt0 -mbacc -msim @gol
637-march=@var{cpu-type} }
638
639@emph{PDP-11 Options}
640@gccoptlist{-mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol
641-mbcopy -mbcopy-builtin -mint32 -mno-int16 @gol
642-mint16 -mno-int32 -mfloat32 -mno-float64 @gol
643-mfloat64 -mno-float32 -mabshi -mno-abshi @gol
644-mbranch-expensive -mbranch-cheap @gol
645-msplit -mno-split -munix-asm -mdec-asm}
646
647@emph{PowerPC Options}
648See RS/6000 and PowerPC Options.
649
650@emph{RS/6000 and PowerPC Options}
651@gccoptlist{-mcpu=@var{cpu-type} @gol
652-mtune=@var{cpu-type} @gol
653-mpower -mno-power -mpower2 -mno-power2 @gol
654-mpowerpc -mpowerpc64 -mno-powerpc @gol
655-maltivec -mno-altivec @gol
656-mpowerpc-gpopt -mno-powerpc-gpopt @gol
657-mpowerpc-gfxopt -mno-powerpc-gfxopt @gol
658-mmfcrf -mno-mfcrf -mpopcntb -mno-popcntb -mfprnd -mno-fprnd @gol
659-mnew-mnemonics -mold-mnemonics @gol
660-mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc @gol
661-m64 -m32 -mxl-compat -mno-xl-compat -mpe @gol
662-malign-power -malign-natural @gol
663-msoft-float -mhard-float -mmultiple -mno-multiple @gol
664-mstring -mno-string -mupdate -mno-update @gol
665-mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol
666-mstrict-align -mno-strict-align -mrelocatable @gol
667-mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol
668-mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol
669-mdynamic-no-pic -maltivec -mswdiv @gol
670-mprioritize-restricted-insns=@var{priority} @gol
671-msched-costly-dep=@var{dependence_type} @gol
672-minsert-sched-nops=@var{scheme} @gol
673-mcall-sysv -mcall-netbsd @gol
674-maix-struct-return -msvr4-struct-return @gol
675-mabi=@var{abi-type} -msecure-plt -mbss-plt @gol
676-misel -mno-isel @gol
677-misel=yes -misel=no @gol
678-mspe -mno-spe @gol
679-mspe=yes -mspe=no @gol
680-mvrsave -mno-vrsave @gol
681-mmulhw -mno-mulhw @gol
682-mdlmzb -mno-dlmzb @gol
683-mfloat-gprs=yes -mfloat-gprs=no -mfloat-gprs=single -mfloat-gprs=double @gol
684-mprototype -mno-prototype @gol
685-msim -mmvme -mads -myellowknife -memb -msdata @gol
686-msdata=@var{opt} -mvxworks -mwindiss -G @var{num} -pthread}
687
688@emph{S/390 and zSeries Options}
689@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
690-mhard-float -msoft-float -mlong-double-64 -mlong-double-128 @gol
691-mbackchain -mno-backchain -mpacked-stack -mno-packed-stack @gol
692-msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol
693-m64 -m31 -mdebug -mno-debug -mesa -mzarch @gol
694-mtpf-trace -mno-tpf-trace -mfused-madd -mno-fused-madd @gol
695-mwarn-framesize -mwarn-dynamicstack -mstack-size -mstack-guard}
696
697@emph{Score Options}
698@gccoptlist{-meb -mel @gol
699-mnhwloop @gol
700-muls @gol
701-mmac @gol
702-mscore5 -mscore5u -mscore7 -mscore7d}
703
704@emph{SH Options}
705@gccoptlist{-m1 -m2 -m2e -m3 -m3e @gol
706-m4-nofpu -m4-single-only -m4-single -m4 @gol
707-m4a-nofpu -m4a-single-only -m4a-single -m4a -m4al @gol
708-m5-64media -m5-64media-nofpu @gol
709-m5-32media -m5-32media-nofpu @gol
710-m5-compact -m5-compact-nofpu @gol
711-mb -ml -mdalign -mrelax @gol
712-mbigtable -mfmovd -mhitachi -mrenesas -mno-renesas -mnomacsave @gol
713-mieee -misize -mpadstruct -mspace @gol
714-mprefergot -musermode -multcost=@var{number} -mdiv=@var{strategy} @gol
715-mdivsi3_libfunc=@var{name} @gol
716-madjust-unroll -mindexed-addressing -mgettrcost=@var{number} -mpt-fixed @gol
717 -minvalid-symbols}
718
719@emph{SPARC Options}
720@gccoptlist{-mcpu=@var{cpu-type} @gol
721-mtune=@var{cpu-type} @gol
722-mcmodel=@var{code-model} @gol
723-m32 -m64 -mapp-regs -mno-app-regs @gol
724-mfaster-structs -mno-faster-structs @gol
725-mfpu -mno-fpu -mhard-float -msoft-float @gol
726-mhard-quad-float -msoft-quad-float @gol
727-mimpure-text -mno-impure-text -mlittle-endian @gol
728-mstack-bias -mno-stack-bias @gol
729-munaligned-doubles -mno-unaligned-doubles @gol
730-mv8plus -mno-v8plus -mvis -mno-vis
731-threads -pthreads -pthread}
732
733@emph{System V Options}
734@gccoptlist{-Qy -Qn -YP,@var{paths} -Ym,@var{dir}}
735
736@emph{TMS320C3x/C4x Options}
737@gccoptlist{-mcpu=@var{cpu} -mbig -msmall -mregparm -mmemparm @gol
738-mfast-fix -mmpyi -mbk -mti -mdp-isr-reload @gol
739-mrpts=@var{count} -mrptb -mdb -mloop-unsigned @gol
740-mparallel-insns -mparallel-mpy -mpreserve-float}
741
742@emph{V850 Options}
743@gccoptlist{-mlong-calls -mno-long-calls -mep -mno-ep @gol
744-mprolog-function -mno-prolog-function -mspace @gol
745-mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol
746-mapp-regs -mno-app-regs @gol
747-mdisable-callt -mno-disable-callt @gol
748-mv850e1 @gol
749-mv850e @gol
750-mv850 -mbig-switch}
751
752@emph{VAX Options}
753@gccoptlist{-mg -mgnu -munix}
754
755@emph{x86-64 Options}
756See i386 and x86-64 Options.
757
758@emph{Xstormy16 Options}
759@gccoptlist{-msim}
760
761@emph{Xtensa Options}
762@gccoptlist{-mconst16 -mno-const16 @gol
763-mfused-madd -mno-fused-madd @gol
764-mtext-section-literals -mno-text-section-literals @gol
765-mtarget-align -mno-target-align @gol
766-mlongcalls -mno-longcalls}
767
768@emph{zSeries Options}
769See S/390 and zSeries Options.
770
771@item Code Generation Options
772@xref{Code Gen Options,,Options for Code Generation Conventions}.
773@gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol
774-ffixed-@var{reg} -fexceptions @gol
775-fnon-call-exceptions -funwind-tables @gol
776-fasynchronous-unwind-tables @gol
777-finhibit-size-directive -finstrument-functions @gol
778-fno-common -fno-ident @gol
779-fpcc-struct-return -fpic -fPIC -fpie -fPIE @gol
780-fno-jump-tables @gol
781-freg-struct-return -fshort-enums @gol
782-fshort-double -fshort-wchar @gol
783-fverbose-asm -fpack-struct[=@var{n}] -fstack-check @gol
784-fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
785-fargument-alias -fargument-noalias @gol
786-fargument-noalias-global -fargument-noalias-anything
787-fleading-underscore -ftls-model=@var{model} @gol
788-ftrapv -fwrapv -fbounds-check @gol
789-fvisibility}
790@end table
791
792@menu
793* Overall Options:: Controlling the kind of output:
794 an executable, object files, assembler files,
795 or preprocessed source.
796* C Dialect Options:: Controlling the variant of C language compiled.
797* C++ Dialect Options:: Variations on C++.
798* Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
799 and Objective-C++.
800* Language Independent Options:: Controlling how diagnostics should be
801 formatted.
802* Warning Options:: How picky should the compiler be?
803* Debugging Options:: Symbol tables, measurements, and debugging dumps.
804* Optimize Options:: How much optimization?
805* Preprocessor Options:: Controlling header files and macro definitions.
806 Also, getting dependency information for Make.
807* Assembler Options:: Passing options to the assembler.
808* Link Options:: Specifying libraries and so on.
809* Directory Options:: Where to find header files and libraries.
810 Where to find the compiler executable files.
811* Spec Files:: How to pass switches to sub-processes.
812* Target Options:: Running a cross-compiler, or an old version of GCC.
813@end menu
814
815@node Overall Options
816@section Options Controlling the Kind of Output
817
818Compilation can involve up to four stages: preprocessing, compilation
819proper, assembly and linking, always in that order. GCC is capable of
820preprocessing and compiling several files either into several
821assembler input files, or into one assembler input file; then each
822assembler input file produces an object file, and linking combines all
823the object files (those newly compiled, and those specified as input)
824into an executable file.
825
826@cindex file name suffix
827For any given input file, the file name suffix determines what kind of
828compilation is done:
829
830@table @gcctabopt
831@item @var{file}.c
832C source code which must be preprocessed.
833
834@item @var{file}.i
835C source code which should not be preprocessed.
836
837@item @var{file}.ii
838C++ source code which should not be preprocessed.
839
840@item @var{file}.m
841Objective-C source code. Note that you must link with the @file{libobjc}
842library to make an Objective-C program work.
843
844@item @var{file}.mi
845Objective-C source code which should not be preprocessed.
846
847@item @var{file}.mm
848@itemx @var{file}.M
849Objective-C++ source code. Note that you must link with the @file{libobjc}
850library to make an Objective-C++ program work. Note that @samp{.M} refers
851to a literal capital M@.
852
853@item @var{file}.mii
854Objective-C++ source code which should not be preprocessed.
855
856@item @var{file}.h
857C, C++, Objective-C or Objective-C++ header file to be turned into a
858precompiled header.
859
860@item @var{file}.cc
861@itemx @var{file}.cp
862@itemx @var{file}.cxx
863@itemx @var{file}.cpp
864@itemx @var{file}.CPP
865@itemx @var{file}.c++
866@itemx @var{file}.C
867C++ source code which must be preprocessed. Note that in @samp{.cxx},
868the last two letters must both be literally @samp{x}. Likewise,
869@samp{.C} refers to a literal capital C@.
870
871@item @var{file}.mm
872@itemx @var{file}.M
873Objective-C++ source code which must be preprocessed.
874
875@item @var{file}.mii
876Objective-C++ source code which should not be preprocessed.
877
878@item @var{file}.hh
879@itemx @var{file}.H
880C++ header file to be turned into a precompiled header.
881
882@item @var{file}.f
883@itemx @var{file}.for
884@itemx @var{file}.FOR
885Fixed form Fortran source code which should not be preprocessed.
886
887@item @var{file}.F
888@itemx @var{file}.fpp
889@itemx @var{file}.FPP
890Fixed form Fortran source code which must be preprocessed (with the traditional
891preprocessor).
892
893@item @var{file}.f90
894@itemx @var{file}.f95
895Free form Fortran source code which should not be preprocessed.
896
897@item @var{file}.F90
898@itemx @var{file}.F95
899Free form Fortran source code which must be preprocessed (with the
900traditional preprocessor).
901
902@c FIXME: Descriptions of Java file types.
903@c @var{file}.java
904@c @var{file}.class
905@c @var{file}.zip
906@c @var{file}.jar
907
908@item @var{file}.ads
909Ada source code file which contains a library unit declaration (a
910declaration of a package, subprogram, or generic, or a generic
911instantiation), or a library unit renaming declaration (a package,
912generic, or subprogram renaming declaration). Such files are also
913called @dfn{specs}.
914
915@itemx @var{file}.adb
916Ada source code file containing a library unit body (a subprogram or
917package body). Such files are also called @dfn{bodies}.
918
919@c GCC also knows about some suffixes for languages not yet included:
920@c Pascal:
921@c @var{file}.p
922@c @var{file}.pas
923@c Ratfor:
924@c @var{file}.r
925
926@item @var{file}.s
927Assembler code.
928
929@item @var{file}.S
930Assembler code which must be preprocessed.
931
932@item @var{other}
933An object file to be fed straight into linking.
934Any file name with no recognized suffix is treated this way.
935@end table
936
937@opindex x
938You can specify the input language explicitly with the @option{-x} option:
939
940@table @gcctabopt
941@item -x @var{language}
942Specify explicitly the @var{language} for the following input files
943(rather than letting the compiler choose a default based on the file
944name suffix). This option applies to all following input files until
945the next @option{-x} option. Possible values for @var{language} are:
946@smallexample
947c c-header c-cpp-output
948c++ c++-header c++-cpp-output
949objective-c objective-c-header objective-c-cpp-output
950objective-c++ objective-c++-header objective-c++-cpp-output
951assembler assembler-with-cpp
952ada
953f95 f95-cpp-input
954java
955treelang
956@end smallexample
957
958@item -x none
959Turn off any specification of a language, so that subsequent files are
960handled according to their file name suffixes (as they are if @option{-x}
961has not been used at all).
962
963@item -pass-exit-codes
964@opindex pass-exit-codes
965Normally the @command{gcc} program will exit with the code of 1 if any
966phase of the compiler returns a non-success return code. If you specify
967@option{-pass-exit-codes}, the @command{gcc} program will instead return with
968numerically highest error produced by any phase that returned an error
969indication. The C, C++, and Fortran frontends return 4, if an internal
970compiler error is encountered.
971@end table
972
973If you only want some of the stages of compilation, you can use
974@option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
975one of the options @option{-c}, @option{-S}, or @option{-E} to say where
976@command{gcc} is to stop. Note that some combinations (for example,
977@samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
978
979@table @gcctabopt
980@item -c
981@opindex c
982Compile or assemble the source files, but do not link. The linking
983stage simply is not done. The ultimate output is in the form of an
984object file for each source file.
985
986By default, the object file name for a source file is made by replacing
987the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
988
989Unrecognized input files, not requiring compilation or assembly, are
990ignored.
991
992@item -S
993@opindex S
994Stop after the stage of compilation proper; do not assemble. The output
995is in the form of an assembler code file for each non-assembler input
996file specified.
997
998By default, the assembler file name for a source file is made by
999replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
1000
1001Input files that don't require compilation are ignored.
1002
1003@item -E
1004@opindex E
1005Stop after the preprocessing stage; do not run the compiler proper. The
1006output is in the form of preprocessed source code, which is sent to the
1007standard output.
1008
1009Input files which don't require preprocessing are ignored.
1010
1011@cindex output file option
1012@item -o @var{file}
1013@opindex o
1014Place output in file @var{file}. This applies regardless to whatever
1015sort of output is being produced, whether it be an executable file,
1016an object file, an assembler file or preprocessed C code.
1017
1018If @option{-o} is not specified, the default is to put an executable
1019file in @file{a.out}, the object file for
1020@file{@var{source}.@var{suffix}} in @file{@var{source}.o}, its
1021assembler file in @file{@var{source}.s}, a precompiled header file in
1022@file{@var{source}.@var{suffix}.gch}, and all preprocessed C source on
1023standard output.
1024
1025@item -v
1026@opindex v
1027Print (on standard error output) the commands executed to run the stages
1028of compilation. Also print the version number of the compiler driver
1029program and of the preprocessor and the compiler proper.
1030
1031@item -###
1032@opindex ###
1033Like @option{-v} except the commands are not executed and all command
1034arguments are quoted. This is useful for shell scripts to capture the
1035driver-generated command lines.
1036
1037@item -pipe
1038@opindex pipe
1039Use pipes rather than temporary files for communication between the
1040various stages of compilation. This fails to work on some systems where
1041the assembler is unable to read from a pipe; but the GNU assembler has
1042no trouble.
1043
1044@item -combine
1045@opindex combine
1046If you are compiling multiple source files, this option tells the driver
1047to pass all the source files to the compiler at once (for those
1048languages for which the compiler can handle this). This will allow
1049intermodule analysis (IMA) to be performed by the compiler. Currently the only
1050language for which this is supported is C@. If you pass source files for
1051multiple languages to the driver, using this option, the driver will invoke
1052the compiler(s) that support IMA once each, passing each compiler all the
1053source files appropriate for it. For those languages that do not support
1054IMA this option will be ignored, and the compiler will be invoked once for
1055each source file in that language. If you use this option in conjunction
1056with @option{-save-temps}, the compiler will generate multiple
1057pre-processed files
1058(one for each source file), but only one (combined) @file{.o} or
1059@file{.s} file.
1060
1061@item --help
1062@opindex help
1063Print (on the standard output) a description of the command line options
1064understood by @command{gcc}. If the @option{-v} option is also specified
1065then @option{--help} will also be passed on to the various processes
1066invoked by @command{gcc}, so that they can display the command line options
1067they accept. If the @option{-Wextra} option is also specified then command
1068line options which have no documentation associated with them will also
1069be displayed.
1070
1071@item --target-help
1072@opindex target-help
1073Print (on the standard output) a description of target specific command
1074line options for each tool.
1075
1076@item --version
1077@opindex version
1078Display the version number and copyrights of the invoked GCC@.
1079
1080@include @value{srcdir}/../libiberty/at-file.texi
1081@end table
1082
1083@node Invoking G++
1084@section Compiling C++ Programs
1085
1086@cindex suffixes for C++ source
1087@cindex C++ source file suffixes
1088C++ source files conventionally use one of the suffixes @samp{.C},
1089@samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or
1090@samp{.cxx}; C++ header files often use @samp{.hh} or @samp{.H}; and
1091preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes
1092files with these names and compiles them as C++ programs even if you
1093call the compiler the same way as for compiling C programs (usually
1094with the name @command{gcc}).
1095
1096@findex g++
1097@findex c++
1098However, the use of @command{gcc} does not add the C++ library.
1099@command{g++} is a program that calls GCC and treats @samp{.c},
1100@samp{.h} and @samp{.i} files as C++ source files instead of C source
1101files unless @option{-x} is used, and automatically specifies linking
1102against the C++ library. This program is also useful when
1103precompiling a C header file with a @samp{.h} extension for use in C++
1104compilations. On many systems, @command{g++} is also installed with
1105the name @command{c++}.
1106
1107@cindex invoking @command{g++}
1108When you compile C++ programs, you may specify many of the same
1109command-line options that you use for compiling programs in any
1110language; or command-line options meaningful for C and related
1111languages; or options that are meaningful only for C++ programs.
1112@xref{C Dialect Options,,Options Controlling C Dialect}, for
1113explanations of options for languages related to C@.
1114@xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
1115explanations of options that are meaningful only for C++ programs.
1116
1117@node C Dialect Options
1118@section Options Controlling C Dialect
1119@cindex dialect options
1120@cindex language dialect options
1121@cindex options, dialect
1122
1123The following options control the dialect of C (or languages derived
1124from C, such as C++, Objective-C and Objective-C++) that the compiler
1125accepts:
1126
1127@table @gcctabopt
1128@cindex ANSI support
1129@cindex ISO support
1130@item -ansi
1131@opindex ansi
1132In C mode, support all ISO C90 programs. In C++ mode,
1133remove GNU extensions that conflict with ISO C++.
1134
1135This turns off certain features of GCC that are incompatible with ISO
1136C90 (when compiling C code), or of standard C++ (when compiling C++ code),
1137such as the @code{asm} and @code{typeof} keywords, and
1138predefined macros such as @code{unix} and @code{vax} that identify the
1139type of system you are using. It also enables the undesirable and
1140rarely used ISO trigraph feature. For the C compiler,
1141it disables recognition of C++ style @samp{//} comments as well as
1142the @code{inline} keyword.
1143
1144The alternate keywords @code{__asm__}, @code{__extension__},
1145@code{__inline__} and @code{__typeof__} continue to work despite
1146@option{-ansi}. You would not want to use them in an ISO C program, of
1147course, but it is useful to put them in header files that might be included
1148in compilations done with @option{-ansi}. Alternate predefined macros
1149such as @code{__unix__} and @code{__vax__} are also available, with or
1150without @option{-ansi}.
1151
1152The @option{-ansi} option does not cause non-ISO programs to be
1153rejected gratuitously. For that, @option{-pedantic} is required in
1154addition to @option{-ansi}. @xref{Warning Options}.
1155
1156The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
1157option is used. Some header files may notice this macro and refrain
1158from declaring certain functions or defining certain macros that the
1159ISO standard doesn't call for; this is to avoid interfering with any
1160programs that might use these names for other things.
1161
1162Functions which would normally be built in but do not have semantics
1163defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
1164functions with @option{-ansi} is used. @xref{Other Builtins,,Other
1165built-in functions provided by GCC}, for details of the functions
1166affected.
1167
1168@item -std=
1169@opindex std
1170Determine the language standard. This option is currently only
1171supported when compiling C or C++. A value for this option must be
1172provided; possible values are
1173
1174@table @samp
1175@item c89
1176@itemx iso9899:1990
1177ISO C90 (same as @option{-ansi}).
1178
1179@item iso9899:199409
1180ISO C90 as modified in amendment 1.
1181
1182@item c99
1183@itemx c9x
1184@itemx iso9899:1999
1185@itemx iso9899:199x
1186ISO C99. Note that this standard is not yet fully supported; see
1187@w{@uref{http://gcc.gnu.org/gcc-4.2/c99status.html}} for more information. The
1188names @samp{c9x} and @samp{iso9899:199x} are deprecated.
1189
1190@item gnu89
1191Default, ISO C90 plus GNU extensions (including some C99 features).
1192
1193@item gnu99
1194@itemx gnu9x
1195ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC,
1196this will become the default. The name @samp{gnu9x} is deprecated.
1197
1198@item c++98
1199The 1998 ISO C++ standard plus amendments.
1200
1201@item gnu++98
1202The same as @option{-std=c++98} plus GNU extensions. This is the
1203default for C++ code.
1204@end table
1205
1206Even when this option is not specified, you can still use some of the
1207features of newer standards in so far as they do not conflict with
1208previous C standards. For example, you may use @code{__restrict__} even
1209when @option{-std=c99} is not specified.
1210
1211The @option{-std} options specifying some version of ISO C have the same
1212effects as @option{-ansi}, except that features that were not in ISO C90
1213but are in the specified version (for example, @samp{//} comments and
1214the @code{inline} keyword in ISO C99) are not disabled.
1215
1216@xref{Standards,,Language Standards Supported by GCC}, for details of
1217these standard versions.
1218
1219@item -fgnu89-inline
1220@opindex fgnu89-inline
1221The option @option{-fgnu89-inline} tells GCC to use the traditional
1222GNU semantics for @code{inline} functions when in C99 mode.
1223@xref{Inline,,An Inline Function is As Fast As a Macro}. Using this
1224option is roughly equivalent to adding the @code{gnu_inline} function
1225attribute to all inline functions (@pxref{Function Attributes}).
1226
1227This option is accepted by GCC versions 4.1.3 and up. In GCC versions
1228prior to 4.3, C99 inline semantics are not supported, and thus this
1229option is effectively assumed to be present regardless of whether or not
1230it is specified; the only effect of specifying it explicitly is to
1231disable warnings about using inline functions in C99 mode. Likewise,
1232the option @option{-fno-gnu89-inline} is not supported in versions of
1233GCC before 4.3. It will be supported only in C99 or gnu99 mode, not in
1234C89 or gnu89 mode.
1235
1236The preprocesor macros @code{__GNUC_GNU_INLINE__} and
1237@code{__GNUC_STDC_INLINE__} may be used to check which semantics are
1238in effect for @code{inline} functions. @xref{Common Predefined
1239Macros,,,cpp,The C Preprocessor}.
1240
1241@item -aux-info @var{filename}
1242@opindex aux-info
1243Output to the given filename prototyped declarations for all functions
1244declared and/or defined in a translation unit, including those in header
1245files. This option is silently ignored in any language other than C@.
1246
1247Besides declarations, the file indicates, in comments, the origin of
1248each declaration (source file and line), whether the declaration was
1249implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
1250@samp{O} for old, respectively, in the first character after the line
1251number and the colon), and whether it came from a declaration or a
1252definition (@samp{C} or @samp{F}, respectively, in the following
1253character). In the case of function definitions, a K&R-style list of
1254arguments followed by their declarations is also provided, inside
1255comments, after the declaration.
1256
1257@item -fno-asm
1258@opindex fno-asm
1259Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1260keyword, so that code can use these words as identifiers. You can use
1261the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
1262instead. @option{-ansi} implies @option{-fno-asm}.
1263
1264In C++, this switch only affects the @code{typeof} keyword, since
1265@code{asm} and @code{inline} are standard keywords. You may want to
1266use the @option{-fno-gnu-keywords} flag instead, which has the same
1267effect. In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
1268switch only affects the @code{asm} and @code{typeof} keywords, since
1269@code{inline} is a standard keyword in ISO C99.
1270
1271@item -fno-builtin
1272@itemx -fno-builtin-@var{function}
1273@opindex fno-builtin
1274@cindex built-in functions
1275Don't recognize built-in functions that do not begin with
1276@samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in
1277functions provided by GCC}, for details of the functions affected,
1278including those which are not built-in functions when @option{-ansi} or
1279@option{-std} options for strict ISO C conformance are used because they
1280do not have an ISO standard meaning.
1281
1282GCC normally generates special code to handle certain built-in functions
1283more efficiently; for instance, calls to @code{alloca} may become single
1284instructions that adjust the stack directly, and calls to @code{memcpy}
1285may become inline copy loops. The resulting code is often both smaller
1286and faster, but since the function calls no longer appear as such, you
1287cannot set a breakpoint on those calls, nor can you change the behavior
1288of the functions by linking with a different library. In addition,
1289when a function is recognized as a built-in function, GCC may use
1290information about that function to warn about problems with calls to
1291that function, or to generate more efficient code, even if the
1292resulting code still contains calls to that function. For example,
1293warnings are given with @option{-Wformat} for bad calls to
1294@code{printf}, when @code{printf} is built in, and @code{strlen} is
1295known not to modify global memory.
1296
1297With the @option{-fno-builtin-@var{function}} option
1298only the built-in function @var{function} is
1299disabled. @var{function} must not begin with @samp{__builtin_}. If a
1300function is named this is not built-in in this version of GCC, this
1301option is ignored. There is no corresponding
1302@option{-fbuiltin-@var{function}} option; if you wish to enable
1303built-in functions selectively when using @option{-fno-builtin} or
1304@option{-ffreestanding}, you may define macros such as:
1305
1306@smallexample
1307#define abs(n) __builtin_abs ((n))
1308#define strcpy(d, s) __builtin_strcpy ((d), (s))
1309@end smallexample
1310
1311@item -fhosted
1312@opindex fhosted
1313@cindex hosted environment
1314
1315Assert that compilation takes place in a hosted environment. This implies
1316@option{-fbuiltin}. A hosted environment is one in which the
1317entire standard library is available, and in which @code{main} has a return
1318type of @code{int}. Examples are nearly everything except a kernel.
1319This is equivalent to @option{-fno-freestanding}.
1320
1321@item -ffreestanding
1322@opindex ffreestanding
1323@cindex hosted environment
1324
1325Assert that compilation takes place in a freestanding environment. This
1326implies @option{-fno-builtin}. A freestanding environment
1327is one in which the standard library may not exist, and program startup may
1328not necessarily be at @code{main}. The most obvious example is an OS kernel.
1329This is equivalent to @option{-fno-hosted}.
1330
1331@xref{Standards,,Language Standards Supported by GCC}, for details of
1332freestanding and hosted environments.
1333
1334@item -fopenmp
1335@opindex fopenmp
1336@cindex openmp parallel
1337Enable handling of OpenMP directives @code{#pragma omp} in C/C++ and
1338@code{!$omp} in Fortran. When @option{-fopenmp} is specified, the
1339compiler generates parallel code according to the OpenMP Application
1340Program Interface v2.5 @w{@uref{http://www.openmp.org/}}.
1341
1342@item -fms-extensions
1343@opindex fms-extensions
1344Accept some non-standard constructs used in Microsoft header files.
1345
1346Some cases of unnamed fields in structures and unions are only
1347accepted with this option. @xref{Unnamed Fields,,Unnamed struct/union
1348fields within structs/unions}, for details.
1349
1350@item -trigraphs
1351@opindex trigraphs
1352Support ISO C trigraphs. The @option{-ansi} option (and @option{-std}
1353options for strict ISO C conformance) implies @option{-trigraphs}.
1354
1355@item -no-integrated-cpp
1356@opindex no-integrated-cpp
1357Performs a compilation in two passes: preprocessing and compiling. This
1358option allows a user supplied "cc1", "cc1plus", or "cc1obj" via the
1359@option{-B} option. The user supplied compilation step can then add in
1360an additional preprocessing step after normal preprocessing but before
1361compiling. The default is to use the integrated cpp (internal cpp)
1362
1363The semantics of this option will change if "cc1", "cc1plus", and
1364"cc1obj" are merged.
1365
1366@cindex traditional C language
1367@cindex C language, traditional
1368@item -traditional
1369@itemx -traditional-cpp
1370@opindex traditional-cpp
1371@opindex traditional
1372Formerly, these options caused GCC to attempt to emulate a pre-standard
1373C compiler. They are now only supported with the @option{-E} switch.
1374The preprocessor continues to support a pre-standard mode. See the GNU
1375CPP manual for details.
1376
1377@item -fcond-mismatch
1378@opindex fcond-mismatch
1379Allow conditional expressions with mismatched types in the second and
1380third arguments. The value of such an expression is void. This option
1381is not supported for C++.
1382
1383@item -funsigned-char
1384@opindex funsigned-char
1385Let the type @code{char} be unsigned, like @code{unsigned char}.
1386
1387Each kind of machine has a default for what @code{char} should
1388be. It is either like @code{unsigned char} by default or like
1389@code{signed char} by default.
1390
1391Ideally, a portable program should always use @code{signed char} or
1392@code{unsigned char} when it depends on the signedness of an object.
1393But many programs have been written to use plain @code{char} and
1394expect it to be signed, or expect it to be unsigned, depending on the
1395machines they were written for. This option, and its inverse, let you
1396make such a program work with the opposite default.
1397
1398The type @code{char} is always a distinct type from each of
1399@code{signed char} or @code{unsigned char}, even though its behavior
1400is always just like one of those two.
1401
1402@item -fsigned-char
1403@opindex fsigned-char
1404Let the type @code{char} be signed, like @code{signed char}.
1405
1406Note that this is equivalent to @option{-fno-unsigned-char}, which is
1407the negative form of @option{-funsigned-char}. Likewise, the option
1408@option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
1409
1410@item -fsigned-bitfields
1411@itemx -funsigned-bitfields
1412@itemx -fno-signed-bitfields
1413@itemx -fno-unsigned-bitfields
1414@opindex fsigned-bitfields
1415@opindex funsigned-bitfields
1416@opindex fno-signed-bitfields
1417@opindex fno-unsigned-bitfields
1418These options control whether a bit-field is signed or unsigned, when the
1419declaration does not use either @code{signed} or @code{unsigned}. By
1420default, such a bit-field is signed, because this is consistent: the
1421basic integer types such as @code{int} are signed types.
1422@end table
1423
1424@node C++ Dialect Options
1425@section Options Controlling C++ Dialect
1426
1427@cindex compiler options, C++
1428@cindex C++ options, command line
1429@cindex options, C++
1430This section describes the command-line options that are only meaningful
1431for C++ programs; but you can also use most of the GNU compiler options
1432regardless of what language your program is in. For example, you
1433might compile a file @code{firstClass.C} like this:
1434
1435@smallexample
1436g++ -g -frepo -O -c firstClass.C
1437@end smallexample
1438
1439@noindent
1440In this example, only @option{-frepo} is an option meant
1441only for C++ programs; you can use the other options with any
1442language supported by GCC@.
1443
1444Here is a list of options that are @emph{only} for compiling C++ programs:
1445
1446@table @gcctabopt
1447
1448@item -fabi-version=@var{n}
1449@opindex fabi-version
1450Use version @var{n} of the C++ ABI@. Version 2 is the version of the
1451C++ ABI that first appeared in G++ 3.4. Version 1 is the version of
1452the C++ ABI that first appeared in G++ 3.2. Version 0 will always be
1453the version that conforms most closely to the C++ ABI specification.
1454Therefore, the ABI obtained using version 0 will change as ABI bugs
1455are fixed.
1456
1457The default is version 2.
1458
1459@item -fno-access-control
1460@opindex fno-access-control
1461Turn off all access checking. This switch is mainly useful for working
1462around bugs in the access control code.
1463
1464@item -fcheck-new
1465@opindex fcheck-new
1466Check that the pointer returned by @code{operator new} is non-null
1467before attempting to modify the storage allocated. This check is
1468normally unnecessary because the C++ standard specifies that
1469@code{operator new} will only return @code{0} if it is declared
1470@samp{throw()}, in which case the compiler will always check the
1471return value even without this option. In all other cases, when
1472@code{operator new} has a non-empty exception specification, memory
1473exhaustion is signalled by throwing @code{std::bad_alloc}. See also
1474@samp{new (nothrow)}.
1475
1476@item -fconserve-space
1477@opindex fconserve-space
1478Put uninitialized or runtime-initialized global variables into the
1479common segment, as C does. This saves space in the executable at the
1480cost of not diagnosing duplicate definitions. If you compile with this
1481flag and your program mysteriously crashes after @code{main()} has
1482completed, you may have an object that is being destroyed twice because
1483two definitions were merged.
1484
1485This option is no longer useful on most targets, now that support has
1486been added for putting variables into BSS without making them common.
1487
1488@item -ffriend-injection
1489@opindex ffriend-injection
1490Inject friend functions into the enclosing namespace, so that they are
1491visible outside the scope of the class in which they are declared.
1492Friend functions were documented to work this way in the old Annotated
1493C++ Reference Manual, and versions of G++ before 4.1 always worked
1494that way. However, in ISO C++ a friend function which is not declared
1495in an enclosing scope can only be found using argument dependent
1496lookup. This option causes friends to be injected as they were in
1497earlier releases.
1498
1499This option is for compatibility, and may be removed in a future
1500release of G++.
1501
1502@item -fno-elide-constructors
1503@opindex fno-elide-constructors
1504The C++ standard allows an implementation to omit creating a temporary
1505which is only used to initialize another object of the same type.
1506Specifying this option disables that optimization, and forces G++ to
1507call the copy constructor in all cases.
1508
1509@item -fno-enforce-eh-specs
1510@opindex fno-enforce-eh-specs
1511Don't generate code to check for violation of exception specifications
1512at runtime. This option violates the C++ standard, but may be useful
1513for reducing code size in production builds, much like defining
1514@samp{NDEBUG}. This does not give user code permission to throw
1515exceptions in violation of the exception specifications; the compiler
1516will still optimize based on the specifications, so throwing an
1517unexpected exception will result in undefined behavior.
1518
1519@item -ffor-scope
1520@itemx -fno-for-scope
1521@opindex ffor-scope
1522@opindex fno-for-scope
1523If @option{-ffor-scope} is specified, the scope of variables declared in
1524a @i{for-init-statement} is limited to the @samp{for} loop itself,
1525as specified by the C++ standard.
1526If @option{-fno-for-scope} is specified, the scope of variables declared in
1527a @i{for-init-statement} extends to the end of the enclosing scope,
1528as was the case in old versions of G++, and other (traditional)
1529implementations of C++.
1530
1531The default if neither flag is given to follow the standard,
1532but to allow and give a warning for old-style code that would
1533otherwise be invalid, or have different behavior.
1534
1535@item -fno-gnu-keywords
1536@opindex fno-gnu-keywords
1537Do not recognize @code{typeof} as a keyword, so that code can use this
1538word as an identifier. You can use the keyword @code{__typeof__} instead.
1539@option{-ansi} implies @option{-fno-gnu-keywords}.
1540
1541@item -fno-implicit-templates
1542@opindex fno-implicit-templates
1543Never emit code for non-inline templates which are instantiated
1544implicitly (i.e.@: by use); only emit code for explicit instantiations.
1545@xref{Template Instantiation}, for more information.
1546
1547@item -fno-implicit-inline-templates
1548@opindex fno-implicit-inline-templates
1549Don't emit code for implicit instantiations of inline templates, either.
1550The default is to handle inlines differently so that compiles with and
1551without optimization will need the same set of explicit instantiations.
1552
1553@item -fno-implement-inlines
1554@opindex fno-implement-inlines
1555To save space, do not emit out-of-line copies of inline functions
1556controlled by @samp{#pragma implementation}. This will cause linker
1557errors if these functions are not inlined everywhere they are called.
1558
1559@item -fms-extensions
1560@opindex fms-extensions
1561Disable pedantic warnings about constructs used in MFC, such as implicit
1562int and getting a pointer to member function via non-standard syntax.
1563
1564@item -fno-nonansi-builtins
1565@opindex fno-nonansi-builtins
1566Disable built-in declarations of functions that are not mandated by
1567ANSI/ISO C@. These include @code{ffs}, @code{alloca}, @code{_exit},
1568@code{index}, @code{bzero}, @code{conjf}, and other related functions.
1569
1570@item -fno-operator-names
1571@opindex fno-operator-names
1572Do not treat the operator name keywords @code{and}, @code{bitand},
1573@code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1574synonyms as keywords.
1575
1576@item -fno-optional-diags
1577@opindex fno-optional-diags
1578Disable diagnostics that the standard says a compiler does not need to
1579issue. Currently, the only such diagnostic issued by G++ is the one for
1580a name having multiple meanings within a class.
1581
1582@item -fpermissive
1583@opindex fpermissive
1584Downgrade some diagnostics about nonconformant code from errors to
1585warnings. Thus, using @option{-fpermissive} will allow some
1586nonconforming code to compile.
1587
1588@item -frepo
1589@opindex frepo
1590Enable automatic template instantiation at link time. This option also
1591implies @option{-fno-implicit-templates}. @xref{Template
1592Instantiation}, for more information.
1593
1594@item -fno-rtti
1595@opindex fno-rtti
1596Disable generation of information about every class with virtual
1597functions for use by the C++ runtime type identification features
1598(@samp{dynamic_cast} and @samp{typeid}). If you don't use those parts
1599of the language, you can save some space by using this flag. Note that
1600exception handling uses the same information, but it will generate it as
1601needed. The @samp{dynamic_cast} operator can still be used for casts that
1602do not require runtime type information, i.e. casts to @code{void *} or to
1603unambiguous base classes.
1604
1605@item -fstats
1606@opindex fstats
1607Emit statistics about front-end processing at the end of the compilation.
1608This information is generally only useful to the G++ development team.
1609
1610@item -ftemplate-depth-@var{n}
1611@opindex ftemplate-depth
1612Set the maximum instantiation depth for template classes to @var{n}.
1613A limit on the template instantiation depth is needed to detect
1614endless recursions during template class instantiation. ANSI/ISO C++
1615conforming programs must not rely on a maximum depth greater than 17.
1616
1617@item -fno-threadsafe-statics
1618@opindex fno-threadsafe-statics
1619Do not emit the extra code to use the routines specified in the C++
1620ABI for thread-safe initialization of local statics. You can use this
1621option to reduce code size slightly in code that doesn't need to be
1622thread-safe.
1623
1624@item -fuse-cxa-atexit
1625@opindex fuse-cxa-atexit
1626Register destructors for objects with static storage duration with the
1627@code{__cxa_atexit} function rather than the @code{atexit} function.
1628This option is required for fully standards-compliant handling of static
1629destructors, but will only work if your C library supports
1630@code{__cxa_atexit}.
1631
1632@item -fno-use-cxa-get-exception-ptr
1633@opindex fno-use-cxa-get-exception-ptr
1634Don't use the @code{__cxa_get_exception_ptr} runtime routine. This
1635will cause @code{std::uncaught_exception} to be incorrect, but is necessary
1636if the runtime routine is not available.
1637
1638@item -fvisibility-inlines-hidden
1639@opindex fvisibility-inlines-hidden
1640This switch declares that the user does not attempt to compare
1641pointers to inline methods where the addresses of the two functions
1642were taken in different shared objects.
1643
1644The effect of this is that GCC may, effectively, mark inline methods with
1645@code{__attribute__ ((visibility ("hidden")))} so that they do not
1646appear in the export table of a DSO and do not require a PLT indirection
1647when used within the DSO@. Enabling this option can have a dramatic effect
1648on load and link times of a DSO as it massively reduces the size of the
1649dynamic export table when the library makes heavy use of templates.
1650
1651The behaviour of this switch is not quite the same as marking the
1652methods as hidden directly, because it does not affect static variables
1653local to the function or cause the compiler to deduce that
1654the function is defined in only one shared object.
1655
1656You may mark a method as having a visibility explicitly to negate the
1657effect of the switch for that method. For example, if you do want to
1658compare pointers to a particular inline method, you might mark it as
1659having default visibility. Marking the enclosing class with explicit
1660visibility will have no effect.
1661
1662Explicitly instantiated inline methods are unaffected by this option
1663as their linkage might otherwise cross a shared library boundary.
1664@xref{Template Instantiation}.
1665
1666@item -fno-weak
1667@opindex fno-weak
1668Do not use weak symbol support, even if it is provided by the linker.
1669By default, G++ will use weak symbols if they are available. This
1670option exists only for testing, and should not be used by end-users;
1671it will result in inferior code and has no benefits. This option may
1672be removed in a future release of G++.
1673
1674@item -nostdinc++
1675@opindex nostdinc++
1676Do not search for header files in the standard directories specific to
1677C++, but do still search the other standard directories. (This option
1678is used when building the C++ library.)
1679@end table
1680
1681In addition, these optimization, warning, and code generation options
1682have meanings only for C++ programs:
1683
1684@table @gcctabopt
1685@item -fno-default-inline
1686@opindex fno-default-inline
1687Do not assume @samp{inline} for functions defined inside a class scope.
1688@xref{Optimize Options,,Options That Control Optimization}. Note that these
1689functions will have linkage like inline functions; they just won't be
1690inlined by default.
1691
1692@item -Wabi @r{(C++ only)}
1693@opindex Wabi
1694Warn when G++ generates code that is probably not compatible with the
1695vendor-neutral C++ ABI@. Although an effort has been made to warn about
1696all such cases, there are probably some cases that are not warned about,
1697even though G++ is generating incompatible code. There may also be
1698cases where warnings are emitted even though the code that is generated
1699will be compatible.
1700
1701You should rewrite your code to avoid these warnings if you are
1702concerned about the fact that code generated by G++ may not be binary
1703compatible with code generated by other compilers.
1704
1705The known incompatibilities at this point include:
1706
1707@itemize @bullet
1708
1709@item
1710Incorrect handling of tail-padding for bit-fields. G++ may attempt to
1711pack data into the same byte as a base class. For example:
1712
1713@smallexample
1714struct A @{ virtual void f(); int f1 : 1; @};
1715struct B : public A @{ int f2 : 1; @};
1716@end smallexample
1717
1718@noindent
1719In this case, G++ will place @code{B::f2} into the same byte
1720as@code{A::f1}; other compilers will not. You can avoid this problem
1721by explicitly padding @code{A} so that its size is a multiple of the
1722byte size on your platform; that will cause G++ and other compilers to
1723layout @code{B} identically.
1724
1725@item
1726Incorrect handling of tail-padding for virtual bases. G++ does not use
1727tail padding when laying out virtual bases. For example:
1728
1729@smallexample
1730struct A @{ virtual void f(); char c1; @};
1731struct B @{ B(); char c2; @};
1732struct C : public A, public virtual B @{@};
1733@end smallexample
1734
1735@noindent
1736In this case, G++ will not place @code{B} into the tail-padding for
1737@code{A}; other compilers will. You can avoid this problem by
1738explicitly padding @code{A} so that its size is a multiple of its
1739alignment (ignoring virtual base classes); that will cause G++ and other
1740compilers to layout @code{C} identically.
1741
1742@item
1743Incorrect handling of bit-fields with declared widths greater than that
1744of their underlying types, when the bit-fields appear in a union. For
1745example:
1746
1747@smallexample
1748union U @{ int i : 4096; @};
1749@end smallexample
1750
1751@noindent
1752Assuming that an @code{int} does not have 4096 bits, G++ will make the
1753union too small by the number of bits in an @code{int}.
1754
1755@item
1756Empty classes can be placed at incorrect offsets. For example:
1757
1758@smallexample
1759struct A @{@};
1760
1761struct B @{
1762 A a;
1763 virtual void f ();
1764@};
1765
1766struct C : public B, public A @{@};
1767@end smallexample
1768
1769@noindent
1770G++ will place the @code{A} base class of @code{C} at a nonzero offset;
1771it should be placed at offset zero. G++ mistakenly believes that the
1772@code{A} data member of @code{B} is already at offset zero.
1773
1774@item
1775Names of template functions whose types involve @code{typename} or
1776template template parameters can be mangled incorrectly.
1777
1778@smallexample
1779template <typename Q>
1780void f(typename Q::X) @{@}
1781
1782template <template <typename> class Q>
1783void f(typename Q<int>::X) @{@}
1784@end smallexample
1785
1786@noindent
1787Instantiations of these templates may be mangled incorrectly.
1788
1789@end itemize
1790
1791@item -Wctor-dtor-privacy @r{(C++ only)}
1792@opindex Wctor-dtor-privacy
1793Warn when a class seems unusable because all the constructors or
1794destructors in that class are private, and it has neither friends nor
1795public static member functions.
1796
1797@item -Wnon-virtual-dtor @r{(C++ only)}
1798@opindex Wnon-virtual-dtor
1799Warn when a class appears to be polymorphic, thereby requiring a virtual
1800destructor, yet it declares a non-virtual one. This warning is also
1801enabled if -Weffc++ is specified.
1802
1803@item -Wreorder @r{(C++ only)}
1804@opindex Wreorder
1805@cindex reordering, warning
1806@cindex warning for reordering of member initializers
1807Warn when the order of member initializers given in the code does not
1808match the order in which they must be executed. For instance:
1809
1810@smallexample
1811struct A @{
1812 int i;
1813 int j;
1814 A(): j (0), i (1) @{ @}
1815@};
1816@end smallexample
1817
1818The compiler will rearrange the member initializers for @samp{i}
1819and @samp{j} to match the declaration order of the members, emitting
1820a warning to that effect. This warning is enabled by @option{-Wall}.
1821@end table
1822
1823The following @option{-W@dots{}} options are not affected by @option{-Wall}.
1824
1825@table @gcctabopt
1826@item -Weffc++ @r{(C++ only)}
1827@opindex Weffc++
1828Warn about violations of the following style guidelines from Scott Meyers'
1829@cite{Effective C++} book:
1830
1831@itemize @bullet
1832@item
1833Item 11: Define a copy constructor and an assignment operator for classes
1834with dynamically allocated memory.
1835
1836@item
1837Item 12: Prefer initialization to assignment in constructors.
1838
1839@item
1840Item 14: Make destructors virtual in base classes.
1841
1842@item
1843Item 15: Have @code{operator=} return a reference to @code{*this}.
1844
1845@item
1846Item 23: Don't try to return a reference when you must return an object.
1847
1848@end itemize
1849
1850Also warn about violations of the following style guidelines from
1851Scott Meyers' @cite{More Effective C++} book:
1852
1853@itemize @bullet
1854@item
1855Item 6: Distinguish between prefix and postfix forms of increment and
1856decrement operators.
1857
1858@item
1859Item 7: Never overload @code{&&}, @code{||}, or @code{,}.
1860
1861@end itemize
1862
1863When selecting this option, be aware that the standard library
1864headers do not obey all of these guidelines; use @samp{grep -v}
1865to filter out those warnings.
1866
1867@item -Wno-deprecated @r{(C++ only)}
1868@opindex Wno-deprecated
1869Do not warn about usage of deprecated features. @xref{Deprecated Features}.
1870
1871@item -Wstrict-null-sentinel @r{(C++ only)}
1872@opindex Wstrict-null-sentinel
1873Warn also about the use of an uncasted @code{NULL} as sentinel. When
1874compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
1875to @code{__null}. Although it is a null pointer constant not a null pointer,
1876it is guaranteed to of the same size as a pointer. But this use is
1877not portable across different compilers.
1878
1879@item -Wno-non-template-friend @r{(C++ only)}
1880@opindex Wno-non-template-friend
1881Disable warnings when non-templatized friend functions are declared
1882within a template. Since the advent of explicit template specification
1883support in G++, if the name of the friend is an unqualified-id (i.e.,
1884@samp{friend foo(int)}), the C++ language specification demands that the
1885friend declare or define an ordinary, nontemplate function. (Section
188614.5.3). Before G++ implemented explicit specification, unqualified-ids
1887could be interpreted as a particular specialization of a templatized
1888function. Because this non-conforming behavior is no longer the default
1889behavior for G++, @option{-Wnon-template-friend} allows the compiler to
1890check existing code for potential trouble spots and is on by default.
1891This new compiler behavior can be turned off with
1892@option{-Wno-non-template-friend} which keeps the conformant compiler code
1893but disables the helpful warning.
1894
1895@item -Wold-style-cast @r{(C++ only)}
1896@opindex Wold-style-cast
1897Warn if an old-style (C-style) cast to a non-void type is used within
1898a C++ program. The new-style casts (@samp{dynamic_cast},
1899@samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are
1900less vulnerable to unintended effects and much easier to search for.
1901
1902@item -Woverloaded-virtual @r{(C++ only)}
1903@opindex Woverloaded-virtual
1904@cindex overloaded virtual fn, warning
1905@cindex warning for overloaded virtual fn
1906Warn when a function declaration hides virtual functions from a
1907base class. For example, in:
1908
1909@smallexample
1910struct A @{
1911 virtual void f();
1912@};
1913
1914struct B: public A @{
1915 void f(int);
1916@};
1917@end smallexample
1918
1919the @code{A} class version of @code{f} is hidden in @code{B}, and code
1920like:
1921
1922@smallexample
1923B* b;
1924b->f();
1925@end smallexample
1926
1927will fail to compile.
1928
1929@item -Wno-pmf-conversions @r{(C++ only)}
1930@opindex Wno-pmf-conversions
1931Disable the diagnostic for converting a bound pointer to member function
1932to a plain pointer.
1933
1934@item -Wsign-promo @r{(C++ only)}
1935@opindex Wsign-promo
1936Warn when overload resolution chooses a promotion from unsigned or
1937enumerated type to a signed type, over a conversion to an unsigned type of
1938the same size. Previous versions of G++ would try to preserve
1939unsignedness, but the standard mandates the current behavior.
1940
1941@smallexample
1942struct A @{
1943 operator int ();
1944 A& operator = (int);
1945@};
1946
1947main ()
1948@{
1949 A a,b;
1950 a = b;
1951@}
1952@end smallexample
1953
1954In this example, G++ will synthesize a default @samp{A& operator =
1955(const A&);}, while cfront will use the user-defined @samp{operator =}.
1956@end table
1957
1958@node Objective-C and Objective-C++ Dialect Options
1959@section Options Controlling Objective-C and Objective-C++ Dialects
1960
1961@cindex compiler options, Objective-C and Objective-C++
1962@cindex Objective-C and Objective-C++ options, command line
1963@cindex options, Objective-C and Objective-C++
1964(NOTE: This manual does not describe the Objective-C and Objective-C++
1965languages themselves. See @xref{Standards,,Language Standards
1966Supported by GCC}, for references.)
1967
1968This section describes the command-line options that are only meaningful
1969for Objective-C and Objective-C++ programs, but you can also use most of
1970the language-independent GNU compiler options.
1971For example, you might compile a file @code{some_class.m} like this:
1972
1973@smallexample
1974gcc -g -fgnu-runtime -O -c some_class.m
1975@end smallexample
1976
1977@noindent
1978In this example, @option{-fgnu-runtime} is an option meant only for
1979Objective-C and Objective-C++ programs; you can use the other options with
1980any language supported by GCC@.
1981
1982Note that since Objective-C is an extension of the C language, Objective-C
1983compilations may also use options specific to the C front-end (e.g.,
1984@option{-Wtraditional}). Similarly, Objective-C++ compilations may use
1985C++-specific options (e.g., @option{-Wabi}).
1986
1987Here is a list of options that are @emph{only} for compiling Objective-C
1988and Objective-C++ programs:
1989
1990@table @gcctabopt
1991@item -fconstant-string-class=@var{class-name}
1992@opindex fconstant-string-class
1993Use @var{class-name} as the name of the class to instantiate for each
1994literal string specified with the syntax @code{@@"@dots{}"}. The default
1995class name is @code{NXConstantString} if the GNU runtime is being used, and
1996@code{NSConstantString} if the NeXT runtime is being used (see below). The
1997@option{-fconstant-cfstrings} option, if also present, will override the
1998@option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} literals
1999to be laid out as constant CoreFoundation strings.
2000
2001@item -fgnu-runtime
2002@opindex fgnu-runtime
2003Generate object code compatible with the standard GNU Objective-C
2004runtime. This is the default for most types of systems.
2005
2006@item -fnext-runtime
2007@opindex fnext-runtime
2008Generate output compatible with the NeXT runtime. This is the default
2009for NeXT-based systems, including Darwin and Mac OS X@. The macro
2010@code{__NEXT_RUNTIME__} is predefined if (and only if) this option is
2011used.
2012
2013@item -fno-nil-receivers
2014@opindex fno-nil-receivers
2015Assume that all Objective-C message dispatches (e.g.,
2016@code{[receiver message:arg]}) in this translation unit ensure that the receiver
2017is not @code{nil}. This allows for more efficient entry points in the runtime
2018to be used. Currently, this option is only available in conjunction with
2019the NeXT runtime on Mac OS X 10.3 and later.
2020
2021@item -fobjc-call-cxx-cdtors
2022@opindex fobjc-call-cxx-cdtors
2023For each Objective-C class, check if any of its instance variables is a
2024C++ object with a non-trivial default constructor. If so, synthesize a
2025special @code{- (id) .cxx_construct} instance method that will run
2026non-trivial default constructors on any such instance variables, in order,
2027and then return @code{self}. Similarly, check if any instance variable
2028is a C++ object with a non-trivial destructor, and if so, synthesize a
2029special @code{- (void) .cxx_destruct} method that will run
2030all such default destructors, in reverse order.
2031
2032The @code{- (id) .cxx_construct} and/or @code{- (void) .cxx_destruct} methods
2033thusly generated will only operate on instance variables declared in the
2034current Objective-C class, and not those inherited from superclasses. It
2035is the responsibility of the Objective-C runtime to invoke all such methods
2036in an object's inheritance hierarchy. The @code{- (id) .cxx_construct} methods
2037will be invoked by the runtime immediately after a new object
2038instance is allocated; the @code{- (void) .cxx_destruct} methods will
2039be invoked immediately before the runtime deallocates an object instance.
2040
2041As of this writing, only the NeXT runtime on Mac OS X 10.4 and later has
2042support for invoking the @code{- (id) .cxx_construct} and
2043@code{- (void) .cxx_destruct} methods.
2044
2045@item -fobjc-direct-dispatch
2046@opindex fobjc-direct-dispatch
2047Allow fast jumps to the message dispatcher. On Darwin this is
2048accomplished via the comm page.
2049
2050@item -fobjc-exceptions
2051@opindex fobjc-exceptions
2052Enable syntactic support for structured exception handling in Objective-C,
2053similar to what is offered by C++ and Java. This option is
2054unavailable in conjunction with the NeXT runtime on Mac OS X 10.2 and
2055earlier.
2056
2057@smallexample
2058 @@try @{
2059 @dots{}
2060 @@throw expr;
2061 @dots{}
2062 @}
2063 @@catch (AnObjCClass *exc) @{
2064 @dots{}
2065 @@throw expr;
2066 @dots{}
2067 @@throw;
2068 @dots{}
2069 @}
2070 @@catch (AnotherClass *exc) @{
2071 @dots{}
2072 @}
2073 @@catch (id allOthers) @{
2074 @dots{}
2075 @}
2076 @@finally @{
2077 @dots{}
2078 @@throw expr;
2079 @dots{}
2080 @}
2081@end smallexample
2082
2083The @code{@@throw} statement may appear anywhere in an Objective-C or
2084Objective-C++ program; when used inside of a @code{@@catch} block, the
2085@code{@@throw} may appear without an argument (as shown above), in which case
2086the object caught by the @code{@@catch} will be rethrown.
2087
2088Note that only (pointers to) Objective-C objects may be thrown and
2089caught using this scheme. When an object is thrown, it will be caught
2090by the nearest @code{@@catch} clause capable of handling objects of that type,
2091analogously to how @code{catch} blocks work in C++ and Java. A
2092@code{@@catch(id @dots{})} clause (as shown above) may also be provided to catch
2093any and all Objective-C exceptions not caught by previous @code{@@catch}
2094clauses (if any).
2095
2096The @code{@@finally} clause, if present, will be executed upon exit from the
2097immediately preceding @code{@@try @dots{} @@catch} section. This will happen
2098regardless of whether any exceptions are thrown, caught or rethrown
2099inside the @code{@@try @dots{} @@catch} section, analogously to the behavior
2100of the @code{finally} clause in Java.
2101
2102There are several caveats to using the new exception mechanism:
2103
2104@itemize @bullet
2105@item
2106Although currently designed to be binary compatible with @code{NS_HANDLER}-style
2107idioms provided by the @code{NSException} class, the new
2108exceptions can only be used on Mac OS X 10.3 (Panther) and later
2109systems, due to additional functionality needed in the (NeXT) Objective-C
2110runtime.
2111
2112@item
2113As mentioned above, the new exceptions do not support handling
2114types other than Objective-C objects. Furthermore, when used from
2115Objective-C++, the Objective-C exception model does not interoperate with C++
2116exceptions at this time. This means you cannot @code{@@throw} an exception
2117from Objective-C and @code{catch} it in C++, or vice versa
2118(i.e., @code{throw @dots{} @@catch}).
2119@end itemize
2120
2121The @option{-fobjc-exceptions} switch also enables the use of synchronization
2122blocks for thread-safe execution:
2123
2124@smallexample
2125 @@synchronized (ObjCClass *guard) @{
2126 @dots{}
2127 @}
2128@end smallexample
2129
2130Upon entering the @code{@@synchronized} block, a thread of execution shall
2131first check whether a lock has been placed on the corresponding @code{guard}
2132object by another thread. If it has, the current thread shall wait until
2133the other thread relinquishes its lock. Once @code{guard} becomes available,
2134the current thread will place its own lock on it, execute the code contained in
2135the @code{@@synchronized} block, and finally relinquish the lock (thereby
2136making @code{guard} available to other threads).
2137
2138Unlike Java, Objective-C does not allow for entire methods to be marked
2139@code{@@synchronized}. Note that throwing exceptions out of
2140@code{@@synchronized} blocks is allowed, and will cause the guarding object
2141to be unlocked properly.
2142
2143@item -fobjc-gc
2144@opindex fobjc-gc
2145Enable garbage collection (GC) in Objective-C and Objective-C++ programs.
2146
2147@item -freplace-objc-classes
2148@opindex freplace-objc-classes
2149Emit a special marker instructing @command{ld(1)} not to statically link in
2150the resulting object file, and allow @command{dyld(1)} to load it in at
2151run time instead. This is used in conjunction with the Fix-and-Continue
2152debugging mode, where the object file in question may be recompiled and
2153dynamically reloaded in the course of program execution, without the need
2154to restart the program itself. Currently, Fix-and-Continue functionality
2155is only available in conjunction with the NeXT runtime on Mac OS X 10.3
2156and later.
2157
2158@item -fzero-link
2159@opindex fzero-link
2160When compiling for the NeXT runtime, the compiler ordinarily replaces calls
2161to @code{objc_getClass("@dots{}")} (when the name of the class is known at
2162compile time) with static class references that get initialized at load time,
2163which improves run-time performance. Specifying the @option{-fzero-link} flag
2164suppresses this behavior and causes calls to @code{objc_getClass("@dots{}")}
2165to be retained. This is useful in Zero-Link debugging mode, since it allows
2166for individual class implementations to be modified during program execution.
2167
2168@item -gen-decls
2169@opindex gen-decls
2170Dump interface declarations for all classes seen in the source file to a
2171file named @file{@var{sourcename}.decl}.
2172
2173@item -Wassign-intercept
2174@opindex Wassign-intercept
2175Warn whenever an Objective-C assignment is being intercepted by the
2176garbage collector.
2177
2178@item -Wno-protocol
2179@opindex Wno-protocol
2180If a class is declared to implement a protocol, a warning is issued for
2181every method in the protocol that is not implemented by the class. The
2182default behavior is to issue a warning for every method not explicitly
2183implemented in the class, even if a method implementation is inherited
2184from the superclass. If you use the @option{-Wno-protocol} option, then
2185methods inherited from the superclass are considered to be implemented,
2186and no warning is issued for them.
2187
2188@item -Wselector
2189@opindex Wselector
2190Warn if multiple methods of different types for the same selector are
2191found during compilation. The check is performed on the list of methods
2192in the final stage of compilation. Additionally, a check is performed
2193for each selector appearing in a @code{@@selector(@dots{})}
2194expression, and a corresponding method for that selector has been found
2195during compilation. Because these checks scan the method table only at
2196the end of compilation, these warnings are not produced if the final
2197stage of compilation is not reached, for example because an error is
2198found during compilation, or because the @option{-fsyntax-only} option is
2199being used.
2200
2201@item -Wstrict-selector-match
2202@opindex Wstrict-selector-match
2203Warn if multiple methods with differing argument and/or return types are
2204found for a given selector when attempting to send a message using this
2205selector to a receiver of type @code{id} or @code{Class}. When this flag
2206is off (which is the default behavior), the compiler will omit such warnings
2207if any differences found are confined to types which share the same size
2208and alignment.
2209
2210@item -Wundeclared-selector
2211@opindex Wundeclared-selector
2212Warn if a @code{@@selector(@dots{})} expression referring to an
2213undeclared selector is found. A selector is considered undeclared if no
2214method with that name has been declared before the
2215@code{@@selector(@dots{})} expression, either explicitly in an
2216@code{@@interface} or @code{@@protocol} declaration, or implicitly in
2217an @code{@@implementation} section. This option always performs its
2218checks as soon as a @code{@@selector(@dots{})} expression is found,
2219while @option{-Wselector} only performs its checks in the final stage of
2220compilation. This also enforces the coding style convention
2221that methods and selectors must be declared before being used.
2222
2223@item -print-objc-runtime-info
2224@opindex print-objc-runtime-info
2225Generate C header describing the largest structure that is passed by
2226value, if any.
2227
2228@end table
2229
2230@node Language Independent Options
2231@section Options to Control Diagnostic Messages Formatting
2232@cindex options to control diagnostics formatting
2233@cindex diagnostic messages
2234@cindex message formatting
2235
2236Traditionally, diagnostic messages have been formatted irrespective of
2237the output device's aspect (e.g.@: its width, @dots{}). The options described
2238below can be used to control the diagnostic messages formatting
2239algorithm, e.g.@: how many characters per line, how often source location
2240information should be reported. Right now, only the C++ front end can
2241honor these options. However it is expected, in the near future, that
2242the remaining front ends would be able to digest them correctly.
2243
2244@table @gcctabopt
2245@item -fmessage-length=@var{n}
2246@opindex fmessage-length
2247Try to format error messages so that they fit on lines of about @var{n}
2248characters. The default is 72 characters for @command{g++} and 0 for the rest of
2249the front ends supported by GCC@. If @var{n} is zero, then no
2250line-wrapping will be done; each error message will appear on a single
2251line.
2252
2253@opindex fdiagnostics-show-location
2254@item -fdiagnostics-show-location=once
2255Only meaningful in line-wrapping mode. Instructs the diagnostic messages
2256reporter to emit @emph{once} source location information; that is, in
2257case the message is too long to fit on a single physical line and has to
2258be wrapped, the source location won't be emitted (as prefix) again,
2259over and over, in subsequent continuation lines. This is the default
2260behavior.
2261
2262@item -fdiagnostics-show-location=every-line
2263Only meaningful in line-wrapping mode. Instructs the diagnostic
2264messages reporter to emit the same source location information (as
2265prefix) for physical lines that result from the process of breaking
2266a message which is too long to fit on a single line.
2267
2268@item -fdiagnostics-show-option
2269@opindex fdiagnostics-show-option
2270This option instructs the diagnostic machinery to add text to each
2271diagnostic emitted, which indicates which command line option directly
2272controls that diagnostic, when such an option is known to the
2273diagnostic machinery.
2274
2275@end table
2276
2277@node Warning Options
2278@section Options to Request or Suppress Warnings
2279@cindex options to control warnings
2280@cindex warning messages
2281@cindex messages, warning
2282@cindex suppressing warnings
2283
2284Warnings are diagnostic messages that report constructions which
2285are not inherently erroneous but which are risky or suggest there
2286may have been an error.
2287
2288You can request many specific warnings with options beginning @samp{-W},
2289for example @option{-Wimplicit} to request warnings on implicit
2290declarations. Each of these specific warning options also has a
2291negative form beginning @samp{-Wno-} to turn off warnings;
2292for example, @option{-Wno-implicit}. This manual lists only one of the
2293two forms, whichever is not the default.
2294
2295The following options control the amount and kinds of warnings produced
2296by GCC; for further, language-specific options also refer to
2297@ref{C++ Dialect Options} and @ref{Objective-C and Objective-C++ Dialect
2298Options}.
2299
2300@table @gcctabopt
2301@cindex syntax checking
2302@item -fsyntax-only
2303@opindex fsyntax-only
2304Check the code for syntax errors, but don't do anything beyond that.
2305
2306@item -pedantic
2307@opindex pedantic
2308Issue all the warnings demanded by strict ISO C and ISO C++;
2309reject all programs that use forbidden extensions, and some other
2310programs that do not follow ISO C and ISO C++. For ISO C, follows the
2311version of the ISO C standard specified by any @option{-std} option used.
2312
2313Valid ISO C and ISO C++ programs should compile properly with or without
2314this option (though a rare few will require @option{-ansi} or a
2315@option{-std} option specifying the required version of ISO C)@. However,
2316without this option, certain GNU extensions and traditional C and C++
2317features are supported as well. With this option, they are rejected.
2318
2319@option{-pedantic} does not cause warning messages for use of the
2320alternate keywords whose names begin and end with @samp{__}. Pedantic
2321warnings are also disabled in the expression that follows
2322@code{__extension__}. However, only system header files should use
2323these escape routes; application programs should avoid them.
2324@xref{Alternate Keywords}.
2325
2326Some users try to use @option{-pedantic} to check programs for strict ISO
2327C conformance. They soon find that it does not do quite what they want:
2328it finds some non-ISO practices, but not all---only those for which
2329ISO C @emph{requires} a diagnostic, and some others for which
2330diagnostics have been added.
2331
2332A feature to report any failure to conform to ISO C might be useful in
2333some instances, but would require considerable additional work and would
2334be quite different from @option{-pedantic}. We don't have plans to
2335support such a feature in the near future.
2336
2337Where the standard specified with @option{-std} represents a GNU
2338extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
2339corresponding @dfn{base standard}, the version of ISO C on which the GNU
2340extended dialect is based. Warnings from @option{-pedantic} are given
2341where they are required by the base standard. (It would not make sense
2342for such warnings to be given only for features not in the specified GNU
2343C dialect, since by definition the GNU dialects of C include all
2344features the compiler supports with the given option, and there would be
2345nothing to warn about.)
2346
2347@item -pedantic-errors
2348@opindex pedantic-errors
2349Like @option{-pedantic}, except that errors are produced rather than
2350warnings.
2351
2352@item -w
2353@opindex w
2354Inhibit all warning messages.
2355
2356@item -Wno-import
2357@opindex Wno-import
2358Inhibit warning messages about the use of @samp{#import}.
2359
2360@item -Wchar-subscripts
2361@opindex Wchar-subscripts
2362Warn if an array subscript has type @code{char}. This is a common cause
2363of error, as programmers often forget that this type is signed on some
2364machines.
2365This warning is enabled by @option{-Wall}.
2366
2367@item -Wcomment
2368@opindex Wcomment
2369Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
2370comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
2371This warning is enabled by @option{-Wall}.
2372
2373@item -Wfatal-errors
2374@opindex Wfatal-errors
2375This option causes the compiler to abort compilation on the first error
2376occurred rather than trying to keep going and printing further error
2377messages.
2378
2379@item -Wformat
2380@opindex Wformat
2381@opindex ffreestanding
2382@opindex fno-builtin
2383Check calls to @code{printf} and @code{scanf}, etc., to make sure that
2384the arguments supplied have types appropriate to the format string
2385specified, and that the conversions specified in the format string make
2386sense. This includes standard functions, and others specified by format
2387attributes (@pxref{Function Attributes}), in the @code{printf},
2388@code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
2389not in the C standard) families (or other target-specific families).
2390Which functions are checked without format attributes having been
2391specified depends on the standard version selected, and such checks of
2392functions without the attribute specified are disabled by
2393@option{-ffreestanding} or @option{-fno-builtin}.
2394
2395The formats are checked against the format features supported by GNU
2396libc version 2.2. These include all ISO C90 and C99 features, as well
2397as features from the Single Unix Specification and some BSD and GNU
2398extensions. Other library implementations may not support all these
2399features; GCC does not support warning about features that go beyond a
2400particular library's limitations. However, if @option{-pedantic} is used
2401with @option{-Wformat}, warnings will be given about format features not
2402in the selected standard version (but not for @code{strfmon} formats,
2403since those are not in any version of the C standard). @xref{C Dialect
2404Options,,Options Controlling C Dialect}.
2405
2406Since @option{-Wformat} also checks for null format arguments for
2407several functions, @option{-Wformat} also implies @option{-Wnonnull}.
2408
2409@option{-Wformat} is included in @option{-Wall}. For more control over some
2410aspects of format checking, the options @option{-Wformat-y2k},
2411@option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
2412@option{-Wformat-nonliteral}, @option{-Wformat-security}, and
2413@option{-Wformat=2} are available, but are not included in @option{-Wall}.
2414
2415@item -Wformat-y2k
2416@opindex Wformat-y2k
2417If @option{-Wformat} is specified, also warn about @code{strftime}
2418formats which may yield only a two-digit year.
2419
2420@item -Wno-format-extra-args
2421@opindex Wno-format-extra-args
2422If @option{-Wformat} is specified, do not warn about excess arguments to a
2423@code{printf} or @code{scanf} format function. The C standard specifies
2424that such arguments are ignored.
2425
2426Where the unused arguments lie between used arguments that are
2427specified with @samp{$} operand number specifications, normally
2428warnings are still given, since the implementation could not know what
2429type to pass to @code{va_arg} to skip the unused arguments. However,
2430in the case of @code{scanf} formats, this option will suppress the
2431warning if the unused arguments are all pointers, since the Single
2432Unix Specification says that such unused arguments are allowed.
2433
2434@item -Wno-format-zero-length
2435@opindex Wno-format-zero-length
2436If @option{-Wformat} is specified, do not warn about zero-length formats.
2437The C standard specifies that zero-length formats are allowed.
2438
2439@item -Wformat-nonliteral
2440@opindex Wformat-nonliteral
2441If @option{-Wformat} is specified, also warn if the format string is not a
2442string literal and so cannot be checked, unless the format function
2443takes its format arguments as a @code{va_list}.
2444
2445@item -Wformat-security
2446@opindex Wformat-security
2447If @option{-Wformat} is specified, also warn about uses of format
2448functions that represent possible security problems. At present, this
2449warns about calls to @code{printf} and @code{scanf} functions where the
2450format string is not a string literal and there are no format arguments,
2451as in @code{printf (foo);}. This may be a security hole if the format
2452string came from untrusted input and contains @samp{%n}. (This is
2453currently a subset of what @option{-Wformat-nonliteral} warns about, but
2454in future warnings may be added to @option{-Wformat-security} that are not
2455included in @option{-Wformat-nonliteral}.)
2456
2457@item -Wformat=2
2458@opindex Wformat=2
2459Enable @option{-Wformat} plus format checks not included in
2460@option{-Wformat}. Currently equivalent to @samp{-Wformat
2461-Wformat-nonliteral -Wformat-security -Wformat-y2k}.
2462
2463@item -Wnonnull
2464@opindex Wnonnull
2465Warn about passing a null pointer for arguments marked as
2466requiring a non-null value by the @code{nonnull} function attribute.
2467
2468@option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It
2469can be disabled with the @option{-Wno-nonnull} option.
2470
2471@item -Winit-self @r{(C, C++, Objective-C and Objective-C++ only)}
2472@opindex Winit-self
2473Warn about uninitialized variables which are initialized with themselves.
2474Note this option can only be used with the @option{-Wuninitialized} option,
2475which in turn only works with @option{-O1} and above.
2476
2477For example, GCC will warn about @code{i} being uninitialized in the
2478following snippet only when @option{-Winit-self} has been specified:
2479@smallexample
2480@group
2481int f()
2482@{
2483 int i = i;
2484 return i;
2485@}
2486@end group
2487@end smallexample
2488
2489@item -Wimplicit-int
2490@opindex Wimplicit-int
2491Warn when a declaration does not specify a type.
2492This warning is enabled by @option{-Wall}.
2493
2494@item -Wimplicit-function-declaration
2495@itemx -Werror-implicit-function-declaration
2496@opindex Wimplicit-function-declaration
2497@opindex Werror-implicit-function-declaration
2498Give a warning (or error) whenever a function is used before being
2499declared. The form @option{-Wno-error-implicit-function-declaration}
2500is not supported.
2501This warning is enabled by @option{-Wall} (as a warning, not an error).
2502
2503@item -Wimplicit
2504@opindex Wimplicit
2505Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
2506This warning is enabled by @option{-Wall}.
2507
2508@item -Wmain
2509@opindex Wmain
2510Warn if the type of @samp{main} is suspicious. @samp{main} should be a
2511function with external linkage, returning int, taking either zero
2512arguments, two, or three arguments of appropriate types.
2513This warning is enabled by @option{-Wall}.
2514
2515@item -Wmissing-braces
2516@opindex Wmissing-braces
2517Warn if an aggregate or union initializer is not fully bracketed. In
2518the following example, the initializer for @samp{a} is not fully
2519bracketed, but that for @samp{b} is fully bracketed.
2520
2521@smallexample
2522int a[2][2] = @{ 0, 1, 2, 3 @};
2523int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
2524@end smallexample
2525
2526This warning is enabled by @option{-Wall}.
2527
2528@item -Wmissing-include-dirs @r{(C, C++, Objective-C and Objective-C++ only)}
2529@opindex Wmissing-include-dirs
2530Warn if a user-supplied include directory does not exist.
2531
2532@item -Wparentheses
2533@opindex Wparentheses
2534Warn if parentheses are omitted in certain contexts, such
2535as when there is an assignment in a context where a truth value
2536is expected, or when operators are nested whose precedence people
2537often get confused about. Only the warning for an assignment used as
2538a truth value is supported when compiling C++; the other warnings are
2539only supported when compiling C@.
2540
2541Also warn if a comparison like @samp{x<=y<=z} appears; this is
2542equivalent to @samp{(x<=y ? 1 : 0) <= z}, which is a different
2543interpretation from that of ordinary mathematical notation.
2544
2545Also warn about constructions where there may be confusion to which
2546@code{if} statement an @code{else} branch belongs. Here is an example of
2547such a case:
2548
2549@smallexample
2550@group
2551@{
2552 if (a)
2553 if (b)
2554 foo ();
2555 else
2556 bar ();
2557@}
2558@end group
2559@end smallexample
2560
2561In C, every @code{else} branch belongs to the innermost possible @code{if}
2562statement, which in this example is @code{if (b)}. This is often not
2563what the programmer expected, as illustrated in the above example by
2564indentation the programmer chose. When there is the potential for this
2565confusion, GCC will issue a warning when this flag is specified.
2566To eliminate the warning, add explicit braces around the innermost
2567@code{if} statement so there is no way the @code{else} could belong to
2568the enclosing @code{if}. The resulting code would look like this:
2569
2570@smallexample
2571@group
2572@{
2573 if (a)
2574 @{
2575 if (b)
2576 foo ();
2577 else
2578 bar ();
2579 @}
2580@}
2581@end group
2582@end smallexample
2583
2584This warning is enabled by @option{-Wall}.
2585
2586@item -Wsequence-point
2587@opindex Wsequence-point
2588Warn about code that may have undefined semantics because of violations
2589of sequence point rules in the C and C++ standards.
2590
2591The C and C++ standards defines the order in which expressions in a C/C++
2592program are evaluated in terms of @dfn{sequence points}, which represent
2593a partial ordering between the execution of parts of the program: those
2594executed before the sequence point, and those executed after it. These
2595occur after the evaluation of a full expression (one which is not part
2596of a larger expression), after the evaluation of the first operand of a
2597@code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
2598function is called (but after the evaluation of its arguments and the
2599expression denoting the called function), and in certain other places.
2600Other than as expressed by the sequence point rules, the order of
2601evaluation of subexpressions of an expression is not specified. All
2602these rules describe only a partial order rather than a total order,
2603since, for example, if two functions are called within one expression
2604with no sequence point between them, the order in which the functions
2605are called is not specified. However, the standards committee have
2606ruled that function calls do not overlap.
2607
2608It is not specified when between sequence points modifications to the
2609values of objects take effect. Programs whose behavior depends on this
2610have undefined behavior; the C and C++ standards specify that ``Between
2611the previous and next sequence point an object shall have its stored
2612value modified at most once by the evaluation of an expression.
2613Furthermore, the prior value shall be read only to determine the value
2614to be stored.''. If a program breaks these rules, the results on any
2615particular implementation are entirely unpredictable.
2616
2617Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
2618= b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
2619diagnosed by this option, and it may give an occasional false positive
2620result, but in general it has been found fairly effective at detecting
2621this sort of problem in programs.
2622
2623The standard is worded confusingly, therefore there is some debate
2624over the precise meaning of the sequence point rules in subtle cases.
2625Links to discussions of the problem, including proposed formal
2626definitions, may be found on the GCC readings page, at
2627@w{@uref{http://gcc.gnu.org/readings.html}}.
2628
2629This warning is enabled by @option{-Wall} for C and C++.
2630
2631@item -Wreturn-type
2632@opindex Wreturn-type
2633Warn whenever a function is defined with a return-type that defaults to
2634@code{int}. Also warn about any @code{return} statement with no
2635return-value in a function whose return-type is not @code{void}.
2636
2637For C, also warn if the return type of a function has a type qualifier
2638such as @code{const}. Such a type qualifier has no effect, since the
2639value returned by a function is not an lvalue. ISO C prohibits
2640qualified @code{void} return types on function definitions, so such
2641return types always receive a warning even without this option.
2642
2643For C++, a function without return type always produces a diagnostic
2644message, even when @option{-Wno-return-type} is specified. The only
2645exceptions are @samp{main} and functions defined in system headers.
2646
2647This warning is enabled by @option{-Wall}.
2648
2649@item -Wswitch
2650@opindex Wswitch
2651Warn whenever a @code{switch} statement has an index of enumerated type
2652and lacks a @code{case} for one or more of the named codes of that
2653enumeration. (The presence of a @code{default} label prevents this
2654warning.) @code{case} labels outside the enumeration range also
2655provoke warnings when this option is used.
2656This warning is enabled by @option{-Wall}.
2657
2658@item -Wswitch-default
2659@opindex Wswitch-switch
2660Warn whenever a @code{switch} statement does not have a @code{default}
2661case.
2662
2663@item -Wswitch-enum
2664@opindex Wswitch-enum
2665Warn whenever a @code{switch} statement has an index of enumerated type
2666and lacks a @code{case} for one or more of the named codes of that
2667enumeration. @code{case} labels outside the enumeration range also
2668provoke warnings when this option is used.
2669
2670@item -Wtrigraphs
2671@opindex Wtrigraphs
2672Warn if any trigraphs are encountered that might change the meaning of
2673the program (trigraphs within comments are not warned about).
2674This warning is enabled by @option{-Wall}.
2675
2676@item -Wunused-function
2677@opindex Wunused-function
2678Warn whenever a static function is declared but not defined or a
2679non-inline static function is unused.
2680This warning is enabled by @option{-Wall}.
2681
2682@item -Wunused-label
2683@opindex Wunused-label
2684Warn whenever a label is declared but not used.
2685This warning is enabled by @option{-Wall}.
2686
2687To suppress this warning use the @samp{unused} attribute
2688(@pxref{Variable Attributes}).
2689
2690@item -Wunused-parameter
2691@opindex Wunused-parameter
2692Warn whenever a function parameter is unused aside from its declaration.
2693
2694To suppress this warning use the @samp{unused} attribute
2695(@pxref{Variable Attributes}).
2696
2697@item -Wunused-variable
2698@opindex Wunused-variable
2699Warn whenever a local variable or non-constant static variable is unused
2700aside from its declaration.
2701This warning is enabled by @option{-Wall}.
2702
2703To suppress this warning use the @samp{unused} attribute
2704(@pxref{Variable Attributes}).
2705
2706@item -Wunused-value
2707@opindex Wunused-value
2708Warn whenever a statement computes a result that is explicitly not used.
2709This warning is enabled by @option{-Wall}.
2710
2711To suppress this warning cast the expression to @samp{void}.
2712
2713@item -Wunused
2714@opindex Wunused
2715All the above @option{-Wunused} options combined.
2716
2717In order to get a warning about an unused function parameter, you must
2718either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
2719@samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
2720
2721@item -Wuninitialized
2722@opindex Wuninitialized
2723Warn if an automatic variable is used without first being initialized or
2724if a variable may be clobbered by a @code{setjmp} call.
2725
2726These warnings are possible only in optimizing compilation,
2727because they require data flow information that is computed only
2728when optimizing. If you do not specify @option{-O}, you will not get
2729these warnings. Instead, GCC will issue a warning about @option{-Wuninitialized}
2730requiring @option{-O}.
2731
2732If you want to warn about code which uses the uninitialized value of the
2733variable in its own initializer, use the @option{-Winit-self} option.
2734
2735These warnings occur for individual uninitialized or clobbered
2736elements of structure, union or array variables as well as for
2737variables which are uninitialized or clobbered as a whole. They do
2738not occur for variables or elements declared @code{volatile}. Because
2739these warnings depend on optimization, the exact variables or elements
2740for which there are warnings will depend on the precise optimization
2741options and version of GCC used.
2742
2743Note that there may be no warning about a variable that is used only
2744to compute a value that itself is never used, because such
2745computations may be deleted by data flow analysis before the warnings
2746are printed.
2747
2748These warnings are made optional because GCC is not smart
2749enough to see all the reasons why the code might be correct
2750despite appearing to have an error. Here is one example of how
2751this can happen:
2752
2753@smallexample
2754@group
2755@{
2756 int x;
2757 switch (y)
2758 @{
2759 case 1: x = 1;
2760 break;
2761 case 2: x = 4;
2762 break;
2763 case 3: x = 5;
2764 @}
2765 foo (x);
2766@}
2767@end group
2768@end smallexample
2769
2770@noindent
2771If the value of @code{y} is always 1, 2 or 3, then @code{x} is
2772always initialized, but GCC doesn't know this. Here is
2773another common case:
2774
2775@smallexample
2776@{
2777 int save_y;
2778 if (change_y) save_y = y, y = new_y;
2779 @dots{}
2780 if (change_y) y = save_y;
2781@}
2782@end smallexample
2783
2784@noindent
2785This has no bug because @code{save_y} is used only if it is set.
2786
2787@cindex @code{longjmp} warnings
2788This option also warns when a non-volatile automatic variable might be
2789changed by a call to @code{longjmp}. These warnings as well are possible
2790only in optimizing compilation.
2791
2792The compiler sees only the calls to @code{setjmp}. It cannot know
2793where @code{longjmp} will be called; in fact, a signal handler could
2794call it at any point in the code. As a result, you may get a warning
2795even when there is in fact no problem because @code{longjmp} cannot
2796in fact be called at the place which would cause a problem.
2797
2798Some spurious warnings can be avoided if you declare all the functions
2799you use that never return as @code{noreturn}. @xref{Function
2800Attributes}.
2801
2802This warning is enabled by @option{-Wall}.
2803
2804@item -Wunknown-pragmas
2805@opindex Wunknown-pragmas
2806@cindex warning for unknown pragmas
2807@cindex unknown pragmas, warning
2808@cindex pragmas, warning of unknown
2809Warn when a #pragma directive is encountered which is not understood by
2810GCC@. If this command line option is used, warnings will even be issued
2811for unknown pragmas in system header files. This is not the case if
2812the warnings were only enabled by the @option{-Wall} command line option.
2813
2814@item -Wno-pragmas
2815@opindex Wno-pragmas
2816@opindex Wpragmas
2817Do not warn about misuses of pragmas, such as incorrect parameters,
2818invalid syntax, or conflicts between pragmas. See also
2819@samp{-Wunknown-pragmas}.
2820
2821@item -Wstrict-aliasing
2822@opindex Wstrict-aliasing
2823This option is only active when @option{-fstrict-aliasing} is active.
2824It warns about code which might break the strict aliasing rules that the
2825compiler is using for optimization. The warning does not catch all
2826cases, but does attempt to catch the more common pitfalls. It is
2827included in @option{-Wall}.
2828
2829@item -Wstrict-aliasing=2
2830@opindex Wstrict-aliasing=2
2831This option is only active when @option{-fstrict-aliasing} is active.
2832It warns about code which might break the strict aliasing rules that the
2833compiler is using for optimization. This warning catches more cases than
2834@option{-Wstrict-aliasing}, but it will also give a warning for some ambiguous
2835cases that are safe.
2836
2837@item -Wstrict-overflow
2838@item -Wstrict-overflow=@var{n}
2839@opindex Wstrict-overflow
2840This option is only active when @option{-fstrict-overflow} is active.
2841It warns about cases where the compiler optimizes based on the
2842assumption that signed overflow does not occur. Note that it does not
2843warn about all cases where the code might overflow: it only warns
2844about cases where the compiler implements some optimization. Thus
2845this warning depends on the optimization level.
2846
2847An optimization which assumes that signed overflow does not occur is
2848perfectly safe if the values of the variables involved are such that
2849overflow never does, in fact, occur. Therefore this warning can
2850easily give a false positive: a warning about code which is not
2851actually a problem. To help focus on important issues, several
2852warning levels are defined. No warnings are issued for the use of
2853undefined signed overflow when estimating how many iterations a loop
2854will require, in particular when determining whether a loop will be
2855executed at all.
2856
2857@table @option
2858@item -Wstrict-overflow=1
2859Warn about cases which are both questionable and easy to avoid. For
2860example: @code{x + 1 > x}; with @option{-fstrict-overflow}, the
2861compiler will simplify this to @code{1}. This level of
2862@option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
2863are not, and must be explicitly requested.
2864
2865@item -Wstrict-overflow=2
2866Also warn about other cases where a comparison is simplified to a
2867constant. For example: @code{abs (x) >= 0}. This can only be
2868simplified when @option{-fstrict-overflow} is in effect, because
2869@code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
2870zero. @option{-Wstrict-overflow} (with no level) is the same as
2871@option{-Wstrict-overflow=2}.
2872
2873@item -Wstrict-overflow=3
2874Also warn about other cases where a comparison is simplified. For
2875example: @code{x + 1 > 1} will be simplified to @code{x > 0}.
2876
2877@item -Wstrict-overflow=4
2878Also warn about other simplifications not covered by the above cases.
2879For example: @code{(x * 10) / 5} will be simplified to @code{x * 2}.
2880
2881@item -Wstrict-overflow=5
2882Also warn about cases where the compiler reduces the magnitude of a
2883constant involved in a comparison. For example: @code{x + 2 > y} will
2884be simplified to @code{x + 1 >= y}. This is reported only at the
2885highest warning level because this simplification applies to many
2886comparisons, so this warning level will give a very large number of
2887false positives.
2888@end table
2889
2890@item -Wall
2891@opindex Wall
2892All of the above @samp{-W} options combined. This enables all the
2893warnings about constructions that some users consider questionable, and
2894that are easy to avoid (or modify to prevent the warning), even in
2895conjunction with macros. This also enables some language-specific
2896warnings described in @ref{C++ Dialect Options} and
2897@ref{Objective-C and Objective-C++ Dialect Options}.
2898@end table
2899
2900The following @option{-W@dots{}} options are not implied by @option{-Wall}.
2901Some of them warn about constructions that users generally do not
2902consider questionable, but which occasionally you might wish to check
2903for; others warn about constructions that are necessary or hard to avoid
2904in some cases, and there is no simple way to modify the code to suppress
2905the warning.
2906
2907@table @gcctabopt
2908@item -Wextra
2909@opindex W
2910@opindex Wextra
2911(This option used to be called @option{-W}. The older name is still
2912supported, but the newer name is more descriptive.) Print extra warning
2913messages for these events:
2914
2915@itemize @bullet
2916@item
2917A function can return either with or without a value. (Falling
2918off the end of the function body is considered returning without
2919a value.) For example, this function would evoke such a
2920warning:
2921
2922@smallexample
2923@group
2924foo (a)
2925@{
2926 if (a > 0)
2927 return a;
2928@}
2929@end group
2930@end smallexample
2931
2932@item
2933An expression-statement or the left-hand side of a comma expression
2934contains no side effects.
2935To suppress the warning, cast the unused expression to void.
2936For example, an expression such as @samp{x[i,j]} will cause a warning,
2937but @samp{x[(void)i,j]} will not.
2938
2939@item
2940An unsigned value is compared against zero with @samp{<} or @samp{>=}.
2941
2942@item
2943Storage-class specifiers like @code{static} are not the first things in
2944a declaration. According to the C Standard, this usage is obsolescent.
2945
2946@item
2947If @option{-Wall} or @option{-Wunused} is also specified, warn about unused
2948arguments.
2949
2950@item
2951A comparison between signed and unsigned values could produce an
2952incorrect result when the signed value is converted to unsigned.
2953(But don't warn if @option{-Wno-sign-compare} is also specified.)
2954
2955@item
2956An aggregate has an initializer which does not initialize all members.
2957This warning can be independently controlled by
2958@option{-Wmissing-field-initializers}.
2959
2960@item
2961An initialized field without side effects is overridden when using
2962designated initializers (@pxref{Designated Inits, , Designated
2963Initializers}). This warning can be independently controlled by
2964@option{-Woverride-init}.
2965
2966@item
2967A function parameter is declared without a type specifier in K&R-style
2968functions:
2969
2970@smallexample
2971void foo(bar) @{ @}
2972@end smallexample
2973
2974@item
2975An empty body occurs in an @samp{if} or @samp{else} statement.
2976
2977@item
2978A pointer is compared against integer zero with @samp{<}, @samp{<=},
2979@samp{>}, or @samp{>=}.
2980
2981@item
2982A variable might be changed by @samp{longjmp} or @samp{vfork}.
2983
2984@item @r{(C++ only)}
2985An enumerator and a non-enumerator both appear in a conditional expression.
2986
2987@item @r{(C++ only)}
2988A non-static reference or non-static @samp{const} member appears in a
2989class without constructors.
2990
2991@item @r{(C++ only)}
2992Ambiguous virtual bases.
2993
2994@item @r{(C++ only)}
2995Subscripting an array which has been declared @samp{register}.
2996
2997@item @r{(C++ only)}
2998Taking the address of a variable which has been declared @samp{register}.
2999
3000@item @r{(C++ only)}
3001A base class is not initialized in a derived class' copy constructor.
3002@end itemize
3003
3004@item -Wno-div-by-zero
3005@opindex Wno-div-by-zero
3006@opindex Wdiv-by-zero
3007Do not warn about compile-time integer division by zero. Floating point
3008division by zero is not warned about, as it can be a legitimate way of
3009obtaining infinities and NaNs.
3010
3011@item -Wsystem-headers
3012@opindex Wsystem-headers
3013@cindex warnings from system headers
3014@cindex system headers, warnings from
3015Print warning messages for constructs found in system header files.
3016Warnings from system headers are normally suppressed, on the assumption
3017that they usually do not indicate real problems and would only make the
3018compiler output harder to read. Using this command line option tells
3019GCC to emit warnings from system headers as if they occurred in user
3020code. However, note that using @option{-Wall} in conjunction with this
3021option will @emph{not} warn about unknown pragmas in system
3022headers---for that, @option{-Wunknown-pragmas} must also be used.
3023
3024@item -Wfloat-equal
3025@opindex Wfloat-equal
3026Warn if floating point values are used in equality comparisons.
3027
3028The idea behind this is that sometimes it is convenient (for the
3029programmer) to consider floating-point values as approximations to
3030infinitely precise real numbers. If you are doing this, then you need
3031to compute (by analyzing the code, or in some other way) the maximum or
3032likely maximum error that the computation introduces, and allow for it
3033when performing comparisons (and when producing output, but that's a
3034different problem). In particular, instead of testing for equality, you
3035would check to see whether the two values have ranges that overlap; and
3036this is done with the relational operators, so equality comparisons are
3037probably mistaken.
3038
3039@item -Wtraditional @r{(C only)}
3040@opindex Wtraditional
3041Warn about certain constructs that behave differently in traditional and
3042ISO C@. Also warn about ISO C constructs that have no traditional C
3043equivalent, and/or problematic constructs which should be avoided.
3044
3045@itemize @bullet
3046@item
3047Macro parameters that appear within string literals in the macro body.
3048In traditional C macro replacement takes place within string literals,
3049but does not in ISO C@.
3050
3051@item
3052In traditional C, some preprocessor directives did not exist.
3053Traditional preprocessors would only consider a line to be a directive
3054if the @samp{#} appeared in column 1 on the line. Therefore
3055@option{-Wtraditional} warns about directives that traditional C
3056understands but would ignore because the @samp{#} does not appear as the
3057first character on the line. It also suggests you hide directives like
3058@samp{#pragma} not understood by traditional C by indenting them. Some
3059traditional implementations would not recognize @samp{#elif}, so it
3060suggests avoiding it altogether.
3061
3062@item
3063A function-like macro that appears without arguments.
3064
3065@item
3066The unary plus operator.
3067
3068@item
3069The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
3070constant suffixes. (Traditional C does support the @samp{L} suffix on integer
3071constants.) Note, these suffixes appear in macros defined in the system
3072headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
3073Use of these macros in user code might normally lead to spurious
3074warnings, however GCC's integrated preprocessor has enough context to
3075avoid warning in these cases.
3076
3077@item
3078A function declared external in one block and then used after the end of
3079the block.
3080
3081@item
3082A @code{switch} statement has an operand of type @code{long}.
3083
3084@item
3085A non-@code{static} function declaration follows a @code{static} one.
3086This construct is not accepted by some traditional C compilers.
3087
3088@item
3089The ISO type of an integer constant has a different width or
3090signedness from its traditional type. This warning is only issued if
3091the base of the constant is ten. I.e.@: hexadecimal or octal values, which
3092typically represent bit patterns, are not warned about.
3093
3094@item
3095Usage of ISO string concatenation is detected.
3096
3097@item
3098Initialization of automatic aggregates.
3099
3100@item
3101Identifier conflicts with labels. Traditional C lacks a separate
3102namespace for labels.
3103
3104@item
3105Initialization of unions. If the initializer is zero, the warning is
3106omitted. This is done under the assumption that the zero initializer in
3107user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
3108initializer warnings and relies on default initialization to zero in the
3109traditional C case.
3110
3111@item
3112Conversions by prototypes between fixed/floating point values and vice
3113versa. The absence of these prototypes when compiling with traditional
3114C would cause serious problems. This is a subset of the possible
3115conversion warnings, for the full set use @option{-Wconversion}.
3116
3117@item
3118Use of ISO C style function definitions. This warning intentionally is
3119@emph{not} issued for prototype declarations or variadic functions
3120because these ISO C features will appear in your code when using
3121libiberty's traditional C compatibility macros, @code{PARAMS} and
3122@code{VPARAMS}. This warning is also bypassed for nested functions
3123because that feature is already a GCC extension and thus not relevant to
3124traditional C compatibility.
3125@end itemize
3126
3127@item -Wdeclaration-after-statement @r{(C only)}
3128@opindex Wdeclaration-after-statement
3129Warn when a declaration is found after a statement in a block. This
3130construct, known from C++, was introduced with ISO C99 and is by default
3131allowed in GCC@. It is not supported by ISO C90 and was not supported by
3132GCC versions before GCC 3.0. @xref{Mixed Declarations}.
3133
3134@item -Wundef
3135@opindex Wundef
3136Warn if an undefined identifier is evaluated in an @samp{#if} directive.
3137
3138@item -Wno-endif-labels
3139@opindex Wno-endif-labels
3140@opindex Wendif-labels
3141Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
3142
3143@item -Wshadow
3144@opindex Wshadow
3145Warn whenever a local variable shadows another local variable, parameter or
3146global variable or whenever a built-in function is shadowed.
3147
3148@item -Wlarger-than-@var{len}
3149@opindex Wlarger-than
3150Warn whenever an object of larger than @var{len} bytes is defined.
3151
3152@item -Wunsafe-loop-optimizations
3153@opindex Wunsafe-loop-optimizations
3154Warn if the loop cannot be optimized because the compiler could not
3155assume anything on the bounds of the loop indices. With
3156@option{-funsafe-loop-optimizations} warn if the compiler made
3157such assumptions.
3158
3159@item -Wpointer-arith
3160@opindex Wpointer-arith
3161Warn about anything that depends on the ``size of'' a function type or
3162of @code{void}. GNU C assigns these types a size of 1, for
3163convenience in calculations with @code{void *} pointers and pointers
3164to functions.
3165
3166@item -Wbad-function-cast @r{(C only)}
3167@opindex Wbad-function-cast
3168Warn whenever a function call is cast to a non-matching type.
3169For example, warn if @code{int malloc()} is cast to @code{anything *}.
3170
3171@item -Wc++-compat
3172Warn about ISO C constructs that are outside of the common subset of
3173ISO C and ISO C++, e.g.@: request for implicit conversion from
3174@code{void *} to a pointer to non-@code{void} type.
3175
3176@item -Wcast-qual
3177@opindex Wcast-qual
3178Warn whenever a pointer is cast so as to remove a type qualifier from
3179the target type. For example, warn if a @code{const char *} is cast
3180to an ordinary @code{char *}.
3181
3182@item -Wcast-align
3183@opindex Wcast-align
3184Warn whenever a pointer is cast such that the required alignment of the
3185target is increased. For example, warn if a @code{char *} is cast to
3186an @code{int *} on machines where integers can only be accessed at
3187two- or four-byte boundaries.
3188
3189@item -Wwrite-strings
3190@opindex Wwrite-strings
3191When compiling C, give string constants the type @code{const
3192char[@var{length}]} so that
3193copying the address of one into a non-@code{const} @code{char *}
3194pointer will get a warning; when compiling C++, warn about the
3195deprecated conversion from string literals to @code{char *}. This
3196warning, by default, is enabled for C++ programs.
3197These warnings will help you find at
3198compile time code that can try to write into a string constant, but
3199only if you have been very careful about using @code{const} in
3200declarations and prototypes. Otherwise, it will just be a nuisance;
3201this is why we did not make @option{-Wall} request these warnings.
3202
3203@item -Wconversion
3204@opindex Wconversion
3205Warn if a prototype causes a type conversion that is different from what
3206would happen to the same argument in the absence of a prototype. This
3207includes conversions of fixed point to floating and vice versa, and
3208conversions changing the width or signedness of a fixed point argument
3209except when the same as the default promotion.
3210
3211Also, warn if a negative integer constant expression is implicitly
3212converted to an unsigned type. For example, warn about the assignment
3213@code{x = -1} if @code{x} is unsigned. But do not warn about explicit
3214casts like @code{(unsigned) -1}.
3215
3216@item -Wsign-compare
3217@opindex Wsign-compare
3218@cindex warning for comparison of signed and unsigned values
3219@cindex comparison of signed and unsigned values, warning
3220@cindex signed and unsigned values, comparison warning
3221Warn when a comparison between signed and unsigned values could produce
3222an incorrect result when the signed value is converted to unsigned.
3223This warning is also enabled by @option{-Wextra}; to get the other warnings
3224of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
3225
3226@item -Waddress
3227@opindex Waddress
3228@opindex Wno-address
3229Warn about suspicious uses of memory addresses. These include using
3230the address of a function in a conditional expression, such as
3231@code{void func(void); if (func)}, and comparisons against the memory
3232address of a string literal, such as @code{if (x == "abc")}. Such
3233uses typically indicate a programmer error: the address of a function
3234always evaluates to true, so their use in a conditional usually
3235indicate that the programmer forgot the parentheses in a function
3236call; and comparisons against string literals result in unspecified
3237behavior and are not portable in C, so they usually indicate that the
3238programmer intended to use @code{strcmp}. This warning is enabled by
3239@option{-Wall}.
3240
3241@item -Waggregate-return
3242@opindex Waggregate-return
3243Warn if any functions that return structures or unions are defined or
3244called. (In languages where you can return an array, this also elicits
3245a warning.)
3246
3247@item -Wno-attributes
3248@opindex Wno-attributes
3249@opindex Wattributes
3250Do not warn if an unexpected @code{__attribute__} is used, such as
3251unrecognized attributes, function attributes applied to variables,
3252etc. This will not stop errors for incorrect use of supported
3253attributes.
3254
3255@item -Wstrict-prototypes @r{(C only)}
3256@opindex Wstrict-prototypes
3257Warn if a function is declared or defined without specifying the
3258argument types. (An old-style function definition is permitted without
3259a warning if preceded by a declaration which specifies the argument
3260types.)
3261
3262@item -Wold-style-definition @r{(C only)}
3263@opindex Wold-style-definition
3264Warn if an old-style function definition is used. A warning is given
3265even if there is a previous prototype.
3266
3267@item -Wmissing-prototypes @r{(C only)}
3268@opindex Wmissing-prototypes
3269Warn if a global function is defined without a previous prototype
3270declaration. This warning is issued even if the definition itself
3271provides a prototype. The aim is to detect global functions that fail
3272to be declared in header files.
3273
3274@item -Wmissing-declarations @r{(C only)}
3275@opindex Wmissing-declarations
3276Warn if a global function is defined without a previous declaration.
3277Do so even if the definition itself provides a prototype.
3278Use this option to detect global functions that are not declared in
3279header files.
3280
3281@item -Wmissing-field-initializers
3282@opindex Wmissing-field-initializers
3283@opindex W
3284@opindex Wextra
3285Warn if a structure's initializer has some fields missing. For
3286example, the following code would cause such a warning, because
3287@code{x.h} is implicitly zero:
3288
3289@smallexample
3290struct s @{ int f, g, h; @};
3291struct s x = @{ 3, 4 @};
3292@end smallexample
3293
3294This option does not warn about designated initializers, so the following
3295modification would not trigger a warning:
3296
3297@smallexample
3298struct s @{ int f, g, h; @};
3299struct s x = @{ .f = 3, .g = 4 @};
3300@end smallexample
3301
3302This warning is included in @option{-Wextra}. To get other @option{-Wextra}
3303warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
3304
3305@item -Wmissing-noreturn
3306@opindex Wmissing-noreturn
3307Warn about functions which might be candidates for attribute @code{noreturn}.
3308Note these are only possible candidates, not absolute ones. Care should
3309be taken to manually verify functions actually do not ever return before
3310adding the @code{noreturn} attribute, otherwise subtle code generation
3311bugs could be introduced. You will not get a warning for @code{main} in
3312hosted C environments.
3313
3314@item -Wmissing-format-attribute
3315@opindex Wmissing-format-attribute
3316@opindex Wformat
3317Warn about function pointers which might be candidates for @code{format}
3318attributes. Note these are only possible candidates, not absolute ones.
3319GCC will guess that function pointers with @code{format} attributes that
3320are used in assignment, initialization, parameter passing or return
3321statements should have a corresponding @code{format} attribute in the
3322resulting type. I.e.@: the left-hand side of the assignment or
3323initialization, the type of the parameter variable, or the return type
3324of the containing function respectively should also have a @code{format}
3325attribute to avoid the warning.
3326
3327GCC will also warn about function definitions which might be
3328candidates for @code{format} attributes. Again, these are only
3329possible candidates. GCC will guess that @code{format} attributes
3330might be appropriate for any function that calls a function like
3331@code{vprintf} or @code{vscanf}, but this might not always be the
3332case, and some functions for which @code{format} attributes are
3333appropriate may not be detected.
3334
3335@item -Wno-multichar
3336@opindex Wno-multichar
3337@opindex Wmultichar
3338Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
3339Usually they indicate a typo in the user's code, as they have
3340implementation-defined values, and should not be used in portable code.
3341
3342@item -Wnormalized=<none|id|nfc|nfkc>
3343@opindex Wnormalized
3344@cindex NFC
3345@cindex NFKC
3346@cindex character set, input normalization
3347In ISO C and ISO C++, two identifiers are different if they are
3348different sequences of characters. However, sometimes when characters
3349outside the basic ASCII character set are used, you can have two
3350different character sequences that look the same. To avoid confusion,
3351the ISO 10646 standard sets out some @dfn{normalization rules} which
3352when applied ensure that two sequences that look the same are turned into
3353the same sequence. GCC can warn you if you are using identifiers which
3354have not been normalized; this option controls that warning.
3355
3356There are four levels of warning that GCC supports. The default is
3357@option{-Wnormalized=nfc}, which warns about any identifier which is
3358not in the ISO 10646 ``C'' normalized form, @dfn{NFC}. NFC is the
3359recommended form for most uses.
3360
3361Unfortunately, there are some characters which ISO C and ISO C++ allow
3362in identifiers that when turned into NFC aren't allowable as
3363identifiers. That is, there's no way to use these symbols in portable
3364ISO C or C++ and have all your identifiers in NFC.
3365@option{-Wnormalized=id} suppresses the warning for these characters.
3366It is hoped that future versions of the standards involved will correct
3367this, which is why this option is not the default.
3368
3369You can switch the warning off for all characters by writing
3370@option{-Wnormalized=none}. You would only want to do this if you
3371were using some other normalization scheme (like ``D''), because
3372otherwise you can easily create bugs that are literally impossible to see.
3373
3374Some characters in ISO 10646 have distinct meanings but look identical
3375in some fonts or display methodologies, especially once formatting has
3376been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
3377LETTER N'', will display just like a regular @code{n} which has been
3378placed in a superscript. ISO 10646 defines the @dfn{NFKC}
3379normalization scheme to convert all these into a standard form as
3380well, and GCC will warn if your code is not in NFKC if you use
3381@option{-Wnormalized=nfkc}. This warning is comparable to warning
3382about every identifier that contains the letter O because it might be
3383confused with the digit 0, and so is not the default, but may be
3384useful as a local coding convention if the programming environment is
3385unable to be fixed to display these characters distinctly.
3386
3387@item -Wno-deprecated-declarations
3388@opindex Wno-deprecated-declarations
3389Do not warn about uses of functions (@pxref{Function Attributes}),
3390variables (@pxref{Variable Attributes}), and types (@pxref{Type
3391Attributes}) marked as deprecated by using the @code{deprecated}
3392attribute.
3393
3394@item -Wno-overflow
3395@opindex Wno-overflow
3396Do not warn about compile-time overflow in constant expressions.
3397
3398@item -Woverride-init
3399@opindex Woverride-init
3400@opindex W
3401@opindex Wextra
3402Warn if an initialized field without side effects is overridden when
3403using designated initializers (@pxref{Designated Inits, , Designated
3404Initializers}).
3405
3406This warning is included in @option{-Wextra}. To get other
3407@option{-Wextra} warnings without this one, use @samp{-Wextra
3408-Wno-override-init}.
3409
3410@item -Wpacked
3411@opindex Wpacked
3412Warn if a structure is given the packed attribute, but the packed
3413attribute has no effect on the layout or size of the structure.
3414Such structures may be mis-aligned for little benefit. For
3415instance, in this code, the variable @code{f.x} in @code{struct bar}
3416will be misaligned even though @code{struct bar} does not itself
3417have the packed attribute:
3418
3419@smallexample
3420@group
3421struct foo @{
3422 int x;
3423 char a, b, c, d;
3424@} __attribute__((packed));
3425struct bar @{
3426 char z;
3427 struct foo f;
3428@};
3429@end group
3430@end smallexample
3431
3432@item -Wpadded
3433@opindex Wpadded
3434Warn if padding is included in a structure, either to align an element
3435of the structure or to align the whole structure. Sometimes when this
3436happens it is possible to rearrange the fields of the structure to
3437reduce the padding and so make the structure smaller.
3438
3439@item -Wredundant-decls
3440@opindex Wredundant-decls
3441Warn if anything is declared more than once in the same scope, even in
3442cases where multiple declaration is valid and changes nothing.
3443
3444@item -Wnested-externs @r{(C only)}
3445@opindex Wnested-externs
3446Warn if an @code{extern} declaration is encountered within a function.
3447
3448@item -Wunreachable-code
3449@opindex Wunreachable-code
3450Warn if the compiler detects that code will never be executed.
3451
3452This option is intended to warn when the compiler detects that at
3453least a whole line of source code will never be executed, because
3454some condition is never satisfied or because it is after a
3455procedure that never returns.
3456
3457It is possible for this option to produce a warning even though there
3458are circumstances under which part of the affected line can be executed,
3459so care should be taken when removing apparently-unreachable code.
3460
3461For instance, when a function is inlined, a warning may mean that the
3462line is unreachable in only one inlined copy of the function.
3463
3464This option is not made part of @option{-Wall} because in a debugging
3465version of a program there is often substantial code which checks
3466correct functioning of the program and is, hopefully, unreachable
3467because the program does work. Another common use of unreachable
3468code is to provide behavior which is selectable at compile-time.
3469
3470@item -Winline
3471@opindex Winline
3472Warn if a function can not be inlined and it was declared as inline.
3473Even with this option, the compiler will not warn about failures to
3474inline functions declared in system headers.
3475
3476The compiler uses a variety of heuristics to determine whether or not
3477to inline a function. For example, the compiler takes into account
3478the size of the function being inlined and the amount of inlining
3479that has already been done in the current function. Therefore,
3480seemingly insignificant changes in the source program can cause the
3481warnings produced by @option{-Winline} to appear or disappear.
3482
3483@item -Wno-invalid-offsetof @r{(C++ only)}
3484@opindex Wno-invalid-offsetof
3485Suppress warnings from applying the @samp{offsetof} macro to a non-POD
3486type. According to the 1998 ISO C++ standard, applying @samp{offsetof}
3487to a non-POD type is undefined. In existing C++ implementations,
3488however, @samp{offsetof} typically gives meaningful results even when
3489applied to certain kinds of non-POD types. (Such as a simple
3490@samp{struct} that fails to be a POD type only by virtue of having a
3491constructor.) This flag is for users who are aware that they are
3492writing nonportable code and who have deliberately chosen to ignore the
3493warning about it.
3494
3495The restrictions on @samp{offsetof} may be relaxed in a future version
3496of the C++ standard.
3497
3498@item -Wno-int-to-pointer-cast @r{(C only)}
3499@opindex Wno-int-to-pointer-cast
3500Suppress warnings from casts to pointer type of an integer of a
3501different size.
3502
3503@item -Wno-pointer-to-int-cast @r{(C only)}
3504@opindex Wno-pointer-to-int-cast
3505Suppress warnings from casts from a pointer to an integer type of a
3506different size.
3507
3508@item -Winvalid-pch
3509@opindex Winvalid-pch
3510Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
3511the search path but can't be used.
3512
3513@item -Wlong-long
3514@opindex Wlong-long
3515@opindex Wno-long-long
3516Warn if @samp{long long} type is used. This is default. To inhibit
3517the warning messages, use @option{-Wno-long-long}. Flags
3518@option{-Wlong-long} and @option{-Wno-long-long} are taken into account
3519only when @option{-pedantic} flag is used.
3520
3521@item -Wvariadic-macros
3522@opindex Wvariadic-macros
3523@opindex Wno-variadic-macros
3524Warn if variadic macros are used in pedantic ISO C90 mode, or the GNU
3525alternate syntax when in pedantic ISO C99 mode. This is default.
3526To inhibit the warning messages, use @option{-Wno-variadic-macros}.
3527
3528@item -Wvolatile-register-var
3529@opindex Wvolatile-register-var
3530@opindex Wno-volatile-register-var
3531Warn if a register variable is declared volatile. The volatile
3532modifier does not inhibit all optimizations that may eliminate reads
3533and/or writes to register variables.
3534
3535@item -Wdisabled-optimization
3536@opindex Wdisabled-optimization
3537Warn if a requested optimization pass is disabled. This warning does
3538not generally indicate that there is anything wrong with your code; it
3539merely indicates that GCC's optimizers were unable to handle the code
3540effectively. Often, the problem is that your code is too big or too
3541complex; GCC will refuse to optimize programs when the optimization
3542itself is likely to take inordinate amounts of time.
3543
3544@item -Wpointer-sign
3545@opindex Wpointer-sign
3546@opindex Wno-pointer-sign
3547Warn for pointer argument passing or assignment with different signedness.
3548This option is only supported for C and Objective-C@. It is implied by
3549@option{-Wall} and by @option{-pedantic}, which can be disabled with
3550@option{-Wno-pointer-sign}.
3551
3552@item -Werror
3553@opindex Werror
3554Make all warnings into errors.
3555
3556@item -Werror=
3557@opindex Werror=
3558Make the specified warning into an errors. The specifier for a
3559warning is appended, for example @option{-Werror=switch} turns the
3560warnings controlled by @option{-Wswitch} into errors. This switch
3561takes a negative form, to be used to negate @option{-Werror} for
3562specific warnings, for example @option{-Wno-error=switch} makes
3563@option{-Wswitch} warnings not be errors, even when @option{-Werror}
3564is in effect. You can use the @option{-fdiagnostics-show-option}
3565option to have each controllable warning amended with the option which
3566controls it, to determine what to use with this option.
3567
3568Note that specifying @option{-Werror=}@var{foo} automatically implies
3569@option{-W}@var{foo}. However, @option{-Wno-error=}@var{foo} does not
3570imply anything.
3571
3572@item -Wstack-protector
3573@opindex Wstack-protector
3574This option is only active when @option{-fstack-protector} is active. It
3575warns about functions that will not be protected against stack smashing.
3576
3577@item -Woverlength-strings
3578@opindex Woverlength-strings
3579Warn about string constants which are longer than the ``minimum
3580maximum'' length specified in the C standard. Modern compilers
3581generally allow string constants which are much longer than the
3582standard's minimum limit, but very portable programs should avoid
3583using longer strings.
3584
3585The limit applies @emph{after} string constant concatenation, and does
3586not count the trailing NUL@. In C89, the limit was 509 characters; in
3587C99, it was raised to 4095. C++98 does not specify a normative
3588minimum maximum, so we do not diagnose overlength strings in C++@.
3589
3590This option is implied by @option{-pedantic}, and can be disabled with
3591@option{-Wno-overlength-strings}.
3592@end table
3593
3594@node Debugging Options
3595@section Options for Debugging Your Program or GCC
3596@cindex options, debugging
3597@cindex debugging information options
3598
3599GCC has various special options that are used for debugging
3600either your program or GCC:
3601
3602@table @gcctabopt
3603@item -g
3604@opindex g
3605Produce debugging information in the operating system's native format
3606(stabs, COFF, XCOFF, or DWARF 2)@. GDB can work with this debugging
3607information.
3608
3609On most systems that use stabs format, @option{-g} enables use of extra
3610debugging information that only GDB can use; this extra information
3611makes debugging work better in GDB but will probably make other debuggers
3612crash or
3613refuse to read the program. If you want to control for certain whether
3614to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
3615@option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
3616
3617GCC allows you to use @option{-g} with
3618@option{-O}. The shortcuts taken by optimized code may occasionally
3619produce surprising results: some variables you declared may not exist
3620at all; flow of control may briefly move where you did not expect it;
3621some statements may not be executed because they compute constant
3622results or their values were already at hand; some statements may
3623execute in different places because they were moved out of loops.
3624
3625Nevertheless it proves possible to debug optimized output. This makes
3626it reasonable to use the optimizer for programs that might have bugs.
3627
3628The following options are useful when GCC is generated with the
3629capability for more than one debugging format.
3630
3631@item -ggdb
3632@opindex ggdb
3633Produce debugging information for use by GDB@. This means to use the
3634most expressive format available (DWARF 2, stabs, or the native format
3635if neither of those are supported), including GDB extensions if at all
3636possible.
3637
3638@item -gstabs
3639@opindex gstabs
3640Produce debugging information in stabs format (if that is supported),
3641without GDB extensions. This is the format used by DBX on most BSD
3642systems. On MIPS, Alpha and System V Release 4 systems this option
3643produces stabs debugging output which is not understood by DBX or SDB@.
3644On System V Release 4 systems this option requires the GNU assembler.
3645
3646@item -feliminate-unused-debug-symbols
3647@opindex feliminate-unused-debug-symbols
3648Produce debugging information in stabs format (if that is supported),
3649for only symbols that are actually used.
3650
3651@item -femit-class-debug-always
3652Instead of emitting debugging information for a C++ class in only one
3653object file, emit it in all object files using the class. This option
3654should be used only with debuggers that are unable to handle the way GCC
3655normally emits debugging information for classes because using this
3656option will increase the size of debugging information by as much as a
3657factor of two.
3658
3659@item -gstabs+
3660@opindex gstabs+
3661Produce debugging information in stabs format (if that is supported),
3662using GNU extensions understood only by the GNU debugger (GDB)@. The
3663use of these extensions is likely to make other debuggers crash or
3664refuse to read the program.
3665
3666@item -gcoff
3667@opindex gcoff
3668Produce debugging information in COFF format (if that is supported).
3669This is the format used by SDB on most System V systems prior to
3670System V Release 4.
3671
3672@item -gxcoff
3673@opindex gxcoff
3674Produce debugging information in XCOFF format (if that is supported).
3675This is the format used by the DBX debugger on IBM RS/6000 systems.
3676
3677@item -gxcoff+
3678@opindex gxcoff+
3679Produce debugging information in XCOFF format (if that is supported),
3680using GNU extensions understood only by the GNU debugger (GDB)@. The
3681use of these extensions is likely to make other debuggers crash or
3682refuse to read the program, and may cause assemblers other than the GNU
3683assembler (GAS) to fail with an error.
3684
3685@item -gdwarf-2
3686@opindex gdwarf-2
3687Produce debugging information in DWARF version 2 format (if that is
3688supported). This is the format used by DBX on IRIX 6. With this
3689option, GCC uses features of DWARF version 3 when they are useful;
3690version 3 is upward compatible with version 2, but may still cause
3691problems for older debuggers.
3692
3693@item -gvms
3694@opindex gvms
3695Produce debugging information in VMS debug format (if that is
3696supported). This is the format used by DEBUG on VMS systems.
3697
3698@item -g@var{level}
3699@itemx -ggdb@var{level}
3700@itemx -gstabs@var{level}
3701@itemx -gcoff@var{level}
3702@itemx -gxcoff@var{level}
3703@itemx -gvms@var{level}
3704Request debugging information and also use @var{level} to specify how
3705much information. The default level is 2.
3706
3707Level 1 produces minimal information, enough for making backtraces in
3708parts of the program that you don't plan to debug. This includes
3709descriptions of functions and external variables, but no information
3710about local variables and no line numbers.
3711
3712Level 3 includes extra information, such as all the macro definitions
3713present in the program. Some debuggers support macro expansion when
3714you use @option{-g3}.
3715
3716@option{-gdwarf-2} does not accept a concatenated debug level, because
3717GCC used to support an option @option{-gdwarf} that meant to generate
3718debug information in version 1 of the DWARF format (which is very
3719different from version 2), and it would have been too confusing. That
3720debug format is long obsolete, but the option cannot be changed now.
3721Instead use an additional @option{-g@var{level}} option to change the
3722debug level for DWARF2.
3723
3724@item -feliminate-dwarf2-dups
3725@opindex feliminate-dwarf2-dups
3726Compress DWARF2 debugging information by eliminating duplicated
3727information about each symbol. This option only makes sense when
3728generating DWARF2 debugging information with @option{-gdwarf-2}.
3729
3730@cindex @command{prof}
3731@item -p
3732@opindex p
3733Generate extra code to write profile information suitable for the
3734analysis program @command{prof}. You must use this option when compiling
3735the source files you want data about, and you must also use it when
3736linking.
3737
3738@cindex @command{gprof}
3739@item -pg
3740@opindex pg
3741Generate extra code to write profile information suitable for the
3742analysis program @command{gprof}. You must use this option when compiling
3743the source files you want data about, and you must also use it when
3744linking.
3745
3746@item -Q
3747@opindex Q
3748Makes the compiler print out each function name as it is compiled, and
3749print some statistics about each pass when it finishes.
3750
3751@item -ftime-report
3752@opindex ftime-report
3753Makes the compiler print some statistics about the time consumed by each
3754pass when it finishes.
3755
3756@item -fmem-report
3757@opindex fmem-report
3758Makes the compiler print some statistics about permanent memory
3759allocation when it finishes.
3760
3761@item -fprofile-arcs
3762@opindex fprofile-arcs
3763Add code so that program flow @dfn{arcs} are instrumented. During
3764execution the program records how many times each branch and call is
3765executed and how many times it is taken or returns. When the compiled
3766program exits it saves this data to a file called
3767@file{@var{auxname}.gcda} for each source file. The data may be used for
3768profile-directed optimizations (@option{-fbranch-probabilities}), or for
3769test coverage analysis (@option{-ftest-coverage}). Each object file's
3770@var{auxname} is generated from the name of the output file, if
3771explicitly specified and it is not the final executable, otherwise it is
3772the basename of the source file. In both cases any suffix is removed
3773(e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
3774@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
3775@xref{Cross-profiling}.
3776
3777@cindex @command{gcov}
3778@item --coverage
3779@opindex coverage
3780
3781This option is used to compile and link code instrumented for coverage
3782analysis. The option is a synonym for @option{-fprofile-arcs}
3783@option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
3784linking). See the documentation for those options for more details.
3785
3786@itemize
3787
3788@item
3789Compile the source files with @option{-fprofile-arcs} plus optimization
3790and code generation options. For test coverage analysis, use the
3791additional @option{-ftest-coverage} option. You do not need to profile
3792every source file in a program.
3793
3794@item
3795Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
3796(the latter implies the former).
3797
3798@item
3799Run the program on a representative workload to generate the arc profile
3800information. This may be repeated any number of times. You can run
3801concurrent instances of your program, and provided that the file system
3802supports locking, the data files will be correctly updated. Also
3803@code{fork} calls are detected and correctly handled (double counting
3804will not happen).
3805
3806@item
3807For profile-directed optimizations, compile the source files again with
3808the same optimization and code generation options plus
3809@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
3810Control Optimization}).
3811
3812@item
3813For test coverage analysis, use @command{gcov} to produce human readable
3814information from the @file{.gcno} and @file{.gcda} files. Refer to the
3815@command{gcov} documentation for further information.
3816
3817@end itemize
3818
3819With @option{-fprofile-arcs}, for each function of your program GCC
3820creates a program flow graph, then finds a spanning tree for the graph.
3821Only arcs that are not on the spanning tree have to be instrumented: the
3822compiler adds code to count the number of times that these arcs are
3823executed. When an arc is the only exit or only entrance to a block, the
3824instrumentation code can be added to the block; otherwise, a new basic
3825block must be created to hold the instrumentation code.
3826
3827@need 2000
3828@item -ftest-coverage
3829@opindex ftest-coverage
3830Produce a notes file that the @command{gcov} code-coverage utility
3831(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
3832show program coverage. Each source file's note file is called
3833@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
3834above for a description of @var{auxname} and instructions on how to
3835generate test coverage data. Coverage data will match the source files
3836more closely, if you do not optimize.
3837
3838@item -d@var{letters}
3839@item -fdump-rtl-@var{pass}
3840@opindex d
3841Says to make debugging dumps during compilation at times specified by
3842@var{letters}. This is used for debugging the RTL-based passes of the
3843compiler. The file names for most of the dumps are made by appending a
3844pass number and a word to the @var{dumpname}. @var{dumpname} is generated
3845from the name of the output file, if explicitly specified and it is not
3846an executable, otherwise it is the basename of the source file.
3847
3848Most debug dumps can be enabled either passing a letter to the @option{-d}
3849option, or with a long @option{-fdump-rtl} switch; here are the possible
3850letters for use in @var{letters} and @var{pass}, and their meanings:
3851
3852@table @gcctabopt
3853@item -dA
3854@opindex dA
3855Annotate the assembler output with miscellaneous debugging information.
3856
3857@item -dB
3858@itemx -fdump-rtl-bbro
3859@opindex dB
3860@opindex fdump-rtl-bbro
3861Dump after block reordering, to @file{@var{file}.148r.bbro}.
3862
3863@item -dc
3864@itemx -fdump-rtl-combine
3865@opindex dc
3866@opindex fdump-rtl-combine
3867Dump after instruction combination, to the file @file{@var{file}.129r.combine}.
3868
3869@item -dC
3870@itemx -fdump-rtl-ce1
3871@itemx -fdump-rtl-ce2
3872@opindex dC
3873@opindex fdump-rtl-ce1
3874@opindex fdump-rtl-ce2
3875@option{-dC} and @option{-fdump-rtl-ce1} enable dumping after the
3876first if conversion, to the file @file{@var{file}.117r.ce1}. @option{-dC}
3877and @option{-fdump-rtl-ce2} enable dumping after the second if
3878conversion, to the file @file{@var{file}.130r.ce2}.
3879
3880@item -dd
3881@itemx -fdump-rtl-btl
3882@itemx -fdump-rtl-dbr
3883@opindex dd
3884@opindex fdump-rtl-btl
3885@opindex fdump-rtl-dbr
3886@option{-dd} and @option{-fdump-rtl-btl} enable dumping after branch
3887target load optimization, to @file{@var{file}.31.btl}. @option{-dd}
3888and @option{-fdump-rtl-dbr} enable dumping after delayed branch
3889scheduling, to @file{@var{file}.36.dbr}.
3890
3891@item -dD
3892@opindex dD
3893Dump all macro definitions, at the end of preprocessing, in addition to
3894normal output.
3895
3896@item -dE
3897@itemx -fdump-rtl-ce3
3898@opindex dE
3899@opindex fdump-rtl-ce3
3900Dump after the third if conversion, to @file{@var{file}.146r.ce3}.
3901
3902@item -df
3903@itemx -fdump-rtl-cfg
3904@itemx -fdump-rtl-life
3905@opindex df
3906@opindex fdump-rtl-cfg
3907@opindex fdump-rtl-life
3908@option{-df} and @option{-fdump-rtl-cfg} enable dumping after control
3909and data flow analysis, to @file{@var{file}.116r.cfg}. @option{-df}
3910and @option{-fdump-rtl-cfg} enable dumping dump after life analysis,
3911to @file{@var{file}.128r.life1} and @file{@var{file}.135r.life2}.
3912
3913@item -dg
3914@itemx -fdump-rtl-greg
3915@opindex dg
3916@opindex fdump-rtl-greg
3917Dump after global register allocation, to @file{@var{file}.139r.greg}.
3918
3919@item -dG
3920@itemx -fdump-rtl-gcse
3921@itemx -fdump-rtl-bypass
3922@opindex dG
3923@opindex fdump-rtl-gcse
3924@opindex fdump-rtl-bypass
3925@option{-dG} and @option{-fdump-rtl-gcse} enable dumping after GCSE, to
3926@file{@var{file}.114r.gcse}. @option{-dG} and @option{-fdump-rtl-bypass}
3927enable dumping after jump bypassing and control flow optimizations, to
3928@file{@var{file}.115r.bypass}.
3929
3930@item -dh
3931@itemx -fdump-rtl-eh
3932@opindex dh
3933@opindex fdump-rtl-eh
3934Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
3935
3936@item -di
3937@itemx -fdump-rtl-sibling
3938@opindex di
3939@opindex fdump-rtl-sibling
3940Dump after sibling call optimizations, to @file{@var{file}.106r.sibling}.
3941
3942@item -dj
3943@itemx -fdump-rtl-jump
3944@opindex dj
3945@opindex fdump-rtl-jump
3946Dump after the first jump optimization, to @file{@var{file}.112r.jump}.
3947
3948@item -dk
3949@itemx -fdump-rtl-stack
3950@opindex dk
3951@opindex fdump-rtl-stack
3952Dump after conversion from registers to stack, to @file{@var{file}.152r.stack}.
3953
3954@item -dl
3955@itemx -fdump-rtl-lreg
3956@opindex dl
3957@opindex fdump-rtl-lreg
3958Dump after local register allocation, to @file{@var{file}.138r.lreg}.
3959
3960@item -dL
3961@itemx -fdump-rtl-loop2
3962@opindex dL
3963@opindex fdump-rtl-loop2
3964@option{-dL} and @option{-fdump-rtl-loop2} enable dumping after the
3965loop optimization pass, to @file{@var{file}.119r.loop2},
3966@file{@var{file}.120r.loop2_init},
3967@file{@var{file}.121r.loop2_invariant}, and
3968@file{@var{file}.125r.loop2_done}.
3969
3970@item -dm
3971@itemx -fdump-rtl-sms
3972@opindex dm
3973@opindex fdump-rtl-sms
3974Dump after modulo scheduling, to @file{@var{file}.136r.sms}.
3975
3976@item -dM
3977@itemx -fdump-rtl-mach
3978@opindex dM
3979@opindex fdump-rtl-mach
3980Dump after performing the machine dependent reorganization pass, to
3981@file{@var{file}.155r.mach}.
3982
3983@item -dn
3984@itemx -fdump-rtl-rnreg
3985@opindex dn
3986@opindex fdump-rtl-rnreg
3987Dump after register renumbering, to @file{@var{file}.147r.rnreg}.
3988
3989@item -dN
3990@itemx -fdump-rtl-regmove
3991@opindex dN
3992@opindex fdump-rtl-regmove
3993Dump after the register move pass, to @file{@var{file}.132r.regmove}.
3994
3995@item -do
3996@itemx -fdump-rtl-postreload
3997@opindex do
3998@opindex fdump-rtl-postreload
3999Dump after post-reload optimizations, to @file{@var{file}.24.postreload}.
4000
4001@item -dr
4002@itemx -fdump-rtl-expand
4003@opindex dr
4004@opindex fdump-rtl-expand
4005Dump after RTL generation, to @file{@var{file}.104r.expand}.
4006
4007@item -dR
4008@itemx -fdump-rtl-sched2
4009@opindex dR
4010@opindex fdump-rtl-sched2
4011Dump after the second scheduling pass, to @file{@var{file}.150r.sched2}.
4012
4013@item -ds
4014@itemx -fdump-rtl-cse
4015@opindex ds
4016@opindex fdump-rtl-cse
4017Dump after CSE (including the jump optimization that sometimes follows
4018CSE), to @file{@var{file}.113r.cse}.
4019
4020@item -dS
4021@itemx -fdump-rtl-sched
4022@opindex dS
4023@opindex fdump-rtl-sched
4024Dump after the first scheduling pass, to @file{@var{file}.21.sched}.
4025
4026@item -dt
4027@itemx -fdump-rtl-cse2
4028@opindex dt
4029@opindex fdump-rtl-cse2
4030Dump after the second CSE pass (including the jump optimization that
4031sometimes follows CSE), to @file{@var{file}.127r.cse2}.
4032
4033@item -dT
4034@itemx -fdump-rtl-tracer
4035@opindex dT
4036@opindex fdump-rtl-tracer
4037Dump after running tracer, to @file{@var{file}.118r.tracer}.
4038
4039@item -dV
4040@itemx -fdump-rtl-vpt
4041@itemx -fdump-rtl-vartrack
4042@opindex dV
4043@opindex fdump-rtl-vpt
4044@opindex fdump-rtl-vartrack
4045@option{-dV} and @option{-fdump-rtl-vpt} enable dumping after the value
4046profile transformations, to @file{@var{file}.10.vpt}. @option{-dV}
4047and @option{-fdump-rtl-vartrack} enable dumping after variable tracking,
4048to @file{@var{file}.154r.vartrack}.
4049
4050@item -dw
4051@itemx -fdump-rtl-flow2
4052@opindex dw
4053@opindex fdump-rtl-flow2
4054Dump after the second flow pass, to @file{@var{file}.142r.flow2}.
4055
4056@item -dz
4057@itemx -fdump-rtl-peephole2
4058@opindex dz
4059@opindex fdump-rtl-peephole2
4060Dump after the peephole pass, to @file{@var{file}.145r.peephole2}.
4061
4062@item -dZ
4063@itemx -fdump-rtl-web
4064@opindex dZ
4065@opindex fdump-rtl-web
4066Dump after live range splitting, to @file{@var{file}.126r.web}.
4067
4068@item -da
4069@itemx -fdump-rtl-all
4070@opindex da
4071@opindex fdump-rtl-all
4072Produce all the dumps listed above.
4073
4074@item -dH
4075@opindex dH
4076Produce a core dump whenever an error occurs.
4077
4078@item -dm
4079@opindex dm
4080Print statistics on memory usage, at the end of the run, to
4081standard error.
4082
4083@item -dp
4084@opindex dp
4085Annotate the assembler output with a comment indicating which
4086pattern and alternative was used. The length of each instruction is
4087also printed.
4088
4089@item -dP
4090@opindex dP
4091Dump the RTL in the assembler output as a comment before each instruction.
4092Also turns on @option{-dp} annotation.
4093
4094@item -dv
4095@opindex dv
4096For each of the other indicated dump files (either with @option{-d} or
4097@option{-fdump-rtl-@var{pass}}), dump a representation of the control flow
4098graph suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
4099
4100@item -dx
4101@opindex dx
4102Just generate RTL for a function instead of compiling it. Usually used
4103with @samp{r} (@option{-fdump-rtl-expand}).
4104
4105@item -dy
4106@opindex dy
4107Dump debugging information during parsing, to standard error.
4108@end table
4109
4110@item -fdump-noaddr
4111@opindex fdump-noaddr
4112When doing debugging dumps (see @option{-d} option above), suppress
4113address output. This makes it more feasible to use diff on debugging
4114dumps for compiler invocations with different compiler binaries and/or
4115different text / bss / data / heap / stack / dso start locations.
4116
4117@item -fdump-unnumbered
4118@opindex fdump-unnumbered
4119When doing debugging dumps (see @option{-d} option above), suppress instruction
4120numbers, line number note and address output. This makes it more feasible to
4121use diff on debugging dumps for compiler invocations with different
4122options, in particular with and without @option{-g}.
4123
4124@item -fdump-translation-unit @r{(C++ only)}
4125@itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
4126@opindex fdump-translation-unit
4127Dump a representation of the tree structure for the entire translation
4128unit to a file. The file name is made by appending @file{.tu} to the
4129source file name. If the @samp{-@var{options}} form is used, @var{options}
4130controls the details of the dump as described for the
4131@option{-fdump-tree} options.
4132
4133@item -fdump-class-hierarchy @r{(C++ only)}
4134@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
4135@opindex fdump-class-hierarchy
4136Dump a representation of each class's hierarchy and virtual function
4137table layout to a file. The file name is made by appending @file{.class}
4138to the source file name. If the @samp{-@var{options}} form is used,
4139@var{options} controls the details of the dump as described for the
4140@option{-fdump-tree} options.
4141
4142@item -fdump-ipa-@var{switch}
4143@opindex fdump-ipa
4144Control the dumping at various stages of inter-procedural analysis
4145language tree to a file. The file name is generated by appending a switch
4146specific suffix to the source file name. The following dumps are possible:
4147
4148@table @samp
4149@item all
4150Enables all inter-procedural analysis dumps; currently the only produced
4151dump is the @samp{cgraph} dump.
4152
4153@item cgraph
4154Dumps information about call-graph optimization, unused function removal,
4155and inlining decisions.
4156@end table
4157
4158@item -fdump-tree-@var{switch}
4159@itemx -fdump-tree-@var{switch}-@var{options}
4160@opindex fdump-tree
4161Control the dumping at various stages of processing the intermediate
4162language tree to a file. The file name is generated by appending a switch
4163specific suffix to the source file name. If the @samp{-@var{options}}
4164form is used, @var{options} is a list of @samp{-} separated options that
4165control the details of the dump. Not all options are applicable to all
4166dumps, those which are not meaningful will be ignored. The following
4167options are available
4168
4169@table @samp
4170@item address
4171Print the address of each node. Usually this is not meaningful as it
4172changes according to the environment and source file. Its primary use
4173is for tying up a dump file with a debug environment.
4174@item slim
4175Inhibit dumping of members of a scope or body of a function merely
4176because that scope has been reached. Only dump such items when they
4177are directly reachable by some other path. When dumping pretty-printed
4178trees, this option inhibits dumping the bodies of control structures.
4179@item raw
4180Print a raw representation of the tree. By default, trees are
4181pretty-printed into a C-like representation.
4182@item details
4183Enable more detailed dumps (not honored by every dump option).
4184@item stats
4185Enable dumping various statistics about the pass (not honored by every dump
4186option).
4187@item blocks
4188Enable showing basic block boundaries (disabled in raw dumps).
4189@item vops
4190Enable showing virtual operands for every statement.
4191@item lineno
4192Enable showing line numbers for statements.
4193@item uid
4194Enable showing the unique ID (@code{DECL_UID}) for each variable.
4195@item all
4196Turn on all options, except @option{raw}, @option{slim} and @option{lineno}.
4197@end table
4198
4199The following tree dumps are possible:
4200@table @samp
4201
4202@item original
4203Dump before any tree based optimization, to @file{@var{file}.original}.
4204
4205@item optimized
4206Dump after all tree based optimization, to @file{@var{file}.optimized}.
4207
4208@item inlined
4209Dump after function inlining, to @file{@var{file}.inlined}.
4210
4211@item gimple
4212@opindex fdump-tree-gimple
4213Dump each function before and after the gimplification pass to a file. The
4214file name is made by appending @file{.gimple} to the source file name.
4215
4216@item cfg
4217@opindex fdump-tree-cfg
4218Dump the control flow graph of each function to a file. The file name is
4219made by appending @file{.cfg} to the source file name.
4220
4221@item vcg
4222@opindex fdump-tree-vcg
4223Dump the control flow graph of each function to a file in VCG format. The
4224file name is made by appending @file{.vcg} to the source file name. Note
4225that if the file contains more than one function, the generated file cannot
4226be used directly by VCG@. You will need to cut and paste each function's
4227graph into its own separate file first.
4228
4229@item ch
4230@opindex fdump-tree-ch
4231Dump each function after copying loop headers. The file name is made by
4232appending @file{.ch} to the source file name.
4233
4234@item ssa
4235@opindex fdump-tree-ssa
4236Dump SSA related information to a file. The file name is made by appending
4237@file{.ssa} to the source file name.
4238
4239@item salias
4240@opindex fdump-tree-salias
4241Dump structure aliasing variable information to a file. This file name
4242is made by appending @file{.salias} to the source file name.
4243
4244@item alias
4245@opindex fdump-tree-alias
4246Dump aliasing information for each function. The file name is made by
4247appending @file{.alias} to the source file name.
4248
4249@item ccp
4250@opindex fdump-tree-ccp
4251Dump each function after CCP@. The file name is made by appending
4252@file{.ccp} to the source file name.
4253
4254@item storeccp
4255@opindex fdump-tree-storeccp
4256Dump each function after STORE-CCP. The file name is made by appending
4257@file{.storeccp} to the source file name.
4258
4259@item pre
4260@opindex fdump-tree-pre
4261Dump trees after partial redundancy elimination. The file name is made
4262by appending @file{.pre} to the source file name.
4263
4264@item fre
4265@opindex fdump-tree-fre
4266Dump trees after full redundancy elimination. The file name is made
4267by appending @file{.fre} to the source file name.
4268
4269@item copyprop
4270@opindex fdump-tree-copyprop
4271Dump trees after copy propagation. The file name is made
4272by appending @file{.copyprop} to the source file name.
4273
4274@item store_copyprop
4275@opindex fdump-tree-store_copyprop
4276Dump trees after store copy-propagation. The file name is made
4277by appending @file{.store_copyprop} to the source file name.
4278
4279@item dce
4280@opindex fdump-tree-dce
4281Dump each function after dead code elimination. The file name is made by
4282appending @file{.dce} to the source file name.
4283
4284@item mudflap
4285@opindex fdump-tree-mudflap
4286Dump each function after adding mudflap instrumentation. The file name is
4287made by appending @file{.mudflap} to the source file name.
4288
4289@item sra
4290@opindex fdump-tree-sra
4291Dump each function after performing scalar replacement of aggregates. The
4292file name is made by appending @file{.sra} to the source file name.
4293
4294@item sink
4295@opindex fdump-tree-sink
4296Dump each function after performing code sinking. The file name is made
4297by appending @file{.sink} to the source file name.
4298
4299@item dom
4300@opindex fdump-tree-dom
4301Dump each function after applying dominator tree optimizations. The file
4302name is made by appending @file{.dom} to the source file name.
4303
4304@item dse
4305@opindex fdump-tree-dse
4306Dump each function after applying dead store elimination. The file
4307name is made by appending @file{.dse} to the source file name.
4308
4309@item phiopt
4310@opindex fdump-tree-phiopt
4311Dump each function after optimizing PHI nodes into straightline code. The file
4312name is made by appending @file{.phiopt} to the source file name.
4313
4314@item forwprop
4315@opindex fdump-tree-forwprop
4316Dump each function after forward propagating single use variables. The file
4317name is made by appending @file{.forwprop} to the source file name.
4318
4319@item copyrename
4320@opindex fdump-tree-copyrename
4321Dump each function after applying the copy rename optimization. The file
4322name is made by appending @file{.copyrename} to the source file name.
4323
4324@item nrv
4325@opindex fdump-tree-nrv
4326Dump each function after applying the named return value optimization on
4327generic trees. The file name is made by appending @file{.nrv} to the source
4328file name.
4329
4330@item vect
4331@opindex fdump-tree-vect
4332Dump each function after applying vectorization of loops. The file name is
4333made by appending @file{.vect} to the source file name.
4334
4335@item vrp
4336@opindex fdump-tree-vrp
4337Dump each function after Value Range Propagation (VRP). The file name
4338is made by appending @file{.vrp} to the source file name.
4339
4340@item all
4341@opindex fdump-tree-all
4342Enable all the available tree dumps with the flags provided in this option.
4343@end table
4344
4345@item -ftree-vectorizer-verbose=@var{n}
4346@opindex ftree-vectorizer-verbose
4347This option controls the amount of debugging output the vectorizer prints.
4348This information is written to standard error, unless
4349@option{-fdump-tree-all} or @option{-fdump-tree-vect} is specified,
4350in which case it is output to the usual dump listing file, @file{.vect}.
4351For @var{n}=0 no diagnostic information is reported.
4352If @var{n}=1 the vectorizer reports each loop that got vectorized,
4353and the total number of loops that got vectorized.
4354If @var{n}=2 the vectorizer also reports non-vectorized loops that passed
4355the first analysis phase (vect_analyze_loop_form) - i.e. countable,
4356inner-most, single-bb, single-entry/exit loops. This is the same verbosity
4357level that @option{-fdump-tree-vect-stats} uses.
4358Higher verbosity levels mean either more information dumped for each
4359reported loop, or same amount of information reported for more loops:
4360If @var{n}=3, alignment related information is added to the reports.
4361If @var{n}=4, data-references related information (e.g. memory dependences,
4362memory access-patterns) is added to the reports.
4363If @var{n}=5, the vectorizer reports also non-vectorized inner-most loops
4364that did not pass the first analysis phase (i.e. may not be countable, or
4365may have complicated control-flow).
4366If @var{n}=6, the vectorizer reports also non-vectorized nested loops.
4367For @var{n}=7, all the information the vectorizer generates during its
4368analysis and transformation is reported. This is the same verbosity level
4369that @option{-fdump-tree-vect-details} uses.
4370
4371@item -frandom-seed=@var{string}
4372@opindex frandom-string
4373This option provides a seed that GCC uses when it would otherwise use
4374random numbers. It is used to generate certain symbol names
4375that have to be different in every compiled file. It is also used to
4376place unique stamps in coverage data files and the object files that
4377produce them. You can use the @option{-frandom-seed} option to produce
4378reproducibly identical object files.
4379
4380The @var{string} should be different for every file you compile.
4381
4382@item -fsched-verbose=@var{n}
4383@opindex fsched-verbose
4384On targets that use instruction scheduling, this option controls the
4385amount of debugging output the scheduler prints. This information is
4386written to standard error, unless @option{-dS} or @option{-dR} is
4387specified, in which case it is output to the usual dump
4388listing file, @file{.sched} or @file{.sched2} respectively. However
4389for @var{n} greater than nine, the output is always printed to standard
4390error.
4391
4392For @var{n} greater than zero, @option{-fsched-verbose} outputs the
4393same information as @option{-dRS}. For @var{n} greater than one, it
4394also output basic block probabilities, detailed ready list information
4395and unit/insn info. For @var{n} greater than two, it includes RTL
4396at abort point, control-flow and regions info. And for @var{n} over
4397four, @option{-fsched-verbose} also includes dependence info.
4398
4399@item -save-temps
4400@opindex save-temps
4401Store the usual ``temporary'' intermediate files permanently; place them
4402in the current directory and name them based on the source file. Thus,
4403compiling @file{foo.c} with @samp{-c -save-temps} would produce files
4404@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
4405preprocessed @file{foo.i} output file even though the compiler now
4406normally uses an integrated preprocessor.
4407
4408When used in combination with the @option{-x} command line option,
4409@option{-save-temps} is sensible enough to avoid over writing an
4410input source file with the same extension as an intermediate file.
4411The corresponding intermediate file may be obtained by renaming the
4412source file before using @option{-save-temps}.
4413
4414@item -time
4415@opindex time
4416Report the CPU time taken by each subprocess in the compilation
4417sequence. For C source files, this is the compiler proper and assembler
4418(plus the linker if linking is done). The output looks like this:
4419
4420@smallexample
4421# cc1 0.12 0.01
4422# as 0.00 0.01
4423@end smallexample
4424
4425The first number on each line is the ``user time'', that is time spent
4426executing the program itself. The second number is ``system time'',
4427time spent executing operating system routines on behalf of the program.
4428Both numbers are in seconds.
4429
4430@item -fvar-tracking
4431@opindex fvar-tracking
4432Run variable tracking pass. It computes where variables are stored at each
4433position in code. Better debugging information is then generated
4434(if the debugging information format supports this information).
4435
4436It is enabled by default when compiling with optimization (@option{-Os},
4437@option{-O}, @option{-O2}, ...), debugging information (@option{-g}) and
4438the debug info format supports it.
4439
4440@item -print-file-name=@var{library}
4441@opindex print-file-name
4442Print the full absolute name of the library file @var{library} that
4443would be used when linking---and don't do anything else. With this
4444option, GCC does not compile or link anything; it just prints the
4445file name.
4446
4447@item -print-multi-directory
4448@opindex print-multi-directory
4449Print the directory name corresponding to the multilib selected by any
4450other switches present in the command line. This directory is supposed
4451to exist in @env{GCC_EXEC_PREFIX}.
4452
4453@item -print-multi-lib
4454@opindex print-multi-lib
4455Print the mapping from multilib directory names to compiler switches
4456that enable them. The directory name is separated from the switches by
4457@samp{;}, and each switch starts with an @samp{@@} instead of the
4458@samp{-}, without spaces between multiple switches. This is supposed to
4459ease shell-processing.
4460
4461@item -print-prog-name=@var{program}
4462@opindex print-prog-name
4463Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
4464
4465@item -print-libgcc-file-name
4466@opindex print-libgcc-file-name
4467Same as @option{-print-file-name=libgcc.a}.
4468
4469This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
4470but you do want to link with @file{libgcc.a}. You can do
4471
4472@smallexample
4473gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
4474@end smallexample
4475
4476@item -print-search-dirs
4477@opindex print-search-dirs
4478Print the name of the configured installation directory and a list of
4479program and library directories @command{gcc} will search---and don't do anything else.
4480
4481This is useful when @command{gcc} prints the error message
4482@samp{installation problem, cannot exec cpp0: No such file or directory}.
4483To resolve this you either need to put @file{cpp0} and the other compiler
4484components where @command{gcc} expects to find them, or you can set the environment
4485variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
4486Don't forget the trailing @samp{/}.
4487@xref{Environment Variables}.
4488
4489@item -dumpmachine
4490@opindex dumpmachine
4491Print the compiler's target machine (for example,
4492@samp{i686-pc-linux-gnu})---and don't do anything else.
4493
4494@item -dumpversion
4495@opindex dumpversion
4496Print the compiler version (for example, @samp{3.0})---and don't do
4497anything else.
4498
4499@item -dumpspecs
4500@opindex dumpspecs
4501Print the compiler's built-in specs---and don't do anything else. (This
4502is used when GCC itself is being built.) @xref{Spec Files}.
4503
4504@item -feliminate-unused-debug-types
4505@opindex feliminate-unused-debug-types
4506Normally, when producing DWARF2 output, GCC will emit debugging
4507information for all types declared in a compilation
4508unit, regardless of whether or not they are actually used
4509in that compilation unit. Sometimes this is useful, such as
4510if, in the debugger, you want to cast a value to a type that is
4511not actually used in your program (but is declared). More often,
4512however, this results in a significant amount of wasted space.
4513With this option, GCC will avoid producing debug symbol output
4514for types that are nowhere used in the source file being compiled.
4515@end table
4516
4517@node Optimize Options
4518@section Options That Control Optimization
4519@cindex optimize options
4520@cindex options, optimization
4521
4522These options control various sorts of optimizations.
4523
4524Without any optimization option, the compiler's goal is to reduce the
4525cost of compilation and to make debugging produce the expected
4526results. Statements are independent: if you stop the program with a
4527breakpoint between statements, you can then assign a new value to any
4528variable or change the program counter to any other statement in the
4529function and get exactly the results you would expect from the source
4530code.
4531
4532Turning on optimization flags makes the compiler attempt to improve
4533the performance and/or code size at the expense of compilation time
4534and possibly the ability to debug the program.
4535
4536The compiler performs optimization based on the knowledge it has of
4537the program. Optimization levels @option{-O} and above, in
4538particular, enable @emph{unit-at-a-time} mode, which allows the
4539compiler to consider information gained from later functions in
4540the file when compiling a function. Compiling multiple files at
4541once to a single output file in @emph{unit-at-a-time} mode allows
4542the compiler to use information gained from all of the files when
4543compiling each of them.
4544
4545Not all optimizations are controlled directly by a flag. Only
4546optimizations that have a flag are listed.
4547
4548@table @gcctabopt
4549@item -O
4550@itemx -O1
4551@opindex O
4552@opindex O1
4553Optimize. Optimizing compilation takes somewhat more time, and a lot
4554more memory for a large function.
4555
4556With @option{-O}, the compiler tries to reduce code size and execution
4557time, without performing any optimizations that take a great deal of
4558compilation time.
4559
4560@option{-O} turns on the following optimization flags:
4561@gccoptlist{-fdefer-pop @gol
4562-fdelayed-branch @gol
4563-fguess-branch-probability @gol
4564-fcprop-registers @gol
4565-fif-conversion @gol
4566-fif-conversion2 @gol
4567-ftree-ccp @gol
4568-ftree-dce @gol
4569-ftree-dominator-opts @gol
4570-ftree-dse @gol
4571-ftree-ter @gol
4572-ftree-lrs @gol
4573-ftree-sra @gol
4574-ftree-copyrename @gol
4575-ftree-fre @gol
4576-ftree-ch @gol
4577-funit-at-a-time @gol
4578-fmerge-constants}
4579
4580@option{-O} also turns on @option{-fomit-frame-pointer} on machines
4581where doing so does not interfere with debugging.
4582
4583@item -O2
4584@opindex O2
4585Optimize even more. GCC performs nearly all supported optimizations
4586that do not involve a space-speed tradeoff. The compiler does not
4587perform loop unrolling or function inlining when you specify @option{-O2}.
4588As compared to @option{-O}, this option increases both compilation time
4589and the performance of the generated code.
4590
4591@option{-O2} turns on all optimization flags specified by @option{-O}. It
4592also turns on the following optimization flags:
4593@gccoptlist{-fthread-jumps @gol
4594-fcrossjumping @gol
4595-foptimize-sibling-calls @gol
4596-fcse-follow-jumps -fcse-skip-blocks @gol
4597-fgcse -fgcse-lm @gol
4598-fexpensive-optimizations @gol
4599-frerun-cse-after-loop @gol
4600-fcaller-saves @gol
4601-fpeephole2 @gol
4602-fschedule-insns -fschedule-insns2 @gol
4603-fsched-interblock -fsched-spec @gol
4604-fregmove @gol
4605-fstrict-aliasing -fstrict-overflow @gol
4606-fdelete-null-pointer-checks @gol
4607-freorder-blocks -freorder-functions @gol
4608-falign-functions -falign-jumps @gol
4609-falign-loops -falign-labels @gol
4610-ftree-vrp @gol
4611-ftree-pre}
4612
4613Please note the warning under @option{-fgcse} about
4614invoking @option{-O2} on programs that use computed gotos.
4615
4616@option{-O2} doesn't turn on @option{-ftree-vrp} for the Ada compiler.
4617This option must be explicitly specified on the command line to be
4618enabled for the Ada compiler.
4619
4620@item -O3
4621@opindex O3
4622Optimize yet more. @option{-O3} turns on all optimizations specified by
4623@option{-O2} and also turns on the @option{-finline-functions},
4624@option{-funswitch-loops} and @option{-fgcse-after-reload} options.
4625
4626@item -O0
4627@opindex O0
4628Do not optimize. This is the default.
4629
4630@item -Os
4631@opindex Os
4632Optimize for size. @option{-Os} enables all @option{-O2} optimizations that
4633do not typically increase code size. It also performs further
4634optimizations designed to reduce code size.
4635
4636@option{-Os} disables the following optimization flags:
4637@gccoptlist{-falign-functions -falign-jumps -falign-loops @gol
4638-falign-labels -freorder-blocks -freorder-blocks-and-partition @gol
4639-fprefetch-loop-arrays -ftree-vect-loop-version}
4640
4641If you use multiple @option{-O} options, with or without level numbers,
4642the last such option is the one that is effective.
4643@end table
4644
4645Options of the form @option{-f@var{flag}} specify machine-independent
4646flags. Most flags have both positive and negative forms; the negative
4647form of @option{-ffoo} would be @option{-fno-foo}. In the table
4648below, only one of the forms is listed---the one you typically will
4649use. You can figure out the other form by either removing @samp{no-}
4650or adding it.
4651
4652The following options control specific optimizations. They are either
4653activated by @option{-O} options or are related to ones that are. You
4654can use the following flags in the rare cases when ``fine-tuning'' of
4655optimizations to be performed is desired.
4656
4657@table @gcctabopt
4658@item -fno-default-inline
4659@opindex fno-default-inline
4660Do not make member functions inline by default merely because they are
4661defined inside the class scope (C++ only). Otherwise, when you specify
4662@w{@option{-O}}, member functions defined inside class scope are compiled
4663inline by default; i.e., you don't need to add @samp{inline} in front of
4664the member function name.
4665
4666@item -fno-defer-pop
4667@opindex fno-defer-pop
4668Always pop the arguments to each function call as soon as that function
4669returns. For machines which must pop arguments after a function call,
4670the compiler normally lets arguments accumulate on the stack for several
4671function calls and pops them all at once.
4672
4673Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4674
4675@item -fforce-mem
4676@opindex fforce-mem
4677Force memory operands to be copied into registers before doing
4678arithmetic on them. This produces better code by making all memory
4679references potential common subexpressions. When they are not common
4680subexpressions, instruction combination should eliminate the separate
4681register-load. This option is now a nop and will be removed in 4.3.
4682
4683@item -fforce-addr
4684@opindex fforce-addr
4685Force memory address constants to be copied into registers before
4686doing arithmetic on them.
4687
4688@item -fomit-frame-pointer
4689@opindex fomit-frame-pointer
4690Don't keep the frame pointer in a register for functions that
4691don't need one. This avoids the instructions to save, set up and
4692restore frame pointers; it also makes an extra register available
4693in many functions. @strong{It also makes debugging impossible on
4694some machines.}
4695
4696On some machines, such as the VAX, this flag has no effect, because
4697the standard calling sequence automatically handles the frame pointer
4698and nothing is saved by pretending it doesn't exist. The
4699machine-description macro @code{FRAME_POINTER_REQUIRED} controls
4700whether a target machine supports this flag. @xref{Registers,,Register
4701Usage, gccint, GNU Compiler Collection (GCC) Internals}.
4702
4703Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4704
4705@item -foptimize-sibling-calls
4706@opindex foptimize-sibling-calls
4707Optimize sibling and tail recursive calls.
4708
4709Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4710
4711@item -fno-inline
4712@opindex fno-inline
4713Don't pay attention to the @code{inline} keyword. Normally this option
4714is used to keep the compiler from expanding any functions inline.
4715Note that if you are not optimizing, no functions can be expanded inline.
4716
4717@item -finline-functions
4718@opindex finline-functions
4719Integrate all simple functions into their callers. The compiler
4720heuristically decides which functions are simple enough to be worth
4721integrating in this way.
4722
4723If all calls to a given function are integrated, and the function is
4724declared @code{static}, then the function is normally not output as
4725assembler code in its own right.
4726
4727Enabled at level @option{-O3}.
4728
4729@item -finline-functions-called-once
4730@opindex finline-functions-called-once
4731Consider all @code{static} functions called once for inlining into their
4732caller even if they are not marked @code{inline}. If a call to a given
4733function is integrated, then the function is not output as assembler code
4734in its own right.
4735
4736Enabled if @option{-funit-at-a-time} is enabled.
4737
4738@item -fearly-inlining
4739@opindex fearly-inlining
4740Inline functions marked by @code{always_inline} and functions whose body seems
4741smaller than the function call overhead early before doing
4742@option{-fprofile-generate} instrumentation and real inlining pass. Doing so
4743makes profiling significantly cheaper and usually inlining faster on programs
4744having large chains of nested wrapper functions.
4745
4746Enabled by default.
4747
4748@item -finline-limit=@var{n}
4749@opindex finline-limit
4750By default, GCC limits the size of functions that can be inlined. This flag
4751allows the control of this limit for functions that are explicitly marked as
4752inline (i.e., marked with the inline keyword or defined within the class
4753definition in c++). @var{n} is the size of functions that can be inlined in
4754number of pseudo instructions (not counting parameter handling). The default
4755value of @var{n} is 600.
4756Increasing this value can result in more inlined code at
4757the cost of compilation time and memory consumption. Decreasing usually makes
4758the compilation faster and less code will be inlined (which presumably
4759means slower programs). This option is particularly useful for programs that
4760use inlining heavily such as those based on recursive templates with C++.
4761
4762Inlining is actually controlled by a number of parameters, which may be
4763specified individually by using @option{--param @var{name}=@var{value}}.
4764The @option{-finline-limit=@var{n}} option sets some of these parameters
4765as follows:
4766
4767@table @gcctabopt
4768@item max-inline-insns-single
4769 is set to @var{n}/2.
4770@item max-inline-insns-auto
4771 is set to @var{n}/2.
4772@item min-inline-insns
4773 is set to 130 or @var{n}/4, whichever is smaller.
4774@item max-inline-insns-rtl
4775 is set to @var{n}.
4776@end table
4777
4778See below for a documentation of the individual
4779parameters controlling inlining.
4780
4781@emph{Note:} pseudo instruction represents, in this particular context, an
4782abstract measurement of function's size. In no way does it represent a count
4783of assembly instructions and as such its exact meaning might change from one
4784release to an another.
4785
4786@item -fkeep-inline-functions
4787@opindex fkeep-inline-functions
4788In C, emit @code{static} functions that are declared @code{inline}
4789into the object file, even if the function has been inlined into all
4790of its callers. This switch does not affect functions using the
4791@code{extern inline} extension in GNU C@. In C++, emit any and all
4792inline functions into the object file.
4793
4794@item -fkeep-static-consts
4795@opindex fkeep-static-consts
4796Emit variables declared @code{static const} when optimization isn't turned
4797on, even if the variables aren't referenced.
4798
4799GCC enables this option by default. If you want to force the compiler to
4800check if the variable was referenced, regardless of whether or not
4801optimization is turned on, use the @option{-fno-keep-static-consts} option.
4802
4803@item -fmerge-constants
4804Attempt to merge identical constants (string constants and floating point
4805constants) across compilation units.
4806
4807This option is the default for optimized compilation if the assembler and
4808linker support it. Use @option{-fno-merge-constants} to inhibit this
4809behavior.
4810
4811Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
4812
4813@item -fmerge-all-constants
4814Attempt to merge identical constants and identical variables.
4815
4816This option implies @option{-fmerge-constants}. In addition to
4817@option{-fmerge-constants} this considers e.g.@: even constant initialized
4818arrays or initialized constant variables with integral or floating point
4819types. Languages like C or C++ require each non-automatic variable to
4820have distinct location, so using this option will result in non-conforming
4821behavior.
4822
4823@item -fmodulo-sched
4824@opindex fmodulo-sched
4825Perform swing modulo scheduling immediately before the first scheduling
4826pass. This pass looks at innermost loops and reorders their
4827instructions by overlapping different iterations.
4828
4829@item -fno-branch-count-reg
4830@opindex fno-branch-count-reg
4831Do not use ``decrement and branch'' instructions on a count register,
4832but instead generate a sequence of instructions that decrement a
4833register, compare it against zero, then branch based upon the result.
4834This option is only meaningful on architectures that support such
4835instructions, which include x86, PowerPC, IA-64 and S/390.
4836
4837The default is @option{-fbranch-count-reg}.
4838
4839@item -fno-function-cse
4840@opindex fno-function-cse
4841Do not put function addresses in registers; make each instruction that
4842calls a constant function contain the function's address explicitly.
4843
4844This option results in less efficient code, but some strange hacks
4845that alter the assembler output may be confused by the optimizations
4846performed when this option is not used.
4847
4848The default is @option{-ffunction-cse}
4849
4850@item -fno-zero-initialized-in-bss
4851@opindex fno-zero-initialized-in-bss
4852If the target supports a BSS section, GCC by default puts variables that
4853are initialized to zero into BSS@. This can save space in the resulting
4854code.
4855
4856This option turns off this behavior because some programs explicitly
4857rely on variables going to the data section. E.g., so that the
4858resulting executable can find the beginning of that section and/or make
4859assumptions based on that.
4860
4861The default is @option{-fzero-initialized-in-bss}.
4862
4863@item -fbounds-check
4864@opindex fbounds-check
4865For front-ends that support it, generate additional code to check that
4866indices used to access arrays are within the declared range. This is
4867currently only supported by the Java and Fortran front-ends, where
4868this option defaults to true and false respectively.
4869
4870@item -fmudflap -fmudflapth -fmudflapir
4871@opindex fmudflap
4872@opindex fmudflapth
4873@opindex fmudflapir
4874@cindex bounds checking
4875@cindex mudflap
4876For front-ends that support it (C and C++), instrument all risky
4877pointer/array dereferencing operations, some standard library
4878string/heap functions, and some other associated constructs with
4879range/validity tests. Modules so instrumented should be immune to
4880buffer overflows, invalid heap use, and some other classes of C/C++
4881programming errors. The instrumentation relies on a separate runtime
4882library (@file{libmudflap}), which will be linked into a program if
4883@option{-fmudflap} is given at link time. Run-time behavior of the
4884instrumented program is controlled by the @env{MUDFLAP_OPTIONS}
4885environment variable. See @code{env MUDFLAP_OPTIONS=-help a.out}
4886for its options.
4887
4888Use @option{-fmudflapth} instead of @option{-fmudflap} to compile and to
4889link if your program is multi-threaded. Use @option{-fmudflapir}, in
4890addition to @option{-fmudflap} or @option{-fmudflapth}, if
4891instrumentation should ignore pointer reads. This produces less
4892instrumentation (and therefore faster execution) and still provides
4893some protection against outright memory corrupting writes, but allows
4894erroneously read data to propagate within a program.
4895
4896@item -fthread-jumps
4897@opindex fthread-jumps
4898Perform optimizations where we check to see if a jump branches to a
4899location where another comparison subsumed by the first is found. If
4900so, the first branch is redirected to either the destination of the
4901second branch or a point immediately following it, depending on whether
4902the condition is known to be true or false.
4903
4904Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4905
4906@item -fcse-follow-jumps
4907@opindex fcse-follow-jumps
4908In common subexpression elimination, scan through jump instructions
4909when the target of the jump is not reached by any other path. For
4910example, when CSE encounters an @code{if} statement with an
4911@code{else} clause, CSE will follow the jump when the condition
4912tested is false.
4913
4914Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4915
4916@item -fcse-skip-blocks
4917@opindex fcse-skip-blocks
4918This is similar to @option{-fcse-follow-jumps}, but causes CSE to
4919follow jumps which conditionally skip over blocks. When CSE
4920encounters a simple @code{if} statement with no else clause,
4921@option{-fcse-skip-blocks} causes CSE to follow the jump around the
4922body of the @code{if}.
4923
4924Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4925
4926@item -frerun-cse-after-loop
4927@opindex frerun-cse-after-loop
4928Re-run common subexpression elimination after loop optimizations has been
4929performed.
4930
4931Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4932
4933@item -fgcse
4934@opindex fgcse
4935Perform a global common subexpression elimination pass.
4936This pass also performs global constant and copy propagation.
4937
4938@emph{Note:} When compiling a program using computed gotos, a GCC
4939extension, you may get better runtime performance if you disable
4940the global common subexpression elimination pass by adding
4941@option{-fno-gcse} to the command line.
4942
4943Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4944
4945@item -fgcse-lm
4946@opindex fgcse-lm
4947When @option{-fgcse-lm} is enabled, global common subexpression elimination will
4948attempt to move loads which are only killed by stores into themselves. This
4949allows a loop containing a load/store sequence to be changed to a load outside
4950the loop, and a copy/store within the loop.
4951
4952Enabled by default when gcse is enabled.
4953
4954@item -fgcse-sm
4955@opindex fgcse-sm
4956When @option{-fgcse-sm} is enabled, a store motion pass is run after
4957global common subexpression elimination. This pass will attempt to move
4958stores out of loops. When used in conjunction with @option{-fgcse-lm},
4959loops containing a load/store sequence can be changed to a load before
4960the loop and a store after the loop.
4961
4962Not enabled at any optimization level.
4963
4964@item -fgcse-las
4965@opindex fgcse-las
4966When @option{-fgcse-las} is enabled, the global common subexpression
4967elimination pass eliminates redundant loads that come after stores to the
4968same memory location (both partial and full redundancies).
4969
4970Not enabled at any optimization level.
4971
4972@item -fgcse-after-reload
4973@opindex fgcse-after-reload
4974When @option{-fgcse-after-reload} is enabled, a redundant load elimination
4975pass is performed after reload. The purpose of this pass is to cleanup
4976redundant spilling.
4977
4978@item -funsafe-loop-optimizations
4979@opindex funsafe-loop-optimizations
4980If given, the loop optimizer will assume that loop indices do not
4981overflow, and that the loops with nontrivial exit condition are not
4982infinite. This enables a wider range of loop optimizations even if
4983the loop optimizer itself cannot prove that these assumptions are valid.
4984Using @option{-Wunsafe-loop-optimizations}, the compiler will warn you
4985if it finds this kind of loop.
4986
4987@item -fcrossjumping
4988@opindex crossjumping
4989Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
4990resulting code may or may not perform better than without cross-jumping.
4991
4992Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
4993
4994@item -fif-conversion
4995@opindex if-conversion
4996Attempt to transform conditional jumps into branch-less equivalents. This
4997include use of conditional moves, min, max, set flags and abs instructions, and
4998some tricks doable by standard arithmetics. The use of conditional execution
4999on chips where it is available is controlled by @code{if-conversion2}.
5000
5001Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5002
5003@item -fif-conversion2
5004@opindex if-conversion2
5005Use conditional execution (where available) to transform conditional jumps into
5006branch-less equivalents.
5007
5008Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5009
5010@item -fdelete-null-pointer-checks
5011@opindex fdelete-null-pointer-checks
5012Use global dataflow analysis to identify and eliminate useless checks
5013for null pointers. The compiler assumes that dereferencing a null
5014pointer would have halted the program. If a pointer is checked after
5015it has already been dereferenced, it cannot be null.
5016
5017In some environments, this assumption is not true, and programs can
5018safely dereference null pointers. Use
5019@option{-fno-delete-null-pointer-checks} to disable this optimization
5020for programs which depend on that behavior.
5021
5022Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5023
5024@item -fexpensive-optimizations
5025@opindex fexpensive-optimizations
5026Perform a number of minor optimizations that are relatively expensive.
5027
5028Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5029
5030@item -foptimize-register-move
5031@itemx -fregmove
5032@opindex foptimize-register-move
5033@opindex fregmove
5034Attempt to reassign register numbers in move instructions and as
5035operands of other simple instructions in order to maximize the amount of
5036register tying. This is especially helpful on machines with two-operand
5037instructions.
5038
5039Note @option{-fregmove} and @option{-foptimize-register-move} are the same
5040optimization.
5041
5042Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5043
5044@item -fdelayed-branch
5045@opindex fdelayed-branch
5046If supported for the target machine, attempt to reorder instructions
5047to exploit instruction slots available after delayed branch
5048instructions.
5049
5050Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5051
5052@item -fschedule-insns
5053@opindex fschedule-insns
5054If supported for the target machine, attempt to reorder instructions to
5055eliminate execution stalls due to required data being unavailable. This
5056helps machines that have slow floating point or memory load instructions
5057by allowing other instructions to be issued until the result of the load
5058or floating point instruction is required.
5059
5060Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5061
5062@item -fschedule-insns2
5063@opindex fschedule-insns2
5064Similar to @option{-fschedule-insns}, but requests an additional pass of
5065instruction scheduling after register allocation has been done. This is
5066especially useful on machines with a relatively small number of
5067registers and where memory load instructions take more than one cycle.
5068
5069Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5070
5071@item -fno-sched-interblock
5072@opindex fno-sched-interblock
5073Don't schedule instructions across basic blocks. This is normally
5074enabled by default when scheduling before register allocation, i.e.@:
5075with @option{-fschedule-insns} or at @option{-O2} or higher.
5076
5077@item -fno-sched-spec
5078@opindex fno-sched-spec
5079Don't allow speculative motion of non-load instructions. This is normally
5080enabled by default when scheduling before register allocation, i.e.@:
5081with @option{-fschedule-insns} or at @option{-O2} or higher.
5082
5083@item -fsched-spec-load
5084@opindex fsched-spec-load
5085Allow speculative motion of some load instructions. This only makes
5086sense when scheduling before register allocation, i.e.@: with
5087@option{-fschedule-insns} or at @option{-O2} or higher.
5088
5089@item -fsched-spec-load-dangerous
5090@opindex fsched-spec-load-dangerous
5091Allow speculative motion of more load instructions. This only makes
5092sense when scheduling before register allocation, i.e.@: with
5093@option{-fschedule-insns} or at @option{-O2} or higher.
5094
5095@item -fsched-stalled-insns=@var{n}
5096@opindex fsched-stalled-insns
5097Define how many insns (if any) can be moved prematurely from the queue
5098of stalled insns into the ready list, during the second scheduling pass.
5099
5100@item -fsched-stalled-insns-dep=@var{n}
5101@opindex fsched-stalled-insns-dep
5102Define how many insn groups (cycles) will be examined for a dependency
5103on a stalled insn that is candidate for premature removal from the queue
5104of stalled insns. Has an effect only during the second scheduling pass,
5105and only if @option{-fsched-stalled-insns} is used and its value is not zero.
5106
5107@item -fsched2-use-superblocks
5108@opindex fsched2-use-superblocks
5109When scheduling after register allocation, do use superblock scheduling
5110algorithm. Superblock scheduling allows motion across basic block boundaries
5111resulting on faster schedules. This option is experimental, as not all machine
5112descriptions used by GCC model the CPU closely enough to avoid unreliable
5113results from the algorithm.
5114
5115This only makes sense when scheduling after register allocation, i.e.@: with
5116@option{-fschedule-insns2} or at @option{-O2} or higher.
5117
5118@item -fsched2-use-traces
5119@opindex fsched2-use-traces
5120Use @option{-fsched2-use-superblocks} algorithm when scheduling after register
5121allocation and additionally perform code duplication in order to increase the
5122size of superblocks using tracer pass. See @option{-ftracer} for details on
5123trace formation.
5124
5125This mode should produce faster but significantly longer programs. Also
5126without @option{-fbranch-probabilities} the traces constructed may not
5127match the reality and hurt the performance. This only makes
5128sense when scheduling after register allocation, i.e.@: with
5129@option{-fschedule-insns2} or at @option{-O2} or higher.
5130
5131@item -fsee
5132@opindex fsee
5133Eliminates redundant extension instructions and move the non redundant
5134ones to optimal placement using LCM.
5135
5136@item -freschedule-modulo-scheduled-loops
5137@opindex fscheduling-in-modulo-scheduled-loops
5138The modulo scheduling comes before the traditional scheduling, if a loop was modulo scheduled
5139we may want to prevent the later scheduling passes from changing its schedule, we use this
5140option to control that.
5141
5142@item -fcaller-saves
5143@opindex fcaller-saves
5144Enable values to be allocated in registers that will be clobbered by
5145function calls, by emitting extra instructions to save and restore the
5146registers around such calls. Such allocation is done only when it
5147seems to result in better code than would otherwise be produced.
5148
5149This option is always enabled by default on certain machines, usually
5150those which have no call-preserved registers to use instead.
5151
5152Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5153
5154@item -ftree-pre
5155Perform Partial Redundancy Elimination (PRE) on trees. This flag is
5156enabled by default at @option{-O2} and @option{-O3}.
5157
5158@item -ftree-fre
5159Perform Full Redundancy Elimination (FRE) on trees. The difference
5160between FRE and PRE is that FRE only considers expressions
5161that are computed on all paths leading to the redundant computation.
5162This analysis faster than PRE, though it exposes fewer redundancies.
5163This flag is enabled by default at @option{-O} and higher.
5164
5165@item -ftree-copy-prop
5166Perform copy propagation on trees. This pass eliminates unnecessary
5167copy operations. This flag is enabled by default at @option{-O} and
5168higher.
5169
5170@item -ftree-store-copy-prop
5171Perform copy propagation of memory loads and stores. This pass
5172eliminates unnecessary copy operations in memory references
5173(structures, global variables, arrays, etc). This flag is enabled by
5174default at @option{-O2} and higher.
5175
5176@item -ftree-salias
5177Perform structural alias analysis on trees. This flag
5178is enabled by default at @option{-O} and higher.
5179
5180@item -fipa-pta
5181Perform interprocedural pointer analysis.
5182
5183@item -ftree-sink
5184Perform forward store motion on trees. This flag is
5185enabled by default at @option{-O} and higher.
5186
5187@item -ftree-ccp
5188Perform sparse conditional constant propagation (CCP) on trees. This
5189pass only operates on local scalar variables and is enabled by default
5190at @option{-O} and higher.
5191
5192@item -ftree-store-ccp
5193Perform sparse conditional constant propagation (CCP) on trees. This
5194pass operates on both local scalar variables and memory stores and
5195loads (global variables, structures, arrays, etc). This flag is
5196enabled by default at @option{-O2} and higher.
5197
5198@item -ftree-dce
5199Perform dead code elimination (DCE) on trees. This flag is enabled by
5200default at @option{-O} and higher.
5201
5202@item -ftree-dominator-opts
5203Perform a variety of simple scalar cleanups (constant/copy
5204propagation, redundancy elimination, range propagation and expression
5205simplification) based on a dominator tree traversal. This also
5206performs jump threading (to reduce jumps to jumps). This flag is
5207enabled by default at @option{-O} and higher.
5208
5209@item -ftree-ch
5210Perform loop header copying on trees. This is beneficial since it increases
5211effectiveness of code motion optimizations. It also saves one jump. This flag
5212is enabled by default at @option{-O} and higher. It is not enabled
5213for @option{-Os}, since it usually increases code size.
5214
5215@item -ftree-loop-optimize
5216Perform loop optimizations on trees. This flag is enabled by default
5217at @option{-O} and higher.
5218
5219@item -ftree-loop-linear
5220Perform linear loop transformations on tree. This flag can improve cache
5221performance and allow further loop optimizations to take place.
5222
5223@item -ftree-loop-im
5224Perform loop invariant motion on trees. This pass moves only invariants that
5225would be hard to handle at RTL level (function calls, operations that expand to
5226nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
5227operands of conditions that are invariant out of the loop, so that we can use
5228just trivial invariantness analysis in loop unswitching. The pass also includes
5229store motion.
5230
5231@item -ftree-loop-ivcanon
5232Create a canonical counter for number of iterations in the loop for that
5233determining number of iterations requires complicated analysis. Later
5234optimizations then may determine the number easily. Useful especially
5235in connection with unrolling.
5236
5237@item -fivopts
5238Perform induction variable optimizations (strength reduction, induction
5239variable merging and induction variable elimination) on trees.
5240
5241@item -ftree-sra
5242Perform scalar replacement of aggregates. This pass replaces structure
5243references with scalars to prevent committing structures to memory too
5244early. This flag is enabled by default at @option{-O} and higher.
5245
5246@item -ftree-copyrename
5247Perform copy renaming on trees. This pass attempts to rename compiler
5248temporaries to other variables at copy locations, usually resulting in
5249variable names which more closely resemble the original variables. This flag
5250is enabled by default at @option{-O} and higher.
5251
5252@item -ftree-ter
5253Perform temporary expression replacement during the SSA->normal phase. Single
5254use/single def temporaries are replaced at their use location with their
5255defining expression. This results in non-GIMPLE code, but gives the expanders
5256much more complex trees to work on resulting in better RTL generation. This is
5257enabled by default at @option{-O} and higher.
5258
5259@item -ftree-lrs
5260Perform live range splitting during the SSA->normal phase. Distinct live
5261ranges of a variable are split into unique variables, allowing for better
5262optimization later. This is enabled by default at @option{-O} and higher.
5263
5264@item -ftree-vectorize
5265Perform loop vectorization on trees.
5266
5267@item -ftree-vect-loop-version
5268@opindex ftree-vect-loop-version
5269Perform loop versioning when doing loop vectorization on trees. When a loop
5270appears to be vectorizable except that data alignment or data dependence cannot
5271be determined at compile time then vectorized and non-vectorized versions of
5272the loop are generated along with runtime checks for alignment or dependence
5273to control which version is executed. This option is enabled by default
5274except at level @option{-Os} where it is disabled.
5275
5276@item -ftree-vrp
5277Perform Value Range Propagation on trees. This is similar to the
5278constant propagation pass, but instead of values, ranges of values are
5279propagated. This allows the optimizers to remove unnecessary range
5280checks like array bound checks and null pointer checks. This is
5281enabled by default at @option{-O2} and higher. Null pointer check
5282elimination is only done if @option{-fdelete-null-pointer-checks} is
5283enabled.
5284
5285@item -ftracer
5286@opindex ftracer
5287Perform tail duplication to enlarge superblock size. This transformation
5288simplifies the control flow of the function allowing other optimizations to do
5289better job.
5290
5291@item -funroll-loops
5292@opindex funroll-loops
5293Unroll loops whose number of iterations can be determined at compile
5294time or upon entry to the loop. @option{-funroll-loops} implies
5295@option{-frerun-cse-after-loop}. This option makes code larger,
5296and may or may not make it run faster.
5297
5298@item -funroll-all-loops
5299@opindex funroll-all-loops
5300Unroll all loops, even if their number of iterations is uncertain when
5301the loop is entered. This usually makes programs run more slowly.
5302@option{-funroll-all-loops} implies the same options as
5303@option{-funroll-loops},
5304
5305@item -fsplit-ivs-in-unroller
5306@opindex fsplit-ivs-in-unroller
5307Enables expressing of values of induction variables in later iterations
5308of the unrolled loop using the value in the first iteration. This breaks
5309long dependency chains, thus improving efficiency of the scheduling passes.
5310
5311Combination of @option{-fweb} and CSE is often sufficient to obtain the
5312same effect. However in cases the loop body is more complicated than
5313a single basic block, this is not reliable. It also does not work at all
5314on some of the architectures due to restrictions in the CSE pass.
5315
5316This optimization is enabled by default.
5317
5318@item -fvariable-expansion-in-unroller
5319@opindex fvariable-expansion-in-unroller
5320With this option, the compiler will create multiple copies of some
5321local variables when unrolling a loop which can result in superior code.
5322
5323@item -fprefetch-loop-arrays
5324@opindex fprefetch-loop-arrays
5325If supported by the target machine, generate instructions to prefetch
5326memory to improve the performance of loops that access large arrays.
5327
5328This option may generate better or worse code; results are highly
5329dependent on the structure of loops within the source code.
5330
5331Disabled at level @option{-Os}.
5332
5333@item -fno-peephole
5334@itemx -fno-peephole2
5335@opindex fno-peephole
5336@opindex fno-peephole2
5337Disable any machine-specific peephole optimizations. The difference
5338between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
5339are implemented in the compiler; some targets use one, some use the
5340other, a few use both.
5341
5342@option{-fpeephole} is enabled by default.
5343@option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5344
5345@item -fno-guess-branch-probability
5346@opindex fno-guess-branch-probability
5347Do not guess branch probabilities using heuristics.
5348
5349GCC will use heuristics to guess branch probabilities if they are
5350not provided by profiling feedback (@option{-fprofile-arcs}). These
5351heuristics are based on the control flow graph. If some branch probabilities
5352are specified by @samp{__builtin_expect}, then the heuristics will be
5353used to guess branch probabilities for the rest of the control flow graph,
5354taking the @samp{__builtin_expect} info into account. The interactions
5355between the heuristics and @samp{__builtin_expect} can be complex, and in
5356some cases, it may be useful to disable the heuristics so that the effects
5357of @samp{__builtin_expect} are easier to understand.
5358
5359The default is @option{-fguess-branch-probability} at levels
5360@option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5361
5362@item -freorder-blocks
5363@opindex freorder-blocks
5364Reorder basic blocks in the compiled function in order to reduce number of
5365taken branches and improve code locality.
5366
5367Enabled at levels @option{-O2}, @option{-O3}.
5368
5369@item -freorder-blocks-and-partition
5370@opindex freorder-blocks-and-partition
5371In addition to reordering basic blocks in the compiled function, in order
5372to reduce number of taken branches, partitions hot and cold basic blocks
5373into separate sections of the assembly and .o files, to improve
5374paging and cache locality performance.
5375
5376This optimization is automatically turned off in the presence of
5377exception handling, for linkonce sections, for functions with a user-defined
5378section attribute and on any architecture that does not support named
5379sections.
5380
5381@item -freorder-functions
5382@opindex freorder-functions
5383Reorder functions in the object file in order to
5384improve code locality. This is implemented by using special
5385subsections @code{.text.hot} for most frequently executed functions and
5386@code{.text.unlikely} for unlikely executed functions. Reordering is done by
5387the linker so object file format must support named sections and linker must
5388place them in a reasonable way.
5389
5390Also profile feedback must be available in to make this option effective. See
5391@option{-fprofile-arcs} for details.
5392
5393Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5394
5395@item -fstrict-aliasing
5396@opindex fstrict-aliasing
5397Allows the compiler to assume the strictest aliasing rules applicable to
5398the language being compiled. For C (and C++), this activates
5399optimizations based on the type of expressions. In particular, an
5400object of one type is assumed never to reside at the same address as an
5401object of a different type, unless the types are almost the same. For
5402example, an @code{unsigned int} can alias an @code{int}, but not a
5403@code{void*} or a @code{double}. A character type may alias any other
5404type.
5405
5406Pay special attention to code like this:
5407@smallexample
5408union a_union @{
5409 int i;
5410 double d;
5411@};
5412
5413int f() @{
5414 a_union t;
5415 t.d = 3.0;
5416 return t.i;
5417@}
5418@end smallexample
5419The practice of reading from a different union member than the one most
5420recently written to (called ``type-punning'') is common. Even with
5421@option{-fstrict-aliasing}, type-punning is allowed, provided the memory
5422is accessed through the union type. So, the code above will work as
5423expected. However, this code might not:
5424@smallexample
5425int f() @{
5426 a_union t;
5427 int* ip;
5428 t.d = 3.0;
5429 ip = &t.i;
5430 return *ip;
5431@}
5432@end smallexample
5433
5434Every language that wishes to perform language-specific alias analysis
5435should define a function that computes, given an @code{tree}
5436node, an alias set for the node. Nodes in different alias sets are not
5437allowed to alias. For an example, see the C front-end function
5438@code{c_get_alias_set}.
5439
5440Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5441
5442@item -fstrict-overflow
5443@opindex fstrict-overflow
5444Allow the compiler to assume strict signed overflow rules, depending
5445on the language being compiled. For C (and C++) this means that
5446overflow when doing arithmetic with signed numbers is undefined, which
5447means that the compiler may assume that it will not happen. This
5448permits various optimizations. For example, the compiler will assume
5449that an expression like @code{i + 10 > i} will always be true for
5450signed @code{i}. This assumption is only valid if signed overflow is
5451undefined, as the expression is false if @code{i + 10} overflows when
5452using twos complement arithmetic. When this option is in effect any
5453attempt to determine whether an operation on signed numbers will
5454overflow must be written carefully to not actually involve overflow.
5455
5456See also the @option{-fwrapv} option. Using @option{-fwrapv} means
5457that signed overflow is fully defined: it wraps. When
5458@option{-fwrapv} is used, there is no difference between
5459@option{-fstrict-overflow} and @option{-fno-strict-overflow}. With
5460@option{-fwrapv} certain types of overflow are permitted. For
5461example, if the compiler gets an overflow when doing arithmetic on
5462constants, the overflowed value can still be used with
5463@option{-fwrapv}, but not otherwise.
5464
5465The @option{-fstrict-overflow} option is enabled at levels
5466@option{-O2}, @option{-O3}, @option{-Os}.
5467
5468@item -falign-functions
5469@itemx -falign-functions=@var{n}
5470@opindex falign-functions
5471Align the start of functions to the next power-of-two greater than
5472@var{n}, skipping up to @var{n} bytes. For instance,
5473@option{-falign-functions=32} aligns functions to the next 32-byte
5474boundary, but @option{-falign-functions=24} would align to the next
547532-byte boundary only if this can be done by skipping 23 bytes or less.
5476
5477@option{-fno-align-functions} and @option{-falign-functions=1} are
5478equivalent and mean that functions will not be aligned.
5479
5480Some assemblers only support this flag when @var{n} is a power of two;
5481in that case, it is rounded up.
5482
5483If @var{n} is not specified or is zero, use a machine-dependent default.
5484
5485Enabled at levels @option{-O2}, @option{-O3}.
5486
5487@item -falign-labels
5488@itemx -falign-labels=@var{n}
5489@opindex falign-labels
5490Align all branch targets to a power-of-two boundary, skipping up to
5491@var{n} bytes like @option{-falign-functions}. This option can easily
5492make code slower, because it must insert dummy operations for when the
5493branch target is reached in the usual flow of the code.
5494
5495@option{-fno-align-labels} and @option{-falign-labels=1} are
5496equivalent and mean that labels will not be aligned.
5497
5498If @option{-falign-loops} or @option{-falign-jumps} are applicable and
5499are greater than this value, then their values are used instead.
5500
5501If @var{n} is not specified or is zero, use a machine-dependent default
5502which is very likely to be @samp{1}, meaning no alignment.
5503
5504Enabled at levels @option{-O2}, @option{-O3}.
5505
5506@item -falign-loops
5507@itemx -falign-loops=@var{n}
5508@opindex falign-loops
5509Align loops to a power-of-two boundary, skipping up to @var{n} bytes
5510like @option{-falign-functions}. The hope is that the loop will be
5511executed many times, which will make up for any execution of the dummy
5512operations.
5513
5514@option{-fno-align-loops} and @option{-falign-loops=1} are
5515equivalent and mean that loops will not be aligned.
5516
5517If @var{n} is not specified or is zero, use a machine-dependent default.
5518
5519Enabled at levels @option{-O2}, @option{-O3}.
5520
5521@item -falign-jumps
5522@itemx -falign-jumps=@var{n}
5523@opindex falign-jumps
5524Align branch targets to a power-of-two boundary, for branch targets
5525where the targets can only be reached by jumping, skipping up to @var{n}
5526bytes like @option{-falign-functions}. In this case, no dummy operations
5527need be executed.
5528
5529@option{-fno-align-jumps} and @option{-falign-jumps=1} are
5530equivalent and mean that loops will not be aligned.
5531
5532If @var{n} is not specified or is zero, use a machine-dependent default.
5533
5534Enabled at levels @option{-O2}, @option{-O3}.
5535
5536@item -funit-at-a-time
5537@opindex funit-at-a-time
5538Parse the whole compilation unit before starting to produce code.
5539This allows some extra optimizations to take place but consumes
5540more memory (in general). There are some compatibility issues
5541with @emph{unit-at-a-time} mode:
5542@itemize @bullet
5543@item
5544enabling @emph{unit-at-a-time} mode may change the order
5545in which functions, variables, and top-level @code{asm} statements
5546are emitted, and will likely break code relying on some particular
5547ordering. The majority of such top-level @code{asm} statements,
5548though, can be replaced by @code{section} attributes. The
5549@option{fno-toplevel-reorder} option may be used to keep the ordering
5550used in the input file, at the cost of some optimizations.
5551
5552@item
5553@emph{unit-at-a-time} mode removes unreferenced static variables
5554and functions. This may result in undefined references
5555when an @code{asm} statement refers directly to variables or functions
5556that are otherwise unused. In that case either the variable/function
5557shall be listed as an operand of the @code{asm} statement operand or,
5558in the case of top-level @code{asm} statements the attribute @code{used}
5559shall be used on the declaration.
5560
5561@item
5562Static functions now can use non-standard passing conventions that
5563may break @code{asm} statements calling functions directly. Again,
5564attribute @code{used} will prevent this behavior.
5565@end itemize
5566
5567As a temporary workaround, @option{-fno-unit-at-a-time} can be used,
5568but this scheme may not be supported by future releases of GCC@.
5569
5570Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5571
5572@item -fno-toplevel-reorder
5573Do not reorder top-level functions, variables, and @code{asm}
5574statements. Output them in the same order that they appear in the
5575input file. When this option is used, unreferenced static variables
5576will not be removed. This option is intended to support existing code
5577which relies on a particular ordering. For new code, it is better to
5578use attributes.
5579
5580@item -fweb
5581@opindex fweb
5582Constructs webs as commonly used for register allocation purposes and assign
5583each web individual pseudo register. This allows the register allocation pass
5584to operate on pseudos directly, but also strengthens several other optimization
5585passes, such as CSE, loop optimizer and trivial dead code remover. It can,
5586however, make debugging impossible, since variables will no longer stay in a
5587``home register''.
5588
5589Enabled by default with @option{-funroll-loops}.
5590
5591@item -fwhole-program
5592@opindex fwhole-program
5593Assume that the current compilation unit represents whole program being
5594compiled. All public functions and variables with the exception of @code{main}
5595and those merged by attribute @code{externally_visible} become static functions
5596and in a affect gets more aggressively optimized by interprocedural optimizers.
5597While this option is equivalent to proper use of @code{static} keyword for
5598programs consisting of single file, in combination with option
5599@option{--combine} this flag can be used to compile most of smaller scale C
5600programs since the functions and variables become local for the whole combined
5601compilation unit, not for the single source file itself.
5602
5603
5604@item -fno-cprop-registers
5605@opindex fno-cprop-registers
5606After register allocation and post-register allocation instruction splitting,
5607we perform a copy-propagation pass to try to reduce scheduling dependencies
5608and occasionally eliminate the copy.
5609
5610Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5611
5612@item -fprofile-generate
5613@opindex fprofile-generate
5614
5615Enable options usually used for instrumenting application to produce
5616profile useful for later recompilation with profile feedback based
5617optimization. You must use @option{-fprofile-generate} both when
5618compiling and when linking your program.
5619
5620The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
5621
5622@item -fprofile-use
5623@opindex fprofile-use
5624Enable profile feedback directed optimizations, and optimizations
5625generally profitable only with profile feedback available.
5626
5627The following options are enabled: @code{-fbranch-probabilities}, @code{-fvpt},
5628@code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}
5629
5630@end table
5631
5632The following options control compiler behavior regarding floating
5633point arithmetic. These options trade off between speed and
5634correctness. All must be specifically enabled.
5635
5636@table @gcctabopt
5637@item -ffloat-store
5638@opindex ffloat-store
5639Do not store floating point variables in registers, and inhibit other
5640options that might change whether a floating point value is taken from a
5641register or memory.
5642
5643@cindex floating point precision
5644This option prevents undesirable excess precision on machines such as
5645the 68000 where the floating registers (of the 68881) keep more
5646precision than a @code{double} is supposed to have. Similarly for the
5647x86 architecture. For most programs, the excess precision does only
5648good, but a few programs rely on the precise definition of IEEE floating
5649point. Use @option{-ffloat-store} for such programs, after modifying
5650them to store all pertinent intermediate computations into variables.
5651
5652@item -ffast-math
5653@opindex ffast-math
5654Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @*
5655@option{-fno-trapping-math}, @option{-ffinite-math-only},
5656@option{-fno-rounding-math}, @option{-fno-signaling-nans}
5657and @option{fcx-limited-range}.
5658
5659This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
5660
5661This option should never be turned on by any @option{-O} option since
5662it can result in incorrect output for programs which depend on
5663an exact implementation of IEEE or ISO rules/specifications for
5664math functions.
5665
5666@item -fno-math-errno
5667@opindex fno-math-errno
5668Do not set ERRNO after calling math functions that are executed
5669with a single instruction, e.g., sqrt. A program that relies on
5670IEEE exceptions for math error handling may want to use this flag
5671for speed while maintaining IEEE arithmetic compatibility.
5672
5673This option should never be turned on by any @option{-O} option since
5674it can result in incorrect output for programs which depend on
5675an exact implementation of IEEE or ISO rules/specifications for
5676math functions.
5677
5678The default is @option{-fmath-errno}.
5679
5680On Darwin and FreeBSD systems, the math library never sets @code{errno}.
5681There is therefore
5682no reason for the compiler to consider the possibility that it might,
5683and @option{-fno-math-errno} is the default.
5684
5685@item -funsafe-math-optimizations
5686@opindex funsafe-math-optimizations
5687Allow optimizations for floating-point arithmetic that (a) assume
5688that arguments and results are valid and (b) may violate IEEE or
5689ANSI standards. When used at link-time, it may include libraries
5690or startup files that change the default FPU control word or other
5691similar optimizations.
5692
5693This option should never be turned on by any @option{-O} option since
5694it can result in incorrect output for programs which depend on
5695an exact implementation of IEEE or ISO rules/specifications for
5696math functions.
5697
5698The default is @option{-fno-unsafe-math-optimizations}.
5699
5700@item -ffinite-math-only
5701@opindex ffinite-math-only
5702Allow optimizations for floating-point arithmetic that assume
5703that arguments and results are not NaNs or +-Infs.
5704
5705This option should never be turned on by any @option{-O} option since
5706it can result in incorrect output for programs which depend on
5707an exact implementation of IEEE or ISO rules/specifications.
5708
5709The default is @option{-fno-finite-math-only}.
5710
5711@item -fno-trapping-math
5712@opindex fno-trapping-math
5713Compile code assuming that floating-point operations cannot generate
5714user-visible traps. These traps include division by zero, overflow,
5715underflow, inexact result and invalid operation. This option implies
5716@option{-fno-signaling-nans}. Setting this option may allow faster
5717code if one relies on ``non-stop'' IEEE arithmetic, for example.
5718
5719This option should never be turned on by any @option{-O} option since
5720it can result in incorrect output for programs which depend on
5721an exact implementation of IEEE or ISO rules/specifications for
5722math functions.
5723
5724The default is @option{-ftrapping-math}.
5725
5726@item -frounding-math
5727@opindex frounding-math
5728Disable transformations and optimizations that assume default floating
5729point rounding behavior. This is round-to-zero for all floating point
5730to integer conversions, and round-to-nearest for all other arithmetic
5731truncations. This option should be specified for programs that change
5732the FP rounding mode dynamically, or that may be executed with a
5733non-default rounding mode. This option disables constant folding of
5734floating point expressions at compile-time (which may be affected by
5735rounding mode) and arithmetic transformations that are unsafe in the
5736presence of sign-dependent rounding modes.
5737
5738The default is @option{-fno-rounding-math}.
5739
5740This option is experimental and does not currently guarantee to
5741disable all GCC optimizations that are affected by rounding mode.
5742Future versions of GCC may provide finer control of this setting
5743using C99's @code{FENV_ACCESS} pragma. This command line option
5744will be used to specify the default state for @code{FENV_ACCESS}.
5745
5746@item -frtl-abstract-sequences
5747@opindex frtl-abstract-sequences
5748It is a size optimization method. This option is to find identical
5749sequences of code, which can be turned into pseudo-procedures and
5750then replace all occurrences with calls to the newly created
5751subroutine. It is kind of an opposite of @option{-finline-functions}.
5752This optimization runs at RTL level.
5753
5754@item -fsignaling-nans
5755@opindex fsignaling-nans
5756Compile code assuming that IEEE signaling NaNs may generate user-visible
5757traps during floating-point operations. Setting this option disables
5758optimizations that may change the number of exceptions visible with
5759signaling NaNs. This option implies @option{-ftrapping-math}.
5760
5761This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
5762be defined.
5763
5764The default is @option{-fno-signaling-nans}.
5765
5766This option is experimental and does not currently guarantee to
5767disable all GCC optimizations that affect signaling NaN behavior.
5768
5769@item -fsingle-precision-constant
5770@opindex fsingle-precision-constant
5771Treat floating point constant as single precision constant instead of
5772implicitly converting it to double precision constant.
5773
5774@item -fcx-limited-range
5775@itemx -fno-cx-limited-range
5776@opindex fcx-limited-range
5777@opindex fno-cx-limited-range
5778When enabled, this option states that a range reduction step is not
5779needed when performing complex division. The default is
5780@option{-fno-cx-limited-range}, but is enabled by @option{-ffast-math}.
5781
5782This option controls the default setting of the ISO C99
5783@code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to
5784all languages.
5785
5786@end table
5787
5788The following options control optimizations that may improve
5789performance, but are not enabled by any @option{-O} options. This
5790section includes experimental options that may produce broken code.
5791
5792@table @gcctabopt
5793@item -fbranch-probabilities
5794@opindex fbranch-probabilities
5795After running a program compiled with @option{-fprofile-arcs}
5796(@pxref{Debugging Options,, Options for Debugging Your Program or
5797@command{gcc}}), you can compile it a second time using
5798@option{-fbranch-probabilities}, to improve optimizations based on
5799the number of times each branch was taken. When the program
5800compiled with @option{-fprofile-arcs} exits it saves arc execution
5801counts to a file called @file{@var{sourcename}.gcda} for each source
5802file The information in this data file is very dependent on the
5803structure of the generated code, so you must use the same source code
5804and the same optimization options for both compilations.
5805
5806With @option{-fbranch-probabilities}, GCC puts a
5807@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
5808These can be used to improve optimization. Currently, they are only
5809used in one place: in @file{reorg.c}, instead of guessing which path a
5810branch is mostly to take, the @samp{REG_BR_PROB} values are used to
5811exactly determine which path is taken more often.
5812
5813@item -fprofile-values
5814@opindex fprofile-values
5815If combined with @option{-fprofile-arcs}, it adds code so that some
5816data about values of expressions in the program is gathered.
5817
5818With @option{-fbranch-probabilities}, it reads back the data gathered
5819from profiling values of expressions and adds @samp{REG_VALUE_PROFILE}
5820notes to instructions for their later usage in optimizations.
5821
5822Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
5823
5824@item -fvpt
5825@opindex fvpt
5826If combined with @option{-fprofile-arcs}, it instructs the compiler to add
5827a code to gather information about values of expressions.
5828
5829With @option{-fbranch-probabilities}, it reads back the data gathered
5830and actually performs the optimizations based on them.
5831Currently the optimizations include specialization of division operation
5832using the knowledge about the value of the denominator.
5833
5834@item -frename-registers
5835@opindex frename-registers
5836Attempt to avoid false dependencies in scheduled code by making use
5837of registers left over after register allocation. This optimization
5838will most benefit processors with lots of registers. Depending on the
5839debug information format adopted by the target, however, it can
5840make debugging impossible, since variables will no longer stay in
5841a ``home register''.
5842
5843Enabled by default with @option{-funroll-loops}.
5844
5845@item -ftracer
5846@opindex ftracer
5847Perform tail duplication to enlarge superblock size. This transformation
5848simplifies the control flow of the function allowing other optimizations to do
5849better job.
5850
5851Enabled with @option{-fprofile-use}.
5852
5853@item -funroll-loops
5854@opindex funroll-loops
5855Unroll loops whose number of iterations can be determined at compile time or
5856upon entry to the loop. @option{-funroll-loops} implies
5857@option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.
5858It also turns on complete loop peeling (i.e.@: complete removal of loops with
5859small constant number of iterations). This option makes code larger, and may
5860or may not make it run faster.
5861
5862Enabled with @option{-fprofile-use}.
5863
5864@item -funroll-all-loops
5865@opindex funroll-all-loops
5866Unroll all loops, even if their number of iterations is uncertain when
5867the loop is entered. This usually makes programs run more slowly.
5868@option{-funroll-all-loops} implies the same options as
5869@option{-funroll-loops}.
5870
5871@item -fpeel-loops
5872@opindex fpeel-loops
5873Peels the loops for that there is enough information that they do not
5874roll much (from profile feedback). It also turns on complete loop peeling
5875(i.e.@: complete removal of loops with small constant number of iterations).
5876
5877Enabled with @option{-fprofile-use}.
5878
5879@item -fmove-loop-invariants
5880@opindex fmove-loop-invariants
5881Enables the loop invariant motion pass in the RTL loop optimizer. Enabled
5882at level @option{-O1}
5883
5884@item -funswitch-loops
5885@opindex funswitch-loops
5886Move branches with loop invariant conditions out of the loop, with duplicates
5887of the loop on both branches (modified according to result of the condition).
5888
5889@item -ffunction-sections
5890@itemx -fdata-sections
5891@opindex ffunction-sections
5892@opindex fdata-sections
5893Place each function or data item into its own section in the output
5894file if the target supports arbitrary sections. The name of the
5895function or the name of the data item determines the section's name
5896in the output file.
5897
5898Use these options on systems where the linker can perform optimizations
5899to improve locality of reference in the instruction space. Most systems
5900using the ELF object format and SPARC processors running Solaris 2 have
5901linkers with such optimizations. AIX may have these optimizations in
5902the future.
5903
5904Only use these options when there are significant benefits from doing
5905so. When you specify these options, the assembler and linker will
5906create larger object and executable files and will also be slower.
5907You will not be able to use @code{gprof} on all systems if you
5908specify this option and you may have problems with debugging if
5909you specify both this option and @option{-g}.
5910
5911@item -fbranch-target-load-optimize
5912@opindex fbranch-target-load-optimize
5913Perform branch target register load optimization before prologue / epilogue
5914threading.
5915The use of target registers can typically be exposed only during reload,
5916thus hoisting loads out of loops and doing inter-block scheduling needs
5917a separate optimization pass.
5918
5919@item -fbranch-target-load-optimize2
5920@opindex fbranch-target-load-optimize2
5921Perform branch target register load optimization after prologue / epilogue
5922threading.
5923
5924@item -fbtr-bb-exclusive
5925@opindex fbtr-bb-exclusive
5926When performing branch target register load optimization, don't reuse
5927branch target registers in within any basic block.
5928
5929@item -fstack-protector
5930Emit extra code to check for buffer overflows, such as stack smashing
5931attacks. This is done by adding a guard variable to functions with
5932vulnerable objects. This includes functions that call alloca, and
5933functions with buffers larger than 8 bytes. The guards are initialized
5934when a function is entered and then checked when the function exits.
5935If a guard check fails, an error message is printed and the program exits.
5936
5937@item -fstack-protector-all
5938Like @option{-fstack-protector} except that all functions are protected.
5939
5940@item -fsection-anchors
5941@opindex fsection-anchors
5942Try to reduce the number of symbolic address calculations by using
5943shared ``anchor'' symbols to address nearby objects. This transformation
5944can help to reduce the number of GOT entries and GOT accesses on some
5945targets.
5946
5947For example, the implementation of the following function @code{foo}:
5948
5949@smallexample
5950static int a, b, c;
5951int foo (void) @{ return a + b + c; @}
5952@end smallexample
5953
5954would usually calculate the addresses of all three variables, but if you
5955compile it with @option{-fsection-anchors}, it will access the variables
5956from a common anchor point instead. The effect is similar to the
5957following pseudocode (which isn't valid C):
5958
5959@smallexample
5960int foo (void)
5961@{
5962 register int *xr = &x;
5963 return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
5964@}
5965@end smallexample
5966
5967Not all targets support this option.
5968
5969@item --param @var{name}=@var{value}
5970@opindex param
5971In some places, GCC uses various constants to control the amount of
5972optimization that is done. For example, GCC will not inline functions
5973that contain more that a certain number of instructions. You can
5974control some of these constants on the command-line using the
5975@option{--param} option.
5976
5977The names of specific parameters, and the meaning of the values, are
5978tied to the internals of the compiler, and are subject to change
5979without notice in future releases.
5980
5981In each case, the @var{value} is an integer. The allowable choices for
5982@var{name} are given in the following table:
5983
5984@table @gcctabopt
5985@item salias-max-implicit-fields
5986The maximum number of fields in a variable without direct
5987structure accesses for which structure aliasing will consider trying
5988to track each field. The default is 5
5989
5990@item salias-max-array-elements
5991The maximum number of elements an array can have and its elements
5992still be tracked individually by structure aliasing. The default is 4
5993
5994@item sra-max-structure-size
5995The maximum structure size, in bytes, at which the scalar replacement
5996of aggregates (SRA) optimization will perform block copies. The
5997default value, 0, implies that GCC will select the most appropriate
5998size itself.
5999
6000@item sra-field-structure-ratio
6001The threshold ratio (as a percentage) between instantiated fields and
6002the complete structure size. We say that if the ratio of the number
6003of bytes in instantiated fields to the number of bytes in the complete
6004structure exceeds this parameter, then block copies are not used. The
6005default is 75.
6006
6007@item max-crossjump-edges
6008The maximum number of incoming edges to consider for crossjumping.
6009The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
6010the number of edges incoming to each block. Increasing values mean
6011more aggressive optimization, making the compile time increase with
6012probably small improvement in executable size.
6013
6014@item min-crossjump-insns
6015The minimum number of instructions which must be matched at the end
6016of two blocks before crossjumping will be performed on them. This
6017value is ignored in the case where all instructions in the block being
6018crossjumped from are matched. The default value is 5.
6019
6020@item max-grow-copy-bb-insns
6021The maximum code size expansion factor when copying basic blocks
6022instead of jumping. The expansion is relative to a jump instruction.
6023The default value is 8.
6024
6025@item max-goto-duplication-insns
6026The maximum number of instructions to duplicate to a block that jumps
6027to a computed goto. To avoid @math{O(N^2)} behavior in a number of
6028passes, GCC factors computed gotos early in the compilation process,
6029and unfactors them as late as possible. Only computed jumps at the
6030end of a basic blocks with no more than max-goto-duplication-insns are
6031unfactored. The default value is 8.
6032
6033@item max-delay-slot-insn-search
6034The maximum number of instructions to consider when looking for an
6035instruction to fill a delay slot. If more than this arbitrary number of
6036instructions is searched, the time savings from filling the delay slot
6037will be minimal so stop searching. Increasing values mean more
6038aggressive optimization, making the compile time increase with probably
6039small improvement in executable run time.
6040
6041@item max-delay-slot-live-search
6042When trying to fill delay slots, the maximum number of instructions to
6043consider when searching for a block with valid live register
6044information. Increasing this arbitrarily chosen value means more
6045aggressive optimization, increasing the compile time. This parameter
6046should be removed when the delay slot code is rewritten to maintain the
6047control-flow graph.
6048
6049@item max-gcse-memory
6050The approximate maximum amount of memory that will be allocated in
6051order to perform the global common subexpression elimination
6052optimization. If more memory than specified is required, the
6053optimization will not be done.
6054
6055@item max-gcse-passes
6056The maximum number of passes of GCSE to run. The default is 1.
6057
6058@item max-pending-list-length
6059The maximum number of pending dependencies scheduling will allow
6060before flushing the current state and starting over. Large functions
6061with few branches or calls can create excessively large lists which
6062needlessly consume memory and resources.
6063
6064@item max-inline-insns-single
6065Several parameters control the tree inliner used in gcc.
6066This number sets the maximum number of instructions (counted in GCC's
6067internal representation) in a single function that the tree inliner
6068will consider for inlining. This only affects functions declared
6069inline and methods implemented in a class declaration (C++).
6070The default value is 450.
6071
6072@item max-inline-insns-auto
6073When you use @option{-finline-functions} (included in @option{-O3}),
6074a lot of functions that would otherwise not be considered for inlining
6075by the compiler will be investigated. To those functions, a different
6076(more restrictive) limit compared to functions declared inline can
6077be applied.
6078The default value is 90.
6079
6080@item large-function-insns
6081The limit specifying really large functions. For functions larger than this
6082limit after inlining inlining is constrained by
6083@option{--param large-function-growth}. This parameter is useful primarily
6084to avoid extreme compilation time caused by non-linear algorithms used by the
6085backend.
6086This parameter is ignored when @option{-funit-at-a-time} is not used.
6087The default value is 2700.
6088
6089@item large-function-growth
6090Specifies maximal growth of large function caused by inlining in percents.
6091This parameter is ignored when @option{-funit-at-a-time} is not used.
6092The default value is 100 which limits large function growth to 2.0 times
6093the original size.
6094
6095@item large-unit-insns
6096The limit specifying large translation unit. Growth caused by inlining of
6097units larger than this limit is limited by @option{--param inline-unit-growth}.
6098For small units this might be too tight (consider unit consisting of function A
6099that is inline and B that just calls A three time. If B is small relative to
6100A, the growth of unit is 300\% and yet such inlining is very sane. For very
6101large units consisting of small inlininable functions however the overall unit
6102growth limit is needed to avoid exponential explosion of code size. Thus for
6103smaller units, the size is increased to @option{--param large-unit-insns}
6104before applying @option{--param inline-unit-growth}. The default is 10000
6105
6106@item inline-unit-growth
6107Specifies maximal overall growth of the compilation unit caused by inlining.
6108This parameter is ignored when @option{-funit-at-a-time} is not used.
6109The default value is 50 which limits unit growth to 1.5 times the original
6110size.
6111
6112@item max-inline-insns-recursive
6113@itemx max-inline-insns-recursive-auto
6114Specifies maximum number of instructions out-of-line copy of self recursive inline
6115function can grow into by performing recursive inlining.
6116
6117For functions declared inline @option{--param max-inline-insns-recursive} is
6118taken into account. For function not declared inline, recursive inlining
6119happens only when @option{-finline-functions} (included in @option{-O3}) is
6120enabled and @option{--param max-inline-insns-recursive-auto} is used. The
6121default value is 450.
6122
6123@item max-inline-recursive-depth
6124@itemx max-inline-recursive-depth-auto
6125Specifies maximum recursion depth used by the recursive inlining.
6126
6127For functions declared inline @option{--param max-inline-recursive-depth} is
6128taken into account. For function not declared inline, recursive inlining
6129happens only when @option{-finline-functions} (included in @option{-O3}) is
6130enabled and @option{--param max-inline-recursive-depth-auto} is used. The
6131default value is 450.
6132
6133@item min-inline-recursive-probability
6134Recursive inlining is profitable only for function having deep recursion
6135in average and can hurt for function having little recursion depth by
6136increasing the prologue size or complexity of function body to other
6137optimizers.
6138
6139When profile feedback is available (see @option{-fprofile-generate}) the actual
6140recursion depth can be guessed from probability that function will recurse via
6141given call expression. This parameter limits inlining only to call expression
6142whose probability exceeds given threshold (in percents). The default value is
614310.
6144
6145@item inline-call-cost
6146Specify cost of call instruction relative to simple arithmetics operations
6147(having cost of 1). Increasing this cost disqualifies inlining of non-leaf
6148functions and at the same time increases size of leaf function that is believed to
6149reduce function size by being inlined. In effect it increases amount of
6150inlining for code having large abstraction penalty (many functions that just
6151pass the arguments to other functions) and decrease inlining for code with low
6152abstraction penalty. The default value is 16.
6153
6154@item max-unrolled-insns
6155The maximum number of instructions that a loop should have if that loop
6156is unrolled, and if the loop is unrolled, it determines how many times
6157the loop code is unrolled.
6158
6159@item max-average-unrolled-insns
6160The maximum number of instructions biased by probabilities of their execution
6161that a loop should have if that loop is unrolled, and if the loop is unrolled,
6162it determines how many times the loop code is unrolled.
6163
6164@item max-unroll-times
6165The maximum number of unrollings of a single loop.
6166
6167@item max-peeled-insns
6168The maximum number of instructions that a loop should have if that loop
6169is peeled, and if the loop is peeled, it determines how many times
6170the loop code is peeled.
6171
6172@item max-peel-times
6173The maximum number of peelings of a single loop.
6174
6175@item max-completely-peeled-insns
6176The maximum number of insns of a completely peeled loop.
6177
6178@item max-completely-peel-times
6179The maximum number of iterations of a loop to be suitable for complete peeling.
6180
6181@item max-unswitch-insns
6182The maximum number of insns of an unswitched loop.
6183
6184@item max-unswitch-level
6185The maximum number of branches unswitched in a single loop.
6186
6187@item lim-expensive
6188The minimum cost of an expensive expression in the loop invariant motion.
6189
6190@item iv-consider-all-candidates-bound
6191Bound on number of candidates for induction variables below that
6192all candidates are considered for each use in induction variable
6193optimizations. Only the most relevant candidates are considered
6194if there are more candidates, to avoid quadratic time complexity.
6195
6196@item iv-max-considered-uses
6197The induction variable optimizations give up on loops that contain more
6198induction variable uses.
6199
6200@item iv-always-prune-cand-set-bound
6201If number of candidates in the set is smaller than this value,
6202we always try to remove unnecessary ivs from the set during its
6203optimization when a new iv is added to the set.
6204
6205@item scev-max-expr-size
6206Bound on size of expressions used in the scalar evolutions analyzer.
6207Large expressions slow the analyzer.
6208
6209@item vect-max-version-checks
6210The maximum number of runtime checks that can be performed when doing
6211loop versioning in the vectorizer. See option ftree-vect-loop-version
6212for more information.
6213
6214@item max-iterations-to-track
6215
6216The maximum number of iterations of a loop the brute force algorithm
6217for analysis of # of iterations of the loop tries to evaluate.
6218
6219@item hot-bb-count-fraction
6220Select fraction of the maximal count of repetitions of basic block in program
6221given basic block needs to have to be considered hot.
6222
6223@item hot-bb-frequency-fraction
6224Select fraction of the maximal frequency of executions of basic block in
6225function given basic block needs to have to be considered hot
6226
6227@item max-predicted-iterations
6228The maximum number of loop iterations we predict statically. This is useful
6229in cases where function contain single loop with known bound and other loop
6230with unknown. We predict the known number of iterations correctly, while
6231the unknown number of iterations average to roughly 10. This means that the
6232loop without bounds would appear artificially cold relative to the other one.
6233
6234@item tracer-dynamic-coverage
6235@itemx tracer-dynamic-coverage-feedback
6236
6237This value is used to limit superblock formation once the given percentage of
6238executed instructions is covered. This limits unnecessary code size
6239expansion.
6240
6241The @option{tracer-dynamic-coverage-feedback} is used only when profile
6242feedback is available. The real profiles (as opposed to statically estimated
6243ones) are much less balanced allowing the threshold to be larger value.
6244
6245@item tracer-max-code-growth
6246Stop tail duplication once code growth has reached given percentage. This is
6247rather hokey argument, as most of the duplicates will be eliminated later in
6248cross jumping, so it may be set to much higher values than is the desired code
6249growth.
6250
6251@item tracer-min-branch-ratio
6252
6253Stop reverse growth when the reverse probability of best edge is less than this
6254threshold (in percent).
6255
6256@item tracer-min-branch-ratio
6257@itemx tracer-min-branch-ratio-feedback
6258
6259Stop forward growth if the best edge do have probability lower than this
6260threshold.
6261
6262Similarly to @option{tracer-dynamic-coverage} two values are present, one for
6263compilation for profile feedback and one for compilation without. The value
6264for compilation with profile feedback needs to be more conservative (higher) in
6265order to make tracer effective.
6266
6267@item max-cse-path-length
6268
6269Maximum number of basic blocks on path that cse considers. The default is 10.
6270
6271@item max-cse-insns
6272The maximum instructions CSE process before flushing. The default is 1000.
6273
6274@item global-var-threshold
6275
6276Counts the number of function calls (@var{n}) and the number of
6277call-clobbered variables (@var{v}). If @var{n}x@var{v} is larger than this limit, a
6278single artificial variable will be created to represent all the
6279call-clobbered variables at function call sites. This artificial
6280variable will then be made to alias every call-clobbered variable.
6281(done as @code{int * size_t} on the host machine; beware overflow).
6282
6283@item max-aliased-vops
6284
6285Maximum number of virtual operands allowed to represent aliases
6286before triggering the alias grouping heuristic. Alias grouping
6287reduces compile times and memory consumption needed for aliasing at
6288the expense of precision loss in alias information.
6289
6290@item ggc-min-expand
6291
6292GCC uses a garbage collector to manage its own memory allocation. This
6293parameter specifies the minimum percentage by which the garbage
6294collector's heap should be allowed to expand between collections.
6295Tuning this may improve compilation speed; it has no effect on code
6296generation.
6297
6298The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
6299RAM >= 1GB@. If @code{getrlimit} is available, the notion of "RAM" is
6300the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If
6301GCC is not able to calculate RAM on a particular platform, the lower
6302bound of 30% is used. Setting this parameter and
6303@option{ggc-min-heapsize} to zero causes a full collection to occur at
6304every opportunity. This is extremely slow, but can be useful for
6305debugging.
6306
6307@item ggc-min-heapsize
6308
6309Minimum size of the garbage collector's heap before it begins bothering
6310to collect garbage. The first collection occurs after the heap expands
6311by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again,
6312tuning this may improve compilation speed, and has no effect on code
6313generation.
6314
6315The default is the smaller of RAM/8, RLIMIT_RSS, or a limit which
6316tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
6317with a lower bound of 4096 (four megabytes) and an upper bound of
6318131072 (128 megabytes). If GCC is not able to calculate RAM on a
6319particular platform, the lower bound is used. Setting this parameter
6320very large effectively disables garbage collection. Setting this
6321parameter and @option{ggc-min-expand} to zero causes a full collection
6322to occur at every opportunity.
6323
6324@item max-reload-search-insns
6325The maximum number of instruction reload should look backward for equivalent
6326register. Increasing values mean more aggressive optimization, making the
6327compile time increase with probably slightly better performance. The default
6328value is 100.
6329
6330@item max-cselib-memory-locations
6331The maximum number of memory locations cselib should take into account.
6332Increasing values mean more aggressive optimization, making the compile time
6333increase with probably slightly better performance. The default value is 500.
6334
6335@item max-flow-memory-locations
6336Similar as @option{max-cselib-memory-locations} but for dataflow liveness.
6337The default value is 100.
6338
6339@item reorder-blocks-duplicate
6340@itemx reorder-blocks-duplicate-feedback
6341
6342Used by basic block reordering pass to decide whether to use unconditional
6343branch or duplicate the code on its destination. Code is duplicated when its
6344estimated size is smaller than this value multiplied by the estimated size of
6345unconditional jump in the hot spots of the program.
6346
6347The @option{reorder-block-duplicate-feedback} is used only when profile
6348feedback is available and may be set to higher values than
6349@option{reorder-block-duplicate} since information about the hot spots is more
6350accurate.
6351
6352@item max-sched-ready-insns
6353The maximum number of instructions ready to be issued the scheduler should
6354consider at any given time during the first scheduling pass. Increasing
6355values mean more thorough searches, making the compilation time increase
6356with probably little benefit. The default value is 100.
6357
6358@item max-sched-region-blocks
6359The maximum number of blocks in a region to be considered for
6360interblock scheduling. The default value is 10.
6361
6362@item max-sched-region-insns
6363The maximum number of insns in a region to be considered for
6364interblock scheduling. The default value is 100.
6365
6366@item min-spec-prob
6367The minimum probability (in percents) of reaching a source block
6368for interblock speculative scheduling. The default value is 40.
6369
6370@item max-sched-extend-regions-iters
6371The maximum number of iterations through CFG to extend regions.
63720 - disable region extension,
6373N - do at most N iterations.
6374The default value is 0.
6375
6376@item max-sched-insn-conflict-delay
6377The maximum conflict delay for an insn to be considered for speculative motion.
6378The default value is 3.
6379
6380@item sched-spec-prob-cutoff
6381The minimal probability of speculation success (in percents), so that
6382speculative insn will be scheduled.
6383The default value is 40.
6384
6385@item max-last-value-rtl
6386
6387The maximum size measured as number of RTLs that can be recorded in an expression
6388in combiner for a pseudo register as last known value of that register. The default
6389is 10000.
6390
6391@item integer-share-limit
6392Small integer constants can use a shared data structure, reducing the
6393compiler's memory usage and increasing its speed. This sets the maximum
6394value of a shared integer constant's. The default value is 256.
6395
6396@item min-virtual-mappings
6397Specifies the minimum number of virtual mappings in the incremental
6398SSA updater that should be registered to trigger the virtual mappings
6399heuristic defined by virtual-mappings-ratio. The default value is
6400100.
6401
6402@item virtual-mappings-ratio
6403If the number of virtual mappings is virtual-mappings-ratio bigger
6404than the number of virtual symbols to be updated, then the incremental
6405SSA updater switches to a full update for those symbols. The default
6406ratio is 3.
6407
6408@item ssp-buffer-size
6409The minimum size of buffers (i.e. arrays) that will receive stack smashing
6410protection when @option{-fstack-protection} is used.
6411
6412@item max-jump-thread-duplication-stmts
6413Maximum number of statements allowed in a block that needs to be
6414duplicated when threading jumps.
6415
6416@item max-fields-for-field-sensitive
6417Maximum number of fields in a structure we will treat in
6418a field sensitive manner during pointer analysis.
6419
6420@end table
6421@end table
6422
6423@node Preprocessor Options
6424@section Options Controlling the Preprocessor
6425@cindex preprocessor options
6426@cindex options, preprocessor
6427
6428These options control the C preprocessor, which is run on each C source
6429file before actual compilation.
6430
6431If you use the @option{-E} option, nothing is done except preprocessing.
6432Some of these options make sense only together with @option{-E} because
6433they cause the preprocessor output to be unsuitable for actual
6434compilation.
6435
6436@table @gcctabopt
6437@opindex Wp
6438You can use @option{-Wp,@var{option}} to bypass the compiler driver
6439and pass @var{option} directly through to the preprocessor. If
6440@var{option} contains commas, it is split into multiple options at the
6441commas. However, many options are modified, translated or interpreted
6442by the compiler driver before being passed to the preprocessor, and
6443@option{-Wp} forcibly bypasses this phase. The preprocessor's direct
6444interface is undocumented and subject to change, so whenever possible
6445you should avoid using @option{-Wp} and let the driver handle the
6446options instead.
6447
6448@item -Xpreprocessor @var{option}
6449@opindex preprocessor
6450Pass @var{option} as an option to the preprocessor. You can use this to
6451supply system-specific preprocessor options which GCC does not know how to
6452recognize.
6453
6454If you want to pass an option that takes an argument, you must use
6455@option{-Xpreprocessor} twice, once for the option and once for the argument.
6456@end table
6457
6458@include cppopts.texi
6459
6460@node Assembler Options
6461@section Passing Options to the Assembler
6462
6463@c prevent bad page break with this line
6464You can pass options to the assembler.
6465
6466@table @gcctabopt
6467@item -Wa,@var{option}
6468@opindex Wa
6469Pass @var{option} as an option to the assembler. If @var{option}
6470contains commas, it is split into multiple options at the commas.
6471
6472@item -Xassembler @var{option}
6473@opindex Xassembler
6474Pass @var{option} as an option to the assembler. You can use this to
6475supply system-specific assembler options which GCC does not know how to
6476recognize.
6477
6478If you want to pass an option that takes an argument, you must use
6479@option{-Xassembler} twice, once for the option and once for the argument.
6480
6481@end table
6482
6483@node Link Options
6484@section Options for Linking
6485@cindex link options
6486@cindex options, linking
6487
6488These options come into play when the compiler links object files into
6489an executable output file. They are meaningless if the compiler is
6490not doing a link step.
6491
6492@table @gcctabopt
6493@cindex file names
6494@item @var{object-file-name}
6495A file name that does not end in a special recognized suffix is
6496considered to name an object file or library. (Object files are
6497distinguished from libraries by the linker according to the file
6498contents.) If linking is done, these object files are used as input
6499to the linker.
6500
6501@item -c
6502@itemx -S
6503@itemx -E
6504@opindex c
6505@opindex S
6506@opindex E
6507If any of these options is used, then the linker is not run, and
6508object file names should not be used as arguments. @xref{Overall
6509Options}.
6510
6511@cindex Libraries
6512@item -l@var{library}
6513@itemx -l @var{library}
6514@opindex l
6515Search the library named @var{library} when linking. (The second
6516alternative with the library as a separate argument is only for
6517POSIX compliance and is not recommended.)
6518
6519It makes a difference where in the command you write this option; the
6520linker searches and processes libraries and object files in the order they
6521are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
6522after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
6523to functions in @samp{z}, those functions may not be loaded.
6524
6525The linker searches a standard list of directories for the library,
6526which is actually a file named @file{lib@var{library}.a}. The linker
6527then uses this file as if it had been specified precisely by name.
6528
6529The directories searched include several standard system directories
6530plus any that you specify with @option{-L}.
6531
6532Normally the files found this way are library files---archive files
6533whose members are object files. The linker handles an archive file by
6534scanning through it for members which define symbols that have so far
6535been referenced but not defined. But if the file that is found is an
6536ordinary object file, it is linked in the usual fashion. The only
6537difference between using an @option{-l} option and specifying a file name
6538is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
6539and searches several directories.
6540
6541@item -lobjc
6542@opindex lobjc
6543You need this special case of the @option{-l} option in order to
6544link an Objective-C or Objective-C++ program.
6545
6546@item -nostartfiles
6547@opindex nostartfiles
6548Do not use the standard system startup files when linking.
6549The standard system libraries are used normally, unless @option{-nostdlib}
6550or @option{-nodefaultlibs} is used.
6551
6552@item -nodefaultlibs
6553@opindex nodefaultlibs
6554Do not use the standard system libraries when linking.
6555Only the libraries you specify will be passed to the linker.
6556The standard startup files are used normally, unless @option{-nostartfiles}
6557is used. The compiler may generate calls to @code{memcmp},
6558@code{memset}, @code{memcpy} and @code{memmove}.
6559These entries are usually resolved by entries in
6560libc. These entry points should be supplied through some other
6561mechanism when this option is specified.
6562
6563@item -nostdlib
6564@opindex nostdlib
6565Do not use the standard system startup files or libraries when linking.
6566No startup files and only the libraries you specify will be passed to
6567the linker. The compiler may generate calls to @code{memcmp}, @code{memset},
6568@code{memcpy} and @code{memmove}.
6569These entries are usually resolved by entries in
6570libc. These entry points should be supplied through some other
6571mechanism when this option is specified.
6572
6573@cindex @option{-lgcc}, use with @option{-nostdlib}
6574@cindex @option{-nostdlib} and unresolved references
6575@cindex unresolved references and @option{-nostdlib}
6576@cindex @option{-lgcc}, use with @option{-nodefaultlibs}
6577@cindex @option{-nodefaultlibs} and unresolved references
6578@cindex unresolved references and @option{-nodefaultlibs}
6579One of the standard libraries bypassed by @option{-nostdlib} and
6580@option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
6581that GCC uses to overcome shortcomings of particular machines, or special
6582needs for some languages.
6583(@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
6584Collection (GCC) Internals},
6585for more discussion of @file{libgcc.a}.)
6586In most cases, you need @file{libgcc.a} even when you want to avoid
6587other standard libraries. In other words, when you specify @option{-nostdlib}
6588or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
6589This ensures that you have no unresolved references to internal GCC
6590library subroutines. (For example, @samp{__main}, used to ensure C++
6591constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
6592GNU Compiler Collection (GCC) Internals}.)
6593
6594@item -pie
6595@opindex pie
6596Produce a position independent executable on targets which support it.
6597For predictable results, you must also specify the same set of options
6598that were used to generate code (@option{-fpie}, @option{-fPIE},
6599or model suboptions) when you specify this option.
6600
6601@item -rdynamic
6602@opindex rdynamic
6603Pass the flag @option{-export-dynamic} to the ELF linker, on targets
6604that support it. This instructs the linker to add all symbols, not
6605only used ones, to the dynamic symbol table. This option is needed
6606for some uses of @code{dlopen} or to allow obtaining backtraces
6607from within a program.
6608
6609@item -s
6610@opindex s
6611Remove all symbol table and relocation information from the executable.
6612
6613@item -static
6614@opindex static
6615On systems that support dynamic linking, this prevents linking with the shared
6616libraries. On other systems, this option has no effect.
6617
6618@item -shared
6619@opindex shared
6620Produce a shared object which can then be linked with other objects to
6621form an executable. Not all systems support this option. For predictable
6622results, you must also specify the same set of options that were used to
6623generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
6624when you specify this option.@footnote{On some systems, @samp{gcc -shared}
6625needs to build supplementary stub code for constructors to work. On
6626multi-libbed systems, @samp{gcc -shared} must select the correct support
6627libraries to link against. Failing to supply the correct flags may lead
6628to subtle defects. Supplying them in cases where they are not necessary
6629is innocuous.}
6630
6631@item -shared-libgcc
6632@itemx -static-libgcc
6633@opindex shared-libgcc
6634@opindex static-libgcc
6635On systems that provide @file{libgcc} as a shared library, these options
6636force the use of either the shared or static version respectively.
6637If no shared version of @file{libgcc} was built when the compiler was
6638configured, these options have no effect.
6639
6640There are several situations in which an application should use the
6641shared @file{libgcc} instead of the static version. The most common
6642of these is when the application wishes to throw and catch exceptions
6643across different shared libraries. In that case, each of the libraries
6644as well as the application itself should use the shared @file{libgcc}.
6645
6646Therefore, the G++ and GCJ drivers automatically add
6647@option{-shared-libgcc} whenever you build a shared library or a main
6648executable, because C++ and Java programs typically use exceptions, so
6649this is the right thing to do.
6650
6651If, instead, you use the GCC driver to create shared libraries, you may
6652find that they will not always be linked with the shared @file{libgcc}.
6653If GCC finds, at its configuration time, that you have a non-GNU linker
6654or a GNU linker that does not support option @option{--eh-frame-hdr},
6655it will link the shared version of @file{libgcc} into shared libraries
6656by default. Otherwise, it will take advantage of the linker and optimize
6657away the linking with the shared version of @file{libgcc}, linking with
6658the static version of libgcc by default. This allows exceptions to
6659propagate through such shared libraries, without incurring relocation
6660costs at library load time.
6661
6662However, if a library or main executable is supposed to throw or catch
6663exceptions, you must link it using the G++ or GCJ driver, as appropriate
6664for the languages used in the program, or using the option
6665@option{-shared-libgcc}, such that it is linked with the shared
6666@file{libgcc}.
6667
6668@item -symbolic
6669@opindex symbolic
6670Bind references to global symbols when building a shared object. Warn
6671about any unresolved references (unless overridden by the link editor
6672option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
6673this option.
6674
6675@item -Xlinker @var{option}
6676@opindex Xlinker
6677Pass @var{option} as an option to the linker. You can use this to
6678supply system-specific linker options which GCC does not know how to
6679recognize.
6680
6681If you want to pass an option that takes an argument, you must use
6682@option{-Xlinker} twice, once for the option and once for the argument.
6683For example, to pass @option{-assert definitions}, you must write
6684@samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
6685@option{-Xlinker "-assert definitions"}, because this passes the entire
6686string as a single argument, which is not what the linker expects.
6687
6688@item -Wl,@var{option}
6689@opindex Wl
6690Pass @var{option} as an option to the linker. If @var{option} contains
6691commas, it is split into multiple options at the commas.
6692
6693@item -u @var{symbol}
6694@opindex u
6695Pretend the symbol @var{symbol} is undefined, to force linking of
6696library modules to define it. You can use @option{-u} multiple times with
6697different symbols to force loading of additional library modules.
6698@end table
6699
6700@node Directory Options
6701@section Options for Directory Search
6702@cindex directory options
6703@cindex options, directory search
6704@cindex search path
6705
6706These options specify directories to search for header files, for
6707libraries and for parts of the compiler:
6708
6709@table @gcctabopt
6710@item -I@var{dir}
6711@opindex I
6712Add the directory @var{dir} to the head of the list of directories to be
6713searched for header files. This can be used to override a system header
6714file, substituting your own version, since these directories are
6715searched before the system header file directories. However, you should
6716not use this option to add directories that contain vendor-supplied
6717system header files (use @option{-isystem} for that). If you use more than
6718one @option{-I} option, the directories are scanned in left-to-right
6719order; the standard system directories come after.
6720
6721If a standard system include directory, or a directory specified with
6722@option{-isystem}, is also specified with @option{-I}, the @option{-I}
6723option will be ignored. The directory will still be searched but as a
6724system directory at its normal position in the system include chain.
6725This is to ensure that GCC's procedure to fix buggy system headers and
6726the ordering for the include_next directive are not inadvertently changed.
6727If you really need to change the search order for system directories,
6728use the @option{-nostdinc} and/or @option{-isystem} options.
6729
6730@item -iquote@var{dir}
6731@opindex iquote
6732Add the directory @var{dir} to the head of the list of directories to
6733be searched for header files only for the case of @samp{#include
6734"@var{file}"}; they are not searched for @samp{#include <@var{file}>},
6735otherwise just like @option{-I}.
6736
6737@item -L@var{dir}
6738@opindex L
6739Add directory @var{dir} to the list of directories to be searched
6740for @option{-l}.
6741
6742@item -B@var{prefix}
6743@opindex B
6744This option specifies where to find the executables, libraries,
6745include files, and data files of the compiler itself.
6746
6747The compiler driver program runs one or more of the subprograms
6748@file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
6749@var{prefix} as a prefix for each program it tries to run, both with and
6750without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
6751
6752For each subprogram to be run, the compiler driver first tries the
6753@option{-B} prefix, if any. If that name is not found, or if @option{-B}
6754was not specified, the driver tries two standard prefixes, which are
6755@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of
6756those results in a file name that is found, the unmodified program
6757name is searched for using the directories specified in your
6758@env{PATH} environment variable.
6759
6760The compiler will check to see if the path provided by the @option{-B}
6761refers to a directory, and if necessary it will add a directory
6762separator character at the end of the path.
6763
6764@option{-B} prefixes that effectively specify directory names also apply
6765to libraries in the linker, because the compiler translates these
6766options into @option{-L} options for the linker. They also apply to
6767includes files in the preprocessor, because the compiler translates these
6768options into @option{-isystem} options for the preprocessor. In this case,
6769the compiler appends @samp{include} to the prefix.
6770
6771The run-time support file @file{libgcc.a} can also be searched for using
6772the @option{-B} prefix, if needed. If it is not found there, the two
6773standard prefixes above are tried, and that is all. The file is left
6774out of the link if it is not found by those means.
6775
6776Another way to specify a prefix much like the @option{-B} prefix is to use
6777the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
6778Variables}.
6779
6780As a special kludge, if the path provided by @option{-B} is
6781@file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
67829, then it will be replaced by @file{[dir/]include}. This is to help
6783with boot-strapping the compiler.
6784
6785@item -specs=@var{file}
6786@opindex specs
6787Process @var{file} after the compiler reads in the standard @file{specs}
6788file, in order to override the defaults that the @file{gcc} driver
6789program uses when determining what switches to pass to @file{cc1},
6790@file{cc1plus}, @file{as}, @file{ld}, etc. More than one
6791@option{-specs=@var{file}} can be specified on the command line, and they
6792are processed in order, from left to right.
6793
6794@item --sysroot=@var{dir}
6795@opindex sysroot
6796Use @var{dir} as the logical root directory for headers and libraries.
6797For example, if the compiler would normally search for headers in
6798@file{/usr/include} and libraries in @file{/usr/lib}, it will instead
6799search @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
6800
6801If you use both this option and the @option{-isysroot} option, then
6802the @option{--sysroot} option will apply to libraries, but the
6803@option{-isysroot} option will apply to header files.
6804
6805The GNU linker (beginning with version 2.16) has the necessary support
6806for this option. If your linker does not support this option, the
6807header file aspect of @option{--sysroot} will still work, but the
6808library aspect will not.
6809
6810@item -I-
6811@opindex I-
6812This option has been deprecated. Please use @option{-iquote} instead for
6813@option{-I} directories before the @option{-I-} and remove the @option{-I-}.
6814Any directories you specify with @option{-I} options before the @option{-I-}
6815option are searched only for the case of @samp{#include "@var{file}"};
6816they are not searched for @samp{#include <@var{file}>}.
6817
6818If additional directories are specified with @option{-I} options after
6819the @option{-I-}, these directories are searched for all @samp{#include}
6820directives. (Ordinarily @emph{all} @option{-I} directories are used
6821this way.)
6822
6823In addition, the @option{-I-} option inhibits the use of the current
6824directory (where the current input file came from) as the first search
6825directory for @samp{#include "@var{file}"}. There is no way to
6826override this effect of @option{-I-}. With @option{-I.} you can specify
6827searching the directory which was current when the compiler was
6828invoked. That is not exactly the same as what the preprocessor does
6829by default, but it is often satisfactory.
6830
6831@option{-I-} does not inhibit the use of the standard system directories
6832for header files. Thus, @option{-I-} and @option{-nostdinc} are
6833independent.
6834@end table
6835
6836@c man end
6837
6838@node Spec Files
6839@section Specifying subprocesses and the switches to pass to them
6840@cindex Spec Files
6841
6842@command{gcc} is a driver program. It performs its job by invoking a
6843sequence of other programs to do the work of compiling, assembling and
6844linking. GCC interprets its command-line parameters and uses these to
6845deduce which programs it should invoke, and which command-line options
6846it ought to place on their command lines. This behavior is controlled
6847by @dfn{spec strings}. In most cases there is one spec string for each
6848program that GCC can invoke, but a few programs have multiple spec
6849strings to control their behavior. The spec strings built into GCC can
6850be overridden by using the @option{-specs=} command-line switch to specify
6851a spec file.
6852
6853@dfn{Spec files} are plaintext files that are used to construct spec
6854strings. They consist of a sequence of directives separated by blank
6855lines. The type of directive is determined by the first non-whitespace
6856character on the line and it can be one of the following:
6857
6858@table @code
6859@item %@var{command}
6860Issues a @var{command} to the spec file processor. The commands that can
6861appear here are:
6862
6863@table @code
6864@item %include <@var{file}>
6865@cindex %include
6866Search for @var{file} and insert its text at the current point in the
6867specs file.
6868
6869@item %include_noerr <@var{file}>
6870@cindex %include_noerr
6871Just like @samp{%include}, but do not generate an error message if the include
6872file cannot be found.
6873
6874@item %rename @var{old_name} @var{new_name}
6875@cindex %rename
6876Rename the spec string @var{old_name} to @var{new_name}.
6877
6878@end table
6879
6880@item *[@var{spec_name}]:
6881This tells the compiler to create, override or delete the named spec
6882string. All lines after this directive up to the next directive or
6883blank line are considered to be the text for the spec string. If this
6884results in an empty string then the spec will be deleted. (Or, if the
6885spec did not exist, then nothing will happened.) Otherwise, if the spec
6886does not currently exist a new spec will be created. If the spec does
6887exist then its contents will be overridden by the text of this
6888directive, unless the first character of that text is the @samp{+}
6889character, in which case the text will be appended to the spec.
6890
6891@item [@var{suffix}]:
6892Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
6893and up to the next directive or blank line are considered to make up the
6894spec string for the indicated suffix. When the compiler encounters an
6895input file with the named suffix, it will processes the spec string in
6896order to work out how to compile that file. For example:
6897
6898@smallexample
6899.ZZ:
6900z-compile -input %i
6901@end smallexample
6902
6903This says that any input file whose name ends in @samp{.ZZ} should be
6904passed to the program @samp{z-compile}, which should be invoked with the
6905command-line switch @option{-input} and with the result of performing the
6906@samp{%i} substitution. (See below.)
6907
6908As an alternative to providing a spec string, the text that follows a
6909suffix directive can be one of the following:
6910
6911@table @code
6912@item @@@var{language}
6913This says that the suffix is an alias for a known @var{language}. This is
6914similar to using the @option{-x} command-line switch to GCC to specify a
6915language explicitly. For example:
6916
6917@smallexample
6918.ZZ:
6919@@c++
6920@end smallexample
6921
6922Says that .ZZ files are, in fact, C++ source files.
6923
6924@item #@var{name}
6925This causes an error messages saying:
6926
6927@smallexample
6928@var{name} compiler not installed on this system.
6929@end smallexample
6930@end table
6931
6932GCC already has an extensive list of suffixes built into it.
6933This directive will add an entry to the end of the list of suffixes, but
6934since the list is searched from the end backwards, it is effectively
6935possible to override earlier entries using this technique.
6936
6937@end table
6938
6939GCC has the following spec strings built into it. Spec files can
6940override these strings or create their own. Note that individual
6941targets can also add their own spec strings to this list.
6942
6943@smallexample
6944asm Options to pass to the assembler
6945asm_final Options to pass to the assembler post-processor
6946cpp Options to pass to the C preprocessor
6947cc1 Options to pass to the C compiler
6948cc1plus Options to pass to the C++ compiler
6949endfile Object files to include at the end of the link
6950link Options to pass to the linker
6951lib Libraries to include on the command line to the linker
6952libgcc Decides which GCC support library to pass to the linker
6953linker Sets the name of the linker
6954predefines Defines to be passed to the C preprocessor
6955signed_char Defines to pass to CPP to say whether @code{char} is signed
6956 by default
6957startfile Object files to include at the start of the link
6958@end smallexample
6959
6960Here is a small example of a spec file:
6961
6962@smallexample
6963%rename lib old_lib
6964
6965*lib:
6966--start-group -lgcc -lc -leval1 --end-group %(old_lib)
6967@end smallexample
6968
6969This example renames the spec called @samp{lib} to @samp{old_lib} and
6970then overrides the previous definition of @samp{lib} with a new one.
6971The new definition adds in some extra command-line options before
6972including the text of the old definition.
6973
6974@dfn{Spec strings} are a list of command-line options to be passed to their
6975corresponding program. In addition, the spec strings can contain
6976@samp{%}-prefixed sequences to substitute variable text or to
6977conditionally insert text into the command line. Using these constructs
6978it is possible to generate quite complex command lines.
6979
6980Here is a table of all defined @samp{%}-sequences for spec
6981strings. Note that spaces are not generated automatically around the
6982results of expanding these sequences. Therefore you can concatenate them
6983together or combine them with constant text in a single argument.
6984
6985@table @code
6986@item %%
6987Substitute one @samp{%} into the program name or argument.
6988
6989@item %i
6990Substitute the name of the input file being processed.
6991
6992@item %b
6993Substitute the basename of the input file being processed.
6994This is the substring up to (and not including) the last period
6995and not including the directory.
6996
6997@item %B
6998This is the same as @samp{%b}, but include the file suffix (text after
6999the last period).
7000
7001@item %d
7002Marks the argument containing or following the @samp{%d} as a
7003temporary file name, so that that file will be deleted if GCC exits
7004successfully. Unlike @samp{%g}, this contributes no text to the
7005argument.
7006
7007@item %g@var{suffix}
7008Substitute a file name that has suffix @var{suffix} and is chosen
7009once per compilation, and mark the argument in the same way as
7010@samp{%d}. To reduce exposure to denial-of-service attacks, the file
7011name is now chosen in a way that is hard to predict even when previously
7012chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
7013might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
7014the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
7015treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
7016was simply substituted with a file name chosen once per compilation,
7017without regard to any appended suffix (which was therefore treated
7018just like ordinary text), making such attacks more likely to succeed.
7019
7020@item %u@var{suffix}
7021Like @samp{%g}, but generates a new temporary file name even if
7022@samp{%u@var{suffix}} was already seen.
7023
7024@item %U@var{suffix}
7025Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
7026new one if there is no such last file name. In the absence of any
7027@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
7028the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
7029would involve the generation of two distinct file names, one
7030for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
7031simply substituted with a file name chosen for the previous @samp{%u},
7032without regard to any appended suffix.
7033
7034@item %j@var{suffix}
7035Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
7036writable, and if save-temps is off; otherwise, substitute the name
7037of a temporary file, just like @samp{%u}. This temporary file is not
7038meant for communication between processes, but rather as a junk
7039disposal mechanism.
7040
7041@item %|@var{suffix}
7042@itemx %m@var{suffix}
7043Like @samp{%g}, except if @option{-pipe} is in effect. In that case
7044@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
7045all. These are the two most common ways to instruct a program that it
7046should read from standard input or write to standard output. If you
7047need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
7048construct: see for example @file{f/lang-specs.h}.
7049
7050@item %.@var{SUFFIX}
7051Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
7052when it is subsequently output with @samp{%*}. @var{SUFFIX} is
7053terminated by the next space or %.
7054
7055@item %w
7056Marks the argument containing or following the @samp{%w} as the
7057designated output file of this compilation. This puts the argument
7058into the sequence of arguments that @samp{%o} will substitute later.
7059
7060@item %o
7061Substitutes the names of all the output files, with spaces
7062automatically placed around them. You should write spaces
7063around the @samp{%o} as well or the results are undefined.
7064@samp{%o} is for use in the specs for running the linker.
7065Input files whose names have no recognized suffix are not compiled
7066at all, but they are included among the output files, so they will
7067be linked.
7068
7069@item %O
7070Substitutes the suffix for object files. Note that this is
7071handled specially when it immediately follows @samp{%g, %u, or %U},
7072because of the need for those to form complete file names. The
7073handling is such that @samp{%O} is treated exactly as if it had already
7074been substituted, except that @samp{%g, %u, and %U} do not currently
7075support additional @var{suffix} characters following @samp{%O} as they would
7076following, for example, @samp{.o}.
7077
7078@item %p
7079Substitutes the standard macro predefinitions for the
7080current target machine. Use this when running @code{cpp}.
7081
7082@item %P
7083Like @samp{%p}, but puts @samp{__} before and after the name of each
7084predefined macro, except for macros that start with @samp{__} or with
7085@samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
7086C@.
7087
7088@item %I
7089Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
7090@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
7091@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
7092and @option{-imultilib} as necessary.
7093
7094@item %s
7095Current argument is the name of a library or startup file of some sort.
7096Search for that file in a standard list of directories and substitute
7097the full name found.
7098
7099@item %e@var{str}
7100Print @var{str} as an error message. @var{str} is terminated by a newline.
7101Use this when inconsistent options are detected.
7102
7103@item %(@var{name})
7104Substitute the contents of spec string @var{name} at this point.
7105
7106@item %[@var{name}]
7107Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
7108
7109@item %x@{@var{option}@}
7110Accumulate an option for @samp{%X}.
7111
7112@item %X
7113Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
7114spec string.
7115
7116@item %Y
7117Output the accumulated assembler options specified by @option{-Wa}.
7118
7119@item %Z
7120Output the accumulated preprocessor options specified by @option{-Wp}.
7121
7122@item %a
7123Process the @code{asm} spec. This is used to compute the
7124switches to be passed to the assembler.
7125
7126@item %A
7127Process the @code{asm_final} spec. This is a spec string for
7128passing switches to an assembler post-processor, if such a program is
7129needed.
7130
7131@item %l
7132Process the @code{link} spec. This is the spec for computing the
7133command line passed to the linker. Typically it will make use of the
7134@samp{%L %G %S %D and %E} sequences.
7135
7136@item %D
7137Dump out a @option{-L} option for each directory that GCC believes might
7138contain startup files. If the target supports multilibs then the
7139current multilib directory will be prepended to each of these paths.
7140
7141@item %L
7142Process the @code{lib} spec. This is a spec string for deciding which
7143libraries should be included on the command line to the linker.
7144
7145@item %G
7146Process the @code{libgcc} spec. This is a spec string for deciding
7147which GCC support library should be included on the command line to the linker.
7148
7149@item %S
7150Process the @code{startfile} spec. This is a spec for deciding which
7151object files should be the first ones passed to the linker. Typically
7152this might be a file named @file{crt0.o}.
7153
7154@item %E
7155Process the @code{endfile} spec. This is a spec string that specifies
7156the last object files that will be passed to the linker.
7157
7158@item %C
7159Process the @code{cpp} spec. This is used to construct the arguments
7160to be passed to the C preprocessor.
7161
7162@item %1
7163Process the @code{cc1} spec. This is used to construct the options to be
7164passed to the actual C compiler (@samp{cc1}).
7165
7166@item %2
7167Process the @code{cc1plus} spec. This is used to construct the options to be
7168passed to the actual C++ compiler (@samp{cc1plus}).
7169
7170@item %*
7171Substitute the variable part of a matched option. See below.
7172Note that each comma in the substituted string is replaced by
7173a single space.
7174
7175@item %<@code{S}
7176Remove all occurrences of @code{-S} from the command line. Note---this
7177command is position dependent. @samp{%} commands in the spec string
7178before this one will see @code{-S}, @samp{%} commands in the spec string
7179after this one will not.
7180
7181@item %:@var{function}(@var{args})
7182Call the named function @var{function}, passing it @var{args}.
7183@var{args} is first processed as a nested spec string, then split
7184into an argument vector in the usual fashion. The function returns
7185a string which is processed as if it had appeared literally as part
7186of the current spec.
7187
7188The following built-in spec functions are provided:
7189
7190@table @code
7191@item @code{if-exists}
7192The @code{if-exists} spec function takes one argument, an absolute
7193pathname to a file. If the file exists, @code{if-exists} returns the
7194pathname. Here is a small example of its usage:
7195
7196@smallexample
7197*startfile:
7198crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
7199@end smallexample
7200
7201@item @code{if-exists-else}
7202The @code{if-exists-else} spec function is similar to the @code{if-exists}
7203spec function, except that it takes two arguments. The first argument is
7204an absolute pathname to a file. If the file exists, @code{if-exists-else}
7205returns the pathname. If it does not exist, it returns the second argument.
7206This way, @code{if-exists-else} can be used to select one file or another,
7207based on the existence of the first. Here is a small example of its usage:
7208
7209@smallexample
7210*startfile:
7211crt0%O%s %:if-exists(crti%O%s) \
7212%:if-exists-else(crtbeginT%O%s crtbegin%O%s)
7213@end smallexample
7214
7215@item @code{replace-outfile}
7216The @code{replace-outfile} spec function takes two arguments. It looks for the
7217first argument in the outfiles array and replaces it with the second argument. Here
7218is a small example of its usage:
7219
7220@smallexample
7221%@{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)@}
7222@end smallexample
7223
7224@end table
7225
7226@item %@{@code{S}@}
7227Substitutes the @code{-S} switch, if that switch was given to GCC@.
7228If that switch was not specified, this substitutes nothing. Note that
7229the leading dash is omitted when specifying this option, and it is
7230automatically inserted if the substitution is performed. Thus the spec
7231string @samp{%@{foo@}} would match the command-line option @option{-foo}
7232and would output the command line option @option{-foo}.
7233
7234@item %W@{@code{S}@}
7235Like %@{@code{S}@} but mark last argument supplied within as a file to be
7236deleted on failure.
7237
7238@item %@{@code{S}*@}
7239Substitutes all the switches specified to GCC whose names start
7240with @code{-S}, but which also take an argument. This is used for
7241switches like @option{-o}, @option{-D}, @option{-I}, etc.
7242GCC considers @option{-o foo} as being
7243one switch whose names starts with @samp{o}. %@{o*@} would substitute this
7244text, including the space. Thus two arguments would be generated.
7245
7246@item %@{@code{S}*&@code{T}*@}
7247Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
7248(the order of @code{S} and @code{T} in the spec is not significant).
7249There can be any number of ampersand-separated variables; for each the
7250wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
7251
7252@item %@{@code{S}:@code{X}@}
7253Substitutes @code{X}, if the @samp{-S} switch was given to GCC@.
7254
7255@item %@{!@code{S}:@code{X}@}
7256Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@.
7257
7258@item %@{@code{S}*:@code{X}@}
7259Substitutes @code{X} if one or more switches whose names start with
7260@code{-S} are specified to GCC@. Normally @code{X} is substituted only
7261once, no matter how many such switches appeared. However, if @code{%*}
7262appears somewhere in @code{X}, then @code{X} will be substituted once
7263for each matching switch, with the @code{%*} replaced by the part of
7264that switch that matched the @code{*}.
7265
7266@item %@{.@code{S}:@code{X}@}
7267Substitutes @code{X}, if processing a file with suffix @code{S}.
7268
7269@item %@{!.@code{S}:@code{X}@}
7270Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
7271
7272@item %@{@code{S}|@code{P}:@code{X}@}
7273Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@.
7274This may be combined with @samp{!}, @samp{.}, and @code{*} sequences as well,
7275although they have a stronger binding than the @samp{|}. If @code{%*}
7276appears in @code{X}, all of the alternatives must be starred, and only
7277the first matching alternative is substituted.
7278
7279For example, a spec string like this:
7280
7281@smallexample
7282%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
7283@end smallexample
7284
7285will output the following command-line options from the following input
7286command-line options:
7287
7288@smallexample
7289fred.c -foo -baz
7290jim.d -bar -boggle
7291-d fred.c -foo -baz -boggle
7292-d jim.d -bar -baz -boggle
7293@end smallexample
7294
7295@item %@{S:X; T:Y; :D@}
7296
7297If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was
7298given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
7299be as many clauses as you need. This may be combined with @code{.},
7300@code{!}, @code{|}, and @code{*} as needed.
7301
7302
7303@end table
7304
7305The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
7306construct may contain other nested @samp{%} constructs or spaces, or
7307even newlines. They are processed as usual, as described above.
7308Trailing white space in @code{X} is ignored. White space may also
7309appear anywhere on the left side of the colon in these constructs,
7310except between @code{.} or @code{*} and the corresponding word.
7311
7312The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
7313handled specifically in these constructs. If another value of
7314@option{-O} or the negated form of a @option{-f}, @option{-m}, or
7315@option{-W} switch is found later in the command line, the earlier
7316switch value is ignored, except with @{@code{S}*@} where @code{S} is
7317just one letter, which passes all matching options.
7318
7319The character @samp{|} at the beginning of the predicate text is used to
7320indicate that a command should be piped to the following command, but
7321only if @option{-pipe} is specified.
7322
7323It is built into GCC which switches take arguments and which do not.
7324(You might think it would be useful to generalize this to allow each
7325compiler's spec to say which switches take arguments. But this cannot
7326be done in a consistent fashion. GCC cannot even decide which input
7327files have been specified without knowing which switches take arguments,
7328and it must know which input files to compile in order to tell which
7329compilers to run).
7330
7331GCC also knows implicitly that arguments starting in @option{-l} are to be
7332treated as compiler output files, and passed to the linker in their
7333proper position among the other output files.
7334
7335@c man begin OPTIONS
7336
7337@node Target Options
7338@section Specifying Target Machine and Compiler Version
7339@cindex target options
7340@cindex cross compiling
7341@cindex specifying machine version
7342@cindex specifying compiler version and target machine
7343@cindex compiler version, specifying
7344@cindex target machine, specifying
7345
7346The usual way to run GCC is to run the executable called @file{gcc}, or
7347@file{<machine>-gcc} when cross-compiling, or
7348@file{<machine>-gcc-<version>} to run a version other than the one that
7349was installed last. Sometimes this is inconvenient, so GCC provides
7350options that will switch to another cross-compiler or version.
7351
7352@table @gcctabopt
7353@item -b @var{machine}
7354@opindex b
7355The argument @var{machine} specifies the target machine for compilation.
7356
7357The value to use for @var{machine} is the same as was specified as the
7358machine type when configuring GCC as a cross-compiler. For
7359example, if a cross-compiler was configured with @samp{configure
7360arm-elf}, meaning to compile for an arm processor with elf binaries,
7361then you would specify @option{-b arm-elf} to run that cross compiler.
7362Because there are other options beginning with @option{-b}, the
7363configuration must contain a hyphen.
7364
7365@item -V @var{version}
7366@opindex V
7367The argument @var{version} specifies which version of GCC to run.
7368This is useful when multiple versions are installed. For example,
7369@var{version} might be @samp{4.0}, meaning to run GCC version 4.0.
7370@end table
7371
7372The @option{-V} and @option{-b} options work by running the
7373@file{<machine>-gcc-<version>} executable, so there's no real reason to
7374use them if you can just run that directly.
7375
7376@node Submodel Options
7377@section Hardware Models and Configurations
7378@cindex submodel options
7379@cindex specifying hardware config
7380@cindex hardware models and configurations, specifying
7381@cindex machine dependent options
7382
7383Earlier we discussed the standard option @option{-b} which chooses among
7384different installed compilers for completely different target
7385machines, such as VAX vs.@: 68000 vs.@: 80386.
7386
7387In addition, each of these target machine types can have its own
7388special options, starting with @samp{-m}, to choose among various
7389hardware models or configurations---for example, 68010 vs 68020,
7390floating coprocessor or none. A single installed version of the
7391compiler can compile for any model or configuration, according to the
7392options specified.
7393
7394Some configurations of the compiler also support additional special
7395options, usually for compatibility with other compilers on the same
7396platform.
7397
7398@c This list is ordered alphanumerically by subsection name.
7399@c It should be the same order and spelling as these options are listed
7400@c in Machine Dependent Options
7401
7402@menu
7403* ARC Options::
7404* ARM Options::
7405* AVR Options::
7406* Blackfin Options::
7407* CRIS Options::
7408* CRX Options::
7409* Darwin Options::
7410* DEC Alpha Options::
7411* DEC Alpha/VMS Options::
7412* FRV Options::
7413* GNU/Linux Options::
7414* H8/300 Options::
7415* HPPA Options::
7416* i386 and x86-64 Options::
7417* IA-64 Options::
7418* M32C Options::
7419* M32R/D Options::
7420* M680x0 Options::
7421* M68hc1x Options::
7422* MCore Options::
7423* MIPS Options::
7424* MMIX Options::
7425* MN10300 Options::
7426* MT Options::
7427* PDP-11 Options::
7428* PowerPC Options::
7429* RS/6000 and PowerPC Options::
7430* S/390 and zSeries Options::
7431* Score Options::
7432* SH Options::
7433* SPARC Options::
7434* System V Options::
7435* TMS320C3x/C4x Options::
7436* V850 Options::
7437* VAX Options::
7438* x86-64 Options::
7439* Xstormy16 Options::
7440* Xtensa Options::
7441* zSeries Options::
7442@end menu
7443
7444@node ARC Options
7445@subsection ARC Options
7446@cindex ARC Options
7447
7448These options are defined for ARC implementations:
7449
7450@table @gcctabopt
7451@item -EL
7452@opindex EL
7453Compile code for little endian mode. This is the default.
7454
7455@item -EB
7456@opindex EB
7457Compile code for big endian mode.
7458
7459@item -mmangle-cpu
7460@opindex mmangle-cpu
7461Prepend the name of the cpu to all public symbol names.
7462In multiple-processor systems, there are many ARC variants with different
7463instruction and register set characteristics. This flag prevents code
7464compiled for one cpu to be linked with code compiled for another.
7465No facility exists for handling variants that are ``almost identical''.
7466This is an all or nothing option.
7467
7468@item -mcpu=@var{cpu}
7469@opindex mcpu
7470Compile code for ARC variant @var{cpu}.
7471Which variants are supported depend on the configuration.
7472All variants support @option{-mcpu=base}, this is the default.
7473
7474@item -mtext=@var{text-section}
7475@itemx -mdata=@var{data-section}
7476@itemx -mrodata=@var{readonly-data-section}
7477@opindex mtext
7478@opindex mdata
7479@opindex mrodata
7480Put functions, data, and readonly data in @var{text-section},
7481@var{data-section}, and @var{readonly-data-section} respectively
7482by default. This can be overridden with the @code{section} attribute.
7483@xref{Variable Attributes}.
7484
7485@end table
7486
7487@node ARM Options
7488@subsection ARM Options
7489@cindex ARM options
7490
7491These @samp{-m} options are defined for Advanced RISC Machines (ARM)
7492architectures:
7493
7494@table @gcctabopt
7495@item -mabi=@var{name}
7496@opindex mabi
7497Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu},
7498@samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.
7499
7500@item -mapcs-frame
7501@opindex mapcs-frame
7502Generate a stack frame that is compliant with the ARM Procedure Call
7503Standard for all functions, even if this is not strictly necessary for
7504correct execution of the code. Specifying @option{-fomit-frame-pointer}
7505with this option will cause the stack frames not to be generated for
7506leaf functions. The default is @option{-mno-apcs-frame}.
7507
7508@item -mapcs
7509@opindex mapcs
7510This is a synonym for @option{-mapcs-frame}.
7511
7512@ignore
7513@c not currently implemented
7514@item -mapcs-stack-check
7515@opindex mapcs-stack-check
7516Generate code to check the amount of stack space available upon entry to
7517every function (that actually uses some stack space). If there is
7518insufficient space available then either the function
7519@samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
7520called, depending upon the amount of stack space required. The run time
7521system is required to provide these functions. The default is
7522@option{-mno-apcs-stack-check}, since this produces smaller code.
7523
7524@c not currently implemented
7525@item -mapcs-float
7526@opindex mapcs-float
7527Pass floating point arguments using the float point registers. This is
7528one of the variants of the APCS@. This option is recommended if the
7529target hardware has a floating point unit or if a lot of floating point
7530arithmetic is going to be performed by the code. The default is
7531@option{-mno-apcs-float}, since integer only code is slightly increased in
7532size if @option{-mapcs-float} is used.
7533
7534@c not currently implemented
7535@item -mapcs-reentrant
7536@opindex mapcs-reentrant
7537Generate reentrant, position independent code. The default is
7538@option{-mno-apcs-reentrant}.
7539@end ignore
7540
7541@item -mthumb-interwork
7542@opindex mthumb-interwork
7543Generate code which supports calling between the ARM and Thumb
7544instruction sets. Without this option the two instruction sets cannot
7545be reliably used inside one program. The default is
7546@option{-mno-thumb-interwork}, since slightly larger code is generated
7547when @option{-mthumb-interwork} is specified.
7548
7549@item -mno-sched-prolog
7550@opindex mno-sched-prolog
7551Prevent the reordering of instructions in the function prolog, or the
7552merging of those instruction with the instructions in the function's
7553body. This means that all functions will start with a recognizable set
7554of instructions (or in fact one of a choice from a small set of
7555different function prologues), and this information can be used to
7556locate the start if functions inside an executable piece of code. The
7557default is @option{-msched-prolog}.
7558
7559@item -mhard-float
7560@opindex mhard-float
7561Generate output containing floating point instructions. This is the
7562default.
7563
7564@item -msoft-float
7565@opindex msoft-float
7566Generate output containing library calls for floating point.
7567@strong{Warning:} the requisite libraries are not available for all ARM
7568targets. Normally the facilities of the machine's usual C compiler are
7569used, but this cannot be done directly in cross-compilation. You must make
7570your own arrangements to provide suitable library functions for
7571cross-compilation.
7572
7573@option{-msoft-float} changes the calling convention in the output file;
7574therefore, it is only useful if you compile @emph{all} of a program with
7575this option. In particular, you need to compile @file{libgcc.a}, the
7576library that comes with GCC, with @option{-msoft-float} in order for
7577this to work.
7578
7579@item -mfloat-abi=@var{name}
7580@opindex mfloat-abi
7581Specifies which ABI to use for floating point values. Permissible values
7582are: @samp{soft}, @samp{softfp} and @samp{hard}.
7583
7584@samp{soft} and @samp{hard} are equivalent to @option{-msoft-float}
7585and @option{-mhard-float} respectively. @samp{softfp} allows the generation
7586of floating point instructions, but still uses the soft-float calling
7587conventions.
7588
7589@item -mlittle-endian
7590@opindex mlittle-endian
7591Generate code for a processor running in little-endian mode. This is
7592the default for all standard configurations.
7593
7594@item -mbig-endian
7595@opindex mbig-endian
7596Generate code for a processor running in big-endian mode; the default is
7597to compile code for a little-endian processor.
7598
7599@item -mwords-little-endian
7600@opindex mwords-little-endian
7601This option only applies when generating code for big-endian processors.
7602Generate code for a little-endian word order but a big-endian byte
7603order. That is, a byte order of the form @samp{32107654}. Note: this
7604option should only be used if you require compatibility with code for
7605big-endian ARM processors generated by versions of the compiler prior to
76062.8.
7607
7608@item -mcpu=@var{name}
7609@opindex mcpu
7610This specifies the name of the target ARM processor. GCC uses this name
7611to determine what kind of instructions it can emit when generating
7612assembly code. Permissible names are: @samp{arm2}, @samp{arm250},
7613@samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
7614@samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
7615@samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
7616@samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
7617@samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},
7618@samp{arm8}, @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
7619@samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
7620@samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},
7621@samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},
7622@samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},
7623@samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
7624@samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
7625@samp{arm1176jz-s}, @samp{arm1176jzf-s}, @samp{xscale}, @samp{iwmmxt},
7626@samp{ep9312}.
7627
7628@itemx -mtune=@var{name}
7629@opindex mtune
7630This option is very similar to the @option{-mcpu=} option, except that
7631instead of specifying the actual target processor type, and hence
7632restricting which instructions can be used, it specifies that GCC should
7633tune the performance of the code as if the target were of the type
7634specified in this option, but still choosing the instructions that it
7635will generate based on the cpu specified by a @option{-mcpu=} option.
7636For some ARM implementations better performance can be obtained by using
7637this option.
7638
7639@item -march=@var{name}
7640@opindex march
7641This specifies the name of the target ARM architecture. GCC uses this
7642name to determine what kind of instructions it can emit when generating
7643assembly code. This option can be used in conjunction with or instead
7644of the @option{-mcpu=} option. Permissible names are: @samp{armv2},
7645@samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
7646@samp{armv5}, @samp{armv5t}, @samp{armv5te}, @samp{armv6}, @samp{armv6j},
7647@samp{iwmmxt}, @samp{ep9312}.
7648
7649@item -mfpu=@var{name}
7650@itemx -mfpe=@var{number}
7651@itemx -mfp=@var{number}
7652@opindex mfpu
7653@opindex mfpe
7654@opindex mfp
7655This specifies what floating point hardware (or hardware emulation) is
7656available on the target. Permissible names are: @samp{fpa}, @samp{fpe2},
7657@samp{fpe3}, @samp{maverick}, @samp{vfp}. @option{-mfp} and @option{-mfpe}
7658are synonyms for @option{-mfpu}=@samp{fpe}@var{number}, for compatibility
7659with older versions of GCC@.
7660
7661If @option{-msoft-float} is specified this specifies the format of
7662floating point values.
7663
7664@item -mstructure-size-boundary=@var{n}
7665@opindex mstructure-size-boundary
7666The size of all structures and unions will be rounded up to a multiple
7667of the number of bits set by this option. Permissible values are 8, 32
7668and 64. The default value varies for different toolchains. For the COFF
7669targeted toolchain the default value is 8. A value of 64 is only allowed
7670if the underlying ABI supports it.
7671
7672Specifying the larger number can produce faster, more efficient code, but
7673can also increase the size of the program. Different values are potentially
7674incompatible. Code compiled with one value cannot necessarily expect to
7675work with code or libraries compiled with another value, if they exchange
7676information using structures or unions.
7677
7678@item -mabort-on-noreturn
7679@opindex mabort-on-noreturn
7680Generate a call to the function @code{abort} at the end of a
7681@code{noreturn} function. It will be executed if the function tries to
7682return.
7683
7684@item -mlong-calls
7685@itemx -mno-long-calls
7686@opindex mlong-calls
7687@opindex mno-long-calls
7688Tells the compiler to perform function calls by first loading the
7689address of the function into a register and then performing a subroutine
7690call on this register. This switch is needed if the target function
7691will lie outside of the 64 megabyte addressing range of the offset based
7692version of subroutine call instruction.
7693
7694Even if this switch is enabled, not all function calls will be turned
7695into long calls. The heuristic is that static functions, functions
7696which have the @samp{short-call} attribute, functions that are inside
7697the scope of a @samp{#pragma no_long_calls} directive and functions whose
7698definitions have already been compiled within the current compilation
7699unit, will not be turned into long calls. The exception to this rule is
7700that weak function definitions, functions with the @samp{long-call}
7701attribute or the @samp{section} attribute, and functions that are within
7702the scope of a @samp{#pragma long_calls} directive, will always be
7703turned into long calls.
7704
7705This feature is not enabled by default. Specifying
7706@option{-mno-long-calls} will restore the default behavior, as will
7707placing the function calls within the scope of a @samp{#pragma
7708long_calls_off} directive. Note these switches have no effect on how
7709the compiler generates code to handle function calls via function
7710pointers.
7711
7712@item -mnop-fun-dllimport
7713@opindex mnop-fun-dllimport
7714Disable support for the @code{dllimport} attribute.
7715
7716@item -msingle-pic-base
7717@opindex msingle-pic-base
7718Treat the register used for PIC addressing as read-only, rather than
7719loading it in the prologue for each function. The run-time system is
7720responsible for initializing this register with an appropriate value
7721before execution begins.
7722
7723@item -mpic-register=@var{reg}
7724@opindex mpic-register
7725Specify the register to be used for PIC addressing. The default is R10
7726unless stack-checking is enabled, when R9 is used.
7727
7728@item -mcirrus-fix-invalid-insns
7729@opindex mcirrus-fix-invalid-insns
7730@opindex mno-cirrus-fix-invalid-insns
7731Insert NOPs into the instruction stream to in order to work around
7732problems with invalid Maverick instruction combinations. This option
7733is only valid if the @option{-mcpu=ep9312} option has been used to
7734enable generation of instructions for the Cirrus Maverick floating
7735point co-processor. This option is not enabled by default, since the
7736problem is only present in older Maverick implementations. The default
7737can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns}
7738switch.
7739
7740@item -mpoke-function-name
7741@opindex mpoke-function-name
7742Write the name of each function into the text section, directly
7743preceding the function prologue. The generated code is similar to this:
7744
7745@smallexample
7746 t0
7747 .ascii "arm_poke_function_name", 0
7748 .align
7749 t1
7750 .word 0xff000000 + (t1 - t0)
7751 arm_poke_function_name
7752 mov ip, sp
7753 stmfd sp!, @{fp, ip, lr, pc@}
7754 sub fp, ip, #4
7755@end smallexample
7756
7757When performing a stack backtrace, code can inspect the value of
7758@code{pc} stored at @code{fp + 0}. If the trace function then looks at
7759location @code{pc - 12} and the top 8 bits are set, then we know that
7760there is a function name embedded immediately preceding this location
7761and has length @code{((pc[-3]) & 0xff000000)}.
7762
7763@item -mthumb
7764@opindex mthumb
7765Generate code for the 16-bit Thumb instruction set. The default is to
7766use the 32-bit ARM instruction set.
7767
7768@item -mtpcs-frame
7769@opindex mtpcs-frame
7770Generate a stack frame that is compliant with the Thumb Procedure Call
7771Standard for all non-leaf functions. (A leaf function is one that does
7772not call any other functions.) The default is @option{-mno-tpcs-frame}.
7773
7774@item -mtpcs-leaf-frame
7775@opindex mtpcs-leaf-frame
7776Generate a stack frame that is compliant with the Thumb Procedure Call
7777Standard for all leaf functions. (A leaf function is one that does
7778not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
7779
7780@item -mcallee-super-interworking
7781@opindex mcallee-super-interworking
7782Gives all externally visible functions in the file being compiled an ARM
7783instruction set header which switches to Thumb mode before executing the
7784rest of the function. This allows these functions to be called from
7785non-interworking code.
7786
7787@item -mcaller-super-interworking
7788@opindex mcaller-super-interworking
7789Allows calls via function pointers (including virtual functions) to
7790execute correctly regardless of whether the target code has been
7791compiled for interworking or not. There is a small overhead in the cost
7792of executing a function pointer if this option is enabled.
7793
7794@item -mtp=@var{name}
7795@opindex mtp
7796Specify the access model for the thread local storage pointer. The valid
7797models are @option{soft}, which generates calls to @code{__aeabi_read_tp},
7798@option{cp15}, which fetches the thread pointer from @code{cp15} directly
7799(supported in the arm6k architecture), and @option{auto}, which uses the
7800best available method for the selected processor. The default setting is
7801@option{auto}.
7802
7803@end table
7804
7805@node AVR Options
7806@subsection AVR Options
7807@cindex AVR Options
7808
7809These options are defined for AVR implementations:
7810
7811@table @gcctabopt
7812@item -mmcu=@var{mcu}
7813@opindex mmcu
7814Specify ATMEL AVR instruction set or MCU type.
7815
7816Instruction set avr1 is for the minimal AVR core, not supported by the C
7817compiler, only for assembler programs (MCU types: at90s1200, attiny10,
7818attiny11, attiny12, attiny15, attiny28).
7819
7820Instruction set avr2 (default) is for the classic AVR core with up to
78218K program memory space (MCU types: at90s2313, at90s2323, attiny22,
7822at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
7823at90c8534, at90s8535).
7824
7825Instruction set avr3 is for the classic AVR core with up to 128K program
7826memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
7827
7828Instruction set avr4 is for the enhanced AVR core with up to 8K program
7829memory space (MCU types: atmega8, atmega83, atmega85).
7830
7831Instruction set avr5 is for the enhanced AVR core with up to 128K program
7832memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
7833atmega64, atmega128, at43usb355, at94k).
7834
7835@item -msize
7836@opindex msize
7837Output instruction sizes to the asm file.
7838
7839@item -minit-stack=@var{N}
7840@opindex minit-stack
7841Specify the initial stack address, which may be a symbol or numeric value,
7842@samp{__stack} is the default.
7843
7844@item -mno-interrupts
7845@opindex mno-interrupts
7846Generated code is not compatible with hardware interrupts.
7847Code size will be smaller.
7848
7849@item -mcall-prologues
7850@opindex mcall-prologues
7851Functions prologues/epilogues expanded as call to appropriate
7852subroutines. Code size will be smaller.
7853
7854@item -mno-tablejump
7855@opindex mno-tablejump
7856Do not generate tablejump insns which sometimes increase code size.
7857
7858@item -mtiny-stack
7859@opindex mtiny-stack
7860Change only the low 8 bits of the stack pointer.
7861
7862@item -mint8
7863@opindex mint8
7864Assume int to be 8 bit integer. This affects the sizes of all types: A
7865char will be 1 byte, an int will be 1 byte, an long will be 2 bytes
7866and long long will be 4 bytes. Please note that this option does not
7867comply to the C standards, but it will provide you with smaller code
7868size.
7869@end table
7870
7871@node Blackfin Options
7872@subsection Blackfin Options
7873@cindex Blackfin Options
7874
7875@table @gcctabopt
7876@item -momit-leaf-frame-pointer
7877@opindex momit-leaf-frame-pointer
7878Don't keep the frame pointer in a register for leaf functions. This
7879avoids the instructions to save, set up and restore frame pointers and
7880makes an extra register available in leaf functions. The option
7881@option{-fomit-frame-pointer} removes the frame pointer for all functions
7882which might make debugging harder.
7883
7884@item -mspecld-anomaly
7885@opindex mspecld-anomaly
7886When enabled, the compiler will ensure that the generated code does not
7887contain speculative loads after jump instructions. This option is enabled
7888by default.
7889
7890@item -mno-specld-anomaly
7891@opindex mno-specld-anomaly
7892Don't generate extra code to prevent speculative loads from occurring.
7893
7894@item -mcsync-anomaly
7895@opindex mcsync-anomaly
7896When enabled, the compiler will ensure that the generated code does not
7897contain CSYNC or SSYNC instructions too soon after conditional branches.
7898This option is enabled by default.
7899
7900@item -mno-csync-anomaly
7901@opindex mno-csync-anomaly
7902Don't generate extra code to prevent CSYNC or SSYNC instructions from
7903occurring too soon after a conditional branch.
7904
7905@item -mlow-64k
7906@opindex mlow-64k
7907When enabled, the compiler is free to take advantage of the knowledge that
7908the entire program fits into the low 64k of memory.
7909
7910@item -mno-low-64k
7911@opindex mno-low-64k
7912Assume that the program is arbitrarily large. This is the default.
7913
7914@item -mid-shared-library
7915@opindex mid-shared-library
7916Generate code that supports shared libraries via the library ID method.
7917This allows for execute in place and shared libraries in an environment
7918without virtual memory management. This option implies @option{-fPIC}.
7919
7920@item -mno-id-shared-library
7921@opindex mno-id-shared-library
7922Generate code that doesn't assume ID based shared libraries are being used.
7923This is the default.
7924
7925@item -mshared-library-id=n
7926@opindex mshared-library-id
7927Specified the identification number of the ID based shared library being
7928compiled. Specifying a value of 0 will generate more compact code, specifying
7929other values will force the allocation of that number to the current
7930library but is no more space or time efficient than omitting this option.
7931
7932@item -mlong-calls
7933@itemx -mno-long-calls
7934@opindex mlong-calls
7935@opindex mno-long-calls
7936Tells the compiler to perform function calls by first loading the
7937address of the function into a register and then performing a subroutine
7938call on this register. This switch is needed if the target function
7939will lie outside of the 24 bit addressing range of the offset based
7940version of subroutine call instruction.
7941
7942This feature is not enabled by default. Specifying
7943@option{-mno-long-calls} will restore the default behavior. Note these
7944switches have no effect on how the compiler generates code to handle
7945function calls via function pointers.
7946@end table
7947
7948@node CRIS Options
7949@subsection CRIS Options
7950@cindex CRIS Options
7951
7952These options are defined specifically for the CRIS ports.
7953
7954@table @gcctabopt
7955@item -march=@var{architecture-type}
7956@itemx -mcpu=@var{architecture-type}
7957@opindex march
7958@opindex mcpu
7959Generate code for the specified architecture. The choices for
7960@var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
7961respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
7962Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
7963@samp{v10}.
7964
7965@item -mtune=@var{architecture-type}
7966@opindex mtune
7967Tune to @var{architecture-type} everything applicable about the generated
7968code, except for the ABI and the set of available instructions. The
7969choices for @var{architecture-type} are the same as for
7970@option{-march=@var{architecture-type}}.
7971
7972@item -mmax-stack-frame=@var{n}
7973@opindex mmax-stack-frame
7974Warn when the stack frame of a function exceeds @var{n} bytes.
7975
7976@item -melinux-stacksize=@var{n}
7977@opindex melinux-stacksize
7978Only available with the @samp{cris-axis-aout} target. Arranges for
7979indications in the program to the kernel loader that the stack of the
7980program should be set to @var{n} bytes.
7981
7982@item -metrax4
7983@itemx -metrax100
7984@opindex metrax4
7985@opindex metrax100
7986The options @option{-metrax4} and @option{-metrax100} are synonyms for
7987@option{-march=v3} and @option{-march=v8} respectively.
7988
7989@item -mmul-bug-workaround
7990@itemx -mno-mul-bug-workaround
7991@opindex mmul-bug-workaround
7992@opindex mno-mul-bug-workaround
7993Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
7994models where it applies. This option is active by default.
7995
7996@item -mpdebug
7997@opindex mpdebug
7998Enable CRIS-specific verbose debug-related information in the assembly
7999code. This option also has the effect to turn off the @samp{#NO_APP}
8000formatted-code indicator to the assembler at the beginning of the
8001assembly file.
8002
8003@item -mcc-init
8004@opindex mcc-init
8005Do not use condition-code results from previous instruction; always emit
8006compare and test instructions before use of condition codes.
8007
8008@item -mno-side-effects
8009@opindex mno-side-effects
8010Do not emit instructions with side-effects in addressing modes other than
8011post-increment.
8012
8013@item -mstack-align
8014@itemx -mno-stack-align
8015@itemx -mdata-align
8016@itemx -mno-data-align
8017@itemx -mconst-align
8018@itemx -mno-const-align
8019@opindex mstack-align
8020@opindex mno-stack-align
8021@opindex mdata-align
8022@opindex mno-data-align
8023@opindex mconst-align
8024@opindex mno-const-align
8025These options (no-options) arranges (eliminate arrangements) for the
8026stack-frame, individual data and constants to be aligned for the maximum
8027single data access size for the chosen CPU model. The default is to
8028arrange for 32-bit alignment. ABI details such as structure layout are
8029not affected by these options.
8030
8031@item -m32-bit
8032@itemx -m16-bit
8033@itemx -m8-bit
8034@opindex m32-bit
8035@opindex m16-bit
8036@opindex m8-bit
8037Similar to the stack- data- and const-align options above, these options
8038arrange for stack-frame, writable data and constants to all be 32-bit,
803916-bit or 8-bit aligned. The default is 32-bit alignment.
8040
8041@item -mno-prologue-epilogue
8042@itemx -mprologue-epilogue
8043@opindex mno-prologue-epilogue
8044@opindex mprologue-epilogue
8045With @option{-mno-prologue-epilogue}, the normal function prologue and
8046epilogue that sets up the stack-frame are omitted and no return
8047instructions or return sequences are generated in the code. Use this
8048option only together with visual inspection of the compiled code: no
8049warnings or errors are generated when call-saved registers must be saved,
8050or storage for local variable needs to be allocated.
8051
8052@item -mno-gotplt
8053@itemx -mgotplt
8054@opindex mno-gotplt
8055@opindex mgotplt
8056With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
8057instruction sequences that load addresses for functions from the PLT part
8058of the GOT rather than (traditional on other architectures) calls to the
8059PLT@. The default is @option{-mgotplt}.
8060
8061@item -maout
8062@opindex maout
8063Legacy no-op option only recognized with the cris-axis-aout target.
8064
8065@item -melf
8066@opindex melf
8067Legacy no-op option only recognized with the cris-axis-elf and
8068cris-axis-linux-gnu targets.
8069
8070@item -melinux
8071@opindex melinux
8072Only recognized with the cris-axis-aout target, where it selects a
8073GNU/linux-like multilib, include files and instruction set for
8074@option{-march=v8}.
8075
8076@item -mlinux
8077@opindex mlinux
8078Legacy no-op option only recognized with the cris-axis-linux-gnu target.
8079
8080@item -sim
8081@opindex sim
8082This option, recognized for the cris-axis-aout and cris-axis-elf arranges
8083to link with input-output functions from a simulator library. Code,
8084initialized data and zero-initialized data are allocated consecutively.
8085
8086@item -sim2
8087@opindex sim2
8088Like @option{-sim}, but pass linker options to locate initialized data at
80890x40000000 and zero-initialized data at 0x80000000.
8090@end table
8091
8092@node CRX Options
8093@subsection CRX Options
8094@cindex CRX Options
8095
8096These options are defined specifically for the CRX ports.
8097
8098@table @gcctabopt
8099
8100@item -mmac
8101@opindex mmac
8102Enable the use of multiply-accumulate instructions. Disabled by default.
8103
8104@item -mpush-args
8105@opindex mpush-args
8106Push instructions will be used to pass outgoing arguments when functions
8107are called. Enabled by default.
8108@end table
8109
8110@node Darwin Options
8111@subsection Darwin Options
8112@cindex Darwin options
8113
8114These options are defined for all architectures running the Darwin operating
8115system.
8116
8117FSF GCC on Darwin does not create ``fat'' object files; it will create
8118an object file for the single architecture that it was built to
8119target. Apple's GCC on Darwin does create ``fat'' files if multiple
8120@option{-arch} options are used; it does so by running the compiler or
8121linker multiple times and joining the results together with
8122@file{lipo}.
8123
8124The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
8125@samp{i686}) is determined by the flags that specify the ISA
8126that GCC is targetting, like @option{-mcpu} or @option{-march}. The
8127@option{-force_cpusubtype_ALL} option can be used to override this.
8128
8129The Darwin tools vary in their behavior when presented with an ISA
8130mismatch. The assembler, @file{as}, will only permit instructions to
8131be used that are valid for the subtype of the file it is generating,
8132so you cannot put 64-bit instructions in an @samp{ppc750} object file.
8133The linker for shared libraries, @file{/usr/bin/libtool}, will fail
8134and print an error if asked to create a shared library with a less
8135restrictive subtype than its input files (for instance, trying to put
8136a @samp{ppc970} object file in a @samp{ppc7400} library). The linker
8137for executables, @file{ld}, will quietly give the executable the most
8138restrictive subtype of any of its input files.
8139
8140@table @gcctabopt
8141@item -F@var{dir}
8142@opindex F
8143Add the framework directory @var{dir} to the head of the list of
8144directories to be searched for header files. These directories are
8145interleaved with those specified by @option{-I} options and are
8146scanned in a left-to-right order.
8147
8148A framework directory is a directory with frameworks in it. A
8149framework is a directory with a @samp{"Headers"} and/or
8150@samp{"PrivateHeaders"} directory contained directly in it that ends
8151in @samp{".framework"}. The name of a framework is the name of this
8152directory excluding the @samp{".framework"}. Headers associated with
8153the framework are found in one of those two directories, with
8154@samp{"Headers"} being searched first. A subframework is a framework
8155directory that is in a framework's @samp{"Frameworks"} directory.
8156Includes of subframework headers can only appear in a header of a
8157framework that contains the subframework, or in a sibling subframework
8158header. Two subframeworks are siblings if they occur in the same
8159framework. A subframework should not have the same name as a
8160framework, a warning will be issued if this is violated. Currently a
8161subframework cannot have subframeworks, in the future, the mechanism
8162may be extended to support this. The standard frameworks can be found
8163in @samp{"/System/Library/Frameworks"} and
8164@samp{"/Library/Frameworks"}. An example include looks like
8165@code{#include <Framework/header.h>}, where @samp{Framework} denotes
8166the name of the framework and header.h is found in the
8167@samp{"PrivateHeaders"} or @samp{"Headers"} directory.
8168
8169@item -gused
8170@opindex gused
8171Emit debugging information for symbols that are used. For STABS
8172debugging format, this enables @option{-feliminate-unused-debug-symbols}.
8173This is by default ON@.
8174
8175@item -gfull
8176@opindex gfull
8177Emit debugging information for all symbols and types.
8178
8179@item -mmacosx-version-min=@var{version}
8180The earliest version of MacOS X that this executable will run on
8181is @var{version}. Typical values of @var{version} include @code{10.1},
8182@code{10.2}, and @code{10.3.9}.
8183
8184The default for this option is to make choices that seem to be most
8185useful.
8186
8187@item -mkernel
8188@opindex mkernel
8189Enable kernel development mode. The @option{-mkernel} option sets
8190@option{-static}, @option{-fno-common}, @option{-fno-cxa-atexit},
8191@option{-fno-exceptions}, @option{-fno-non-call-exceptions},
8192@option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where
8193applicable. This mode also sets @option{-mno-altivec},
8194@option{-msoft-float}, @option{-fno-builtin} and
8195@option{-mlong-branch} for PowerPC targets.
8196
8197@item -mone-byte-bool
8198@opindex mone-byte-bool
8199Override the defaults for @samp{bool} so that @samp{sizeof(bool)==1}.
8200By default @samp{sizeof(bool)} is @samp{4} when compiling for
8201Darwin/PowerPC and @samp{1} when compiling for Darwin/x86, so this
8202option has no effect on x86.
8203
8204@strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
8205to generate code that is not binary compatible with code generated
8206without that switch. Using this switch may require recompiling all
8207other modules in a program, including system libraries. Use this
8208switch to conform to a non-default data model.
8209
8210@item -mfix-and-continue
8211@itemx -ffix-and-continue
8212@itemx -findirect-data
8213@opindex mfix-and-continue
8214@opindex ffix-and-continue
8215@opindex findirect-data
8216Generate code suitable for fast turn around development. Needed to
8217enable gdb to dynamically load @code{.o} files into already running
8218programs. @option{-findirect-data} and @option{-ffix-and-continue}
8219are provided for backwards compatibility.
8220
8221@item -all_load
8222@opindex all_load
8223Loads all members of static archive libraries.
8224See man ld(1) for more information.
8225
8226@item -arch_errors_fatal
8227@opindex arch_errors_fatal
8228Cause the errors having to do with files that have the wrong architecture
8229to be fatal.
8230
8231@item -bind_at_load
8232@opindex bind_at_load
8233Causes the output file to be marked such that the dynamic linker will
8234bind all undefined references when the file is loaded or launched.
8235
8236@item -bundle
8237@opindex bundle
8238Produce a Mach-o bundle format file.
8239See man ld(1) for more information.
8240
8241@item -bundle_loader @var{executable}
8242@opindex bundle_loader
8243This option specifies the @var{executable} that will be loading the build
8244output file being linked. See man ld(1) for more information.
8245
8246@item -dynamiclib
8247@opindex dynamiclib
8248When passed this option, GCC will produce a dynamic library instead of
8249an executable when linking, using the Darwin @file{libtool} command.
8250
8251@item -force_cpusubtype_ALL
8252@opindex force_cpusubtype_ALL
8253This causes GCC's output file to have the @var{ALL} subtype, instead of
8254one controlled by the @option{-mcpu} or @option{-march} option.
8255
8256@item -allowable_client @var{client_name}
8257@itemx -client_name
8258@itemx -compatibility_version
8259@itemx -current_version
8260@itemx -dead_strip
8261@itemx -dependency-file
8262@itemx -dylib_file
8263@itemx -dylinker_install_name
8264@itemx -dynamic
8265@itemx -exported_symbols_list
8266@itemx -filelist
8267@itemx -flat_namespace
8268@itemx -force_flat_namespace
8269@itemx -headerpad_max_install_names
8270@itemx -image_base
8271@itemx -init
8272@itemx -install_name
8273@itemx -keep_private_externs
8274@itemx -multi_module
8275@itemx -multiply_defined
8276@itemx -multiply_defined_unused
8277@itemx -noall_load
8278@itemx -no_dead_strip_inits_and_terms
8279@itemx -nofixprebinding
8280@itemx -nomultidefs
8281@itemx -noprebind
8282@itemx -noseglinkedit
8283@itemx -pagezero_size
8284@itemx -prebind
8285@itemx -prebind_all_twolevel_modules
8286@itemx -private_bundle
8287@itemx -read_only_relocs
8288@itemx -sectalign
8289@itemx -sectobjectsymbols
8290@itemx -whyload
8291@itemx -seg1addr
8292@itemx -sectcreate
8293@itemx -sectobjectsymbols
8294@itemx -sectorder
8295@itemx -segaddr
8296@itemx -segs_read_only_addr
8297@itemx -segs_read_write_addr
8298@itemx -seg_addr_table
8299@itemx -seg_addr_table_filename
8300@itemx -seglinkedit
8301@itemx -segprot
8302@itemx -segs_read_only_addr
8303@itemx -segs_read_write_addr
8304@itemx -single_module
8305@itemx -static
8306@itemx -sub_library
8307@itemx -sub_umbrella
8308@itemx -twolevel_namespace
8309@itemx -umbrella
8310@itemx -undefined
8311@itemx -unexported_symbols_list
8312@itemx -weak_reference_mismatches
8313@itemx -whatsloaded
8314
8315@opindex allowable_client
8316@opindex client_name
8317@opindex compatibility_version
8318@opindex current_version
8319@opindex dead_strip
8320@opindex dependency-file
8321@opindex dylib_file
8322@opindex dylinker_install_name
8323@opindex dynamic
8324@opindex exported_symbols_list
8325@opindex filelist
8326@opindex flat_namespace
8327@opindex force_flat_namespace
8328@opindex headerpad_max_install_names
8329@opindex image_base
8330@opindex init
8331@opindex install_name
8332@opindex keep_private_externs
8333@opindex multi_module
8334@opindex multiply_defined
8335@opindex multiply_defined_unused
8336@opindex noall_load
8337@opindex no_dead_strip_inits_and_terms
8338@opindex nofixprebinding
8339@opindex nomultidefs
8340@opindex noprebind
8341@opindex noseglinkedit
8342@opindex pagezero_size
8343@opindex prebind
8344@opindex prebind_all_twolevel_modules
8345@opindex private_bundle
8346@opindex read_only_relocs
8347@opindex sectalign
8348@opindex sectobjectsymbols
8349@opindex whyload
8350@opindex seg1addr
8351@opindex sectcreate
8352@opindex sectobjectsymbols
8353@opindex sectorder
8354@opindex segaddr
8355@opindex segs_read_only_addr
8356@opindex segs_read_write_addr
8357@opindex seg_addr_table
8358@opindex seg_addr_table_filename
8359@opindex seglinkedit
8360@opindex segprot
8361@opindex segs_read_only_addr
8362@opindex segs_read_write_addr
8363@opindex single_module
8364@opindex static
8365@opindex sub_library
8366@opindex sub_umbrella
8367@opindex twolevel_namespace
8368@opindex umbrella
8369@opindex undefined
8370@opindex unexported_symbols_list
8371@opindex weak_reference_mismatches
8372@opindex whatsloaded
8373
8374These options are passed to the Darwin linker. The Darwin linker man page
8375describes them in detail.
8376@end table
8377
8378@node DEC Alpha Options
8379@subsection DEC Alpha Options
8380
8381These @samp{-m} options are defined for the DEC Alpha implementations:
8382
8383@table @gcctabopt
8384@item -mno-soft-float
8385@itemx -msoft-float
8386@opindex mno-soft-float
8387@opindex msoft-float
8388Use (do not use) the hardware floating-point instructions for
8389floating-point operations. When @option{-msoft-float} is specified,
8390functions in @file{libgcc.a} will be used to perform floating-point
8391operations. Unless they are replaced by routines that emulate the
8392floating-point operations, or compiled in such a way as to call such
8393emulations routines, these routines will issue floating-point
8394operations. If you are compiling for an Alpha without floating-point
8395operations, you must ensure that the library is built so as not to call
8396them.
8397
8398Note that Alpha implementations without floating-point operations are
8399required to have floating-point registers.
8400
8401@item -mfp-reg
8402@itemx -mno-fp-regs
8403@opindex mfp-reg
8404@opindex mno-fp-regs
8405Generate code that uses (does not use) the floating-point register set.
8406@option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
8407register set is not used, floating point operands are passed in integer
8408registers as if they were integers and floating-point results are passed
8409in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
8410so any function with a floating-point argument or return value called by code
8411compiled with @option{-mno-fp-regs} must also be compiled with that
8412option.
8413
8414A typical use of this option is building a kernel that does not use,
8415and hence need not save and restore, any floating-point registers.
8416
8417@item -mieee
8418@opindex mieee
8419The Alpha architecture implements floating-point hardware optimized for
8420maximum performance. It is mostly compliant with the IEEE floating
8421point standard. However, for full compliance, software assistance is
8422required. This option generates code fully IEEE compliant code
8423@emph{except} that the @var{inexact-flag} is not maintained (see below).
8424If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
8425defined during compilation. The resulting code is less efficient but is
8426able to correctly support denormalized numbers and exceptional IEEE
8427values such as not-a-number and plus/minus infinity. Other Alpha
8428compilers call this option @option{-ieee_with_no_inexact}.
8429
8430@item -mieee-with-inexact
8431@opindex mieee-with-inexact
8432This is like @option{-mieee} except the generated code also maintains
8433the IEEE @var{inexact-flag}. Turning on this option causes the
8434generated code to implement fully-compliant IEEE math. In addition to
8435@code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
8436macro. On some Alpha implementations the resulting code may execute
8437significantly slower than the code generated by default. Since there is
8438very little code that depends on the @var{inexact-flag}, you should
8439normally not specify this option. Other Alpha compilers call this
8440option @option{-ieee_with_inexact}.
8441
8442@item -mfp-trap-mode=@var{trap-mode}
8443@opindex mfp-trap-mode
8444This option controls what floating-point related traps are enabled.
8445Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
8446The trap mode can be set to one of four values:
8447
8448@table @samp
8449@item n
8450This is the default (normal) setting. The only traps that are enabled
8451are the ones that cannot be disabled in software (e.g., division by zero
8452trap).
8453
8454@item u
8455In addition to the traps enabled by @samp{n}, underflow traps are enabled
8456as well.
8457
8458@item su
8459Like @samp{u}, but the instructions are marked to be safe for software
8460completion (see Alpha architecture manual for details).
8461
8462@item sui
8463Like @samp{su}, but inexact traps are enabled as well.
8464@end table
8465
8466@item -mfp-rounding-mode=@var{rounding-mode}
8467@opindex mfp-rounding-mode
8468Selects the IEEE rounding mode. Other Alpha compilers call this option
8469@option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
8470of:
8471
8472@table @samp
8473@item n
8474Normal IEEE rounding mode. Floating point numbers are rounded towards
8475the nearest machine number or towards the even machine number in case
8476of a tie.
8477
8478@item m
8479Round towards minus infinity.
8480
8481@item c
8482Chopped rounding mode. Floating point numbers are rounded towards zero.
8483
8484@item d
8485Dynamic rounding mode. A field in the floating point control register
8486(@var{fpcr}, see Alpha architecture reference manual) controls the
8487rounding mode in effect. The C library initializes this register for
8488rounding towards plus infinity. Thus, unless your program modifies the
8489@var{fpcr}, @samp{d} corresponds to round towards plus infinity.
8490@end table
8491
8492@item -mtrap-precision=@var{trap-precision}
8493@opindex mtrap-precision
8494In the Alpha architecture, floating point traps are imprecise. This
8495means without software assistance it is impossible to recover from a
8496floating trap and program execution normally needs to be terminated.
8497GCC can generate code that can assist operating system trap handlers
8498in determining the exact location that caused a floating point trap.
8499Depending on the requirements of an application, different levels of
8500precisions can be selected:
8501
8502@table @samp
8503@item p
8504Program precision. This option is the default and means a trap handler
8505can only identify which program caused a floating point exception.
8506
8507@item f
8508Function precision. The trap handler can determine the function that
8509caused a floating point exception.
8510
8511@item i
8512Instruction precision. The trap handler can determine the exact
8513instruction that caused a floating point exception.
8514@end table
8515
8516Other Alpha compilers provide the equivalent options called
8517@option{-scope_safe} and @option{-resumption_safe}.
8518
8519@item -mieee-conformant
8520@opindex mieee-conformant
8521This option marks the generated code as IEEE conformant. You must not
8522use this option unless you also specify @option{-mtrap-precision=i} and either
8523@option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
8524is to emit the line @samp{.eflag 48} in the function prologue of the
8525generated assembly file. Under DEC Unix, this has the effect that
8526IEEE-conformant math library routines will be linked in.
8527
8528@item -mbuild-constants
8529@opindex mbuild-constants
8530Normally GCC examines a 32- or 64-bit integer constant to
8531see if it can construct it from smaller constants in two or three
8532instructions. If it cannot, it will output the constant as a literal and
8533generate code to load it from the data segment at runtime.
8534
8535Use this option to require GCC to construct @emph{all} integer constants
8536using code, even if it takes more instructions (the maximum is six).
8537
8538You would typically use this option to build a shared library dynamic
8539loader. Itself a shared library, it must relocate itself in memory
8540before it can find the variables and constants in its own data segment.
8541
8542@item -malpha-as
8543@itemx -mgas
8544@opindex malpha-as
8545@opindex mgas
8546Select whether to generate code to be assembled by the vendor-supplied
8547assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
8548
8549@item -mbwx
8550@itemx -mno-bwx
8551@itemx -mcix
8552@itemx -mno-cix
8553@itemx -mfix
8554@itemx -mno-fix
8555@itemx -mmax
8556@itemx -mno-max
8557@opindex mbwx
8558@opindex mno-bwx
8559@opindex mcix
8560@opindex mno-cix
8561@opindex mfix
8562@opindex mno-fix
8563@opindex mmax
8564@opindex mno-max
8565Indicate whether GCC should generate code to use the optional BWX,
8566CIX, FIX and MAX instruction sets. The default is to use the instruction
8567sets supported by the CPU type specified via @option{-mcpu=} option or that
8568of the CPU on which GCC was built if none was specified.
8569
8570@item -mfloat-vax
8571@itemx -mfloat-ieee
8572@opindex mfloat-vax
8573@opindex mfloat-ieee
8574Generate code that uses (does not use) VAX F and G floating point
8575arithmetic instead of IEEE single and double precision.
8576
8577@item -mexplicit-relocs
8578@itemx -mno-explicit-relocs
8579@opindex mexplicit-relocs
8580@opindex mno-explicit-relocs
8581Older Alpha assemblers provided no way to generate symbol relocations
8582except via assembler macros. Use of these macros does not allow
8583optimal instruction scheduling. GNU binutils as of version 2.12
8584supports a new syntax that allows the compiler to explicitly mark
8585which relocations should apply to which instructions. This option
8586is mostly useful for debugging, as GCC detects the capabilities of
8587the assembler when it is built and sets the default accordingly.
8588
8589@item -msmall-data
8590@itemx -mlarge-data
8591@opindex msmall-data
8592@opindex mlarge-data
8593When @option{-mexplicit-relocs} is in effect, static data is
8594accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
8595is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
8596(the @code{.sdata} and @code{.sbss} sections) and are accessed via
859716-bit relocations off of the @code{$gp} register. This limits the
8598size of the small data area to 64KB, but allows the variables to be
8599directly accessed via a single instruction.
8600
8601The default is @option{-mlarge-data}. With this option the data area
8602is limited to just below 2GB@. Programs that require more than 2GB of
8603data must use @code{malloc} or @code{mmap} to allocate the data in the
8604heap instead of in the program's data segment.
8605
8606When generating code for shared libraries, @option{-fpic} implies
8607@option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
8608
8609@item -msmall-text
8610@itemx -mlarge-text
8611@opindex msmall-text
8612@opindex mlarge-text
8613When @option{-msmall-text} is used, the compiler assumes that the
8614code of the entire program (or shared library) fits in 4MB, and is
8615thus reachable with a branch instruction. When @option{-msmall-data}
8616is used, the compiler can assume that all local symbols share the
8617same @code{$gp} value, and thus reduce the number of instructions
8618required for a function call from 4 to 1.
8619
8620The default is @option{-mlarge-text}.
8621
8622@item -mcpu=@var{cpu_type}
8623@opindex mcpu
8624Set the instruction set and instruction scheduling parameters for
8625machine type @var{cpu_type}. You can specify either the @samp{EV}
8626style name or the corresponding chip number. GCC supports scheduling
8627parameters for the EV4, EV5 and EV6 family of processors and will
8628choose the default values for the instruction set from the processor
8629you specify. If you do not specify a processor type, GCC will default
8630to the processor on which the compiler was built.
8631
8632Supported values for @var{cpu_type} are
8633
8634@table @samp
8635@item ev4
8636@itemx ev45
8637@itemx 21064
8638Schedules as an EV4 and has no instruction set extensions.
8639
8640@item ev5
8641@itemx 21164
8642Schedules as an EV5 and has no instruction set extensions.
8643
8644@item ev56
8645@itemx 21164a
8646Schedules as an EV5 and supports the BWX extension.
8647
8648@item pca56
8649@itemx 21164pc
8650@itemx 21164PC
8651Schedules as an EV5 and supports the BWX and MAX extensions.
8652
8653@item ev6
8654@itemx 21264
8655Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
8656
8657@item ev67
8658@itemx 21264a
8659Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
8660@end table
8661
8662@item -mtune=@var{cpu_type}
8663@opindex mtune
8664Set only the instruction scheduling parameters for machine type
8665@var{cpu_type}. The instruction set is not changed.
8666
8667@item -mmemory-latency=@var{time}
8668@opindex mmemory-latency
8669Sets the latency the scheduler should assume for typical memory
8670references as seen by the application. This number is highly
8671dependent on the memory access patterns used by the application
8672and the size of the external cache on the machine.
8673
8674Valid options for @var{time} are
8675
8676@table @samp
8677@item @var{number}
8678A decimal number representing clock cycles.
8679
8680@item L1
8681@itemx L2
8682@itemx L3
8683@itemx main
8684The compiler contains estimates of the number of clock cycles for
8685``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
8686(also called Dcache, Scache, and Bcache), as well as to main memory.
8687Note that L3 is only valid for EV5.
8688
8689@end table
8690@end table
8691
8692@node DEC Alpha/VMS Options
8693@subsection DEC Alpha/VMS Options
8694
8695These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
8696
8697@table @gcctabopt
8698@item -mvms-return-codes
8699@opindex mvms-return-codes
8700Return VMS condition codes from main. The default is to return POSIX
8701style condition (e.g.@ error) codes.
8702@end table
8703
8704@node FRV Options
8705@subsection FRV Options
8706@cindex FRV Options
8707
8708@table @gcctabopt
8709@item -mgpr-32
8710@opindex mgpr-32
8711
8712Only use the first 32 general purpose registers.
8713
8714@item -mgpr-64
8715@opindex mgpr-64
8716
8717Use all 64 general purpose registers.
8718
8719@item -mfpr-32
8720@opindex mfpr-32
8721
8722Use only the first 32 floating point registers.
8723
8724@item -mfpr-64
8725@opindex mfpr-64
8726
8727Use all 64 floating point registers
8728
8729@item -mhard-float
8730@opindex mhard-float
8731
8732Use hardware instructions for floating point operations.
8733
8734@item -msoft-float
8735@opindex msoft-float
8736
8737Use library routines for floating point operations.
8738
8739@item -malloc-cc
8740@opindex malloc-cc
8741
8742Dynamically allocate condition code registers.
8743
8744@item -mfixed-cc
8745@opindex mfixed-cc
8746
8747Do not try to dynamically allocate condition code registers, only
8748use @code{icc0} and @code{fcc0}.
8749
8750@item -mdword
8751@opindex mdword
8752
8753Change ABI to use double word insns.
8754
8755@item -mno-dword
8756@opindex mno-dword
8757
8758Do not use double word instructions.
8759
8760@item -mdouble
8761@opindex mdouble
8762
8763Use floating point double instructions.
8764
8765@item -mno-double
8766@opindex mno-double
8767
8768Do not use floating point double instructions.
8769
8770@item -mmedia
8771@opindex mmedia
8772
8773Use media instructions.
8774
8775@item -mno-media
8776@opindex mno-media
8777
8778Do not use media instructions.
8779
8780@item -mmuladd
8781@opindex mmuladd
8782
8783Use multiply and add/subtract instructions.
8784
8785@item -mno-muladd
8786@opindex mno-muladd
8787
8788Do not use multiply and add/subtract instructions.
8789
8790@item -mfdpic
8791@opindex mfdpic
8792
8793Select the FDPIC ABI, that uses function descriptors to represent
8794pointers to functions. Without any PIC/PIE-related options, it
8795implies @option{-fPIE}. With @option{-fpic} or @option{-fpie}, it
8796assumes GOT entries and small data are within a 12-bit range from the
8797GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
8798are computed with 32 bits.
8799
8800@item -minline-plt
8801@opindex minline-plt
8802
8803Enable inlining of PLT entries in function calls to functions that are
8804not known to bind locally. It has no effect without @option{-mfdpic}.
8805It's enabled by default if optimizing for speed and compiling for
8806shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
8807optimization option such as @option{-O3} or above is present in the
8808command line.
8809
8810@item -mTLS
8811@opindex TLS
8812
8813Assume a large TLS segment when generating thread-local code.
8814
8815@item -mtls
8816@opindex tls
8817
8818Do not assume a large TLS segment when generating thread-local code.
8819
8820@item -mgprel-ro
8821@opindex mgprel-ro
8822
8823Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
8824that is known to be in read-only sections. It's enabled by default,
8825except for @option{-fpic} or @option{-fpie}: even though it may help
8826make the global offset table smaller, it trades 1 instruction for 4.
8827With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
8828one of which may be shared by multiple symbols, and it avoids the need
8829for a GOT entry for the referenced symbol, so it's more likely to be a
8830win. If it is not, @option{-mno-gprel-ro} can be used to disable it.
8831
8832@item -multilib-library-pic
8833@opindex multilib-library-pic
8834
8835Link with the (library, not FD) pic libraries. It's implied by
8836@option{-mlibrary-pic}, as well as by @option{-fPIC} and
8837@option{-fpic} without @option{-mfdpic}. You should never have to use
8838it explicitly.
8839
8840@item -mlinked-fp
8841@opindex mlinked-fp
8842
8843Follow the EABI requirement of always creating a frame pointer whenever
8844a stack frame is allocated. This option is enabled by default and can
8845be disabled with @option{-mno-linked-fp}.
8846
8847@item -mlong-calls
8848@opindex mlong-calls
8849
8850Use indirect addressing to call functions outside the current
8851compilation unit. This allows the functions to be placed anywhere
8852within the 32-bit address space.
8853
8854@item -malign-labels
8855@opindex malign-labels
8856
8857Try to align labels to an 8-byte boundary by inserting nops into the
8858previous packet. This option only has an effect when VLIW packing
8859is enabled. It doesn't create new packets; it merely adds nops to
8860existing ones.
8861
8862@item -mlibrary-pic
8863@opindex mlibrary-pic
8864
8865Generate position-independent EABI code.
8866
8867@item -macc-4
8868@opindex macc-4
8869
8870Use only the first four media accumulator registers.
8871
8872@item -macc-8
8873@opindex macc-8
8874
8875Use all eight media accumulator registers.
8876
8877@item -mpack
8878@opindex mpack
8879
8880Pack VLIW instructions.
8881
8882@item -mno-pack
8883@opindex mno-pack
8884
8885Do not pack VLIW instructions.
8886
8887@item -mno-eflags
8888@opindex mno-eflags
8889
8890Do not mark ABI switches in e_flags.
8891
8892@item -mcond-move
8893@opindex mcond-move
8894
8895Enable the use of conditional-move instructions (default).
8896
8897This switch is mainly for debugging the compiler and will likely be removed
8898in a future version.
8899
8900@item -mno-cond-move
8901@opindex mno-cond-move
8902
8903Disable the use of conditional-move instructions.
8904
8905This switch is mainly for debugging the compiler and will likely be removed
8906in a future version.
8907
8908@item -mscc
8909@opindex mscc
8910
8911Enable the use of conditional set instructions (default).
8912
8913This switch is mainly for debugging the compiler and will likely be removed
8914in a future version.
8915
8916@item -mno-scc
8917@opindex mno-scc
8918
8919Disable the use of conditional set instructions.
8920
8921This switch is mainly for debugging the compiler and will likely be removed
8922in a future version.
8923
8924@item -mcond-exec
8925@opindex mcond-exec
8926
8927Enable the use of conditional execution (default).
8928
8929This switch is mainly for debugging the compiler and will likely be removed
8930in a future version.
8931
8932@item -mno-cond-exec
8933@opindex mno-cond-exec
8934
8935Disable the use of conditional execution.
8936
8937This switch is mainly for debugging the compiler and will likely be removed
8938in a future version.
8939
8940@item -mvliw-branch
8941@opindex mvliw-branch
8942
8943Run a pass to pack branches into VLIW instructions (default).
8944
8945This switch is mainly for debugging the compiler and will likely be removed
8946in a future version.
8947
8948@item -mno-vliw-branch
8949@opindex mno-vliw-branch
8950
8951Do not run a pass to pack branches into VLIW instructions.
8952
8953This switch is mainly for debugging the compiler and will likely be removed
8954in a future version.
8955
8956@item -mmulti-cond-exec
8957@opindex mmulti-cond-exec
8958
8959Enable optimization of @code{&&} and @code{||} in conditional execution
8960(default).
8961
8962This switch is mainly for debugging the compiler and will likely be removed
8963in a future version.
8964
8965@item -mno-multi-cond-exec
8966@opindex mno-multi-cond-exec
8967
8968Disable optimization of @code{&&} and @code{||} in conditional execution.
8969
8970This switch is mainly for debugging the compiler and will likely be removed
8971in a future version.
8972
8973@item -mnested-cond-exec
8974@opindex mnested-cond-exec
8975
8976Enable nested conditional execution optimizations (default).
8977
8978This switch is mainly for debugging the compiler and will likely be removed
8979in a future version.
8980
8981@item -mno-nested-cond-exec
8982@opindex mno-nested-cond-exec
8983
8984Disable nested conditional execution optimizations.
8985
8986This switch is mainly for debugging the compiler and will likely be removed
8987in a future version.
8988
8989@item -moptimize-membar
8990@opindex moptimize-membar
8991
8992This switch removes redundant @code{membar} instructions from the
8993compiler generated code. It is enabled by default.
8994
8995@item -mno-optimize-membar
8996@opindex mno-optimize-membar
8997
8998This switch disables the automatic removal of redundant @code{membar}
8999instructions from the generated code.
9000
9001@item -mtomcat-stats
9002@opindex mtomcat-stats
9003
9004Cause gas to print out tomcat statistics.
9005
9006@item -mcpu=@var{cpu}
9007@opindex mcpu
9008
9009Select the processor type for which to generate code. Possible values are
9010@samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
9011@samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
9012
9013@end table
9014
9015@node GNU/Linux Options
9016@subsection GNU/Linux Options
9017
9018These @samp{-m} options are defined for GNU/Linux targets:
9019
9020@table @gcctabopt
9021@item -mglibc
9022@opindex mglibc
9023Use the GNU C library instead of uClibc. This is the default except
9024on @samp{*-*-linux-*uclibc*} targets.
9025
9026@item -muclibc
9027@opindex muclibc
9028Use uClibc instead of the GNU C library. This is the default on
9029@samp{*-*-linux-*uclibc*} targets.
9030@end table
9031
9032@node H8/300 Options
9033@subsection H8/300 Options
9034
9035These @samp{-m} options are defined for the H8/300 implementations:
9036
9037@table @gcctabopt
9038@item -mrelax
9039@opindex mrelax
9040Shorten some address references at link time, when possible; uses the
9041linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
9042ld, Using ld}, for a fuller description.
9043
9044@item -mh
9045@opindex mh
9046Generate code for the H8/300H@.
9047
9048@item -ms
9049@opindex ms
9050Generate code for the H8S@.
9051
9052@item -mn
9053@opindex mn
9054Generate code for the H8S and H8/300H in the normal mode. This switch
9055must be used either with @option{-mh} or @option{-ms}.
9056
9057@item -ms2600
9058@opindex ms2600
9059Generate code for the H8S/2600. This switch must be used with @option{-ms}.
9060
9061@item -mint32
9062@opindex mint32
9063Make @code{int} data 32 bits by default.
9064
9065@item -malign-300
9066@opindex malign-300
9067On the H8/300H and H8S, use the same alignment rules as for the H8/300.
9068The default for the H8/300H and H8S is to align longs and floats on 4
9069byte boundaries.
9070@option{-malign-300} causes them to be aligned on 2 byte boundaries.
9071This option has no effect on the H8/300.
9072@end table
9073
9074@node HPPA Options
9075@subsection HPPA Options
9076@cindex HPPA Options
9077
9078These @samp{-m} options are defined for the HPPA family of computers:
9079
9080@table @gcctabopt
9081@item -march=@var{architecture-type}
9082@opindex march
9083Generate code for the specified architecture. The choices for
9084@var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
90851.1, and @samp{2.0} for PA 2.0 processors. Refer to
9086@file{/usr/lib/sched.models} on an HP-UX system to determine the proper
9087architecture option for your machine. Code compiled for lower numbered
9088architectures will run on higher numbered architectures, but not the
9089other way around.
9090
9091@item -mpa-risc-1-0
9092@itemx -mpa-risc-1-1
9093@itemx -mpa-risc-2-0
9094@opindex mpa-risc-1-0
9095@opindex mpa-risc-1-1
9096@opindex mpa-risc-2-0
9097Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
9098
9099@item -mbig-switch
9100@opindex mbig-switch
9101Generate code suitable for big switch tables. Use this option only if
9102the assembler/linker complain about out of range branches within a switch
9103table.
9104
9105@item -mjump-in-delay
9106@opindex mjump-in-delay
9107Fill delay slots of function calls with unconditional jump instructions
9108by modifying the return pointer for the function call to be the target
9109of the conditional jump.
9110
9111@item -mdisable-fpregs
9112@opindex mdisable-fpregs
9113Prevent floating point registers from being used in any manner. This is
9114necessary for compiling kernels which perform lazy context switching of
9115floating point registers. If you use this option and attempt to perform
9116floating point operations, the compiler will abort.
9117
9118@item -mdisable-indexing
9119@opindex mdisable-indexing
9120Prevent the compiler from using indexing address modes. This avoids some
9121rather obscure problems when compiling MIG generated code under MACH@.
9122
9123@item -mno-space-regs
9124@opindex mno-space-regs
9125Generate code that assumes the target has no space registers. This allows
9126GCC to generate faster indirect calls and use unscaled index address modes.
9127
9128Such code is suitable for level 0 PA systems and kernels.
9129
9130@item -mfast-indirect-calls
9131@opindex mfast-indirect-calls
9132Generate code that assumes calls never cross space boundaries. This
9133allows GCC to emit code which performs faster indirect calls.
9134
9135This option will not work in the presence of shared libraries or nested
9136functions.
9137
9138@item -mfixed-range=@var{register-range}
9139@opindex mfixed-range
9140Generate code treating the given register range as fixed registers.
9141A fixed register is one that the register allocator can not use. This is
9142useful when compiling kernel code. A register range is specified as
9143two registers separated by a dash. Multiple register ranges can be
9144specified separated by a comma.
9145
9146@item -mlong-load-store
9147@opindex mlong-load-store
9148Generate 3-instruction load and store sequences as sometimes required by
9149the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
9150the HP compilers.
9151
9152@item -mportable-runtime
9153@opindex mportable-runtime
9154Use the portable calling conventions proposed by HP for ELF systems.
9155
9156@item -mgas
9157@opindex mgas
9158Enable the use of assembler directives only GAS understands.
9159
9160@item -mschedule=@var{cpu-type}
9161@opindex mschedule
9162Schedule code according to the constraints for the machine type
9163@var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
9164@samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer
9165to @file{/usr/lib/sched.models} on an HP-UX system to determine the
9166proper scheduling option for your machine. The default scheduling is
9167@samp{8000}.
9168
9169@item -mlinker-opt
9170@opindex mlinker-opt
9171Enable the optimization pass in the HP-UX linker. Note this makes symbolic
9172debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9
9173linkers in which they give bogus error messages when linking some programs.
9174
9175@item -msoft-float
9176@opindex msoft-float
9177Generate output containing library calls for floating point.
9178@strong{Warning:} the requisite libraries are not available for all HPPA
9179targets. Normally the facilities of the machine's usual C compiler are
9180used, but this cannot be done directly in cross-compilation. You must make
9181your own arrangements to provide suitable library functions for
9182cross-compilation. The embedded target @samp{hppa1.1-*-pro}
9183does provide software floating point support.
9184
9185@option{-msoft-float} changes the calling convention in the output file;
9186therefore, it is only useful if you compile @emph{all} of a program with
9187this option. In particular, you need to compile @file{libgcc.a}, the
9188library that comes with GCC, with @option{-msoft-float} in order for
9189this to work.
9190
9191@item -msio
9192@opindex msio
9193Generate the predefine, @code{_SIO}, for server IO@. The default is
9194@option{-mwsio}. This generates the predefines, @code{__hp9000s700},
9195@code{__hp9000s700__} and @code{_WSIO}, for workstation IO@. These
9196options are available under HP-UX and HI-UX@.
9197
9198@item -mgnu-ld
9199@opindex gnu-ld
9200Use GNU ld specific options. This passes @option{-shared} to ld when
9201building a shared library. It is the default when GCC is configured,
9202explicitly or implicitly, with the GNU linker. This option does not
9203have any affect on which ld is called, it only changes what parameters
9204are passed to that ld. The ld that is called is determined by the
9205@option{--with-ld} configure option, GCC's program search path, and
9206finally by the user's @env{PATH}. The linker used by GCC can be printed
9207using @samp{which `gcc -print-prog-name=ld`}. This option is only available
9208on the 64 bit HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
9209
9210@item -mhp-ld
9211@opindex hp-ld
9212Use HP ld specific options. This passes @option{-b} to ld when building
9213a shared library and passes @option{+Accept TypeMismatch} to ld on all
9214links. It is the default when GCC is configured, explicitly or
9215implicitly, with the HP linker. This option does not have any affect on
9216which ld is called, it only changes what parameters are passed to that
9217ld. The ld that is called is determined by the @option{--with-ld}
9218configure option, GCC's program search path, and finally by the user's
9219@env{PATH}. The linker used by GCC can be printed using @samp{which
9220`gcc -print-prog-name=ld`}. This option is only available on the 64 bit
9221HP-UX GCC, i.e. configured with @samp{hppa*64*-*-hpux*}.
9222
9223@item -mlong-calls
9224@opindex mno-long-calls
9225Generate code that uses long call sequences. This ensures that a call
9226is always able to reach linker generated stubs. The default is to generate
9227long calls only when the distance from the call site to the beginning
9228of the function or translation unit, as the case may be, exceeds a
9229predefined limit set by the branch type being used. The limits for
9230normal calls are 7,600,000 and 240,000 bytes, respectively for the
9231PA 2.0 and PA 1.X architectures. Sibcalls are always limited at
9232240,000 bytes.
9233
9234Distances are measured from the beginning of functions when using the
9235@option{-ffunction-sections} option, or when using the @option{-mgas}
9236and @option{-mno-portable-runtime} options together under HP-UX with
9237the SOM linker.
9238
9239It is normally not desirable to use this option as it will degrade
9240performance. However, it may be useful in large applications,
9241particularly when partial linking is used to build the application.
9242
9243The types of long calls used depends on the capabilities of the
9244assembler and linker, and the type of code being generated. The
9245impact on systems that support long absolute calls, and long pic
9246symbol-difference or pc-relative calls should be relatively small.
9247However, an indirect call is used on 32-bit ELF systems in pic code
9248and it is quite long.
9249
9250@item -munix=@var{unix-std}
9251@opindex march
9252Generate compiler predefines and select a startfile for the specified
9253UNIX standard. The choices for @var{unix-std} are @samp{93}, @samp{95}
9254and @samp{98}. @samp{93} is supported on all HP-UX versions. @samp{95}
9255is available on HP-UX 10.10 and later. @samp{98} is available on HP-UX
925611.11 and later. The default values are @samp{93} for HP-UX 10.00,
9257@samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
9258and later.
9259
9260@option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
9261@option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
9262and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
9263@option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
9264@code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
9265@code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
9266
9267It is @emph{important} to note that this option changes the interfaces
9268for various library routines. It also affects the operational behavior
9269of the C library. Thus, @emph{extreme} care is needed in using this
9270option.
9271
9272Library code that is intended to operate with more than one UNIX
9273standard must test, set and restore the variable @var{__xpg4_extended_mask}
9274as appropriate. Most GNU software doesn't provide this capability.
9275
9276@item -nolibdld
9277@opindex nolibdld
9278Suppress the generation of link options to search libdld.sl when the
9279@option{-static} option is specified on HP-UX 10 and later.
9280
9281@item -static
9282@opindex static
9283The HP-UX implementation of setlocale in libc has a dependency on
9284libdld.sl. There isn't an archive version of libdld.sl. Thus,
9285when the @option{-static} option is specified, special link options
9286are needed to resolve this dependency.
9287
9288On HP-UX 10 and later, the GCC driver adds the necessary options to
9289link with libdld.sl when the @option{-static} option is specified.
9290This causes the resulting binary to be dynamic. On the 64-bit port,
9291the linkers generate dynamic binaries by default in any case. The
9292@option{-nolibdld} option can be used to prevent the GCC driver from
9293adding these link options.
9294
9295@item -threads
9296@opindex threads
9297Add support for multithreading with the @dfn{dce thread} library
9298under HP-UX@. This option sets flags for both the preprocessor and
9299linker.
9300@end table
9301
9302@node i386 and x86-64 Options
9303@subsection Intel 386 and AMD x86-64 Options
9304@cindex i386 Options
9305@cindex x86-64 Options
9306@cindex Intel 386 Options
9307@cindex AMD x86-64 Options
9308
9309These @samp{-m} options are defined for the i386 and x86-64 family of
9310computers:
9311
9312@table @gcctabopt
9313@item -mtune=@var{cpu-type}
9314@opindex mtune
9315Tune to @var{cpu-type} everything applicable about the generated code, except
9316for the ABI and the set of available instructions. The choices for
9317@var{cpu-type} are:
9318@table @emph
9319@item generic
9320Produce code optimized for the most common IA32/AMD64/EM64T processors.
9321If you know the CPU on which your code will run, then you should use
9322the corresponding @option{-mtune} option instead of
9323@option{-mtune=generic}. But, if you do not know exactly what CPU users
9324of your application will have, then you should use this option.
9325
9326As new processors are deployed in the marketplace, the behavior of this
9327option will change. Therefore, if you upgrade to a newer version of
9328GCC, the code generated option will change to reflect the processors
9329that were most common when that version of GCC was released.
9330
9331There is no @option{-march=generic} option because @option{-march}
9332indicates the instruction set the compiler can use, and there is no
9333generic instruction set applicable to all processors. In contrast,
9334@option{-mtune} indicates the processor (or, in this case, collection of
9335processors) for which the code is optimized.
9336@item native
9337This selects the CPU to tune for at compilation time by determining
9338the processor type of the compiling machine. Using @option{-mtune=native}
9339will produce code optimized for the local machine under the constraints
9340of the selected instruction set. Using @option{-march=native} will
9341enable all instruction subsets supported by the local machine (hence
9342the result might not run on different machines).
9343@item i386
9344Original Intel's i386 CPU@.
9345@item i486
9346Intel's i486 CPU@. (No scheduling is implemented for this chip.)
9347@item i586, pentium
9348Intel Pentium CPU with no MMX support.
9349@item pentium-mmx
9350Intel PentiumMMX CPU based on Pentium core with MMX instruction set support.
9351@item pentiumpro
9352Intel PentiumPro CPU@.
9353@item i686
9354Same as @code{generic}, but when used as @code{march} option, PentiumPro
9355instruction set will be used, so the code will run on all i686 family chips.
9356@item pentium2
9357Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support.
9358@item pentium3, pentium3m
9359Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set
9360support.
9361@item pentium-m
9362Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set
9363support. Used by Centrino notebooks.
9364@item pentium4, pentium4m
9365Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support.
9366@item prescott
9367Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction
9368set support.
9369@item nocona
9370Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE,
9371SSE2 and SSE3 instruction set support.
9372@item core2
9373Intel Core2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3
9374instruction set support.
9375@item k6
9376AMD K6 CPU with MMX instruction set support.
9377@item k6-2, k6-3
9378Improved versions of AMD K6 CPU with MMX and 3dNOW! instruction set support.
9379@item athlon, athlon-tbird
9380AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and SSE prefetch instructions
9381support.
9382@item athlon-4, athlon-xp, athlon-mp
9383Improved AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and full SSE
9384instruction set support.
9385@item k8, opteron, athlon64, athlon-fx
9386AMD K8 core based CPUs with x86-64 instruction set support. (This supersets
9387MMX, SSE, SSE2, 3dNOW!, enhanced 3dNOW! and 64-bit instruction set extensions.)
9388@item k8-sse3, opteron-sse3, athlon64-sse3
9389Improved versions of k8, opteron and athlon64 with SSE3 instruction set support.
9390@item winchip-c6
9391IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction
9392set support.
9393@item winchip2
9394IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3dNOW!
9395instruction set support.
9396@item c3
9397Via C3 CPU with MMX and 3dNOW! instruction set support. (No scheduling is
9398implemented for this chip.)
9399@item c3-2
9400Via C3-2 CPU with MMX and SSE instruction set support. (No scheduling is
9401implemented for this chip.)
9402@item geode
9403Embedded AMD CPU with MMX and 3dNOW! instruction set support.
9404@end table
9405
9406While picking a specific @var{cpu-type} will schedule things appropriately
9407for that particular chip, the compiler will not generate any code that
9408does not run on the i386 without the @option{-march=@var{cpu-type}} option
9409being used.
9410
9411@item -march=@var{cpu-type}
9412@opindex march
9413Generate instructions for the machine type @var{cpu-type}. The choices
9414for @var{cpu-type} are the same as for @option{-mtune}. Moreover,
9415specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}.
9416
9417@item -mcpu=@var{cpu-type}
9418@opindex mcpu
9419A deprecated synonym for @option{-mtune}.
9420
9421@item -m386
9422@itemx -m486
9423@itemx -mpentium
9424@itemx -mpentiumpro
9425@opindex m386
9426@opindex m486
9427@opindex mpentium
9428@opindex mpentiumpro
9429These options are synonyms for @option{-mtune=i386}, @option{-mtune=i486},
9430@option{-mtune=pentium}, and @option{-mtune=pentiumpro} respectively.
9431These synonyms are deprecated.
9432
9433@item -mfpmath=@var{unit}
9434@opindex march
9435Generate floating point arithmetics for selected unit @var{unit}. The choices
9436for @var{unit} are:
9437
9438@table @samp
9439@item 387
9440Use the standard 387 floating point coprocessor present majority of chips and
9441emulated otherwise. Code compiled with this option will run almost everywhere.
9442The temporary results are computed in 80bit precision instead of precision
9443specified by the type resulting in slightly different results compared to most
9444of other chips. See @option{-ffloat-store} for more detailed description.
9445
9446This is the default choice for i386 compiler.
9447
9448@item sse
9449Use scalar floating point instructions present in the SSE instruction set.
9450This instruction set is supported by Pentium3 and newer chips, in the AMD line
9451by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE
9452instruction set supports only single precision arithmetics, thus the double and
9453extended precision arithmetics is still done using 387. Later version, present
9454only in Pentium4 and the future AMD x86-64 chips supports double precision
9455arithmetics too.
9456
9457For the i386 compiler, you need to use @option{-march=@var{cpu-type}}, @option{-msse}
9458or @option{-msse2} switches to enable SSE extensions and make this option
9459effective. For the x86-64 compiler, these extensions are enabled by default.
9460
9461The resulting code should be considerably faster in the majority of cases and avoid
9462the numerical instability problems of 387 code, but may break some existing
9463code that expects temporaries to be 80bit.
9464
9465This is the default choice for the x86-64 compiler.
9466
9467@item sse,387
9468Attempt to utilize both instruction sets at once. This effectively double the
9469amount of available registers and on chips with separate execution units for
9470387 and SSE the execution resources too. Use this option with care, as it is
9471still experimental, because the GCC register allocator does not model separate
9472functional units well resulting in instable performance.
9473@end table
9474
9475@item -masm=@var{dialect}
9476@opindex masm=@var{dialect}
9477Output asm instructions using selected @var{dialect}. Supported
9478choices are @samp{intel} or @samp{att} (the default one). Darwin does
9479not support @samp{intel}.
9480
9481@item -mieee-fp
9482@itemx -mno-ieee-fp
9483@opindex mieee-fp
9484@opindex mno-ieee-fp
9485Control whether or not the compiler uses IEEE floating point
9486comparisons. These handle correctly the case where the result of a
9487comparison is unordered.
9488
9489@item -msoft-float
9490@opindex msoft-float
9491Generate output containing library calls for floating point.
9492@strong{Warning:} the requisite libraries are not part of GCC@.
9493Normally the facilities of the machine's usual C compiler are used, but
9494this can't be done directly in cross-compilation. You must make your
9495own arrangements to provide suitable library functions for
9496cross-compilation.
9497
9498On machines where a function returns floating point results in the 80387
9499register stack, some floating point opcodes may be emitted even if
9500@option{-msoft-float} is used.
9501
9502@item -mno-fp-ret-in-387
9503@opindex mno-fp-ret-in-387
9504Do not use the FPU registers for return values of functions.
9505
9506The usual calling convention has functions return values of types
9507@code{float} and @code{double} in an FPU register, even if there
9508is no FPU@. The idea is that the operating system should emulate
9509an FPU@.
9510
9511The option @option{-mno-fp-ret-in-387} causes such values to be returned
9512in ordinary CPU registers instead.
9513
9514@item -mno-fancy-math-387
9515@opindex mno-fancy-math-387
9516Some 387 emulators do not support the @code{sin}, @code{cos} and
9517@code{sqrt} instructions for the 387. Specify this option to avoid
9518generating those instructions. This option is the default on
9519OpenBSD and NetBSD@. This option is overridden when @option{-march}
9520indicates that the target cpu will always have an FPU and so the
9521instruction will not need emulation. As of revision 2.6.1, these
9522instructions are not generated unless you also use the
9523@option{-funsafe-math-optimizations} switch.
9524
9525@item -malign-double
9526@itemx -mno-align-double
9527@opindex malign-double
9528@opindex mno-align-double
9529Control whether GCC aligns @code{double}, @code{long double}, and
9530@code{long long} variables on a two word boundary or a one word
9531boundary. Aligning @code{double} variables on a two word boundary will
9532produce code that runs somewhat faster on a @samp{Pentium} at the
9533expense of more memory.
9534
9535On x86-64, @option{-malign-double} is enabled by default.
9536
9537@strong{Warning:} if you use the @option{-malign-double} switch,
9538structures containing the above types will be aligned differently than
9539the published application binary interface specifications for the 386
9540and will not be binary compatible with structures in code compiled
9541without that switch.
9542
9543@item -m96bit-long-double
9544@itemx -m128bit-long-double
9545@opindex m96bit-long-double
9546@opindex m128bit-long-double
9547These switches control the size of @code{long double} type. The i386
9548application binary interface specifies the size to be 96 bits,
9549so @option{-m96bit-long-double} is the default in 32 bit mode.
9550
9551Modern architectures (Pentium and newer) would prefer @code{long double}
9552to be aligned to an 8 or 16 byte boundary. In arrays or structures
9553conforming to the ABI, this would not be possible. So specifying a
9554@option{-m128bit-long-double} will align @code{long double}
9555to a 16 byte boundary by padding the @code{long double} with an additional
955632 bit zero.
9557
9558In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
9559its ABI specifies that @code{long double} is to be aligned on 16 byte boundary.
9560
9561Notice that neither of these options enable any extra precision over the x87
9562standard of 80 bits for a @code{long double}.
9563
9564@strong{Warning:} if you override the default value for your target ABI, the
9565structures and arrays containing @code{long double} variables will change
9566their size as well as function calling convention for function taking
9567@code{long double} will be modified. Hence they will not be binary
9568compatible with arrays or structures in code compiled without that switch.
9569
9570@item -mmlarge-data-threshold=@var{number}
9571@opindex mlarge-data-threshold=@var{number}
9572When @option{-mcmodel=medium} is specified, the data greater than
9573@var{threshold} are placed in large data section. This value must be the
9574same across all object linked into the binary and defaults to 65535.
9575
9576@item -msvr3-shlib
9577@itemx -mno-svr3-shlib
9578@opindex msvr3-shlib
9579@opindex mno-svr3-shlib
9580Control whether GCC places uninitialized local variables into the
9581@code{bss} or @code{data} segments. @option{-msvr3-shlib} places them
9582into @code{bss}. These options are meaningful only on System V Release 3.
9583
9584@item -mrtd
9585@opindex mrtd
9586Use a different function-calling convention, in which functions that
9587take a fixed number of arguments return with the @code{ret} @var{num}
9588instruction, which pops their arguments while returning. This saves one
9589instruction in the caller since there is no need to pop the arguments
9590there.
9591
9592You can specify that an individual function is called with this calling
9593sequence with the function attribute @samp{stdcall}. You can also
9594override the @option{-mrtd} option by using the function attribute
9595@samp{cdecl}. @xref{Function Attributes}.
9596
9597@strong{Warning:} this calling convention is incompatible with the one
9598normally used on Unix, so you cannot use it if you need to call
9599libraries compiled with the Unix compiler.
9600
9601Also, you must provide function prototypes for all functions that
9602take variable numbers of arguments (including @code{printf});
9603otherwise incorrect code will be generated for calls to those
9604functions.
9605
9606In addition, seriously incorrect code will result if you call a
9607function with too many arguments. (Normally, extra arguments are
9608harmlessly ignored.)
9609
9610@item -mregparm=@var{num}
9611@opindex mregparm
9612Control how many registers are used to pass integer arguments. By
9613default, no registers are used to pass arguments, and at most 3
9614registers can be used. You can control this behavior for a specific
9615function by using the function attribute @samp{regparm}.
9616@xref{Function Attributes}.
9617
9618@strong{Warning:} if you use this switch, and
9619@var{num} is nonzero, then you must build all modules with the same
9620value, including any libraries. This includes the system libraries and
9621startup modules.
9622
9623@item -msseregparm
9624@opindex msseregparm
9625Use SSE register passing conventions for float and double arguments
9626and return values. You can control this behavior for a specific
9627function by using the function attribute @samp{sseregparm}.
9628@xref{Function Attributes}.
9629
9630@strong{Warning:} if you use this switch then you must build all
9631modules with the same value, including any libraries. This includes
9632the system libraries and startup modules.
9633
9634@item -mstackrealign
9635@opindex mstackrealign
9636Realign the stack at entry. On the Intel x86, the
9637@option{-mstackrealign} option will generate an alternate prologue and
9638epilogue that realigns the runtime stack. This supports mixing legacy
9639codes that keep a 4-byte aligned stack with modern codes that keep a
964016-byte stack for SSE compatibility. The alternate prologue and
9641epilogue are slower and bigger than the regular ones, and the
9642alternate prologue requires an extra scratch register; this lowers the
9643number of registers available if used in conjunction with the
9644@code{regparm} attribute. The @option{-mstackrealign} option is
9645incompatible with the nested function prologue; this is considered a
9646hard error. See also the attribute @code{force_align_arg_pointer},
9647applicable to individual functions.
9648
9649@item -mpreferred-stack-boundary=@var{num}
9650@opindex mpreferred-stack-boundary
9651Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
9652byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
9653the default is 4 (16 bytes or 128 bits).
9654
9655On Pentium and PentiumPro, @code{double} and @code{long double} values
9656should be aligned to an 8 byte boundary (see @option{-malign-double}) or
9657suffer significant run time performance penalties. On Pentium III, the
9658Streaming SIMD Extension (SSE) data type @code{__m128} may not work
9659properly if it is not 16 byte aligned.
9660
9661To ensure proper alignment of this values on the stack, the stack boundary
9662must be as aligned as that required by any value stored on the stack.
9663Further, every function must be generated such that it keeps the stack
9664aligned. Thus calling a function compiled with a higher preferred
9665stack boundary from a function compiled with a lower preferred stack
9666boundary will most likely misalign the stack. It is recommended that
9667libraries that use callbacks always use the default setting.
9668
9669This extra alignment does consume extra stack space, and generally
9670increases code size. Code that is sensitive to stack space usage, such
9671as embedded systems and operating system kernels, may want to reduce the
9672preferred alignment to @option{-mpreferred-stack-boundary=2}.
9673
9674@item -mmmx
9675@itemx -mno-mmx
9676@item -msse
9677@itemx -mno-sse
9678@item -msse2
9679@itemx -mno-sse2
9680@item -msse3
9681@itemx -mno-sse3
9682@item -m3dnow
9683@itemx -mno-3dnow
9684@opindex mmmx
9685@opindex mno-mmx
9686@opindex msse
9687@opindex mno-sse
9688@opindex m3dnow
9689@opindex mno-3dnow
9690These switches enable or disable the use of instructions in the MMX,
9691SSE, SSE2 or 3DNow! extended instruction sets. These extensions are
9692also available as built-in functions: see @ref{X86 Built-in Functions},
9693for details of the functions enabled and disabled by these switches.
9694
9695To have SSE/SSE2 instructions generated automatically from floating-point
9696code (as opposed to 387 instructions), see @option{-mfpmath=sse}.
9697
9698These options will enable GCC to use these extended instructions in
9699generated code, even without @option{-mfpmath=sse}. Applications which
9700perform runtime CPU detection must compile separate files for each
9701supported architecture, using the appropriate flags. In particular,
9702the file containing the CPU detection code should be compiled without
9703these options.
9704
9705@item -mpush-args
9706@itemx -mno-push-args
9707@opindex mpush-args
9708@opindex mno-push-args
9709Use PUSH operations to store outgoing parameters. This method is shorter
9710and usually equally fast as method using SUB/MOV operations and is enabled
9711by default. In some cases disabling it may improve performance because of
9712improved scheduling and reduced dependencies.
9713
9714@item -maccumulate-outgoing-args
9715@opindex maccumulate-outgoing-args
9716If enabled, the maximum amount of space required for outgoing arguments will be
9717computed in the function prologue. This is faster on most modern CPUs
9718because of reduced dependencies, improved scheduling and reduced stack usage
9719when preferred stack boundary is not equal to 2. The drawback is a notable
9720increase in code size. This switch implies @option{-mno-push-args}.
9721
9722@item -mthreads
9723@opindex mthreads
9724Support thread-safe exception handling on @samp{Mingw32}. Code that relies
9725on thread-safe exception handling must compile and link all code with the
9726@option{-mthreads} option. When compiling, @option{-mthreads} defines
9727@option{-D_MT}; when linking, it links in a special thread helper library
9728@option{-lmingwthrd} which cleans up per thread exception handling data.
9729
9730@item -mno-align-stringops
9731@opindex mno-align-stringops
9732Do not align destination of inlined string operations. This switch reduces
9733code size and improves performance in case the destination is already aligned,
9734but GCC doesn't know about it.
9735
9736@item -minline-all-stringops
9737@opindex minline-all-stringops
9738By default GCC inlines string operations only when destination is known to be
9739aligned at least to 4 byte boundary. This enables more inlining, increase code
9740size, but may improve performance of code that depends on fast memcpy, strlen
9741and memset for short lengths.
9742
9743@item -momit-leaf-frame-pointer
9744@opindex momit-leaf-frame-pointer
9745Don't keep the frame pointer in a register for leaf functions. This
9746avoids the instructions to save, set up and restore frame pointers and
9747makes an extra register available in leaf functions. The option
9748@option{-fomit-frame-pointer} removes the frame pointer for all functions
9749which might make debugging harder.
9750
9751@item -mtls-direct-seg-refs
9752@itemx -mno-tls-direct-seg-refs
9753@opindex mtls-direct-seg-refs
9754Controls whether TLS variables may be accessed with offsets from the
9755TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
9756or whether the thread base pointer must be added. Whether or not this
9757is legal depends on the operating system, and whether it maps the
9758segment to cover the entire TLS area.
9759
9760For systems that use GNU libc, the default is on.
9761@end table
9762
9763These @samp{-m} switches are supported in addition to the above
9764on AMD x86-64 processors in 64-bit environments.
9765
9766@table @gcctabopt
9767@item -m32
9768@itemx -m64
9769@opindex m32
9770@opindex m64
9771Generate code for a 32-bit or 64-bit environment.
9772The 32-bit environment sets int, long and pointer to 32 bits and
9773generates code that runs on any i386 system.
9774The 64-bit environment sets int to 32 bits and long and pointer
9775to 64 bits and generates code for AMD's x86-64 architecture. For
9776darwin only the -m64 option turns off the @option{-fno-pic} and
9777@option{-mdynamic-no-pic} options.
9778
9779@item -mno-red-zone
9780@opindex no-red-zone
9781Do not use a so called red zone for x86-64 code. The red zone is mandated
9782by the x86-64 ABI, it is a 128-byte area beyond the location of the
9783stack pointer that will not be modified by signal or interrupt handlers
9784and therefore can be used for temporary data without adjusting the stack
9785pointer. The flag @option{-mno-red-zone} disables this red zone.
9786
9787@item -mcmodel=small
9788@opindex mcmodel=small
9789Generate code for the small code model: the program and its symbols must
9790be linked in the lower 2 GB of the address space. Pointers are 64 bits.
9791Programs can be statically or dynamically linked. This is the default
9792code model.
9793
9794@item -mcmodel=kernel
9795@opindex mcmodel=kernel
9796Generate code for the kernel code model. The kernel runs in the
9797negative 2 GB of the address space.
9798This model has to be used for Linux kernel code.
9799
9800@item -mcmodel=medium
9801@opindex mcmodel=medium
9802Generate code for the medium model: The program is linked in the lower 2
9803GB of the address space but symbols can be located anywhere in the
9804address space. Programs can be statically or dynamically linked, but
9805building of shared libraries are not supported with the medium model.
9806
9807@item -mcmodel=large
9808@opindex mcmodel=large
9809Generate code for the large model: This model makes no assumptions
9810about addresses and sizes of sections. Currently GCC does not implement
9811this model.
9812@end table
9813
9814@node IA-64 Options
9815@subsection IA-64 Options
9816@cindex IA-64 Options
9817
9818These are the @samp{-m} options defined for the Intel IA-64 architecture.
9819
9820@table @gcctabopt
9821@item -mbig-endian
9822@opindex mbig-endian
9823Generate code for a big endian target. This is the default for HP-UX@.
9824
9825@item -mlittle-endian
9826@opindex mlittle-endian
9827Generate code for a little endian target. This is the default for AIX5
9828and GNU/Linux.
9829
9830@item -mgnu-as
9831@itemx -mno-gnu-as
9832@opindex mgnu-as
9833@opindex mno-gnu-as
9834Generate (or don't) code for the GNU assembler. This is the default.
9835@c Also, this is the default if the configure option @option{--with-gnu-as}
9836@c is used.
9837
9838@item -mgnu-ld
9839@itemx -mno-gnu-ld
9840@opindex mgnu-ld
9841@opindex mno-gnu-ld
9842Generate (or don't) code for the GNU linker. This is the default.
9843@c Also, this is the default if the configure option @option{--with-gnu-ld}
9844@c is used.
9845
9846@item -mno-pic
9847@opindex mno-pic
9848Generate code that does not use a global pointer register. The result
9849is not position independent code, and violates the IA-64 ABI@.
9850
9851@item -mvolatile-asm-stop
9852@itemx -mno-volatile-asm-stop
9853@opindex mvolatile-asm-stop
9854@opindex mno-volatile-asm-stop
9855Generate (or don't) a stop bit immediately before and after volatile asm
9856statements.
9857
9858@item -mregister-names
9859@itemx -mno-register-names
9860@opindex mregister-names
9861@opindex mno-register-names
9862Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
9863the stacked registers. This may make assembler output more readable.
9864
9865@item -mno-sdata
9866@itemx -msdata
9867@opindex mno-sdata
9868@opindex msdata
9869Disable (or enable) optimizations that use the small data section. This may
9870be useful for working around optimizer bugs.
9871
9872@item -mconstant-gp
9873@opindex mconstant-gp
9874Generate code that uses a single constant global pointer value. This is
9875useful when compiling kernel code.
9876
9877@item -mauto-pic
9878@opindex mauto-pic
9879Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
9880This is useful when compiling firmware code.
9881
9882@item -minline-float-divide-min-latency
9883@opindex minline-float-divide-min-latency
9884Generate code for inline divides of floating point values
9885using the minimum latency algorithm.
9886
9887@item -minline-float-divide-max-throughput
9888@opindex minline-float-divide-max-throughput
9889Generate code for inline divides of floating point values
9890using the maximum throughput algorithm.
9891
9892@item -minline-int-divide-min-latency
9893@opindex minline-int-divide-min-latency
9894Generate code for inline divides of integer values
9895using the minimum latency algorithm.
9896
9897@item -minline-int-divide-max-throughput
9898@opindex minline-int-divide-max-throughput
9899Generate code for inline divides of integer values
9900using the maximum throughput algorithm.
9901
9902@item -minline-sqrt-min-latency
9903@opindex minline-sqrt-min-latency
9904Generate code for inline square roots
9905using the minimum latency algorithm.
9906
9907@item -minline-sqrt-max-throughput
9908@opindex minline-sqrt-max-throughput
9909Generate code for inline square roots
9910using the maximum throughput algorithm.
9911
9912@item -mno-dwarf2-asm
9913@itemx -mdwarf2-asm
9914@opindex mno-dwarf2-asm
9915@opindex mdwarf2-asm
9916Don't (or do) generate assembler code for the DWARF2 line number debugging
9917info. This may be useful when not using the GNU assembler.
9918
9919@item -mearly-stop-bits
9920@itemx -mno-early-stop-bits
9921@opindex mearly-stop-bits
9922@opindex mno-early-stop-bits
9923Allow stop bits to be placed earlier than immediately preceding the
9924instruction that triggered the stop bit. This can improve instruction
9925scheduling, but does not always do so.
9926
9927@item -mfixed-range=@var{register-range}
9928@opindex mfixed-range
9929Generate code treating the given register range as fixed registers.
9930A fixed register is one that the register allocator can not use. This is
9931useful when compiling kernel code. A register range is specified as
9932two registers separated by a dash. Multiple register ranges can be
9933specified separated by a comma.
9934
9935@item -mtls-size=@var{tls-size}
9936@opindex mtls-size
9937Specify bit size of immediate TLS offsets. Valid values are 14, 22, and
993864.
9939
9940@item -mtune=@var{cpu-type}
9941@opindex mtune
9942Tune the instruction scheduling for a particular CPU, Valid values are
9943itanium, itanium1, merced, itanium2, and mckinley.
9944
9945@item -mt
9946@itemx -pthread
9947@opindex mt
9948@opindex pthread
9949Add support for multithreading using the POSIX threads library. This
9950option sets flags for both the preprocessor and linker. It does
9951not affect the thread safety of object code produced by the compiler or
9952that of libraries supplied with it. These are HP-UX specific flags.
9953
9954@item -milp32
9955@itemx -mlp64
9956@opindex milp32
9957@opindex mlp64
9958Generate code for a 32-bit or 64-bit environment.
9959The 32-bit environment sets int, long and pointer to 32 bits.
9960The 64-bit environment sets int to 32 bits and long and pointer
9961to 64 bits. These are HP-UX specific flags.
9962
9963@item -mno-sched-br-data-spec
9964@itemx -msched-br-data-spec
9965@opindex mno-sched-br-data-spec
9966@opindex msched-br-data-spec
9967(Dis/En)able data speculative scheduling before reload.
9968This will result in generation of the ld.a instructions and
9969the corresponding check instructions (ld.c / chk.a).
9970The default is 'disable'.
9971
9972@item -msched-ar-data-spec
9973@itemx -mno-sched-ar-data-spec
9974@opindex msched-ar-data-spec
9975@opindex mno-sched-ar-data-spec
9976(En/Dis)able data speculative scheduling after reload.
9977This will result in generation of the ld.a instructions and
9978the corresponding check instructions (ld.c / chk.a).
9979The default is 'enable'.
9980
9981@item -mno-sched-control-spec
9982@itemx -msched-control-spec
9983@opindex mno-sched-control-spec
9984@opindex msched-control-spec
9985(Dis/En)able control speculative scheduling. This feature is
9986available only during region scheduling (i.e. before reload).
9987This will result in generation of the ld.s instructions and
9988the corresponding check instructions chk.s .
9989The default is 'disable'.
9990
9991@item -msched-br-in-data-spec
9992@itemx -mno-sched-br-in-data-spec
9993@opindex msched-br-in-data-spec
9994@opindex mno-sched-br-in-data-spec
9995(En/Dis)able speculative scheduling of the instructions that
9996are dependent on the data speculative loads before reload.
9997This is effective only with @option{-msched-br-data-spec} enabled.
9998The default is 'enable'.
9999
10000@item -msched-ar-in-data-spec
10001@itemx -mno-sched-ar-in-data-spec
10002@opindex msched-ar-in-data-spec
10003@opindex mno-sched-ar-in-data-spec
10004(En/Dis)able speculative scheduling of the instructions that
10005are dependent on the data speculative loads after reload.
10006This is effective only with @option{-msched-ar-data-spec} enabled.
10007The default is 'enable'.
10008
10009@item -msched-in-control-spec
10010@itemx -mno-sched-in-control-spec
10011@opindex msched-in-control-spec
10012@opindex mno-sched-in-control-spec
10013(En/Dis)able speculative scheduling of the instructions that
10014are dependent on the control speculative loads.
10015This is effective only with @option{-msched-control-spec} enabled.
10016The default is 'enable'.
10017
10018@item -msched-ldc
10019@itemx -mno-sched-ldc
10020@opindex msched-ldc
10021@opindex mno-sched-ldc
10022(En/Dis)able use of simple data speculation checks ld.c .
10023If disabled, only chk.a instructions will be emitted to check
10024data speculative loads.
10025The default is 'enable'.
10026
10027@item -mno-sched-control-ldc
10028@itemx -msched-control-ldc
10029@opindex mno-sched-control-ldc
10030@opindex msched-control-ldc
10031(Dis/En)able use of ld.c instructions to check control speculative loads.
10032If enabled, in case of control speculative load with no speculatively
10033scheduled dependent instructions this load will be emitted as ld.sa and
10034ld.c will be used to check it.
10035The default is 'disable'.
10036
10037@item -mno-sched-spec-verbose
10038@itemx -msched-spec-verbose
10039@opindex mno-sched-spec-verbose
10040@opindex msched-spec-verbose
10041(Dis/En)able printing of the information about speculative motions.
10042
10043@item -mno-sched-prefer-non-data-spec-insns
10044@itemx -msched-prefer-non-data-spec-insns
10045@opindex mno-sched-prefer-non-data-spec-insns
10046@opindex msched-prefer-non-data-spec-insns
10047If enabled, data speculative instructions will be chosen for schedule
10048only if there are no other choices at the moment. This will make
10049the use of the data speculation much more conservative.
10050The default is 'disable'.
10051
10052@item -mno-sched-prefer-non-control-spec-insns
10053@itemx -msched-prefer-non-control-spec-insns
10054@opindex mno-sched-prefer-non-control-spec-insns
10055@opindex msched-prefer-non-control-spec-insns
10056If enabled, control speculative instructions will be chosen for schedule
10057only if there are no other choices at the moment. This will make
10058the use of the control speculation much more conservative.
10059The default is 'disable'.
10060
10061@item -mno-sched-count-spec-in-critical-path
10062@itemx -msched-count-spec-in-critical-path
10063@opindex mno-sched-count-spec-in-critical-path
10064@opindex msched-count-spec-in-critical-path
10065If enabled, speculative dependencies will be considered during
10066computation of the instructions priorities. This will make the use of the
10067speculation a bit more conservative.
10068The default is 'disable'.
10069
10070@end table
10071
10072@node M32C Options
10073@subsection M32C Options
10074@cindex M32C options
10075
10076@table @gcctabopt
10077@item -mcpu=@var{name}
10078@opindex mcpu=
10079Select the CPU for which code is generated. @var{name} may be one of
10080@samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to
10081/60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for
10082the M32C/80 series.
10083
10084@item -msim
10085@opindex msim
10086Specifies that the program will be run on the simulator. This causes
10087an alternate runtime library to be linked in which supports, for
10088example, file I/O. You must not use this option when generating
10089programs that will run on real hardware; you must provide your own
10090runtime library for whatever I/O functions are needed.
10091
10092@item -memregs=@var{number}
10093@opindex memregs=
10094Specifies the number of memory-based pseudo-registers GCC will use
10095during code generation. These pseudo-registers will be used like real
10096registers, so there is a tradeoff between GCC's ability to fit the
10097code into available registers, and the performance penalty of using
10098memory instead of registers. Note that all modules in a program must
10099be compiled with the same value for this option. Because of that, you
10100must not use this option with the default runtime libraries gcc
10101builds.
10102
10103@end table
10104
10105@node M32R/D Options
10106@subsection M32R/D Options
10107@cindex M32R/D options
10108
10109These @option{-m} options are defined for Renesas M32R/D architectures:
10110
10111@table @gcctabopt
10112@item -m32r2
10113@opindex m32r2
10114Generate code for the M32R/2@.
10115
10116@item -m32rx
10117@opindex m32rx
10118Generate code for the M32R/X@.
10119
10120@item -m32r
10121@opindex m32r
10122Generate code for the M32R@. This is the default.
10123
10124@item -mmodel=small
10125@opindex mmodel=small
10126Assume all objects live in the lower 16MB of memory (so that their addresses
10127can be loaded with the @code{ld24} instruction), and assume all subroutines
10128are reachable with the @code{bl} instruction.
10129This is the default.
10130
10131The addressability of a particular object can be set with the
10132@code{model} attribute.
10133
10134@item -mmodel=medium
10135@opindex mmodel=medium
10136Assume objects may be anywhere in the 32-bit address space (the compiler
10137will generate @code{seth/add3} instructions to load their addresses), and
10138assume all subroutines are reachable with the @code{bl} instruction.
10139
10140@item -mmodel=large
10141@opindex mmodel=large
10142Assume objects may be anywhere in the 32-bit address space (the compiler
10143will generate @code{seth/add3} instructions to load their addresses), and
10144assume subroutines may not be reachable with the @code{bl} instruction
10145(the compiler will generate the much slower @code{seth/add3/jl}
10146instruction sequence).
10147
10148@item -msdata=none
10149@opindex msdata=none
10150Disable use of the small data area. Variables will be put into
10151one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
10152@code{section} attribute has been specified).
10153This is the default.
10154
10155The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
10156Objects may be explicitly put in the small data area with the
10157@code{section} attribute using one of these sections.
10158
10159@item -msdata=sdata
10160@opindex msdata=sdata
10161Put small global and static data in the small data area, but do not
10162generate special code to reference them.
10163
10164@item -msdata=use
10165@opindex msdata=use
10166Put small global and static data in the small data area, and generate
10167special instructions to reference them.
10168
10169@item -G @var{num}
10170@opindex G
10171@cindex smaller data references
10172Put global and static objects less than or equal to @var{num} bytes
10173into the small data or bss sections instead of the normal data or bss
10174sections. The default value of @var{num} is 8.
10175The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
10176for this option to have any effect.
10177
10178All modules should be compiled with the same @option{-G @var{num}} value.
10179Compiling with different values of @var{num} may or may not work; if it
10180doesn't the linker will give an error message---incorrect code will not be
10181generated.
10182
10183@item -mdebug
10184@opindex mdebug
10185Makes the M32R specific code in the compiler display some statistics
10186that might help in debugging programs.
10187
10188@item -malign-loops
10189@opindex malign-loops
10190Align all loops to a 32-byte boundary.
10191
10192@item -mno-align-loops
10193@opindex mno-align-loops
10194Do not enforce a 32-byte alignment for loops. This is the default.
10195
10196@item -missue-rate=@var{number}
10197@opindex missue-rate=@var{number}
10198Issue @var{number} instructions per cycle. @var{number} can only be 1
10199or 2.
10200
10201@item -mbranch-cost=@var{number}
10202@opindex mbranch-cost=@var{number}
10203@var{number} can only be 1 or 2. If it is 1 then branches will be
10204preferred over conditional code, if it is 2, then the opposite will
10205apply.
10206
10207@item -mflush-trap=@var{number}
10208@opindex mflush-trap=@var{number}
10209Specifies the trap number to use to flush the cache. The default is
1021012. Valid numbers are between 0 and 15 inclusive.
10211
10212@item -mno-flush-trap
10213@opindex mno-flush-trap
10214Specifies that the cache cannot be flushed by using a trap.
10215
10216@item -mflush-func=@var{name}
10217@opindex mflush-func=@var{name}
10218Specifies the name of the operating system function to call to flush
10219the cache. The default is @emph{_flush_cache}, but a function call
10220will only be used if a trap is not available.
10221
10222@item -mno-flush-func
10223@opindex mno-flush-func
10224Indicates that there is no OS function for flushing the cache.
10225
10226@end table
10227
10228@node M680x0 Options
10229@subsection M680x0 Options
10230@cindex M680x0 options
10231
10232These are the @samp{-m} options defined for the 68000 series. The default
10233values for these options depends on which style of 68000 was selected when
10234the compiler was configured; the defaults for the most common choices are
10235given below.
10236
10237@table @gcctabopt
10238@item -m68000
10239@itemx -mc68000
10240@opindex m68000
10241@opindex mc68000
10242Generate output for a 68000. This is the default
10243when the compiler is configured for 68000-based systems.
10244
10245Use this option for microcontrollers with a 68000 or EC000 core,
10246including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
10247
10248@item -m68020
10249@itemx -mc68020
10250@opindex m68020
10251@opindex mc68020
10252Generate output for a 68020. This is the default
10253when the compiler is configured for 68020-based systems.
10254
10255@item -m68881
10256@opindex m68881
10257Generate output containing 68881 instructions for floating point.
10258This is the default for most 68020 systems unless @option{--nfp} was
10259specified when the compiler was configured.
10260
10261@item -m68030
10262@opindex m68030
10263Generate output for a 68030. This is the default when the compiler is
10264configured for 68030-based systems.
10265
10266@item -m68040
10267@opindex m68040
10268Generate output for a 68040. This is the default when the compiler is
10269configured for 68040-based systems.
10270
10271This option inhibits the use of 68881/68882 instructions that have to be
10272emulated by software on the 68040. Use this option if your 68040 does not
10273have code to emulate those instructions.
10274
10275@item -m68060
10276@opindex m68060
10277Generate output for a 68060. This is the default when the compiler is
10278configured for 68060-based systems.
10279
10280This option inhibits the use of 68020 and 68881/68882 instructions that
10281have to be emulated by software on the 68060. Use this option if your 68060
10282does not have code to emulate those instructions.
10283
10284@item -mcpu32
10285@opindex mcpu32
10286Generate output for a CPU32. This is the default
10287when the compiler is configured for CPU32-based systems.
10288
10289Use this option for microcontrollers with a
10290CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
1029168336, 68340, 68341, 68349 and 68360.
10292
10293@item -m5200
10294@opindex m5200
10295Generate output for a 520X ``coldfire'' family cpu. This is the default
10296when the compiler is configured for 520X-based systems.
10297
10298Use this option for microcontroller with a 5200 core, including
10299the MCF5202, MCF5203, MCF5204 and MCF5202.
10300
10301@item -mcfv4e
10302@opindex mcfv4e
10303Generate output for a ColdFire V4e family cpu (e.g.@: 547x/548x).
10304This includes use of hardware floating point instructions.
10305
10306@item -m68020-40
10307@opindex m68020-40
10308Generate output for a 68040, without using any of the new instructions.
10309This results in code which can run relatively efficiently on either a
1031068020/68881 or a 68030 or a 68040. The generated code does use the
1031168881 instructions that are emulated on the 68040.
10312
10313@item -m68020-60
10314@opindex m68020-60
10315Generate output for a 68060, without using any of the new instructions.
10316This results in code which can run relatively efficiently on either a
1031768020/68881 or a 68030 or a 68040. The generated code does use the
1031868881 instructions that are emulated on the 68060.
10319
10320@item -msoft-float
10321@opindex msoft-float
10322Generate output containing library calls for floating point.
10323@strong{Warning:} the requisite libraries are not available for all m68k
10324targets. Normally the facilities of the machine's usual C compiler are
10325used, but this can't be done directly in cross-compilation. You must
10326make your own arrangements to provide suitable library functions for
10327cross-compilation. The embedded targets @samp{m68k-*-aout} and
10328@samp{m68k-*-coff} do provide software floating point support.
10329
10330@item -mshort
10331@opindex mshort
10332Consider type @code{int} to be 16 bits wide, like @code{short int}.
10333Additionally, parameters passed on the stack are also aligned to a
1033416-bit boundary even on targets whose API mandates promotion to 32-bit.
10335
10336@item -mnobitfield
10337@opindex mnobitfield
10338Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
10339and @option{-m5200} options imply @w{@option{-mnobitfield}}.
10340
10341@item -mbitfield
10342@opindex mbitfield
10343Do use the bit-field instructions. The @option{-m68020} option implies
10344@option{-mbitfield}. This is the default if you use a configuration
10345designed for a 68020.
10346
10347@item -mrtd
10348@opindex mrtd
10349Use a different function-calling convention, in which functions
10350that take a fixed number of arguments return with the @code{rtd}
10351instruction, which pops their arguments while returning. This
10352saves one instruction in the caller since there is no need to pop
10353the arguments there.
10354
10355This calling convention is incompatible with the one normally
10356used on Unix, so you cannot use it if you need to call libraries
10357compiled with the Unix compiler.
10358
10359Also, you must provide function prototypes for all functions that
10360take variable numbers of arguments (including @code{printf});
10361otherwise incorrect code will be generated for calls to those
10362functions.
10363
10364In addition, seriously incorrect code will result if you call a
10365function with too many arguments. (Normally, extra arguments are
10366harmlessly ignored.)
10367
10368The @code{rtd} instruction is supported by the 68010, 68020, 68030,
1036968040, 68060 and CPU32 processors, but not by the 68000 or 5200.
10370
10371@item -malign-int
10372@itemx -mno-align-int
10373@opindex malign-int
10374@opindex mno-align-int
10375Control whether GCC aligns @code{int}, @code{long}, @code{long long},
10376@code{float}, @code{double}, and @code{long double} variables on a 32-bit
10377boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
10378Aligning variables on 32-bit boundaries produces code that runs somewhat
10379faster on processors with 32-bit busses at the expense of more memory.
10380
10381@strong{Warning:} if you use the @option{-malign-int} switch, GCC will
10382align structures containing the above types differently than
10383most published application binary interface specifications for the m68k.
10384
10385@item -mpcrel
10386@opindex mpcrel
10387Use the pc-relative addressing mode of the 68000 directly, instead of
10388using a global offset table. At present, this option implies @option{-fpic},
10389allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
10390not presently supported with @option{-mpcrel}, though this could be supported for
1039168020 and higher processors.
10392
10393@item -mno-strict-align
10394@itemx -mstrict-align
10395@opindex mno-strict-align
10396@opindex mstrict-align
10397Do not (do) assume that unaligned memory references will be handled by
10398the system.
10399
10400@item -msep-data
10401Generate code that allows the data segment to be located in a different
10402area of memory from the text segment. This allows for execute in place in
10403an environment without virtual memory management. This option implies
10404@option{-fPIC}.
10405
10406@item -mno-sep-data
10407Generate code that assumes that the data segment follows the text segment.
10408This is the default.
10409
10410@item -mid-shared-library
10411Generate code that supports shared libraries via the library ID method.
10412This allows for execute in place and shared libraries in an environment
10413without virtual memory management. This option implies @option{-fPIC}.
10414
10415@item -mno-id-shared-library
10416Generate code that doesn't assume ID based shared libraries are being used.
10417This is the default.
10418
10419@item -mshared-library-id=n
10420Specified the identification number of the ID based shared library being
10421compiled. Specifying a value of 0 will generate more compact code, specifying
10422other values will force the allocation of that number to the current
10423library but is no more space or time efficient than omitting this option.
10424
10425@end table
10426
10427@node M68hc1x Options
10428@subsection M68hc1x Options
10429@cindex M68hc1x options
10430
10431These are the @samp{-m} options defined for the 68hc11 and 68hc12
10432microcontrollers. The default values for these options depends on
10433which style of microcontroller was selected when the compiler was configured;
10434the defaults for the most common choices are given below.
10435
10436@table @gcctabopt
10437@item -m6811
10438@itemx -m68hc11
10439@opindex m6811
10440@opindex m68hc11
10441Generate output for a 68HC11. This is the default
10442when the compiler is configured for 68HC11-based systems.
10443
10444@item -m6812
10445@itemx -m68hc12
10446@opindex m6812
10447@opindex m68hc12
10448Generate output for a 68HC12. This is the default
10449when the compiler is configured for 68HC12-based systems.
10450
10451@item -m68S12
10452@itemx -m68hcs12
10453@opindex m68S12
10454@opindex m68hcs12
10455Generate output for a 68HCS12.
10456
10457@item -mauto-incdec
10458@opindex mauto-incdec
10459Enable the use of 68HC12 pre and post auto-increment and auto-decrement
10460addressing modes.
10461
10462@item -minmax
10463@itemx -nominmax
10464@opindex minmax
10465@opindex mnominmax
10466Enable the use of 68HC12 min and max instructions.
10467
10468@item -mlong-calls
10469@itemx -mno-long-calls
10470@opindex mlong-calls
10471@opindex mno-long-calls
10472Treat all calls as being far away (near). If calls are assumed to be
10473far away, the compiler will use the @code{call} instruction to
10474call a function and the @code{rtc} instruction for returning.
10475
10476@item -mshort
10477@opindex mshort
10478Consider type @code{int} to be 16 bits wide, like @code{short int}.
10479
10480@item -msoft-reg-count=@var{count}
10481@opindex msoft-reg-count
10482Specify the number of pseudo-soft registers which are used for the
10483code generation. The maximum number is 32. Using more pseudo-soft
10484register may or may not result in better code depending on the program.
10485The default is 4 for 68HC11 and 2 for 68HC12.
10486
10487@end table
10488
10489@node MCore Options
10490@subsection MCore Options
10491@cindex MCore options
10492
10493These are the @samp{-m} options defined for the Motorola M*Core
10494processors.
10495
10496@table @gcctabopt
10497
10498@item -mhardlit
10499@itemx -mno-hardlit
10500@opindex mhardlit
10501@opindex mno-hardlit
10502Inline constants into the code stream if it can be done in two
10503instructions or less.
10504
10505@item -mdiv
10506@itemx -mno-div
10507@opindex mdiv
10508@opindex mno-div
10509Use the divide instruction. (Enabled by default).
10510
10511@item -mrelax-immediate
10512@itemx -mno-relax-immediate
10513@opindex mrelax-immediate
10514@opindex mno-relax-immediate
10515Allow arbitrary sized immediates in bit operations.
10516
10517@item -mwide-bitfields
10518@itemx -mno-wide-bitfields
10519@opindex mwide-bitfields
10520@opindex mno-wide-bitfields
10521Always treat bit-fields as int-sized.
10522
10523@item -m4byte-functions
10524@itemx -mno-4byte-functions
10525@opindex m4byte-functions
10526@opindex mno-4byte-functions
10527Force all functions to be aligned to a four byte boundary.
10528
10529@item -mcallgraph-data
10530@itemx -mno-callgraph-data
10531@opindex mcallgraph-data
10532@opindex mno-callgraph-data
10533Emit callgraph information.
10534
10535@item -mslow-bytes
10536@itemx -mno-slow-bytes
10537@opindex mslow-bytes
10538@opindex mno-slow-bytes
10539Prefer word access when reading byte quantities.
10540
10541@item -mlittle-endian
10542@itemx -mbig-endian
10543@opindex mlittle-endian
10544@opindex mbig-endian
10545Generate code for a little endian target.
10546
10547@item -m210
10548@itemx -m340
10549@opindex m210
10550@opindex m340
10551Generate code for the 210 processor.
10552@end table
10553
10554@node MIPS Options
10555@subsection MIPS Options
10556@cindex MIPS options
10557
10558@table @gcctabopt
10559
10560@item -EB
10561@opindex EB
10562Generate big-endian code.
10563
10564@item -EL
10565@opindex EL
10566Generate little-endian code. This is the default for @samp{mips*el-*-*}
10567configurations.
10568
10569@item -march=@var{arch}
10570@opindex march
10571Generate code that will run on @var{arch}, which can be the name of a
10572generic MIPS ISA, or the name of a particular processor.
10573The ISA names are:
10574@samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
10575@samp{mips32}, @samp{mips32r2}, and @samp{mips64}.
10576The processor names are:
10577@samp{4kc}, @samp{4km}, @samp{4kp},
10578@samp{5kc}, @samp{5kf},
10579@samp{20kc},
10580@samp{24k}, @samp{24kc}, @samp{24kf}, @samp{24kx},
10581@samp{m4k},
10582@samp{orion},
10583@samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
10584@samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000},
10585@samp{rm7000}, @samp{rm9000},
10586@samp{sb1},
10587@samp{sr71000},
10588@samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
10589@samp{vr5000}, @samp{vr5400} and @samp{vr5500}.
10590The special value @samp{from-abi} selects the
10591most compatible architecture for the selected ABI (that is,
10592@samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
10593
10594In processor names, a final @samp{000} can be abbreviated as @samp{k}
10595(for example, @samp{-march=r2k}). Prefixes are optional, and
10596@samp{vr} may be written @samp{r}.
10597
10598GCC defines two macros based on the value of this option. The first
10599is @samp{_MIPS_ARCH}, which gives the name of target architecture, as
10600a string. The second has the form @samp{_MIPS_ARCH_@var{foo}},
10601where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@.
10602For example, @samp{-march=r2000} will set @samp{_MIPS_ARCH}
10603to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}.
10604
10605Note that the @samp{_MIPS_ARCH} macro uses the processor names given
10606above. In other words, it will have the full prefix and will not
10607abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},
10608the macro names the resolved architecture (either @samp{"mips1"} or
10609@samp{"mips3"}). It names the default architecture when no
10610@option{-march} option is given.
10611
10612@item -mtune=@var{arch}
10613@opindex mtune
10614Optimize for @var{arch}. Among other things, this option controls
10615the way instructions are scheduled, and the perceived cost of arithmetic
10616operations. The list of @var{arch} values is the same as for
10617@option{-march}.
10618
10619When this option is not used, GCC will optimize for the processor
10620specified by @option{-march}. By using @option{-march} and
10621@option{-mtune} together, it is possible to generate code that will
10622run on a family of processors, but optimize the code for one
10623particular member of that family.
10624
10625@samp{-mtune} defines the macros @samp{_MIPS_TUNE} and
10626@samp{_MIPS_TUNE_@var{foo}}, which work in the same way as the
10627@samp{-march} ones described above.
10628
10629@item -mips1
10630@opindex mips1
10631Equivalent to @samp{-march=mips1}.
10632
10633@item -mips2
10634@opindex mips2
10635Equivalent to @samp{-march=mips2}.
10636
10637@item -mips3
10638@opindex mips3
10639Equivalent to @samp{-march=mips3}.
10640
10641@item -mips4
10642@opindex mips4
10643Equivalent to @samp{-march=mips4}.
10644
10645@item -mips32
10646@opindex mips32
10647Equivalent to @samp{-march=mips32}.
10648
10649@item -mips32r2
10650@opindex mips32r2
10651Equivalent to @samp{-march=mips32r2}.
10652
10653@item -mips64
10654@opindex mips64
10655Equivalent to @samp{-march=mips64}.
10656
10657@item -mips16
10658@itemx -mno-mips16
10659@opindex mips16
10660@opindex mno-mips16
10661Generate (do not generate) MIPS16 code. If GCC is targetting a
10662MIPS32 or MIPS64 architecture, it will make use of the MIPS16e ASE@.
10663
10664@item -mabi=32
10665@itemx -mabi=o64
10666@itemx -mabi=n32
10667@itemx -mabi=64
10668@itemx -mabi=eabi
10669@opindex mabi=32
10670@opindex mabi=o64
10671@opindex mabi=n32
10672@opindex mabi=64
10673@opindex mabi=eabi
10674Generate code for the given ABI@.
10675
10676Note that the EABI has a 32-bit and a 64-bit variant. GCC normally
10677generates 64-bit code when you select a 64-bit architecture, but you
10678can use @option{-mgp32} to get 32-bit code instead.
10679
10680For information about the O64 ABI, see
10681@w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
10682
10683@item -mabicalls
10684@itemx -mno-abicalls
10685@opindex mabicalls
10686@opindex mno-abicalls
10687Generate (do not generate) code that is suitable for SVR4-style
10688dynamic objects. @option{-mabicalls} is the default for SVR4-based
10689systems.
10690
10691@item -mshared
10692@itemx -mno-shared
10693Generate (do not generate) code that is fully position-independent,
10694and that can therefore be linked into shared libraries. This option
10695only affects @option{-mabicalls}.
10696
10697All @option{-mabicalls} code has traditionally been position-independent,
10698regardless of options like @option{-fPIC} and @option{-fpic}. However,
10699as an extension, the GNU toolchain allows executables to use absolute
10700accesses for locally-binding symbols. It can also use shorter GP
10701initialization sequences and generate direct calls to locally-defined
10702functions. This mode is selected by @option{-mno-shared}.
10703
10704@option{-mno-shared} depends on binutils 2.16 or higher and generates
10705objects that can only be linked by the GNU linker. However, the option
10706does not affect the ABI of the final executable; it only affects the ABI
10707of relocatable objects. Using @option{-mno-shared} will generally make
10708executables both smaller and quicker.
10709
10710@option{-mshared} is the default.
10711
10712@item -mxgot
10713@itemx -mno-xgot
10714@opindex mxgot
10715@opindex mno-xgot
10716Lift (do not lift) the usual restrictions on the size of the global
10717offset table.
10718
10719GCC normally uses a single instruction to load values from the GOT@.
10720While this is relatively efficient, it will only work if the GOT
10721is smaller than about 64k. Anything larger will cause the linker
10722to report an error such as:
10723
10724@cindex relocation truncated to fit (MIPS)
10725@smallexample
10726relocation truncated to fit: R_MIPS_GOT16 foobar
10727@end smallexample
10728
10729If this happens, you should recompile your code with @option{-mxgot}.
10730It should then work with very large GOTs, although it will also be
10731less efficient, since it will take three instructions to fetch the
10732value of a global symbol.
10733
10734Note that some linkers can create multiple GOTs. If you have such a
10735linker, you should only need to use @option{-mxgot} when a single object
10736file accesses more than 64k's worth of GOT entries. Very few do.
10737
10738These options have no effect unless GCC is generating position
10739independent code.
10740
10741@item -mgp32
10742@opindex mgp32
10743Assume that general-purpose registers are 32 bits wide.
10744
10745@item -mgp64
10746@opindex mgp64
10747Assume that general-purpose registers are 64 bits wide.
10748
10749@item -mfp32
10750@opindex mfp32
10751Assume that floating-point registers are 32 bits wide.
10752
10753@item -mfp64
10754@opindex mfp64
10755Assume that floating-point registers are 64 bits wide.
10756
10757@item -mhard-float
10758@opindex mhard-float
10759Use floating-point coprocessor instructions.
10760
10761@item -msoft-float
10762@opindex msoft-float
10763Do not use floating-point coprocessor instructions. Implement
10764floating-point calculations using library calls instead.
10765
10766@item -msingle-float
10767@opindex msingle-float
10768Assume that the floating-point coprocessor only supports single-precision
10769operations.
10770
10771@itemx -mdouble-float
10772@opindex mdouble-float
10773Assume that the floating-point coprocessor supports double-precision
10774operations. This is the default.
10775
10776@itemx -mdsp
10777@itemx -mno-dsp
10778@opindex mdsp
10779@opindex mno-dsp
10780Use (do not use) the MIPS DSP ASE. @xref{MIPS DSP Built-in Functions}.
10781
10782@itemx -mpaired-single
10783@itemx -mno-paired-single
10784@opindex mpaired-single
10785@opindex mno-paired-single
10786Use (do not use) paired-single floating-point instructions.
10787@xref{MIPS Paired-Single Support}. This option can only be used
10788when generating 64-bit code and requires hardware floating-point
10789support to be enabled.
10790
10791@itemx -mips3d
10792@itemx -mno-mips3d
10793@opindex mips3d
10794@opindex mno-mips3d
10795Use (do not use) the MIPS-3D ASE@. @xref{MIPS-3D Built-in Functions}.
10796The option @option{-mips3d} implies @option{-mpaired-single}.
10797
10798@item -mlong64
10799@opindex mlong64
10800Force @code{long} types to be 64 bits wide. See @option{-mlong32} for
10801an explanation of the default and the way that the pointer size is
10802determined.
10803
10804@item -mlong32
10805@opindex mlong32
10806Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
10807
10808The default size of @code{int}s, @code{long}s and pointers depends on
10809the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI
10810uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
1081132-bit @code{long}s. Pointers are the same size as @code{long}s,
10812or the same size as integer registers, whichever is smaller.
10813
10814@item -msym32
10815@itemx -mno-sym32
10816@opindex msym32
10817@opindex mno-sym32
10818Assume (do not assume) that all symbols have 32-bit values, regardless
10819of the selected ABI@. This option is useful in combination with
10820@option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
10821to generate shorter and faster references to symbolic addresses.
10822
10823@item -G @var{num}
10824@opindex G
10825@cindex smaller data references (MIPS)
10826@cindex gp-relative references (MIPS)
10827Put global and static items less than or equal to @var{num} bytes into
10828the small data or bss section instead of the normal data or bss section.
10829This allows the data to be accessed using a single instruction.
10830
10831All modules should be compiled with the same @option{-G @var{num}}
10832value.
10833
10834@item -membedded-data
10835@itemx -mno-embedded-data
10836@opindex membedded-data
10837@opindex mno-embedded-data
10838Allocate variables to the read-only data section first if possible, then
10839next in the small data section if possible, otherwise in data. This gives
10840slightly slower code than the default, but reduces the amount of RAM required
10841when executing, and thus may be preferred for some embedded systems.
10842
10843@item -muninit-const-in-rodata
10844@itemx -mno-uninit-const-in-rodata
10845@opindex muninit-const-in-rodata
10846@opindex mno-uninit-const-in-rodata
10847Put uninitialized @code{const} variables in the read-only data section.
10848This option is only meaningful in conjunction with @option{-membedded-data}.
10849
10850@item -msplit-addresses
10851@itemx -mno-split-addresses
10852@opindex msplit-addresses
10853@opindex mno-split-addresses
10854Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
10855relocation operators. This option has been superseded by
10856@option{-mexplicit-relocs} but is retained for backwards compatibility.
10857
10858@item -mexplicit-relocs
10859@itemx -mno-explicit-relocs
10860@opindex mexplicit-relocs
10861@opindex mno-explicit-relocs
10862Use (do not use) assembler relocation operators when dealing with symbolic
10863addresses. The alternative, selected by @option{-mno-explicit-relocs},
10864is to use assembler macros instead.
10865
10866@option{-mexplicit-relocs} is the default if GCC was configured
10867to use an assembler that supports relocation operators.
10868
10869@item -mcheck-zero-division
10870@itemx -mno-check-zero-division
10871@opindex mcheck-zero-division
10872@opindex mno-check-zero-division
10873Trap (do not trap) on integer division by zero. The default is
10874@option{-mcheck-zero-division}.
10875
10876@item -mdivide-traps
10877@itemx -mdivide-breaks
10878@opindex mdivide-traps
10879@opindex mdivide-breaks
10880MIPS systems check for division by zero by generating either a
10881conditional trap or a break instruction. Using traps results in
10882smaller code, but is only supported on MIPS II and later. Also, some
10883versions of the Linux kernel have a bug that prevents trap from
10884generating the proper signal (@code{SIGFPE}). Use @option{-mdivide-traps} to
10885allow conditional traps on architectures that support them and
10886@option{-mdivide-breaks} to force the use of breaks.
10887
10888The default is usually @option{-mdivide-traps}, but this can be
10889overridden at configure time using @option{--with-divide=breaks}.
10890Divide-by-zero checks can be completely disabled using
10891@option{-mno-check-zero-division}.
10892
10893@item -mmemcpy
10894@itemx -mno-memcpy
10895@opindex mmemcpy
10896@opindex mno-memcpy
10897Force (do not force) the use of @code{memcpy()} for non-trivial block
10898moves. The default is @option{-mno-memcpy}, which allows GCC to inline
10899most constant-sized copies.
10900
10901@item -mlong-calls
10902@itemx -mno-long-calls
10903@opindex mlong-calls
10904@opindex mno-long-calls
10905Disable (do not disable) use of the @code{jal} instruction. Calling
10906functions using @code{jal} is more efficient but requires the caller
10907and callee to be in the same 256 megabyte segment.
10908
10909This option has no effect on abicalls code. The default is
10910@option{-mno-long-calls}.
10911
10912@item -mmad
10913@itemx -mno-mad
10914@opindex mmad
10915@opindex mno-mad
10916Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
10917instructions, as provided by the R4650 ISA@.
10918
10919@item -mfused-madd
10920@itemx -mno-fused-madd
10921@opindex mfused-madd
10922@opindex mno-fused-madd
10923Enable (disable) use of the floating point multiply-accumulate
10924instructions, when they are available. The default is
10925@option{-mfused-madd}.
10926
10927When multiply-accumulate instructions are used, the intermediate
10928product is calculated to infinite precision and is not subject to
10929the FCSR Flush to Zero bit. This may be undesirable in some
10930circumstances.
10931
10932@item -nocpp
10933@opindex nocpp
10934Tell the MIPS assembler to not run its preprocessor over user
10935assembler files (with a @samp{.s} suffix) when assembling them.
10936
10937@item -mfix-r4000
10938@itemx -mno-fix-r4000
10939@opindex mfix-r4000
10940@opindex mno-fix-r4000
10941Work around certain R4000 CPU errata:
10942@itemize @minus
10943@item
10944A double-word or a variable shift may give an incorrect result if executed
10945immediately after starting an integer division.
10946@item
10947A double-word or a variable shift may give an incorrect result if executed
10948while an integer multiplication is in progress.
10949@item
10950An integer division may give an incorrect result if started in a delay slot
10951of a taken branch or a jump.
10952@end itemize
10953
10954@item -mfix-r4400
10955@itemx -mno-fix-r4400
10956@opindex mfix-r4400
10957@opindex mno-fix-r4400
10958Work around certain R4400 CPU errata:
10959@itemize @minus
10960@item
10961A double-word or a variable shift may give an incorrect result if executed
10962immediately after starting an integer division.
10963@end itemize
10964
10965@item -mfix-vr4120
10966@itemx -mno-fix-vr4120
10967@opindex mfix-vr4120
10968Work around certain VR4120 errata:
10969@itemize @minus
10970@item
10971@code{dmultu} does not always produce the correct result.
10972@item
10973@code{div} and @code{ddiv} do not always produce the correct result if one
10974of the operands is negative.
10975@end itemize
10976The workarounds for the division errata rely on special functions in
10977@file{libgcc.a}. At present, these functions are only provided by
10978the @code{mips64vr*-elf} configurations.
10979
10980Other VR4120 errata require a nop to be inserted between certain pairs of
10981instructions. These errata are handled by the assembler, not by GCC itself.
10982
10983@item -mfix-vr4130
10984@opindex mfix-vr4130
10985Work around the VR4130 @code{mflo}/@code{mfhi} errata. The
10986workarounds are implemented by the assembler rather than by GCC,
10987although GCC will avoid using @code{mflo} and @code{mfhi} if the
10988VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
10989instructions are available instead.
10990
10991@item -mfix-sb1
10992@itemx -mno-fix-sb1
10993@opindex mfix-sb1
10994Work around certain SB-1 CPU core errata.
10995(This flag currently works around the SB-1 revision 2
10996``F1'' and ``F2'' floating point errata.)
10997
10998@item -mflush-func=@var{func}
10999@itemx -mno-flush-func
11000@opindex mflush-func
11001Specifies the function to call to flush the I and D caches, or to not
11002call any such function. If called, the function must take the same
11003arguments as the common @code{_flush_func()}, that is, the address of the
11004memory range for which the cache is being flushed, the size of the
11005memory range, and the number 3 (to flush both caches). The default
11006depends on the target GCC was configured for, but commonly is either
11007@samp{_flush_func} or @samp{__cpu_flush}.
11008
11009@item -mbranch-likely
11010@itemx -mno-branch-likely
11011@opindex mbranch-likely
11012@opindex mno-branch-likely
11013Enable or disable use of Branch Likely instructions, regardless of the
11014default for the selected architecture. By default, Branch Likely
11015instructions may be generated if they are supported by the selected
11016architecture. An exception is for the MIPS32 and MIPS64 architectures
11017and processors which implement those architectures; for those, Branch
11018Likely instructions will not be generated by default because the MIPS32
11019and MIPS64 architectures specifically deprecate their use.
11020
11021@item -mfp-exceptions
11022@itemx -mno-fp-exceptions
11023@opindex mfp-exceptions
11024Specifies whether FP exceptions are enabled. This affects how we schedule
11025FP instructions for some processors. The default is that FP exceptions are
11026enabled.
11027
11028For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
1102964-bit code, then we can use both FP pipes. Otherwise, we can only use one
11030FP pipe.
11031
11032@item -mvr4130-align
11033@itemx -mno-vr4130-align
11034@opindex mvr4130-align
11035The VR4130 pipeline is two-way superscalar, but can only issue two
11036instructions together if the first one is 8-byte aligned. When this
11037option is enabled, GCC will align pairs of instructions that it
11038thinks should execute in parallel.
11039
11040This option only has an effect when optimizing for the VR4130.
11041It normally makes code faster, but at the expense of making it bigger.
11042It is enabled by default at optimization level @option{-O3}.
11043@end table
11044
11045@node MMIX Options
11046@subsection MMIX Options
11047@cindex MMIX Options
11048
11049These options are defined for the MMIX:
11050
11051@table @gcctabopt
11052@item -mlibfuncs
11053@itemx -mno-libfuncs
11054@opindex mlibfuncs
11055@opindex mno-libfuncs
11056Specify that intrinsic library functions are being compiled, passing all
11057values in registers, no matter the size.
11058
11059@item -mepsilon
11060@itemx -mno-epsilon
11061@opindex mepsilon
11062@opindex mno-epsilon
11063Generate floating-point comparison instructions that compare with respect
11064to the @code{rE} epsilon register.
11065
11066@item -mabi=mmixware
11067@itemx -mabi=gnu
11068@opindex mabi-mmixware
11069@opindex mabi=gnu
11070Generate code that passes function parameters and return values that (in
11071the called function) are seen as registers @code{$0} and up, as opposed to
11072the GNU ABI which uses global registers @code{$231} and up.
11073
11074@item -mzero-extend
11075@itemx -mno-zero-extend
11076@opindex mzero-extend
11077@opindex mno-zero-extend
11078When reading data from memory in sizes shorter than 64 bits, use (do not
11079use) zero-extending load instructions by default, rather than
11080sign-extending ones.
11081
11082@item -mknuthdiv
11083@itemx -mno-knuthdiv
11084@opindex mknuthdiv
11085@opindex mno-knuthdiv
11086Make the result of a division yielding a remainder have the same sign as
11087the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
11088remainder follows the sign of the dividend. Both methods are
11089arithmetically valid, the latter being almost exclusively used.
11090
11091@item -mtoplevel-symbols
11092@itemx -mno-toplevel-symbols
11093@opindex mtoplevel-symbols
11094@opindex mno-toplevel-symbols
11095Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
11096code can be used with the @code{PREFIX} assembly directive.
11097
11098@item -melf
11099@opindex melf
11100Generate an executable in the ELF format, rather than the default
11101@samp{mmo} format used by the @command{mmix} simulator.
11102
11103@item -mbranch-predict
11104@itemx -mno-branch-predict
11105@opindex mbranch-predict
11106@opindex mno-branch-predict
11107Use (do not use) the probable-branch instructions, when static branch
11108prediction indicates a probable branch.
11109
11110@item -mbase-addresses
11111@itemx -mno-base-addresses
11112@opindex mbase-addresses
11113@opindex mno-base-addresses
11114Generate (do not generate) code that uses @emph{base addresses}. Using a
11115base address automatically generates a request (handled by the assembler
11116and the linker) for a constant to be set up in a global register. The
11117register is used for one or more base address requests within the range 0
11118to 255 from the value held in the register. The generally leads to short
11119and fast code, but the number of different data items that can be
11120addressed is limited. This means that a program that uses lots of static
11121data may require @option{-mno-base-addresses}.
11122
11123@item -msingle-exit
11124@itemx -mno-single-exit
11125@opindex msingle-exit
11126@opindex mno-single-exit
11127Force (do not force) generated code to have a single exit point in each
11128function.
11129@end table
11130
11131@node MN10300 Options
11132@subsection MN10300 Options
11133@cindex MN10300 options
11134
11135These @option{-m} options are defined for Matsushita MN10300 architectures:
11136
11137@table @gcctabopt
11138@item -mmult-bug
11139@opindex mmult-bug
11140Generate code to avoid bugs in the multiply instructions for the MN10300
11141processors. This is the default.
11142
11143@item -mno-mult-bug
11144@opindex mno-mult-bug
11145Do not generate code to avoid bugs in the multiply instructions for the
11146MN10300 processors.
11147
11148@item -mam33
11149@opindex mam33
11150Generate code which uses features specific to the AM33 processor.
11151
11152@item -mno-am33
11153@opindex mno-am33
11154Do not generate code which uses features specific to the AM33 processor. This
11155is the default.
11156
11157@item -mreturn-pointer-on-d0
11158@opindex mreturn-pointer-on-d0
11159When generating a function which returns a pointer, return the pointer
11160in both @code{a0} and @code{d0}. Otherwise, the pointer is returned
11161only in a0, and attempts to call such functions without a prototype
11162would result in errors. Note that this option is on by default; use
11163@option{-mno-return-pointer-on-d0} to disable it.
11164
11165@item -mno-crt0
11166@opindex mno-crt0
11167Do not link in the C run-time initialization object file.
11168
11169@item -mrelax
11170@opindex mrelax
11171Indicate to the linker that it should perform a relaxation optimization pass
11172to shorten branches, calls and absolute memory addresses. This option only
11173has an effect when used on the command line for the final link step.
11174
11175This option makes symbolic debugging impossible.
11176@end table
11177
11178@node MT Options
11179@subsection MT Options
11180@cindex MT options
11181
11182These @option{-m} options are defined for Morpho MT architectures:
11183
11184@table @gcctabopt
11185
11186@item -march=@var{cpu-type}
11187@opindex march
11188Generate code that will run on @var{cpu-type}, which is the name of a system
11189representing a certain processor type. Possible values for
11190@var{cpu-type} are @samp{ms1-64-001}, @samp{ms1-16-002},
11191@samp{ms1-16-003} and @samp{ms2}.
11192
11193When this option is not used, the default is @option{-march=ms1-16-002}.
11194
11195@item -mbacc
11196@opindex mbacc
11197Use byte loads and stores when generating code.
11198
11199@item -mno-bacc
11200@opindex mno-bacc
11201Do not use byte loads and stores when generating code.
11202
11203@item -msim
11204@opindex msim
11205Use simulator runtime
11206
11207@item -mno-crt0
11208@opindex mno-crt0
11209Do not link in the C run-time initialization object file
11210@file{crti.o}. Other run-time initialization and termination files
11211such as @file{startup.o} and @file{exit.o} are still included on the
11212linker command line.
11213
11214@end table
11215
11216@node PDP-11 Options
11217@subsection PDP-11 Options
11218@cindex PDP-11 Options
11219
11220These options are defined for the PDP-11:
11221
11222@table @gcctabopt
11223@item -mfpu
11224@opindex mfpu
11225Use hardware FPP floating point. This is the default. (FIS floating
11226point on the PDP-11/40 is not supported.)
11227
11228@item -msoft-float
11229@opindex msoft-float
11230Do not use hardware floating point.
11231
11232@item -mac0
11233@opindex mac0
11234Return floating-point results in ac0 (fr0 in Unix assembler syntax).
11235
11236@item -mno-ac0
11237@opindex mno-ac0
11238Return floating-point results in memory. This is the default.
11239
11240@item -m40
11241@opindex m40
11242Generate code for a PDP-11/40.
11243
11244@item -m45
11245@opindex m45
11246Generate code for a PDP-11/45. This is the default.
11247
11248@item -m10
11249@opindex m10
11250Generate code for a PDP-11/10.
11251
11252@item -mbcopy-builtin
11253@opindex bcopy-builtin
11254Use inline @code{movmemhi} patterns for copying memory. This is the
11255default.
11256
11257@item -mbcopy
11258@opindex mbcopy
11259Do not use inline @code{movmemhi} patterns for copying memory.
11260
11261@item -mint16
11262@itemx -mno-int32
11263@opindex mint16
11264@opindex mno-int32
11265Use 16-bit @code{int}. This is the default.
11266
11267@item -mint32
11268@itemx -mno-int16
11269@opindex mint32
11270@opindex mno-int16
11271Use 32-bit @code{int}.
11272
11273@item -mfloat64
11274@itemx -mno-float32
11275@opindex mfloat64
11276@opindex mno-float32
11277Use 64-bit @code{float}. This is the default.
11278
11279@item -mfloat32
11280@itemx -mno-float64
11281@opindex mfloat32
11282@opindex mno-float64
11283Use 32-bit @code{float}.
11284
11285@item -mabshi
11286@opindex mabshi
11287Use @code{abshi2} pattern. This is the default.
11288
11289@item -mno-abshi
11290@opindex mno-abshi
11291Do not use @code{abshi2} pattern.
11292
11293@item -mbranch-expensive
11294@opindex mbranch-expensive
11295Pretend that branches are expensive. This is for experimenting with
11296code generation only.
11297
11298@item -mbranch-cheap
11299@opindex mbranch-cheap
11300Do not pretend that branches are expensive. This is the default.
11301
11302@item -msplit
11303@opindex msplit
11304Generate code for a system with split I&D@.
11305
11306@item -mno-split
11307@opindex mno-split
11308Generate code for a system without split I&D@. This is the default.
11309
11310@item -munix-asm
11311@opindex munix-asm
11312Use Unix assembler syntax. This is the default when configured for
11313@samp{pdp11-*-bsd}.
11314
11315@item -mdec-asm
11316@opindex mdec-asm
11317Use DEC assembler syntax. This is the default when configured for any
11318PDP-11 target other than @samp{pdp11-*-bsd}.
11319@end table
11320
11321@node PowerPC Options
11322@subsection PowerPC Options
11323@cindex PowerPC options
11324
11325These are listed under @xref{RS/6000 and PowerPC Options}.
11326
11327@node RS/6000 and PowerPC Options
11328@subsection IBM RS/6000 and PowerPC Options
11329@cindex RS/6000 and PowerPC Options
11330@cindex IBM RS/6000 and PowerPC Options
11331
11332These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
11333@table @gcctabopt
11334@item -mpower
11335@itemx -mno-power
11336@itemx -mpower2
11337@itemx -mno-power2
11338@itemx -mpowerpc
11339@itemx -mno-powerpc
11340@itemx -mpowerpc-gpopt
11341@itemx -mno-powerpc-gpopt
11342@itemx -mpowerpc-gfxopt
11343@itemx -mno-powerpc-gfxopt
11344@itemx -mpowerpc64
11345@itemx -mno-powerpc64
11346@itemx -mmfcrf
11347@itemx -mno-mfcrf
11348@itemx -mpopcntb
11349@itemx -mno-popcntb
11350@itemx -mfprnd
11351@itemx -mno-fprnd
11352@opindex mpower
11353@opindex mno-power
11354@opindex mpower2
11355@opindex mno-power2
11356@opindex mpowerpc
11357@opindex mno-powerpc
11358@opindex mpowerpc-gpopt
11359@opindex mno-powerpc-gpopt
11360@opindex mpowerpc-gfxopt
11361@opindex mno-powerpc-gfxopt
11362@opindex mpowerpc64
11363@opindex mno-powerpc64
11364@opindex mmfcrf
11365@opindex mno-mfcrf
11366@opindex mpopcntb
11367@opindex mno-popcntb
11368@opindex mfprnd
11369@opindex mno-fprnd
11370GCC supports two related instruction set architectures for the
11371RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those
11372instructions supported by the @samp{rios} chip set used in the original
11373RS/6000 systems and the @dfn{PowerPC} instruction set is the
11374architecture of the Freescale MPC5xx, MPC6xx, MPC8xx microprocessors, and
11375the IBM 4xx, 6xx, and follow-on microprocessors.
11376
11377Neither architecture is a subset of the other. However there is a
11378large common subset of instructions supported by both. An MQ
11379register is included in processors supporting the POWER architecture.
11380
11381You use these options to specify which instructions are available on the
11382processor you are using. The default value of these options is
11383determined when configuring GCC@. Specifying the
11384@option{-mcpu=@var{cpu_type}} overrides the specification of these
11385options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
11386rather than the options listed above.
11387
11388The @option{-mpower} option allows GCC to generate instructions that
11389are found only in the POWER architecture and to use the MQ register.
11390Specifying @option{-mpower2} implies @option{-power} and also allows GCC
11391to generate instructions that are present in the POWER2 architecture but
11392not the original POWER architecture.
11393
11394The @option{-mpowerpc} option allows GCC to generate instructions that
11395are found only in the 32-bit subset of the PowerPC architecture.
11396Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
11397GCC to use the optional PowerPC architecture instructions in the
11398General Purpose group, including floating-point square root. Specifying
11399@option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
11400use the optional PowerPC architecture instructions in the Graphics
11401group, including floating-point select.
11402
11403The @option{-mmfcrf} option allows GCC to generate the move from
11404condition register field instruction implemented on the POWER4
11405processor and other processors that support the PowerPC V2.01
11406architecture.
11407The @option{-mpopcntb} option allows GCC to generate the popcount and
11408double precision FP reciprocal estimate instruction implemented on the
11409POWER5 processor and other processors that support the PowerPC V2.02
11410architecture.
11411The @option{-mfprnd} option allows GCC to generate the FP round to
11412integer instructions implemented on the POWER5+ processor and other
11413processors that support the PowerPC V2.03 architecture.
11414
11415The @option{-mpowerpc64} option allows GCC to generate the additional
1141664-bit instructions that are found in the full PowerPC64 architecture
11417and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
11418@option{-mno-powerpc64}.
11419
11420If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
11421will use only the instructions in the common subset of both
11422architectures plus some special AIX common-mode calls, and will not use
11423the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
11424permits GCC to use any instruction from either architecture and to
11425allow use of the MQ register; specify this for the Motorola MPC601.
11426
11427@item -mnew-mnemonics
11428@itemx -mold-mnemonics
11429@opindex mnew-mnemonics
11430@opindex mold-mnemonics
11431Select which mnemonics to use in the generated assembler code. With
11432@option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
11433the PowerPC architecture. With @option{-mold-mnemonics} it uses the
11434assembler mnemonics defined for the POWER architecture. Instructions
11435defined in only one architecture have only one mnemonic; GCC uses that
11436mnemonic irrespective of which of these options is specified.
11437
11438GCC defaults to the mnemonics appropriate for the architecture in
11439use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
11440value of these option. Unless you are building a cross-compiler, you
11441should normally not specify either @option{-mnew-mnemonics} or
11442@option{-mold-mnemonics}, but should instead accept the default.
11443
11444@item -mcpu=@var{cpu_type}
11445@opindex mcpu
11446Set architecture type, register usage, choice of mnemonics, and
11447instruction scheduling parameters for machine type @var{cpu_type}.
11448Supported values for @var{cpu_type} are @samp{401}, @samp{403},
11449@samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{505},
11450@samp{601}, @samp{602}, @samp{603}, @samp{603e}, @samp{604},
11451@samp{604e}, @samp{620}, @samp{630}, @samp{740}, @samp{7400},
11452@samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
11453@samp{860}, @samp{970}, @samp{8540}, @samp{ec603e}, @samp{G3},
11454@samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3},
11455@samp{power4}, @samp{power5}, @samp{power5+}, @samp{power6},
11456@samp{common}, @samp{powerpc}, @samp{powerpc64},
11457@samp{rios}, @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64}.
11458
11459@option{-mcpu=common} selects a completely generic processor. Code
11460generated under this option will run on any POWER or PowerPC processor.
11461GCC will use only the instructions in the common subset of both
11462architectures, and will not use the MQ register. GCC assumes a generic
11463processor model for scheduling purposes.
11464
11465@option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
11466@option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
11467PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
11468types, with an appropriate, generic processor model assumed for
11469scheduling purposes.
11470
11471The other options specify a specific processor. Code generated under
11472those options will run best on that processor, and may not run at all on
11473others.
11474
11475The @option{-mcpu} options automatically enable or disable the
11476following options: @option{-maltivec}, @option{-mfprnd},
11477@option{-mhard-float}, @option{-mmfcrf}, @option{-mmultiple},
11478@option{-mnew-mnemonics}, @option{-mpopcntb}, @option{-mpower},
11479@option{-mpower2}, @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
11480@option{-mpowerpc-gfxopt}, @option{-mstring}, @option{-mmulhw}, @option{-mdlmzb}.
11481The particular options
11482set for any particular CPU will vary between compiler versions,
11483depending on what setting seems to produce optimal code for that CPU;
11484it doesn't necessarily reflect the actual hardware's capabilities. If
11485you wish to set an individual option to a particular value, you may
11486specify it after the @option{-mcpu} option, like @samp{-mcpu=970
11487-mno-altivec}.
11488
11489On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
11490not enabled or disabled by the @option{-mcpu} option at present because
11491AIX does not have full support for these options. You may still
11492enable or disable them individually if you're sure it'll work in your
11493environment.
11494
11495@item -mtune=@var{cpu_type}
11496@opindex mtune
11497Set the instruction scheduling parameters for machine type
11498@var{cpu_type}, but do not set the architecture type, register usage, or
11499choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
11500values for @var{cpu_type} are used for @option{-mtune} as for
11501@option{-mcpu}. If both are specified, the code generated will use the
11502architecture, registers, and mnemonics set by @option{-mcpu}, but the
11503scheduling parameters set by @option{-mtune}.
11504
11505@item -mswdiv
11506@itemx -mno-swdiv
11507@opindex mswdiv
11508@opindex mno-swdiv
11509Generate code to compute division as reciprocal estimate and iterative
11510refinement, creating opportunities for increased throughput. This
11511feature requires: optional PowerPC Graphics instruction set for single
11512precision and FRE instruction for double precision, assuming divides
11513cannot generate user-visible traps, and the domain values not include
11514Infinities, denormals or zero denominator.
11515
11516@item -maltivec
11517@itemx -mno-altivec
11518@opindex maltivec
11519@opindex mno-altivec
11520Generate code that uses (does not use) AltiVec instructions, and also
11521enable the use of built-in functions that allow more direct access to
11522the AltiVec instruction set. You may also need to set
11523@option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
11524enhancements.
11525
11526@item -mvrsave
11527@item -mno-vrsave
11528@opindex mvrsave
11529@opindex mno-vrsave
11530Generate VRSAVE instructions when generating AltiVec code.
11531
11532@item -msecure-plt
11533@opindex msecure-plt
11534Generate code that allows ld and ld.so to build executables and shared
11535libraries with non-exec .plt and .got sections. This is a PowerPC
1153632-bit SYSV ABI option.
11537
11538@item -mbss-plt
11539@opindex mbss-plt
11540Generate code that uses a BSS .plt section that ld.so fills in, and
11541requires .plt and .got sections that are both writable and executable.
11542This is a PowerPC 32-bit SYSV ABI option.
11543
11544@item -misel
11545@itemx -mno-isel
11546@opindex misel
11547@opindex mno-isel
11548This switch enables or disables the generation of ISEL instructions.
11549
11550@item -misel=@var{yes/no}
11551This switch has been deprecated. Use @option{-misel} and
11552@option{-mno-isel} instead.
11553
11554@item -mspe
11555@itemx -mno-spe
11556@opindex mspe
11557@opindex mno-spe
11558This switch enables or disables the generation of SPE simd
11559instructions.
11560
11561@item -mspe=@var{yes/no}
11562This option has been deprecated. Use @option{-mspe} and
11563@option{-mno-spe} instead.
11564
11565@item -mfloat-gprs=@var{yes/single/double/no}
11566@itemx -mfloat-gprs
11567@opindex mfloat-gprs
11568This switch enables or disables the generation of floating point
11569operations on the general purpose registers for architectures that
11570support it.
11571
11572The argument @var{yes} or @var{single} enables the use of
11573single-precision floating point operations.
11574
11575The argument @var{double} enables the use of single and
11576double-precision floating point operations.
11577
11578The argument @var{no} disables floating point operations on the
11579general purpose registers.
11580
11581This option is currently only available on the MPC854x.
11582
11583@item -m32
11584@itemx -m64
11585@opindex m32
11586@opindex m64
11587Generate code for 32-bit or 64-bit environments of Darwin and SVR4
11588targets (including GNU/Linux). The 32-bit environment sets int, long
11589and pointer to 32 bits and generates code that runs on any PowerPC
11590variant. The 64-bit environment sets int to 32 bits and long and
11591pointer to 64 bits, and generates code for PowerPC64, as for
11592@option{-mpowerpc64}.
11593
11594@item -mfull-toc
11595@itemx -mno-fp-in-toc
11596@itemx -mno-sum-in-toc
11597@itemx -mminimal-toc
11598@opindex mfull-toc
11599@opindex mno-fp-in-toc
11600@opindex mno-sum-in-toc
11601@opindex mminimal-toc
11602Modify generation of the TOC (Table Of Contents), which is created for
11603every executable file. The @option{-mfull-toc} option is selected by
11604default. In that case, GCC will allocate at least one TOC entry for
11605each unique non-automatic variable reference in your program. GCC
11606will also place floating-point constants in the TOC@. However, only
1160716,384 entries are available in the TOC@.
11608
11609If you receive a linker error message that saying you have overflowed
11610the available TOC space, you can reduce the amount of TOC space used
11611with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
11612@option{-mno-fp-in-toc} prevents GCC from putting floating-point
11613constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
11614generate code to calculate the sum of an address and a constant at
11615run-time instead of putting that sum into the TOC@. You may specify one
11616or both of these options. Each causes GCC to produce very slightly
11617slower and larger code at the expense of conserving TOC space.
11618
11619If you still run out of space in the TOC even when you specify both of
11620these options, specify @option{-mminimal-toc} instead. This option causes
11621GCC to make only one TOC entry for every file. When you specify this
11622option, GCC will produce code that is slower and larger but which
11623uses extremely little TOC space. You may wish to use this option
11624only on files that contain less frequently executed code.
11625
11626@item -maix64
11627@itemx -maix32
11628@opindex maix64
11629@opindex maix32
11630Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
11631@code{long} type, and the infrastructure needed to support them.
11632Specifying @option{-maix64} implies @option{-mpowerpc64} and
11633@option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
11634implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
11635
11636@item -mxl-compat
11637@itemx -mno-xl-compat
11638@opindex mxl-compat
11639@opindex mno-xl-compat
11640Produce code that conforms more closely to IBM XL compiler semantics
11641when using AIX-compatible ABI. Pass floating-point arguments to
11642prototyped functions beyond the register save area (RSA) on the stack
11643in addition to argument FPRs. Do not assume that most significant
11644double in 128-bit long double value is properly rounded when comparing
11645values and converting to double. Use XL symbol names for long double
11646support routines.
11647
11648The AIX calling convention was extended but not initially documented to
11649handle an obscure K&R C case of calling a function that takes the
11650address of its arguments with fewer arguments than declared. IBM XL
11651compilers access floating point arguments which do not fit in the
11652RSA from the stack when a subroutine is compiled without
11653optimization. Because always storing floating-point arguments on the
11654stack is inefficient and rarely needed, this option is not enabled by
11655default and only is necessary when calling subroutines compiled by IBM
11656XL compilers without optimization.
11657
11658@item -mpe
11659@opindex mpe
11660Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
11661application written to use message passing with special startup code to
11662enable the application to run. The system must have PE installed in the
11663standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
11664must be overridden with the @option{-specs=} option to specify the
11665appropriate directory location. The Parallel Environment does not
11666support threads, so the @option{-mpe} option and the @option{-pthread}
11667option are incompatible.
11668
11669@item -malign-natural
11670@itemx -malign-power
11671@opindex malign-natural
11672@opindex malign-power
11673On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
11674@option{-malign-natural} overrides the ABI-defined alignment of larger
11675types, such as floating-point doubles, on their natural size-based boundary.
11676The option @option{-malign-power} instructs GCC to follow the ABI-specified
11677alignment rules. GCC defaults to the standard alignment defined in the ABI@.
11678
11679On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
11680is not supported.
11681
11682@item -msoft-float
11683@itemx -mhard-float
11684@opindex msoft-float
11685@opindex mhard-float
11686Generate code that does not use (uses) the floating-point register set.
11687Software floating point emulation is provided if you use the
11688@option{-msoft-float} option, and pass the option to GCC when linking.
11689
11690@item -mmultiple
11691@itemx -mno-multiple
11692@opindex mmultiple
11693@opindex mno-multiple
11694Generate code that uses (does not use) the load multiple word
11695instructions and the store multiple word instructions. These
11696instructions are generated by default on POWER systems, and not
11697generated on PowerPC systems. Do not use @option{-mmultiple} on little
11698endian PowerPC systems, since those instructions do not work when the
11699processor is in little endian mode. The exceptions are PPC740 and
11700PPC750 which permit the instructions usage in little endian mode.
11701
11702@item -mstring
11703@itemx -mno-string
11704@opindex mstring
11705@opindex mno-string
11706Generate code that uses (does not use) the load string instructions
11707and the store string word instructions to save multiple registers and
11708do small block moves. These instructions are generated by default on
11709POWER systems, and not generated on PowerPC systems. Do not use
11710@option{-mstring} on little endian PowerPC systems, since those
11711instructions do not work when the processor is in little endian mode.
11712The exceptions are PPC740 and PPC750 which permit the instructions
11713usage in little endian mode.
11714
11715@item -mupdate
11716@itemx -mno-update
11717@opindex mupdate
11718@opindex mno-update
11719Generate code that uses (does not use) the load or store instructions
11720that update the base register to the address of the calculated memory
11721location. These instructions are generated by default. If you use
11722@option{-mno-update}, there is a small window between the time that the
11723stack pointer is updated and the address of the previous frame is
11724stored, which means code that walks the stack frame across interrupts or
11725signals may get corrupted data.
11726
11727@item -mfused-madd
11728@itemx -mno-fused-madd
11729@opindex mfused-madd
11730@opindex mno-fused-madd
11731Generate code that uses (does not use) the floating point multiply and
11732accumulate instructions. These instructions are generated by default if
11733hardware floating is used.
11734
11735@item -mmulhw
11736@itemx -mno-mulhw
11737@opindex mmulhw
11738@opindex mno-mulhw
11739Generate code that uses (does not use) the half-word multiply and
11740multiply-accumulate instructions on the IBM 405 and 440 processors.
11741These instructions are generated by default when targetting those
11742processors.
11743
11744@item -mdlmzb
11745@itemx -mno-dlmzb
11746@opindex mdlmzb
11747@opindex mno-dlmzb
11748Generate code that uses (does not use) the string-search @samp{dlmzb}
11749instruction on the IBM 405 and 440 processors. This instruction is
11750generated by default when targetting those processors.
11751
11752@item -mno-bit-align
11753@itemx -mbit-align
11754@opindex mno-bit-align
11755@opindex mbit-align
11756On System V.4 and embedded PowerPC systems do not (do) force structures
11757and unions that contain bit-fields to be aligned to the base type of the
11758bit-field.
11759
11760For example, by default a structure containing nothing but 8
11761@code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
11762boundary and have a size of 4 bytes. By using @option{-mno-bit-align},
11763the structure would be aligned to a 1 byte boundary and be one byte in
11764size.
11765
11766@item -mno-strict-align
11767@itemx -mstrict-align
11768@opindex mno-strict-align
11769@opindex mstrict-align
11770On System V.4 and embedded PowerPC systems do not (do) assume that
11771unaligned memory references will be handled by the system.
11772
11773@item -mrelocatable
11774@itemx -mno-relocatable
11775@opindex mrelocatable
11776@opindex mno-relocatable
11777On embedded PowerPC systems generate code that allows (does not allow)
11778the program to be relocated to a different address at runtime. If you
11779use @option{-mrelocatable} on any module, all objects linked together must
11780be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
11781
11782@item -mrelocatable-lib
11783@itemx -mno-relocatable-lib
11784@opindex mrelocatable-lib
11785@opindex mno-relocatable-lib
11786On embedded PowerPC systems generate code that allows (does not allow)
11787the program to be relocated to a different address at runtime. Modules
11788compiled with @option{-mrelocatable-lib} can be linked with either modules
11789compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
11790with modules compiled with the @option{-mrelocatable} options.
11791
11792@item -mno-toc
11793@itemx -mtoc
11794@opindex mno-toc
11795@opindex mtoc
11796On System V.4 and embedded PowerPC systems do not (do) assume that
11797register 2 contains a pointer to a global area pointing to the addresses
11798used in the program.
11799
11800@item -mlittle
11801@itemx -mlittle-endian
11802@opindex mlittle
11803@opindex mlittle-endian
11804On System V.4 and embedded PowerPC systems compile code for the
11805processor in little endian mode. The @option{-mlittle-endian} option is
11806the same as @option{-mlittle}.
11807
11808@item -mbig
11809@itemx -mbig-endian
11810@opindex mbig
11811@opindex mbig-endian
11812On System V.4 and embedded PowerPC systems compile code for the
11813processor in big endian mode. The @option{-mbig-endian} option is
11814the same as @option{-mbig}.
11815
11816@item -mdynamic-no-pic
11817@opindex mdynamic-no-pic
11818On Darwin and Mac OS X systems, compile code so that it is not
11819relocatable, but that its external references are relocatable. The
11820resulting code is suitable for applications, but not shared
11821libraries.
11822
11823@item -mprioritize-restricted-insns=@var{priority}
11824@opindex mprioritize-restricted-insns
11825This option controls the priority that is assigned to
11826dispatch-slot restricted instructions during the second scheduling
11827pass. The argument @var{priority} takes the value @var{0/1/2} to assign
11828@var{no/highest/second-highest} priority to dispatch slot restricted
11829instructions.
11830
11831@item -msched-costly-dep=@var{dependence_type}
11832@opindex msched-costly-dep
11833This option controls which dependences are considered costly
11834by the target during instruction scheduling. The argument
11835@var{dependence_type} takes one of the following values:
11836@var{no}: no dependence is costly,
11837@var{all}: all dependences are costly,
11838@var{true_store_to_load}: a true dependence from store to load is costly,
11839@var{store_to_load}: any dependence from store to load is costly,
11840@var{number}: any dependence which latency >= @var{number} is costly.
11841
11842@item -minsert-sched-nops=@var{scheme}
11843@opindex minsert-sched-nops
11844This option controls which nop insertion scheme will be used during
11845the second scheduling pass. The argument @var{scheme} takes one of the
11846following values:
11847@var{no}: Don't insert nops.
11848@var{pad}: Pad with nops any dispatch group which has vacant issue slots,
11849according to the scheduler's grouping.
11850@var{regroup_exact}: Insert nops to force costly dependent insns into
11851separate groups. Insert exactly as many nops as needed to force an insn
11852to a new group, according to the estimated processor grouping.
11853@var{number}: Insert nops to force costly dependent insns into
11854separate groups. Insert @var{number} nops to force an insn to a new group.
11855
11856@item -mcall-sysv
11857@opindex mcall-sysv
11858On System V.4 and embedded PowerPC systems compile code using calling
11859conventions that adheres to the March 1995 draft of the System V
11860Application Binary Interface, PowerPC processor supplement. This is the
11861default unless you configured GCC using @samp{powerpc-*-eabiaix}.
11862
11863@item -mcall-sysv-eabi
11864@opindex mcall-sysv-eabi
11865Specify both @option{-mcall-sysv} and @option{-meabi} options.
11866
11867@item -mcall-sysv-noeabi
11868@opindex mcall-sysv-noeabi
11869Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
11870
11871@item -mcall-solaris
11872@opindex mcall-solaris
11873On System V.4 and embedded PowerPC systems compile code for the Solaris
11874operating system.
11875
11876@item -mcall-linux
11877@opindex mcall-linux
11878On System V.4 and embedded PowerPC systems compile code for the
11879Linux-based GNU system.
11880
11881@item -mcall-gnu
11882@opindex mcall-gnu
11883On System V.4 and embedded PowerPC systems compile code for the
11884Hurd-based GNU system.
11885
11886@item -mcall-netbsd
11887@opindex mcall-netbsd
11888On System V.4 and embedded PowerPC systems compile code for the
11889NetBSD operating system.
11890
11891@item -maix-struct-return
11892@opindex maix-struct-return
11893Return all structures in memory (as specified by the AIX ABI)@.
11894
11895@item -msvr4-struct-return
11896@opindex msvr4-struct-return
11897Return structures smaller than 8 bytes in registers (as specified by the
11898SVR4 ABI)@.
11899
11900@item -mabi=@var{abi-type}
11901@opindex mabi
11902Extend the current ABI with a particular extension, or remove such extension.
11903Valid values are @var{altivec}, @var{no-altivec}, @var{spe},
11904@var{no-spe}, @var{ibmlongdouble}, @var{ieeelongdouble}@.
11905
11906@item -mabi=spe
11907@opindex mabi=spe
11908Extend the current ABI with SPE ABI extensions. This does not change
11909the default ABI, instead it adds the SPE ABI extensions to the current
11910ABI@.
11911
11912@item -mabi=no-spe
11913@opindex mabi=no-spe
11914Disable Booke SPE ABI extensions for the current ABI@.
11915
11916@item -mabi=ibmlongdouble
11917@opindex mabi=ibmlongdouble
11918Change the current ABI to use IBM extended precision long double.
11919This is a PowerPC 32-bit SYSV ABI option.
11920
11921@item -mabi=ieeelongdouble
11922@opindex mabi=ieeelongdouble
11923Change the current ABI to use IEEE extended precision long double.
11924This is a PowerPC 32-bit Linux ABI option.
11925
11926@item -mprototype
11927@itemx -mno-prototype
11928@opindex mprototype
11929@opindex mno-prototype
11930On System V.4 and embedded PowerPC systems assume that all calls to
11931variable argument functions are properly prototyped. Otherwise, the
11932compiler must insert an instruction before every non prototyped call to
11933set or clear bit 6 of the condition code register (@var{CR}) to
11934indicate whether floating point values were passed in the floating point
11935registers in case the function takes a variable arguments. With
11936@option{-mprototype}, only calls to prototyped variable argument functions
11937will set or clear the bit.
11938
11939@item -msim
11940@opindex msim
11941On embedded PowerPC systems, assume that the startup module is called
11942@file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
11943@file{libc.a}. This is the default for @samp{powerpc-*-eabisim}.
11944configurations.
11945
11946@item -mmvme
11947@opindex mmvme
11948On embedded PowerPC systems, assume that the startup module is called
11949@file{crt0.o} and the standard C libraries are @file{libmvme.a} and
11950@file{libc.a}.
11951
11952@item -mads
11953@opindex mads
11954On embedded PowerPC systems, assume that the startup module is called
11955@file{crt0.o} and the standard C libraries are @file{libads.a} and
11956@file{libc.a}.
11957
11958@item -myellowknife
11959@opindex myellowknife
11960On embedded PowerPC systems, assume that the startup module is called
11961@file{crt0.o} and the standard C libraries are @file{libyk.a} and
11962@file{libc.a}.
11963
11964@item -mvxworks
11965@opindex mvxworks
11966On System V.4 and embedded PowerPC systems, specify that you are
11967compiling for a VxWorks system.
11968
11969@item -mwindiss
11970@opindex mwindiss
11971Specify that you are compiling for the WindISS simulation environment.
11972
11973@item -memb
11974@opindex memb
11975On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
11976header to indicate that @samp{eabi} extended relocations are used.
11977
11978@item -meabi
11979@itemx -mno-eabi
11980@opindex meabi
11981@opindex mno-eabi
11982On System V.4 and embedded PowerPC systems do (do not) adhere to the
11983Embedded Applications Binary Interface (eabi) which is a set of
11984modifications to the System V.4 specifications. Selecting @option{-meabi}
11985means that the stack is aligned to an 8 byte boundary, a function
11986@code{__eabi} is called to from @code{main} to set up the eabi
11987environment, and the @option{-msdata} option can use both @code{r2} and
11988@code{r13} to point to two separate small data areas. Selecting
11989@option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
11990do not call an initialization function from @code{main}, and the
11991@option{-msdata} option will only use @code{r13} to point to a single
11992small data area. The @option{-meabi} option is on by default if you
11993configured GCC using one of the @samp{powerpc*-*-eabi*} options.
11994
11995@item -msdata=eabi
11996@opindex msdata=eabi
11997On System V.4 and embedded PowerPC systems, put small initialized
11998@code{const} global and static data in the @samp{.sdata2} section, which
11999is pointed to by register @code{r2}. Put small initialized
12000non-@code{const} global and static data in the @samp{.sdata} section,
12001which is pointed to by register @code{r13}. Put small uninitialized
12002global and static data in the @samp{.sbss} section, which is adjacent to
12003the @samp{.sdata} section. The @option{-msdata=eabi} option is
12004incompatible with the @option{-mrelocatable} option. The
12005@option{-msdata=eabi} option also sets the @option{-memb} option.
12006
12007@item -msdata=sysv
12008@opindex msdata=sysv
12009On System V.4 and embedded PowerPC systems, put small global and static
12010data in the @samp{.sdata} section, which is pointed to by register
12011@code{r13}. Put small uninitialized global and static data in the
12012@samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
12013The @option{-msdata=sysv} option is incompatible with the
12014@option{-mrelocatable} option.
12015
12016@item -msdata=default
12017@itemx -msdata
12018@opindex msdata=default
12019@opindex msdata
12020On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
12021compile code the same as @option{-msdata=eabi}, otherwise compile code the
12022same as @option{-msdata=sysv}.
12023
12024@item -msdata-data
12025@opindex msdata-data
12026On System V.4 and embedded PowerPC systems, put small global
12027data in the @samp{.sdata} section. Put small uninitialized global
12028data in the @samp{.sbss} section. Do not use register @code{r13}
12029to address small data however. This is the default behavior unless
12030other @option{-msdata} options are used.
12031
12032@item -msdata=none
12033@itemx -mno-sdata
12034@opindex msdata=none
12035@opindex mno-sdata
12036On embedded PowerPC systems, put all initialized global and static data
12037in the @samp{.data} section, and all uninitialized data in the
12038@samp{.bss} section.
12039
12040@item -G @var{num}
12041@opindex G
12042@cindex smaller data references (PowerPC)
12043@cindex .sdata/.sdata2 references (PowerPC)
12044On embedded PowerPC systems, put global and static items less than or
12045equal to @var{num} bytes into the small data or bss sections instead of
12046the normal data or bss section. By default, @var{num} is 8. The
12047@option{-G @var{num}} switch is also passed to the linker.
12048All modules should be compiled with the same @option{-G @var{num}} value.
12049
12050@item -mregnames
12051@itemx -mno-regnames
12052@opindex mregnames
12053@opindex mno-regnames
12054On System V.4 and embedded PowerPC systems do (do not) emit register
12055names in the assembly language output using symbolic forms.
12056
12057@item -mlongcall
12058@itemx -mno-longcall
12059@opindex mlongcall
12060@opindex mno-longcall
12061By default assume that all calls are far away so that a longer more
12062expensive calling sequence is required. This is required for calls
12063further than 32 megabytes (33,554,432 bytes) from the current location.
12064A short call will be generated if the compiler knows
12065the call cannot be that far away. This setting can be overridden by
12066the @code{shortcall} function attribute, or by @code{#pragma
12067longcall(0)}.
12068
12069Some linkers are capable of detecting out-of-range calls and generating
12070glue code on the fly. On these systems, long calls are unnecessary and
12071generate slower code. As of this writing, the AIX linker can do this,
12072as can the GNU linker for PowerPC/64. It is planned to add this feature
12073to the GNU linker for 32-bit PowerPC systems as well.
12074
12075On Darwin/PPC systems, @code{#pragma longcall} will generate ``jbsr
12076callee, L42'', plus a ``branch island'' (glue code). The two target
12077addresses represent the callee and the ``branch island''. The
12078Darwin/PPC linker will prefer the first address and generate a ``bl
12079callee'' if the PPC ``bl'' instruction will reach the callee directly;
12080otherwise, the linker will generate ``bl L42'' to call the ``branch
12081island''. The ``branch island'' is appended to the body of the
12082calling function; it computes the full 32-bit address of the callee
12083and jumps to it.
12084
12085On Mach-O (Darwin) systems, this option directs the compiler emit to
12086the glue for every direct call, and the Darwin linker decides whether
12087to use or discard it.
12088
12089In the future, we may cause GCC to ignore all longcall specifications
12090when the linker is known to generate glue.
12091
12092@item -pthread
12093@opindex pthread
12094Adds support for multithreading with the @dfn{pthreads} library.
12095This option sets flags for both the preprocessor and linker.
12096
12097@end table
12098
12099@node S/390 and zSeries Options
12100@subsection S/390 and zSeries Options
12101@cindex S/390 and zSeries Options
12102
12103These are the @samp{-m} options defined for the S/390 and zSeries architecture.
12104
12105@table @gcctabopt
12106@item -mhard-float
12107@itemx -msoft-float
12108@opindex mhard-float
12109@opindex msoft-float
12110Use (do not use) the hardware floating-point instructions and registers
12111for floating-point operations. When @option{-msoft-float} is specified,
12112functions in @file{libgcc.a} will be used to perform floating-point
12113operations. When @option{-mhard-float} is specified, the compiler
12114generates IEEE floating-point instructions. This is the default.
12115
12116@item -mlong-double-64
12117@itemx -mlong-double-128
12118@opindex mlong-double-64
12119@opindex mlong-double-128
12120These switches control the size of @code{long double} type. A size
12121of 64bit makes the @code{long double} type equivalent to the @code{double}
12122type. This is the default.
12123
12124@item -mbackchain
12125@itemx -mno-backchain
12126@opindex mbackchain
12127@opindex mno-backchain
12128Store (do not store) the address of the caller's frame as backchain pointer
12129into the callee's stack frame.
12130A backchain may be needed to allow debugging using tools that do not understand
12131DWARF-2 call frame information.
12132When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
12133at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
12134the backchain is placed into the topmost word of the 96/160 byte register
12135save area.
12136
12137In general, code compiled with @option{-mbackchain} is call-compatible with
12138code compiled with @option{-mmo-backchain}; however, use of the backchain
12139for debugging purposes usually requires that the whole binary is built with
12140@option{-mbackchain}. Note that the combination of @option{-mbackchain},
12141@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
12142to build a linux kernel use @option{-msoft-float}.
12143
12144The default is to not maintain the backchain.
12145
12146@item -mpacked-stack
12147@item -mno-packed-stack
12148@opindex mpacked-stack
12149@opindex mno-packed-stack
12150Use (do not use) the packed stack layout. When @option{-mno-packed-stack} is
12151specified, the compiler uses the all fields of the 96/160 byte register save
12152area only for their default purpose; unused fields still take up stack space.
12153When @option{-mpacked-stack} is specified, register save slots are densely
12154packed at the top of the register save area; unused space is reused for other
12155purposes, allowing for more efficient use of the available stack space.
12156However, when @option{-mbackchain} is also in effect, the topmost word of
12157the save area is always used to store the backchain, and the return address
12158register is always saved two words below the backchain.
12159
12160As long as the stack frame backchain is not used, code generated with
12161@option{-mpacked-stack} is call-compatible with code generated with
12162@option{-mno-packed-stack}. Note that some non-FSF releases of GCC 2.95 for
12163S/390 or zSeries generated code that uses the stack frame backchain at run
12164time, not just for debugging purposes. Such code is not call-compatible
12165with code compiled with @option{-mpacked-stack}. Also, note that the
12166combination of @option{-mbackchain},
12167@option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
12168to build a linux kernel use @option{-msoft-float}.
12169
12170The default is to not use the packed stack layout.
12171
12172@item -msmall-exec
12173@itemx -mno-small-exec
12174@opindex msmall-exec
12175@opindex mno-small-exec
12176Generate (or do not generate) code using the @code{bras} instruction
12177to do subroutine calls.
12178This only works reliably if the total executable size does not
12179exceed 64k. The default is to use the @code{basr} instruction instead,
12180which does not have this limitation.
12181
12182@item -m64
12183@itemx -m31
12184@opindex m64
12185@opindex m31
12186When @option{-m31} is specified, generate code compliant to the
12187GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate
12188code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in
12189particular to generate 64-bit instructions. For the @samp{s390}
12190targets, the default is @option{-m31}, while the @samp{s390x}
12191targets default to @option{-m64}.
12192
12193@item -mzarch
12194@itemx -mesa
12195@opindex mzarch
12196@opindex mesa
12197When @option{-mzarch} is specified, generate code using the
12198instructions available on z/Architecture.
12199When @option{-mesa} is specified, generate code using the
12200instructions available on ESA/390. Note that @option{-mesa} is
12201not possible with @option{-m64}.
12202When generating code compliant to the GNU/Linux for S/390 ABI,
12203the default is @option{-mesa}. When generating code compliant
12204to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
12205
12206@item -mmvcle
12207@itemx -mno-mvcle
12208@opindex mmvcle
12209@opindex mno-mvcle
12210Generate (or do not generate) code using the @code{mvcle} instruction
12211to perform block moves. When @option{-mno-mvcle} is specified,
12212use a @code{mvc} loop instead. This is the default unless optimizing for
12213size.
12214
12215@item -mdebug
12216@itemx -mno-debug
12217@opindex mdebug
12218@opindex mno-debug
12219Print (or do not print) additional debug information when compiling.
12220The default is to not print debug information.
12221
12222@item -march=@var{cpu-type}
12223@opindex march
12224Generate code that will run on @var{cpu-type}, which is the name of a system
12225representing a certain processor type. Possible values for
12226@var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, and @samp{z990}.
12227When generating code using the instructions available on z/Architecture,
12228the default is @option{-march=z900}. Otherwise, the default is
12229@option{-march=g5}.
12230
12231@item -mtune=@var{cpu-type}
12232@opindex mtune
12233Tune to @var{cpu-type} everything applicable about the generated code,
12234except for the ABI and the set of available instructions.
12235The list of @var{cpu-type} values is the same as for @option{-march}.
12236The default is the value used for @option{-march}.
12237
12238@item -mtpf-trace
12239@itemx -mno-tpf-trace
12240@opindex mtpf-trace
12241@opindex mno-tpf-trace
12242Generate code that adds (does not add) in TPF OS specific branches to trace
12243routines in the operating system. This option is off by default, even
12244when compiling for the TPF OS@.
12245
12246@item -mfused-madd
12247@itemx -mno-fused-madd
12248@opindex mfused-madd
12249@opindex mno-fused-madd
12250Generate code that uses (does not use) the floating point multiply and
12251accumulate instructions. These instructions are generated by default if
12252hardware floating point is used.
12253
12254@item -mwarn-framesize=@var{framesize}
12255@opindex mwarn-framesize
12256Emit a warning if the current function exceeds the given frame size. Because
12257this is a compile time check it doesn't need to be a real problem when the program
12258runs. It is intended to identify functions which most probably cause
12259a stack overflow. It is useful to be used in an environment with limited stack
12260size e.g.@: the linux kernel.
12261
12262@item -mwarn-dynamicstack
12263@opindex mwarn-dynamicstack
12264Emit a warning if the function calls alloca or uses dynamically
12265sized arrays. This is generally a bad idea with a limited stack size.
12266
12267@item -mstack-guard=@var{stack-guard}
12268@item -mstack-size=@var{stack-size}
12269@opindex mstack-guard
12270@opindex mstack-size
12271These arguments always have to be used in conjunction. If they are present the s390
12272back end emits additional instructions in the function prologue which trigger a trap
12273if the stack size is @var{stack-guard} bytes above the @var{stack-size}
12274(remember that the stack on s390 grows downward). These options are intended to
12275be used to help debugging stack overflow problems. The additionally emitted code
12276causes only little overhead and hence can also be used in production like systems
12277without greater performance degradation. The given values have to be exact
12278powers of 2 and @var{stack-size} has to be greater than @var{stack-guard} without
12279exceeding 64k.
12280In order to be efficient the extra code makes the assumption that the stack starts
12281at an address aligned to the value given by @var{stack-size}.
12282@end table
12283
12284@node Score Options
12285@subsection Score Options
12286@cindex Score Options
12287
12288These options are defined for Score implementations:
12289
12290@table @gcctabopt
12291@item -meb
12292@opindex meb
12293Compile code for big endian mode. This is the default.
12294
12295@item -mel
12296@opindex mel
12297Compile code for little endian mode.
12298
12299@item -mnhwloop
12300@opindex mnhwloop
12301Disable generate bcnz instruction.
12302
12303@item -muls
12304@opindex muls
12305Enable generate unaligned load and store instruction.
12306
12307@item -mmac
12308@opindex mmac
12309Enable the use of multiply-accumulate instructions. Disabled by default.
12310
12311@item -mscore5
12312@opindex mscore5
12313Specify the SCORE5 as the target architecture.
12314
12315@item -mscore5u
12316@opindex mscore5u
12317Specify the SCORE5U of the target architecture.
12318
12319@item -mscore7
12320@opindex mscore7
12321Specify the SCORE7 as the target architecture. This is the default.
12322
12323@item -mscore7d
12324@opindex mscore7d
12325Specify the SCORE7D as the target architecture.
12326@end table
12327
12328@node SH Options
12329@subsection SH Options
12330
12331These @samp{-m} options are defined for the SH implementations:
12332
12333@table @gcctabopt
12334@item -m1
12335@opindex m1
12336Generate code for the SH1.
12337
12338@item -m2
12339@opindex m2
12340Generate code for the SH2.
12341
12342@item -m2e
12343Generate code for the SH2e.
12344
12345@item -m3
12346@opindex m3
12347Generate code for the SH3.
12348
12349@item -m3e
12350@opindex m3e
12351Generate code for the SH3e.
12352
12353@item -m4-nofpu
12354@opindex m4-nofpu
12355Generate code for the SH4 without a floating-point unit.
12356
12357@item -m4-single-only
12358@opindex m4-single-only
12359Generate code for the SH4 with a floating-point unit that only
12360supports single-precision arithmetic.
12361
12362@item -m4-single
12363@opindex m4-single
12364Generate code for the SH4 assuming the floating-point unit is in
12365single-precision mode by default.
12366
12367@item -m4
12368@opindex m4
12369Generate code for the SH4.
12370
12371@item -m4a-nofpu
12372@opindex m4a-nofpu
12373Generate code for the SH4al-dsp, or for a SH4a in such a way that the
12374floating-point unit is not used.
12375
12376@item -m4a-single-only
12377@opindex m4a-single-only
12378Generate code for the SH4a, in such a way that no double-precision
12379floating point operations are used.
12380
12381@item -m4a-single
12382@opindex m4a-single
12383Generate code for the SH4a assuming the floating-point unit is in
12384single-precision mode by default.
12385
12386@item -m4a
12387@opindex m4a
12388Generate code for the SH4a.
12389
12390@item -m4al
12391@opindex m4al
12392Same as @option{-m4a-nofpu}, except that it implicitly passes
12393@option{-dsp} to the assembler. GCC doesn't generate any DSP
12394instructions at the moment.
12395
12396@item -mb
12397@opindex mb
12398Compile code for the processor in big endian mode.
12399
12400@item -ml
12401@opindex ml
12402Compile code for the processor in little endian mode.
12403
12404@item -mdalign
12405@opindex mdalign
12406Align doubles at 64-bit boundaries. Note that this changes the calling
12407conventions, and thus some functions from the standard C library will
12408not work unless you recompile it first with @option{-mdalign}.
12409
12410@item -mrelax
12411@opindex mrelax
12412Shorten some address references at link time, when possible; uses the
12413linker option @option{-relax}.
12414
12415@item -mbigtable
12416@opindex mbigtable
12417Use 32-bit offsets in @code{switch} tables. The default is to use
1241816-bit offsets.
12419
12420@item -mfmovd
12421@opindex mfmovd
12422Enable the use of the instruction @code{fmovd}.
12423
12424@item -mhitachi
12425@opindex mhitachi
12426Comply with the calling conventions defined by Renesas.
12427
12428@item -mrenesas
12429@opindex mhitachi
12430Comply with the calling conventions defined by Renesas.
12431
12432@item -mno-renesas
12433@opindex mhitachi
12434Comply with the calling conventions defined for GCC before the Renesas
12435conventions were available. This option is the default for all
12436targets of the SH toolchain except for @samp{sh-symbianelf}.
12437
12438@item -mnomacsave
12439@opindex mnomacsave
12440Mark the @code{MAC} register as call-clobbered, even if
12441@option{-mhitachi} is given.
12442
12443@item -mieee
12444@opindex mieee
12445Increase IEEE-compliance of floating-point code.
12446At the moment, this is equivalent to @option{-fno-finite-math-only}.
12447When generating 16 bit SH opcodes, getting IEEE-conforming results for
12448comparisons of NANs / infinities incurs extra overhead in every
12449floating point comparison, therefore the default is set to
12450@option{-ffinite-math-only}.
12451
12452@item -misize
12453@opindex misize
12454Dump instruction size and location in the assembly code.
12455
12456@item -mpadstruct
12457@opindex mpadstruct
12458This option is deprecated. It pads structures to multiple of 4 bytes,
12459which is incompatible with the SH ABI@.
12460
12461@item -mspace
12462@opindex mspace
12463Optimize for space instead of speed. Implied by @option{-Os}.
12464
12465@item -mprefergot
12466@opindex mprefergot
12467When generating position-independent code, emit function calls using
12468the Global Offset Table instead of the Procedure Linkage Table.
12469
12470@item -musermode
12471@opindex musermode
12472Generate a library function call to invalidate instruction cache
12473entries, after fixing up a trampoline. This library function call
12474doesn't assume it can write to the whole memory address space. This
12475is the default when the target is @code{sh-*-linux*}.
12476
12477@item -multcost=@var{number}
12478@opindex multcost=@var{number}
12479Set the cost to assume for a multiply insn.
12480
12481@item -mdiv=@var{strategy}
12482@opindex mdiv=@var{strategy}
12483Set the division strategy to use for SHmedia code. @var{strategy} must be
12484one of: call, call2, fp, inv, inv:minlat, inv20u, inv20l, inv:call,
12485inv:call2, inv:fp .
12486"fp" performs the operation in floating point. This has a very high latency,
12487but needs only a few instructions, so it might be a good choice if
12488your code has enough easily exploitable ILP to allow the compiler to
12489schedule the floating point instructions together with other instructions.
12490Division by zero causes a floating point exception.
12491"inv" uses integer operations to calculate the inverse of the divisor,
12492and then multiplies the dividend with the inverse. This strategy allows
12493cse and hoisting of the inverse calculation. Division by zero calculates
12494an unspecified result, but does not trap.
12495"inv:minlat" is a variant of "inv" where if no cse / hoisting opportunities
12496have been found, or if the entire operation has been hoisted to the same
12497place, the last stages of the inverse calculation are intertwined with the
12498final multiply to reduce the overall latency, at the expense of using a few
12499more instructions, and thus offering fewer scheduling opportunities with
12500other code.
12501"call" calls a library function that usually implements the inv:minlat
12502strategy.
12503This gives high code density for m5-*media-nofpu compilations.
12504"call2" uses a different entry point of the same library function, where it
12505assumes that a pointer to a lookup table has already been set up, which
12506exposes the pointer load to cse / code hoisting optimizations.
12507"inv:call", "inv:call2" and "inv:fp" all use the "inv" algorithm for initial
12508code generation, but if the code stays unoptimized, revert to the "call",
12509"call2", or "fp" strategies, respectively. Note that the
12510potentially-trapping side effect of division by zero is carried by a
12511separate instruction, so it is possible that all the integer instructions
12512are hoisted out, but the marker for the side effect stays where it is.
12513A recombination to fp operations or a call is not possible in that case.
12514"inv20u" and "inv20l" are variants of the "inv:minlat" strategy. In the case
12515that the inverse calculation was nor separated from the multiply, they speed
12516up division where the dividend fits into 20 bits (plus sign where applicable),
12517by inserting a test to skip a number of operations in this case; this test
12518slows down the case of larger dividends. inv20u assumes the case of a such
12519a small dividend to be unlikely, and inv20l assumes it to be likely.
12520
12521@item -mdivsi3_libfunc=@var{name}
12522@opindex mdivsi3_libfunc=@var{name}
12523Set the name of the library function used for 32 bit signed division to
12524@var{name}. This only affect the name used in the call and inv:call
12525division strategies, and the compiler will still expect the same
12526sets of input/output/clobbered registers as if this option was not present.
12527
12528@item -madjust-unroll
12529@opindex madjust-unroll
12530Throttle unrolling to avoid thrashing target registers.
12531This option only has an effect if the gcc code base supports the
12532TARGET_ADJUST_UNROLL_MAX target hook.
12533
12534@item -mindexed-addressing
12535@opindex mindexed-addressing
12536Enable the use of the indexed addressing mode for SHmedia32/SHcompact.
12537This is only safe if the hardware and/or OS implement 32 bit wrap-around
12538semantics for the indexed addressing mode. The architecture allows the
12539implementation of processors with 64 bit MMU, which the OS could use to
12540get 32 bit addressing, but since no current hardware implementation supports
12541this or any other way to make the indexed addressing mode safe to use in
12542the 32 bit ABI, the default is -mno-indexed-addressing.
12543
12544@item -mgettrcost=@var{number}
12545@opindex mgettrcost=@var{number}
12546Set the cost assumed for the gettr instruction to @var{number}.
12547The default is 2 if @option{-mpt-fixed} is in effect, 100 otherwise.
12548
12549@item -mpt-fixed
12550@opindex mpt-fixed
12551Assume pt* instructions won't trap. This will generally generate better
12552scheduled code, but is unsafe on current hardware. The current architecture
12553definition says that ptabs and ptrel trap when the target anded with 3 is 3.
12554This has the unintentional effect of making it unsafe to schedule ptabs /
12555ptrel before a branch, or hoist it out of a loop. For example,
12556__do_global_ctors, a part of libgcc that runs constructors at program
12557startup, calls functions in a list which is delimited by -1. With the
12558-mpt-fixed option, the ptabs will be done before testing against -1.
12559That means that all the constructors will be run a bit quicker, but when
12560the loop comes to the end of the list, the program crashes because ptabs
12561loads -1 into a target register. Since this option is unsafe for any
12562hardware implementing the current architecture specification, the default
12563is -mno-pt-fixed. Unless the user specifies a specific cost with
12564@option{-mgettrcost}, -mno-pt-fixed also implies @option{-mgettrcost=100};
12565this deters register allocation using target registers for storing
12566ordinary integers.
12567
12568@item -minvalid-symbols
12569@opindex minvalid-symbols
12570Assume symbols might be invalid. Ordinary function symbols generated by
12571the compiler will always be valid to load with movi/shori/ptabs or
12572movi/shori/ptrel, but with assembler and/or linker tricks it is possible
12573to generate symbols that will cause ptabs / ptrel to trap.
12574This option is only meaningful when @option{-mno-pt-fixed} is in effect.
12575It will then prevent cross-basic-block cse, hoisting and most scheduling
12576of symbol loads. The default is @option{-mno-invalid-symbols}.
12577@end table
12578
12579@node SPARC Options
12580@subsection SPARC Options
12581@cindex SPARC options
12582
12583These @samp{-m} options are supported on the SPARC:
12584
12585@table @gcctabopt
12586@item -mno-app-regs
12587@itemx -mapp-regs
12588@opindex mno-app-regs
12589@opindex mapp-regs
12590Specify @option{-mapp-regs} to generate output using the global registers
125912 through 4, which the SPARC SVR4 ABI reserves for applications. This
12592is the default.
12593
12594To be fully SVR4 ABI compliant at the cost of some performance loss,
12595specify @option{-mno-app-regs}. You should compile libraries and system
12596software with this option.
12597
12598@item -mfpu
12599@itemx -mhard-float
12600@opindex mfpu
12601@opindex mhard-float
12602Generate output containing floating point instructions. This is the
12603default.
12604
12605@item -mno-fpu
12606@itemx -msoft-float
12607@opindex mno-fpu
12608@opindex msoft-float
12609Generate output containing library calls for floating point.
12610@strong{Warning:} the requisite libraries are not available for all SPARC
12611targets. Normally the facilities of the machine's usual C compiler are
12612used, but this cannot be done directly in cross-compilation. You must make
12613your own arrangements to provide suitable library functions for
12614cross-compilation. The embedded targets @samp{sparc-*-aout} and
12615@samp{sparclite-*-*} do provide software floating point support.
12616
12617@option{-msoft-float} changes the calling convention in the output file;
12618therefore, it is only useful if you compile @emph{all} of a program with
12619this option. In particular, you need to compile @file{libgcc.a}, the
12620library that comes with GCC, with @option{-msoft-float} in order for
12621this to work.
12622
12623@item -mhard-quad-float
12624@opindex mhard-quad-float
12625Generate output containing quad-word (long double) floating point
12626instructions.
12627
12628@item -msoft-quad-float
12629@opindex msoft-quad-float
12630Generate output containing library calls for quad-word (long double)
12631floating point instructions. The functions called are those specified
12632in the SPARC ABI@. This is the default.
12633
12634As of this writing, there are no SPARC implementations that have hardware
12635support for the quad-word floating point instructions. They all invoke
12636a trap handler for one of these instructions, and then the trap handler
12637emulates the effect of the instruction. Because of the trap handler overhead,
12638this is much slower than calling the ABI library routines. Thus the
12639@option{-msoft-quad-float} option is the default.
12640
12641@item -mno-unaligned-doubles
12642@itemx -munaligned-doubles
12643@opindex mno-unaligned-doubles
12644@opindex munaligned-doubles
12645Assume that doubles have 8 byte alignment. This is the default.
12646
12647With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
12648alignment only if they are contained in another type, or if they have an
12649absolute address. Otherwise, it assumes they have 4 byte alignment.
12650Specifying this option avoids some rare compatibility problems with code
12651generated by other compilers. It is not the default because it results
12652in a performance loss, especially for floating point code.
12653
12654@item -mno-faster-structs
12655@itemx -mfaster-structs
12656@opindex mno-faster-structs
12657@opindex mfaster-structs
12658With @option{-mfaster-structs}, the compiler assumes that structures
12659should have 8 byte alignment. This enables the use of pairs of
12660@code{ldd} and @code{std} instructions for copies in structure
12661assignment, in place of twice as many @code{ld} and @code{st} pairs.
12662However, the use of this changed alignment directly violates the SPARC
12663ABI@. Thus, it's intended only for use on targets where the developer
12664acknowledges that their resulting code will not be directly in line with
12665the rules of the ABI@.
12666
12667@item -mimpure-text
12668@opindex mimpure-text
12669@option{-mimpure-text}, used in addition to @option{-shared}, tells
12670the compiler to not pass @option{-z text} to the linker when linking a
12671shared object. Using this option, you can link position-dependent
12672code into a shared object.
12673
12674@option{-mimpure-text} suppresses the ``relocations remain against
12675allocatable but non-writable sections'' linker error message.
12676However, the necessary relocations will trigger copy-on-write, and the
12677shared object is not actually shared across processes. Instead of
12678using @option{-mimpure-text}, you should compile all source code with
12679@option{-fpic} or @option{-fPIC}.
12680
12681This option is only available on SunOS and Solaris.
12682
12683@item -mcpu=@var{cpu_type}
12684@opindex mcpu
12685Set the instruction set, register set, and instruction scheduling parameters
12686for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
12687@samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
12688@samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x},
12689@samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc},
12690@samp{ultrasparc3}, and @samp{niagara}.
12691
12692Default instruction scheduling parameters are used for values that select
12693an architecture and not an implementation. These are @samp{v7}, @samp{v8},
12694@samp{sparclite}, @samp{sparclet}, @samp{v9}.
12695
12696Here is a list of each supported architecture and their supported
12697implementations.
12698
12699@smallexample
12700 v7: cypress
12701 v8: supersparc, hypersparc
12702 sparclite: f930, f934, sparclite86x
12703 sparclet: tsc701
12704 v9: ultrasparc, ultrasparc3, niagara
12705@end smallexample
12706
12707By default (unless configured otherwise), GCC generates code for the V7
12708variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler
12709additionally optimizes it for the Cypress CY7C602 chip, as used in the
12710SPARCStation/SPARCServer 3xx series. This is also appropriate for the older
12711SPARCStation 1, 2, IPX etc.
12712
12713With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
12714architecture. The only difference from V7 code is that the compiler emits
12715the integer multiply and integer divide instructions which exist in SPARC-V8
12716but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally
12717optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
127182000 series.
12719
12720With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
12721the SPARC architecture. This adds the integer multiply, integer divide step
12722and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
12723With @option{-mcpu=f930}, the compiler additionally optimizes it for the
12724Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@. With
12725@option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
12726MB86934 chip, which is the more recent SPARClite with FPU@.
12727
12728With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
12729the SPARC architecture. This adds the integer multiply, multiply/accumulate,
12730integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
12731but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally
12732optimizes it for the TEMIC SPARClet chip.
12733
12734With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
12735architecture. This adds 64-bit integer and floating-point move instructions,
127363 additional floating-point condition code registers and conditional move
12737instructions. With @option{-mcpu=ultrasparc}, the compiler additionally
12738optimizes it for the Sun UltraSPARC I/II/IIi chips. With
12739@option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
12740Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips. With
12741@option{-mcpu=niagara}, the compiler additionally optimizes it for
12742Sun UltraSPARC T1 chips.
12743
12744@item -mtune=@var{cpu_type}
12745@opindex mtune
12746Set the instruction scheduling parameters for machine type
12747@var{cpu_type}, but do not set the instruction set or register set that the
12748option @option{-mcpu=@var{cpu_type}} would.
12749
12750The same values for @option{-mcpu=@var{cpu_type}} can be used for
12751@option{-mtune=@var{cpu_type}}, but the only useful values are those
12752that select a particular cpu implementation. Those are @samp{cypress},
12753@samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
12754@samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc},
12755@samp{ultrasparc3}, and @samp{niagara}.
12756
12757@item -mv8plus
12758@itemx -mno-v8plus
12759@opindex mv8plus
12760@opindex mno-v8plus
12761With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@. The
12762difference from the V8 ABI is that the global and out registers are
12763considered 64-bit wide. This is enabled by default on Solaris in 32-bit
12764mode for all SPARC-V9 processors.
12765
12766@item -mvis
12767@itemx -mno-vis
12768@opindex mvis
12769@opindex mno-vis
12770With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
12771Visual Instruction Set extensions. The default is @option{-mno-vis}.
12772@end table
12773
12774These @samp{-m} options are supported in addition to the above
12775on SPARC-V9 processors in 64-bit environments:
12776
12777@table @gcctabopt
12778@item -mlittle-endian
12779@opindex mlittle-endian
12780Generate code for a processor running in little-endian mode. It is only
12781available for a few configurations and most notably not on Solaris and Linux.
12782
12783@item -m32
12784@itemx -m64
12785@opindex m32
12786@opindex m64
12787Generate code for a 32-bit or 64-bit environment.
12788The 32-bit environment sets int, long and pointer to 32 bits.
12789The 64-bit environment sets int to 32 bits and long and pointer
12790to 64 bits.
12791
12792@item -mcmodel=medlow
12793@opindex mcmodel=medlow
12794Generate code for the Medium/Low code model: 64-bit addresses, programs
12795must be linked in the low 32 bits of memory. Programs can be statically
12796or dynamically linked.
12797
12798@item -mcmodel=medmid
12799@opindex mcmodel=medmid
12800Generate code for the Medium/Middle code model: 64-bit addresses, programs
12801must be linked in the low 44 bits of memory, the text and data segments must
12802be less than 2GB in size and the data segment must be located within 2GB of
12803the text segment.
12804
12805@item -mcmodel=medany
12806@opindex mcmodel=medany
12807Generate code for the Medium/Anywhere code model: 64-bit addresses, programs
12808may be linked anywhere in memory, the text and data segments must be less
12809than 2GB in size and the data segment must be located within 2GB of the
12810text segment.
12811
12812@item -mcmodel=embmedany
12813@opindex mcmodel=embmedany
12814Generate code for the Medium/Anywhere code model for embedded systems:
1281564-bit addresses, the text and data segments must be less than 2GB in
12816size, both starting anywhere in memory (determined at link time). The
12817global register %g4 points to the base of the data segment. Programs
12818are statically linked and PIC is not supported.
12819
12820@item -mstack-bias
12821@itemx -mno-stack-bias
12822@opindex mstack-bias
12823@opindex mno-stack-bias
12824With @option{-mstack-bias}, GCC assumes that the stack pointer, and
12825frame pointer if present, are offset by @minus{}2047 which must be added back
12826when making stack frame references. This is the default in 64-bit mode.
12827Otherwise, assume no such offset is present.
12828@end table
12829
12830These switches are supported in addition to the above on Solaris:
12831
12832@table @gcctabopt
12833@item -threads
12834@opindex threads
12835Add support for multithreading using the Solaris threads library. This
12836option sets flags for both the preprocessor and linker. This option does
12837not affect the thread safety of object code produced by the compiler or
12838that of libraries supplied with it.
12839
12840@item -pthreads
12841@opindex pthreads
12842Add support for multithreading using the POSIX threads library. This
12843option sets flags for both the preprocessor and linker. This option does
12844not affect the thread safety of object code produced by the compiler or
12845that of libraries supplied with it.
12846
12847@item -pthread
12848@opindex pthread
12849This is a synonym for @option{-pthreads}.
12850@end table
12851
12852@node System V Options
12853@subsection Options for System V
12854
12855These additional options are available on System V Release 4 for
12856compatibility with other compilers on those systems:
12857
12858@table @gcctabopt
12859@item -G
12860@opindex G
12861Create a shared object.
12862It is recommended that @option{-symbolic} or @option{-shared} be used instead.
12863
12864@item -Qy
12865@opindex Qy
12866Identify the versions of each tool used by the compiler, in a
12867@code{.ident} assembler directive in the output.
12868
12869@item -Qn
12870@opindex Qn
12871Refrain from adding @code{.ident} directives to the output file (this is
12872the default).
12873
12874@item -YP,@var{dirs}
12875@opindex YP
12876Search the directories @var{dirs}, and no others, for libraries
12877specified with @option{-l}.
12878
12879@item -Ym,@var{dir}
12880@opindex Ym
12881Look in the directory @var{dir} to find the M4 preprocessor.
12882The assembler uses this option.
12883@c This is supposed to go with a -Yd for predefined M4 macro files, but
12884@c the generic assembler that comes with Solaris takes just -Ym.
12885@end table
12886
12887@node TMS320C3x/C4x Options
12888@subsection TMS320C3x/C4x Options
12889@cindex TMS320C3x/C4x Options
12890
12891These @samp{-m} options are defined for TMS320C3x/C4x implementations:
12892
12893@table @gcctabopt
12894
12895@item -mcpu=@var{cpu_type}
12896@opindex mcpu
12897Set the instruction set, register set, and instruction scheduling
12898parameters for machine type @var{cpu_type}. Supported values for
12899@var{cpu_type} are @samp{c30}, @samp{c31}, @samp{c32}, @samp{c40}, and
12900@samp{c44}. The default is @samp{c40} to generate code for the
12901TMS320C40.
12902
12903@item -mbig-memory
12904@itemx -mbig
12905@itemx -msmall-memory
12906@itemx -msmall
12907@opindex mbig-memory
12908@opindex mbig
12909@opindex msmall-memory
12910@opindex msmall
12911Generates code for the big or small memory model. The small memory
12912model assumed that all data fits into one 64K word page. At run-time
12913the data page (DP) register must be set to point to the 64K page
12914containing the .bss and .data program sections. The big memory model is
12915the default and requires reloading of the DP register for every direct
12916memory access.
12917
12918@item -mbk
12919@itemx -mno-bk
12920@opindex mbk
12921@opindex mno-bk
12922Allow (disallow) allocation of general integer operands into the block
12923count register BK@.
12924
12925@item -mdb
12926@itemx -mno-db
12927@opindex mdb
12928@opindex mno-db
12929Enable (disable) generation of code using decrement and branch,
12930DBcond(D), instructions. This is enabled by default for the C4x. To be
12931on the safe side, this is disabled for the C3x, since the maximum
12932iteration count on the C3x is @math{2^{23} + 1} (but who iterates loops more than
12933@math{2^{23}} times on the C3x?). Note that GCC will try to reverse a loop so
12934that it can utilize the decrement and branch instruction, but will give
12935up if there is more than one memory reference in the loop. Thus a loop
12936where the loop counter is decremented can generate slightly more
12937efficient code, in cases where the RPTB instruction cannot be utilized.
12938
12939@item -mdp-isr-reload
12940@itemx -mparanoid
12941@opindex mdp-isr-reload
12942@opindex mparanoid
12943Force the DP register to be saved on entry to an interrupt service
12944routine (ISR), reloaded to point to the data section, and restored on
12945exit from the ISR@. This should not be required unless someone has
12946violated the small memory model by modifying the DP register, say within
12947an object library.
12948
12949@item -mmpyi
12950@itemx -mno-mpyi
12951@opindex mmpyi
12952@opindex mno-mpyi
12953For the C3x use the 24-bit MPYI instruction for integer multiplies
12954instead of a library call to guarantee 32-bit results. Note that if one
12955of the operands is a constant, then the multiplication will be performed
12956using shifts and adds. If the @option{-mmpyi} option is not specified for the C3x,
12957then squaring operations are performed inline instead of a library call.
12958
12959@item -mfast-fix
12960@itemx -mno-fast-fix
12961@opindex mfast-fix
12962@opindex mno-fast-fix
12963The C3x/C4x FIX instruction to convert a floating point value to an
12964integer value chooses the nearest integer less than or equal to the
12965floating point value rather than to the nearest integer. Thus if the
12966floating point number is negative, the result will be incorrectly
12967truncated an additional code is necessary to detect and correct this
12968case. This option can be used to disable generation of the additional
12969code required to correct the result.
12970
12971@item -mrptb
12972@itemx -mno-rptb
12973@opindex mrptb
12974@opindex mno-rptb
12975Enable (disable) generation of repeat block sequences using the RPTB
12976instruction for zero overhead looping. The RPTB construct is only used
12977for innermost loops that do not call functions or jump across the loop
12978boundaries. There is no advantage having nested RPTB loops due to the
12979overhead required to save and restore the RC, RS, and RE registers.
12980This is enabled by default with @option{-O2}.
12981
12982@item -mrpts=@var{count}
12983@itemx -mno-rpts
12984@opindex mrpts
12985@opindex mno-rpts
12986Enable (disable) the use of the single instruction repeat instruction
12987RPTS@. If a repeat block contains a single instruction, and the loop
12988count can be guaranteed to be less than the value @var{count}, GCC will
12989emit a RPTS instruction instead of a RPTB@. If no value is specified,
12990then a RPTS will be emitted even if the loop count cannot be determined
12991at compile time. Note that the repeated instruction following RPTS does
12992not have to be reloaded from memory each iteration, thus freeing up the
12993CPU buses for operands. However, since interrupts are blocked by this
12994instruction, it is disabled by default.
12995
12996@item -mloop-unsigned
12997@itemx -mno-loop-unsigned
12998@opindex mloop-unsigned
12999@opindex mno-loop-unsigned
13000The maximum iteration count when using RPTS and RPTB (and DB on the C40)
13001is @math{2^{31} + 1} since these instructions test if the iteration count is
13002negative to terminate the loop. If the iteration count is unsigned
13003there is a possibility than the @math{2^{31} + 1} maximum iteration count may be
13004exceeded. This switch allows an unsigned iteration count.
13005
13006@item -mti
13007@opindex mti
13008Try to emit an assembler syntax that the TI assembler (asm30) is happy
13009with. This also enforces compatibility with the API employed by the TI
13010C3x C compiler. For example, long doubles are passed as structures
13011rather than in floating point registers.
13012
13013@item -mregparm
13014@itemx -mmemparm
13015@opindex mregparm
13016@opindex mmemparm
13017Generate code that uses registers (stack) for passing arguments to functions.
13018By default, arguments are passed in registers where possible rather
13019than by pushing arguments on to the stack.
13020
13021@item -mparallel-insns
13022@itemx -mno-parallel-insns
13023@opindex mparallel-insns
13024@opindex mno-parallel-insns
13025Allow the generation of parallel instructions. This is enabled by
13026default with @option{-O2}.
13027
13028@item -mparallel-mpy
13029@itemx -mno-parallel-mpy
13030@opindex mparallel-mpy
13031@opindex mno-parallel-mpy
13032Allow the generation of MPY||ADD and MPY||SUB parallel instructions,
13033provided @option{-mparallel-insns} is also specified. These instructions have
13034tight register constraints which can pessimize the code generation
13035of large functions.
13036
13037@end table
13038
13039@node V850 Options
13040@subsection V850 Options
13041@cindex V850 Options
13042
13043These @samp{-m} options are defined for V850 implementations:
13044
13045@table @gcctabopt
13046@item -mlong-calls
13047@itemx -mno-long-calls
13048@opindex mlong-calls
13049@opindex mno-long-calls
13050Treat all calls as being far away (near). If calls are assumed to be
13051far away, the compiler will always load the functions address up into a
13052register, and call indirect through the pointer.
13053
13054@item -mno-ep
13055@itemx -mep
13056@opindex mno-ep
13057@opindex mep
13058Do not optimize (do optimize) basic blocks that use the same index
13059pointer 4 or more times to copy pointer into the @code{ep} register, and
13060use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
13061option is on by default if you optimize.
13062
13063@item -mno-prolog-function
13064@itemx -mprolog-function
13065@opindex mno-prolog-function
13066@opindex mprolog-function
13067Do not use (do use) external functions to save and restore registers
13068at the prologue and epilogue of a function. The external functions
13069are slower, but use less code space if more than one function saves
13070the same number of registers. The @option{-mprolog-function} option
13071is on by default if you optimize.
13072
13073@item -mspace
13074@opindex mspace
13075Try to make the code as small as possible. At present, this just turns
13076on the @option{-mep} and @option{-mprolog-function} options.
13077
13078@item -mtda=@var{n}
13079@opindex mtda
13080Put static or global variables whose size is @var{n} bytes or less into
13081the tiny data area that register @code{ep} points to. The tiny data
13082area can hold up to 256 bytes in total (128 bytes for byte references).
13083
13084@item -msda=@var{n}
13085@opindex msda
13086Put static or global variables whose size is @var{n} bytes or less into
13087the small data area that register @code{gp} points to. The small data
13088area can hold up to 64 kilobytes.
13089
13090@item -mzda=@var{n}
13091@opindex mzda
13092Put static or global variables whose size is @var{n} bytes or less into
13093the first 32 kilobytes of memory.
13094
13095@item -mv850
13096@opindex mv850
13097Specify that the target processor is the V850.
13098
13099@item -mbig-switch
13100@opindex mbig-switch
13101Generate code suitable for big switch tables. Use this option only if
13102the assembler/linker complain about out of range branches within a switch
13103table.
13104
13105@item -mapp-regs
13106@opindex mapp-regs
13107This option will cause r2 and r5 to be used in the code generated by
13108the compiler. This setting is the default.
13109
13110@item -mno-app-regs
13111@opindex mno-app-regs
13112This option will cause r2 and r5 to be treated as fixed registers.
13113
13114@item -mv850e1
13115@opindex mv850e1
13116Specify that the target processor is the V850E1. The preprocessor
13117constants @samp{__v850e1__} and @samp{__v850e__} will be defined if
13118this option is used.
13119
13120@item -mv850e
13121@opindex mv850e
13122Specify that the target processor is the V850E@. The preprocessor
13123constant @samp{__v850e__} will be defined if this option is used.
13124
13125If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
13126are defined then a default target processor will be chosen and the
13127relevant @samp{__v850*__} preprocessor constant will be defined.
13128
13129The preprocessor constants @samp{__v850} and @samp{__v851__} are always
13130defined, regardless of which processor variant is the target.
13131
13132@item -mdisable-callt
13133@opindex mdisable-callt
13134This option will suppress generation of the CALLT instruction for the
13135v850e and v850e1 flavors of the v850 architecture. The default is
13136@option{-mno-disable-callt} which allows the CALLT instruction to be used.
13137
13138@end table
13139
13140@node VAX Options
13141@subsection VAX Options
13142@cindex VAX options
13143
13144These @samp{-m} options are defined for the VAX:
13145
13146@table @gcctabopt
13147@item -munix
13148@opindex munix
13149Do not output certain jump instructions (@code{aobleq} and so on)
13150that the Unix assembler for the VAX cannot handle across long
13151ranges.
13152
13153@item -mgnu
13154@opindex mgnu
13155Do output those jump instructions, on the assumption that you
13156will assemble with the GNU assembler.
13157
13158@item -mg
13159@opindex mg
13160Output code for g-format floating point numbers instead of d-format.
13161@end table
13162
13163@node x86-64 Options
13164@subsection x86-64 Options
13165@cindex x86-64 options
13166
13167These are listed under @xref{i386 and x86-64 Options}.
13168
13169@node Xstormy16 Options
13170@subsection Xstormy16 Options
13171@cindex Xstormy16 Options
13172
13173These options are defined for Xstormy16:
13174
13175@table @gcctabopt
13176@item -msim
13177@opindex msim
13178Choose startup files and linker script suitable for the simulator.
13179@end table
13180
13181@node Xtensa Options
13182@subsection Xtensa Options
13183@cindex Xtensa Options
13184
13185These options are supported for Xtensa targets:
13186
13187@table @gcctabopt
13188@item -mconst16
13189@itemx -mno-const16
13190@opindex mconst16
13191@opindex mno-const16
13192Enable or disable use of @code{CONST16} instructions for loading
13193constant values. The @code{CONST16} instruction is currently not a
13194standard option from Tensilica. When enabled, @code{CONST16}
13195instructions are always used in place of the standard @code{L32R}
13196instructions. The use of @code{CONST16} is enabled by default only if
13197the @code{L32R} instruction is not available.
13198
13199@item -mfused-madd
13200@itemx -mno-fused-madd
13201@opindex mfused-madd
13202@opindex mno-fused-madd
13203Enable or disable use of fused multiply/add and multiply/subtract
13204instructions in the floating-point option. This has no effect if the
13205floating-point option is not also enabled. Disabling fused multiply/add
13206and multiply/subtract instructions forces the compiler to use separate
13207instructions for the multiply and add/subtract operations. This may be
13208desirable in some cases where strict IEEE 754-compliant results are
13209required: the fused multiply add/subtract instructions do not round the
13210intermediate result, thereby producing results with @emph{more} bits of
13211precision than specified by the IEEE standard. Disabling fused multiply
13212add/subtract instructions also ensures that the program output is not
13213sensitive to the compiler's ability to combine multiply and add/subtract
13214operations.
13215
13216@item -mtext-section-literals
13217@itemx -mno-text-section-literals
13218@opindex mtext-section-literals
13219@opindex mno-text-section-literals
13220Control the treatment of literal pools. The default is
13221@option{-mno-text-section-literals}, which places literals in a separate
13222section in the output file. This allows the literal pool to be placed
13223in a data RAM/ROM, and it also allows the linker to combine literal
13224pools from separate object files to remove redundant literals and
13225improve code size. With @option{-mtext-section-literals}, the literals
13226are interspersed in the text section in order to keep them as close as
13227possible to their references. This may be necessary for large assembly
13228files.
13229
13230@item -mtarget-align
13231@itemx -mno-target-align
13232@opindex mtarget-align
13233@opindex mno-target-align
13234When this option is enabled, GCC instructs the assembler to
13235automatically align instructions to reduce branch penalties at the
13236expense of some code density. The assembler attempts to widen density
13237instructions to align branch targets and the instructions following call
13238instructions. If there are not enough preceding safe density
13239instructions to align a target, no widening will be performed. The
13240default is @option{-mtarget-align}. These options do not affect the
13241treatment of auto-aligned instructions like @code{LOOP}, which the
13242assembler will always align, either by widening density instructions or
13243by inserting no-op instructions.
13244
13245@item -mlongcalls
13246@itemx -mno-longcalls
13247@opindex mlongcalls
13248@opindex mno-longcalls
13249When this option is enabled, GCC instructs the assembler to translate
13250direct calls to indirect calls unless it can determine that the target
13251of a direct call is in the range allowed by the call instruction. This
13252translation typically occurs for calls to functions in other source
13253files. Specifically, the assembler translates a direct @code{CALL}
13254instruction into an @code{L32R} followed by a @code{CALLX} instruction.
13255The default is @option{-mno-longcalls}. This option should be used in
13256programs where the call target can potentially be out of range. This
13257option is implemented in the assembler, not the compiler, so the
13258assembly code generated by GCC will still show direct call
13259instructions---look at the disassembled object code to see the actual
13260instructions. Note that the assembler will use an indirect call for
13261every cross-file call, not just those that really will be out of range.
13262@end table
13263
13264@node zSeries Options
13265@subsection zSeries Options
13266@cindex zSeries options
13267
13268These are listed under @xref{S/390 and zSeries Options}.
13269
13270@node Code Gen Options
13271@section Options for Code Generation Conventions
13272@cindex code generation conventions
13273@cindex options, code generation
13274@cindex run-time options
13275
13276These machine-independent options control the interface conventions
13277used in code generation.
13278
13279Most of them have both positive and negative forms; the negative form
13280of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
13281one of the forms is listed---the one which is not the default. You
13282can figure out the other form by either removing @samp{no-} or adding
13283it.
13284
13285@table @gcctabopt
13286@item -fbounds-check
13287@opindex fbounds-check
13288For front-ends that support it, generate additional code to check that
13289indices used to access arrays are within the declared range. This is
13290currently only supported by the Java and Fortran front-ends, where
13291this option defaults to true and false respectively.
13292
13293@item -ftrapv
13294@opindex ftrapv
13295This option generates traps for signed overflow on addition, subtraction,
13296multiplication operations.
13297
13298@item -fwrapv
13299@opindex fwrapv
13300This option instructs the compiler to assume that signed arithmetic
13301overflow of addition, subtraction and multiplication wraps around
13302using twos-complement representation. This flag enables some optimizations
13303and disables others. This option is enabled by default for the Java
13304front-end, as required by the Java language specification.
13305
13306@item -fexceptions
13307@opindex fexceptions
13308Enable exception handling. Generates extra code needed to propagate
13309exceptions. For some targets, this implies GCC will generate frame
13310unwind information for all functions, which can produce significant data
13311size overhead, although it does not affect execution. If you do not
13312specify this option, GCC will enable it by default for languages like
13313C++ which normally require exception handling, and disable it for
13314languages like C that do not normally require it. However, you may need
13315to enable this option when compiling C code that needs to interoperate
13316properly with exception handlers written in C++. You may also wish to
13317disable this option if you are compiling older C++ programs that don't
13318use exception handling.
13319
13320@item -fnon-call-exceptions
13321@opindex fnon-call-exceptions
13322Generate code that allows trapping instructions to throw exceptions.
13323Note that this requires platform-specific runtime support that does
13324not exist everywhere. Moreover, it only allows @emph{trapping}
13325instructions to throw exceptions, i.e.@: memory references or floating
13326point instructions. It does not allow exceptions to be thrown from
13327arbitrary signal handlers such as @code{SIGALRM}.
13328
13329@item -funwind-tables
13330@opindex funwind-tables
13331Similar to @option{-fexceptions}, except that it will just generate any needed
13332static data, but will not affect the generated code in any other way.
13333You will normally not enable this option; instead, a language processor
13334that needs this handling would enable it on your behalf.
13335
13336@item -fasynchronous-unwind-tables
13337@opindex fasynchronous-unwind-tables
13338Generate unwind table in dwarf2 format, if supported by target machine. The
13339table is exact at each instruction boundary, so it can be used for stack
13340unwinding from asynchronous events (such as debugger or garbage collector).
13341
13342@item -fpcc-struct-return
13343@opindex fpcc-struct-return
13344Return ``short'' @code{struct} and @code{union} values in memory like
13345longer ones, rather than in registers. This convention is less
13346efficient, but it has the advantage of allowing intercallability between
13347GCC-compiled files and files compiled with other compilers, particularly
13348the Portable C Compiler (pcc).
13349
13350The precise convention for returning structures in memory depends
13351on the target configuration macros.
13352
13353Short structures and unions are those whose size and alignment match
13354that of some integer type.
13355
13356@strong{Warning:} code compiled with the @option{-fpcc-struct-return}
13357switch is not binary compatible with code compiled with the
13358@option{-freg-struct-return} switch.
13359Use it to conform to a non-default application binary interface.
13360
13361@item -freg-struct-return
13362@opindex freg-struct-return
13363Return @code{struct} and @code{union} values in registers when possible.
13364This is more efficient for small structures than
13365@option{-fpcc-struct-return}.
13366
13367If you specify neither @option{-fpcc-struct-return} nor
13368@option{-freg-struct-return}, GCC defaults to whichever convention is
13369standard for the target. If there is no standard convention, GCC
13370defaults to @option{-fpcc-struct-return}, except on targets where GCC is
13371the principal compiler. In those cases, we can choose the standard, and
13372we chose the more efficient register return alternative.
13373
13374@strong{Warning:} code compiled with the @option{-freg-struct-return}
13375switch is not binary compatible with code compiled with the
13376@option{-fpcc-struct-return} switch.
13377Use it to conform to a non-default application binary interface.
13378
13379@item -fshort-enums
13380@opindex fshort-enums
13381Allocate to an @code{enum} type only as many bytes as it needs for the
13382declared range of possible values. Specifically, the @code{enum} type
13383will be equivalent to the smallest integer type which has enough room.
13384
13385@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
13386code that is not binary compatible with code generated without that switch.
13387Use it to conform to a non-default application binary interface.
13388
13389@item -fshort-double
13390@opindex fshort-double
13391Use the same size for @code{double} as for @code{float}.
13392
13393@strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
13394code that is not binary compatible with code generated without that switch.
13395Use it to conform to a non-default application binary interface.
13396
13397@item -fshort-wchar
13398@opindex fshort-wchar
13399Override the underlying type for @samp{wchar_t} to be @samp{short
13400unsigned int} instead of the default for the target. This option is
13401useful for building programs to run under WINE@.
13402
13403@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
13404code that is not binary compatible with code generated without that switch.
13405Use it to conform to a non-default application binary interface.
13406
13407@item -fno-common
13408@opindex fno-common
13409In C, allocate even uninitialized global variables in the data section of the
13410object file, rather than generating them as common blocks. This has the
13411effect that if the same variable is declared (without @code{extern}) in
13412two different compilations, you will get an error when you link them.
13413The only reason this might be useful is if you wish to verify that the
13414program will work on other systems which always work this way.
13415
13416@item -fno-ident
13417@opindex fno-ident
13418Ignore the @samp{#ident} directive.
13419
13420@item -finhibit-size-directive
13421@opindex finhibit-size-directive
13422Don't output a @code{.size} assembler directive, or anything else that
13423would cause trouble if the function is split in the middle, and the
13424two halves are placed at locations far apart in memory. This option is
13425used when compiling @file{crtstuff.c}; you should not need to use it
13426for anything else.
13427
13428@item -fverbose-asm
13429@opindex fverbose-asm
13430Put extra commentary information in the generated assembly code to
13431make it more readable. This option is generally only of use to those
13432who actually need to read the generated assembly code (perhaps while
13433debugging the compiler itself).
13434
13435@option{-fno-verbose-asm}, the default, causes the
13436extra information to be omitted and is useful when comparing two assembler
13437files.
13438
13439@item -fpic
13440@opindex fpic
13441@cindex global offset table
13442@cindex PIC
13443Generate position-independent code (PIC) suitable for use in a shared
13444library, if supported for the target machine. Such code accesses all
13445constant addresses through a global offset table (GOT)@. The dynamic
13446loader resolves the GOT entries when the program starts (the dynamic
13447loader is not part of GCC; it is part of the operating system). If
13448the GOT size for the linked executable exceeds a machine-specific
13449maximum size, you get an error message from the linker indicating that
13450@option{-fpic} does not work; in that case, recompile with @option{-fPIC}
13451instead. (These maximums are 8k on the SPARC and 32k
13452on the m68k and RS/6000. The 386 has no such limit.)
13453
13454Position-independent code requires special support, and therefore works
13455only on certain machines. For the 386, GCC supports PIC for System V
13456but not for the Sun 386i. Code generated for the IBM RS/6000 is always
13457position-independent.
13458
13459When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13460are defined to 1.
13461
13462@item -fPIC
13463@opindex fPIC
13464If supported for the target machine, emit position-independent code,
13465suitable for dynamic linking and avoiding any limit on the size of the
13466global offset table. This option makes a difference on the m68k,
13467PowerPC and SPARC@.
13468
13469Position-independent code requires special support, and therefore works
13470only on certain machines.
13471
13472When this flag is set, the macros @code{__pic__} and @code{__PIC__}
13473are defined to 2.
13474
13475@item -fpie
13476@itemx -fPIE
13477@opindex fpie
13478@opindex fPIE
13479These options are similar to @option{-fpic} and @option{-fPIC}, but
13480generated position independent code can be only linked into executables.
13481Usually these options are used when @option{-pie} GCC option will be
13482used during linking.
13483
13484@item -fno-jump-tables
13485@opindex fno-jump-tables
13486Do not use jump tables for switch statements even where it would be
13487more efficient than other code generation strategies. This option is
13488of use in conjunction with @option{-fpic} or @option{-fPIC} for
13489building code which forms part of a dynamic linker and cannot
13490reference the address of a jump table. On some targets, jump tables
13491do not require a GOT and this option is not needed.
13492
13493@item -ffixed-@var{reg}
13494@opindex ffixed
13495Treat the register named @var{reg} as a fixed register; generated code
13496should never refer to it (except perhaps as a stack pointer, frame
13497pointer or in some other fixed role).
13498
13499@var{reg} must be the name of a register. The register names accepted
13500are machine-specific and are defined in the @code{REGISTER_NAMES}
13501macro in the machine description macro file.
13502
13503This flag does not have a negative form, because it specifies a
13504three-way choice.
13505
13506@item -fcall-used-@var{reg}
13507@opindex fcall-used
13508Treat the register named @var{reg} as an allocable register that is
13509clobbered by function calls. It may be allocated for temporaries or
13510variables that do not live across a call. Functions compiled this way
13511will not save and restore the register @var{reg}.
13512
13513It is an error to used this flag with the frame pointer or stack pointer.
13514Use of this flag for other registers that have fixed pervasive roles in
13515the machine's execution model will produce disastrous results.
13516
13517This flag does not have a negative form, because it specifies a
13518three-way choice.
13519
13520@item -fcall-saved-@var{reg}
13521@opindex fcall-saved
13522Treat the register named @var{reg} as an allocable register saved by
13523functions. It may be allocated even for temporaries or variables that
13524live across a call. Functions compiled this way will save and restore
13525the register @var{reg} if they use it.
13526
13527It is an error to used this flag with the frame pointer or stack pointer.
13528Use of this flag for other registers that have fixed pervasive roles in
13529the machine's execution model will produce disastrous results.
13530
13531A different sort of disaster will result from the use of this flag for
13532a register in which function values may be returned.
13533
13534This flag does not have a negative form, because it specifies a
13535three-way choice.
13536
13537@item -fpack-struct[=@var{n}]
13538@opindex fpack-struct
13539Without a value specified, pack all structure members together without
13540holes. When a value is specified (which must be a small power of two), pack
13541structure members according to this value, representing the maximum
13542alignment (that is, objects with default alignment requirements larger than
13543this will be output potentially unaligned at the next fitting location.
13544
13545@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
13546code that is not binary compatible with code generated without that switch.
13547Additionally, it makes the code suboptimal.
13548Use it to conform to a non-default application binary interface.
13549
13550@item -finstrument-functions
13551@opindex finstrument-functions
13552Generate instrumentation calls for entry and exit to functions. Just
13553after function entry and just before function exit, the following
13554profiling functions will be called with the address of the current
13555function and its call site. (On some platforms,
13556@code{__builtin_return_address} does not work beyond the current
13557function, so the call site information may not be available to the
13558profiling functions otherwise.)
13559
13560@smallexample
13561void __cyg_profile_func_enter (void *this_fn,
13562 void *call_site);
13563void __cyg_profile_func_exit (void *this_fn,
13564 void *call_site);
13565@end smallexample
13566
13567The first argument is the address of the start of the current function,
13568which may be looked up exactly in the symbol table.
13569
13570This instrumentation is also done for functions expanded inline in other
13571functions. The profiling calls will indicate where, conceptually, the
13572inline function is entered and exited. This means that addressable
13573versions of such functions must be available. If all your uses of a
13574function are expanded inline, this may mean an additional expansion of
13575code size. If you use @samp{extern inline} in your C code, an
13576addressable version of such functions must be provided. (This is
13577normally the case anyways, but if you get lucky and the optimizer always
13578expands the functions inline, you might have gotten away without
13579providing static copies.)
13580
13581A function may be given the attribute @code{no_instrument_function}, in
13582which case this instrumentation will not be done. This can be used, for
13583example, for the profiling functions listed above, high-priority
13584interrupt routines, and any functions from which the profiling functions
13585cannot safely be called (perhaps signal handlers, if the profiling
13586routines generate output or allocate memory).
13587
13588@item -fstack-check
13589@opindex fstack-check
13590Generate code to verify that you do not go beyond the boundary of the
13591stack. You should specify this flag if you are running in an
13592environment with multiple threads, but only rarely need to specify it in
13593a single-threaded environment since stack overflow is automatically
13594detected on nearly all systems if there is only one stack.
13595
13596Note that this switch does not actually cause checking to be done; the
13597operating system must do that. The switch causes generation of code
13598to ensure that the operating system sees the stack being extended.
13599
13600@item -fstack-limit-register=@var{reg}
13601@itemx -fstack-limit-symbol=@var{sym}
13602@itemx -fno-stack-limit
13603@opindex fstack-limit-register
13604@opindex fstack-limit-symbol
13605@opindex fno-stack-limit
13606Generate code to ensure that the stack does not grow beyond a certain value,
13607either the value of a register or the address of a symbol. If the stack
13608would grow beyond the value, a signal is raised. For most targets,
13609the signal is raised before the stack overruns the boundary, so
13610it is possible to catch the signal without taking special precautions.
13611
13612For instance, if the stack starts at absolute address @samp{0x80000000}
13613and grows downwards, you can use the flags
13614@option{-fstack-limit-symbol=__stack_limit} and
13615@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
13616of 128KB@. Note that this may only work with the GNU linker.
13617
13618@cindex aliasing of parameters
13619@cindex parameters, aliased
13620@item -fargument-alias
13621@itemx -fargument-noalias
13622@itemx -fargument-noalias-global
13623@itemx -fargument-noalias-anything
13624@opindex fargument-alias
13625@opindex fargument-noalias
13626@opindex fargument-noalias-global
13627@opindex fargument-noalias-anything
13628Specify the possible relationships among parameters and between
13629parameters and global data.
13630
13631@option{-fargument-alias} specifies that arguments (parameters) may
13632alias each other and may alias global storage.@*
13633@option{-fargument-noalias} specifies that arguments do not alias
13634each other, but may alias global storage.@*
13635@option{-fargument-noalias-global} specifies that arguments do not
13636alias each other and do not alias global storage.
13637@option{-fargument-noalias-anything} specifies that arguments do not
13638alias any other storage.
13639
13640Each language will automatically use whatever option is required by
13641the language standard. You should not need to use these options yourself.
13642
13643@item -fleading-underscore
13644@opindex fleading-underscore
13645This option and its counterpart, @option{-fno-leading-underscore}, forcibly
13646change the way C symbols are represented in the object file. One use
13647is to help link with legacy assembly code.
13648
13649@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
13650generate code that is not binary compatible with code generated without that
13651switch. Use it to conform to a non-default application binary interface.
13652Not all targets provide complete support for this switch.
13653
13654@item -ftls-model=@var{model}
13655Alter the thread-local storage model to be used (@pxref{Thread-Local}).
13656The @var{model} argument should be one of @code{global-dynamic},
13657@code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
13658
13659The default without @option{-fpic} is @code{initial-exec}; with
13660@option{-fpic} the default is @code{global-dynamic}.
13661
13662@item -fvisibility=@var{default|internal|hidden|protected}
13663@opindex fvisibility
13664Set the default ELF image symbol visibility to the specified option---all
13665symbols will be marked with this unless overridden within the code.
13666Using this feature can very substantially improve linking and
13667load times of shared object libraries, produce more optimized
13668code, provide near-perfect API export and prevent symbol clashes.
13669It is @strong{strongly} recommended that you use this in any shared objects
13670you distribute.
13671
13672Despite the nomenclature, @code{default} always means public ie;
13673available to be linked against from outside the shared object.
13674@code{protected} and @code{internal} are pretty useless in real-world
13675usage so the only other commonly used option will be @code{hidden}.
13676The default if @option{-fvisibility} isn't specified is
13677@code{default}, i.e., make every
13678symbol public---this causes the same behavior as previous versions of
13679GCC@.
13680
13681A good explanation of the benefits offered by ensuring ELF
13682symbols have the correct visibility is given by ``How To Write
13683Shared Libraries'' by Ulrich Drepper (which can be found at
13684@w{@uref{http://people.redhat.com/~drepper/}})---however a superior
13685solution made possible by this option to marking things hidden when
13686the default is public is to make the default hidden and mark things
13687public. This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
13688and @code{__attribute__ ((visibility("default")))} instead of
13689@code{__declspec(dllexport)} you get almost identical semantics with
13690identical syntax. This is a great boon to those working with
13691cross-platform projects.
13692
13693For those adding visibility support to existing code, you may find
13694@samp{#pragma GCC visibility} of use. This works by you enclosing
13695the declarations you wish to set visibility for with (for example)
13696@samp{#pragma GCC visibility push(hidden)} and
13697@samp{#pragma GCC visibility pop}.
13698Bear in mind that symbol visibility should be viewed @strong{as
13699part of the API interface contract} and thus all new code should
13700always specify visibility when it is not the default ie; declarations
13701only for use within the local DSO should @strong{always} be marked explicitly
13702as hidden as so to avoid PLT indirection overheads---making this
13703abundantly clear also aids readability and self-documentation of the code.
13704Note that due to ISO C++ specification requirements, operator new and
13705operator delete must always be of default visibility.
13706
13707Be aware that headers from outside your project, in particular system
13708headers and headers from any other library you use, may not be
13709expecting to be compiled with visibility other than the default. You
13710may need to explicitly say @samp{#pragma GCC visibility push(default)}
13711before including any such headers.
13712
13713@samp{extern} declarations are not affected by @samp{-fvisibility}, so
13714a lot of code can be recompiled with @samp{-fvisibility=hidden} with
13715no modifications. However, this means that calls to @samp{extern}
13716functions with no explicit visibility will use the PLT, so it is more
13717effective to use @samp{__attribute ((visibility))} and/or
13718@samp{#pragma GCC visibility} to tell the compiler which @samp{extern}
13719declarations should be treated as hidden.
13720
13721Note that @samp{-fvisibility} does affect C++ vague linkage
13722entities. This means that, for instance, an exception class that will
13723be thrown between DSOs must be explicitly marked with default
13724visibility so that the @samp{type_info} nodes will be unified between
13725the DSOs.
13726
13727An overview of these techniques, their benefits and how to use them
13728is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
13729
13730@end table
13731
13732@c man end
13733
13734@node Environment Variables
13735@section Environment Variables Affecting GCC
13736@cindex environment variables
13737
13738@c man begin ENVIRONMENT
13739This section describes several environment variables that affect how GCC
13740operates. Some of them work by specifying directories or prefixes to use
13741when searching for various kinds of files. Some are used to specify other
13742aspects of the compilation environment.
13743
13744Note that you can also specify places to search using options such as
13745@option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
13746take precedence over places specified using environment variables, which
13747in turn take precedence over those specified by the configuration of GCC@.
13748@xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
13749GNU Compiler Collection (GCC) Internals}.
13750
13751@table @env
13752@item LANG
13753@itemx LC_CTYPE
13754@c @itemx LC_COLLATE
13755@itemx LC_MESSAGES
13756@c @itemx LC_MONETARY
13757@c @itemx LC_NUMERIC
13758@c @itemx LC_TIME
13759@itemx LC_ALL
13760@findex LANG
13761@findex LC_CTYPE
13762@c @findex LC_COLLATE
13763@findex LC_MESSAGES
13764@c @findex LC_MONETARY
13765@c @findex LC_NUMERIC
13766@c @findex LC_TIME
13767@findex LC_ALL
13768@cindex locale
13769These environment variables control the way that GCC uses
13770localization information that allow GCC to work with different
13771national conventions. GCC inspects the locale categories
13772@env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
13773so. These locale categories can be set to any value supported by your
13774installation. A typical value is @samp{en_GB.UTF-8} for English in the United
13775Kingdom encoded in UTF-8.
13776
13777The @env{LC_CTYPE} environment variable specifies character
13778classification. GCC uses it to determine the character boundaries in
13779a string; this is needed for some multibyte encodings that contain quote
13780and escape characters that would otherwise be interpreted as a string
13781end or escape.
13782
13783The @env{LC_MESSAGES} environment variable specifies the language to
13784use in diagnostic messages.
13785
13786If the @env{LC_ALL} environment variable is set, it overrides the value
13787of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
13788and @env{LC_MESSAGES} default to the value of the @env{LANG}
13789environment variable. If none of these variables are set, GCC
13790defaults to traditional C English behavior.
13791
13792@item TMPDIR
13793@findex TMPDIR
13794If @env{TMPDIR} is set, it specifies the directory to use for temporary
13795files. GCC uses temporary files to hold the output of one stage of
13796compilation which is to be used as input to the next stage: for example,
13797the output of the preprocessor, which is the input to the compiler
13798proper.
13799
13800@item GCC_EXEC_PREFIX
13801@findex GCC_EXEC_PREFIX
13802If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
13803names of the subprograms executed by the compiler. No slash is added
13804when this prefix is combined with the name of a subprogram, but you can
13805specify a prefix that ends with a slash if you wish.
13806
13807If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
13808an appropriate prefix to use based on the pathname it was invoked with.
13809
13810If GCC cannot find the subprogram using the specified prefix, it
13811tries looking in the usual places for the subprogram.
13812
13813The default value of @env{GCC_EXEC_PREFIX} is
13814@file{@var{prefix}/lib/gcc/} where @var{prefix} is the value
13815of @code{prefix} when you ran the @file{configure} script.
13816
13817Other prefixes specified with @option{-B} take precedence over this prefix.
13818
13819This prefix is also used for finding files such as @file{crt0.o} that are
13820used for linking.
13821
13822In addition, the prefix is used in an unusual way in finding the
13823directories to search for header files. For each of the standard
13824directories whose name normally begins with @samp{/usr/local/lib/gcc}
13825(more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
13826replacing that beginning with the specified prefix to produce an
13827alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
13828@file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
13829These alternate directories are searched first; the standard directories
13830come next.
13831
13832@item COMPILER_PATH
13833@findex COMPILER_PATH
13834The value of @env{COMPILER_PATH} is a colon-separated list of
13835directories, much like @env{PATH}. GCC tries the directories thus
13836specified when searching for subprograms, if it can't find the
13837subprograms using @env{GCC_EXEC_PREFIX}.
13838
13839@item LIBRARY_PATH
13840@findex LIBRARY_PATH
13841The value of @env{LIBRARY_PATH} is a colon-separated list of
13842directories, much like @env{PATH}. When configured as a native compiler,
13843GCC tries the directories thus specified when searching for special
13844linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking
13845using GCC also uses these directories when searching for ordinary
13846libraries for the @option{-l} option (but directories specified with
13847@option{-L} come first).
13848
13849@item LANG
13850@findex LANG
13851@cindex locale definition
13852This variable is used to pass locale information to the compiler. One way in
13853which this information is used is to determine the character set to be used
13854when character literals, string literals and comments are parsed in C and C++.
13855When the compiler is configured to allow multibyte characters,
13856the following values for @env{LANG} are recognized:
13857
13858@table @samp
13859@item C-JIS
13860Recognize JIS characters.
13861@item C-SJIS
13862Recognize SJIS characters.
13863@item C-EUCJP
13864Recognize EUCJP characters.
13865@end table
13866
13867If @env{LANG} is not defined, or if it has some other value, then the
13868compiler will use mblen and mbtowc as defined by the default locale to
13869recognize and translate multibyte characters.
13870@end table
13871
13872@noindent
13873Some additional environments variables affect the behavior of the
13874preprocessor.
13875
13876@include cppenv.texi
13877
13878@c man end
13879
13880@node Precompiled Headers
13881@section Using Precompiled Headers
13882@cindex precompiled headers
13883@cindex speed of compilation
13884
13885Often large projects have many header files that are included in every
13886source file. The time the compiler takes to process these header files
13887over and over again can account for nearly all of the time required to
13888build the project. To make builds faster, GCC allows users to
13889`precompile' a header file; then, if builds can use the precompiled
13890header file they will be much faster.
13891
13892To create a precompiled header file, simply compile it as you would any
13893other file, if necessary using the @option{-x} option to make the driver
13894treat it as a C or C++ header file. You will probably want to use a
13895tool like @command{make} to keep the precompiled header up-to-date when
13896the headers it contains change.
13897
13898A precompiled header file will be searched for when @code{#include} is
13899seen in the compilation. As it searches for the included file
13900(@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
13901compiler looks for a precompiled header in each directory just before it
13902looks for the include file in that directory. The name searched for is
13903the name specified in the @code{#include} with @samp{.gch} appended. If
13904the precompiled header file can't be used, it is ignored.
13905
13906For instance, if you have @code{#include "all.h"}, and you have
13907@file{all.h.gch} in the same directory as @file{all.h}, then the
13908precompiled header file will be used if possible, and the original
13909header will be used otherwise.
13910
13911Alternatively, you might decide to put the precompiled header file in a
13912directory and use @option{-I} to ensure that directory is searched
13913before (or instead of) the directory containing the original header.
13914Then, if you want to check that the precompiled header file is always
13915used, you can put a file of the same name as the original header in this
13916directory containing an @code{#error} command.
13917
13918This also works with @option{-include}. So yet another way to use
13919precompiled headers, good for projects not designed with precompiled
13920header files in mind, is to simply take most of the header files used by
13921a project, include them from another header file, precompile that header
13922file, and @option{-include} the precompiled header. If the header files
13923have guards against multiple inclusion, they will be skipped because
13924they've already been included (in the precompiled header).
13925
13926If you need to precompile the same header file for different
13927languages, targets, or compiler options, you can instead make a
13928@emph{directory} named like @file{all.h.gch}, and put each precompiled
13929header in the directory, perhaps using @option{-o}. It doesn't matter
13930what you call the files in the directory, every precompiled header in
13931the directory will be considered. The first precompiled header
13932encountered in the directory that is valid for this compilation will
13933be used; they're searched in no particular order.
13934
13935There are many other possibilities, limited only by your imagination,
13936good sense, and the constraints of your build system.
13937
13938A precompiled header file can be used only when these conditions apply:
13939
13940@itemize
13941@item
13942Only one precompiled header can be used in a particular compilation.
13943
13944@item
13945A precompiled header can't be used once the first C token is seen. You
13946can have preprocessor directives before a precompiled header; you can
13947even include a precompiled header from inside another header, so long as
13948there are no C tokens before the @code{#include}.
13949
13950@item
13951The precompiled header file must be produced for the same language as
13952the current compilation. You can't use a C precompiled header for a C++
13953compilation.
13954
13955@item
13956The precompiled header file must have been produced by the same compiler
13957binary as the current compilation is using.
13958
13959@item
13960Any macros defined before the precompiled header is included must
13961either be defined in the same way as when the precompiled header was
13962generated, or must not affect the precompiled header, which usually
13963means that they don't appear in the precompiled header at all.
13964
13965The @option{-D} option is one way to define a macro before a
13966precompiled header is included; using a @code{#define} can also do it.
13967There are also some options that define macros implicitly, like
13968@option{-O} and @option{-Wdeprecated}; the same rule applies to macros
13969defined this way.
13970
13971@item If debugging information is output when using the precompiled
13972header, using @option{-g} or similar, the same kind of debugging information
13973must have been output when building the precompiled header. However,
13974a precompiled header built using @option{-g} can be used in a compilation
13975when no debugging information is being output.
13976
13977@item The same @option{-m} options must generally be used when building
13978and using the precompiled header. @xref{Submodel Options},
13979for any cases where this rule is relaxed.
13980
13981@item Each of the following options must be the same when building and using
13982the precompiled header:
13983
13984@gccoptlist{-fexceptions -funit-at-a-time}
13985
13986@item
13987Some other command-line options starting with @option{-f},
13988@option{-p}, or @option{-O} must be defined in the same way as when
13989the precompiled header was generated. At present, it's not clear
13990which options are safe to change and which are not; the safest choice
13991is to use exactly the same options when generating and using the
13992precompiled header. The following are known to be safe:
13993
13994@gccoptlist{-fmessage-length= -fpreprocessed
13995-fsched-interblock -fsched-spec -fsched-spec-load -fsched-spec-load-dangerous
13996-fsched-verbose=<number> -fschedule-insns -fvisibility=
13997-pedantic-errors}
13998
13999@end itemize
14000
14001For all of these except the last, the compiler will automatically
14002ignore the precompiled header if the conditions aren't met. If you
14003find an option combination that doesn't work and doesn't cause the
14004precompiled header to be ignored, please consider filing a bug report,
14005see @ref{Bugs}.
14006
14007If you do use differing options when generating and using the
14008precompiled header, the actual behavior will be a mixture of the
14009behavior for the options. For instance, if you use @option{-g} to
14010generate the precompiled header but not when using it, you may or may
14011not get debugging information for routines in the precompiled header.
14012
14013@node Running Protoize
14014@section Running Protoize
14015
14016The program @code{protoize} is an optional part of GCC@. You can use
14017it to add prototypes to a program, thus converting the program to ISO
14018C in one respect. The companion program @code{unprotoize} does the
14019reverse: it removes argument types from any prototypes that are found.
14020
14021When you run these programs, you must specify a set of source files as
14022command line arguments. The conversion programs start out by compiling
14023these files to see what functions they define. The information gathered
14024about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
14025
14026After scanning comes actual conversion. The specified files are all
14027eligible to be converted; any files they include (whether sources or
14028just headers) are eligible as well.
14029
14030But not all the eligible files are converted. By default,
14031@code{protoize} and @code{unprotoize} convert only source and header
14032files in the current directory. You can specify additional directories
14033whose files should be converted with the @option{-d @var{directory}}
14034option. You can also specify particular files to exclude with the
14035@option{-x @var{file}} option. A file is converted if it is eligible, its
14036directory name matches one of the specified directory names, and its
14037name within the directory has not been excluded.
14038
14039Basic conversion with @code{protoize} consists of rewriting most
14040function definitions and function declarations to specify the types of
14041the arguments. The only ones not rewritten are those for varargs
14042functions.
14043
14044@code{protoize} optionally inserts prototype declarations at the
14045beginning of the source file, to make them available for any calls that
14046precede the function's definition. Or it can insert prototype
14047declarations with block scope in the blocks where undeclared functions
14048are called.
14049
14050Basic conversion with @code{unprotoize} consists of rewriting most
14051function declarations to remove any argument types, and rewriting
14052function definitions to the old-style pre-ISO form.
14053
14054Both conversion programs print a warning for any function declaration or
14055definition that they can't convert. You can suppress these warnings
14056with @option{-q}.
14057
14058The output from @code{protoize} or @code{unprotoize} replaces the
14059original source file. The original file is renamed to a name ending
14060with @samp{.save} (for DOS, the saved filename ends in @samp{.sav}
14061without the original @samp{.c} suffix). If the @samp{.save} (@samp{.sav}
14062for DOS) file already exists, then the source file is simply discarded.
14063
14064@code{protoize} and @code{unprotoize} both depend on GCC itself to
14065scan the program and collect information about the functions it uses.
14066So neither of these programs will work until GCC is installed.
14067
14068Here is a table of the options you can use with @code{protoize} and
14069@code{unprotoize}. Each option works with both programs unless
14070otherwise stated.
14071
14072@table @code
14073@item -B @var{directory}
14074Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
14075usual directory (normally @file{/usr/local/lib}). This file contains
14076prototype information about standard system functions. This option
14077applies only to @code{protoize}.
14078
14079@item -c @var{compilation-options}
14080Use @var{compilation-options} as the options when running @command{gcc} to
14081produce the @samp{.X} files. The special option @option{-aux-info} is
14082always passed in addition, to tell @command{gcc} to write a @samp{.X} file.
14083
14084Note that the compilation options must be given as a single argument to
14085@code{protoize} or @code{unprotoize}. If you want to specify several
14086@command{gcc} options, you must quote the entire set of compilation options
14087to make them a single word in the shell.
14088
14089There are certain @command{gcc} arguments that you cannot use, because they
14090would produce the wrong kind of output. These include @option{-g},
14091@option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in
14092the @var{compilation-options}, they are ignored.
14093
14094@item -C
14095Rename files to end in @samp{.C} (@samp{.cc} for DOS-based file
14096systems) instead of @samp{.c}. This is convenient if you are converting
14097a C program to C++. This option applies only to @code{protoize}.
14098
14099@item -g
14100Add explicit global declarations. This means inserting explicit
14101declarations at the beginning of each source file for each function
14102that is called in the file and was not declared. These declarations
14103precede the first function definition that contains a call to an
14104undeclared function. This option applies only to @code{protoize}.
14105
14106@item -i @var{string}
14107Indent old-style parameter declarations with the string @var{string}.
14108This option applies only to @code{protoize}.
14109
14110@code{unprotoize} converts prototyped function definitions to old-style
14111function definitions, where the arguments are declared between the
14112argument list and the initial @samp{@{}. By default, @code{unprotoize}
14113uses five spaces as the indentation. If you want to indent with just
14114one space instead, use @option{-i " "}.
14115
14116@item -k
14117Keep the @samp{.X} files. Normally, they are deleted after conversion
14118is finished.
14119
14120@item -l
14121Add explicit local declarations. @code{protoize} with @option{-l} inserts
14122a prototype declaration for each function in each block which calls the
14123function without any declaration. This option applies only to
14124@code{protoize}.
14125
14126@item -n
14127Make no real changes. This mode just prints information about the conversions
14128that would have been done without @option{-n}.
14129
14130@item -N
14131Make no @samp{.save} files. The original files are simply deleted.
14132Use this option with caution.
14133
14134@item -p @var{program}
14135Use the program @var{program} as the compiler. Normally, the name
14136@file{gcc} is used.
14137
14138@item -q
14139Work quietly. Most warnings are suppressed.
14140
14141@item -v
14142Print the version number, just like @option{-v} for @command{gcc}.
14143@end table
14144
14145If you need special compiler options to compile one of your program's
14146source files, then you should generate that file's @samp{.X} file
14147specially, by running @command{gcc} on that source file with the
14148appropriate options and the option @option{-aux-info}. Then run
14149@code{protoize} on the entire set of files. @code{protoize} will use
14150the existing @samp{.X} file because it is newer than the source file.
14151For example:
14152
14153@smallexample
14154gcc -Dfoo=bar file1.c -aux-info file1.X
14155protoize *.c
14156@end smallexample
14157
14158@noindent
14159You need to include the special files along with the rest in the
14160@code{protoize} command, even though their @samp{.X} files already
14161exist, because otherwise they won't get converted.
14162
14163@xref{Protoize Caveats}, for more information on how to use
14164@code{protoize} successfully.