-@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
+@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
+@c 2000, 2001 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 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be included in translations
+approved by the Free Software Foundation instead of in the original
+English.
+@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 [@samp{-c}|@samp{-S}|@samp{-E}] [@samp{-std=}@var{standard}]
+ [@samp{-g}] [@samp{-pg}] [@samp{-O}@var{level}]
+ [@samp{-W}@var{warn}...] [@samp{-pedantic}]
+ [@samp{-I}@var{dir}...] [@samp{-L}@var{dir}...]
+ [@samp{-D}@var{macro}[=@var{defn}]...] [@samp{-U}@var{macro}]
+ [@samp{-f}@var{option}...] [@samp{-m}@var{machine-option}...]
+ [@samp{-o} @var{outfile}] @var{infile}...
+
+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
+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 @file{gcc}, or
+@w{@uref{http://gcc.gnu.org/thanks.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 @samp{-c} option
@cindex grouping options
@cindex options, grouping
-The @code{gcc} program accepts options and file names as operands. Many
+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: @samp{-dr} is very different from @w{@samp{-d
-r}}.
@samp{-ffoo} would be @samp{-fno-foo}. This manual documents
only one of these two forms, whichever one is not the default.
+@c man end
+
@menu
* Option Summary:: Brief list of all options, without explanations.
* Overall Options:: Controlling the kind of output:
* 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.
+ formatted.
* Warning Options:: How picky should the compiler be?
* Debugging Options:: Symbol tables, measurements, and debugging dumps.
* Optimize Options:: How much optimization?
* Running Protoize:: Automatically adding or removing function prototypes.
@end menu
+@c man begin OPTIONS
+
@node Option Summary
@section Option Summary
@table @emph
@item Overall Options
@xref{Overall Options,,Options Controlling the Kind of Output}.
-@smallexample
--c -S -E -o @var{file} -pipe -pass-exit-codes -x @var{language}
--v --target-help --help
-@end smallexample
+@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}.
-@smallexample
--ansi -std=@var{standard} -fno-asm -fno-builtin
--fhosted -ffreestanding
--trigraphs -traditional -traditional-cpp
--fallow-single-precision -fcond-mismatch
--fsigned-bitfields -fsigned-char
--funsigned-bitfields -funsigned-char
--fwritable-strings -fshort-wchar
-@end smallexample
+@gccoptlist{
+-ansi -std=@var{standard} -fno-asm -fno-builtin @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}.
-@smallexample
--fno-access-control -fcheck-new -fconserve-space
--fdollars-in-identifiers -fno-elide-constructors
--fno-enforce-eh-specs -fexternal-templates
--falt-external-templates
--ffor-scope -fno-for-scope -fno-gnu-keywords -fhonor-std
--fhuge-objects -fno-implicit-templates
--fno-implicit-inline-templates -finit-priority
--fno-implement-inlines -fms-extensions
--fname-mangling-version-@var{n} -fno-operator-names
--fno-optional-diags -fpermissive
--frepo -fno-rtti -fsquangle -ftemplate-depth-@var{n}
--fuse-cxa-atexit -fvtable-thunks -nostdinc++
--fno-default-inline -Wctor-dtor-privacy
--Wnon-virtual-dtor -Wreorder
--Weffc++ -Wno-deprecated
--Wno-non-template-friend -Wold-style-cast
--Woverloaded-virtual -Wno-pmf-conversions
--Wsign-promo -Wsynth
-@end smallexample
+@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 -fhonor-std @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}.
-@smallexample
--fmessage-length=@var{n}
--fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]}
-@end smallexample
+@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}.
-@smallexample
--fsyntax-only -pedantic -pedantic-errors
--w -W -Wall -Waggregate-return
--Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment
--Wconversion -Wdisabled-optimization -Werror
--Wfloat-equal -Wformat
--Wid-clash-@var{len} -Wimplicit -Wimplicit-int
--Wimplicit-function-declaration
--Werror-implicit-function-declaration
--Wimport -Winline
--Wlarger-than-@var{len} -Wlong-long
--Wmain -Wmissing-declarations
--Wmissing-format-attribute -Wmissing-noreturn
--Wmultichar -Wno-import -Wpacked -Wpadded
--Wparentheses -Wpointer-arith -Wredundant-decls
--Wreturn-type -Wsequence-point -Wshadow
--Wsign-compare -Wswitch -Wsystem-headers
--Wtrigraphs -Wundef -Wuninitialized
--Wunknown-pragmas -Wunreachable-code
--Wunused -Wunused-function -Wunused-label -Wunused-parameter
--Wunused-value -Wunused-variable -Wwrite-strings
-@end smallexample
+@gccoptlist{
+-fsyntax-only -pedantic -pedantic-errors @gol
+-w -W -Wall -Waggregate-return @gol
+-Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment @gol
+-Wconversion -Wdisabled-optimization -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
-@smallexample
--Wbad-function-cast -Wmissing-prototypes -Wnested-externs
--Wstrict-prototypes -Wtraditional
-@end smallexample
+@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}.
-@smallexample
--a -ax -d@var{letters} -fdump-unnumbered -fdump-translation-unit-@var{file}
--fpretend-float -fprofile-arcs -ftest-coverage
--g -g@var{level} -gcoff -gdwarf -gdwarf-1 -gdwarf-1+ -gdwarf-2
--ggdb -gstabs -gstabs+ -gxcoff -gxcoff+
--p -pg -print-file-name=@var{library} -print-libgcc-file-name
--print-prog-name=@var{program} -print-search-dirs -Q
--save-temps -time
-@end smallexample
+@gccoptlist{
+-a -ax -d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
+-fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} -fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
+-fdump-ast-original@r{[}-@var{n}@r{]} -fdump-ast-optimized@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+ -gxcoff -gxcoff+ @gol
+-p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol
+-print-prog-name=@var{program} -print-search-dirs -Q @gol
+-save-temps -time}
@item Optimization Options
@xref{Optimize Options,,Options that Control Optimization}.
-@smallexample
--falign-functions=@var{n} -falign-jumps=@var{n}
--falign-labels=@var{n} -falign-loops=@var{n}
--fbranch-probabilities -fcaller-saves
--fcse-follow-jumps -fcse-skip-blocks -fdata-sections -fdce
--fdelayed-branch -fdelete-null-pointer-checks
--fexpensive-optimizations -ffast-math -ffloat-store
--fforce-addr -fforce-mem -ffunction-sections -fgcse
--finline-functions -finline-limit=@var{n} -fkeep-inline-functions
--fkeep-static-consts -fmove-all-movables
--fno-default-inline -fno-defer-pop
--fno-function-cse -fno-inline -fno-math-errno -fno-peephole
--fomit-frame-pointer -foptimize-register-move
--foptimize-sibling-calls -freduce-all-givs
--fregmove -frename-registers
--frerun-cse-after-loop -frerun-loop-opt
--fschedule-insns -fschedule-insns2
--fsingle-precision-constant -fssa
--fstrength-reduce -fstrict-aliasing -fthread-jumps -ftrapv
--funroll-all-loops -funroll-loops
--O -O0 -O1 -O2 -O3 -Os
-@end smallexample
+@gccoptlist{
+-falign-functions=@var{n} -falign-jumps=@var{n} @gol
+-falign-labels=@var{n} -falign-loops=@var{n} @gol
+-fbranch-probabilities -fcaller-saves @gol
+-fcse-follow-jumps -fcse-skip-blocks -fdata-sections -fdce @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 -fmove-all-movables @gol
+-fno-default-inline -fno-defer-pop @gol
+-fno-function-cse -fno-guess-branch-probability @gol
+-fno-inline -fno-math-errno -fno-peephole @gol
+-funsafe-math-optimizations -fno-trapping-math @gol
+-fomit-frame-pointer -foptimize-register-move @gol
+-foptimize-sibling-calls -freduce-all-givs @gol
+-fregmove -frename-registers @gol
+-frerun-cse-after-loop -frerun-loop-opt @gol
+-fschedule-insns -fschedule-insns2 @gol
+-fsingle-precision-constant -fssa @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}.
-@smallexample
--A@var{question}(@var{answer}) -C -dD -dM -dN
--D@var{macro}@r{[}=@var{defn}@r{]} -E -H
--idirafter @var{dir}
--include @var{file} -imacros @var{file}
--iprefix @var{file} -iwithprefix @var{dir}
--iwithprefixbefore @var{dir} -isystem @var{dir} -isystem-c++ @var{dir}
--M -MD -MM -MMD -MG -nostdinc -P -trigraphs
--undef -U@var{macro} -Wp,@var{option}
-@end smallexample
+@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}.
-@smallexample
--Wa,@var{option}
-@end smallexample
+@gccoptlist{
+-Wa\,@var{option}}
@item Linker Options
@xref{Link Options,,Options for Linking}.
-@smallexample
-@var{object-file-name} -l@var{library}
--nostartfiles -nodefaultlibs -nostdlib
--s -static -shared -symbolic
--Wl,@var{option} -Xlinker @var{option}
--u @var{symbol}
-@end smallexample
+@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}.
-@smallexample
--B@var{prefix} -I@var{dir} -I- -L@var{dir} -specs=@var{file}
-@end smallexample
+@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}.
-@smallexample
--b @var{machine} -V @var{version}
-@end smallexample
+@gccoptlist{
+-b @var{machine} -V @var{version}}
@item Machine Dependent Options
@xref{Submodel Options,,Hardware Models and Configurations}.
-@smallexample
@emph{M680x0 Options}
--m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040
--m68060 -mcpu32 -m5200 -m68881 -mbitfield -mc68000 -mc68020
--mfpa -mnobitfield -mrtd -mshort -msoft-float -mpcrel
--malign-int -mstrict-align
+@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}
--m6811 -m6812 -m68hc11 -m68hc12
--mauto-incdec -mshort -msoft-reg-count=@var{count}
+@gccoptlist{
+-m6811 -m6812 -m68hc11 -m68hc12 @gol
+-mauto-incdec -mshort -msoft-reg-count=@var{count}}
@emph{VAX Options}
--mg -mgnu -munix
+@gccoptlist{
+-mg -mgnu -munix}
@emph{SPARC Options}
--mcpu=@var{cpu type}
--mtune=@var{cpu type}
--mcmodel=@var{code model}
--m32 -m64
--mapp-regs -mbroken-saverestore -mcypress
--mepilogue -mfaster-structs -mflat
--mfpu -mhard-float -mhard-quad-float
--mimpure-text -mlive-g0 -mno-app-regs
--mno-epilogue -mno-faster-structs -mno-flat -mno-fpu
--mno-impure-text -mno-stack-bias -mno-unaligned-doubles
--msoft-float -msoft-quad-float -msparclite -mstack-bias
--msupersparc -munaligned-doubles -mv8
+@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}
--mc1 -mc2 -mc32 -mc34 -mc38
--margcount -mnoargcount
--mlong32 -mlong64
--mvolatile-cache -mvolatile-nocache
+@gccoptlist{
+-mc1 -mc2 -mc32 -mc34 -mc38 @gol
+-margcount -mnoargcount @gol
+-mlong32 -mlong64 @gol
+-mvolatile-cache -mvolatile-nocache}
@emph{AMD29K Options}
--m29000 -m29050 -mbw -mnbw -mdw -mndw
--mlarge -mnormal -msmall
--mkernel-registers -mno-reuse-arg-regs
--mno-stack-check -mno-storem-bug
--mreuse-arg-regs -msoft-float -mstack-check
--mstorem-bug -muser-registers
+@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}
--mapcs-frame -mno-apcs-frame
--mapcs-26 -mapcs-32
--mapcs-stack-check -mno-apcs-stack-check
--mapcs-float -mno-apcs-float
--mapcs-reentrant -mno-apcs-reentrant
--msched-prolog -mno-sched-prolog
--mlittle-endian -mbig-endian -mwords-little-endian
--malignment-traps -mno-alignment-traps
--msoft-float -mhard-float -mfpe
--mthumb-interwork -mno-thumb-interwork
--mcpu= -march= -mfpe=
--mstructure-size-boundary=
--mbsd -mxopen -mno-symrename
--mabort-on-noreturn
--mlong-calls -mno-long-calls
--mnop-fun-dllimport -mno-nop-fun-dllimport
--msingle-pic-base -mno-single-pic-base
--mpic-register=
-
-@emph{Thumb Options}
--mtpcs-frame -mno-tpcs-frame
--mtpcs-leaf-frame -mno-tpcs-leaf-frame
--mlittle-endian -mbig-endian
--mthumb-interwork -mno-thumb-interwork
--mstructure-size-boundary=
--mnop-fun-dllimport -mno-nop-fun-dllimport
--mcallee-super-interworking -mno-callee-super-interworking
--mcaller-super-interworking -mno-caller-super-interworking
--msingle-pic-base -mno-single-pic-base
--mpic-register=
+@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}
--mrelax
+@gccoptlist{
+-mrelax}
@emph{MN10300 Options}
--mmult-bug
--mno-mult-bug
--mam33
--mno-am33
--mrelax
+@gccoptlist{
+-mmult-bug @gol
+-mno-mult-bug @gol
+-mam33 @gol
+-mno-am33 @gol
+-mrelax}
@emph{M32R/D Options}
--mcode-model=@var{model type} -msdata=@var{sdata type}
--G @var{num}
+@gccoptlist{
+-mcode-model=@var{model type} -msdata=@var{sdata type} @gol
+-G @var{num}}
@emph{M88K Options}
--m88000 -m88100 -m88110 -mbig-pic
--mcheck-zero-division -mhandle-large-shift
--midentify-revision -mno-check-zero-division
--mno-ocs-debug-info -mno-ocs-frame-position
--mno-optimize-arg-area -mno-serialize-volatile
--mno-underscores -mocs-debug-info
--mocs-frame-position -moptimize-arg-area
--mserialize-volatile -mshort-data-@var{num} -msvr3
--msvr4 -mtrap-large-shift -muse-div-instruction
--mversion-03.00 -mwarn-passed-structs
+@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}
--mcpu=@var{cpu type}
--mtune=@var{cpu type}
--mpower -mno-power -mpower2 -mno-power2
--mpowerpc -mpowerpc64 -mno-powerpc
--mpowerpc-gpopt -mno-powerpc-gpopt
--mpowerpc-gfxopt -mno-powerpc-gfxopt
--mnew-mnemonics -mold-mnemonics
--mfull-toc -mminimal-toc -mno-fop-in-toc -mno-sum-in-toc
--m64 -m32 -mxl-call -mno-xl-call -mthreads -mpe
--msoft-float -mhard-float -mmultiple -mno-multiple
--mstring -mno-string -mupdate -mno-update
--mfused-madd -mno-fused-madd -mbit-align -mno-bit-align
--mstrict-align -mno-strict-align -mrelocatable
--mno-relocatable -mrelocatable-lib -mno-relocatable-lib
--mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian
--mcall-aix -mcall-sysv -mprototype -mno-prototype
--msim -mmvme -mads -myellowknife -memb -msdata
--msdata=@var{opt} -mvxworks -G @var{num}
+@gccoptlist{
+-mcpu=@var{cpu type} @gol
+-mtune=@var{cpu type} @gol
+-mpower -mno-power -mpower2 -mno-power2 @gol
+-mpowerpc -mpowerpc64 -mno-powerpc @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 -mthreads -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 -mprototype -mno-prototype @gol
+-msim -mmvme -mads -myellowknife -memb -msdata @gol
+-msdata=@var{opt} -mvxworks -G @var{num}}
@emph{RT Options}
--mcall-lib-mul -mfp-arg-in-fpregs -mfp-arg-in-gregs
--mfull-fp-blocks -mhc-struct-return -min-line-mul
--mminimum-fp-blocks -mnohc-struct-return
+@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}
--mabicalls -mcpu=@var{cpu type}
--membedded-data -muninit-const-in-rodata
--membedded-pic -mfp32 -mfp64 -mgas -mgp32 -mgp64
--mgpopt -mhalf-pic -mhard-float -mint64 -mips1
--mips2 -mips3 -mips4 -mlong64 -mlong32 -mlong-calls -mmemcpy
--mmips-as -mmips-tfile -mno-abicalls
--mno-embedded-data -mno-uninit-const-in-rodata -mno-embedded-pic
--mno-gpopt -mno-long-calls
--mno-memcpy -mno-mips-tfile -mno-rnames -mno-stats
--mrnames -msoft-float
--m4650 -msingle-float -mmad
--mstats -EL -EB -G @var{num} -nocpp
--mabi=32 -mabi=n32 -mabi=64 -mabi=eabi
--mfix7000 -mno-crt0
+@gccoptlist{
+-mabicalls -mcpu=@var{cpu type} @gol
+-membedded-data -muninit-const-in-rodata @gol
+-membedded-pic -mfp32 -mfp64 -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}
@emph{i386 Options}
--mcpu=@var{cpu type} -march=@var{cpu type}
--mintel-syntax -mieee-fp -mno-fancy-math-387
--mno-fp-ret-in-387 -msoft-float -msvr3-shlib
--mno-wide-multiply -mrtd -malign-double
--mreg-alloc=@var{list} -mregparm=@var{num}
--malign-jumps=@var{num} -malign-loops=@var{num}
--malign-functions=@var{num} -mpreferred-stack-boundary=@var{num}
--mthreads -mno-align-stringops -minline-all-stringops
--mpush-args -maccumulate-outgoing-args
+@gccoptlist{
+-mcpu=@var{cpu type} -march=@var{cpu type} @gol
+-mintel-syntax -mieee-fp -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
+-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}
@emph{HPPA Options}
--march=@var{architecture type}
--mbig-switch -mdisable-fpregs -mdisable-indexing
--mfast-indirect-calls -mgas -mjump-in-delay
--mlong-load-store -mno-big-switch -mno-disable-fpregs
--mno-disable-indexing -mno-fast-indirect-calls -mno-gas
--mno-jump-in-delay -mno-long-load-store
--mno-portable-runtime -mno-soft-float
--mno-space-regs -msoft-float -mpa-risc-1-0
--mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime
--mschedule=@var{cpu type} -mspace-regs
+@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}
--m@var{cpu type} -masm-compat -mclean-linkage
--mcode-align -mcomplex-addr -mleaf-procedures
--mic-compat -mic2.0-compat -mic3.0-compat
--mintel-asm -mno-clean-linkage -mno-code-align
--mno-complex-addr -mno-leaf-procedures
--mno-old-align -mno-strict-align -mno-tail-call
--mnumerics -mold-align -msoft-float -mstrict-align
--mtail-call
+@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}
--mfp-regs -mno-fp-regs -mno-soft-float -msoft-float
--malpha-as -mgas
--mieee -mieee-with-inexact -mieee-conformant
--mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode}
--mtrap-precision=@var{mode} -mbuild-constants
--mcpu=@var{cpu type}
--mbwx -mno-bwx -mcix -mno-cix -mmax -mno-max
--mmemory-latency=@var{time}
+@gccoptlist{
+-mfp-regs -mno-fp-regs -mno-soft-float -msoft-float @gol
+-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} @gol
+-mbwx -mno-bwx -mcix -mno-cix -mmax -mno-max @gol
+-mmemory-latency=@var{time}}
@emph{Clipper Options}
--mc300 -mc400
+@gccoptlist{
+-mc300 -mc400}
@emph{H8/300 Options}
--mrelax -mh -ms -mint32 -malign-300
+@gccoptlist{
+-mrelax -mh -ms -mint32 -malign-300}
@emph{SH Options}
--m1 -m2 -m3 -m3e
--m4-nofpu -m4-single-only -m4-single -m4
--mb -ml -mdalign -mrelax
--mbigtable -mfmovd -mhitachi -mnomacsave
--misize -mpadstruct -mspace
+@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
+-misize -mpadstruct -mspace @gol
-mprefergot
--musermode
+-musermode}
@emph{System V Options}
--Qy -Qn -YP,@var{paths} -Ym,@var{dir}
+@gccoptlist{
+-Qy -Qn -YP\,@var{paths} -Ym\,@var{dir}}
@emph{ARC Options}
--EB -EL
--mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text section}
--mdata=@var{data section} -mrodata=@var{readonly data section}
+@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}
--mcpu=@var{cpu} -mbig -msmall -mregparm -mmemparm
--mfast-fix -mmpyi -mbk -mti -mdp-isr-reload
--mrpts=@var{count} -mrptb -mdb -mloop-unsigned
--mparallel-insns -mparallel-mpy -mpreserve-float
+@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}
--mlong-calls -mno-long-calls -mep -mno-ep
--mprolog-function -mno-prolog-function -mspace
--mtda=@var{n} -msda=@var{n} -mzda=@var{n}
--mv850 -mbig-switch
+@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}
--m32032 -m32332 -m32532 -m32081 -m32381 -mmult-add -mnomult-add
--msoft-float -mrtd -mnortd -mregparam -mnoregparam -msb -mnosb
--mbitfield -mnobitfield -mhimem -mnohimem
+@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}
--mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts
--mcall-prologues
+@gccoptlist{
+-mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts @gol
+-mcall-prologues -mno-tablejump -mtiny-stack}
@emph{MCore Options}
--mhardlit, -mno-hardlit -mdiv -mno-div -mrelax-immediates
--mno-relax-immediates -mwide-bitfields -mno-wide-bitfields
--m4byte-functions -mno-4byte-functions -mcallgraph-data
--mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim
--mlittle-endian -mbig-endian -m210 -m340 -mstack-increment
-@end smallexample
+@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{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}}
@item Code Generation Options
@xref{Code Gen Options,,Options for Code Generation Conventions}.
-@smallexample
--fcall-saved-@var{reg} -fcall-used-@var{reg}
--fexceptions -funwind-tables -ffixed-@var{reg}
--finhibit-size-directive -finstrument-functions
--fcheck-memory-usage -fprefix-function-name
--fno-common -fno-ident -fno-gnu-linker
--fpcc-struct-return -fpic -fPIC
--freg-struct-return -fshared-data -fshort-enums
--fshort-double -fvolatile -fvolatile-global -fvolatile-static
--fverbose-asm -fpack-struct -fstack-check
--fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym}
--fargument-alias -fargument-noalias
--fargument-noalias-global
--fleading-underscore
-@end smallexample
+@gccoptlist{
+-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol
+-fexceptions -funwind-tables -ffixed-@var{reg} @gol
+-finhibit-size-directive -finstrument-functions @gol
+-fcheck-memory-usage -fprefix-function-name @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
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.
+ formatted.
* Warning Options:: How picky should the compiler be?
* Debugging Options:: Symbol tables, measurements, and debugging dumps.
* Optimize Options:: How much optimization?
For any given input file, the file name suffix determines what kind of
compilation is done:
-@table @code
+@table @gcctabopt
@item @var{file}.c
C source code which must be preprocessed.
You can specify the input language explicitly with the @samp{-x} option:
-@table @code
+@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
has not been used at all).
@item -pass-exit-codes
-Normally the @code{gcc} program will exit with the code of 1 if any
+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
-@samp{-pass-exit-codes}, the @code{gcc} program will instead return with
+@samp{-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
-@samp{-x} (or filename suffixes) to tell @code{gcc} where to start, and
+@samp{-x} (or filename suffixes) to tell @command{gcc} where to start, and
one of the options @samp{-c}, @samp{-S}, or @samp{-E} to say where
-@code{gcc} is to stop. Note that some combinations (for example,
-@samp{-x cpp-output -E} instruct @code{gcc} to do nothing at all.
+@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 @code
+@table @gcctabopt
@item -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
@item --help
Print (on the standard output) a description of the command line options
-understood by @code{gcc}. If the @code{-v} option is also specified
-then @code{--help} will also be passed on to the various processes
-invoked by @code{gcc}, so that they can display the command line options
-they accept. If the @code{-W} option is also specified then command
+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.
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 @code{gcc}).
+the name @command{gcc}).
@findex g++
@findex c++
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.
-@code{g++} is a program that calls GCC with the default language
+@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, @code{g++} is also
-installed with the name @code{c++}.
+library. On many systems, @command{g++} is also
+installed with the name @command{c++}.
-@cindex invoking @code{g++}
+@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
The following options control the dialect of C (or languages derived
from C, such as C++ and Objective C) that the compiler accepts:
-@table @code
+@table @gcctabopt
@cindex ANSI support
@cindex ISO support
@item -ansi
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,
+rarely used ISO trigraph feature. For the C compiler,
it disables recognition of C++ style @samp{//} comments as well as
the @code{inline} keyword.
@item -std=
Determine the language standard. A value for this option must be provided;
-possible values are
+possible values are
-@itemize @minus
+@table @samp
@item iso9899:1990
-Same as -ansi
+Same as @option{-ansi}
@item iso9899:199409
ISO C as modified in amend. 1
@item iso9899:1999
ISO C99. Note that this standard is not yet fully supported; see
-@uref{http://gcc.gnu.org/c99status.html} for more information.
+@w{@uref{http://gcc.gnu.org/c99status.html}} for more information.
@item c89
-same as -std=iso9899:1990
+same as @option{-std=iso9899:1990}
@item c99
-same as -std=iso9899:1999
+same as @option{-std=iso9899:1999}
@item gnu89
default, iso9899:1990 + gnu extensions
iso9899:1999 + gnu extensions
@item iso9899:199x
-same as -std=iso9899:1999, deprecated
+same as @option{-std=iso9899:1999}, deprecated
@item c9x
-same as -std=iso9899:1999, deprecated
+same as @option{-std=iso9899:1999}, deprecated
@item gnu9x
-same as -std=gnu99, deprecated
+same as @option{-std=gnu99}, deprecated
-@end itemize
+@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 -std=c99 is not specified.
+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.
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 @samp{-fno-gnu-keywords} flag instead, which has the same effect.
+use the @samp{-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
@cindex builtin functions
Don't recognize builtin functions that do not begin with
@samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in
functions provided by GNU CC}, for details of the functions affected,
-including those which are not builtin functions when @samp{-ansi} is
-used because they do not have an ISO standard meaning.
+including those which are not builtin 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 builtin functions
more efficiently; for instance, calls to @code{alloca} may become single
cannot set a breakpoint on those calls, nor can you change the behavior
of the functions by linking with a different library.
+In C++, @samp{-fno-builtin} is always in effect. The @samp{-fbuiltin}
+option has no effect. Therefore, in C++, the only way to get the
+optimization benefits of builtin functions is to call the function
+using the @samp{__builtin_} prefix. The GNU C++ Standard Library uses
+builtin functions to implement many functions (like
+@code{std::strchr}), so that you automatically get efficient code.
+
@item -fhosted
@cindex hosted environment
@item -trigraphs
Support ISO C trigraphs. You don't want to know about this
-brain-damage. The @samp{-ansi} option implies @samp{-trigraphs}.
+brain-damage. 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 -fcond-mismatch
Allow conditional expressions with mismatched types in the second and
-third arguments. The value of such an expression is void.
+third arguments. The value of such an expression is void. This option
+is not supported for C++.
@item -funsigned-char
Let the type @code{char} be unsigned, like @code{unsigned char}.
Here is a list of options that are @emph{only} for compiling C++ programs:
-@table @code
+@table @gcctabopt
@item -fno-access-control
Turn off all access checking. This switch is mainly useful for working
around bugs in the access control code.
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
+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 @samp{-fno-const-strings}, you cannot
+actually modify the value of a string constant, unless you also use
+@samp{-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
Accept @samp{$} in identifiers. You can also explicitly prohibit use of
@samp{$} with the option @samp{-fno-dollars-in-identifiers}. (GNU C allows
@item -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.
+word as an identifier. You can use the keyword @code{__typeof__} instead.
@samp{-ansi} implies @samp{-fno-gnu-keywords}.
@item -fhonor-std
@code{using-declarations}, @code{using-directives}, and
@code{namespace-names}, if they involve @code{std}.
-@item -fhuge-objects
-Support virtual function calls for objects that exceed the size
-representable by a @samp{short int}. Users should not use this flag by
-default; if you need to use it, the compiler will tell you so.
-
-This flag is not useful when compiling with -fvtable-thunks.
-
-Like all options that change the ABI, all C++ code, @emph{including
-libgcc} must be built with the same setting of this option.
-
@item -fno-implicit-templates
Never emit code for non-inline templates which are instantiated
implicitly (i.e. by use); only emit code for explicit instantiations.
The default is to handle inlines differently so that compiles with and
without optimization will need the same set of explicit instantiations.
-@item -finit-priority
-Support @samp{__attribute__ ((init_priority (n)))} for controlling the
-order of initialization of file-scope objects. On ELF targets, this
-requires GNU ld 2.10 or later.
-
@item -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
-Disable pedwarns about constructs used in MFC, such as implicit int and
-getting a pointer to member function via non-standard syntax.
+Disable pedantic warnings about constructs used in MFC, such as implicit
+int and getting a pointer to member function via non-standard syntax.
-@item -fname-mangling-version-@var{n}
-Control the way in which names are mangled. Version 0 is compatible
-with versions of g++ before 2.8. Version 1 is the default. Version 1
-will allow correct mangling of function templates. For example,
-version 0 mangling does not mangle foo<int, double> and foo<int, char>
-given this declaration:
-
-@example
-template <class T, class U> void foo(T t);
-@end example
-
-Like all options that change the ABI, all C++ code, @emph{including
-libgcc} must be built with the same setting of this option.
+@item -fno-nonansi-builtins
+Disable builtin 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
Do not treat the operator name keywords @code{and}, @code{bitand},
exception handling uses the same information, but it will generate it as
needed.
-@item -fsquangle
-@itemx -fno-squangle
-@samp{-fsquangle} will enable a compressed form of name mangling for
-identifiers. In particular, it helps to shorten very long names by recognizing
-types and class names which occur more than once, replacing them with special
-short ID codes. This option also requires any C++ libraries being used to
-be compiled with this option as well. The compiler has this disabled (the
-equivalent of @samp{-fno-squangle}) by default.
-
-Like all options that change the ABI, all C++ code, @emph{including
-libgcc.a} must be built with the same setting of this option.
+@item -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}
Set the maximum instantiation depth for template classes to @var{n}.
destructors, but will only work if your C library supports
@code{__cxa_atexit}.
-@item -fvtable-thunks
-Use @samp{thunks} to implement the virtual function dispatch table
-(@samp{vtable}). The traditional (cfront-style) approach to
-implementing vtables was to store a pointer to the function and two
-offsets for adjusting the @samp{this} pointer at the call site. Newer
-implementations store a single pointer to a @samp{thunk} function which
-does any necessary adjustment and then calls the target function.
+@item -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
+@samp{-ffunction-sections} and @samp{-Wl,--gc-sections}, in order to
+also discard the functions themselves.
-This option also enables a heuristic for controlling emission of
-vtables; if a class has any non-inline virtual functions, the vtable
-will be emitted in the translation unit containing the first one of
-those.
+This optimization requires GNU as and GNU ld. Not all systems support
+this option. @samp{-Wl,--gc-sections} is ignored without @samp{-static}.
-Like all options that change the ABI, all C++ code, @emph{including
-libgcc.a} must be built with the same setting of this option.
+@item -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++
Do not search for header files in the standard directories specific to
In addition, these optimization, warning, and code generation options
have meanings only for C++ programs:
-@table @code
+@table @gcctabopt
@item -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
The following @samp{-W@dots{}} options are not affected by @samp{-Wall}.
-@table @code
+@table @gcctabopt
@item -Weffc++ (C++ only)
Warn about violations of various style guidelines from Scott Meyers'
@cite{Effective C++} books. If you use this option, you should be aware
@item -Wold-style-cast (C++ only)
Warn if an old-style (C-style) cast 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.
+@samp{const_cast}) are less vulnerable to unintended effects, and much
+easier to grep for.
@item -Woverloaded-virtual (C++ only)
@cindex overloaded virtual fn, warning
@cindex warning for overloaded virtual fn
-Warn when a derived class function declaration may be an error in
-defining a virtual function. In a derived class, the
-definitions of virtual functions must match the type signature of a
-virtual function declared in the base class. With this option, the
-compiler warns when you define a function with the same name as a
-virtual function, but with a type signature that does not match any
-declarations from the base class.
+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 (C++ only)
Disable the diagnostic for converting a bound pointer to member function
(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 @samp{-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}
+Use @var{class name} as the name of the class to instantiate for each
+literal string specified with the syntax @code{@@"..."}. The default
+class name is @code{NXConstantString}.
+
+@item -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
+Generate output compatible with the NeXT runtime. This is the default
+for NeXT-based systems, including Darwin and Mac OS X.
+
+@item -gen-decls
+Dump interface declarations for all classes seen in the source file to a
+file named @file{@var{sourcename}.decl}.
+
+@item -Wno-protocol
+Do not warn if methods required by a protocol are not implemented
+in the class adopting it.
+
+@item -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
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.
+the remaining front-ends would be able to digest them correctly.
-@table @code
+@table @gcctabopt
@item -fmessage-length=@var{n}
Try to format error messages so that they fit on lines of about @var{n}
characters. The default is 72 characters for 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-wrapping will be done; each error message will appear on a single
line.
@item -fdiagnostics-show-location=once
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
-behaviour.
+behaviour.
@item -fdiagnostics-show-location=every-line
Only meaningful in line-wrapping mode. Instructs the diagnostic
These options control the amount and kinds of warnings produced by GCC:
-@table @code
+@table @gcctabopt
@cindex syntax checking
@item -fsyntax-only
Check the code for syntax errors, but don't do anything beyond that.
version of the ISO C standard specified by any @samp{-std} option used.
Valid ISO C and ISO C++ programs should compile properly with or without
-this option (though a rare few will require @samp{-ansi}). However,
+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.
be quite different from @samp{-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
Like @samp{-pedantic}, except that errors are produced rather than
warnings.
@item -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.
+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 @samp{-pedantic} is used
+with @samp{-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}.
+
+@samp{-Wformat} is included in @samp{-Wall}. For more control over some
+aspects of format checking, the options @samp{-Wno-format-y2k},
+@samp{-Wno-format-extra-args}, @samp{-Wformat-nonliteral},
+@samp{-Wformat-security} and @samp{-Wformat=2} are available, but are
+not included in @samp{-Wall}.
+
+@item -Wno-format-y2k
+If @samp{-Wformat} is specified, do not warn about @code{strftime}
+formats which may yield only a two-digit year.
+
+@item -Wno-format-extra-args
+If @samp{-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.
+
+@item -Wformat-nonliteral
+If @samp{-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
+If @samp{-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 @samp{-Wformat-nonliteral} warns about, but
+in future warnings may be added to @samp{-Wformat-security} that are not
+included in @samp{-Wformat-nonliteral}.)
+
+@item -Wformat=2
+Enable @samp{-Wformat} plus format checks not included in
+@samp{-Wformat}. Currently equivalent to @samp{-Wformat
+-Wformat-nonliteral -Wformat-security}.
@item -Wimplicit-int
Warn when a declaration does not specify a type.
function with external linkage, returning int, taking either zero
arguments, two, or three arguments of appropriate types.
+@item -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 -Wmultichar
Warn if a multicharacter constant (@samp{'FOOF'}) is used. Usually they
indicate a typo in the user's code, as they have implementation-defined
There is some controversy over the precise meaning of the sequence point
rules in subtle cases. Alternative formal definitions may be found in
Clive Feather's ``Annex S''
-@uref{http://wwwold.dkuug.dk/JTC1/SC22/WG14/www/docs/n925.htm} and in
+@w{@uref{http://wwwold.dkuug.dk/JTC1/SC22/WG14/www/docs/n925.htm}} and in
Michael Norrish's thesis
-@uref{http://www.cl.cam.ac.uk/users/mn200/PhD/thesis-report.ps.gz}.
+@w{@uref{http://www.cl.cam.ac.uk/users/mn200/PhD/thesis-report.ps.gz}}.
Other discussions are by Raymond Mak
-@uref{http://wwwold.dkuug.dk/JTC1/SC22/WG14/www/docs/n926.htm} and
+@w{@uref{http://wwwold.dkuug.dk/JTC1/SC22/WG14/www/docs/n926.htm}} and
D. Hugh Redelmeier
-@uref{http://wwwold.dkuug.dk/JTC1/SC22/WG14/www/docs/n927.htm}.
+@w{@uref{http://wwwold.dkuug.dk/JTC1/SC22/WG14/www/docs/n927.htm}}.
@item -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}.
+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 @samp{-Wno-return-type} is specified. The only
in some cases, and there is no simple way to modify the code to suppress
the warning.
-@table @code
+@table @gcctabopt
@item -W
Print extra warning messages for these events:
@item -Wtraditional (C only)
Warn about certain constructs that behave differently in traditional and
-ISO C.
+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 arguments occurring within string constants in the macro body.
-These would substitute the argument in traditional C, but are part of
-the constant in ISO C.
+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
+@samp{-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 recognise @samp{#elif}, so it
+suggests avoiding it altogether.
+
+@item
+A function-like macro that appears without arguments.
+
+@item
+The unary plus operator.
+
+@item
+The `U' integer constant suffix, or the `F' or `L' floating point
+constant suffixes. (Traditonal C does support the `L' suffix on integer
+constants.) Note, these suffixes appear in macros defined in the system
+headers of most modern systems, e.g. the _MIN/_MAX macros in 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
Usage of ISO string concatenation is detected.
@item
-A function macro appears without arguments.
-
-@item
-The unary plus operator.
-
-@item
Initialization of automatic aggregates.
@item
traditional C case.
@item
-The `U' integer constant suffix, or the `F' or `L' floating point
-constant suffixes. (Traditonal C does support the `L' suffix on integer
-constants.) Note, these suffixes appear in macros defined in the system
-headers of most modern systems, e.g. the _MIN/_MAX macros in limits.h.
-Use of these macros can lead to spurious warnings as they do not
-necessarily reflect whether the code in question is any less portable to
-traditional C given that suitable backup definitions are provided.
+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 @samp{-Wconversion}.
@end itemize
@item -Wundef
Warn if an undefined identifier is evaluated in an @samp{#if} directive.
@item -Wshadow
-Warn whenever a local variable shadows another local variable.
-
-@item -Wid-clash-@var{len}
-Warn whenever two distinct identifiers match in the first @var{len}
-characters. This may help you prepare a program that will compile
-with certain obsolete, brain-damaged compilers.
+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}
Warn whenever an object of larger than @var{len} bytes is defined.
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.
+bugs could be introduced. You will not get a warning for @code{main} in
+hosted C environments.
@item -Wmissing-format-attribute
If @samp{-Wformat} is enabled, also warn about functions which might be
@item -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.
+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
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.
+line is unreachable in only one inlined copy of the function.
This option is not made part of @samp{-Wall} because in a debugging
version of a program there is often substantial code which checks
GCC has various special options that are used for debugging
either your program or GCC:
-@table @code
+@table @gcctabopt
@item -g
Produce debugging information in the operating system's native format
(stabs, COFF, XCOFF, or DWARF). GDB can work with this debugging
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
+Makes the compiler print some statistics about the time consumed by each
+pass when it finishes.
+
+@item -fmem-report
+Makes the compiler print some statistics about permanent memory
+allocation when it finishes.
+
@item -ax
Generate extra code to profile basic blocks. Your executable will
produce output that is a superset of that produced when @samp{-a} is
@item __bb_trace__
Write the sequence of basic blocks executed to file @file{bbtrace.gz}.
The file will be compressed using the program @samp{gzip}, which must
-exist in your @code{PATH}. On systems without the @samp{popen}
+exist in your @env{PATH}. On systems without the @samp{popen}
function, the file will be named @file{bbtrace} and will not be
compressed. @strong{Profiling for even a few seconds on these systems
will produce a very large file.} Note: @code{__bb_hidecall__} and
(@pxref{Gcov,, @code{gcov}: a GCC Test Coverage Program}).
The data file names begin with the name of your source file:
-@table @code
+@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.
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}).
+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
Dump after global register allocation, to @file{@var{file}.19.greg}.
@item o
Dump after post-reload CSE and other optimizations, to @file{@var{file}.20.postreload}.
-@item G
+@item G
Dump after GCSE, to @file{@var{file}.08.gcse}.
@item i
Dump after sibling call optimizations, to @file{@var{file}.01.sibling}.
Dump after loop optimization, to @file{@var{file}.09.loop}.
@item M
Dump after performing the machine dependent reorganisation pass, to
-@file{@var{file}.28.mach}.
+@file{@var{file}.28.mach}.
@item n
Dump after register renumbering, to @file{@var{file}.23.rnreg}.
@item N
@file{@var{file}.25.sched2}.
@item s
Dump after CSE (including the jump optimization that sometimes follows
-CSE), to @file{@var{file}.03.cse}.
+CSE), to @file{@var{file}.03.cse}.
@item S
Dump after the first instruction scheduling pass, to
@file{@var{file}.17.sched}.
use diff on debugging dumps for compiler invocations with different
options, in particular with and without -g.
-@item -fdump-translation-unit-@var{file} (C and C++ only)
+@item -fdump-translation-unit (C and C++ only)
+@item -fdump-translation-unit-@var{number} (C and C++ only)
Dump a representation of the tree structure for the entire translation
-unit to @var{file}.
+unit to a file. The file name is made by appending @file{.tu} to the
+source file name. If the -@var{number} form is used, @var{number}
+controls the details of the dump as described for the -fdump-tree options.
+
+@item -fdump-class-hierarchy (C++ only)
+@item -fdump-class-hierarchy-@var{number} (C++ only)
+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 -@var{number} form is used, @var{number}
+controls the details of the dump as described for the -fdump-tree
+options.
+
+@item -fdump-ast-@var{switch} (C++ only)
+@item -fdump-ast-@var{switch}-@var{number} (C++ only)
+Control the dumping at various stages of processing the abstract syntax
+tree to a file. The file name is generated by appending a switch
+specific suffix to the source file name. If the -@var{number} form is
+used, @var{number} is a bit mask which controls the details of the
+dump. The following bits are meaningful (these are not set symbolically,
+as the primary function of these dumps is for debugging gcc itself):
+
+@table @samp
+@item bit0 (1)
+Print the address of each node. Usually this is not meaningful as it
+changes according to the environment and source file.
+@item bit1 (2)
+Inhibit dumping of members of a scope or body of a function, unless they
+are reachable by some other path.
+@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}.
+@end table
@item -fpretend-float
When running a cross-compiler, pretend that the target machine uses the
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 cpp: No such file or directory}.
-To resolve this you either need to put @file{cpp} and the other compiler
+@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 @code{GCC_EXEC_PREFIX} to the directory where you installed them.
+variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
Don't forget the trailing '/'.
@xref{Environment Variables}.
+
+@item -dumpmachine
+Print the compiler's target machine (for example,
+@samp{i686-pc-linux-gnu})---and don't do anything else.
+
+@item -dumpversion
+Print the compiler version (for example, @samp{3.0})---and don't do
+anything else.
+
+@item -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
These options control various sorts of optimizations:
-@table @code
+@table @gcctabopt
@item -O
@itemx -O1
Optimize. Optimizing compilation takes somewhat more time, and a lot
You can figure out the other form by either removing @samp{no-} or
adding it.
-@table @code
+@table @gcctabopt
@item -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
@item -finline-limit=@var{n}
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
+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 n is 10000. 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
+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
performed when this option is not used.
@item -ffast-math
-This option allows GCC to violate some ISO or IEEE rules and/or
-specifications in the interest of optimizing code for speed. For
-example, it allows the compiler to assume arguments to the @code{sqrt}
-function are non-negative numbers and that no floating-point values
-are NaNs.
+Sets @samp{-fno-math-errno}, @samp{-funsafe-math-optimizations},
+and @samp{-fno-trapping-math}.
+
+This option causes the preprocessor macro __FAST_MATH__ to be defined.
This option should never be turned on by any @samp{-O} option since
it can result in incorrect output for programs which depend 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 @samp{-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 @samp{-fmath-errno}. The @samp{-ffast-math} option
sets @samp{-fno-math-errno}.
+
+@item -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.
+
+This option should never be turned on by any @samp{-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 @samp{-fno-unsafe-math-optimizations}. The
+@samp{-ffast-math} option sets @samp{-funsafe-math-optimizations}.
+
+@item -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 @samp{-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 @samp{-ftrapping-math}. The @samp{-ffast-math}
+option sets @samp{-fno-trapping-math}.
@end table
@c following causes underfulls.. they don't look great, but we deal.
You can use the following flags in the rare cases when ``fine-tuning''
of optimizations to be performed is desired.
-@table @code
+@table @gcctabopt
@item -fstrength-reduce
Perform the optimizations of loop strength reduction and
elimination of iteration variables.
Perform a global common subexpression elimination pass.
This pass also performs global constant and copy propagation.
+@item -fgcse-lm
+When -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
+When -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 -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
Use global dataflow analysis to identify and eliminate useless null
pointer checks. Programs which rely on NULL pointer dereferences @emph{not}
instructions. GCC enables this optimization by default with @samp{-O2}
or higher.
-Note @code{-fregmove} and @code{-foptimize-register-move} are the same
+Note @option{-fregmove} and @option{-foptimize-register-move} are the same
optimization.
@item -fdelayed-branch
they have helped determine the efficacy of various
approaches to improving loop optimizations.
-Please let us (@email{gcc@@gcc.gnu.org} and @email{fortran@@gnu.org})
+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}
@item -fbranch-probabilities
After running a program compiled with @samp{-fprofile-arcs}
(@pxref{Debugging Options,, Options for Debugging Your Program or
-@code{gcc}}), you can compile it a second time using
+@command{gcc}}), you can compile it a second time using
@samp{-fbranch-probabilities}, to improve optimizations based on
guessing the path a branch might take.
exactly determine which path is taken more often.
@end ifset
+@item -fno-guess-branch-probability
+Sometimes gcc will opt to guess branch probabilities when none are
+available from either profile directed feedback (@samp{-fprofile-arcs})
+or @samp{__builtin_expect}. 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
Allows the compiler to assume the strictest aliasing rules applicable to
the language being compiled. For C (and C++), this activates
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.
+type.
Pay special attention to code like this:
@example
-union a_union @{
+union a_union @{
int i;
double d;
@};
is accessed through the union type. So, the code above will work as
expected. However, this code might not:
@example
-int f() @{
+int f() @{
a_union t;
int* ip;
t.d = 3.0;
@item -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. User's should not
+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 -fdce
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 --param @var{name}=@var{value}
+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
+@samp{--param} option.
+
+In each case, the @var{value} is a 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-inline-insns
+If an function contains more than this many instructions, it
+will not be inlined. This option is precisely equivalent to
+@samp{-finline-limit}.
+
+@end table
@end table
@node Preprocessor Options
they cause the preprocessor output to be unsuitable for actual
compilation.
-@table @code
+@table @gcctabopt
@item -include @var{file}
Process @var{file} as input before processing the regular input file.
In effect, the contents of @var{file} are compiled first. Any @samp{-D}
processing the regular input file. Because the output generated from
@var{file} is discarded, the only effect of @samp{-imacros @var{file}}
is to make the macros defined in @var{file} available for use in the
-main input.
-
-Any @samp{-D} and @samp{-U} options on the command line are always
-processed before @samp{-imacros @var{file}}, regardless of the order in
-which they are written. All the @samp{-include} and @samp{-imacros}
-options are processed in the order in which they are written.
+main input. All the @samp{-include} and @samp{-imacros} options are
+processed in the order in which they are written.
@item -idirafter @var{dir}
@cindex second include path
By using both @samp{-nostdinc} and @samp{-I-}, you can limit the include-file
search path to only those directories you specify explicitly.
+@item -remap
+@findex -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
Do not predefine any nonstandard macros. (Including architecture flags).
@cindex make
@cindex dependencies, make
@item -M
-Tell the preprocessor to output a rule suitable for @code{make}
-describing the dependencies of each object file. For each source file,
-the preprocessor outputs one @code{make}-rule whose target is the object
-file name for that source file and whose dependencies are all the
-@code{#include} header files it uses. This rule may be a single line or
-may be continued with @samp{\}-newline if it is long. The list of rules
-is printed on standard output instead of the preprocessed C program.
+@findex -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.
@samp{-M} implies @samp{-E}.
-Another way to specify output of a @code{make} rule is by setting
-the environment variable @code{DEPENDENCIES_OUTPUT} (@pxref{Environment
-Variables}).
-
@item -MM
-Like @samp{-M} but the output mentions only the user header files
-included with @samp{#include "@var{file}"}. System header files
-included with @samp{#include <@var{file}>} are omitted.
+@findex -MM
+Like @samp{-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
-Like @samp{-M} but the dependency information is written to a file made by
-replacing ".c" with ".d" at the end of the input file names.
-This is in addition to compiling the file as specified---@samp{-MD} does
-not inhibit ordinary compilation the way @samp{-M} does.
+@findex -MD
+Like @samp{-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 ".d" instead.
+
+This is in addition to compiling the main file as specified ---
+@samp{-MD} does not inhibit ordinary compilation the way @samp{-M} does,
+unless you also specify @samp{-MG}.
-In 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.
+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
+@findex -MMD
Like @samp{-MD} except mention only user header files, not system
-header files.
+-header files.
+
+@item -MF @var{file}
+@findex -MF
+When used with @samp{-M} or @samp{-MM}, specifies a file to write the
+dependencies to. This allows the preprocessor to write the preprocessed
+file to stdout normally. If no @samp{-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
-Treat missing header files as generated files and assume they live in the
-same directory as the source file. If you specify @samp{-MG}, you
-must also specify either @samp{-M} or @samp{-MM}. @samp{-MG} is not
-supported with @samp{-MD} or @samp{-MMD}.
+@findex -MG
+When used with @samp{-M} or @samp{-MM}, @samp{-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
+@findex -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}
+@findex -MQ
+@findex -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 @samp{-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 @samp{-MT}, or use multiple @samp{-MT} options.
+
+The targets you specify are output in the order they appear on the
+command line. @samp{-MQ} is identical to @samp{-MT}, except that the
+target name is quoted for Make, but with @samp{-MT} it isn't. For
+example, -MT '$(objpfx)foo.o' gives
+
+@smallexample
+$(objpfx)foo.o: /tmp/foo.c
+@end smallexample
+
+but -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
+@samp{-MQ}.
@item -H
Print the name of each header file used, in addition to other normal
Define macro @var{macro} as @var{defn}. All instances of @samp{-D} on
the command line are processed before any @samp{-U} options.
+Any @samp{-D} and @samp{-U} options on the command line are processed in
+order, and always before @samp{-imacros @var{file}}, regardless of the
+order in which they are written.
+
@item -U@var{macro}
Undefine macro @var{macro}. @samp{-U} options are evaluated after all
@samp{-D} options, but before any @samp{-include} and @samp{-imacros}
options.
+Any @samp{-D} and @samp{-U} options on the command line are processed in
+order, and always before @samp{-imacros @var{file}}, regardless of the
+order in which they are written.
+
@item -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 @samp{-E}
Like @samp{-dD} except that the macro arguments and contents are omitted.
Only @samp{#define @var{name}} is included in the output.
+@item -dI
+@findex -dI
+Output @samp{#include} directives in addition to the result of
+preprocessing.
+
@item -trigraphs
-Support ISO C trigraphs. The @samp{-ansi} option also has this effect.
+@findex -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 @samp{-std} and @samp{-ansi} options.
+
+The nine trigraph sequences are
+@table @samp
+@item ??(
+-> @samp{[}
+
+@item ??)
+-> @samp{]}
+
+@item ??<
+-> @samp{@{}
+
+@item ??>
+-> @samp{@}}
+
+@item ??=
+-> @samp{#}
+
+@item ??/
+-> @samp{\}
+
+@item ??'
+-> @samp{^}
+
+@item ??!
+-> @samp{|}
-@item -Wp,@var{option}
+@item ??-
+-> @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}
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
@c prevent bad page break with this line
You can pass options to the assembler.
-@table @code
-@item -Wa,@var{option}
+@table @gcctabopt
+@item -Wa\,@var{option}
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
an executable output file. They are meaningless if the compiler is
not doing a link step.
-@table @code
+@table @gcctabopt
@cindex file names
@item @var{object-file-name}
A file name that does not end in a special recognized suffix is
@cindex Libraries
@item -l@var{library}
-Search the library named @var{library} when linking.
+@itemx -l @var{library}
+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 processes libraries and object files in the order they
+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.
@item -nostartfiles
Do not use the standard system startup files when linking.
-The standard system libraries are used normally, unless @code{-nostdlib}
-or @code{-nodefaultlibs} is used.
+The standard system libraries are used normally, unless @option{-nostdlib}
+or @option{-nodefaultlibs} is used.
@item -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 @code{-nostartfiles}
+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
or @samp{-nodefaultlibs} you should usually specify @samp{-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}}.)
+constructors will be called; @pxref{Collect2,,@command{collect2}}.)
@item -s
Remove all symbol table and relocation information from the executable.
@item -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
+results, you must also specify the same set of options that were used to
generate code (@samp{-fpic}, @samp{-fPIC}, or model suboptions)
-when you specify this option.@footnote{On some systems, @code{gcc -shared}
+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, @code{gcc -shared} must select the correct support
+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
+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 @samp{-shared} option, the GCC
+driver automatically adds @samp{-shared-libgcc}, unless you explicitly
+specify @samp{-static-libgcc}. The G++ driver automatically adds
+@samp{-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 @samp{-shared-libgcc} if you want to use the shared
+@file{libgcc}.
+
@item -symbolic
Bind references to global symbols when building a shared object. Warn
about any unresolved references (unless overridden by the link editor
@samp{-Xlinker "-assert definitions"}, because this passes the entire
string as a single argument, which is not what the linker expects.
-@item -Wl,@var{option}
+@item -Wl\,@var{option}
Pass @var{option} as an option to the linker. If @var{option} contains
commas, it is split into multiple options at the commas.
These options specify directories to search for header files, for
libraries and for parts of the compiler:
-@table @code
+@table @gcctabopt
@item -I@var{dir}
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. If you use more
-than one @samp{-I} option, the directories are scanned in left-to-right
+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 @samp{-isystem} for that). If you use more than
+one @samp{-I} option, the directories are scanned in left-to-right
order; the standard system directories come after.
@item -I-
@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
-@samp{PATH} environment variable.
+@env{PATH} environment variable.
@samp{-B} prefixes that effectively specify directory names also apply
to libraries in the linker, because the compiler translates these
out of the link if it is not found by those means.
Another way to specify a prefix much like the @samp{-B} prefix is to use
-the environment variable @code{GCC_EXEC_PREFIX}. @xref{Environment
+the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
Variables}.
@item -specs=@var{file}
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
-@code{GCC} is a driver program. It performs its job by invoking a
+@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
@table @code
@item %@var{command}
Issues a @var{command} to the spec file processor. The commands that can
-appear here are:
+appear here are:
@table @code
@item %include <@var{file}>
@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
+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:
@table @code
@item @@@var{language}
This says that the suffix is an alias for a known @var{language}. This is
-similar to using the @code{-x} command-line switch to GCC to specify a
+similar to using the @option{-x} command-line switch to GCC to specify a
language explicitly. For example:
@smallexample
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.
+targets can also add their own spec strings to this list.
@smallexample
asm Options to pass to the assembler
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
+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 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.
+together or combine them with constant text in a single argument.
@table @code
@item %%
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.
+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
+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 ... %g.o ... %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
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 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
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.
+C.
@item %I
Substitute a @samp{-iprefix} option made from 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.
+the full name found.
@item %e@var{str}
Print @var{str} as an error message. @var{str} is terminated by a newline.
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 %D
Dump out a @samp{-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.
+current multilib directory will be prepended to each of these paths.
+
+@item %M
+Output the multilib directory with directory seperators replaced with
+"_". If multilib directories are not set, or the multilib directory is
+"." 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.
+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.
+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}.
+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.
+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
@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:
+to tell cpp whether a char is signed. It typically has the definition:
@smallexample
%@{funsigned-char:-D__CHAR_UNSIGNED__@}
@end smallexample
@item %W@{@code{S}@}
Like %@{@code{S}@} but mark last argument supplied within as a file to be
-deleted on failure.
+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 @samp{-o, -D, -I}, etc. GCC considers @samp{-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.
+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
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}.
+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.
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.
+above.
The @samp{-O, -f, -m, and -W} switches are handled specifically in these
constructs. If another value of @samp{-O} or the negated form of a @samp{-f, -m, or
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).
+compilers to run).
GCC also knows implicitly that arguments starting in @samp{-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
by side. One of them (probably the newest) will be the default, but
you may sometimes wish to use another.
-@table @code
+@table @gcctabopt
@item -b @var{machine}
The argument @var{machine} specifies the target machine for compilation.
This is useful when you have installed GCC as a cross-compiler.
80386} becomes an alias for @samp{-b i386v}.
In one respect, the @samp{-b} or @samp{-V} do not completely change
-to a different compiler: the top-level driver program @code{gcc}
+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
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 @code{ogcc}
-and that for version 2.1 is installed as @code{gcc}, then the command
-@code{gcc} will use version 2.1 by default, while @code{ogcc} will use
+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 @samp{-V} option.
* Convex Options::
* AMD29K Options::
* ARM Options::
-* Thumb Options::
* MN10200 Options::
* MN10300 Options::
* M32R/D Options::
* NS32K Options::
* AVR Options::
* MCore Options::
+* IA-64 Options::
* D30V Options::
@end menu
the compiler was configured; the defaults for the most common choices are
given below.
-@table @code
+@table @gcctabopt
@item -m68000
@itemx -mc68000
Generate output for a 68000. This is the default
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
+Use this option for microcontroller with a 5200 core, including
the MCF5202, MCF5203, MCF5204 and MCF5202.
@item -malign-int
@itemx -mno-align-int
-Control whether GCC aligns @code{int}, @code{long}, @code{long long},
+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 (@samp{-malign-int}) or a 16-bit boundary (@samp{-mno-align-int}).
Aligning variables on 32-bit boundaries produces code that runs somewhat
@cindex M68hc1x options
These are the @samp{-m} options defined for the 68hc11 and 68hc12
-microcontrollers. The default values for these options depends on
+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 @code
+@table @gcctabopt
@item -m6811
@itemx -m68hc11
Generate output for a 68HC11. This is the default
These @samp{-m} options are defined for the Vax:
-@table @code
+@table @gcctabopt
@item -munix
Do not output certain jump instructions (@code{aobleq} and so on)
that the Unix assembler for the Vax cannot handle across long
These @samp{-m} switches are supported on the SPARC:
-@table @code
+@table @gcctabopt
@item -mno-app-regs
@itemx -mapp-regs
Specify @samp{-mapp-regs} to generate output using the global registers
These @samp{-m} switches are supported in addition to the above
on the SPARCLET processor.
-@table @code
+@table @gcctabopt
@item -mlittle-endian
Generate code for a processor running in little-endian mode.
@end table
These @samp{-m} switches are supported in addition to the above
-on SPARC V9 processors in 64 bit environments.
+on SPARC V9 processors in 64-bit environments.
-@table @code
+@table @gcctabopt
@item -mlittle-endian
Generate code for a processor running in little-endian mode.
@item -m32
@itemx -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
+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
@item -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
+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 still 64 bits.
+data segment. Pointers are still 64 bits.
Programs are statically linked, PIC is not supported.
@item -mstack-bias
These @samp{-m} options are defined for Convex:
-@table @code
+@table @gcctabopt
@item -mc1
Generate output for C1. The code will run on any Convex machine.
The preprocessor symbol @code{__convex__c1__} is defined.
These @samp{-m} options are defined for the AMD Am29000:
-@table @code
+@table @gcctabopt
@item -mdw
@kindex -mdw
@cindex DW bit (29k)
These @samp{-m} options are defined for Advanced RISC Machines (ARM)
architectures:
-@table @code
+@table @gcctabopt
@item -mapcs-frame
@kindex -mapcs-frame
Generate a stack frame that is compliant with the ARM Procedure Call
option. This option replaces the @samp{-m6} option of previous releases
of the compiler.
+@ignore
+@c not currently implemented
@item -mapcs-stack-check
@kindex -mapcs-stack-check
@kindex -mno-apcs-stack-check
system is required to provide these functions. The default is
@samp{-mno-apcs-stack-check}, since this produces smaller code.
+@c not currently implemented
@item -mapcs-float
@kindex -mapcs-float
@kindex -mno-apcs-float
@samp{-mno-apcs-float}, since integer only code is slightly increased in
size if @samp{-mapcs-float} is used.
+@c not currently implemented
@item -mapcs-reentrant
@kindex -mapcs-reentrant
@kindex -mno-apcs-reentrant
-Generate reentrant, position independent code. This is the equivalent
-to specifying the @samp{-fpic} option. The default is
+Generate reentrant, position independent code. The default is
@samp{-mno-apcs-reentrant}.
+@end ignore
@item -mthumb-interwork
@kindex -mthumb-interwork
@kindex -mno-thumb-interwork
-Generate code which supports calling between the ARM and THUMB
+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
@samp{-mno-thumb-interwork}, since slightly larger code is generated
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.
-
+objects in memory.
+
@item -mno-alignment-traps
@kindex -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 (implementations prior to
-ARMv4).
+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.
+memory.
The default setting for most targets is -mno-alignment-traps, since
this produces better code when there are no half-word memory
-instructions available.
+instructions available.
@item -mshort-load-bytes
+@itemx -mno-short-load-words
@kindex -mshort-load-bytes
-This is a deprecated alias for @samp{-malignment-traps}.
+@kindex -mno-short-load-words
+These are deprecated aliases for @samp{-malignment-traps}.
@item -mno-short-load-bytes
+@itemx -mshort-load-words
@kindex -mno-short-load-bytes
-This is a deprecated alias for @samp{-mno-alignment-traps}.
-
-@item -mshort-load-words
@kindex -mshort-load-words
-This is a deprecated alias for @samp{-mno-alignment-traps}.
-
-@item -mno-short-load-words
-@kindex -mno-short-load-words
-This is a deprecated alias for @samp{-malignment-traps}.
+This are deprecated aliases for @samp{-mno-alignment-traps}.
@item -mbsd
@kindex -mbsd
@item -mcpu=<name>
@kindex -mcpu=
This specifies the name of the target ARM processor. GCC uses this name
-to determine what kind of instructions it can use when generating
+to determine what kind of instructions it can emit when generating
assembly code. Permissible names are: arm2, arm250, arm3, arm6, arm60,
arm600, arm610, arm620, arm7, arm7m, arm7d, arm7dm, arm7di, arm7dmi,
arm70, arm700, arm700i, arm710, arm710c, arm7100, arm7500, arm7500fe,
arm7tdmi, arm8, strongarm, strongarm110, strongarm1100, arm8, arm810,
-arm9, arm920, arm920t, arm9tdmi.
+arm9, arm9e, arm920, arm920t, arm940t, arm9tdmi, arm10tdmi, arm1020t,
+xscale.
@itemx -mtune=<name>
@kindex -mtune=
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 @samp{-mcpu=} option.
-For some arm implementations better performance can be obtained by using
+For some ARM implementations better performance can be obtained by using
this option.
@item -march=<name>
@kindex -march=
This specifies the name of the target ARM architecture. GCC uses this
-name to determine what kind of instructions it can use when generating
+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 @samp{-mcpu=} option. Permissible names are: armv2, armv2a,
-armv3, armv3m, armv4, armv4t, armv5.
+armv3, armv3m, armv4, armv4t, armv5, armv5t, armv5te.
@item -mfpe=<number>
@itemx -mfp=<number>
@kindex -mfp=
This specifies the version of the floating point emulation available on
the target. Permissible values are 2 and 3. @samp{-mfp=} is a synonym
-for @samp{-mfpe=} to support older versions of GCC.
+for @samp{-mfpe=}, for compatibility with older versions of GCC.
@item -mstructure-size-boundary=<n>
@kindex -mstructure-size-boundary
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. Programmers are encouraged to use the 32
-value as future versions of the toolchain may default to this value.
+using structures or unions.
@item -mabort-on-noreturn
@kindex -mabort-on-noreturn
@kindex -mnoabort-on-noreturn
-Generate a call to the function abort at the end of a noreturn function.
-It will be executed if the function tries to return.
+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
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.
+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
turned into long calls.
This feature is not enabled by default. Specifying
-@samp{--no-long-calls} will restore the default behaviour, as will
+@samp{-mno-long-calls} will restore the default behaviour, 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.
+pointers.
@item -mnop-fun-dllimport
@kindex -mnop-fun-dllimport
-Disable the support for the @emph{dllimport} attribute.
+Disable support for the @emph{dllimport} attribute.
@item -msingle-pic-base
@kindex -msingle-pic-base
Specify the register to be used for PIC addressing. The default is R10
unless stack-checking is enabled, when R9 is used.
-@end table
+@item -mpoke-function-name
+@kindex -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:
-@node Thumb Options
-@subsection Thumb Options
-@cindex Thumb Options
+@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
-@table @code
+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-interwork
-@kindex -mthumb-interwork
-@kindex -mno-thumb-interwork
-Generate code which supports calling between the THUMB and ARM
-instruction sets. Without this option the two instruction sets cannot
-be reliably used inside one program. The default is
-@samp{-mno-thumb-interwork}, since slightly smaller code is generated
-with this option.
+@item -mthumb
+@kindex -mthumb
+Generate code for the 16-bit Thumb instruction set. The default is to
+use the 32-bit ARM instruction set.
@item -mtpcs-frame
@kindex -mtpcs-frame
@kindex -mno-tpcs-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 @samp{-mno-apcs-frame}.
+not call any other functions.) The default is @samp{-mno-tpcs-frame}.
@item -mtpcs-leaf-frame
@kindex -mtpcs-leaf-frame
@kindex -mno-tpcs-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 @samp{-mno-apcs-leaf-frame}.
-
-@item -mlittle-endian
-@kindex -mlittle-endian
-Generate code for a processor running in little-endian mode. This is
-the default for all standard configurations.
-
-@item -mbig-endian
-@kindex -mbig-endian
-Generate code for a processor running in big-endian mode.
-
-@item -mstructure-size-boundary=<n>
-@kindex -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 produced 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. Programmers are encouraged to use the 32
-value as future versions of the toolchain may default to this value.
-
-@item -mnop-fun-dllimport
-@kindex -mnop-fun-dllimport
-Disable the support for the @emph{dllimport} attribute.
+not call any other functions.) The default is @samp{-mno-apcs-leaf-frame}.
@item -mcallee-super-interworking
@kindex -mcallee-super-interworking
compiled for interworking or not. There is a small overhead in the cost
of executing a function pointer if this option is enabled.
-@item -msingle-pic-base
-@kindex -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 initialising this register with an appropriate value
-before execution begins.
-
-@item -mpic-register=<reg>
-@kindex -mpic-register=
-Specify the register to be used for PIC addressing. The default is R10.
-
@end table
@node MN10200 Options
@subsection MN10200 Options
@cindex MN10200 options
These @samp{-m} options are defined for Matsushita MN10200 architectures:
-@table @code
+@table @gcctabopt
@item -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.
+This option makes symbolic debugging impossible.
@end table
@node MN10300 Options
@cindex MN10300 options
These @samp{-m} options are defined for Matsushita MN10300 architectures:
-@table @code
+@table @gcctabopt
@item -mmult-bug
Generate code to avoid bugs in the multiply instructions for the MN10300
processors. This is the default.
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.
+This option makes symbolic debugging impossible.
@end table
These @samp{-m} options are defined for Mitsubishi M32R/D architectures:
-@table @code
+@table @gcctabopt
@item -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
@code{model} attribute.
@item -mcode-model=medium
-Assume objects may be anywhere in the 32 bit address space (the compiler
+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
-Assume objects may be anywhere in the 32 bit address space (the compiler
+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}
These @samp{-m} options are defined for Motorola 88k architectures:
-@table @code
+@table @gcctabopt
@item -m88000
@kindex -m88000
Generate code that works well on both the m88100 and the
@cindex IBM RS/6000 and PowerPC Options
These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
-@table @code
+@table @gcctabopt
@item -mpower
@itemx -mno-power
@itemx -mpower2
and 64-bit PowerPC architecture machine types, with an appropriate,
generic processor model assumed for scheduling purposes.@refill
-Specifying any of the following options:
+Specifying any of the following options:
@samp{-mcpu=rios1}, @samp{-mcpu=rios2}, @samp{-mcpu=rsc},
-@samp{-mcpu=power}, or @samp{-mcpu=power2}
-enables the @samp{-mpower} option and disables the @samp{-mpowerpc} option;
+@samp{-mcpu=power}, or @samp{-mcpu=power2}
+enables the @samp{-mpower} option and disables the @samp{-mpowerpc} option;
@samp{-mcpu=601} enables both the @samp{-mpower} and @samp{-mpowerpc} options.
All of @samp{-mcpu=rs64a}, @samp{-mcpu=602}, @samp{-mcpu=603},
@samp{-mcpu=603e}, @samp{-mcpu=604}, @samp{-mcpu=620}, @samp{-mcpu=630},
@samp{-mcpu=740}, and @samp{-mcpu=750}
-enable the @samp{-mpowerpc} option and disable the @samp{-mpower} option.
+enable the @samp{-mpowerpc} option and disable the @samp{-mpower} option.
Exactly similarly, all of @samp{-mcpu=403},
-@samp{-mcpu=505}, @samp{-mcpu=821}, @samp{-mcpu=860} and @samp{-mcpu=powerpc}
+@samp{-mcpu=505}, @samp{-mcpu=821}, @samp{-mcpu=860} and @samp{-mcpu=powerpc}
enable the @samp{-mpowerpc} option and disable the @samp{-mpower} option.
-@samp{-mcpu=common} disables both the
+@samp{-mcpu=common} disables both the
@samp{-mpower} and @samp{-mpowerpc} options.@refill
AIX versions 4 or greater selects @samp{-mcpu=common} by default, so
@itemx -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 @code{-meabi}
+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 @samp{-msdata} option can use both @code{r2} and
@code{r13} to point to two separate small data areas. Selecting
-@code{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
+@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
@samp{-msdata} option will only use @code{r13} to point to a single
small data area. The @samp{-meabi} option is on by default if you
These @samp{-m} options are defined for the IBM RT PC:
-@table @code
+@table @gcctabopt
@item -min-line-mul
Use an in-line code sequence for integer multiplies. This is the
default.
These @samp{-m} options are defined for the MIPS family of computers:
-@table @code
+@table @gcctabopt
@item -mcpu=@var{cpu type}
Assume the defaults for the machine type @var{cpu type} when scheduling
instructions. The choices for @var{cpu type} are @samp{r2000}, @samp{r3000},
ISA level.
@item -mips3
-Issue instructions from level 3 of the MIPS ISA (64 bit instructions).
+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
@itemx -mno-uninit-const-in-rodata
When used together with -membedded-data, it will always store uninitialized
const variables in the read-only data section.
-
+
@item -msingle-float
@itemx -mdouble-float
The @samp{-msingle-float} switch tells gcc to assume that the floating
These @samp{-m} options are defined for the i386 family of computers:
-@table @code
+@table @gcctabopt
@item -mcpu=@var{cpu type}
Assume the defaults for the machine type @var{cpu type} when scheduling
-instructions. The choices for @var{cpu type} are:
-
-@multitable @columnfractions .20 .20 .20 .20
-@item @samp{i386} @tab @samp{i486} @tab @samp{i586} @tab @samp{i686}
-@item @samp{pentium} @tab @samp{pentiumpro} @tab @samp{k6} @tab @samp{athlon}
-@end multitable
+instructions. The choices for @var{cpu type} are @samp{i386},
+@samp{i486}, @samp{i586}, @samp{i686}, @samp{pentium},
+@samp{pentiumpro}, @samp{pentium4}, @samp{k6}, and @samp{athlon}
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 @samp{-march=@var{cpu type}} option
being used. @samp{i586} is equivalent to @samp{pentium} and @samp{i686}
-is equivalent to @samp{pentiumpro}. @samp{k6} is the AMD chip as
-opposed to the Intel ones.
+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}
Generate instructions for the machine type @var{cpu type}. The choices
-for @var{cpu type} are the same as for @samp{-mcpu}. Moreover,
+for @var{cpu type} are the same as for @samp{-mcpu}. Moreover,
specifying @samp{-march=@var{cpu type}} implies @samp{-mcpu=@var{cpu type}}.
@item -m386
@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 @samp{-ffast-math} switch.
+also use the @samp{-funsafe-math-optimizations} switch.
@item -malign-double
@itemx -mno-align-double
produce code that runs somewhat faster on a @samp{Pentium} at the
expense of more memory.
-@strong{Warning:} if you use the @samp{-malign-double} switch,
-structures containing the above types will be aligned differently than
-the published application binary interface specifications for the 386.
+@item -m128bit-long-double
+@itemx -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)
+preffer @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 @samp{-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
+@itemx -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
@item -mno-wide-multiply
@itemx -mwide-multiply
Control whether GCC uses the @code{mul} and @code{imul} that produce
-64 bit results in @code{eax:edx} from 32 bit operands to do @code{long
+64-bit results in @code{eax:edx} from 32-bit operands to do @code{long
long} multiplies and 32-bit division by constants.
@item -mrtd
function with too many arguments. (Normally, extra arguments are
harmlessly ignored.)
-@item -mreg-alloc=@var{regs}
-Control the default allocation order of integer registers. The
-string @var{regs} is a series of letters specifying a register. The
-supported letters are: @code{a} allocate EAX; @code{b} allocate EBX;
-@code{c} allocate ECX; @code{d} allocate EDX; @code{S} allocate ESI;
-@code{D} allocate EDI; @code{B} allocate EBP.
-
@item -mregparm=@var{num}
Control how many registers are used to pass integer arguments. By
default, no registers are used to pass arguments, and at most 3
value, including any libraries. This includes the system libraries and
startup modules.
-@item -malign-loops=@var{num}
-Align loops to a 2 raised to a @var{num} byte boundary. If
-@samp{-malign-loops} is not specified, the default is 2 unless
-gas 2.8 (or later) is being used in which case the default is
-to align the loop on a 16 byte boundary if it is less than 8
-bytes away.
-
-@item -malign-jumps=@var{num}
-Align instructions that are only jumped to to a 2 raised to a @var{num}
-byte boundary. If @samp{-malign-jumps} is not specified, the default is
-2 if optimizing for a 386, and 4 if optimizing for a 486 unless
-gas 2.8 (or later) is being used in which case the default is
-to align the instruction on a 16 byte boundary if it is less
-than 8 bytes away.
-
-@item -malign-functions=@var{num}
-Align the start of functions to a 2 raised to @var{num} byte boundary.
-If @samp{-malign-functions} is not specified, the default is 2 if optimizing
-for a 386, and 4 if optimizing for a 486.
-
@item -mpreferred-stack-boundary=@var{num}
Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
byte boundary. If @samp{-mpreferred-stack-boundary} is not specified,
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.
+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
@item -mthreads
@kindex -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
-@samp{-mthreads} option. When compiling, @samp{-mthreads} defines
-@samp{-D_MT}; when linking, it links in a special thread helper library
+Support thread-safe exception handling on @samp{Mingw32}. Code that relies
+on thread-safe exception handling must compile and link all code with the
+@samp{-mthreads} option. When compiling, @samp{-mthreads} defines
+@samp{-D_MT}; when linking, it links in a special thread helper library
@samp{-lmingwthrd} which cleans up per thread exception handling data.
@item -mno-align-stringops
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
+@kindex -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
+@samp{-fomit-frame-pointer} removes the frame pointer for all functions
+which might make debugging harder.
@end table
@node HPPA Options
These @samp{-m} options are defined for the HPPA family of computers:
-@table @code
+@table @gcctabopt
@item -march=@var{architecture type}
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
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.
+support.
@item -mpa-risc-1-0
@itemx -mpa-risc-1-1
@item -mschedule=@var{cpu type}
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
+@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.
These @samp{-m} options are defined for the Intel 960 implementations:
-@table @code
+@table @gcctabopt
@item -m@var{cpu type}
Assume the defaults for the machine type @var{cpu type} for some of
the other options, including instruction scheduling, floating point
These @samp{-m} options are defined for the DEC Alpha implementations:
-@table @code
+@table @gcctabopt
@item -mno-soft-float
@itemx -msoft-float
Use (do not use) the hardware floating-point instructions for
-floating-point operations. When @code{-msoft-float} is specified,
-functions in @file{libgcc1.c} will be used to perform floating-point
+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
@item -mfp-reg
@itemx -mno-fp-regs
Generate code that uses (does not use) the floating-point register set.
-@code{-mno-fp-regs} implies @code{-msoft-float}. If the floating-point
+@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 $0 instead of $f0. This is a non-standard calling sequence, so any
function with a floating-point argument or return value called by code
-compiled with @code{-mno-fp-regs} must also be compiled with that
+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,
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
-@code{-ieee_with_no_inexact}.
+@option{-ieee_with_no_inexact}.
@item -mieee-with-inexact
@c overfull hbox here --bob 22 jul96
code to implement fully-compliant IEEE math. The option is a shorthand
for @samp{-D_IEEE_FP -D_IEEE_FP_INEXACT} plus the three following:
@samp{-mieee-conformant},
-@samp{-mfp-trap-mode=sui},
-and @samp{-mtrap-precision=i}.
+@samp{-mfp-trap-mode=sui},
+and @samp{-mtrap-precision=i}.
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
These @samp{-m} options are defined for the Clipper implementations:
-@table @code
+@table @gcctabopt
@item -mc300
Produce code for a C300 Clipper processor. This is the default.
These @samp{-m} options are defined for the H8/300 implementations:
-@table @code
+@table @gcctabopt
@item -mrelax
Shorten some address references at link time, when possible; uses the
linker option @samp{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
These @samp{-m} options are defined for the SH implementations:
-@table @code
+@table @gcctabopt
@item -m1
Generate code for the SH1.
Compile code for the processor in little endian mode.
@item -mdalign
-Align doubles at 64 bit boundaries. Note that this changes the calling
+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 -mdalign.
@item -mnomacsave
Mark the @code{MAC} register as call-clobbered, even if
-@code{-mhitachi} is given.
+@option{-mhitachi} is given.
@item -misize
Dump instruction size and location in the assembly code.
which is incompatible with the SH ABI.
@item -mspace
-Optimize for space instead of speed. Implied by @code{-Os}.
+Optimize for space instead of speed. Implied by @option{-Os}.
@item -mprefergot
When generating position-independent code, emit function calls using
These additional options are available on System V Release 4 for
compatibility with other compilers on those systems:
-@table @code
+@table @gcctabopt
@item -G
Create a shared object.
It is recommended that @samp{-symbolic} or @samp{-shared} be used instead.
Refrain from adding @code{.ident} directives to the output file (this is
the default).
-@item -YP,@var{dirs}
+@item -YP\,@var{dirs}
Search the directories @var{dirs}, and no others, for libraries
specified with @samp{-l}.
-@item -Ym,@var{dir}
+@item -Ym\,@var{dir}
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
These @samp{-m} options are defined for TMS320C3x/C4x implementations:
-@table @code
+@table @gcctabopt
@item -mcpu=@var{cpu_type}
Set the instruction set, register set, and instruction scheduling
@item -mbk
@itemx -mno-bk
Allow (disallow) allocation of general integer operands into the block
-count register BK.
+count register BK.
@item -mdb
@itemx -mno-db
These @samp{-m} options are defined for V850 implementations:
-@table @code
+@table @gcctabopt
@item -mlong-calls
@itemx -mno-long-calls
Treat all calls as being far away (near). If calls are assumed to be
@item -mzda=@var{n}
Put static or global variables whose size is @var{n} bytes or less into
the first 32 kilobytes of memory.
-
+
@item -mv850
Specify that the target processor is the V850.
These options are defined for ARC implementations:
-@table @code
+@table @gcctabopt
@item -EL
Compile code for little endian mode. This is the default.
the compiler was configured; the defaults for the most common choices are
given below.
-@table @code
+@table @gcctabopt
@item -m32032
@itemx -m32032
Generate output for a 32032. This is the default
These options are defined for AVR implementations:
-@table @code
+@table @gcctabopt
@item -mmcu=@var{mcu}
-Specify ATMEL AVR mcu (at90s23xx,attiny22,at90s44xx,at90s85xx,atmega603,
-atmega103).
+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).
+
+Instruction set avr4 is for the enhanced AVR core with up to 8K program
+memory space (MCU types: atmega83, atmega85).
+
+Instruction set avr5 is for the enhanced AVR core with up to 128K program
+memory space (MCU types: atmega161, atmega163, atmega32, at94k).
@item -msize
-Output instruction size's to the asm file
+Output instruction sizes to the asm file.
@item -minit-stack=@var{N}
-Specify the initial stack address
+Specify the initial stack address, which may be a symbol or numeric value,
+__stack is the default.
@item -mno-interrupts
Generated code is not compatible with hardware interrupts.
@item -mcall-prologues
Functions prologues/epilogues expanded as call to appropriate
subroutines. Code size will be smaller.
+
+@item -mno-tablejump
+Do not generate tablejump insns which sometimes increase code size.
+
+@item -mtiny-stack
+Change only the low 8 bits of the stack pointer.
@end table
@node MCore Options
@cindex MCore options
These are the @samp{-m} options defined for the Motorola M*Core
-processors.
+processors.
-@table @code
+@table @gcctabopt
@item -mhardlit
@itemx -mhardlit
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
+Generate code for a big endian target. This is the default for HPUX.
+
+@item -mlittle-endian
+Generate code for a little endian target. This is the default for AIX5
+and Linux.
+
+@item -mgnu-as
+@itemx -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 @samp{--with-gnu-as}
+@c is used.
+
+@item -mgnu-ld
+@itemx -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 @samp{--with-gnu-ld}
+@c is used.
+
+@item -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
+Generate (or don't) a stop bit immediately before and after volatile asm
+statements.
+
+@item -mb-step
+Generate code that works around Itanium B step errata.
+
+@item -mregister-names
+@itemx -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
+Disable (or enable) optimizations that use the small data section. This may
+be useful for working around optimizer bugs.
+
+@item -mconstant-gp
+Generate code that uses a single constant global pointer value. This is
+useful when compiling kernel code.
+
+@item -mauto-pic
+Generate code that is self-relocatable. This implies @samp{-mconstant-gp}.
+This is useful when compiling firmware code.
+
+@item -minline-divide-min-latency
+Generate code for inline divides using the minimum latency algorithm.
+
+@item -minline-divide-max-throughput
+Generate code for inline divides using the maximum throughput algorithm.
+
+@item -mno-dwarf2-asm
+@itemx -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}
+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 @code
+@table @gcctabopt
@item -mextmem
Link the @samp{.text}, @samp{.data}, @samp{.bss}, @samp{.strings},
@samp{.rodata}, @samp{.rodata1}, @samp{.data1} sections into external
can figure out the other form by either removing @samp{no-} or adding
it.
-@table @code
+@table @gcctabopt
@item -fexceptions
Enable exception handling. Generates extra code needed to propagate
exceptions. For some targets, this implies GNU CC 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, GNU CC will enable it by default for languages like
-C++ which normally require exception handling, and disable itfor
+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
use exception handling.
@item -funwind-tables
-Similar to @code{-fexceptions}, except that it will just generate any needed
+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.
exists in one copy per process.
@item -fno-common
-Allocate even uninitialized global variables in the data section of the
+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.
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
-@code{collect2} program to make sure the system linker includes
-constructors and destructors. (@code{collect2} is included in the GCC
-distribution.) For systems which @emph{must} use @code{collect2}, the
-compiler driver @code{gcc} is configured to do this automatically.
+@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
Don't output a @code{.size} assembler directive, or anything else that
@code{__asm__} keywords in functions with memory checking enabled. GNU
CC cannot understand what the @code{asm} statement may do, and therefore
cannot generate the appropriate code, so it will reject it. However, if
-you specify the function attribute @code{no_check_memory_usage} (see
-@pxref{Function Attributes}, GNU CC will disable memory checking within a
+you specify the function attribute @code{no_check_memory_usage}
+(@pxref{Function Attributes}), GNU CC will disable memory checking within a
function; you may use @code{asm} statements inside such functions. You
may have an inline expansion of a non-checked function within a checked
function; in that case GNU CC will not generate checks for the inlined
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);
+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,
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
@xref{Driver}.
@end ifset
-@table @code
+@table @env
@item LANG
@itemx LC_CTYPE
@c @itemx LC_COLLATE
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
-@code{LC_CTYPE} and @code{LC_MESSAGES} if it has been configured to do
+@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 @code{LC_CTYPE} environment variable specifies character
+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 @code{LC_MESSAGES} environment variable specifies the language to
+The @env{LC_MESSAGES} environment variable specifies the language to
use in diagnostic messages.
-If the @code{LC_ALL} environment variable is set, it overrides the value
-of @code{LC_CTYPE} and @code{LC_MESSAGES}; otherwise, @code{LC_CTYPE}
-and @code{LC_MESSAGES} default to the value of the @code{LANG}
+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 @code{TMPDIR} is set, it specifies the directory to use for temporary
+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
@item GCC_EXEC_PREFIX
@findex GCC_EXEC_PREFIX
-If @code{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
+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 @code{GCC_EXEC_PREFIX} is not set, GNU CC will attempt to figure out
+If @env{GCC_EXEC_PREFIX} is not set, GNU CC 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 @code{GCC_EXEC_PREFIX} is
+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.
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 @code{GCC_INCLUDE_DIR}), GCC tries
+(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 @samp{-Bfoo/}, GCC will search
@file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
@item COMPILER_PATH
@findex COMPILER_PATH
-The value of @code{COMPILER_PATH} is a colon-separated list of
-directories, much like @code{PATH}. GCC tries the directories thus
+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 @code{GCC_EXEC_PREFIX}.
+subprograms using @env{GCC_EXEC_PREFIX}.
@item LIBRARY_PATH
@findex LIBRARY_PATH
-The value of @code{LIBRARY_PATH} is a colon-separated list of
-directories, much like @code{PATH}. When configured as a native compiler,
+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 @code{GCC_EXEC_PREFIX}. Linking
+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 @samp{-l} option (but directories specified with
@samp{-L} come first).
@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
-@code{PATH}. When GCC searches for header files, it tries the
+@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 @samp{-I} but before the standard header
file directories.
(@pxref{Preprocessor Options}), but it goes to a separate file, and is
in addition to the usual results of compilation.
-The value of @code{DEPENDENCIES_OUTPUT} can be just a file name, in
+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
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 @code{LANG} are recognized:
+the following values for @env{LANG} are recognized:
-@table @code
+@table @samp
@item C-JIS
Recognize JIS characters.
@item C-SJIS
Recognize EUCJP characters.
@end table
-If @code{LANG} is not defined, or if it has some other value, then the
+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 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}
+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.
@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
+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
@xref{Protoize Caveats}, for more information on how to use
@code{protoize} successfully.
-