diff options
Diffstat (limited to 'contrib/gcc/doc/invoke.texi')
| -rw-r--r-- | contrib/gcc/doc/invoke.texi | 10463 |
1 files changed, 10463 insertions, 0 deletions
diff --git a/contrib/gcc/doc/invoke.texi b/contrib/gcc/doc/invoke.texi new file mode 100644 index 000000000000..51db49adb028 --- /dev/null +++ b/contrib/gcc/doc/invoke.texi @@ -0,0 +1,10463 @@ +@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, +@c 2000, 2001, 2002 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@ignore +@c man begin COPYRIGHT +Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, +1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with the +Invariant Sections being ``GNU General Public License'' and ``Funding +Free Software'', the Front-Cover texts being (a) (see below), and with +the Back-Cover Texts being (b) (see below). A copy of the license is +included in the gfdl(7) man page. + +(a) The FSF's Front-Cover Text is: + + A GNU Manual + +(b) The FSF's Back-Cover Text is: + + You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. +@c man end +@c Set file name and title for the man page. +@setfilename gcc +@settitle GNU project C and C++ compiler +@c man begin SYNOPSIS +gcc [@option{-c}|@option{-S}|@option{-E}] [@option{-std=}@var{standard}] + [@option{-g}] [@option{-pg}] [@option{-O}@var{level}] + [@option{-W}@var{warn}@dots{}] [@option{-pedantic}] + [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}] + [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}] + [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}] + [@option{-o} @var{outfile}] @var{infile}@dots{} + +Only the most useful options are listed here; see below for the +remainder. @samp{g++} accepts mostly the same options as @samp{gcc}. +@c man end +@c man begin SEEALSO +gpl(7), gfdl(7), fsf-funding(7), +cpp(1), gcov(1), g77(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1) +and the Info entries for @file{gcc}, @file{cpp}, @file{g77}, @file{as}, +@file{ld}, @file{binutils} and @file{gdb}. +@c man end +@c man begin BUGS +For instructions on reporting bugs, see +@w{@uref{http://gcc.gnu.org/bugs.html}}. Use of the @command{gccbug} +script to report bugs is recommended. +@c man end +@c man begin AUTHOR +See the Info entry for @command{gcc}, or +@w{@uref{http://gcc.gnu.org/onlinedocs/gcc/Contributors.html}}, +for contributors to GCC@. +@c man end +@end ignore + +@node Invoking GCC +@chapter GCC Command Options +@cindex GCC command options +@cindex command options +@cindex options, GCC command + +@c man begin DESCRIPTION + +When you invoke GCC, it normally does preprocessing, compilation, +assembly and linking. The ``overall options'' allow you to stop this +process at an intermediate stage. For example, the @option{-c} option +says not to run the linker. Then the output consists of object files +output by the assembler. + +Other options are passed on to one stage of processing. Some options +control the preprocessor and others the compiler itself. Yet other +options control the assembler and linker; most of these are not +documented here, since you rarely need to use any of them. + +@cindex C compilation options +Most of the command line options that you can use with GCC are useful +for C programs; when an option is only useful with another language +(usually C++), the explanation says so explicitly. If the description +for a particular option does not mention a source language, you can use +that option with all supported languages. + +@cindex C++ compilation options +@xref{Invoking G++,,Compiling C++ Programs}, for a summary of special +options for compiling C++ programs. + +@cindex grouping options +@cindex options, grouping +The @command{gcc} program accepts options and file names as operands. Many +options have multi-letter names; therefore multiple single-letter options +may @emph{not} be grouped: @option{-dr} is very different from @w{@samp{-d +-r}}. + +@cindex order of options +@cindex options, order +You can mix options and other arguments. For the most part, the order +you use doesn't matter. Order does matter when you use several options +of the same kind; for example, if you specify @option{-L} more than once, +the directories are searched in the order specified. + +Many options have long names starting with @samp{-f} or with +@samp{-W}---for example, @option{-fforce-mem}, +@option{-fstrength-reduce}, @option{-Wformat} and so on. Most of +these have both positive and negative forms; the negative form of +@option{-ffoo} would be @option{-fno-foo}. This manual documents +only one of these two forms, whichever one is not the default. + +@c man end + +@xref{Option Index}, for an index to GCC's options. + +@menu +* Option Summary:: Brief list of all options, without explanations. +* Overall Options:: Controlling the kind of output: + an executable, object files, assembler files, + or preprocessed source. +* Invoking G++:: Compiling C++ programs. +* C Dialect Options:: Controlling the variant of C language compiled. +* C++ Dialect Options:: Variations on C++. +* Objective-C Dialect Options:: Variations on Objective-C. +* Language Independent Options:: Controlling how diagnostics should be + formatted. +* Warning Options:: How picky should the compiler be? +* Debugging Options:: Symbol tables, measurements, and debugging dumps. +* Optimize Options:: How much optimization? +* Preprocessor Options:: Controlling header files and macro definitions. + Also, getting dependency information for Make. +* Assembler Options:: Passing options to the assembler. +* Link Options:: Specifying libraries and so on. +* Directory Options:: Where to find header files and libraries. + Where to find the compiler executable files. +* Spec Files:: How to pass switches to sub-processes. +* Target Options:: Running a cross-compiler, or an old version of GCC. +* Submodel Options:: Specifying minor hardware or convention variations, + such as 68010 vs 68020. +* Code Gen Options:: Specifying conventions for function calls, data layout + and register usage. +* Environment Variables:: Env vars that affect GCC. +* Running Protoize:: Automatically adding or removing function prototypes. +@end menu + +@c man begin OPTIONS + +@node Option Summary +@section Option Summary + +Here is a summary of all the options, grouped by type. Explanations are +in the following sections. + +@table @emph +@item Overall Options +@xref{Overall Options,,Options Controlling the Kind of Output}. +@gccoptlist{ +-c -S -E -o @var{file} -pipe -pass-exit-codes -x @var{language} @gol +-v --target-help --help} + +@item C Language Options +@xref{C Dialect Options,,Options Controlling C Dialect}. +@gccoptlist{ +-ansi -std=@var{standard} -aux-info @var{filename} @gol +-fno-asm -fno-builtin -fno-builtin-@var{function} @gol +-fhosted -ffreestanding @gol +-trigraphs -traditional -traditional-cpp @gol +-fallow-single-precision -fcond-mismatch @gol +-fsigned-bitfields -fsigned-char @gol +-funsigned-bitfields -funsigned-char @gol +-fwritable-strings -fshort-wchar} + +@item C++ Language Options +@xref{C++ Dialect Options,,Options Controlling C++ Dialect}. +@gccoptlist{ +-fno-access-control -fcheck-new -fconserve-space @gol +-fno-const-strings -fdollars-in-identifiers @gol +-fno-elide-constructors @gol +-fno-enforce-eh-specs -fexternal-templates @gol +-falt-external-templates @gol +-ffor-scope -fno-for-scope -fno-gnu-keywords @gol +-fno-implicit-templates @gol +-fno-implicit-inline-templates @gol +-fno-implement-inlines -fms-extensions @gol +-fno-nonansi-builtins -fno-operator-names @gol +-fno-optional-diags -fpermissive @gol +-frepo -fno-rtti -fstats -ftemplate-depth-@var{n} @gol +-fuse-cxa-atexit -fvtable-gc -fno-weak -nostdinc++ @gol +-fno-default-inline -Wctor-dtor-privacy @gol +-Wnon-virtual-dtor -Wreorder @gol +-Weffc++ -Wno-deprecated @gol +-Wno-non-template-friend -Wold-style-cast @gol +-Woverloaded-virtual -Wno-pmf-conversions @gol +-Wsign-promo -Wsynth} + +@item Objective-C Language Options +@xref{Objective-C Dialect Options,,Options Controlling Objective-C Dialect}. +@gccoptlist{ +-fconstant-string-class=@var{class-name} @gol +-fgnu-runtime -fnext-runtime -gen-decls @gol +-Wno-protocol -Wselector} + +@item Language Independent Options +@xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}. +@gccoptlist{ +-fmessage-length=@var{n} @gol +-fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]}} + +@item Warning Options +@xref{Warning Options,,Options to Request or Suppress Warnings}. +@gccoptlist{ +-fsyntax-only -pedantic -pedantic-errors @gol +-w -W -Wall -Waggregate-return @gol +-Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment @gol +-Wconversion -Wno-deprecated-declarations @gol +-Wdisabled-optimization -Wdiv-by-zero -Werror @gol +-Wfloat-equal -Wformat -Wformat=2 @gol +-Wformat-nonliteral -Wformat-security @gol +-Wimplicit -Wimplicit-int @gol +-Wimplicit-function-declaration @gol +-Werror-implicit-function-declaration @gol +-Wimport -Winline @gol +-Wlarger-than-@var{len} -Wlong-long @gol +-Wmain -Wmissing-braces -Wmissing-declarations @gol +-Wmissing-format-attribute -Wmissing-noreturn @gol +-Wmultichar -Wno-format-extra-args -Wno-format-y2k @gol +-Wno-import -Wpacked -Wpadded @gol +-Wparentheses -Wpointer-arith -Wredundant-decls @gol +-Wreturn-type -Wsequence-point -Wshadow @gol +-Wsign-compare -Wswitch -Wsystem-headers @gol +-Wtrigraphs -Wundef -Wuninitialized @gol +-Wunknown-pragmas -Wunreachable-code @gol +-Wunused -Wunused-function -Wunused-label -Wunused-parameter @gol +-Wunused-value -Wunused-variable -Wwrite-strings} + +@item C-only Warning Options +@gccoptlist{ +-Wbad-function-cast -Wmissing-prototypes -Wnested-externs @gol +-Wstrict-prototypes -Wtraditional} + +@item Debugging Options +@xref{Debugging Options,,Options for Debugging Your Program or GCC}. +@gccoptlist{ +-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol +-fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} @gol +-fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol +-fdump-tree-original@r{[}-@var{n}@r{]} -fdump-tree-optimized@r{[}-@var{n}@r{]} @gol +-fdump-tree-inlined@r{[}-@var{n}@r{]} @gol +-fmem-report -fpretend-float @gol +-fprofile-arcs -ftest-coverage -ftime-report @gol +-g -g@var{level} -gcoff -gdwarf -gdwarf-1 -gdwarf-1+ -gdwarf-2 @gol +-ggdb -gstabs -gstabs+ -gvms -gxcoff -gxcoff+ @gol +-p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol +-print-multi-directory -print-multi-lib @gol +-print-prog-name=@var{program} -print-search-dirs -Q @gol +-save-temps -time} + +@item Optimization Options +@xref{Optimize Options,,Options that Control Optimization}. +@gccoptlist{ +-falign-functions=@var{n} -falign-jumps=@var{n} @gol +-falign-labels=@var{n} -falign-loops=@var{n} @gol +-fbranch-probabilities -fcaller-saves -fcprop-registers @gol +-fcse-follow-jumps -fcse-skip-blocks -fdata-sections @gol +-fdelayed-branch -fdelete-null-pointer-checks @gol +-fexpensive-optimizations -ffast-math -ffloat-store @gol +-fforce-addr -fforce-mem -ffunction-sections @gol +-fgcse -fgcse-lm -fgcse-sm @gol +-finline-functions -finline-limit=@var{n} -fkeep-inline-functions @gol +-fkeep-static-consts -fmerge-constants -fmerge-all-constants @gol +-fmove-all-movables -fno-default-inline -fno-defer-pop @gol +-fno-function-cse -fno-guess-branch-probability @gol +-fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol +-funsafe-math-optimizations -fno-trapping-math @gol +-fomit-frame-pointer -foptimize-register-move @gol +-foptimize-sibling-calls -fprefetch-loop-arrays @gol +-freduce-all-givs -fregmove -frename-registers @gol +-frerun-cse-after-loop -frerun-loop-opt @gol +-fschedule-insns -fschedule-insns2 @gol +-fsingle-precision-constant -fssa -fssa-ccp -fssa-dce @gol +-fstrength-reduce -fstrict-aliasing -fthread-jumps -ftrapv @gol +-funroll-all-loops -funroll-loops @gol +--param @var{name}=@var{value} +-O -O0 -O1 -O2 -O3 -Os} + +@item Preprocessor Options +@xref{Preprocessor Options,,Options Controlling the Preprocessor}. +@gccoptlist{ +-$ -A@var{question}=@var{answer} -A-@var{question}@r{[}=@var{answer}@r{]} @gol +-C -dD -dI -dM -dN @gol +-D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol +-idirafter @var{dir} @gol +-include @var{file} -imacros @var{file} @gol +-iprefix @var{file} -iwithprefix @var{dir} @gol +-iwithprefixbefore @var{dir} -isystem @var{dir} @gol +-M -MM -MF -MG -MP -MQ -MT -nostdinc -P -remap @gol +-trigraphs -undef -U@var{macro} -Wp,@var{option}} + +@item Assembler Option +@xref{Assembler Options,,Passing Options to the Assembler}. +@gccoptlist{ +-Wa,@var{option}} + +@item Linker Options +@xref{Link Options,,Options for Linking}. +@gccoptlist{ +@var{object-file-name} -l@var{library} @gol +-nostartfiles -nodefaultlibs -nostdlib @gol +-s -static -static-libgcc -shared -shared-libgcc -symbolic @gol +-Wl,@var{option} -Xlinker @var{option} @gol +-u @var{symbol}} + +@item Directory Options +@xref{Directory Options,,Options for Directory Search}. +@gccoptlist{ +-B@var{prefix} -I@var{dir} -I- -L@var{dir} -specs=@var{file}} + +@item Target Options +@c I wrote this xref this way to avoid overfull hbox. -- rms +@xref{Target Options}. +@gccoptlist{ +-b @var{machine} -V @var{version}} + +@item Machine Dependent Options +@xref{Submodel Options,,Hardware Models and Configurations}. + +@emph{M680x0 Options} +@gccoptlist{ +-m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol +-m68060 -mcpu32 -m5200 -m68881 -mbitfield -mc68000 -mc68020 @gol +-mfpa -mnobitfield -mrtd -mshort -msoft-float -mpcrel @gol +-malign-int -mstrict-align} + +@emph{M68hc1x Options} +@gccoptlist{ +-m6811 -m6812 -m68hc11 -m68hc12 @gol +-mauto-incdec -mshort -msoft-reg-count=@var{count}} + +@emph{VAX Options} +@gccoptlist{ +-mg -mgnu -munix} + +@emph{SPARC Options} +@gccoptlist{ +-mcpu=@var{cpu-type} @gol +-mtune=@var{cpu-type} @gol +-mcmodel=@var{code-model} @gol +-m32 -m64 @gol +-mapp-regs -mbroken-saverestore -mcypress @gol +-mepilogue -mfaster-structs -mflat @gol +-mfpu -mhard-float -mhard-quad-float @gol +-mimpure-text -mlive-g0 -mno-app-regs @gol +-mno-epilogue -mno-faster-structs -mno-flat -mno-fpu @gol +-mno-impure-text -mno-stack-bias -mno-unaligned-doubles @gol +-msoft-float -msoft-quad-float -msparclite -mstack-bias @gol +-msupersparc -munaligned-doubles -mv8} + +@emph{Convex Options} +@gccoptlist{ +-mc1 -mc2 -mc32 -mc34 -mc38 @gol +-margcount -mnoargcount @gol +-mlong32 -mlong64 @gol +-mvolatile-cache -mvolatile-nocache} + +@emph{AMD29K Options} +@gccoptlist{ +-m29000 -m29050 -mbw -mnbw -mdw -mndw @gol +-mlarge -mnormal -msmall @gol +-mkernel-registers -mno-reuse-arg-regs @gol +-mno-stack-check -mno-storem-bug @gol +-mreuse-arg-regs -msoft-float -mstack-check @gol +-mstorem-bug -muser-registers} + +@emph{ARM Options} +@gccoptlist{ +-mapcs-frame -mno-apcs-frame @gol +-mapcs-26 -mapcs-32 @gol +-mapcs-stack-check -mno-apcs-stack-check @gol +-mapcs-float -mno-apcs-float @gol +-mapcs-reentrant -mno-apcs-reentrant @gol +-msched-prolog -mno-sched-prolog @gol +-mlittle-endian -mbig-endian -mwords-little-endian @gol +-malignment-traps -mno-alignment-traps @gol +-msoft-float -mhard-float -mfpe @gol +-mthumb-interwork -mno-thumb-interwork @gol +-mcpu=@var{name} -march=@var{name} -mfpe=@var{name} @gol +-mstructure-size-boundary=@var{n} @gol +-mbsd -mxopen -mno-symrename @gol +-mabort-on-noreturn @gol +-mlong-calls -mno-long-calls @gol +-msingle-pic-base -mno-single-pic-base @gol +-mpic-register=@var{reg} @gol +-mnop-fun-dllimport @gol +-mpoke-function-name @gol +-mthumb -marm @gol +-mtpcs-frame -mtpcs-leaf-frame @gol +-mcaller-super-interworking -mcallee-super-interworking } + +@emph{MN10200 Options} +@gccoptlist{ +-mrelax} + +@emph{MN10300 Options} +@gccoptlist{ +-mmult-bug -mno-mult-bug @gol +-mam33 -mno-am33 @gol +-mno-crt0 -mrelax} + +@emph{M32R/D Options} +@gccoptlist{ +-m32rx -m32r -mcode-model=@var{model-type} -msdata=@var{sdata-type} @gol +-G @var{num}} + +@emph{M88K Options} +@gccoptlist{ +-m88000 -m88100 -m88110 -mbig-pic @gol +-mcheck-zero-division -mhandle-large-shift @gol +-midentify-revision -mno-check-zero-division @gol +-mno-ocs-debug-info -mno-ocs-frame-position @gol +-mno-optimize-arg-area -mno-serialize-volatile @gol +-mno-underscores -mocs-debug-info @gol +-mocs-frame-position -moptimize-arg-area @gol +-mserialize-volatile -mshort-data-@var{num} -msvr3 @gol +-msvr4 -mtrap-large-shift -muse-div-instruction @gol +-mversion-03.00 -mwarn-passed-structs} + +@emph{RS/6000 and PowerPC Options} +@gccoptlist{ +-mcpu=@var{cpu-type} @gol +-mtune=@var{cpu-type} @gol +-mpower -mno-power -mpower2 -mno-power2 @gol +-mpowerpc -mpowerpc64 -mno-powerpc @gol +-maltivec -mno-altivec @gol +-mpowerpc-gpopt -mno-powerpc-gpopt @gol +-mpowerpc-gfxopt -mno-powerpc-gfxopt @gol +-mnew-mnemonics -mold-mnemonics @gol +-mfull-toc -mminimal-toc -mno-fop-in-toc -mno-sum-in-toc @gol +-m64 -m32 -mxl-call -mno-xl-call -mpe @gol +-msoft-float -mhard-float -mmultiple -mno-multiple @gol +-mstring -mno-string -mupdate -mno-update @gol +-mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol +-mstrict-align -mno-strict-align -mrelocatable @gol +-mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol +-mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol +-mcall-aix -mcall-sysv -mcall-netbsd @gol +-maix-struct-return -msvr4-struct-return +-mabi=altivec @gol +-mprototype -mno-prototype @gol +-msim -mmvme -mads -myellowknife -memb -msdata @gol +-msdata=@var{opt} -mvxworks -G @var{num} -pthread} + +@emph{RT Options} +@gccoptlist{ +-mcall-lib-mul -mfp-arg-in-fpregs -mfp-arg-in-gregs @gol +-mfull-fp-blocks -mhc-struct-return -min-line-mul @gol +-mminimum-fp-blocks -mnohc-struct-return} + +@emph{MIPS Options} +@gccoptlist{ +-mabicalls -march=@var{cpu-type} -mtune=@var{cpu=type} @gol +-mcpu=@var{cpu-type} -membedded-data -muninit-const-in-rodata @gol +-membedded-pic -mfp32 -mfp64 -mfused-madd -mno-fused-madd @gol +-mgas -mgp32 -mgp64 @gol +-mgpopt -mhalf-pic -mhard-float -mint64 -mips1 @gol +-mips2 -mips3 -mips4 -mlong64 -mlong32 -mlong-calls -mmemcpy @gol +-mmips-as -mmips-tfile -mno-abicalls @gol +-mno-embedded-data -mno-uninit-const-in-rodata @gol +-mno-embedded-pic -mno-gpopt -mno-long-calls @gol +-mno-memcpy -mno-mips-tfile -mno-rnames -mno-stats @gol +-mrnames -msoft-float @gol +-m4650 -msingle-float -mmad @gol +-mstats -EL -EB -G @var{num} -nocpp @gol +-mabi=32 -mabi=n32 -mabi=64 -mabi=eabi @gol +-mfix7000 -mno-crt0 -mflush-func=@var{func} -mno-flush-func} + +@emph{i386 and x86-64 Options} +@gccoptlist{ +-mcpu=@var{cpu-type} -march=@var{cpu-type} -mfpmath=@var{unit} @gol +-masm=@var{dialect} -mno-fancy-math-387 @gol +-mno-fp-ret-in-387 -msoft-float -msvr3-shlib @gol +-mno-wide-multiply -mrtd -malign-double @gol +-mpreferred-stack-boundary=@var{num} @gol +-mmmx -msse -msse2 -msse-math -m3dnow @gol +-mthreads -mno-align-stringops -minline-all-stringops @gol +-mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol +-m96bit-long-double -mregparm=@var{num} -momit-leaf-frame-pointer @gol +-mno-red-zone@gol +-m32 -m64} + +@emph{HPPA Options} +@gccoptlist{ +-march=@var{architecture-type} @gol +-mbig-switch -mdisable-fpregs -mdisable-indexing @gol +-mfast-indirect-calls -mgas -mjump-in-delay @gol +-mlong-load-store -mno-big-switch -mno-disable-fpregs @gol +-mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol +-mno-jump-in-delay -mno-long-load-store @gol +-mno-portable-runtime -mno-soft-float @gol +-mno-space-regs -msoft-float -mpa-risc-1-0 @gol +-mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime @gol +-mschedule=@var{cpu-type} -mspace-regs} + +@emph{Intel 960 Options} +@gccoptlist{ +-m@var{cpu-type} -masm-compat -mclean-linkage @gol +-mcode-align -mcomplex-addr -mleaf-procedures @gol +-mic-compat -mic2.0-compat -mic3.0-compat @gol +-mintel-asm -mno-clean-linkage -mno-code-align @gol +-mno-complex-addr -mno-leaf-procedures @gol +-mno-old-align -mno-strict-align -mno-tail-call @gol +-mnumerics -mold-align -msoft-float -mstrict-align @gol +-mtail-call} + +@emph{DEC Alpha Options} +@gccoptlist{ +-mno-fp-regs -msoft-float -malpha-as -mgas @gol +-mieee -mieee-with-inexact -mieee-conformant @gol +-mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} @gol +-mtrap-precision=@var{mode} -mbuild-constants @gol +-mcpu=@var{cpu-type} -mtune=@var{cpu-type} @gol +-mbwx -mmax -mfix -mcix @gol +-mfloat-vax -mfloat-ieee @gol +-mexplicit-relocs -msmall-data -mlarge-data @gol +-mmemory-latency=@var{time}} + +@emph{DEC Alpha/VMS Options} +@gccoptlist{ +-mvms-return-codes} + +@emph{Clipper Options} +@gccoptlist{ +-mc300 -mc400} + +@emph{H8/300 Options} +@gccoptlist{ +-mrelax -mh -ms -mint32 -malign-300} + +@emph{SH Options} +@gccoptlist{ +-m1 -m2 -m3 -m3e @gol +-m4-nofpu -m4-single-only -m4-single -m4 @gol +-mb -ml -mdalign -mrelax @gol +-mbigtable -mfmovd -mhitachi -mnomacsave @gol +-mieee -misize -mpadstruct -mspace @gol +-mprefergot -musermode} + +@emph{System V Options} +@gccoptlist{ +-Qy -Qn -YP,@var{paths} -Ym,@var{dir}} + +@emph{ARC Options} +@gccoptlist{ +-EB -EL @gol +-mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text-section} @gol +-mdata=@var{data-section} -mrodata=@var{readonly-data-section}} + +@emph{TMS320C3x/C4x Options} +@gccoptlist{ +-mcpu=@var{cpu} -mbig -msmall -mregparm -mmemparm @gol +-mfast-fix -mmpyi -mbk -mti -mdp-isr-reload @gol +-mrpts=@var{count} -mrptb -mdb -mloop-unsigned @gol +-mparallel-insns -mparallel-mpy -mpreserve-float} + +@emph{V850 Options} +@gccoptlist{ +-mlong-calls -mno-long-calls -mep -mno-ep @gol +-mprolog-function -mno-prolog-function -mspace @gol +-mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol +-mv850 -mbig-switch} + +@emph{NS32K Options} +@gccoptlist{ +-m32032 -m32332 -m32532 -m32081 -m32381 @gol +-mmult-add -mnomult-add -msoft-float -mrtd -mnortd @gol +-mregparam -mnoregparam -msb -mnosb @gol +-mbitfield -mnobitfield -mhimem -mnohimem} + +@emph{AVR Options} +@gccoptlist{ +-mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts @gol +-mcall-prologues -mno-tablejump -mtiny-stack} + +@emph{MCore Options} +@gccoptlist{ +-mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol +-mno-relax-immediates -mwide-bitfields -mno-wide-bitfields @gol +-m4byte-functions -mno-4byte-functions -mcallgraph-data @gol +-mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim @gol +-mlittle-endian -mbig-endian -m210 -m340 -mstack-increment} + +@emph{MMIX Options} +@gccoptlist{ +-mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol +-mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol +-melf -mbranch-predict -mno-branch-predict} + +@emph{IA-64 Options} +@gccoptlist{ +-mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol +-mvolatile-asm-stop -mb-step -mregister-names -mno-sdata @gol +-mconstant-gp -mauto-pic -minline-divide-min-latency @gol +-minline-divide-max-throughput -mno-dwarf2-asm @gol +-mfixed-range=@var{register-range}} + +@emph{D30V Options} +@gccoptlist{ +-mextmem -mextmemory -monchip -mno-asm-optimize -masm-optimize @gol +-mbranch-cost=@var{n} -mcond-exec=@var{n}} + +@emph{S/390 and zSeries Options} +@gccoptlist{ +-mhard-float -msoft-float -mbackchain -mno-backchain @gol +-msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol +-m64 -m31 -mdebug -mno-debug} + +@emph{CRIS Options} +@gccoptlist{ +-mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol +-mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol +-metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol +-mstack-align -mdata-align -mconst-align @gol +-m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol +-melf -maout -melinux -mlinux -sim -sim2} + +@emph{PDP-11 Options} +@gccoptlist{ +-mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol +-mbcopy -mbcopy-builtin -mint32 -mno-int16 @gol +-mint16 -mno-int32 -mfloat32 -mno-float64 @gol +-mfloat64 -mno-float32 -mabshi -mno-abshi @gol +-mbranch-expensive -mbranch-cheap @gol +-msplit -mno-split -munix-asm -mdec-asm} + +@emph{Xstormy16 Options} +@gccoptlist{ +-msim} + +@emph{Xtensa Options} +@gccoptlist{ +-mbig-endian -mlittle-endian @gol +-mdensity -mno-density @gol +-mmac16 -mno-mac16 @gol +-mmul16 -mno-mul16 @gol +-mmul32 -mno-mul32 @gol +-mnsa -mno-nsa @gol +-mminmax -mno-minmax @gol +-msext -mno-sext @gol +-mbooleans -mno-booleans @gol +-mhard-float -msoft-float @gol +-mfused-madd -mno-fused-madd @gol +-mserialize-volatile -mno-serialize-volatile @gol +-mtext-section-literals -mno-text-section-literals @gol +-mtarget-align -mno-target-align @gol +-mlongcalls -mno-longcalls} + +@item Code Generation Options +@xref{Code Gen Options,,Options for Code Generation Conventions}. +@gccoptlist{ +-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol +-ffixed-@var{reg} -fexceptions @gol +-fnon-call-exceptions -funwind-tables @gol +-fasynchronous-unwind-tables @gol +-finhibit-size-directive -finstrument-functions @gol +-fno-common -fno-ident -fno-gnu-linker @gol +-fpcc-struct-return -fpic -fPIC @gol +-freg-struct-return -fshared-data -fshort-enums @gol +-fshort-double -fvolatile @gol +-fvolatile-global -fvolatile-static @gol +-fverbose-asm -fpack-struct -fstack-check @gol +-fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol +-fargument-alias -fargument-noalias @gol +-fargument-noalias-global -fleading-underscore} +@end table + +@menu +* Overall Options:: Controlling the kind of output: + an executable, object files, assembler files, + or preprocessed source. +* C Dialect Options:: Controlling the variant of C language compiled. +* C++ Dialect Options:: Variations on C++. +* Objective-C Dialect Options:: Variations on Objective-C. +* Language Independent Options:: Controlling how diagnostics should be + formatted. +* Warning Options:: How picky should the compiler be? +* Debugging Options:: Symbol tables, measurements, and debugging dumps. +* Optimize Options:: How much optimization? +* Preprocessor Options:: Controlling header files and macro definitions. + Also, getting dependency information for Make. +* Assembler Options:: Passing options to the assembler. +* Link Options:: Specifying libraries and so on. +* Directory Options:: Where to find header files and libraries. + Where to find the compiler executable files. +* Spec Files:: How to pass switches to sub-processes. +* Target Options:: Running a cross-compiler, or an old version of GCC. +@end menu + +@node Overall Options +@section Options Controlling the Kind of Output + +Compilation can involve up to four stages: preprocessing, compilation +proper, assembly and linking, always in that order. The first three +stages apply to an individual source file, and end by producing an +object file; linking combines all the object files (those newly +compiled, and those specified as input) into an executable file. + +@cindex file name suffix +For any given input file, the file name suffix determines what kind of +compilation is done: + +@table @gcctabopt +@item @var{file}.c +C source code which must be preprocessed. + +@item @var{file}.i +C source code which should not be preprocessed. + +@item @var{file}.ii +C++ source code which should not be preprocessed. + +@item @var{file}.m +Objective-C source code. Note that you must link with the library +@file{libobjc.a} to make an Objective-C program work. + +@item @var{file}.mi +Objective-C source code which should not be preprocessed. + +@item @var{file}.h +C header file (not to be compiled or linked). + +@item @var{file}.cc +@itemx @var{file}.cp +@itemx @var{file}.cxx +@itemx @var{file}.cpp +@itemx @var{file}.c++ +@itemx @var{file}.C +C++ source code which must be preprocessed. Note that in @samp{.cxx}, +the last two letters must both be literally @samp{x}. Likewise, +@samp{.C} refers to a literal capital C@. + +@item @var{file}.f +@itemx @var{file}.for +@itemx @var{file}.FOR +Fortran source code which should not be preprocessed. + +@item @var{file}.F +@itemx @var{file}.fpp +@itemx @var{file}.FPP +Fortran source code which must be preprocessed (with the traditional +preprocessor). + +@item @var{file}.r +Fortran source code which must be preprocessed with a RATFOR +preprocessor (not included with GCC)@. + +@xref{Overall Options,,Options Controlling the Kind of Output, g77, +Using and Porting GNU Fortran}, for more details of the handling of +Fortran input files. + +@c FIXME: Descriptions of Java file types. +@c @var{file}.java +@c @var{file}.class +@c @var{file}.zip +@c @var{file}.jar + +@item @var{file}.ads +Ada source code file which contains a library unit declaration (a +declaration of a package, subprogram, or generic, or a generic +instantiation), or a library unit renaming declaration (a package, +generic, or subprogram renaming declaration). Such files are also +called @dfn{specs}. + +@itemx @var{file}.adb +Ada source code file containing a library unit body (a subprogram or +package body). Such files are also called @dfn{bodies}. + +@c GCC also knows about some suffixes for languages not yet included: +@c Pascal: +@c @var{file}.p +@c @var{file}.pas + +@item @var{file}.ch +@itemx @var{file}.chi +CHILL source code (preprocessed with the traditional preprocessor). + +@item @var{file}.s +Assembler code. + +@item @var{file}.S +Assembler code which must be preprocessed. + +@item @var{other} +An object file to be fed straight into linking. +Any file name with no recognized suffix is treated this way. +@end table + +@opindex x +You can specify the input language explicitly with the @option{-x} option: + +@table @gcctabopt +@item -x @var{language} +Specify explicitly the @var{language} for the following input files +(rather than letting the compiler choose a default based on the file +name suffix). This option applies to all following input files until +the next @option{-x} option. Possible values for @var{language} are: +@example +c c-header cpp-output +c++ c++-cpp-output +objective-c objc-cpp-output +assembler assembler-with-cpp +ada +chill +f77 f77-cpp-input ratfor +java +@end example + +@item -x none +Turn off any specification of a language, so that subsequent files are +handled according to their file name suffixes (as they are if @option{-x} +has not been used at all). + +@item -pass-exit-codes +@opindex pass-exit-codes +Normally the @command{gcc} program will exit with the code of 1 if any +phase of the compiler returns a non-success return code. If you specify +@option{-pass-exit-codes}, the @command{gcc} program will instead return with +numerically highest error produced by any phase that returned an error +indication. +@end table + +If you only want some of the stages of compilation, you can use +@option{-x} (or filename suffixes) to tell @command{gcc} where to start, and +one of the options @option{-c}, @option{-S}, or @option{-E} to say where +@command{gcc} is to stop. Note that some combinations (for example, +@samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all. + +@table @gcctabopt +@item -c +@opindex c +Compile or assemble the source files, but do not link. The linking +stage simply is not done. The ultimate output is in the form of an +object file for each source file. + +By default, the object file name for a source file is made by replacing +the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}. + +Unrecognized input files, not requiring compilation or assembly, are +ignored. + +@item -S +@opindex S +Stop after the stage of compilation proper; do not assemble. The output +is in the form of an assembler code file for each non-assembler input +file specified. + +By default, the assembler file name for a source file is made by +replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}. + +Input files that don't require compilation are ignored. + +@item -E +@opindex E +Stop after the preprocessing stage; do not run the compiler proper. The +output is in the form of preprocessed source code, which is sent to the +standard output. + +Input files which don't require preprocessing are ignored. + +@cindex output file option +@item -o @var{file} +@opindex o +Place output in file @var{file}. This applies regardless to whatever +sort of output is being produced, whether it be an executable file, +an object file, an assembler file or preprocessed C code. + +Since only one output file can be specified, it does not make sense to +use @option{-o} when compiling more than one input file, unless you are +producing an executable file as output. + +If @option{-o} is not specified, the default is to put an executable file +in @file{a.out}, the object file for @file{@var{source}.@var{suffix}} in +@file{@var{source}.o}, its assembler file in @file{@var{source}.s}, and +all preprocessed C source on standard output. + +@item -v +@opindex v +Print (on standard error output) the commands executed to run the stages +of compilation. Also print the version number of the compiler driver +program and of the preprocessor and the compiler proper. + +@item -pipe +@opindex pipe +Use pipes rather than temporary files for communication between the +various stages of compilation. This fails to work on some systems where +the assembler is unable to read from a pipe; but the GNU assembler has +no trouble. + +@item --help +@opindex help +Print (on the standard output) a description of the command line options +understood by @command{gcc}. If the @option{-v} option is also specified +then @option{--help} will also be passed on to the various processes +invoked by @command{gcc}, so that they can display the command line options +they accept. If the @option{-W} option is also specified then command +line options which have no documentation associated with them will also +be displayed. + +@item --target-help +@opindex target-help +Print (on the standard output) a description of target specific command +line options for each tool. +@end table + +@node Invoking G++ +@section Compiling C++ Programs + +@cindex suffixes for C++ source +@cindex C++ source file suffixes +C++ source files conventionally use one of the suffixes @samp{.C}, +@samp{.cc}, @samp{.cpp}, @samp{.c++}, @samp{.cp}, or @samp{.cxx}; +preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes +files with these names and compiles them as C++ programs even if you +call the compiler the same way as for compiling C programs (usually with +the name @command{gcc}). + +@findex g++ +@findex c++ +However, C++ programs often require class libraries as well as a +compiler that understands the C++ language---and under some +circumstances, you might want to compile programs from standard input, +or otherwise without a suffix that flags them as C++ programs. +@command{g++} is a program that calls GCC with the default language +set to C++, and automatically specifies linking against the C++ +library. On many systems, @command{g++} is also +installed with the name @command{c++}. + +@cindex invoking @command{g++} +When you compile C++ programs, you may specify many of the same +command-line options that you use for compiling programs in any +language; or command-line options meaningful for C and related +languages; or options that are meaningful only for C++ programs. +@xref{C Dialect Options,,Options Controlling C Dialect}, for +explanations of options for languages related to C@. +@xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for +explanations of options that are meaningful only for C++ programs. + +@node C Dialect Options +@section Options Controlling C Dialect +@cindex dialect options +@cindex language dialect options +@cindex options, dialect + +The following options control the dialect of C (or languages derived +from C, such as C++ and Objective-C) that the compiler accepts: + +@table @gcctabopt +@cindex ANSI support +@cindex ISO support +@item -ansi +@opindex ansi +In C mode, support all ISO C89 programs. In C++ mode, +remove GNU extensions that conflict with ISO C++. + +This turns off certain features of GCC that are incompatible with ISO +C89 (when compiling C code), or of standard C++ (when compiling C++ code), +such as the @code{asm} and @code{typeof} keywords, and +predefined macros such as @code{unix} and @code{vax} that identify the +type of system you are using. It also enables the undesirable and +rarely used ISO trigraph feature. For the C compiler, +it disables recognition of C++ style @samp{//} comments as well as +the @code{inline} keyword. + +The alternate keywords @code{__asm__}, @code{__extension__}, +@code{__inline__} and @code{__typeof__} continue to work despite +@option{-ansi}. You would not want to use them in an ISO C program, of +course, but it is useful to put them in header files that might be included +in compilations done with @option{-ansi}. Alternate predefined macros +such as @code{__unix__} and @code{__vax__} are also available, with or +without @option{-ansi}. + +The @option{-ansi} option does not cause non-ISO programs to be +rejected gratuitously. For that, @option{-pedantic} is required in +addition to @option{-ansi}. @xref{Warning Options}. + +The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi} +option is used. Some header files may notice this macro and refrain +from declaring certain functions or defining certain macros that the +ISO standard doesn't call for; this is to avoid interfering with any +programs that might use these names for other things. + +Functions which would normally be built in but do not have semantics +defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in +functions with @option{-ansi} is used. @xref{Other Builtins,,Other +built-in functions provided by GCC}, for details of the functions +affected. + +@item -std= +@opindex std +Determine the language standard. This option is currently only +supported when compiling C@. A value for this option must be provided; +possible values are + +@table @samp +@item c89 +@itemx iso9899:1990 +ISO C89 (same as @option{-ansi}). + +@item iso9899:199409 +ISO C89 as modified in amendment 1. + +@item c99 +@itemx c9x +@itemx iso9899:1999 +@itemx iso9899:199x +ISO C99. Note that this standard is not yet fully supported; see +@w{@uref{http://gcc.gnu.org/c99status.html}} for more information. The +names @samp{c9x} and @samp{iso9899:199x} are deprecated. + +@item gnu89 +Default, ISO C89 plus GNU extensions (including some C99 features). + +@item gnu99 +@item gnu9x +ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC, +this will become the default. The name @samp{gnu9x} is deprecated. + +@end table + +Even when this option is not specified, you can still use some of the +features of newer standards in so far as they do not conflict with +previous C standards. For example, you may use @code{__restrict__} even +when @option{-std=c99} is not specified. + +The @option{-std} options specifying some version of ISO C have the same +effects as @option{-ansi}, except that features that were not in ISO C89 +but are in the specified version (for example, @samp{//} comments and +the @code{inline} keyword in ISO C99) are not disabled. + +@xref{Standards,,Language Standards Supported by GCC}, for details of +these standard versions. + +@item -aux-info @var{filename} +@opindex aux-info +Output to the given filename prototyped declarations for all functions +declared and/or defined in a translation unit, including those in header +files. This option is silently ignored in any language other than C@. + +Besides declarations, the file indicates, in comments, the origin of +each declaration (source file and line), whether the declaration was +implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or +@samp{O} for old, respectively, in the first character after the line +number and the colon), and whether it came from a declaration or a +definition (@samp{C} or @samp{F}, respectively, in the following +character). In the case of function definitions, a K&R-style list of +arguments followed by their declarations is also provided, inside +comments, after the declaration. + +@item -fno-asm +@opindex fno-asm +Do not recognize @code{asm}, @code{inline} or @code{typeof} as a +keyword, so that code can use these words as identifiers. You can use +the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__} +instead. @option{-ansi} implies @option{-fno-asm}. + +In C++, this switch only affects the @code{typeof} keyword, since +@code{asm} and @code{inline} are standard keywords. You may want to +use the @option{-fno-gnu-keywords} flag instead, which has the same +effect. In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this +switch only affects the @code{asm} and @code{typeof} keywords, since +@code{inline} is a standard keyword in ISO C99. + +@item -fno-builtin +@itemx -fno-builtin-@var{function} @r{(C and Objective-C only)} +@opindex fno-builtin +@cindex built-in functions +Don't recognize built-in functions that do not begin with +@samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in +functions provided by GCC}, for details of the functions affected, +including those which are not built-in functions when @option{-ansi} or +@option{-std} options for strict ISO C conformance are used because they +do not have an ISO standard meaning. + +GCC normally generates special code to handle certain built-in functions +more efficiently; for instance, calls to @code{alloca} may become single +instructions that adjust the stack directly, and calls to @code{memcpy} +may become inline copy loops. The resulting code is often both smaller +and faster, but since the function calls no longer appear as such, you +cannot set a breakpoint on those calls, nor can you change the behavior +of the functions by linking with a different library. + +In C++, @option{-fno-builtin} is always in effect. The @option{-fbuiltin} +option has no effect. Therefore, in C++, the only way to get the +optimization benefits of built-in functions is to call the function +using the @samp{__builtin_} prefix. The GNU C++ Standard Library uses +built-in functions to implement many functions (like +@code{std::strchr}), so that you automatically get efficient code. + +With the @option{-fno-builtin-@var{function}} option, not available +when compiling C++, only the built-in function @var{function} is +disabled. @var{function} must not begin with @samp{__builtin_}. If a +function is named this is not built-in in this version of GCC, this +option is ignored. There is no corresponding +@option{-fbuiltin-@var{function}} option; if you wish to enable +built-in functions selectively when using @option{-fno-builtin} or +@option{-ffreestanding}, you may define macros such as: + +@smallexample +#define abs(n) __builtin_abs ((n)) +#define strcpy(d, s) __builtin_strcpy ((d), (s)) +@end smallexample + +@item -fhosted +@opindex fhosted +@cindex hosted environment + +Assert that compilation takes place in a hosted environment. This implies +@option{-fbuiltin}. A hosted environment is one in which the +entire standard library is available, and in which @code{main} has a return +type of @code{int}. Examples are nearly everything except a kernel. +This is equivalent to @option{-fno-freestanding}. + +@item -ffreestanding +@opindex ffreestanding +@cindex hosted environment + +Assert that compilation takes place in a freestanding environment. This +implies @option{-fno-builtin}. A freestanding environment +is one in which the standard library may not exist, and program startup may +not necessarily be at @code{main}. The most obvious example is an OS kernel. +This is equivalent to @option{-fno-hosted}. + +@xref{Standards,,Language Standards Supported by GCC}, for details of +freestanding and hosted environments. + +@item -trigraphs +@opindex trigraphs +Support ISO C trigraphs. The @option{-ansi} option (and @option{-std} +options for strict ISO C conformance) implies @option{-trigraphs}. + +@cindex traditional C language +@cindex C language, traditional +@item -traditional +@opindex traditional +Attempt to support some aspects of traditional C compilers. +Specifically: + +@itemize @bullet +@item +All @code{extern} declarations take effect globally even if they +are written inside of a function definition. This includes implicit +declarations of functions. + +@item +The newer keywords @code{typeof}, @code{inline}, @code{signed}, @code{const} +and @code{volatile} are not recognized. (You can still use the +alternative keywords such as @code{__typeof__}, @code{__inline__}, and +so on.) + +@item +Comparisons between pointers and integers are always allowed. + +@item +Integer types @code{unsigned short} and @code{unsigned char} promote +to @code{unsigned int}. + +@item +Out-of-range floating point literals are not an error. + +@item +Certain constructs which ISO regards as a single invalid preprocessing +number, such as @samp{0xe-0xd}, are treated as expressions instead. + +@item +String ``constants'' are not necessarily constant; they are stored in +writable space, and identical looking constants are allocated +separately. (This is the same as the effect of +@option{-fwritable-strings}.) + +@cindex @code{longjmp} and automatic variables +@item +All automatic variables not declared @code{register} are preserved by +@code{longjmp}. Ordinarily, GNU C follows ISO C: automatic variables +not declared @code{volatile} may be clobbered. + +@item +@cindex @samp{\x} +@cindex @samp{\a} +@cindex escape sequences, traditional +The character escape sequences @samp{\x} and @samp{\a} evaluate as the +literal characters @samp{x} and @samp{a} respectively. Without +@w{@option{-traditional}}, @samp{\x} is a prefix for the hexadecimal +representation of a character, and @samp{\a} produces a bell. +@end itemize + +This option is deprecated and may be removed. + +You may wish to use @option{-fno-builtin} as well as @option{-traditional} +if your program uses names that are normally GNU C built-in functions for +other purposes of its own. + +You cannot use @option{-traditional} if you include any header files that +rely on ISO C features. Some vendors are starting to ship systems with +ISO C header files and you cannot use @option{-traditional} on such +systems to compile files that include any system headers. + +The @option{-traditional} option also enables @option{-traditional-cpp}. + +@item -traditional-cpp +@opindex traditional-cpp +Attempt to support some aspects of traditional C preprocessors. +See the GNU CPP manual for details. + +@item -fcond-mismatch +@opindex fcond-mismatch +Allow conditional expressions with mismatched types in the second and +third arguments. The value of such an expression is void. This option +is not supported for C++. + +@item -funsigned-char +@opindex funsigned-char +Let the type @code{char} be unsigned, like @code{unsigned char}. + +Each kind of machine has a default for what @code{char} should +be. It is either like @code{unsigned char} by default or like +@code{signed char} by default. + +Ideally, a portable program should always use @code{signed char} or +@code{unsigned char} when it depends on the signedness of an object. +But many programs have been written to use plain @code{char} and +expect it to be signed, or expect it to be unsigned, depending on the +machines they were written for. This option, and its inverse, let you +make such a program work with the opposite default. + +The type @code{char} is always a distinct type from each of +@code{signed char} or @code{unsigned char}, even though its behavior +is always just like one of those two. + +@item -fsigned-char +@opindex fsigned-char +Let the type @code{char} be signed, like @code{signed char}. + +Note that this is equivalent to @option{-fno-unsigned-char}, which is +the negative form of @option{-funsigned-char}. Likewise, the option +@option{-fno-signed-char} is equivalent to @option{-funsigned-char}. + +@item -fsigned-bitfields +@itemx -funsigned-bitfields +@itemx -fno-signed-bitfields +@itemx -fno-unsigned-bitfields +@opindex fsigned-bitfields +@opindex funsigned-bitfields +@opindex fno-signed-bitfields +@opindex fno-unsigned-bitfields +These options control whether a bit-field is signed or unsigned, when the +declaration does not use either @code{signed} or @code{unsigned}. By +default, such a bit-field is signed, because this is consistent: the +basic integer types such as @code{int} are signed types. + +However, when @option{-traditional} is used, bit-fields are all unsigned +no matter what. + +@item -fwritable-strings +@opindex fwritable-strings +Store string constants in the writable data segment and don't uniquize +them. This is for compatibility with old programs which assume they can +write into string constants. The option @option{-traditional} also has +this effect. + +Writing into string constants is a very bad idea; ``constants'' should +be constant. + +@item -fallow-single-precision +@opindex fallow-single-precision +Do not promote single precision math operations to double precision, +even when compiling with @option{-traditional}. + +Traditional K&R C promotes all floating point operations to double +precision, regardless of the sizes of the operands. On the +architecture for which you are compiling, single precision may be faster +than double precision. If you must use @option{-traditional}, but want +to use single precision operations when the operands are single +precision, use this option. This option has no effect when compiling +with ISO or GNU C conventions (the default). + +@item -fshort-wchar +@opindex fshort-wchar +Override the underlying type for @samp{wchar_t} to be @samp{short +unsigned int} instead of the default for the target. This option is +useful for building programs to run under WINE@. +@end table + +@node C++ Dialect Options +@section Options Controlling C++ Dialect + +@cindex compiler options, C++ +@cindex C++ options, command line +@cindex options, C++ +This section describes the command-line options that are only meaningful +for C++ programs; but you can also use most of the GNU compiler options +regardless of what language your program is in. For example, you +might compile a file @code{firstClass.C} like this: + +@example +g++ -g -frepo -O -c firstClass.C +@end example + +@noindent +In this example, only @option{-frepo} is an option meant +only for C++ programs; you can use the other options with any +language supported by GCC@. + +Here is a list of options that are @emph{only} for compiling C++ programs: + +@table @gcctabopt +@item -fno-access-control +@opindex fno-access-control +Turn off all access checking. This switch is mainly useful for working +around bugs in the access control code. + +@item -fcheck-new +@opindex fcheck-new +Check that the pointer returned by @code{operator new} is non-null +before attempting to modify the storage allocated. The current Working +Paper requires that @code{operator new} never return a null pointer, so +this check is normally unnecessary. + +An alternative to using this option is to specify that your +@code{operator new} does not throw any exceptions; if you declare it +@samp{throw()}, G++ will check the return value. See also @samp{new +(nothrow)}. + +@item -fconserve-space +@opindex fconserve-space +Put uninitialized or runtime-initialized global variables into the +common segment, as C does. This saves space in the executable at the +cost of not diagnosing duplicate definitions. If you compile with this +flag and your program mysteriously crashes after @code{main()} has +completed, you may have an object that is being destroyed twice because +two definitions were merged. + +This option is no longer useful on most targets, now that support has +been added for putting variables into BSS without making them common. + +@item -fno-const-strings +@opindex fno-const-strings +Give string constants type @code{char *} instead of type @code{const +char *}. By default, G++ uses type @code{const char *} as required by +the standard. Even if you use @option{-fno-const-strings}, you cannot +actually modify the value of a string constant, unless you also use +@option{-fwritable-strings}. + +This option might be removed in a future release of G++. For maximum +portability, you should structure your code so that it works with +string constants that have type @code{const char *}. + +@item -fdollars-in-identifiers +@opindex fdollars-in-identifiers +Accept @samp{$} in identifiers. You can also explicitly prohibit use of +@samp{$} with the option @option{-fno-dollars-in-identifiers}. (GNU C allows +@samp{$} by default on most target systems, but there are a few exceptions.) +Traditional C allowed the character @samp{$} to form part of +identifiers. However, ISO C and C++ forbid @samp{$} in identifiers. + +@item -fno-elide-constructors +@opindex fno-elide-constructors +The C++ standard allows an implementation to omit creating a temporary +which is only used to initialize another object of the same type. +Specifying this option disables that optimization, and forces G++ to +call the copy constructor in all cases. + +@item -fno-enforce-eh-specs +@opindex fno-enforce-eh-specs +Don't check for violation of exception specifications at runtime. This +option violates the C++ standard, but may be useful for reducing code +size in production builds, much like defining @samp{NDEBUG}. The compiler +will still optimize based on the exception specifications. + +@item -fexternal-templates +@opindex fexternal-templates + +Cause @samp{#pragma interface} and @samp{implementation} to apply to +template instantiation; template instances are emitted or not according +to the location of the template definition. @xref{Template +Instantiation}, for more information. + +This option is deprecated. + +@item -falt-external-templates +@opindex falt-external-templates +Similar to @option{-fexternal-templates}, but template instances are +emitted or not according to the place where they are first instantiated. +@xref{Template Instantiation}, for more information. + +This option is deprecated. + +@item -ffor-scope +@itemx -fno-for-scope +@opindex ffor-scope +@opindex fno-for-scope +If @option{-ffor-scope} is specified, the scope of variables declared in +a @i{for-init-statement} is limited to the @samp{for} loop itself, +as specified by the C++ standard. +If @option{-fno-for-scope} is specified, the scope of variables declared in +a @i{for-init-statement} extends to the end of the enclosing scope, +as was the case in old versions of G++, and other (traditional) +implementations of C++. + +The default if neither flag is given to follow the standard, +but to allow and give a warning for old-style code that would +otherwise be invalid, or have different behavior. + +@item -fno-gnu-keywords +@opindex fno-gnu-keywords +Do not recognize @code{typeof} as a keyword, so that code can use this +word as an identifier. You can use the keyword @code{__typeof__} instead. +@option{-ansi} implies @option{-fno-gnu-keywords}. + +@item -fno-implicit-templates +@opindex fno-implicit-templates +Never emit code for non-inline templates which are instantiated +implicitly (i.e.@: by use); only emit code for explicit instantiations. +@xref{Template Instantiation}, for more information. + +@item -fno-implicit-inline-templates +@opindex fno-implicit-inline-templates +Don't emit code for implicit instantiations of inline templates, either. +The default is to handle inlines differently so that compiles with and +without optimization will need the same set of explicit instantiations. + +@item -fno-implement-inlines +@opindex fno-implement-inlines +To save space, do not emit out-of-line copies of inline functions +controlled by @samp{#pragma implementation}. This will cause linker +errors if these functions are not inlined everywhere they are called. + +@item -fms-extensions +@opindex fms-extensions +Disable pedantic warnings about constructs used in MFC, such as implicit +int and getting a pointer to member function via non-standard syntax. + +@item -fno-nonansi-builtins +@opindex fno-nonansi-builtins +Disable built-in declarations of functions that are not mandated by +ANSI/ISO C@. These include @code{ffs}, @code{alloca}, @code{_exit}, +@code{index}, @code{bzero}, @code{conjf}, and other related functions. + +@item -fno-operator-names +@opindex fno-operator-names +Do not treat the operator name keywords @code{and}, @code{bitand}, +@code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as +synonyms as keywords. + +@item -fno-optional-diags +@opindex fno-optional-diags +Disable diagnostics that the standard says a compiler does not need to +issue. Currently, the only such diagnostic issued by G++ is the one for +a name having multiple meanings within a class. + +@item -fpermissive +@opindex fpermissive +Downgrade messages about nonconformant code from errors to warnings. By +default, G++ effectively sets @option{-pedantic-errors} without +@option{-pedantic}; this option reverses that. This behavior and this +option are superseded by @option{-pedantic}, which works as it does for GNU C@. + +@item -frepo +@opindex frepo +Enable automatic template instantiation at link time. This option also +implies @option{-fno-implicit-templates}. @xref{Template +Instantiation}, for more information. + +@item -fno-rtti +@opindex fno-rtti +Disable generation of information about every class with virtual +functions for use by the C++ runtime type identification features +(@samp{dynamic_cast} and @samp{typeid}). If you don't use those parts +of the language, you can save some space by using this flag. Note that +exception handling uses the same information, but it will generate it as +needed. + +@item -fstats +@opindex fstats +Emit statistics about front-end processing at the end of the compilation. +This information is generally only useful to the G++ development team. + +@item -ftemplate-depth-@var{n} +@opindex ftemplate-depth +Set the maximum instantiation depth for template classes to @var{n}. +A limit on the template instantiation depth is needed to detect +endless recursions during template class instantiation. ANSI/ISO C++ +conforming programs must not rely on a maximum depth greater than 17. + +@item -fuse-cxa-atexit +@opindex fuse-cxa-atexit +Register destructors for objects with static storage duration with the +@code{__cxa_atexit} function rather than the @code{atexit} function. +This option is required for fully standards-compliant handling of static +destructors, but will only work if your C library supports +@code{__cxa_atexit}. + +@item -fvtable-gc +@opindex fvtable-gc +Emit special relocations for vtables and virtual function references +so that the linker can identify unused virtual functions and zero out +vtable slots that refer to them. This is most useful with +@option{-ffunction-sections} and @option{-Wl,--gc-sections}, in order to +also discard the functions themselves. + +This optimization requires GNU as and GNU ld. Not all systems support +this option. @option{-Wl,--gc-sections} is ignored without @option{-static}. + +@item -fno-weak +@opindex fno-weak +Do not use weak symbol support, even if it is provided by the linker. +By default, G++ will use weak symbols if they are available. This +option exists only for testing, and should not be used by end-users; +it will result in inferior code and has no benefits. This option may +be removed in a future release of G++. + +@item -nostdinc++ +@opindex nostdinc++ +Do not search for header files in the standard directories specific to +C++, but do still search the other standard directories. (This option +is used when building the C++ library.) +@end table + +In addition, these optimization, warning, and code generation options +have meanings only for C++ programs: + +@table @gcctabopt +@item -fno-default-inline +@opindex fno-default-inline +Do not assume @samp{inline} for functions defined inside a class scope. +@xref{Optimize Options,,Options That Control Optimization}. Note that these +functions will have linkage like inline functions; they just won't be +inlined by default. + +@item -Wctor-dtor-privacy @r{(C++ only)} +@opindex Wctor-dtor-privacy +Warn when a class seems unusable, because all the constructors or +destructors in a class are private and the class has no friends or +public static member functions. + +@item -Wnon-virtual-dtor @r{(C++ only)} +@opindex Wnon-virtual-dtor +Warn when a class declares a non-virtual destructor that should probably +be virtual, because it looks like the class will be used polymorphically. + +@item -Wreorder @r{(C++ only)} +@opindex Wreorder +@cindex reordering, warning +@cindex warning for reordering of member initializers +Warn when the order of member initializers given in the code does not +match the order in which they must be executed. For instance: + +@smallexample +struct A @{ + int i; + int j; + A(): j (0), i (1) @{ @} +@}; +@end smallexample + +Here the compiler will warn that the member initializers for @samp{i} +and @samp{j} will be rearranged to match the declaration order of the +members. +@end table + +The following @option{-W@dots{}} options are not affected by @option{-Wall}. + +@table @gcctabopt +@item -Weffc++ @r{(C++ only)} +@opindex Weffc++ +Warn about violations of various style guidelines from Scott Meyers' +@cite{Effective C++} books. If you use this option, you should be aware +that the standard library headers do not obey all of these guidelines; +you can use @samp{grep -v} to filter out those warnings. + +@item -Wno-deprecated @r{(C++ only)} +@opindex Wno-deprecated +Do not warn about usage of deprecated features. @xref{Deprecated Features}. + +@item -Wno-non-template-friend @r{(C++ only)} +@opindex Wno-non-template-friend +Disable warnings when non-templatized friend functions are declared +within a template. With the advent of explicit template specification +support in G++, if the name of the friend is an unqualified-id (i.e., +@samp{friend foo(int)}), the C++ language specification demands that the +friend declare or define an ordinary, nontemplate function. (Section +14.5.3). Before G++ implemented explicit specification, unqualified-ids +could be interpreted as a particular specialization of a templatized +function. Because this non-conforming behavior is no longer the default +behavior for G++, @option{-Wnon-template-friend} allows the compiler to +check existing code for potential trouble spots, and is on by default. +This new compiler behavior can be turned off with +@option{-Wno-non-template-friend} which keeps the conformant compiler code +but disables the helpful warning. + +@item -Wold-style-cast @r{(C++ only)} +@opindex Wold-style-cast +Warn if an old-style (C-style) cast to a non-void type is used within +a C++ program. The new-style casts (@samp{static_cast}, +@samp{reinterpret_cast}, and @samp{const_cast}) are less vulnerable to +unintended effects, and much easier to grep for. + +@item -Woverloaded-virtual @r{(C++ only)} +@opindex Woverloaded-virtual +@cindex overloaded virtual fn, warning +@cindex warning for overloaded virtual fn +Warn when a function declaration hides virtual functions from a +base class. For example, in: + +@smallexample +struct A @{ + virtual void f(); +@}; + +struct B: public A @{ + void f(int); +@}; +@end smallexample + +the @code{A} class version of @code{f} is hidden in @code{B}, and code +like this: + +@smallexample +B* b; +b->f(); +@end smallexample + +will fail to compile. + +@item -Wno-pmf-conversions @r{(C++ only)} +@opindex Wno-pmf-conversions +Disable the diagnostic for converting a bound pointer to member function +to a plain pointer. + +@item -Wsign-promo @r{(C++ only)} +@opindex Wsign-promo +Warn when overload resolution chooses a promotion from unsigned or +enumeral type to a signed type over a conversion to an unsigned type of +the same size. Previous versions of G++ would try to preserve +unsignedness, but the standard mandates the current behavior. + +@item -Wsynth @r{(C++ only)} +@opindex Wsynth +@cindex warning for synthesized methods +@cindex synthesized methods, warning +Warn when G++'s synthesis behavior does not match that of cfront. For +instance: + +@smallexample +struct A @{ + operator int (); + A& operator = (int); +@}; + +main () +@{ + A a,b; + a = b; +@} +@end smallexample + +In this example, G++ will synthesize a default @samp{A& operator = +(const A&);}, while cfront will use the user-defined @samp{operator =}. +@end table + +@node Objective-C Dialect Options +@section Options Controlling Objective-C Dialect + +@cindex compiler options, Objective-C +@cindex Objective-C options, command line +@cindex options, Objective-C +This section describes the command-line options that are only meaningful +for Objective-C programs; but you can also use most of the GNU compiler +options regardless of what language your program is in. For example, +you might compile a file @code{some_class.m} like this: + +@example +gcc -g -fgnu-runtime -O -c some_class.m +@end example + +@noindent +In this example, only @option{-fgnu-runtime} is an option meant only for +Objective-C programs; you can use the other options with any language +supported by GCC@. + +Here is a list of options that are @emph{only} for compiling Objective-C +programs: + +@table @gcctabopt +@item -fconstant-string-class=@var{class-name} +@opindex fconstant-string-class +Use @var{class-name} as the name of the class to instantiate for each +literal string specified with the syntax @code{@@"@dots{}"}. The default +class name is @code{NXConstantString}. + +@item -fgnu-runtime +@opindex fgnu-runtime +Generate object code compatible with the standard GNU Objective-C +runtime. This is the default for most types of systems. + +@item -fnext-runtime +@opindex fnext-runtime +Generate output compatible with the NeXT runtime. This is the default +for NeXT-based systems, including Darwin and Mac OS X@. + +@item -gen-decls +@opindex gen-decls +Dump interface declarations for all classes seen in the source file to a +file named @file{@var{sourcename}.decl}. + +@item -Wno-protocol +@opindex Wno-protocol +Do not warn if methods required by a protocol are not implemented +in the class adopting it. + +@item -Wselector +@opindex Wselector +Warn if a selector has multiple methods of different types defined. + +@c not documented because only avail via -Wp +@c @item -print-objc-runtime-info + +@end table + +@node Language Independent Options +@section Options to Control Diagnostic Messages Formatting +@cindex options to control diagnostics formatting +@cindex diagnostic messages +@cindex message formatting + +Traditionally, diagnostic messages have been formatted irrespective of +the output device's aspect (e.g.@: its width, @dots{}). The options described +below can be used to control the diagnostic messages formatting +algorithm, e.g.@: how many characters per line, how often source location +information should be reported. Right now, only the C++ front end can +honor these options. However it is expected, in the near future, that +the remaining front ends would be able to digest them correctly. + +@table @gcctabopt +@item -fmessage-length=@var{n} +@opindex fmessage-length +Try to format error messages so that they fit on lines of about @var{n} +characters. The default is 72 characters for @command{g++} and 0 for the rest of +the front ends supported by GCC@. If @var{n} is zero, then no +line-wrapping will be done; each error message will appear on a single +line. + +@opindex fdiagnostics-show-location +@item -fdiagnostics-show-location=once +Only meaningful in line-wrapping mode. Instructs the diagnostic messages +reporter to emit @emph{once} source location information; that is, in +case the message is too long to fit on a single physical line and has to +be wrapped, the source location won't be emitted (as prefix) again, +over and over, in subsequent continuation lines. This is the default +behavior. + +@item -fdiagnostics-show-location=every-line +Only meaningful in line-wrapping mode. Instructs the diagnostic +messages reporter to emit the same source location information (as +prefix) for physical lines that result from the process of breaking +a message which is too long to fit on a single line. + +@end table + +@node Warning Options +@section Options to Request or Suppress Warnings +@cindex options to control warnings +@cindex warning messages +@cindex messages, warning +@cindex suppressing warnings + +Warnings are diagnostic messages that report constructions which +are not inherently erroneous but which are risky or suggest there +may have been an error. + +You can request many specific warnings with options beginning @samp{-W}, +for example @option{-Wimplicit} to request warnings on implicit +declarations. Each of these specific warning options also has a +negative form beginning @samp{-Wno-} to turn off warnings; +for example, @option{-Wno-implicit}. This manual lists only one of the +two forms, whichever is not the default. + +These options control the amount and kinds of warnings produced by GCC: + +@table @gcctabopt +@cindex syntax checking +@item -fsyntax-only +@opindex fsyntax-only +Check the code for syntax errors, but don't do anything beyond that. + +@item -pedantic +@opindex pedantic +Issue all the warnings demanded by strict ISO C and ISO C++; +reject all programs that use forbidden extensions, and some other +programs that do not follow ISO C and ISO C++. For ISO C, follows the +version of the ISO C standard specified by any @option{-std} option used. + +Valid ISO C and ISO C++ programs should compile properly with or without +this option (though a rare few will require @option{-ansi} or a +@option{-std} option specifying the required version of ISO C)@. However, +without this option, certain GNU extensions and traditional C and C++ +features are supported as well. With this option, they are rejected. + +@option{-pedantic} does not cause warning messages for use of the +alternate keywords whose names begin and end with @samp{__}. Pedantic +warnings are also disabled in the expression that follows +@code{__extension__}. However, only system header files should use +these escape routes; application programs should avoid them. +@xref{Alternate Keywords}. + +Some users try to use @option{-pedantic} to check programs for strict ISO +C conformance. They soon find that it does not do quite what they want: +it finds some non-ISO practices, but not all---only those for which +ISO C @emph{requires} a diagnostic, and some others for which +diagnostics have been added. + +A feature to report any failure to conform to ISO C might be useful in +some instances, but would require considerable additional work and would +be quite different from @option{-pedantic}. We don't have plans to +support such a feature in the near future. + +Where the standard specified with @option{-std} represents a GNU +extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a +corresponding @dfn{base standard}, the version of ISO C on which the GNU +extended dialect is based. Warnings from @option{-pedantic} are given +where they are required by the base standard. (It would not make sense +for such warnings to be given only for features not in the specified GNU +C dialect, since by definition the GNU dialects of C include all +features the compiler supports with the given option, and there would be +nothing to warn about.) + +@item -pedantic-errors +@opindex pedantic-errors +Like @option{-pedantic}, except that errors are produced rather than +warnings. + +@item -w +@opindex w +Inhibit all warning messages. + +@item -Wno-import +@opindex Wno-import +Inhibit warning messages about the use of @samp{#import}. + +@item -Wchar-subscripts +@opindex Wchar-subscripts +Warn if an array subscript has type @code{char}. This is a common cause +of error, as programmers often forget that this type is signed on some +machines. + +@item -Wcomment +@opindex Wcomment +Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*} +comment, or whenever a Backslash-Newline appears in a @samp{//} comment. + +@item -Wformat +@opindex Wformat +Check calls to @code{printf} and @code{scanf}, etc., to make sure that +the arguments supplied have types appropriate to the format string +specified, and that the conversions specified in the format string make +sense. This includes standard functions, and others specified by format +attributes (@pxref{Function Attributes}), in the @code{printf}, +@code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension, +not in the C standard) families. + +The formats are checked against the format features supported by GNU +libc version 2.2. These include all ISO C89 and C99 features, as well +as features from the Single Unix Specification and some BSD and GNU +extensions. Other library implementations may not support all these +features; GCC does not support warning about features that go beyond a +particular library's limitations. However, if @option{-pedantic} is used +with @option{-Wformat}, warnings will be given about format features not +in the selected standard version (but not for @code{strfmon} formats, +since those are not in any version of the C standard). @xref{C Dialect +Options,,Options Controlling C Dialect}. + +@option{-Wformat} is included in @option{-Wall}. For more control over some +aspects of format checking, the options @option{-Wno-format-y2k}, +@option{-Wno-format-extra-args}, @option{-Wformat-nonliteral}, +@option{-Wformat-security} and @option{-Wformat=2} are available, but are +not included in @option{-Wall}. + +@item -Wno-format-y2k +@opindex Wno-format-y2k +If @option{-Wformat} is specified, do not warn about @code{strftime} +formats which may yield only a two-digit year. + +@item -Wno-format-extra-args +@opindex Wno-format-extra-args +If @option{-Wformat} is specified, do not warn about excess arguments to a +@code{printf} or @code{scanf} format function. The C standard specifies +that such arguments are ignored. + +Where the unused arguments lie between used arguments that are +specified with @samp{$} operand number specifications, normally +warnings are still given, since the implementation could not know what +type to pass to @code{va_arg} to skip the unused arguments. However, +in the case of @code{scanf} formats, this option will suppress the +warning if the unused arguments are all pointers, since the Single +Unix Specification says that such unused arguments are allowed. + +@item -Wformat-nonliteral +@opindex Wformat-nonliteral +If @option{-Wformat} is specified, also warn if the format string is not a +string literal and so cannot be checked, unless the format function +takes its format arguments as a @code{va_list}. + +@item -Wformat-security +@opindex Wformat-security +If @option{-Wformat} is specified, also warn about uses of format +functions that represent possible security problems. At present, this +warns about calls to @code{printf} and @code{scanf} functions where the +format string is not a string literal and there are no format arguments, +as in @code{printf (foo);}. This may be a security hole if the format +string came from untrusted input and contains @samp{%n}. (This is +currently a subset of what @option{-Wformat-nonliteral} warns about, but +in future warnings may be added to @option{-Wformat-security} that are not +included in @option{-Wformat-nonliteral}.) + +@item -Wformat=2 +@opindex Wformat=2 +Enable @option{-Wformat} plus format checks not included in +@option{-Wformat}. Currently equivalent to @samp{-Wformat +-Wformat-nonliteral -Wformat-security}. + +@item -Wimplicit-int +@opindex Wimplicit-int +Warn when a declaration does not specify a type. + +@item -Wimplicit-function-declaration +@itemx -Werror-implicit-function-declaration +@opindex Wimplicit-function-declaration +@opindex Werror-implicit-function-declaration +Give a warning (or error) whenever a function is used before being +declared. + +@item -Wimplicit +@opindex Wimplicit +Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}. + +@item -Wmain +@opindex Wmain +Warn if the type of @samp{main} is suspicious. @samp{main} should be a +function with external linkage, returning int, taking either zero +arguments, two, or three arguments of appropriate types. + +@item -Wmissing-braces +@opindex Wmissing-braces +Warn if an aggregate or union initializer is not fully bracketed. In +the following example, the initializer for @samp{a} is not fully +bracketed, but that for @samp{b} is fully bracketed. + +@smallexample +int a[2][2] = @{ 0, 1, 2, 3 @}; +int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @}; +@end smallexample + +@item -Wparentheses +@opindex Wparentheses +Warn if parentheses are omitted in certain contexts, such +as when there is an assignment in a context where a truth value +is expected, or when operators are nested whose precedence people +often get confused about. + +Also warn about constructions where there may be confusion to which +@code{if} statement an @code{else} branch belongs. Here is an example of +such a case: + +@smallexample +@group +@{ + if (a) + if (b) + foo (); + else + bar (); +@} +@end group +@end smallexample + +In C, every @code{else} branch belongs to the innermost possible @code{if} +statement, which in this example is @code{if (b)}. This is often not +what the programmer expected, as illustrated in the above example by +indentation the programmer chose. When there is the potential for this +confusion, GCC will issue a warning when this flag is specified. +To eliminate the warning, add explicit braces around the innermost +@code{if} statement so there is no way the @code{else} could belong to +the enclosing @code{if}. The resulting code would look like this: + +@smallexample +@group +@{ + if (a) + @{ + if (b) + foo (); + else + bar (); + @} +@} +@end group +@end smallexample + +@item -Wsequence-point +@opindex Wsequence-point +Warn about code that may have undefined semantics because of violations +of sequence point rules in the C standard. + +The C standard defines the order in which expressions in a C program are +evaluated in terms of @dfn{sequence points}, which represent a partial +ordering between the execution of parts of the program: those executed +before the sequence point, and those executed after it. These occur +after the evaluation of a full expression (one which is not part of a +larger expression), after the evaluation of the first operand of a +@code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a +function is called (but after the evaluation of its arguments and the +expression denoting the called function), and in certain other places. +Other than as expressed by the sequence point rules, the order of +evaluation of subexpressions of an expression is not specified. All +these rules describe only a partial order rather than a total order, +since, for example, if two functions are called within one expression +with no sequence point between them, the order in which the functions +are called is not specified. However, the standards committee have +ruled that function calls do not overlap. + +It is not specified when between sequence points modifications to the +values of objects take effect. Programs whose behavior depends on this +have undefined behavior; the C standard specifies that ``Between the +previous and next sequence point an object shall have its stored value +modified at most once by the evaluation of an expression. Furthermore, +the prior value shall be read only to determine the value to be +stored.''. If a program breaks these rules, the results on any +particular implementation are entirely unpredictable. + +Examples of code with undefined behavior are @code{a = a++;}, @code{a[n] += b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not +diagnosed by this option, and it may give an occasional false positive +result, but in general it has been found fairly effective at detecting +this sort of problem in programs. + +The present implementation of this option only works for C programs. A +future implementation may also work for C++ programs. + +The C standard is worded confusingly, therefore there is some debate +over the precise meaning of the sequence point rules in subtle cases. +Links to discussions of the problem, including proposed formal +definitions, may be found on our readings page, at +@w{@uref{http://gcc.gnu.org/readings.html}}. + +@item -Wreturn-type +@opindex Wreturn-type +Warn whenever a function is defined with a return-type that defaults to +@code{int}. Also warn about any @code{return} statement with no +return-value in a function whose return-type is not @code{void}. + +For C++, a function without return type always produces a diagnostic +message, even when @option{-Wno-return-type} is specified. The only +exceptions are @samp{main} and functions defined in system headers. + +@item -Wswitch +@opindex Wswitch +Warn whenever a @code{switch} statement has an index of enumeral type +and lacks a @code{case} for one or more of the named codes of that +enumeration. (The presence of a @code{default} label prevents this +warning.) @code{case} labels outside the enumeration range also +provoke warnings when this option is used. + +@item -Wtrigraphs +@opindex Wtrigraphs +Warn if any trigraphs are encountered that might change the meaning of +the program (trigraphs within comments are not warned about). + +@item -Wunused-function +@opindex Wunused-function +Warn whenever a static function is declared but not defined or a +non\-inline static function is unused. + +@item -Wunused-label +@opindex Wunused-label +Warn whenever a label is declared but not used. + +To suppress this warning use the @samp{unused} attribute +(@pxref{Variable Attributes}). + +@item -Wunused-parameter +@opindex Wunused-parameter +Warn whenever a function parameter is unused aside from its declaration. + +To suppress this warning use the @samp{unused} attribute +(@pxref{Variable Attributes}). + +@item -Wunused-variable +@opindex Wunused-variable +Warn whenever a local variable or non-constant static variable is unused +aside from its declaration + +To suppress this warning use the @samp{unused} attribute +(@pxref{Variable Attributes}). + +@item -Wunused-value +@opindex Wunused-value +Warn whenever a statement computes a result that is explicitly not used. + +To suppress this warning cast the expression to @samp{void}. + +@item -Wunused +@opindex Wunused +All all the above @option{-Wunused} options combined. + +In order to get a warning about an unused function parameter, you must +either specify @samp{-W -Wunused} or separately specify +@option{-Wunused-parameter}. + +@item -Wuninitialized +@opindex Wuninitialized +Warn if an automatic variable is used without first being initialized or +if a variable may be clobbered by a @code{setjmp} call. + +These warnings are possible only in optimizing compilation, +because they require data flow information that is computed only +when optimizing. If you don't specify @option{-O}, you simply won't +get these warnings. + +These warnings occur only for variables that are candidates for +register allocation. Therefore, they do not occur for a variable that +is declared @code{volatile}, or whose address is taken, or whose size +is other than 1, 2, 4 or 8 bytes. Also, they do not occur for +structures, unions or arrays, even when they are in registers. + +Note that there may be no warning about a variable that is used only +to compute a value that itself is never used, because such +computations may be deleted by data flow analysis before the warnings +are printed. + +These warnings are made optional because GCC is not smart +enough to see all the reasons why the code might be correct +despite appearing to have an error. Here is one example of how +this can happen: + +@smallexample +@group +@{ + int x; + switch (y) + @{ + case 1: x = 1; + break; + case 2: x = 4; + break; + case 3: x = 5; + @} + foo (x); +@} +@end group +@end smallexample + +@noindent +If the value of @code{y} is always 1, 2 or 3, then @code{x} is +always initialized, but GCC doesn't know this. Here is +another common case: + +@smallexample +@{ + int save_y; + if (change_y) save_y = y, y = new_y; + @dots{} + if (change_y) y = save_y; +@} +@end smallexample + +@noindent +This has no bug because @code{save_y} is used only if it is set. + +@cindex @code{longjmp} warnings +This option also warns when a non-volatile automatic variable might be +changed by a call to @code{longjmp}. These warnings as well are possible +only in optimizing compilation. + +The compiler sees only the calls to @code{setjmp}. It cannot know +where @code{longjmp} will be called; in fact, a signal handler could +call it at any point in the code. As a result, you may get a warning +even when there is in fact no problem because @code{longjmp} cannot +in fact be called at the place which would cause a problem. + +Some spurious warnings can be avoided if you declare all the functions +you use that never return as @code{noreturn}. @xref{Function +Attributes}. + +@item -Wreorder @r{(C++ only)} +@opindex Wreorder +@cindex reordering, warning +@cindex warning for reordering of member initializers +Warn when the order of member initializers given in the code does not +match the order in which they must be executed. For instance: + +@item -Wunknown-pragmas +@opindex Wunknown-pragmas +@cindex warning for unknown pragmas +@cindex unknown pragmas, warning +@cindex pragmas, warning of unknown +Warn when a #pragma directive is encountered which is not understood by +GCC@. If this command line option is used, warnings will even be issued +for unknown pragmas in system header files. This is not the case if +the warnings were only enabled by the @option{-Wall} command line option. + +@item -Wall +@opindex Wall +All of the above @samp{-W} options combined. This enables all the +warnings about constructions that some users consider questionable, and +that are easy to avoid (or modify to prevent the warning), even in +conjunction with macros. + +@item -Wdiv-by-zero +@opindex Wno-div-by-zero +@opindex Wdiv-by-zero +Warn about compile-time integer division by zero. This is default. To +inhibit the warning messages, use @option{-Wno-div-by-zero}. Floating +point division by zero is not warned about, as it can be a legitimate +way of obtaining infinities and NaNs. + +@item -Wmultichar +@opindex Wno-multichar +@opindex Wmultichar +Warn if a multicharacter constant (@samp{'FOOF'}) is used. This is +default. To inhibit the warning messages, use @option{-Wno-multichar}. +Usually they indicate a typo in the user's code, as they have +implementation-defined values, and should not be used in portable code. + +@item -Wsystem-headers +@opindex Wsystem-headers +@cindex warnings from system headers +@cindex system headers, warnings from +Print warning messages for constructs found in system header files. +Warnings from system headers are normally suppressed, on the assumption +that they usually do not indicate real problems and would only make the +compiler output harder to read. Using this command line option tells +GCC to emit warnings from system headers as if they occurred in user +code. However, note that using @option{-Wall} in conjunction with this +option will @emph{not} warn about unknown pragmas in system +headers---for that, @option{-Wunknown-pragmas} must also be used. +@end table + +The following @option{-W@dots{}} options are not implied by @option{-Wall}. +Some of them warn about constructions that users generally do not +consider questionable, but which occasionally you might wish to check +for; others warn about constructions that are necessary or hard to avoid +in some cases, and there is no simple way to modify the code to suppress +the warning. + +@table @gcctabopt +@item -W +@opindex W +Print extra warning messages for these events: + +@itemize @bullet +@item +A function can return either with or without a value. (Falling +off the end of the function body is considered returning without +a value.) For example, this function would evoke such a +warning: + +@smallexample +@group +foo (a) +@{ + if (a > 0) + return a; +@} +@end group +@end smallexample + +@item +An expression-statement or the left-hand side of a comma expression +contains no side effects. +To suppress the warning, cast the unused expression to void. +For example, an expression such as @samp{x[i,j]} will cause a warning, +but @samp{x[(void)i,j]} will not. + +@item +An unsigned value is compared against zero with @samp{<} or @samp{<=}. + +@item +A comparison like @samp{x<=y<=z} appears; this is equivalent to +@samp{(x<=y ? 1 : 0) <= z}, which is a different interpretation from +that of ordinary mathematical notation. + +@item +Storage-class specifiers like @code{static} are not the first things in +a declaration. According to the C Standard, this usage is obsolescent. + +@item +The return type of a function has a type qualifier such as @code{const}. +Such a type qualifier has no effect, since the value returned by a +function is not an lvalue. (But don't warn about the GNU extension of +@code{volatile void} return types. That extension will be warned about +if @option{-pedantic} is specified.) + +@item +If @option{-Wall} or @option{-Wunused} is also specified, warn about unused +arguments. + +@item +A comparison between signed and unsigned values could produce an +incorrect result when the signed value is converted to unsigned. +(But don't warn if @option{-Wno-sign-compare} is also specified.) + +@item +An aggregate has a partly bracketed initializer. +For example, the following code would evoke such a warning, +because braces are missing around the initializer for @code{x.h}: + +@smallexample +struct s @{ int f, g; @}; +struct t @{ struct s h; int i; @}; +struct t x = @{ 1, 2, 3 @}; +@end smallexample + +@item +An aggregate has an initializer which does not initialize all members. +For example, the following code would cause such a warning, because +@code{x.h} would be implicitly initialized to zero: + +@smallexample +struct s @{ int f, g, h; @}; +struct s x = @{ 3, 4 @}; +@end smallexample +@end itemize + +@item -Wfloat-equal +@opindex Wfloat-equal +Warn if floating point values are used in equality comparisons. + +The idea behind this is that sometimes it is convenient (for the +programmer) to consider floating-point values as approximations to +infinitely precise real numbers. If you are doing this, then you need +to compute (by analysing the code, or in some other way) the maximum or +likely maximum error that the computation introduces, and allow for it +when performing comparisons (and when producing output, but that's a +different problem). In particular, instead of testing for equality, you +would check to see whether the two values have ranges that overlap; and +this is done with the relational operators, so equality comparisons are +probably mistaken. + +@item -Wtraditional @r{(C only)} +@opindex Wtraditional +Warn about certain constructs that behave differently in traditional and +ISO C@. Also warn about ISO C constructs that have no traditional C +equivalent, and/or problematic constructs which should be avoided. + +@itemize @bullet +@item +Macro parameters that appear within string literals in the macro body. +In traditional C macro replacement takes place within string literals, +but does not in ISO C@. + +@item +In traditional C, some preprocessor directives did not exist. +Traditional preprocessors would only consider a line to be a directive +if the @samp{#} appeared in column 1 on the line. Therefore +@option{-Wtraditional} warns about directives that traditional C +understands but would ignore because the @samp{#} does not appear as the +first character on the line. It also suggests you hide directives like +@samp{#pragma} not understood by traditional C by indenting them. Some +traditional implementations would not recognize @samp{#elif}, so it +suggests avoiding it altogether. + +@item +A function-like macro that appears without arguments. + +@item +The unary plus operator. + +@item +The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point +constant suffixes. (Traditional C does support the @samp{L} suffix on integer +constants.) Note, these suffixes appear in macros defined in the system +headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}. +Use of these macros in user code might normally lead to spurious +warnings, however gcc's integrated preprocessor has enough context to +avoid warning in these cases. + +@item +A function declared external in one block and then used after the end of +the block. + +@item +A @code{switch} statement has an operand of type @code{long}. + +@item +A non-@code{static} function declaration follows a @code{static} one. +This construct is not accepted by some traditional C compilers. + +@item +The ISO type of an integer constant has a different width or +signedness from its traditional type. This warning is only issued if +the base of the constant is ten. I.e.@: hexadecimal or octal values, which +typically represent bit patterns, are not warned about. + +@item +Usage of ISO string concatenation is detected. + +@item +Initialization of automatic aggregates. + +@item +Identifier conflicts with labels. Traditional C lacks a separate +namespace for labels. + +@item +Initialization of unions. If the initializer is zero, the warning is +omitted. This is done under the assumption that the zero initializer in +user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing +initializer warnings and relies on default initialization to zero in the +traditional C case. + +@item +Conversions by prototypes between fixed/floating point values and vice +versa. The absence of these prototypes when compiling with traditional +C would cause serious problems. This is a subset of the possible +conversion warnings, for the full set use @option{-Wconversion}. +@end itemize + +@item -Wundef +@opindex Wundef +Warn if an undefined identifier is evaluated in an @samp{#if} directive. + +@item -Wshadow +@opindex Wshadow +Warn whenever a local variable shadows another local variable, parameter or +global variable or whenever a built-in function is shadowed. + +@item -Wlarger-than-@var{len} +@opindex Wlarger-than +Warn whenever an object of larger than @var{len} bytes is defined. + +@item -Wpointer-arith +@opindex Wpointer-arith +Warn about anything that depends on the ``size of'' a function type or +of @code{void}. GNU C assigns these types a size of 1, for +convenience in calculations with @code{void *} pointers and pointers +to functions. + +@item -Wbad-function-cast @r{(C only)} +@opindex Wbad-function-cast +Warn whenever a function call is cast to a non-matching type. +For example, warn if @code{int malloc()} is cast to @code{anything *}. + +@item -Wcast-qual +@opindex Wcast-qual +Warn whenever a pointer is cast so as to remove a type qualifier from +the target type. For example, warn if a @code{const char *} is cast +to an ordinary @code{char *}. + +@item -Wcast-align +@opindex Wcast-align +Warn whenever a pointer is cast such that the required alignment of the +target is increased. For example, warn if a @code{char *} is cast to +an @code{int *} on machines where integers can only be accessed at +two- or four-byte boundaries. + +@item -Wwrite-strings +@opindex Wwrite-strings +When compiling C, give string constants the type @code{const +char[@var{length}]} so that +copying the address of one into a non-@code{const} @code{char *} +pointer will get a warning; when compiling C++, warn about the +deprecated conversion from string constants to @code{char *}. +These warnings will help you find at +compile time code that can try to write into a string constant, but +only if you have been very careful about using @code{const} in +declarations and prototypes. Otherwise, it will just be a nuisance; +this is why we did not make @option{-Wall} request these warnings. + +@item -Wconversion +@opindex Wconversion +Warn if a prototype causes a type conversion that is different from what +would happen to the same argument in the absence of a prototype. This +includes conversions of fixed point to floating and vice versa, and +conversions changing the width or signedness of a fixed point argument +except when the same as the default promotion. + +Also, warn if a negative integer constant expression is implicitly +converted to an unsigned type. For example, warn about the assignment +@code{x = -1} if @code{x} is unsigned. But do not warn about explicit +casts like @code{(unsigned) -1}. + +@item -Wsign-compare +@opindex Wsign-compare +@cindex warning for comparison of signed and unsigned values +@cindex comparison of signed and unsigned values, warning +@cindex signed and unsigned values, comparison warning +Warn when a comparison between signed and unsigned values could produce +an incorrect result when the signed value is converted to unsigned. +This warning is also enabled by @option{-W}; to get the other warnings +of @option{-W} without this warning, use @samp{-W -Wno-sign-compare}. + +@item -Waggregate-return +@opindex Waggregate-return +Warn if any functions that return structures or unions are defined or +called. (In languages where you can return an array, this also elicits +a warning.) + +@item -Wstrict-prototypes @r{(C only)} +@opindex Wstrict-prototypes +Warn if a function is declared or defined without specifying the +argument types. (An old-style function definition is permitted without +a warning if preceded by a declaration which specifies the argument +types.) + +@item -Wmissing-prototypes @r{(C only)} +@opindex Wmissing-prototypes +Warn if a global function is defined without a previous prototype +declaration. This warning is issued even if the definition itself +provides a prototype. The aim is to detect global functions that fail +to be declared in header files. + +@item -Wmissing-declarations +@opindex Wmissing-declarations +Warn if a global function is defined without a previous declaration. +Do so even if the definition itself provides a prototype. +Use this option to detect global functions that are not declared in +header files. + +@item -Wmissing-noreturn +@opindex Wmissing-noreturn +Warn about functions which might be candidates for attribute @code{noreturn}. +Note these are only possible candidates, not absolute ones. Care should +be taken to manually verify functions actually do not ever return before +adding the @code{noreturn} attribute, otherwise subtle code generation +bugs could be introduced. You will not get a warning for @code{main} in +hosted C environments. + +@item -Wmissing-format-attribute +@opindex Wmissing-format-attribute +@opindex Wformat +If @option{-Wformat} is enabled, also warn about functions which might be +candidates for @code{format} attributes. Note these are only possible +candidates, not absolute ones. GCC will guess that @code{format} +attributes might be appropriate for any function that calls a function +like @code{vprintf} or @code{vscanf}, but this might not always be the +case, and some functions for which @code{format} attributes are +appropriate may not be detected. This option has no effect unless +@option{-Wformat} is enabled (possibly by @option{-Wall}). + +@item -Wno-deprecated-declarations +@opindex Wno-deprecated-declarations +Do not warn about uses of functions, variables, and types marked as +deprecated by using the @code{deprecated} attribute. +(@pxref{Function Attributes}, @pxref{Variable Attributes}, +@pxref{Type Attributes}.) + +@item -Wpacked +@opindex Wpacked +Warn if a structure is given the packed attribute, but the packed +attribute has no effect on the layout or size of the structure. +Such structures may be mis-aligned for little benefit. For +instance, in this code, the variable @code{f.x} in @code{struct bar} +will be misaligned even though @code{struct bar} does not itself +have the packed attribute: + +@smallexample +@group +struct foo @{ + int x; + char a, b, c, d; +@} __attribute__((packed)); +struct bar @{ + char z; + struct foo f; +@}; +@end group +@end smallexample + +@item -Wpadded +@opindex Wpadded +Warn if padding is included in a structure, either to align an element +of the structure or to align the whole structure. Sometimes when this +happens it is possible to rearrange the fields of the structure to +reduce the padding and so make the structure smaller. + +@item -Wredundant-decls +@opindex Wredundant-decls +Warn if anything is declared more than once in the same scope, even in +cases where multiple declaration is valid and changes nothing. + +@item -Wnested-externs @r{(C only)} +@opindex Wnested-externs +Warn if an @code{extern} declaration is encountered within a function. + +@item -Wunreachable-code +@opindex Wunreachable-code +Warn if the compiler detects that code will never be executed. + +This option is intended to warn when the compiler detects that at +least a whole line of source code will never be executed, because +some condition is never satisfied or because it is after a +procedure that never returns. + +It is possible for this option to produce a warning even though there +are circumstances under which part of the affected line can be executed, +so care should be taken when removing apparently-unreachable code. + +For instance, when a function is inlined, a warning may mean that the +line is unreachable in only one inlined copy of the function. + +This option is not made part of @option{-Wall} because in a debugging +version of a program there is often substantial code which checks +correct functioning of the program and is, hopefully, unreachable +because the program does work. Another common use of unreachable +code is to provide behavior which is selectable at compile-time. + +@item -Winline +@opindex Winline +Warn if a function can not be inlined and it was declared as inline. + +@item -Wlong-long +@opindex Wlong-long +@opindex Wno-long-long +Warn if @samp{long long} type is used. This is default. To inhibit +the warning messages, use @option{-Wno-long-long}. Flags +@option{-Wlong-long} and @option{-Wno-long-long} are taken into account +only when @option{-pedantic} flag is used. + +@item -Wdisabled-optimization +@opindex Wdisabled-optimization +Warn if a requested optimization pass is disabled. This warning does +not generally indicate that there is anything wrong with your code; it +merely indicates that GCC's optimizers were unable to handle the code +effectively. Often, the problem is that your code is too big or too +complex; GCC will refuse to optimize programs when the optimization +itself is likely to take inordinate amounts of time. + +@item -Werror +@opindex Werror +Make all warnings into errors. +@end table + +@node Debugging Options +@section Options for Debugging Your Program or GCC +@cindex options, debugging +@cindex debugging information options + +GCC has various special options that are used for debugging +either your program or GCC: + +@table @gcctabopt +@item -g +@opindex g +Produce debugging information in the operating system's native format +(stabs, COFF, XCOFF, or DWARF)@. GDB can work with this debugging +information. + +On most systems that use stabs format, @option{-g} enables use of extra +debugging information that only GDB can use; this extra information +makes debugging work better in GDB but will probably make other debuggers +crash or +refuse to read the program. If you want to control for certain whether +to generate the extra information, use @option{-gstabs+}, @option{-gstabs}, +@option{-gxcoff+}, @option{-gxcoff}, @option{-gdwarf-1+}, @option{-gdwarf-1}, +or @option{-gvms} (see below). + +Unlike most other C compilers, GCC allows you to use @option{-g} with +@option{-O}. The shortcuts taken by optimized code may occasionally +produce surprising results: some variables you declared may not exist +at all; flow of control may briefly move where you did not expect it; +some statements may not be executed because they compute constant +results or their values were already at hand; some statements may +execute in different places because they were moved out of loops. + +Nevertheless it proves possible to debug optimized output. This makes +it reasonable to use the optimizer for programs that might have bugs. + +The following options are useful when GCC is generated with the +capability for more than one debugging format. + +@item -ggdb +@opindex ggdb +Produce debugging information for use by GDB@. This means to use the +most expressive format available (DWARF 2, stabs, or the native format +if neither of those are supported), including GDB extensions if at all +possible. + +@item -gstabs +@opindex gstabs +Produce debugging information in stabs format (if that is supported), +without GDB extensions. This is the format used by DBX on most BSD +systems. On MIPS, Alpha and System V Release 4 systems this option +produces stabs debugging output which is not understood by DBX or SDB@. +On System V Release 4 systems this option requires the GNU assembler. + +@item -gstabs+ +@opindex gstabs+ +Produce debugging information in stabs format (if that is supported), +using GNU extensions understood only by the GNU debugger (GDB)@. The +use of these extensions is likely to make other debuggers crash or +refuse to read the program. + +@item -gcoff +@opindex gcoff +Produce debugging information in COFF format (if that is supported). +This is the format used by SDB on most System V systems prior to +System V Release 4. + +@item -gxcoff +@opindex gxcoff +Produce debugging information in XCOFF format (if that is supported). +This is the format used by the DBX debugger on IBM RS/6000 systems. + +@item -gxcoff+ +@opindex gxcoff+ +Produce debugging information in XCOFF format (if that is supported), +using GNU extensions understood only by the GNU debugger (GDB)@. The +use of these extensions is likely to make other debuggers crash or +refuse to read the program, and may cause assemblers other than the GNU +assembler (GAS) to fail with an error. + +@item -gdwarf +@opindex gdwarf +Produce debugging information in DWARF version 1 format (if that is +supported). This is the format used by SDB on most System V Release 4 +systems. + +@item -gdwarf+ +@opindex gdwarf+ +Produce debugging information in DWARF version 1 format (if that is +supported), using GNU extensions understood only by the GNU debugger +(GDB)@. The use of these extensions is likely to make other debuggers +crash or refuse to read the program. + +@item -gdwarf-2 +@opindex gdwarf-2 +Produce debugging information in DWARF version 2 format (if that is +supported). This is the format used by DBX on IRIX 6. + +@item -gvms +@opindex gvms +Produce debugging information in VMS debug format (if that is +supported). This is the format used by DEBUG on VMS systems. + +@item -g@var{level} +@itemx -ggdb@var{level} +@itemx -gstabs@var{level} +@itemx -gcoff@var{level} +@itemx -gxcoff@var{level} +@itemx -gdwarf@var{level} +@itemx -gdwarf-2@var{level} +@itemx -gvms@var{level} +Request debugging information and also use @var{level} to specify how +much information. The default level is 2. + +Level 1 produces minimal information, enough for making backtraces in +parts of the program that you don't plan to debug. This includes +descriptions of functions and external variables, but no information +about local variables and no line numbers. + +Level 3 includes extra information, such as all the macro definitions +present in the program. Some debuggers support macro expansion when +you use @option{-g3}. + +@cindex @code{prof} +@item -p +@opindex p +Generate extra code to write profile information suitable for the +analysis program @code{prof}. You must use this option when compiling +the source files you want data about, and you must also use it when +linking. + +@cindex @code{gprof} +@item -pg +@opindex pg +Generate extra code to write profile information suitable for the +analysis program @code{gprof}. You must use this option when compiling +the source files you want data about, and you must also use it when +linking. + +@cindex @code{tcov} +@item -a +@opindex a +Generate extra code to write profile information for basic blocks, which will +record the number of times each basic block is executed, the basic block start +address, and the function name containing the basic block. If @option{-g} is +used, the line number and filename of the start of the basic block will also be +recorded. If not overridden by the machine description, the default action is +to append to the text file @file{bb.out}. + +This data could be analyzed by a program like @code{tcov}. Note, +however, that the format of the data is not what @code{tcov} expects. +Eventually GNU @code{gprof} should be extended to process this data. + +@item -Q +@opindex Q +Makes the compiler print out each function name as it is compiled, and +print some statistics about each pass when it finishes. + +@item -ftime-report +@opindex ftime-report +Makes the compiler print some statistics about the time consumed by each +pass when it finishes. + +@item -fmem-report +@opindex fmem-report +Makes the compiler print some statistics about permanent memory +allocation when it finishes. + +@item -fprofile-arcs +@opindex fprofile-arcs +Instrument @dfn{arcs} during compilation to generate coverage data +or for profile-directed block ordering. During execution the program +records how many times each branch is executed and how many times it is +taken. When the compiled program exits it saves this data to a file +called @file{@var{sourcename}.da} for each source file. + +For profile-directed block ordering, compile the program with +@option{-fprofile-arcs} plus optimization and code generation options, +generate the arc profile information by running the program on a +selected workload, and then compile the program again with the same +optimization and code generation options plus +@option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that +Control Optimization}). + +The other use of @option{-fprofile-arcs} is for use with @code{gcov}, +when it is used with the @option{-ftest-coverage} option. GCC +supports two methods of determining code coverage: the options that +support @code{gcov}, and options @option{-a} and @option{-ax}, which +write information to text files. The options that support @code{gcov} +do not need to instrument every arc in the program, so a program compiled +with them runs faster than a program compiled with @option{-a}, which +adds instrumentation code to every basic block in the program. The +tradeoff: since @code{gcov} does not have execution counts for all +branches, it must start with the execution counts for the instrumented +branches, and then iterate over the program flow graph until the entire +graph has been solved. Hence, @code{gcov} runs a little more slowly than +a program which uses information from @option{-a} and @option{-ax}. + +With @option{-fprofile-arcs}, for each function of your program GCC +creates a program flow graph, then finds a spanning tree for the graph. +Only arcs that are not on the spanning tree have to be instrumented: the +compiler adds code to count the number of times that these arcs are +executed. When an arc is the only exit or only entrance to a block, the +instrumentation code can be added to the block; otherwise, a new basic +block must be created to hold the instrumentation code. + +This option makes it possible to estimate branch probabilities and to +calculate basic block execution counts. In general, basic block +execution counts as provided by @option{-a} do not give enough +information to estimate all branch probabilities. + +@need 2000 +@item -ftest-coverage +@opindex ftest-coverage +Create data files for the @code{gcov} code-coverage utility +(@pxref{Gcov,, @code{gcov}: a GCC Test Coverage Program}). +The data file names begin with the name of your source file: + +@table @gcctabopt +@item @var{sourcename}.bb +A mapping from basic blocks to line numbers, which @code{gcov} uses to +associate basic block execution counts with line numbers. + +@item @var{sourcename}.bbg +A list of all arcs in the program flow graph. This allows @code{gcov} +to reconstruct the program flow graph, so that it can compute all basic +block and arc execution counts from the information in the +@code{@var{sourcename}.da} file. +@end table + +Use @option{-ftest-coverage} with @option{-fprofile-arcs}; the latter +option adds instrumentation to the program, which then writes +execution counts to another data file: + +@table @gcctabopt +@item @var{sourcename}.da +Runtime arc execution counts, used in conjunction with the arc +information in the file @code{@var{sourcename}.bbg}. +@end table + +Coverage data will map better to the source files if +@option{-ftest-coverage} is used without optimization. + +@item -d@var{letters} +@opindex d +Says to make debugging dumps during compilation at times specified by +@var{letters}. This is used for debugging the compiler. The file names +for most of the dumps are made by appending a pass number and a word to +the source file name (e.g. @file{foo.c.00.rtl} or @file{foo.c.01.sibling}). +Here are the possible letters for use in @var{letters}, and their meanings: + +@table @samp +@item A +@opindex dA +Annotate the assembler output with miscellaneous debugging information. +@item b +@opindex db +Dump after computing branch probabilities, to @file{@var{file}.14.bp}. +@item B +@opindex dB +Dump after block reordering, to @file{@var{file}.29.bbro}. +@item c +@opindex dc +Dump after instruction combination, to the file @file{@var{file}.16.combine}. +@item C +@opindex dC +Dump after the first if conversion, to the file @file{@var{file}.17.ce}. +@item d +@opindex dd +Dump after delayed branch scheduling, to @file{@var{file}.31.dbr}. +@item D +@opindex dD +Dump all macro definitions, at the end of preprocessing, in addition to +normal output. +@item e +@opindex de +Dump after SSA optimizations, to @file{@var{file}.04.ssa} and +@file{@var{file}.07.ussa}. +@item E +@opindex dE +Dump after the second if conversion, to @file{@var{file}.26.ce2}. +@item f +@opindex df +Dump after life analysis, to @file{@var{file}.15.life}. +@item F +@opindex dF +Dump after purging @code{ADDRESSOF} codes, to @file{@var{file}.09.addressof}. +@item g +@opindex dg +Dump after global register allocation, to @file{@var{file}.21.greg}. +@item h +@opindex dh +Dump after finalization of EH handling code, to @file{@var{file}.02.eh}. +@item k +@opindex dk +Dump after reg-to-stack conversion, to @file{@var{file}.28.stack}. +@item o +@opindex do +Dump after post-reload optimizations, to @file{@var{file}.22.postreload}. +@item G +@opindex dG +Dump after GCSE, to @file{@var{file}.10.gcse}. +@item i +@opindex di +Dump after sibling call optimizations, to @file{@var{file}.01.sibling}. +@item j +@opindex dj +Dump after the first jump optimization, to @file{@var{file}.03.jump}. +@item k +@opindex dk +Dump after conversion from registers to stack, to @file{@var{file}.32.stack}. +@item l +@opindex dl +Dump after local register allocation, to @file{@var{file}.20.lreg}. +@item L +@opindex dL +Dump after loop optimization, to @file{@var{file}.11.loop}. +@item M +@opindex dM +Dump after performing the machine dependent reorganisation pass, to +@file{@var{file}.30.mach}. +@item n +@opindex dn +Dump after register renumbering, to @file{@var{file}.25.rnreg}. +@item N +@opindex dN +Dump after the register move pass, to @file{@var{file}.18.regmove}. +@item r +@opindex dr +Dump after RTL generation, to @file{@var{file}.00.rtl}. +@item R +@opindex dR +Dump after the second scheduling pass, to @file{@var{file}.27.sched2}. +@item s +@opindex ds +Dump after CSE (including the jump optimization that sometimes follows +CSE), to @file{@var{file}.08.cse}. +@item S +@opindex dS +Dump after the first scheduling pass, to @file{@var{file}.19.sched}. +@item t +@opindex dt +Dump after the second CSE pass (including the jump optimization that +sometimes follows CSE), to @file{@var{file}.12.cse2}. +@item w +@opindex dw +Dump after the second flow pass, to @file{@var{file}.23.flow2}. +@item X +@opindex dX +Dump after SSA dead code elimination, to @file{@var{file}.06.ssadce}. +@item z +@opindex dz +Dump after the peephole pass, to @file{@var{file}.24.peephole2}. +@item a +@opindex da +Produce all the dumps listed above. +@item m +@opindex dm +Print statistics on memory usage, at the end of the run, to +standard error. +@item p +@opindex dp +Annotate the assembler output with a comment indicating which +pattern and alternative was used. The length of each instruction is +also printed. +@item P +@opindex dP +Dump the RTL in the assembler output as a comment before each instruction. +Also turns on @option{-dp} annotation. +@item v +@opindex dv +For each of the other indicated dump files (except for +@file{@var{file}.00.rtl}), dump a representation of the control flow graph +suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}. +@item x +@opindex dx +Just generate RTL for a function instead of compiling it. Usually used +with @samp{r}. +@item y +@opindex dy +Dump debugging information during parsing, to standard error. +@end table + +@item -fdump-unnumbered +@opindex fdump-unnumbered +When doing debugging dumps (see @option{-d} option above), suppress instruction +numbers and line number note output. This makes it more feasible to +use diff on debugging dumps for compiler invocations with different +options, in particular with and without @option{-g}. + +@item -fdump-translation-unit @r{(C and C++ only)} +@itemx -fdump-translation-unit-@var{options} @r{(C and C++ only)} +@opindex fdump-translation-unit +Dump a representation of the tree structure for the entire translation +unit to a file. The file name is made by appending @file{.tu} to the +source file name. If the @samp{-@var{options}} form is used, @var{options} +controls the details of the dump as described for the +@option{-fdump-tree} options. + +@item -fdump-class-hierarchy @r{(C++ only)} +@itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)} +@opindex fdump-class-hierarchy +Dump a representation of each class's hierarchy and virtual function +table layout to a file. The file name is made by appending @file{.class} +to the source file name. If the @samp{-@var{options}} form is used, +@var{options} controls the details of the dump as described for the +@option{-fdump-tree} options. + +@item -fdump-tree-@var{switch} @r{(C++ only)} +@itemx -fdump-tree-@var{switch}-@var{options} @r{(C++ only)} +@opindex fdump-tree +Control the dumping at various stages of processing the intermediate +language tree to a file. The file name is generated by appending a switch +specific suffix to the source file name. If the @samp{-@var{options}} +form is used, @var{options} is a list of @samp{-} separated options that +control the details of the dump. Not all options are applicable to all +dumps, those which are not meaningful will be ignored. The following +options are available + +@table @samp +@item address +Print the address of each node. Usually this is not meaningful as it +changes according to the environment and source file. Its primary use +is for tying up a dump file with a debug environment. +@item slim +Inhibit dumping of members of a scope or body of a function merely +because that scope has been reached. Only dump such items when they +are directly reachable by some other path. +@item all +Turn on all options. +@end table + +The following tree dumps are possible: +@table @samp +@item original +Dump before any tree based optimization, to @file{@var{file}.original}. +@item optimized +Dump after all tree based optimization, to @file{@var{file}.optimized}. +@item inlined +Dump after function inlining, to @file{@var{file}.inlined}. +@end table + +@item -fpretend-float +@opindex fpretend-float +When running a cross-compiler, pretend that the target machine uses the +same floating point format as the host machine. This causes incorrect +output of the actual floating constants, but the actual instruction +sequence will probably be the same as GCC would make when running on +the target machine. + +@item -save-temps +@opindex save-temps +Store the usual ``temporary'' intermediate files permanently; place them +in the current directory and name them based on the source file. Thus, +compiling @file{foo.c} with @samp{-c -save-temps} would produce files +@file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a +preprocessed @file{foo.i} output file even though the compiler now +normally uses an integrated preprocessor. + +@item -time +@opindex time +Report the CPU time taken by each subprocess in the compilation +sequence. For C source files, this is the compiler proper and assembler +(plus the linker if linking is done). The output looks like this: + +@smallexample +# cc1 0.12 0.01 +# as 0.00 0.01 +@end smallexample + +The first number on each line is the ``user time,'' that is time spent +executing the program itself. The second number is ``system time,'' +time spent executing operating system routines on behalf of the program. +Both numbers are in seconds. + +@item -print-file-name=@var{library} +@opindex print-file-name +Print the full absolute name of the library file @var{library} that +would be used when linking---and don't do anything else. With this +option, GCC does not compile or link anything; it just prints the +file name. + +@item -print-multi-directory +@opindex print-multi-directory +Print the directory name corresponding to the multilib selected by any +other switches present in the command line. This directory is supposed +to exist in @env{GCC_EXEC_PREFIX}. + +@item -print-multi-lib +@opindex print-multi-lib +Print the mapping from multilib directory names to compiler switches +that enable them. The directory name is separated from the switches by +@samp{;}, and each switch starts with an @samp{@@} instead of the +@samp{-}, without spaces between multiple switches. This is supposed to +ease shell-processing. + +@item -print-prog-name=@var{program} +@opindex print-prog-name +Like @option{-print-file-name}, but searches for a program such as @samp{cpp}. + +@item -print-libgcc-file-name +@opindex print-libgcc-file-name +Same as @option{-print-file-name=libgcc.a}. + +This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs} +but you do want to link with @file{libgcc.a}. You can do + +@example +gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name` +@end example + +@item -print-search-dirs +@opindex print-search-dirs +Print the name of the configured installation directory and a list of +program and library directories gcc will search---and don't do anything else. + +This is useful when gcc prints the error message +@samp{installation problem, cannot exec cpp0: No such file or directory}. +To resolve this you either need to put @file{cpp0} and the other compiler +components where gcc expects to find them, or you can set the environment +variable @env{GCC_EXEC_PREFIX} to the directory where you installed them. +Don't forget the trailing '/'. +@xref{Environment Variables}. + +@item -dumpmachine +@opindex dumpmachine +Print the compiler's target machine (for example, +@samp{i686-pc-linux-gnu})---and don't do anything else. + +@item -dumpversion +@opindex dumpversion +Print the compiler version (for example, @samp{3.0})---and don't do +anything else. + +@item -dumpspecs +@opindex dumpspecs +Print the compiler's built-in specs---and don't do anything else. (This +is used when GCC itself is being built.) @xref{Spec Files}. +@end table + +@node Optimize Options +@section Options That Control Optimization +@cindex optimize options +@cindex options, optimization + +These options control various sorts of optimizations: + +@table @gcctabopt +@item -O +@itemx -O1 +@opindex O +@opindex O1 +Optimize. Optimizing compilation takes somewhat more time, and a lot +more memory for a large function. + +Without @option{-O}, the compiler's goal is to reduce the cost of +compilation and to make debugging produce the expected results. +Statements are independent: if you stop the program with a breakpoint +between statements, you can then assign a new value to any variable or +change the program counter to any other statement in the function and +get exactly the results you would expect from the source code. + +With @option{-O}, the compiler tries to reduce code size and execution +time, without performing any optimizations that take a great deal of +compilation time. + +@item -O2 +@opindex O2 +Optimize even more. GCC performs nearly all supported optimizations +that do not involve a space-speed tradeoff. The compiler does not +perform loop unrolling or function inlining when you specify @option{-O2}. +As compared to @option{-O}, this option increases both compilation time +and the performance of the generated code. + +@option{-O2} turns on all optional optimizations except for loop unrolling, +function inlining, and register renaming. It also turns on the +@option{-fforce-mem} option on all machines and frame pointer elimination +on machines where doing so does not interfere with debugging. + +Please note the warning under @option{-fgcse} about +invoking @option{-O2} on programs that use computed gotos. + +@item -O3 +@opindex O3 +Optimize yet more. @option{-O3} turns on all optimizations specified by +@option{-O2} and also turns on the @option{-finline-functions} and +@option{-frename-registers} options. + +@item -O0 +@opindex O0 +Do not optimize. + +@item -Os +@opindex Os +Optimize for size. @option{-Os} enables all @option{-O2} optimizations that +do not typically increase code size. It also performs further +optimizations designed to reduce code size. + +If you use multiple @option{-O} options, with or without level numbers, +the last such option is the one that is effective. +@end table + +Options of the form @option{-f@var{flag}} specify machine-independent +flags. Most flags have both positive and negative forms; the negative +form of @option{-ffoo} would be @option{-fno-foo}. In the table below, +only one of the forms is listed---the one which is not the default. +You can figure out the other form by either removing @samp{no-} or +adding it. + +@table @gcctabopt +@item -ffloat-store +@opindex ffloat-store +Do not store floating point variables in registers, and inhibit other +options that might change whether a floating point value is taken from a +register or memory. + +@cindex floating point precision +This option prevents undesirable excess precision on machines such as +the 68000 where the floating registers (of the 68881) keep more +precision than a @code{double} is supposed to have. Similarly for the +x86 architecture. For most programs, the excess precision does only +good, but a few programs rely on the precise definition of IEEE floating +point. Use @option{-ffloat-store} for such programs, after modifying +them to store all pertinent intermediate computations into variables. + +@item -fno-default-inline +@opindex fno-default-inline +Do not make member functions inline by default merely because they are +defined inside the class scope (C++ only). Otherwise, when you specify +@w{@option{-O}}, member functions defined inside class scope are compiled +inline by default; i.e., you don't need to add @samp{inline} in front of +the member function name. + +@item -fno-defer-pop +@opindex fno-defer-pop +Always pop the arguments to each function call as soon as that function +returns. For machines which must pop arguments after a function call, +the compiler normally lets arguments accumulate on the stack for several +function calls and pops them all at once. + +@item -fforce-mem +@opindex fforce-mem +Force memory operands to be copied into registers before doing +arithmetic on them. This produces better code by making all memory +references potential common subexpressions. When they are not common +subexpressions, instruction combination should eliminate the separate +register-load. The @option{-O2} option turns on this option. + +@item -fforce-addr +@opindex fforce-addr +Force memory address constants to be copied into registers before +doing arithmetic on them. This may produce better code just as +@option{-fforce-mem} may. + +@item -fomit-frame-pointer +@opindex fomit-frame-pointer +Don't keep the frame pointer in a register for functions that +don't need one. This avoids the instructions to save, set up and +restore frame pointers; it also makes an extra register available +in many functions. @strong{It also makes debugging impossible on +some machines.} + +On some machines, such as the VAX, this flag has no effect, because +the standard calling sequence automatically handles the frame pointer +and nothing is saved by pretending it doesn't exist. The +machine-description macro @code{FRAME_POINTER_REQUIRED} controls +whether a target machine supports this flag. @xref{Registers,,Register +Usage, gccint, GNU Compiler Collection (GCC) Internals}. + +@item -foptimize-sibling-calls +@opindex foptimize-sibling-calls +Optimize sibling and tail recursive calls. + +@item -ftrapv +@opindex ftrapv +This option generates traps for signed overflow on addition, subtraction, +multiplication operations. + +@item -fno-inline +@opindex fno-inline +Don't pay attention to the @code{inline} keyword. Normally this option +is used to keep the compiler from expanding any functions inline. +Note that if you are not optimizing, no functions can be expanded inline. + +@item -finline-functions +@opindex finline-functions +Integrate all simple functions into their callers. The compiler +heuristically decides which functions are simple enough to be worth +integrating in this way. + +If all calls to a given function are integrated, and the function is +declared @code{static}, then the function is normally not output as +assembler code in its own right. + +@item -finline-limit=@var{n} +@opindex finline-limit +By default, gcc limits the size of functions that can be inlined. This flag +allows the control of this limit for functions that are explicitly marked as +inline (ie marked with the inline keyword or defined within the class +definition in c++). @var{n} is the size of functions that can be inlined in +number of pseudo instructions (not counting parameter handling). The default +value of @var{n} is 600. +Increasing this value can result in more inlined code at +the cost of compilation time and memory consumption. Decreasing usually makes +the compilation faster and less code will be inlined (which presumably +means slower programs). This option is particularly useful for programs that +use inlining heavily such as those based on recursive templates with C++. + +@emph{Note:} pseudo instruction represents, in this particular context, an +abstract measurement of function's size. In no way, it represents a count +of assembly instructions and as such its exact meaning might change from one +release to an another. + +@item -fkeep-inline-functions +@opindex fkeep-inline-functions +Even if all calls to a given function are integrated, and the function +is declared @code{static}, nevertheless output a separate run-time +callable version of the function. This switch does not affect +@code{extern inline} functions. + +@item -fkeep-static-consts +@opindex fkeep-static-consts +Emit variables declared @code{static const} when optimization isn't turned +on, even if the variables aren't referenced. + +GCC enables this option by default. If you want to force the compiler to +check if the variable was referenced, regardless of whether or not +optimization is turned on, use the @option{-fno-keep-static-consts} option. + +@item -fmerge-constants +Attempt to merge identical constants (string constants and floating point +constants) accross compilation units. + +This option is default for optimized compilation if assembler and linker +support it. Use @option{-fno-merge-constants} to inhibit this behavior. + +@item -fmerge-all-constants +Attempt to merge identical constants and identical variables. + +This option implies @option{-fmerge-constants}. In addition to +@option{-fmerge-constants} this considers e.g. even constant initialized +arrays or initialized constant variables with integral or floating point +types. Languages like C or C++ require each non-automatic variable to +have distinct location, so using this option will result in non-conforming +behavior. + +@item -fno-function-cse +@opindex fno-function-cse +Do not put function addresses in registers; make each instruction that +calls a constant function contain the function's address explicitly. + +This option results in less efficient code, but some strange hacks +that alter the assembler output may be confused by the optimizations +performed when this option is not used. + +@item -ffast-math +@opindex ffast-math +Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, and @* +@option{-fno-trapping-math}. + +This option causes the preprocessor macro @code{__FAST_MATH__} to be defined. + +This option should never be turned on by any @option{-O} option since +it can result in incorrect output for programs which depend on +an exact implementation of IEEE or ISO rules/specifications for +math functions. + +@item -fno-math-errno +@opindex fno-math-errno +Do not set ERRNO after calling math functions that are executed +with a single instruction, e.g., sqrt. A program that relies on +IEEE exceptions for math error handling may want to use this flag +for speed while maintaining IEEE arithmetic compatibility. + +This option should never be turned on by any @option{-O} option since +it can result in incorrect output for programs which depend on +an exact implementation of IEEE or ISO rules/specifications for +math functions. + +The default is @option{-fmath-errno}. + +@item -funsafe-math-optimizations +@opindex funsafe-math-optimizations +Allow optimizations for floating-point arithmetic that (a) assume +that arguments and results are valid and (b) may violate IEEE or +ANSI standards. When used at link-time, it may include libraries +or startup files that change the default FPU control word or other +similar optimizations. + +This option should never be turned on by any @option{-O} option since +it can result in incorrect output for programs which depend on +an exact implementation of IEEE or ISO rules/specifications for +math functions. + +The default is @option{-fno-unsafe-math-optimizations}. + +@item -fno-trapping-math +@opindex fno-trapping-math +Compile code assuming that floating-point operations cannot generate +user-visible traps. Setting this option may allow faster code +if one relies on ``non-stop'' IEEE arithmetic, for example. + +This option should never be turned on by any @option{-O} option since +it can result in incorrect output for programs which depend on +an exact implementation of IEEE or ISO rules/specifications for +math functions. + +The default is @option{-ftrapping-math}. +@end table + +The following options control specific optimizations. The @option{-O2} +option turns on all of these optimizations except @option{-funroll-loops} +and @option{-funroll-all-loops}. On most machines, the @option{-O} option +turns on the @option{-fthread-jumps} and @option{-fdelayed-branch} options, +but specific machines may handle it differently. + +You can use the following flags in the rare cases when ``fine-tuning'' +of optimizations to be performed is desired. + +Not all of the optimizations performed by GCC have @option{-f} options +to control them. + +@table @gcctabopt +@item -fstrength-reduce +@opindex fstrength-reduce +Perform the optimizations of loop strength reduction and +elimination of iteration variables. + +@item -fthread-jumps +@opindex fthread-jumps +Perform optimizations where we check to see if a jump branches to a +location where another comparison subsumed by the first is found. If +so, the first branch is redirected to either the destination of the +second branch or a point immediately following it, depending on whether +the condition is known to be true or false. + +@item -fcse-follow-jumps +@opindex fcse-follow-jumps +In common subexpression elimination, scan through jump instructions +when the target of the jump is not reached by any other path. For +example, when CSE encounters an @code{if} statement with an +@code{else} clause, CSE will follow the jump when the condition +tested is false. + +@item -fcse-skip-blocks +@opindex fcse-skip-blocks +This is similar to @option{-fcse-follow-jumps}, but causes CSE to +follow jumps which conditionally skip over blocks. When CSE +encounters a simple @code{if} statement with no else clause, +@option{-fcse-skip-blocks} causes CSE to follow the jump around the +body of the @code{if}. + +@item -frerun-cse-after-loop +@opindex frerun-cse-after-loop +Re-run common subexpression elimination after loop optimizations has been +performed. + +@item -frerun-loop-opt +@opindex frerun-loop-opt +Run the loop optimizer twice. + +@item -fgcse +@opindex fgcse +Perform a global common subexpression elimination pass. +This pass also performs global constant and copy propagation. + +@emph{Note:} When compiling a program using computed gotos, a GCC +extension, you may get better runtime performance if you disable +the global common subexpression elmination pass by adding +@option{-fno-gcse} to the command line. + +@item -fgcse-lm +@opindex fgcse-lm +When @option{-fgcse-lm} is enabled, global common subexpression elimination will +attempt to move loads which are only killed by stores into themselves. This +allows a loop containing a load/store sequence to be changed to a load outside +the loop, and a copy/store within the loop. + +@item -fgcse-sm +@opindex fgcse-sm +When @option{-fgcse-sm} is enabled, A store motion pass is run after global common +subexpression elimination. This pass will attempt to move stores out of loops. +When used in conjunction with @option{-fgcse-lm}, loops containing a load/store sequence +can be changed to a load before the loop and a store after the loop. + +@item -fdelete-null-pointer-checks +@opindex fdelete-null-pointer-checks +Use global dataflow analysis to identify and eliminate useless checks +for null pointers. The compiler assumes that dereferencing a null +pointer would have halted the program. If a pointer is checked after +it has already been dereferenced, it cannot be null. + +In some environments, this assumption is not true, and programs can +safely dereference null pointers. Use +@option{-fno-delete-null-pointer-checks} to disable this optimization +for programs which depend on that behavior. + +@item -fexpensive-optimizations +@opindex fexpensive-optimizations +Perform a number of minor optimizations that are relatively expensive. + +@item -foptimize-register-move +@itemx -fregmove +@opindex foptimize-register-move +@opindex fregmove +Attempt to reassign register numbers in move instructions and as +operands of other simple instructions in order to maximize the amount of +register tying. This is especially helpful on machines with two-operand +instructions. GCC enables this optimization by default with @option{-O2} +or higher. + +Note @option{-fregmove} and @option{-foptimize-register-move} are the same +optimization. + +@item -fdelayed-branch +@opindex fdelayed-branch +If supported for the target machine, attempt to reorder instructions +to exploit instruction slots available after delayed branch +instructions. + +@item -fschedule-insns +@opindex fschedule-insns +If supported for the target machine, attempt to reorder instructions to +eliminate execution stalls due to required data being unavailable. This +helps machines that have slow floating point or memory load instructions +by allowing other instructions to be issued until the result of the load +or floating point instruction is required. + +@item -fschedule-insns2 +@opindex fschedule-insns2 +Similar to @option{-fschedule-insns}, but requests an additional pass of +instruction scheduling after register allocation has been done. This is +especially useful on machines with a relatively small number of +registers and where memory load instructions take more than one cycle. + +@item -ffunction-sections +@itemx -fdata-sections +@opindex ffunction-sections +@opindex fdata-sections +Place each function or data item into its own section in the output +file if the target supports arbitrary sections. The name of the +function or the name of the data item determines the section's name +in the output file. + +Use these options on systems where the linker can perform optimizations +to improve locality of reference in the instruction space. HPPA +processors running HP-UX and Sparc processors running Solaris 2 have +linkers with such optimizations. Other systems using the ELF object format +as well as AIX may have these optimizations in the future. + +Only use these options when there are significant benefits from doing +so. When you specify these options, the assembler and linker will +create larger object and executable files and will also be slower. +You will not be able to use @code{gprof} on all systems if you +specify this option and you may have problems with debugging if +you specify both this option and @option{-g}. + +@item -fcaller-saves +@opindex fcaller-saves +Enable values to be allocated in registers that will be clobbered by +function calls, by emitting extra instructions to save and restore the +registers around such calls. Such allocation is done only when it +seems to result in better code than would otherwise be produced. + +This option is always enabled by default on certain machines, usually +those which have no call-preserved registers to use instead. + +For all machines, optimization level 2 and higher enables this flag by +default. + +@item -funroll-loops +@opindex funroll-loops +Unroll loops whose number of iterations can be determined at compile +time or upon entry to the loop. @option{-funroll-loops} implies both +@option{-fstrength-reduce} and @option{-frerun-cse-after-loop}. This +option makes code larger, and may or may not make it run faster. + +@item -funroll-all-loops +@opindex funroll-all-loops +Unroll all loops, even if their number of iterations is uncertain when +the loop is entered. This usually makes programs run more slowly. +@option{-funroll-all-loops} implies the same options as +@option{-funroll-loops}, + +@item -fprefetch-loop-arrays +@opindex fprefetch-loop-arrays +If supported by the target machine, generate instructions to prefetch +memory to improve the performance of loops that access large arrays. + +@item -fmove-all-movables +@opindex fmove-all-movables +Forces all invariant computations in loops to be moved +outside the loop. + +@item -freduce-all-givs +@opindex freduce-all-givs +Forces all general-induction variables in loops to be +strength-reduced. + +@emph{Note:} When compiling programs written in Fortran, +@option{-fmove-all-movables} and @option{-freduce-all-givs} are enabled +by default when you use the optimizer. + +These options may generate better or worse code; results are highly +dependent on the structure of loops within the source code. + +These two options are intended to be removed someday, once +they have helped determine the efficacy of various +approaches to improving loop optimizations. + +Please let us (@w{@email{gcc@@gcc.gnu.org}} and @w{@email{fortran@@gnu.org}}) +know how use of these options affects +the performance of your production code. +We're very interested in code that runs @emph{slower} +when these options are @emph{enabled}. + +@item -fno-peephole +@itemx -fno-peephole2 +@opindex fno-peephole +@opindex fno-peephole2 +Disable any machine-specific peephole optimizations. The difference +between @option{-fno-peephole} and @option{-fno-peephole2} is in how they +are implemented in the compiler; some targets use one, some use the +other, a few use both. + +@item -fbranch-probabilities +@opindex fbranch-probabilities +After running a program compiled with @option{-fprofile-arcs} +(@pxref{Debugging Options,, Options for Debugging Your Program or +@command{gcc}}), you can compile it a second time using +@option{-fbranch-probabilities}, to improve optimizations based on +the number of times each branch was taken. When the program +compiled with @option{-fprofile-arcs} exits it saves arc execution +counts to a file called @file{@var{sourcename}.da} for each source +file The information in this data file is very dependent on the +structure of the generated code, so you must use the same source code +and the same optimization options for both compilations. + +With @option{-fbranch-probabilities}, GCC puts a @samp{REG_EXEC_COUNT} +note on the first instruction of each basic block, and a +@samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}. +These can be used to improve optimization. Currently, they are only +used in one place: in @file{reorg.c}, instead of guessing which path a +branch is mostly to take, the @samp{REG_BR_PROB} values are used to +exactly determine which path is taken more often. + +@item -fno-guess-branch-probability +@opindex fno-guess-branch-probability +Do not guess branch probabilities using a randomized model. + +Sometimes gcc will opt to use a randomized model to guess branch +probabilities, when none are available from either profiling feedback +(@option{-fprofile-arcs}) or @samp{__builtin_expect}. This means that +different runs of the compiler on the same program may produce different +object code. + +In a hard real-time system, people don't want different runs of the +compiler to produce code that has different behavior; minimizing +non-determinism is of paramount import. This switch allows users to +reduce non-determinism, possibly at the expense of inferior +optimization. + +@item -fstrict-aliasing +@opindex fstrict-aliasing +Allows the compiler to assume the strictest aliasing rules applicable to +the language being compiled. For C (and C++), this activates +optimizations based on the type of expressions. In particular, an +object of one type is assumed never to reside at the same address as an +object of a different type, unless the types are almost the same. For +example, an @code{unsigned int} can alias an @code{int}, but not a +@code{void*} or a @code{double}. A character type may alias any other +type. + +Pay special attention to code like this: +@example +union a_union @{ + int i; + double d; +@}; + +int f() @{ + a_union t; + t.d = 3.0; + return t.i; +@} +@end example +The practice of reading from a different union member than the one most +recently written to (called ``type-punning'') is common. Even with +@option{-fstrict-aliasing}, type-punning is allowed, provided the memory +is accessed through the union type. So, the code above will work as +expected. However, this code might not: +@example +int f() @{ + a_union t; + int* ip; + t.d = 3.0; + ip = &t.i; + return *ip; +@} +@end example + +Every language that wishes to perform language-specific alias analysis +should define a function that computes, given an @code{tree} +node, an alias set for the node. Nodes in different alias sets are not +allowed to alias. For an example, see the C front-end function +@code{c_get_alias_set}. + +@item -falign-functions +@itemx -falign-functions=@var{n} +@opindex falign-functions +Align the start of functions to the next power-of-two greater than +@var{n}, skipping up to @var{n} bytes. For instance, +@option{-falign-functions=32} aligns functions to the next 32-byte +boundary, but @option{-falign-functions=24} would align to the next +32-byte boundary only if this can be done by skipping 23 bytes or less. + +@option{-fno-align-functions} and @option{-falign-functions=1} are +equivalent and mean that functions will not be aligned. + +Some assemblers only support this flag when @var{n} is a power of two; +in that case, it is rounded up. + +If @var{n} is not specified, use a machine-dependent default. + +@item -falign-labels +@itemx -falign-labels=@var{n} +@opindex falign-labels +Align all branch targets to a power-of-two boundary, skipping up to +@var{n} bytes like @option{-falign-functions}. This option can easily +make code slower, because it must insert dummy operations for when the +branch target is reached in the usual flow of the code. + +If @option{-falign-loops} or @option{-falign-jumps} are applicable and +are greater than this value, then their values are used instead. + +If @var{n} is not specified, use a machine-dependent default which is +very likely to be @samp{1}, meaning no alignment. + +@item -falign-loops +@itemx -falign-loops=@var{n} +@opindex falign-loops +Align loops to a power-of-two boundary, skipping up to @var{n} bytes +like @option{-falign-functions}. The hope is that the loop will be +executed many times, which will make up for any execution of the dummy +operations. + +If @var{n} is not specified, use a machine-dependent default. + +@item -falign-jumps +@itemx -falign-jumps=@var{n} +@opindex falign-jumps +Align branch targets to a power-of-two boundary, for branch targets +where the targets can only be reached by jumping, skipping up to @var{n} +bytes like @option{-falign-functions}. In this case, no dummy operations +need be executed. + +If @var{n} is not specified, use a machine-dependent default. + +@item -fssa +@opindex fssa +Perform optimizations in static single assignment form. Each function's +flow graph is translated into SSA form, optimizations are performed, and +the flow graph is translated back from SSA form. Users should not +specify this option, since it is not yet ready for production use. + +@item -fssa-ccp +@opindex fssa-ccp +Perform Sparse Conditional Constant Propagation in SSA form. Requires +@option{-fssa}. Like @option{-fssa}, this is an experimental feature. + +@item -fssa-dce +@opindex fssa-dce +Perform aggressive dead-code elimination in SSA form. Requires @option{-fssa}. +Like @option{-fssa}, this is an experimental feature. + +@item -fsingle-precision-constant +@opindex fsingle-precision-constant +Treat floating point constant as single precision constant instead of +implicitly converting it to double precision constant. + +@item -frename-registers +@opindex frename-registers +Attempt to avoid false dependencies in scheduled code by making use +of registers left over after register allocation. This optimization +will most benefit processors with lots of registers. It can, however, +make debugging impossible, since variables will no longer stay in +a ``home register''. + +@item -fno-cprop-registers +@opindex fno-cprop-registers +After register allocation and post-register allocation instruction splitting, +we perform a copy-propagation pass to try to reduce scheduling dependencies +and occasionally eliminate the copy. + +@item --param @var{name}=@var{value} +@opindex param +In some places, GCC uses various constants to control the amount of +optimization that is done. For example, GCC will not inline functions +that contain more that a certain number of instructions. You can +control some of these constants on the command-line using the +@option{--param} option. + +In each case, the @var{value} is an integer. The allowable choices for +@var{name} are given in the following table: + +@table @gcctabopt +@item max-delay-slot-insn-search +The maximum number of instructions to consider when looking for an +instruction to fill a delay slot. If more than this arbitrary number of +instructions is searched, the time savings from filling the delay slot +will be minimal so stop searching. Increasing values mean more +aggressive optimization, making the compile time increase with probably +small improvement in executable run time. + +@item max-delay-slot-live-search +When trying to fill delay slots, the maximum number of instructions to +consider when searching for a block with valid live register +information. Increasing this arbitrarily chosen value means more +aggressive optimization, increasing the compile time. This parameter +should be removed when the delay slot code is rewritten to maintain the +control-flow graph. + +@item max-gcse-memory +The approximate maximum amount of memory that will be allocated in +order to perform the global common subexpression elimination +optimization. If more memory than specified is required, the +optimization will not be done. + +@item max-gcse-passes +The maximum number of passes of GCSE to run. + +@item max-pending-list-length +The maximum number of pending dependencies scheduling will allow +before flushing the current state and starting over. Large functions +with few branches or calls can create excessively large lists which +needlessly consume memory and resources. + +@item max-inline-insns +If an function contains more than this many instructions, it +will not be inlined. This option is precisely equivalent to +@option{-finline-limit}. + +@end table +@end table + +@node Preprocessor Options +@section Options Controlling the Preprocessor +@cindex preprocessor options +@cindex options, preprocessor + +These options control the C preprocessor, which is run on each C source +file before actual compilation. + +If you use the @option{-E} option, nothing is done except preprocessing. +Some of these options make sense only together with @option{-E} because +they cause the preprocessor output to be unsuitable for actual +compilation. + +@table @gcctabopt +@item -include @var{file} +@opindex include +Process @var{file} as input before processing the regular input file. +In effect, the contents of @var{file} are compiled first. Any @option{-D} +and @option{-U} options on the command line are always processed before +@option{-include @var{file}}, regardless of the order in which they are +written. All the @option{-include} and @option{-imacros} options are +processed in the order in which they are written. + +@item -imacros @var{file} +@opindex imacros +Process @var{file} as input, discarding the resulting output, before +processing the regular input file. Because the output generated from +@var{file} is discarded, the only effect of @option{-imacros @var{file}} +is to make the macros defined in @var{file} available for use in the +main input. All the @option{-include} and @option{-imacros} options are +processed in the order in which they are written. + +@item -idirafter @var{dir} +@opindex idirafter +@cindex second include path +Add the directory @var{dir} to the second include path. The directories +on the second include path are searched when a header file is not found +in any of the directories in the main include path (the one that +@option{-I} adds to). + +@item -iprefix @var{prefix} +@opindex iprefix +Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix} +options. + +@item -iwithprefix @var{dir} +@opindex iwithprefix +Add a directory to the second include path. The directory's name is +made by concatenating @var{prefix} and @var{dir}, where @var{prefix} was +specified previously with @option{-iprefix}. If you have not specified a +prefix yet, the directory containing the installed passes of the +compiler is used as the default. + +@item -iwithprefixbefore @var{dir} +@opindex iwithprefixbefore +Add a directory to the main include path. The directory's name is made +by concatenating @var{prefix} and @var{dir}, as in the case of +@option{-iwithprefix}. + +@item -isystem @var{dir} +@opindex isystem +Add a directory to the beginning of the second include path, marking it +as a system directory, so that it gets the same special treatment as +is applied to the standard system directories. + +@item -nostdinc +@opindex nostdinc +Do not search the standard system directories for header files. Only +the directories you have specified with @option{-I} options (and the +current directory, if appropriate) are searched. @xref{Directory +Options}, for information on @option{-I}. + +By using both @option{-nostdinc} and @option{-I-}, you can limit the include-file +search path to only those directories you specify explicitly. + +@item -remap +@opindex remap +When searching for a header file in a directory, remap file names if a +file named @file{header.gcc} exists in that directory. This can be used +to work around limitations of file systems with file name restrictions. +The @file{header.gcc} file should contain a series of lines with two +tokens on each line: the first token is the name to map, and the second +token is the actual name to use. + +@item -undef +@opindex undef +Do not predefine any nonstandard macros. (Including architecture flags). + +@item -E +@opindex E +Run only the C preprocessor. Preprocess all the C source files +specified and output the results to standard output or to the +specified output file. + +@item -C +@opindex C +Tell the preprocessor not to discard comments. Used with the +@option{-E} option. + +@item -P +@opindex P +Tell the preprocessor not to generate @samp{#line} directives. +Used with the @option{-E} option. + +@cindex make +@cindex dependencies, make +@item -M +@opindex M +Instead of outputting the result of preprocessing, output a rule +suitable for @code{make} describing the dependencies of the main source +file. The preprocessor outputs one @code{make} rule containing the +object file name for that source file, a colon, and the names of all the +included files. Unless overridden explicitly, the object file name +consists of the basename of the source file with any suffix replaced with +object file suffix. If there are many included files then the +rule is split into several lines using @samp{\}-newline. + +@option{-M} implies @option{-E}. + +@item -MM +@opindex MM +Like @option{-M}, but mention only the files included with @samp{#include +"@var{file}"}. System header files included with @samp{#include +<@var{file}>} are omitted. + +@item -MD +@opindex MD +Like @option{-M} but the dependency information is written to a file +rather than stdout. @code{gcc} will use the same file name and +directory as the object file, but with the suffix @file{.d} instead. + +This is in addition to compiling the main file as specified---@option{-MD} +does not inhibit ordinary compilation the way @option{-M} does, +unless you also specify @option{-MG}. + +With Mach, you can use the utility @code{md} to merge multiple +dependency files into a single dependency file suitable for using with +the @samp{make} command. + +@item -MMD +@opindex MMD +Like @option{-MD} except mention only user header files, not system +-header files. + +@item -MF @var{file} +@opindex MF +When used with @option{-M} or @option{-MM}, specifies a file to write the +dependencies to. This allows the preprocessor to write the preprocessed +file to stdout normally. If no @option{-MF} switch is given, CPP sends +the rules to stdout and suppresses normal preprocessed output. + +Another way to specify output of a @code{make} rule is by setting +the environment variable @env{DEPENDENCIES_OUTPUT} (@pxref{Environment +Variables}). + +@item -MG +@opindex MG +When used with @option{-M} or @option{-MM}, @option{-MG} says to treat missing +header files as generated files and assume they live in the same +directory as the source file. It suppresses preprocessed output, as a +missing header file is ordinarily an error. + +This feature is used in automatic updating of makefiles. + +@item -MP +@opindex MP +This option instructs CPP to add a phony target for each dependency +other than the main file, causing each to depend on nothing. These +dummy rules work around errors @code{make} gives if you remove header +files without updating the @code{Makefile} to match. + +This is typical output:- + +@smallexample +/tmp/test.o: /tmp/test.c /tmp/test.h + +/tmp/test.h: +@end smallexample + +@item -MQ @var{target} +@item -MT @var{target} +@opindex MQ +@opindex MT +By default CPP uses the main file name, including any path, and appends +the object suffix, normally ``.o'', to it to obtain the name of the +target for dependency generation. With @option{-MT} you can specify a +target yourself, overriding the default one. + +If you want multiple targets, you can specify them as a single argument +to @option{-MT}, or use multiple @option{-MT} options. + +The targets you specify are output in the order they appear on the +command line. @option{-MQ} is identical to @option{-MT}, except that the +target name is quoted for Make, but with @option{-MT} it isn't. For +example, @option{-MT '$(objpfx)foo.o'} gives + +@smallexample +$(objpfx)foo.o: /tmp/foo.c +@end smallexample + +but @option{-MQ '$(objpfx)foo.o'} gives + +@smallexample +$$(objpfx)foo.o: /tmp/foo.c +@end smallexample + +The default target is automatically quoted, as if it were given with +@option{-MQ}. + +@item -H +@opindex H +Print the name of each header file used, in addition to other normal +activities. + +@item -A@var{question}(@var{answer}) +@opindex A +Assert the answer @var{answer} for @var{question}, in case it is tested +with a preprocessing conditional such as @samp{#if +#@var{question}(@var{answer})}. @option{-A-} disables the standard +assertions that normally describe the target machine. + +@item -D@var{macro} +@opindex D +Define macro @var{macro} with the string @samp{1} as its definition. + +@item -D@var{macro}=@var{defn} +Define macro @var{macro} as @var{defn}. All instances of @option{-D} on +the command line are processed before any @option{-U} options. + +Any @option{-D} and @option{-U} options on the command line are processed in +order, and always before @option{-imacros @var{file}}, regardless of the +order in which they are written. + +@item -U@var{macro} +@opindex U +Undefine macro @var{macro}. @option{-U} options are evaluated after all +@option{-D} options, but before any @option{-include} and @option{-imacros} +options. + +Any @option{-D} and @option{-U} options on the command line are processed in +order, and always before @option{-imacros @var{file}}, regardless of the +order in which they are written. + +@item -dM +@opindex dM +Tell the preprocessor to output only a list of the macro definitions +that are in effect at the end of preprocessing. Used with the @option{-E} +option. + +@item -dD +@opindex dD +Tell the preprocessing to pass all macro definitions into the output, in +their proper sequence in the rest of the output. + +@item -dN +@opindex dN +Like @option{-dD} except that the macro arguments and contents are omitted. +Only @samp{#define @var{name}} is included in the output. + +@item -dI +@opindex dI +Output @samp{#include} directives in addition to the result of +preprocessing. + +@item -fpreprocessed +@opindex fpreprocessed +Indicate to the preprocessor that the input file has already been +preprocessed. This suppresses things like macro expansion, trigraph +conversion, escaped newline splicing, and processing of most directives. +The preprocessor still recognizes and removes comments, so that you can +pass a file preprocessed with @option{-C} to the compiler without +problems. In this mode the integrated preprocessor is little more than +a tokenizer for the front ends. + +@option{-fpreprocessed} is implicit if the input file has one of the +extensions @samp{i}, @samp{ii} or @samp{mi}. These are the extensions +that GCC uses for preprocessed files created by @option{-save-temps}. + +@item -trigraphs +@opindex trigraphs +Process ISO standard trigraph sequences. These are three-character +sequences, all starting with @samp{??}, that are defined by ISO C to +stand for single characters. For example, @samp{??/} stands for +@samp{\}, so @samp{'??/n'} is a character constant for a newline. By +default, GCC ignores trigraphs, but in standard-conforming modes it +converts them. See the @option{-std} and @option{-ansi} options. + +The nine trigraph sequences are +@table @samp +@item ??( +@expansion{} @samp{[} + +@item ??) +@expansion{} @samp{]} + +@item ??< +@expansion{} @samp{@{} + +@item ??> +@expansion{} @samp{@}} + +@item ??= +@expansion{} @samp{#} + +@item ??/ +@expansion{} @samp{\} + +@item ??' +@expansion{} @samp{^} + +@item ??! +@expansion{} @samp{|} + +@item ??- +@expansion{} @samp{~} + +@end table + +Trigraph support is not popular, so many compilers do not implement it +properly. Portable code should not rely on trigraphs being either +converted or ignored. + +@item -Wp,@var{option} +@opindex Wp +Pass @var{option} as an option to the preprocessor. If @var{option} +contains commas, it is split into multiple options at the commas. +@end table + +@node Assembler Options +@section Passing Options to the Assembler + +@c prevent bad page break with this line +You can pass options to the assembler. + +@table @gcctabopt +@item -Wa,@var{option} +@opindex Wa +Pass @var{option} as an option to the assembler. If @var{option} +contains commas, it is split into multiple options at the commas. +@end table + +@node Link Options +@section Options for Linking +@cindex link options +@cindex options, linking + +These options come into play when the compiler links object files into +an executable output file. They are meaningless if the compiler is +not doing a link step. + +@table @gcctabopt +@cindex file names +@item @var{object-file-name} +A file name that does not end in a special recognized suffix is +considered to name an object file or library. (Object files are +distinguished from libraries by the linker according to the file +contents.) If linking is done, these object files are used as input +to the linker. + +@item -c +@itemx -S +@itemx -E +@opindex c +@opindex S +@opindex E +If any of these options is used, then the linker is not run, and +object file names should not be used as arguments. @xref{Overall +Options}. + +@cindex Libraries +@item -l@var{library} +@itemx -l @var{library} +@opindex l +Search the library named @var{library} when linking. (The second +alternative with the library as a separate argument is only for +POSIX compliance and is not recommended.) + +It makes a difference where in the command you write this option; the +linker searches and processes libraries and object files in the order they +are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z} +after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers +to functions in @samp{z}, those functions may not be loaded. + +The linker searches a standard list of directories for the library, +which is actually a file named @file{lib@var{library}.a}. The linker +then uses this file as if it had been specified precisely by name. + +The directories searched include several standard system directories +plus any that you specify with @option{-L}. + +Normally the files found this way are library files---archive files +whose members are object files. The linker handles an archive file by +scanning through it for members which define symbols that have so far +been referenced but not defined. But if the file that is found is an +ordinary object file, it is linked in the usual fashion. The only +difference between using an @option{-l} option and specifying a file name +is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a} +and searches several directories. + +@item -lobjc +@opindex lobjc +You need this special case of the @option{-l} option in order to +link an Objective-C program. + +@item -nostartfiles +@opindex nostartfiles +Do not use the standard system startup files when linking. +The standard system libraries are used normally, unless @option{-nostdlib} +or @option{-nodefaultlibs} is used. + +@item -nodefaultlibs +@opindex nodefaultlibs +Do not use the standard system libraries when linking. +Only the libraries you specify will be passed to the linker. +The standard startup files are used normally, unless @option{-nostartfiles} +is used. The compiler may generate calls to memcmp, memset, and memcpy +for System V (and ISO C) environments or to bcopy and bzero for +BSD environments. These entries are usually resolved by entries in +libc. These entry points should be supplied through some other +mechanism when this option is specified. + +@item -nostdlib +@opindex nostdlib +Do not use the standard system startup files or libraries when linking. +No startup files and only the libraries you specify will be passed to +the linker. The compiler may generate calls to memcmp, memset, and memcpy +for System V (and ISO C) environments or to bcopy and bzero for +BSD environments. These entries are usually resolved by entries in +libc. These entry points should be supplied through some other +mechanism when this option is specified. + +@cindex @option{-lgcc}, use with @option{-nostdlib} +@cindex @option{-nostdlib} and unresolved references +@cindex unresolved references and @option{-nostdlib} +@cindex @option{-lgcc}, use with @option{-nodefaultlibs} +@cindex @option{-nodefaultlibs} and unresolved references +@cindex unresolved references and @option{-nodefaultlibs} +One of the standard libraries bypassed by @option{-nostdlib} and +@option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines +that GCC uses to overcome shortcomings of particular machines, or special +needs for some languages. +(@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler +Collection (GCC) Internals}, +for more discussion of @file{libgcc.a}.) +In most cases, you need @file{libgcc.a} even when you want to avoid +other standard libraries. In other words, when you specify @option{-nostdlib} +or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well. +This ensures that you have no unresolved references to internal GCC +library subroutines. (For example, @samp{__main}, used to ensure C++ +constructors will be called; @pxref{Collect2,,@code{collect2}, gccint, +GNU Compiler Collection (GCC) Internals}.) + +@item -s +@opindex s +Remove all symbol table and relocation information from the executable. + +@item -static +@opindex static +On systems that support dynamic linking, this prevents linking with the shared +libraries. On other systems, this option has no effect. + +@item -shared +@opindex shared +Produce a shared object which can then be linked with other objects to +form an executable. Not all systems support this option. For predictable +results, you must also specify the same set of options that were used to +generate code (@option{-fpic}, @option{-fPIC}, or model suboptions) +when you specify this option.@footnote{On some systems, @samp{gcc -shared} +needs to build supplementary stub code for constructors to work. On +multi-libbed systems, @samp{gcc -shared} must select the correct support +libraries to link against. Failing to supply the correct flags may lead +to subtle defects. Supplying them in cases where they are not necessary +is innocuous.} + +@item -shared-libgcc +@itemx -static-libgcc +@opindex shared-libgcc +@opindex static-libgcc +On systems that provide @file{libgcc} as a shared library, these options +force the use of either the shared or static version respectively. +If no shared version of @file{libgcc} was built when the compiler was +configured, these options have no effect. + +There are several situations in which an application should use the +shared @file{libgcc} instead of the static version. The most common +of these is when the application wishes to throw and catch exceptions +across different shared libraries. In that case, each of the libraries +as well as the application itself should use the shared @file{libgcc}. + +Therefore, whenever you specify the @option{-shared} option, the GCC +driver automatically adds @option{-shared-libgcc}, unless you explicitly +specify @option{-static-libgcc}. The G++ driver automatically adds +@option{-shared-libgcc} when you build a main executable as well because +for C++ programs that is typically the right thing to do. +(Exception-handling will not work reliably otherwise.) + +However, when linking a main executable written in C, you must +explicitly say @option{-shared-libgcc} if you want to use the shared +@file{libgcc}. + +@item -symbolic +@opindex symbolic +Bind references to global symbols when building a shared object. Warn +about any unresolved references (unless overridden by the link editor +option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support +this option. + +@item -Xlinker @var{option} +@opindex Xlinker +Pass @var{option} as an option to the linker. You can use this to +supply system-specific linker options which GCC does not know how to +recognize. + +If you want to pass an option that takes an argument, you must use +@option{-Xlinker} twice, once for the option and once for the argument. +For example, to pass @option{-assert definitions}, you must write +@samp{-Xlinker -assert -Xlinker definitions}. It does not work to write +@option{-Xlinker "-assert definitions"}, because this passes the entire +string as a single argument, which is not what the linker expects. + +@item -Wl,@var{option} +@opindex Wl +Pass @var{option} as an option to the linker. If @var{option} contains +commas, it is split into multiple options at the commas. + +@item -u @var{symbol} +@opindex u +Pretend the symbol @var{symbol} is undefined, to force linking of +library modules to define it. You can use @option{-u} multiple times with +different symbols to force loading of additional library modules. +@end table + +@node Directory Options +@section Options for Directory Search +@cindex directory options +@cindex options, directory search +@cindex search path + +These options specify directories to search for header files, for +libraries and for parts of the compiler: + +@table @gcctabopt +@item -I@var{dir} +@opindex I +Add the directory @var{dir} to the head of the list of directories to be +searched for header files. This can be used to override a system header +file, substituting your own version, since these directories are +searched before the system header file directories. However, you should +not use this option to add directories that contain vendor-supplied +system header files (use @option{-isystem} for that). If you use more than +one @option{-I} option, the directories are scanned in left-to-right +order; the standard system directories come after. + +If a standard system include directory, or a directory specified with +@option{-isystem}, is also specified with @option{-I}, it will be +searched only in the position requested by @option{-I}. Also, it will +not be considered a system include directory. If that directory really +does contain system headers, there is a good chance that they will +break. For instance, if GCC's installation procedure edited the headers +in @file{/usr/include} to fix bugs, @samp{-I/usr/include} will cause the +original, buggy headers to be found instead of the corrected ones. GCC +will issue a warning when a system include directory is hidden in this +way. + +@item -I- +@opindex I- +Any directories you specify with @option{-I} options before the @option{-I-} +option are searched only for the case of @samp{#include "@var{file}"}; +they are not searched for @samp{#include <@var{file}>}. + +If additional directories are specified with @option{-I} options after +the @option{-I-}, these directories are searched for all @samp{#include} +directives. (Ordinarily @emph{all} @option{-I} directories are used +this way.) + +In addition, the @option{-I-} option inhibits the use of the current +directory (where the current input file came from) as the first search +directory for @samp{#include "@var{file}"}. There is no way to +override this effect of @option{-I-}. With @option{-I.} you can specify +searching the directory which was current when the compiler was +invoked. That is not exactly the same as what the preprocessor does +by default, but it is often satisfactory. + +@option{-I-} does not inhibit the use of the standard system directories +for header files. Thus, @option{-I-} and @option{-nostdinc} are +independent. + +@item -L@var{dir} +@opindex L +Add directory @var{dir} to the list of directories to be searched +for @option{-l}. + +@item -B@var{prefix} +@opindex B +This option specifies where to find the executables, libraries, +include files, and data files of the compiler itself. + +The compiler driver program runs one or more of the subprograms +@file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries +@var{prefix} as a prefix for each program it tries to run, both with and +without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}). + +For each subprogram to be run, the compiler driver first tries the +@option{-B} prefix, if any. If that name is not found, or if @option{-B} +was not specified, the driver tries two standard prefixes, which are +@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc-lib/}. If neither of +those results in a file name that is found, the unmodified program +name is searched for using the directories specified in your +@env{PATH} environment variable. + +The compiler will check to see if the path provided by the @option{-B} +refers to a directory, and if necessary it will add a directory +separator character at the end of the path. + +@option{-B} prefixes that effectively specify directory names also apply +to libraries in the linker, because the compiler translates these +options into @option{-L} options for the linker. They also apply to +includes files in the preprocessor, because the compiler translates these +options into @option{-isystem} options for the preprocessor. In this case, +the compiler appends @samp{include} to the prefix. + +The run-time support file @file{libgcc.a} can also be searched for using +the @option{-B} prefix, if needed. If it is not found there, the two +standard prefixes above are tried, and that is all. The file is left +out of the link if it is not found by those means. + +Another way to specify a prefix much like the @option{-B} prefix is to use +the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment +Variables}. + +As a special kludge, if the path provided by @option{-B} is +@file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to +9, then it will be replaced by @file{[dir/]include}. This is to help +with boot-strapping the compiler. + +@item -specs=@var{file} +@opindex specs +Process @var{file} after the compiler reads in the standard @file{specs} +file, in order to override the defaults that the @file{gcc} driver +program uses when determining what switches to pass to @file{cc1}, +@file{cc1plus}, @file{as}, @file{ld}, etc. More than one +@option{-specs=@var{file}} can be specified on the command line, and they +are processed in order, from left to right. +@end table + +@c man end + +@node Spec Files +@section Specifying subprocesses and the switches to pass to them +@cindex Spec Files +@command{gcc} is a driver program. It performs its job by invoking a +sequence of other programs to do the work of compiling, assembling and +linking. GCC interprets its command-line parameters and uses these to +deduce which programs it should invoke, and which command-line options +it ought to place on their command lines. This behavior is controlled +by @dfn{spec strings}. In most cases there is one spec string for each +program that GCC can invoke, but a few programs have multiple spec +strings to control their behavior. The spec strings built into GCC can +be overridden by using the @option{-specs=} command-line switch to specify +a spec file. + +@dfn{Spec files} are plaintext files that are used to construct spec +strings. They consist of a sequence of directives separated by blank +lines. The type of directive is determined by the first non-whitespace +character on the line and it can be one of the following: + +@table @code +@item %@var{command} +Issues a @var{command} to the spec file processor. The commands that can +appear here are: + +@table @code +@item %include <@var{file}> +@cindex %include +Search for @var{file} and insert its text at the current point in the +specs file. + +@item %include_noerr <@var{file}> +@cindex %include_noerr +Just like @samp{%include}, but do not generate an error message if the include +file cannot be found. + +@item %rename @var{old_name} @var{new_name} +@cindex %rename +Rename the spec string @var{old_name} to @var{new_name}. + +@end table + +@item *[@var{spec_name}]: +This tells the compiler to create, override or delete the named spec +string. All lines after this directive up to the next directive or +blank line are considered to be the text for the spec string. If this +results in an empty string then the spec will be deleted. (Or, if the +spec did not exist, then nothing will happened.) Otherwise, if the spec +does not currently exist a new spec will be created. If the spec does +exist then its contents will be overridden by the text of this +directive, unless the first character of that text is the @samp{+} +character, in which case the text will be appended to the spec. + +@item [@var{suffix}]: +Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive +and up to the next directive or blank line are considered to make up the +spec string for the indicated suffix. When the compiler encounters an +input file with the named suffix, it will processes the spec string in +order to work out how to compile that file. For example: + +@smallexample +.ZZ: +z-compile -input %i +@end smallexample + +This says that any input file whose name ends in @samp{.ZZ} should be +passed to the program @samp{z-compile}, which should be invoked with the +command-line switch @option{-input} and with the result of performing the +@samp{%i} substitution. (See below.) + +As an alternative to providing a spec string, the text that follows a +suffix directive can be one of the following: + +@table @code +@item @@@var{language} +This says that the suffix is an alias for a known @var{language}. This is +similar to using the @option{-x} command-line switch to GCC to specify a +language explicitly. For example: + +@smallexample +.ZZ: +@@c++ +@end smallexample + +Says that .ZZ files are, in fact, C++ source files. + +@item #@var{name} +This causes an error messages saying: + +@smallexample +@var{name} compiler not installed on this system. +@end smallexample +@end table + +GCC already has an extensive list of suffixes built into it. +This directive will add an entry to the end of the list of suffixes, but +since the list is searched from the end backwards, it is effectively +possible to override earlier entries using this technique. + +@end table + +GCC has the following spec strings built into it. Spec files can +override these strings or create their own. Note that individual +targets can also add their own spec strings to this list. + +@smallexample +asm Options to pass to the assembler +asm_final Options to pass to the assembler post-processor +cpp Options to pass to the C preprocessor +cc1 Options to pass to the C compiler +cc1plus Options to pass to the C++ compiler +endfile Object files to include at the end of the link +link Options to pass to the linker +lib Libraries to include on the command line to the linker +libgcc Decides which GCC support library to pass to the linker +linker Sets the name of the linker +predefines Defines to be passed to the C preprocessor +signed_char Defines to pass to CPP to say whether @code{char} is signed + by default +startfile Object files to include at the start of the link +@end smallexample + +Here is a small example of a spec file: + +@smallexample +%rename lib old_lib + +*lib: +--start-group -lgcc -lc -leval1 --end-group %(old_lib) +@end smallexample + +This example renames the spec called @samp{lib} to @samp{old_lib} and +then overrides the previous definition of @samp{lib} with a new one. +The new definition adds in some extra command-line options before +including the text of the old definition. + +@dfn{Spec strings} are a list of command-line options to be passed to their +corresponding program. In addition, the spec strings can contain +@samp{%}-prefixed sequences to substitute variable text or to +conditionally insert text into the command line. Using these constructs +it is possible to generate quite complex command lines. + +Here is a table of all defined @samp{%}-sequences for spec +strings. Note that spaces are not generated automatically around the +results of expanding these sequences. Therefore you can concatenate them +together or combine them with constant text in a single argument. + +@table @code +@item %% +Substitute one @samp{%} into the program name or argument. + +@item %i +Substitute the name of the input file being processed. + +@item %b +Substitute the basename of the input file being processed. +This is the substring up to (and not including) the last period +and not including the directory. + +@item %B +This is the same as @samp{%b}, but include the file suffix (text after +the last period). + +@item %d +Marks the argument containing or following the @samp{%d} as a +temporary file name, so that that file will be deleted if GCC exits +successfully. Unlike @samp{%g}, this contributes no text to the +argument. + +@item %g@var{suffix} +Substitute a file name that has suffix @var{suffix} and is chosen +once per compilation, and mark the argument in the same way as +@samp{%d}. To reduce exposure to denial-of-service attacks, the file +name is now chosen in a way that is hard to predict even when previously +chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s} +might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches +the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is +treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g} +was simply substituted with a file name chosen once per compilation, +without regard to any appended suffix (which was therefore treated +just like ordinary text), making such attacks more likely to succeed. + +@item %u@var{suffix} +Like @samp{%g}, but generates a new temporary file name even if +@samp{%u@var{suffix}} was already seen. + +@item %U@var{suffix} +Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a +new one if there is no such last file name. In the absence of any +@samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share +the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s} +would involve the generation of two distinct file names, one +for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was +simply substituted with a file name chosen for the previous @samp{%u}, +without regard to any appended suffix. + +@item %j@var{SUFFIX} +Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is +writable, and if save-temps is off; otherwise, substitute the name +of a temporary file, just like @samp{%u}. This temporary file is not +meant for communication between processes, but rather as a junk +disposal mechanism. + +@item %.@var{SUFFIX} +Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args +when it is subsequently output with @samp{%*}. @var{SUFFIX} is +terminated by the next space or %. + +@item %w +Marks the argument containing or following the @samp{%w} as the +designated output file of this compilation. This puts the argument +into the sequence of arguments that @samp{%o} will substitute later. + +@item %o +Substitutes the names of all the output files, with spaces +automatically placed around them. You should write spaces +around the @samp{%o} as well or the results are undefined. +@samp{%o} is for use in the specs for running the linker. +Input files whose names have no recognized suffix are not compiled +at all, but they are included among the output files, so they will +be linked. + +@item %O +Substitutes the suffix for object files. Note that this is +handled specially when it immediately follows @samp{%g, %u, or %U}, +because of the need for those to form complete file names. The +handling is such that @samp{%O} is treated exactly as if it had already +been substituted, except that @samp{%g, %u, and %U} do not currently +support additional @var{suffix} characters following @samp{%O} as they would +following, for example, @samp{.o}. + +@item %p +Substitutes the standard macro predefinitions for the +current target machine. Use this when running @code{cpp}. + +@item %P +Like @samp{%p}, but puts @samp{__} before and after the name of each +predefined macro, except for macros that start with @samp{__} or with +@samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO +C@. + +@item %I +Substitute a @option{-iprefix} option made from @env{GCC_EXEC_PREFIX}. + +@item %s +Current argument is the name of a library or startup file of some sort. +Search for that file in a standard list of directories and substitute +the full name found. + +@item %e@var{str} +Print @var{str} as an error message. @var{str} is terminated by a newline. +Use this when inconsistent options are detected. + +@item %| +Output @samp{-} if the input for the current command is coming from a pipe. + +@item %(@var{name}) +Substitute the contents of spec string @var{name} at this point. + +@item %[@var{name}] +Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments. + +@item %x@{@var{option}@} +Accumulate an option for @samp{%X}. + +@item %X +Output the accumulated linker options specified by @option{-Wl} or a @samp{%x} +spec string. + +@item %Y +Output the accumulated assembler options specified by @option{-Wa}. + +@item %Z +Output the accumulated preprocessor options specified by @option{-Wp}. + +@item %v1 +Substitute the major version number of GCC@. +(For version 2.9.5, this is 2.) + +@item %v2 +Substitute the minor version number of GCC@. +(For version 2.9.5, this is 9.) + +@item %v3 +Substitute the patch level number of GCC@. +(For version 2.9.5, this is 5.) + +@item %a +Process the @code{asm} spec. This is used to compute the +switches to be passed to the assembler. + +@item %A +Process the @code{asm_final} spec. This is a spec string for +passing switches to an assembler post-processor, if such a program is +needed. + +@item %l +Process the @code{link} spec. This is the spec for computing the +command line passed to the linker. Typically it will make use of the +@samp{%L %G %S %D and %E} sequences. + +@item %D +Dump out a @option{-L} option for each directory that GCC believes might +contain startup files. If the target supports multilibs then the +current multilib directory will be prepended to each of these paths. + +@item %M +Output the multilib directory with directory separators replaced with +@samp{_}. If multilib directories are not set, or the multilib directory is +@file{.} then this option emits nothing. + +@item %L +Process the @code{lib} spec. This is a spec string for deciding which +libraries should be included on the command line to the linker. + +@item %G +Process the @code{libgcc} spec. This is a spec string for deciding +which GCC support library should be included on the command line to the linker. + +@item %S +Process the @code{startfile} spec. This is a spec for deciding which +object files should be the first ones passed to the linker. Typically +this might be a file named @file{crt0.o}. + +@item %E +Process the @code{endfile} spec. This is a spec string that specifies +the last object files that will be passed to the linker. + +@item %C +Process the @code{cpp} spec. This is used to construct the arguments +to be passed to the C preprocessor. + +@item %c +Process the @code{signed_char} spec. This is intended to be used +to tell cpp whether a char is signed. It typically has the definition: +@smallexample +%@{funsigned-char:-D__CHAR_UNSIGNED__@} +@end smallexample + +@item %1 +Process the @code{cc1} spec. This is used to construct the options to be +passed to the actual C compiler (@samp{cc1}). + +@item %2 +Process the @code{cc1plus} spec. This is used to construct the options to be +passed to the actual C++ compiler (@samp{cc1plus}). + +@item %* +Substitute the variable part of a matched option. See below. +Note that each comma in the substituted string is replaced by +a single space. + +@item %@{@code{S}@} +Substitutes the @code{-S} switch, if that switch was given to GCC@. +If that switch was not specified, this substitutes nothing. Note that +the leading dash is omitted when specifying this option, and it is +automatically inserted if the substitution is performed. Thus the spec +string @samp{%@{foo@}} would match the command-line option @option{-foo} +and would output the command line option @option{-foo}. + +@item %W@{@code{S}@} +Like %@{@code{S}@} but mark last argument supplied within as a file to be +deleted on failure. + +@item %@{@code{S}*@} +Substitutes all the switches specified to GCC whose names start +with @code{-S}, but which also take an argument. This is used for +switches like @option{-o}, @option{-D}, @option{-I}, etc. +GCC considers @option{-o foo} as being +one switch whose names starts with @samp{o}. %@{o*@} would substitute this +text, including the space. Thus two arguments would be generated. + +@item %@{^@code{S}*@} +Like %@{@code{S}*@}, but don't put a blank between a switch and its +argument. Thus %@{^o*@} would only generate one argument, not two. + +@item %@{@code{S}*&@code{T}*@} +Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options +(the order of @code{S} and @code{T} in the spec is not significant). +There can be any number of ampersand-separated variables; for each the +wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}. + +@item %@{<@code{S}@} +Remove all occurrences of @code{-S} from the command line. Note---this +command is position dependent. @samp{%} commands in the spec string +before this option will see @code{-S}, @samp{%} commands in the spec +string after this option will not. + +@item %@{@code{S}*:@code{X}@} +Substitutes @code{X} if one or more switches whose names start with +@code{-S} are specified to GCC@. Note that the tail part of the +@code{-S} option (i.e.@: the part matched by the @samp{*}) will be substituted +for each occurrence of @samp{%*} within @code{X}. + +@item %@{@code{S}:@code{X}@} +Substitutes @code{X}, but only if the @samp{-S} switch was given to GCC@. + +@item %@{!@code{S}:@code{X}@} +Substitutes @code{X}, but only if the @samp{-S} switch was @emph{not} given to GCC@. + +@item %@{|@code{S}:@code{X}@} +Like %@{@code{S}:@code{X}@}, but if no @code{S} switch, substitute @samp{-}. + +@item %@{|!@code{S}:@code{X}@} +Like %@{!@code{S}:@code{X}@}, but if there is an @code{S} switch, substitute @samp{-}. + +@item %@{.@code{S}:@code{X}@} +Substitutes @code{X}, but only if processing a file with suffix @code{S}. + +@item %@{!.@code{S}:@code{X}@} +Substitutes @code{X}, but only if @emph{not} processing a file with suffix @code{S}. + +@item %@{@code{S}|@code{P}:@code{X}@} +Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@. This may be +combined with @samp{!} and @samp{.} sequences as well, although they +have a stronger binding than the @samp{|}. For example a spec string +like this: + +@smallexample +%@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@} +@end smallexample + +will output the following command-line options from the following input +command-line options: + +@smallexample +fred.c -foo -baz +jim.d -bar -boggle +-d fred.c -foo -baz -boggle +-d jim.d -bar -baz -boggle +@end smallexample + +@end table + +The conditional text @code{X} in a %@{@code{S}:@code{X}@} or +%@{!@code{S}:@code{X}@} construct may contain other nested @samp{%} constructs +or spaces, or even newlines. They are processed as usual, as described +above. + +The @option{-O}, @option{-f}, @option{-m}, and @option{-W} +switches are handled specifically in these +constructs. If another value of @option{-O} or the negated form of a @option{-f}, @option{-m}, or +@option{-W} switch is found later in the command line, the earlier switch +value is ignored, except with @{@code{S}*@} where @code{S} is just one +letter, which passes all matching options. + +The character @samp{|} at the beginning of the predicate text is used to indicate +that a command should be piped to the following command, but only if @option{-pipe} +is specified. + +It is built into GCC which switches take arguments and which do not. +(You might think it would be useful to generalize this to allow each +compiler's spec to say which switches take arguments. But this cannot +be done in a consistent fashion. GCC cannot even decide which input +files have been specified without knowing which switches take arguments, +and it must know which input files to compile in order to tell which +compilers to run). + +GCC also knows implicitly that arguments starting in @option{-l} are to be +treated as compiler output files, and passed to the linker in their +proper position among the other output files. + +@c man begin OPTIONS + +@node Target Options +@section Specifying Target Machine and Compiler Version +@cindex target options +@cindex cross compiling +@cindex specifying machine version +@cindex specifying compiler version and target machine +@cindex compiler version, specifying +@cindex target machine, specifying + +By default, GCC compiles code for the same type of machine that you +are using. However, it can also be installed as a cross-compiler, to +compile for some other type of machine. In fact, several different +configurations of GCC, for different target machines, can be +installed side by side. Then you specify which one to use with the +@option{-b} option. + +In addition, older and newer versions of GCC can be installed side +by side. One of them (probably the newest) will be the default, but +you may sometimes wish to use another. + +@table @gcctabopt +@item -b @var{machine} +@opindex b +The argument @var{machine} specifies the target machine for compilation. +This is useful when you have installed GCC as a cross-compiler. + +The value to use for @var{machine} is the same as was specified as the +machine type when configuring GCC as a cross-compiler. For +example, if a cross-compiler was configured with @samp{configure +i386v}, meaning to compile for an 80386 running System V, then you +would specify @option{-b i386v} to run that cross compiler. + +When you do not specify @option{-b}, it normally means to compile for +the same type of machine that you are using. + +@item -V @var{version} +@opindex V +The argument @var{version} specifies which version of GCC to run. +This is useful when multiple versions are installed. For example, +@var{version} might be @samp{2.0}, meaning to run GCC version 2.0. + +The default version, when you do not specify @option{-V}, is the last +version of GCC that you installed. +@end table + +The @option{-b} and @option{-V} options actually work by controlling part of +the file name used for the executable files and libraries used for +compilation. A given version of GCC, for a given target machine, is +normally kept in the directory @file{/usr/local/lib/gcc-lib/@var{machine}/@var{version}}. + +Thus, sites can customize the effect of @option{-b} or @option{-V} either by +changing the names of these directories or adding alternate names (or +symbolic links). If in directory @file{/usr/local/lib/gcc-lib/} the +file @file{80386} is a link to the file @file{i386v}, then @option{-b +80386} becomes an alias for @option{-b i386v}. + +In one respect, the @option{-b} or @option{-V} do not completely change +to a different compiler: the top-level driver program @command{gcc} +that you originally invoked continues to run and invoke the other +executables (preprocessor, compiler per se, assembler and linker) +that do the real work. However, since no real work is done in the +driver program, it usually does not matter that the driver program +in use is not the one for the specified target. It is common for the +interface to the other executables to change incompatibly between +compiler versions, so unless the version specified is very close to that +of the driver (for example, @option{-V 3.0} with a driver program from GCC +version 3.0.1), use of @option{-V} may not work; for example, using +@option{-V 2.95.2} will not work with a driver program from GCC 3.0. + +The only way that the driver program depends on the target machine is +in the parsing and handling of special machine-specific options. +However, this is controlled by a file which is found, along with the +other executables, in the directory for the specified version and +target machine. As a result, a single installed driver program adapts +to any specified target machine, and sufficiently similar compiler +versions. + +The driver program executable does control one significant thing, +however: the default version and target machine. Therefore, you can +install different instances of the driver program, compiled for +different targets or versions, under different names. + +For example, if the driver for version 2.0 is installed as @command{ogcc} +and that for version 2.1 is installed as @command{gcc}, then the command +@command{gcc} will use version 2.1 by default, while @command{ogcc} will use +2.0 by default. However, you can choose either version with either +command with the @option{-V} option. + +@node Submodel Options +@section Hardware Models and Configurations +@cindex submodel options +@cindex specifying hardware config +@cindex hardware models and configurations, specifying +@cindex machine dependent options + +Earlier we discussed the standard option @option{-b} which chooses among +different installed compilers for completely different target +machines, such as VAX vs.@: 68000 vs.@: 80386. + +In addition, each of these target machine types can have its own +special options, starting with @samp{-m}, to choose among various +hardware models or configurations---for example, 68010 vs 68020, +floating coprocessor or none. A single installed version of the +compiler can compile for any model or configuration, according to the +options specified. + +Some configurations of the compiler also support additional special +options, usually for compatibility with other compilers on the same +platform. + +These options are defined by the macro @code{TARGET_SWITCHES} in the +machine description. The default for the options is also defined by +that macro, which enables you to change the defaults. + +@menu +* M680x0 Options:: +* M68hc1x Options:: +* VAX Options:: +* SPARC Options:: +* Convex Options:: +* AMD29K Options:: +* ARM Options:: +* MN10200 Options:: +* MN10300 Options:: +* M32R/D Options:: +* M88K Options:: +* RS/6000 and PowerPC Options:: +* RT Options:: +* MIPS Options:: +* i386 and x86-64 Options:: +* HPPA Options:: +* Intel 960 Options:: +* DEC Alpha Options:: +* DEC Alpha/VMS Options:: +* Clipper Options:: +* H8/300 Options:: +* SH Options:: +* System V Options:: +* TMS320C3x/C4x Options:: +* V850 Options:: +* ARC Options:: +* NS32K Options:: +* AVR Options:: +* MCore Options:: +* IA-64 Options:: +* D30V Options:: +* S/390 and zSeries Options:: +* CRIS Options:: +* MMIX Options:: +* PDP-11 Options:: +* Xstormy16 Options:: +* Xtensa Options:: +@end menu + +@node M680x0 Options +@subsection M680x0 Options +@cindex M680x0 options + +These are the @samp{-m} options defined for the 68000 series. The default +values for these options depends on which style of 68000 was selected when +the compiler was configured; the defaults for the most common choices are +given below. + +@table @gcctabopt +@item -m68000 +@itemx -mc68000 +@opindex m68000 +@opindex mc68000 +Generate output for a 68000. This is the default +when the compiler is configured for 68000-based systems. + +Use this option for microcontrollers with a 68000 or EC000 core, +including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356. + +@item -m68020 +@itemx -mc68020 +@opindex m68020 +@opindex mc68020 +Generate output for a 68020. This is the default +when the compiler is configured for 68020-based systems. + +@item -m68881 +@opindex m68881 +Generate output containing 68881 instructions for floating point. +This is the default for most 68020 systems unless @option{--nfp} was +specified when the compiler was configured. + +@item -m68030 +@opindex m68030 +Generate output for a 68030. This is the default when the compiler is +configured for 68030-based systems. + +@item -m68040 +@opindex m68040 +Generate output for a 68040. This is the default when the compiler is +configured for 68040-based systems. + +This option inhibits the use of 68881/68882 instructions that have to be +emulated by software on the 68040. Use this option if your 68040 does not +have code to emulate those instructions. + +@item -m68060 +@opindex m68060 +Generate output for a 68060. This is the default when the compiler is +configured for 68060-based systems. + +This option inhibits the use of 68020 and 68881/68882 instructions that +have to be emulated by software on the 68060. Use this option if your 68060 +does not have code to emulate those instructions. + +@item -mcpu32 +@opindex mcpu32 +Generate output for a CPU32. This is the default +when the compiler is configured for CPU32-based systems. + +Use this option for microcontrollers with a +CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334, +68336, 68340, 68341, 68349 and 68360. + +@item -m5200 +@opindex m5200 +Generate output for a 520X ``coldfire'' family cpu. This is the default +when the compiler is configured for 520X-based systems. + +Use this option for microcontroller with a 5200 core, including +the MCF5202, MCF5203, MCF5204 and MCF5202. + + +@item -m68020-40 +@opindex m68020-40 +Generate output for a 68040, without using any of the new instructions. +This results in code which can run relatively efficiently on either a +68020/68881 or a 68030 or a 68040. The generated code does use the +68881 instructions that are emulated on the 68040. + +@item -m68020-60 +@opindex m68020-60 +Generate output for a 68060, without using any of the new instructions. +This results in code which can run relatively efficiently on either a +68020/68881 or a 68030 or a 68040. The generated code does use the +68881 instructions that are emulated on the 68060. + +@item -mfpa +@opindex mfpa +Generate output containing Sun FPA instructions for floating point. + +@item -msoft-float +@opindex msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries are not available for all m68k +targets. Normally the facilities of the machine's usual C compiler are +used, but this can't be done directly in cross-compilation. You must +make your own arrangements to provide suitable library functions for +cross-compilation. The embedded targets @samp{m68k-*-aout} and +@samp{m68k-*-coff} do provide software floating point support. + +@item -mshort +@opindex mshort +Consider type @code{int} to be 16 bits wide, like @code{short int}. + +@item -mnobitfield +@opindex mnobitfield +Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32} +and @option{-m5200} options imply @w{@option{-mnobitfield}}. + +@item -mbitfield +@opindex mbitfield +Do use the bit-field instructions. The @option{-m68020} option implies +@option{-mbitfield}. This is the default if you use a configuration +designed for a 68020. + +@item -mrtd +@opindex mrtd +Use a different function-calling convention, in which functions +that take a fixed number of arguments return with the @code{rtd} +instruction, which pops their arguments while returning. This +saves one instruction in the caller since there is no need to pop +the arguments there. + +This calling convention is incompatible with the one normally +used on Unix, so you cannot use it if you need to call libraries +compiled with the Unix compiler. + +Also, you must provide function prototypes for all functions that +take variable numbers of arguments (including @code{printf}); +otherwise incorrect code will be generated for calls to those +functions. + +In addition, seriously incorrect code will result if you call a +function with too many arguments. (Normally, extra arguments are +harmlessly ignored.) + +The @code{rtd} instruction is supported by the 68010, 68020, 68030, +68040, 68060 and CPU32 processors, but not by the 68000 or 5200. + +@item -malign-int +@itemx -mno-align-int +@opindex malign-int +@opindex mno-align-int +Control whether GCC aligns @code{int}, @code{long}, @code{long long}, +@code{float}, @code{double}, and @code{long double} variables on a 32-bit +boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}). +Aligning variables on 32-bit boundaries produces code that runs somewhat +faster on processors with 32-bit busses at the expense of more memory. + +@strong{Warning:} if you use the @option{-malign-int} switch, GCC will +align structures containing the above types differently than +most published application binary interface specifications for the m68k. + +@item -mpcrel +@opindex mpcrel +Use the pc-relative addressing mode of the 68000 directly, instead of +using a global offset table. At present, this option implies @option{-fpic}, +allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is +not presently supported with @option{-mpcrel}, though this could be supported for +68020 and higher processors. + +@item -mno-strict-align +@itemx -mstrict-align +@opindex mno-strict-align +@opindex mstrict-align +Do not (do) assume that unaligned memory references will be handled by +the system. + +@end table + +@node M68hc1x Options +@subsection M68hc1x Options +@cindex M68hc1x options + +These are the @samp{-m} options defined for the 68hc11 and 68hc12 +microcontrollers. The default values for these options depends on +which style of microcontroller was selected when the compiler was configured; +the defaults for the most common choices are given below. + +@table @gcctabopt +@item -m6811 +@itemx -m68hc11 +@opindex m6811 +@opindex m68hc11 +Generate output for a 68HC11. This is the default +when the compiler is configured for 68HC11-based systems. + +@item -m6812 +@itemx -m68hc12 +@opindex m6812 +@opindex m68hc12 +Generate output for a 68HC12. This is the default +when the compiler is configured for 68HC12-based systems. + +@item -mauto-incdec +@opindex mauto-incdec +Enable the use of 68HC12 pre and post auto-increment and auto-decrement +addressing modes. + +@item -mshort +@opindex mshort +Consider type @code{int} to be 16 bits wide, like @code{short int}. + +@item -msoft-reg-count=@var{count} +@opindex msoft-reg-count +Specify the number of pseudo-soft registers which are used for the +code generation. The maximum number is 32. Using more pseudo-soft +register may or may not result in better code depending on the program. +The default is 4 for 68HC11 and 2 for 68HC12. + +@end table + +@node VAX Options +@subsection VAX Options +@cindex VAX options + +These @samp{-m} options are defined for the VAX: + +@table @gcctabopt +@item -munix +@opindex munix +Do not output certain jump instructions (@code{aobleq} and so on) +that the Unix assembler for the VAX cannot handle across long +ranges. + +@item -mgnu +@opindex mgnu +Do output those jump instructions, on the assumption that you +will assemble with the GNU assembler. + +@item -mg +@opindex mg +Output code for g-format floating point numbers instead of d-format. +@end table + +@node SPARC Options +@subsection SPARC Options +@cindex SPARC options + +These @samp{-m} switches are supported on the SPARC: + +@table @gcctabopt +@item -mno-app-regs +@itemx -mapp-regs +@opindex mno-app-regs +@opindex mapp-regs +Specify @option{-mapp-regs} to generate output using the global registers +2 through 4, which the SPARC SVR4 ABI reserves for applications. This +is the default. + +To be fully SVR4 ABI compliant at the cost of some performance loss, +specify @option{-mno-app-regs}. You should compile libraries and system +software with this option. + +@item -mfpu +@itemx -mhard-float +@opindex mfpu +@opindex mhard-float +Generate output containing floating point instructions. This is the +default. + +@item -mno-fpu +@itemx -msoft-float +@opindex mno-fpu +@opindex msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries are not available for all SPARC +targets. Normally the facilities of the machine's usual C compiler are +used, but this cannot be done directly in cross-compilation. You must make +your own arrangements to provide suitable library functions for +cross-compilation. The embedded targets @samp{sparc-*-aout} and +@samp{sparclite-*-*} do provide software floating point support. + +@option{-msoft-float} changes the calling convention in the output file; +therefore, it is only useful if you compile @emph{all} of a program with +this option. In particular, you need to compile @file{libgcc.a}, the +library that comes with GCC, with @option{-msoft-float} in order for +this to work. + +@item -mhard-quad-float +@opindex mhard-quad-float +Generate output containing quad-word (long double) floating point +instructions. + +@item -msoft-quad-float +@opindex msoft-quad-float +Generate output containing library calls for quad-word (long double) +floating point instructions. The functions called are those specified +in the SPARC ABI@. This is the default. + +As of this writing, there are no sparc implementations that have hardware +support for the quad-word floating point instructions. They all invoke +a trap handler for one of these instructions, and then the trap handler +emulates the effect of the instruction. Because of the trap handler overhead, +this is much slower than calling the ABI library routines. Thus the +@option{-msoft-quad-float} option is the default. + +@item -mno-epilogue +@itemx -mepilogue +@opindex mno-epilogue +@opindex mepilogue +With @option{-mepilogue} (the default), the compiler always emits code for +function exit at the end of each function. Any function exit in +the middle of the function (such as a return statement in C) will +generate a jump to the exit code at the end of the function. + +With @option{-mno-epilogue}, the compiler tries to emit exit code inline +at every function exit. + +@item -mno-flat +@itemx -mflat +@opindex mno-flat +@opindex mflat +With @option{-mflat}, the compiler does not generate save/restore instructions +and will use a ``flat'' or single register window calling convention. +This model uses %i7 as the frame pointer and is compatible with the normal +register window model. Code from either may be intermixed. +The local registers and the input registers (0--5) are still treated as +``call saved'' registers and will be saved on the stack as necessary. + +With @option{-mno-flat} (the default), the compiler emits save/restore +instructions (except for leaf functions) and is the normal mode of operation. + +@item -mno-unaligned-doubles +@itemx -munaligned-doubles +@opindex mno-unaligned-doubles +@opindex munaligned-doubles +Assume that doubles have 8 byte alignment. This is the default. + +With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte +alignment only if they are contained in another type, or if they have an +absolute address. Otherwise, it assumes they have 4 byte alignment. +Specifying this option avoids some rare compatibility problems with code +generated by other compilers. It is not the default because it results +in a performance loss, especially for floating point code. + +@item -mno-faster-structs +@itemx -mfaster-structs +@opindex mno-faster-structs +@opindex mfaster-structs +With @option{-mfaster-structs}, the compiler assumes that structures +should have 8 byte alignment. This enables the use of pairs of +@code{ldd} and @code{std} instructions for copies in structure +assignment, in place of twice as many @code{ld} and @code{st} pairs. +However, the use of this changed alignment directly violates the Sparc +ABI@. Thus, it's intended only for use on targets where the developer +acknowledges that their resulting code will not be directly in line with +the rules of the ABI@. + +@item -mv8 +@itemx -msparclite +@opindex mv8 +@opindex msparclite +These two options select variations on the SPARC architecture. + +By default (unless specifically configured for the Fujitsu SPARClite), +GCC generates code for the v7 variant of the SPARC architecture. + +@option{-mv8} will give you SPARC v8 code. The only difference from v7 +code is that the compiler emits the integer multiply and integer +divide instructions which exist in SPARC v8 but not in SPARC v7. + +@option{-msparclite} will give you SPARClite code. This adds the integer +multiply, integer divide step and scan (@code{ffs}) instructions which +exist in SPARClite but not in SPARC v7. + +These options are deprecated and will be deleted in a future GCC release. +They have been replaced with @option{-mcpu=xxx}. + +@item -mcypress +@itemx -msupersparc +@opindex mcypress +@opindex msupersparc +These two options select the processor for which the code is optimized. + +With @option{-mcypress} (the default), the compiler optimizes code for the +Cypress CY7C602 chip, as used in the SparcStation/SparcServer 3xx series. +This is also appropriate for the older SparcStation 1, 2, IPX etc. + +With @option{-msupersparc} the compiler optimizes code for the SuperSparc cpu, as +used in the SparcStation 10, 1000 and 2000 series. This flag also enables use +of the full SPARC v8 instruction set. + +These options are deprecated and will be deleted in a future GCC release. +They have been replaced with @option{-mcpu=xxx}. + +@item -mcpu=@var{cpu_type} +@opindex mcpu +Set the instruction set, register set, and instruction scheduling parameters +for machine type @var{cpu_type}. Supported values for @var{cpu_type} are +@samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite}, +@samp{hypersparc}, @samp{sparclite86x}, @samp{f930}, @samp{f934}, +@samp{sparclet}, @samp{tsc701}, @samp{v9}, and @samp{ultrasparc}. + +Default instruction scheduling parameters are used for values that select +an architecture and not an implementation. These are @samp{v7}, @samp{v8}, +@samp{sparclite}, @samp{sparclet}, @samp{v9}. + +Here is a list of each supported architecture and their supported +implementations. + +@smallexample + v7: cypress + v8: supersparc, hypersparc + sparclite: f930, f934, sparclite86x + sparclet: tsc701 + v9: ultrasparc +@end smallexample + +@item -mtune=@var{cpu_type} +@opindex mtune +Set the instruction scheduling parameters for machine type +@var{cpu_type}, but do not set the instruction set or register set that the +option @option{-mcpu=@var{cpu_type}} would. + +The same values for @option{-mcpu=@var{cpu_type}} can be used for +@option{-mtune=@var{cpu_type}}, but the only useful values are those +that select a particular cpu implementation. Those are @samp{cypress}, +@samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934}, +@samp{sparclite86x}, @samp{tsc701}, and @samp{ultrasparc}. + +@end table + +These @samp{-m} switches are supported in addition to the above +on the SPARCLET processor. + +@table @gcctabopt +@item -mlittle-endian +@opindex mlittle-endian +Generate code for a processor running in little-endian mode. + +@item -mlive-g0 +@opindex mlive-g0 +Treat register @code{%g0} as a normal register. +GCC will continue to clobber it as necessary but will not assume +it always reads as 0. + +@item -mbroken-saverestore +@opindex mbroken-saverestore +Generate code that does not use non-trivial forms of the @code{save} and +@code{restore} instructions. Early versions of the SPARCLET processor do +not correctly handle @code{save} and @code{restore} instructions used with +arguments. They correctly handle them used without arguments. A @code{save} +instruction used without arguments increments the current window pointer +but does not allocate a new stack frame. It is assumed that the window +overflow trap handler will properly handle this case as will interrupt +handlers. +@end table + +These @samp{-m} switches are supported in addition to the above +on SPARC V9 processors in 64-bit environments. + +@table @gcctabopt +@item -mlittle-endian +@opindex mlittle-endian +Generate code for a processor running in little-endian mode. + +@item -m32 +@itemx -m64 +@opindex m32 +@opindex m64 +Generate code for a 32-bit or 64-bit environment. +The 32-bit environment sets int, long and pointer to 32 bits. +The 64-bit environment sets int to 32 bits and long and pointer +to 64 bits. + +@item -mcmodel=medlow +@opindex mcmodel=medlow +Generate code for the Medium/Low code model: the program must be linked +in the low 32 bits of the address space. Pointers are 64 bits. +Programs can be statically or dynamically linked. + +@item -mcmodel=medmid +@opindex mcmodel=medmid +Generate code for the Medium/Middle code model: the program must be linked +in the low 44 bits of the address space, the text segment must be less than +2G bytes, and data segment must be within 2G of the text segment. +Pointers are 64 bits. + +@item -mcmodel=medany +@opindex mcmodel=medany +Generate code for the Medium/Anywhere code model: the program may be linked +anywhere in the address space, the text segment must be less than +2G bytes, and data segment must be within 2G of the text segment. +Pointers are 64 bits. + +@item -mcmodel=embmedany +@opindex mcmodel=embmedany +Generate code for the Medium/Anywhere code model for embedded systems: +assume a 32-bit text and a 32-bit data segment, both starting anywhere +(determined at link time). Register %g4 points to the base of the +data segment. Pointers are still 64 bits. +Programs are statically linked, PIC is not supported. + +@item -mstack-bias +@itemx -mno-stack-bias +@opindex mstack-bias +@opindex mno-stack-bias +With @option{-mstack-bias}, GCC assumes that the stack pointer, and +frame pointer if present, are offset by @minus{}2047 which must be added back +when making stack frame references. +Otherwise, assume no such offset is present. +@end table + +@node Convex Options +@subsection Convex Options +@cindex Convex options + +These @samp{-m} options are defined for Convex: + +@table @gcctabopt +@item -mc1 +@opindex mc1 +Generate output for C1. The code will run on any Convex machine. +The preprocessor symbol @code{__convex__c1__} is defined. + +@item -mc2 +@opindex mc2 +Generate output for C2. Uses instructions not available on C1. +Scheduling and other optimizations are chosen for max performance on C2. +The preprocessor symbol @code{__convex_c2__} is defined. + +@item -mc32 +@opindex mc32 +Generate output for C32xx. Uses instructions not available on C1. +Scheduling and other optimizations are chosen for max performance on C32. +The preprocessor symbol @code{__convex_c32__} is defined. + +@item -mc34 +@opindex mc34 +Generate output for C34xx. Uses instructions not available on C1. +Scheduling and other optimizations are chosen for max performance on C34. +The preprocessor symbol @code{__convex_c34__} is defined. + +@item -mc38 +@opindex mc38 +Generate output for C38xx. Uses instructions not available on C1. +Scheduling and other optimizations are chosen for max performance on C38. +The preprocessor symbol @code{__convex_c38__} is defined. + +@item -margcount +@opindex margcount +Generate code which puts an argument count in the word preceding each +argument list. This is compatible with regular CC, and a few programs +may need the argument count word. GDB and other source-level debuggers +do not need it; this info is in the symbol table. + +@item -mnoargcount +@opindex mnoargcount +Omit the argument count word. This is the default. + +@item -mvolatile-cache +@opindex mvolatile-cache +Allow volatile references to be cached. This is the default. + +@item -mvolatile-nocache +@opindex mvolatile-nocache +Volatile references bypass the data cache, going all the way to memory. +This is only needed for multi-processor code that does not use standard +synchronization instructions. Making non-volatile references to volatile +locations will not necessarily work. + +@item -mlong32 +@opindex mlong32 +Type long is 32 bits, the same as type int. This is the default. + +@item -mlong64 +@opindex mlong64 +Type long is 64 bits, the same as type long long. This option is useless, +because no library support exists for it. +@end table + +@node AMD29K Options +@subsection AMD29K Options +@cindex AMD29K options + +These @samp{-m} options are defined for the AMD Am29000: + +@table @gcctabopt +@item -mdw +@opindex mdw +@cindex DW bit (29k) +Generate code that assumes the @code{DW} bit is set, i.e., that byte and +halfword operations are directly supported by the hardware. This is the +default. + +@item -mndw +@opindex mndw +Generate code that assumes the @code{DW} bit is not set. + +@item -mbw +@opindex mbw +@cindex byte writes (29k) +Generate code that assumes the system supports byte and halfword write +operations. This is the default. + +@item -mnbw +@opindex mnbw +Generate code that assumes the systems does not support byte and +halfword write operations. @option{-mnbw} implies @option{-mndw}. + +@item -msmall +@opindex msmall +@cindex memory model (29k) +Use a small memory model that assumes that all function addresses are +either within a single 256 KB segment or at an absolute address of less +than 256k. This allows the @code{call} instruction to be used instead +of a @code{const}, @code{consth}, @code{calli} sequence. + +@item -mnormal +@opindex mnormal +Use the normal memory model: Generate @code{call} instructions only when +calling functions in the same file and @code{calli} instructions +otherwise. This works if each file occupies less than 256 KB but allows +the entire executable to be larger than 256 KB@. This is the default. + +@item -mlarge +@opindex mlarge +Always use @code{calli} instructions. Specify this option if you expect +a single file to compile into more than 256 KB of code. + +@item -m29050 +@opindex m29050 +@cindex processor selection (29k) +Generate code for the Am29050. + +@item -m29000 +@opindex m29000 +Generate code for the Am29000. This is the default. + +@item -mkernel-registers +@opindex mkernel-registers +@cindex kernel and user registers (29k) +Generate references to registers @code{gr64-gr95} instead of to +registers @code{gr96-gr127}. This option can be used when compiling +kernel code that wants a set of global registers disjoint from that used +by user-mode code. + +Note that when this option is used, register names in @samp{-f} flags +must use the normal, user-mode, names. + +@item -muser-registers +@opindex muser-registers +Use the normal set of global registers, @code{gr96-gr127}. This is the +default. + +@item -mstack-check +@itemx -mno-stack-check +@opindex mstack-check +@opindex mno-stack-check +@cindex stack checks (29k) +Insert (or do not insert) a call to @code{__msp_check} after each stack +adjustment. This is often used for kernel code. + +@item -mstorem-bug +@itemx -mno-storem-bug +@opindex mstorem-bug +@opindex mno-storem-bug +@cindex storem bug (29k) +@option{-mstorem-bug} handles 29k processors which cannot handle the +separation of a mtsrim insn and a storem instruction (most 29000 chips +to date, but not the 29050). + +@item -mno-reuse-arg-regs +@itemx -mreuse-arg-regs +@opindex mno-reuse-arg-regs +@opindex mreuse-arg-regs +@option{-mno-reuse-arg-regs} tells the compiler to only use incoming argument +registers for copying out arguments. This helps detect calling a function +with fewer arguments than it was declared with. + +@item -mno-impure-text +@itemx -mimpure-text +@opindex mno-impure-text +@opindex mimpure-text +@option{-mimpure-text}, used in addition to @option{-shared}, tells the compiler to +not pass @option{-assert pure-text} to the linker when linking a shared object. + +@item -msoft-float +@opindex msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries are not part of GCC@. +Normally the facilities of the machine's usual C compiler are used, but +this can't be done directly in cross-compilation. You must make your +own arrangements to provide suitable library functions for +cross-compilation. + +@item -mno-multm +@opindex mno-multm +Do not generate multm or multmu instructions. This is useful for some embedded +systems which do not have trap handlers for these instructions. +@end table + +@node ARM Options +@subsection ARM Options +@cindex ARM options + +These @samp{-m} options are defined for Advanced RISC Machines (ARM) +architectures: + +@table @gcctabopt +@item -mapcs-frame +@opindex mapcs-frame +Generate a stack frame that is compliant with the ARM Procedure Call +Standard for all functions, even if this is not strictly necessary for +correct execution of the code. Specifying @option{-fomit-frame-pointer} +with this option will cause the stack frames not to be generated for +leaf functions. The default is @option{-mno-apcs-frame}. + +@item -mapcs +@opindex mapcs +This is a synonym for @option{-mapcs-frame}. + +@item -mapcs-26 +@opindex mapcs-26 +Generate code for a processor running with a 26-bit program counter, +and conforming to the function calling standards for the APCS 26-bit +option. This option replaces the @option{-m2} and @option{-m3} options +of previous releases of the compiler. + +@item -mapcs-32 +@opindex mapcs-32 +Generate code for a processor running with a 32-bit program counter, +and conforming to the function calling standards for the APCS 32-bit +option. This option replaces the @option{-m6} option of previous releases +of the compiler. + +@ignore +@c not currently implemented +@item -mapcs-stack-check +@opindex mapcs-stack-check +Generate code to check the amount of stack space available upon entry to +every function (that actually uses some stack space). If there is +insufficient space available then either the function +@samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be +called, depending upon the amount of stack space required. The run time +system is required to provide these functions. The default is +@option{-mno-apcs-stack-check}, since this produces smaller code. + +@c not currently implemented +@item -mapcs-float +@opindex mapcs-float +Pass floating point arguments using the float point registers. This is +one of the variants of the APCS@. This option is recommended if the +target hardware has a floating point unit or if a lot of floating point +arithmetic is going to be performed by the code. The default is +@option{-mno-apcs-float}, since integer only code is slightly increased in +size if @option{-mapcs-float} is used. + +@c not currently implemented +@item -mapcs-reentrant +@opindex mapcs-reentrant +Generate reentrant, position independent code. The default is +@option{-mno-apcs-reentrant}. +@end ignore + +@item -mthumb-interwork +@opindex mthumb-interwork +Generate code which supports calling between the ARM and Thumb +instruction sets. Without this option the two instruction sets cannot +be reliably used inside one program. The default is +@option{-mno-thumb-interwork}, since slightly larger code is generated +when @option{-mthumb-interwork} is specified. + +@item -mno-sched-prolog +@opindex mno-sched-prolog +Prevent the reordering of instructions in the function prolog, or the +merging of those instruction with the instructions in the function's +body. This means that all functions will start with a recognizable set +of instructions (or in fact one of a choice from a small set of +different function prologues), and this information can be used to +locate the start if functions inside an executable piece of code. The +default is @option{-msched-prolog}. + +@item -mhard-float +@opindex mhard-float +Generate output containing floating point instructions. This is the +default. + +@item -msoft-float +@opindex msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries are not available for all ARM +targets. Normally the facilities of the machine's usual C compiler are +used, but this cannot be done directly in cross-compilation. You must make +your own arrangements to provide suitable library functions for +cross-compilation. + +@option{-msoft-float} changes the calling convention in the output file; +therefore, it is only useful if you compile @emph{all} of a program with +this option. In particular, you need to compile @file{libgcc.a}, the +library that comes with GCC, with @option{-msoft-float} in order for +this to work. + +@item -mlittle-endian +@opindex mlittle-endian +Generate code for a processor running in little-endian mode. This is +the default for all standard configurations. + +@item -mbig-endian +@opindex mbig-endian +Generate code for a processor running in big-endian mode; the default is +to compile code for a little-endian processor. + +@item -mwords-little-endian +@opindex mwords-little-endian +This option only applies when generating code for big-endian processors. +Generate code for a little-endian word order but a big-endian byte +order. That is, a byte order of the form @samp{32107654}. Note: this +option should only be used if you require compatibility with code for +big-endian ARM processors generated by versions of the compiler prior to +2.8. + +@item -malignment-traps +@opindex malignment-traps +Generate code that will not trap if the MMU has alignment traps enabled. +On ARM architectures prior to ARMv4, there were no instructions to +access half-word objects stored in memory. However, when reading from +memory a feature of the ARM architecture allows a word load to be used, +even if the address is unaligned, and the processor core will rotate the +data as it is being loaded. This option tells the compiler that such +misaligned accesses will cause a MMU trap and that it should instead +synthesise the access as a series of byte accesses. The compiler can +still use word accesses to load half-word data if it knows that the +address is aligned to a word boundary. + +This option is ignored when compiling for ARM architecture 4 or later, +since these processors have instructions to directly access half-word +objects in memory. + +@item -mno-alignment-traps +@opindex mno-alignment-traps +Generate code that assumes that the MMU will not trap unaligned +accesses. This produces better code when the target instruction set +does not have half-word memory operations (i.e.@: implementations prior to +ARMv4). + +Note that you cannot use this option to access unaligned word objects, +since the processor will only fetch one 32-bit aligned object from +memory. + +The default setting for most targets is @option{-mno-alignment-traps}, since +this produces better code when there are no half-word memory +instructions available. + +@item -mshort-load-bytes +@itemx -mno-short-load-words +@opindex mshort-load-bytes +@opindex mno-short-load-words +These are deprecated aliases for @option{-malignment-traps}. + +@item -mno-short-load-bytes +@itemx -mshort-load-words +@opindex mno-short-load-bytes +@opindex mshort-load-words +This are deprecated aliases for @option{-mno-alignment-traps}. + +@item -mbsd +@opindex mbsd +This option only applies to RISC iX@. Emulate the native BSD-mode +compiler. This is the default if @option{-ansi} is not specified. + +@item -mxopen +@opindex mxopen +This option only applies to RISC iX@. Emulate the native X/Open-mode +compiler. + +@item -mno-symrename +@opindex mno-symrename +This option only applies to RISC iX@. Do not run the assembler +post-processor, @samp{symrename}, after code has been assembled. +Normally it is necessary to modify some of the standard symbols in +preparation for linking with the RISC iX C library; this option +suppresses this pass. The post-processor is never run when the +compiler is built for cross-compilation. + +@item -mcpu=@var{name} +@opindex mcpu +This specifies the name of the target ARM processor. GCC uses this name +to determine what kind of instructions it can emit when generating +assembly code. Permissible names are: @samp{arm2}, @samp{arm250}, +@samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610}, +@samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm}, +@samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700}, +@samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100}, +@samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm8}, +@samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100}, +@samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920}, +@samp{arm920t}, @samp{arm940t}, @samp{arm9tdmi}, @samp{arm10tdmi}, +@samp{arm1020t}, @samp{xscale}. + +@itemx -mtune=@var{name} +@opindex mtune +This option is very similar to the @option{-mcpu=} option, except that +instead of specifying the actual target processor type, and hence +restricting which instructions can be used, it specifies that GCC should +tune the performance of the code as if the target were of the type +specified in this option, but still choosing the instructions that it +will generate based on the cpu specified by a @option{-mcpu=} option. +For some ARM implementations better performance can be obtained by using +this option. + +@item -march=@var{name} +@opindex march +This specifies the name of the target ARM architecture. GCC uses this +name to determine what kind of instructions it can emit when generating +assembly code. This option can be used in conjunction with or instead +of the @option{-mcpu=} option. Permissible names are: @samp{armv2}, +@samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t}, +@samp{armv5}, @samp{armv5t}, @samp{armv5te}. + +@item -mfpe=@var{number} +@itemx -mfp=@var{number} +@opindex mfpe +@opindex mfp +This specifies the version of the floating point emulation available on +the target. Permissible values are 2 and 3. @option{-mfp=} is a synonym +for @option{-mfpe=}, for compatibility with older versions of GCC@. + +@item -mstructure-size-boundary=@var{n} +@opindex mstructure-size-boundary +The size of all structures and unions will be rounded up to a multiple +of the number of bits set by this option. Permissible values are 8 and +32. The default value varies for different toolchains. For the COFF +targeted toolchain the default value is 8. Specifying the larger number +can produce faster, more efficient code, but can also increase the size +of the program. The two values are potentially incompatible. Code +compiled with one value cannot necessarily expect to work with code or +libraries compiled with the other value, if they exchange information +using structures or unions. + +@item -mabort-on-noreturn +@opindex mabort-on-noreturn +Generate a call to the function @code{abort} at the end of a +@code{noreturn} function. It will be executed if the function tries to +return. + +@item -mlong-calls +@itemx -mno-long-calls +@opindex mlong-calls +@opindex mno-long-calls +Tells the compiler to perform function calls by first loading the +address of the function into a register and then performing a subroutine +call on this register. This switch is needed if the target function +will lie outside of the 64 megabyte addressing range of the offset based +version of subroutine call instruction. + +Even if this switch is enabled, not all function calls will be turned +into long calls. The heuristic is that static functions, functions +which have the @samp{short-call} attribute, functions that are inside +the scope of a @samp{#pragma no_long_calls} directive and functions whose +definitions have already been compiled within the current compilation +unit, will not be turned into long calls. The exception to this rule is +that weak function definitions, functions with the @samp{long-call} +attribute or the @samp{section} attribute, and functions that are within +the scope of a @samp{#pragma long_calls} directive, will always be +turned into long calls. + +This feature is not enabled by default. Specifying +@option{-mno-long-calls} will restore the default behavior, as will +placing the function calls within the scope of a @samp{#pragma +long_calls_off} directive. Note these switches have no effect on how +the compiler generates code to handle function calls via function +pointers. + +@item -mnop-fun-dllimport +@opindex mnop-fun-dllimport +Disable support for the @code{dllimport} attribute. + +@item -msingle-pic-base +@opindex msingle-pic-base +Treat the register used for PIC addressing as read-only, rather than +loading it in the prologue for each function. The run-time system is +responsible for initializing this register with an appropriate value +before execution begins. + +@item -mpic-register=@var{reg} +@opindex mpic-register +Specify the register to be used for PIC addressing. The default is R10 +unless stack-checking is enabled, when R9 is used. + +@item -mpoke-function-name +@opindex mpoke-function-name +Write the name of each function into the text section, directly +preceding the function prologue. The generated code is similar to this: + +@smallexample + t0 + .ascii "arm_poke_function_name", 0 + .align + t1 + .word 0xff000000 + (t1 - t0) + arm_poke_function_name + mov ip, sp + stmfd sp!, @{fp, ip, lr, pc@} + sub fp, ip, #4 +@end smallexample + +When performing a stack backtrace, code can inspect the value of +@code{pc} stored at @code{fp + 0}. If the trace function then looks at +location @code{pc - 12} and the top 8 bits are set, then we know that +there is a function name embedded immediately preceding this location +and has length @code{((pc[-3]) & 0xff000000)}. + +@item -mthumb +@opindex mthumb +Generate code for the 16-bit Thumb instruction set. The default is to +use the 32-bit ARM instruction set. + +@item -mtpcs-frame +@opindex mtpcs-frame +Generate a stack frame that is compliant with the Thumb Procedure Call +Standard for all non-leaf functions. (A leaf function is one that does +not call any other functions.) The default is @option{-mno-tpcs-frame}. + +@item -mtpcs-leaf-frame +@opindex mtpcs-leaf-frame +Generate a stack frame that is compliant with the Thumb Procedure Call +Standard for all leaf functions. (A leaf function is one that does +not call any other functions.) The default is @option{-mno-apcs-leaf-frame}. + +@item -mcallee-super-interworking +@opindex mcallee-super-interworking +Gives all externally visible functions in the file being compiled an ARM +instruction set header which switches to Thumb mode before executing the +rest of the function. This allows these functions to be called from +non-interworking code. + +@item -mcaller-super-interworking +@opindex mcaller-super-interworking +Allows calls via function pointers (including virtual functions) to +execute correctly regardless of whether the target code has been +compiled for interworking or not. There is a small overhead in the cost +of executing a function pointer if this option is enabled. + +@end table + +@node MN10200 Options +@subsection MN10200 Options +@cindex MN10200 options +These @option{-m} options are defined for Matsushita MN10200 architectures: +@table @gcctabopt + +@item -mrelax +@opindex mrelax +Indicate to the linker that it should perform a relaxation optimization pass +to shorten branches, calls and absolute memory addresses. This option only +has an effect when used on the command line for the final link step. + +This option makes symbolic debugging impossible. +@end table + +@node MN10300 Options +@subsection MN10300 Options +@cindex MN10300 options +These @option{-m} options are defined for Matsushita MN10300 architectures: + +@table @gcctabopt +@item -mmult-bug +@opindex mmult-bug +Generate code to avoid bugs in the multiply instructions for the MN10300 +processors. This is the default. + +@item -mno-mult-bug +@opindex mno-mult-bug +Do not generate code to avoid bugs in the multiply instructions for the +MN10300 processors. + +@item -mam33 +@opindex mam33 +Generate code which uses features specific to the AM33 processor. + +@item -mno-am33 +@opindex mno-am33 +Do not generate code which uses features specific to the AM33 processor. This +is the default. + +@item -mno-crt0 +@opindex mno-crt0 +Do not link in the C run-time initialization object file. + +@item -mrelax +@opindex mrelax +Indicate to the linker that it should perform a relaxation optimization pass +to shorten branches, calls and absolute memory addresses. This option only +has an effect when used on the command line for the final link step. + +This option makes symbolic debugging impossible. +@end table + + +@node M32R/D Options +@subsection M32R/D Options +@cindex M32R/D options + +These @option{-m} options are defined for Mitsubishi M32R/D architectures: + +@table @gcctabopt +@item -m32rx +@opindex m32rx +Generate code for the M32R/X@. + +@item -m32r +@opindex m32r +Generate code for the M32R@. This is the default. + +@item -mcode-model=small +@opindex mcode-model=small +Assume all objects live in the lower 16MB of memory (so that their addresses +can be loaded with the @code{ld24} instruction), and assume all subroutines +are reachable with the @code{bl} instruction. +This is the default. + +The addressability of a particular object can be set with the +@code{model} attribute. + +@item -mcode-model=medium +@opindex mcode-model=medium +Assume objects may be anywhere in the 32-bit address space (the compiler +will generate @code{seth/add3} instructions to load their addresses), and +assume all subroutines are reachable with the @code{bl} instruction. + +@item -mcode-model=large +@opindex mcode-model=large +Assume objects may be anywhere in the 32-bit address space (the compiler +will generate @code{seth/add3} instructions to load their addresses), and +assume subroutines may not be reachable with the @code{bl} instruction +(the compiler will generate the much slower @code{seth/add3/jl} +instruction sequence). + +@item -msdata=none +@opindex msdata=none +Disable use of the small data area. Variables will be put into +one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the +@code{section} attribute has been specified). +This is the default. + +The small data area consists of sections @samp{.sdata} and @samp{.sbss}. +Objects may be explicitly put in the small data area with the +@code{section} attribute using one of these sections. + +@item -msdata=sdata +@opindex msdata=sdata +Put small global and static data in the small data area, but do not +generate special code to reference them. + +@item -msdata=use +@opindex msdata=use +Put small global and static data in the small data area, and generate +special instructions to reference them. + +@item -G @var{num} +@opindex G +@cindex smaller data references +Put global and static objects less than or equal to @var{num} bytes +into the small data or bss sections instead of the normal data or bss +sections. The default value of @var{num} is 8. +The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use} +for this option to have any effect. + +All modules should be compiled with the same @option{-G @var{num}} value. +Compiling with different values of @var{num} may or may not work; if it +doesn't the linker will give an error message---incorrect code will not be +generated. + +@end table + +@node M88K Options +@subsection M88K Options +@cindex M88k options + +These @samp{-m} options are defined for Motorola 88k architectures: + +@table @gcctabopt +@item -m88000 +@opindex m88000 +Generate code that works well on both the m88100 and the +m88110. + +@item -m88100 +@opindex m88100 +Generate code that works best for the m88100, but that also +runs on the m88110. + +@item -m88110 +@opindex m88110 +Generate code that works best for the m88110, and may not run +on the m88100. + +@item -mbig-pic +@opindex mbig-pic +Obsolete option to be removed from the next revision. +Use @option{-fPIC}. + +@item -midentify-revision +@opindex midentify-revision +@cindex identifying source, compiler (88k) +Include an @code{ident} directive in the assembler output recording the +source file name, compiler name and version, timestamp, and compilation +flags used. + +@item -mno-underscores +@opindex mno-underscores +@cindex underscores, avoiding (88k) +In assembler output, emit symbol names without adding an underscore +character at the beginning of each name. The default is to use an +underscore as prefix on each name. + +@item -mocs-debug-info +@itemx -mno-ocs-debug-info +@opindex mocs-debug-info +@opindex mno-ocs-debug-info +@cindex OCS (88k) +@cindex debugging, 88k OCS +Include (or omit) additional debugging information (about registers used +in each stack frame) as specified in the 88open Object Compatibility +Standard, ``OCS''@. This extra information allows debugging of code that +has had the frame pointer eliminated. The default for DG/UX, SVr4, and +Delta 88 SVr3.2 is to include this information; other 88k configurations +omit this information by default. + +@item -mocs-frame-position +@opindex mocs-frame-position +@cindex register positions in frame (88k) +When emitting COFF debugging information for automatic variables and +parameters stored on the stack, use the offset from the canonical frame +address, which is the stack pointer (register 31) on entry to the +function. The DG/UX, SVr4, Delta88 SVr3.2, and BCS configurations use +@option{-mocs-frame-position}; other 88k configurations have the default +@option{-mno-ocs-frame-position}. + +@item -mno-ocs-frame-position +@opindex mno-ocs-frame-position +@cindex register positions in frame (88k) +When emitting COFF debugging information for automatic variables and +parameters stored on the stack, use the offset from the frame pointer +register (register 30). When this option is in effect, the frame +pointer is not eliminated when debugging information is selected by the +-g switch. + +@item -moptimize-arg-area +@opindex moptimize-arg-area +@cindex arguments in frame (88k) +Save space by reorganizing the stack frame. This option generates code +that does not agree with the 88open specifications, but uses less +memory. + +@itemx -mno-optimize-arg-area +@opindex mno-optimize-arg-area +Do not reorganize the stack frame to save space. This is the default. +The generated conforms to the specification, but uses more memory. + +@item -mshort-data-@var{num} +@opindex mshort-data +@cindex smaller data references (88k) +@cindex r0-relative references (88k) +Generate smaller data references by making them relative to @code{r0}, +which allows loading a value using a single instruction (rather than the +usual two). You control which data references are affected by +specifying @var{num} with this option. For example, if you specify +@option{-mshort-data-512}, then the data references affected are those +involving displacements of less than 512 bytes. +@option{-mshort-data-@var{num}} is not effective for @var{num} greater +than 64k. + +@item -mserialize-volatile +@opindex mserialize-volatile +@itemx -mno-serialize-volatile +@opindex mno-serialize-volatile +@cindex sequential consistency on 88k +Do, or don't, generate code to guarantee sequential consistency +of volatile memory references. By default, consistency is +guaranteed. + +The order of memory references made by the MC88110 processor does +not always match the order of the instructions requesting those +references. In particular, a load instruction may execute before +a preceding store instruction. Such reordering violates +sequential consistency of volatile memory references, when there +are multiple processors. When consistency must be guaranteed, +GCC generates special instructions, as needed, to force +execution in the proper order. + +The MC88100 processor does not reorder memory references and so +always provides sequential consistency. However, by default, GCC +generates the special instructions to guarantee consistency +even when you use @option{-m88100}, so that the code may be run on an +MC88110 processor. If you intend to run your code only on the +MC88100 processor, you may use @option{-mno-serialize-volatile}. + +The extra code generated to guarantee consistency may affect the +performance of your application. If you know that you can safely +forgo this guarantee, you may use @option{-mno-serialize-volatile}. + +@item -msvr4 +@itemx -msvr3 +@opindex msvr4 +@opindex msvr3 +@cindex assembler syntax, 88k +@cindex SVr4 +Turn on (@option{-msvr4}) or off (@option{-msvr3}) compiler extensions +related to System V release 4 (SVr4). This controls the following: + +@enumerate +@item +Which variant of the assembler syntax to emit. +@item +@option{-msvr4} makes the C preprocessor recognize @samp{#pragma weak} +that is used on System V release 4. +@item +@option{-msvr4} makes GCC issue additional declaration directives used in +SVr4. +@end enumerate + +@option{-msvr4} is the default for the m88k-motorola-sysv4 and +m88k-dg-dgux m88k configurations. @option{-msvr3} is the default for all +other m88k configurations. + +@item -mversion-03.00 +@opindex mversion-03.00 +This option is obsolete, and is ignored. +@c ??? which asm syntax better for GAS? option there too? + +@item -mno-check-zero-division +@itemx -mcheck-zero-division +@opindex mno-check-zero-division +@opindex mcheck-zero-division +@cindex zero division on 88k +Do, or don't, generate code to guarantee that integer division by +zero will be detected. By default, detection is guaranteed. + +Some models of the MC88100 processor fail to trap upon integer +division by zero under certain conditions. By default, when +compiling code that might be run on such a processor, GCC +generates code that explicitly checks for zero-valued divisors +and traps with exception number 503 when one is detected. Use of +@option{-mno-check-zero-division} suppresses such checking for code +generated to run on an MC88100 processor. + +GCC assumes that the MC88110 processor correctly detects all instances +of integer division by zero. When @option{-m88110} is specified, no +explicit checks for zero-valued divisors are generated, and both +@option{-mcheck-zero-division} and @option{-mno-check-zero-division} are +ignored. + +@item -muse-div-instruction +@opindex muse-div-instruction +@cindex divide instruction, 88k +Use the div instruction for signed integer division on the +MC88100 processor. By default, the div instruction is not used. + +On the MC88100 processor the signed integer division instruction +div) traps to the operating system on a negative operand. The +operating system transparently completes the operation, but at a +large cost in execution time. By default, when compiling code +that might be run on an MC88100 processor, GCC emulates signed +integer division using the unsigned integer division instruction +divu), thereby avoiding the large penalty of a trap to the +operating system. Such emulation has its own, smaller, execution +cost in both time and space. To the extent that your code's +important signed integer division operations are performed on two +nonnegative operands, it may be desirable to use the div +instruction directly. + +On the MC88110 processor the div instruction (also known as the +divs instruction) processes negative operands without trapping to +the operating system. When @option{-m88110} is specified, +@option{-muse-div-instruction} is ignored, and the div instruction is used +for signed integer division. + +Note that the result of dividing @code{INT_MIN} by @minus{}1 is undefined. In +particular, the behavior of such a division with and without +@option{-muse-div-instruction} may differ. + +@item -mtrap-large-shift +@itemx -mhandle-large-shift +@opindex mtrap-large-shift +@opindex mhandle-large-shift +@cindex bit shift overflow (88k) +@cindex large bit shifts (88k) +Include code to detect bit-shifts of more than 31 bits; respectively, +trap such shifts or emit code to handle them properly. By default GCC +makes no special provision for large bit shifts. + +@item -mwarn-passed-structs +@opindex mwarn-passed-structs +@cindex structure passing (88k) +Warn when a function passes a struct as an argument or result. +Structure-passing conventions have changed during the evolution of the C +language, and are often the source of portability problems. By default, +GCC issues no such warning. +@end table + +@c break page here to avoid unsightly interparagraph stretch. +@c -zw, 2001-8-17 +@page + +@node RS/6000 and PowerPC Options +@subsection IBM RS/6000 and PowerPC Options +@cindex RS/6000 and PowerPC Options +@cindex IBM RS/6000 and PowerPC Options + +These @samp{-m} options are defined for the IBM RS/6000 and PowerPC: +@table @gcctabopt +@item -mpower +@itemx -mno-power +@itemx -mpower2 +@itemx -mno-power2 +@itemx -mpowerpc +@itemx -mno-powerpc +@itemx -mpowerpc-gpopt +@itemx -mno-powerpc-gpopt +@itemx -mpowerpc-gfxopt +@itemx -mno-powerpc-gfxopt +@itemx -mpowerpc64 +@itemx -mno-powerpc64 +@opindex mpower +@opindex mno-power +@opindex mpower2 +@opindex mno-power2 +@opindex mpowerpc +@opindex mno-powerpc +@opindex mpowerpc-gpopt +@opindex mno-powerpc-gpopt +@opindex mpowerpc-gfxopt +@opindex mno-powerpc-gfxopt +@opindex mpowerpc64 +@opindex mno-powerpc64 +GCC supports two related instruction set architectures for the +RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those +instructions supported by the @samp{rios} chip set used in the original +RS/6000 systems and the @dfn{PowerPC} instruction set is the +architecture of the Motorola MPC5xx, MPC6xx, MPC8xx microprocessors, and +the IBM 4xx microprocessors. + +Neither architecture is a subset of the other. However there is a +large common subset of instructions supported by both. An MQ +register is included in processors supporting the POWER architecture. + +You use these options to specify which instructions are available on the +processor you are using. The default value of these options is +determined when configuring GCC@. Specifying the +@option{-mcpu=@var{cpu_type}} overrides the specification of these +options. We recommend you use the @option{-mcpu=@var{cpu_type}} option +rather than the options listed above. + +The @option{-mpower} option allows GCC to generate instructions that +are found only in the POWER architecture and to use the MQ register. +Specifying @option{-mpower2} implies @option{-power} and also allows GCC +to generate instructions that are present in the POWER2 architecture but +not the original POWER architecture. + +The @option{-mpowerpc} option allows GCC to generate instructions that +are found only in the 32-bit subset of the PowerPC architecture. +Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows +GCC to use the optional PowerPC architecture instructions in the +General Purpose group, including floating-point square root. Specifying +@option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to +use the optional PowerPC architecture instructions in the Graphics +group, including floating-point select. + +The @option{-mpowerpc64} option allows GCC to generate the additional +64-bit instructions that are found in the full PowerPC64 architecture +and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to +@option{-mno-powerpc64}. + +If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC +will use only the instructions in the common subset of both +architectures plus some special AIX common-mode calls, and will not use +the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc} +permits GCC to use any instruction from either architecture and to +allow use of the MQ register; specify this for the Motorola MPC601. + +@item -mnew-mnemonics +@itemx -mold-mnemonics +@opindex mnew-mnemonics +@opindex mold-mnemonics +Select which mnemonics to use in the generated assembler code. With +@option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for +the PowerPC architecture. With @option{-mold-mnemonics} it uses the +assembler mnemonics defined for the POWER architecture. Instructions +defined in only one architecture have only one mnemonic; GCC uses that +mnemonic irrespective of which of these options is specified. + +GCC defaults to the mnemonics appropriate for the architecture in +use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the +value of these option. Unless you are building a cross-compiler, you +should normally not specify either @option{-mnew-mnemonics} or +@option{-mold-mnemonics}, but should instead accept the default. + +@item -mcpu=@var{cpu_type} +@opindex mcpu +Set architecture type, register usage, choice of mnemonics, and +instruction scheduling parameters for machine type @var{cpu_type}. +Supported values for @var{cpu_type} are @samp{rios}, @samp{rios1}, +@samp{rsc}, @samp{rios2}, @samp{rs64a}, @samp{601}, @samp{602}, +@samp{603}, @samp{603e}, @samp{604}, @samp{604e}, @samp{620}, +@samp{630}, @samp{740}, @samp{7400}, @samp{7450}, @samp{750}, +@samp{power}, @samp{power2}, @samp{powerpc}, @samp{403}, @samp{505}, +@samp{801}, @samp{821}, @samp{823}, and @samp{860} and @samp{common}. + +@option{-mcpu=common} selects a completely generic processor. Code +generated under this option will run on any POWER or PowerPC processor. +GCC will use only the instructions in the common subset of both +architectures, and will not use the MQ register. GCC assumes a generic +processor model for scheduling purposes. + +@option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and +@option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit +PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine +types, with an appropriate, generic processor model assumed for +scheduling purposes. + +The other options specify a specific processor. Code generated under +those options will run best on that processor, and may not run at all on +others. + +The @option{-mcpu} options automatically enable or disable other +@option{-m} options as follows: + +@table @samp +@item common +@option{-mno-power}, @option{-mno-powerc} + +@item power +@itemx power2 +@itemx rios1 +@itemx rios2 +@itemx rsc +@option{-mpower}, @option{-mno-powerpc}, @option{-mno-new-mnemonics} + +@item powerpc +@itemx rs64a +@itemx 602 +@itemx 603 +@itemx 603e +@itemx 604 +@itemx 620 +@itemx 630 +@itemx 740 +@itemx 7400 +@itemx 7450 +@itemx 750 +@itemx 505 +@option{-mno-power}, @option{-mpowerpc}, @option{-mnew-mnemonics} + +@item 601 +@option{-mpower}, @option{-mpowerpc}, @option{-mnew-mnemonics} + +@item 403 +@itemx 821 +@itemx 860 +@option{-mno-power}, @option{-mpowerpc}, @option{-mnew-mnemonics}, @option{-msoft-float} +@end table + +@item -mtune=@var{cpu_type} +@opindex mtune +Set the instruction scheduling parameters for machine type +@var{cpu_type}, but do not set the architecture type, register usage, or +choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same +values for @var{cpu_type} are used for @option{-mtune} as for +@option{-mcpu}. If both are specified, the code generated will use the +architecture, registers, and mnemonics set by @option{-mcpu}, but the +scheduling parameters set by @option{-mtune}. + +@item -maltivec +@itemx -mno-altivec +@opindex maltivec +@opindex mno-altivec +These switches enable or disable the use of built-in functions that +allow access to the AltiVec instruction set. You may also need to set +@option{-mabi=altivec} to adjust the current ABI with AltiVec ABI +enhancements. + +@item -mfull-toc +@itemx -mno-fp-in-toc +@itemx -mno-sum-in-toc +@itemx -mminimal-toc +@opindex mfull-toc +@opindex mno-fp-in-toc +@opindex mno-sum-in-toc +@opindex mminimal-toc +Modify generation of the TOC (Table Of Contents), which is created for +every executable file. The @option{-mfull-toc} option is selected by +default. In that case, GCC will allocate at least one TOC entry for +each unique non-automatic variable reference in your program. GCC +will also place floating-point constants in the TOC@. However, only +16,384 entries are available in the TOC@. + +If you receive a linker error message that saying you have overflowed +the available TOC space, you can reduce the amount of TOC space used +with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options. +@option{-mno-fp-in-toc} prevents GCC from putting floating-point +constants in the TOC and @option{-mno-sum-in-toc} forces GCC to +generate code to calculate the sum of an address and a constant at +run-time instead of putting that sum into the TOC@. You may specify one +or both of these options. Each causes GCC to produce very slightly +slower and larger code at the expense of conserving TOC space. + +If you still run out of space in the TOC even when you specify both of +these options, specify @option{-mminimal-toc} instead. This option causes +GCC to make only one TOC entry for every file. When you specify this +option, GCC will produce code that is slower and larger but which +uses extremely little TOC space. You may wish to use this option +only on files that contain less frequently executed code. + +@item -maix64 +@itemx -maix32 +@opindex maix64 +@opindex maix32 +Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit +@code{long} type, and the infrastructure needed to support them. +Specifying @option{-maix64} implies @option{-mpowerpc64} and +@option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and +implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}. + +@item -mxl-call +@itemx -mno-xl-call +@opindex mxl-call +@opindex mno-xl-call +On AIX, pass floating-point arguments to prototyped functions beyond the +register save area (RSA) on the stack in addition to argument FPRs. The +AIX calling convention was extended but not initially documented to +handle an obscure K&R C case of calling a function that takes the +address of its arguments with fewer arguments than declared. AIX XL +compilers access floating point arguments which do not fit in the +RSA from the stack when a subroutine is compiled without +optimization. Because always storing floating-point arguments on the +stack is inefficient and rarely needed, this option is not enabled by +default and only is necessary when calling subroutines compiled by AIX +XL compilers without optimization. + +@item -mpe +@opindex mpe +Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an +application written to use message passing with special startup code to +enable the application to run. The system must have PE installed in the +standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file +must be overridden with the @option{-specs=} option to specify the +appropriate directory location. The Parallel Environment does not +support threads, so the @option{-mpe} option and the @option{-pthread} +option are incompatible. + +@item -msoft-float +@itemx -mhard-float +@opindex msoft-float +@opindex mhard-float +Generate code that does not use (uses) the floating-point register set. +Software floating point emulation is provided if you use the +@option{-msoft-float} option, and pass the option to GCC when linking. + +@item -mmultiple +@itemx -mno-multiple +@opindex mmultiple +@opindex mno-multiple +Generate code that uses (does not use) the load multiple word +instructions and the store multiple word instructions. These +instructions are generated by default on POWER systems, and not +generated on PowerPC systems. Do not use @option{-mmultiple} on little +endian PowerPC systems, since those instructions do not work when the +processor is in little endian mode. The exceptions are PPC740 and +PPC750 which permit the instructions usage in little endian mode. + +@item -mstring +@itemx -mno-string +@opindex mstring +@opindex mno-string +Generate code that uses (does not use) the load string instructions +and the store string word instructions to save multiple registers and +do small block moves. These instructions are generated by default on +POWER systems, and not generated on PowerPC systems. Do not use +@option{-mstring} on little endian PowerPC systems, since those +instructions do not work when the processor is in little endian mode. +The exceptions are PPC740 and PPC750 which permit the instructions +usage in little endian mode. + +@item -mupdate +@itemx -mno-update +@opindex mupdate +@opindex mno-update +Generate code that uses (does not use) the load or store instructions +that update the base register to the address of the calculated memory +location. These instructions are generated by default. If you use +@option{-mno-update}, there is a small window between the time that the +stack pointer is updated and the address of the previous frame is +stored, which means code that walks the stack frame across interrupts or +signals may get corrupted data. + +@item -mfused-madd +@itemx -mno-fused-madd +@opindex mfused-madd +@opindex mno-fused-madd +Generate code that uses (does not use) the floating point multiply and +accumulate instructions. These instructions are generated by default if +hardware floating is used. + +@item -mno-bit-align +@itemx -mbit-align +@opindex mno-bit-align +@opindex mbit-align +On System V.4 and embedded PowerPC systems do not (do) force structures +and unions that contain bit-fields to be aligned to the base type of the +bit-field. + +For example, by default a structure containing nothing but 8 +@code{unsigned} bit-fields of length 1 would be aligned to a 4 byte +boundary and have a size of 4 bytes. By using @option{-mno-bit-align}, +the structure would be aligned to a 1 byte boundary and be one byte in +size. + +@item -mno-strict-align +@itemx -mstrict-align +@opindex mno-strict-align +@opindex mstrict-align +On System V.4 and embedded PowerPC systems do not (do) assume that +unaligned memory references will be handled by the system. + +@item -mrelocatable +@itemx -mno-relocatable +@opindex mrelocatable +@opindex mno-relocatable +On embedded PowerPC systems generate code that allows (does not allow) +the program to be relocated to a different address at runtime. If you +use @option{-mrelocatable} on any module, all objects linked together must +be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}. + +@item -mrelocatable-lib +@itemx -mno-relocatable-lib +@opindex mrelocatable-lib +@opindex mno-relocatable-lib +On embedded PowerPC systems generate code that allows (does not allow) +the program to be relocated to a different address at runtime. Modules +compiled with @option{-mrelocatable-lib} can be linked with either modules +compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or +with modules compiled with the @option{-mrelocatable} options. + +@item -mno-toc +@itemx -mtoc +@opindex mno-toc +@opindex mtoc +On System V.4 and embedded PowerPC systems do not (do) assume that +register 2 contains a pointer to a global area pointing to the addresses +used in the program. + +@item -mlittle +@itemx -mlittle-endian +@opindex mlittle +@opindex mlittle-endian +On System V.4 and embedded PowerPC systems compile code for the +processor in little endian mode. The @option{-mlittle-endian} option is +the same as @option{-mlittle}. + +@item -mbig +@itemx -mbig-endian +@opindex mbig +@opindex mbig-endian +On System V.4 and embedded PowerPC systems compile code for the +processor in big endian mode. The @option{-mbig-endian} option is +the same as @option{-mbig}. + +@item -mcall-sysv +@opindex mcall-sysv +On System V.4 and embedded PowerPC systems compile code using calling +conventions that adheres to the March 1995 draft of the System V +Application Binary Interface, PowerPC processor supplement. This is the +default unless you configured GCC using @samp{powerpc-*-eabiaix}. + +@item -mcall-sysv-eabi +@opindex mcall-sysv-eabi +Specify both @option{-mcall-sysv} and @option{-meabi} options. + +@item -mcall-sysv-noeabi +@opindex mcall-sysv-noeabi +Specify both @option{-mcall-sysv} and @option{-mno-eabi} options. + +@item -mcall-aix +@opindex mcall-aix +On System V.4 and embedded PowerPC systems compile code using calling +conventions that are similar to those used on AIX@. This is the +default if you configured GCC using @samp{powerpc-*-eabiaix}. + +@item -mcall-solaris +@opindex mcall-solaris +On System V.4 and embedded PowerPC systems compile code for the Solaris +operating system. + +@item -mcall-linux +@opindex mcall-linux +On System V.4 and embedded PowerPC systems compile code for the +Linux-based GNU system. + +@item -mcall-gnu +@opindex mcall-gnu +On System V.4 and embedded PowerPC systems compile code for the +Hurd-based GNU system. + +@item -mcall-netbsd +@opindex mcall-netbsd +On System V.4 and embedded PowerPC systems compile code for the +NetBSD operating system. + +@item -maix-struct-return +@opindex maix-struct-return +Return all structures in memory (as specified by the AIX ABI)@. + +@item -msvr4-struct-return +@opindex msvr4-struct-return +Return structures smaller than 8 bytes in registers (as specified by the +SVR4 ABI)@. + +@item -mabi=altivec +@opindex mabi=altivec +Extend the current ABI with AltiVec ABI extensions. This does not +change the default ABI, instead it adds the AltiVec ABI extensions to +the current ABI@. + +@item -mprototype +@itemx -mno-prototype +@opindex mprototype +@opindex mno-prototype +On System V.4 and embedded PowerPC systems assume that all calls to +variable argument functions are properly prototyped. Otherwise, the +compiler must insert an instruction before every non prototyped call to +set or clear bit 6 of the condition code register (@var{CR}) to +indicate whether floating point values were passed in the floating point +registers in case the function takes a variable arguments. With +@option{-mprototype}, only calls to prototyped variable argument functions +will set or clear the bit. + +@item -msim +@opindex msim +On embedded PowerPC systems, assume that the startup module is called +@file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and +@file{libc.a}. This is the default for @samp{powerpc-*-eabisim}. +configurations. + +@item -mmvme +@opindex mmvme +On embedded PowerPC systems, assume that the startup module is called +@file{crt0.o} and the standard C libraries are @file{libmvme.a} and +@file{libc.a}. + +@item -mads +@opindex mads +On embedded PowerPC systems, assume that the startup module is called +@file{crt0.o} and the standard C libraries are @file{libads.a} and +@file{libc.a}. + +@item -myellowknife +@opindex myellowknife +On embedded PowerPC systems, assume that the startup module is called +@file{crt0.o} and the standard C libraries are @file{libyk.a} and +@file{libc.a}. + +@item -mvxworks +@opindex mvxworks +On System V.4 and embedded PowerPC systems, specify that you are +compiling for a VxWorks system. + +@item -memb +@opindex memb +On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags +header to indicate that @samp{eabi} extended relocations are used. + +@item -meabi +@itemx -mno-eabi +@opindex meabi +@opindex mno-eabi +On System V.4 and embedded PowerPC systems do (do not) adhere to the +Embedded Applications Binary Interface (eabi) which is a set of +modifications to the System V.4 specifications. Selecting @option{-meabi} +means that the stack is aligned to an 8 byte boundary, a function +@code{__eabi} is called to from @code{main} to set up the eabi +environment, and the @option{-msdata} option can use both @code{r2} and +@code{r13} to point to two separate small data areas. Selecting +@option{-mno-eabi} means that the stack is aligned to a 16 byte boundary, +do not call an initialization function from @code{main}, and the +@option{-msdata} option will only use @code{r13} to point to a single +small data area. The @option{-meabi} option is on by default if you +configured GCC using one of the @samp{powerpc*-*-eabi*} options. + +@item -msdata=eabi +@opindex msdata=eabi +On System V.4 and embedded PowerPC systems, put small initialized +@code{const} global and static data in the @samp{.sdata2} section, which +is pointed to by register @code{r2}. Put small initialized +non-@code{const} global and static data in the @samp{.sdata} section, +which is pointed to by register @code{r13}. Put small uninitialized +global and static data in the @samp{.sbss} section, which is adjacent to +the @samp{.sdata} section. The @option{-msdata=eabi} option is +incompatible with the @option{-mrelocatable} option. The +@option{-msdata=eabi} option also sets the @option{-memb} option. + +@item -msdata=sysv +@opindex msdata=sysv +On System V.4 and embedded PowerPC systems, put small global and static +data in the @samp{.sdata} section, which is pointed to by register +@code{r13}. Put small uninitialized global and static data in the +@samp{.sbss} section, which is adjacent to the @samp{.sdata} section. +The @option{-msdata=sysv} option is incompatible with the +@option{-mrelocatable} option. + +@item -msdata=default +@itemx -msdata +@opindex msdata=default +@opindex msdata +On System V.4 and embedded PowerPC systems, if @option{-meabi} is used, +compile code the same as @option{-msdata=eabi}, otherwise compile code the +same as @option{-msdata=sysv}. + +@item -msdata-data +@opindex msdata-data +On System V.4 and embedded PowerPC systems, put small global and static +data in the @samp{.sdata} section. Put small uninitialized global and +static data in the @samp{.sbss} section. Do not use register @code{r13} +to address small data however. This is the default behavior unless +other @option{-msdata} options are used. + +@item -msdata=none +@itemx -mno-sdata +@opindex msdata=none +@opindex mno-sdata +On embedded PowerPC systems, put all initialized global and static data +in the @samp{.data} section, and all uninitialized data in the +@samp{.bss} section. + +@item -G @var{num} +@opindex G +@cindex smaller data references (PowerPC) +@cindex .sdata/.sdata2 references (PowerPC) +On embedded PowerPC systems, put global and static items less than or +equal to @var{num} bytes into the small data or bss sections instead of +the normal data or bss section. By default, @var{num} is 8. The +@option{-G @var{num}} switch is also passed to the linker. +All modules should be compiled with the same @option{-G @var{num}} value. + +@item -mregnames +@itemx -mno-regnames +@opindex mregnames +@opindex mno-regnames +On System V.4 and embedded PowerPC systems do (do not) emit register +names in the assembly language output using symbolic forms. + +@item -pthread +@opindex pthread +Adds support for multithreading with the @dfn{pthreads} library. +This option sets flags for both the preprocessor and linker. + +@end table + +@node RT Options +@subsection IBM RT Options +@cindex RT options +@cindex IBM RT options + +These @samp{-m} options are defined for the IBM RT PC: + +@table @gcctabopt +@item -min-line-mul +@opindex min-line-mul +Use an in-line code sequence for integer multiplies. This is the +default. + +@item -mcall-lib-mul +@opindex mcall-lib-mul +Call @code{lmul$$} for integer multiples. + +@item -mfull-fp-blocks +@opindex mfull-fp-blocks +Generate full-size floating point data blocks, including the minimum +amount of scratch space recommended by IBM@. This is the default. + +@item -mminimum-fp-blocks +@opindex mminimum-fp-blocks +Do not include extra scratch space in floating point data blocks. This +results in smaller code, but slower execution, since scratch space must +be allocated dynamically. + +@cindex @file{varargs.h} and RT PC +@cindex @file{stdarg.h} and RT PC +@item -mfp-arg-in-fpregs +@opindex mfp-arg-in-fpregs +Use a calling sequence incompatible with the IBM calling convention in +which floating point arguments are passed in floating point registers. +Note that @code{varargs.h} and @code{stdarg.h} will not work with +floating point operands if this option is specified. + +@item -mfp-arg-in-gregs +@opindex mfp-arg-in-gregs +Use the normal calling convention for floating point arguments. This is +the default. + +@item -mhc-struct-return +@opindex mhc-struct-return +Return structures of more than one word in memory, rather than in a +register. This provides compatibility with the MetaWare HighC (hc) +compiler. Use the option @option{-fpcc-struct-return} for compatibility +with the Portable C Compiler (pcc). + +@item -mnohc-struct-return +@opindex mnohc-struct-return +Return some structures of more than one word in registers, when +convenient. This is the default. For compatibility with the +IBM-supplied compilers, use the option @option{-fpcc-struct-return} or the +option @option{-mhc-struct-return}. +@end table + +@node MIPS Options +@subsection MIPS Options +@cindex MIPS options + +These @samp{-m} options are defined for the MIPS family of computers: + +@table @gcctabopt + +@item -march=@var{cpu-type} +@opindex march +Assume the defaults for the machine type @var{cpu-type} when generating +instructions. The choices for @var{cpu-type} are @samp{r2000}, @samp{r3000}, +@samp{r3900}, @samp{r4000}, @samp{r4100}, @samp{r4300}, @samp{r4400}, +@samp{r4600}, @samp{r4650}, @samp{r5000}, @samp{r6000}, @samp{r8000}, +and @samp{orion}. Additionally, the @samp{r2000}, @samp{r3000}, +@samp{r4000}, @samp{r5000}, and @samp{r6000} can be abbreviated as +@samp{r2k} (or @samp{r2K}), @samp{r3k}, etc. + +@item -mtune=@var{cpu-type} +@opindex mtune +Assume the defaults for the machine type @var{cpu-type} when scheduling +instructions. The choices for @var{cpu-type} are @samp{r2000}, @samp{r3000}, +@samp{r3900}, @samp{r4000}, @samp{r4100}, @samp{r4300}, @samp{r4400}, +@samp{r4600}, @samp{r4650}, @samp{r5000}, @samp{r6000}, @samp{r8000}, +and @samp{orion}. Additionally, the @samp{r2000}, @samp{r3000}, +@samp{r4000}, @samp{r5000}, and @samp{r6000} can be abbreviated as +@samp{r2k} (or @samp{r2K}), @samp{r3k}, etc. While picking a specific +@var{cpu-type} will schedule things appropriately for that particular +chip, the compiler will not generate any code that does not meet level 1 +of the MIPS ISA (instruction set architecture) without a @option{-mipsX} +or @option{-mabi} switch being used. + +@item -mcpu=@var{cpu-type} +@opindex mcpu +This is identical to specifying both @option{-march} and @option{-mtune}. + +@item -mips1 +@opindex mips1 +Issue instructions from level 1 of the MIPS ISA@. This is the default. +@samp{r3000} is the default @var{cpu-type} at this ISA level. + +@item -mips2 +@opindex mips2 +Issue instructions from level 2 of the MIPS ISA (branch likely, square +root instructions). @samp{r6000} is the default @var{cpu-type} at this +ISA level. + +@item -mips3 +@opindex mips3 +Issue instructions from level 3 of the MIPS ISA (64-bit instructions). +@samp{r4000} is the default @var{cpu-type} at this ISA level. + +@item -mips4 +@opindex mips4 +Issue instructions from level 4 of the MIPS ISA (conditional move, +prefetch, enhanced FPU instructions). @samp{r8000} is the default +@var{cpu-type} at this ISA level. + +@item -mfp32 +@opindex mfp32 +Assume that 32 32-bit floating point registers are available. This is +the default. + +@item -mfp64 +@opindex mfp64 +Assume that 32 64-bit floating point registers are available. This is +the default when the @option{-mips3} option is used. + +@item -mfused-madd +@itemx -mno-fused-madd +@opindex mfused-madd +@opindex mno-fused-madd +Generate code that uses (does not use) the floating point multiply and +accumulate instructions, when they are available. These instructions +are generated by default if they are available, but this may be +undesirable if the extra precision causes problems or on certain chips +in the mode where denormals are rounded to zero where denormals +generated by multiply and accumulate instructions cause exceptions +anyway. + +@item -mgp32 +@opindex mgp32 +Assume that 32 32-bit general purpose registers are available. This is +the default. + +@item -mgp64 +@opindex mgp64 +Assume that 32 64-bit general purpose registers are available. This is +the default when the @option{-mips3} option is used. + +@item -mint64 +@opindex mint64 +Force int and long types to be 64 bits wide. See @option{-mlong32} for an +explanation of the default, and the width of pointers. + +@item -mlong64 +@opindex mlong64 +Force long types to be 64 bits wide. See @option{-mlong32} for an +explanation of the default, and the width of pointers. + +@item -mlong32 +@opindex mlong32 +Force long, int, and pointer types to be 32 bits wide. + +If none of @option{-mlong32}, @option{-mlong64}, or @option{-mint64} are set, +the size of ints, longs, and pointers depends on the ABI and ISA chosen. +For @option{-mabi=32}, and @option{-mabi=n32}, ints and longs are 32 bits +wide. For @option{-mabi=64}, ints are 32 bits, and longs are 64 bits wide. +For @option{-mabi=eabi} and either @option{-mips1} or @option{-mips2}, ints +and longs are 32 bits wide. For @option{-mabi=eabi} and higher ISAs, ints +are 32 bits, and longs are 64 bits wide. The width of pointer types is +the smaller of the width of longs or the width of general purpose +registers (which in turn depends on the ISA)@. + +@item -mabi=32 +@itemx -mabi=o64 +@itemx -mabi=n32 +@itemx -mabi=64 +@itemx -mabi=eabi +@opindex mabi=32 +@opindex mabi=o64 +@opindex mabi=n32 +@opindex mabi=64 +@opindex mabi=eabi +Generate code for the indicated ABI@. The default instruction level is +@option{-mips1} for @samp{32}, @option{-mips3} for @samp{n32}, and +@option{-mips4} otherwise. Conversely, with @option{-mips1} or +@option{-mips2}, the default ABI is @samp{32}; otherwise, the default ABI +is @samp{64}. + +@item -mmips-as +@opindex mmips-as +Generate code for the MIPS assembler, and invoke @file{mips-tfile} to +add normal debug information. This is the default for all +platforms except for the OSF/1 reference platform, using the OSF/rose +object format. If the either of the @option{-gstabs} or @option{-gstabs+} +switches are used, the @file{mips-tfile} program will encapsulate the +stabs within MIPS ECOFF@. + +@item -mgas +@opindex mgas +Generate code for the GNU assembler. This is the default on the OSF/1 +reference platform, using the OSF/rose object format. Also, this is +the default if the configure option @option{--with-gnu-as} is used. + +@item -msplit-addresses +@itemx -mno-split-addresses +@opindex msplit-addresses +@opindex mno-split-addresses +Generate code to load the high and low parts of address constants separately. +This allows GCC to optimize away redundant loads of the high order +bits of addresses. This optimization requires GNU as and GNU ld. +This optimization is enabled by default for some embedded targets where +GNU as and GNU ld are standard. + +@item -mrnames +@itemx -mno-rnames +@opindex mrnames +@opindex mno-rnames +The @option{-mrnames} switch says to output code using the MIPS software +names for the registers, instead of the hardware names (ie, @var{a0} +instead of @var{$4}). The only known assembler that supports this option +is the Algorithmics assembler. + +@item -mgpopt +@itemx -mno-gpopt +@opindex mgpopt +@opindex mno-gpopt +The @option{-mgpopt} switch says to write all of the data declarations +before the instructions in the text section, this allows the MIPS +assembler to generate one word memory references instead of using two +words for short global or static data items. This is on by default if +optimization is selected. + +@item -mstats +@itemx -mno-stats +@opindex mstats +@opindex mno-stats +For each non-inline function processed, the @option{-mstats} switch +causes the compiler to emit one line to the standard error file to +print statistics about the program (number of registers saved, stack +size, etc.). + +@item -mmemcpy +@itemx -mno-memcpy +@opindex mmemcpy +@opindex mno-memcpy +The @option{-mmemcpy} switch makes all block moves call the appropriate +string function (@samp{memcpy} or @samp{bcopy}) instead of possibly +generating inline code. + +@item -mmips-tfile +@itemx -mno-mips-tfile +@opindex mmips-tfile +@opindex mno-mips-tfile +The @option{-mno-mips-tfile} switch causes the compiler not +postprocess the object file with the @file{mips-tfile} program, +after the MIPS assembler has generated it to add debug support. If +@file{mips-tfile} is not run, then no local variables will be +available to the debugger. In addition, @file{stage2} and +@file{stage3} objects will have the temporary file names passed to the +assembler embedded in the object file, which means the objects will +not compare the same. The @option{-mno-mips-tfile} switch should only +be used when there are bugs in the @file{mips-tfile} program that +prevents compilation. + +@item -msoft-float +@opindex msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries are not part of GCC@. +Normally the facilities of the machine's usual C compiler are used, but +this can't be done directly in cross-compilation. You must make your +own arrangements to provide suitable library functions for +cross-compilation. + +@item -mhard-float +@opindex mhard-float +Generate output containing floating point instructions. This is the +default if you use the unmodified sources. + +@item -mabicalls +@itemx -mno-abicalls +@opindex mabicalls +@opindex mno-abicalls +Emit (or do not emit) the pseudo operations @samp{.abicalls}, +@samp{.cpload}, and @samp{.cprestore} that some System V.4 ports use for +position independent code. + +@item -mlong-calls +@itemx -mno-long-calls +@opindex mlong-calls +@opindex mno-long-calls +Do all calls with the @samp{JALR} instruction, which requires +loading up a function's address into a register before the call. +You need to use this switch, if you call outside of the current +512 megabyte segment to functions that are not through pointers. + +@item -mhalf-pic +@itemx -mno-half-pic +@opindex mhalf-pic +@opindex mno-half-pic +Put pointers to extern references into the data section and load them +up, rather than put the references in the text section. + +@item -membedded-pic +@itemx -mno-embedded-pic +@opindex membedded-pic +@opindex mno-embedded-pic +Generate PIC code suitable for some embedded systems. All calls are +made using PC relative address, and all data is addressed using the $gp +register. No more than 65536 bytes of global data may be used. This +requires GNU as and GNU ld which do most of the work. This currently +only works on targets which use ECOFF; it does not work with ELF@. + +@item -membedded-data +@itemx -mno-embedded-data +@opindex membedded-data +@opindex mno-embedded-data +Allocate variables to the read-only data section first if possible, then +next in the small data section if possible, otherwise in data. This gives +slightly slower code than the default, but reduces the amount of RAM required +when executing, and thus may be preferred for some embedded systems. + +@item -muninit-const-in-rodata +@itemx -mno-uninit-const-in-rodata +@opindex muninit-const-in-rodata +@opindex mno-uninit-const-in-rodata +When used together with @option{-membedded-data}, it will always store uninitialized +const variables in the read-only data section. + +@item -msingle-float +@itemx -mdouble-float +@opindex msingle-float +@opindex mdouble-float +The @option{-msingle-float} switch tells gcc to assume that the floating +point coprocessor only supports single precision operations, as on the +@samp{r4650} chip. The @option{-mdouble-float} switch permits gcc to use +double precision operations. This is the default. + +@item -mmad +@itemx -mno-mad +@opindex mmad +@opindex mno-mad +Permit use of the @samp{mad}, @samp{madu} and @samp{mul} instructions, +as on the @samp{r4650} chip. + +@item -m4650 +@opindex m4650 +Turns on @option{-msingle-float}, @option{-mmad}, and, at least for now, +@option{-mcpu=r4650}. + +@item -mips16 +@itemx -mno-mips16 +@opindex mips16 +@opindex mno-mips16 +Enable 16-bit instructions. + +@item -mentry +@opindex mentry +Use the entry and exit pseudo ops. This option can only be used with +@option{-mips16}. + +@item -EL +@opindex EL +Compile code for the processor in little endian mode. +The requisite libraries are assumed to exist. + +@item -EB +@opindex EB +Compile code for the processor in big endian mode. +The requisite libraries are assumed to exist. + +@item -G @var{num} +@opindex G +@cindex smaller data references (MIPS) +@cindex gp-relative references (MIPS) +Put global and static items less than or equal to @var{num} bytes into +the small data or bss sections instead of the normal data or bss +section. This allows the assembler to emit one word memory reference +instructions based on the global pointer (@var{gp} or @var{$28}), +instead of the normal two words used. By default, @var{num} is 8 when +the MIPS assembler is used, and 0 when the GNU assembler is used. The +@option{-G @var{num}} switch is also passed to the assembler and linker. +All modules should be compiled with the same @option{-G @var{num}} +value. + +@item -nocpp +@opindex nocpp +Tell the MIPS assembler to not run its preprocessor over user +assembler files (with a @samp{.s} suffix) when assembling them. + +@item -mfix7000 +@opindex mfix7000 +Pass an option to gas which will cause nops to be inserted if +the read of the destination register of an mfhi or mflo instruction +occurs in the following two instructions. + +@item -no-crt0 +@opindex no-crt0 +Do not include the default crt0. + +@item -mflush-func=@var{func} +@itemx -mno-flush-func +@opindex mflush-func +Specifies the function to call to flush the I and D caches, or to not +call any such function. If called, the function must take the same +arguments as the common @code{_flush_func()}, that is, the address of the +memory range for which the cache is being flushed, the size of the +memory range, and the number 3 (to flush both caches). The default +depends on the target gcc was configured for, but commonly is either +@samp{_flush_func} or @samp{__cpu_flush}. +@end table + +These options are defined by the macro +@code{TARGET_SWITCHES} in the machine description. The default for the +options is also defined by that macro, which enables you to change the +defaults. + +@node i386 and x86-64 Options +@subsection Intel 386 and AMD x86-64 Options +@cindex i386 Options +@cindex x86-64 Options +@cindex Intel 386 Options +@cindex AMD x86-64 Options + +These @samp{-m} options are defined for the i386 and x86-64 family of +computers: + +@table @gcctabopt +@item -mcpu=@var{cpu-type} +@opindex mcpu +Tune to @var{cpu-type} everything applicable about the generated code, except +for the ABI and the set of available instructions. The choices for +@var{cpu-type} are @samp{i386}, @samp{i486}, @samp{i586}, @samp{i686}, +@samp{pentium}, @samp{pentium-mmx}, @samp{pentiumpro}, @samp{pentium2}, +@samp{pentium3}, @samp{pentium4}, @samp{k6}, @samp{k6-2}, @samp{k6-3}, +@samp{athlon}, @samp{athlon-tbird}, @samp{athlon-4}, @samp{athlon-xp} +and @samp{athlon-mp}. + +While picking a specific @var{cpu-type} will schedule things appropriately +for that particular chip, the compiler will not generate any code that +does not run on the i386 without the @option{-march=@var{cpu-type}} option +being used. @samp{i586} is equivalent to @samp{pentium} and @samp{i686} +is equivalent to @samp{pentiumpro}. @samp{k6} and @samp{athlon} are the +AMD chips as opposed to the Intel ones. + +@item -march=@var{cpu-type} +@opindex march +Generate instructions for the machine type @var{cpu-type}. The choices +for @var{cpu-type} are the same as for @option{-mcpu}. Moreover, +specifying @option{-march=@var{cpu-type}} implies @option{-mcpu=@var{cpu-type}}. + +@item -m386 +@itemx -m486 +@itemx -mpentium +@itemx -mpentiumpro +@opindex m386 +@opindex m486 +@opindex mpentium +@opindex mpentiumpro +These options are synonyms for @option{-mcpu=i386}, @option{-mcpu=i486}, +@option{-mcpu=pentium}, and @option{-mcpu=pentiumpro} respectively. +These synonyms are deprecated. + +@item -mfpmath=@var{unit} +@opindex march +generate floating point arithmetics for selected unit @var{unit}. the choices +for @var{unit} are: + +@table @samp +@item 387 +Use the standard 387 floating point coprocessor present majority of chips and +emulated otherwise. Code compiled with this option will run almost everywhere. +The temporary results are computed in 80bit precesion instead of precision +specified by the type resulting in slightly different results compared to most +of other chips. See @option{-ffloat-store} for more detailed description. + +This is the default choice for i386 compiler. + +@item sse +Use scalar floating point instructions present in the SSE instruction set. +This instruction set is supported by Pentium3 and newer chips, in the AMD line +by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE +instruction set supports only single precision arithmetics, thus the double and +extended precision arithmetics is still done using 387. Later version, present +only in Pentium4 and the future AMD x86-64 chips supports double precision +arithmetics too. + +For i387 you need to use @option{-march=@var{cpu-type}}, @option{-msse} or +@option{-msse2} switches to enable SSE extensions and make this option +effective. For x86-64 compiler, these extensions are enabled by default. + +The resulting code should be considerably faster in majority of cases and avoid +the numerical instability problems of 387 code, but may break some existing +code that expects temporaries to be 80bit. + +This is the default choice for x86-64 compiler. + +@item sse,387 +Attempt to utilize both instruction sets at once. This effectivly double the +amount of available registers and on chips with separate execution units for +387 and SSE the execution resources too. Use this option with care, as it is +still experimental, because gcc register allocator does not model separate +functional units well resulting in instable performance. +@end table + +@item -masm=@var{dialect} +@opindex masm=@var{dialect} +Output asm instructions using selected @var{dialect}. Supported choices are +@samp{intel} or @samp{att} (the default one). + +@item -mieee-fp +@itemx -mno-ieee-fp +@opindex mieee-fp +@opindex mno-ieee-fp +Control whether or not the compiler uses IEEE floating point +comparisons. These handle correctly the case where the result of a +comparison is unordered. + +@item -msoft-float +@opindex msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries are not part of GCC@. +Normally the facilities of the machine's usual C compiler are used, but +this can't be done directly in cross-compilation. You must make your +own arrangements to provide suitable library functions for +cross-compilation. + +On machines where a function returns floating point results in the 80387 +register stack, some floating point opcodes may be emitted even if +@option{-msoft-float} is used. + +@item -mno-fp-ret-in-387 +@opindex mno-fp-ret-in-387 +Do not use the FPU registers for return values of functions. + +The usual calling convention has functions return values of types +@code{float} and @code{double} in an FPU register, even if there +is no FPU@. The idea is that the operating system should emulate +an FPU@. + +The option @option{-mno-fp-ret-in-387} causes such values to be returned +in ordinary CPU registers instead. + +@item -mno-fancy-math-387 +@opindex mno-fancy-math-387 +Some 387 emulators do not support the @code{sin}, @code{cos} and +@code{sqrt} instructions for the 387. Specify this option to avoid +generating those instructions. This option is the default on FreeBSD@. +As of revision 2.6.1, these instructions are not generated unless you +also use the @option{-funsafe-math-optimizations} switch. + +@item -malign-double +@itemx -mno-align-double +@opindex malign-double +@opindex mno-align-double +Control whether GCC aligns @code{double}, @code{long double}, and +@code{long long} variables on a two word boundary or a one word +boundary. Aligning @code{double} variables on a two word boundary will +produce code that runs somewhat faster on a @samp{Pentium} at the +expense of more memory. + +@item -m128bit-long-double +@opindex m128bit-long-double +Control the size of @code{long double} type. i386 application binary interface +specify the size to be 12 bytes, while modern architectures (Pentium and newer) +prefer @code{long double} aligned to 8 or 16 byte boundary. This is +impossible to reach with 12 byte long doubles in the array accesses. + +@strong{Warning:} if you use the @option{-m128bit-long-double} switch, the +structures and arrays containing @code{long double} will change their size as +well as function calling convention for function taking @code{long double} +will be modified. + +@item -m96bit-long-double +@opindex m96bit-long-double +Set the size of @code{long double} to 96 bits as required by the i386 +application binary interface. This is the default. + +@item -msvr3-shlib +@itemx -mno-svr3-shlib +@opindex msvr3-shlib +@opindex mno-svr3-shlib +Control whether GCC places uninitialized local variables into the +@code{bss} or @code{data} segments. @option{-msvr3-shlib} places them +into @code{bss}. These options are meaningful only on System V Release 3. + +@item -mrtd +@opindex mrtd +Use a different function-calling convention, in which functions that +take a fixed number of arguments return with the @code{ret} @var{num} +instruction, which pops their arguments while returning. This saves one +instruction in the caller since there is no need to pop the arguments +there. + +You can specify that an individual function is called with this calling +sequence with the function attribute @samp{stdcall}. You can also +override the @option{-mrtd} option by using the function attribute +@samp{cdecl}. @xref{Function Attributes}. + +@strong{Warning:} this calling convention is incompatible with the one +normally used on Unix, so you cannot use it if you need to call +libraries compiled with the Unix compiler. + +Also, you must provide function prototypes for all functions that +take variable numbers of arguments (including @code{printf}); +otherwise incorrect code will be generated for calls to those +functions. + +In addition, seriously incorrect code will result if you call a +function with too many arguments. (Normally, extra arguments are +harmlessly ignored.) + +@item -mregparm=@var{num} +@opindex mregparm +Control how many registers are used to pass integer arguments. By +default, no registers are used to pass arguments, and at most 3 +registers can be used. You can control this behavior for a specific +function by using the function attribute @samp{regparm}. +@xref{Function Attributes}. + +@strong{Warning:} if you use this switch, and +@var{num} is nonzero, then you must build all modules with the same +value, including any libraries. This includes the system libraries and +startup modules. + +@item -mpreferred-stack-boundary=@var{num} +@opindex mpreferred-stack-boundary +Attempt to keep the stack boundary aligned to a 2 raised to @var{num} +byte boundary. If @option{-mpreferred-stack-boundary} is not specified, +the default is 4 (16 bytes or 128 bits), except when optimizing for code +size (@option{-Os}), in which case the default is the minimum correct +alignment (4 bytes for x86, and 8 bytes for x86-64). + +On Pentium and PentiumPro, @code{double} and @code{long double} values +should be aligned to an 8 byte boundary (see @option{-malign-double}) or +suffer significant run time performance penalties. On Pentium III, the +Streaming SIMD Extension (SSE) data type @code{__m128} suffers similar +penalties if it is not 16 byte aligned. + +To ensure proper alignment of this values on the stack, the stack boundary +must be as aligned as that required by any value stored on the stack. +Further, every function must be generated such that it keeps the stack +aligned. Thus calling a function compiled with a higher preferred +stack boundary from a function compiled with a lower preferred stack +boundary will most likely misalign the stack. It is recommended that +libraries that use callbacks always use the default setting. + +This extra alignment does consume extra stack space, and generally +increases code size. Code that is sensitive to stack space usage, such +as embedded systems and operating system kernels, may want to reduce the +preferred alignment to @option{-mpreferred-stack-boundary=2}. + +@item -mmmx +@itemx -mno-mmx +@item -msse +@itemx -mno-sse +@item -msse2 +@itemx -mno-sse2 +@item -m3dnow +@itemx -mno-3dnow +@opindex mmmx +@opindex mno-mmx +@opindex msse +@opindex mno-sse +@opindex m3dnow +@opindex mno-3dnow +These switches enable or disable the use of built-in functions that allow +direct access to the MMX, SSE and 3Dnow extensions of the instruction set. + +@xref{X86 Built-in Functions}, for details of the functions enabled +and disabled by these switches. + +@item -mpush-args +@itemx -mno-push-args +@opindex mpush-args +@opindex mno-push-args +Use PUSH operations to store outgoing parameters. This method is shorter +and usually equally fast as method using SUB/MOV operations and is enabled +by default. In some cases disabling it may improve performance because of +improved scheduling and reduced dependencies. + +@item -maccumulate-outgoing-args +@opindex maccumulate-outgoing-args +If enabled, the maximum amount of space required for outgoing arguments will be +computed in the function prologue. This is faster on most modern CPUs +because of reduced dependencies, improved scheduling and reduced stack usage +when preferred stack boundary is not equal to 2. The drawback is a notable +increase in code size. This switch implies @option{-mno-push-args}. + +@item -mthreads +@opindex mthreads +Support thread-safe exception handling on @samp{Mingw32}. Code that relies +on thread-safe exception handling must compile and link all code with the +@option{-mthreads} option. When compiling, @option{-mthreads} defines +@option{-D_MT}; when linking, it links in a special thread helper library +@option{-lmingwthrd} which cleans up per thread exception handling data. + +@item -mno-align-stringops +@opindex mno-align-stringops +Do not align destination of inlined string operations. This switch reduces +code size and improves performance in case the destination is already aligned, +but gcc don't know about it. + +@item -minline-all-stringops +@opindex minline-all-stringops +By default GCC inlines string operations only when destination is known to be +aligned at least to 4 byte boundary. This enables more inlining, increase code +size, but may improve performance of code that depends on fast memcpy, strlen +and memset for short lengths. + +@item -momit-leaf-frame-pointer +@opindex momit-leaf-frame-pointer +Don't keep the frame pointer in a register for leaf functions. This +avoids the instructions to save, set up and restore frame pointers and +makes an extra register available in leaf functions. The option +@option{-fomit-frame-pointer} removes the frame pointer for all functions +which might make debugging harder. +@end table + +These @samp{-m} switches are supported in addition to the above +on AMD x86-64 processors in 64-bit environments. + +@table @gcctabopt +@item -m32 +@itemx -m64 +@opindex m32 +@opindex m64 +Generate code for a 32-bit or 64-bit environment. +The 32-bit environment sets int, long and pointer to 32 bits and +generates code that runs on any i386 system. +The 64-bit environment sets int to 32 bits and long and pointer +to 64 bits and generates code for AMD's x86-64 architecture. + +@item -mno-red-zone +@opindex no-red-zone +Do not use a so called red zone for x86-64 code. The red zone is mandated +by the x86-64 ABI, it is a 128-byte area beyond the location of the +stack pointer that will not be modified by signal or interrupt handlers +and therefore can be used for temporary data without adjusting the stack +pointer. The flag @option{-mno-red-zone} disables this red zone. +@end table + +@node HPPA Options +@subsection HPPA Options +@cindex HPPA Options + +These @samp{-m} options are defined for the HPPA family of computers: + +@table @gcctabopt +@item -march=@var{architecture-type} +@opindex march +Generate code for the specified architecture. The choices for +@var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA +1.1, and @samp{2.0} for PA 2.0 processors. Refer to +@file{/usr/lib/sched.models} on an HP-UX system to determine the proper +architecture option for your machine. Code compiled for lower numbered +architectures will run on higher numbered architectures, but not the +other way around. + +PA 2.0 support currently requires gas snapshot 19990413 or later. The +next release of binutils (current is 2.9.1) will probably contain PA 2.0 +support. + +@item -mpa-risc-1-0 +@itemx -mpa-risc-1-1 +@itemx -mpa-risc-2-0 +@opindex mpa-risc-1-0 +@opindex mpa-risc-1-1 +@opindex mpa-risc-2-0 +Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively. + +@item -mbig-switch +@opindex mbig-switch +Generate code suitable for big switch tables. Use this option only if +the assembler/linker complain about out of range branches within a switch +table. + +@item -mjump-in-delay +@opindex mjump-in-delay +Fill delay slots of function calls with unconditional jump instructions +by modifying the return pointer for the function call to be the target +of the conditional jump. + +@item -mdisable-fpregs +@opindex mdisable-fpregs +Prevent floating point registers from being used in any manner. This is +necessary for compiling kernels which perform lazy context switching of +floating point registers. If you use this option and attempt to perform +floating point operations, the compiler will abort. + +@item -mdisable-indexing +@opindex mdisable-indexing +Prevent the compiler from using indexing address modes. This avoids some +rather obscure problems when compiling MIG generated code under MACH@. + +@item -mno-space-regs +@opindex mno-space-regs +Generate code that assumes the target has no space registers. This allows +GCC to generate faster indirect calls and use unscaled index address modes. + +Such code is suitable for level 0 PA systems and kernels. + +@item -mfast-indirect-calls +@opindex mfast-indirect-calls +Generate code that assumes calls never cross space boundaries. This +allows GCC to emit code which performs faster indirect calls. + +This option will not work in the presence of shared libraries or nested +functions. + +@item -mlong-load-store +@opindex mlong-load-store +Generate 3-instruction load and store sequences as sometimes required by +the HP-UX 10 linker. This is equivalent to the @samp{+k} option to +the HP compilers. + +@item -mportable-runtime +@opindex mportable-runtime +Use the portable calling conventions proposed by HP for ELF systems. + +@item -mgas +@opindex mgas +Enable the use of assembler directives only GAS understands. + +@item -mschedule=@var{cpu-type} +@opindex mschedule +Schedule code according to the constraints for the machine type +@var{cpu-type}. The choices for @var{cpu-type} are @samp{700} +@samp{7100}, @samp{7100LC}, @samp{7200}, and @samp{8000}. Refer to +@file{/usr/lib/sched.models} on an HP-UX system to determine the +proper scheduling option for your machine. + +@item -mlinker-opt +@opindex mlinker-opt +Enable the optimization pass in the HPUX linker. Note this makes symbolic +debugging impossible. It also triggers a bug in the HPUX 8 and HPUX 9 linkers +in which they give bogus error messages when linking some programs. + +@item -msoft-float +@opindex msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries are not available for all HPPA +targets. Normally the facilities of the machine's usual C compiler are +used, but this cannot be done directly in cross-compilation. You must make +your own arrangements to provide suitable library functions for +cross-compilation. The embedded target @samp{hppa1.1-*-pro} +does provide software floating point support. + +@option{-msoft-float} changes the calling convention in the output file; +therefore, it is only useful if you compile @emph{all} of a program with +this option. In particular, you need to compile @file{libgcc.a}, the +library that comes with GCC, with @option{-msoft-float} in order for +this to work. +@end table + +@node Intel 960 Options +@subsection Intel 960 Options + +These @samp{-m} options are defined for the Intel 960 implementations: + +@table @gcctabopt +@item -m@var{cpu-type} +@opindex mka +@opindex mkb +@opindex mmc +@opindex mca +@opindex mcf +@opindex msa +@opindex msb +Assume the defaults for the machine type @var{cpu-type} for some of +the other options, including instruction scheduling, floating point +support, and addressing modes. The choices for @var{cpu-type} are +@samp{ka}, @samp{kb}, @samp{mc}, @samp{ca}, @samp{cf}, +@samp{sa}, and @samp{sb}. +The default is +@samp{kb}. + +@item -mnumerics +@itemx -msoft-float +@opindex mnumerics +@opindex msoft-float +The @option{-mnumerics} option indicates that the processor does support +floating-point instructions. The @option{-msoft-float} option indicates +that floating-point support should not be assumed. + +@item -mleaf-procedures +@itemx -mno-leaf-procedures +@opindex mleaf-procedures +@opindex mno-leaf-procedures +Do (or do not) attempt to alter leaf procedures to be callable with the +@code{bal} instruction as well as @code{call}. This will result in more +efficient code for explicit calls when the @code{bal} instruction can be +substituted by the assembler or linker, but less efficient code in other +cases, such as calls via function pointers, or using a linker that doesn't +support this optimization. + +@item -mtail-call +@itemx -mno-tail-call +@opindex mtail-call +@opindex mno-tail-call +Do (or do not) make additional attempts (beyond those of the +machine-independent portions of the compiler) to optimize tail-recursive +calls into branches. You may not want to do this because the detection of +cases where this is not valid is not totally complete. The default is +@option{-mno-tail-call}. + +@item -mcomplex-addr +@itemx -mno-complex-addr +@opindex mcomplex-addr +@opindex mno-complex-addr +Assume (or do not assume) that the use of a complex addressing mode is a +win on this implementation of the i960. Complex addressing modes may not +be worthwhile on the K-series, but they definitely are on the C-series. +The default is currently @option{-mcomplex-addr} for all processors except +the CB and CC@. + +@item -mcode-align +@itemx -mno-code-align +@opindex mcode-align +@opindex mno-code-align +Align code to 8-byte boundaries for faster fetching (or don't bother). +Currently turned on by default for C-series implementations only. + +@ignore +@item -mclean-linkage +@itemx -mno-clean-linkage +@opindex mclean-linkage +@opindex mno-clean-linkage +These options are not fully implemented. +@end ignore + +@item -mic-compat +@itemx -mic2.0-compat +@itemx -mic3.0-compat +@opindex mic-compat +@opindex mic2.0-compat +@opindex mic3.0-compat +Enable compatibility with iC960 v2.0 or v3.0. + +@item -masm-compat +@itemx -mintel-asm +@opindex masm-compat +@opindex mintel-asm +Enable compatibility with the iC960 assembler. + +@item -mstrict-align +@itemx -mno-strict-align +@opindex mstrict-align +@opindex mno-strict-align +Do not permit (do permit) unaligned accesses. + +@item -mold-align +@opindex mold-align +Enable structure-alignment compatibility with Intel's gcc release version +1.3 (based on gcc 1.37). This option implies @option{-mstrict-align}. + +@item -mlong-double-64 +@opindex mlong-double-64 +Implement type @samp{long double} as 64-bit floating point numbers. +Without the option @samp{long double} is implemented by 80-bit +floating point numbers. The only reason we have it because there is +no 128-bit @samp{long double} support in @samp{fp-bit.c} yet. So it +is only useful for people using soft-float targets. Otherwise, we +should recommend against use of it. + +@end table + +@node DEC Alpha Options +@subsection DEC Alpha Options + +These @samp{-m} options are defined for the DEC Alpha implementations: + +@table @gcctabopt +@item -mno-soft-float +@itemx -msoft-float +@opindex mno-soft-float +@opindex msoft-float +Use (do not use) the hardware floating-point instructions for +floating-point operations. When @option{-msoft-float} is specified, +functions in @file{libgcc.a} will be used to perform floating-point +operations. Unless they are replaced by routines that emulate the +floating-point operations, or compiled in such a way as to call such +emulations routines, these routines will issue floating-point +operations. If you are compiling for an Alpha without floating-point +operations, you must ensure that the library is built so as not to call +them. + +Note that Alpha implementations without floating-point operations are +required to have floating-point registers. + +@item -mfp-reg +@itemx -mno-fp-regs +@opindex mfp-reg +@opindex mno-fp-regs +Generate code that uses (does not use) the floating-point register set. +@option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point +register set is not used, floating point operands are passed in integer +registers as if they were integers and floating-point results are passed +in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence, +so any function with a floating-point argument or return value called by code +compiled with @option{-mno-fp-regs} must also be compiled with that +option. + +A typical use of this option is building a kernel that does not use, +and hence need not save and restore, any floating-point registers. + +@item -mieee +@opindex mieee +The Alpha architecture implements floating-point hardware optimized for +maximum performance. It is mostly compliant with the IEEE floating +point standard. However, for full compliance, software assistance is +required. This option generates code fully IEEE compliant code +@emph{except} that the @var{inexact-flag} is not maintained (see below). +If this option is turned on, the preprocessor macro @code{_IEEE_FP} is +defined during compilation. The resulting code is less efficient but is +able to correctly support denormalized numbers and exceptional IEEE +values such as not-a-number and plus/minus infinity. Other Alpha +compilers call this option @option{-ieee_with_no_inexact}. + +@item -mieee-with-inexact +@opindex mieee-with-inexact +This is like @option{-mieee} except the generated code also maintains +the IEEE @var{inexact-flag}. Turning on this option causes the +generated code to implement fully-compliant IEEE math. In addition to +@code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor +macro. On some Alpha implementations the resulting code may execute +significantly slower than the code generated by default. Since there is +very little code that depends on the @var{inexact-flag}, you should +normally not specify this option. Other Alpha compilers call this +option @option{-ieee_with_inexact}. + +@item -mfp-trap-mode=@var{trap-mode} +@opindex mfp-trap-mode +This option controls what floating-point related traps are enabled. +Other Alpha compilers call this option @option{-fptm @var{trap-mode}}. +The trap mode can be set to one of four values: + +@table @samp +@item n +This is the default (normal) setting. The only traps that are enabled +are the ones that cannot be disabled in software (e.g., division by zero +trap). + +@item u +In addition to the traps enabled by @samp{n}, underflow traps are enabled +as well. + +@item su +Like @samp{su}, but the instructions are marked to be safe for software +completion (see Alpha architecture manual for details). + +@item sui +Like @samp{su}, but inexact traps are enabled as well. +@end table + +@item -mfp-rounding-mode=@var{rounding-mode} +@opindex mfp-rounding-mode +Selects the IEEE rounding mode. Other Alpha compilers call this option +@option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one +of: + +@table @samp +@item n +Normal IEEE rounding mode. Floating point numbers are rounded towards +the nearest machine number or towards the even machine number in case +of a tie. + +@item m +Round towards minus infinity. + +@item c +Chopped rounding mode. Floating point numbers are rounded towards zero. + +@item d +Dynamic rounding mode. A field in the floating point control register +(@var{fpcr}, see Alpha architecture reference manual) controls the +rounding mode in effect. The C library initializes this register for +rounding towards plus infinity. Thus, unless your program modifies the +@var{fpcr}, @samp{d} corresponds to round towards plus infinity. +@end table + +@item -mtrap-precision=@var{trap-precision} +@opindex mtrap-precision +In the Alpha architecture, floating point traps are imprecise. This +means without software assistance it is impossible to recover from a +floating trap and program execution normally needs to be terminated. +GCC can generate code that can assist operating system trap handlers +in determining the exact location that caused a floating point trap. +Depending on the requirements of an application, different levels of +precisions can be selected: + +@table @samp +@item p +Program precision. This option is the default and means a trap handler +can only identify which program caused a floating point exception. + +@item f +Function precision. The trap handler can determine the function that +caused a floating point exception. + +@item i +Instruction precision. The trap handler can determine the exact +instruction that caused a floating point exception. +@end table + +Other Alpha compilers provide the equivalent options called +@option{-scope_safe} and @option{-resumption_safe}. + +@item -mieee-conformant +@opindex mieee-conformant +This option marks the generated code as IEEE conformant. You must not +use this option unless you also specify @option{-mtrap-precision=i} and either +@option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect +is to emit the line @samp{.eflag 48} in the function prologue of the +generated assembly file. Under DEC Unix, this has the effect that +IEEE-conformant math library routines will be linked in. + +@item -mbuild-constants +@opindex mbuild-constants +Normally GCC examines a 32- or 64-bit integer constant to +see if it can construct it from smaller constants in two or three +instructions. If it cannot, it will output the constant as a literal and +generate code to load it from the data segment at runtime. + +Use this option to require GCC to construct @emph{all} integer constants +using code, even if it takes more instructions (the maximum is six). + +You would typically use this option to build a shared library dynamic +loader. Itself a shared library, it must relocate itself in memory +before it can find the variables and constants in its own data segment. + +@item -malpha-as +@itemx -mgas +@opindex malpha-as +@opindex mgas +Select whether to generate code to be assembled by the vendor-supplied +assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}. + +@item -mbwx +@itemx -mno-bwx +@itemx -mcix +@itemx -mno-cix +@itemx -mfix +@itemx -mno-fix +@itemx -mmax +@itemx -mno-max +@opindex mbwx +@opindex mno-bwx +@opindex mcix +@opindex mno-cix +@opindex mfix +@opindex mno-fix +@opindex mmax +@opindex mno-max +Indicate whether GCC should generate code to use the optional BWX, +CIX, FIX and MAX instruction sets. The default is to use the instruction +sets supported by the CPU type specified via @option{-mcpu=} option or that +of the CPU on which GCC was built if none was specified. + +@item -mfloat-vax +@itemx -mfloat-ieee +@opindex mfloat-vax +@opindex mfloat-ieee +Generate code that uses (does not use) VAX F and G floating point +arithmetic instead of IEEE single and double precision. + +@item -mexplicit-relocs +@itemx -mno-explicit-relocs +@opindex mexplicit-relocs +@opindex mno-explicit-relocs +Older Alpha assemblers provided no way to generate symbol relocations +except via assembler macros. Use of these macros does not allow +optimial instruction scheduling. GNU binutils as of version 2.12 +supports a new syntax that allows the compiler to explicitly mark +which relocations should apply to which instructions. This option +is mostly useful for debugging, as GCC detects the capabilities of +the assembler when it is built and sets the default accordingly. + +@item -msmall-data +@itemx -mlarge-data +@opindex msmall-data +@opindex mlarge-data +When @option{-mexplicit-relocs} is in effect, static data is +accessed via @dfn{gp-relative} relocations. When @option{-msmall-data} +is used, objects 8 bytes long or smaller are placed in a @dfn{small data area} +(the @code{.sdata} and @code{.sbss} sections) and are accessed via +16-bit relocations off of the @code{$gp} register. This limits the +size of the small data area to 64KB, but allows the variables to be +directly accessed via a single instruction. + +The default is @option{-mlarge-data}. With this option the data area +is limited to just below 2GB. Programs that require more than 2GB of +data must use @code{malloc} or @code{mmap} to allocate the data in the +heap instead of in the program's data segment. + +When generating code for shared libraries, @option{-fpic} implies +@option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}. + +@item -mcpu=@var{cpu_type} +@opindex mcpu +Set the instruction set and instruction scheduling parameters for +machine type @var{cpu_type}. You can specify either the @samp{EV} +style name or the corresponding chip number. GCC supports scheduling +parameters for the EV4, EV5 and EV6 family of processors and will +choose the default values for the instruction set from the processor +you specify. If you do not specify a processor type, GCC will default +to the processor on which the compiler was built. + +Supported values for @var{cpu_type} are + +@table @samp +@item ev4 +@item ev45 +@itemx 21064 +Schedules as an EV4 and has no instruction set extensions. + +@item ev5 +@itemx 21164 +Schedules as an EV5 and has no instruction set extensions. + +@item ev56 +@itemx 21164a +Schedules as an EV5 and supports the BWX extension. + +@item pca56 +@itemx 21164pc +@itemx 21164PC +Schedules as an EV5 and supports the BWX and MAX extensions. + +@item ev6 +@itemx 21264 +Schedules as an EV6 and supports the BWX, FIX, and MAX extensions. + +@item ev67 +@item 21264a +Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions. +@end table + +@item -mtune=@var{cpu_type} +@opindex mtune +Set only the instruction scheduling parameters for machine type +@var{cpu_type}. The instruction set is not changed. + +@item -mmemory-latency=@var{time} +@opindex mmemory-latency +Sets the latency the scheduler should assume for typical memory +references as seen by the application. This number is highly +dependent on the memory access patterns used by the application +and the size of the external cache on the machine. + +Valid options for @var{time} are + +@table @samp +@item @var{number} +A decimal number representing clock cycles. + +@item L1 +@itemx L2 +@itemx L3 +@itemx main +The compiler contains estimates of the number of clock cycles for +``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches +(also called Dcache, Scache, and Bcache), as well as to main memory. +Note that L3 is only valid for EV5. + +@end table +@end table + +@node DEC Alpha/VMS Options +@subsection DEC Alpha/VMS Options + +These @samp{-m} options are defined for the DEC Alpha/VMS implementations: + +@table @gcctabopt +@item -mvms-return-codes +@opindex mvms-return-codes +Return VMS condition codes from main. The default is to return POSIX +style condition (e.g.@ error) codes. +@end table + +@node Clipper Options +@subsection Clipper Options + +These @samp{-m} options are defined for the Clipper implementations: + +@table @gcctabopt +@item -mc300 +@opindex mc300 +Produce code for a C300 Clipper processor. This is the default. + +@item -mc400 +@opindex mc400 +Produce code for a C400 Clipper processor, i.e.@: use floating point +registers f8--f15. +@end table + +@node H8/300 Options +@subsection H8/300 Options + +These @samp{-m} options are defined for the H8/300 implementations: + +@table @gcctabopt +@item -mrelax +@opindex mrelax +Shorten some address references at link time, when possible; uses the +linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300, +ld.info, Using ld}, for a fuller description. + +@item -mh +@opindex mh +Generate code for the H8/300H@. + +@item -ms +@opindex ms +Generate code for the H8/S@. + +@item -ms2600 +@opindex ms2600 +Generate code for the H8/S2600. This switch must be used with @option{-ms}. + +@item -mint32 +@opindex mint32 +Make @code{int} data 32 bits by default. + +@item -malign-300 +@opindex malign-300 +On the H8/300H and H8/S, use the same alignment rules as for the H8/300. +The default for the H8/300H and H8/S is to align longs and floats on 4 +byte boundaries. +@option{-malign-300} causes them to be aligned on 2 byte boundaries. +This option has no effect on the H8/300. +@end table + +@node SH Options +@subsection SH Options + +These @samp{-m} options are defined for the SH implementations: + +@table @gcctabopt +@item -m1 +@opindex m1 +Generate code for the SH1. + +@item -m2 +@opindex m2 +Generate code for the SH2. + +@item -m3 +@opindex m3 +Generate code for the SH3. + +@item -m3e +@opindex m3e +Generate code for the SH3e. + +@item -m4-nofpu +@opindex m4-nofpu +Generate code for the SH4 without a floating-point unit. + +@item -m4-single-only +@opindex m4-single-only +Generate code for the SH4 with a floating-point unit that only +supports single-precision arithmetic. + +@item -m4-single +@opindex m4-single +Generate code for the SH4 assuming the floating-point unit is in +single-precision mode by default. + +@item -m4 +@opindex m4 +Generate code for the SH4. + +@item -mb +@opindex mb +Compile code for the processor in big endian mode. + +@item -ml +@opindex ml +Compile code for the processor in little endian mode. + +@item -mdalign +@opindex mdalign +Align doubles at 64-bit boundaries. Note that this changes the calling +conventions, and thus some functions from the standard C library will +not work unless you recompile it first with @option{-mdalign}. + +@item -mrelax +@opindex mrelax +Shorten some address references at link time, when possible; uses the +linker option @option{-relax}. + +@item -mbigtable +@opindex mbigtable +Use 32-bit offsets in @code{switch} tables. The default is to use +16-bit offsets. + +@item -mfmovd +@opindex mfmovd +Enable the use of the instruction @code{fmovd}. + +@item -mhitachi +@opindex mhitachi +Comply with the calling conventions defined by Hitachi. + +@item -mnomacsave +@opindex mnomacsave +Mark the @code{MAC} register as call-clobbered, even if +@option{-mhitachi} is given. + +@item -mieee +@opindex mieee +Increase IEEE-compliance of floating-point code. + +@item -misize +@opindex misize +Dump instruction size and location in the assembly code. + +@item -mpadstruct +@opindex mpadstruct +This option is deprecated. It pads structures to multiple of 4 bytes, +which is incompatible with the SH ABI@. + +@item -mspace +@opindex mspace +Optimize for space instead of speed. Implied by @option{-Os}. + +@item -mprefergot +@opindex mprefergot +When generating position-independent code, emit function calls using +the Global Offset Table instead of the Procedure Linkage Table. + +@item -musermode +@opindex musermode +Generate a library function call to invalidate instruction cache +entries, after fixing up a trampoline. This library function call +doesn't assume it can write to the whole memory address space. This +is the default when the target is @code{sh-*-linux*}. +@end table + +@node System V Options +@subsection Options for System V + +These additional options are available on System V Release 4 for +compatibility with other compilers on those systems: + +@table @gcctabopt +@item -G +@opindex G +Create a shared object. +It is recommended that @option{-symbolic} or @option{-shared} be used instead. + +@item -Qy +@opindex Qy +Identify the versions of each tool used by the compiler, in a +@code{.ident} assembler directive in the output. + +@item -Qn +@opindex Qn +Refrain from adding @code{.ident} directives to the output file (this is +the default). + +@item -YP,@var{dirs} +@opindex YP +Search the directories @var{dirs}, and no others, for libraries +specified with @option{-l}. + +@item -Ym,@var{dir} +@opindex Ym +Look in the directory @var{dir} to find the M4 preprocessor. +The assembler uses this option. +@c This is supposed to go with a -Yd for predefined M4 macro files, but +@c the generic assembler that comes with Solaris takes just -Ym. +@end table + +@node TMS320C3x/C4x Options +@subsection TMS320C3x/C4x Options +@cindex TMS320C3x/C4x Options + +These @samp{-m} options are defined for TMS320C3x/C4x implementations: + +@table @gcctabopt + +@item -mcpu=@var{cpu_type} +@opindex mcpu +Set the instruction set, register set, and instruction scheduling +parameters for machine type @var{cpu_type}. Supported values for +@var{cpu_type} are @samp{c30}, @samp{c31}, @samp{c32}, @samp{c40}, and +@samp{c44}. The default is @samp{c40} to generate code for the +TMS320C40. + +@item -mbig-memory +@item -mbig +@itemx -msmall-memory +@itemx -msmall +@opindex mbig-memory +@opindex mbig +@opindex msmall-memory +@opindex msmall +Generates code for the big or small memory model. The small memory +model assumed that all data fits into one 64K word page. At run-time +the data page (DP) register must be set to point to the 64K page +containing the .bss and .data program sections. The big memory model is +the default and requires reloading of the DP register for every direct +memory access. + +@item -mbk +@itemx -mno-bk +@opindex mbk +@opindex mno-bk +Allow (disallow) allocation of general integer operands into the block +count register BK@. + +@item -mdb +@itemx -mno-db +@opindex mdb +@opindex mno-db +Enable (disable) generation of code using decrement and branch, +DBcond(D), instructions. This is enabled by default for the C4x. To be +on the safe side, this is disabled for the C3x, since the maximum +iteration count on the C3x is @math{2^23 + 1} (but who iterates loops more than +@math{2^23} times on the C3x?). Note that GCC will try to reverse a loop so +that it can utilise the decrement and branch instruction, but will give +up if there is more than one memory reference in the loop. Thus a loop +where the loop counter is decremented can generate slightly more +efficient code, in cases where the RPTB instruction cannot be utilised. + +@item -mdp-isr-reload +@itemx -mparanoid +@opindex mdp-isr-reload +@opindex mparanoid +Force the DP register to be saved on entry to an interrupt service +routine (ISR), reloaded to point to the data section, and restored on +exit from the ISR@. This should not be required unless someone has +violated the small memory model by modifying the DP register, say within +an object library. + +@item -mmpyi +@itemx -mno-mpyi +@opindex mmpyi +@opindex mno-mpyi +For the C3x use the 24-bit MPYI instruction for integer multiplies +instead of a library call to guarantee 32-bit results. Note that if one +of the operands is a constant, then the multiplication will be performed +using shifts and adds. If the @option{-mmpyi} option is not specified for the C3x, +then squaring operations are performed inline instead of a library call. + +@item -mfast-fix +@itemx -mno-fast-fix +@opindex mfast-fix +@opindex mno-fast-fix +The C3x/C4x FIX instruction to convert a floating point value to an +integer value chooses the nearest integer less than or equal to the +floating point value rather than to the nearest integer. Thus if the +floating point number is negative, the result will be incorrectly +truncated an additional code is necessary to detect and correct this +case. This option can be used to disable generation of the additional +code required to correct the result. + +@item -mrptb +@itemx -mno-rptb +@opindex mrptb +@opindex mno-rptb +Enable (disable) generation of repeat block sequences using the RPTB +instruction for zero overhead looping. The RPTB construct is only used +for innermost loops that do not call functions or jump across the loop +boundaries. There is no advantage having nested RPTB loops due to the +overhead required to save and restore the RC, RS, and RE registers. +This is enabled by default with @option{-O2}. + +@item -mrpts=@var{count} +@itemx -mno-rpts +@opindex mrpts +@opindex mno-rpts +Enable (disable) the use of the single instruction repeat instruction +RPTS@. If a repeat block contains a single instruction, and the loop +count can be guaranteed to be less than the value @var{count}, GCC will +emit a RPTS instruction instead of a RPTB@. If no value is specified, +then a RPTS will be emitted even if the loop count cannot be determined +at compile time. Note that the repeated instruction following RPTS does +not have to be reloaded from memory each iteration, thus freeing up the +CPU buses for operands. However, since interrupts are blocked by this +instruction, it is disabled by default. + +@item -mloop-unsigned +@itemx -mno-loop-unsigned +@opindex mloop-unsigned +@opindex mno-loop-unsigned +The maximum iteration count when using RPTS and RPTB (and DB on the C40) +is @math{2^31 + 1} since these instructions test if the iteration count is +negative to terminate the loop. If the iteration count is unsigned +there is a possibility than the @math{2^31 + 1} maximum iteration count may be +exceeded. This switch allows an unsigned iteration count. + +@item -mti +@opindex mti +Try to emit an assembler syntax that the TI assembler (asm30) is happy +with. This also enforces compatibility with the API employed by the TI +C3x C compiler. For example, long doubles are passed as structures +rather than in floating point registers. + +@item -mregparm +@itemx -mmemparm +@opindex mregparm +@opindex mmemparm +Generate code that uses registers (stack) for passing arguments to functions. +By default, arguments are passed in registers where possible rather +than by pushing arguments on to the stack. + +@item -mparallel-insns +@itemx -mno-parallel-insns +@opindex mparallel-insns +@opindex mno-parallel-insns +Allow the generation of parallel instructions. This is enabled by +default with @option{-O2}. + +@item -mparallel-mpy +@itemx -mno-parallel-mpy +@opindex mparallel-mpy +@opindex mno-parallel-mpy +Allow the generation of MPY||ADD and MPY||SUB parallel instructions, +provided @option{-mparallel-insns} is also specified. These instructions have +tight register constraints which can pessimize the code generation +of large functions. + +@end table + +@node V850 Options +@subsection V850 Options +@cindex V850 Options + +These @samp{-m} options are defined for V850 implementations: + +@table @gcctabopt +@item -mlong-calls +@itemx -mno-long-calls +@opindex mlong-calls +@opindex mno-long-calls +Treat all calls as being far away (near). If calls are assumed to be +far away, the compiler will always load the functions address up into a +register, and call indirect through the pointer. + +@item -mno-ep +@itemx -mep +@opindex mno-ep +@opindex mep +Do not optimize (do optimize) basic blocks that use the same index +pointer 4 or more times to copy pointer into the @code{ep} register, and +use the shorter @code{sld} and @code{sst} instructions. The @option{-mep} +option is on by default if you optimize. + +@item -mno-prolog-function +@itemx -mprolog-function +@opindex mno-prolog-function +@opindex mprolog-function +Do not use (do use) external functions to save and restore registers at +the prolog and epilog of a function. The external functions are slower, +but use less code space if more than one function saves the same number +of registers. The @option{-mprolog-function} option is on by default if +you optimize. + +@item -mspace +@opindex mspace +Try to make the code as small as possible. At present, this just turns +on the @option{-mep} and @option{-mprolog-function} options. + +@item -mtda=@var{n} +@opindex mtda +Put static or global variables whose size is @var{n} bytes or less into +the tiny data area that register @code{ep} points to. The tiny data +area can hold up to 256 bytes in total (128 bytes for byte references). + +@item -msda=@var{n} +@opindex msda +Put static or global variables whose size is @var{n} bytes or less into +the small data area that register @code{gp} points to. The small data +area can hold up to 64 kilobytes. + +@item -mzda=@var{n} +@opindex mzda +Put static or global variables whose size is @var{n} bytes or less into +the first 32 kilobytes of memory. + +@item -mv850 +@opindex mv850 +Specify that the target processor is the V850. + +@item -mbig-switch +@opindex mbig-switch +Generate code suitable for big switch tables. Use this option only if +the assembler/linker complain about out of range branches within a switch +table. +@end table + +@node ARC Options +@subsection ARC Options +@cindex ARC Options + +These options are defined for ARC implementations: + +@table @gcctabopt +@item -EL +@opindex EL +Compile code for little endian mode. This is the default. + +@item -EB +@opindex EB +Compile code for big endian mode. + +@item -mmangle-cpu +@opindex mmangle-cpu +Prepend the name of the cpu to all public symbol names. +In multiple-processor systems, there are many ARC variants with different +instruction and register set characteristics. This flag prevents code +compiled for one cpu to be linked with code compiled for another. +No facility exists for handling variants that are ``almost identical''. +This is an all or nothing option. + +@item -mcpu=@var{cpu} +@opindex mcpu +Compile code for ARC variant @var{cpu}. +Which variants are supported depend on the configuration. +All variants support @option{-mcpu=base}, this is the default. + +@item -mtext=@var{text-section} +@itemx -mdata=@var{data-section} +@itemx -mrodata=@var{readonly-data-section} +@opindex mtext +@opindex mdata +@opindex mrodata +Put functions, data, and readonly data in @var{text-section}, +@var{data-section}, and @var{readonly-data-section} respectively +by default. This can be overridden with the @code{section} attribute. +@xref{Variable Attributes}. + +@end table + +@node NS32K Options +@subsection NS32K Options +@cindex NS32K options + +These are the @samp{-m} options defined for the 32000 series. The default +values for these options depends on which style of 32000 was selected when +the compiler was configured; the defaults for the most common choices are +given below. + +@table @gcctabopt +@item -m32032 +@itemx -m32032 +@opindex m32032 +@opindex m32032 +Generate output for a 32032. This is the default +when the compiler is configured for 32032 and 32016 based systems. + +@item -m32332 +@itemx -m32332 +@opindex m32332 +@opindex m32332 +Generate output for a 32332. This is the default +when the compiler is configured for 32332-based systems. + +@item -m32532 +@itemx -m32532 +@opindex m32532 +@opindex m32532 +Generate output for a 32532. This is the default +when the compiler is configured for 32532-based systems. + +@item -m32081 +@opindex m32081 +Generate output containing 32081 instructions for floating point. +This is the default for all systems. + +@item -m32381 +@opindex m32381 +Generate output containing 32381 instructions for floating point. This +also implies @option{-m32081}. The 32381 is only compatible with the 32332 +and 32532 cpus. This is the default for the pc532-netbsd configuration. + +@item -mmulti-add +@opindex mmulti-add +Try and generate multiply-add floating point instructions @code{polyF} +and @code{dotF}. This option is only available if the @option{-m32381} +option is in effect. Using these instructions requires changes to +register allocation which generally has a negative impact on +performance. This option should only be enabled when compiling code +particularly likely to make heavy use of multiply-add instructions. + +@item -mnomulti-add +@opindex mnomulti-add +Do not try and generate multiply-add floating point instructions +@code{polyF} and @code{dotF}. This is the default on all platforms. + +@item -msoft-float +@opindex msoft-float +Generate output containing library calls for floating point. +@strong{Warning:} the requisite libraries may not be available. + +@item -mnobitfield +@opindex mnobitfield +Do not use the bit-field instructions. On some machines it is faster to +use shifting and masking operations. This is the default for the pc532. + +@item -mbitfield +@opindex mbitfield +Do use the bit-field instructions. This is the default for all platforms +except the pc532. + +@item -mrtd +@opindex mrtd +Use a different function-calling convention, in which functions +that take a fixed number of arguments return pop their +arguments on return with the @code{ret} instruction. + +This calling convention is incompatible with the one normally +used on Unix, so you cannot use it if you need to call libraries +compiled with the Unix compiler. + +Also, you must provide function prototypes for all functions that +take variable numbers of arguments (including @code{printf}); +otherwise incorrect code will be generated for calls to those +functions. + +In addition, seriously incorrect code will result if you call a +function with too many arguments. (Normally, extra arguments are +harmlessly ignored.) + +This option takes its name from the 680x0 @code{rtd} instruction. + + +@item -mregparam +@opindex mregparam +Use a different function-calling convention where the first two arguments +are passed in registers. + +This calling convention is incompatible with the one normally +used on Unix, so you cannot use it if you need to call libraries +compiled with the Unix compiler. + +@item -mnoregparam +@opindex mnoregparam +Do not pass any arguments in registers. This is the default for all +targets. + +@item -msb +@opindex msb +It is OK to use the sb as an index register which is always loaded with +zero. This is the default for the pc532-netbsd target. + +@item -mnosb +@opindex mnosb +The sb register is not available for use or has not been initialized to +zero by the run time system. This is the default for all targets except +the pc532-netbsd. It is also implied whenever @option{-mhimem} or +@option{-fpic} is set. + +@item -mhimem +@opindex mhimem +Many ns32000 series addressing modes use displacements of up to 512MB@. +If an address is above 512MB then displacements from zero can not be used. +This option causes code to be generated which can be loaded above 512MB@. +This may be useful for operating systems or ROM code. + +@item -mnohimem +@opindex mnohimem +Assume code will be loaded in the first 512MB of virtual address space. +This is the default for all platforms. + + +@end table + +@node AVR Options +@subsection AVR Options +@cindex AVR Options + +These options are defined for AVR implementations: + +@table @gcctabopt +@item -mmcu=@var{mcu} +@opindex mmcu +Specify ATMEL AVR instruction set or MCU type. + +Instruction set avr1 is for the minimal AVR core, not supported by the C +compiler, only for assembler programs (MCU types: at90s1200, attiny10, +attiny11, attiny12, attiny15, attiny28). + +Instruction set avr2 (default) is for the classic AVR core with up to +8K program memory space (MCU types: at90s2313, at90s2323, attiny22, +at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515, +at90c8534, at90s8535). + +Instruction set avr3 is for the classic AVR core with up to 128K program +memory space (MCU types: atmega103, atmega603, at43usb320, at76c711). + +Instruction set avr4 is for the enhanced AVR core with up to 8K program +memory space (MCU types: atmega8, atmega83, atmega85). + +Instruction set avr5 is for the enhanced AVR core with up to 128K program +memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323, +atmega64, atmega128, at43usb355, at94k). + +@item -msize +@opindex msize +Output instruction sizes to the asm file. + +@item -minit-stack=@var{N} +@opindex minit-stack +Specify the initial stack address, which may be a symbol or numeric value, +@samp{__stack} is the default. + +@item -mno-interrupts +@opindex mno-interrupts +Generated code is not compatible with hardware interrupts. +Code size will be smaller. + +@item -mcall-prologues +@opindex mcall-prologues +Functions prologues/epilogues expanded as call to appropriate +subroutines. Code size will be smaller. + +@item -mno-tablejump +@opindex mno-tablejump +Do not generate tablejump insns which sometimes increase code size. + +@item -mtiny-stack +@opindex mtiny-stack +Change only the low 8 bits of the stack pointer. +@end table + +@node MCore Options +@subsection MCore Options +@cindex MCore options + +These are the @samp{-m} options defined for the Motorola M*Core +processors. + +@table @gcctabopt + +@item -mhardlit +@itemx -mhardlit +@itemx -mno-hardlit +@opindex mhardlit +@opindex mhardlit +@opindex mno-hardlit +Inline constants into the code stream if it can be done in two +instructions or less. + +@item -mdiv +@itemx -mdiv +@itemx -mno-div +@opindex mdiv +@opindex mdiv +@opindex mno-div +Use the divide instruction. (Enabled by default). + +@item -mrelax-immediate +@itemx -mrelax-immediate +@itemx -mno-relax-immediate +@opindex mrelax-immediate +@opindex mrelax-immediate +@opindex mno-relax-immediate +Allow arbitrary sized immediates in bit operations. + +@item -mwide-bitfields +@itemx -mwide-bitfields +@itemx -mno-wide-bitfields +@opindex mwide-bitfields +@opindex mwide-bitfields +@opindex mno-wide-bitfields +Always treat bit-fields as int-sized. + +@item -m4byte-functions +@itemx -m4byte-functions +@itemx -mno-4byte-functions +@opindex m4byte-functions +@opindex m4byte-functions +@opindex mno-4byte-functions +Force all functions to be aligned to a four byte boundary. + +@item -mcallgraph-data +@itemx -mcallgraph-data +@itemx -mno-callgraph-data +@opindex mcallgraph-data +@opindex mcallgraph-data +@opindex mno-callgraph-data +Emit callgraph information. + +@item -mslow-bytes +@itemx -mslow-bytes +@itemx -mno-slow-bytes +@opindex mslow-bytes +@opindex mslow-bytes +@opindex mno-slow-bytes +Prefer word access when reading byte quantities. + +@item -mlittle-endian +@itemx -mlittle-endian +@itemx -mbig-endian +@opindex mlittle-endian +@opindex mlittle-endian +@opindex mbig-endian +Generate code for a little endian target. + +@item -m210 +@itemx -m210 +@itemx -m340 +@opindex m210 +@opindex m210 +@opindex m340 +Generate code for the 210 processor. +@end table + +@node IA-64 Options +@subsection IA-64 Options +@cindex IA-64 Options + +These are the @samp{-m} options defined for the Intel IA-64 architecture. + +@table @gcctabopt +@item -mbig-endian +@opindex mbig-endian +Generate code for a big endian target. This is the default for HPUX@. + +@item -mlittle-endian +@opindex mlittle-endian +Generate code for a little endian target. This is the default for AIX5 +and Linux. + +@item -mgnu-as +@itemx -mno-gnu-as +@opindex mgnu-as +@opindex mno-gnu-as +Generate (or don't) code for the GNU assembler. This is the default. +@c Also, this is the default if the configure option @option{--with-gnu-as} +@c is used. + +@item -mgnu-ld +@itemx -mno-gnu-ld +@opindex mgnu-ld +@opindex mno-gnu-ld +Generate (or don't) code for the GNU linker. This is the default. +@c Also, this is the default if the configure option @option{--with-gnu-ld} +@c is used. + +@item -mno-pic +@opindex mno-pic +Generate code that does not use a global pointer register. The result +is not position independent code, and violates the IA-64 ABI@. + +@item -mvolatile-asm-stop +@itemx -mno-volatile-asm-stop +@opindex mvolatile-asm-stop +@opindex mno-volatile-asm-stop +Generate (or don't) a stop bit immediately before and after volatile asm +statements. + +@item -mb-step +@opindex mb-step +Generate code that works around Itanium B step errata. + +@item -mregister-names +@itemx -mno-register-names +@opindex mregister-names +@opindex mno-register-names +Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for +the stacked registers. This may make assembler output more readable. + +@item -mno-sdata +@itemx -msdata +@opindex mno-sdata +@opindex msdata +Disable (or enable) optimizations that use the small data section. This may +be useful for working around optimizer bugs. + +@item -mconstant-gp +@opindex mconstant-gp +Generate code that uses a single constant global pointer value. This is +useful when compiling kernel code. + +@item -mauto-pic +@opindex mauto-pic +Generate code that is self-relocatable. This implies @option{-mconstant-gp}. +This is useful when compiling firmware code. + +@item -minline-divide-min-latency +@opindex minline-divide-min-latency +Generate code for inline divides using the minimum latency algorithm. + +@item -minline-divide-max-throughput +@opindex minline-divide-max-throughput +Generate code for inline divides using the maximum throughput algorithm. + +@item -mno-dwarf2-asm +@itemx -mdwarf2-asm +@opindex mno-dwarf2-asm +@opindex mdwarf2-asm +Don't (or do) generate assembler code for the DWARF2 line number debugging +info. This may be useful when not using the GNU assembler. + +@item -mfixed-range=@var{register-range} +@opindex mfixed-range +Generate code treating the given register range as fixed registers. +A fixed register is one that the register allocator can not use. This is +useful when compiling kernel code. A register range is specified as +two registers separated by a dash. Multiple register ranges can be +specified separated by a comma. +@end table + +@node D30V Options +@subsection D30V Options +@cindex D30V Options + +These @samp{-m} options are defined for D30V implementations: + +@table @gcctabopt +@item -mextmem +@opindex mextmem +Link the @samp{.text}, @samp{.data}, @samp{.bss}, @samp{.strings}, +@samp{.rodata}, @samp{.rodata1}, @samp{.data1} sections into external +memory, which starts at location @code{0x80000000}. + +@item -mextmemory +@opindex mextmemory +Same as the @option{-mextmem} switch. + +@item -monchip +@opindex monchip +Link the @samp{.text} section into onchip text memory, which starts at +location @code{0x0}. Also link @samp{.data}, @samp{.bss}, +@samp{.strings}, @samp{.rodata}, @samp{.rodata1}, @samp{.data1} sections +into onchip data memory, which starts at location @code{0x20000000}. + +@item -mno-asm-optimize +@itemx -masm-optimize +@opindex mno-asm-optimize +@opindex masm-optimize +Disable (enable) passing @option{-O} to the assembler when optimizing. +The assembler uses the @option{-O} option to automatically parallelize +adjacent short instructions where possible. + +@item -mbranch-cost=@var{n} +@opindex mbranch-cost +Increase the internal costs of branches to @var{n}. Higher costs means +that the compiler will issue more instructions to avoid doing a branch. +The default is 2. + +@item -mcond-exec=@var{n} +@opindex mcond-exec +Specify the maximum number of conditionally executed instructions that +replace a branch. The default is 4. +@end table + +@node S/390 and zSeries Options +@subsection S/390 and zSeries Options +@cindex S/390 and zSeries Options + +These are the @samp{-m} options defined for the S/390 and zSeries architecture. + +@table @gcctabopt +@item -mhard-float +@itemx -msoft-float +@opindex mhard-float +@opindex msoft-float +Use (do not use) the hardware floating-point instructions and registers +for floating-point operations. When @option{-msoft-float} is specified, +functions in @file{libgcc.a} will be used to perform floating-point +operations. When @option{-mhard-float} is specified, the compiler +generates IEEE floating-point instructions. This is the default. + +@item -mbackchain +@itemx -mno-backchain +@opindex mbackchain +@opindex mno-backchain +Generate (or do not generate) code which maintains an explicit +backchain within the stack frame that points to the caller's frame. +This is currently needed to allow debugging. The default is to +generate the backchain. + +@item -msmall-exec +@itemx -mno-small-exec +@opindex msmall-exec +@opindex mno-small-exec +Generate (or do not generate) code using the @code{bras} instruction +to do subroutine calls. +This only works reliably if the total executable size does not +exceed 64k. The default is to use the @code{basr} instruction instead, +which does not have this limitation. + +@item -m64 +@itemx -m31 +@opindex m64 +@opindex m31 +When @option{-m31} is specified, generate code compliant to the +Linux for S/390 ABI@. When @option{-m64} is specified, generate +code compliant to the Linux for zSeries ABI@. This allows GCC in +particular to generate 64-bit instructions. For the @samp{s390} +targets, the default is @option{-m31}, while the @samp{s390x} +targets default to @option{-m64}. + +@item -mmvcle +@itemx -mno-mvcle +@opindex mmvcle +@opindex mno-mvcle +Generate (or do not generate) code using the @code{mvcle} instruction +to perform block moves. When @option{-mno-mvcle} is specifed, +use a @code{mvc} loop instead. This is the default. + +@item -mdebug +@itemx -mno-debug +@opindex mdebug +@opindex mno-debug +Print (or do not print) additional debug information when compiling. +The default is to not print debug information. + +@end table + +@node CRIS Options +@subsection CRIS Options +@cindex CRIS Options + +These options are defined specifically for the CRIS ports. + +@table @gcctabopt +@item -march=@var{architecture-type} +@itemx -mcpu=@var{architecture-type} +@opindex march +@opindex mcpu +Generate code for the specified architecture. The choices for +@var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for +respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX. +Default is @samp{v0} except for cris-axis-linux-gnu, where the default is +@samp{v10}. + +@item -mtune=@var{architecture-type} +@opindex mtune +Tune to @var{architecture-type} everything applicable about the generated +code, except for the ABI and the set of available instructions. The +choices for @var{architecture-type} are the same as for +@option{-march=@var{architecture-type}}. + +@item -mmax-stack-frame=@var{n} +@opindex mmax-stack-frame +Warn when the stack frame of a function exceeds @var{n} bytes. + +@item -melinux-stacksize=@var{n} +@opindex melinux-stacksize +Only available with the @samp{cris-axis-aout} target. Arranges for +indications in the program to the kernel loader that the stack of the +program should be set to @var{n} bytes. + +@item -metrax4 +@itemx -metrax100 +@opindex metrax4 +@opindex metrax100 +The options @option{-metrax4} and @option{-metrax100} are synonyms for +@option{-march=v3} and @option{-march=v8} respectively. + +@item -mpdebug +@opindex mpdebug +Enable CRIS-specific verbose debug-related information in the assembly +code. This option also has the effect to turn off the @samp{#NO_APP} +formatted-code indicator to the assembler at the beginning of the +assembly file. + +@item -mcc-init +@opindex mcc-init +Do not use condition-code results from previous instruction; always emit +compare and test instructions before use of condition codes. + +@item -mno-side-effects +@opindex mno-side-effects +Do not emit instructions with side-effects in addressing modes other than +post-increment. + +@item -mstack-align +@itemx -mno-stack-align +@itemx -mdata-align +@itemx -mno-data-align +@itemx -mconst-align +@itemx -mno-const-align +@opindex mstack-align +@opindex mno-stack-align +@opindex mdata-align +@opindex mno-data-align +@opindex mconst-align +@opindex mno-const-align +These options (no-options) arranges (eliminate arrangements) for the +stack-frame, individual data and constants to be aligned for the maximum +single data access size for the chosen CPU model. The default is to +arrange for 32-bit alignment. ABI details such as structure layout are +not affected by these options. + +@item -m32-bit +@itemx -m16-bit +@itemx -m8-bit +@opindex m32-bit +@opindex m16-bit +@opindex m8-bit +Similar to the stack- data- and const-align options above, these options +arrange for stack-frame, writable data and constants to all be 32-bit, +16-bit or 8-bit aligned. The default is 32-bit alignment. + +@item -mno-prologue-epilogue +@itemx -mprologue-epilogue +@opindex mno-prologue-epilogue +@opindex mprologue-epilogue +With @option{-mno-prologue-epilogue}, the normal function prologue and +epilogue that sets up the stack-frame are omitted and no return +instructions or return sequences are generated in the code. Use this +option only together with visual inspection of the compiled code: no +warnings or errors are generated when call-saved registers must be saved, +or storage for local variable needs to be allocated. + +@item -mno-gotplt +@itemx -mgotplt +@opindex mno-gotplt +@opindex mgotplt +With @option{-fpic} and @option{-fPIC}, don't generate (do generate) +instruction sequences that load addresses for functions from the PLT part +of the GOT rather than (traditional on other architectures) calls to the +PLT. The default is @option{-mgotplt}. + +@item -maout +@opindex maout +Legacy no-op option only recognized with the cris-axis-aout target. + +@item -melf +@opindex melf +Legacy no-op option only recognized with the cris-axis-elf and +cris-axis-linux-gnu targets. + +@item -melinux +@opindex melinux +Only recognized with the cris-axis-aout target, where it selects a +GNU/linux-like multilib, include files and instruction set for +@option{-march=v8}. + +@item -mlinux +@opindex mlinux +Legacy no-op option only recognized with the cris-axis-linux-gnu target. + +@item -sim +@opindex sim +This option, recognized for the cris-axis-aout and cris-axis-elf arranges +to link with input-output functions from a simulator library. Code, +initialized data and zero-initialized data are allocated consecutively. + +@item -sim2 +@opindex sim2 +Like @option{-sim}, but pass linker options to locate initialized data at +0x40000000 and zero-initialized data at 0x80000000. +@end table + +@node MMIX Options +@subsection MMIX Options +@cindex MMIX Options + +These options are defined for the MMIX: + +@table @gcctabopt +@item -mlibfuncs +@itemx -mno-libfuncs +@opindex mlibfuncs +@opindex mno-libfuncs +Specify that intrinsic library functions are being compiled, passing all +values in registers, no matter the size. + +@item -mepsilon +@itemx -mno-epsilon +@opindex mepsilon +@opindex mno-epsilon +Generate floating-point comparison instructions that compare with respect +to the @code{rE} epsilon register. + +@item -mabi=mmixware +@itemx -mabi=gnu +@opindex mabi-mmixware +@opindex mabi=gnu +Generate code that passes function parameters and return values that (in +the called function) are seen as registers @code{$0} and up, as opposed to +the GNU ABI which uses global registers @code{$231} and up. + +@item -mzero-extend +@itemx -mno-zero-extend +@opindex mzero-extend +@opindex mno-zero-extend +When reading data from memory in sizes shorter than 64 bits, use (do not +use) zero-extending load instructions by default, rather than +sign-extending ones. + +@item -mknuthdiv +@itemx -mno-knuthdiv +@opindex mknuthdiv +@opindex mno-knuthdiv +Make the result of a division yielding a remainder have the same sign as +the divisor. With the default, @option{-mno-knuthdiv}, the sign of the +remainder follows the sign of the dividend. Both methods are +arithmetically valid, the latter being almost exclusively used. + +@item -mtoplevel-symbols +@itemx -mno-toplevel-symbols +@opindex mtoplevel-symbols +@opindex mno-toplevel-symbols +Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly +code can be used with the @code{PREFIX} assembly directive. + +@item -melf +@opindex melf +Generate an executable in the ELF format, rather than the default +@samp{mmo} format used by the @command{mmix} simulator. + +@item -mbranch-predict +@itemx -mno-branch-predict +@opindex mbranch-predict +@opindex mno-branch-predict +Use (do not use) the probable-branch instructions, when static branch +prediction indicates a probable branch. +@end table + +@node PDP-11 Options +@subsection PDP-11 Options +@cindex PDP-11 Options + +These options are defined for the PDP-11: + +@table @gcctabopt +@item -mfpu +@opindex mfpu +Use hardware FPP floating point. This is the default. (FIS floating +point on the PDP-11/40 is not supported.) + +@item -msoft-float +@opindex msoft-float +Do not use hardware floating point. + +@item -mac0 +@opindex mac0 +Return floating-point results in ac0 (fr0 in Unix assembler syntax). + +@item -mno-ac0 +@opindex mno-ac0 +Return floating-point results in memory. This is the default. + +@item -m40 +@opindex m40 +Generate code for a PDP-11/40. + +@item -m45 +@opindex m45 +Generate code for a PDP-11/45. This is the default. + +@item -m10 +@opindex m10 +Generate code for a PDP-11/10. + +@item -mbcopy-builtin +@opindex bcopy-builtin +Use inline @code{movstrhi} patterns for copying memory. This is the +default. + +@item -mbcopy +@opindex mbcopy +Do not use inline @code{movstrhi} patterns for copying memory. + +@item -mint16 +@itemx -mno-int32 +@opindex mint16 +@opindex mno-int32 +Use 16-bit @code{int}. This is the default. + +@item -mint32 +@itemx -mno-int16 +@opindex mint32 +@opindex mno-int16 +Use 32-bit @code{int}. + +@item -mfloat64 +@itemx -mno-float32 +@opindex mfloat64 +@opindex mno-float32 +Use 64-bit @code{float}. This is the default. + +@item -mfloat32 +@item -mno-float64 +@opindex mfloat32 +@opindex mno-float64 +Use 32-bit @code{float}. + +@item -mabshi +@opindex mabshi +Use @code{abshi2} pattern. This is the default. + +@item -mno-abshi +@opindex mno-abshi +Do not use @code{abshi2} pattern. + +@item -mbranch-expensive +@opindex mbranch-expensive +Pretend that branches are expensive. This is for experimenting with +code generation only. + +@item -mbranch-cheap +@opindex mbranch-cheap +Do not pretend that branches are expensive. This is the default. + +@item -msplit +@opindex msplit +Generate code for a system with split I&D. + +@item -mno-split +@opindex mno-split +Generate code for a system without split I&D. This is the default. + +@item -munix-asm +@opindex munix-asm +Use Unix assembler syntax. This is the default when configured for +@samp{pdp11-*-bsd}. + +@item -mdec-asm +@opindex mdec-asm +Use DEC assembler syntax. This is the default when configured for any +PDP-11 target other than @samp{pdp11-*-bsd}. +@end table + +@node Xstormy16 Options +@subsection Xstormy16 Options +@cindex Xstormy16 Options + +These options are defined for Xstormy16: + +@table @gcctabopt +@item -msim +@opindex msim +Choose startup files and linker script suitable for the simulator. +@end table + +@node Xtensa Options +@subsection Xtensa Options +@cindex Xtensa Options + +The Xtensa architecture is designed to support many different +configurations. The compiler's default options can be set to match a +particular Xtensa configuration by copying a configuration file into the +GCC sources when building GCC@. The options below may be used to +override the default options. + +@table @gcctabopt +@item -mbig-endian +@itemx -mlittle-endian +@opindex mbig-endian +@opindex mlittle-endian +Specify big-endian or little-endian byte ordering for the target Xtensa +processor. + +@item -mdensity +@itemx -mno-density +@opindex mdensity +@opindex mno-density +Enable or disable use of the optional Xtensa code density instructions. + +@item -mmac16 +@itemx -mno-mac16 +@opindex mmac16 +@opindex mno-mac16 +Enable or disable use of the Xtensa MAC16 option. When enabled, GCC +will generate MAC16 instructions from standard C code, with the +limitation that it will use neither the MR register file nor any +instruction that operates on the MR registers. When this option is +disabled, GCC will translate 16-bit multiply/accumulate operations to a +combination of core instructions and library calls, depending on whether +any other multiplier options are enabled. + +@item -mmul16 +@itemx -mno-mul16 +@opindex mmul16 +@opindex mno-mul16 +Enable or disable use of the 16-bit integer multiplier option. When +enabled, the compiler will generate 16-bit multiply instructions for +multiplications of 16 bits or smaller in standard C code. When this +option is disabled, the compiler will either use 32-bit multiply or +MAC16 instructions if they are available or generate library calls to +perform the multiply operations using shifts and adds. + +@item -mmul32 +@itemx -mno-mul32 +@opindex mmul32 +@opindex mno-mul32 +Enable or disable use of the 32-bit integer multiplier option. When +enabled, the compiler will generate 32-bit multiply instructions for +multiplications of 32 bits or smaller in standard C code. When this +option is disabled, the compiler will generate library calls to perform +the multiply operations using either shifts and adds or 16-bit multiply +instructions if they are available. + +@item -mnsa +@itemx -mno-nsa +@opindex mnsa +@opindex mno-nsa +Enable or disable use of the optional normalization shift amount +(@code{NSA}) instructions to implement the built-in @code{ffs} function. + +@item -mminmax +@itemx -mno-minmax +@opindex mminmax +@opindex mno-minmax +Enable or disable use of the optional minimum and maximum value +instructions. + +@item -msext +@itemx -mno-sext +@opindex msext +@opindex mno-sext +Enable or disable use of the optional sign extend (@code{SEXT}) +instruction. + +@item -mbooleans +@itemx -mno-booleans +@opindex mbooleans +@opindex mno-booleans +Enable or disable support for the boolean register file used by Xtensa +coprocessors. This is not typically useful by itself but may be +required for other options that make use of the boolean registers (e.g., +the floating-point option). + +@item -mhard-float +@itemx -msoft-float +@opindex mhard-float +@opindex msoft-float +Enable or disable use of the floating-point option. When enabled, GCC +generates floating-point instructions for 32-bit @code{float} +operations. When this option is disabled, GCC generates library calls +to emulate 32-bit floating-point operations using integer instructions. +Regardless of this option, 64-bit @code{double} operations are always +emulated with calls to library functions. + +@item -mfused-madd +@itemx -mno-fused-madd +@opindex mfused-madd +@opindex mno-fused-madd +Enable or disable use of fused multiply/add and multiply/subtract +instructions in the floating-point option. This has no effect if the +floating-point option is not also enabled. Disabling fused multiply/add +and multiply/subtract instructions forces the compiler to use separate +instructions for the multiply and add/subtract operations. This may be +desirable in some cases where strict IEEE 754-compliant results are +required: the fused multiply add/subtract instructions do not round the +intermediate result, thereby producing results with @emph{more} bits of +precision than specified by the IEEE standard. Disabling fused multiply +add/subtract instructions also ensures that the program output is not +sensitive to the compiler's ability to combine multiply and add/subtract +operations. + +@item -mserialize-volatile +@itemx -mno-serialize-volatile +@opindex mserialize-volatile +@opindex mno-serialize-volatile +When this option is enabled, GCC inserts @code{MEMW} instructions before +@code{volatile} memory references to guarantee sequential consistency. +The default is @option{-mserialize-volatile}. Use +@option{-mno-serialize-volatile} to omit the @code{MEMW} instructions. + +@item -mtext-section-literals +@itemx -mno-text-section-literals +@opindex mtext-section-literals +@opindex mno-text-section-literals +Control the treatment of literal pools. The default is +@option{-mno-text-section-literals}, which places literals in a separate +section in the output file. This allows the literal pool to be placed +in a data RAM/ROM, and it also allows the linker to combine literal +pools from separate object files to remove redundant literals and +improve code size. With @option{-mtext-section-literals}, the literals +are interspersed in the text section in order to keep them as close as +possible to their references. This may be necessary for large assembly +files. + +@item -mtarget-align +@itemx -mno-target-align +@opindex mtarget-align +@opindex mno-target-align +When this option is enabled, GCC instructs the assembler to +automatically align instructions to reduce branch penalties at the +expense of some code density. The assembler attempts to widen density +instructions to align branch targets and the instructions following call +instructions. If there are not enough preceding safe density +instructions to align a target, no widening will be performed. The +default is @option{-mtarget-align}. These options do not affect the +treatment of auto-aligned instructions like @code{LOOP}, which the +assembler will always align, either by widening density instructions or +by inserting no-op instructions. + +@item -mlongcalls +@itemx -mno-longcalls +@opindex mlongcalls +@opindex mno-longcalls +When this option is enabled, GCC instructs the assembler to translate +direct calls to indirect calls unless it can determine that the target +of a direct call is in the range allowed by the call instruction. This +translation typically occurs for calls to functions in other source +files. Specifically, the assembler translates a direct @code{CALL} +instruction into an @code{L32R} followed by a @code{CALLX} instruction. +The default is @option{-mno-longcalls}. This option should be used in +programs where the call target can potentially be out of range. This +option is implemented in the assembler, not the compiler, so the +assembly code generated by GCC will still show direct call +instructions---look at the disassembled object code to see the actual +instructions. Note that the assembler will use an indirect call for +every cross-file call, not just those that really will be out of range. +@end table + +@node Code Gen Options +@section Options for Code Generation Conventions +@cindex code generation conventions +@cindex options, code generation +@cindex run-time options + +These machine-independent options control the interface conventions +used in code generation. + +Most of them have both positive and negative forms; the negative form +of @option{-ffoo} would be @option{-fno-foo}. In the table below, only +one of the forms is listed---the one which is not the default. You +can figure out the other form by either removing @samp{no-} or adding +it. + +@table @gcctabopt +@item -fexceptions +@opindex fexceptions +Enable exception handling. Generates extra code needed to propagate +exceptions. For some targets, this implies GCC will generate frame +unwind information for all functions, which can produce significant data +size overhead, although it does not affect execution. If you do not +specify this option, GCC will enable it by default for languages like +C++ which normally require exception handling, and disable it for +languages like C that do not normally require it. However, you may need +to enable this option when compiling C code that needs to interoperate +properly with exception handlers written in C++. You may also wish to +disable this option if you are compiling older C++ programs that don't +use exception handling. + +@item -fnon-call-exceptions +@opindex fnon-call-exceptions +Generate code that allows trapping instructions to throw exceptions. +Note that this requires platform-specific runtime support that does +not exist everywhere. Moreover, it only allows @emph{trapping} +instructions to throw exceptions, i.e.@: memory references or floating +point instructions. It does not allow exceptions to be thrown from +arbitrary signal handlers such as @code{SIGALRM}. + +@item -funwind-tables +@opindex funwind-tables +Similar to @option{-fexceptions}, except that it will just generate any needed +static data, but will not affect the generated code in any other way. +You will normally not enable this option; instead, a language processor +that needs this handling would enable it on your behalf. + +@item -fasynchronous-unwind-tables +@opindex funwind-tables +Generate unwind table in dwarf2 format, if supported by target machine. The +table is exact at each instruction boundary, so it can be used for stack +unwinding from asynchronous events (such as debugger or garbage collector). + +@item -fpcc-struct-return +@opindex fpcc-struct-return +Return ``short'' @code{struct} and @code{union} values in memory like +longer ones, rather than in registers. This convention is less +efficient, but it has the advantage of allowing intercallability between +GCC-compiled files and files compiled with other compilers. + +The precise convention for returning structures in memory depends +on the target configuration macros. + +Short structures and unions are those whose size and alignment match +that of some integer type. + +@item -freg-struct-return +@opindex freg-struct-return +Return @code{struct} and @code{union} values in registers when possible. +This is more efficient for small structures than +@option{-fpcc-struct-return}. + +If you specify neither @option{-fpcc-struct-return} nor +@option{-freg-struct-return}, GCC defaults to whichever convention is +standard for the target. If there is no standard convention, GCC +defaults to @option{-fpcc-struct-return}, except on targets where GCC is +the principal compiler. In those cases, we can choose the standard, and +we chose the more efficient register return alternative. + +@item -fshort-enums +@opindex fshort-enums +Allocate to an @code{enum} type only as many bytes as it needs for the +declared range of possible values. Specifically, the @code{enum} type +will be equivalent to the smallest integer type which has enough room. + +@item -fshort-double +@opindex fshort-double +Use the same size for @code{double} as for @code{float}. + +@item -fshared-data +@opindex fshared-data +Requests that the data and non-@code{const} variables of this +compilation be shared data rather than private data. The distinction +makes sense only on certain operating systems, where shared data is +shared between processes running the same program, while private data +exists in one copy per process. + +@item -fno-common +@opindex fno-common +In C, allocate even uninitialized global variables in the data section of the +object file, rather than generating them as common blocks. This has the +effect that if the same variable is declared (without @code{extern}) in +two different compilations, you will get an error when you link them. +The only reason this might be useful is if you wish to verify that the +program will work on other systems which always work this way. + +@item -fno-ident +@opindex fno-ident +Ignore the @samp{#ident} directive. + +@item -fno-gnu-linker +@opindex fno-gnu-linker +Do not output global initializations (such as C++ constructors and +destructors) in the form used by the GNU linker (on systems where the GNU +linker is the standard method of handling them). Use this option when +you want to use a non-GNU linker, which also requires using the +@command{collect2} program to make sure the system linker includes +constructors and destructors. (@command{collect2} is included in the GCC +distribution.) For systems which @emph{must} use @command{collect2}, the +compiler driver @command{gcc} is configured to do this automatically. + +@item -finhibit-size-directive +@opindex finhibit-size-directive +Don't output a @code{.size} assembler directive, or anything else that +would cause trouble if the function is split in the middle, and the +two halves are placed at locations far apart in memory. This option is +used when compiling @file{crtstuff.c}; you should not need to use it +for anything else. + +@item -fverbose-asm +@opindex fverbose-asm +Put extra commentary information in the generated assembly code to +make it more readable. This option is generally only of use to those +who actually need to read the generated assembly code (perhaps while +debugging the compiler itself). + +@option{-fno-verbose-asm}, the default, causes the +extra information to be omitted and is useful when comparing two assembler +files. + +@item -fvolatile +@opindex fvolatile +Consider all memory references through pointers to be volatile. + +@item -fvolatile-global +@opindex fvolatile-global +Consider all memory references to extern and global data items to +be volatile. GCC does not consider static data items to be volatile +because of this switch. + +@item -fvolatile-static +@opindex fvolatile-static +Consider all memory references to static data to be volatile. + +@item -fpic +@opindex fpic +@cindex global offset table +@cindex PIC +Generate position-independent code (PIC) suitable for use in a shared +library, if supported for the target machine. Such code accesses all +constant addresses through a global offset table (GOT)@. The dynamic +loader resolves the GOT entries when the program starts (the dynamic +loader is not part of GCC; it is part of the operating system). If +the GOT size for the linked executable exceeds a machine-specific +maximum size, you get an error message from the linker indicating that +@option{-fpic} does not work; in that case, recompile with @option{-fPIC} +instead. (These maximums are 16k on the m88k, 8k on the Sparc, and 32k +on the m68k and RS/6000. The 386 has no such limit.) + +Position-independent code requires special support, and therefore works +only on certain machines. For the 386, GCC supports PIC for System V +but not for the Sun 386i. Code generated for the IBM RS/6000 is always +position-independent. + +@item -fPIC +@opindex fPIC +If supported for the target machine, emit position-independent code, +suitable for dynamic linking and avoiding any limit on the size of the +global offset table. This option makes a difference on the m68k, m88k, +and the Sparc. + +Position-independent code requires special support, and therefore works +only on certain machines. + +@item -ffixed-@var{reg} +@opindex ffixed +Treat the register named @var{reg} as a fixed register; generated code +should never refer to it (except perhaps as a stack pointer, frame +pointer or in some other fixed role). + +@var{reg} must be the name of a register. The register names accepted +are machine-specific and are defined in the @code{REGISTER_NAMES} +macro in the machine description macro file. + +This flag does not have a negative form, because it specifies a +three-way choice. + +@item -fcall-used-@var{reg} +@opindex fcall-used +Treat the register named @var{reg} as an allocable register that is +clobbered by function calls. It may be allocated for temporaries or +variables that do not live across a call. Functions compiled this way +will not save and restore the register @var{reg}. + +It is an error to used this flag with the frame pointer or stack pointer. +Use of this flag for other registers that have fixed pervasive roles in +the machine's execution model will produce disastrous results. + +This flag does not have a negative form, because it specifies a +three-way choice. + +@item -fcall-saved-@var{reg} +@opindex fcall-saved +Treat the register named @var{reg} as an allocable register saved by +functions. It may be allocated even for temporaries or variables that +live across a call. Functions compiled this way will save and restore +the register @var{reg} if they use it. + +It is an error to used this flag with the frame pointer or stack pointer. +Use of this flag for other registers that have fixed pervasive roles in +the machine's execution model will produce disastrous results. + +A different sort of disaster will result from the use of this flag for +a register in which function values may be returned. + +This flag does not have a negative form, because it specifies a +three-way choice. + +@item -fpack-struct +@opindex fpack-struct +Pack all structure members together without holes. Usually you would +not want to use this option, since it makes the code suboptimal, and +the offsets of structure members won't agree with system libraries. + +@item -finstrument-functions +@opindex finstrument-functions +Generate instrumentation calls for entry and exit to functions. Just +after function entry and just before function exit, the following +profiling functions will be called with the address of the current +function and its call site. (On some platforms, +@code{__builtin_return_address} does not work beyond the current +function, so the call site information may not be available to the +profiling functions otherwise.) + +@example +void __cyg_profile_func_enter (void *this_fn, + void *call_site); +void __cyg_profile_func_exit (void *this_fn, + void *call_site); +@end example + +The first argument is the address of the start of the current function, +which may be looked up exactly in the symbol table. + +This instrumentation is also done for functions expanded inline in other +functions. The profiling calls will indicate where, conceptually, the +inline function is entered and exited. This means that addressable +versions of such functions must be available. If all your uses of a +function are expanded inline, this may mean an additional expansion of +code size. If you use @samp{extern inline} in your C code, an +addressable version of such functions must be provided. (This is +normally the case anyways, but if you get lucky and the optimizer always +expands the functions inline, you might have gotten away without +providing static copies.) + +A function may be given the attribute @code{no_instrument_function}, in +which case this instrumentation will not be done. This can be used, for +example, for the profiling functions listed above, high-priority +interrupt routines, and any functions from which the profiling functions +cannot safely be called (perhaps signal handlers, if the profiling +routines generate output or allocate memory). + +@item -fstack-check +@opindex fstack-check +Generate code to verify that you do not go beyond the boundary of the +stack. You should specify this flag if you are running in an +environment with multiple threads, but only rarely need to specify it in +a single-threaded environment since stack overflow is automatically +detected on nearly all systems if there is only one stack. + +Note that this switch does not actually cause checking to be done; the +operating system must do that. The switch causes generation of code +to ensure that the operating system sees the stack being extended. + +@item -fstack-limit-register=@var{reg} +@itemx -fstack-limit-symbol=@var{sym} +@itemx -fno-stack-limit +@opindex fstack-limit-register +@opindex fstack-limit-symbol +@opindex fno-stack-limit +Generate code to ensure that the stack does not grow beyond a certain value, +either the value of a register or the address of a symbol. If the stack +would grow beyond the value, a signal is raised. For most targets, +the signal is raised before the stack overruns the boundary, so +it is possible to catch the signal without taking special precautions. + +For instance, if the stack starts at absolute address @samp{0x80000000} +and grows downwards, you can use the flags +@option{-fstack-limit-symbol=__stack_limit} and +@option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit +of 128KB@. Note that this may only work with the GNU linker. + +@cindex aliasing of parameters +@cindex parameters, aliased +@item -fargument-alias +@itemx -fargument-noalias +@itemx -fargument-noalias-global +@opindex fargument-alias +@opindex fargument-noalias +@opindex fargument-noalias-global +Specify the possible relationships among parameters and between +parameters and global data. + +@option{-fargument-alias} specifies that arguments (parameters) may +alias each other and may alias global storage.@* +@option{-fargument-noalias} specifies that arguments do not alias +each other, but may alias global storage.@* +@option{-fargument-noalias-global} specifies that arguments do not +alias each other and do not alias global storage. + +Each language will automatically use whatever option is required by +the language standard. You should not need to use these options yourself. + +@item -fleading-underscore +@opindex fleading-underscore +This option and its counterpart, @option{-fno-leading-underscore}, forcibly +change the way C symbols are represented in the object file. One use +is to help link with legacy assembly code. + +Be warned that you should know what you are doing when invoking this +option, and that not all targets provide complete support for it. +@end table + +@c man end + +@node Environment Variables +@section Environment Variables Affecting GCC +@cindex environment variables + +@c man begin ENVIRONMENT + +This section describes several environment variables that affect how GCC +operates. Some of them work by specifying directories or prefixes to use +when searching for various kinds of files. Some are used to specify other +aspects of the compilation environment. + +Note that you can also specify places to search using options such as +@option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These +take precedence over places specified using environment variables, which +in turn take precedence over those specified by the configuration of GCC@. +@xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint, +GNU Compiler Collection (GCC) Internals}. + +@table @env +@item LANG +@itemx LC_CTYPE +@c @itemx LC_COLLATE +@itemx LC_MESSAGES +@c @itemx LC_MONETARY +@c @itemx LC_NUMERIC +@c @itemx LC_TIME +@itemx LC_ALL +@findex LANG +@findex LC_CTYPE +@c @findex LC_COLLATE +@findex LC_MESSAGES +@c @findex LC_MONETARY +@c @findex LC_NUMERIC +@c @findex LC_TIME +@findex LC_ALL +@cindex locale +These environment variables control the way that GCC uses +localization information that allow GCC to work with different +national conventions. GCC inspects the locale categories +@env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do +so. These locale categories can be set to any value supported by your +installation. A typical value is @samp{en_UK} for English in the United +Kingdom. + +The @env{LC_CTYPE} environment variable specifies character +classification. GCC uses it to determine the character boundaries in +a string; this is needed for some multibyte encodings that contain quote +and escape characters that would otherwise be interpreted as a string +end or escape. + +The @env{LC_MESSAGES} environment variable specifies the language to +use in diagnostic messages. + +If the @env{LC_ALL} environment variable is set, it overrides the value +of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE} +and @env{LC_MESSAGES} default to the value of the @env{LANG} +environment variable. If none of these variables are set, GCC +defaults to traditional C English behavior. + +@item TMPDIR +@findex TMPDIR +If @env{TMPDIR} is set, it specifies the directory to use for temporary +files. GCC uses temporary files to hold the output of one stage of +compilation which is to be used as input to the next stage: for example, +the output of the preprocessor, which is the input to the compiler +proper. + +@item GCC_EXEC_PREFIX +@findex GCC_EXEC_PREFIX +If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the +names of the subprograms executed by the compiler. No slash is added +when this prefix is combined with the name of a subprogram, but you can +specify a prefix that ends with a slash if you wish. + +If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out +an appropriate prefix to use based on the pathname it was invoked with. + +If GCC cannot find the subprogram using the specified prefix, it +tries looking in the usual places for the subprogram. + +The default value of @env{GCC_EXEC_PREFIX} is +@file{@var{prefix}/lib/gcc-lib/} where @var{prefix} is the value +of @code{prefix} when you ran the @file{configure} script. + +Other prefixes specified with @option{-B} take precedence over this prefix. + +This prefix is also used for finding files such as @file{crt0.o} that are +used for linking. + +In addition, the prefix is used in an unusual way in finding the +directories to search for header files. For each of the standard +directories whose name normally begins with @samp{/usr/local/lib/gcc-lib} +(more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries +replacing that beginning with the specified prefix to produce an +alternate directory name. Thus, with @option{-Bfoo/}, GCC will search +@file{foo/bar} where it would normally search @file{/usr/local/lib/bar}. +These alternate directories are searched first; the standard directories +come next. + +@item COMPILER_PATH +@findex COMPILER_PATH +The value of @env{COMPILER_PATH} is a colon-separated list of +directories, much like @env{PATH}. GCC tries the directories thus +specified when searching for subprograms, if it can't find the +subprograms using @env{GCC_EXEC_PREFIX}. + +@item LIBRARY_PATH +@findex LIBRARY_PATH +The value of @env{LIBRARY_PATH} is a colon-separated list of +directories, much like @env{PATH}. When configured as a native compiler, +GCC tries the directories thus specified when searching for special +linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking +using GCC also uses these directories when searching for ordinary +libraries for the @option{-l} option (but directories specified with +@option{-L} come first). + +@item C_INCLUDE_PATH +@itemx CPLUS_INCLUDE_PATH +@itemx OBJC_INCLUDE_PATH +@findex C_INCLUDE_PATH +@findex CPLUS_INCLUDE_PATH +@findex OBJC_INCLUDE_PATH +@c @itemx OBJCPLUS_INCLUDE_PATH +These environment variables pertain to particular languages. Each +variable's value is a colon-separated list of directories, much like +@env{PATH}. When GCC searches for header files, it tries the +directories listed in the variable for the language you are using, after +the directories specified with @option{-I} but before the standard header +file directories. + +@item DEPENDENCIES_OUTPUT +@findex DEPENDENCIES_OUTPUT +@cindex dependencies for make as output +If this variable is set, its value specifies how to output dependencies +for Make based on the header files processed by the compiler. This +output looks much like the output from the @option{-M} option +(@pxref{Preprocessor Options}), but it goes to a separate file, and is +in addition to the usual results of compilation. + +The value of @env{DEPENDENCIES_OUTPUT} can be just a file name, in +which case the Make rules are written to that file, guessing the target +name from the source file name. Or the value can have the form +@samp{@var{file} @var{target}}, in which case the rules are written to +file @var{file} using @var{target} as the target name. + +@item LANG +@findex LANG +@cindex locale definition +This variable is used to pass locale information to the compiler. One way in +which this information is used is to determine the character set to be used +when character literals, string literals and comments are parsed in C and C++. +When the compiler is configured to allow multibyte characters, +the following values for @env{LANG} are recognized: + +@table @samp +@item C-JIS +Recognize JIS characters. +@item C-SJIS +Recognize SJIS characters. +@item C-EUCJP +Recognize EUCJP characters. +@end table + +If @env{LANG} is not defined, or if it has some other value, then the +compiler will use mblen and mbtowc as defined by the default locale to +recognize and translate multibyte characters. +@end table + +@c man end + +@node Running Protoize +@section Running Protoize + +The program @code{protoize} is an optional part of GCC@. You can use +it to add prototypes to a program, thus converting the program to ISO +C in one respect. The companion program @code{unprotoize} does the +reverse: it removes argument types from any prototypes that are found. + +When you run these programs, you must specify a set of source files as +command line arguments. The conversion programs start out by compiling +these files to see what functions they define. The information gathered +about a file @var{foo} is saved in a file named @file{@var{foo}.X}. + +After scanning comes actual conversion. The specified files are all +eligible to be converted; any files they include (whether sources or +just headers) are eligible as well. + +But not all the eligible files are converted. By default, +@code{protoize} and @code{unprotoize} convert only source and header +files in the current directory. You can specify additional directories +whose files should be converted with the @option{-d @var{directory}} +option. You can also specify particular files to exclude with the +@option{-x @var{file}} option. A file is converted if it is eligible, its +directory name matches one of the specified directory names, and its +name within the directory has not been excluded. + +Basic conversion with @code{protoize} consists of rewriting most +function definitions and function declarations to specify the types of +the arguments. The only ones not rewritten are those for varargs +functions. + +@code{protoize} optionally inserts prototype declarations at the +beginning of the source file, to make them available for any calls that +precede the function's definition. Or it can insert prototype +declarations with block scope in the blocks where undeclared functions +are called. + +Basic conversion with @code{unprotoize} consists of rewriting most +function declarations to remove any argument types, and rewriting +function definitions to the old-style pre-ISO form. + +Both conversion programs print a warning for any function declaration or +definition that they can't convert. You can suppress these warnings +with @option{-q}. + +The output from @code{protoize} or @code{unprotoize} replaces the +original source file. The original file is renamed to a name ending +with @samp{.save} (for DOS, the saved filename ends in @samp{.sav} +without the original @samp{.c} suffix). If the @samp{.save} (@samp{.sav} +for DOS) file already exists, then the source file is simply discarded. + +@code{protoize} and @code{unprotoize} both depend on GCC itself to +scan the program and collect information about the functions it uses. +So neither of these programs will work until GCC is installed. + +Here is a table of the options you can use with @code{protoize} and +@code{unprotoize}. Each option works with both programs unless +otherwise stated. + +@table @code +@item -B @var{directory} +Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the +usual directory (normally @file{/usr/local/lib}). This file contains +prototype information about standard system functions. This option +applies only to @code{protoize}. + +@item -c @var{compilation-options} +Use @var{compilation-options} as the options when running @code{gcc} to +produce the @samp{.X} files. The special option @option{-aux-info} is +always passed in addition, to tell @code{gcc} to write a @samp{.X} file. + +Note that the compilation options must be given as a single argument to +@code{protoize} or @code{unprotoize}. If you want to specify several +@code{gcc} options, you must quote the entire set of compilation options +to make them a single word in the shell. + +There are certain @code{gcc} arguments that you cannot use, because they +would produce the wrong kind of output. These include @option{-g}, +@option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in +the @var{compilation-options}, they are ignored. + +@item -C +Rename files to end in @samp{.C} (@samp{.cc} for DOS-based file +systems) instead of @samp{.c}. This is convenient if you are converting +a C program to C++. This option applies only to @code{protoize}. + +@item -g +Add explicit global declarations. This means inserting explicit +declarations at the beginning of each source file for each function +that is called in the file and was not declared. These declarations +precede the first function definition that contains a call to an +undeclared function. This option applies only to @code{protoize}. + +@item -i @var{string} +Indent old-style parameter declarations with the string @var{string}. +This option applies only to @code{protoize}. + +@code{unprotoize} converts prototyped function definitions to old-style +function definitions, where the arguments are declared between the +argument list and the initial @samp{@{}. By default, @code{unprotoize} +uses five spaces as the indentation. If you want to indent with just +one space instead, use @option{-i " "}. + +@item -k +Keep the @samp{.X} files. Normally, they are deleted after conversion +is finished. + +@item -l +Add explicit local declarations. @code{protoize} with @option{-l} inserts +a prototype declaration for each function in each block which calls the +function without any declaration. This option applies only to +@code{protoize}. + +@item -n +Make no real changes. This mode just prints information about the conversions +that would have been done without @option{-n}. + +@item -N +Make no @samp{.save} files. The original files are simply deleted. +Use this option with caution. + +@item -p @var{program} +Use the program @var{program} as the compiler. Normally, the name +@file{gcc} is used. + +@item -q +Work quietly. Most warnings are suppressed. + +@item -v +Print the version number, just like @option{-v} for @code{gcc}. +@end table + +If you need special compiler options to compile one of your program's +source files, then you should generate that file's @samp{.X} file +specially, by running @code{gcc} on that source file with the +appropriate options and the option @option{-aux-info}. Then run +@code{protoize} on the entire set of files. @code{protoize} will use +the existing @samp{.X} file because it is newer than the source file. +For example: + +@example +gcc -Dfoo=bar file1.c -aux-info file1.X +protoize *.c +@end example + +@noindent +You need to include the special files along with the rest in the +@code{protoize} command, even though their @samp{.X} files already +exist, because otherwise they won't get converted. + +@xref{Protoize Caveats}, for more information on how to use +@code{protoize} successfully. |